# Set Up Design System > 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. - Skill: `velimirmueller/set-up-design-system` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add velimirmueller/set-up-design-system` - Raw SKILL.md: https://api.skillmd.com/api/skills/velimirmueller/set-up-design-system/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Design & Media - Author: VelimirMueller (https://skillmd.com/u/velimirmueller) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/velimirmueller/set-up-design-system --- # Set Up Design System ## 1. Audit current state ```bash 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 # shadcn/ui marker ``` 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 ```bash 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. ```css /* src/index.css (or src/style.css) */ @import "tailwindcss"; /* class-based dark mode: `dark:` applies under .dark on */ @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 ```ts // src/utils/cn.ts import { clsx, type ClassValue } from 'clsx'; import { twMerge } from 'tailwind-merge'; /** Merge class lists, with later Tailwind utilities winning over earlier ones. */ export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)); } ``` ## 7. A variant-driven primitive (atom) ### React ```tsx // src/components/atoms/Button/Button.tsx 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 & VariantProps; export function Button({ className, variant, size, ...props }: ButtonProps) { return