Transforms

Transforms project a component specification into artifacts your codebase can consume: a TypeScript contract, a baseline stylesheet, a token inventory. Instead of writing those by hand, you derive them from the spec and keep them in sync as the design evolves. This concept is described in RFC 001: Component Dictionary.

Transforms take spec data as far as it deterministically goes — every prop, token, and style Figma captured — before inference enters the picture. Structured spec data is stable, regeneratable, and cheap to re-read; it’s the right foundation for agents and tooling to build on, not a replacement for them. What the spec can’t know — behavior, interaction states, accessibility semantics — belongs to agentically-extended specs and the authored files that live alongside.

Spec output

output/
  _dictionary/
    styling.byComponent.json   # token usage indexed by component
    styling.byToken.json       # token usage indexed by token name across components

  ds-alert/
    api.yaml            # spec
    variants.yaml       # variant data
    contract.ts         # generated — props interface and defaults
    styles.css          # generated — baseline token rules
    styling.json        # generated — token inventory

React component or prototyping kit

src/components/DsAlert/
  generated/
    contract.ts         # from specs transform
    styles.css          # from specs transform
  DsAlert.tsx           # implementation
  extensions.css        # overrides, states, and behavior not regenerated
  DsAlert.test.tsx
  index.ts

How It Works

specs transform discovers component subfolders under the output directory (each must contain an api.yaml), then runs one or more named transformers against every component.

specs transform [transformers...] [options]

Transformer names can be passed as positional arguments, configured in specs.config.yaml, or left absent to use the CLI default (contract).

Transformer Resolution Order

Positional arguments — specs transform css styling
config.transform.transformers in specs.config.yaml
CLI default: contract

Available Transformers

Transformer	Output file	What it produces
`contract`	`contract.ts`	TypeScript Props interface and defaults constant
`css`	`styles.css`	CSS rules per anatomy element, with token vars and variant selectors

Running All Transformers

specs transform contract css

Or configure them in specs.config.yaml so specs transform alone is enough:

config:
  transformers:
    - name: contract
    - name: css