Wds 6 Asset Generation

Follow the instructions in ./workflow.md.

Content Purpose Examples

Three examples demonstrating how to define clear, testable content purpose

---

Example 1: Landing Page Hero

content_purpose:
  content_type: "Landing page hero section"

  purpose_statement: "Hook Problem Aware hairdressers by validating their frustration and promising transformation"

  audience:
    who: "Harriet (hairdresser, ambitious, small-town)"
    state: "Problem Aware - feels behind when clients ask about trends"
    context: "Landing on site from Google search or Instagram ad"

  success_criteria:
    - "User immediately recognizes themselves in the problem"
    - "User feels validated, not alone"
    - "User wants to continue reading (doesn't bounce)"

  model_priorities:
    primary: ["Customer Awareness ⭐⭐⭐", "Golden Circle ⭐⭐⭐"]
    secondary: ["Badass Users ⭐⭐", "Trigger Map ⭐⭐"]
    tertiary: ["Action Mapping ⭐"]

  review_question: "Does a Problem Aware hairdresser feel seen and want to learn more?"

Analysis:

• Specific audience state: Problem Aware (not just "hairdressers")
• Measurable outcome: "Recognizes themselves" and "doesn't bounce"
• Model priority: Customer Awareness and Golden Circle emphasized for landing page hook
• Testable: Can observe if users recognize themselves and continue reading

---

Example 2: Error Message

content_purpose:
  content_type: "Form validation error message"

  purpose_statement: "Help user fix invalid email while maintaining confidence and reducing frustration"

  audience:
    who: "New user attempting signup"
    state: "Frustrated - made a typo, wants to fix it quickly"
    context: "Just clicked submit and saw error"

  success_criteria:
    - "User understands what's wrong"
    - "User knows exactly how to fix it"
    - "User doesn't feel stupid or blamed"
    - "User successfully resubmits"

  model_priorities:
    primary: ["Badass Users ⭐⭐⭐", "Action Mapping ⭐⭐⭐"]
    secondary: ["Customer Awareness ⭐"]
    tertiary: ["Golden Circle ⭐", "Trigger Map ⭐"]

  review_question: "Can user fix error quickly without feeling frustrated?"

Analysis:

• Emotional state: Frustrated (critical for error messages)
• Dual focus: Fix problem AND maintain confidence
• Model priority: Badass Users and Action Mapping for functional content
• Testable: Can measure successful resubmission and user sentiment

---

Example 3: Product Comparison Feature

content_purpose:
  content_type: "Shelf life comparison row in feature table"

  purpose_statement: "Convince value-conscious users that 3x longer shelf life saves them money and hassle"

  audience:
    who: "Product Aware users comparing us to competitors"
    state: "Evaluating features, looking for differentiators"
    context: "In active comparison mode, possibly has competitor tab open"

  success_criteria:
    - "User understands the 3x advantage"
    - "User connects longer shelf life to personal benefit (saves money/waste)"
    - "User sees this as competitive advantage worth paying for"

  model_priorities:
    primary: ["Trigger Map ⭐⭐⭐", "Badass Users ⭐⭐"]
    secondary: ["Action Mapping ⭐⭐", "Customer Awareness ⭐"]
    tertiary: ["Golden Circle ⭐"]

  review_question: "Does user see 3x shelf life as a compelling reason to choose us?"

Analysis:

• Comparison context: User actively evaluating competitors
• Value connection: Not just "3x longer" but "saves money/hassle"
• Model priority: Trigger Map emphasized for understanding driving forces
• Testable: Can assess if users understand and value the advantage

---

Quick Reference: Purpose Templates

Persuasion:

• "Convince [audience] that [claim] by [strategy]"
• "Activate [driving force] through [benefit/proof]"
• "Move [start awareness] to [end awareness] by [approach]"

Education:

• "Enable [user] to [action] with [confidence level]"
• "Help [user] understand [concept] in [timeframe]"

Functional:

• "Guide [user] to [action] with zero [friction]"
• "Maintain [emotion] while [outcome]"

Brand:

• "Connect [audience] to our [value]"
• "Inspire [emotion] through [story]"

---

_Examples demonstrating content purpose definition across different content types_

Action Filter Example: Hairdresser Newsletter

Trigger Map Context: Hairdresser newsletter signup

Action Filter:

action_filter:
  required_action:
    description: "Click the 'Start Staying Ahead' button to begin email signup"
    success_criteria: "User clicks with confidence, clear on what they'll get"

  business_impact:
    connection: "Email capture drives 500 newsletter signups goal"
    logic: "Click button → Enter email → Confirm subscription → New subscriber"

  user_motivation:
    positive_driver: "Satisfies wish to 'be local beauty authority' by getting trend info"
    negative_driver: "Addresses fear of 'missing industry trends' with regular updates"

  essential_information:
    - "WHAT they'll get: Weekly trend alerts (enables confident click)"
    - "HOW OFTEN: Every Monday (sets expectation, reduces uncertainty)"
    - "TIME INVESTMENT: 60 seconds per trend (shows it's manageable)"
    - "SOCIAL PROOF: 2,000 stylists (reduces risk, builds trust)"
    - "COMMITMENT LEVEL: Free, cancel anytime (removes fear barrier)"

  cut_list:
    - "Company founding story (doesn't enable signup action)"
    - "Technical newsletter platform details (irrelevant to action)"
    - "Full team bios (nice but doesn't reduce barriers)"

  action_barriers:
    - barrier: "Fear of email overload"
      solution: "Weekly (not daily), 60-second reads, unsubscribe anytime"
    - barrier: "Uncertainty about value"
      solution: "Specific: 'Top 5 trends' + testimonial about client reactions"
    - barrier: "Distrust of free offers"
      solution: "2,000 stylists already using it (social proof)"

---

Analysis

Required Action: "Click signup button with confidence" - specific, observable behavior

Business Connection: Click → Email capture → Subscription → 500 signups goal

User Motivation:

• Wish: "Be beauty authority" → Gets trend info
• Fear: "Miss trends" → Regular updates

Essential Information (5 elements): All focused on enabling confident click by addressing barriers: 1. What: Weekly trend alerts (clarifies offering) 2. When: Every Monday (sets expectation) 3. Time: 60 seconds (shows manageable) 4. Proof: 2,000 stylists (builds trust) 5. Commitment: Free, cancel anytime (removes risk)

Cut List (3 elements): All "nice to know" but don't enable the action:

• Company story (impressive but irrelevant)
• Technical details (doesn't reduce barriers)
• Team bios (interesting but unnecessary)

Barriers Addressed (3): Each barrier gets specific content solution:

• Email overload → "Weekly, 60 seconds, unsubscribe"
• Uncertainty → "Top 5 trends + testimonial"
• Distrust → "2,000 using it" (social proof)

---

Key Insights

Information is filtered through action:

• Only 5 essential elements kept
• 3 "nice to know" elements cut
• Everything serves the signup action

Barriers drive content:

• Each barrier identified gets targeted content
• Not generic "benefits" but specific barrier removal
• Content is strategic, not decorative

Business + User alignment:

• Action serves business goal (email capture → signups)
• Action serves user motivation (authority wish, trends fear)
• Win-win: both parties get what they need

---

_Example demonstrating Action Mapping for hairdresser newsletter signup_

Badass Users Principles

Kathy Sierra's framework for user-centered content

---

Core Philosophy

"Users don't care about your product. They care about being awesome at what your product helps them do."

The Insight: Don't make a better product. Make a better USER.

---

The Five Key Principles

1. Make Them Better, Not Your Product Better

Focus on THEIR capability, not your features

Bad (product-focused):

• "Our AI analyzes 10,000 beauty sources"
• "We send weekly emails with 5 trends"
• "Our platform has been trusted since 2018"

Good (capability-focused):

• "You'll spot trends before your competitors"
• "You'll always have something new to talk about with clients"
• "You'll feel confident when clients ask about the latest looks"

Frame: "You'll be able to..." not "Our product has..."

---

2. Show The Transformation

From: Current state → To: Badass state

Make the path visible:

• Where they are (current state: struggling, uncertain)
• Where they're going (badass state: capable, confident)
• That the path is real and achievable

Examples:

• Specific numbers: "60 seconds per trend" (concrete, not vague)
• Social proof: "2,000 stylists already there" (others did it)
• Quick win: "Try it on your next client" (immediate application)

---

3. Create "Aha Moments"

Insights that shift perspective and build confidence

Not just understanding—perspective shift:

Examples:

• "Oh! I don't need to follow 100 accounts—I just need THIS digest!"
• "Oh! This is about my CLIENT'S reactions, not just knowing trends!"
• "Oh! 60 seconds is all I need—I thought it would take hours!"

Characteristics:

• Specific insight (not vague "understanding")
• Removes a barrier or misconception
• Unlocks confidence to act
• Memorable and quotable

---

4. Reduce Cognitive Load

Don't make them think unnecessarily

Strategies:

• Too many choices? → Reduce options or guide selection
• Too much jargon? → Use plain language
• Too many steps? → Break down or simplify
• Unclear what to do? → Make next step obvious

Cognitive load reduction often means cutting 30-40% of planned content

Remove:

• Unnecessary decisions
• Complex explanations
• Industry jargon
• Multiple CTAs
• Non-essential features

---

5. Focus on Skills, Not Tools

What skill or capability are we helping them develop?

Not (tool-focused):

• "Using our platform"
• "Receiving emails"
• "Accessing our database"

But (skill-focused):

• "Staying current effortlessly"
• "Impressing your clients"
• "Becoming the local authority"

The tool is the vehicle, the skill is what matters

---

Application Framework

For each piece of content, ask:

1. Does this make THEM feel capable? (not us look good) 2. Does it show transformation? (current → badass with visible path) 3. Does it create an "aha moment"? (perspective shift that unlocks confidence) 4. Does it reduce cognitive load? (or add unnecessary complexity) 5. Does it focus on skills gained? (not just tools used)

---

Common Mistakes

Mistake #1: Feature Focus

• Talking about product capabilities instead of user capabilities
• "We have..." instead of "You'll be able to..."

Mistake #2: Vague Transformation

• Aspirational marketing fluff without concrete path
• No specifics on how transformation happens

Mistake #3: No Aha Moment

• Just explaining features
• Missing the key insight that shifts perspective

Mistake #4: Cognitive Overload

• Trying to say everything
• Multiple options without guidance
• Complex language

Mistake #5: Tool Obsession

• Focusing on using the product
• Missing the skill they're actually developing

---

Key Quotes

On Product vs. User:

"Nobody cares about your product. They care about being badass at what your product helps them do."

On Transformation:

"Make the user awesome, not your product awesome."

On Skills:

"People want to be great photographers, not great at using Photoshop."

---

_Badass Users principles reference for Step 4 - Empowerment Frame_

Example: Badass Users Framework Applied to Hairdresser Newsletter

Trigger Map Context: Hairdresser newsletter signup

Empowerment Frame:

empowerment_frame:
  transformation:
    current_state:
      description: "Harriet feels behind when clients ask about trends she hasn't heard of"
      feelings: ["frustrated", "embarrassed", "uncertain"]
      capabilities: "Can't confidently discuss latest trends with clients"

    badass_state:
      description: "Harriet is always ahead—clients see her as their beauty authority"
      feelings: ["confident", "proud", "expert"]
      capabilities: "Spots trends before competitors, impresses clients, leads conversations"

    visibility: "2,000 stylists already there + 'Try it on next client Monday' = immediate, real path"

  aha_moment:
    insight: "Oh! I don't need to follow 100 accounts or read for hours—60 seconds on Monday morning is enough!"
    why_powerful: "Removes the overwhelm barrier. Being ahead doesn't require massive effort—just smart curation."

  capability_framing:
    - feature: "AI analyzes 10,000 beauty sources weekly"
      reframed: "You'll spot trends before your competitors even hear about them"

    - feature: "Weekly email with 5 top trends"
      reframed: "You'll always have something new and exciting to talk about with clients"

    - feature: "60-second explainers for each trend"
      reframed: "You'll understand trends fast enough to use them the same day"

    - feature: "2,000 stylist subscribers"
      reframed: "You'll join successful stylists who are already ahead"

  cognitive_load:
    potential_issues:
      - issue: "Fear of email overload / another thing to manage"
        solution: "Emphasize: 'Weekly, not daily' + '60 seconds' + 'Monday morning ritual'"

      - issue: "Uncertainty about what trends are or how to use them"
        solution: "'Client conversation starters included' = no guesswork"

    simplifications:
      - "Cut: Technical details about AI or sources (doesn't help capability)"
      - "Cut: Company history (irrelevant to their transformation)"
      - "Simplify: One clear CTA, not multiple options"

  skill_focus:
    primary_skill: "Staying ahead of beauty trends effortlessly"
    supporting_skills:
      - "Impressing clients with current knowledge"
      - "Leading beauty conversations in their town"
      - "Building authority and reputation"
    tools_secondary: "Newsletter is the vehicle, but skill is what matters"

---

Key Transformations

Current → Badass:

• From: "Behind and embarrassed" → To: "Ahead and confident"
• From: "Can't discuss trends" → To: "Leads trend conversations"
• Path made real: 2,000 already there + immediate application

The Aha Moment: "60 seconds is enough" - removes the massive barrier of thinking staying ahead requires hours of work

Feature → Capability Reframing:

• "AI analyzes sources" → "You'll spot trends first" (about THEM, not us)
• "Weekly email" → "Always something new to discuss" (capability, not delivery)
• "60-second explainers" → "Understand fast enough to use same day" (skill outcome)

Cognitive Load Reduction:

• Addressed fear of "another thing to manage" → "Weekly + 60 seconds + ritual"
• Removed uncertainty → "Conversation starters included"
• Cut all non-essential: company history, technical details, multiple CTAs

Skill Focus: Primary skill is "staying ahead effortlessly" - not "using a newsletter"

---

_Example demonstrating Badass Users framework application for hairdresser newsletter_

Example: Golden Circle Applied to Hairdresser Newsletter

Trigger Map Context: Hairdresser newsletter signup

Structural Order:

structural_order:
  section_why:
    purpose: "Emotional connection—problem recognition and aspiration"
    content_elements:
      - order: 1
        element: "Headline: 'Are Your Clients Asking About Trends You Haven't Heard Of?'"
        rationale: "Opens with emotional pain point—immediate recognition"

      - order: 2
        element: "Subhead: 'Stop feeling behind. Become your town's go-to beauty authority.'"
        rationale: "Validation (you're not alone) + aspiration (badass state)"

      - order: 3
        element: "Visual: Split image—uncertain hairdresser → confident trendsetter"
        rationale: "Shows transformation visually, reinforces emotional journey"

  section_how:
    purpose: "Solution approach—how stylists stay ahead"
    content_elements:
      - order: 1
        element: "Heading: 'Here's How Stylists Stay Ahead:'"
        rationale: "Introduces solution category (trend newsletters) to Problem Aware users"

      - order: 2
        element: "Weekly trend alerts delivered Monday morning"
        rationale: "Explains the method—simple, regular, manageable"

      - order: 3
        element: "60-second explainers—understand it fast"
        rationale: "Key differentiator—reduces cognitive load fear"

      - order: 4
        element: "Client conversation starters included"
        rationale: "Shows transformation path—immediate application"

  section_what:
    purpose: "Product naming, proof, and action"
    content_elements:
      - order: 1
        element: "Heading: 'Join TrendWeek—Free for Stylists'"
        rationale: "NOW we can name the product (moved to Product Aware)"

      - order: 2
        element: "2,000 stylists already ahead"
        rationale: "Social proof builds credibility before ask"

      - order: 3
        element: "Button: 'Start Staying Ahead'"
        rationale: "Capability-framed CTA (not 'sign up')"

      - order: 4
        element: "Subtext: 'Free. No credit card. Cancel anytime.'"
        rationale: "Risk removal last—addresses final barrier"

  flow_validation:
    feels_natural: "Yes—emotion → method → specifics flows smoothly"
    persuasive_arc: "WHY connects emotionally, HOW builds confidence, WHAT enables action without jumping too fast"

---

Analysis

WHY Section:

• Opens with emotional pain (problem recognition)
• Validates feeling (not alone)
• Shifts to aspiration (can become authority)
• Flow: Problem → Validation → Aspiration

HOW Section:

• Introduces solution approach
• Explains method (weekly delivery)
• Shows differentiator (60-second format)
• Demonstrates transformation path (conversation starters)
• Flow: Introduction → Method → Differentiator → Application

WHAT Section:

• Names the product (now user is Product Aware)
• Provides social proof (credibility)
• Capability-framed CTA (action)
• Removes risk (final barrier)
• Flow: Naming → Proof → Action → Risk Removal

Persuasive Arc: Emotion (WHY) → Method (HOW) → Specifics (WHAT) creates smooth journey from pain recognition to empowered action.

---

_Example demonstrating Golden Circle sequencing for hairdresser newsletter content_

Golden Circle Framework Guide

Simon Sinek's WHY → HOW → WHAT model for persuasive content sequencing

---

The Golden Circle Model

    WHY (Core)
     ↓
    HOW (Process)
     ↓
    WHAT (Proof)

---

The Three Levels

WHY - The Purpose, Cause, Belief

Purpose: Connect emotionally, establish motivation

Questions:

• Why does this matter?
• Why should the user care?
• What's the emotional truth?

Good WHY Examples:

• "Are your clients asking about trends you haven't heard of?" (emotional truth)
• "You deserve to feel ahead, not behind" (aspiration)
• "Every stylist feels this—you're not alone" (validation)

Bad WHY Examples:

• "Our company was founded in 2018" (not emotional)
• "TrendWeek is a beauty newsletter" (WHAT, not WHY)
• "Sign up now" (jumping to action without motivation)

Connects to:

• User's driving forces (from Trigger Map)
• Current emotional state (from Empowerment Frame)
• The problem or aspiration that matters

---

HOW - The Process, Approach, Differentiator

Purpose: Bridge emotion to specifics, show the method

Questions:

• How does this work?
• How do you do it differently?
• What's the method?

Example HOW Content:

• "Here's how stylists stay ahead: Weekly trend alerts delivered Monday morning"
• "60-second explainers—understand trends fast enough to use them same day"
• "Client conversation starters included—no guesswork"

Connects to:

• Essential information (Action Filter)
• Capability framing (Empowerment Frame)
• The transformation path

---

WHAT - The Tangible, Proof, Specifics

Purpose: Provide concrete details and enable action

Questions:

• What exactly do you do/offer?
• What are the features?
• What's the concrete evidence?

Example WHAT Content:

• "Join TrendWeek—Free for Stylists"
• "2,000 stylists already ahead"
• "Start Staying Ahead" (CTA button)
• "Free. Cancel anytime."

Includes:

• Specific features or offers
• Tangible evidence
• Social proof
• The ask/action

---

Key Insights

Start with WHY:

• People don't buy WHAT you do, they buy WHY you do it
• Emotion drives decisions, logic justifies them
• WHY creates connection before presenting solution

Bridge with HOW:

• HOW explains the approach that delivers on the WHY
• Shows your unique method or differentiator
• Builds confidence in the transformation

Prove with WHAT:

• WHAT provides concrete specifics after buy-in
• Only effective after WHY and HOW establish context
• Enables action with confidence

---

Common Mistakes

Mistake #1: Starting with WHAT

• ❌ "TrendWeek is a weekly newsletter for hairdressers..."
• ✅ "Are your clients asking about trends you haven't heard of?"

Mistake #2: Missing WHY

• Content feels cold and transactional
• No emotional connection
• Features without context

Mistake #3: WHAT before WHY

• Content feels salesy and pushy
• User isn't ready to hear specifics
• Premature call to action

---

Sequencing Within Sections

The Golden Circle is fractal—apply it at page level AND within each section:

WHY Section Micro-sequence: 1. Problem recognition (emotional hook) 2. Validation (you're not alone) 3. Aspiration (you can feel different)

HOW Section Micro-sequence: 1. Introduce solution approach 2. Explain key differentiator 3. Show transformation path

WHAT Section Micro-sequence: 1. Name the product/offer 2. Social proof 3. Clear CTA 4. Risk removal

---

Application Notes

• The "aha moment" from Step 4 often lives in the HOW section (the insight that bridges emotion to action)
• If WHAT comes before WHY, content feels salesy and pushy
• If WHY is missing, content feels cold and transactional
• This structure works for pages, sections, paragraphs, even sentences
• The Golden Circle creates natural persuasive flow: emotion → method → specifics

---

_Golden Circle framework guide for Step 5 - Structural Order_

Example: Hairdresser Newsletter Signup

Trigger Map Context: Hairdresser newsletter signup

Content Generations:

---

Variation A: Wish-Focused (Become the Authority)

Rationale: Emphasizes the positive driving force: "Wish to be local beauty authority." This variation speaks to aspiration and confidence. Works best for users who are motivated by status and recognition.

Content:

WHY Section:

• Headline: "Become Your Town's Go-To Beauty Authority"
• Subhead: "The trends your clients are asking about? You'll spot them first."
• Visual: Confident hairdresser surrounded by admiring clients

HOW Section:

• Heading: "Here's How Stylists Stay Ahead:"
• Every Monday morning: Top 5 trends in your inbox
• 60-second explainers—understand and apply the same day
• Client conversation starters included—lead the discussion

WHAT Section:

• Heading: "Join 2,000 Stylists Who Are Already Ahead"
• Button: "Start Leading Trends"
• Subtext: "Free. No credit card. Cancel anytime."

Why This Might Resonate: For hairdressers who are confident but want to level up. Aspirational tone matches their ambition.

---

Variation B: Fear-Focused (Stop Falling Behind)

Rationale: Addresses the negative driving force: "Fear of missing industry trends." This variation acknowledges the pain point directly. Works best for users feeling frustrated or embarrassed.

Content:

WHY Section:

• Headline: "Are Your Clients Asking About Trends You Haven't Heard Of?"
• Subhead: "Stop feeling behind. Never miss a trend again."
• Visual: Split image—uncertain hairdresser → confident trendsetter

HOW Section:

• Heading: "Here's How to Never Miss a Trend:"
• Weekly alerts delivered Monday morning—stay current effortlessly
• 60-second reads—no time wasted
• Client conversation starters—no more guesswork

WHAT Section:

• Heading: "Join TrendWeek—Free for Stylists"
• "2,000 stylists already staying ahead"
• Button: "Stop Missing Out"
• Subtext: "Free. No credit card. Cancel anytime."

Why This Might Resonate: For hairdressers actively experiencing the pain. Direct problem recognition creates immediate connection.

---

Variation C: Balanced (Recognition + Aspiration)

Rationale: Combines both driving forces naturally—opens with problem recognition (fear), bridges to aspiration (wish). Works for most users by meeting them where they are and showing where they can go.

Content:

WHY Section:

• Headline: "Your Clients Are Asking. You Should Be Leading."
• Subhead: "Stop playing catch-up. Become the trendsetter your town needs."
• Visual: Transformation sequence—uncertain → confident → authority

HOW Section:

• Heading: "Here's How Stylists Go From Behind to Ahead:"
• Monday mornings: Top 5 trends delivered to your inbox
• 60 seconds per trend—fast enough to use the same day
• Conversation starters included—turn knowledge into client impact

WHAT Section:

• Heading: "Join TrendWeek—Free for Stylists"
• "2,000 stylists made the shift. Your turn."
• Button: "Start Staying Ahead"
• Subtext: "Free. No credit card. Cancel anytime."

Why This Might Resonate: Balanced approach works broadly. Acknowledges pain without dwelling, focuses on transformation.

---

Refinement Process

User selects: "I like Variation B's headline and opening, but prefer Variation C's HOW section and Variation A's CTA framing."

Agent refines and combines:

---

FINAL CONTENT

WHY Section:

• Headline: "Are Your Clients Asking About Trends You Haven't Heard Of?"
• Subhead: "Stop feeling behind. Become your town's go-to beauty authority."
• Visual: Split image—uncertain hairdresser → confident trendsetter

HOW Section:

• Heading: "Here's How Stylists Go From Behind to Ahead:"
• Monday mornings: Top 5 trends delivered
• 60 seconds per trend—fast enough to use the same day
• Conversation starters included—lead the discussion

WHAT Section:

• Heading: "Join TrendWeek—Free for Stylists"
• "2,000 stylists already ahead"
• Button: "Start Leading Trends"
• Subtext: "Free. No credit card. Cancel anytime."

---

Strategic Traceability:

• Business Goal: Increase newsletter signups
• Driving Forces Addressed:
• Fear: Missing industry trends (opening headline)
• Wish: Be local beauty authority (subhead, CTA)
• Awareness Journey: Problem Aware → Solution Aware (recognizes problem, sees how to solve it)
• Action Enabled: Sign up for free newsletter
• Empowerment Achieved: "You'll be able to lead trends" (not just follow)

---

_Example demonstrating how variations combine strategic context into final content_

Content Generation Instructions

How to generate strategically grounded content variations

---

1. Synthesize All Context

Before generating, review and confirm you understand:

• [ ] WHO the user is and what drives them (Trigger Map)
• [ ] WHERE they are in awareness (START → END)
• [ ] WHAT action this content must enable (Action Filter)
• [ ] HOW to make them feel capable (Empowerment Frame)
• [ ] WHAT order creates persuasive flow (Golden Circle)

---

2. Generate Multiple Variations

Create 2-3 content variations that differ in:

Variation A: Wish-Focused

• Emphasizes positive driving forces
• Aspirational tone
• "Become the authority," "Stay ahead," "Impress your clients"

Variation B: Fear-Focused

• Addresses negative driving forces
• Problem-recognition tone
• "Stop feeling behind," "Never miss a trend," "No more embarrassment"

Variation C: Balanced OR Awareness-Shifted (choose one):

• Balanced: Combines wish + fear naturally
• Awareness-Shifted: Uses different starting awareness level (if user was uncertain)

For each variation, include:

• Complete content (headlines, body, CTA)
• Rationale explaining the approach
• Why this might resonate

---

3. Presentation Format

Use this format:

---

## Variation A: [Name - e.g., "Wish-Focused"]

### Rationale
[Why this approach, what driving force it emphasizes, when this works best]

### Content

**WHY Section:**
[Content for WHY]

**HOW Section:**
[Content for HOW]

**WHAT Section:**
[Content for WHAT]

### Why This Might Resonate
[Specific user insight or context that makes this effective]

---

## Variation B: [Name]
[Same structure]

---

## Variation C: [Name]
[Same structure]

---

---

4. Explain Strategic Choices

For each variation, show how you applied the strategic context:

• "This opens with [X] because the user is Problem Aware—they need problem validation first"
• "This uses 'you'll be able to' framing because of Badass Users principle"
• "This puts social proof before CTA because Action Filter identified trust as a barrier"

Make the strategy visible.

---

_Reference for generating content variations in Step 6_

Content Creation Workshop Guide

Strategic, Multi-Model Content Generation for WDS

---

What Is This?

The Content Creation Workshop is a disciplined, multi-model framework for generating strategically grounded content. Instead of "blurting out versions," agents use five strategic models in sequence to create content that is:

• ✅ Strategically grounded (serves business goals)
• ✅ Awareness-appropriate (speaks to user's current understanding)
• ✅ Action-focused (enables specific user behaviors)
• ✅ Empowering (makes users feel capable)
• ✅ Structurally persuasive (WHY → HOW → WHAT flow)

---

When to Use

Use this workshop whenever creating:

• Page headlines and hero content
• Section content and feature descriptions
• Value propositions and benefit statements
• CTAs with strategic importance
• About/mission statements
• Landing page content
• Onboarding narratives
• Feature announcements
• Case studies and testimonials
• Any user-facing text where purpose and context matter

Skip this workshop for:

• ❌ Standard UI microcopy (form labels, generic buttons, tooltips)
• ❌ System messages (loading, generic errors, confirmations)
• ❌ Navigation labels
• ❌ Standard form instructions
• ❌ Technical documentation
• ❌ Code comments
• ❌ Internal notes
• ❌ Placeholder content during prototyping

For UI microcopy: Use Tone of Voice guidelines (defined in Product Brief)

• Form labels: "Email" vs "Email address" (tone-dependent)
• Buttons: "Submit" vs "Continue" vs "Let's go" (tone-dependent)
• Errors: "Invalid input" vs "Hmm, that doesn't look right" (tone-dependent)
• See Tone of Voice Guide

---

The Five-Model Framework

0. Content Purpose = The Job To Do

• Defines: WHAT must this content accomplish? HOW will we know it worked?
• Answers: What's the measurable outcome? Which models should we emphasize?

1. Trigger Map = Strategic Foundation

• Provides: Business goal, solution, user, driving forces, customer awareness positioning
• Answers: WHO are we serving? WHAT motivates them? WHERE are they in their journey?

2. Customer Awareness Cycle = Content Strategy

• Provides: Language appropriate to awareness level, information priorities, required proof
• Answers: WHAT can they understand? WHAT do they need to know? WHAT will they believe?

3. Action Mapping = Content Filter

• Provides: Required user action, relevance test
• Answers: WHAT must they DO after reading this? Is this content necessary?

4. Badass Users = Tone & Frame

• Provides: Empowerment framing, transformation narrative, cognitive load reduction
• Answers: HOW does this make them feel capable? WHAT's the "aha moment"?

5. Golden Circle = Structural Order

• Provides: WHY → HOW → WHAT sequence
• Answers: WHAT order creates the most persuasive flow?

---

Workshop Structure

The workshop follows 7 sequential considerations (agents can adapt flow naturally):

0. Define Content Purpose - What job must this content do? 1. Load Trigger Map Context - Establish strategic foundation 2. Apply Customer Awareness Strategy - Determine appropriate language & information 3. Define Required Action - Filter for relevance 4. Frame User Empowerment - Set tone and transformation narrative 5. Determine Structural Order - Sequence content for persuasion 6. Generate & Review Content - Create options and select

Duration: 15-30 minutes per content section

Mode Options:

• Quick Mode: Agent synthesizes internally, presents reasoning + variants
• Workshop Mode: Collaborative conversation through each consideration

---

How to Use

For Agents

When you encounter content creation in a workflow:

1. Define Purpose First - "What job must this content do?"

• If user provides purpose → Use it
• If not → Ask: "What should this content accomplish?"
• Define success criteria: "How will we know it worked?"

2. Select Mode:

• Quick Mode: User says "Suggest content for [X]"
• Synthesize all strategic considerations internally
• Present: Purpose → Reasoning → Multiple variants → Selection
• Workshop Mode: User says "Let's work through content for [X]"
• Collaborative conversation through considerations
• Adapt flow naturally (skip/combine as appropriate)

3. Check for Trigger Map - Does the current context have a Trigger Map?

• If YES → Proceed with strategic generation
• If NO → Suggest creating a Trigger Map first (route to Phase 2)

4. Execute Strategically:

• Consider all strategic layers (Trigger Map, Awareness, Action, Empowerment, Structure)
• Emphasize models based on content purpose (see Content Purpose Guide)
• Don't force rigid steps - adapt naturally

5. Present Options - Offer 2-3 variations:

• Different driving force angles (wish vs fear)
• Different awareness approaches (if uncertain)
• Different structural emphases

6. Enable Review:

• Does content achieve its stated purpose?
• Objective criteria, not "I like it"

For Designers

You control the strategic context and mode:

1. Define content purpose - Be specific about what the content must accomplish 2. Choose your mode:

• Need quick suggestions? → "Suggest content for this hero section"
• Want to explore together? → "Let's work through the homepage hero"

3. Provide context or let agent find it (Trigger Map, page purpose, user state) 4. Review against purpose - Does it do its job? (objective criteria) 5. Select or refine - Choose variant or combine elements 6. Iterate if needed - Purpose not achieved? Refine and regenerate

---

Integration Points

In Phase 4: UX Design - Sketch Review Flow

When designer presents a sketch:

1. Agent identifies text elements (headlines, CTAs, sections, microcopy) 2. Agent suggests purposes for each element based on:

• Position on page (hero vs. footer)
• Content type (headline vs. error message)
• Page context (landing vs. onboarding)

3. Agent recommends model priorities for each purpose 4. Designer confirms/refines purposes 5. Agent generates content for approved purposes 6. Content is documented in page specification

Granularity Options:

• Element-by-element: For critical content (hero headline, primary CTA)
• Section-level: For cohesive blocks (feature section, testimonials)
• Batch: For repetitive elements (form labels, tooltips)

Example Sketch Review:

DESIGNER: "Here's the landing page sketch [wireframe]"

AGENT: "I see several text elements. Let me suggest purposes:

📝 Hero Headline
Purpose: Hook Problem Aware users by validating frustration
Models: Customer Awareness ⭐⭐⭐, Golden Circle ⭐⭐⭐

📝 Hero Subhead
Purpose: Promise transformation, reduce anxiety
Models: Badass Users ⭐⭐, Customer Awareness ⭐⭐

📝 Feature Section (whole section)
Purpose: Show how solution works, enable understanding
Models: Action Mapping ⭐⭐⭐, Badass Users ⭐⭐

📝 CTA Button
Purpose: Make signup feel empowering and low-risk
Models: Badass Users ⭐⭐⭐, Action Mapping ⭐⭐

Does this match your intent?"

DESIGNER: "Yes, generate content"
[OR]
DESIGNER: "Make headline more fear-focused"
→ AGENT: Updates purpose, generates accordingly

In Phase 4: UX Design - Page Specifications

When creating page specifications:

• Hero sections → Purpose-driven content generation
• Key feature descriptions → Purpose-driven content generation
• CTAs and conversion points → Purpose-driven content generation
• Error/empty state messages → Purpose-driven content generation

When working with Freya:

• Freya identifies text elements in sketches
• Suggests purposes automatically
• Generates content after confirmation
• Documents everything in page specifications

In Phase 1: Product Brief (Pitch)

When creating pitch deck content:

• Problem statement → Run this workshop
• Solution description → Run this workshop
• Value propositions → Run this workshop

---

What You Get

For each content section:

1. Purpose Statement (what this content must do)

• Clear job definition
• Success criteria
• Model priority emphasis

2. Strategic Context Document (shows your thinking)

• Trigger Map reference
• Awareness journey map
• Action requirement
• Empowerment frame
• Structural sequence

3. Content Options (2-3 variations)

• Fully written content
• Different angles/approaches
• Rationale for each option
• Model emphasis explained

4. Selected Content (final version)

• Refined and approved
• Ready for implementation
• Traceable to strategic context
• Reviewable against purpose

---

Alpha Status Notice

⚠️ This workshop is in Alpha - first real-world usage pending.

What this means:

• Structure is theoretically sound but untested in practice
• Steps may need refinement based on actual usage
• Timing estimates may be inaccurate
• You may discover missing elements or unnecessary steps

Please provide feedback:

• What worked well?
• What felt clunky or unnecessary?
• What's missing?
• How could this be more efficient?

Alpha will be removed when:

• Successfully used in 3+ real projects
• Timing validated and adjusted
• Feedback integrated
• No major structural changes needed for 2 months

---

Files

Entry Point:

• content-creation-workshop.md - Start here

Micro-Steps:

• steps/workflow.md - Sequential execution guide
• steps/step-00-define-purpose.md
• steps/step-01-load-trigger-map-context.md
• steps/step-02-awareness-strategy.md
• steps/step-03-action-filter.md
• steps/step-04-empowerment-frame.md
• steps/step-05-structural-order.md
• steps/step-06-generate-content.md

Output Template:

• content-output.template.md - Structured output format

---

Related Resources

Strategic Models:

• Customer Awareness Cycle
• Golden Circle
• Action Mapping
• Kathy Sierra Badass Users

Whiteport Methods:

• Trigger Mapping Guide
• Content Purpose Guide - Start here for content effectiveness

Workflows:

• Phase 4: UX Design
• Phase 1: Product Exploration

---

Let's create strategically grounded content, not guesswork. 🎯

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 to Code Workshop

Status: Coming Soon

Purpose: Extract design specifications from Figma and implement them in code

Tool: Figma Desktop MCP Server Direction: Figma → Code

---

Overview

This workshop will guide AI agents through importing design specifications from Figma to generate or update code implementations.

When to Use Figma to Code

Import from Figma when:

• ✅ Designer has updated visual specifications in Figma
• ✅ New design system components need implementation
• ✅ Design tokens (colors, spacing, typography) need extraction
• ✅ Component states have been refined visually
• ✅ Design-code sync is needed after visual iteration

---

Planned Workflow

1. Connection Check - Verify Figma Desktop MCP server 2. Select Figma Node - Identify what to import 3. Extract Design Specs - Get colors, spacing, typography, layout 4. Generate/Update Code - Create or update components 5. Verify Implementation - Compare code output to Figma design

---

This workshop will be developed to complement the Code to Figma workflow.

Figma Integration - Summary

Last Updated: January 9, 2026 Version: WDS v6 Status: Active Development

---

Overview

This integration enables bidirectional workflow between code and Figma for design system development and visual refinement.

Bidirectional Workflow

Code ⇄ Figma

Two Main Workflows:

1. Code to Figma (C2F): Send code implementations to Figma for visual documentation and refinement 2. Figma to Code (F2C): Import design specifications from Figma to generate or update code

Key Innovation: Specification-driven approach ensures design-code parity through shared OBJECT IDs, enabling traceability and consistency across both directions.

---

Workshop Structure

Code to Figma (C2F) Workshop

Location: code-to-figma/

Purpose: Send code implementations to Figma for design review, documentation, and visual iteration

Workflow Steps: 1. Connection Check - Verify html.to.design MCP server 2. Identify Type - Determine export scenario (prototype page, design system component, or frontend view) 3. Prepare Specifications - Find or create OBJECT IDs for proper Figma layer naming 4. Generate & Validate - Create Figma-compatible HTML with validation 5. Send to Figma - Execute export and verify success

Key Features:

• Specification-driven OBJECT ID naming
• Three export scenarios with specific ID patterns
• Automated validation before export
• Reverse engineering for missing specifications

---

Figma to Code (F2C) Workshop

Location: figma-to-code/

Status: Coming Soon

Purpose: Import design specifications from Figma to generate or update code implementations

Planned Workflow: 1. Connection Check - Verify Figma Desktop MCP server 2. Select Figma Node - Identify what to import 3. Extract Design Specs - Get colors, spacing, typography, layout 4. Generate/Update Code - Create or update components 5. Verify Implementation - Compare code output to Figma design

---

Reference Documentation

Location: reference/

Supporting documentation for Figma integration workflows:

1. `figma-designer-guide.md` - Guide for designers creating components in Figma 2. `mcp-server-integration.md` - MCP server setup and configuration 3. `tools-reference.md` - Reference for Figma MCP tools and parameters 4. `when-to-extract-decision-guide.md` - Decision tree for when to use Figma integration 5. `figma-mcp-integration.md` - Technical documentation about MCP integration 6. `prototype-to-figma-workflow.md` - Iterative refinement workflow documentation

---

Folder Structure

wds-6-asset-generation/
├── code-to-figma/              # C2F Workshop
│   ├── workflow.md
│   └── steps/
│       ├── step-01-connection-check.md
│       ├── step-02-identify-export-type.md
│       ├── step-03-prepare-specifications.md
│       ├── step-04-generate-validate.md
│       ├── step-05-execute-export.md
│       └── [substeps folders]
│
├── figma-to-code/              # F2C Workshop (coming soon)
│   └── README.md
│
├── reference/                  # Reference documentation
│   ├── figma-designer-guide.md
│   ├── mcp-server-integration.md
│   ├── tools-reference.md
│   ├── when-to-extract-decision-guide.md
│   ├── figma-mcp-integration.md
│   └── prototype-to-figma-workflow.md
│
└── INTEGRATION-SUMMARY.md      # This file

---

Core Concepts

The Missing Dimension

Before: WDS created specifications and functional prototypes, but visual design creation was manual

After: WDS now supports iterative visual refinement through Figma extraction

Design System Evolution

Key Principle: Design system grows organically as prototypes are built

Process: 1. Create prototype with existing design system (may look basic) 2. Extract to Figma when gaps identified 3. Refine visuals and create missing components 4. Update design system with new tokens/components 5. Re-render prototype with enhanced design system 6. Iterate until polished

When to Extract

Extract when:

• Design system is incomplete
• Prototype needs visual polish
• New components required
• Stakeholder presentation needed

Don't extract when:

• Design system covers all needs
• Prototype looks sufficient
• Rapid iteration more important
• Early exploration phase

---

Tool Integration

html.to.design

Role: Convert HTML prototypes to Figma for visual refinement

Process: 1. Upload HTML prototype 2. Configure conversion options 3. Import to Figma 4. Refine design 5. Extract design system updates

Benefits:

• Preserves layout structure
• Converts CSS to Figma styles
• Maintains element hierarchy
• Enables visual refinement

Area Tag System

Role: Precise region mapping for image-based prototypes

Usage:

• Map clickable regions on images
• Include Object IDs for traceability
• Extract coordinates via dev mode
• Document region mappings

Integration:

• Works with dev-mode.js component
• Supports image-based prototypes
• Enables precise click mapping

Dev Mode Component

Role: Extract Object IDs and area coordinates from prototypes

Features:

• Shift + Click to copy Object IDs
• Visual highlights
• Area tag detection
• Coordinate extraction

Benefit: Maintains traceability through Figma extraction

---

Workflow Integration

Phase 4: UX Design

Updated Step 4D (Prototype):

• Create functional prototype
• Test functionality
• NEW: Assess visual quality
• NEW: Option to extract to Figma
• Continue to PRD update

Phase 7: Design System

New Workflow Branch:

• Existing: Component specification → Design system
• Existing: Figma manual creation → Design system
• NEW: Prototype extraction → Figma → Design system

Iteration Loop

Complete Cycle:

1. Sketch (concept)
2. Specification (detailed)
3. Prototype (functional)
4. Figma extraction (if needed)
5. Visual refinement
6. Design system update
7. Re-render prototype
8. Assess → Iterate or Complete

---

Benefits

For Designers

Flexibility:

• Start with functional prototypes
• Refine visuals when needed
• Iterate incrementally
• Build design system organically

Efficiency:

• Don't need complete design system upfront
• Extract only when necessary
• Reuse refined components
• Reduce rework

For Teams

Collaboration:

• Shared design language
• Clear handoff process
• Bidirectional sync
• Maintained traceability

Quality:

• Polished final products
• Consistent design system
• Professional visuals
• Stakeholder-ready

For Projects

Speed:

• Faster initial prototypes
• Iterative refinement
• Parallel work streams
• Reduced bottlenecks

Flexibility:

• Adapt to changing requirements
• Grow design system as needed
• Balance speed and polish
• Ship working products

---

Public Release Readiness

Documentation Status

✅ Complete:

• Prototype-to-Figma workflow
• Decision guide
• Tools reference
• Phase 4D integration
• Phase 7 README update

✅ Tested:

• Workflow logic validated
• Integration points confirmed
• Decision framework practical
• Tool capabilities verified

✅ Ready for:

• Public documentation
• User testing
• Team adoption
• Production use

What's Not Included

Out of Scope:

• MagicPatterns integration (not needed with html.to.design)
• Automated extraction (manual process documented)
• Real-time sync (manual iteration cycle)

Future Enhancements:

• Automated design token extraction
• Figma plugin for WDS
• Real-time bidirectional sync
• AI-powered component matching

---

Migration Notes

For Existing WDS Users

No Breaking Changes:

• Existing workflows continue to work
• New workflow is optional
• Backward compatible
• Incremental adoption

How to Adopt: 1. Read prototype-to-Figma workflow 2. Try with one prototype 3. Refine in Figma 4. Update design system 5. Re-render and compare 6. Expand to more pages

For New WDS Users

Recommended Approach: 1. Start with first page 2. Create basic prototype 3. Extract to Figma 4. Build design system foundation 5. Use for subsequent pages 6. Extract only when gaps found

---

Success Metrics

Quality Indicators

✅ Prototypes look polished ✅ Design system is comprehensive ✅ Figma and code are in sync ✅ Object IDs maintained throughout ✅ Iterations are productive ✅ Team aligned on visual direction

Efficiency Indicators

✅ Fewer refinement cycles needed ✅ Design system grows organically ✅ Reusable components identified ✅ Faster subsequent prototypes ✅ Reduced rework

---

Next Steps

For Documentation

1. ✅ Core workflow documentation complete 2. ✅ Decision guides created 3. ✅ Tools reference documented 4. ✅ Integration points updated 5. 🔄 Session logs cleanup (in progress) 6. ⏳ User testing and feedback 7. ⏳ Video tutorials (future) 8. ⏳ Example projects (future)

For Implementation

1. ✅ Workflow files created 2. ✅ Phase 4D updated 3. ✅ Phase 7 updated 4. ⏳ Test with real projects 5. ⏳ Gather user feedback 6. ⏳ Refine based on usage 7. ⏳ Create example case studies

---

Key Takeaways

The Complete WDS Flow

Concept-First Approach: 1. Sketch and specification are source of truth 2. Generate functional prototypes from specs 3. Apply design system (may be incomplete initially) 4. Extract to Figma when visual refinement needed 5. Refine design and extend design system 6. Re-render with enhanced design system 7. Iterate until polished

Design System Philosophy

Just-In-Time Design Definitions:

• Don't need complete design system upfront
• Build definitions as needed
• Extract from working prototypes
• Grow organically with product
• Reduce upfront investment

Iterative Refinement

Balanced Approach:

• Functional first, polish later
• Extract strategically, not automatically
• Iterate incrementally
• Ship working products
• Balance speed and quality

---

Contact and Support

Documentation Location:

• workflows/wds-6-asset-generation/wds-6-asset-generation/

Related Documentation:

• Phase 4: UX Design workflows
• Phase 7: Design System workflows
• Interactive Prototypes guides
• Figma Integration guides

Questions or Issues:

• Review decision guide for common scenarios
• Check tools reference for troubleshooting
• Follow workflow documentation step-by-step
• Test with simple prototype first

---

This integration completes the WDS design workflow, enabling teams to create polished, production-ready designs through iterative refinement of functional prototypes.

---

Version History

v1.0 - January 8, 2026

• Initial release
• Prototype-to-Figma workflow
• Decision guide
• Tools reference
• Phase 4D and Phase 7 integration

Future Versions:

• User feedback integration
• Enhanced automation
• Additional tool integrations
• Example case studies

Figma MCP Integration for WDS

Purpose: Technical guide for integrating Figma with WDS using Model Context Protocol (MCP).

Audience: AI agents, developers, technical designers

---

Overview

Figma MCP enables:

• Reading component specifications from Figma
• Extracting design tokens
• Generating WDS component specifications
• Maintaining Figma ↔ WDS sync

---

MCP Server Setup

Prerequisites

• Figma API access token
• MCP server configured
• WDS project initialized
• Design system mode set to "custom"

---

Configuration

Add to MCP configuration:

{
  "mcpServers": {
    "figma": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-figma"],
      "env": {
        "FIGMA_PERSONAL_ACCESS_TOKEN": "your-figma-token"
      }
    }
  }
}

Get Figma API token:

1. Go to Figma → Settings → Account 2. Scroll to "Personal access tokens" 3. Click "Generate new token" 4. Copy token and add to configuration

---

MCP Operations

1. Read Figma Component

Purpose: Extract component data from Figma

Input:

• Figma file ID
• Node ID
• Or component name

Output:

• Component structure
• Variants
• Properties
• Design tokens used

Example:

Agent: Read Figma component Button/Primary

MCP Response:
{
  "name": "Button/Primary [btn-001]",
  "type": "COMPONENT_SET",
  "variants": [
    {
      "name": "Type=Primary, Size=Medium, State=Default",
      "properties": {
        "Type": "Primary",
        "Size": "Medium",
        "State": "Default"
      },
      "styles": {
        "background": "primary/600",
        "padding": "16px 12px",
        "borderRadius": "8px"
      }
    },
    // ... more variants
  ],
  "description": "Button Primary [btn-001]...",
  "nodeId": "456:789"
}

---

2. Extract Design Tokens

Purpose: Get design token values from Figma

Input:

• Figma file ID
• Token type (colors, typography, spacing)

Output:

• Token definitions
• Token values
• Token mappings

Example:

Agent: Extract color tokens from Figma

MCP Response:
{
  "colors": {
    "primary/50": "#eff6ff",
    "primary/500": "#3b82f6",
    "primary/600": "#2563eb",
    "gray/900": "#111827"
  }
}

---

3. Get Component Node ID

Purpose: Find Figma node ID for component

Input:

• Component name or WDS component ID

Output:

• Figma node ID
• File ID
• Full Figma URL

Example:

Agent: Get node ID for Button [btn-001]

MCP Response:
{
  "componentId": "btn-001",
  "fileId": "abc123",
  "nodeId": "456:789",
  "url": "figma://file/abc123/node/456:789"
}

---

4. List Components

Purpose: Get all components in Figma file

Input:

• Figma file ID
• Optional: filter by type

Output:

• List of components
• Component names
• Node IDs

Example:

Agent: List all button components

MCP Response:
{
  "components": [
    {
      "name": "Button/Primary [btn-001]",
      "nodeId": "456:789",
      "type": "COMPONENT_SET"
    },
    {
      "name": "Button/Secondary [btn-001]",
      "nodeId": "456:790",
      "type": "COMPONENT_SET"
    }
  ]
}

---

Sync Workflows

Figma → WDS Sync

When: Component created or updated in Figma

Process:

Step 1: Detect Change

Designer updates Button/Primary in Figma
Designer notifies WDS system
Or: Automated webhook triggers sync

Step 2: Read Component

Agent: Read Figma component Button/Primary [btn-001]

MCP reads:
- Component structure
- All variants
- All states
- Properties
- Design tokens
- Description

Step 3: Parse Component Data

Agent extracts:
- Component type: Button
- WDS ID: btn-001
- Variants: primary, secondary, ghost
- States: default, hover, active, disabled, loading
- Sizes: small, medium, large
- Design tokens: primary/600, spacing/4, radius/md

Step 4: Generate WDS Specification

Agent creates/updates:
D-Design-System/components/button.md

Using template: component.template.md
Filling in:
- Component name and ID
- Variants from Figma
- States from Figma
- Styling from design tokens
- Description from Figma

Step 5: Update Mappings

Agent updates:
D-Design-System/figma-mappings.md

Adds/updates:
Button [btn-001] → figma://file/abc123/node/456:789

Step 6: Verify and Confirm

Agent presents generated spec to designer
Designer reviews and confirms
Spec is committed to repository

---

WDS → Figma Notification

When: WDS specification updated

Process:

Step 1: Detect Change

WDS specification updated
Git commit triggers notification

Step 2: Identify Figma Component

Agent reads figma-mappings.md
Finds: Button [btn-001] → figma://file/abc123/node/456:789

Step 3: Notify Designer

Agent creates notification:
"Button [btn-001] specification updated in WDS.
Please review and update Figma component if needed.

Changes:
- Added new loading state
- Updated hover animation
- Modified padding values

Figma component: [Link to Figma]"

Step 4: Designer Updates Figma

Designer reviews changes
Updates Figma component
Confirms sync complete

Note: Full WDS → Figma automation requires Figma API write access (currently read-only for MCP).

---

Component Specification Generation

Template-Based Generation

Agent uses component template:

Input:

Figma component data:
{
  "name": "Button/Primary [btn-001]",
  "variants": [...],
  "states": [...],
  "tokens": {...},
  "description": "..."
}

Template: templates/component.template.md

Output: D-Design-System/components/button.md

Process:

1. Load component template 2. Fill in component name and ID 3. Extract and format variants 4. Extract and format states 5. Map design tokens to WDS tokens 6. Add styling specifications 7. Include description and usage 8. Generate accessibility notes 9. Add version history 10. Save to design system folder

---

Token Mapping

Figma variables → WDS tokens:

Agent maps:

Figma: primary/600 → WDS: color-primary-600
Figma: spacing/4 → WDS: spacing-4
Figma: Text/Body → WDS: text-body
Figma: shadow/sm → WDS: shadow-sm

Mapping rules:

• Figma collection/variable → WDS category-name-value
• Maintain semantic meaning
• Consistent naming across systems
• Document custom mappings

---

Error Handling

Component Not Found

Error: Figma component doesn't exist

Agent response:

⚠️ Component not found in Figma

Component: Button/Primary [btn-001]
File ID: abc123
Node ID: 456:789

Possible causes:
- Component deleted in Figma
- Node ID changed
- File ID incorrect
- Access permissions

Actions:
1. Verify component exists in Figma
2. Update node ID in figma-mappings.md
3. Re-sync component

---

Missing WDS Component ID

Error: Figma component has no WDS ID in description

Agent response:

⚠️ WDS Component ID missing

Component: Button/Primary
Figma node: 456:789

Please add WDS component ID to Figma description:
Format: [component-id]
Example: Button/Primary [btn-001]

After adding ID, re-sync component.

---

Token Mapping Failure

Error: Can't map Figma variable to WDS token

Agent response:

⚠️ Token mapping failed

Figma variable: custom-blue-500
No matching WDS token found

Options:
1. Create new WDS token: color-custom-blue-500
2. Map to existing token: color-primary-500
3. Add custom mapping rule

Your choice:

---

Sync Conflict

Error: Figma and WDS have different versions

Agent response:

⚠️ Sync conflict detected

Component: Button [btn-001]

Figma version:
- Last updated: 2024-12-15
- Changes: Added loading state

WDS version:
- Last updated: 2024-12-14
- Changes: Updated hover animation

Options:
1. Figma wins (overwrite WDS)
2. WDS wins (notify designer)
3. Manual merge (review both)

Your choice:

---

Best Practices

For AI Agents

DO ✅

• Always check for WDS component ID in Figma
• Verify token mappings before generating specs
• Present generated specs for designer review
• Update figma-mappings.md after sync
• Document sync operations in version history

DON'T ❌

• Don't overwrite WDS specs without confirmation
• Don't create components without designer approval
• Don't skip token mapping validation
• Don't ignore sync conflicts
• Don't forget to update mappings

---

For Designers

DO ✅

• Add WDS component ID to all Figma components
• Use design tokens (variables) consistently
• Document component changes
• Notify system when updating components
• Review generated specs before committing

DON'T ❌

• Don't use hardcoded values
• Don't skip component descriptions
• Don't forget to sync after changes
• Don't detach component instances
• Don't change component IDs

---

Integration Points

Phase 4: UX Design

When component is specified in Phase 4:

1. Designer creates sketch 2. Agent specifies component 3. Design system router checks for similar components 4. If new component needed:

• Designer creates in Figma
• MCP reads from Figma
• Spec generated automatically

---

Phase 5: Design System

When component is added to design system:

1. Component specification complete 2. Agent checks: Figma component exists? 3. If yes:

• MCP reads Figma component
• Extracts styling details
• Updates WDS spec with Figma data

4. If no:

• Designer creates in Figma
• MCP syncs to WDS

---

Command Reference

Read Component

Agent: Read Figma component [component-name]
MCP: Returns component data

Extract Tokens

Agent: Extract [token-type] tokens from Figma
MCP: Returns token definitions

Get Node ID

Agent: Get Figma node ID for [component-id]
MCP: Returns node ID and URL

List Components

Agent: List Figma components [optional: filter]
MCP: Returns component list

Sync Component

Agent: Sync Figma component [component-name] to WDS
MCP: Reads component, generates spec, updates mappings

---

Troubleshooting

MCP Server Not Responding

Check:

• MCP server is running
• Figma API token is valid
• Network connection is active
• File ID and node ID are correct

---

Invalid API Token

Error: 403 Forbidden

Solution:

1. Generate new Figma API token 2. Update MCP configuration 3. Restart MCP server 4. Retry operation

---

Rate Limiting

Error: 429 Too Many Requests

Solution:

• Wait before retrying
• Batch operations when possible
• Cache component data
• Reduce sync frequency

---

Future Enhancements

Planned features:

• Automated sync on Figma changes (webhooks)
• Bidirectional sync (WDS → Figma write)
• Batch component import
• Design token extraction automation
• Component usage tracking from Figma
• Visual diff for sync conflicts

---

This MCP integration enables seamless Figma ↔ WDS synchronization while maintaining designer control and design system consistency.

Figma Plugin Setup Guide

Reference for setting up the html.to.design plugin and MCP server connection.

---

1. Plugin Installation

Install the html.to.design plugin in Figma:

1. Open Figma (desktop app or web: figma.com) 2. Click on your profile icon (top-right corner) 3. Select "Community" from the menu 4. In the search bar, type "html.to.design" 5. Click on the "html.to.design" plugin result 6. Click "Install" or "Try it out" button 7. Plugin is now installed

---

2. Activate Plugin

Activate the plugin in your Figma file:

1. Open any Figma file (or create a new one for testing) 2. Right-click anywhere on the canvas 3. Select "Plugins" > "html.to.design" OR use the menu: Plugins > html.to.design 4. The plugin panel should appear on the right side of your screen 5. Keep the plugin panel open during the export process

---

3. Verify MCP Configuration

Confirm that the html.to.design MCP server is configured in the IDE:

1. Open your IDE Settings/Preferences 2. Navigate to the MCP Servers section 3. Look for "html.to.design" in the server list

If configured: MCP server is ready. Run a test export to verify connection.

If not configured: The html.to.design MCP server needs to be added to your IDE configuration. Refer to your IDE's MCP server documentation for configuration steps. The server should connect to the html.to.design plugin running in Figma.

---

Troubleshooting

Figma Specification Preparation

Reference for analyzing code and creating specifications with OBJECT IDs for Figma export.

---

1. Analyze Code

Extract component information from code to create specifications:

Component Structure:

• Identify component name and file location
• Map parent/child relationships
• Note component hierarchy

Props & States:

• Extract available props
• Identify state variations (hover, active, disabled, focus, etc.)
• Note conditional rendering logic

Visual Properties:

• Extract CSS classes used
• Note inline styles
• Identify design tokens/CSS variables referenced
• Document colors, spacing, typography

Content:

• Extract text content
• Note language variations (if i18n present)
• Identify dynamic vs. static content

Behavior:

• Document event handlers
• Note interactive elements
• Identify navigation/routing

---

2. Generate OBJECT IDs

Create OBJECT IDs following project naming conventions. Determine the pattern by analyzing existing IDs in specifications:

Pattern A - Page-based:

• Format: {page}-{section}-{element}
• Example: start-hero-cta, start-message-headline
• Use when: Exporting full pages or page sections

Pattern B - Component-based:

• Format: {component}-{variant}-{state}
• Example: btn-cta-primary-hover, input-text-disabled
• Use when: Exporting design system components

Pattern C - Hierarchical:

• Format: {parent}-{child}-{grandchild}
• Example: header-nav-menu-item, footer-social-icon-twitter
• Use when: Exporting component blocks with nested elements

For each component without OBJECT ID: 1. Identify component type and context 2. Apply naming pattern 3. Ensure uniqueness 4. Add state suffix if applicable

---

3. Create Specification Document

Generate a specification document with the generated OBJECT IDs.

Determine location:

• Design system component: docs/D-Design-System/03-Atomic-Components/{category}/
• Page component: docs/C-UX-Scenarios/{scenario}/{page}/
• Shared component: docs/D-Design-System/04-Molecules/ or 05-Organisms/

Specification structure:

# {Component/Page Name}

**OBJECT ID**: `{primary-object-id}`

## Purpose
{Brief description from code analysis}

## Structure
- **HTML Tag**: `<{tag}>`
- **CSS Class**: `.{class-name}`
- **Component File**: `{file-path}`
- **OBJECT ID**: `{object-id}`

## Visual Style
- **Typography**: {font-family}, {size}, {weight}, {color}
- **Colors**: Background, Border, Text
- **Spacing**: Padding, Margin
- **Layout**: {display}, {positioning}

## States
### {State Name}
- **OBJECT ID**: `{component-id-state}`
- **Visual Changes**: {description}
- **Trigger**: {user action or condition}

## Behavior
{Interactive behavior description}

## Content
- **EN**: "{english-content}"
- **SE**: "{swedish-content}" (if applicable)

---

4. Review with User

Present the generated specification for approval:

Present:

• Location of specification document
• Generated OBJECT IDs with descriptions
• Naming pattern used
• Component coverage count

User options: 1. Approve and proceed - Use these OBJECT IDs for export 2. Modify IDs - Adjust naming before proceeding 3. Review document - See full specification first

Once approved, proceed to HTML generation with finalized OBJECT IDs.

MCP Server Integration for Prototype-to-Figma Workflow

Purpose: Enable precise component injection from HTML prototypes into Figma using MCP server.

Key Advantage: Component-level precision - inject exactly what needs refinement, not entire pages.

---

Overview

The MCP (Model Context Protocol) server integration enables WDS to communicate directly with Figma, allowing:

• Selective component extraction from HTML prototypes
• Direct injection into specific Figma files/pages
• Object ID preservation for traceability
• Automated mapping between code and design
• Batch operations for multiple components

---

Architecture

Component Flow

HTML Prototype (with Object IDs)
    ↓
WDS Agent identifies components to extract
    ↓
MCP Server reads HTML/CSS for selected components
    ↓
Converts to Figma-compatible format
    ↓
Injects into target Figma file/page
    ↓
Designer refines in Figma
    ↓
MCP Server reads refined design
    ↓
Updates WDS Design System
    ↓
Re-render prototype with enhanced design system

MCP Server Role

Bidirectional Bridge:

• WDS → Figma: Inject components for refinement
• Figma → WDS: Read refined components back

Capabilities:

• Read HTML/CSS structure
• Convert to Figma nodes
• Create frames, auto-layout, text layers
• Apply styling (colors, spacing, typography)
• Preserve Object IDs in layer names
• Read Figma component definitions
• Extract design tokens
• Map component variants

---

Commands

Extract Component to Figma

Command:

wds figma inject <component-id> [options]

Parameters:

• component-id: Object ID of component to extract (e.g., "btn-login-submit")
• --file <file-id>: Target Figma file ID
• --page <page-name>: Target page within Figma file
• --position <x,y>: Position to inject component (optional)
• --batch <file>: Extract multiple components from list

Example:

# Inject single component (page name matches specification)
wds figma inject btn-login-submit --file abc123 --page "01-Customer-Onboarding / 1.2-Sign-In"

# Inject multiple components to same scenario/page
wds figma inject --batch components-to-refine.txt --file abc123 --page "01-Customer-Onboarding / 1.2-Sign-In"

Page Naming Convention:

• Format: [Scenario-Number]-[Scenario-Name] / [Page-Number]-[Page-Name]
• Example: 01-Customer-Onboarding / 1.2-Sign-In
• Matches WDS specification structure in docs/C-UX-Scenarios/
• Maintains traceability from spec → prototype → Figma

Output:

✓ Component btn-login-submit extracted from prototype
✓ Converted to Figma format
✓ Injected into Figma file abc123, page "Login Components"
✓ Object ID preserved in layer name
✓ Position: (100, 200)

---

Extract Section to Figma

Command:

wds figma inject-section <section-name> [options]

Parameters:

• section-name: Section identifier from specification
• --file <file-id>: Target Figma file ID
• --page <page-name>: Target page within Figma file
• --include-children: Include all child components

Example:

# Inject entire login form section
wds figma inject-section login-form --file abc123 --include-children

---

Read Refined Component from Figma

Command:

wds figma read <component-id> [options]

Parameters:

• component-id: Object ID of component in Figma
• --file <file-id>: Source Figma file ID
• --extract-tokens: Extract design tokens
• --update-design-system: Automatically update design system

Example:

# Read refined component and update design system
wds figma read btn-login-submit --file abc123 --extract-tokens --update-design-system

Output:

✓ Component btn-login-submit read from Figma
✓ Design tokens extracted:
  - Background: primary.600
  - Text: neutral.50
  - Padding: spacing.md spacing.lg
  - Border-radius: radius.md
✓ Design system updated: D-Design-System/components/button.md

---

Batch Operations

Command:

wds figma batch <operation> --list <file>

Operations:

• inject: Inject multiple components
• read: Read multiple refined components
• sync: Bidirectional sync

Example batch file (components-to-refine.txt):

btn-login-submit
btn-signup-cta
input-email
input-password
link-forgot-password

Command:

wds figma batch inject --list components-to-refine.txt --file abc123

---

Workflow Integration

Phase 4D: After Prototype Creation

Agent workflow:

1. Prototype created and tested
2. Visual quality assessment
3. If needs refinement:
   a. Identify components that need polish
   b. Generate component list
   c. Offer to inject to Figma
   d. Execute MCP injection
   e. Provide Figma link to designer

Agent dialogue:

I've identified 5 components that could benefit from visual refinement:
- Login button (btn-login-submit)
- Email input (input-email)
- Password input (input-password)
- Forgot password link (link-forgot-password)
- Sign up CTA (btn-signup-cta)

Would you like me to inject these into Figma for refinement?

[Y] Yes, inject all
[S] Select specific components
[N] No, continue as-is

Choice:

---

Phase 5: Reading Refined Components

Agent workflow:

1. Designer completes refinement in Figma
2. Designer notifies agent
3. Agent reads refined components via MCP
4. Extracts design tokens
5. Updates design system
6. Offers to re-render prototype

Agent dialogue:

I see you've refined the components in Figma. Let me read them back:

Reading btn-login-submit... ✓
Reading input-email... ✓
Reading input-password... ✓
Reading link-forgot-password... ✓
Reading btn-signup-cta... ✓

Design tokens extracted:
- 3 new colors added to palette
- 2 new spacing values defined
- 1 new typography style created

Design system updated:
- Button component enhanced
- Input component refined
- Link component created

Would you like me to re-render the prototype with these improvements?

[Y] Yes, re-render now
[R] Review changes first
[L] Re-render later

Choice:

---

MCP Server Configuration

Setup

1. Install MCP Server

npm install -g @wds/figma-mcp-server

2. Configure Figma API Access

# Set Figma personal access token
export FIGMA_ACCESS_TOKEN="your-token-here"

# Or in .env file
FIGMA_ACCESS_TOKEN=your-token-here

3. Initialize MCP Server

wds figma init

4. Test Connection

wds figma test-connection

---

Configuration File

Location: .wds/figma-mcp-config.yaml

figma:
  access_token: ${FIGMA_ACCESS_TOKEN}
  default_file_id: "abc123def456"
  default_page: "WDS Components"
  
extraction:
  preserve_object_ids: true
  extract_design_tokens: true
  convert_to_components: true
  maintain_hierarchy: true
  
injection:
  auto_layout: true
  responsive_constraints: true
  component_naming: "object-id"
  page_naming: "scenario-page"  # Matches WDS spec structure
  
sync:
  bidirectional: true
  auto_update_design_system: false
  conflict_resolution: "manual"

naming_conventions:
  page_format: "{scenario-number}-{scenario-name} / {page-number}-{page-name}"
  example: "01-Customer-Onboarding / 1.2-Sign-In"
  source: "docs/C-UX-Scenarios/"

---

Figma File Organization

Recommended Structure

Figma file should mirror WDS specification structure:

[Project Name] Design Refinement
├── 01-Customer-Onboarding/
│   ├── 1.1-Start-Page
│   ├── 1.2-Sign-In
│   ├── 1.3-Sign-Up
│   └── ...
├── 02-Family-Management/
│   ├── 2.1-Family-Dashboard
│   ├── 2.2-Add-Member
│   └── ...
└── Components/
    ├── Buttons
    ├── Inputs
    └── Cards

Benefits:

• Direct mapping to WDS specifications
• Easy to locate components by scenario/page
• Maintains project structure consistency
• Clear handoff to developers

Page Naming:

• Use exact scenario and page numbers from specs
• Format: [Number]-[Name] (e.g., 1.2-Sign-In)
• Matches folder structure in docs/C-UX-Scenarios/

---

Component Selection Strategies

Strategy 1: Individual Components

When to use: Specific components need refinement

Process:

# Inject one component at a time
wds figma inject btn-login-submit --file abc123
wds figma inject input-email --file abc123

Advantages:

• Precise control
• Focused refinement
• Easy to track changes

---

Strategy 2: Component Groups

When to use: Related components need consistent refinement

Process:

# Create component group file
echo "btn-login-submit
btn-signup-cta
btn-cancel" > login-buttons.txt

# Inject group
wds figma batch inject --list login-buttons.txt --file abc123

Advantages:

• Consistent design decisions
• Efficient batch processing
• Related components together

---

Strategy 3: Section-Based

When to use: Entire section needs refinement

Process:

# Inject entire section with all components
wds figma inject-section login-form --file abc123 --include-children

Advantages:

• Complete context
• Layout refinement
• Holistic design decisions

---

Strategy 4: Iterative Refinement

When to use: Multiple refinement cycles needed

Process:

# Iteration 1: Inject basic components
wds figma inject btn-login-submit --file abc123

# Designer refines in Figma

# Read back refined version
wds figma read btn-login-submit --file abc123 --update-design-system

# Iteration 2: Re-inject with design system updates
wds figma inject btn-login-submit --file abc123 --version 2

# Continue until satisfied

Advantages:

• Incremental improvement
• Design system grows with each iteration
• Reduced rework

---

Object ID Mapping

Preservation Strategy

In HTML Prototype:

<button data-object-id="btn-login-submit" class="btn-primary">
  Log In
</button>

In Figma (after injection):

Layer name: "btn-login-submit"
Description: "Object ID: btn-login-submit"

In Design System:

# D-Design-System/components/button.md
Button Component [btn-001]

Object ID Mapping:
- btn-login-submit → Login page submit button
- btn-signup-cta → Signup page CTA button

---

Traceability

Benefits:

• Track component from spec → prototype → Figma → design system
• Identify which Figma components map to which code elements
• Update specific components without affecting others
• Maintain consistency across iterations

Workflow:

Specification: "Login button" (conceptual)
    ↓
Prototype: data-object-id="btn-login-submit" (code)
    ↓
Figma: Layer "btn-login-submit" (design)
    ↓
Design System: Button.primary [btn-001] (documentation)
    ↓
Re-rendered Prototype: class="btn-primary" (enhanced code)

---

Design Token Extraction

Automatic Token Detection

MCP Server analyzes:

• Colors used in component
• Spacing/padding values
• Typography styles
• Border radius
• Shadows/effects

Example extraction:

From Figma component:

Background: #2563eb
Text: #ffffff
Padding: 12px 16px
Border-radius: 8px
Font: Inter, 16px, 600

To Design Tokens:

colors:
  primary:
    600: "#2563eb"
  neutral:
    50: "#ffffff"

spacing:
  md: 12px
  lg: 16px

radius:
  md: 8px

typography:
  button:
    font-family: "Inter"
    font-size: 16px
    font-weight: 600

---

Token Mapping

MCP Server can:

• Detect similar colors and suggest token names
• Identify spacing patterns
• Recognize typography scales
• Propose token structure

Agent dialogue:

I've analyzed the refined button component and detected these values:

Colors:
- Background: #2563eb → Suggest: primary.600
- Text: #ffffff → Suggest: neutral.50

Spacing:
- Padding horizontal: 16px → Suggest: spacing.lg
- Padding vertical: 12px → Suggest: spacing.md

Would you like to:
[A] Accept all suggestions
[C] Customize token names
[R] Review each token

Choice:

---

Error Handling

Common Issues

Issue: Component not found in prototype

Error: Component with Object ID "btn-login-submit" not found in prototype

Solution:
- Verify Object ID exists in HTML
- Check data-object-id attribute
- Ensure prototype file is current

Issue: Figma file access denied

Error: Cannot access Figma file abc123

Solution:
- Verify Figma access token
- Check file permissions
- Ensure file ID is correct

Issue: Component structure too complex

Warning: Component has deeply nested structure (8 levels)
This may not convert cleanly to Figma

Suggestion:
- Simplify HTML structure
- Extract sub-components separately
- Use flatter hierarchy

---

Conflict Resolution

Scenario: Component exists in both prototype and Figma

Options:

Component btn-login-submit already exists in Figma.

[O] Overwrite with new version
[M] Merge changes
[V] Create new version
[S] Skip this component

Choice:

Merge strategy:

• Preserve Figma refinements
• Apply new structural changes
• Prompt for conflicts

---

Best Practices

DO ✅

1. Use Object IDs consistently

<!-- Good: Clear, consistent Object IDs -->
<button data-object-id="btn-login-submit">
<input data-object-id="input-email">
<a data-object-id="link-forgot-password">

2. Extract components incrementally

# Start with critical components
wds figma inject btn-login-submit --file abc123

# Then expand to related components
wds figma inject input-email --file abc123

3. Document extraction decisions

# extraction-log.md

## 2026-01-08: Login Page Components

Extracted to Figma:
- btn-login-submit: Needs brand color refinement
- input-email: Needs focus state design
- input-password: Needs show/hide icon

Skipped:
- link-terms: Standard link, no refinement needed

4. Sync regularly

# After designer completes refinement
wds figma read btn-login-submit --file abc123 --update-design-system

# Re-render to verify
wds prototype render login-page --with-design-system

---

DON'T ❌

1. Don't inject entire pages

# Avoid: Too broad, loses precision
wds figma inject-page login --file abc123

# Better: Specific components
wds figma inject btn-login-submit --file abc123

2. Don't skip Object ID mapping

<!-- Avoid: No traceability -->
<button class="btn-primary">

<!-- Better: Clear Object ID -->
<button data-object-id="btn-login-submit" class="btn-primary">

3. Don't forget to read back

# Incomplete workflow
wds figma inject btn-login-submit --file abc123
# Designer refines...
# ❌ Never read back refined version

# Complete workflow
wds figma inject btn-login-submit --file abc123
# Designer refines...
wds figma read btn-login-submit --file abc123 ✅

---

Advanced Features

Variant Detection

MCP Server can detect component variants:

Analyzing button components in Figma...

Found 3 button variants:
- btn-login-submit (primary variant)
- btn-cancel (secondary variant)
- btn-delete (danger variant)

Suggest creating Button component with variants?
[Y/N]:

---

State Extraction

MCP Server extracts component states:

Reading btn-login-submit from Figma...

States detected:
- Default: #2563eb background
- Hover: #1d4ed8 background (darker)
- Active: #1e40af background (darkest)
- Disabled: #9ca3af background (gray)

Add all states to design system?
[Y/N]:

---

Responsive Constraints

MCP Server preserves responsive behavior:

Component has responsive constraints:
- Width: Fill container
- Height: Hug contents
- Min width: 120px
- Max width: 400px

Apply constraints in re-rendered prototype?
[Y/N]:

---

Integration with Existing Figma Workflow

Compatibility

Works with existing Figma → WDS workflow:

Workflow A (Existing): Designer creates in Figma → MCP reads → WDS spec Workflow B (New): Prototype → MCP injects → Figma → MCP reads → WDS spec

Both workflows use same MCP server, same token extraction, same design system updates.

---

Unified Design System

All paths lead to design system:

Path 1: Manual Figma design → MCP → Design System
Path 2: Prototype → MCP → Figma → MCP → Design System
Path 3: Specification → Prototype → Design System (no Figma)

Result: Single source of truth in Design System

---

Performance Considerations

Batch Processing

Efficient for multiple components:

# Sequential (slower)
wds figma inject btn-1 --file abc123
wds figma inject btn-2 --file abc123
wds figma inject btn-3 --file abc123

# Batch (faster)
wds figma batch inject --list buttons.txt --file abc123

Performance:

• Sequential: ~5 seconds per component
• Batch: ~2 seconds per component (parallel processing)

---

Caching

MCP Server caches:

• Figma file structure
• Component definitions
• Design tokens
• Object ID mappings

Benefits:

• Faster subsequent operations
• Reduced API calls
• Offline capability (limited)

---

Security

API Token Management

Best practices:

# Never commit tokens to git
echo "FIGMA_ACCESS_TOKEN=*" >> .gitignore

# Use environment variables
export FIGMA_ACCESS_TOKEN="token"

# Or use secure credential storage
wds figma set-token --secure

---

Access Control

Figma file permissions:

• MCP server requires edit access to inject components
• Read-only access sufficient for reading refined components
• Consider separate files for WDS injection vs production design

---

Troubleshooting

Debug Mode

# Enable verbose logging
wds figma inject btn-login-submit --file abc123 --debug

# Output shows:
# - HTML parsing steps
# - Figma API calls
# - Conversion process
# - Injection details
# - Error stack traces

---

Validation

# Validate before injection
wds figma validate btn-login-submit

# Checks:
# - Object ID exists
# - HTML structure valid
# - CSS parseable
# - Figma file accessible

---

Summary

MCP Server integration enables:

✅ Precision: Inject specific components, not entire pages ✅ Automation: Automated Object ID mapping and token extraction ✅ Bidirectional: Prototype → Figma → Design System → Prototype ✅ Traceability: Maintain Object ID connections throughout ✅ Efficiency: Batch operations and caching ✅ Integration: Works with existing Figma workflows

Result: Seamless, precise component refinement workflow that maintains traceability and enables iterative design improvement.

---

This MCP server integration is the key to making the prototype-to-Figma workflow practical and efficient for production use.

Prototype to Figma Workflow

Purpose: Extract working HTML prototypes into Figma for visual design refinement when the design system is incomplete.

When to Use: When prototypes look incomplete or not visually appealing because design system components aren't fully developed yet.

---

Overview

This workflow enables iterative visual refinement:

Sketch → Spec → Prototype (basic) → Figma (refine) → Design System (extend) → Re-render → Iterate

Key Principle: Code prototypes are functional but may lack visual polish. Extract to Figma for design refinement, then feed improvements back to design system.

---

When to Extract to Figma

Extract When:

✅ Visual refinement needed

• Prototype works but looks unpolished
• Design system lacks components for this view
• Spacing/typography needs fine-tuning
• Color palette needs expansion

✅ Design system gaps identified

• Missing component variants
• Incomplete state definitions
• Need new design tokens
• Pattern library needs expansion

✅ Stakeholder presentation

• Need polished visuals for approval
• Client review requires high-fidelity
• Marketing materials needed

Don't Extract When:

❌ Prototype is sufficient

• Design system already covers all needs
• Visual quality meets requirements
• Focus is on functionality, not aesthetics

❌ Early exploration

• Still validating concepts
• Rapid iteration needed
• Design decisions not finalized

---

The Iterative Refinement Loop

Iteration 1: Basic Prototype

Input: Specification from Phase 4C

Phase 4D: Create Prototype

Sketch → Spec → Generate HTML/CSS/JS
Result: Functional but basic-looking prototype

Assessment:

• Does it work functionally? ✅
• Does it look polished? ❌ (Design system incomplete)

Decision: Extract to Figma for visual refinement

---

Iteration 2: Visual Refinement

Step 1: Extract to Figma

Use MCP server to inject components directly into Figma:

# MCP server enables precise component injection
# Select specific components to extract
# Inject directly into Figma view
# Maintain Object ID traceability

What gets extracted:

• Specific components (not entire page)
• Layout structure (frames, auto-layout)
• Text content (converted to text layers)
• Colors (as fills)
• Spacing (as padding/gaps)
• Component boundaries preserved

Step 2: Refine in Figma

Designer works in Figma to:

• Apply proper typography styles
• Refine color palette
• Adjust spacing/padding
• Add visual polish (shadows, borders, effects)
• Create missing component variants
• Define proper states

Step 3: Document Design Decisions

Capture in Figma:

• Design tokens (colors, spacing, typography)
• Component specifications
• State definitions
• Variant rules

Step 4: Extract Design System Updates

From refined Figma design:

• New design tokens → D-Design-System/design-tokens.md
• New components → D-Design-System/components/
• Updated variants → Existing component files
• New states → Component state definitions

---

Iteration 3: Re-render with Enhanced Design System

Step 5: Update Design System

Apply Figma refinements to design system:

# D-Design-System/design-tokens.md

Colors:
  primary:
    50: "#f0f9ff"
    600: "#2563eb"  # From Figma refinement
    700: "#1d4ed8"  # New from Figma
    
Spacing:
  xs: 4px
  sm: 8px
  md: 16px   # Refined in Figma
  lg: 24px   # New from Figma
  
Typography:
  heading-1:
    font: "Inter"
    size: 32px    # Refined in Figma
    weight: 700
    line-height: 1.2

Step 6: Re-render Prototype

Regenerate prototype with enhanced design system:

Same HTML structure + Enhanced design system = Polished prototype

Assessment:

• Does it work functionally? ✅
• Does it look polished? ✅ (Design system now complete)

Decision: Prototype complete, or iterate again if needed

---

Detailed Workflow Steps

Phase 1: Identify Need for Figma Refinement

After Phase 4D prototype creation:

<ask> Prototype Assessment

Your prototype is functional! Now let's assess visual quality:

1. Looks good - Design system covers everything needed 2. Needs refinement - Missing components/polish, extract to Figma 3. Needs minor tweaks - Quick CSS adjustments sufficient

Choice [1/2/3]: </ask>

<check if="choice == 2"> <action>Proceed to Figma extraction workflow</action> </check>

---

Phase 2: Extract Prototype to Figma

Agent: Freya WDS Designer Agent (automated)

Freya's Process:

1. Analyze prototype components

Freya automatically:

• Scans prototype for all components with Object IDs
• Identifies components that need visual refinement
• Compares against existing design system
• Determines which components are missing or incomplete

2. Present extraction options

<ask> I've analyzed the prototype and identified components that could benefit from visual refinement:

Missing from design system:

• Login button (btn-login-submit)
• Email input (input-email)
• Password input (input-password)

Incomplete in design system:

• Forgot password link (link-forgot-password) - needs hover state

Would you like me to inject these into Figma for refinement?

[A] All components (4 total) [S] Select specific components [N] No, continue as-is

Choice: </ask>

3. Inject via MCP server (automated)

Freya automatically:

• Determines target Figma file from project config
• Creates/navigates to page matching scenario/page structure
• Page naming: [Scenario-Number]-[Scenario-Name] / [Page-Number]-[Page-Name]
• Example: 01-Customer-Onboarding / 1.2-Sign-In
• Injects selected components via MCP server
• Preserves Object IDs in layer names
• Maintains component boundaries

<output> ✓ Injecting components to Figma... ✓ Target: [Project] Design Refinement / 01-Customer-Onboarding / 1.2-Sign-In ✓ btn-login-submit → Injected at (100, 200) ✓ input-email → Injected at (100, 300)

All components injected successfully!

Figma link: <https://figma.com/file/abc123?node-id=...>

You can now refine these components in Figma. Let me know when you're ready to read them back. </output>

4. Wait for designer refinement

Freya pauses workflow and waits for user to:

• Open Figma
• Refine visual design
• Apply design tokens
• Create component variants
• Define states
• Notify when complete

Output:

• Specific components injected into Figma
• Layers named with Object IDs
• Page structure matches specification
• Figma link provided to designer
• Freya ready to read refined components back

Advantages:

• ✅ Fully automated by Freya
• ✅ Component-level precision
• ✅ Automatic Object ID mapping
• ✅ Page structure matches specs
• ✅ No manual commands needed
• ✅ Seamless workflow integration

---

Phase 3: Refine Design in Figma

Designer tasks:

1. Apply Design Tokens

Convert extracted values to proper tokens:

Before (extracted):
- Fill: #2563eb (hardcoded)

After (refined):
- Fill: {primary.600} (design token)

2. Create/Update Components

Identify reusable patterns:

Extracted button → Create Figma component
- Name: Button/Primary [btn-001]
- Add variants: primary, secondary, ghost
- Add states: default, hover, active, disabled
- Document in description

3. Refine Visual Design

Polish the design:

• Typography hierarchy
• Spacing consistency
• Color harmony
• Visual effects (shadows, borders)
• Responsive behavior

4. Document Decisions

In Figma file, create documentation frame:

Design Decisions:
├── Color Palette (with token names)
├── Typography Scale (with token names)
├── Spacing System (with token names)
├── Component Specifications
└── State Definitions

Important: If you discover better design solutions during refinement:

• ✅ Explore new ideas and improvements
• ✅ Document design decisions in Figma
• ✅ Update specifications to match new design
• ✅ Notify Freya of specification changes needed
• ❌ Don't let Figma and specs diverge

Workflow for design changes: 1. Refine design in Figma (explore improvements) 2. Document what changed and why 3. Update specification to reflect new design 4. Freya reads refined design from Figma 5. Design system updated 6. Re-render prototype matches updated spec

---

Phase 4: Extract Design System Updates

Agent: Freya WDS Designer Agent (automated)

Freya's Process:

1. User notifies completion

<ask> Have you finished refining the components in Figma?

[Y] Yes, read them back [N] Not yet, still working

Choice: </ask>

2. Read refined components (automated)

Freya automatically:

• Connects to Figma via MCP server
• Reads all injected components from target page
• Extracts design tokens (colors, spacing, typography)
• Identifies component variants and states
• Analyzes design decisions

<output> ✓ Reading refined components from Figma... ✓ btn-login-submit → Read successfully ✓ input-email → Read successfully ✓ input-password → Read successfully ✓ link-forgot-password → Read successfully

Analyzing design refinements... </output>

3. Extract and present design tokens

<output> Design tokens extracted:

Colors:

• primary.600: #2563eb (new)
• primary.700: #1d4ed8 (new)
• neutral.50: #ffffff

Spacing:

• spacing.md: 12px (refined from 16px)
• spacing.lg: 16px (new)

Typography:

• button.font-size: 16px (new)
• button.font-weight: 600 (new)

Component updates:

• Button component: Added primary variant, hover/active states
• Input component: Added focus state, error state
• Link component: Created new component with hover state

</output>

<ask> Did you make any design changes that differ from the original specification?

[Y] Yes, I improved the design [N] No, stayed true to spec

Choice: </ask>

<check if="yes"> <ask>Please describe what changed in the design and why:

(This helps me update the specification to match your refined design) </ask>

<output>Thank you! I'll note these changes for the specification update.

Specification updates needed:

• {list design changes that differ from original spec}

After updating the design system, we should update the specification to reflect these improvements.</output> </check>

<ask> Would you like me to update the design system with these changes?

[Y] Yes, update design system [R] Review changes first [C] Customize before updating

Choice: </ask>

4. Update design system (automated)

Freya automatically updates D-Design-System/design-tokens.md:

## Colors (Updated from Figma)

### Primary
- primary.50: #f0f9ff
- primary.600: #2563eb (refined)
- primary.700: #1d4ed8 (new)

### Spacing (Updated from Figma)
- xs: 4px
- sm: 8px  
- md: 16px (refined from 12px)
- lg: 24px (new)

2. Component Specifications

Create/update component files:

# D-Design-System/components/button.md

Button Component [btn-001]

**Figma Reference:** [Link to Figma component]

## Variants (From Figma refinement)
- primary (updated styling)
- secondary (new variant)
- ghost (new variant)

## States (From Figma refinement)
- default
- hover (updated animation)
- active (new state)
- disabled (updated opacity)

## Styling (From Figma)
- Background: {primary.600}
- Text: {neutral.50}
- Padding: {spacing.md} {spacing.lg}
- Border-radius: {radius.md}

3. Update Figma Mappings

# D-Design-System/figma-mappings.md

Button [btn-001] → figma://file/abc123/node/456:789
Input [inp-001] → figma://file/abc123/node/456:790
Card [crd-001] → figma://file/abc123/node/456:791

---

Phase 5: Re-render Prototype with Enhanced Design System

Back to Phase 4D:

1. Update prototype templates

Apply new design tokens:

<!-- Before -->
<button style="background: #2563eb; padding: 12px 16px;">

<!-- After (with design system) -->
<button class="btn-primary">
  <!-- Styled via design system tokens -->
</button>

2. Regenerate or update prototype

<ask> Re-render approach:

1. Regenerate - Create fresh prototype with new design system 2. Update - Apply design system to existing prototype 3. Hybrid - Update critical sections, regenerate others

Choice [1/2/3]: </ask>

3. Test updated prototype

Verify:

• Visual quality improved ✅
• Functionality preserved ✅
• Design system applied correctly ✅
• All Object IDs maintained ✅

---

Phase 6: Iterate or Complete

Assessment:

<ask> Prototype quality check:

1. Complete - Looks polished, ready for development 2. Iterate - Needs another refinement cycle 3. Minor tweaks - Small adjustments needed

Choice [1/2/3]: </ask>

<check if="choice == 2"> <action>Return to Phase 2 (Extract to Figma again)</action> <output>Starting iteration 2 with enhanced design system as baseline</output> </check>

<check if="choice == 1"> <output>✅ Prototype complete and polished!</output> <action>Mark prototype as final</action> <action>Update scenario tracking</action> </check>

---

Tools Integration

html.to.design

Purpose: Convert HTML prototypes to Figma

Features:

• Preserves layout structure
• Converts CSS to Figma styles
• Maintains element hierarchy
• Extracts design tokens
• Creates Figma components

Usage:

1. Upload HTML file
2. Configure conversion options
3. Download Figma file
4. Import to Figma workspace

Best Practices:

• Clean HTML structure before extraction
• Use semantic HTML elements
• Include Object IDs in data attributes
• Document area tags for image sections

NanoBanana (Optional)

Purpose: Agent-driven asset creation and design inspiration tool

Website: <https://nanobanana.com>

Use Case in WDS: Create visual assets, design inspiration, and possibly export design elements

Description: Think of it as "agent-driven Photoshop" - an AI-powered tool for creating visual design assets and exploring design possibilities.

Features

Asset Creation:

• Visual design generation
• Design inspiration and variations
• Asset creation (images, graphics, icons)
• Design exploration
• Possibly code export for certain elements

Integration with WDS

Workflow:

Design Concept
    → NanoBanana (create assets/inspiration)
    → Visual Assets
    → Use in Figma or Prototypes
    → Refine and integrate

When to use:

• Need visual design inspiration
• Creating custom graphics/assets
• Exploring design variations
• Generating design ideas
• Creating placeholder assets

When to Skip:

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

Best Practices

DO ✅

• Use for design exploration and inspiration
• Generate multiple variations
• Refine AI-generated assets in Figma
• Use as creative starting point
• Export and integrate into design system

DON'T ❌

• Use as replacement for design thinking
• Skip refinement of generated assets
• Ignore brand guidelines
• Use without customization
• Rely solely on AI-generated designs

Design System Updates

D-Design-System/
  design-tokens.md              ← Updated from Figma
  components/
    button.md                   ← Updated from Figma
    input.md                    ← New from Figma
  figma-mappings.md             ← Figma node references
  refinement-history.md         ← Track iterations

---

Decision Framework

When to Extract to Figma?

Extract if ANY of these are true:

1. Visual Quality Gap

• Prototype looks unpolished
• Design system incomplete
• Missing visual hierarchy

2. Design System Gaps

• Need new components
• Missing variants/states
• Token palette incomplete

3. Stakeholder Needs

• Client presentation required
• High-fidelity mockups needed
• Marketing materials

Don't extract if ALL of these are true:

1. Prototype looks good enough 2. Design system covers all needs 3. Focus is on functionality 4. Rapid iteration more important

---

Best Practices

DO ✅

1. Maintain Object IDs

• Keep Object IDs through extraction
• Use as Figma layer names
• Enables traceability

2. Document Iterations

• Track version history
• Note design decisions
• Record token changes
• Update specifications when design evolves
• Document why design changed from original spec

3. Sync Bidirectionally

• Figma → Design System
• Design System → Prototype
• Keep everything aligned

4. Iterate Incrementally

• Small refinement cycles
• Test after each iteration
• Don't over-polish early

DON'T ❌

1. Don't Extract Too Early

• Wait until concept is validated
• Ensure functionality works first
• Don't polish throwaway work

2. Don't Lose Traceability

• Maintain Object ID connections
• Document Figma references
• Track design system changes

3. Don't Diverge Without Updating Specs

• New design ideas during Figma refinement are welcome
• BUT: Update specifications to match new design decisions
• Keep Figma, specs, and code in sync
• Update design system consistently
• Specifications remain the source of truth

4. Don't Over-Iterate

• Know when "good enough" is sufficient
• Balance polish with progress
• Ship working products

---

Troubleshooting

Extraction Issues

Problem: html.to.design doesn't preserve layout

Solution:

• Use semantic HTML structure
• Avoid complex CSS positioning
• Simplify before extraction
• Use Flexbox/Grid layouts

---

Problem: Object IDs lost in extraction

Solution:

• Add Object IDs to data attributes
• Use as CSS classes
• Include in element IDs
• Document mapping separately

---

Figma Refinement Issues

Problem: Can't match design system tokens

Solution:

• Create Figma variables first
• Map extracted values to variables
• Document token mappings
• Use consistent naming

---

Problem: Components don't match code structure

Solution:

• Align Figma component hierarchy with HTML
• Use same naming conventions
• Document component boundaries
• Keep structures parallel

---

Re-rendering Issues

Problem: Design system changes break prototype

Solution:

• Test incrementally
• Update one token at a time
• Verify after each change
• Keep rollback version

---

Problem: Prototype loses functionality after re-render

Solution:

• Preserve JavaScript logic
• Don't change HTML structure
• Only update styling
• Test all interactions

---

Success Metrics

Quality Indicators:

✅ Prototype looks polished ✅ Design system is comprehensive ✅ Figma and code are in sync ✅ Object IDs maintained throughout ✅ Iterations are productive ✅ Team alignment on visual direction

Efficiency Indicators:

✅ Fewer refinement cycles needed ✅ Design system grows organically ✅ Reusable components identified ✅ Faster subsequent prototypes ✅ Reduced rework

---

Example: Complete Iteration Cycle

Iteration 1: Basic Prototype

Input: Login page specification

Output: Functional HTML prototype

• Form works
• Validation functions
• But looks basic (incomplete design system)

Assessment: Needs visual refinement

---

Iteration 2: Figma Refinement

Extract to Figma:

• Upload to html.to.design
• Import to Figma
• Structure preserved

Refine in Figma:

• Apply proper typography (Inter font)
• Refine color palette (brand colors)
• Add button variants (primary, secondary)
• Define input states (default, focus, error)
• Add visual polish (shadows, borders)

Extract to Design System:

• New tokens: colors, spacing, typography
• New components: Button [btn-001], Input [inp-001]
• Updated: design-tokens.md, components/

---

Iteration 3: Re-render

Update Prototype:

• Apply new design tokens
• Use new component classes
• Regenerate with design system

Result:

• Same functionality ✅
• Polished visuals ✅
• Design system extended ✅

Assessment: Complete! Ready for development

---

Integration with Existing Workflows

Phase 4D: Prototype

Updated decision point:

After prototype creation:

1. Test functionality
2. Assess visual quality
3. If needs refinement → Extract to Figma
4. If sufficient → Complete

Phase 5: Design System

New workflow branch:

Design System can be populated via:

A. Component specification (existing)
B. Figma manual creation (existing)
C. Prototype extraction (NEW - this workflow)

---

Next Steps

To implement this workflow:

1. ✅ Read this guide 2. ✅ Set up html.to.design account 3. ✅ Create test prototype 4. ✅ Practice extraction process 5. ✅ Refine in Figma 6. ✅ Update design system 7. ✅ Re-render and compare 8. ✅ Iterate until comfortable

---

This workflow completes the WDS design refinement loop, enabling iterative improvement from functional prototypes to polished, production-ready designs.

3D Render

Overview

Full 3D rendered objects or scenes with realistic materials, lighting, and depth.

Rendering Characteristics

Prompt Keywords

3D render, 3D illustration, CGI, rendered, studio lighting, material design, glossy, matte, metallic

Best For

• Product showcases, device mockups, abstract hero images
• Technology brands, gaming, automotive

Dimensions Guide

• Product renders: 1:1 or 4:3
• Hero scenes: 16:9 or 21:9
• Device mockups: device-specific ratios

Comic Book

Overview

Bold outlines, halftone dots, speech bubbles, and dynamic action-style compositions.

Rendering Characteristics

Prompt Keywords

comic book, comic style, halftone, bold outlines, pop art, graphic novel, ink, dynamic, action

Best For

• Gaming, entertainment, youth brands, marketing campaigns
• Storytelling sequences, feature explanations, onboarding

Dimensions Guide

• Panels: various ratios, comic grid layout
• Characters: variable, action poses

Flat Design

Overview

No gradients, shadows, or 3D effects — pure shapes, clean colors, geometric simplicity.

Rendering Characteristics

Prompt Keywords

flat design, flat illustration, minimalist, geometric, solid colors, no shadows, 2D, clean shapes

Best For

• UI elements, icons, infographics, onboarding illustrations
• Fast-loading assets, scalable graphics

Dimensions Guide

• Icons: 24x24 to 256x256
• Illustrations: variable
• Infographics: full-width

Hyper-realistic

Overview

Beyond photography — extreme detail, perfect lighting, idealized reality.

Rendering Characteristics

Prompt Keywords

hyper-realistic, ultra-detailed, 8K, macro detail, cinematic lighting, photographic, sharp focus, professional photography

Best For

• Luxury brands, food photography, automotive, jewelry
• Hero images that need to feel premium

Dimensions Guide

• Hero: 2560x1440 or higher
• Product: 1:1, high resolution
• Detail shots: macro crop ratios

Illustration

Overview

Hand-crafted digital illustrations — custom, warm, and brand-unique.

Rendering Characteristics

Prompt Keywords

illustration, digital illustration, hand-drawn, custom art, vector style, flat illustration, character illustration

Best For

• Brand storytelling, onboarding flows, empty states, error pages
• Distinctive brand identity that photography can't deliver

Dimensions Guide

• Spot illustrations: 400x400 to 800x800
• Scene illustrations: 16:9 or custom
• Icons as illustrations: 64x64 to 256x256

Isometric

Overview

3D-like objects rendered in isometric projection — no perspective, parallel lines.

Rendering Characteristics

Prompt Keywords

isometric, isometric illustration, 3D isometric, parallel projection, geometric, clean, technical illustration

Best For

• Tech products, data visualization, process diagrams, feature showcases
• Explaining complex systems or workflows visually

Dimensions Guide

• Scene: 16:9 or square
• Individual objects: 1:1 ratio
• Infographics: variable height

Line Art

Overview

Pure outlines — no fill, no shading, just clean continuous lines.

Rendering Characteristics

Prompt Keywords

line art, line drawing, outline, continuous line, single line, clean lines, black and white, monoline

Best For

• Icons, technical diagrams, coloring-book style, decorative patterns
• Minimalist brands, loading animations base art

Dimensions Guide

• Icons: 24x24 to 128x128
• Decorative: variable
• Diagrams: content-dependent

Pencil Sketch

Overview

Hand-drawn pencil or charcoal look — raw, authentic, in-progress feel.

Rendering Characteristics

Prompt Keywords

pencil sketch, hand-drawn, graphite, charcoal, sketch style, rough drawing, crosshatch, tonal

Best For

• Architecture, concept art, wireframe-style illustrations, draft previews
• Conveying "in progress" or "behind the scenes" feel

Dimensions Guide

• Concept sketches: variable
• Wireframe illustrations: page-width

Photorealistic

Overview

Images that look like real photographs — natural lighting, real textures, believable scenes.

Rendering Characteristics

Prompt Keywords

photorealistic, realistic, photograph, natural lighting, high detail, lifelike, studio quality, DSLR

Best For

• Product photography, hero images, team portraits, real estate
• Any context where authenticity matters

Dimensions Guide

• Hero images: 1920x1080 or 2560x1440
• Product shots: 1:1 or 4:3 ratio
• Portraits: 3:4 ratio

Watercolor

Overview

Soft, flowing artwork with transparent washes, organic edges, and painterly feel.

Rendering Characteristics

Prompt Keywords

watercolor, watercolour, painted, soft washes, paper texture, transparent paint, flowing color, artistic

Best For

• Wedding sites, wellness, art galleries, stationery, boutique brands
• Backgrounds, decorative elements, section dividers

Dimensions Guide

• Backgrounds: full-width, transparent edges
• Decorative: variable, organic shapes

Brutalist

Overview

Raw, bold, unapologetic design that breaks conventions intentionally.

Visual Characteristics

Prompt Keywords

brutalist, raw, bold, unconventional, stark, industrial, exposed structure, anti-design

Best For

• Creative agencies, art portfolios, experimental projects, fashion
• Brands that want to stand out through contrast

Avoid

• Healthcare, finance, government, accessibility-critical applications

Corporate

Overview

Professional, trustworthy design that communicates reliability and authority.

Visual Characteristics

Prompt Keywords

corporate, professional, trustworthy, clean, business, authoritative, polished, structured

Best For

• B2B software, financial services, consulting, enterprise tools
• Sites that need to convey trust and competence

Avoid

• Creative agencies, children's products, casual/playful brands

Editorial

Overview

Magazine-inspired design with strong typography hierarchy, editorial layouts, and storytelling focus.

Visual Characteristics

Prompt Keywords

editorial, magazine, typographic, sophisticated, storytelling, grid-based, print-inspired, refined

Best For

• Media, publications, blogs, luxury brands, cultural institutions
• Content-heavy sites where reading experience matters

Avoid

• SaaS dashboards, e-commerce with many products, data-heavy apps