Settings

Controls how a run behaves. Changing a setting produces different output, never incorrect output: a different team reading the same library may set every one of these differently and each result is correct.

Authored in config/settings.yaml. Members are grouped by concern, and each concern carries its own directory.

Property	Type	Default	Description
author	string	—	Author recorded in generated spec metadata
data	object	—	Source acquisition and the directory holding fetched, computed, and authored data
spec	object	—	The generated spec — where it lands, how it is split, what it contains, how values are serialized
assets	object	—	Shared resources every code output points at: icons, images, generated CSS, fonts

data

Property	Type	Default	Description
directory	string	—	Directory holding fetched downloads, computed caches, extracted assets, and authored inputs
sources	object	—	Sources the workspace reads from, keyed by source name

data.sources.<name>

Property	Type	Default	Description
key	string	(required)	Figma file key the source reads from
fetch	string[]	—	Artifacts to download (e.g. file, variables, styles, icons)

spec

Property	Type	Default	Description
directory	string	—	Directory the generated spec is written to
format	'JSON' | 'YAML'	'JSON'	Serialization format
keys	'SAFE' | 'CAMEL' | 'SNAKE' | 'KEBAB' | 'PASCAL' | 'TRAIN'	'SAFE'	Key casing style
layout	'LAYOUT' | 'PARENT_CHILDREN' | 'BOTH'	'LAYOUT'	Element hierarchy representation
tokens	'TOKEN' | 'TOKEN_NAME' | 'TOKEN_FIGMA_EXTENSIONS' | 'FIGMA_NAME' | 'CUSTOM' | 'FIGMA_SYNTAX_WEB' | 'FIGMA_SYNTAX_IOS' | 'FIGMA_SYNTAX_ANDROID'	'TOKEN'	Token reference output format
color	ColorFormat	'HEX'	Color value output format
variantDepth	1 | 2 | 3 | 9999	9999	Maximum variant nesting depth (9999 = unlimited)
details	'FULL' | 'LAYERED'	'LAYERED'	Output detail level
collapsePrimitiveWrapper	boolean	false	Strip a root container that only wraps one child — a text/glyph leaf, or a slot — and promote the child to spec root
promotePrimitives	boolean	false	Promote primitive layers in composed example content to instances of the design system’s own components
roles	boolean	false	Read Figma Dev Mode annotations and emit anatomy.<element>.role and .actions — the on-switch for the role feature (ADR-067)
roleValidation	'warn' | 'error'	'warn'	Severity for unmet required role obligations, such as a control with no accessible-name source; error fails the transform (ADR-067)
invalidVariants	boolean	false	Include variants marked invalid
invalidCombinations	boolean	true	Include invalidVariantCombinations list
emptyVariants	boolean	false	Include variants with no element overrides
defaultSlotContent	boolean	false	Pro. Emit the component’s default slot content into Component.slotContentExamples. Ignored on the free tier
splitComponents	boolean	true	Write one file per component rather than a single combined library file
splitConcerns	boolean	true	Write one file per concern (api, styling, variants)
useSubfolders	boolean	true	Nest each component’s files in a subfolder named for the component

assets

Property	Type	Default	Description
directory	string	—	Directory holding shared assets

Grouped by consumer rather than producer: icons, images, generated CSS, and fonts arrive from fetch, from generate, from transform, or from a process outside this tool — and every code output points at them, whatever the platform.

DEFAULT_SETTINGS

A runtime export from @directededges/specs-schema. Provides defaults for every setting that has one. Typed as ResolvedSettings — all defaulted properties are required:

const DEFAULT_SETTINGS: ResolvedSettings = {
  spec: {
    format: 'JSON',
    keys: 'SAFE',
    layout: 'LAYOUT',
    tokens: 'TOKEN',
    color: 'HEX',
    variantDepth: 9999,
    details: 'LAYERED',
    collapsePrimitiveWrapper: false,
    promotePrimitives: false,
    roles: false,
    roleValidation: 'warn',
    invalidVariants: false,
    invalidCombinations: true,
    emptyVariants: false,
    defaultSlotContent: false,
  },
};

Directories, sources, and author carry no default: the consumer supplies them, and this package has no basis for choosing one. They stay optional on ResolvedSettings for exactly that reason.

The three split flags are different. Every downstream command — transform, analyze, render — reads the split layout, so the shape of generated output is not a per-consumer choice; leaving each consumer to pick its own default is how the same workspace ends up emitting two layouts. DEFAULT_SETTINGS carries them as true and they are required on ResolvedSettings.