shadcn-theming

Documents the token hierarchy (component → semantic → primitive OKLCH values) and the validation checklist (dark-mode overrides, chart/sidebar variables, no hard-coded hex).

shadcn Theming

Agent Workflow (MANDATORY)

Before theming work, spawn agents in parallel, one Agent call each with a name:

1. fuse-ai-pilot:explore-codebase - Find existing theme tokens
2. fuse-ai-pilot:research-expert - Verify OKLCH patterns via Context7

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

Overview

Feature	Description
CSS Variables	--background, --foreground, --primary
OKLCH Colors	Wide-gamut P3 color space
Dark Mode	.dark class or prefers-color-scheme
Tailwind v4	@theme directive integration

Critical Rules

1. ALWAYS use OKLCH color space for all tokens
2. ALWAYS define dark mode overrides for every token
3. NEVER hard-code hex or rgb in components
4. USE @theme directive for Tailwind v4 integration
5. MAP semantic tokens to primitive OKLCH values

Architecture

app/
├── globals.css         # :root + .dark token definitions
└── tailwind.config.ts  # Optional (v3) or @theme (v4)

-> See theme-setup.md for complete theme

Token Hierarchy

Component: --card, --card-foreground, --button-*
    ↑
Semantic: --primary, --secondary, --accent, --muted
    ↑
Primitive: oklch(55% 0.20 260), oklch(98% 0.01 260)

Validation Checklist

[ ] CSS variables defined in :root
[ ] Dark mode overrides in .dark
[ ] OKLCH color space used
[ ] Chart variables (--chart-1 to --chart-5)
[ ] Sidebar variables if applicable
[ ] No hard-coded hex in components

Best Practices

DO

• Use OKLCH for all colors
• Define semantic tokens mapped to primitives
• Provide dark mode overrides for all tokens
• Use @theme for Tailwind v4 integration

DON'T

• Hard-code hex or rgb values
• Skip dark mode definitions
• Mix color spaces (hex + oklch)
• Define tokens only in Tailwind config

Reference Guide

Concepts

Topic	Reference	When to Consult
Theming Guide	theming-guide.md	CSS variables and OKLCH setup

Templates

Template	When to Use
theme-setup.md	Complete theme configuration