shadcn Theming

Agent Workflow (MANDATORY)

Before theming work, use TeamCreate :

• fuse-ai-pilot:explore-codebase - Find existing theme tokens

• 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

• ALWAYS use OKLCH color space for all tokens

• ALWAYS define dark mode overrides for every token

• NEVER hard-code hex or rgb in components

• USE @theme directive for Tailwind v4 integration

• 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