shadcn-integration

Key Principle: OKLCH tokens remain the source of truth. shadcn CSS variables are aliases that reference OKLCH tokens, not hardcoded values.

This skill is auto-invoked when:

• User runs /init --tokens --shadcn
• User asks to add shadcn components to a project
• Customizing shadcn theme colors or styles
• Setting up Next.js with shadcn/ui

Benefits:

• WCAG-compliant colors via OKLCH with perceptual uniformity
• Full shadcn component library compatibility
• 8 customization options without manual CSS editing
• Automatic dark mode support
• Menu-specific theming with variants

<quick_start> <trigger_pattern> Auto-invoke when:

• /init --tokens --shadcn command is run
• User asks to "add shadcn" or "setup shadcn"
• User wants to customize theme colors
• Setting up new Next.js project with components </trigger_pattern>

<basic_workflow> Step 1: Run the questionnaire (8 questions)

/init --tokens --shadcn

Step 2: Review generated files

• design/systems/shadcn-variables.css - CSS variables
• components.json - shadcn CLI config
• components/ui/menu-variants.ts - Menu styling

Step 3: Import in globals.css

@import '../design/systems/shadcn-variables.css';

Step 4: Add components

npx shadcn@latest add button card dropdown-menu

</basic_workflow>

<immediate_value> Before:

• Manual theme.css editing with hardcoded HSL values
• Inconsistent color contrast
• No systematic menu theming
• Dark mode requires manual CSS duplication

After:

• 8 questions → complete theme system
• OKLCH ensures WCAG-compliant contrast
• Menu variants via tailwind-variants
• Automatic dark mode via CSS variables </immediate_value> </quick_start>

Use AskUserQuestion tool with these questions in sequence:

1. Style Preset → Determines shadcn style + density
2. Base Color → Generates OKLCH primary scale (11 shades)
3. Theme Mode → Configures light/dark/system preference
4. Icon Library → Sets package and components.json config
5. Font Family → Configures next/font
6. Border Radius → Sets --radius CSS variable
7. Menu Color → Generates menu background tokens
8. Menu Accent → Generates menu active state tokens

Run the token generation script:

node .spec-flow/scripts/node/generate-shadcn-tokens.js --config answers.json

Generated files:

• design/systems/shadcn-variables.css - shadcn CSS variable aliases
• design/systems/tokens.json - Full token definitions
• components.json - shadcn CLI configuration
• components/ui/menu-variants.ts - Menu styling with tailwind-variants

Based on questionnaire answers:

# Icon library (based on choice)
pnpm add lucide-react  # or @heroicons/react or @phosphor-icons/react

# shadcn dependencies
pnpm add tailwindcss-animate class-variance-authority clsx tailwind-merge

# For menu variants
pnpm add tailwind-variants

Update app/layout.tsx with font configuration:

import { Inter } from 'next/font/google'

const fontSans = Inter({
  subsets: ['latin'],
  variable: '--font-sans',
})

export default function RootLayout({ children }) {
  return (
    <html lang="en" className={fontSans.variable}>
      <body>{children}</body>
    </html>
  )
}

Now users can add components that automatically use the generated theme:

npx shadcn@latest add button
npx shadcn@latest add card
npx shadcn@latest add dropdown-menu
npx shadcn@latest add dialog

Components will use CSS variables from shadcn-variables.css.