Design-Tokens und Themen

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:

1. 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.
2. 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.
3. 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).