Releases

Version history for both Specs packages. Each release follows Semantic Versioning.

@specs-schema

[0.24.0] - 2026-06-05

Introduces the transformer pipeline’s schema foundation. Config.transformers (a flat TransformEntry[]) replaces the old two-level config.transform.transformers wrapper, and a new workspace.schema.json provides IDE validation for specs.config.yaml. Config.processing.states adds a concept-keyed map that classifies Figma variant props as browser-driven or consumer-controlled states, enabling the css transformer to emit semantic CSS selectors and the contract transformer to omit browser-driven props from Props interfaces.

Added

• TransformEntry type (ADR-053) — { name: string; [option: string]: unknown }. Describes a single transformer entry in config.transformers. Transformer-specific options sit inline alongside name.

• workspace.schema.json (ADR-054) — New top-level JSON schema file for the workspace config file (specs.config.yaml). Defines the full workspace shape including dataDirectory, outputDirectory, sources, output, author, and the config block (which embeds the component Config schema). Config.transformers is defined here rather than in the component schema, keeping transform configuration CLI-only and out of the per-component spec.

• Config.transformers — TransformEntry[] directly on Config — Replaces the two-level config.transform.transformers shape. The wrapper object is gone; config.transformers is the array. Absence means CLI defaults apply.

• VariantStateEntry type (ADR-055) — classifies a Figma variant prop as a semantic state concept; fields: prop (string, required), value (string, optional — the Figma enum value activating the concept; defaults to "true" for boolean props), contract ('omit' | 'keep', optional — overrides the concept’s canonical default)

• Config.processing.states — Record<string, VariantStateEntry> — concept-keyed map (key = concept name, e.g. hover, disabled); classifies variant props for deterministic use by CSS and contract transformers; absence means all props emit as data-* attribute selectors and all props are retained in contracts

Changed

• Config.transform removed; replaced by Config.transformers — The intermediate TransformConfig wrapper object is eliminated. transform.transformers collapses to transformers directly on Config/ResolvedConfig.

Removed

[0.23.0] - Unreleased

Added

Changed

Removed

[0.22.0] - 2026-05-23

Introduces the composition and slot-content model across ADRs 042, 046–052. Composition is a named registry entry with a top-level anatomy + elements + layout triplet and an optional slotContent map of bundled SlotContent fills. SlotContentRef ({ $slotContent }) is the universal pointer for all slot fills — component-scoped examples, intra-composition bundled fills, and cross-composition references all resolve to anatomy + elements + layout. PropConfigurations widens to accept PropBinding and SlotContentRef; InstanceExample.propConfigurations widens to accept SlotContentRef (not PropBinding). Children widens to SlotBinding for slot-bound containers. Config gains the examples-detection settings and output gates (ADR-050).

Added

• SlotContent — { anatomy, elements, layout }; the anonymous structural triplet used as a named slot fill. Carries no metadata; identity lives at the key where it is stored (ADR-046)
• Composition — { title?, description?, anatomy, elements, layout, slotContent?: Record<string, SlotContent> }; a named registry entry whose top-level triplet is the primary content. Optional slotContent bundles named fills alongside it for authoring convenience (ADR-042, ADR-046)
• Compositions — Record<string, Composition>; registry alias for external composition files
• SlotContentRef — { $slotContent: string }; universal JSON Pointer reference for slot fills. Resolves to a Composition entry (top-level triplet), a Composition.slotContent entry, or a Component.slotContentExamples entry — all yield anatomy + elements + layout (ADR-046)
• Component.slotContentExamples — Record<string, SlotContent>; named slot-content examples per component, referenceable by SlotContentRef from SlotBinding.examples and from Element.propConfigurations slot-prop entries. specs-from-figma de-duplicates entries by structural equality across variants and slots (ADR-047)
• SlotBinding — extends PropBinding with optional examples?: SlotContentRef[]; used in Element.children for slot-bound containers. Each examples[i] points to a slot-content entry; emitters currently write a single entry at index 0 — Figma’s authoring default for the slot layer. Non-contractual reference material; code consumers handle missing slots through component logic and ignore it (ADR-047)
• Component.instanceExamples — typed as InstanceExamples (Record<string, InstanceExample>); named documented usages per component (ADR-048)
• InstanceExample — { title?, propConfigurations?: Record<string, string | number | boolean | SlotContentRef> }; scalar props set directly, slot props filled via SlotContentRef. PropBinding not accepted — documented configurations are not live bindings (ADR-048)
• Config.processing.instanceExamples — { scope?: 'PAGE' | 'FILE', match?: string[], exclude?: string[], parentNames?: string[] }; instance-example detection settings, mirroring processing.subcomponents. scope is PAGE | FILE (NESTED is inapplicable); match is an optional secondary name filter (the primary relevance test is structural identity — the candidate is an instance of the component being generated — so absence accepts every in-scope instance, subject to exclude/parentNames); parentNames filters candidates by immediate-parent frame/section name. Absence of the block is the off-switch — its presence enables both detection and output (no separate include flag), like processing.subcomponents. Pro-gated. Added to ResolvedConfig (with scope required, match optional) (ADR-050)
• Config.include.defaultSlotContent — boolean output gate, default false; added to ResolvedConfig (required) and DEFAULT_CONFIG. Pro-gated — ignored on the free tier (ADR-050)
• Config.format.tokens — adds FIGMA_SYNTAX_WEB, FIGMA_SYNTAX_IOS, FIGMA_SYNTAX_ANDROID profiles emitting per-platform Figma code syntax, falling back to TOKEN (ADR-051)

Changed

• Children — widened from string[] | PropBinding to string[] | SlotBinding; existing { $binding } values still validate because SlotBinding is a structural superset of PropBinding (ADR-047)
• PropConfigurations — value union widened from string | number | boolean to string | number | boolean | PropBinding | SlotContentRef; enables scalar prop pass-through (PropBinding) and slot-prop fills (SlotContentRef). InstanceExample.propConfigurations widens separately and does not accept PropBinding (ADR-049)
• PropConfigurations.$nested — added reserved key typed as NestedPropConfiguration[] ({ path: string[] } plus the prop-config payload, keyed value PropConfigurationValue); path-addressed configurations of nested descendant instances, where path is a list of instanceOf element keys to the configured descendant and the terminal instance owns the filled slot/prop. Deep slot fills reuse SlotContentRef — no new payload, no Element change. InstanceExample.propConfigurations does not gain $nested (ADR-052)

Removed

[0.21.0] - 2026-05-22

Extends Config.format.tokens with per-platform Figma code syntax profiles. The new FIGMA_SYNTAX_WEB, FIGMA_SYNTAX_IOS, and FIGMA_SYNTAX_ANDROID options emit the platform-specific code syntax authored on Figma variables, falling back to the resolved TOKEN reference when no syntax is defined.

Added

• Config.format.tokens — adds FIGMA_SYNTAX_WEB, FIGMA_SYNTAX_IOS, FIGMA_SYNTAX_ANDROID profiles emitting per-platform Figma code syntax, falling back to TOKEN

[0.20.0] - 2026-05-06

Adds configurable color output format (Config.format.color) supporting nine format options from hex strings to structured DTCG Color objects. Renames ColorValue to ColorObject for specificity and widens ColorStyle, Shadow.color, and GradientStop.color to accept formatted color strings alongside structured objects and token references.

Added

• Config.format.color — typed as ColorFormat ('HEX' | 'HEXA' | 'RGB' | 'RGBA' | 'HSLA' | 'HSB' | 'OKLCH' | 'OKLAB' | 'OBJECT'); controls color value output format; defaults to HEX

Changed

• ColorObject — renamed from ColorValue for specificity; the type represents a DTCG Color §4.1 structured object, not a generic “color value”
• ColorStyle — widened to string | ColorObject | TokenReference | GradientValue | null; the string arm supports formatted color strings when Config.format.color is non-OBJECT
• Shadow.color — widened to string | ColorObject | TokenReference; same string arm rationale as ColorStyle
• GradientStop.color — widened to string | ColorObject | TokenReference; same string arm rationale as ColorStyle

[0.19.0] - 2026-04-28

Replaces Figma-raw x, y, and layoutPositioning with constraint-based positioning properties. position replaces layoutPositioning as a strict Position enum. Directional offsets (top, bottom, start, end, centerHorizontalOffset, centerVerticalOffset) replace x/y with anchor semantics derived from Figma constraints. See the Layout Positioning guide for constraint mapping rules and platform usage examples.

Added

• Styles.position — typed as Position ('AUTO' | 'ABSOLUTE') or null; structural property, not token-bindable (replaces layoutPositioning)
• Styles.top — typed as PositionOffset (number | string | null); block-start offset from vertical MIN, STRETCH, or SCALE constraint
• Styles.bottom — typed as PositionOffset; block-end offset from vertical MAX or STRETCH constraint
• Styles.start — typed as PositionOffset; inline-start offset from horizontal MIN, STRETCH, or SCALE constraint
• Styles.end — typed as PositionOffset; inline-end offset from horizontal MAX or STRETCH constraint
• Styles.centerHorizontalOffset — typed as PositionOffset; horizontal offset from center (CENTER constraint)
• Styles.centerVerticalOffset — typed as PositionOffset; vertical offset from center (CENTER constraint)

Removed

• Styles.x — replaced by Styles.start, Styles.end, or Styles.centerHorizontalOffset depending on constraint
• Styles.y — replaced by Styles.top, Styles.bottom, or Styles.centerVerticalOffset depending on constraint
• Styles.layoutPositioning — replaced by Styles.position

Migration

• Styles.x → Styles.start / Styles.end / Styles.centerHorizontalOffset: determine which property to read based on the node’s horizontal constraint; SCALE values are percentage strings (e.g. "25%")
• Styles.y → Styles.top / Styles.bottom / Styles.centerVerticalOffset: same constraint-based mapping for the vertical axis
• Styles.layoutPositioning → Styles.position: rename and narrow type — replace generic Style handling with exhaustive match on 'AUTO' | 'ABSOLUTE'

[0.18.0] - 2026-04-24

Replaces Figma-native layout property names with semantic equivalents for auto-layout alignment and wrapping. Introduces a bi-axial itemSpacing model that consolidates counterAxisSpacing into a single property, and narrows layoutMode from a generic Style to a strict enum. Five renamed alignment/wrap fields use plain-language names (mainAxisAlignment, crossAxisAlignment, wrapAlignment, wrap) instead of Figma axis terminology. The documentation site was considerably rearchitected with updated content and navigation.

Added

• Styles.itemSpacing — widened from Style to Style | ItemSpacing (scalar when uniform, ItemSpacing object with horizontal/vertical when axes differ)
• Styles.wrap — boolean toggle for auto-layout wrapping (replaces layoutWrap)
• Styles.wrapAlignment — typed as WrapAlignment ('START' | 'SPACE_BETWEEN') or null; structural property, not token-bindable (replaces counterAxisAlignContent)
• Styles.mainAxisAlignment — typed as MainAxisAlignment ('START' | 'END' | 'CENTER' | 'SPACE_BETWEEN') or null; structural property, not token-bindable (replaces primaryAxisAlignItems)
• Styles.crossAxisAlignment — typed as CrossAxisAlignment ('START' | 'END' | 'CENTER' | 'STRETCH' | 'BASELINE') or null; structural property, not token-bindable (replaces counterAxisAlignItems)

Changed

• Styles.layoutMode — narrowed from Style to LayoutMode ('NONE' | 'HORIZONTAL' | 'VERTICAL') or null; enum constraint, no TokenReference

Removed

• Styles.counterAxisSpacing — consolidated into Styles.itemSpacing bi-axial model
• Styles.layoutWrap — replaced by Styles.wrap
• Styles.counterAxisAlignContent — replaced by Styles.wrapAlignment
• Styles.primaryAxisAlignItems — replaced by Styles.mainAxisAlignment
• Styles.counterAxisAlignItems — replaced by Styles.crossAxisAlignment

Migration

• Styles.counterAxisSpacing → Styles.itemSpacing.vertical: read the vertical sub-field of the ItemSpacing object when axes differ; scalar itemSpacing applies uniformly
• Styles.layoutMode → LayoutMode | null: replace generic Style handling with exhaustive match on 'NONE' | 'HORIZONTAL' | 'VERTICAL'
• Styles.layoutWrap → Styles.wrap: rename only; same boolean semantics
• Styles.counterAxisAlignContent → Styles.wrapAlignment: rename and remap values — 'AUTO' → 'START', 'SPACE_BETWEEN' → 'SPACE_BETWEEN'
• Styles.primaryAxisAlignItems → Styles.mainAxisAlignment: rename and narrow type — replace generic Style handling with exhaustive match on 'START' | 'END' | 'CENTER' | 'SPACE_BETWEEN'; remap Figma values 'MIN' → 'START', 'MAX' → 'END'
• Styles.counterAxisAlignItems → Styles.crossAxisAlignment: rename and narrow type — replace generic Style handling with exhaustive match on 'START' | 'END' | 'CENTER' | 'STRETCH' | 'BASELINE'; remap Figma values 'MIN' → 'START', 'MAX' → 'END'

[0.17.0] - 2026-04-13

Introduces ResolvedConfig as the fully-resolved counterpart to Config, where every property with a default is guaranteed present. Config properties with defaults are now optional, making input configs more tolerant of omissions. Removes the unused Variant.name and Variant.baseline fields.

Added

• ResolvedConfig — fully-resolved config type where every property with a default is required; only true feature toggles (subcomponents, glyphNamePattern, codeOnlyPropsPattern) remain optional

Changed

• Config — all properties with defaults are now optional (input type tolerant of omissions):
  • processing.variantDepth — optional; defaults to 9999
  • processing.details — optional; defaults to LAYERED
  • format.output — optional; defaults to JSON
  • format.keys — optional; defaults to SAFE
  • format.layout — optional; defaults to LAYOUT
• ResolvedConfig — all properties with defaults are required (post-merge guarantee):
  • processing.slotConstraints — required (default false)
  • processing.inferNumberProps — required (default false)
  • format.tokens — required (default TOKEN)
  • include.invalidVariants — required (default false)
  • include.invalidCombinations — required (default true)
  • include.emptyVariants — required (default false)
  • subcomponents.scope — required when subcomponents is present (default NESTED)
• DEFAULT_CONFIG — typed as ResolvedConfig; now explicitly includes slotConstraints: false, inferNumberProps: false; removed subcomponents (feature toggle — off by default, matching the Figma plugin)

Removed

• Variant.name — unused optional label; variant identity is fully described by configuration
• Variant.baseline — never populated in output; baseline determination is an internal processing concern

Migration

• Variant.name → removed: delete any references; use Variant.configuration to identify variants
• Variant.baseline → removed: delete any references; no replacement needed (field was never populated)

[0.16.0] - 2026-04-05

Adds Config.include.emptyVariants for controlling inclusion of layered variants with no elements. Makes invalidVariants and invalidCombinations optional with sensible defaults, and removes the unused variantNames field.

Added

• Config.include.emptyVariants — optional boolean to control inclusion of layered variants that contain no elements; defaults to false

Changed

• Config.include.invalidVariants — now optional; defaults to false when absent
• Config.include.invalidCombinations — now optional; defaults to true when absent

Removed

• Config.include.variantNames — unused field removed from the API

Migration

• Config.include.variantNames → removed: delete any references to this field from config construction code; regenerate cached specs to remove the field from serialized output

[0.15.0] - 2026-03-25

Adds structured subcomponent discovery via a new Config.processing.subcomponents object with scope, match, and exclude settings, replacing the flat subcomponentNamePattern string. Introduces SubcomponentRef for referencing subcomponent definitions and widens instanceOf on both AnatomyElement and Element to accept it. Corrects Typography field types for leadingTrim, fontFamily, and fontStyle to match actual Figma API values.

Added

• SubcomponentRef — reference to a subcomponent definition via { $ref: "#/subcomponents/{key}" }
• AnatomyElement.instanceOf — widened to accept string | SubcomponentRef
• Element.instanceOf — widened to accept string | PropBinding | SubcomponentRef
• Config.processing.subcomponents — optional nested object grouping subcomponent discovery settings: scope, match, and exclude. Absence means no subcomponent detection
• Config.processing.subcomponents.scope — optional enum (NESTED | PAGE) controlling where the transformer searches for subcomponents
• Config.processing.subcomponents.match — required array of {C}/{S} template patterns defining which assets are subcomponents
• Config.processing.subcomponents.exclude — optional array of {C}/{S} template patterns defining which matched assets to exclude

Changed

• Typography.leadingTrim — corrected from number | 'mixed' | TokenReference to 'NONE' | 'CAP_HEIGHT' | 'mixed' per Figma API
• Typography.fontFamily — corrected from string | number | 'mixed' to string | 'mixed' | TokenReference; removed impossible number, added TokenReference for variable-bound fonts
• Typography.fontStyle — corrected from string | number | 'mixed' to string | 'mixed' | TokenReference; removed impossible number, added TokenReference for variable-bound fonts

Removed

• Config.processing.subcomponentNamePattern — replaced by Config.processing.subcomponents.match
• Config.include.subcomponents — subcomponent inclusion is now implied by the presence of match patterns

Migration

• Config.processing.subcomponentNamePattern → Config.processing.subcomponents.match: wrap the single pattern string in a one-element array
• Config.include.subcomponents → removed: remove the field; subcomponents are included when processing.subcomponents is defined with match patterns. Omit processing.subcomponents entirely to disable detection

[0.14.0] - 2026-03-18

Introduces code-only props support with FigmaCodeOnlySource provenance metadata and a configurable container-layer naming pattern, plus a new NumberProp type for numeric property values. Adds DTCG-aligned $extensions for platform-specific metadata across all prop types, replacing the prior x-platform convention on BooleanProp. Expands SlotProp with minItems, maxItems, and anyOf constraints consolidatable via the new slotConstraints processing flag.

Added

• FigmaCodeOnlySource — provenance metadata for props extracted from a Figma code-only container layer (kind, layer, instanceOf?)
• FigmaPropExtension.source — optional FigmaCodeOnlySource on the Figma extension, present only for code-only props
• Config.processing.codeOnlyPropsPattern — optional naming pattern for detecting the code-only props container layer
• Config.processing.inferNumberProps — opt-in flag to infer NumberProp from TEXT code-only props
• NumberProp — numeric property type for number-valued component props
• AnyProp — NumberProp added as a fifth union member (type: 'number')
• FigmaPropExtension — Figma-specific metadata for prop definitions (native prop type)
• PropExtensions — DTCG §5.2.3 platform-specific extensions container, keyed by reverse-domain notation
• BooleanProp.$extensions — optional platform metadata on boolean props
• StringProp.$extensions — optional platform metadata on string props
• EnumProp.$extensions — optional platform metadata on enum props
• SlotProp.$extensions — optional platform metadata on slot props
• SlotProp.minItems — minimum number of items the slot accepts
• SlotProp.maxItems — maximum number of items the slot accepts
• SlotProp.anyOf — component type names permitted in the slot
• Config.processing.slotConstraints — opt-in flag to consolidate slot constraint code-only props into slot properties

Changed

• BooleanProp — x-platform replaced by $extensions to align with DTCG convention used on TokenReference

[0.13.0] - 2026-03-13

Added

• Metadata.schema.latest — optional stable URL pointing to the latest schema on main for discovery
• Metadata.generator.license — optional resolved license state: status and level nested inside generator
• Styles.fillColor — glyph fill color for GLYPH element type
• StringProp.examples — sample values demonstrating typical content for string props
• Element.content — unified content for text strings and glyph names
• SlotProp.nullable — optional flag indicating the slot prop accepts null
• Conditional — conditional binding with if/condition/then/else for derived values
• ConditionExpression — declarative condition pairing an operation (string) with args
• ConditionArgs — condition arguments: value (PropBinding) and optional compareTo

Changed

• SlotProp.default — now optional; omitted when no meaningful default exists
• ColorStyleValue — accepts bare hex strings (e.g. #666E74) matching the existing ColorStyle type
• BooleanProp, StringProp, EnumProp, SlotProp — allow $-prefixed metadata fields via patternProperties
• Metadata.schema.url — clarified as versioned schema URL pinned to a git tag
• ElementType — 'icon' renamed to 'glyph' to distinguish raw visual assets from composed Icon components
• Config.processing.iconNamePattern → Config.processing.glyphNamePattern — glyph detection pattern
• StringProp.default — now optional; use examples for demo content
• StringProp.default — widened to string | null for nullable props
• SlotProp.default — widened to string | null for nullable slot props
• BindingKey — 'text' replaced by 'content'

Removed

• TextProp — merged into StringProp
• IconProp — merged into StringProp
• Element.text — use Element.content instead

Migration

• TextProp / IconProp → StringProp: replace all type imports and references with StringProp; the shape is identical
• Element.text → Element.content: read element content from content instead of text; applies to both text strings and glyph names
• ElementType 'icon' → 'glyph': update all references to the 'icon' literal in element type checks
• Config.processing.iconNamePattern → Config.processing.glyphNamePattern: update config objects and any code referencing this field

[0.12.0] - 2026-03-05

Added

• ElementTypeRef — reference to an external element type definition via $ref URI
• Config.processing.iconNamePattern — optional naming pattern for detecting icon content assets
• Sides — per-side composite object with logical directions: top, end, bottom, start
• Corners — per-corner composite object with logical directions: topStart, topEnd, bottomEnd, bottomStart
• Styles.padding — scalar when uniform, Sides object when per-side values differ

Changed

• AnatomyElement.type — widened from string to string | ElementTypeRef
• Styles.strokeWeight — accepts Style | Sides instead of Style; scalar when uniform, Sides object when per-side values differ
• Styles.cornerRadius — accepts Style | Corners instead of Style; scalar when uniform, Corners object when per-corner values differ

Removed

• Styles.paddingLeft — use Styles.padding with Sides.start instead
• Styles.paddingRight — use Styles.padding with Sides.end instead
• Styles.paddingTop — use Styles.padding with Sides.top instead
• Styles.paddingBottom — use Styles.padding with Sides.bottom instead
• Styles.strokeTopWeight — use Styles.strokeWeight with Sides.top instead
• Styles.strokeBottomWeight — use Styles.strokeWeight with Sides.bottom instead
• Styles.strokeLeftWeight — use Styles.strokeWeight with Sides.start instead
• Styles.strokeRightWeight — use Styles.strokeWeight with Sides.end instead
• Styles.topLeftRadius — use Styles.cornerRadius with Corners.topStart instead
• Styles.topRightRadius — use Styles.cornerRadius with Corners.topEnd instead
• Styles.bottomLeftRadius — use Styles.cornerRadius with Corners.bottomStart instead
• Styles.bottomRightRadius — use Styles.cornerRadius with Corners.bottomEnd instead

Migration

• Styles.paddingLeft / paddingRight / paddingTop / paddingBottom → Styles.padding: when all sides are equal, read padding as a number; when sides differ, read padding as a Sides object with top, end, bottom, start using logical directions (start = left in LTR)
• Styles.strokeTopWeight / strokeBottomWeight / strokeLeftWeight / strokeRightWeight → Styles.strokeWeight: same scalar-or-Sides pattern; individual per-side stroke weights now live under Sides.top, Sides.end, Sides.bottom, Sides.start
• Styles.topLeftRadius / topRightRadius / bottomLeftRadius / bottomRightRadius → Styles.cornerRadius: same scalar-or-Corners pattern; per-corner values use Corners.topStart, Corners.topEnd, Corners.bottomEnd, Corners.bottomStart

[0.11.0] - 2026-03-04

Added

• PropBinding — component-prop binding type; discriminated by $binding key; replaces ReferenceValue
• TokenReference — unified DTCG-aligned token reference; replaces VariableStyle and FigmaStyle; $token and $type are the complete platform-facing API
• TokenReference.$token — DTCG dot-separated token path, usable directly as a DTCG alias
• TokenReference.$type — DTCG token type discriminator: color, dimension, string, number, boolean, shadow, gradient, typography, effects
• TokenReference.$extensions["com.figma"] — optional Figma extraction metadata: id, name, collectionName, rawValue
• Styles.typography — composite typography; value is TokenReference, Typography, or omitted
• Typography — 13 optional inline text properties: fontSize, fontFamily, fontStyle, lineHeight, letterSpacing, textCase, textDecoration, paragraphIndent, paragraphSpacing, leadingTrim, listSpacing, hangingPunctuation, hangingList
• Styles.aspectRatio — aspect ratio constraint; AspectRatioValue pair or null when unconstrained
• AspectRatioValue — required x (numerator) and y (denominator) number fields
• AspectRatioStyle — type alias AspectRatioValue | null
• Config.format.tokens — token reference serialization profile; five options: TOKEN (default, $token + $type), TOKEN_NAME (dot-delimited path string only), TOKEN_FIGMA_EXTENSIONS ($token + $type + $extensions["com.figma"]), FIGMA_NAME (slash-delimited path string only), CUSTOM (same as TOKEN, signals custom post-processing)
• Metadata.license? — optional { status: string; description: string } field
• styles.textColor — style key for text colour
• styles.cornerSmoothing — style key for corner smoothing (Figma squircle factor)
• styles.effects — style key replacing effectStyleId; TokenReference or inline Effects
• Shadow — fields: visible, inset?, offsetX, offsetY, blur, spread, color
• Blur — fields: visible, radius
• Effects — fields: shadows?, layerBlur?, backgroundBlur?
• GradientStop — fields: position (0–1), color
• GradientCenter — fields: x, y (0–1)
• LinearGradient — discriminated by type: 'LINEAR'; fields: angle, stops
• RadialGradient — discriminated by type: 'RADIAL'; fields: center, stops
• AngularGradient — discriminated by type: 'ANGULAR'; fields: center, stops
• GradientValue — discriminated union LinearGradient | RadialGradient | AngularGradient

Changed

• Element.instanceOf — accepts string | PropBinding; bound form is { $binding: "#/props/..." }
• Element.text — accepts string | PropBinding; bound form is { $binding: "#/props/..." }
• Style — PropBinding replaces ReferenceValue; TokenReference replaces VariableStyle and FigmaStyle
• Config.format — variables, simplifyVariables, and simplifyStyles replaced by single tokens field; token output shape is now controlled entirely by the tokens profile
• Styles.backgroundColor — narrowed to ColorStyle; inline gradients representable
• Styles.textColor — narrowed to ColorStyle; inline gradients representable
• Styles.strokes — narrowed to ColorStyle; inline gradients representable
• styles.fills renamed to styles.backgroundColor

Removed

• Config.format.variables — removed; use Config.format.tokens instead
• Config.format.simplifyVariables — removed; use Config.format.tokens profile instead
• Config.format.simplifyStyles — removed; use Config.format.tokens profile instead
• ReferenceValue — removed; use PropBinding instead
• isReferenceValue — removed; no replacement; prop-binding guards are upstream consumer responsibility
• VariableStyle — removed; use TokenReference instead
• FigmaStyle — removed; use TokenReference instead
• Styles.fontSize — removed; use typography.fontSize instead
• Styles.fontFamily — removed; use typography.fontFamily instead
• Styles.fontStyle — removed; use typography.fontStyle instead
• Styles.lineHeight — removed; use typography.lineHeight instead
• Styles.letterSpacing — removed; use typography.letterSpacing instead
• Styles.textCase — removed; use typography.textCase instead
• Styles.textDecoration — removed; use typography.textDecoration instead
• Styles.paragraphIndent — removed; use typography.paragraphIndent instead
• Styles.paragraphSpacing — removed; use typography.paragraphSpacing instead
• Styles.leadingTrim — removed; use typography.leadingTrim instead
• Styles.listSpacing — removed; use typography.listSpacing instead
• Styles.hangingPunctuation — removed; use typography.hangingPunctuation instead
• Styles.hangingList — removed; use typography.hangingList instead
• Styles.textStyleId — removed; use typography with a TokenReference instead
• styles.effectStyleId — removed with no deprecation period; consumers must migrate to styles.effects

Migration

• config.format.variables / simplifyVariables / simplifyStyles → config.format.tokens: set tokens to a profile — TOKEN (default) for $token + $type; TOKEN_NAME for dot-delimited string; TOKEN_FIGMA_EXTENSIONS for full object with Figma metadata; FIGMA_NAME for slash-delimited string; CUSTOM for custom post-processing
• Element.instanceOf → Element.instanceOf: replace { $ref: "#/props/..." } with { $binding: "#/props/..." }; update any isReferenceValue guards to narrow against $binding directly
• Element.text → Element.text: same key rename from $ref to $binding
• Styles.visible → Styles.visible: same key rename from $ref to $binding
• VariableStyle → TokenReference: replace { id, variableName, collectionName } with { $token: "<Collection>.<name>", $type: "<type>", $extensions: { "com.figma": { id, name, collectionName } } }; read token path from $token and token category from $type
• FigmaStyle → TokenReference: replace { id, name } with { $token: "<dot.path>", $type: "typography" | "effects" | ... } and move the Figma UUID to $extensions["com.figma"].id
• Styles.<typographyProperty> → Styles.typography.<property>: all 14 flat typography properties replaced with single composite typography field; when typography is a TokenReference, read $token for the style path; when typography is a Typography object, read individual fields
• fills → backgroundColor: any consumer reading component.styles.fills must update to component.styles.backgroundColor
• effectStyleId → effects: any consumer reading styles.effectStyleId must update to styles.effects; when effects is a TokenReference, read $token and $type; when effects is an Effects, read from shadows, layerBlur, or backgroundBlur by role

[0.9.0] - 2026-02-12

Added

• DEFAULT_CONFIG - Default configuration constant for transformer setup
  • Provides sensible defaults for all Config fields
  • Ensures consistent behavior across CLI, MCP, and Plugin environments
  • Co-located with Config type definition for easy maintenance

[0.10.0] - 2026-02-16

Added

• Runtime JS build - Compile TypeScript types to dist/index.js for ESM consumers
  • Enables ESM runtime imports without loading .ts files
  • Keeps type definitions in types/ for TypeScript tooling

[0.8.0] - 2026-02-10

Added

• TypeScript type definitions (types/ package): Complete type definitions for all schema entities
  • Core types: Component, Anatomy, Props, Variant, Metadata, Config, Styles, Element, Layout
  • Property types with proper discriminators: BooleanProp, TextProp, IconProp, EnumProp, SlotProp
  • Style types supporting all 59 properties with specific value types
  • Reference value types for prop bindings and style references

Changed

• Component.metadata - Now optional to support components without full metadata
• Variant.layout - Changed from single LayoutNode to array of LayoutNode for proper hierarchical representation
• Props type values - TextProp, IconProp, and EnumProp now use type: 'string' with discriminators (matching schema)
• Style properties - Changed from generic Record<string, Style> to specific Partial interface with all 59 style properties
• VariableStyle - Now includes all properties from schema: id (required), rawValue, name, variableName, collectionName, collectionId (all optional)
• FigmaStyle - Simplified to match schema: id (required), name (optional)

Fixed

• SlotProp.default - Now accepts both null and string types
• TextProp/IconProp nullable - Made nullable field optional (was incorrectly required)
• Metadata.source - Added missing nodeType field with enum: COMPONENT | COMPONENT_SET | FRAME
• Metadata.config - Added complete Config definition with processing, format, and include options
• StyleKey type - Expanded from incomplete list to all 59 valid style properties matching schema

[0.7.0]

Changed

• Added distinct anatomy types for line, ellipse, star, polygon and rectange, all which were previously vector
• Removed autodetecion of icon assets based on isAsset plugin since this function is unavailable in the REST API

[0.6.0] - 2026-01-27

Added

• Styles schema: New styles.schema.json providing complete validation for style properties

  • Defines 60+ style properties (fills, opacity, cornerRadius, fontSize, etc.)
  • Type-specific validation for each property based on Style processor classes
  • Supports all style value types: primitives, variables, Figma styles, and prop bindings
  • Documents which value shapes depend on config.format settings (simplifyVariables, simplifyStyles)

• Style value types: Precise type definitions for style property values

  • NumberStyleValue: number | VariableStyle | null
  • BooleanStyleValue: boolean | VariableStyle | null
  • BooleanBindableStyleValue: boolean | VariableStyle | ReferenceValue | null (for visible only)
  • ColorStyleValue: string | VariableStyle | FigmaStyle | null
  • StringStyleValue: string | VariableStyle | null
  • MixedNumberStyleValue: number | “mixed” | VariableStyle | null
  • MixedStringStyleValue: string | VariableStyle | null
  • StrokeStyleValue: number | “mixed” | VariableStyle | null
  • CornerStyleValue: number | “mixed” | VariableStyle | null
  • FontStyleValue: string | number | “mixed” | null
  • LineHeightStyleValue: string | number | VariableStyle | null
  • StyleIdValue: string | FigmaStyle | null

• Styles reference documentation: New reference/styles.yaml providing human-readable documentation

  • Maps style properties to their applicable element types (COMPONENT, FRAME, TEXT, etc.)
  • Documents style processing categories from RAW_STYLES_LOOKUP
  • Lists all 60+ style properties with descriptions and value types
  • Generated from StyleKeys.ts and RawStyles.ts constants

Changed

• VariableStyle definition: Removed internal-only rawValue property

  • Only includes properties emitted by Style.data(): id, name, variableName, collectionName, collectionId
  • rawValue is used internally for rendering but never serialized

• FigmaStyle definition: Improved descriptions

  • Documents simplified vs full object output based on config.format.simplifyStyles

• Styles property: Now references styles.schema.json#/definitions/Styles

  • Replaces generic additionalProperties: Style with precise property-level validation
  • Each style property validates against its specific value type union

[0.5.0] - 2025-12-29

Added

• Instance of attribute: Added optional instanceOf property to element definitions

  • Indicates the component or component set name that an instance element references
  • Only present for instance elements (Figma INSTANCE nodes)
  • Shows ComponentSet name for variant instances, or Component name for standalone instances
  • Also added to anatomy element definitions

• Text property: Added optional text property to element definitions

  • Contains the text content for text elements
  • Can be a string value or a ReferenceValue when bound to a text prop

• Unified property bindings: Property bindings now appear as $ref values on their natural properties

  • children can now be a ReferenceValue (for slot content bindings)
  • instanceOf can now be a ReferenceValue (for instance swap bindings)
  • visible style can now be a ReferenceValue (for boolean prop bindings)
  • text can be a ReferenceValue (for text prop bindings)
  • Added ReferenceValue definition with $ref JSON pointer to props

Removed

• propBindings section: Removed separate propBindings property from elements
  • Bindings are now represented directly on their target properties using $ref

[0.4.0] - 2025-12-27

Added

• Layout structure: Added optional layout property to variant definitions that provides hierarchical element structure as a nested tree
  • Layout represents element nesting relationships in a recursive format
  • Leaf nodes are strings (element names)
  • Parent nodes are objects with element name as key and children array as value
  • Example: { "parentElement": ["childA", { "childB": ["grandchild"] }] }

Changed

• Schema now supports both structure representations:
  • New: layout at variant level (hierarchical tree)
  • Existing: parent and children properties in each element (maintained for backward compatibility)

Deprecated

• included property has been removed from element definitions
  • Element inclusion is now determined by presence in the layout tree
  • Elements not present in layout are considered excluded from that variant

[0.3.0] - Previous release

Versions

• 0.24.0 — 2026-06-05
• 0.23.0 — Unreleased
• 0.22.0 — 2026-05-23
• 0.21.0 — 2026-05-22
• 0.20.0 — 2026-05-06
• 0.19.0 — 2026-04-28
• 0.18.0 — 2026-04-24
• 0.17.0 — 2026-04-13
• 0.16.0 — 2026-04-05
• 0.15.0 — 2026-03-25
• 0.14.0 — 2026-03-18
• 0.13.0 — 2026-03-13
• 0.12.0 — 2026-03-05
• 0.11.0 — 2026-03-04
• 0.9.0 — 2026-02-12
• 0.10.0 — 2026-02-16
• 0.8.0 — 2026-02-10
• 0.7.0
• 0.6.0 — 2026-01-27
• 0.5.0 — 2025-12-29
• 0.4.0 — 2025-12-27
• 0.3.0 — Previous release

@specs-cli

[0.20.0] - 2026-06-07

Introduces the specs analyze command with two analyzers: props (cross-library prop governance aggregate) and styling (token usage dictionary, moved from transforms). Extends the css and contract transformers with subcomponent support, a configurable CSS rule pipeline, and the border-shift-inset-shadow rule. Refines css output: boolean props emit presence selectors and disabled guards wrap hover/active.

Added

• specs analyze command — New command for on-demand analysis passes over component specs. Accepts one or more analyzer names as positional arguments (specs analyze props, specs analyze props styling). Output goes to _analysis/ by default; override with --analysis <path>. No config key — analyzers are run on demand, not as part of the regular transform pipeline.

• props analyzer — Reads every component’s api.yaml and produces _analysis/props.yaml: a cross-library aggregate with six sections — summary counts, prop name frequency, enum discordance (same prop name, divergent value sets), boolean naming patterns, API surface per component, and a slot inventory. Designed as structured input for LLM-assisted API governance analysis.

• styling analyzer — Moved from the transform registry to the analyzer registry. Writes _analysis/styling.byComponent.json and _analysis/styling.byToken.json (previously written to _dictionary/). Invoke with specs analyze styling.

• css transformer: subcomponent support — For each entry in variants.yaml’s subcomponents map, emits a styles.css inside a dedicated subfolder named after the subcomponent key (e.g. dsActionList/group/styles.css). BEM selectors are scoped to the subcomponent’s own kebab-case class name (e.g. .group, .group__text). Subcomponent subdirs are created automatically.

• contract transformer: subcomponent support — For each entry in api.yaml’s subcomponents map, emits a contract.ts inside a dedicated subfolder named after the subcomponent key (e.g. dsActionList/group/contract.ts). Interface and enum type names are prefixed with both the component and subcomponent name (e.g. DsActionListGroupProps). Subcomponent subdirs are created automatically.

• css transformer: configurable rule pipeline — The css transformer now accepts a rules list under its transformer options. Rules run as pre-passes on the structured variants data before CSS emission, enabling semantic rewrites that require cross-variant context. Configure per-component in specs.config.yaml:

  transformers:
    - name: css
      rules:
        - border-shift-inset-shadow

• css transformer: border-shift-inset-shadow rule — Eliminates layout shift from border-width changes across variants. Detects elements whose strokeWeight or strokes change in any variant (INSIDE strokes only), rewrites the default block to reserve space with a transparent border (border: Npx solid transparent), and rewrites variant stroke changes to box-shadow: inset 0 0 0 Npx <color>. OUTSIDE and CENTER strokes are unaffected (they use outline, which is already layout-safe).

Changed

• css transformer: presence selectors for boolean props — Data attribute selectors for variant props whose value is a JS boolean true now emit [data-x] (presence) instead of [data-x="true"] (value). String-valued props (e.g. checked: "checked", checked: "indeterminate") continue to emit value selectors. Matches the TSX idiom data-x={value || undefined}.

• css transformer: :not(:disabled) guard on hover/active — When the disabled concept is configured in processing.states, :hover and :active selectors (including compound variants like [data-checked="checked"]:hover) are automatically guarded with :not(:disabled):not([aria-disabled="true"]) to prevent interaction styles from applying to disabled elements.

Removed

Dependency updates

• No upstream dependency changes since 0.19.0. Continues to reference @directededges/specs-schema ^0.24.0 and @directededges/specs-from-figma ^0.22.0.

[0.19.0] - 2026-06-05

Introduces the specs transform command and three transformers: contract (typed Props interface + Defaults), css (BEM stylesheet with token vars and concept-driven state selectors via processing.states), and styling (token usage dictionary). Specs generated by the CLI now correctly identify themselves in metadata.generator instead of reporting the Figma plugin. Upstream: specs-from-figma v0.22.0 adds RestFoundations.generator for caller identity and fixes INSTANCE width/height variable bindings; specs-schema v0.24.0 adds Config.transformers, workspace.schema.json, and Config.processing.states.

Added

• specs transform command — Discovers component subfolders under the output directory (each must contain api.yaml) and runs one or more named transformers against every component. Transformer names resolve in priority order: positional arguments → config.transformers → CLI default (contract). Accepts -o/--output, --config, and --verbose options. Closes DirectedEdges/specs#137

• contract transformer — Emits contract.ts per component: a typed Props interface (enum union types, nullable types, slot props excluded) and a Defaults const (satisfies Props) for every prop with a declared default. Default transformer when none are specified. Closes DirectedEdges/specs#137

• css transformer — Emits styles.css per component from variants.yaml. Default element styles become root/BEM-child selectors; variant configurations become [data-propName="value"] attribute selectors (camelCase prop names kebabized); multi-prop configurations produce compound selectors. Token references resolve to var(--) based on config.format.tokens: path-derived kebab for TOKEN/TOKEN_NAME/FIGMA_NAME; verbatim for FIGMA_SYNTAX_WEB vars that already start with --; $cssVar field or path derivation for CUSTOM. Closes DirectedEdges/specs#139

• styling transformer — Emits styling.json per component: token/style usage grouped by category (variables, colorStyles, textStyles, effectStyles), each row recording name, appliedAs, and appliedTo (anatomy element → occurrence count). After all components run, finalize() writes two aggregate files to _dictionary/: styling.byComponent.json (all components combined) and styling.byToken.json (token-first index: token name → components/elements using it). Subcomponents appear as dot-separated keys. Closes DirectedEdges/specs#138

• config.transformers block in init config template — specs init now generates a commented-out transformers: block showing all three transformers, ready to uncomment.

• processing.states support in css and contract transformers — Both transformers now read config.processing.states, a concept-keyed map that classifies Figma variant props as semantic states. The css transformer emits real CSS pseudo-classes (:hover, :active, :focus-within) and ARIA attribute selectors ([aria-disabled="true"], [aria-invalid="true"]) for classified props instead of data-* attribute selectors. The contract transformer omits browser-driven props from generated Props interfaces automatically — no additional config flag required. prop and value bridge any naming gap between library conventions (e.g. isDisabled, pressed) and canonical concept names. Absence of processing.states is backward-compatible: all props continue to emit as data-* selectors and appear in contracts unchanged.

Fixed

• metadata.generator now correctly identifies the CLI — Previously, specs generated by the CLI reported the Figma plugin name, version, and URL in metadata.generator. The CLI now passes { name: '@directededges/specs-cli', version, url } via RestFoundations.generator, and the version is stamped from __SPECS_CLI_VERSION__ injected at build time. Closes DirectedEdges/specs#133

Changed

Removed

Dependency updates

• @directededges/specs-schema → ^0.24.0 — adds Config.transformers (flat array, replaces config.transform.transformers), workspace.schema.json for IDE validation of specs.config.yaml, and Config.processing.states (Record<string, VariantStateEntry>) for concept-keyed variant state classification.
• @directededges/specs-from-figma → ^0.22.0 — RestFoundations.generator lets the CLI supply its own identity to metadata.generator; fixes INSTANCE width/height variable bindings; color components values rounded to 4dp.

[0.18.0] - 2026-05-29

Hardens license-key validation to hard-fail on transient errors and improves actionable error messages for stale or inaccessible Figma file keys.

Fixed

• generate no longer silently produces free-tier output when a license key can’t be validated (#119) — if a key was supplied (via -l, SPECS_LICENSE_KEY, or ANOVA_LICENSE_KEY) but the license check could not be completed — a transient proxy/network failure or a rate-limit (e.g. the upstream validator returning 429) — the run previously fell back to FREE and wrote free-tier specs under a valid paid key, with only an easily-missed status line. generate now hard-fails on these transient states (network-error, error, and a future rate-limited) with an actionable message (“retry in a few seconds, or remove the key for free-tier output”) and a retryable exit code (NETWORK_ERROR, or RATE_LIMIT once the validator distinguishes it). Definitive key rejections (invalid/removed/expired) still fall back to free-tier output as before.
• Actionable fetch/generate error messages for stale or inaccessible Figma file keys (#125) — a fetch that hit a 404 previously surfaced only HTTP 404 while fetching <alias>.<kind>, with no hint that the cause was the file key pinned in config. The 404 case now explains that the configured key is likely stale or out of reach (file moved/deleted/recreated, or the token can’t open it) and points at sources.<alias>.key in the config file. Auth failures are split: 401 reports a missing/invalid/expired FIGMA_TOKEN and where to set it (.env), while 403 reports valid-but-no-access and points at the same config key. In generate, a missing source .file.json now tips the user to run specs fetch or check sources.<alias>.key.

Dependency updates

• @directededges/specs-from-figma ^0.20.0 → ^0.21.0 — SLOT elements now evaluate the same container-surface styles as frames: auto-layout config, strokes, padding, and corner-smoothing. Slot styling in generated specs is more complete.
• @directededges/specs-schema ^0.22.0 — no version change.

[0.17.0] - 2026-05-23

Surfaces the new composition/examples model to CLI users: config loading now accepts include.defaultSlotContent and the processing.instanceExamples block, so generated specs can include slot-content examples and pre-configured instance examples (both Pro-gated). --split-concerns gains a third examples.yaml output for these examples, and a fix ensures they’re no longer silently dropped when splitting concerns.

Added

• Examples config (ADR-050) — ConfigLoader now accepts the new include.defaultSlotContent flag (added to the include allowlist) and validates processing.instanceExamples (scope ∈ PAGE/FILE with PAGE fallback; match required; exclude/parentNames array-checked), passing them through to the engine. instanceExamples output is driven by the presence of processing.instanceExamples (no include.instanceExamples flag), mirroring subcomponents. Both example features are Pro-gated — silently omitted on the free tier. Surfaces slotContentExamples/instanceExamples generation to CLI users.

Changed

• --split-concerns now emits a third examples.yaml — slot-content and instance examples are written to examples.yaml (per-concern mode) or <component>/examples.yaml (combined mode), alongside api.yaml and variants.yaml. The file is emitted only when at least one component has examples, and components without examples are omitted from it.

Fixed

• --split-concerns no longer drops examples — slotContentExamples and instanceExamples (component- and subcomponent-level) were assigned to neither the api nor variants concern, so --split-concerns silently discarded them, leaving the $slotContent references in default/variants dangling. They are now routed into examples.yaml.

Removed

Dependency updates

• @directededges/specs-schema ^0.21.0 → ^0.22.0 — adds the composition and slot-content model (ADR-042, 046–052): Composition, SlotContent, and the universal SlotContentRef ({ $slotContent }) pointer, plus Component.slotContentExamples and Component.instanceExamples. Specs can now carry named slot-content examples and documented instance examples, and Config gains processing.instanceExamples (example detection) and include.defaultSlotContent (output gate).
• @directededges/specs-from-figma ^0.19.0 → ^0.20.0 — detects and emits slot-content examples (de-duplicated across variants and slots) and instance examples (pre-configured usages of a component), both Pro-gated. REST page/file-scoped discovery now correctly finds candidates under CANVAS nodes, and a plugin-only hashing bug that collapsed all slot fills into a single example is fixed.

[0.16.0] - 2026-05-22

Adds the platform code-syntax token profiles (FIGMA_SYNTAX_WEB/IOS/ANDROID) to config loading and templates, so specs can emit each Figma variable’s per-platform code syntax. Picks up upstream transformer improvements: conditional-visibility boolean prop exposure, detection of subcomponents nested inside sections/frames, and a fix for SLOT properties that previously leaked raw GUID objects into output.

Added

• Platform code-syntax token profiles (ADR-051, DirectedEdges/specs#103) — format.tokens now accepts FIGMA_SYNTAX_WEB, FIGMA_SYNTAX_IOS, and FIGMA_SYNTAX_ANDROID in config loading and templates, surfacing the platform code-syntax profiles to CLI users. The transformer (specs-from-figma) emits each variable’s Figma codeSyntax for the selected platform, falling back to the standard token output when a platform has no code syntax defined.

Dependency updates

• @directededges/specs-schema ^0.20.0 → ^0.21.0 — adds the FIGMA_SYNTAX_WEB/IOS/ANDROID format.tokens profiles.
• @directededges/specs-from-figma ^0.18.0 → ^0.19.0 — serializes the new platform code-syntax profiles from Figma codeSyntax; specs now expose a boolean-prop reference for conditional visibility bindings; subcomponents nested inside sections/frames are now detected under subcomponents.scope: PAGE; SLOT properties no longer emit raw GUID objects into output.

[0.15.1] - 2026-05-20

Patch release fixing the scan → generate round-trip. generate now accepts the v2 (markdown-table) manifests that scan has emitted since 0.15.0, restoring the documented workflow.

Fixed

• generate now accepts v2 (table) manifests — generate’s source auto-detection only recognized the legacy v1 checkbox-list format (- [), so any manifest produced by specs scan in 0.15.0 failed with Error: Unrecognized source format, breaking the documented scan && generate round-trip. generate now detects v2 manifests via the **Scan format version:** header and dispatches to ManifestParserV2, while continuing to support v1 manifests and raw JSON files. (#101)
• Escaped pipes in component names round-trip — scan escapes | as \| in manifest table cells; ManifestParserV2 now unescapes them so names like Toggle | On/Off parse back to their literal form.

Dependency updates

• No upstream dependency changes since 0.15.0. Continues to reference @directededges/specs-schema ^0.20.0 and @directededges/specs-from-figma ^0.18.0.

[0.15.0] - 2026-05-15

scan now drives curation from Figma’s Ready for Dev signal and merges intelligently with prior manifests, preserving manual edits except where Figma’s devStatus has changed. Introduces a new v2 manifest format with automatic migration from v1.

Added

• Ready-for-Dev curation in scan — Components with devStatus: READY_FOR_DEV are now checked by default. Libraries with no devStatus signal anywhere fall back to the legacy heuristic.
• Manifest merge on rescan — Re-running scan preserves manual checkbox edits unless devStatus changed for a row (Figma wins on flips). --keep-checks locks manual edits regardless of devStatus changes; --reset-checks ignores the prior manifest entirely.
• Glyphs section in scan manifest — When config.processing.glyphNamePattern is set, top-level components matching the pattern are routed to a read-only ## Glyphs section after ## Components. Glyph rows have no checkboxes and are excluded from specs generate. The section is omitted when no matches are found. Pattern matching reuses the same {i}-placeholder semantics as the engine’s glyph detection.
• v2 manifest format — New markdown-table format with a Dev Status column, **Scan format version:** header, and **File last modified:** metadata. Legacy v1 (checkbox-list) manifests are detected and migrated automatically.

Changed

• Docs updated — cli/commands/scan.md, cli/getting-started.md, and cli/workflows.md reflect the new curation flow and manifest format.

Dependency updates

• No upstream dependency changes since 0.14.0. Continues to reference @directededges/specs-schema ^0.20.0 and @directededges/specs-from-figma ^0.18.0.

[0.14.0] - 2026-05-15

Dependency-only release that picks up specs-from-figma 0.18.0. No CLI source changes.

Dependency updates

• @directededges/specs-from-figma 0.18.0 — Restores ~170 invalid variants previously dropped by the empty-variant filter, accounting for the bulk of test-round 0009 parity diffs. Fixes a figma.mixed Symbol crash on text nodes with mixed text styles. TEXT elements now emit explicit size styles (width, height, minWidth, minHeight, maxWidth, maxHeight); GLYPH elements now emit shadow/blur effects and aspect-ratio constraints alongside their fill color.

[0.13.1] - 2026-05-08

Patch fix for --split-concerns output shape.

Fixed

• props defaults to {} instead of [] when a component has no props (#84) — splitComponentByConcern and extractApiFromSubcomponents were filling missing props with an empty array, producing output that violated the schema (Props is an object). Components with no props (e.g. a divider) now emit props: {}. The ComponentApiData and SubcomponentApiData interfaces are corrected to type props as Record<string, any>.

[0.13.0] - 2026-05-06

Adds configurable color output format (config.format.color) with nine options from hex strings to structured DTCG Color objects. Fixes EISDIR crash when outputDirectory targets a directory, and corrects config template URLs.

Added

• config.format.color — validates and normalizes the new ColorFormat option (HEX, HEXA, RGB, RGBA, HSLA, HSB, OKLCH, OKLAB, OBJECT); defaults to HEX. Config template updated with inline docs. (ADR 043)

Fixed

• EISDIR when outputDirectory is a directory in single-file mode (#34) — When outputDirectory pointed to an existing directory (e.g. from a prior --split-components run), specs generate without split flags crashed with EISDIR. Now appends library.{format} as the default filename.
• Config template URLs now point to the doc site (directededges.github.io/specs/config/...) instead of 404ing GitHub raw paths (#43)

Dependency updates

• @directededges/specs-schema 0.20.0 — New Config.format.color option typed as ColorFormat. ColorValue renamed to ColorObject. ColorStyle, Shadow.color, and GradientStop.color widened to accept formatted color strings alongside structured objects and token references.
• @directededges/specs-from-figma 0.17.0 — Ten bug fixes: INSTANCE_SWAP prop resolution now correctly resolves names, strips glyph patterns, and formats keys; visible: true no longer leaks into default variant output; auto-layout fallback elements emit correct width/height; glyph fill colors on nested instances now resolve to token references instead of raw hex. RAW colors emit structured ColorValue objects per ADR-009.

[0.12.2] - 2026-04-28

Dependency update: picks up constraint-based layout positioning from specs-schema 0.19.0 and specs-from-figma 0.16.0. Also fixes glyph instanceOf leaking into variant output.

Dependency updates

• @directededges/specs-schema 0.19.0 — Positioning properties x, y, and layoutPositioning are replaced by constraint-based equivalents: position ('AUTO' | 'ABSOLUTE'), top, bottom, start, end, centerHorizontalOffset, and centerVerticalOffset. Offset values are pixel numbers for MIN/MAX/CENTER/STRETCH constraints and percentage strings (e.g. "25%") for SCALE constraints.
• @directededges/specs-from-figma 0.16.0 — Specs now emit constraint-based positioning instead of raw pixel coordinates. A new postEvaluate pipeline step ensures positioning values are computed before variant differencing, so variant diffs correctly capture position changes. Fixes glyph elements incorrectly emitting instanceOf in variant output, and SCALE constraints now emit both start and end percentages.

---

[0.12.1] - 2026-04-24

Dependency patch: picks up specs-from-figma 0.15.1 subcomponent indexer propagation fix.

Dependency updates

• @directededges/specs-from-figma 0.15.1 — Fixed subcomponent indexer propagation: getMainComponentAsync() now correctly sets the indexer on parent COMPONENT_SET nodes, eliminating “[RestInstanceNode] No indexer set” warnings during subcomponent discovery.

---

[0.12.0] - 2026-04-24

Dependency update: picks up specs-schema 0.18.0 layout property renames and specs-from-figma 0.15.0 bi-axial spacing model.

Dependency updates

• @directededges/specs-schema 0.18.0 — Layout alignment properties renamed from Figma axis terminology to platform-neutral names: primaryAxisAlignItems → mainAxisAlignment, counterAxisAlignItems → crossAxisAlignment, counterAxisAlignContent → wrapAlignment, layoutWrap → wrap. counterAxisSpacing consolidated into a bi-axial itemSpacing model. layoutMode narrowed from generic style to strict 'NONE' | 'HORIZONTAL' | 'VERTICAL' enum.
• @directededges/specs-from-figma 0.15.0 — Wrap-enabled auto-layout frames now emit bi-axial itemSpacing with horizontal/vertical fields instead of separate itemSpacing/counterAxisSpacing keys. Alignment values remapped from Figma terminology (MIN → START, MAX → END). wrapAlignment is only emitted when wrap: true, stripped as dead otherwise.

[0.11.0] - 2026-04-16

Fix: config file split options (splitComponents, splitConcerns, useSubfolders) were ignored because Commander’s explicit false default shadowed the config values. Also makes generate and scan runnable with zero arguments using a default file path derived from config.

Added

• generate now runs without arguments. When no source argument is provided, generate resolves the manifest path to {dataDirectory}/{alias}.manifest.md using the source alias from specs.config.yaml (prefers library, otherwise the first source alias whose data includes file). Running specs generate with no flags now uses this default manifest plus outputDirectory from config — matching the zero-arg ergonomics of scan and fetch. If no source alias has data: [file], an error suggests running specs scan first.
• scan now runs without arguments. The <file> positional argument is now optional. With one source configured in specs.config.yaml (whose data includes file), specs scan auto-resolves {dataDirectory}/{alias}.file.json. An explicit file path still works and takes precedence.
• scan --source <alias> flag. When two or more sources in specs.config.yaml have data: [file, ...], scan fails loudly with the list of available aliases and requires --source <alias> to disambiguate. Passing both [file] and --source is rejected as a conflict. This stricter convention (vs. generate’s preference-based fallback) prevents silent behavior changes when a second source is added to config.

Fixed

• Config file split options now take effect. Commander boolean flags (--split-components, --split-concerns, --use-subfolders) previously defaulted to false, which caused the nullish coalescing chain (options.flag ?? config.value ?? false) to short-circuit before consulting specs.config.yaml. Removed the Commander defaults so the flags are undefined when absent, allowing config values to flow through.

Docs

• Updated docs/cli/ (index, getting-started, claude-onboarding, examples, commands/generate, commands/scan, commands/index, commands/apply-custom-tokens) to document and demonstrate the zero-arg specs generate workflow. Existing specs generate components.md examples are preserved where they document explicit-argument option behavior.

Dependency updates

• No upstream package changes. Continues to target @directededges/specs-schema ^0.17.0 and @directededges/specs-from-figma ^0.14.2.

[0.10.2] - 2026-04-14

Dependency patch: picks up the DTCG-compliant token path separator fix from specs-from-figma.

Changed

• Bump @directededges/specs-from-figma to ^0.14.2 — Picks up the fix for $token path separators violating DTCG character restrictions.

Dependency updates

• @directededges/specs-from-figma 0.14.2 — Token references ($token values) in TOKEN, TOKEN_NAME, TOKEN_FIGMA_EXTENSIONS, and CUSTOM profiles now use / as the path separator instead of . (period). The DTCG spec (§5.1.1) prohibits . in token and group names, and this aligns all profiles with the existing FIGMA_NAME behavior.

[0.10.1] - 2026-04-14

Dependency patch: picks up a fix from specs-from-figma for empty variant filtering in LAYERED mode.

Changed

• Bump @directededges/specs-from-figma to ^0.14.1 — Picks up the fix for empty variant filtering in LAYERED mode, where variants with configuration but no element or layout differences were not being excluded when emptyVariants: false.

Dependency updates

• @directededges/specs-from-figma 0.14.1 — Fixes the emptyVariants: false filter in LAYERED mode. Previously, variants that had a configuration object but no elements array (e.g., variants with only layout differences removed) were incorrectly retained in output. The filter now correctly excludes variants that lack both element and layout differences from their layered baseline.

[0.10.0] - 2026-04-13

Renames audit → scan, sourceDirectory → dataDirectory, and the config file from .specs.config.yaml to specs.config.yaml. Adds a --data-dir flag and makes config format values case-insensitive. Config types now use ResolvedConfig for full default guarantees.

Added

• --data-dir flag on fetch, scan, and generate — Override the config dataDirectory per run from the command line. On fetch, --outDir is retained as a deprecated alias.

Changed

• Config file renamed from .specs.config.yaml to specs.config.yaml — The config file is no longer a hidden dotfile. Specs config is actively edited (Figma file keys, output directories, format options), so it belongs visible in the filesystem — consistent with vite.config.ts, tailwind.config.js, and other tools where config is a first-class part of the workflow. The JSON variant is also renamed from .specs.config.json to specs.config.json. The global config path (~/.specs/config.yaml) is unchanged since home-directory configs are conventionally hidden.
• audit command renamed to scan — Better describes the command’s purpose: scan a file and produce a manifest for component curation. specs audit still works as a deprecated alias with a stderr warning.
• sourceDirectory config field renamed to dataDirectory — Aligns the field name with its default value (./data) and removes confusion with the sources config block. sourceDirectory still works as a deprecated alias with a stderr warning.
• generate manifest mode falls back to config.outputDirectory — --output is no longer required when outputDirectory is set in the config file, fixing the main flag/config inconsistency reported by users.
• Config types now distinguish partial input from resolved output — CLIConfig.config and ConfigLoader.mergeConfig use ResolvedConfig (all defaults guaranteed) instead of Config (which now permits omitted fields)
• init template annotates license-gated configs — The YAML config template generated by specs init now notes that format.tokens and include.invalidCombinations require a license key to produce output.

Fixed

• Config format values are now case-insensitive — Lowercase values like yaml, camel, or layout in config files were silently rejected by validation and reset to defaults (e.g., output: yaml always produced JSON). All format.* values are now normalized to uppercase before validation, matching how the CLI flag already works.
• YAML options type annotation includes CreateNodeOptions — FileWriter.YAML_OPTIONS was typed without ParseOptions & CreateNodeOptions, causing a compile error for aliasDuplicateObjects
• Config merge test references legacy subcomponentNamePattern — Updated to use subcomponents (the current property shape) with toEqual instead of toBe
• Vitest mock type mismatch in GenerateCommand tests — Replaced ReturnType<typeof vi.spyOn> with MockInstance for vitest 3.x compatibility

Deprecated

• sourceDirectory config field — Use dataDirectory instead. Will be removed in a future release.
• specs audit command — Use specs scan instead. Will be removed in a future release.
• fetch --outDir flag — Use --data-dir instead. Will be removed in a future release.

Dependency updates

• @directededges/specs-schema v0.17.0 — Introduces ResolvedConfig (fully-resolved config with all defaults guaranteed) alongside the now-more-permissive Config (optional fields with defaults). Removes unused Variant.name and Variant.baseline fields from output.
• @directededges/specs-from-figma v0.14.0 — Fixes format.keys not applying when config values are lowercase and not formatting invalidVariantCombinations dimension names. Internal types updated to ResolvedConfig.

[0.9.0] - 2026-04-09

Adds complete config template generation, better Figma rate-limit error messages, and fixes for YAML-only-comments config crashes, output format not being respected, and stale command references.

Changed

• init config template includes all settings — The YAML template generated by specs init now includes every Config field and output section option: codeOnlyPropsPattern, slotConstraints, inferNumberProps, emptyVariants, splitComponents, splitConcerns, and useSubfolders. All new entries are commented out with their defaults. (#16)
• fetch rate-limit errors surface Figma response headers — When Figma returns HTTP 429, the error message now includes the Retry-After duration (formatted as seconds, minutes, hours, or days), seat tier (Viewer/Collab or Dev/Full), plan tier, and a link to Figma’s rate limit documentation.

Fixed

• Config validation crashes on YAML sections with only comments — When specs.config.yaml contains sections like include: with only commented-out fields, the YAML parser produces null instead of an empty object. The config validator’s deepMerge and validateAndCorrectConfig methods now guard against null values, preventing TypeError: Cannot convert undefined or null to object crashes. Null values from YAML parsing no longer overwrite defaults. (spec-demo)
• File output ignores config.format.output — The generate command always wrote YAML files regardless of the format.output config setting. The OutputFormat type, FileManifest extensions, and all writers now respect the configured format (JSON or YAML). The DEFAULT_OUTPUT_CONFIG.defaultFormat is aligned with specs-schema’s DEFAULT_CONFIG.format.output (JSON). (#14)
• audit and init terminal output references defunct batch command — Post-run help text in audit and init told users to run specs batch …. The batch command was consolidated into generate; all references now point to specs generate.
• audit --variables flag not writing to manifest header — The -v/--variables flag was parsed but never passed to the manifest generator. The **Variables:** metadata line is now written when the flag is provided, and ManifestParser extracts it back into metadata. (#18)

Dependency updates

• @directededges/specs-from-figma v0.13.0 — Slot anyOf values now respect the configured key format instead of using raw Figma component names. Width/height fallback warnings for rotated nodes are more informative when geometry data is absent.

[0.8.0] - 2026-04-07

Adds fetch UX improvements (animated spinner, elapsed time, --no-geometry), renames the config key from model to config, and fixes style reconciliation and large-file fetch crashes.

Added

• fetch animated spinner with elapsed time — The fetch command now displays an animated braille spinner with a live elapsed-time counter while downloading each payload. The final success line includes the total duration per request (e.g., ✓ Downloaded: kds file (14s)). Non-TTY environments fall back to a static log line.
• fetch --no-geometry flag — Omits ?geometry=paths from Figma file requests, reducing payload size by roughly half. Vector path data (fillGeometry, strokeGeometry, size, relativeTransform) is excluded; width/height fall back to absoluteBoundingBox during processing.
• audit default output path — -o is now optional. When omitted, the manifest writes to {sourceDirectory}/{alias}.manifest.md using the config’s sourceDirectory and the input filename. Added --config flag for config file resolution.

Changed

• Config key rename: model → config — The YAML key model: and internal property CLIConfig.model are renamed to config: / CLIConfig.config to align with the upstream Config type from @directededges/specs-schema. Updates source, tests, and all documentation.

Refactored

• Remove dead styles payload shapes from loadFoundations — Removed two unused code paths: the all_styles simplified format and the styles object-map format. Only the Figma REST API format (meta.styles) is retained. Updated JSDoc to describe the two actual data sources (file seed + styles endpoint).
• Comment out false-defaulting include fields in config template — invalidVariants and invalidCombinations now have schema-level defaults and no longer need explicit values in the generated config template.

Fixed

• Style $custom reconciliation in loadFoundations — Published Figma styles referenced by components use file-local IDs (e.g., 19108:2530) that differ from the styles endpoint’s node_id (e.g., 5115:6703). The shared key hash now bridges these two sources, ensuring $custom token objects from the styles endpoint are available when resolving style references during spec generation.
• generate -c uses component ID as output key — In file mode (generate <file> -c <id>), the component’s Figma node ID was used as the output key instead of its name. Now resolves the display name from the file’s componentSets or components metadata.
• fetch writes raw response directly to disk — Previously, fetch parsed the Figma response into JSON and re-serialized it with pretty-printing before writing. This caused Invalid string length crashes on large files (400MB+). Now writes the raw response body straight to disk, eliminating unnecessary memory overhead.

Dependency updates

• @directededges/specs-from-figma v0.12.0 — When the REST API response lacks geometry data (e.g., when using --no-geometry), width and height fall back to absoluteBoundingBox. A console warning now surfaces when this fallback is used on a rotated node, where bounding box dimensions may be inflated.

[0.7.0] - 2026-04-05

Rebrands from anova-cli to specs-cli and publishes to npmjs.org. Updates all dependencies to published npm packages. Removes the deprecated variantNames config field per specs-schema v0.16.0.

Changed

• Package rename — @directededges/anova-cli → @directededges/specs-cli
• Config file names — .anova.config.yaml → specs.config.yaml (and .json variant)
• Config search path — ~/.anova/config.yaml → ~/.specs/config.yaml
• Dependencies — switched from local file: references to published npm packages: @directededges/specs-schema@^0.16.0, @directededges/specs-from-figma@^0.11.0
• Publishing target — npm registry (was GitHub Packages)

Removed

• Config.include.variantNames — removed from config template, validation, and documentation per specs-schema v0.16.0 (ADR 034). Added emptyVariants to valid config include keys.

Dependency updates

• @directededges/specs-schema v0.16.0 — removes variantNames, adds optional emptyVariants, makes invalidVariants and invalidCombinations optional with defaults
• @directededges/specs-from-figma v0.11.0 — renames from anova-transformer, adds pageId resolution, empty variant filtering, stroke align fix, license metadata in output

[0.6.0] - 2026-03-25

Adds a new applyCustomTokens CLI command for injecting custom token objects into fetched foundation data, enabling the CUSTOM token profile in the transformer. Implements anova v0.15.0 schema with restructured subcomponent configuration and corrected typography types, and anova-transformer v0.10.0 with expanded subcomponent discovery and custom token support.

Added

• License key support — -l, --license <key> flag and ANOVA_LICENSE_KEY environment variable for Pro features (token references, variable bindings, visibility bindings)
• License status display — shows License: PRO (active) or fallback reason (e.g., License: FREE (invalid — key not recognized)) when a key is provided
• Manifest mode for generate — generate now accepts markdown manifests directly, replacing the separate batch command; processes all [x] marked components in a single pass
• applyCustomTokens command — New CLI command that injects $custom token objects from a JSON mapping file into fetched variables and styles JSON files. Config-aware with -v/-s override flags. Supports idempotent re-application, status summary, and validation of mapping entries.
• $custom passthrough in loadFoundations — Variables and styles map entries now preserve $custom properties when loading from JSON files, enabling the transformer to read custom token objects.

Changed

• generate command unified — accepts both JSON files (with -c for single component) and markdown manifests (for multiple components); all split flags (--split-components, --split-concerns, --use-subfolders) work in both modes
• ManifestParser — fixed regex to correctly parse component entries from manifest markdown
• Documentation — updated all docs to reflect unified generate command, removed batch references, added license setup guide and Free vs. Pro feature comparison

Dependency updates

• @directededges/anova v0.15.0 — Subcomponent configuration moves from a flat subcomponentNamePattern string to a structured subcomponents object supporting multiple match patterns, an exclude list, and a page-level search scope. Subcomponent references in anatomy and element output now use $ref pointers. Typography fields leadingTrim, fontFamily, and fontStyle are corrected to match actual Figma API values.
• @directededges/anova-transformer v0.10.0 — Specs now support page-level subcomponent discovery (scanning beyond the component tree), multiple and excludable match patterns for subcomponent detection, and alphabetically ordered subcomponent output. Subcomponent references in instanceOf fields emit as $ref pointers. The new CUSTOM token profile uses $custom objects from variables and styles as style property values. Fixes detection of subcomponents nested as instances and inconsistent slash spacing in Figma component names.

Removed

• batch command — consolidated into generate; use anova generate manifest.md instead of anova batch manifest.md

[0.5.0] - 2026-03-18

Supports code-only props extraction: the transformer now detects a configurable container layer, excludes it from anatomy, and surfaces its children as props with $extensions provenance metadata. Slot constraint code-only props are promoted to SlotProp.minItems, maxItems, and anyOf fields. Also introduces NumberProp inference from text-based code-only props when enabled.

Added

• ConfigLoader validation for new processing config fields: codeOnlyPropsPattern (string), slotConstraints (boolean), and inferNumberProps (boolean)

Changed

• Compatible with @directededges/anova v0.14.0 and @directededges/anova-transformer v0.9.0

Fixed

• ConfigLoader was validating iconNamePattern instead of glyphNamePattern, the field name used in Config.processing since v0.3.0. The validator now correctly references glyphNamePattern
• BatchCommand manifest parser regex now handles component names containing parentheses

[0.4.0] - 2026-03-13

Changed

• Compatible with @directededges/anova v0.13.0 and @directededges/anova-transformer v0.8.0

[0.3.0] - 2026-03-08

Added

• iconNamePattern config support for detecting icon content assets

Changed

• Compatible with @directededges/anova v0.12.0 and @directededges/anova-transformer v0.7.1

[0.2.0] - 2026-03-04

Changed

• Updated for @directededges/anova v0.11.0 compatibility
• Config defect fix

[0.1.0] - 2026-02-10

Added

• Initial CLI and MCP server for design system operations
• Component.fromRestApi integration with anova-transformer

Versions

• 0.20.0 — 2026-06-07
• 0.19.0 — 2026-06-05
• 0.18.0 — 2026-05-29
• 0.17.0 — 2026-05-23
• 0.16.0 — 2026-05-22
• 0.15.1 — 2026-05-20
• 0.15.0 — 2026-05-15
• 0.14.0 — 2026-05-15
• 0.13.1 — 2026-05-08
• 0.13.0 — 2026-05-06
• 0.12.2 — 2026-04-28
• 0.12.1 — 2026-04-24
• 0.12.0 — 2026-04-24
• 0.11.0 — 2026-04-16
• 0.10.2 — 2026-04-14
• 0.10.1 — 2026-04-14
• 0.10.0 — 2026-04-13
• 0.9.0 — 2026-04-09
• 0.8.0 — 2026-04-07
• 0.7.0 — 2026-04-05
• 0.6.0 — 2026-03-25
• 0.5.0 — 2026-03-18
• 0.4.0 — 2026-03-13
• 0.3.0 — 2026-03-08
• 0.2.0 — 2026-03-04
• 0.1.0 — 2026-02-10