# WDS Design System Standards

**Version:** 1.0
**For:** Freya UX Designer Agent
**Purpose:** Complete reference for creating project design systems following WDS methodology

---

## 1. Atomic Design Methodology

Design systems are built using atomic design principles - organizing components by complexity.

### Hierarchy

```
Design Tokens (colors, typography, spacing)
  ↓
Atoms (basic building blocks)
  ↓
Molecules (simple combinations of atoms)
  ↓
Organisms (complex combinations of atoms + molecules)
  ↓
Patterns (page-level compositions)
```

### Atoms

**Definition:** Basic building blocks that cannot be broken down further without losing meaning.

**Examples:**
- Button
- Input field
- Icon
- Label
- Badge
- Avatar
- Link

**Characteristics:**
- Single-purpose elements
- No child components
- Highly reusable
- Configured through props

### Molecules

**Definition:** Simple combinations of atoms that work together as a unit.

**Examples:**
- Form Field (Label + Input + Helper text)
- Search Field (Input + Search icon + Clear button)
- Message Bubble (Avatar + Text + Timestamp)
- Nav Item (Icon + Label)
- Stat Card (Label + Value + Icon/Badge)

**Characteristics:**
- Combine 2-4 atoms
- Single functional purpose
- Reusable across contexts
- Document which atoms used (composition)

### Organisms

**Definition:** Complex components combining atoms and molecules into distinct sections.

**Examples:**
- Card (Header + Media + Content + Actions)
- Chat Interface (Header + Message Bubbles + Input Field)
- Navigation Header (Logo + Nav Items + User Menu)
- Modal (Overlay + Card + Actions)
- Data Table (Headers + Rows + Pagination)

**Characteristics:**
- Combine atoms + molecules
- Complex functionality
- Often context-specific
- Document complete composition tree

### Patterns

**Definition:** Page-level compositions and recurring design solutions.

**Examples:**
- Navigation patterns (header nav, sidebar nav, mobile menu)
- Form patterns (single-step, multi-step, inline validation)
- Layout patterns (dashboard, list-detail, content+sidebar)

**Characteristics:**
- Combine organisms
- Solve specific UX problems
- Context-dependent
- Document usage guidelines

---

## 2. Component Anatomy

Anatomy describes the structural parts that make up a component.

### Anatomy Documentation

Every component should document its anatomy:

**Example: Button Anatomy**

```
┌─────────────────────────────┐
│  [icon] Label Text [badge]  │  ← Container
└─────────────────────────────┘
     ↑        ↑         ↑
  Leading   Label   Trailing
   icon      text    element
```

**Parts:**
1. **Container** - Clickable surface (padding, background, border)
2. **Leading Icon** (optional) - Icon before label
3. **Label** (required) - Text describing action
4. **Trailing Element** (optional) - Icon, badge, or indicator after label

### Anatomy Standards

**Part Naming:**
- Use descriptive names (header, content, actions - not top, middle, bottom)
- Indicate optionality (required vs optional parts)
- Use consistent terminology across components

**Visual Representation:**
- Use ASCII diagrams for structure
- Label each part clearly
- Show hierarchy (container > children)

**Documentation:**
- List all parts
- Describe purpose of each
- Note which are required vs optional
- Include spacing between parts

---

## 3. Slots (Content Placeholders)

**Key Principle:** Structure is shared, content is page-specific.

### What Are Slots?

Slots are flexible content placeholders within components. The component defines WHERE content goes (slot architecture), but each page fills those slots with DIFFERENT content.

**Example: Button**

```yaml
# Component structure (shared):
Button:
  anatomy:
    - container
    - leadingIcon slot
    - label slot
    - trailingIcon slot

# Page 1 usage (content page-specific):
slots:
  label: "Download Report"
  leadingIcon: download-icon

# Page 2 usage (different content, same structure):
slots:
  label: "Submit"
  trailingIcon: arrow-right-icon
```

The button anatomy/structure never changes. Only the slot content changes per page.

### Slot Documentation Format

```markdown
## Slots

### 1. [Slot Name] (required/optional)
- **Type:** Text | Icon | Image | Component
- **Position:** [Where in anatomy]
- **Purpose:** [What it's for]
- **Examples:**
  - Page 1: [example content]
  - Page 2: [example content]
```

### Slot Naming Conventions

**Content Slots:**
- `label` - Primary text content
- `title` - Heading text
- `body` - Paragraph content
- `description` - Supporting text

**Media Slots:**
- `media` - Image, video, or chart area
- `icon` - Icon placeholder
- `avatar` - User image
- `thumbnail` - Preview image

**Positional Slots:**
- `leadingIcon` / `trailingIcon` - Icons before/after content
- `header` / `footer` - Top/bottom sections
- `actions` - Button/link area

**Complex Slots:**
- `children` - Default slot for nested content
- `items` - Array/list of content
- `[role]Content` - Role-specific content (e.g., `headerContent`)

### Slots vs Nested Components

**Slots:** Placeholders for content (text, icons, images)
**Nested Components:** When one component contains another component

Example - Card organism:
- **Slots:** title (text), body (text), media (image)
- **Nested Components:** contains Button atoms in actions area

---

## 4. Props (Configuration)

**Key Principle:** Props configure HOW a component looks and behaves (not WHAT content it shows).

### Props vs Slots

| Aspect | Props | Slots |
|--------|-------|-------|
| **Purpose** | Configure appearance/behavior | Fill with content |
| **Type** | Boolean, string, number, enum | Text, elements, components |
| **Example** | `size="large"`, `disabled=true` | `label="Submit"`, `icon=checkmark` |
| **Shared?** | Define available options | Content varies per usage |

### Standard Props

#### Visual Props
- `variant` - Visual style (primary, secondary, ghost, outlined, filled)
- `size` - Size variation (small, medium, large)
- `color` - Color theme (default, accent, success, warning, error)

#### State Props
- `disabled` - Boolean, disables interaction
- `loading` - Boolean, shows loading state
- `error` - Boolean, shows error state
- `active` - Boolean, active/selected state

#### Layout Props
- `fullWidth` - Boolean, expand to container width
- `padding` - Spacing inside component
- `margin` - Spacing outside component
- `alignment` - Text/content alignment

#### Behavior Props
- `onClick` - Function, click handler
- `onChange` - Function, change handler
- `placeholder` - String, placeholder text
- `required` - Boolean, required field

### Props Documentation Format

```markdown
## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| variant | 'primary' \| 'secondary' \| 'ghost' | 'primary' | Visual style |
| size | 'small' \| 'medium' \| 'large' | 'medium' | Component size |
| disabled | boolean | false | Disables interaction |
| fullWidth | boolean | false | Expand to container width |
```

---

## 5. States

Interactive states show how components respond to user interaction.

### Standard States

#### Default State
- Initial appearance
- No user interaction yet
- Resting state

#### Hover State
- Mouse over component
- Visual feedback (color shift, elevation)
- Indicates interactivity

#### Active/Pressed State
- User clicking/tapping
- Visual depression or color change
- Confirms interaction received

#### Focused State
- Keyboard focus
- Visible focus ring/outline
- Critical for accessibility

#### Disabled State
- Component non-interactive
- Reduced opacity/color
- Cursor: not-allowed
- No hover/active states

#### Loading State
- Async action in progress
- Spinner or skeleton
- Disabled interaction
- Indicates wait time

#### Error State
- Validation failure
- Red color, error icon
- Error message shown
- Highlights problem area

#### Success State
- Action completed successfully
- Green color, check icon
- Confirmation message
- Positive feedback

### State Documentation

```markdown
## States

### Default
- Background: [color]
- Text: [color]
- Border: [style]
- Elevation: [value]

### Hover
- Background: [color + overlay]
- Elevation: [increased]
- Cursor: pointer

### Active
- Background: [color + overlay]
- Elevation: [decreased]
- Scale: [slightly smaller]

### Disabled
- Background: [muted color]
- Text: [reduced opacity]
- Cursor: not-allowed
- No hover/active states
```

---

## 6. Variants

Variants are visual style variations of the same component.

### When to Create Variants

**Create variant when:**
- Visual style differs significantly
- Semantic meaning differs (primary vs secondary action)
- Context requires different emphasis

**Don't create variant when:**
- Only content changes (use slots instead)
- Only size changes (use size prop instead)
- Could be handled by props/states

### Standard Variant Types

#### Button Variants
- `primary` - Main actions (filled, high emphasis)
- `secondary` - Secondary actions (outlined, medium emphasis)
- `ghost` - Tertiary actions (text only, low emphasis)
- `text` - Minimal actions (no background)

#### Card Variants
- `elevated` - Shadow/elevation for depth
- `outlined` - Border, no shadow
- `filled` - Background color, no border/shadow

#### Alert/Badge Variants
- `info` - Informational (blue)
- `success` - Positive outcome (green)
- `warning` - Caution needed (yellow)
- `error` - Problem/failure (red)

### Variant Documentation

```markdown
## Variants

### Primary
- **Use:** Main call-to-action
- **Visual:** Filled background, brand color
- **Example:** "Submit", "Get Started", "Buy Now"

### Secondary
- **Use:** Secondary actions
- **Visual:** Outlined, no fill
- **Example:** "Cancel", "Learn More", "Back"

### Ghost
- **Use:** Tertiary/subtle actions
- **Visual:** No background or border, text only
- **Example:** "Skip", "Dismiss", "Not now"
```

---

## 7. Specifications

Technical measurements and implementation details.

### What to Specify

#### Dimensions
- Width (fixed, min, max, or fluid)
- Height (fixed, min, max, or auto)
- Aspect ratio (for media)

#### Spacing
- Padding (internal spacing)
- Margin (external spacing)
- Gap (space between child elements)

#### Typography
- Font family
- Font size
- Font weight
- Line height
- Letter spacing

#### Colors
- Background colors
- Text colors
- Border colors
- State color overlays

#### Borders
- Border width
- Border radius (corner rounding)
- Border style (solid, dashed, none)

#### Elevation
- Box shadow
- Z-index
- Layering order

### Specifications Documentation

```markdown
## Specifications

### Dimensions
- Min width: 64px
- Height: 40px (medium), 32px (small), 48px (large)
- Padding: 16px horizontal, 8px vertical

### Typography
- Font: Body-Medium
- Size: 14px
- Weight: 500
- Letter spacing: 0.1px

### Colors
- Background (primary): brand-500
- Text (primary): white
- Border: none
- Hover overlay: black 8% opacity

### Border
- Radius: 4px
- Width: 0px (no border for primary variant)

### Elevation
- Default: 0dp
- Hover: 2dp shadow
- Active: 0dp
```

---

## 8. Pattern Recognition (Freya's Workflow)

How Freya builds the design system incrementally during page design.

### Second-Occurrence Trigger

**Rule:** Document a component in the design system when it appears for the **second time** across pages.

**Rationale:**
- First occurrence: Might be one-off, wait and see
- Second occurrence: Pattern emerging, worth documenting
- Prevents premature abstraction

### Pattern Recognition Workflow

```
Page 1.1: Uses Button component
  → Freya: Notes first occurrence, continues

Page 1.2: Uses Button again (second occurrence)
  → Freya: "I've used 'Button' twice now. Should I document this in the design system?"
  → User: "Yes"
  → Freya: Creates atoms/button/ with complete documentation

Page 1.3: Uses Button + Card
  → Button: Already documented
  → Card: Second occurrence
  → Freya: "Card appears second time, adding to design system..."
  → Creates organisms/card/

Page 1.4: Uses Button + Card + Input
  → Button: Already documented
  → Card: Already documented
  → Input: Second occurrence
  → Freya: Documents Input component
```

### Component Classification

**Determining atom vs molecule vs organism:**

**Atom if:**
- Cannot be broken down further
- Single-purpose element
- No child components
- Examples: Button, Input, Icon, Label

**Molecule if:**
- Combines 2-4 atoms
- Simple functional unit
- Clear single purpose
- Examples: Form Field (Label + Input), Search Field (Input + Icon + Button)

**Organism if:**
- Combines atoms + molecules
- Complex functionality
- Multiple purposes/sections
- Examples: Card, Chat Interface, Navigation Header

**When uncertain:**
- Start with molecule
- Can promote to organism if complexity increases
- Better to start simpler, increase complexity as needed

### Incremental Documentation

**First documentation (second occurrence):**
- Create folder structure
- Document anatomy
- Document slots
- Document basic props/states
- Create 00-overview, 01-anatomy, 02-slots

**Subsequent occurrences:**
- Add new variants discovered
- Add new states observed
- Refine prop definitions
- Add usage examples
- Update existing files

### Documentation Checklist

When documenting a component on second occurrence:

- [ ] Create component folder (atoms/molecules/organisms/[component-name]/)
- [ ] Create 00-[name].md (overview)
- [ ] Create 01-anatomy.md (structural breakdown)
- [ ] Create 02-slots.md (content placeholders)
- [ ] Create 03-props.md or 03-composition.md
  - Atoms: props (configuration)
  - Molecules/Organisms: composition (which atoms/molecules used)
- [ ] Create 04-states.md (interactive states)
- [ ] Create 05-variants.md (visual variations)
- [ ] Create 06-specs.md (measurements) - if needed
- [ ] Update component index (04-components.md)

---

## 9. Component Documentation Template

### Atoms Template

```markdown
# [Component Name]

## Overview
[Brief description - what it is, primary purpose]

## Anatomy
[ASCII diagram showing structural parts]

**Parts:**
1. **[Part name]** (required/optional) - [Purpose]
2. **[Part name]** (required/optional) - [Purpose]

## Slots

### 1. [Slot Name] (required/optional)
- **Type:** [Text | Icon | Image | Component]
- **Position:** [Where in anatomy]
- **Purpose:** [What it's for]
- **Examples:**
  - [Example 1]
  - [Example 2]

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| [prop] | [type] | [default] | [description] |

## States

### [State Name]
- Background: [value]
- Text: [value]
- Border: [value]
- [Other properties]

## Variants

### [Variant Name]
- **Use:** [When to use]
- **Visual:** [How it looks]
- **Example:** [Example usage]

## Specifications

### Dimensions
- Width: [value]
- Height: [value]
- Padding: [value]

### Typography
- Font: [value]
- Size: [value]
- Weight: [value]

### Colors
- Background: [value]
- Text: [value]

### Border
- Radius: [value]
- Width: [value]

### Elevation
- Shadow: [value]
```

### Molecules/Organisms Template

Same as atoms template, but add:

```markdown
## Composition

This [molecule/organism] combines the following components:

### Atoms Used
| Atom | From | Role |
|------|------|------|
| [Component] | atoms/[name]/ | [Purpose in this molecule] |

### Molecules Used (organisms only)
| Molecule | From | Role |
|----------|------|------|
| [Component] | molecules/[name]/ | [Purpose in this organism] |

## Composition Diagram

```
┌─────────────────────────────────┐
│ [Molecule/Organism]             │
│  ├─ [Atom 1]                    │
│  ├─ [Atom 2]                    │
│  └─ [Molecule 1]                │
│      ├─ [Atom 3]                │
│      └─ [Atom 4]                │
└─────────────────────────────────┘
```
```

---

## 10. Complete Examples

### Example 1: Button (Atom)

**File:** `atoms/button/02-slots.md`

```markdown
# Button Slots

## Overview

Slots are content placeholders. Button structure is shared, content is page-specific.

## Slot Architecture

```
┌─────────────────────────────┐
│  [leadingIcon] [label] [trailingIcon]  │
└─────────────────────────────┘
      ↑           ↑          ↑
    Slot 1     Slot 2     Slot 3
```

## Available Slots

### 1. leadingIcon (optional)
- **Type:** Icon
- **Position:** Before label
- **Purpose:** Visual context for action
- **Examples:**
  - Download button: Download icon
  - Delete button: Trash icon
  - Submit button: Checkmark icon

### 2. label (required)
- **Type:** Text
- **Position:** Center
- **Purpose:** Describes the action
- **Examples:**
  - "Get Personalized Advice"
  - "Submit"
  - "Cancel"

### 3. trailingIcon (optional)
- **Type:** Icon or Badge
- **Position:** After label
- **Purpose:** Additional context
- **Examples:**
  - External link: Arrow-out icon
  - Loading: Spinner
  - Badge: Notification count

## Implementation

**Structure is shared:**
- Button anatomy (container, padding, border radius)
- States (hover, active, disabled)
- Visual style (colors, typography)

**Content is page-specific:**
- Each page fills slots with different content
- Same button component, different label/icons
```

---

### Example 2: Form Field (Molecule)

**File:** `molecules/form-field/03-composition.md`

```markdown
# Form Field Composition

## Overview

Form Field is a **molecule** that combines 3 atoms into a functional input unit.

## Composition Diagram

```
┌─────────────────────────────────┐
│ Form Field (molecule)           │
│  ├─ Label (atom)                │
│  ├─ Input (atom)                │
│  └─ Helper Text (atom)          │
└─────────────────────────────────┘
```

## Components Used

### Atoms
| Atom | From | Role |
|------|------|------|
| **Label** | `atoms/label/` | Field name, required indicator |
| **Input** | `atoms/input/` | Text entry field |
| **Helper Text** | `atoms/typography/` | Instructions or error messages |

## Composition Rules

1. **Label** is always above Input
2. **Helper Text** appears below Input
3. Spacing: 4px between Label and Input, 4px between Input and Helper
4. Error state: Helper Text turns red, Input gets red border

## Variants

### Standard
- Label + Input + Helper text (optional)

### Required
- Label + Required indicator (*) + Input + Helper text

### Error
- Label + Input (red border) + Error message (red)

### Disabled
- All atoms use disabled state
```

---

### Example 3: Card (Organism)

**File:** `organisms/card/02-slots.md`

```markdown
# Card Slots

## Overview

Card structure is reusable. Content filling each slot is page-specific.

## Slot Architecture

```
┌─────────────────────────────────┐
│ [header]                        │ ← Slot 1
├─────────────────────────────────┤
│ [media]                         │ ← Slot 2
├─────────────────────────────────┤
│ [title]                         │ ← Slot 3
│ [body]                          │ ← Slot 4
├─────────────────────────────────┤
│ [actions]                       │ ← Slot 5
└─────────────────────────────────┘
```

## Available Slots

### 1. header (optional)
- **Type:** Component (Avatar + Title + Subtitle + Menu)
- **Content Examples:**
  - User profile: Avatar, "John Doe", "2 hours ago"
  - Article card: Category badge, "Investments", "5 min read"

### 2. media (optional)
- **Type:** Image, Chart, or Video
- **Content Examples:**
  - Portfolio card: Performance chart
  - Article card: Hero image

### 3. title (required)
- **Type:** Text (Headline)
- **Content Examples:**
  - "Your Recommended Allocation"
  - "Getting Started with Investing"

### 4. body (optional)
- **Type:** Text (Paragraph)
- **Content Examples:**
  - "Based on your goals, we recommend..."
  - "Learn the fundamentals..."

### 5. actions (optional)
- **Type:** Buttons
- **Content Examples:**
  - Single: ["Learn More"]
  - Dual: ["Dismiss", "View Details"]

## Key Principle

**Shared:**
- Card anatomy (container, spacing, elevation)
- Visual style (colors, borders, shadows)
- Behavior (clickable, states)

**Page-Specific:**
- Content filling each slot
- Which slots are used
- How actions behave
```

---

## Summary

### Core Principles

1. **Atomic Design** - Organize by complexity (atoms → molecules → organisms)
2. **Anatomy** - Document structural parts clearly
3. **Slots** - Structure shared, content page-specific
4. **Props** - Configure appearance/behavior
5. **States** - Document all interactive states
6. **Variants** - Visual style variations
7. **Specifications** - Technical measurements
8. **Pattern Recognition** - Second occurrence triggers documentation
9. **Templates** - Use consistent documentation format
10. **Examples** - Learn from complete examples

### For Freya

**When designing pages:**
- Use components from existing design system
- Track component usage
- On second occurrence → ask to document
- Classify as atom/molecule/organism
- Document comprehensively using templates
- Extract design tokens (colors, typography, spacing)
- Build design system incrementally as patterns emerge

**Goal:** Every project gets a complete, well-documented design system that grows naturally from the actual page designs created.

---

**End of WDS Design System Standards**