Token Map
Map an extracted Figma / source-code token bag onto the active OD design system, producing a deterministic mapping the generate stage can consume.
Get the complete skill folder, including its scripts and reference files.
When to use this skill
Use Token Map when an AI agent needs a reusable SKILL.md workflow for this job: Map an extracted Figma / source-code token bag onto the active OD design system, producing a deterministic mapping the generate stage can consume.
When not to use it
Skip Token Map when the task is outside the creativity category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/token-map # Save SKILL.md to ~/.claude/skills/token-map/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/token-map/SKILL.md. For a shared project, commit the folder at .claude/skills/token-map/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Token Map skill for this task: Use Token Map when this documented workflow matches the task. Confirm any required inputs or files before making changes.
What supports this recommendation?
70/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 75/100
- Practical detail
- 68/100
- Source evidence
- 63/100
- Source signals
- 70/100
Model compatibility evidence
- claudeuntested
No model-specific signal or recorded compatibility test was found.
- chatgptuntested
No model-specific signal or recorded compatibility test was found.
- geminiuntested
No model-specific signal or recorded compatibility test was found.
- copilotuntested
No model-specific signal or recorded compatibility test was found.
- llamauntested
No model-specific signal or recorded compatibility test was found.
- perplexityuntested
No model-specific signal or recorded compatibility test was found.
- mistraluntested
No model-specific signal or recorded compatibility test was found.
- grokuntested
No model-specific signal or recorded compatibility test was found.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
# 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
```text 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.
Use that role evidence to choose among existing active design-system tokens and to decide whether an anonymous token should be renamed or left unmatched before the executable mapping pass. Keep the on-disk token-map contract unchanged: the atom still writes the existing bucket files, `unmatched.json`, and `meta.json` only.
For example, this is a useful reasoning note for deciding whether `color-3` should map to the active primary token:
```jsonc { "source": "color-3", "value": "#5B8DEF", "role": "primary", "targetCandidates": ["--ds-color-primary", "--ds-color-link"], "evidence": [ "Button/Primary fill", "Selected tab indicator", "Link text in Settings frame" ] } ```
Then map to an active design-system token only when the evidence is role-based, not value-only. If the top candidates are too close to call, or if the evidence points to conflicting roles (`primary` vs `link` vs `focus-ring`), leave the source token unmatched using the existing `no-target-equivalent` reason and include the competing candidates in the hint. This keeps automation useful for common anonymous-token cases while preserving human review for ambiguous brand decisions.
### Before / after expectation
Without semantic inference, an anonymous Figma token can only produce an uncertain value-level mapping:
```jsonc { "source": "color-3", "value": "#5B8DEF", "target": null, "reason": "no-target-equivalent" } ```
With semantic inference, the same token should carry role evidence before it is accepted:
```jsonc { "source": "color-3", "value": "#5B8DEF", "target": "--ds-color-primary", "via": "name" } ```
This deterministic v1 atom does not claim a measured accuracy lift by itself. Treat the expected improvement as coverage of previously manual anonymous-token cases when the Figma tree contains enough role evidence. Real accuracy numbers require a fixture suite with known source tokens, expected semantic roles, and a before/after agent run. See `examples/semantic-inference-before-after.json` for a deterministic same-token-batch simulation that compares the old value-level output with the semantic inference output.
## Convergence
The atom completes when every input token is either mapped or explicitly recorded under `unmatched.json` with a non-empty `reason`. The `until` evaluator reads `tokens.unmatched.length === 0` on strict mode; default is "soft converge" (proceed with `unmatched.json` populated).
## Anti-patterns the prompt fragment forbids
- Injecting a new token into DESIGN.md without explicit user approval (use a `confirmation` GenUI surface for that). - Mapping hex colours by visual proximity alone; perceptual ΔE thresholds belong in the visual-diff evaluator (Phase 7). - Collapsing distinct source tokens onto the same target token silently; record collisions in `unmatched.json` with reason `target-collision`.
## Status
Implemented by the daemon runner in `apps/daemon/src/plugins/atoms/token-map.ts`. It parses design-system tokens, performs deterministic mapping, and writes the mapped and unmatched outputs.
Intended uses
- Use Token Map when this documented workflow matches the task.
Implementation notes
- Review the source instructions and adapt inputs before running the workflow.
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.