Designer's Guide

Build your system, step by step

From zero to a full Figma token system with Claude Code. You never write code: you type short lines, and Figma fills up.

Before you start

You need four things, and a couple of words explained:

Claude Code: the app where you type your lines. The skills run inside it.
Figma Desktop: the desktop app, not the browser. The skills write into the file you have open.
Node.js 18 or newer: a small background tool the Figma connection runs on. Check by typing node --version in a terminal.
A Figma file to build in.

Works on macOS and Linux. Windows is not supported for now.

Skill means a ready-made ability for Claude Code. Variable is Figma's word for a named value, like a color or a number. Token is the same thing in design-system language.

Install

Two parts: connect Claude Code to Figma once, then get the skills.

Part 1: Connect Claude Code to Figma (one time)

Create a Figma access token. In Figma, create a personal access token named Figma Console MCP with these scopes: File content (read), File versions (read), Variables (read), Comments (read and write). Copy it right away, because Figma shows it only once. Treat it like a password.
Screenshot to come
The token screen in Figma with the four scopes selected (token hidden)
Add the connection to Claude Code. In a terminal, run the command in the setup doc with your token in it, then restart Claude Code.
Add the plugin to Figma. In Figma Desktop, open your file and choose Plugins, Development, Import plugin from manifest. Pick ~/.figma-console-mcp/plugin/manifest.json and run the plugin. That file appears after the connection has run once.
Screenshot to come
Plugins, Development, Import plugin from manifest
Test it. In Claude Code, type Check Figma status. It should say Figma is connected.

Part 2: Get the skills (pick one)

Option A · no terminal

Ask Claude Code

On the project's GitHub page choose Code, then Download ZIP, and unzip it.
Open the unzipped folder in Claude Code.
Type Run ./install.sh to install the skills.
Restart Claude Code.

Option B · terminal

Run the installer

Download and unzip the project, as in Option A.
In a terminal, go to that folder and run ./install.sh
Want a preview first? Run ./install.sh --check. It copies nothing.
Restart Claude Code.

The installer only copies skills into ~/.claude/skills and never deletes anything. Prefer one project only? Open the unzipped folder in Claude Code and the skills load from it, no install needed.

Screenshot to come

The installer reporting each skill as new or up to date

Part 3: Each time you work

Open your Figma file in Figma Desktop and run the Desktop Bridge plugin.
In Claude Code, type a line such as Spacing.
Open the Variables panel in Figma. Each tier should show references, not hex values.

The mental model

The color system has three tiers. Each one points at the one before it, so a change in one place flows everywhere.

BrandPurple/500A raw value. Nothing points anywhere.
AliasPrimary/500A role. A reference to Brand/Purple/500.
MappedText/actionA usage. A reference to Alias/Primary/500 (Primary/200 in Dark).

Brand holds raw values: color scales, spacing, fonts. Nothing there points anywhere.
Alias holds roles such as Primary, Neutral and Error. Each is a reference to a Brand variable.
Mapped holds usage: Surface, Border, Text and Icon. This is what you apply to layers. It has Light and Dark modes.
Responsive is separate: type sizes with a Desktop and a Mobile mode.

Why references? Swap Purple for another color and every role and every layer follows. A copied hex looks identical today and breaks that tomorrow, so the skills never write one into Alias or Mapped.

Build your system

Two ways. The one-line way does everything. The step-by-step way runs one skill at a time, in this order, because each tier builds on the one before.

The one-line way

Step 1 · figma-starter

The whole system from one line

Runs the whole build for you: colors, aliases, Light and Dark usage, spacing, radius, borders, motion, type and the Design Tokens page. It calls the other skills in order.

Type: /figma-starter Plum:#3B1A53 Periwinkle:#8E7FAE heading "Moneta Sans" body Lato
You will see: The complete token system in your file, and the Design Tokens page documenting it.

Common tweaks

Name:#HEX (one to four)Your brand colors, in order: Primary, Secondary, Tertiary, Accent.
heading <font> body <font>Font families. Quote names with spaces. Defaults are Inter and Roboto.
dry runShow the plan and write nothing.
Safe to repeatSteps that already exist are skipped.

The step-by-step way

Add dry run to any line to preview without writing.

Step 2 · figma-color-scale

An 11-step color scale from one hex

Turns one base color into an 11-step scale. Your hex becomes the 500 Default; darker steps are the color at lower opacity over black, lighter steps over white.

Type: Purple:#5C3FC4
You will see: A Purple group in the Brand collection with Purple/950 down to Purple/50, in that order.

Common tweaks

Name:#HEXOne color. Name=#HEX and Name:HEX work too.
-defaultAdds Red, Blue, Orange, Green and Gray scales, plus Foundation (White and Black).
Foundation White:#FAFAF7 Black:#0B0B0DSets your own white and black. Either one alone works.
One per lineType several colors in one message, one per line.

Step 3 · figma-alias-bridge

Roles that follow your colors

Links a whole Brand group to an Alias role, step for step. Each Alias variable is a reference to the matching Brand variable.

Type: Brand/Purple -> Alias/Primary (Purple)
You will see: An Alias group named Primary whose variables point at Purple/950 to Purple/50.
Run it after: Brand scales to link from.

Common tweaks

-defaultSix links: Gray to Neutral, Red to Error, Green to Success, Orange to Warning, Blue to Information, Foundation to Foundation.
Primary and friends-default never creates Primary, Secondary and so on. Type those lines yourself, in the same message if you like.
(Purple)Text in parentheses is a reminder and is dropped from the name.
Run it againIt repoints, never duplicates.

Step 4 · figma-mapped-roles

Light and Dark usage tokens

Builds the usage tier, the one you actually apply to layers: Surface, Border, Text and Icon, each pointing at an Alias variable.

Type: Mapped
You will see: A Mapped collection with Light mode. Add Dark and it fills the same variables with mirrored steps.
Run it after: Alias roles first (run the alias bridge, including Foundation).

Common tweaks

Mapped/TextBuild one group only. Also Mapped/Icon, Mapped/Surface, Mapped/Border.
Mapped darkAdds the Dark mode and fills it.
Alias/Neutral/900 -> Mapped/Text/headingPoint one variable at one Alias variable.
reset Mapped/TextPut hand-changed variables back to the preset. Hand-tuned values are kept otherwise.

Step 5 · figma-spacing

A spacing scale on a 4px grid

Writes a fixed spacing scale in 4px units. It is the same every run.

Type: Spacing
You will see: A Spacing group in Brand: Spacing/0 to Spacing/24, where Spacing/4 is 16px.

Common tweaks

Spacing/4Write one step. Several can share a message.
reset SpacingOverwrite hand-changed values.

Step 6 · figma-radius

A border radius scale

Writes a fixed corner radius scale in 4px units, plus a full value for pills and circles.

Type: Border radius
You will see: A Border radius group in Brand: Border radius/2 is 8px, and full is 9999.

Common tweaks

Border radius/2One step. Several can share a message.
reset Border radiusOverwrite hand-changed values.

Step 7 · figma-border-width

A border weight scale

Writes a fixed border weight scale.

Type: Border width
You will see: A Border width group in Brand with steps 0, 0-25 (1px), 0-5 (2px) and 1 (4px).

Common tweaks

Border width/0-5One step. Several can share a message.
reset Border widthOverwrite hand-changed values.

Step 8 · figma-motion

Durations and easing curves

Writes animation durations and easing curves as Figma’s own timing and easing variables.

Type: Motion
You will see: Motion/Duration from XFast (250ms) to XSlow (2500ms) with Default at 1000ms, and Motion/Easing: Standard, Enter, Exit, Linear.

Common tweaks

Motion/DurationOne group. Motion/Easing works too.
reset MotionOverwrite hand-changed values.

Step 9 · figma-type-scale

A responsive type scale with text styles

Builds typography in one run: font family and weight variables, a type scale with Desktop and Mobile modes, and one text style per role.

Type: Typography
You will see: Font variables in Brand, a Responsive collection with Desktop and Mobile modes, and text styles bound to both.

Common tweaks

Typography heading Playfair body LatoYour own fonts. Either one can be given alone. Defaults are Inter and Roboto.
Typography base 18 ratio 1.333 mobile 1.2Change the base size and the Desktop and Mobile ratios. Settings are not stored, so repeat them on later runs.
reset ResponsiveRecalculate the size variables.
reset type stylesRebind hand-changed styles to the preset.

Step 10 · figma-token-docs

A Design Tokens page that documents it all

Builds a reference page for the whole system, generated from your live variables and text styles.

Type: Design Tokens
You will see: A page named Design Tokens: a clickable contents frame, a how-to guide, token health, color scales, roles, Light and Dark usage, contrast checks, text styles, spacing, radius and border width.
Run it after: Best after the tokens exist.

Common tweaks

Run it againAfter any token change, rerun it. It refreshes the frames it made.

Step 11 · figma-contrast-fix

Accessibility fixes for failing pairs

Finds Mapped text and border pairs that fail WCAG AA (4.5:1 for text, 3:1 for borders) in Light and Dark, and previews a passing fix for each.

Type: Contrast fix
You will see: A Contrast fixes (preview) frame on the Design Tokens page. Nothing changes until you ask.
Run it after: Mapped tokens and the Design Tokens page.

Common tweaks

Contrast fix applyApply every fix. It is a separate request from previewing, because a fix can be a brand decision.
Contrast fix apply Text/actionApply the fix for one variable.
Contrast fix apply darkApply only the Dark mode.
Not fixableIf no single step passes, it says so and changes nothing: change the surface instead.

Step 12 · figma-export-tokens

Tokens as code for developers

Turns your Figma variables into files a developer can import. References stay references.

Type: Export tokens
You will see: tokens.css, tokens.tokens.json and tailwind.theme.css in a tokens folder. Nothing is written to Figma.

Common tweaks

Export tokens cssOnly the CSS. json and tailwind work too, and can be combined.
Export tokens to src/stylesWrite to another folder.
Rebuild, do not editThe files are generated. Run it again after tokens change.

Cheat sheet

Skill	Type
The whole system from one line	`/figma-starter Plum:#3B1A53 Periwinkle:#8E7FAE heading "Moneta Sans" body Lato`
An 11-step color scale from one hex	`Purple:#5C3FC4`
Roles that follow your colors	`Brand/Purple -> Alias/Primary (Purple)`
Light and Dark usage tokens	`Mapped`
A spacing scale on a 4px grid	`Spacing`
A border radius scale	`Border radius`
A border weight scale	`Border width`
Durations and easing curves	`Motion`
A responsive type scale with text styles	`Typography`
A Design Tokens page that documents it all	`Design Tokens`
Accessibility fixes for failing pairs	`Contrast fix`
Tokens as code for developers	`Export tokens`

Add dry run to preview. Type -h after a skill name for its usage.

Troubleshooting

A skill says nothing was written

Figma is not connected. Open your file in Figma Desktop, run the Desktop Bridge plugin in that file, and restart Claude Code if you just added the server. The skill names what is missing and never guesses.

Claude does not know the skill

Run the install again, then restart Claude Code. Type / to see the installed figma-* skills.

A font is refused

The heading and body fonts must be available in your Figma account. Google Fonts are. Figma suggests the closest name it can find, so retype the line with that name.

Mapped says Alias/Foundation is missing

Send Brand/Foundation -> Alias/Foundation, or run the alias bridge with -default. Then send the Mapped line again.

Dark mode is empty

Type Mapped dark. Mapped starts with Light only.

The Design Tokens page shows failing contrast

Type Contrast fix to preview a passing fix for each pair, then Contrast fix apply for the ones you want.

I changed a token and the page or the code is out of date

Run Design Tokens again, and Export tokens if you use the code files.

I am not sure what a line will do

Add dry run to it and nothing is written. Type -h after a skill name (for example /figma-spacing -h) for its usage.

Next steps

Open your Design Tokens page in Figma and look around. Then make it yours: change a brand color, rerun the skills and watch every tier follow.

Want to contribute, report a bug or ask for a skill? Everything lives on GitHub.