theming-tokens_skill

Overview

This skill helps teams create and maintain robust theme systems, color variables, and design tokens across primitives, semantic layers, and component-specific tokens. It codifies a three-tier token hierarchy and provides practical patterns for light/dark mode, Tailwind v4 @theme integration, and validation checks. The goal is consistent, accessible design values that are easy to map and override.

How this skill works

The skill inspects a codebase to locate existing tokens and recommends a clear separation: primitive tokens (raw values), semantic tokens (purpose-based mappings), and component tokens (component-specific variables). It produces CSS/OKLCH examples, dark-mode overrides, and a Tailwind v4 @theme snippet. It also provides a checklist to validate primitives, semantics, dark-mode coverage, and the absence of hard-coded hex in components.

When to use it

• When building or refactoring a design system and you need a consistent token hierarchy.
• When introducing dark-mode support and wanting systematic overrides tied to primitives.
• When mapping OKLCH color primitives into semantic roles for components and themes.
• When integrating tokens into Tailwind v4 using @theme and centralizing theme values.
• When auditing a codebase to replace hard-coded colors with design tokens.

Best practices

• Use the three-tier hierarchy: primitives → semantic → component to keep intent clear.
• Prefer OKLCH (or wide-gamut color spaces) for color primitives to ensure perceptual consistency.
• Map all semantic tokens to primitives and avoid direct hex usage in components.
• Provide explicit dark-mode overrides for every semantic token that affects UI surfaces.
• Keep spacing/radius on a consistent grid (e.g., 4px) and reference them from components.

Example use cases

• Define base color primitives (oklch) and map them to semantic roles like --color-primary and --color-surface.
• Create component tokens such as --button-bg and --card-padding that reference semantic tokens and spacing primitives.
• Add a .dark scope with semantic overrides to enable a single dark-mode switch.
• Integrate theme tokens into Tailwind v4 via @theme to expose design tokens to utility classes.
• Run a validation checklist to confirm primitives exist, semantics are mapped, and no hard-coded hex values remain.