From Toge Design Agent
Use when applying design tokens, choosing colors, typography, spacing, or surface styles for a product UI. Trigger phrases: "what token should I use", "design token", "color token", "apply tokens", "which color for", "semantic color", "dark mode token", "typography token", "surface token", "what class for", "token for danger", "token for success".
How this skill is triggered — by the user, by Claude, or both
Slash command
/toge:design-tokensThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
This skill maps design intent to the correct token class. The system uses a **three-layer architecture** — never skip layers or reach into primitives from component code.
This skill maps design intent to the correct token class. The system uses a three-layer architecture — never skip layers or reach into primitives from component code.
For the full token list, see the references folder:
references/style.css — the real token source — all @theme definitions, CSS custom properties, primitives, semantic tokens, bridge layer, typography, and max-width tokens as they are actually shippedreferences/primitives.yaml — palette inventory and usage rulesreferences/color-tokens.yaml — surface, semantic, text, border, outline token referencereferences/typography.yaml — component typography classesreferences/bridge-dark-mode.yaml — bridge layer, light/dark resolved valuesWhen in doubt about a token value or whether it exists, read the authoritative source first:
guide/toge-design-system/tokens/style.cssreferences/style.css (may lag behind the project's installed version — prefer the project source)Do not rely on memory for token names. Read the file.
Layer 1 — Primitives --color-{palette}-{shade} CSS vars only. Never use in components.
Layer 2 — Bridge (semantic) @layer base :root / .dark Maps primitives to semantic meaning.
Layer 3 — Utilities bg-{token}, .text-{token}, .border-* Use these in components.
Rule: Components always use Layer 3. Layer 1 exists only in references/style.css.
Exception: ubas palette — for data visualization only: charts, graphs, progress rings. Status badges, tags, labels, and any UI element that communicates semantic state must use semantic color families (success, danger, caution, etc.), not ubas.
In-theme — generate bg-* utilities. Full table in references/color-tokens.md.
| Class | Use when |
|---|---|
bg-surface-white | Page / canvas background — topmost layer |
bg-surface-gray | Main gray canvas / app shell |
bg-surface | Alias for surface-gray |
bg-surface-adaptive | Cards, panels, inputs — translucent elevation overlay |
bg-surface-hover | Hover state on any surface |
bg-surface-pressed | Pressed / mousedown state |
bg-surface-disabled | Disabled container |
bg-surface-inverted | Dark surface in light mode (tooltips, dark chips) |
bg-surface-inverted-hover | Hover on inverted surface |
bg-surface-inverted-pressed | Pressed on inverted surface |
bg-surface-active | Selected / active item |
bg-surface-active-soft | Soft selected state |
Seven families: brand · success · information · danger · pending · caution · accent
Each has 9 tokens — full list per family in references/color-tokens.md:
| Modifier | Class | Use when |
|---|---|---|
{family} | bg-{family} | Filled background for this state |
{family}-hover | bg-{family}-hover | Hover on filled background |
{family}-pressed | bg-{family}-pressed | Pressed state on filled background |
{family}-subtle | bg-{family}-subtle | Soft/tinted background |
{family}-subtle-hover | bg-{family}-subtle-hover | Hover on subtle background |
{family}-subtle-pressed | bg-{family}-subtle-pressed | Pressed on subtle background |
{family}-text | text-{family}-text | Text color for this state |
{family}-text-hover | text-{family}-text-hover | Text on hover |
{family}-text-pressed | text-{family}-text-pressed | Text on press |
Control tokens: bg-control · bg-control-hover · bg-control-pressed
Do not generate Tailwind utilities. Use as classes directly.
Text — full table in references/color-tokens.md:
text-strong · text-supporting · text-base · text-weak · text-disabled · text-on-fill-disabled · text-inverted · text-inverted-base · text-inverted-weak · text-inverted-disabled
Border — always pair with border for width:
<div class="border border-base">...</div>
border-strong · border-supporting · border-base · border-base-hover · border-base-pressed · border-weak · border-disabled · border-on-fill-disabled
Outline — same values as border, for outline-color:
outline-strong · outline-base · outline-weak · (same modifiers as border)
Toggle .dark on <html>. Never use media queries. All tokens adapt automatically.
Surface token resolved values (light → dark):
bg-surface-white → #fff light / #262b2b (mushroom-950) dark — darkest layerbg-surface-gray → mushroom-50 light / #394141 (mushroom-900) darkbg-surface-adaptive → translucent mushroom-950 overlay light / translucent white overlay dark→ Full bridge values in references/bridge-dark-mode.md
Full class list in references/typography.md.
| Group | Classes |
|---|---|
| Body | body · body-medium · body-md · body-md-medium · body-lg · body-lg-medium |
| Label | label-xs · label-xs-medium · label-sm · label-sm-medium |
| Heading | heading-xl · heading-lg · heading-md · heading-sm · heading-xs |
| Subheading | subheading-sm · subheading-xs |
| Utility | caption · caption-medium · overline · code |
| Prose | typography (wrapper for long-form content) |
Default body: 14px. Always use component classes — never raw text-{size} utilities (e.g., text-sm, text-base, text-lg).
| Class | Value | Use for |
|---|---|---|
max-w-content-sm | 640px | Narrow: forms, auth pages |
max-w-content-md | 1000px | Standard: dashboards, settings |
max-w-content-lg | 1320px | Wide: landing pages, full-width tables |
max-w-content-full | 100% | Edge-to-edge: full-bleed sections |
Never use raw color or spacing values in any form — not in Tailwind bracket syntax, not in inline style attributes, not in CSS-in-JS. Always use token classes or CSS custom properties. If no token exists, add /* no token: intentional raw value */ as an inline comment.
❌ bg-[#251F31] → bg-surface-gray or bg-surface-adaptive
❌ text-[#262B2B] → text-strong or text-base
❌ border-[#D9DEDE] → border border-base or border-weak
❌ shadow-[0_1px_3px_rgba(0,0,0,0.1)] → use shadow token from surfaces.md
❌ bg-mushroom-100 → bg-surface-gray (primitive in component code)
❌ text-kangkong-600 → text-strong / text-{family}-text
✅ bg-surface-white → page/canvas background, light mode
✅ bg-surface-adaptive → cards, panels, inputs — adapts light/dark
✅ bg-surface-gray → app shell, main canvas
✅ text-strong → primary text
✅ text-base → default body text
✅ text-weak → secondary/supporting text
✅ border border-base → default border
✅ border border-weak → subtle divider
Leave an inline comment so the intent is explicit and reviewable:
<!-- no token: intentional raw value — chart grid line color, ubas exception -->
<div class="bg-[#F5F5F5]">
Backgrounds:
bg-surface-graybg-surface-adaptivebg-surface-whitebg-{family} or bg-{family}-subtlebg-mushroom-100Text:
text-strong, text-base, text-weak, etc.text-{family}-texttext-kangkong-600Borders:
border border-base — defaultborder border-weak — subtle dividerborder border-strong — high emphasis / focus ringborder-mushroom-300Choosing a semantic family:
| Intent | Family |
|---|---|
| Primary actions, brand identity | brand |
| Positive outcome, saved, complete | success |
| Error, destructive action, delete | danger |
| Warning, needs attention | caution |
| Loading, in review, not yet complete | pending |
| Info, help, neutral notice | information |
| Highlights, secondary brand | accent |
Guides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.
npx claudepluginhub micserr/sprout-design-agent --plugin toge