wordle/_bmad/wds/data/design-system/figma-component-structure.md

Figma Component Structure for WDS

Purpose: Guidelines for organizing and structuring components in Figma for seamless WDS integration.

Referenced by: Mode B (Custom Design System) workflows

---

Core Principle

Figma components should mirror WDS component structure to enable seamless synchronization and specification generation.

Figma Component → WDS Component Specification → React Implementation

---

Component Organization in Figma

File Structure

Recommended Figma file organization:

Design System File (Figma)
├── 📄 Cover (project info)
├── 🎨 Foundation
│   ├── Colors
│   ├── Typography
│   ├── Spacing
│   └── Effects
├── ⚛️ Components
│   ├── Buttons
│   ├── Inputs
│   ├── Cards
│   └── [other component types]
└── 📱 Examples
    └── Component usage examples

Benefits:

• Clear organization
• Easy navigation
• Matches WDS structure
• Facilitates MCP integration

---

Component Naming Convention

Format

Pattern: [ComponentType]/[ComponentName]

Examples:

Button/Primary
Button/Secondary
Button/Ghost
Input/Text
Input/Email
Card/Profile
Card/Content

Rules:

• Use forward slash for hierarchy
• Title case for names
• Match WDS component names
• Consistent across all components

---

Component Properties

Required Properties

Every component must have:

1. Description

   • Component purpose
   • When to use
   • WDS component ID (e.g., "btn-001")

2. Variants

   • Organized by property
   • Clear naming
   • All states included

3. Auto Layout

   • Proper spacing
   • Responsive behavior
   • Padding/gap values

Example Description:

Button Primary [btn-001]

Primary action button for main user actions.
Use for: Submit forms, confirm actions, proceed to next step.

WDS Component: Button.primary [btn-001]

---

Variant Structure

Organizing Variants

Use Figma's variant properties:

Property 1: Type (variant)

• Primary
• Secondary
• Ghost
• Outline

Property 2: Size

• Small
• Medium
• Large

Property 3: State

• Default
• Hover
• Active
• Disabled
• Loading

Property 4: Icon (optional)

• None
• Left
• Right
• Only

Result: Figma generates all combinations automatically

---

Variant Naming

Format: Property=Value

Examples:

Type=Primary, Size=Medium, State=Default
Type=Primary, Size=Medium, State=Hover
Type=Secondary, Size=Large, State=Disabled

Benefits:

• Clear property structure
• Easy to find specific variants
• MCP can parse programmatically
• Matches WDS variant system

---

State Documentation

Required States

Interactive Components (Buttons, Links):

• Default
• Hover
• Active (pressed)
• Disabled
• Focus (optional)
• Loading (optional)

Form Components (Inputs, Selects):

• Default (empty)
• Focus (active)
• Filled (has content)
• Disabled
• Error
• Success (optional)

Feedback Components (Alerts, Toasts):

• Default
• Success
• Error
• Warning
• Info

---

State Visual Indicators

Document state changes:

Hover:

• Background color change
• Border change
• Shadow change
• Scale change
• Cursor change

Active:

• Background color (darker)
• Scale (slightly smaller)
• Shadow (reduced)

Disabled:

• Opacity (0.5-0.6)
• Cursor (not-allowed)
• Grayscale (optional)

Loading:

• Spinner/progress indicator
• Disabled interaction
• Loading text

---

Design Tokens in Figma

Using Figma Variables

Map Figma variables to WDS tokens:

Colors:

Figma Variable → WDS Token
primary/500 → color-primary-500
gray/900 → color-gray-900
success/600 → color-success-600

Typography:

Figma Style → WDS Token
Text/Display → text-display
Text/Heading-1 → text-heading-1
Text/Body → text-body

Spacing:

Figma Variable → WDS Token
spacing/2 → spacing-2
spacing/4 → spacing-4
spacing/8 → spacing-8

Effects:

Figma Effect → WDS Token
shadow/sm → shadow-sm
shadow/md → shadow-md
radius/md → radius-md

---

Component Documentation

Component Description Template

[Component Name] [component-id]

**Purpose:** [Brief description]

**When to use:**
- [Use case 1]
- [Use case 2]

**When not to use:**
- [Anti-pattern 1]
- [Anti-pattern 2]

**WDS Component:** [ComponentType].[variant] [component-id]

**Variants:** [List of variants]
**States:** [List of states]
**Size:** [Available sizes]

**Accessibility:**
- [ARIA attributes]
- [Keyboard support]
- [Screen reader behavior]

Example:

Button Primary [btn-001]

**Purpose:** Trigger primary actions in the interface

**When to use:**
- Submit forms
- Confirm important actions
- Proceed to next step
- Primary call-to-action

**When not to use:**
- Secondary actions (use Button Secondary)
- Destructive actions (use Button Destructive)
- Navigation (use Link component)

**WDS Component:** Button.primary [btn-001]

**Variants:** primary, secondary, ghost, outline
**States:** default, hover, active, disabled, loading
**Size:** small, medium, large

**Accessibility:**
- role="button"
- aria-disabled when disabled
- aria-busy when loading
- Keyboard: Enter/Space to activate

---

Auto Layout Best Practices

Spacing

Use consistent spacing values:

• Padding: 8px, 12px, 16px, 24px
• Gap: 4px, 8px, 12px, 16px
• Match WDS spacing tokens

Auto Layout Settings:

• Horizontal/Vertical alignment
• Padding (all sides or specific)
• Gap between items
• Resizing behavior

---

Resizing Behavior

Set appropriate constraints:

Buttons:

• Hug contents (width)
• Fixed height
• Min width for touch targets (44px)

Inputs:

• Fill container (width)
• Fixed height (40-48px)
• Responsive to content

Cards:

• Fill container or fixed width
• Hug contents (height)
• Responsive to content

---

Component Instances

Creating Instances

Best practices:

• Always use component instances (not detached)
• Override only necessary properties
• Maintain connection to main component
• Document overrides if needed

Overridable Properties:

• Text content
• Icons
• Colors (if using variables)
• Spacing (if needed)

Non-Overridable:

• Structure
• Layout
• Core styling
• States

---

Figma to WDS Mapping

Component ID System

Add WDS component ID to Figma:

In component description:

Button Primary [btn-001]

In component name:

Button/Primary [btn-001]

Benefits:

• Easy to find components
• Clear WDS mapping
• MCP can extract ID
• Bidirectional sync

---

Node ID Tracking

Figma generates unique node IDs:

Format:

figma://file/[file-id]/node/[node-id]

How to get node ID:

1. Select component in Figma
2. Right-click → "Copy link to selection"
3. Extract node ID from URL

Store in WDS:

# D-Design-System/figma-mappings.md
Button [btn-001] → figma://file/abc123/node/456:789
Input [inp-001] → figma://file/abc123/node/456:790

---

Sync Workflow

Figma → WDS

When component is created/updated in Figma:

1. Designer creates/updates component
2. Designer adds WDS component ID to description
3. MCP reads component via Figma API
4. MCP extracts:
   • Component structure
   • Variants
   • States
   • Properties
   • Design tokens used
5. MCP generates/updates WDS specification
6. Designer reviews and confirms

---

WDS → Figma

When specification is updated in WDS:

1. Specification updated in WDS
2. Designer notified of changes
3. Designer updates Figma component
4. Designer confirms sync
5. Node ID verified/updated

Note: This is semi-automated. Full automation requires Figma API write access.

---

Quality Checklist

Component Creation

• Component name follows convention
• WDS component ID in description
• All variants defined
• All states documented
• Auto layout properly configured
• Design tokens used (not hardcoded values)
• Accessibility notes included
• Usage guidelines documented

Variant Structure

• Variants organized by properties
• Property names clear and consistent
• All combinations make sense
• No redundant variants
• States properly differentiated

Documentation

• Purpose clearly stated
• When to use documented
• When not to use documented
• Accessibility requirements noted
• Examples provided

---

Common Mistakes to Avoid

❌ Mistake 1: Hardcoded Values

Wrong:

Background: #2563eb (hardcoded hex)
Padding: 16px (hardcoded value)

Right:

Background: primary/600 (variable)
Padding: spacing/4 (variable)

❌ Mistake 2: Detached Instances

Wrong:

• Detaching component instances
• Losing connection to main component
• Manual updates required

Right:

• Always use instances
• Override only necessary properties
• Maintain component connection

❌ Mistake 3: Inconsistent Naming

Wrong:

btn-primary
ButtonSecondary
button_ghost

Right:

Button/Primary
Button/Secondary
Button/Ghost

❌ Mistake 4: Missing States

Wrong:

• Only default state
• No hover/active states
• No disabled state

Right:

• All required states
• Visual differentiation
• State transitions documented

❌ Mistake 5: No WDS Component ID

Wrong:

Button Primary
(no component ID)

Right:

Button Primary [btn-001]
(clear WDS mapping)

---

Examples

Button Component in Figma

Component Name: Button/Primary [btn-001]

Description:

Button Primary [btn-001]

Primary action button for main user actions.

WDS Component: Button.primary [btn-001]
Variants: primary, secondary, ghost, outline
States: default, hover, active, disabled, loading
Sizes: small, medium, large

Variants:

Type=Primary, Size=Medium, State=Default
Type=Primary, Size=Medium, State=Hover
Type=Primary, Size=Medium, State=Active
Type=Primary, Size=Medium, State=Disabled
Type=Primary, Size=Large, State=Default
[... all combinations]

Properties:

• Auto Layout: Horizontal
• Padding: 16px (horizontal), 12px (vertical)
• Gap: 8px (if icon)
• Border Radius: 8px
• Background: primary/600 (variable)

---

Input Component in Figma

Component Name: Input/Text [inp-001]

Description:

Input Text [inp-001]

Text input field for user data entry.

WDS Component: Input.text [inp-001]
States: default, focus, filled, disabled, error, success

Variants:

State=Default
State=Focus
State=Filled
State=Disabled
State=Error
State=Success

Properties:

• Auto Layout: Horizontal
• Padding: 12px
• Height: 44px (fixed)
• Border: 1px solid gray/300
• Border Radius: 8px
• Background: white

---

Further Reading

• Figma MCP Integration: figma-mcp-integration.md
• Designer Guide: figma-designer-guide.md
• Token Architecture: token-architecture.md
• Component Boundaries: component-boundaries.md

---

This structure enables seamless Figma ↔ WDS integration and maintains design system consistency across tools.