Configuration

The project config is dta.config.ts (also .mts, .js, .mjs or .json). Unknown keys are rejected. This page is generated from the same schema the CLI validates with; as a JSON Schema it is published at /schemas/dta.config.schema.json, so a dta.config.json can point $schema at it. Example configs: Core concepts.

$schema

Key	Type	Default	Description
$schema	string		URL of this JSON Schema, for editor support in dta.config.json. Ignored by DTA.

figma

Key	Type	Default	Description
figma	object	{}	Where dta pull and dta push find the Figma file.
figma.fileKey	string		Key of the Figma file (from its URL: figma.com/file/<key>/…).
figma.personalAccessToken	string		Figma personal access token. Prefer the FIGMA_PERSONAL_ACCESS_TOKEN environment variable.
figma.source	'api' | 'file'		How tokens are sourced: api (REST API, Enterprise plans only) or file (an exported file, dta pull --from-file).

collections

Key	Type	Default	Description
collections	string[]		Collections to include (default: all of them).

layers

Key	Type	Default	Description
layers	object		Deprecated: use collections. Kept so v1 configs still load.
layers.primitives	string		Deprecated.
layers.brand	string		Deprecated.
layers.dimension	string		Deprecated.

brands

Key	Type	Default	Description
brands	string[]		Modes to build into one theme file each (brands, or themes such as Light and Dark).

breakpoints

Key	Type	Default	Description
breakpoints	object		With this section, dta build writes the tokens of a breakpoint collection to variables.css: the default mode on :root, every other mode inside its media query, aliases as var() references. Without it, such a collection only resolves aliases.
breakpoints.collection	string (required)		The collection whose modes are breakpoints, e.g. ScreenType.
breakpoints.default	string (required)		The mode written on :root without a media query: the smallest screen for mobile-first queries (min-width), the largest for desktop-first (max-width).
breakpoints.modes	{ [name]: string } (required)		Every other mode and its media query, without @media: { Tablet: '(min-width: 768px)', Desktop: '(min-width: 1024px)' }. The blocks are written in this order, so a later query wins where several match.

tokens

Key	Type	Default	Description
tokens	object	{}	Where the token files live.
tokens.dir	string	"tokens"	Folder of the token files.
tokens.stripEmojis	boolean	false	Strip emoji characters from collection and mode names in file names.
tokens.resolver	string		The DTCG resolver document (*.resolver.json) in the tokens folder to read; default: the only one there.

modifiers

Key	Type	Default	Description
modifiers	{ [name]: string }		For a DTCG resolver document: the context each modifier is read in by default, e.g. { theme: "light" }.

outputs

Key	Type	Default	Description
outputs	object		What dta build writes and where. formats chooses the outputs (all by default); the other keys move them.
outputs.formats	('css' | 'tailwind-v4' | 'tailwind-v3' | 'js' | 'ios-swift' | 'android-xml' | 'android-compose')[]		Which outputs dta build writes: the web outputs css, tailwind-v4, tailwind-v3, js (the default: all four) and the native ones ios-swift, android-xml, android-compose (only when listed). dta init writes it from your answer to “Which formats should dta generate?”.
outputs.css	object		CSS custom properties: variables.css, base.css and one theme file per brand (default folder output/css).
outputs.css.outDir	string (required)		Folder the files are written to, relative to the project.
outputs.css.prefix	never		Removed; rejected. It never had an effect: delete the line.
outputs.tailwind	object		Tailwind theme files (default folder output/tailwind).
outputs.tailwind.outDir	string (required)		Folder the files are written to, relative to the project.
outputs.tailwind.version	never		Removed; rejected. It never had an effect: formats chooses the Tailwind versions. Delete the line.
outputs.ios	object		Swift for SwiftUI (ios-swift in formats): DesignTokens.swift and one BrandTokens+<Brand>.swift per brand (default folder output/ios).
outputs.ios.outDir	string		Folder the files are written to, relative to the project.
outputs.ios.lang	never		Removed; rejected. formats chooses the native outputs. Delete the line.
outputs.android	object		Android (android-xml, android-compose in formats): resource XML in main/values/ and <brand>/values/, Compose in compose/DesignTokens.kt (default folder output/android).
outputs.android.outDir	string		Folder the files are written to, relative to the project.
outputs.android.package	string		The Kotlin package of DesignTokens.kt (default designtokens).
outputs.android.lang	never		Removed; rejected. formats chooses the native outputs. Delete the line.
outputs.docs	never		Removed in v2; rejected.

lint

Key	Type	Default	Description
lint	object		dta lint rules (also run by dta push).
lint.rules	object		Configurable rules by name, with their options. A configured rule is a warning unless its severity says otherwise.
lint.rules.semantic-must-alias	object		Fails when a token in the listed collections holds a raw value instead of an alias.
lint.rules.semantic-must-alias.severity	'error' | 'warn' | 'off'		error fails dta lint, warn (the default) reports, off disables the rule.
lint.rules.semantic-must-alias.collections	string[]		Collections whose tokens must all be aliases.
lint.rules.naming-pattern	object		Fails when a path segment does not match the pattern of its collection.
lint.rules.naming-pattern.severity	'error' | 'warn' | 'off'		error fails dta lint, warn (the default) reports, off disables the rule.
lint.rules.naming-pattern.patterns	{ [name]: string }		Collection name → regular expression every path segment must match.
lint.rules.naming-case	object		Fails when a path segment is not in the case style of its collection (TICKET-019).
lint.rules.naming-case.severity	'error' | 'warn' | 'off'		error fails dta lint, warn (the default) reports, off disables the rule.
lint.rules.naming-case.collections	{ [name]: 'kebab-case' | 'camelCase' | 'PascalCase' | 'snake_case' }		Collection name → the case every path segment uses: kebab-case, camelCase, PascalCase or snake_case. Scale steps (700, 0-5, 1.5, 2xl) fit every style; $root is not checked.
lint.rules.naming-depth	object		Fails when a token path has fewer or more segments than its collection allows (TICKET-019).
lint.rules.naming-depth.severity	'error' | 'warn' | 'off'		error fails dta lint, warn (the default) reports, off disables the rule.
lint.rules.naming-depth.collections	{ [name]: object }		Collection name → { min, max }: how many path segments a token name has.
lint.rules.no-spaces	object		Reports spaces in collection names and token path segments; some outputs and tools handle them badly (TICKET-019).
lint.rules.no-spaces.severity	'error' | 'warn' | 'off'		error fails dta lint, warn (the default) reports, off disables the rule.
lint.rules.collection-pattern	object		Fails when a collection name does not match the pattern (TICKET-019).
lint.rules.collection-pattern.severity	'error' | 'warn' | 'off'		error fails dta lint, warn (the default) reports, off disables the rule.
lint.rules.collection-pattern.pattern	string		Regular expression every collection name must match (not anchored: write ^…$ for the whole name).
lint.rules.color-contrast	object		Checks the contrast of text and background pairs, per mode, through aliases.
lint.rules.color-contrast.severity	'error' | 'warn' | 'off'		error fails dta lint, warn (the default) reports, off disables the rule.
lint.rules.color-contrast.minRatio	number		Minimum WCAG contrast ratio (default 4.5, level AA).
lint.rules.color-contrast.pairs	([string, string])[]		[foreground, background] token names.
lint.rules.no-duplicate-values	object		Reports raw values that appear more than once, across all collections and modes.
lint.rules.no-duplicate-values.severity	'error' | 'warn' | 'off'		error fails dta lint, warn (the default) reports, off disables the rule.

diff

Key	Type	Default	Description
diff	object		What dta diff builds and renders: the project build and its stories.
diff.setup	string		Optional command that prepares the fresh checkout of the base, run in its repo root. Without it, dta diff reuses your installed packages when the lockfile did not change, and otherwise runs the lockfile’s clean install (npm ci, pnpm install –frozen-lockfile, …).
diff.build	string		Command that builds the static output, run at the base and the head.
diff.outDir	string (required)		Folder of the static output, relative to the project.
diff.stories	string[] | object	{"type":"static-site","manifest":"stories/manifest.json"}	Where the stories come from: a list of pages (["/", "/pricing"]), a dta.stories/1 manifest in the static output (static-site, the default) or the index of a static Storybook build (storybook).
diff.stories.manifest	string	"stories/manifest.json"	(type: 'static-site') Path of the dta.stories/1 manifest inside outDir.
diff.stories.index	string	"index.json"	(type: 'storybook') Storybook’s index inside outDir (the storybook build output).
diff.stories.excludeTags	string[]	["skip-dta-diff"]	(type: 'storybook') Stories with one of these tags are not rendered.
diff.stories.exclude	string[]	[]	(type: 'storybook') Regular expressions; stories whose id matches one are not rendered.
diff.viewports	integer[]	[1280]	Viewport widths for stories that do not suggest their own.
diff.threshold	number	0	Changed-pixel ratio (0–1) a story may differ by before it counts as changed.
diff.colorThreshold	number	0	Per-pixel colour tolerance (0–1); 0 sees every colour change.
diff.thresholds	object	{}	Review thresholds by cause, as changed-pixel ratios (0–1).
diff.thresholds.explained	number	0	A story explained by token changes needs a review above this ratio.
diff.thresholds.unexplained	number	0	A story no token change explains fails above this ratio.
diff.publish	string | object		Publish hook: a command run on the report folder (path as argument and DTA_REPORT_DIR) that prints the public base URL as its last stdout line, or { command, url } where url is a JSON path ($.deployment.url) or a regular expression to find it. --publish overrides it.
diff.publish.command	string (required)		The publish command.
diff.publish.url	string		JSON path or regular expression that finds the URL in its output.
diff.base	string		Default base for dta diff (a git ref or directory); --base overrides it.
diff.workflow	'single' | 'split'		The GitHub workflow dta init writes: single (one file, for repositories without outside contributors) or split (three files, safe for pull requests from forks). Saved so a re-run does not ask again.

audit

Key	Type	Default	Description
audit	object		dta audit: where to look for hard-coded values that should be tokens.
audit.paths	string[]		Files and folders dta audit scans when no paths are given (default src).
audit.ignore	string[]		Globs of files not to scan, relative to the project (**/*.test.ts).
audit.languages	('css' | 'scss' | 'js' | 'astro' | 'vue' | 'svelte' | 'html')[]		Languages to scan (default: all). js covers JS, TS, JSX and TSX.
audit.near	boolean		Also report colours within about 2 % per channel of a token (like --near).
audit.baseline	string	".dta/audit-baseline.json"	Accepted findings; dta audit --update-baseline writes it.

context

Key	Type	Default	Description
context	object		With this section, dta build also writes the context file for coding agents and the pointer in AGENTS.md, like dta context. Off by default.
context.out	string	"DESIGN.md"	Context file for coding agents, relative to the project.

brief

Key	Type	Default	Description
brief	object		dta brief: what the brief for AI design tools says beyond the tokens.
brief.identity	string		One line on the brand’s character, which tokens cannot say: “Calm, trustworthy, institutional.”
brief.rules	string[]		The rules a generator should follow, one line each: “Never use pure black: use Colors.Text.Default.”

push

Key	Type	Default	Description
push	object		dta push settings.
push.skipConfirmation	boolean		Skip the typed confirmation before pushing to Figma (CI, automation).