/phase-5-design-system

name: phase-5-design-system
context: fork
background: false
classification: capability
classification-reason: Pattern guidance may overlap with model's built-in knowledge as it improves
deprecation-risk: medium
effort: medium
user-invocable: false
description: |
  Build platform-independent design systems and consistent component libraries.
  Triggers: design system, component library, design tokens
  default: bkit:pipeline-guide
  frontend: bkit:frontend-architect
allowed-tools:
  - Read
  - Write
  - Edit
  - Glob
  - Bash
next-skill: phase-6-ui-integration
pdca-phase: do
task-template: "[Phase-5] {feature}"

Phase 5: Design System

> Build platform-independent design system

Purpose

Build a reusable UI component library. Enable consistent design and fast development.

---

What is a Design System?

Definition

A design system is **a collection of reusable components and clear standards** that enables building consistent user experiences at scale.

Why is it Needed? (Framework Agnostic)

| Problem | Design System Solution | |---------|----------------------| | Designer-developer mismatch | Single Source of Truth | | Duplicate component development | Reusable component library | | Inconsistent UI/UX | Unified design tokens and rules | | Increased maintenance cost | Centralized change management | | Delayed new member onboarding | Documented component catalog |

3 Layers of Design System

┌─────────────────────────────────────────────────────┐
│              Design Tokens                           │
│   Color, Typography, Spacing, Radius, Shadow, ...   │
├─────────────────────────────────────────────────────┤
│              Core Components                         │
│   Button, Input, Card, Dialog, Avatar, Badge, ...   │
├─────────────────────────────────────────────────────┤
│            Composite Components                      │
│   Form, DataTable, Navigation, SearchBar, ...       │
└─────────────────────────────────────────────────────┘

Platform-specific Implementation Tools

| Platform | Recommended Tools | Design Token Method | |----------|------------------|---------------------| | **Web (React/Next.js)** | shadcn/ui, Radix | CSS Variables | | **Web (Vue)** | Vuetify, PrimeVue | CSS Variables | | **Flutter** | Material 3, Custom Theme | ThemeData | | **iOS (SwiftUI)** | Native Components | Asset Catalog, Color Set | | **Android (Compose)** | Material 3 | MaterialTheme | | **React Native** | NativeBase, Tamagui | StyleSheet + Theme |

---

What to Do in This Phase

1. **Install Base Components**: Button, Input, Card, etc. 2. **Customize**: Adjust to project style 3. **Composite Components**: Combine multiple base components 4. **Documentation**: Document component usage

Deliverables

components/
└── ui/                     # shadcn/ui components
    ├── button.tsx
    ├── input.tsx
    ├── card.tsx
    └── ...

lib/
└── utils.ts                # Utilities (cn function, etc.)

docs/02-design/
└── design-system.md        # Design system specification

PDCA Application

• **Plan**: Required component list
• **Design**: Component structure, variants design
• **Do**: Implement/customize components
• **Check**: Review consistency
• **Act**: Finalize and proceed to Phase 6

Level-wise Application

| Level | Application Method | |-------|-------------------| | Starter | Optional (simple projects may skip) | | Dynamic | Required | | Enterprise | Required (including design tokens) |

shadcn/ui Installation

# Initial setup
npx shadcn@latest init

# Add components
npx shadcn@latest add button
npx shadcn@latest add input
npx shadcn@latest add card

Required Component List

Basic

• Button, Input, Textarea
• Card, Badge, Avatar
• Dialog, Sheet, Popover

Form

• Form, Label, Select
• Checkbox, Radio, Switch

Navigation

• Navigation Menu, Tabs
• Breadcrumb, Pagination

Custom Theme Building

Design Token Override

shadcn/ui is CSS variable-based, so customize themes in `globals.css`.

/* globals.css */
@layer base {
  :root {
    /* ===== Colors ===== */
    --background: 0 0% 100%;
    --foreground: 222.2 84% 4.9%;
    --primary: 221.2 83.2% 53.3%;      /* Brand main color */
    --primary-foreground: 210 40% 98%;
    --secondary: 210 40% 96.1%;
    --accent: 210 40% 96.1%;
    --destructive: 0 84.2% 60.2%;
    --muted: 210 40% 96.1%;
    --muted-foreground: 215.4 16.3% 46.9%;

    /* ===== Typography ===== */
    --font-sans: 'Pretendard', sans-serif;
    --font-mono: 'JetBrains Mono', monospace;

    /* ===== Spacing (rem units) ===== */
    --spacing-xs: 0.25rem;   /* 4px */
    --spacing-sm: 0.5rem;    /* 8px */
    --spacing-md: 1rem;      /* 16px */
    --spacing-lg: 1.5rem;    /* 24px */
    --spacing-xl: 2rem;      /* 32px */

    /* ===== Border Radius ===== */
    --radius: 0.5rem;
    --radius-sm: 0.25rem;
    --radius-lg: 0.75rem;
    --radius-full: 9999px;

    /* ===== Shadows ===== */
    --shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05);
    --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1);
    --shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1);
  }

  .dark {
    --background: 222.2 84% 4.9%;
    --foreground: 210 40% 98%;
    --primary: 217.2 91.2% 59.8%;
    /* ... dark mode overrides */
  }
}

Tailwind Config Extension

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: {
          50: 'hsl(var(--brand-50))',
          500: 'hsl(var(--brand-500))',
          900: 'hsl(var(--brand-900))',
        },
      },
      fontFamily: {
        sans: ['var(--font-sans)', 'system-ui'],
        mono: ['var(--font-mono)', 'monospace'],
      },
      spacing: {
        'xs': 'var(--spacing-xs)',
        'sm': 'var(--spacing-sm)',
        'md': 'var(--spacing-md)',
        'lg': 'var(--spacing-lg)',
        'xl': 'var(--spacing-xl)',
      },
      borderRadius: {
        'sm': 'var(--radius-sm)',
        'DEFAULT': 'var(--radius)',
        '