Repaint in your design tone

By the time you finish 03-first-run.md, the side panel and options page are already up — but they are wearing the base’s default tone (neutral grays with a blue accent). This page ends with that tone replaced by yours.

There are two paths. Either pull colors directly out of a Figma file, or hand the AI a one-word tone ("warm beige", "professional blue") and let it pick a palette. Both are optional, the same way 04-real-backend.md is. If your design tone is not nailed down yet, skip this page and the base default tone will keep working.

When to come back to this page

Situation	Where to go
The tone is not decided yet	Stay on the base default and come back later
You have a Figma file	”Sync from a Figma URL” below
You only have a tone in your head (“warm beige”)	“One-word tone” below
You want to restyle components, not just colors	”How deep to go” below

Trigger

Type one line into Claude Code:

customize design tokens

customize design, repaint extension, or the Korean 디자인 톤 갈아끼우기 will all hit the same place — sub-phase 5-b of the 5-customize-extension skill.

If you have already done a customize pass before, the AI checks first:

The brand is already filled in. Which sub-phase do you want to redo? — 5-a branding / 5-b UI theme / 5-c domain permissions

For this page, pick 5-b UI theme only.

Sync from a Figma URL

If Figma MCP is registered, the first question splits in two:

Where should I pull the design tokens from?

• Pull from Figma — recommended
• Use a tone word

Figma MCP registration is covered in the MCP section of 01-prerequisites.md. If you have not registered it, this fork does not appear and the flow drops straight into the tone-word path. You can stop here, register it, and come back — one thing at a time is the safer rhythm.

If you pick the Figma path, the AI asks for a URL:

figma.com/design/<fileKey>/<file-name>?node-id=<nodeId>

Paste this exact shape. In Figma, right-click a frame and choose Copy link to selection — it copies in this form. A whole-file URL (no node-id=) works too, but pulling from one specific frame gives cleaner color mapping.

After you paste and hit Enter, you should see something like:

✓ Pulled 7 Figma variables (text/bg/primary/secondary/border)
✓ Updated src/shared/ui/tokens.css
✓ Recorded figma_file_key, figma_node_id, synced_at in brand.json

What it should look like: open src/shared/ui/tokens.css and the --color-primary, --color-secondary CSS variables now hold the hex values from your Figma file.

When it does not look like that:

• Could not parse the Figma URL → The URL is missing node-id=. Right-click the frame in Figma again and re-copy the link.
• No color variables found → The Figma frame does not have design variables defined (the Variables panel is empty). The AI will still try to fill the tokens by reading the frame as an image, but the result is less precise. Add variables in Figma first if you can.
• Some variables came in but not all (primary is set, secondary is empty) → The AI suggests a complementary color in the same tone. The result summary names which ones are AI-filled.

One-word tone

If Figma is not in the picture, the AI asks for a single word instead:

Tell me the tone in one word. (Examples: “professional blue”, “warm beige”, “tech green”)

Leaving it blank keeps the base default — the entire 5-b sub-phase is skipped. A word triggers the AI to pick a primary, secondary, background, and text color set in that tone and write it into tokens.css.

If the result feels off, run the same flow again with a different word ("darker blue", "more saturated"). Each call replaces the recommendation with a fresh one.

How deep to go

Once colors are in place, one more question:

How far do you want the theme to reach?

• Colors only — recommended
• Colors and fonts
• Full theme

Colors only is the safe first pass. Buttons, inputs, and cards keep the base shapes; only the color variables change. You can come back later and dial it up one step at a time.

Full theme is a bigger job. The side panel, options page, and popup all get their button, input, and card styles redrawn against the tone. Once you commit to it, the later /implement-popup-ui and /implement-options-ui runs will keep the same styling.

Checking it landed

After the customize flow finishes, you need a build and a Chrome reload:

pnpm run build

Then in chrome://extensions, click the refresh arrow on your extension card so Chrome re-reads dist/. Reopen the side panel and the new colors should be there.

If the colors did not change, it is almost always one of these:

• The build never ran → run pnpm run build again
• Chrome is caching the old dist/ → click the refresh arrow on the card, then close and reopen the side panel

The second pass — after you edit Figma

When you change something in Figma and run customize design tokens again, the same figma_file_key is already stored in brand.json, so the AI does not ask for the URL a second time. It only syncs the variables that changed.

Anything you hand-edited in tokens.css is preserved. The variable names you touched land in brand.json under a manual_overrides key, and the auto-sync skips those slots so your tweaks do not get overwritten.

If you actually do want Figma to win and overwrite your hand edits, the AI will check explicitly:

manual_overrides has secondary and accent in it. Should the Figma values overwrite them?

Next

With the tone in place, you can either go to 04-real-backend.md to wire up Supabase or your own server, or stay in console-log mode and move straight to 09-distribution.md. Design does not need to be locked before distribution, but it can be.

If anything snags during build or reload, the build/cache section of 06-troubleshooting.md is the first stop.