stage 5 · migration and adoptionmigrationtokenscolortailwind
Migrate a Tailwind Config to Semantic Tokens
Converts raw Tailwind color values into a two-tier token structure — existing stops become primitives, semantic roles get added — without touching component utility classes.
Variablesfill in to personalize the prompt
play · migrate-tailwind-tokens
You are helping me migrate an existing Tailwind CSS color configuration to a structured two-tier token system (primitive + semantic).
**Step 1 — Read the references:**
Read the following from the Sistema knowledge base:
- Token architecture synthesis: `{{sistema_url}}/raw/principles/tokens/architecture`
- Color architecture synthesis: `{{sistema_url}}/raw/principles/color/architecture`
Pay attention to the distinction between primitive colors (raw values organized by hue and step) and semantic roles (how those values are used by components and surfaces). The token architecture synthesis defines the naming principles for each tier.
My existing Tailwind config — paste the `theme.colors` section:
{{tailwind_colors}}
Perform the migration in two steps:
**Step 1 — Extract primitives.** Reorganize the raw color values as primitive tokens using a consistent step scale (e.g. `primary-10` through `primary-99`). Do not change any values, only rename and restructure.
**Step 2 — Define semantic roles.** Map those primitives to semantic roles following the naming convention from the token architecture synthesis. Every component-facing role must have a name that communicates its purpose, not its value.
Output:
- A `tokens/primitive/colors.json` file with the restructured primitives
- A `tokens/semantic/colors.json` file with the role mapping
- A Tailwind `theme.extend` config that reads from CSS custom properties so existing Tailwind utility classes continue to work after migration
---
2 KB refs
paste intoClaude CodeCursor
Tip
Plays work best when your agent has read DESIGN.md first. Run session-start at the beginning of each session to orient it.
How plays work
Covers DESIGN.md setup, pulling KB references into prompts, and running plays end-to-end.
Read the guideTip
Plays work best when your agent has read DESIGN.md first. Run session-start at the beginning of each session to orient it.
How plays work
Covers DESIGN.md setup, pulling KB references into prompts, and running plays end-to-end.
Read the guide