fast-next-template/frontend/docs/design-system

Design System Documentation

FastNext Template Design System - A comprehensive guide to building consistent, accessible, and beautiful user interfaces.

---

🚀 Quick Navigation

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

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

1. Quick Start - Essential patterns
2. Reference - Bookmark for lookup
3. 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

1. Quick Start - Basics
2. Components - shadcn/ui library
3. Component Creation - Building custom components
4. Reference - Bookmark

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

---

Path 3: Layout Specialist (20 minutes)

Goal: Master layouts and spacing

1. Quick Start - Basics
2. Foundations - Spacing tokens
3. Layouts - Grid vs Flex patterns
4. Spacing Philosophy - Margin/padding rules
5. Reference - Bookmark

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

---

Path 4: Form Specialist (15 minutes)

Goal: Master forms and validation

1. Quick Start - Basics
2. Components - Form components
3. Forms - Patterns & validation
4. Accessibility - ARIA for forms
5. 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

1. AI Guidelines - Read once, code forever
2. 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:

1. Quick Start
2. Foundations
3. Components
4. Layouts
5. Spacing Philosophy
6. Component Creation
7. Forms
8. Accessibility
9. AI Guidelines
10. Reference

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:

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

---

🏗️ Technology Stack

• Framework: Next.js 15 + 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

1. Read Component Creation Guide
2. Follow the template
3. Add to Component Showcase
4. Document in Components

Adding a New Pattern

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

Updating Colors/Tokens

1. Edit src/app/globals.css
2. Test in both light and dark modes
3. Verify WCAG AA contrast
4. 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?

1. Quick Answer: Check Reference
2. Pattern Question: Search relevant doc (Layouts, Components, etc.)
3. Can't Find It: Browse Interactive Examples
4. 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

• shadcn/ui Documentation
• Tailwind CSS 4 Documentation
• OKLCH Color Picker
• WCAG 2.1 Guidelines
• Radix UI Primitives

---

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