bi-agents/_bmad/wds/workflows/6-asset-generation/data/tools-reference.md

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:

1. Create visual design assets and explore design concepts
2. Convert sketches/specifications to visual designs (images or code)
3. 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/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/4-ux-design/agentic-development/
• Figma Integration: workflows/6-asset-generation/workflow-figma.md
• Dev Mode: workflows/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.