917 lines
23 KiB
Markdown
917 lines
23 KiB
Markdown
# Phase 5: Design System (Component Library)
|
|
|
|
**Agent:** Baldr the UX Expert
|
|
**Output:** `D-Design-System/` (or your configured prefix)
|
|
|
|
---
|
|
|
|
## What This Phase Does
|
|
|
|
Design System builds your component library following atomic design principles. Working with Baldr, you create reusable patterns that serve user psychology and ensure visual consistency.
|
|
|
|
**The key approach:** The design system grows **alongside** Phase 4 work. As you sketch and specify pages, you simultaneously extract and document components. By the time your scenarios are complete, your design system is already built.
|
|
|
|
---
|
|
|
|
## What You'll Create
|
|
|
|
Your Design System includes:
|
|
|
|
- **Visual Design (01-Visual-Design/)** - Early design exploration before scenarios
|
|
- Mood boards and style direction
|
|
- NanoBanana design concepts
|
|
- Color and typography exploration
|
|
- Visual inspiration and references
|
|
- **Assets (02-Assets/)** - Final production assets
|
|
- Logos and brand elements
|
|
- Icon sets
|
|
- Photography and illustrations
|
|
- Custom graphics
|
|
- **Design Tokens** - Colors, typography, spacing, shadows
|
|
- **Atomic Components** - Buttons, inputs, labels, icons
|
|
- **Molecular Components** - Form groups, cards, list items
|
|
- **Organism Components** - Headers, footers, complex sections
|
|
- **Usage Guidelines** - When and how to use each component
|
|
- **Component Variants** - Different states and sizes
|
|
|
|
---
|
|
|
|
## Atomic Design Structure
|
|
|
|
Following Brad Frost's methodology:
|
|
|
|
### Foundation (Design Tokens)
|
|
|
|
The values everything else builds on:
|
|
|
|
- **Colors** - Primary, secondary, semantic (success, error, warning)
|
|
- **Typography** - Font families, sizes, weights, line heights
|
|
- **Spacing** - Consistent spacing scale
|
|
- **Shadows** - Elevation levels
|
|
- **Borders** - Radius and stroke styles
|
|
- **Breakpoints** - Responsive design points
|
|
|
|
### Atoms
|
|
|
|
The smallest building blocks:
|
|
|
|
- Buttons
|
|
- Input fields
|
|
- Labels
|
|
- Icons
|
|
- Badges
|
|
- Dividers
|
|
|
|
### Molecules
|
|
|
|
Groups of atoms working together:
|
|
|
|
- Form groups (label + input + error)
|
|
- Search bars (input + button)
|
|
- Card headers (title + action)
|
|
- Navigation items (icon + label)
|
|
|
|
### Organisms
|
|
|
|
Complex components made of molecules:
|
|
|
|
- Page headers
|
|
- Navigation bars
|
|
- Form sections
|
|
- Card layouts
|
|
- List views
|
|
|
|
---
|
|
|
|
## How It Works
|
|
|
|
### The Parallel Workflow
|
|
|
|
Phase 5 isn't a separate phase you do _after_ Phase 4 - it happens **during** Phase 4:
|
|
|
|
```
|
|
Phase 4 Page Design → Phase 5 Design System
|
|
───────────────── ─────────────────
|
|
Sketch button for Page 1.1 → Create "Primary Button" atom
|
|
Reuse button on Page 1.2 → Reference existing atom
|
|
Sketch input for Page 2.1 → Create "Text Input" atom
|
|
Create form on Page 2.2 → Create "Form Group" molecule
|
|
Notice pattern across pages → Extract as reusable component
|
|
```
|
|
|
|
**The rhythm:**
|
|
|
|
1. Design a page/component in Phase 4
|
|
2. Notice "This could be reusable"
|
|
3. Extract to Design System
|
|
4. Next page references the system component
|
|
5. Repeat
|
|
|
|
### Visual Design Exploration (01-Visual-Design/)
|
|
|
|
**Independent Design Phase - Can Start Anytime:**
|
|
|
|
**Key Insight:** Brand identity and visual design are NOT tied to the product! You can establish your visual identity at any time - before, during, or after product strategy work.
|
|
|
|
**Purpose:** Establish the visual language that will tie UX to Brand. This is where you define how your brand's personality will be expressed visually across all touchpoints.
|
|
|
|
**Timing Options:**
|
|
- **Before product work:** Establish brand identity first, then build products around it
|
|
- **Parallel to strategy:** Develop visual identity while defining product strategy
|
|
- **After strategy:** Use strategic insights to inform visual direction
|
|
|
|
Before diving into scenario-specific design (Phase 4), establish your visual direction:
|
|
|
|
**Mood Boards:**
|
|
- Collect visual inspiration
|
|
- Define style direction (modern, playful, professional, etc.)
|
|
- Establish visual tone and personality
|
|
- Reference examples from similar products
|
|
|
|
**Design Concepts (NanoBanana):**
|
|
- Generate design variations using NanoBanana
|
|
- Explore different visual approaches
|
|
- Create custom graphics and illustrations
|
|
- Generate placeholder assets for prototypes
|
|
|
|
**Color Exploration:**
|
|
- Test color palette options
|
|
- Define primary, secondary, and semantic colors
|
|
- Ensure accessibility (contrast ratios)
|
|
- Document color psychology and usage
|
|
|
|
**Typography Tests:**
|
|
- Experiment with font pairings
|
|
- Define hierarchy (headings, body, labels)
|
|
- Test readability at different sizes
|
|
- Document font usage guidelines
|
|
|
|
**When to Use:**
|
|
- **AFTER Phase 1 & 2** (Product Brief and Trigger Map must be complete first!)
|
|
- When establishing brand identity (with strategic context)
|
|
- When exploring multiple visual directions (informed by user psychology)
|
|
- Before committing to design tokens
|
|
- Before Phase 4 scenarios (but after strategic foundation)
|
|
|
|
**Output Location:** `D-Design-System/01-Visual-Design/`
|
|
|
|
---
|
|
|
|
### Production Assets (02-Assets/)
|
|
|
|
**Later in Design Process - As Design Solidifies:**
|
|
|
|
Once your visual direction is established and scenarios are designed:
|
|
|
|
**Logos:**
|
|
- Final logo files (SVG, PNG)
|
|
- Logo variations (light/dark, horizontal/vertical)
|
|
- Brand mark and wordmark
|
|
- Usage guidelines
|
|
|
|
**Icons:**
|
|
- Icon sets for UI elements
|
|
- Custom icons for product features
|
|
- Consistent style and sizing
|
|
- Multiple formats (SVG, PNG)
|
|
|
|
**Images:**
|
|
- Photography for product pages
|
|
- Illustrations for empty states
|
|
- Hero images and backgrounds
|
|
- Optimized for web
|
|
|
|
**Graphics:**
|
|
- Custom graphics and elements
|
|
- Decorative elements
|
|
- Patterns and textures
|
|
- Exported from NanoBanana or Figma
|
|
|
|
**When to Add:**
|
|
- After visual direction is established
|
|
- When design is near completion
|
|
- Before development handoff
|
|
- As final assets are created
|
|
|
|
**Output Location:** `D-Design-System/02-Assets/`
|
|
|
|
---
|
|
|
|
### Figma Integration (Optional)
|
|
|
|
**Automated Visual Refinement:**
|
|
|
|
WDS supports automated Figma integration via MCP server for visual design refinement:
|
|
|
|
**Workflow:**
|
|
1. Create functional prototype in Phase 4D
|
|
2. Freya identifies components needing visual polish
|
|
3. Freya injects components to Figma automatically (via MCP server)
|
|
4. Designer refines visual design in Figma
|
|
5. Freya reads refined components back automatically
|
|
6. Design system updated with new tokens/components
|
|
7. Prototype re-rendered with polished design
|
|
|
|
**Benefits:**
|
|
- Build design system organically (no upfront investment)
|
|
- Component-level precision (not full-page extraction)
|
|
- Automated Object ID traceability
|
|
- Bidirectional sync (Prototype ↔ Figma ↔ Design System)
|
|
|
|
**Tools:**
|
|
- **Figma MCP** (recommended): Automated integration via MCP server
|
|
- **Figma**: Visual design tool for refinement
|
|
- See: [Figma Integration Guide](../src/workflows/5-design-system/figma-integration/prototype-to-figma-workflow.md)
|
|
|
|
---
|
|
|
|
### Component Extraction
|
|
|
|
As you specify scenarios in Phase 4, components naturally emerge:
|
|
|
|
1. **Identify patterns** - "This button style appears in multiple places"
|
|
2. **Extract to system** - Document the component with all variants
|
|
3. **Reference in specs** - Link scenario specs to system components
|
|
|
|
---
|
|
|
|
## Creating Your Design System Documentation
|
|
|
|
### The Extraction Process
|
|
|
|
**Step 1: Spot the Pattern**
|
|
|
|
While working on Phase 4 scenarios, notice when you're designing something reusable:
|
|
|
|
- "I just designed this button for Page 1.1... and I need it again on Page 1.2"
|
|
- "This form input pattern will be used everywhere"
|
|
- "We have 3 different card layouts, but they share the same structure"
|
|
|
|
**Step 2: Create the Component Document**
|
|
|
|
In your `D-Design-System/` folder, create a component file:
|
|
|
|
```
|
|
D-Design-System/
|
|
├── 01-design-tokens.md
|
|
├── 02-atoms/
|
|
│ ├── primary-button.md ← Create this
|
|
│ ├── text-input.md
|
|
│ └── ...
|
|
├── 03-molecules/
|
|
│ └── form-group.md
|
|
└── 04-organisms/
|
|
└── page-header.md
|
|
```
|
|
|
|
**Step 3: Document the Component**
|
|
|
|
Use this template for each component:
|
|
|
|
````markdown
|
|
# Primary Button
|
|
|
|
## Overview
|
|
|
|
The primary button is used for the main call-to-action on any page or section.
|
|
|
|
## Component Details
|
|
|
|
**Category:** Atom
|
|
**Object ID Pattern:** `*-primary-button`
|
|
**Component Library:** [If using one, e.g., "Chakra UI Button"]
|
|
**Figma Component:** Primary Button
|
|
|
|
## Variants
|
|
|
|
### Size
|
|
|
|
- **Small:** Compact spaces, secondary actions
|
|
- **Medium:** Default size for most use cases
|
|
- **Large:** Hero sections, important CTAs
|
|
|
|
### State
|
|
|
|
- **Default:** Ready for interaction
|
|
- **Hover:** Visual feedback on mouse over
|
|
- **Active:** Currently being clicked
|
|
- **Disabled:** Action not available
|
|
- **Loading:** Processing user action
|
|
|
|
## Visual Specifications
|
|
|
|
**Design Tokens:**
|
|
|
|
- Background: `color-primary-500`
|
|
- Text: `color-white`
|
|
- Border Radius: `radius-md`
|
|
- Padding: `spacing-3` (vertical), `spacing-6` (horizontal)
|
|
- Font: `font-semibold`, `text-base`
|
|
|
|
**States:**
|
|
|
|
- Hover: `color-primary-600`
|
|
- Active: `color-primary-700`
|
|
- Disabled: `color-gray-300`, opacity 50%
|
|
|
|
## Usage Guidelines
|
|
|
|
**When to use:**
|
|
|
|
- Primary action on a page or modal
|
|
- Main CTA in hero sections
|
|
- Form submissions
|
|
- Confirmation actions
|
|
|
|
**When NOT to use:**
|
|
|
|
- Multiple primary actions (use secondary instead)
|
|
- Destructive actions (use danger variant)
|
|
- Navigation (use links or secondary buttons)
|
|
|
|
## Accessibility
|
|
|
|
- Minimum contrast ratio: 4.5:1
|
|
- Keyboard accessible (Enter/Space)
|
|
- Focus visible indicator
|
|
- ARIA label when icon-only
|
|
|
|
## Example Usage
|
|
|
|
**In specifications:**
|
|
|
|
```markdown
|
|
### Submit Button
|
|
|
|
**Object ID:** `contact-form-submit-button`
|
|
**Component:** primary-button
|
|
**Variant:** size=large
|
|
**State:** default → loading → success
|
|
```
|
|
````
|
|
|
|
**In Figma:**
|
|
Use "Primary Button" component from library
|
|
|
|
**In Code (if using Chakra):**
|
|
|
|
```jsx
|
|
<Button colorScheme="blue" size="lg">
|
|
Submit
|
|
</Button>
|
|
```
|
|
|
|
## Used In
|
|
|
|
- 1.1-Start-Page: Hero CTA
|
|
- 1.2-Sign-Up: Submit registration
|
|
- 2.1-Contact-Form: Send message
|
|
- [Update as you use the component]
|
|
|
|
```
|
|
|
|
**Step 4: Update as You Go**
|
|
|
|
Each time you use this component in a new scenario:
|
|
1. Add it to the "Used In" section
|
|
2. Note any new variants discovered
|
|
3. Update specifications if the component evolves
|
|
|
|
### Interactive Component Gathering
|
|
|
|
**As you work through Phase 4:**
|
|
|
|
```
|
|
|
|
Design Page 1.1
|
|
↓
|
|
Notice: "This button is reusable"
|
|
↓
|
|
Create: primary-button.md in Design System
|
|
↓
|
|
Reference in 1.1 spec: component=primary-button
|
|
↓
|
|
Design Page 1.2
|
|
↓
|
|
Need same button: Reference existing component
|
|
↓
|
|
Design Page 2.1
|
|
↓
|
|
Need slightly different: Add variant to component doc
|
|
↓
|
|
Update all references with new variant option
|
|
|
|
```
|
|
|
|
---
|
|
|
|
## Interactive HTML Component Showcase
|
|
|
|
Beyond documentation, create an **interactive HTML guide** where stakeholders and developers can see and interact with all components.
|
|
|
|
### Structure
|
|
|
|
```
|
|
|
|
D-Design-System/
|
|
├── component-showcase.html ← Interactive guide
|
|
├── component-showcase.css
|
|
├── component-showcase.js
|
|
├── 01-design-tokens.md
|
|
├── 02-atoms/
|
|
│ ├── primary-button.md
|
|
│ └── ...
|
|
|
|
````
|
|
|
|
### What the Showcase Includes
|
|
|
|
**For each component:**
|
|
1. **Live rendered examples** - See the actual component
|
|
2. **All variants** - Size, state, and style options
|
|
3. **Interactive states** - Hover, click, focus to see behavior
|
|
4. **Visual specifications** - Design tokens, spacing, colors used
|
|
5. **Usage notes** - When to use this component
|
|
|
|
### Building the Showcase
|
|
|
|
**As you document each component:**
|
|
|
|
1. **Add to showcase HTML** - Create a card with live examples
|
|
2. **Show all variants** - Size, state, visual options
|
|
3. **Make it interactive** - Buttons click, inputs accept text, states change
|
|
4. **Display tokens** - Show the actual colors, fonts, spacing
|
|
5. **Keep it synced** - Update when components evolve
|
|
|
|
**Use the provided templates:**
|
|
|
|
Find ready-to-use templates in:
|
|
- `reference/templates/component-showcase-template.html`
|
|
- `reference/templates/component-card-template.html`
|
|
|
|
See complete examples in:
|
|
- `examples/dog-week-patterns/D-Design-System/component-showcase.html`
|
|
|
|
### Benefits
|
|
|
|
**For Designers:**
|
|
- Visual inventory of all components
|
|
- See components in isolation
|
|
- Test interactions and states
|
|
- Share with stakeholders for feedback
|
|
|
|
**For Developers:**
|
|
- Visual reference for implementation
|
|
- Understand variant options
|
|
- See all states and interactions
|
|
- Check responsive behavior
|
|
|
|
**For Stakeholders:**
|
|
- See the design language
|
|
- Review consistency
|
|
- Experience interactive components
|
|
- Provide informed feedback
|
|
|
|
**For QA:**
|
|
- Test all component states
|
|
- Verify accessibility
|
|
- Check responsive behavior
|
|
- Document expected behavior
|
|
|
|
### Maintaining the Showcase
|
|
|
|
**Keep it current:**
|
|
- Add new components as they're documented
|
|
- Update when variants change
|
|
- Remove deprecated components
|
|
- Sync with Figma library updates
|
|
|
|
**Single source of truth:**
|
|
- Markdown docs = specifications and usage
|
|
- HTML showcase = visual reference and interaction
|
|
- Figma = design source
|
|
- Code = implementation
|
|
|
|
All four should stay aligned.
|
|
|
|
---
|
|
|
|
## Component Documentation
|
|
|
|
Each component includes:
|
|
|
|
**Purpose & Usage**
|
|
- When to use this component
|
|
- When NOT to use it
|
|
- Psychological intent (connects to Trigger Map)
|
|
|
|
**Variants**
|
|
- Size options (small, medium, large)
|
|
- State options (default, hover, active, disabled)
|
|
- Visual variants (primary, secondary, ghost)
|
|
|
|
**Specifications**
|
|
- Design tokens used
|
|
- Spacing and sizing
|
|
- Responsive behavior
|
|
|
|
**Implementation Notes**
|
|
- Technical guidance for developers
|
|
- Accessibility requirements
|
|
- Animation/interaction details
|
|
|
|
---
|
|
|
|
## Choosing a Component Library
|
|
|
|
### Build vs. Use Existing
|
|
|
|
**Build your own Design System when:**
|
|
- Unique brand identity required
|
|
- Custom interactions not available in libraries
|
|
- Full control over every detail needed
|
|
- Have design resources to maintain system
|
|
|
|
**Use existing component library when:**
|
|
- Fast time to market
|
|
- Standard UI patterns sufficient
|
|
- Limited design resources
|
|
- Want battle-tested accessibility
|
|
|
|
**WDS supports both approaches** - you can document either custom components or library components using the same structure.
|
|
|
|
---
|
|
|
|
## Recommended Component Libraries
|
|
|
|
These libraries work well with WDS's specification approach:
|
|
|
|
### React Ecosystem
|
|
|
|
**Shadcn/ui** (Recommended for flexibility)
|
|
- Not a library, but a collection of copy-paste components
|
|
- Built on Radix UI primitives (excellent accessibility)
|
|
- [ui.shadcn.com](https://ui.shadcn.com)
|
|
|
|
*Pros:*
|
|
- Full component ownership - code lives in your repo
|
|
- Easy to customize without fighting library constraints
|
|
- No package bloat or version conflicts
|
|
- Perfect for WDS documentation (you own the code)
|
|
|
|
*Cons:*
|
|
- Manual updates when new versions release
|
|
- Need to maintain copied code yourself
|
|
- Requires understanding of component internals
|
|
|
|
---
|
|
|
|
**Chakra UI** (Recommended for speed)
|
|
- Comprehensive component library
|
|
- Excellent TypeScript support
|
|
- Built-in dark mode and theming
|
|
- [chakra-ui.com](https://chakra-ui.com)
|
|
|
|
*Pros:*
|
|
- Fast to get started - works out of the box
|
|
- Excellent accessibility defaults
|
|
- Great developer experience
|
|
- Active community and good documentation
|
|
|
|
*Cons:*
|
|
- Less control over internals
|
|
- Can be opinionated about styling approach
|
|
- Larger bundle size than headless options
|
|
|
|
---
|
|
|
|
**Radix UI** (Recommended for headless)
|
|
- Unstyled, accessible components
|
|
- Complete control over styling
|
|
- Composable primitives
|
|
- [radix-ui.com](https://radix-ui.com)
|
|
|
|
*Pros:*
|
|
- Best-in-class accessibility built-in
|
|
- Total styling freedom
|
|
- Small bundle size (only import what you need)
|
|
- No design opinions forced on you
|
|
|
|
*Cons:*
|
|
- Requires you to style everything yourself
|
|
- Steeper learning curve than styled libraries
|
|
- More initial setup work
|
|
|
|
---
|
|
|
|
**Material UI (MUI)**
|
|
- Mature, comprehensive library
|
|
- Material Design by default (can customize)
|
|
- Large ecosystem of additional packages
|
|
- [mui.com](https://mui.com)
|
|
|
|
*Pros:*
|
|
- Battle-tested with large community
|
|
- Very comprehensive component set
|
|
- Good documentation and examples
|
|
- Material Design is familiar to users
|
|
|
|
*Cons:*
|
|
- Heavy bundle size
|
|
- Material Design aesthetic hard to override
|
|
- Can feel dated for modern designs
|
|
- Customization can be complex
|
|
|
|
### Vue Ecosystem
|
|
|
|
**Nuxt UI**
|
|
- Built for Nuxt/Vue 3
|
|
- Modern, fast, accessible
|
|
- [ui.nuxt.com](https://ui.nuxt.com)
|
|
|
|
*Pros:*
|
|
- Optimized specifically for Nuxt
|
|
- Modern design aesthetics
|
|
- Good performance
|
|
- Growing ecosystem
|
|
|
|
*Cons:*
|
|
- Nuxt-specific (not for plain Vue)
|
|
- Younger library with smaller community
|
|
- Less comprehensive than mature alternatives
|
|
|
|
---
|
|
|
|
**PrimeVue**
|
|
- Rich component set
|
|
- Multiple themes available
|
|
- Enterprise-focused
|
|
- [primevue.org](https://primevue.org)
|
|
|
|
*Pros:*
|
|
- Very comprehensive component library
|
|
- Multiple pre-built themes
|
|
- Good for complex enterprise UIs
|
|
- Active development
|
|
|
|
*Cons:*
|
|
- Can feel corporate/dated
|
|
- Larger bundle size
|
|
- Theme customization can be complex
|
|
|
|
### Framework-Agnostic
|
|
|
|
**Tailwind CSS** (Recommended for design freedom)
|
|
- Utility-first CSS framework
|
|
- Combine with headless components
|
|
- Maximum flexibility
|
|
- [tailwindcss.com](https://tailwindcss.com)
|
|
|
|
*Pros:*
|
|
- Complete design freedom
|
|
- Small production bundle (unused styles purged)
|
|
- Fast prototyping with utility classes
|
|
- Pairs perfectly with WDS specifications
|
|
|
|
*Cons:*
|
|
- Not a component library (need to build or combine)
|
|
- HTML can get verbose
|
|
- Learning curve for utility-first approach
|
|
- Need separate component primitives (e.g., Radix)
|
|
|
|
### Selection Criteria
|
|
|
|
**Choose based on:**
|
|
|
|
| Priority | Consider |
|
|
|----------|----------|
|
|
| **Speed** | Chakra UI, MUI, PrimeVue (ready-to-use) |
|
|
| **Customization** | Shadcn/ui, Radix UI, Tailwind (full control) |
|
|
| **Accessibility** | Radix UI, Chakra UI (built-in a11y) |
|
|
| **Design System** | Shadcn/ui, custom components (full documentation) |
|
|
| **Team Familiarity** | What your dev team already knows |
|
|
|
|
### WDS Integration Pattern
|
|
|
|
**With existing library:**
|
|
1. Document library components in your WDS Design System
|
|
2. Reference library component names in specifications
|
|
3. Add project-specific variants/customizations
|
|
4. Maintain consistency across your product
|
|
|
|
**Example WDS entry for library component:**
|
|
```markdown
|
|
## Primary Button
|
|
|
|
**Library Component:** Chakra UI Button
|
|
**Import:** `import { Button } from '@chakra-ui/react'`
|
|
|
|
**Usage in WDS:**
|
|
- Object ID suffix: `-primary-button`
|
|
- Figma Component: Primary Button
|
|
- Props: `colorScheme="blue" size="lg"`
|
|
|
|
**Variants:**
|
|
- Default: `variant="solid"`
|
|
- Secondary: `variant="outline"`
|
|
- Ghost: `variant="ghost"`
|
|
|
|
**When to use:**
|
|
Primary call-to-action buttons...
|
|
````
|
|
|
|
---
|
|
|
|
## Design Application Integration
|
|
|
|
Your WDS component system connects to your visual design tools (Figma, Sketch, Adobe XD):
|
|
|
|
### Unified Naming Convention
|
|
|
|
**Use the exact same names across all tools:**
|
|
|
|
| WDS Component Name | Figma Component | Code Component | Object ID |
|
|
| ------------------ | --------------- | --------------- | ------------------ |
|
|
| `primary-button` | Primary Button | `PrimaryButton` | `*-primary-button` |
|
|
| `text-input` | Text Input | `TextInput` | `*-text-input` |
|
|
| `form-group` | Form Group | `FormGroup` | `*-form-group` |
|
|
|
|
### The Workflow
|
|
|
|
```
|
|
WDS Specification → Figma Design → Code Implementation
|
|
───────────────── ───────── ──────────────────
|
|
1. Document 2. Create 3. Build with
|
|
"primary-button" component same name
|
|
in Design System in Figma in code
|
|
|
|
Object IDs reference the same names:
|
|
signin-form-submit-primary-button (everywhere)
|
|
```
|
|
|
|
### Figma/Design Tool Setup
|
|
|
|
**Component Library Structure:**
|
|
|
|
Match your WDS atomic design structure:
|
|
|
|
```
|
|
Design File/
|
|
├── 🎨 Design Tokens
|
|
│ ├── Colors
|
|
│ ├── Typography
|
|
│ └── Spacing
|
|
├── ⚛️ Atoms
|
|
│ ├── primary-button
|
|
│ ├── text-input
|
|
│ └── ...
|
|
├── 🧬 Molecules
|
|
│ ├── form-group
|
|
│ ├── search-bar
|
|
│ └── ...
|
|
└── 🧩 Organisms
|
|
├── page-header
|
|
└── ...
|
|
```
|
|
|
|
**Naming in Figma:**
|
|
|
|
- Component names match WDS names (kebab-case or Title Case)
|
|
- Variants match WDS variants (Primary, Secondary, Disabled)
|
|
- Properties match WDS states (default, hover, active, error)
|
|
|
|
### Benefits of Unified Naming
|
|
|
|
- **Designers:** Find components easily in Figma library
|
|
- **Developers:** No translation needed from design to code
|
|
- **Testers:** Object IDs make sense and are predictable
|
|
- **Documentation:** Single source of truth for naming
|
|
- **Handoff:** Zero ambiguity about which component to use
|
|
|
|
### When You Design in Figma
|
|
|
|
1. **Reference your WDS Design System** for component names and structure
|
|
2. **Create visual designs** using those exact names
|
|
3. **Export/handoff** with matching naming to developers
|
|
4. **Specifications remain in WDS** - Figma provides the pixels, WDS provides the logic
|
|
|
|
---
|
|
|
|
## Growing the System
|
|
|
|
The design system is living documentation that grows with your product:
|
|
|
|
### Starting Point
|
|
|
|
Begin with what you need for current scenarios:
|
|
|
|
- Extract components from Phase 4 work
|
|
- Document only what you're actually using
|
|
- Avoid speculating about future needs
|
|
|
|
### Evolution
|
|
|
|
As you design more scenarios:
|
|
|
|
- New patterns emerge → add to system
|
|
- Inconsistencies appear → consolidate
|
|
- Components evolve → update documentation
|
|
|
|
### Maintenance
|
|
|
|
- Keep specs in sync with implementation
|
|
- Remove unused components
|
|
- Update when design language evolves
|
|
|
|
---
|
|
|
|
## When to Use This Phase
|
|
|
|
**Enable Design System phase if:**
|
|
|
|
- Building reusable component library
|
|
- Multiple pages/scenarios with shared patterns
|
|
- Need design consistency across product
|
|
- Handoff requires component documentation
|
|
|
|
**Work in parallel with Phase 4 when enabled:**
|
|
|
|
- As you sketch, identify component patterns
|
|
- As you specify, extract to Design System
|
|
- Design System grows with each page completed
|
|
- No separate "design system phase" at the end
|
|
|
|
**Skip this phase if:**
|
|
|
|
- Small project (single landing page)
|
|
- Using existing design system (Material, Chakra, etc.)
|
|
- One-off designs without reuse
|
|
- Quick prototype or MVP without component library needs
|
|
|
|
**Dedicated consolidation when:**
|
|
|
|
- Multiple scenarios complete, need cleanup
|
|
- Preparing for development handoff
|
|
- Found inconsistencies to resolve
|
|
- Onboarding new team members
|
|
|
|
> **Note:** You'll choose whether to enable the Design System phase during project setup (`workflow-init`). This decision can be revisited as your project grows.
|
|
|
|
---
|
|
|
|
## What to Prepare
|
|
|
|
Bring:
|
|
|
|
- Completed or in-progress scenario specs (Phase 4)
|
|
- Any existing brand guidelines
|
|
- Technical framework constraints (React components, etc.)
|
|
|
|
---
|
|
|
|
## What Comes Next
|
|
|
|
Your Design System enables:
|
|
|
|
- **Consistent implementation** - Developers build from clear specs
|
|
- **Faster design** - Reuse components across scenarios
|
|
- **Phase 6 handoff** - Complete component inventory
|
|
|
|
---
|
|
|
|
## Tips for Great Sessions
|
|
|
|
**Extract, don't invent**
|
|
|
|
- Components should come from real design needs
|
|
- Don't create components "just in case"
|
|
- Let the system grow from actual scenarios
|
|
|
|
**Document the why**
|
|
|
|
- Why does this button look this way?
|
|
- What user trigger does it serve?
|
|
- When should developers use variant A vs B?
|
|
|
|
**Stay consistent**
|
|
|
|
- Same component = same specification
|
|
- Variations should be intentional
|
|
- When in doubt, simplify
|
|
|
|
**Connect to psychology**
|
|
|
|
- Every design choice serves a purpose
|
|
- Reference your Trigger Map
|
|
- Components should feel intentional, not arbitrary
|
|
|
|
---
|
|
|
|
## Example Output
|
|
|
|
See: `examples/dog-week-patterns/D-Design-System/` for a complete Design System from a real project.
|
|
|
|
---
|
|
|
|
_Phase 5 of the Whiteport Design Studio method_
|