Releases

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

@specs-schema

[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.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.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.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