Guide · Agent skill
How to use the Token Map agent skill: install and trigger it
Updated · written with AI from the project's own documentation and checked against our catalogue data
Token Map is an agent skill that takes design tokens pulled from a Figma file or an existing codebase and pairs each one with a matching token in your active design system. It writes a mapping file for the generate stage, plus a list of anything it could not match for a person to review. After this guide you will know what the skill does, how to install it, how to ask for it in plain language, and what to check in its output.
Token Mapnexu-io/open-design · Apache-2.0 Download the skill Quick start
- 1Download the ZIP. Download the token-map skill ZIP from this page.
- 2Unzip into a skills folder. Unzip it into ~/.claude/skills/ for all projects, or into the project's .claude/skills/ folder for one project.
- 3Or upload it in the Claude apps. In the Claude apps, open Settings, go to Capabilities, then Skills, and upload the ZIP.
- 4Prepare your inputs. Make sure you have an active DESIGN.md and a tokens.json from figma-extract or design-extract.
- 5Ask for the mapping. Describe the migration in plain language and name the tokens file and the active design system.
- 6Review unmatched.json. Go through each unmatched entry and its reason before using the generated mapping.
What is an agent skill, and what does Token Map do?
An agent skill is a folder with a SKILL.md file that tells an AI agent how to handle a specific kind of task. When the task comes up, the agent follows those instructions.
Token Map handles one boundary in a design migration: the source has its own tokens, the target uses an active design system (DESIGN.md), and you need a deterministic mapping between them. The skill tells the agent to write a token-map folder with colors.json, typography.json, spacing.json, unmatched.json and meta.json.
- colors.json pairs source colours with target tokens such as --ds-token names.
- typography.json pairs font, size and weight combinations.
- spacing.json is a crosswalk between spacing scales.
- unmatched.json lists every token that could not be matched, with a reason.
- meta.json records the source kind (figma or code), a generation time and a digest.
Install the Token Map skill
Download the ZIP for the token-map skill from this page. Then either unzip it into ~/.claude/skills/ to make it available across your projects, or unzip it into a project's .claude/skills/ folder to limit it to that project.
You can also upload the ZIP in the Claude apps. Go to Settings, then Capabilities, then Skills, and add it there.
- Personal install: unzip into ~/.claude/skills/
- Project install: unzip into the project's .claude/skills/ folder
- Claude apps: Settings, Capabilities, Skills, then upload the ZIP
~/.claude/skills/token-map/What you need before it runs
The skill's runner lives in the Open Design daemon (apps/daemon/src/plugins/atoms/token-map.ts), so you need the Open Design daemon available. You also need an active Open Design design system defined in DESIGN.md, because that is where the target tokens come from. Without an active design system there is nothing to map onto.
The input is a tokens.json file produced by an earlier step: figma/tokens.json from figma-extract for a Figma migration, or code/tokens.json from design-extract for a code migration.
- Open Design daemon
- An active design system (DESIGN.md)
- A tokens.json from figma-extract (Figma) or design-extract (code)
How to trigger it with natural requests
You do not need a special command. Describe the migration in plain language and mention mapping tokens to your design system. The agent should pick up the skill from the request and its description, which covers mapping an extracted token bag onto the active design system.
Good requests name the source and the target. Say where the tokens came from and which design system is active.
- Map the tokens in figma/tokens.json onto our active design system.
- Convert the styling tokens from code/tokens.json to the current DESIGN.md and list anything you could not match.
- Create the token map for this Figma migration and show me the unmatched colours and fonts.
How it handles anonymous tokens like color-3
Figma often exports unhelpful names such as color-3, paint/17 or a raw hex value. The skill does not ask you to rename these first. It infers the role of each token from usage evidence: the node path, component name, variant or state labels, nearby text such as Primary or Focus, its position in the rendered tree, and how often it appears in buttons, selected tabs or navigation.
The skill maps a token only when the evidence points to a role. If the top candidates are too close to call, or the evidence conflicts (for example primary against link), the token goes into unmatched.json with the reason no-target-equivalent and the competing candidates listed as hints.
- A value used across primary buttons and selected tabs is stronger evidence for --ds-color-primary than a value that appears once in an illustration.
- Value-only similarity is not enough to match a colour.
- Ambiguous cases stay unmatched for human review.
Read the output and review unmatched items
Start with unmatched.json. It is the audit list a human should review. The skill is designed not to invent target tokens silently, and each unmatched entry has a reason. Collisions, where two different source tokens would land on the same target, are also recorded there with the reason target-collision rather than merged quietly.
The skill does not add new tokens to DESIGN.md without your approval. Any proposed addition should come to you for confirmation first.
- Check every entry in unmatched.json.
- Look for target-collision entries and decide which source token should win.
- Review the examples/semantic-inference-before-after.json file to see how a token moves from unmatched to matched with role evidence.
What people use it for
- Moving a Figma file into a product that already has a design system, so colours, fonts and spacing line up with the existing tokens.
- Converting a codebase's styling tokens to a new design system and getting a list of what did not match.
- Auditing a migration by reviewing an explicit list of unmatched colours, fonts and spacing rather than trusting silent guesses.
Frequently asked questions
Is the Token Map agent skill free?
The source for this skill is published under the Apache-2.0 licence. Check the licence terms on the source repository for details on use and redistribution.
What do I need to run the Token Map skill?
You need the Open Design daemon, an active Open Design design system defined in DESIGN.md, and a tokens.json file from figma-extract or design-extract. The skill has no target tokens to map onto without an active design system.
Where do I put the Token Map skill folder?
Unzip the downloaded ZIP into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder for one project. In the Claude apps, you can upload the ZIP under Settings, Capabilities, Skills.
Does Token Map match colours by how they look?
No. The skill does not match colours by visual similarity alone. Colour matching is based on role evidence, and exact visual comparison belongs to a separate visual diff tool.
Why are some tokens in unmatched.json?
Tokens land there when no target has an equivalent, when the evidence for a match is weak or conflicting, or when two source tokens would collide on the same target. Each entry includes a reason so you can decide what to do.
Does Token Map use the internet or run code on my machine?
The skill's listing says it runs scripts and does not use the network. Review the scripts before running them, and check the source repository for the runner's full behaviour.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Token Map suits designers moving a Figma file into a product with an established design system, and developers converting existing styling tokens to one. It is a poor fit if your project has no active design system, if you need someone to make brand decisions, or if you need exact visual colour matching; in those cases a person or a visual diff tool should do the work.
Download the skill