design-system
Use when architecting design tokens, setting up CSS custom properties, organizing theme systems, debugging CSS specificity issues, or establishing component API patterns. Also use for CSS architecture decisions (Tailwind vs Modules vs Vanilla Extract) and token layer organization.
| Model | Source |
|---|---|
| sonnet | pack: frontend |
Full Reference
Design System
Section titled “Design System”The structural and technical architecture of design systems — token layers, CSS architecture decisions, theming strategies, component API patterns, and CSS debugging. The “how” to ui-craft’s “what.” Where ui-craft answers “what should this look like,” design-system answers “how should it be organized and maintained.”
Announcement
Section titled “Announcement”┏━ 🎨 design-system ━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ [one-line description of design system task] ┃ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Quick Reference
Section titled “Quick Reference”| Item | Value |
|---|---|
| Token model | Three layers: Primitive → Semantic → Component |
| Default CSS approach | Tailwind v4 with @theme CSS custom properties |
| RSC safe approaches | Tailwind v4, CSS Modules, Vanilla Extract, Panda CSS |
| Avoid for RSC | Emotion, styled-components (runtime overhead) |
| Component variant tool | cva (class-variance-authority) + cn() utility |
| Specificity fix | CSS @layer ordering beats specificity fights |
| Extend vs replace | Always extend existing tokens before creating new files |
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Reference Index
Section titled “Reference Index”| I want to… | File |
|---|---|
| Set up the three-layer token model (primitive/semantic/component) | reference/token-architecture.md |
| Choose between Tailwind, CSS Modules, Vanilla Extract, Panda CSS | reference/css-architecture.md |
| Implement dark mode, light mode, or multi-brand theming | reference/theming.md |
| Build component APIs with cva, cn(), and compound patterns | reference/component-api.md |
| Debug z-index, overflow, specificity, layout shift, or spacing issues | reference/css-debugging.md |
Usage: Read the reference file matching your current task from the index above. Each file is self-contained with code examples and inline gotchas.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Integration
Section titled “Integration”| Skill | Relationship |
|---|---|
| ui-craft | ui-craft defines WHAT it looks like, design-system defines HOW it’s structured |
| tailwind-css | design-system defines tokens, Tailwind consumes them via @theme |
| shadcn-ui | shadcn uses CSS variables that follow this three-layer token architecture |
| brand | brand.json values become primitive tokens; never hardcode brand colors |
| nap-ninja | same centralization principle — source of truth over duplication |