whiteport-design-studio 0.1.0

package/src/workflows/5-design-system/figma-integration/reference/figma-designer-guide.md

@@ -0,0 +1,687 @@
+# Figma Designer Guide for WDS
+
+**Purpose:** Step-by-step instructions for designers creating components in Figma for WDS projects.
+
+**Audience:** Visual designers, UX designers, design system maintainers
+
+---
+
+## Getting Started
+
+### Prerequisites
+
+- Figma account with edit access to design system file
+- Understanding of WDS component structure
+- Familiarity with Figma components and variants
+- Access to WDS project repository
+
+---
+
+## Step 1: Set Up Your Figma File
+
+### Create Design System File
+
+**File structure:**
+
+```
+[Project Name] Design System
+├── 📄 Cover
+├── 🎨 Foundation
+│   ├── Colors
+│   ├── Typography
+│   ├── Spacing
+│   └── Effects
+├── ⚛️ Components
+│   ├── Buttons
+│   ├── Inputs
+│   ├── Cards
+│   └── [more types]
+└── 📱 Examples
+```
+
+**Tips:**
+
+- Use clear page names
+- Organize by component type
+- Keep foundation separate
+- Include usage examples
+
+---
+
+### Set Up Design Tokens
+
+**Create Figma variables:**
+
+**Colors:**
+
+```
+Collection: Colors
+├── primary/50
+├── primary/100
+├── primary/500
+├── primary/600
+├── gray/50
+├── gray/900
+└── [more colors]
+```
+
+**Spacing:**
+
+```
+Collection: Spacing
+├── spacing/1 = 4px
+├── spacing/2 = 8px
+├── spacing/4 = 16px
+├── spacing/6 = 24px
+└── [more spacing]
+```
+
+**Typography:**
+
+```
+Styles: Typography
+├── Display/Large
+├── Heading/1
+├── Heading/2
+├── Body/Regular
+└── [more styles]
+```
+
+---
+
+## Step 2: Create Your First Component
+
+### Example: Button Component
+
+**1. Create Base Frame**
+
+```
+Frame name: Button/Primary [btn-001]
+Size: Hug contents (width), Fixed 44px (height)
+Auto Layout: Horizontal
+Padding: 16px (horizontal), 12px (vertical)
+Gap: 8px
+```
+
+**2. Add Content**
+
+```
+├── Icon (optional)
+│   └── Size: 20x20px
+└── Text
+    └── Style: Body/Medium
+    └── Content: "Button Text"
+```
+
+**3. Apply Design Tokens**
+
+```
+Background: primary/600 (variable)
+Text Color: white (variable)
+Border Radius: 8px
+```
+
+**4. Create Component**
+
+```
+Select frame → Create Component
+Name: Button/Primary [btn-001]
+```
+
+---
+
+### Add Component Description
+
+**In component description field:**
+
+```
+Button Primary [btn-001]
+
+Primary action button for main user actions.
+
+**When to use:**
+- Submit forms
+- Confirm actions
+- Proceed to next step
+
+**When not to use:**
+- Secondary actions (use Button/Secondary)
+- Navigation (use Link component)
+
+**WDS Component:** Button.primary [btn-001]
+**Variants:** primary, secondary, ghost
+**States:** default, hover, active, disabled, loading
+**Sizes:** small, medium, large
+
+**Accessibility:**
+- role="button"
+- aria-disabled when disabled
+- Keyboard: Enter/Space to activate
+```
+
+---
+
+## Step 3: Add Variants
+
+### Create Variant Properties
+
+**Select component → Add variant property:**
+
+**Property 1: Type**
+
+```
+Values: Primary, Secondary, Ghost, Outline
+```
+
+**Property 2: Size**
+
+```
+Values: Small, Medium, Large
+```
+
+**Property 3: State**
+
+```
+Values: Default, Hover, Active, Disabled, Loading
+```
+
+---
+
+### Design Each Variant
+
+**Type=Primary, Size=Medium, State=Default:**
+
+```
+Background: primary/600
+Text: white
+Padding: 16px × 12px
+```
+
+**Type=Primary, Size=Medium, State=Hover:**
+
+```
+Background: primary/700 (darker)
+Text: white
+Scale: 1.02 (slightly larger)
+```
+
+**Type=Primary, Size=Medium, State=Active:**
+
+```
+Background: primary/800 (darkest)
+Text: white
+Scale: 0.98 (slightly smaller)
+```
+
+**Type=Primary, Size=Medium, State=Disabled:**
+
+```
+Background: gray/300
+Text: gray/500
+Opacity: 0.6
+Cursor: not-allowed
+```
+
+**Type=Primary, Size=Medium, State=Loading:**
+
+```
+Background: primary/600
+Text: white
+Add: Spinner icon
+Opacity: 0.8
+```
+
+---
+
+### Adjust for Sizes
+
+**Small:**
+
+```
+Padding: 12px × 8px
+Text: Body/Small
+Icon: 16x16px
+Height: 36px
+```
+
+**Medium (default):**
+
+```
+Padding: 16px × 12px
+Text: Body/Medium
+Icon: 20x20px
+Height: 44px
+```
+
+**Large:**
+
+```
+Padding: 20px × 16px
+Text: Body/Large
+Icon: 24x24px
+Height: 52px
+```
+
+---
+
+## Step 4: Document States
+
+### Visual State Indicators
+
+**Create a documentation frame:**
+
+```
+Frame: Button States Documentation
+├── Default
+│   └── Normal appearance
+├── Hover
+│   └── Background darker, slight scale
+├── Active
+│   └── Background darkest, scale down
+├── Disabled
+│   └── Grayed out, reduced opacity
+└── Loading
+    └── Spinner, disabled interaction
+```
+
+**Add annotations:**
+
+- State name
+- Visual changes
+- Interaction behavior
+- Transition duration
+
+---
+
+## Step 5: Get Figma Node ID
+
+### Copy Component Link
+
+**1. Select component in Figma**
+
+**2. Right-click → "Copy link to selection"**
+
+**3. Extract node ID from URL:**
+
+```
+URL: https://www.figma.com/file/abc123/Design-System?node-id=456:789
+
+File ID: abc123
+Node ID: 456:789
+
+Full reference: figma://file/abc123/node/456:789
+```
+
+**4. Add to WDS mapping file:**
+
+```yaml
+# D-Design-System/figma-mappings.md
+Button [btn-001] → figma://file/abc123/node/456:789
+```
+
+---
+
+## Step 6: Sync with WDS
+
+### Manual Sync Process
+
+**1. Create component in Figma** (steps above)
+
+**2. Notify WDS system:**
+
+- Add component ID to Figma description
+- Copy Figma node ID
+- Update `figma-mappings.md`
+
+**3. Generate WDS specification:**
+
+- Use Figma MCP to read component
+- Generate component specification
+- Review and confirm
+
+**4. Verify sync:**
+
+- Check WDS component file created
+- Verify all variants captured
+- Confirm states documented
+- Test component reference
+
+---
+
+### Using Figma MCP (Automated)
+
+**If Figma MCP is configured:**
+
+**1. Create/update component in Figma**
+
+**2. Run MCP sync command:**
+
+```bash
+# In WDS project
+wds figma sync Button/Primary
+```
+
+**3. MCP will:**
+
+- Read component from Figma
+- Extract variants and states
+- Generate WDS specification
+- Update figma-mappings.md
+
+**4. Review generated spec:**
+
+- Check accuracy
+- Add missing details
+- Confirm and commit
+
+---
+
+## Step 7: Maintain Components
+
+### Updating Existing Components
+
+**When updating a component:**
+
+**1. Update in Figma:**
+
+- Modify component
+- Update description if needed
+- Maintain component ID
+
+**2. Sync to WDS:**
+
+- Run MCP sync (if available)
+- Or manually update WDS spec
+- Update version history
+
+**3. Notify team:**
+
+- Document changes
+- Update affected pages
+- Test implementations
+
+---
+
+### Version Control
+
+**Track component changes:**
+
+**In Figma:**
+
+- Use Figma version history
+- Add version notes
+- Tag major changes
+
+**In WDS:**
+
+```markdown
+## Version History
+
+**Created:** 2024-12-09
+**Last Updated:** 2024-12-15
+
+**Changes:**
+
+- 2024-12-09: Created component
+- 2024-12-12: Added loading state
+- 2024-12-15: Updated hover animation
+```
+
+---
+
+## Best Practices
+
+### DO ✅
+
+**1. Use Design Tokens**
+
+- Always use variables for colors
+- Use variables for spacing
+- Apply text styles consistently
+
+**2. Document Thoroughly**
+
+- Clear component descriptions
+- Usage guidelines
+- Accessibility notes
+
+**3. Maintain Consistency**
+
+- Follow naming conventions
+- Use consistent spacing
+- Apply standard states
+
+**4. Test Instances**
+
+- Create example instances
+- Test all variants
+- Verify responsive behavior
+
+**5. Keep Organized**
+
+- Logical component grouping
+- Clear page structure
+- Clean component hierarchy
+
+---
+
+### DON'T ❌
+
+**1. Hardcode Values**
+
+- Don't use hex colors directly
+- Don't use pixel values without variables
+- Don't skip design tokens
+
+**2. Detach Instances**
+
+- Don't break component connections
+- Don't create one-off variations
+- Don't lose main component link
+
+**3. Skip Documentation**
+
+- Don't leave descriptions empty
+- Don't forget WDS component ID
+- Don't skip usage guidelines
+
+**4. Ignore States**
+
+- Don't create only default state
+- Don't forget hover/active
+- Don't skip disabled state
+
+**5. Break Naming Conventions**
+
+- Don't use inconsistent names
+- Don't forget component IDs
+- Don't use unclear abbreviations
+
+---
+
+## Common Workflows
+
+### Creating a New Component Type
+
+**1. Research:**
+
+- Check if similar component exists
+- Review WDS component boundaries guide
+- Decide: new component or variant?
+
+**2. Design:**
+
+- Create base component
+- Add all required states
+- Apply design tokens
+
+**3. Document:**
+
+- Write clear description
+- Add WDS component ID
+- Document usage guidelines
+
+**4. Sync:**
+
+- Get Figma node ID
+- Update WDS mappings
+- Generate specification
+
+**5. Test:**
+
+- Create example instances
+- Test all variants
+- Verify responsive behavior
+
+---
+
+### Adding a Variant to Existing Component
+
+**1. Assess:**
+
+- Is this truly a variant?
+- Or should it be a new component?
+- Check with WDS assessment flow
+
+**2. Add Variant:**
+
+- Add new variant property value
+- Design variant appearance
+- Document differences
+
+**3. Update Documentation:**
+
+- Update component description
+- Add variant to list
+- Document when to use
+
+**4. Sync:**
+
+- Update WDS specification
+- Add variant to component file
+- Update version history
+
+---
+
+### Updating Component Styling
+
+**1. Plan Change:**
+
+- Document what's changing
+- Check impact on instances
+- Notify team
+
+**2. Update Component:**
+
+- Modify main component
+- Test all variants
+- Verify instances update
+
+**3. Sync to WDS:**
+
+- Update WDS specification
+- Document changes
+- Update version history
+
+**4. Verify:**
+
+- Check all instances
+- Test in examples
+- Confirm with team
+
+---
+
+## Troubleshooting
+
+### Component Not Syncing
+
+**Problem:** MCP can't read component
+
+**Solutions:**
+
+- Check component name format
+- Verify WDS component ID in description
+- Ensure component is published
+- Check Figma API access
+
+---
+
+### Variants Not Appearing
+
+**Problem:** Some variants missing in WDS
+
+**Solutions:**
+
+- Check variant property names
+- Verify all combinations exist
+- Ensure consistent naming
+- Re-sync component
+
+---
+
+### Design Tokens Not Applied
+
+**Problem:** Hardcoded values instead of variables
+
+**Solutions:**
+
+- Replace hex colors with variables
+- Use spacing variables
+- Apply text styles
+- Re-sync component
+
+---
+
+### Instance Overrides Lost
+
+**Problem:** Updates break instance overrides
+
+**Solutions:**
+
+- Don't change component structure
+- Add new properties instead
+- Maintain backward compatibility
+- Communicate changes to team
+
+---
+
+## Checklist
+
+### Before Creating Component
+
+- [ ] Checked if similar component exists
+- [ ] Reviewed component boundaries guide
+- [ ] Decided on component vs variant
+- [ ] Prepared design tokens
+- [ ] Planned all required states
+
+### During Component Creation
+
+- [ ] Used design tokens (no hardcoded values)
+- [ ] Created all required states
+- [ ] Applied auto layout properly
+- [ ] Added clear description
+- [ ] Included WDS component ID
+- [ ] Documented usage guidelines
+
+### After Component Creation
+
+- [ ] Copied Figma node ID
+- [ ] Updated figma-mappings.md
+- [ ] Generated WDS specification
+- [ ] Created example instances
+- [ ] Tested all variants
+- [ ] Notified team
+
+---
+
+## Resources
+
+- **Figma Component Structure:** `data/design-system/figma-component-structure.md`
+- **Token Architecture:** `data/design-system/token-architecture.md`
+- **Component Boundaries:** `data/design-system/component-boundaries.md`
+- **Figma MCP Integration:** `figma-mcp-integration.md`
+
+---
+
+**Following this guide ensures your Figma components integrate seamlessly with WDS and maintain design system consistency.**