docs: update all documentation and add AI tooling configs
- Rewrite README.md with current architecture, features and stack - Update docs/API.md with all current endpoints (corporate, BI, client 360) - Update docs/ARCHITECTURE.md with cache, modular queries, services, ETL - Update docs/GUIA-USUARIO.md for all roles (admin, corporate, agente) - Add docs/INDEX.md documentation index - Add PROJETO.md comprehensive project reference - Add BI-CCC-Implementation-Guide.md - Include AI agent configs (.claude, .agents, .gemini, _bmad) - Add netbird VPN configuration - Add status report Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,131 @@
|
||||
# Content Purpose Examples
|
||||
|
||||
**Three examples demonstrating how to define clear, testable content purpose**
|
||||
|
||||
---
|
||||
|
||||
## Example 1: Landing Page Hero
|
||||
|
||||
```yaml
|
||||
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
|
||||
|
||||
```yaml
|
||||
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
|
||||
|
||||
```yaml
|
||||
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_
|
||||
@@ -0,0 +1,97 @@
|
||||
# Action Filter Example: Hairdresser Newsletter
|
||||
|
||||
**Trigger Map Context:** Hairdresser newsletter signup
|
||||
|
||||
**Action Filter:**
|
||||
|
||||
```yaml
|
||||
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_
|
||||
@@ -0,0 +1,159 @@
|
||||
# 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_
|
||||
@@ -0,0 +1,88 @@
|
||||
# Example: Badass Users Framework Applied to Hairdresser Newsletter
|
||||
|
||||
**Trigger Map Context:** Hairdresser newsletter signup
|
||||
|
||||
**Empowerment Frame:**
|
||||
|
||||
```yaml
|
||||
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_
|
||||
@@ -0,0 +1,96 @@
|
||||
# Example: Golden Circle Applied to Hairdresser Newsletter
|
||||
|
||||
**Trigger Map Context:** Hairdresser newsletter signup
|
||||
|
||||
**Structural Order:**
|
||||
|
||||
```yaml
|
||||
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_
|
||||
@@ -0,0 +1,160 @@
|
||||
# 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_
|
||||
@@ -0,0 +1,136 @@
|
||||
# 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_
|
||||
@@ -0,0 +1,95 @@
|
||||
# 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:
|
||||
|
||||
```markdown
|
||||
---
|
||||
|
||||
## 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_
|
||||
@@ -0,0 +1,319 @@
|
||||
# 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](../../../docs/method/tone-of-voice-guide.md)
|
||||
|
||||
---
|
||||
|
||||
## 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](../../../docs/models/customer-awareness-cycle.md)
|
||||
- [Golden Circle](../../../docs/models/golden-circle.md)
|
||||
- [Action Mapping](../../../docs/models/action-mapping.md)
|
||||
- [Kathy Sierra Badass Users](../../../docs/models/kathy-sierra-badass-users.md)
|
||||
|
||||
**Whiteport Methods:**
|
||||
- [Trigger Mapping Guide](../../../docs/method/trigger-mapping-guide.md)
|
||||
- [Content Purpose Guide](../../../docs/method/content-purpose-guide.md) - **Start here for content effectiveness**
|
||||
|
||||
**Workflows:**
|
||||
- [Phase 4: UX Design](../../../docs/method/phase-4-ux-design-guide.md)
|
||||
- [Phase 1: Product Exploration](../../../docs/method/phase-1-product-exploration-guide.md)
|
||||
|
||||
---
|
||||
|
||||
**Let's create strategically grounded content, not guesswork.** 🎯
|
||||
|
||||
@@ -0,0 +1,687 @@
|
||||
# Figma Designer Guide for WDS
|
||||
|
||||
**Purpose:** Step-by-step instructions for designers creating components in Figma for WDS projects.
|
||||
|
||||
**Audience:** Visual designers, UX designers, design system maintainers
|
||||
|
||||
---
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Figma account with edit access to design system file
|
||||
- Understanding of WDS component structure
|
||||
- Familiarity with Figma components and variants
|
||||
- Access to WDS project repository
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Set Up Your Figma File
|
||||
|
||||
### Create Design System File
|
||||
|
||||
**File structure:**
|
||||
|
||||
```
|
||||
[Project Name] Design System
|
||||
├── 📄 Cover
|
||||
├── 🎨 Foundation
|
||||
│ ├── Colors
|
||||
│ ├── Typography
|
||||
│ ├── Spacing
|
||||
│ └── Effects
|
||||
├── ⚛️ Components
|
||||
│ ├── Buttons
|
||||
│ ├── Inputs
|
||||
│ ├── Cards
|
||||
│ └── [more types]
|
||||
└── 📱 Examples
|
||||
```
|
||||
|
||||
**Tips:**
|
||||
|
||||
- Use clear page names
|
||||
- Organize by component type
|
||||
- Keep foundation separate
|
||||
- Include usage examples
|
||||
|
||||
---
|
||||
|
||||
### Set Up Design Tokens
|
||||
|
||||
**Create Figma variables:**
|
||||
|
||||
**Colors:**
|
||||
|
||||
```
|
||||
Collection: Colors
|
||||
├── primary/50
|
||||
├── primary/100
|
||||
├── primary/500
|
||||
├── primary/600
|
||||
├── gray/50
|
||||
├── gray/900
|
||||
└── [more colors]
|
||||
```
|
||||
|
||||
**Spacing:**
|
||||
|
||||
```
|
||||
Collection: Spacing
|
||||
├── spacing/1 = 4px
|
||||
├── spacing/2 = 8px
|
||||
├── spacing/4 = 16px
|
||||
├── spacing/6 = 24px
|
||||
└── [more spacing]
|
||||
```
|
||||
|
||||
**Typography:**
|
||||
|
||||
```
|
||||
Styles: Typography
|
||||
├── Display/Large
|
||||
├── Heading/1
|
||||
├── Heading/2
|
||||
├── Body/Regular
|
||||
└── [more styles]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Create Your First Component
|
||||
|
||||
### Example: Button Component
|
||||
|
||||
**1. Create Base Frame**
|
||||
|
||||
```
|
||||
Frame name: Button/Primary [btn-001]
|
||||
Size: Hug contents (width), Fixed 44px (height)
|
||||
Auto Layout: Horizontal
|
||||
Padding: 16px (horizontal), 12px (vertical)
|
||||
Gap: 8px
|
||||
```
|
||||
|
||||
**2. Add Content**
|
||||
|
||||
```
|
||||
├── Icon (optional)
|
||||
│ └── Size: 20x20px
|
||||
└── Text
|
||||
└── Style: Body/Medium
|
||||
└── Content: "Button Text"
|
||||
```
|
||||
|
||||
**3. Apply Design Tokens**
|
||||
|
||||
```
|
||||
Background: primary/600 (variable)
|
||||
Text Color: white (variable)
|
||||
Border Radius: 8px
|
||||
```
|
||||
|
||||
**4. Create Component**
|
||||
|
||||
```
|
||||
Select frame → Create Component
|
||||
Name: Button/Primary [btn-001]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Add Component Description
|
||||
|
||||
**In component description field:**
|
||||
|
||||
```
|
||||
Button Primary [btn-001]
|
||||
|
||||
Primary action button for main user actions.
|
||||
|
||||
**When to use:**
|
||||
- Submit forms
|
||||
- Confirm actions
|
||||
- Proceed to next step
|
||||
|
||||
**When not to use:**
|
||||
- Secondary actions (use Button/Secondary)
|
||||
- Navigation (use Link component)
|
||||
|
||||
**WDS Component:** Button.primary [btn-001]
|
||||
**Variants:** primary, secondary, ghost
|
||||
**States:** default, hover, active, disabled, loading
|
||||
**Sizes:** small, medium, large
|
||||
|
||||
**Accessibility:**
|
||||
- role="button"
|
||||
- aria-disabled when disabled
|
||||
- Keyboard: Enter/Space to activate
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Add Variants
|
||||
|
||||
### Create Variant Properties
|
||||
|
||||
**Select component → Add variant property:**
|
||||
|
||||
**Property 1: Type**
|
||||
|
||||
```
|
||||
Values: Primary, Secondary, Ghost, Outline
|
||||
```
|
||||
|
||||
**Property 2: Size**
|
||||
|
||||
```
|
||||
Values: Small, Medium, Large
|
||||
```
|
||||
|
||||
**Property 3: State**
|
||||
|
||||
```
|
||||
Values: Default, Hover, Active, Disabled, Loading
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Design Each Variant
|
||||
|
||||
**Type=Primary, Size=Medium, State=Default:**
|
||||
|
||||
```
|
||||
Background: primary/600
|
||||
Text: white
|
||||
Padding: 16px × 12px
|
||||
```
|
||||
|
||||
**Type=Primary, Size=Medium, State=Hover:**
|
||||
|
||||
```
|
||||
Background: primary/700 (darker)
|
||||
Text: white
|
||||
Scale: 1.02 (slightly larger)
|
||||
```
|
||||
|
||||
**Type=Primary, Size=Medium, State=Active:**
|
||||
|
||||
```
|
||||
Background: primary/800 (darkest)
|
||||
Text: white
|
||||
Scale: 0.98 (slightly smaller)
|
||||
```
|
||||
|
||||
**Type=Primary, Size=Medium, State=Disabled:**
|
||||
|
||||
```
|
||||
Background: gray/300
|
||||
Text: gray/500
|
||||
Opacity: 0.6
|
||||
Cursor: not-allowed
|
||||
```
|
||||
|
||||
**Type=Primary, Size=Medium, State=Loading:**
|
||||
|
||||
```
|
||||
Background: primary/600
|
||||
Text: white
|
||||
Add: Spinner icon
|
||||
Opacity: 0.8
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Adjust for Sizes
|
||||
|
||||
**Small:**
|
||||
|
||||
```
|
||||
Padding: 12px × 8px
|
||||
Text: Body/Small
|
||||
Icon: 16x16px
|
||||
Height: 36px
|
||||
```
|
||||
|
||||
**Medium (default):**
|
||||
|
||||
```
|
||||
Padding: 16px × 12px
|
||||
Text: Body/Medium
|
||||
Icon: 20x20px
|
||||
Height: 44px
|
||||
```
|
||||
|
||||
**Large:**
|
||||
|
||||
```
|
||||
Padding: 20px × 16px
|
||||
Text: Body/Large
|
||||
Icon: 24x24px
|
||||
Height: 52px
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Document States
|
||||
|
||||
### Visual State Indicators
|
||||
|
||||
**Create a documentation frame:**
|
||||
|
||||
```
|
||||
Frame: Button States Documentation
|
||||
├── Default
|
||||
│ └── Normal appearance
|
||||
├── Hover
|
||||
│ └── Background darker, slight scale
|
||||
├── Active
|
||||
│ └── Background darkest, scale down
|
||||
├── Disabled
|
||||
│ └── Grayed out, reduced opacity
|
||||
└── Loading
|
||||
└── Spinner, disabled interaction
|
||||
```
|
||||
|
||||
**Add annotations:**
|
||||
|
||||
- State name
|
||||
- Visual changes
|
||||
- Interaction behavior
|
||||
- Transition duration
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Get Figma Node ID
|
||||
|
||||
### Copy Component Link
|
||||
|
||||
**1. Select component in Figma**
|
||||
|
||||
**2. Right-click → "Copy link to selection"**
|
||||
|
||||
**3. Extract node ID from URL:**
|
||||
|
||||
```
|
||||
URL: https://www.figma.com/file/abc123/Design-System?node-id=456:789
|
||||
|
||||
File ID: abc123
|
||||
Node ID: 456:789
|
||||
|
||||
Full reference: figma://file/abc123/node/456:789
|
||||
```
|
||||
|
||||
**4. Add to WDS mapping file:**
|
||||
|
||||
```yaml
|
||||
# D-Design-System/figma-mappings.md
|
||||
Button [btn-001] → figma://file/abc123/node/456:789
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 6: Sync with WDS
|
||||
|
||||
### Manual Sync Process
|
||||
|
||||
**1. Create component in Figma** (steps above)
|
||||
|
||||
**2. Notify WDS system:**
|
||||
|
||||
- Add component ID to Figma description
|
||||
- Copy Figma node ID
|
||||
- Update `figma-mappings.md`
|
||||
|
||||
**3. Generate WDS specification:**
|
||||
|
||||
- Use Figma MCP to read component
|
||||
- Generate component specification
|
||||
- Review and confirm
|
||||
|
||||
**4. Verify sync:**
|
||||
|
||||
- Check WDS component file created
|
||||
- Verify all variants captured
|
||||
- Confirm states documented
|
||||
- Test component reference
|
||||
|
||||
---
|
||||
|
||||
### Using Figma MCP (Automated)
|
||||
|
||||
**If Figma MCP is configured:**
|
||||
|
||||
**1. Create/update component in Figma**
|
||||
|
||||
**2. Run MCP sync command:**
|
||||
|
||||
```bash
|
||||
# In WDS project
|
||||
wds figma sync Button/Primary
|
||||
```
|
||||
|
||||
**3. MCP will:**
|
||||
|
||||
- Read component from Figma
|
||||
- Extract variants and states
|
||||
- Generate WDS specification
|
||||
- Update figma-mappings.md
|
||||
|
||||
**4. Review generated spec:**
|
||||
|
||||
- Check accuracy
|
||||
- Add missing details
|
||||
- Confirm and commit
|
||||
|
||||
---
|
||||
|
||||
## Step 7: Maintain Components
|
||||
|
||||
### Updating Existing Components
|
||||
|
||||
**When updating a component:**
|
||||
|
||||
**1. Update in Figma:**
|
||||
|
||||
- Modify component
|
||||
- Update description if needed
|
||||
- Maintain component ID
|
||||
|
||||
**2. Sync to WDS:**
|
||||
|
||||
- Run MCP sync (if available)
|
||||
- Or manually update WDS spec
|
||||
- Update version history
|
||||
|
||||
**3. Notify team:**
|
||||
|
||||
- Document changes
|
||||
- Update affected pages
|
||||
- Test implementations
|
||||
|
||||
---
|
||||
|
||||
### Version Control
|
||||
|
||||
**Track component changes:**
|
||||
|
||||
**In Figma:**
|
||||
|
||||
- Use Figma version history
|
||||
- Add version notes
|
||||
- Tag major changes
|
||||
|
||||
**In WDS:**
|
||||
|
||||
```markdown
|
||||
## Version History
|
||||
|
||||
**Created:** 2024-12-09
|
||||
**Last Updated:** 2024-12-15
|
||||
|
||||
**Changes:**
|
||||
|
||||
- 2024-12-09: Created component
|
||||
- 2024-12-12: Added loading state
|
||||
- 2024-12-15: Updated hover animation
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### DO ✅
|
||||
|
||||
**1. Use Design Tokens**
|
||||
|
||||
- Always use variables for colors
|
||||
- Use variables for spacing
|
||||
- Apply text styles consistently
|
||||
|
||||
**2. Document Thoroughly**
|
||||
|
||||
- Clear component descriptions
|
||||
- Usage guidelines
|
||||
- Accessibility notes
|
||||
|
||||
**3. Maintain Consistency**
|
||||
|
||||
- Follow naming conventions
|
||||
- Use consistent spacing
|
||||
- Apply standard states
|
||||
|
||||
**4. Test Instances**
|
||||
|
||||
- Create example instances
|
||||
- Test all variants
|
||||
- Verify responsive behavior
|
||||
|
||||
**5. Keep Organized**
|
||||
|
||||
- Logical component grouping
|
||||
- Clear page structure
|
||||
- Clean component hierarchy
|
||||
|
||||
---
|
||||
|
||||
### DON'T ❌
|
||||
|
||||
**1. Hardcode Values**
|
||||
|
||||
- Don't use hex colors directly
|
||||
- Don't use pixel values without variables
|
||||
- Don't skip design tokens
|
||||
|
||||
**2. Detach Instances**
|
||||
|
||||
- Don't break component connections
|
||||
- Don't create one-off variations
|
||||
- Don't lose main component link
|
||||
|
||||
**3. Skip Documentation**
|
||||
|
||||
- Don't leave descriptions empty
|
||||
- Don't forget WDS component ID
|
||||
- Don't skip usage guidelines
|
||||
|
||||
**4. Ignore States**
|
||||
|
||||
- Don't create only default state
|
||||
- Don't forget hover/active
|
||||
- Don't skip disabled state
|
||||
|
||||
**5. Break Naming Conventions**
|
||||
|
||||
- Don't use inconsistent names
|
||||
- Don't forget component IDs
|
||||
- Don't use unclear abbreviations
|
||||
|
||||
---
|
||||
|
||||
## Common Workflows
|
||||
|
||||
### Creating a New Component Type
|
||||
|
||||
**1. Research:**
|
||||
|
||||
- Check if similar component exists
|
||||
- Review WDS component boundaries guide
|
||||
- Decide: new component or variant?
|
||||
|
||||
**2. Design:**
|
||||
|
||||
- Create base component
|
||||
- Add all required states
|
||||
- Apply design tokens
|
||||
|
||||
**3. Document:**
|
||||
|
||||
- Write clear description
|
||||
- Add WDS component ID
|
||||
- Document usage guidelines
|
||||
|
||||
**4. Sync:**
|
||||
|
||||
- Get Figma node ID
|
||||
- Update WDS mappings
|
||||
- Generate specification
|
||||
|
||||
**5. Test:**
|
||||
|
||||
- Create example instances
|
||||
- Test all variants
|
||||
- Verify responsive behavior
|
||||
|
||||
---
|
||||
|
||||
### Adding a Variant to Existing Component
|
||||
|
||||
**1. Assess:**
|
||||
|
||||
- Is this truly a variant?
|
||||
- Or should it be a new component?
|
||||
- Check with WDS assessment flow
|
||||
|
||||
**2. Add Variant:**
|
||||
|
||||
- Add new variant property value
|
||||
- Design variant appearance
|
||||
- Document differences
|
||||
|
||||
**3. Update Documentation:**
|
||||
|
||||
- Update component description
|
||||
- Add variant to list
|
||||
- Document when to use
|
||||
|
||||
**4. Sync:**
|
||||
|
||||
- Update WDS specification
|
||||
- Add variant to component file
|
||||
- Update version history
|
||||
|
||||
---
|
||||
|
||||
### Updating Component Styling
|
||||
|
||||
**1. Plan Change:**
|
||||
|
||||
- Document what's changing
|
||||
- Check impact on instances
|
||||
- Notify team
|
||||
|
||||
**2. Update Component:**
|
||||
|
||||
- Modify main component
|
||||
- Test all variants
|
||||
- Verify instances update
|
||||
|
||||
**3. Sync to WDS:**
|
||||
|
||||
- Update WDS specification
|
||||
- Document changes
|
||||
- Update version history
|
||||
|
||||
**4. Verify:**
|
||||
|
||||
- Check all instances
|
||||
- Test in examples
|
||||
- Confirm with team
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Component Not Syncing
|
||||
|
||||
**Problem:** MCP can't read component
|
||||
|
||||
**Solutions:**
|
||||
|
||||
- Check component name format
|
||||
- Verify WDS component ID in description
|
||||
- Ensure component is published
|
||||
- Check Figma API access
|
||||
|
||||
---
|
||||
|
||||
### Variants Not Appearing
|
||||
|
||||
**Problem:** Some variants missing in WDS
|
||||
|
||||
**Solutions:**
|
||||
|
||||
- Check variant property names
|
||||
- Verify all combinations exist
|
||||
- Ensure consistent naming
|
||||
- Re-sync component
|
||||
|
||||
---
|
||||
|
||||
### Design Tokens Not Applied
|
||||
|
||||
**Problem:** Hardcoded values instead of variables
|
||||
|
||||
**Solutions:**
|
||||
|
||||
- Replace hex colors with variables
|
||||
- Use spacing variables
|
||||
- Apply text styles
|
||||
- Re-sync component
|
||||
|
||||
---
|
||||
|
||||
### Instance Overrides Lost
|
||||
|
||||
**Problem:** Updates break instance overrides
|
||||
|
||||
**Solutions:**
|
||||
|
||||
- Don't change component structure
|
||||
- Add new properties instead
|
||||
- Maintain backward compatibility
|
||||
- Communicate changes to team
|
||||
|
||||
---
|
||||
|
||||
## Checklist
|
||||
|
||||
### Before Creating Component
|
||||
|
||||
- [ ] Checked if similar component exists
|
||||
- [ ] Reviewed component boundaries guide
|
||||
- [ ] Decided on component vs variant
|
||||
- [ ] Prepared design tokens
|
||||
- [ ] Planned all required states
|
||||
|
||||
### During Component Creation
|
||||
|
||||
- [ ] Used design tokens (no hardcoded values)
|
||||
- [ ] Created all required states
|
||||
- [ ] Applied auto layout properly
|
||||
- [ ] Added clear description
|
||||
- [ ] Included WDS component ID
|
||||
- [ ] Documented usage guidelines
|
||||
|
||||
### After Component Creation
|
||||
|
||||
- [ ] Copied Figma node ID
|
||||
- [ ] Updated figma-mappings.md
|
||||
- [ ] Generated WDS specification
|
||||
- [ ] Created example instances
|
||||
- [ ] Tested all variants
|
||||
- [ ] Notified team
|
||||
|
||||
---
|
||||
|
||||
## Resources
|
||||
|
||||
- **Figma Component Structure:** `data/design-system/figma-component-structure.md`
|
||||
- **Token Architecture:** `data/design-system/token-architecture.md`
|
||||
- **Component Boundaries:** `data/design-system/component-boundaries.md`
|
||||
- **Figma MCP Integration:** `figma-mcp-integration.md`
|
||||
|
||||
---
|
||||
|
||||
**Following this guide ensures your Figma components integrate seamlessly with WDS and maintain design system consistency.**
|
||||
@@ -0,0 +1,37 @@
|
||||
# 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.*
|
||||
@@ -0,0 +1,458 @@
|
||||
# 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
|
||||
|
||||
```
|
||||
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/6-asset-generation/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
|
||||
@@ -0,0 +1,661 @@
|
||||
# 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:**
|
||||
|
||||
```json
|
||||
{
|
||||
"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.**
|
||||
@@ -0,0 +1,55 @@
|
||||
# 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
|
||||
|
||||
| Issue | Solution |
|
||||
|-------|----------|
|
||||
| Plugin not found in Community | Search "html to design" (without dots) |
|
||||
| Plugin panel doesn't appear | Try closing and reopening Figma |
|
||||
| MCP server not connecting | Verify Figma plugin is running and panel is open |
|
||||
| Test export fails | Check both plugin and MCP server are active |
|
||||
@@ -0,0 +1,128 @@
|
||||
# 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:**
|
||||
|
||||
```markdown
|
||||
# {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.
|
||||
@@ -0,0 +1,922 @@
|
||||
# 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:**
|
||||
```bash
|
||||
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:**
|
||||
```bash
|
||||
# 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:**
|
||||
```bash
|
||||
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:**
|
||||
```bash
|
||||
# Inject entire login form section
|
||||
wds figma inject-section login-form --file abc123 --include-children
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Read Refined Component from Figma
|
||||
|
||||
**Command:**
|
||||
```bash
|
||||
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:**
|
||||
```bash
|
||||
# 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:**
|
||||
```bash
|
||||
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:**
|
||||
```bash
|
||||
wds figma batch inject --list components-to-refine.txt --file abc123
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Workflow Integration
|
||||
|
||||
### Phase 4D: After Prototype Creation
|
||||
|
||||
**Agent workflow:**
|
||||
|
||||
```markdown
|
||||
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:**
|
||||
|
||||
```markdown
|
||||
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**
|
||||
```bash
|
||||
npm install -g @wds/figma-mcp-server
|
||||
```
|
||||
|
||||
**2. Configure Figma API Access**
|
||||
```bash
|
||||
# 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**
|
||||
```bash
|
||||
wds figma init
|
||||
```
|
||||
|
||||
**4. Test Connection**
|
||||
```bash
|
||||
wds figma test-connection
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Configuration File
|
||||
|
||||
**Location:** `.wds/figma-mcp-config.yaml`
|
||||
|
||||
```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:**
|
||||
```bash
|
||||
# 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:**
|
||||
```bash
|
||||
# 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:**
|
||||
```bash
|
||||
# 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:**
|
||||
```bash
|
||||
# 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:**
|
||||
```html
|
||||
<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:**
|
||||
```yaml
|
||||
# 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:**
|
||||
```yaml
|
||||
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**
|
||||
```html
|
||||
<!-- 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**
|
||||
```bash
|
||||
# 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**
|
||||
```markdown
|
||||
# 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**
|
||||
```bash
|
||||
# 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**
|
||||
```bash
|
||||
# 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**
|
||||
```html
|
||||
<!-- 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**
|
||||
```bash
|
||||
# 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:**
|
||||
|
||||
```bash
|
||||
# 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:**
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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.**
|
||||
@@ -0,0 +1,933 @@
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```yaml
|
||||
# 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`:
|
||||
|
||||
```markdown
|
||||
## 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:
|
||||
|
||||
```markdown
|
||||
# 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**
|
||||
|
||||
```yaml
|
||||
# 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:
|
||||
|
||||
```html
|
||||
<!-- 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:**
|
||||
|
||||
```markdown
|
||||
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:**
|
||||
|
||||
```markdown
|
||||
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.**
|
||||
@@ -0,0 +1,26 @@
|
||||
# 3D Render
|
||||
|
||||
## Overview
|
||||
Full 3D rendered objects or scenes with realistic materials, lighting, and depth.
|
||||
|
||||
## Rendering Characteristics
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| **Detail level** | High — materials, reflections, environment |
|
||||
| **Lighting** | Studio or environmental lighting |
|
||||
| **Texture** | Realistic materials (metal, glass, plastic, fabric) |
|
||||
| **Color** | Full spectrum, material-dependent |
|
||||
| **Depth** | Full 3D with perspective |
|
||||
|
||||
## 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
|
||||
@@ -0,0 +1,25 @@
|
||||
# Comic Book
|
||||
|
||||
## Overview
|
||||
Bold outlines, halftone dots, speech bubbles, and dynamic action-style compositions.
|
||||
|
||||
## Rendering Characteristics
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| **Detail level** | Medium — simplified but expressive |
|
||||
| **Lighting** | High contrast, dramatic shadows |
|
||||
| **Texture** | Halftone dots, Ben-Day dots, ink splatter |
|
||||
| **Color** | Bold, saturated, limited palette |
|
||||
| **Depth** | Flat with dramatic perspective |
|
||||
|
||||
## 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
|
||||
@@ -0,0 +1,26 @@
|
||||
# Flat Design
|
||||
|
||||
## Overview
|
||||
No gradients, shadows, or 3D effects — pure shapes, clean colors, geometric simplicity.
|
||||
|
||||
## Rendering Characteristics
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| **Detail level** | Low — maximally simplified |
|
||||
| **Lighting** | None — flat color fills |
|
||||
| **Texture** | None — smooth, uniform |
|
||||
| **Color** | Solid fills, limited palette |
|
||||
| **Depth** | None — purely 2D |
|
||||
|
||||
## 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
|
||||
@@ -0,0 +1,26 @@
|
||||
# Hyper-realistic
|
||||
|
||||
## Overview
|
||||
Beyond photography — extreme detail, perfect lighting, idealized reality.
|
||||
|
||||
## Rendering Characteristics
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| **Detail level** | Maximum — every pore, thread, reflection |
|
||||
| **Lighting** | Perfect studio or cinematic lighting |
|
||||
| **Texture** | Microscopic detail visible |
|
||||
| **Color** | Rich, enhanced but believable |
|
||||
| **Depth** | Shallow depth of field, bokeh |
|
||||
|
||||
## 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
|
||||
@@ -0,0 +1,26 @@
|
||||
# Illustration
|
||||
|
||||
## Overview
|
||||
Hand-crafted digital illustrations — custom, warm, and brand-unique.
|
||||
|
||||
## Rendering Characteristics
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| **Detail level** | Medium — stylized, not photographic |
|
||||
| **Lighting** | Flat or gently shaded |
|
||||
| **Texture** | Smooth with subtle grain |
|
||||
| **Color** | Brand palette, can be limited |
|
||||
| **Depth** | Flat to moderate depth |
|
||||
|
||||
## 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
|
||||
@@ -0,0 +1,26 @@
|
||||
# Isometric
|
||||
|
||||
## Overview
|
||||
3D-like objects rendered in isometric projection — no perspective, parallel lines.
|
||||
|
||||
## Rendering Characteristics
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| **Detail level** | Medium to high — clean geometry |
|
||||
| **Lighting** | Flat or subtle ambient |
|
||||
| **Texture** | Smooth, clean surfaces |
|
||||
| **Color** | Brand palette, can be vibrant |
|
||||
| **Depth** | Isometric projection (30-degree angles) |
|
||||
|
||||
## 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
|
||||
@@ -0,0 +1,26 @@
|
||||
# Line Art
|
||||
|
||||
## Overview
|
||||
Pure outlines — no fill, no shading, just clean continuous lines.
|
||||
|
||||
## Rendering Characteristics
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| **Detail level** | Low to medium — defined by lines only |
|
||||
| **Lighting** | None — no shading |
|
||||
| **Texture** | None — clean strokes |
|
||||
| **Color** | Single color (usually black) or thin color lines |
|
||||
| **Depth** | Implied through line weight variation |
|
||||
|
||||
## 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
|
||||
@@ -0,0 +1,25 @@
|
||||
# Pencil Sketch
|
||||
|
||||
## Overview
|
||||
Hand-drawn pencil or charcoal look — raw, authentic, in-progress feel.
|
||||
|
||||
## Rendering Characteristics
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| **Detail level** | Variable — from rough to refined |
|
||||
| **Lighting** | Tonal shading, crosshatch |
|
||||
| **Texture** | Paper grain, graphite smudge |
|
||||
| **Color** | Grayscale (or limited color accents) |
|
||||
| **Depth** | Tonal depth through shading |
|
||||
|
||||
## 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
|
||||
@@ -0,0 +1,26 @@
|
||||
# Photorealistic
|
||||
|
||||
## Overview
|
||||
Images that look like real photographs — natural lighting, real textures, believable scenes.
|
||||
|
||||
## Rendering Characteristics
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| **Detail level** | High — realistic textures and materials |
|
||||
| **Lighting** | Natural or studio lighting |
|
||||
| **Texture** | True-to-life materials |
|
||||
| **Color** | Natural color palette |
|
||||
| **Depth** | Realistic depth of field |
|
||||
|
||||
## 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
|
||||
@@ -0,0 +1,25 @@
|
||||
# Watercolor
|
||||
|
||||
## Overview
|
||||
Soft, flowing artwork with transparent washes, organic edges, and painterly feel.
|
||||
|
||||
## Rendering Characteristics
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| **Detail level** | Low to medium — suggestive, not precise |
|
||||
| **Lighting** | Soft, diffused through paint |
|
||||
| **Texture** | Paper grain visible, paint bleeding at edges |
|
||||
| **Color** | Soft, transparent, blended |
|
||||
| **Depth** | Atmospheric — fades into white |
|
||||
|
||||
## 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
|
||||
@@ -0,0 +1,26 @@
|
||||
# Brutalist
|
||||
|
||||
## Overview
|
||||
Raw, bold, unapologetic design that breaks conventions intentionally.
|
||||
|
||||
## Visual Characteristics
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| **Whitespace** | Irregular — sometimes dense, sometimes empty |
|
||||
| **Color palette** | High contrast — black/white, neon accents |
|
||||
| **Typography** | Bold, oversized, mixed weights, sometimes monospace |
|
||||
| **Borders** | Thick, visible, sometimes raw |
|
||||
| **Shadows** | Hard/offset shadows or none |
|
||||
| **Imagery** | Raw, unprocessed, collage-style |
|
||||
| **Icons** | Custom, hand-drawn, or deliberately crude |
|
||||
|
||||
## 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
|
||||
@@ -0,0 +1,26 @@
|
||||
# Corporate
|
||||
|
||||
## Overview
|
||||
Professional, trustworthy design that communicates reliability and authority.
|
||||
|
||||
## Visual Characteristics
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| **Whitespace** | Moderate — structured but not sparse |
|
||||
| **Color palette** | Navy, gray, white + brand accent |
|
||||
| **Typography** | Sans-serif, regular to medium weight |
|
||||
| **Borders** | Clean, defined sections |
|
||||
| **Shadows** | Subtle card elevation |
|
||||
| **Imagery** | Professional photography, team shots, office environments |
|
||||
| **Icons** | Solid or duo-tone, consistent style |
|
||||
|
||||
## 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
|
||||
@@ -0,0 +1,26 @@
|
||||
# Editorial
|
||||
|
||||
## Overview
|
||||
Magazine-inspired design with strong typography hierarchy, editorial layouts, and storytelling focus.
|
||||
|
||||
## Visual Characteristics
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| **Whitespace** | Strategic — frames content like a magazine spread |
|
||||
| **Color palette** | Restrained — often monochrome with one accent |
|
||||
| **Typography** | Strong hierarchy, serif headlines, elegant spacing |
|
||||
| **Borders** | Thin rules, column dividers |
|
||||
| **Shadows** | Minimal |
|
||||
| **Imagery** | Full-bleed photography, editorial style |
|
||||
| **Icons** | Minimal use — typography carries the design |
|
||||
|
||||
## 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
|
||||
@@ -0,0 +1,26 @@
|
||||
# Minimal
|
||||
|
||||
## Overview
|
||||
Clean, spacious design with maximum whitespace and restrained use of elements.
|
||||
|
||||
## Visual Characteristics
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| **Whitespace** | Generous — elements breathe |
|
||||
| **Color palette** | Monochrome + one accent |
|
||||
| **Typography** | Sans-serif, thin to regular weight |
|
||||
| **Borders** | Hairline or none |
|
||||
| **Shadows** | None or very subtle |
|
||||
| **Imagery** | High-contrast, isolated subjects |
|
||||
| **Icons** | Line icons, consistent stroke width |
|
||||
|
||||
## Prompt Keywords
|
||||
`minimal, clean, whitespace, simple, uncluttered, modern, restrained, elegant simplicity`
|
||||
|
||||
## Best For
|
||||
- Portfolio sites, luxury brands, SaaS products, personal sites
|
||||
- Content-focused layouts where text is primary
|
||||
|
||||
## Avoid
|
||||
- Dense data displays, e-commerce with many products, playful brands
|
||||
@@ -0,0 +1,26 @@
|
||||
# Organic
|
||||
|
||||
## Overview
|
||||
Natural, warm design inspired by nature — soft shapes, earthy tones, flowing layouts.
|
||||
|
||||
## Visual Characteristics
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| **Whitespace** | Flowing — irregular but comfortable |
|
||||
| **Color palette** | Earth tones — greens, browns, warm neutrals |
|
||||
| **Typography** | Rounded sans-serif or serif, medium weight |
|
||||
| **Borders** | Rounded corners, organic shapes |
|
||||
| **Shadows** | Soft, diffused |
|
||||
| **Imagery** | Nature photography, textures, hand-drawn elements |
|
||||
| **Icons** | Rounded, organic line style |
|
||||
|
||||
## Prompt Keywords
|
||||
`organic, natural, warm, earthy, soft, flowing, nature-inspired, handcrafted, textured`
|
||||
|
||||
## Best For
|
||||
- Wellness, food, sustainability, outdoor brands, local businesses
|
||||
- Sites that want to feel human and approachable
|
||||
|
||||
## Avoid
|
||||
- High-tech, finance, enterprise software
|
||||
@@ -0,0 +1,26 @@
|
||||
# Playful
|
||||
|
||||
## Overview
|
||||
Fun, energetic design with bold colors, rounded shapes, and a sense of joy.
|
||||
|
||||
## Visual Characteristics
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| **Whitespace** | Moderate — lively but not cramped |
|
||||
| **Color palette** | Vibrant, multi-color, saturated |
|
||||
| **Typography** | Rounded, bold, sometimes quirky display fonts |
|
||||
| **Borders** | Rounded corners, chunky outlines |
|
||||
| **Shadows** | Colorful or offset shadows |
|
||||
| **Imagery** | Illustrations, cartoons, bright photography |
|
||||
| **Icons** | Filled, colorful, sometimes animated |
|
||||
|
||||
## Prompt Keywords
|
||||
`playful, fun, colorful, energetic, vibrant, cheerful, friendly, whimsical, bouncy`
|
||||
|
||||
## Best For
|
||||
- Children's products, games, education, creative tools, food delivery
|
||||
- Brands targeting younger audiences or wanting to feel approachable
|
||||
|
||||
## Avoid
|
||||
- Luxury, finance, healthcare, legal services
|
||||
665
_bmad/wds/workflows/6-asset-generation/data/tools-reference.md
Normal file
665
_bmad/wds/workflows/6-asset-generation/data/tools-reference.md
Normal file
@@ -0,0 +1,665 @@
|
||||
# Design Tools Reference for WDS
|
||||
|
||||
**Purpose:** Quick reference for design tools used in WDS workflows, particularly for prototype-to-Figma extraction.
|
||||
|
||||
---
|
||||
|
||||
## MCP Server (Primary Method)
|
||||
|
||||
**Purpose:** Precise component injection from HTML prototypes to Figma
|
||||
|
||||
**Use Case in WDS:** Extract specific components for visual refinement with full traceability
|
||||
|
||||
**See:** `mcp-server-integration.md` for complete documentation
|
||||
|
||||
### Features
|
||||
|
||||
**Component-Level Precision:**
|
||||
- Select specific components by Object ID
|
||||
- Inject individual components or sections
|
||||
- Batch component extraction
|
||||
- Granular control over what gets refined
|
||||
|
||||
**Conversion Capabilities:**
|
||||
- HTML structure → Figma frames
|
||||
- CSS styles → Figma styling
|
||||
- Layout (Flexbox/Grid) → Auto Layout
|
||||
- Text content → Text layers
|
||||
- Colors → Color fills
|
||||
- Spacing → Padding/gaps
|
||||
|
||||
**Preservation:**
|
||||
- Object IDs maintained in layer names
|
||||
- Element hierarchy preserved
|
||||
- Component boundaries respected
|
||||
- Traceability throughout workflow
|
||||
|
||||
### How to Use
|
||||
|
||||
**1. Prepare Prototype**
|
||||
```
|
||||
Ensure your HTML prototype:
|
||||
- Uses semantic HTML elements
|
||||
- Has Object IDs on all components (data-object-id)
|
||||
- Uses Flexbox or Grid for layouts
|
||||
- Has clean CSS structure
|
||||
```
|
||||
|
||||
**2. Inject via MCP Server**
|
||||
```bash
|
||||
# Single component
|
||||
wds figma inject btn-login-submit --file abc123
|
||||
|
||||
# Multiple components
|
||||
wds figma batch inject --list components.txt --file abc123
|
||||
|
||||
# Entire section
|
||||
wds figma inject-section login-form --file abc123
|
||||
```
|
||||
|
||||
**3. Verify in Figma**
|
||||
```
|
||||
- Open target Figma file
|
||||
- Navigate to injection page
|
||||
- Verify components injected correctly
|
||||
- Check Object IDs preserved
|
||||
```
|
||||
|
||||
**4. Read Refined Components Back**
|
||||
```bash
|
||||
# After designer refines in Figma
|
||||
wds figma read btn-login-submit --file abc123 --update-design-system
|
||||
```
|
||||
|
||||
### Advantages over Manual Upload
|
||||
|
||||
✅ **Component-level precision** - Inject only what needs refinement
|
||||
✅ **Object ID preservation** - Automatic mapping maintained
|
||||
✅ **Bidirectional sync** - Read refined components back
|
||||
✅ **Batch operations** - Efficient multi-component extraction
|
||||
✅ **Direct integration** - Seamless WDS workflow
|
||||
✅ **Automated token extraction** - Design system updates automatic
|
||||
|
||||
---
|
||||
|
||||
## html.to.design (Alternative Method)
|
||||
|
||||
**Purpose:** Manual HTML to Figma conversion (fallback option)
|
||||
|
||||
**Website:** <https://html.to.design>
|
||||
|
||||
**Use Case in WDS:** When MCP server unavailable or for full-page extraction
|
||||
|
||||
**Note:** MCP server approach is preferred for component-level precision and traceability.
|
||||
|
||||
### When to Use html.to.design
|
||||
|
||||
**Use when:**
|
||||
- MCP server not configured
|
||||
- Need to extract entire page at once
|
||||
- Quick one-off conversion needed
|
||||
- Exploring design possibilities
|
||||
|
||||
**Don't use when:**
|
||||
- MCP server available (use MCP instead)
|
||||
- Need component-level precision
|
||||
- Require Object ID traceability
|
||||
- Planning iterative refinement
|
||||
|
||||
### How to Use
|
||||
|
||||
**1. Prepare Prototype**
|
||||
```
|
||||
Ensure your HTML prototype:
|
||||
- Uses semantic HTML elements
|
||||
- Has clean CSS structure
|
||||
- Uses Flexbox or Grid for layouts
|
||||
```
|
||||
|
||||
**2. Upload to html.to.design**
|
||||
```
|
||||
1. Go to https://html.to.design
|
||||
2. Upload HTML file
|
||||
3. Include associated CSS files
|
||||
4. Select target: Figma
|
||||
```
|
||||
|
||||
**3. Import to Figma**
|
||||
```
|
||||
1. Download converted Figma file
|
||||
2. Open in Figma
|
||||
3. Manually add Object IDs to layers
|
||||
4. Begin refinement
|
||||
```
|
||||
|
||||
**Limitations:**
|
||||
- No automatic Object ID preservation
|
||||
- Entire page extraction (less precise)
|
||||
- Manual token extraction required
|
||||
- No automated design system sync
|
||||
|
||||
### Best Practices
|
||||
|
||||
**DO ✅**
|
||||
- Use semantic HTML (header, nav, main, section, article)
|
||||
- Apply consistent class naming
|
||||
- Use Flexbox/Grid for layouts
|
||||
- Include Object IDs for traceability
|
||||
- Clean up HTML before extraction
|
||||
- Test prototype before extracting
|
||||
|
||||
**DON'T ❌**
|
||||
- Use complex CSS positioning (absolute, fixed)
|
||||
- Rely on JavaScript-generated content
|
||||
- Use inline styles excessively
|
||||
- Have deeply nested structures
|
||||
- Include debug/test code
|
||||
- Extract incomplete prototypes
|
||||
|
||||
### Limitations
|
||||
|
||||
**What Works Well:**
|
||||
- Standard layouts (header, content, footer)
|
||||
- Flexbox and Grid layouts
|
||||
- Text content and typography
|
||||
- Basic styling (colors, spacing, borders)
|
||||
- Image placeholders
|
||||
- Component-based structures
|
||||
|
||||
**What May Need Manual Adjustment:**
|
||||
- Complex animations
|
||||
- JavaScript-driven interactions
|
||||
- Dynamic content
|
||||
- Custom SVG graphics
|
||||
- Advanced CSS effects
|
||||
- Responsive breakpoints
|
||||
|
||||
### Tips for Better Extraction
|
||||
|
||||
**1. Simplify Structure**
|
||||
```html
|
||||
<!-- Before: Complex nesting -->
|
||||
<div class="wrapper">
|
||||
<div class="container">
|
||||
<div class="inner">
|
||||
<div class="content">Text</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- After: Simplified -->
|
||||
<div class="content-wrapper">
|
||||
<p>Text</p>
|
||||
</div>
|
||||
```
|
||||
|
||||
**2. Use Flexbox/Grid**
|
||||
```css
|
||||
/* Preferred: Flexbox */
|
||||
.container {
|
||||
display: flex;
|
||||
gap: 16px;
|
||||
padding: 24px;
|
||||
}
|
||||
|
||||
/* Avoid: Absolute positioning */
|
||||
.item {
|
||||
position: absolute;
|
||||
top: 50px;
|
||||
left: 100px;
|
||||
}
|
||||
```
|
||||
|
||||
**3. Include Object IDs**
|
||||
```html
|
||||
<!-- Good: Object ID for traceability -->
|
||||
<button data-object-id="btn-login-submit" class="btn-primary">
|
||||
Log In
|
||||
</button>
|
||||
```
|
||||
|
||||
**4. Clean CSS**
|
||||
```css
|
||||
/* Preferred: Token-based */
|
||||
.button {
|
||||
background: var(--color-primary-600);
|
||||
padding: var(--spacing-md) var(--spacing-lg);
|
||||
border-radius: var(--radius-md);
|
||||
}
|
||||
|
||||
/* Avoid: Hardcoded values scattered -->
|
||||
.button {
|
||||
background: #2563eb;
|
||||
padding: 12px 16px;
|
||||
border-radius: 8px;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## NanoBanana
|
||||
|
||||
**Purpose:** Agent-driven asset creation, design inspiration, and sketch envisioning tool
|
||||
|
||||
**Website:** <https://nanobanana.com>
|
||||
|
||||
**Use Cases in WDS:**
|
||||
1. Create visual design assets and explore design concepts
|
||||
2. Convert sketches/specifications to visual designs (images or code)
|
||||
3. Generate design inspiration and placeholder assets
|
||||
|
||||
**Output Formats:**
|
||||
- Images (visual designs, graphics)
|
||||
- Code snippets (HTML/CSS/React)
|
||||
|
||||
**Description:** Agent-driven Photoshop - AI-powered tool for visual asset creation and design exploration
|
||||
|
||||
### Features
|
||||
|
||||
**Asset Creation Capabilities:**
|
||||
- Visual design generation
|
||||
- Design inspiration and variations
|
||||
- Custom graphics and icons
|
||||
- Image assets
|
||||
- Design concept exploration
|
||||
- Possibly code export for certain elements
|
||||
|
||||
### Integration with WDS
|
||||
|
||||
**Workflow:**
|
||||
```
|
||||
Design Concept
|
||||
→ NanoBanana (create assets/inspiration)
|
||||
→ Visual Assets/Design Ideas
|
||||
→ Import to Figma for refinement
|
||||
→ Integrate into Design System
|
||||
→ Use in Prototypes
|
||||
```
|
||||
|
||||
**When to Use:**
|
||||
- Need visual design inspiration
|
||||
- Creating custom graphics/assets
|
||||
- Exploring design variations
|
||||
- Generating design concepts
|
||||
- Creating placeholder visuals
|
||||
- Brand identity exploration
|
||||
|
||||
**When to Skip:**
|
||||
- Have existing design assets
|
||||
- Working with established brand
|
||||
- Simple text/layout designs
|
||||
- Using stock assets
|
||||
- Strict brand guidelines
|
||||
|
||||
### Best Practices
|
||||
|
||||
**DO ✅**
|
||||
- Use for creative exploration
|
||||
- Generate multiple variations
|
||||
- Refine AI-generated assets
|
||||
- Use as inspiration starting point
|
||||
- Integrate refined assets into design system
|
||||
- Document asset sources
|
||||
|
||||
**DON'T ❌**
|
||||
- Replace human design thinking
|
||||
- Skip refinement process
|
||||
- Ignore brand guidelines
|
||||
- Use without customization
|
||||
- Rely solely on AI output
|
||||
- Skip quality review
|
||||
|
||||
---
|
||||
|
||||
## Area Tag System
|
||||
|
||||
**Purpose:** Precise region mapping in HTML prototypes for interactive hotspots
|
||||
|
||||
**Use Case in WDS:** Map clickable regions on image-based prototypes or complex UI elements
|
||||
|
||||
### What Are Area Tags?
|
||||
|
||||
HTML `<area>` elements within `<map>` tags that define clickable regions on images:
|
||||
|
||||
```html
|
||||
<img src="prototype-screenshot.png" usemap="#prototype-map" alt="Prototype">
|
||||
|
||||
<map name="prototype-map">
|
||||
<area shape="rect"
|
||||
coords="100,50,300,150"
|
||||
data-object-id="btn-login"
|
||||
alt="Login Button"
|
||||
href="#login">
|
||||
<area shape="rect"
|
||||
coords="100,200,300,250"
|
||||
data-object-id="link-signup"
|
||||
alt="Sign Up Link"
|
||||
href="#signup">
|
||||
</map>
|
||||
```
|
||||
|
||||
### When to Use Area Tags
|
||||
|
||||
**Use When:**
|
||||
- Working with image-based prototypes
|
||||
- Need precise click mapping
|
||||
- Complex UI with overlapping elements
|
||||
- Screenshot-based specifications
|
||||
- Testing click regions
|
||||
|
||||
**Don't Use When:**
|
||||
- HTML elements are clickable directly
|
||||
- Simple button/link interactions
|
||||
- Fully interactive prototype exists
|
||||
- Accessibility is primary concern
|
||||
|
||||
### Integration with Dev Mode
|
||||
|
||||
The dev-mode.js component can extract area tag coordinates:
|
||||
|
||||
```javascript
|
||||
// Dev mode detects area tags
|
||||
document.querySelectorAll('area').forEach(area => {
|
||||
const coords = area.coords;
|
||||
const objectId = area.dataset.objectId;
|
||||
console.log(`${objectId}: ${coords}`);
|
||||
});
|
||||
```
|
||||
|
||||
### Creating Area Tags
|
||||
|
||||
**1. Get Coordinates**
|
||||
```
|
||||
Use image editor or browser dev tools:
|
||||
- Top-left corner: (x1, y1)
|
||||
- Bottom-right corner: (x2, y2)
|
||||
- Format: "x1,y1,x2,y2"
|
||||
```
|
||||
|
||||
**2. Define Area**
|
||||
```html
|
||||
<area shape="rect"
|
||||
coords="x1,y1,x2,y2"
|
||||
data-object-id="unique-id"
|
||||
alt="Description"
|
||||
href="#target">
|
||||
```
|
||||
|
||||
**3. Link to Map**
|
||||
```html
|
||||
<img src="image.png" usemap="#mapname">
|
||||
<map name="mapname">
|
||||
<!-- area tags here -->
|
||||
</map>
|
||||
```
|
||||
|
||||
### Best Practices
|
||||
|
||||
**DO ✅**
|
||||
- Include Object IDs in data attributes
|
||||
- Provide descriptive alt text
|
||||
- Test all clickable regions
|
||||
- Document area mappings
|
||||
- Use for image-based prototypes
|
||||
|
||||
**DON'T ❌**
|
||||
- Use for fully interactive HTML prototypes
|
||||
- Forget accessibility considerations
|
||||
- Overlap areas without purpose
|
||||
- Skip testing on different screen sizes
|
||||
- Use as replacement for proper HTML
|
||||
|
||||
### Accessibility Considerations
|
||||
|
||||
Area tags have limitations:
|
||||
- Not keyboard accessible by default
|
||||
- Screen readers may not announce properly
|
||||
- Better to use actual HTML elements when possible
|
||||
|
||||
**Workaround:**
|
||||
```html
|
||||
<!-- Add keyboard support -->
|
||||
<area shape="rect"
|
||||
coords="100,50,300,150"
|
||||
data-object-id="btn-login"
|
||||
alt="Login Button"
|
||||
href="#login"
|
||||
tabindex="0"
|
||||
role="button">
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Dev Mode Component
|
||||
|
||||
**Purpose:** Interactive tool for extracting Object IDs and area coordinates from prototypes
|
||||
|
||||
**Location:** `workflows/4-ux-design/agentic-development/templates/components/dev-mode.js`
|
||||
|
||||
### Features
|
||||
|
||||
**Object ID Extraction:**
|
||||
- Hold Shift + Click to copy Object IDs
|
||||
- Visual highlights when Shift held
|
||||
- Tooltip display on hover
|
||||
- Success feedback when copied
|
||||
- Form field protection
|
||||
|
||||
**Area Tag Extraction:**
|
||||
- Detect area tags in prototype
|
||||
- Extract coordinates
|
||||
- Map to Object IDs
|
||||
- Export for documentation
|
||||
|
||||
### Usage
|
||||
|
||||
**1. Include in Prototype**
|
||||
```html
|
||||
<script src="shared/dev-mode.js"></script>
|
||||
```
|
||||
|
||||
**2. Activate Dev Mode**
|
||||
```
|
||||
- Click "Dev Mode" button, or
|
||||
- Press Ctrl+E (Cmd+E on Mac)
|
||||
```
|
||||
|
||||
**3. Extract Object IDs**
|
||||
```
|
||||
- Hold Shift
|
||||
- Click on element
|
||||
- Object ID copied to clipboard
|
||||
```
|
||||
|
||||
**4. Extract Area Coordinates**
|
||||
```
|
||||
- Dev mode detects area tags
|
||||
- Displays coordinates
|
||||
- Exports mapping data
|
||||
```
|
||||
|
||||
### Integration with html.to.design
|
||||
|
||||
**Workflow:**
|
||||
```
|
||||
1. Create prototype with Object IDs
|
||||
2. Use dev mode to verify Object IDs
|
||||
3. Extract to Figma via html.to.design
|
||||
4. Object IDs preserved in layer names
|
||||
5. Maintain traceability
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tool Comparison
|
||||
|
||||
| Tool | Category | Primary Use | Input | Output | WDS Use Case |
|
||||
|------|----------|-------------|-------|--------|--------------|
|
||||
| **MCP Server** | Figma Integration | Automated sync | HTML + Object ID | Figma components | Precise refinement (PRIMARY) |
|
||||
| **html.to.design** | HTML → Figma | Full-page conversion | HTML/CSS | Figma file | Fallback method (OPTIONAL) |
|
||||
| **NanoBanana** | AI Design | Asset creation + Sketch envisioning | Text/Sketch/Spec | Images or Code | Early exploration OR sketch-to-design (OPTIONAL) |
|
||||
| **Area Tags** | Region mapping | Clickable regions | Image + coords | Clickable map | Image prototypes |
|
||||
| **Dev Mode** | ID extraction | Object ID tracking | Prototype | Object IDs | Traceability |
|
||||
|
||||
---
|
||||
|
||||
## Recommended Workflow
|
||||
|
||||
### Standard Flow (MCP Server - Recommended)
|
||||
|
||||
```
|
||||
1. Create specification (Phase 4C)
|
||||
2. Build HTML prototype manually (Phase 4D)
|
||||
3. Add Object IDs to all components
|
||||
4. Test functionality
|
||||
5. Inject specific components to Figma via MCP server (if needed)
|
||||
6. Refine in Figma
|
||||
7. Read refined components via MCP server
|
||||
8. Design system auto-updated
|
||||
9. Re-render prototype
|
||||
```
|
||||
|
||||
**Advantages:**
|
||||
- Component-level precision
|
||||
- Object ID traceability maintained
|
||||
- Automated design system updates
|
||||
- Bidirectional sync
|
||||
|
||||
### Alternative Flow (Manual Upload - Fallback)
|
||||
|
||||
```
|
||||
1. Create specification (Phase 4C)
|
||||
2. Build HTML prototype manually (Phase 4D)
|
||||
3. Add Object IDs to all elements
|
||||
4. Test functionality
|
||||
5. Upload to html.to.design (if MCP unavailable)
|
||||
6. Manually add Object IDs to Figma layers
|
||||
7. Refine in Figma
|
||||
8. Manually extract design tokens
|
||||
9. Update design system manually
|
||||
10. Re-render prototype
|
||||
```
|
||||
|
||||
**Use when:** MCP server not available
|
||||
|
||||
### With Asset Creation (NanoBanana - Optional)
|
||||
|
||||
```
|
||||
1. Create specification (Phase 4C)
|
||||
2. Use NanoBanana for design inspiration/assets (optional)
|
||||
3. Import assets to Figma
|
||||
4. Build HTML prototype manually (Phase 4D)
|
||||
5. Add Object IDs to all components
|
||||
6. Test functionality
|
||||
7. Inject to Figma via MCP server (if needed)
|
||||
8. Refine in Figma (with NanoBanana assets)
|
||||
9. Read back via MCP server
|
||||
10. Design system auto-updated
|
||||
11. Re-render prototype
|
||||
```
|
||||
|
||||
**Use NanoBanana for:**
|
||||
- Creating custom graphics/icons
|
||||
- Generating design inspiration
|
||||
- Exploring visual concepts
|
||||
- Creating placeholder assets
|
||||
|
||||
### Image-Based Flow (With Area Tags)
|
||||
|
||||
```
|
||||
1. Create specification (Phase 4C)
|
||||
2. Create image-based prototype
|
||||
3. Add area tags for clickable regions
|
||||
4. Include Object IDs in area tags
|
||||
5. Test click regions
|
||||
6. Extract to Figma via html.to.design
|
||||
7. Refine in Figma
|
||||
8. Convert to HTML prototype
|
||||
9. Update design system
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Cost Considerations
|
||||
|
||||
### html.to.design
|
||||
- Free tier available
|
||||
- Paid plans for advanced features
|
||||
- Check current pricing at website
|
||||
|
||||
### NanoBanana
|
||||
- Pricing varies by usage
|
||||
- Check current pricing at website
|
||||
- Consider cost vs time savings
|
||||
|
||||
### Area Tags
|
||||
- Free (standard HTML)
|
||||
- No additional cost
|
||||
|
||||
### Dev Mode
|
||||
- Free (included in WDS)
|
||||
- No additional cost
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### html.to.design Issues
|
||||
|
||||
**Problem:** Layout not preserved
|
||||
**Solution:** Use Flexbox/Grid, simplify structure
|
||||
|
||||
**Problem:** Styles not converted
|
||||
**Solution:** Use standard CSS properties, avoid complex selectors
|
||||
|
||||
**Problem:** Text content missing
|
||||
**Solution:** Ensure text is in HTML, not JavaScript-generated
|
||||
|
||||
### NanoBanana Issues
|
||||
|
||||
**Problem:** Generated code doesn't match design system
|
||||
**Solution:** Customize output, apply design system manually
|
||||
|
||||
**Problem:** Complex interactions not generated correctly
|
||||
**Solution:** Review and rewrite interaction logic
|
||||
|
||||
### Area Tag Issues
|
||||
|
||||
**Problem:** Clicks not registering
|
||||
**Solution:** Verify coordinates, check map name matches
|
||||
|
||||
**Problem:** Accessibility concerns
|
||||
**Solution:** Add keyboard support, use actual HTML when possible
|
||||
|
||||
### Dev Mode Issues
|
||||
|
||||
**Problem:** Object IDs not copying
|
||||
**Solution:** Check Shift key, verify Object IDs exist
|
||||
|
||||
**Problem:** Dev mode not activating
|
||||
**Solution:** Check script loaded, try Ctrl+E
|
||||
|
||||
---
|
||||
|
||||
## Resources
|
||||
|
||||
**html.to.design:**
|
||||
- Website: <https://html.to.design>
|
||||
- Documentation: Check website for latest docs
|
||||
|
||||
**NanoBanana:**
|
||||
- Website: <https://nanobanana.com>
|
||||
- Documentation: Check website for latest docs
|
||||
|
||||
**HTML Area Tags:**
|
||||
- MDN Reference: <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/area>
|
||||
- W3C Spec: <https://www.w3.org/TR/html52/semantics-embedded-content.html#the-area-element>
|
||||
|
||||
**WDS Documentation:**
|
||||
- Prototype Workflow: `workflows/4-ux-design/agentic-development/`
|
||||
- Figma Integration: `workflows/6-asset-generation/workflow-figma.md`
|
||||
- Dev Mode: `workflows/4-ux-design/agentic-development/templates/components/`
|
||||
|
||||
---
|
||||
|
||||
**This reference provides quick access to tool information for WDS design workflows. For detailed workflows, see the specific workflow documentation files.**
|
||||
@@ -0,0 +1,663 @@
|
||||
# When to Extract Prototypes to Figma - Decision Guide
|
||||
|
||||
**Purpose:** Help designers decide when to extract HTML prototypes to Figma for visual refinement.
|
||||
|
||||
**Quick Answer:** Extract when the design system is incomplete and the prototype needs visual polish.
|
||||
|
||||
---
|
||||
|
||||
## Decision Tree
|
||||
|
||||
```
|
||||
Prototype Created
|
||||
↓
|
||||
Does it look polished?
|
||||
↓
|
||||
┌─────┴─────┐
|
||||
YES NO
|
||||
↓ ↓
|
||||
Complete Is design system incomplete?
|
||||
↓
|
||||
┌─────┴─────┐
|
||||
YES NO
|
||||
↓ ↓
|
||||
Extract to Quick CSS fixes
|
||||
Figma sufficient
|
||||
↓
|
||||
Refine design
|
||||
↓
|
||||
Update design system
|
||||
↓
|
||||
Re-render prototype
|
||||
↓
|
||||
Iterate or Complete
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Assessment Checklist
|
||||
|
||||
### ✅ Extract to Figma if:
|
||||
|
||||
- [ ] Prototype not visually appealing or unpolished
|
||||
- [ ] Design system missing components for this view
|
||||
- [ ] Need to define new design tokens (colors, spacing, typography)
|
||||
- [ ] Stakeholder presentation requires high-fidelity
|
||||
- [ ] Multiple similar components need standardization
|
||||
- [ ] Visual hierarchy unclear
|
||||
- [ ] Spacing/alignment inconsistent
|
||||
|
||||
### ❌ Don't Extract if:
|
||||
|
||||
- [ ] Prototype already looks good
|
||||
- [ ] Design system covers all needs
|
||||
- [ ] Still validating functionality
|
||||
- [ ] Rapid iteration more important than polish
|
||||
- [ ] Early exploration phase
|
||||
- [ ] Internal testing only
|
||||
|
||||
---
|
||||
|
||||
## Scenarios
|
||||
|
||||
### Scenario 1: First Page in Project
|
||||
|
||||
**Situation:** Creating first prototype, design system is empty
|
||||
|
||||
**Decision:** ✅ **Extract to Figma**
|
||||
|
||||
**Reason:** Need to establish design foundation
|
||||
- Define color palette
|
||||
- Set typography scale
|
||||
- Create spacing system
|
||||
- Build first components
|
||||
|
||||
**Workflow:**
|
||||
1. Create basic prototype (functional)
|
||||
2. Extract to Figma
|
||||
3. Define complete design system
|
||||
4. Re-render with design system
|
||||
5. Use for all subsequent pages
|
||||
|
||||
---
|
||||
|
||||
### Scenario 2: Similar to Existing Pages
|
||||
|
||||
**Situation:** Design system already has most components needed
|
||||
|
||||
**Decision:** ❌ **Don't Extract**
|
||||
|
||||
**Reason:** Design system sufficient
|
||||
- Reuse existing components
|
||||
- Apply existing tokens
|
||||
- Minor variations can be CSS tweaks
|
||||
|
||||
**Workflow:**
|
||||
1. Create prototype with design system
|
||||
2. Test functionality
|
||||
3. Make minor CSS adjustments if needed
|
||||
4. Complete
|
||||
|
||||
---
|
||||
|
||||
### Scenario 3: New Component Type Needed
|
||||
|
||||
**Situation:** Page needs component type not in design system (e.g., data table)
|
||||
|
||||
**Decision:** ✅ **Extract to Figma**
|
||||
|
||||
**Reason:** Need to design new component properly
|
||||
- Define component structure
|
||||
- Create variants and states
|
||||
- Document design tokens
|
||||
- Add to design system
|
||||
|
||||
**Workflow:**
|
||||
1. Create basic prototype
|
||||
2. Extract to Figma
|
||||
3. Design new component thoroughly
|
||||
4. Add to design system
|
||||
5. Re-render prototype
|
||||
6. Component now available for future use
|
||||
|
||||
---
|
||||
|
||||
### Scenario 4: Stakeholder Presentation
|
||||
|
||||
**Situation:** Working prototype exists but looks basic, client review tomorrow
|
||||
|
||||
**Decision:** ✅ **Extract to Figma**
|
||||
|
||||
**Reason:** Need polished visuals for presentation
|
||||
- Apply professional styling
|
||||
- Refine visual hierarchy
|
||||
- Add polish (shadows, effects)
|
||||
- Create presentation-ready mockups
|
||||
|
||||
**Workflow:**
|
||||
1. Extract current prototype
|
||||
2. Polish in Figma quickly
|
||||
3. Present Figma mockups
|
||||
4. After approval, update design system
|
||||
5. Re-render for development
|
||||
|
||||
---
|
||||
|
||||
### Scenario 5: Rapid Prototyping Phase
|
||||
|
||||
**Situation:** Testing multiple concepts quickly, designs will change
|
||||
|
||||
**Decision:** ❌ **Don't Extract**
|
||||
|
||||
**Reason:** Too early for polish
|
||||
- Focus on functionality
|
||||
- Validate concepts first
|
||||
- Avoid polishing throwaway work
|
||||
|
||||
**Workflow:**
|
||||
1. Create basic prototypes
|
||||
2. Test with users
|
||||
3. Iterate on functionality
|
||||
4. Once concept validated, then extract for polish
|
||||
|
||||
---
|
||||
|
||||
## Design System Maturity Levels
|
||||
|
||||
### Level 1: Empty (0-5 components)
|
||||
|
||||
**Typical Decision:** Extract to Figma
|
||||
**Reason:** Need to build foundation
|
||||
**Focus:** Establish design tokens and core components
|
||||
|
||||
### Level 2: Growing (6-15 components)
|
||||
|
||||
**Typical Decision:** Extract when gaps found
|
||||
**Reason:** Fill missing pieces
|
||||
**Focus:** Expand component library strategically
|
||||
|
||||
### Level 3: Mature (16+ components)
|
||||
|
||||
**Typical Decision:** Rarely extract
|
||||
**Reason:** Most needs covered
|
||||
**Focus:** Reuse existing, minor variations only
|
||||
|
||||
---
|
||||
|
||||
## Cost-Benefit Analysis
|
||||
|
||||
### Benefits of Extracting
|
||||
|
||||
**Design Quality:**
|
||||
- Professional visual polish
|
||||
- Consistent design system
|
||||
- Reusable components
|
||||
- Better stakeholder buy-in
|
||||
|
||||
**Long-term Efficiency:**
|
||||
- Design system grows
|
||||
- Future prototypes faster
|
||||
- Reduced design debt
|
||||
- Team alignment
|
||||
|
||||
### Costs of Extracting
|
||||
|
||||
**Time Investment:**
|
||||
- Extraction process: 15-30 min
|
||||
- Figma refinement: 1-3 hours
|
||||
- Design system update: 30-60 min
|
||||
- Re-rendering: 15-30 min
|
||||
- **Total: 2-5 hours per page**
|
||||
|
||||
**Workflow Overhead:**
|
||||
- Context switching
|
||||
- Tool learning curve
|
||||
- Sync maintenance
|
||||
- Version tracking
|
||||
|
||||
---
|
||||
|
||||
## When Time is Limited
|
||||
|
||||
### High Priority: Extract
|
||||
|
||||
**These pages justify the time investment:**
|
||||
- Landing pages (first impression)
|
||||
- Onboarding flows (user retention)
|
||||
- Checkout/payment (conversion critical)
|
||||
- Dashboard (frequent use)
|
||||
- Marketing pages (brand representation)
|
||||
|
||||
### Lower Priority: Skip
|
||||
|
||||
**These pages can stay basic:**
|
||||
- Admin panels (internal use)
|
||||
- Error pages (rare views)
|
||||
- Settings pages (utility focus)
|
||||
- Debug/test pages (temporary)
|
||||
|
||||
---
|
||||
|
||||
## Team Collaboration Factors
|
||||
|
||||
### Extract When:
|
||||
|
||||
**Designer-Developer Collaboration:**
|
||||
- Designer needs to define visual direction
|
||||
- Developer needs clear component specs
|
||||
- Team needs shared design language
|
||||
|
||||
**Stakeholder Communication:**
|
||||
- Client needs to approve visuals
|
||||
- Marketing needs branded materials
|
||||
- Sales needs demo materials
|
||||
|
||||
### Skip When:
|
||||
|
||||
**Solo Development:**
|
||||
- One person doing design + dev
|
||||
- Direct implementation faster
|
||||
- No handoff needed
|
||||
|
||||
**Internal Tools:**
|
||||
- Team understands context
|
||||
- Functionality over aesthetics
|
||||
- Rapid iteration valued
|
||||
|
||||
---
|
||||
|
||||
## Quality Thresholds
|
||||
|
||||
### Extract if Prototype Has:
|
||||
|
||||
**Visual Issues:**
|
||||
- Inconsistent spacing
|
||||
- Poor typography hierarchy
|
||||
- Clashing colors
|
||||
- Misaligned elements
|
||||
- Unclear visual hierarchy
|
||||
|
||||
**Missing Design Elements:**
|
||||
- No hover states
|
||||
- Missing loading states
|
||||
- Incomplete error states
|
||||
- No disabled states
|
||||
- Basic placeholder styling
|
||||
|
||||
**Component Gaps:**
|
||||
- Custom components needed
|
||||
- Existing components insufficient
|
||||
- New patterns required
|
||||
- Variant expansion needed
|
||||
|
||||
### Don't Extract if Prototype Has:
|
||||
|
||||
**Sufficient Quality:**
|
||||
- Consistent spacing
|
||||
- Clear hierarchy
|
||||
- Appropriate colors
|
||||
- Aligned elements
|
||||
- Professional appearance
|
||||
|
||||
**Complete Design System Coverage:**
|
||||
- All components available
|
||||
- States defined
|
||||
- Variants sufficient
|
||||
- Tokens applied
|
||||
|
||||
---
|
||||
|
||||
## Iteration Strategy
|
||||
|
||||
### First Iteration
|
||||
|
||||
**Always extract if:**
|
||||
- Establishing design foundation
|
||||
- First page in project
|
||||
- Setting visual direction
|
||||
|
||||
### Subsequent Iterations
|
||||
|
||||
**Extract only if:**
|
||||
- Significant design system gaps
|
||||
- New component types needed
|
||||
- Visual quality insufficient
|
||||
|
||||
### Final Iteration
|
||||
|
||||
**Extract if:**
|
||||
- Stakeholder presentation
|
||||
- Production launch
|
||||
- Marketing materials needed
|
||||
|
||||
---
|
||||
|
||||
## Practical Examples
|
||||
|
||||
### Example 1: E-commerce Product Page
|
||||
|
||||
**Phase 1: Sketch (Concept)**
|
||||
- Designer creates hand-drawn sketch of product page
|
||||
- Shows product gallery, reviews section, rating display
|
||||
- Rough layout and component placement
|
||||
|
||||
**Phase 2: Specification (Phase 4C)**
|
||||
- Freya analyzes sketch
|
||||
- Creates detailed specification:
|
||||
- Product gallery: Image carousel with thumbnails
|
||||
- Reviews component: User avatar, rating, text, date
|
||||
- Rating stars: 5-star display with half-star support
|
||||
- All Object IDs defined
|
||||
- Content and interactions specified
|
||||
|
||||
**Phase 3: Prototype (Phase 4D)**
|
||||
- Freya builds functional HTML prototype
|
||||
- Uses existing design system (buttons, inputs, cards)
|
||||
- Product gallery, reviews, ratings are basic/functional but unpolished
|
||||
|
||||
**Initial Assessment:**
|
||||
- Prototype works functionally ✅
|
||||
- Design system has: buttons, inputs, cards
|
||||
- Missing: product gallery, reviews component, rating stars (visual refinement needed)
|
||||
|
||||
**Decision:** ✅ Extract to Figma
|
||||
|
||||
**Phase 4: Figma Refinement**
|
||||
|
||||
Freya automatically:
|
||||
1. Analyzes prototype components
|
||||
2. Identifies missing components (gallery, reviews, ratings)
|
||||
3. Injects to Figma via MCP server
|
||||
4. Page: `02-Product-Catalog / 2.3-Product-Detail`
|
||||
|
||||
Designer in Figma:
|
||||
5. Designs product gallery component (image zoom, transitions)
|
||||
6. Designs reviews component (typography, spacing, layout)
|
||||
7. Designs rating component (star icons, colors, states)
|
||||
8. Applies design tokens (colors, spacing, typography)
|
||||
|
||||
**Phase 5: Design System Update**
|
||||
|
||||
Freya automatically:
|
||||
9. Reads refined components from Figma
|
||||
10. Extracts design tokens
|
||||
11. Updates design system:
|
||||
- `D-Design-System/components/product-gallery.md`
|
||||
- `D-Design-System/components/review-card.md`
|
||||
- `D-Design-System/components/rating-stars.md`
|
||||
|
||||
**Phase 6: Re-render**
|
||||
12. Freya re-renders prototype with enhanced design system
|
||||
13. Prototype now polished and professional
|
||||
|
||||
**Result:**
|
||||
- ✅ Polished product page
|
||||
- ✅ 3 new reusable components in design system
|
||||
- ✅ Specification updated (if design evolved)
|
||||
- ✅ All future product pages can use these components
|
||||
|
||||
---
|
||||
|
||||
### Example 2: Settings Page
|
||||
|
||||
**Phase 1: Sketch (Concept)**
|
||||
- Designer creates simple sketch of settings page
|
||||
- Shows form fields, toggles, save button
|
||||
- Standard layout, no custom components
|
||||
|
||||
**Phase 2: Specification (Phase 4C)**
|
||||
- Freya analyzes sketch
|
||||
- Creates specification:
|
||||
- Form fields: Email, password, notifications
|
||||
- Toggle switches: Email notifications, push notifications
|
||||
- Save button: Standard primary button
|
||||
- All components exist in design system
|
||||
|
||||
**Phase 3: Prototype (Phase 4D)**
|
||||
- Freya builds HTML prototype
|
||||
- Uses existing design system components:
|
||||
- Form inputs (already designed)
|
||||
- Toggle switches (already designed)
|
||||
- Buttons (already designed)
|
||||
- Prototype looks polished immediately
|
||||
|
||||
**Initial Assessment:**
|
||||
- Prototype works functionally ✅
|
||||
- Prototype looks polished ✅
|
||||
- Design system has: forms, toggles, buttons
|
||||
- All components available
|
||||
- Internal use only
|
||||
|
||||
**Decision:** ❌ Don't Extract
|
||||
|
||||
**Actions:**
|
||||
1. Apply existing design system ✅ (already done)
|
||||
2. Minor CSS tweaks for spacing (if needed)
|
||||
3. Test functionality ✅
|
||||
4. Complete ✅
|
||||
|
||||
**Result:**
|
||||
- ✅ Functional, polished page in 30 minutes
|
||||
- ✅ No Figma extraction needed
|
||||
- ✅ Design system reuse successful
|
||||
|
||||
---
|
||||
|
||||
### Example 3: Landing Page
|
||||
|
||||
**Phase 1: Sketch (Concept)**
|
||||
- Designer creates detailed sketch of landing page
|
||||
- Hero section with headline, subtext, CTA
|
||||
- Feature cards with icons and descriptions
|
||||
- Testimonials with photos and quotes
|
||||
- Multiple CTA sections throughout
|
||||
|
||||
**Phase 2: Specification (Phase 4C)**
|
||||
- Freya analyzes sketch
|
||||
- Creates comprehensive specification:
|
||||
- Hero section: Large headline, supporting text, primary CTA
|
||||
- Feature cards: Icon, title, description, learn more link
|
||||
- Testimonials: User photo, quote, name, company
|
||||
- CTA sections: Headline, button, background treatment
|
||||
- All Object IDs defined
|
||||
- Multi-language content specified
|
||||
|
||||
**Phase 3: Prototype (Phase 4D)**
|
||||
- Freya builds functional HTML prototype
|
||||
- Uses basic design system components
|
||||
- Hero, features, testimonials are functional but basic
|
||||
- Client presentation in one week (high priority!)
|
||||
|
||||
**Initial Assessment:**
|
||||
- Prototype works functionally ✅
|
||||
- Design system has basic components
|
||||
- Needs visual refinement: hero section, feature cards, testimonials, CTA sections
|
||||
- Client presentation next week (high stakes!)
|
||||
|
||||
**Decision:** ✅ Extract to Figma
|
||||
|
||||
**Phase 4: Figma Refinement**
|
||||
|
||||
Freya automatically:
|
||||
1. Analyzes prototype components
|
||||
2. Identifies components needing refinement (hero, features, testimonials, CTAs)
|
||||
3. Injects to Figma via MCP server
|
||||
4. Page: `01-Marketing / 1.1-Landing-Page`
|
||||
|
||||
Designer in Figma:
|
||||
5. Designs hero component (brand-critical, high impact)
|
||||
6. Designs feature cards (icons, layout, spacing)
|
||||
7. Designs testimonial component (photos, typography)
|
||||
8. Polishes CTA sections (visual hierarchy, contrast)
|
||||
9. Applies brand colors, typography, spacing tokens
|
||||
|
||||
**Phase 5: Design System Update**
|
||||
|
||||
Freya automatically:
|
||||
10. Reads refined components from Figma
|
||||
11. Extracts design tokens and components
|
||||
12. Updates design system:
|
||||
- `D-Design-System/components/hero-section.md`
|
||||
- `D-Design-System/components/feature-card.md`
|
||||
- `D-Design-System/components/testimonial.md`
|
||||
- `D-Design-System/components/cta-section.md`
|
||||
|
||||
**Phase 6: Re-render for Presentation**
|
||||
13. Freya re-renders prototype with enhanced design system
|
||||
14. Prototype now presentation-ready
|
||||
|
||||
**Result:**
|
||||
- ✅ Polished, professional landing page
|
||||
- ✅ 4 new reusable components for future marketing pages
|
||||
- ✅ Client presentation ready
|
||||
- ✅ Design system significantly expanded
|
||||
|
||||
---
|
||||
|
||||
## Red Flags: When NOT to Extract
|
||||
|
||||
### 🚩 Premature Optimization
|
||||
|
||||
**Sign:** Polishing before validating concept
|
||||
**Problem:** Wasting time on designs that may change
|
||||
**Solution:** Validate functionality first, polish later
|
||||
|
||||
### 🚩 Over-Engineering
|
||||
|
||||
**Sign:** Creating design system for one-off pages
|
||||
**Problem:** Overhead exceeds benefit
|
||||
**Solution:** Keep it simple for unique pages
|
||||
|
||||
### 🚩 Analysis Paralysis
|
||||
|
||||
**Sign:** Endless refinement cycles
|
||||
**Problem:** Never shipping
|
||||
**Solution:** Set "good enough" threshold
|
||||
|
||||
### 🚩 Tool Obsession
|
||||
|
||||
**Sign:** Using Figma because you can, not because you should
|
||||
**Problem:** Process over progress
|
||||
**Solution:** Focus on outcomes, not tools
|
||||
|
||||
---
|
||||
|
||||
## Decision Matrix
|
||||
|
||||
| Factor | Extract | Don't Extract |
|
||||
|--------|---------|---------------|
|
||||
| **Design System Maturity** | Empty/Growing | Mature |
|
||||
| **Visual Quality** | Needs polish | Sufficient |
|
||||
| **Component Coverage** | Gaps exist | Complete |
|
||||
| **Stakeholder Needs** | Presentation | Internal |
|
||||
| **Time Available** | 2-5 hours | < 1 hour |
|
||||
| **Page Importance** | High priority | Low priority |
|
||||
| **Iteration Phase** | First/Final | Middle |
|
||||
| **Team Size** | Collaborative | Solo |
|
||||
|
||||
**Score:** 5+ "Extract" factors → Extract to Figma
|
||||
**Score:** 5+ "Don't Extract" factors → Skip extraction
|
||||
|
||||
---
|
||||
|
||||
## Questions to Ask
|
||||
|
||||
Before deciding, ask yourself:
|
||||
|
||||
1. **Does the design system have what I need?**
|
||||
- Yes → Don't extract
|
||||
- No → Consider extracting
|
||||
|
||||
2. **Is this page important enough to polish?**
|
||||
- Yes → Extract
|
||||
- No → Skip
|
||||
|
||||
3. **Do I have 2-5 hours for refinement?**
|
||||
- Yes → Can extract
|
||||
- No → Skip
|
||||
|
||||
4. **Will this create reusable components?**
|
||||
- Yes → Extract (investment pays off)
|
||||
- No → Skip (one-off work)
|
||||
|
||||
5. **Is the concept validated?**
|
||||
- Yes → Safe to polish
|
||||
- No → Too early
|
||||
|
||||
6. **Do stakeholders need polished visuals?**
|
||||
- Yes → Extract
|
||||
- No → Skip
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### DO ✅
|
||||
|
||||
1. **Extract strategically**
|
||||
- First page in project
|
||||
- High-priority pages
|
||||
- When design system gaps identified
|
||||
|
||||
2. **Batch extractions**
|
||||
- Extract multiple pages together
|
||||
- Efficient use of time
|
||||
- Consistent design decisions
|
||||
|
||||
3. **Document decisions**
|
||||
- Why extracted
|
||||
- What was refined
|
||||
- Design system updates
|
||||
|
||||
4. **Set time limits**
|
||||
- Don't over-polish
|
||||
- Good enough is sufficient
|
||||
- Ship working products
|
||||
|
||||
### DON'T ❌
|
||||
|
||||
1. **Don't extract everything**
|
||||
- Selective extraction
|
||||
- Focus on high-value pages
|
||||
- Skip low-priority pages
|
||||
|
||||
2. **Don't extract too early**
|
||||
- Validate concepts first
|
||||
- Ensure functionality works
|
||||
- Don't polish throwaway work
|
||||
|
||||
3. **Don't extract too late**
|
||||
- Don't accumulate design debt
|
||||
- Address gaps early
|
||||
- Build design system progressively
|
||||
|
||||
4. **Don't extract without plan**
|
||||
- Know what needs refinement
|
||||
- Have clear goals
|
||||
- Update design system after
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
**Extract to Figma when:**
|
||||
- Design system is incomplete
|
||||
- Prototype needs visual polish
|
||||
- New components required
|
||||
- Stakeholder presentation needed
|
||||
- High-priority page
|
||||
- Time available for refinement
|
||||
|
||||
**Skip extraction when:**
|
||||
- Design system covers all needs
|
||||
- Prototype looks sufficient
|
||||
- Rapid iteration more important
|
||||
- Low-priority page
|
||||
- Time constrained
|
||||
- Early exploration phase
|
||||
|
||||
**Remember:** The goal is shipping polished, functional products. Extract strategically, not automatically.
|
||||
|
||||
---
|
||||
|
||||
**Use this guide to make informed decisions about when to invest time in Figma refinement versus moving forward with code-based prototypes.**
|
||||
Reference in New Issue
Block a user