whiteport-design-studio 0.1.0

package/src/data/design-system/figma-component-structure.md

@@ -0,0 +1,697 @@
+# 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:**
+
+```yaml
+# 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.**