home / skills / fusengine / agents / theming-tokens

theming-tokens skill

safe

/plugins/design-expert/skills/theming-tokens

This skill guides you in building a cohesive theming system by organizing primitives, semantic, and component tokens for scalable design.

npx playbooks add skill fusengine/agents --skill theming-tokens

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

3.3 KB

---
name: theming-tokens
description: Use when creating theme systems, color variables, or design system tokens. Covers primitives, semantic, and component tokens.
versions:
  tailwindcss: "4.1"
user-invocable: true
allowed-tools: Read, Write, Edit, Glob, Grep
related-skills: designing-systems, dark-light-modes
---

# Theming Tokens

## Agent Workflow (MANDATORY)

Before implementation, use `TeamCreate` to spawn 3 agents:

1. **fuse-ai-pilot:explore-codebase** - Find existing tokens
2. **fuse-ai-pilot:research-expert** - Tailwind v4 @theme patterns

After: Run **fuse-ai-pilot:sniper** for validation.

---

## Overview

| Feature | Description |
|---------|-------------|
| **Primitives** | Raw values (blue-500, radius-lg) |
| **Semantic** | Purpose-based (primary, surface) |
| **Component** | Specific (button-bg, card-border) |

---

## Token Hierarchy

```
┌─────────────────────────────────────────────────┐
│ COMPONENT TOKENS (specific)                     │
│ --button-bg, --card-border, --input-focus       │
├─────────────────────────────────────────────────┤
│ SEMANTIC TOKENS (purpose)                       │
│ --color-primary, --color-surface, --color-text  │
├─────────────────────────────────────────────────┤
│ PRIMITIVE TOKENS (raw values)                   │
│ --blue-500, --gray-100, --radius-lg             │
└─────────────────────────────────────────────────┘
```

---

## Quick Reference

### Primitive Tokens

```css
:root {
  /* Colors - OKLCH for P3 gamut */
  --blue-500: oklch(55% 0.20 260);
  --green-500: oklch(65% 0.20 145);

  /* Radius */
  --radius-lg: 0.75rem;
  --radius-2xl: 1.5rem;

  /* Spacing (4px grid) */
  --space-4: 1rem;
  --space-6: 1.5rem;
}
```

### Semantic Tokens

```css
:root {
  --color-background: var(--gray-50);
  --color-foreground: var(--gray-900);
  --color-primary: var(--blue-500);
  --color-surface: var(--white);

  /* Glass */
  --glass-bg: rgba(255, 255, 255, 0.8);
  --glass-border: rgba(255, 255, 255, 0.2);
}

.dark {
  --color-background: var(--gray-950);
  --color-foreground: var(--gray-50);
  --glass-bg: rgba(0, 0, 0, 0.4);
}
```

### Component Tokens

```css
:root {
  --button-height: 2.5rem;
  --button-radius: var(--radius-lg);
  --card-radius: var(--radius-2xl);
  --card-padding: var(--space-6);
}
```

### Tailwind v4 @theme

```css
@import "tailwindcss";

@theme {
  --color-primary: oklch(55% 0.20 260);
  --font-display: 'Clash Display', sans-serif;
}
```

---

## Validation Checklist

```
[ ] Primitives defined (colors, spacing, radius)
[ ] Semantics mapped to primitives
[ ] Dark mode overrides present
[ ] @theme configured for Tailwind v4
[ ] No hard-coded hex in components
```

---

## Best Practices

### DO
- Use three-tier hierarchy
- Map semantics to primitives
- Define dark mode overrides
- Use OKLCH for colors

### DON'T
- Hard-code hex values
- Skip semantic layer
- Forget dark mode
- Mix color spaces

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.

FAQ

Why use three-tier token hierarchy?

Separating primitives, semantics, and component tokens preserves intent, simplifies theme swaps, and prevents duplicated hard-coded values.

Should I always use OKLCH for colors?

OKLCH is recommended for perceptual uniformity and wide-gamut work, but choose a color space that fits your project constraints and tooling.