| name | set-up-design-system |
| description | Use when establishing a design system for a frontend project — defines Tailwind v4 @theme tokens (colors/spacing/radius/fonts), class-based dark mode driven by a persisted theme store, a cn() class merger, and variant-driven primitives via class-variance-authority, with shadcn/ui as the optional component registry. |
Set Up Design System
1. Audit current state
grep -E '"(class-variance-authority|clsx|tailwind-merge|tailwindcss|tailwind-variants)"' package.json 2>/dev/null
grep -n "@theme\|@custom-variant" src/index.css src/style.css 2>/dev/null
ls components.json 2>/dev/null
Detect existing tokens, a variant lib, and dark-mode wiring. Prerequisites: Tailwind v4 installed (scaffold-frontend-project), @/ alias, and set-up-state-management (the theme toggle is a UI-state store).
2. Decide what to do
- No tokens/primitives → full setup.
- Tokens present but ad-hoc class strings → add
cn() + cva variants.
- shadcn/ui already initialized → adopt its
cn/cva; just add the token layer + theme store.
3. Detect framework
React → primitives as .tsx with cva. Vue → primitives as SFCs using the same cva class strings. cn() and @theme are framework-agnostic.
4. Install
pnpm add class-variance-authority clsx tailwind-merge
(Optional, React: pnpm dlx shadcn@latest init — generates owned, cva-based primitives into your tree. Then skip hand-writing step 7.)
5. Define tokens in @theme (CSS-first)
Tailwind v4 reads tokens from CSS and generates the matching utilities (bg-brand-600, rounded-card, …). Use semantic names and oklch for perceptually-even colors.
@import "tailwindcss";
@custom-variant dark (&:where(.dark, .dark *));
@theme {
--color-brand-50: oklch(0.97 0.02 255);
--color-brand-500: oklch(0.62 0.19 255);
--color-brand-600: oklch(0.54 0.20 255);
--radius-card: 0.75rem;
--font-sans: "Inter", system-ui, sans-serif;
}
6. The cn() class merger
import { clsx, type ClassValue } from 'clsx';
import { twMerge } from 'tailwind-merge';
export function cn(...inputs: ClassValue[]) {
return twMerge(clsx(inputs));
}
7. A variant-driven primitive (atom)
React
import { cva, type VariantProps } from 'class-variance-authority';
import type { ButtonHTMLAttributes } from 'react';
import { cn } from '@/utils/cn';
const button = cva(
'inline-flex items-center justify-center rounded-md font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-brand-600 disabled:pointer-events-none disabled:opacity-50',
{
variants: {
variant: {
solid: 'bg-brand-600 text-white hover:bg-brand-500',
outline: 'border border-brand-600 text-brand-600 hover:bg-brand-50 dark:hover:bg-brand-600/10',
ghost: 'text-brand-600 hover:bg-brand-50 dark:hover:bg-brand-600/10',
},
size: { sm: 'h-8 px-3 text-sm', md: 'h-10 px-4', lg: 'h-12 px-6 text-lg' },
},
defaultVariants: { variant: 'solid', size: 'md' },
},
);
type ButtonProps = ButtonHTMLAttributes<HTMLButtonElement> & VariantProps<typeof button>;
export function Button({ className, variant, size, ...props }: ButtonProps) {
return <button className={cn(button({ variant, size }), className)} {...props} />;
}
For Vue, mirror with an SFC: define the same button cva map, then :class="cn(button({ variant, size }), $attrs.class)".
8. Dark mode = persisted UI state, applied before first paint (no FOUC)
The theme is UI state — a small persisted store — but it must reach <html> before the bundle paints, or dark-mode users get a flash of light. Two parts:
1. Pre-paint, inline in index.html (runs before the JS bundle loads):
<script>
(() => {
let t = 'system';
try { t = JSON.parse(localStorage.getItem('theme') ?? '{}')?.state?.theme ?? 'system'; } catch {}
const dark = t === 'dark' || (t === 'system' && matchMedia('(prefers-color-scheme: dark)').matches);
document.documentElement.classList.toggle('dark', dark);
})();
</script>
(It parses Zustand's persisted shape stored under the theme key — keep that key in sync with the store.)
2. The store — 'light' | 'dark' | 'system', defaulting to system:
import { create } from 'zustand';
import { persist } from 'zustand/middleware';
type Theme = 'light' | 'dark' | 'system';
type ThemeState = { theme: Theme; setTheme: (t: Theme) => void };
export const useThemeStore = create<ThemeState>()(
persist((set) => ({ theme: 'system', setTheme: (theme) => set({ theme }) }), { name: 'theme' }),
);
export const resolveTheme = (t: Theme): 'light' | 'dark' =>
t === 'system' ? (matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light') : t;
useEffect(() => {
const apply = () =>
document.documentElement.classList.toggle('dark', resolveTheme(useThemeStore.getState().theme) === 'dark');
apply();
const unsub = useThemeStore.subscribe(apply);
const mq = matchMedia('(prefers-color-scheme: dark)');
mq.addEventListener('change', apply);
return () => { unsub(); mq.removeEventListener('change', apply); };
}, []);
Vue: the same store as a Pinia setup-store + a watchEffect + the same matchMedia listener; the inline script's theme key must match the store's persist name.
9. Verify
pnpm tsc --noEmit
pnpm dev
<Button variant="outline" size="lg"> renders with tokens; toggling the theme store flips .dark on <html> and dark: utilities apply. Reload preserves the choice (persisted).
References
- ./design-tokens.md — token naming, cva + cn rationale, dark-mode strategy, theme-is-UI-state, shadcn/ui, when to deviate.
- ../_shared/glossary.md — theme as UI state.
- ../_shared/conventions.md —
@/ alias, atoms layer, stores/.
