Skip to main content
rule CX Codex

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

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/rules/design-tokens.md
Open on GitHub

What 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 :root and .dark.
  • Change bg-blue-600 and text-white to the tokens from the design-tokens rule.

How to install design-tokens

Manually: put the files in place

.claude/rules/design-tokens.md

The paths frontmatter field limits the files

Step 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

Similar IDE rules

All IDE rules for Frontend and UI →

From the same set18

The whole set →
npm npm is a Claude Code rule that guides the packaging of UI components into versioned releases. It enforces strict exports mapping, peer dependency boundaries, and build steps. CX Codex +1 ★ 141repo stars registry registry is a Claude Code rule for publishing UI components as source code. It defines registry metadata and a deployment flow. CX Codex +1 ★ 141repo stars marketplaces The marketplaces rule for Claude Code organizes component discovery and integration from external registries. It helps the agent evaluate code quality before adding dependencies. CX Codex +1 ★ 141repo stars composition The composition rule for Claude Code guides the breakdown of complex UI components into small, focused parts. It serves when building component libraries or flexible interfaces. CX Codex +1 ★ 141repo stars overview overview is a Claude Code rule for designing accessible, composable UI components. It comes into play while shaping component APIs and shared patterns. CX Codex +1 ★ 141repo stars types The types rule for Claude Code standardizes component prop definitions in TypeScript. It provides a framework for building flexible, type-safe interfaces across React projects. CX Codex +1 ★ 141repo stars data-attributes data-attributes is a Claude Code rule for styling component states and targeting nested parts with data-state and data-slot. CX Codex +1 ★ 141repo stars principles The principles rule for Claude Code establishes six core standards for component design. It guides agents during component creation, refactoring, and evaluation. CX Codex +1 ★ 141repo stars

Project sponsors

Companies that keep this analytics open