Design tokens and themes

Connects visual values to semantic interface roles so themes and component refinements remain consistent.

design-tokens-theming

Team members using this skill

See how it helps

When is it useful?

Use when hardcoded colors or spacing make dark mode and visual changes difficult.

What does it help you do?

Separates raw palette values from roles such as text, surface and status.
Uses component tokens only for settings that need a specific override.
Maps supported themes and interaction states without scattering literal values.

Try asking this

Convert our alert and button colors into semantic tokens and show their light, dark, disabled and focus states. Switch themes while an error alert and focused button are visible. Verify contrast and semantic meaning remain consistent without changing component code.

Detailed documentation

Read the skill’s original instructions, examples and checks in their authored language.

Details…Show less

Design Tokens & Theming

Design tokens are the single source of visual truth connecting design decisions to code. Organize tokens by semantic intent rather than raw visual value so themes, dark mode and visual refinements propagate cleanly without hunting down hardcoded values.

1. Three-Tier Token Architecture (Jina Anne / W3C DTCG)

Structure tokens in three deliberate layers:

Tier 1 — Primitive / Reference Tokens (Raw Palette & Scales):
- Context-agnostic raw values defining the available options: color ramps (--color-slate-900, --color-indigo-600, --color-amber-500), spacing steps (--space-1: 0.25rem, --space-2: 0.5rem, --space-4: 1rem), font families, font-size/line-height scales, border radii and easing curves.
- Rule: application screens and feature components should rarely reference primitive color tokens directly, because --color-slate-900 cannot adapt automatically between light and dark themes.
Tier 2 — Semantic / System Tokens (Purpose & Role):
- Alias primitive tokens by their meaning in the interface:
  - Surfaces / Backgrounds: --bg-canvas, --bg-surface, --bg-surface-raised, --bg-surface-overlay, --bg-subtle.
  - Text / Foregrounds: --text-primary, --text-secondary, --text-muted, --text-on-accent, --text-danger.
  - Borders & Focus: --border-subtle, --border-strong, --border-focus, --ring-focus.
  - Interactive & Status: --accent-primary, --accent-primary-hover, --status-success-bg/text/border, --status-warning-*, --status-danger-*.
- Rule: 90%+ of component and layout styling should consume Tier 2 semantic tokens.
Tier 3 — Component-Scoped Tokens (When Justified):
- Introduced only when a complex component needs stable override hooks across themes (--button-bg, --dialog-backdrop, --input-border-invalid), always aliasing Tier 2 semantic tokens by default.

2. Typography, Spacing, Sizing & Elevation Scales

Typographic tokens: bundle font family, font-size (in rem), line-height, font-weight and letter-spacing into coherent semantic roles (heading-xl, heading-md, body-md, body-sm, label-md, code-sm). Use tabular-nums (font-variant-numeric: tabular-nums) on numeric columns, prices, timers and counters so digits never jitter.
Spacing & sizing discipline: derive padding, gaps and layout rhythm from the shared spacing scale (4px/0.25rem base grid). Avoid magic pixel numbers.
Elevation & layering: pair surface elevation tokens (raised, floating, modal) with a documented z-index scale (dropdown, sticky, CreationDrawer, modalBackdrop, modal, popover, toast, tooltip) so overlays never fight in arbitrary z-index: 99999 wars.

3. Token Governance & Alignment

Align visual token values and naming with the UI/UX designer before introducing new primitives.
Audit every new token for WCAG contrast compliance across all supported themes (e.g., ensuring --text-secondary on --bg-surface-raised maintains >= 4.5:1 in both light and dark modes).

Included files 1

SKILL.md