For...	Start Here	Time
Quick Start	⚡ 5-Minute Crash Course	5 min
Component Development	🧩 Components → 🔨 Creation Guide	15 min
Layout Design	📐 Layouts → 📏 Spacing	20 min
AI Code Generation	🤖 AI Guidelines	3 min
Quick Reference	📚 Reference Tables	Instant
Complete Guide	Read all docs in order	1 hour

📖 Documentation Structure

Branding & Identity

Branding Guidelines 🎨
- Mission & Values
- Visual Identity (Logo, Colors, Typography)

Getting Started

00. Quick Start ⚡
- 5-minute crash course
- Essential components and patterns
- Copy-paste ready examples

Fundamentals

01. Foundations 🎨
- Color system (OKLCH)
- Typography scale
- Spacing tokens
- Shadows & radius
02. Components 🧩
- shadcn/ui component library
- All variants documented
- Usage examples
- Composition patterns

Layouts & Spacing

03. Layouts 📐
- Grid vs Flex decision tree
- Common layout patterns
- Responsive strategies
- Before/after examples
04. Spacing Philosophy 📏
- Parent vs child spacing rules
- Margin vs padding strategy
- Gap vs margin for flex/grid
- Consistency patterns

Building Components

05. Component Creation 🔨
- When to create vs compose
- Component templates
- Variant patterns (CVA)
- Testing checklist
06. Forms 📝
- Form patterns & validation
- Error state UI
- Loading states
- Multi-field examples

Best Practices

07. Accessibility ♿
- WCAG AA compliance
- Keyboard navigation
- Screen reader support
- ARIA attributes
08. AI Guidelines 🤖
- Rules for AI code generation
- Required patterns
- Forbidden practices
- Component templates

Reference

99. Reference Tables 📚
- Quick lookup tables
- All tokens at a glance
- Cheat sheet

🎪 Interactive Examples

Explore live examples and copy-paste code:

Component Showcase - All shadcn/ui components with variants
Layout Patterns - Before/after comparisons of layouts
Spacing Examples - Visual spacing demonstrations
Form Patterns - Complete form examples

Each demo page includes:

✅ Live, interactive examples
✅ Click-to-copy code snippets
✅ Before/after comparisons
✅ Links to documentation

🛤️ Learning Paths

Path 1: Speedrun (5 minutes)

Goal: Start building immediately

Quick Start - Essential patterns
Reference - Bookmark for lookup
Start coding!

When to use: You need to build something NOW and will learn deeply later.

Path 2: Component Developer (15 minutes)

Goal: Master component building

Quick Start - Basics
Components - shadcn/ui library
Component Creation - Building custom components
Reference - Bookmark

When to use: You're building reusable components or UI library.

Path 3: Layout Specialist (20 minutes)

Goal: Master layouts and spacing

Quick Start - Basics
Foundations - Spacing tokens
Layouts - Grid vs Flex patterns
Spacing Philosophy - Margin/padding rules
Reference - Bookmark

When to use: You're designing page layouts or dashboard UIs.

Path 4: Form Specialist (15 minutes)

Goal: Master forms and validation

Quick Start - Basics
Components - Form components
Forms - Patterns & validation
Accessibility - ARIA for forms
Reference - Bookmark

When to use: You're building forms with complex validation.

Path 5: AI Setup (3 minutes)

Goal: Configure AI for perfect code generation

AI Guidelines - Read once, code forever
Reference this in your AI context/prompts

When to use: You're using AI assistants (Claude, GitHub Copilot, etc.) to generate code.

Path 6: Comprehensive Mastery (1 hour)

Goal: Complete understanding of the design system

Read all documents in order:

Explore all interactive demos.

When to use: You're the design system maintainer or want complete mastery.

🎯 Key Principles

Our design system is built on these core principles:

🎨 Semantic First - Use bg-primary, not bg-blue-500
♿ Accessible by Default - WCAG AA minimum, keyboard-first
📐 Consistent Spacing - Multiples of 4px (0.25rem)
🧩 Compose, Don't Create - Use shadcn/ui primitives
🌗 Dark Mode Ready - All components work in light/dark
⚡ Pareto Efficient - 80% of needs with 20% of patterns

🏗️ Technology Stack

Framework: Next.js 16 + React 19
Styling: Tailwind CSS 4 (CSS-first configuration)
Components: shadcn/ui (New York style)
Color Space: OKLCH (perceptually uniform)
Icons: lucide-react
Fonts: Geist Sans + Geist Mono

🤝 Contributing to the Design System

Adding a New Component

Read Component Creation Guide
Follow the template
Add to Component Showcase
Document in Components

Adding a New Pattern

Validate it solves a real need (used 3+ times)
Document in appropriate guide
Add to Reference
Create example in /dev/

Updating Colors/Tokens

Edit src/app/globals.css
Test in both light and dark modes
Verify WCAG AA contrast
Update Foundations

📝 Quick Reference

Most Common Patterns

// Button
<Button variant="default">Action</Button>
<Button variant="destructive">Delete</Button>

// Card
<Card>
  <CardHeader>
    <CardTitle>Title</CardTitle>
  </CardHeader>
  <CardContent>Content</CardContent>
</Card>

// Form Input
<Label htmlFor="email">Email</Label>
<Input id="email" type="email" {...field} />
{errors.email && (
  <p className="text-sm text-destructive">{errors.email.message}</p>
)}

// Layout
<div className="container mx-auto px-4 py-8">
  <div className="max-w-4xl mx-auto space-y-6">
    {/* Content */}
  </div>
</div>

// Grid
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
  {items.map(item => <Card key={item.id}>...</Card>)}
</div>

🆘 Need Help?

Quick Answer: Check Reference
Pattern Question: Search relevant doc (Layouts, Components, etc.)
Can't Find It: Browse Interactive Examples
Still Stuck: Read Quick Start or Comprehensive Guide

📊 Design System Metrics

Components: 20+ shadcn/ui components
Color Tokens: 25+ semantic color variables
Layout Patterns: 5 essential patterns (80% coverage)
Spacing Scale: 14 token sizes (0-16)
Typography Scale: 9 sizes (xs-9xl)
Test Coverage: All patterns demonstrated in /dev/

📚 External Resources

Last Updated: November 2, 2025 Version: 1.0 Maintainer: Design System Team

README.md

Design System Documentation

🚀 Quick Navigation