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:

# 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:

# 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:

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

figma-designer-guide.md 11 KB Permalink Cronologia Originale

Figma Designer Guide for WDS

Getting Started

Prerequisites

Step 1: Set Up Your Figma File

Create Design System File

Set Up Design Tokens

Step 2: Create Your First Component

Example: Button Component

Add Component Description

Step 3: Add Variants

Create Variant Properties

Design Each Variant

Adjust for Sizes

Step 4: Document States

Visual State Indicators

Step 5: Get Figma Node ID

Copy Component Link

Step 6: Sync with WDS

Manual Sync Process

Using Figma MCP (Automated)

Step 7: Maintain Components

Updating Existing Components

Version Control

Best Practices

DO ✅

DON'T ❌

Common Workflows

Creating a New Component Type

Adding a Variant to Existing Component

Updating Component Styling

Troubleshooting

Component Not Syncing

Variants Not Appearing

Design Tokens Not Applied

Instance Overrides Lost

Checklist

Before Creating Component

During Component Creation

After Component Creation

Resources

figma-designer-guide.md 11 KB

Permalink Cronologia Originale