Design Tools Reference for WDS

Purpose: Quick reference for design tools used in WDS workflows, particularly for prototype-to-Figma extraction.

MCP Server (Primary Method)

Purpose: Precise component injection from HTML prototypes to Figma

Use Case in WDS: Extract specific components for visual refinement with full traceability

See: mcp-server-integration.md for complete documentation

Features

Component-Level Precision:

Select specific components by Object ID
Inject individual components or sections
Batch component extraction
Granular control over what gets refined

Conversion Capabilities:

HTML structure → Figma frames
CSS styles → Figma styling
Layout (Flexbox/Grid) → Auto Layout
Text content → Text layers
Colors → Color fills
Spacing → Padding/gaps

Preservation:

Object IDs maintained in layer names
Element hierarchy preserved
Component boundaries respected
Traceability throughout workflow

How to Use

1. Prepare Prototype

Ensure your HTML prototype:
- Uses semantic HTML elements
- Has Object IDs on all components (data-object-id)
- Uses Flexbox or Grid for layouts
- Has clean CSS structure

2. Inject via MCP Server

# Single component
wds figma inject btn-login-submit --file abc123

# Multiple components
wds figma batch inject --list components.txt --file abc123

# Entire section
wds figma inject-section login-form --file abc123

3. Verify in Figma

- Open target Figma file
- Navigate to injection page
- Verify components injected correctly
- Check Object IDs preserved

4. Read Refined Components Back

# After designer refines in Figma
wds figma read btn-login-submit --file abc123 --update-design-system

Advantages over Manual Upload

✅ Component-level precision - Inject only what needs refinement
✅ Object ID preservation - Automatic mapping maintained
✅ Bidirectional sync - Read refined components back
✅ Batch operations - Efficient multi-component extraction
✅ Direct integration - Seamless WDS workflow
✅ Automated token extraction - Design system updates automatic

html.to.design (Alternative Method)

Purpose: Manual HTML to Figma conversion (fallback option)

Website: https://html.to.design

Use Case in WDS: When MCP server unavailable or for full-page extraction

Note: MCP server approach is preferred for component-level precision and traceability.

When to Use html.to.design

Use when:

MCP server not configured
Need to extract entire page at once
Quick one-off conversion needed
Exploring design possibilities

Don't use when:

MCP server available (use MCP instead)
Need component-level precision
Require Object ID traceability
Planning iterative refinement

How to Use

1. Prepare Prototype

Ensure your HTML prototype:
- Uses semantic HTML elements
- Has clean CSS structure
- Uses Flexbox or Grid for layouts

2. Upload to html.to.design

1. Go to https://html.to.design
2. Upload HTML file
3. Include associated CSS files
4. Select target: Figma

3. Import to Figma

1. Download converted Figma file
2. Open in Figma
3. Manually add Object IDs to layers
4. Begin refinement

Limitations:

No automatic Object ID preservation
Entire page extraction (less precise)
Manual token extraction required
No automated design system sync

Best Practices

DO ✅

Use semantic HTML (header, nav, main, section, article)
Apply consistent class naming
Use Flexbox/Grid for layouts
Include Object IDs for traceability
Clean up HTML before extraction
Test prototype before extracting

DON'T ❌

Use complex CSS positioning (absolute, fixed)
Rely on JavaScript-generated content
Use inline styles excessively
Have deeply nested structures
Include debug/test code
Extract incomplete prototypes

Limitations

What Works Well:

Standard layouts (header, content, footer)
Flexbox and Grid layouts
Text content and typography
Basic styling (colors, spacing, borders)
Image placeholders
Component-based structures

What May Need Manual Adjustment:

Complex animations
JavaScript-driven interactions
Dynamic content
Custom SVG graphics
Advanced CSS effects
Responsive breakpoints

Tips for Better Extraction

1. Simplify Structure

<!-- Before: Complex nesting -->
<div class="wrapper">
  <div class="container">
    <div class="inner">
      <div class="content">Text</div>
    </div>
  </div>
</div>

<!-- After: Simplified -->
<div class="content-wrapper">
  <p>Text</p>
</div>

2. Use Flexbox/Grid

/* Preferred: Flexbox */
.container {
  display: flex;
  gap: 16px;
  padding: 24px;
}

/* Avoid: Absolute positioning */
.item {
  position: absolute;
  top: 50px;
  left: 100px;
}

3. Include Object IDs

<!-- Good: Object ID for traceability -->
<button data-object-id="btn-login-submit" class="btn-primary">
  Log In
</button>

4. Clean CSS

/* Preferred: Token-based */
.button {
  background: var(--color-primary-600);
  padding: var(--spacing-md) var(--spacing-lg);
  border-radius: var(--radius-md);
}

/* Avoid: Hardcoded values scattered -->
.button {
  background: #2563eb;
  padding: 12px 16px;
  border-radius: 8px;
}

NanoBanana

Purpose: Agent-driven asset creation, design inspiration, and sketch envisioning tool

Website: https://nanobanana.com

Use Cases in WDS:

Create visual design assets and explore design concepts
Convert sketches/specifications to visual designs (images or code)
Generate design inspiration and placeholder assets

Output Formats:

Images (visual designs, graphics)
Code snippets (HTML/CSS/React)

Description: Agent-driven Photoshop - AI-powered tool for visual asset creation and design exploration

Features

Asset Creation Capabilities:

Visual design generation
Design inspiration and variations
Custom graphics and icons
Image assets
Design concept exploration
Possibly code export for certain elements

Integration with WDS

Workflow:

Design Concept
    → NanoBanana (create assets/inspiration)
    → Visual Assets/Design Ideas
    → Import to Figma for refinement
    → Integrate into Design System
    → Use in Prototypes

When to Use:

Need visual design inspiration
Creating custom graphics/assets
Exploring design variations
Generating design concepts
Creating placeholder visuals
Brand identity exploration

When to Skip:

Have existing design assets
Working with established brand
Simple text/layout designs
Using stock assets
Strict brand guidelines

Best Practices

DO ✅

Use for creative exploration
Generate multiple variations
Refine AI-generated assets
Use as inspiration starting point
Integrate refined assets into design system
Document asset sources

DON'T ❌

Replace human design thinking
Skip refinement process
Ignore brand guidelines
Use without customization
Rely solely on AI output
Skip quality review

Area Tag System

Purpose: Precise region mapping in HTML prototypes for interactive hotspots

Use Case in WDS: Map clickable regions on image-based prototypes or complex UI elements

What Are Area Tags?

HTML <area> elements within <map> tags that define clickable regions on images:

<img src="prototype-screenshot.png" usemap="#prototype-map" alt="Prototype">

<map name="prototype-map">
  <area shape="rect" 
        coords="100,50,300,150" 
        data-object-id="btn-login"
        alt="Login Button"
        href="#login">
  <area shape="rect" 
        coords="100,200,300,250" 
        data-object-id="link-signup"
        alt="Sign Up Link"
        href="#signup">
</map>

When to Use Area Tags

Use When:

Working with image-based prototypes
Need precise click mapping
Complex UI with overlapping elements
Screenshot-based specifications
Testing click regions

Don't Use When:

HTML elements are clickable directly
Simple button/link interactions
Fully interactive prototype exists
Accessibility is primary concern

Integration with Dev Mode

The dev-mode.js component can extract area tag coordinates:

// Dev mode detects area tags
document.querySelectorAll('area').forEach(area => {
  const coords = area.coords;
  const objectId = area.dataset.objectId;
  console.log(`${objectId}: ${coords}`);
});

Creating Area Tags

1. Get Coordinates

Use image editor or browser dev tools:
- Top-left corner: (x1, y1)
- Bottom-right corner: (x2, y2)
- Format: "x1,y1,x2,y2"

2. Define Area

<area shape="rect" 
      coords="x1,y1,x2,y2"
      data-object-id="unique-id"
      alt="Description"
      href="#target">

3. Link to Map

<img src="image.png" usemap="#mapname">
<map name="mapname">
  <!-- area tags here -->
</map>

Best Practices

DO ✅

Include Object IDs in data attributes
Provide descriptive alt text
Test all clickable regions
Document area mappings
Use for image-based prototypes

DON'T ❌

Use for fully interactive HTML prototypes
Forget accessibility considerations
Overlap areas without purpose
Skip testing on different screen sizes
Use as replacement for proper HTML

Accessibility Considerations

Area tags have limitations:

Not keyboard accessible by default
Screen readers may not announce properly
Better to use actual HTML elements when possible

Workaround:

<!-- Add keyboard support -->
<area shape="rect" 
      coords="100,50,300,150"
      data-object-id="btn-login"
      alt="Login Button"
      href="#login"
      tabindex="0"
      role="button">

Dev Mode Component

Purpose: Interactive tool for extracting Object IDs and area coordinates from prototypes

Location: workflows/wds-4-ux-design/agentic-development/templates/components/dev-mode.js

Features

Object ID Extraction:

Hold Shift + Click to copy Object IDs
Visual highlights when Shift held
Tooltip display on hover
Success feedback when copied
Form field protection

Area Tag Extraction:

Detect area tags in prototype
Extract coordinates
Map to Object IDs
Export for documentation

Usage

1. Include in Prototype

<script src="shared/dev-mode.js"></script>

2. Activate Dev Mode

- Click "Dev Mode" button, or
- Press Ctrl+E (Cmd+E on Mac)

3. Extract Object IDs

- Hold Shift
- Click on element
- Object ID copied to clipboard

4. Extract Area Coordinates

- Dev mode detects area tags
- Displays coordinates
- Exports mapping data

Integration with html.to.design

Workflow:

1. Create prototype with Object IDs
2. Use dev mode to verify Object IDs
3. Extract to Figma via html.to.design
4. Object IDs preserved in layer names
5. Maintain traceability

Tool Comparison

Tool	Category	Primary Use	Input	Output	WDS Use Case
MCP Server	Figma Integration	Automated sync	HTML + Object ID	Figma components	Precise refinement (PRIMARY)
html.to.design	HTML → Figma	Full-page conversion	HTML/CSS	Figma file	Fallback method (OPTIONAL)
NanoBanana	AI Design	Asset creation + Sketch envisioning	Text/Sketch/Spec	Images or Code	Early exploration OR sketch-to-design (OPTIONAL)
Area Tags	Region mapping	Clickable regions	Image + coords	Clickable map	Image prototypes
Dev Mode	ID extraction	Object ID tracking	Prototype	Object IDs	Traceability

Recommended Workflow

Standard Flow (MCP Server - Recommended)

1. Create specification (Phase 4C)
2. Build HTML prototype manually (Phase 4D)
3. Add Object IDs to all components
4. Test functionality
5. Inject specific components to Figma via MCP server (if needed)
6. Refine in Figma
7. Read refined components via MCP server
8. Design system auto-updated
9. Re-render prototype

Advantages:

Component-level precision
Object ID traceability maintained
Automated design system updates
Bidirectional sync

Alternative Flow (Manual Upload - Fallback)

1. Create specification (Phase 4C)
2. Build HTML prototype manually (Phase 4D)
3. Add Object IDs to all elements
4. Test functionality
5. Upload to html.to.design (if MCP unavailable)
6. Manually add Object IDs to Figma layers
7. Refine in Figma
8. Manually extract design tokens
9. Update design system manually
10. Re-render prototype

Use when: MCP server not available

With Asset Creation (NanoBanana - Optional)

1. Create specification (Phase 4C)
2. Use NanoBanana for design inspiration/assets (optional)
3. Import assets to Figma
4. Build HTML prototype manually (Phase 4D)
5. Add Object IDs to all components
6. Test functionality
7. Inject to Figma via MCP server (if needed)
8. Refine in Figma (with NanoBanana assets)
9. Read back via MCP server
10. Design system auto-updated
11. Re-render prototype

Use NanoBanana for:

Creating custom graphics/icons
Generating design inspiration
Exploring visual concepts
Creating placeholder assets

Image-Based Flow (With Area Tags)

1. Create specification (Phase 4C)
2. Create image-based prototype
3. Add area tags for clickable regions
4. Include Object IDs in area tags
5. Test click regions
6. Extract to Figma via html.to.design
7. Refine in Figma
8. Convert to HTML prototype
9. Update design system

Cost Considerations

html.to.design

Free tier available
Paid plans for advanced features
Check current pricing at website

NanoBanana

Pricing varies by usage
Check current pricing at website
Consider cost vs time savings

Area Tags

Free (standard HTML)
No additional cost

Dev Mode

Free (included in WDS)
No additional cost

Troubleshooting

html.to.design Issues

Problem: Layout not preserved Solution: Use Flexbox/Grid, simplify structure

Problem: Styles not converted Solution: Use standard CSS properties, avoid complex selectors

Problem: Text content missing Solution: Ensure text is in HTML, not JavaScript-generated

NanoBanana Issues

Problem: Generated code doesn't match design system Solution: Customize output, apply design system manually

Problem: Complex interactions not generated correctly Solution: Review and rewrite interaction logic

Area Tag Issues

Problem: Clicks not registering Solution: Verify coordinates, check map name matches

Problem: Accessibility concerns Solution: Add keyboard support, use actual HTML when possible

Dev Mode Issues

Problem: Object IDs not copying Solution: Check Shift key, verify Object IDs exist

Problem: Dev mode not activating Solution: Check script loaded, try Ctrl+E

Resources

html.to.design:

Website: https://html.to.design
Documentation: Check website for latest docs

NanoBanana:

Website: https://nanobanana.com
Documentation: Check website for latest docs

HTML Area Tags:

MDN Reference: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/area
W3C Spec: https://www.w3.org/TR/html52/semantics-embedded-content.html#the-area-element

WDS Documentation:

Prototype Workflow: workflows/wds-4-ux-design/agentic-development/
Figma Integration: workflows/wds-6-asset-generation/workflow-figma.md
Dev Mode: workflows/wds-4-ux-design/agentic-development/templates/components/

This reference provides quick access to tool information for WDS design workflows. For detailed workflows, see the specific workflow documentation files.

tools-reference.md 16 KB Állandó hivatkozás Előzmények Nyers

Design Tools Reference for WDS

MCP Server (Primary Method)

Features

How to Use

Advantages over Manual Upload

html.to.design (Alternative Method)

When to Use html.to.design

How to Use

Best Practices

Limitations

Tips for Better Extraction

NanoBanana

Features

Integration with WDS

Best Practices

Area Tag System

What Are Area Tags?

When to Use Area Tags

Integration with Dev Mode

Creating Area Tags

Best Practices

Accessibility Considerations

Dev Mode Component

Features

Usage

Integration with html.to.design

Tool Comparison

Recommended Workflow

Standard Flow (MCP Server - Recommended)

Alternative Flow (Manual Upload - Fallback)

With Asset Creation (NanoBanana - Optional)

Image-Based Flow (With Area Tags)

Cost Considerations

html.to.design

NanoBanana

Area Tags

Dev Mode

Troubleshooting

html.to.design Issues

NanoBanana Issues

Area Tag Issues

Dev Mode Issues

Resources

tools-reference.md 16 KB

Állandó hivatkozás Előzmények Nyers