WDS Design System Guide

Standards for Building Scalable, Consistent Component Libraries

1. Atomic Design Methodology

Components are organized in three levels of complexity, inspired by atomic design principles:

⚛️ Atoms

Basic building blocks

Button
Input
Icon
Label
Avatar

🔗 Molecules

Combinations of atoms

Search Bar (Input + Button)
Form Field (Label + Input)
Card (Image + Text + Button)
Menu Item (Icon + Label)

🏗️ Organisms

Complex components

Navigation Bar
Hero Section
Product Grid
Footer

Example: Building a Card Component

Atoms used: Image, Heading, Paragraph, Button, Icon

Classification: Molecule (combines multiple atoms)

Can be used in: Organism (e.g., Product Grid contains multiple Cards)

2. Component Anatomy

Every component is broken down into its structural parts.

Button Anatomy Example

Container

Icon (optional)

Label

Anatomy Documentation Format:

## Anatomy

**Parts:**
1. **Container** - The button's outer wrapper
2. **Icon** (optional) - Leading or trailing icon
3. **Label** - The button text
4. **Loading Indicator** (optional) - Replaces icon during loading state

3. Slots (Content Placeholders)

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

Slots define where content goes, not what the content is.

Card Component Slots Example

[title slot]

[description slot]

Structure (shared)

Premium Plan

Unlock all features

Content (page-specific)

Slots Documentation Format:

## Slots

1. **image** - Visual content (photo, illustration, icon)
2. **title** - Main heading
3. **description** - Supporting text
4. **action** - Call-to-action button

4. Props (Configuration Options)

Props control how a component looks and behaves.

Button Props Example

Prop	Type	Options	Default
`variant`	string	primary \| secondary \| ghost	primary
`size`	string	small \| medium \| large	medium
`disabled`	boolean	true \| false	false
`fullWidth`	boolean	true \| false	false

Props Documentation Format:

## Props

| Prop | Type | Options | Default | Description |
|------|------|---------|---------|-------------|
| variant | string | primary, secondary, ghost | primary | Visual style |
| size | string | small, medium, large | medium | Button size |
| disabled | boolean | true, false | false | Disable interactions |
| fullWidth | boolean | true, false | false | Stretch to container width |

5. States (Interactive Behavior)

States define how components respond to user interaction.

Button States Example

Default - Idle state

Hover - Mouse over

Disabled - Not interactive

Loading - Processing

Common States:

default - Idle/resting state
hover - Mouse/pointer over component
active - Currently pressed/clicked
focus - Keyboard focus (accessibility)
disabled - Not interactive
loading - Awaiting response
error - Invalid/failed state
success - Completed successfully

6. Variants (Visual Styles)

Variants are different visual styles of the same component structure.

Button Variants Example

Primary - Main actions

Secondary - Less emphasis

Ghost - Minimal style

When to Create Variants

Same structure, different appearance

✅ Primary vs Secondary button (same anatomy, different colors)
✅ Card with shadow vs Card without shadow
✅ Input with border vs Input with underline only

Different structure = Different component

❌ Button with icon vs Button without icon → Use props/slots
❌ Horizontal nav vs Vertical nav → Separate components

7. Specifications (Technical Measurements)

Precise measurements for implementation.

Button Specifications Example

Property	Small	Medium	Large
Height	32px	40px	48px
Padding (horizontal)	12px	16px	24px
Font Size	14px	16px	18px
Border Radius	4px	6px	8px
Icon Size	16px	20px	24px

Specification Categories:

Dimensions - Width, height, min/max sizes
Spacing - Padding, margin, gap between elements
Typography - Font size, weight, line height
Colors - Background, text, border colors (reference to color system)
Effects - Border radius, shadows, transitions

8. Pattern Recognition (Freya's Workflow)

Rule: Document a component in the design system on its SECOND occurrence.

Incremental Building Process

Page 1.1: Uses Button (first occurrence)

→ Freya notes it, continues without creating design system entry

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 E-Design-System/atoms/button/ with full documentation

Page 1.3: Uses Button + Card

→ Button: Already documented, reference existing spec

→ Card: Second occurrence → Ask to document

Page 2.1: Uses Button (primary variant) + new Ghost variant

→ Freya: "New variant detected! I'll add 'Ghost' to the Button variants."

→ Updates E-Design-System/atoms/button/05-variants.md

Why Second Occurrence?

Prevents Premature Abstraction

❌ Problem with "first occurrence": You document something that never gets reused.

✅ Solution with "second occurrence": You only document actual patterns.

Natural Pattern Emergence

Components earn their place in the design system by being actually reused, not by being potentially reusable.

Freya's Tracking System

Component Usage Tracking:

Button:
  - Page 1.1 (first occurrence)
  - Page 1.2 (second occurrence) ← TRIGGER: Create design system entry
  - Page 1.3 (third occurrence) ← Reference existing

Card:
  - Page 1.2 (first occurrence)
  - Page 1.3 (second occurrence) ← TRIGGER: Create design system entry

Input:
  - Page 2.1 (first occurrence)
  [No second occurrence yet, no design system entry]