Skip to content

Decision Records (ADRs)

Every field in the Specs schema exists because of a decision about what a design system needs to express and how Figma exposes it. An Architecture Decision Record captures one such decision: the problem, the options weighed, the choice made, and the designs rejected along the way.

Where Schema and Settings tell you what a field is, an ADR tells you why it looks that way — read one when a field’s shape surprises you, or when you’re weighing a change. Only accepted decisions appear here, newest first, each left as written, so later records may supersede earlier ones.

069 Rename clipContent to clipsContent

A clipsContent boolean style replaces clipContent, joining visible and locked as element state consumers map to overflow.

066 Lossless key formatting — safe key grammar and Figma name preservation

A format.figmaKeys option and safe key grammar preserve Figma layer names losslessly through com.figma.name.

065 Document the nullable Default and Add NumberProp.nullable

NumberProp gains nullable, and JSDoc documents the default each prop type applies when nullable is absent.

064 Tighten textAlignHorizontal to a Logical-Direction String Enum

A TextAlignHorizontal enum types textAlignHorizontal as START, CENTER, END or JUSTIFY.

063 Image content — backgroundImage fill, an images registry, ImageProp, and ImageBinding

Images are supported by backgroundImage style, ImageProp and binding in components and examples.

062 Text overflow style keys (textOverflow, maxLines)

textOverflow and maxLines properties add truncation to styles already covering typography and layout.

060 Subcomponent Figma Source Identity — Subcomponent.source

A Subcomponent.source carrying pageId, nodeId and nodeType resolves a subcomponent back to its Figma node.

059 Stroke Dash Pattern

A strokeDashPattern property adds dashes to strokes already supported with color, weight and alignment.

058 Collapsing Wrapped Primitives

A collapsePrimitiveWrapper processing option strips plain wrappers, promoting a single text or glyph child to the spec root.

057 Fix Metadata.generator.version Type: numberstring

Metadata.generator.version is typed string, matching the semver values every producer already emits.

056 Rename SlotProp.minItems/maxItems to minChildren/maxChildren

SlotProp.minChildren and maxChildren replace minItems and maxItems, aligning with Figma's slot settings.

055 Variant State Classification via processing.states

A processing.states list of VariantStateEntry classifies variant props as browser-driven or consumer-controlled.

054 Workspace Schema File

A workspace.schema.json file describes specs.config.yaml, covering sources, output and the config block.

053 Transform Command and Configuration

A transform config block with TransformEntry drives the specs transform command's code artifact output.

052 Slotting Content into Nested Instances

A reserved $nested key in PropConfigurations carries path-addressed configurations that reach into nested instances.

051 Platform Code-Syntax Token Profiles

Three FIGMA_SYNTAX_WEB, FIGMA_SYNTAX_IOS and FIGMA_SYNTAX_ANDROID token profiles emit platform code syntax alongside the default TOKEN.

050 Examples Configuration

A processing.instanceExamples block and include.defaultSlotContent govern which examples a spec carries.

049 Prop Configurations and Bindings

PropConfigurations values accept PropBinding and SlotContentRef, so a configuration can forward a prop or fill a slot.

048 Component Instance Examples

An instanceExamples registry carries real instances of a component, stored once and referenced by variants.

047 Component Slot Examples

A slotContentExamples registry and SlotBinding carry example slot fills, referenced rather than duplicated across variants.

046 Slots and Slot References

A SlotContent triplet and SlotContentRef pointer let compositions fill slots by reference.

043 Custom Color Format Configuration

A format.color option with a ColorFormat type emits color as hex, RGB, HSL, OKLCH or object.

042 Composition Structural Type

A Composition type names composed content, carrying anatomy, elements and layout with optional title and description.

041 Layout Positioning — Constraint-Based Naming

Position and PositionOffset types describe constraint-based placement, replacing x, y and layoutPositioning.

040 Replace primaryAxisAlignItems and counterAxisAlignItems with mainAxisAlignment and crossAxisAlignment

mainAxisAlignment and crossAxisAlignment with named enums replace primaryAxisAlignItems and counterAxisAlignItems.

039 Replace layoutWrap and counterAxisAlignContent with wrap and wrapAlignment

wrap and wrapAlignment with a WrapAlignment enum replace layoutWrap and counterAxisAlignContent.

038 Tighten layoutMode to String Literal Enum

A LayoutMode enum types layoutMode as NONE, HORIZONTAL or VERTICAL rather than an open string.

037 Consolidate Item Spacing into a Bi-Axial Model

An ItemSpacing type gives itemSpacing a bi-axial shape, replacing the separate counterAxisSpacing property.

036 Remove name and baseline from Variant

Variant.name and Variant.baseline are removed, leaving a variant identified by its prop configuration alone.

035 Make Config Properties with Defaults Optional

Every Config property carrying a default becomes optional, so a config states only what it changes.

034 Remove variantNames, add emptyVariants, make Config.include fields optional

An emptyVariants include option replaces variantNames, and the remaining Config.include fields become optional.

033 Typography fontFamily/fontStyle — Remove Number, Add TokenReference

Typography.fontFamily and fontStyle accept a TokenReference and drop number, matching how fonts are tokenized.

032 Typography leadingTrim — Correct to String Enum

Typography.leadingTrim is a string enum, matching the values Figma actually reports.

031 Subcomponent Search Scope Config

A processing.subcomponents object with scope, match and exclude replaces subcomponentNamePattern for finding subcomponents.

030 Subcomponent $ref for instanceOf

A SubcomponentRef lets instanceOf point at a subcomponent definition rather than repeat its name.

029 NumberProp — Numeric Property Type

A NumberProp type and inferNumberProps option carry numeric properties alongside boolean, string, enum and slot props.

028 Slot Quantity and Content Constraints

minItems, maxItems and anyOf on SlotProp, with a slotConstraints option, describe what a slot accepts.

027 Code-Only Props

A codeOnlyPropsPattern option and FigmaCodeOnlySource extension emit props that exist in code but not Figma.

026 Unify Platform-Specific Properties Under $extensions

An $extensions object on every prop type unifies platform-specific metadata, replacing the Figma-only x-platform field.

023 Fix schema compliance gaps and improve schema URL metadata

SlotProp.default becomes optional and pattern properties admit $-prefixed keys, bringing types and schema back into compliance.

022 Add nullable support to SlotProp

SlotProp gains nullable and a nullable default, matching the other prop types.

019 Allow null in StringProp.default

StringProp.default accepts null, expressing props whose absent value is meaningful.

018 Conditional Visible Binding

A Conditional type with condition expressions lets visible test a prop value rather than mirror it.

017 Rename icon Element Type to glyph

A glyph element type, GlyphProp and glyphNamePattern emit icons as first-class by applying Figma conventions.

016 Element Content Identification

A content property replaces text, identifying literal or bound content on any element type.

015 Resolve AnyProp oneOf schema violation between TextProp and IconProp

A single StringProp merges TextProp and IconProp, restoring valid oneOf discrimination in AnyProp.

014 Add examples to TextProp and IconProp, deprecate default

An examples array on TextProp and IconProp carries sample values, and default becomes optional.

013 Add fillColor style property for icon elements

A fillColor property colors icon elements alongside backgroundColor, textColor and strokes.

012 Element Type References

An ElementTypeRef widens AnatomyElement.type, letting an element type point at a shared definition.

011 Icon Element Type Support and Detection Config

An ElementType union and iconNamePattern option constrain element types and detect icons by Figma naming.

010 Sides and Corners Composite Types

Composite Sides and Corners types replace flat padding, stroke weight and corner radius properties.

009 Replace Hex String with DTCG Color Object in ColorStyleValue

A DTCG ColorValue object replaces the hex string in ColorStyle, aligning color values with token standards.

008 Introduce PropBinding to Replace ReferenceValue Unions for Bound Properties

A PropBinding type keyed $binding replaces ReferenceValue unions wherever a value is bound to a prop.

007 Consolidate Token Format Configuration into tokens

A format.tokens option replaces variables, simplifyVariables and simplifyStyles with one token output format.

006 Unified Token Reference Type — Replace VariableStyle and FigmaStyle with TokenReference

A single TokenReference type replaces VariableStyle and FigmaStyle for variables, named styles and composite references.

005 Replace Typography Flat Properties with typography — Add Typography Type

A composite typography property replaces fourteen flat text keys including fontSize, lineHeight, letterSpacing and textStyleId.

004 Add aspectRatio to Styles

An aspectRatio property carries an x/y ratio object on styles alongside width and height.

003 Gradient Support for Color Style Properties

Gradient types and a ColorStyle alias let backgroundColor, textColor and strokes carry linear, radial and angular gradients.

002 Replace effectStyleId with effects — Add Shadow, Blur, and Effects Types

An effects property with Shadow, Blur and Effects types replaces effectStyleId to describe shadows and blurs.

001 Surface license state in component output

A license field inside metadata.generator records the license state that produced a component's output.