token-to-theme

name	token-to-theme
description	Use when a design token source already exists and the user wants to audit, map, or apply tokens to a real project's theme layer before component or page implementation.

Token to Theme

Use this skill to map design token candidates into a project's actual theme layer.

This skill sits between design analysis and UI implementation. It should consume a stable token source, inspect the current codebase, and update only the theme layer needed for later component and page work.

What This Skill Does

This skill can:

• read design_analysis.md or an equivalent token source
• inspect the repository's current theme architecture
• map raw token candidates into semantic roles
• update or create theme-layer files such as tokens.css, semantic.css, global CSS variable blocks, or existing shadcn-compatible theme files
• preserve the repository's existing value format and theme conventions where possible

This skill should not:

• implement pages or sections
• redesign the visual system from scratch unless the user explicitly asks
• push raw brand values directly into page components
• restyle business components one by one
• migrate the repository to a completely different theming architecture unless the user approves it

Recommended Inputs

Always confirm these inputs before editing:

• token source: design_analysis.md, a token table, or explicit user-provided token list
• target project root or relevant app directory
• mode: audit, map, or apply
• target stack if known, for example Vue3 + Tailwind + shadcn/ui + Vite
• whether dark mode, semantic states, and typography scale are in scope

If there is no stable token source yet, recommend running figma-to-spec first.

Modes

audit

Read the project theme layer and identify:

• current theme files
• current variable format
• whether the repo already uses semantic roles
• gaps between the token source and the codebase

Do not edit files in this mode.

map

Create a reviewable theme_mapping.md without editing the application code.

Use this mode when the user wants to review the semantic mapping before changes land.

apply

Update the project theme layer with minimal, targeted edits.

In this mode, prefer also generating or updating theme_mapping.md unless the user explicitly wants code-only changes.

Primary Outputs

Optional review artifact:

• theme_mapping.md

Possible code targets:

• existing global CSS variable file
• src/styles/tokens.css
• src/styles/semantic.css
• src/assets/styles/tokens.css
• src/style.css or similar import entry
• existing Tailwind theme file if the repo already uses config-driven theming

Use the file targeting guidance in file-targets.md. Use semantic mapping rules in mapping-rules.md. Use templates in templates.md. Use copyable prompts in usage-examples.md. Use end-to-end handoff recipes in chaining-examples.md.

Quick Start

If your token source came from figma-to-spec, use this review-first sequence:

1. Ensure design_analysis.md is approved.
2. Run token-to-theme in map mode to generate theme_mapping.md.
3. Review the semantic mapping.
4. Run token-to-theme in apply mode to update only the theme layer.

See chaining-examples.md for copyable prompts, including multi-frame handoff patterns.

Workflow

1. Confirm the Source of Truth

Prefer this order:

1. design_analysis.md
2. user-approved token list
3. direct inspection of current design screenshots or notes only if nothing else exists

Do not infer a full token system from scattered code snippets if a design spec exists.

2. Detect the Existing Theme Architecture

Inspect the codebase before editing anything. Determine:

• where global styles live
• whether tokens and semantic variables are already separated
• whether the project uses HSL channels, hex values, OKLCH, or Tailwind @theme
• whether shadcn-compatible semantic roles already exist

Preserve existing conventions unless there is a strong reason to normalize them.

3. Normalize Raw Tokens First

Separate the incoming design information into:

• raw design tokens
• semantic roles
• framework wiring

Do not collapse these layers into one file if the repository already keeps them separate.

4. Map Into Semantic Roles

Always prefer semantic roles over raw design names in the final consumable layer. Examples:

• raw brand color scale -> token layer
• background, foreground, card, border, primary, muted -> semantic layer
• shadcn-compatible variables -> framework consumption layer

5. Edit Only the Theme Layer

Safe edit zones include:

• token variable declarations
• semantic variable declarations
• imports that wire theme files into the app
• Tailwind theme wiring only if the repo already uses it

Avoid editing page components unless a missing import makes the theme layer unreachable.

6. Validate After Edits

After changing files:

• check for syntax or lint errors in touched files
• confirm imports are valid
• confirm the repository still has a coherent token -> semantic -> consumption path

Key Rules

• Preserve the repo's existing value format
• Prefer minimal edits over architectural rewrites
• If the project already uses shadcn-compatible roles, map into them rather than inventing a parallel naming system
• If the project has no semantic layer, create one only if it materially improves maintainability and the change stays small
• Do not add dark mode automatically unless the design source or user explicitly asks for it
• Treat success, warning, and destructive as optional semantic extensions, not mandatory shadcn core roles

Handoff Guidance

A later implementation step should be able to rely on:

• stable semantic roles in CSS variables or theme config
• clear documentation in theme_mapping.md
• minimal ambiguity about which files own token values versus semantic mappings

Once the theme layer is stable, hand off to page-builder for bounded section or page implementation from page_spec.md.