sar/.agents/skills/wds-6-asset-generation/data/figma-designer-guide.md

# 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.**