token-map

Token map

Spec §10 / §21.3.1: every figma-migration / code-migration run crosses the same boundary — "the source has its own tokens; the target uses the active OD design system; we need a deterministic mapping". This atom produces that mapping.

Inputs

• figma/tokens.json from figma-extract (figma-migration), OR
• code/tokens.json from design-extract (code-migration).
• The active design system DESIGN.md (already injected into the prompt; the atom reads from the staged design-system context).

Output

project-cwd/
└── token-map/
    ├── colors.json     # { source: '#hex' | 'tokenName', target: '--ds-token' }[]
    ├── typography.json # font + size + weight pairings
    ├── spacing.json    # spacing scale crosswalk
    ├── unmatched.json  # { source: ..., reason: 'no-target-equivalent' }[]
    └── meta.json       # { sourceKind: 'figma' | 'code', generatedAt, atomDigest }

unmatched.json is the audit list a human reviews; the agent must not invent target tokens silently.

Semantic token inference

Figma often exports anonymous source names such as color-3, paint/17, or raw #5B8DEF. Do not ask the user to rename those before mapping. First infer the semantic role from usage evidence:

• Node path, component name, instance overrides, variant/state labels, frame name, layer name, and nearby text such as Primary, Selected, Link, Error, Focus, Nav, Button, or CTA.
• CSS-like position in the rendered tree: background fill, foreground text/icon, border, divider, overlay, shadow tint, focus ring, status badge, chart series, or brand/accent treatment.
• Contrast relationships: a color paired repeatedly with the main canvas is likely foreground; one paired with foreground inside CTA components is likely primary/accent background; a thin outline around interactive elements is likely border or focus-ring.
• Reuse topology: a value that appears across primary buttons, selected tabs, and active nav items is stronger evidence for --ds-color-primary than a value that appears once in an illustration.