Design Tokens

Design Tokens

This skill ensures consistent token naming and usage across Wythm's codebase.

Token Architecture

Wythm uses a two-layer system:

1. Primitives (colors.primitives.ts) - Raw hex values. The ONLY place for color literals.
2. Semantic Tokens (colors.semantic.ts) - Theme-aware tokens organized by usage.

Quick Reference

Token Structure (dot notation)

color.{usage}.{variant}

In code: theme.colors.{usage}.{variant}

Variant Patterns

Critical Rules

DO

• Use theme.colors.{usage}.{variant} in all components
• Add new tokens to BOTH light and dark schemes
• Follow dot notation naming: color.{usage}.{variant}
• Use kebab-case for multi-word variants: on-brand, border-danger
• Check for existing tokens before creating new ones

DON'T

• Use hex literals outside colors.primitives.ts
• Create deeply nested tokens (max 2 levels)
• Use on-default (use base instead)
• Add tokens to only one color scheme
• Use camelCase in token names (use kebab-case: on-brand not onBrand)

File Locations

When to Read Full Reference

Load references/token-grammar.md when:

• Creating a new usage category (beyond text/background/border/field/icon)
• Adding a new sentiment color (success, warning, info)
• Understanding the complete token creation workflow
• Reviewing naming convention edge cases

Checklist for New Tokens

1. Does similar token already exist? (search colors.semantic.ts)
2. Is raw value needed? (add to colors.primitives.ts)
3. Added to correct usage category?
4. Uses dot notation with kebab-case? (color.text.on-brand)
5. Added to BOTH light and dark schemes?
6. Updated TypeScript types if new keys added?
7. Component uses theme.colors.X.Y not hex literal?

Dot Notation to Code Mapping

Rule: Dot notation uses kebab-case, TypeScript uses camelCase for object keys.