design-tokens — Claude Code rule: what it does, how to install
design-tokens is a Claude Code rule that replaces hardcoded colors with semantic tokens. Light and dark themes then change variable values instead of component classes.
Apache-2.0 ★ 141 updated 2026-11-17
.claude/rules/design-tokens.mdWhat design-tokens does
The design-tokens rule defines names such as --background, --foreground, --primary, and --border for component styling. This keeps a color's role separate from its visual value, so components do not depend on literals such as blue-600 or white.
Its examples place base values in :root, override them in .dark, and connect them through @theme inline for Tailwind CSS. They use oklch() values, add theme variants with [data-theme="brand-b"], and define foreground colors for each semantic role. The guidance also calls for checking contrast against WCAG ratios.
What it helps with
- replace hardcoded component colors
- connect component styles to semantic CSS variables
- add light and dark values through
.dark - create theme variants with
[data-theme] - move color definitions to
oklch()
Example prompts for the agent
- Replace the colors in this component with semantic design tokens.
- Add light and dark theme values using
:rootand.dark. - Change
bg-blue-600andtext-whiteto the tokens from the design-tokens rule.
How to install design-tokens
Manually: put the files in place
.claude/rules/design-tokens.mdThe paths frontmatter field limits the files
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/design-tokens.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/design-tokens.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/design-tokens.mdManually: put the files in place
.clinerules/design-tokens.mdStep by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use
Questions about design-tokens
How do I install design-tokens in Claude Code?
Add the rule to the project at .claude/rules/design-tokens.md.
What does design-tokens do?
It replaces hardcoded component colors with semantic tokens. The rule covers token names, theme overrides, component classes, and oklch() color values.
How does design-tokens handle dark mode?
Base values live in :root, while .dark assigns alternate values to the same variables. Components reference the tokens and use those values automatically.
Source text
design-tokens.md · Apache-2.0
---
title: Design Tokens
impact: MEDIUM
impactDescription: Flexible theming and consistency
tags: design-tokens, css-variables, theming, dark-mode, oklch
---
## Design Tokens
Use semantic design tokens instead of hardcoded colors. Design tokens separate what something is from how it looks.
### Variable Architecture
```css
@import "tailwindcss";
@custom-variant dark (&:is(.dark *));
@theme inline {
--color-background: var(--background);
--color-foreground: var(--foreground);
--color-primary: var(--primary);
--color-primary-foreground: var(--primary-foreground);
}
:root {
--background: oklch(1 0 0);
--foreground: oklch(0.145 0 0);
--primary: oklch(0.205 0 0);
--primary-foreground: oklch(0.985 0 0);
}
.dark {
--background: oklch(0.145 0 0);
--foreground: oklch(0.985 0 0);
--primary: oklch(0.922 0 0);
--primary-foreground: oklch(0.205 0 0);
}
```
### Token Naming
**Base Tokens:**
- `--background` - Main page background
- `--foreground` - Primary text color
- `--muted` - Subtle backgrounds
- `--muted-foreground` - Text on muted
- `--border` - Border colors
- `--ring` - Focus ring
**Semantic Tokens:**
- `--primary` / `--primary-foreground`
- `--secondary` / `--secondary-foreground`
- `--destructive` / `--destructive-foreground`
- `--accent` / `--accent-foreground`
### Usage in Components
**Correct (semantic tokens):**
```tsx
<button className="bg-primary text-primary-foreground hover:bg-primary/90">
Click me
</button>
```
**Incorrect (hardcoded colors):**
```tsx
<button className="bg-blue-600 text-white hover:bg-blue-700">Click me</button>
```
### Component Examples
```tsx
// Card
<div className="bg-background border border-border rounded-lg p-6">
<h2 className="text-foreground font-semibold">Title</h2>
<p className="text-muted-foreground">Description</p>
</div>
// Button variants
<button className="bg-primary text-primary-foreground">Primary</button>
<button className="bg-secondary text-secondary-foreground">Secondary</button>
<button className="bg-destructive text-destructive-foreground">Delete</button>
// Input
<input className="bg-background border border-border text-foreground placeholder:text-muted-foreground" />
```
### Dark Mode
Override tokens in `.dark` class:
```css
:root {
--background: oklch(1 0 0);
--foreground: oklch(0.145 0 0);
}
.dark {
--background: oklch(0.145 0 0);
--foreground: oklch(0.985 0 0);
}
```
Components automatically adapt because they reference tokens.
### Color Format: OKLCH
Use `oklch()` for better color manipulation:
```css
/* ✅ OKLCH - perceptually uniform */
--primary: oklch(0.5 0.2 250);
/* ⚠️ RGB/HSL - harder to manipulate */
--primary: rgb(100, 150, 200);
```
### Best Practices
1. **Never hardcode colors** - Always use design tokens
2. **Use semantic names** - `--primary`, not `--blue-600`
3. **Keep tokens minimal** - Start with base set, add when needed
4. **Document token purpose** - Add comments
5. **Test theme switching** - Ensure all components work in light/dark
6. **Maintain contrast** - Ensure WCAG contrast ratios
### Theme Variants
```css
:root {
--primary: oklch(0.5 0.2 250);
}
[data-theme="brand-b"] {
--primary: oklch(0.5 0.2 120);
}
[data-theme="brand-c"] {
--primary: oklch(0.5 0.2 0);
}
```
### Migration
```tsx
// Before
<div className="bg-white text-gray-900 border-gray-200">Content</div>
// After
<div className="bg-background text-foreground border-border">Content</div>
```
© maxtrigify · Apache-2.0 · maxtrigify/Otto