+
+
+
+
+
+
+
+
+ 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
+
+
+
+ ✓ Click Me
+
+
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]
+
[action slot]
+
+
Structure (shared)
+
+
+
+
+
+
Premium Plan
+
Unlock all features
+
Subscribe
+
+
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
+
+
+
+
+ variantstring
+ primary | secondary | ghost
+ primary
+
+
+ sizestring
+ small | medium | large
+ medium
+
+
+ disabledboolean
+ true | false
+ false
+
+
+ fullWidthboolean
+ 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
+
+
Default - Idle state
+
+
+
+
+ Hover
+
+
Hover - Mouse over
+
+
+
+
+ Disabled
+
+
Disabled - Not interactive
+
+
+
+
+
+ ⏳ Loading
+
+
+
Loading - Processing
+
+
Common States:
+
+ default - Idle/resting statehover - Mouse/pointer over componentactive - Currently pressed/clickedfocus - Keyboard focus (accessibility)disabled - Not interactiveloading - Awaiting responseerror - Invalid/failed statesuccess - Completed successfully
+
+
+
+
+ 6. Variants (Visual Styles)
+
+ Variants are different visual styles of the same component structure.
+
+ Button Variants Example
+
+
+
+
+ Primary
+
+
Primary - Main actions
+
+
+
+
+ Secondary
+
+
Secondary - Less emphasis
+
+
+
+
+ Ghost
+
+
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 sizesSpacing - Padding, margin, gap between elementsTypography - Font size, weight, line heightColors - 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]
+
+
+ WDS Design System Standards | Whiteport Design Studio v0.3.0
+ Reference: _wds/docs/design-system/00-design-system.md
+
+