메뉴
Integration guide for shadcn/ui components with OKLCH design tokens. Use when setting up shadcn, customizing themes, or adding components to Next.js projects. Auto-trigger on /init --tokens --shadcn flag.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
Enforce git commits after every phase and task to enable rollback and prevent lost work. Auto-trigger when completing phases, tasks, or when detecting uncommitted changes. Auto-commit with Conventional Commits format. Verify branch safety, check for merge conflicts, enforce clean working tree. Block completion if changes not committed.
Validates production readiness through performance benchmarking, accessibility audits, security reviews, and code quality checks. Use after implementation phase completes, before deployment, or when conducting quality gates for features. (project)
Deep planning philosophy for craftsman-level architecture. Transforms planning from research-then-design to research-question-simplify-design. Use when --deep flag is set, for epics, complex features (30+ tasks), or when auto_deep_mode preference is enabled. Invokes assumption questioning, codebase soul analysis, and ruthless simplification. (project)
Preview command effects without making changes. Simulates file writes, git operations, agent spawns, and state changes. All reads execute normally for accurate preview. Use --dry-run flag on any command.
Classify workflow failures and attempt automatic recovery. Use when sprint/feature fails during implementation to determine if auto-fix is possible or manual intervention required.
Generate regression tests when bugs are discovered during /debug or continuous checks. Auto-detects test framework, creates Arrange-Act-Assert tests, and links to error-log.md entries. (project)
| name | shadcn-integration |
| description | Integration guide for shadcn/ui components with OKLCH design tokens. Use when setting up shadcn, customizing themes, or adding components to Next.js projects. Auto-trigger on /init --tokens --shadcn flag. |
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:
/init --tokens --shadcnBenefits:
<quick_start> <trigger_pattern> Auto-invoke when:
/init --tokens --shadcn command is run<basic_workflow> Step 1: Run the questionnaire (8 questions)
/init --tokens --shadcn
Step 2: Review generated files
design/systems/shadcn-variables.css - CSS variablescomponents.json - shadcn CLI configcomponents/ui/menu-variants.ts - Menu stylingStep 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:
After:
Use AskUserQuestion tool with these questions in sequence:
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 aliasesdesign/systems/tokens.json - Full token definitionscomponents.json - shadcn CLI configurationcomponents/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.
## OKLCH → shadcn Variable Mapping| OKLCH Token | shadcn Variable | Usage |
|---|---|---|
--color-neutral-50 | --background | Page background |
--color-neutral-900 | --foreground | Primary text |
--color-primary-600 | --primary | Brand actions |
--color-neutral-50 | --primary-foreground | Text on primary |
--color-neutral-100 | --muted | Subtle backgrounds |
--color-neutral-500 | --muted-foreground | Secondary text |
--color-error-fg | --destructive | Delete actions |
--color-neutral-200 | --border | Dividers, inputs |
Menu Color Options:
| Choice | Effect |
|---|---|
background | Uses page background |
surface | Elevated card with shadow |
primaryTint | 5% primary color wash |
glass | Transparent + blur |
Menu Accent Options:
| Choice | Effect |
|---|---|
border | 3px left border on active |
background | Full background highlight |
iconTint | Only icon changes color |
combined | Border + subtle background |
| Choice | Value | Effect |
|---|---|---|
| None | 0 | Sharp corners |
| Small | 0.25rem | Minimal |
| Medium | 0.5rem | Modern (default) |
| Large | 0.75rem | Soft |
| Full | 9999px | Pills |
| Choice | Package | Import |
|---|---|---|
| Lucide | lucide-react | import { Icon } from 'lucide-react' |
| Heroicons | @heroicons/react | import { Icon } from '@heroicons/react/24/outline' |
| Phosphor | @phosphor-icons/react | import { Icon } from '@phosphor-icons/react' |
<quality_gates> FAIL (block next phase):
components.json missing after --shadcn flagWARN (non-blocking):
Validation commands:
# Check components.json exists
test -f components.json && echo "✓ components.json"
# Check shadcn variables
grep -q "shadcn/ui CSS Variable Aliases" design/systems/shadcn-variables.css && echo "✓ shadcn variables"
# Check icon library
pnpm list lucide-react 2>/dev/null || pnpm list @heroicons/react 2>/dev/null && echo "✓ icon library"
</quality_gates>
```bash # 1. Run questionnaire /init --tokens --shadcnpnpm add lucide-react
npx shadcn@latest add button card dropdown-menu
import { Button } from '@/components/ui/button' Click me
</example>
<example name="Custom Primary Color">
When user selects "Custom" for base color:
```typescript
// AskUserQuestion for custom hue
{
question: "Enter OKLCH hue value (0-360)",
header: "Custom Hue",
options: [
{ label: "Teal (175)", description: "Modern, tech-forward" },
{ label: "Coral (15)", description: "Warm, energetic" },
{ label: "Other", description: "Enter exact value" }
]
}
// Result: Full 11-shade scale generated from hue
// oklch(98% 0.045 175) → oklch(14% 0.045 175)
export function Sidebar() { const styles = menuStyles({ menuColor: 'background', menuAccent: 'border' })
return (
Home Settings ) }</example>
</examples>
<troubleshooting>
## Common Issues
**Colors not applying**:
- Verify `@import '../design/systems/shadcn-variables.css'` in globals.css
- Check import order (shadcn-variables before @tailwind directives)
- Ensure Tailwind config has `cssVariables: true`
**Dark mode not working**:
- Add `className="dark"` to html element for class-based dark mode
- Or use `suppressHydrationWarning` with next-themes
- Verify `.dark` CSS block exists in shadcn-variables.css
**Menu variants not found**:
- Install tailwind-variants: `pnpm add tailwind-variants`
- Check `components/ui/menu-variants.ts` exists
- Verify import path in your component
**Icons not loading**:
- Verify correct package installed based on questionnaire choice
- Check import syntax matches package (lucide vs heroicons)
- Ensure tree-shaking is enabled in bundler
**Radius not applying**:
- Check `--radius` variable in :root
- Verify Tailwind config has borderRadius extension
- Some components use `calc(var(--radius) - 2px)` for nested elements
</troubleshooting>
<related_skills>
- `design-tokens` - Core OKLCH token system (this skill extends it)
- `theme-consistency` - Enforces token usage in prototypes
- `mockup-extraction` - Extracts component patterns from mockups
- `frontend-dev` - Uses generated tokens in implementation
</related_skills>