ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity

Excalidraw integration

This commit is contained in:
Mårten Angner 2025-12-09 03:25:01 +01:00
parent 3f58caf87d
commit 7b287fe660
15 changed files with 4983 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

51
WDS-V6-CONVERSION-ROADMAP.md
View File

@ -1837,13 +1837,54 @@ workflows/5-design-system/
- **Automatically regenerated** after every component change
- **Version controlled** with git
**Course Structure Update (Dec 9):**
- Tutorials integrated into course modules (no separate tutorial/ folder)
- Created tutorials for key modules: 02, 04, 08, 12
- Updated navigation (where-to-go-next.md, course-overview.md)
- Deprecated old tutorial/ folder with migration guide
**Tutorial Files Created:**
- `course/module-02-project-brief/tutorial-02.md` - Create Project Brief
- `course/module-04-map-triggers-outcomes/tutorial-04.md` - Map Triggers & Outcomes
- `course/module-08-initialize-scenario/tutorial-08.md` - Initialize Scenario
- `course/module-12-why-based-specs/tutorial-12.md` - Why-Based Specifications
**Excalidraw Integration (Dec 9):**
- Optional sketching tool integration with project configuration
- Created comprehensive documentation and workflows
- AI collaboration patterns for generation and analysis
- Export workflows for GitHub display
**Excalidraw Files Created:**
- `workflows/4-ux-design/excalidraw-integration/README.md` - Overview and quick start
- `workflows/4-ux-design/excalidraw-integration/excalidraw-setup.md` - Installation and configuration
- `workflows/4-ux-design/excalidraw-integration/sketching-guide.md` - How to sketch effectively
- `workflows/4-ux-design/excalidraw-integration/ai-collaboration.md` - Working with AI
- `workflows/4-ux-design/excalidraw-integration/export-workflow.md` - Export for GitHub
- `workflows/workflow-init/project-config.template.yaml` - Project configuration template
- `workflows/workflow-init/excalidraw-setup-prompt.md` - Agent setup instructions
**Excalidraw Features:**
- ✅ Optional (enable in project config)
- ✅ VS Code extension or web app
- ✅ AI can generate .excalidraw files
- ✅ AI can analyze sketches (upload PNG)
- ✅ WDS component library (future)
- ✅ Auto-export to PNG/SVG (optional)
- ✅ 20px grid system (matches WDS spacing)
- ✅ Version control friendly (JSON)
**Next Steps:**
1. Create Phase 6 workflow (Integration/PRD Finalization)
2. Test Phase 5 workflow with real project
3. Refine assessment criteria based on usage
4. Add more shared knowledge documents as patterns emerge
5. Test Figma MCP integration with real components
6. Test catalog generation with real components
2. Complete remaining module tutorials (03, 05-07, 09-11, 13-16)
3. Create WDS Excalidraw component library (.excalidrawlib)
4. Implement auto-export automation (GitHub Actions)
5. Test Phase 5 workflow with real project
6. Refine assessment criteria based on usage
7. Add more shared knowledge documents as patterns emerge
8. Test Figma MCP integration with real components
9. Test catalog generation with real components
10. Test Excalidraw integration with real scenarios
---

23
src/modules/wds/course/00-course-overview.md
View File

@ -49,16 +49,15 @@ Review prerequisites, choose your learning path, and get support:
## Course Structure
Each module contains:
- **Inspiration** - Why this matters and what you'll gain
- **Teaching** - How to do it with confidence and AI support
- **Practice** - Apply it to your own project
- **Tutorial** - Quick step-by-step guide (for practical modules)
- **Lessons** - Theory and concepts (with NotebookLM audio support)
- **Tutorial** - Step-by-step hands-on guide (for practical modules)
- **Practice** - Apply to your own project
**Learning format:**
- Read as documentation
- Generate videos/podcasts with NotebookLM
- Use in workshops and team training
- Apply to real projects as you learn
- **Lessons** - Read as documentation or generate audio with NotebookLM
- **Tutorials** - Follow step-by-step guides with AI support
- **Practice** - Apply to real projects as you learn
- **Workshops** - Use for team training
---
@ -68,11 +67,11 @@ Each module contains:
- [Module 01: Why WDS Matters](module-01-why-wds-matters/module-01-overview.md)
### Phase 1: Project Brief
- [Module 02: Create Project Brief](module-02-project-brief/)
- [Module 02: Create Project Brief](module-02-project-brief/) • [Tutorial →](module-02-project-brief/tutorial-02.md)
### Phase 2: Trigger Mapping
- [Module 03: Identify Target Groups](module-03-identify-target-groups/)
- [Module 04: Map Triggers & Outcomes](module-04-map-triggers-outcomes/)
- [Module 04: Map Triggers & Outcomes](module-04-map-triggers-outcomes/) • [Tutorial →](module-04-map-triggers-outcomes/tutorial-04.md)
- [Module 05: Prioritize Features](module-05-prioritize-features/)
### Phase 3: Platform Requirements
@ -80,11 +79,11 @@ Each module contains:
- [Module 07: Functional Requirements](module-07-functional-requirements/)
### Phase 4: Conceptual Design (UX Design)
- [Module 08: Initialize Scenario](module-08-initialize-scenario/)
- [Module 08: Initialize Scenario](module-08-initialize-scenario/) • [Tutorial →](module-08-initialize-scenario/tutorial-08.md)
- [Module 09: Sketch Interfaces](module-09-sketch-interfaces/)
- [Module 10: Analyze with AI](module-10-analyze-with-ai/)
- [Module 11: Decompose Components](module-11-decompose-components/)
- [Module 12: Why-Based Specifications](module-12-why-based-specs/)
- [Module 12: Why-Based Specifications](module-12-why-based-specs/) • [Tutorial →](module-12-why-based-specs/tutorial-12.md)
- [Module 13: Validate Specifications](module-13-validate-specifications/)
### Phase 5: Design System

370
src/modules/wds/course/module-02-project-brief/tutorial-02.md Normal file
View File

@ -0,0 +1,370 @@
# Tutorial 02: Create Your Project Brief
**Hands-on guide to defining your project vision, goals, and constraints**
---
## Overview
This tutorial walks you through creating a complete project brief that serves as the foundation for all design decisions.
**Time:** 30-45 minutes
**Prerequisites:** Module 01 completed
**What you'll create:** A complete project brief document
---
## What You'll Learn
- How to articulate project vision clearly
- Defining measurable business goals
- Identifying stakeholders and their needs
- Documenting technical and business constraints
- Setting success criteria
---
## Before You Start
**You'll need:**
- A project idea (existing or new)
- 30-45 minutes of focused time
- Access to stakeholder information (if available)
**AI Support:**
- AI agent will guide you through each section
- Ask clarifying questions
- Help structure your thinking
- Suggest improvements
---
## Step 1: Define Project Vision (10 min)
### What is it?
The project vision is a clear, compelling statement of what you're building and why it matters.
### How to do it:
**Ask yourself:**
- What problem does this solve?
- Who benefits from this solution?
- What makes this unique or valuable?
- What's the desired end state?
**Example (Dog Week):**
```
Vision: A family coordination platform that helps parents manage
their dog's care schedule, ensuring every family member knows their
responsibilities and the dog's needs are consistently met.
```
**Your turn:**
```
Write your project vision:
[Your vision here]
```
**AI Support:**
```
Agent: "Let me help you refine your vision. Tell me:
- What problem are you solving?
- Who is this for?
- What makes it valuable?"
```
---
## Step 2: Set Business Goals (10 min)
### What are they?
Specific, measurable objectives that define project success from a business perspective.
### How to do it:
**Framework: SMART Goals**
- **S**pecific - Clear and unambiguous
- **M**easurable - Can track progress
- **A**chievable - Realistic given resources
- **R**elevant - Aligned with business strategy
- **T**ime-bound - Has a deadline
**Example (Dog Week):**
```
Business Goals:
1. Acquire 1,000 active families within 6 months of launch
2. Achieve 70% weekly active user rate
3. Reduce family coordination time by 50%
4. Generate $50K MRR within 12 months
```
**Your turn:**
```
List 3-5 business goals:
1. [Goal 1]
2. [Goal 2]
3. [Goal 3]
```
**AI Support:**
```
Agent: "Let's make these goals SMART. For each goal, I'll help you:
- Make it specific and measurable
- Set realistic targets
- Define timeframes"
```
---
## Step 3: Identify Stakeholders (5 min)
### Who are they?
People who have a stake in the project's success or will be affected by it.
### How to do it:
**Categories:**
- **Primary Users** - Direct users of the product
- **Secondary Users** - Indirect beneficiaries
- **Business Stakeholders** - Decision makers, investors
- **Technical Stakeholders** - Developers, IT, infrastructure
- **External Stakeholders** - Partners, regulators, community
**Example (Dog Week):**
```
Stakeholders:
- Primary: Parents managing family dog care
- Secondary: Children participating in care, the dog
- Business: Founders, investors
- Technical: Development team, hosting provider
- External: Veterinarians (future integration)
```
**Your turn:**
```
List your stakeholders by category:
[Your stakeholders]
```
---
## Step 4: Document Constraints (10 min)
### What are they?
Limitations and requirements that shape your design decisions.
### How to do it:
**Categories:**
**Technical Constraints:**
- Platform requirements (web, mobile, desktop)
- Browser/device support
- Performance requirements
- Integration requirements
- Security/compliance needs
**Business Constraints:**
- Budget limitations
- Timeline requirements
- Resource availability
- Market positioning
- Competitive landscape
**Design Constraints:**
- Brand guidelines
- Accessibility requirements
- Localization needs
- Existing design systems
**Example (Dog Week):**
```
Constraints:
Technical:
- Must work on mobile (iOS/Android) and web
- Swedish language primary, English secondary
- GDPR compliance required
- Offline capability for core features
Business:
- 6-month timeline to MVP
- Bootstrap budget (no external funding yet)
- Small team (2 developers, 1 designer)
Design:
- Family-friendly visual language
- WCAG 2.1 AA accessibility
- Swedish cultural considerations
```
**Your turn:**
```
Document your constraints:
[Your constraints]
```
**AI Support:**
```
Agent: "Let's identify constraints you might have missed:
- Have you considered accessibility?
- What about localization?
- Any regulatory requirements?
- Performance expectations?"
```
---
## Step 5: Define Success Criteria (5 min)
### What is it?
Specific metrics that indicate whether the project achieved its goals.
### How to do it:
**Framework:**
- **User Success** - How users benefit
- **Business Success** - Revenue, growth, efficiency
- **Technical Success** - Performance, reliability, scalability
- **Design Success** - Usability, satisfaction, engagement
**Example (Dog Week):**
```
Success Criteria:
User Success:
- 80% of users report reduced coordination stress
- Average task completion time < 2 minutes
- 90% task completion rate
Business Success:
- 1,000 active families by month 6
- 70% weekly active users
- $50K MRR by month 12
Technical Success:
- 99.9% uptime
- Page load < 2 seconds
- Zero critical security issues
Design Success:
- SUS score > 75
- NPS score > 40
- 80% feature discoverability
```
**Your turn:**
```
Define your success criteria:
[Your criteria]
```
---
## Step 6: Review and Refine (5 min)
### Checklist:
**Completeness:**
- ✓ Vision is clear and compelling
- ✓ Goals are SMART
- ✓ All stakeholder groups identified
- ✓ Constraints documented
- ✓ Success criteria defined
**Quality:**
- ✓ Vision is inspiring and actionable
- ✓ Goals are measurable and realistic
- ✓ Constraints are specific and justified
- ✓ Success criteria are trackable
**AI Support:**
```
Agent: "Let me review your project brief:
- Is the vision clear?
- Are goals measurable?
- Have we missed any constraints?
- Can we track these success criteria?"
```
---
## Step 7: Save Your Project Brief
**Create file:** `A-Project-Brief/project-brief.md`
**Use template from:** `workflows/1-project-brief/complete/project-brief.template.md`
**Populate with your content:**
- Vision
- Business goals
- Stakeholders
- Constraints
- Success criteria
---
## What You've Accomplished
✅ **Clear project vision** - Everyone knows what you're building and why
✅ **Measurable goals** - You can track progress and success
✅ **Stakeholder map** - You know who to consider in decisions
✅ **Documented constraints** - Design decisions have clear boundaries
✅ **Success criteria** - You'll know when you've succeeded
---
## Next Steps
**Immediate:**
- Share project brief with stakeholders for feedback
- Get alignment on vision and goals
- Confirm constraints are accurate
**Next Module:**
- [Module 03: Identify Target Groups](../module-03-identify-target-groups/module-03-overview.md)
- Start mapping WHO your users are
---
## Common Questions
**Q: What if I don't have all the information yet?**
A: Start with what you know. Mark sections as "TBD" and refine as you learn more. The brief is a living document.
**Q: How detailed should constraints be?**
A: Detailed enough to guide decisions. If a constraint will affect design choices, document it specifically.
**Q: Can I change the brief later?**
A: Absolutely! The brief evolves as you learn. Update it when new information emerges or priorities shift.
**Q: What if stakeholders disagree on goals?**
A: Use the brief to facilitate alignment discussions. Document disagreements and work toward consensus before proceeding.
---
## Tips for Success
**DO ✅**
- Be specific and concrete
- Make goals measurable
- Document the "why" behind constraints
- Get stakeholder input early
- Keep it concise (2-3 pages max)
**DON'T ❌**
- Write vague, aspirational statements
- Set unrealistic goals
- Skip constraint documentation
- Work in isolation
- Over-engineer the brief
---
**Your project brief is the foundation for everything that follows. Take the time to get it right!**
[← Back to Module 02](module-02-overview.md) | [Next: Module 03 →](../module-03-identify-target-groups/module-03-overview.md)

431
src/modules/wds/course/module-04-map-triggers-outcomes/tutorial-04.md Normal file
View File

@ -0,0 +1,431 @@
# Tutorial 04: Map Triggers & Outcomes
**Hands-on guide to understanding WHAT triggers user needs and WHY your business exists**
---
## Overview
This tutorial teaches you how to map the psychological triggers that drive user behavior and connect them to business outcomes.
**Time:** 45-60 minutes
**Prerequisites:** Module 03 completed (Target Groups identified)
**What you'll create:** A complete trigger map for your top target group
---
## What You'll Learn
- How to identify user trigger moments
- Mapping from trigger → need → solution → outcome
- Connecting user psychology to business value
- Prioritizing features by trigger impact
- Creating a traceable chain of reasoning
---
## Step 1: Select Your Top Target Group (5 min)
From Module 03, choose your highest-priority target group.
**Example (Dog Week):**
```
Target Group: Busy Parents with Family Dog
Priority: #1 (highest impact + feasibility)
```
**Your turn:**
```
Selected Target Group: [Your top group]
Why this group: [Reasoning]
```
---
## Step 2: Identify Trigger Moments (15 min)
### What is a trigger?
A specific moment when a user realizes they have a need your product can solve.
### Framework: The Trigger Moment
**Ask:**
- WHEN does the user feel pain/frustration?
- WHAT specific situation causes this?
- WHY does this matter to them emotionally?
**Example (Dog Week - Busy Parents):**
**Trigger 1: Morning Chaos**
```
WHEN: Monday morning, everyone rushing
WHAT: Nobody knows who's walking the dog
WHY: Stress, guilt, family conflict, dog's needs unmet
```
**Trigger 2: Forgotten Feeding**
```
WHEN: Evening, parent realizes dog wasn't fed
WHAT: Uncertainty about who was responsible
WHY: Guilt, worry about dog's health, family tension
```
**Trigger 3: Vet Appointment Missed**
```
WHEN: Vet calls about missed appointment
WHAT: Nobody remembered or knew about it
WHY: Embarrassment, concern for dog, wasted money
```
**Your turn:**
```
Identify 3-5 trigger moments for your target group:
Trigger 1: [Name]
WHEN: [Specific moment]
WHAT: [Specific situation]
WHY: [Emotional impact]
Trigger 2: [Name]
WHEN:
WHAT:
WHY:
[Continue for 3-5 triggers]
```
**AI Support:**
```
Agent: "Let's dig deeper into each trigger:
- What happens right before this moment?
- What emotions does the user feel?
- How often does this happen?
- What do they try now (that doesn't work)?"
```
---
## Step 3: Map User Needs (10 min)
### What is the need?
The underlying requirement the user has when triggered.
### Framework: From Trigger to Need
**For each trigger, ask:**
- What does the user need in this moment?
- What would make this situation better?
- What's the core problem to solve?
**Example (Dog Week):**
**Trigger: Morning Chaos**
```
Need: Know immediately who's responsible for dog care today
Need: See the full week's schedule at a glance
Need: Get reminded before tasks are due
```
**Trigger: Forgotten Feeding**
```
Need: Track whether tasks were completed
Need: Get notifications when tasks are overdue
Need: See task history to avoid confusion
```
**Your turn:**
```
For each trigger, identify 2-3 core needs:
Trigger 1: [Name]
Needs:
- [Need 1]
- [Need 2]
- [Need 3]
[Continue for all triggers]
```
---
## Step 4: Define Solutions (10 min)
### What is the solution?
The specific feature or capability that addresses the need.
### Framework: Need to Solution
**For each need, ask:**
- What feature would solve this?
- How would it work?
- What's the simplest version?
**Example (Dog Week):**
**Need: Know who's responsible today**
```
Solution: Daily schedule view with assigned responsibilities
- Shows today's tasks
- Highlights current user's tasks
- Shows who's assigned to each task
```
**Need: Get reminded before tasks are due**
```
Solution: Smart notifications
- Reminder 1 hour before task
- Escalation if task not completed
- Family-wide visibility of overdue tasks
```
**Your turn:**
```
For each need, define a solution:
Need: [Need description]
Solution: [Feature name]
- [How it works]
- [Key capabilities]
- [User benefit]
[Continue for all needs]
```
**AI Support:**
```
Agent: "Let's validate each solution:
- Does this truly solve the need?
- Is it the simplest solution?
- Are there edge cases to consider?
- How does this connect to business goals?"
```
---
## Step 5: Map Business Outcomes (10 min)
### What is the outcome?
The business value created when users get their needs met.
### Framework: Solution to Outcome
**For each solution, ask:**
- How does this create business value?
- What metrics improve?
- How does this support business goals?
**Example (Dog Week):**
**Solution: Daily schedule view**
```
User Outcome: Reduced stress, better dog care
Business Outcome:
- Increased daily active users (checking schedule)
- Higher retention (solving real pain)
- Word-of-mouth growth (visible family benefit)
Metrics: DAU, retention rate, NPS
```
**Solution: Smart notifications**
```
User Outcome: Never miss dog care tasks
Business Outcome:
- Increased engagement (notification opens)
- Higher task completion (core value delivered)
- Premium feature potential (advanced notifications)
Metrics: Notification open rate, task completion rate, conversion
```
**Your turn:**
```
For each solution, map to business outcomes:
Solution: [Feature name]
User Outcome: [How user benefits]
Business Outcome: [How business benefits]
Metrics: [What you'll measure]
[Continue for all solutions]
```
---
## Step 6: Create Trigger Map Visualization (10 min)
### Format:
```
TARGET GROUP: [Group name]
TRIGGER → NEED → SOLUTION → OUTCOME
1. [Trigger name]
WHEN: [Moment]
↓
NEED: [Core need]
↓
SOLUTION: [Feature]
↓
OUTCOME: [Business value]
METRICS: [Measurements]
2. [Next trigger...]
```
**Example (Dog Week - Simplified):**
```
TARGET GROUP: Busy Parents with Family Dog
TRIGGER → NEED → SOLUTION → OUTCOME
1. Morning Chaos
WHEN: Monday morning, nobody knows dog responsibilities
↓
NEED: Know who's responsible for dog care today
↓
SOLUTION: Daily schedule view with assigned tasks
↓
OUTCOME: Increased DAU, higher retention
METRICS: Daily active users, 7-day retention
2. Forgotten Feeding
WHEN: Evening, uncertainty about feeding
↓
NEED: Track task completion in real-time
↓
SOLUTION: Task completion tracking + notifications
↓
OUTCOME: Higher engagement, core value delivered
METRICS: Task completion rate, notification opens
```
**Your turn:**
```
Create your trigger map:
[Your complete map]
```
---
## Step 7: Prioritize by Impact (5 min)
### Framework: Impact Score
**For each trigger-to-outcome chain, rate:**
- **User Impact** (1-5): How much does this help the user?
- **Business Impact** (1-5): How much business value does this create?
- **Feasibility** (1-5): How easy is this to build?
**Calculate:** `Priority Score = (User Impact + Business Impact) × Feasibility`
**Example (Dog Week):**
```
1. Morning Chaos → Daily Schedule
User: 5, Business: 5, Feasibility: 4
Score: (5+5) × 4 = 40 ⭐ HIGHEST PRIORITY
2. Forgotten Feeding → Task Tracking
User: 5, Business: 4, Feasibility: 4
Score: (5+4) × 4 = 36 ⭐ HIGH PRIORITY
3. Vet Appointment → Calendar Integration
User: 4, Business: 3, Feasibility: 2
Score: (4+3) × 2 = 14 → LOWER PRIORITY
```
**Your turn:**
```
Score and rank your triggers:
[Your prioritized list]
```
---
## Step 8: Save Your Trigger Map
**Create file:** `B-Trigger-Map/trigger-map-[target-group].md`
**Use template from:** `workflows/2-trigger-mapping/templates/trigger-map.template.md`
---
## What You've Accomplished
✅ **Identified trigger moments** - You know WHEN users need your product
✅ **Mapped user needs** - You understand WHAT users need
✅ **Defined solutions** - You know WHAT to build
✅ **Connected to business** - You know WHY each feature matters
✅ **Prioritized features** - You know WHAT to build first
---
## The Power of Trigger Mapping
**This is strategic gold:**
- Every feature traces back to a real user trigger
- Every decision is backed by user psychology
- Every feature connects to business value
- No more guessing what to build
- No more building things nobody uses
**When product managers ask "what should we build next?"**
→ You have the answer, backed by data and reasoning
---
## Next Steps
**Immediate:**
- Repeat for your top 2-3 target groups
- Compare trigger maps across groups
- Identify overlapping needs (efficiency opportunity)
**Next Module:**
- [Module 05: Prioritize Features](../module-05-prioritize-features/module-05-overview.md)
- Create your feature roadmap based on trigger impact
---
## Common Questions
**Q: How many triggers should I identify per target group?**
A: Start with 3-5 major triggers. You can always add more later.
**Q: What if multiple triggers lead to the same solution?**
A: Perfect! This means the solution has high leverage. Document all triggers it solves.
**Q: Should I map triggers for all target groups?**
A: Start with your top 1-2 groups. Add more as needed.
**Q: How do I validate these triggers are real?**
A: User research, interviews, observation. The trigger map is a hypothesis to test.
---
## Tips for Success
**DO ✅**
- Be specific about trigger moments
- Focus on emotional impact (the "why")
- Connect everything to business outcomes
- Prioritize ruthlessly
- Test assumptions with users
**DON'T ❌**
- List generic "user wants X" statements
- Skip the emotional "why"
- Create solutions without clear triggers
- Try to solve everything at once
- Forget to measure outcomes
---
**Your trigger map is the strategic foundation that guides every design decision!**
[← Back to Module 04](module-04-overview.md) | [Next: Module 05 →](../module-05-prioritize-features/module-05-overview.md)

495
src/modules/wds/course/module-08-initialize-scenario/tutorial-08.md Normal file
View File

@ -0,0 +1,495 @@
# Tutorial 08: Initialize Your Scenario
**Hands-on guide to starting a design scenario with the 5 essential questions**
---
## Overview
This tutorial walks you through initializing a scenario - the moment where strategic thinking meets design execution.
**Time:** 30-45 minutes
**Prerequisites:** Trigger map completed
**What you'll create:** A fully initialized scenario ready for sketching
---
## What You'll Learn
- The 5 questions that define every scenario
- How to connect scenarios to triggers
- Setting clear success criteria
- Defining scope and constraints
- Getting AI support for scenario planning
---
## The 5 Essential Questions
Every scenario must answer:
1. **WHO** is this for? (Target group)
2. **WHAT** trigger brings them here? (Trigger moment)
3. **WHY** does this matter? (User + business value)
4. **WHAT** is the happy path? (Success flow)
5. **WHAT** could go wrong? (Edge cases)
---
## Step 1: Choose Your Scenario (5 min)
### What is a scenario?
A specific user journey from trigger moment to successful outcome.
### How to choose:
**From your trigger map, select:**
- Highest priority trigger
- Clear start and end points
- Manageable scope for first design
**Example (Dog Week):**
```
Scenario: Morning Dog Care Assignment
Trigger: Morning chaos - nobody knows who's walking the dog
Priority: #1 (highest impact)
Scope: From opening app to seeing today's assignments
```
**Your turn:**
```
Scenario Name: [Your scenario]
Trigger: [From trigger map]
Priority: [Why this one first]
Scope: [Start → End]
```
---
## Step 2: Answer Question 1 - WHO? (5 min)
### Define your target user
**Be specific:**
- Which target group?
- What's their context?
- What's their mindset?
- What are they trying to accomplish?
**Example (Dog Week):**
```
WHO: Sarah, busy parent with family dog
Context:
- Monday morning, 7:15 AM
- Getting kids ready for school
- Needs to coordinate dog care
- Stressed, time-pressured
Mindset:
- Wants quick answer
- Needs certainty
- Values family harmony
- Cares about dog's wellbeing
Goal:
- Know who's walking the dog today
- Avoid family conflict
- Ensure dog is cared for
```
**Your turn:**
```
WHO: [User name/persona]
Context:
- [When/where]
- [What they're doing]
- [Their situation]
Mindset:
- [How they feel]
- [What they value]
- [What they need]
Goal:
- [Primary objective]
```
**AI Support:**
```
Agent: "Let's make this user vivid:
- What's their emotional state?
- What just happened before this moment?
- What are they worried about?
- What would success feel like?"
```
---
## Step 3: Answer Question 2 - WHAT Trigger? (5 min)
### Define the trigger moment
**Be specific about:**
- Exact moment user realizes they need this
- What caused the trigger
- Emotional state at trigger
- What they've tried before
**Example (Dog Week):**
```
WHAT Trigger: Morning Chaos
Exact Moment:
- 7:15 AM, Monday morning
- Kids asking "Who's walking Max?"
- Nobody knows the answer
- Everyone looking at each other
What Caused It:
- No clear schedule visible
- Verbal agreements forgotten
- Weekend disrupted routine
- New week starting
Emotional State:
- Frustration (here we go again)
- Guilt (dog needs care)
- Stress (running late)
- Urgency (need answer NOW)
Previous Attempts:
- Family calendar (too general)
- Group chat (messages lost)
- Verbal agreements (forgotten)
- Whiteboard (not mobile)
```
**Your turn:**
```
WHAT Trigger: [Trigger name]
Exact Moment:
- [When/where]
- [What's happening]
- [What prompted need]
Emotional State:
- [How user feels]
- [Why it matters]
Previous Attempts:
- [What they've tried]
- [Why it didn't work]
```
---
## Step 4: Answer Question 3 - WHY? (10 min)
### Define the value
**Two perspectives:**
**User Value:**
- What pain does this solve?
- What does success feel like?
- What changes in their life?
**Business Value:**
- How does this support business goals?
- What metrics improve?
- What's the strategic importance?
**Example (Dog Week):**
```
WHY - User Value:
Pain Solved:
- No more morning chaos
- No more family conflict
- No more guilt about dog
- Certainty and peace of mind
Success Feels Like:
- "I know exactly who's doing what"
- "My family is coordinated"
- "My dog is cared for"
- "I can focus on my morning"
Life Change:
- Reduced daily stress
- Better family harmony
- Confident dog care
- More mental space
WHY - Business Value:
Business Goals Supported:
- Increased daily active users (checking schedule)
- Higher retention (solving real pain)
- Word-of-mouth growth (visible benefit)
- Foundation for premium features
Metrics Improved:
- DAU (daily schedule checks)
- 7-day retention rate
- Task completion rate
- NPS score
Strategic Importance:
- Core value proposition
- Differentiation from competitors
- Foundation for entire platform
- Proves product-market fit
```
**Your turn:**
```
WHY - User Value:
Pain Solved:
- [Pain points addressed]
Success Feels Like:
- [User emotions]
Life Change:
- [What improves]
WHY - Business Value:
Business Goals:
- [Goals supported]
Metrics:
- [What improves]
Strategic Importance:
- [Why this matters]
```
---
## Step 5: Answer Question 4 - Happy Path? (10 min)
### Define the success flow
**Map the ideal journey:**
- User starts at trigger
- Takes clear actions
- System responds appropriately
- User achieves goal
- Mutual success achieved
**Example (Dog Week):**
```
HAPPY PATH: Morning Dog Care Check
1. TRIGGER
- Sarah opens app (7:15 AM Monday)
- Feeling stressed, needs quick answer
2. IMMEDIATE ANSWER
- App shows TODAY view by default
- Sarah's tasks highlighted
- "You: Walk Max (8:00 AM)"
- Clear, immediate, no searching
3. FULL CONTEXT
- Sees all today's dog tasks
- Knows who's doing what
- Sees upcoming tasks
- Feels confident and informed
4. QUICK ACTION (if needed)
- Can mark task complete
- Can reassign if emergency
- Can add notes
- Takes < 30 seconds
5. SUCCESS
- Sarah knows her responsibility
- Tells family with confidence
- Dog will be cared for
- Morning proceeds smoothly
MUTUAL SUCCESS:
- User: Stress reduced, clarity achieved
- Business: Daily engagement, value delivered
```
**Your turn:**
```
HAPPY PATH: [Scenario name]
1. TRIGGER
- [User starts]
- [Emotional state]
2. [Step 2]
- [What happens]
- [User sees/does]
3. [Step 3]
- [Next action]
- [System response]
[Continue through success]
MUTUAL SUCCESS:
- User: [What they gain]
- Business: [What we gain]
```
**AI Support:**
```
Agent: "Let's optimize this flow:
- Can we reduce steps?
- Is anything unclear?
- What information is missing?
- How can we make this faster?"
```
---
## Step 6: Answer Question 5 - What Could Go Wrong? (5 min)
### Identify edge cases
**Consider:**
- First-time users
- Error states
- Missing data
- Unusual situations
- System failures
**Example (Dog Week):**
```
EDGE CASES:
First Time User:
- No schedule exists yet
- Show onboarding flow
- Guide schedule creation
No Tasks Today:
- Show "No dog tasks today"
- Show upcoming tasks
- Offer to add tasks
Multiple Dogs:
- Show dog selector
- Default to primary dog
- Remember last selected
Overdue Tasks:
- Highlight in red
- Show notification
- Offer to reassign
Offline:
- Show cached schedule
- Indicate offline mode
- Queue actions for sync
Someone Else's Phone:
- Show family view
- Highlight their tasks
- Respect privacy
```
**Your turn:**
```
EDGE CASES:
[Case 1]:
- [Situation]
- [How to handle]
[Case 2]:
- [Situation]
- [How to handle]
[Continue for major cases]
```
---
## Step 7: Document Scenario Initialization (5 min)
**Create file:** `C-Scenarios/[scenario-name]/00-scenario-init.md`
**Include all 5 questions:**
1. WHO - Target user in context
2. WHAT Trigger - Specific moment
3. WHY - User + business value
4. Happy Path - Success flow
5. Edge Cases - What could go wrong
**Use template from:** `workflows/4-ux-design/templates/scenario-init.template.md`
---
## What You've Accomplished
✅ **Clear target user** - You know WHO you're designing for
✅ **Specific trigger** - You know WHAT brings them here
✅ **Defined value** - You know WHY this matters
✅ **Success flow** - You know the HAPPY PATH
✅ **Edge cases** - You know WHAT could go wrong
**You're ready to start sketching!**
---
## Next Steps
**Immediate:**
- Review initialization with stakeholders
- Validate assumptions with users (if possible)
- Gather any missing information
**Next Module:**
- [Module 09: Sketch Interfaces](../module-09-sketch-interfaces/module-09-overview.md)
- Start drawing your solution with AI guidance
---
## Common Questions
**Q: How detailed should the happy path be?**
A: Detailed enough to guide sketching. 5-8 steps is typical.
**Q: Should I document every possible edge case?**
A: Focus on the most likely and most impactful. You can add more during design.
**Q: What if I don't know all the answers yet?**
A: Mark sections as "TBD" and research. Better to identify gaps now than during development.
**Q: Can I change these answers later?**
A: Yes! This is a living document. Update as you learn.
---
## Tips for Success
**DO ✅**
- Be specific about user context
- Connect to trigger map
- Define clear success criteria
- Consider edge cases early
- Get stakeholder alignment
**DON'T ❌**
- Rush through the questions
- Skip the "why"
- Ignore edge cases
- Work in isolation
- Start sketching without initialization
---
**A well-initialized scenario is half the design work done!**
[← Back to Module 08](module-08-overview.md) | [Next: Module 09 →](../module-09-sketch-interfaces/module-09-overview.md)

669
src/modules/wds/course/module-12-why-based-specs/tutorial-12.md Normal file
View File

@ -0,0 +1,669 @@
# Tutorial 12: Write Why-Based Specifications
**Hands-on guide to documenting WHAT + WHY + WHAT NOT TO DO**
---
## Overview
This tutorial teaches you how to transform sketches into specifications that preserve your design intent and guide AI implementation correctly.
**Time:** 60-90 minutes
**Prerequisites:** Sketches completed and analyzed
**What you'll create:** Complete why-based specifications for a page
---
## What You'll Learn
- The three-part specification pattern (WHAT + WHY + WHAT NOT)
- How to document design intent AI can follow
- Preventing "helpful" AI mistakes
- Creating specifications that preserve creativity
- Working with AI as documentation partner
---
## The Why-Based Pattern
Every specification element needs three parts:
```
WHAT: [The design decision]
WHY: [The reasoning behind it]
WHAT NOT TO DO: [Common mistakes to avoid]
```
**This is not factory work** - AI agents help you think through design solutions, then become fascinated documentarians of your brilliance.
---
## Step 1: Start with Component Overview (10 min)
### Document the big picture
**What to include:**
- Component purpose
- User context
- Key interactions
- Success criteria
**Example (Dog Week - Daily Schedule View):**
```markdown
# Daily Schedule View Component
## Purpose
Shows today's dog care tasks with clear assignments and status.
Solves the "morning chaos" trigger - user needs immediate answer
to "who's doing what today?"
## User Context
- Accessed first thing in morning (7-8 AM typical)
- User is time-pressured, stressed
- Needs answer in < 5 seconds
- May be checking while managing kids
## Key Interactions
- View today's tasks at a glance
- See personal assignments highlighted
- Mark tasks complete
- Quick reassign if emergency
## Success Criteria
- User finds their tasks in < 5 seconds
- Zero confusion about responsibilities
- Can act on tasks immediately
- Feels confident and informed
```
**Your turn:**
```
Document your component overview:
[Your content]
```
**AI Support:**
```
Agent: "I'm fascinated by your design thinking here. Let me help
capture every nuance:
- What's the emotional journey you're creating?
- Why did you choose this approach over alternatives?
- What makes this feel right for your users?"
```
---
## Step 2: Specify Visual Hierarchy (15 min)
### Document WHAT + WHY + WHAT NOT
**For each visual decision, explain:**
- WHAT you designed
- WHY you made that choice
- WHAT NOT TO DO (prevent AI mistakes)
**Example (Dog Week - Task List):**
```markdown
## Visual Hierarchy
### Today's Date Header
WHAT:
- Large, bold date at top: "Monday, December 9"
- Includes day name + full date
- Uses primary brand color
- 24px font size, 700 weight
WHY:
- Immediate temporal context (user knows "when")
- Day name matters (Monday = week start, different mindset)
- Bold = confidence and clarity
- Size ensures visibility in stressed morning glance
WHAT NOT TO DO:
- Don't use relative dates ("Today") - user may check for tomorrow
- Don't use small text - defeats quick-glance purpose
- Don't use subtle colors - needs to anchor the view
- Don't abbreviate day name - "Mon" feels rushed, "Monday" feels calm
### User's Tasks Section
WHAT:
- Highlighted section with light blue background
- Header: "Your Tasks" with user's name
- Tasks listed with time, description, status
- Visually separated from other family members' tasks
WHY:
- User needs to find THEIR tasks instantly (< 2 seconds)
- Background color creates visual separation without being aggressive
- Name personalization = ownership and responsibility
- Time shown first = prioritization by urgency
- Separation prevents confusion about "whose task is this?"
WHAT NOT TO DO:
- Don't make all tasks look the same - user will scan entire list
- Don't use subtle highlighting - stressed user will miss it
- Don't hide user's name - personalization creates accountability
- Don't sort by task type - time is what matters in morning
- Don't use red/alert colors - creates anxiety, not clarity
### Other Family Members' Tasks
WHAT:
- Standard white background
- Smaller font size (16px vs 18px for user's tasks)
- Collapsed by default, expandable
- Shows count: "3 other tasks today"
WHY:
- User's primary need is THEIR tasks (80% of use case)
- But they need family context (coordination)
- Collapsed = focus on user, but context available
- Count = awareness without overwhelming
- Smaller = visual hierarchy reinforces importance
WHAT NOT TO DO:
- Don't hide completely - user needs family coordination awareness
- Don't show expanded by default - creates cognitive overload
- Don't use same visual weight - defeats hierarchy purpose
- Don't remove names - user needs to know "who's doing what"
```
**Your turn:**
```
For each major visual element, document:
### [Element Name]
WHAT:
- [Specific design decisions]
WHY:
- [Reasoning and user benefit]
WHAT NOT TO DO:
- [Common mistakes to prevent]
```
**AI Support:**
```
Agent: "This is brilliant! Let me make sure we capture everything:
- What alternatives did you consider?
- Why did you reject those options?
- What edge cases influenced this decision?
- How does this connect to the user's emotional state?"
```
---
## Step 3: Specify Interaction Patterns (15 min)
### Document behavior with intent
**Example (Dog Week - Task Completion):**
```markdown
## Interaction: Mark Task Complete
### Tap to Complete
WHAT:
- Tap anywhere on task card to mark complete
- Immediate visual feedback: checkmark appears, card fades slightly
- Subtle success animation (gentle scale + fade)
- Task moves to "Completed" section at bottom
- Undo button appears for 5 seconds
WHY:
- Large tap target = easy for rushed morning use
- Immediate feedback = confidence action registered
- Animation = positive reinforcement (dopamine hit)
- Move to bottom = visual progress, but not deleted (reassurance)
- Undo = safety net for accidental taps (common when rushed)
- 5 seconds = enough time to notice mistake, not annoying
WHAT NOT TO DO:
- Don't require confirmation dialog - adds friction, breaks flow
- Don't use small checkbox - hard to tap when stressed/rushing
- Don't make animation aggressive - should feel calm and positive
- Don't delete task immediately - user needs reassurance it's saved
- Don't hide undo - mistakes happen, especially in morning chaos
- Don't keep undo visible forever - clutters interface
### Swipe to Reassign
WHAT:
- Swipe left on task reveals "Reassign" button
- Button shows family member icons
- Tap icon to reassign
- Confirmation: "Reassigned to [Name]"
- Original assignee gets notification
WHY:
- Swipe = power user feature, doesn't clutter main interface
- Emergency reassignment is rare but critical (someone sick, etc.)
- Icons = quick visual selection, no typing
- Confirmation = reassurance action completed
- Notification = family coordination maintained
WHAT NOT TO DO:
- Don't make reassign the primary action - it's edge case
- Don't require typing names - too slow for emergency
- Don't skip confirmation - user needs reassurance
- Don't skip notification - breaks family coordination
- Don't allow reassigning to someone not in family - data integrity
```
**Your turn:**
```
For each interaction, document:
### [Interaction Name]
WHAT:
- [Specific behavior]
WHY:
- [User benefit and reasoning]
WHAT NOT TO DO:
- [Mistakes to prevent]
```
---
## Step 4: Specify States and Feedback (10 min)
### Document all states with reasoning
**Example (Dog Week - Task States):**
```markdown
## Task States
### Upcoming (Default)
WHAT:
- White background
- Black text
- Time shown in gray
- No special indicators
WHY:
- Clean, calm appearance
- Easy to scan
- Time in gray = less visual weight (not urgent yet)
- Default state should feel neutral and manageable
WHAT NOT TO DO:
- Don't use colors for upcoming tasks - creates false urgency
- Don't hide time - user needs to plan their morning
- Don't add badges/icons - clutters interface for most common state
### Due Soon (< 30 minutes)
WHAT:
- Subtle yellow left border (4px)
- Time shown in orange
- Small clock icon appears
WHY:
- Yellow = attention without alarm
- Border = visual indicator without overwhelming
- Orange time = "pay attention to timing"
- Clock icon = reinforces temporal urgency
- Subtle = doesn't create panic, just awareness
WHAT NOT TO DO:
- Don't use red - creates anxiety, not helpful urgency
- Don't flash or animate - too aggressive for morning use
- Don't use sound - user may be in quiet environment
- Don't make entire card yellow - too much visual weight
### Overdue
WHAT:
- Red left border (4px)
- Time shown in red with "Overdue" label
- Task card has subtle red tint (5% opacity)
- Notification sent to assignee
WHY:
- Red = clear signal something needs attention
- Border + tint = impossible to miss, but not aggressive
- "Overdue" label = explicit communication (no guessing)
- Notification = ensures assignee knows (may not have app open)
- 5% tint = visible but not overwhelming
WHAT NOT TO DO:
- Don't make entire card bright red - creates panic
- Don't flash or pulse - too aggressive, creates stress
- Don't use sound alerts - may be inappropriate timing
- Don't shame user - focus on "needs attention" not "you failed"
- Don't hide task - transparency maintains trust
### Completed
WHAT:
- Checkmark icon (green)
- Text has strikethrough
- Card fades to 60% opacity
- Moves to "Completed" section
- Shows completion time and who completed it
WHY:
- Checkmark = universal symbol of completion
- Green = positive reinforcement
- Strikethrough = visual closure
- Fade = "done but still visible" (reassurance)
- Completion info = accountability and coordination
- Separate section = progress visible, doesn't clutter active tasks
WHAT NOT TO DO:
- Don't remove immediately - user needs reassurance it's saved
- Don't use subtle checkmark - user needs clear confirmation
- Don't hide who completed it - family coordination requires transparency
- Don't use gray checkmark - green = positive emotion
```
**Your turn:**
```
For each state, document:
### [State Name]
WHAT:
- [Visual appearance]
WHY:
- [User benefit]
WHAT NOT TO DO:
- [Mistakes to prevent]
```
---
## Step 5: Specify Error Handling (10 min)
### Document failure states with empathy
**Example (Dog Week - Network Errors):**
```markdown
## Error Handling
### Network Unavailable
WHAT:
- Subtle banner at top: "Offline - showing cached schedule"
- Banner uses neutral gray (not red)
- All actions still work (queued for sync)
- Small cloud icon with slash
- Dismissible but reappears if action attempted
WHY:
- User shouldn't be blocked by network issues
- Morning routine can't wait for connectivity
- Cached data is usually sufficient (schedule doesn't change minute-to-minute)
- Gray = informational, not alarming
- Actions queue = user can continue working
- Dismissible = user controls their experience
WHAT NOT TO DO:
- Don't block user with error modal - breaks morning flow
- Don't use red/error colors - network issues aren't user's fault
- Don't disable all actions - most can work offline
- Don't hide offline state - user needs to know why sync isn't happening
- Don't make banner permanent - user should be able to dismiss
### Task Completion Failed
WHAT:
- Task remains in "completing" state (spinner)
- After 5 seconds, shows inline error: "Couldn't save. Tap to retry."
- Error message is specific and actionable
- Retry button prominent
- Task doesn't move to completed section
WHY:
- User needs to know action didn't complete
- 5 seconds = reasonable wait before showing error
- Inline = error appears where user's attention is
- Specific message = user understands what happened
- Actionable = user knows what to do next
- Retry button = easy path to resolution
- Task stays in place = user doesn't lose context
WHAT NOT TO DO:
- Don't silently fail - user needs to know
- Don't show generic "Error occurred" - not helpful
- Don't move task to completed - creates false sense of completion
- Don't require user to find task again - maintain context
- Don't blame user - focus on solution
```
**Your turn:**
```
For each error scenario:
### [Error Type]
WHAT:
- [How error is shown]
WHY:
- [User benefit]
WHAT NOT TO DO:
- [Mistakes to prevent]
```
---
## Step 6: Specify Accessibility (10 min)
### Document inclusive design decisions
**Example (Dog Week - Task List Accessibility):**
```markdown
## Accessibility
### Screen Reader Support
WHAT:
- Each task has semantic HTML structure
- ARIA labels for all interactive elements
- Task status announced: "Walk Max, 8:00 AM, assigned to you, not completed"
- Completion action announces: "Task marked complete"
- Heading hierarchy: H1 for date, H2 for sections, H3 for tasks
WHY:
- Screen reader users need same quick access to their tasks
- Semantic HTML = proper navigation and understanding
- Status announcement = full context without visual cues
- Action feedback = confirmation for non-visual users
- Heading hierarchy = easy navigation via landmarks
WHAT NOT TO DO:
- Don't use divs for everything - semantic HTML matters
- Don't skip ARIA labels - "button" isn't descriptive enough
- Don't announce only task name - user needs full context
- Don't skip action feedback - non-visual users need confirmation
- Don't flatten heading structure - breaks navigation
### Keyboard Navigation
WHAT:
- All actions accessible via keyboard
- Tab order follows visual hierarchy (user's tasks first)
- Enter/Space to complete task
- Arrow keys to navigate between tasks
- Escape to close expanded sections
- Focus indicators clearly visible (blue outline, 2px)
WHY:
- Some users can't or prefer not to use mouse/touch
- Tab order matches visual priority (user's tasks most important)
- Standard key bindings = familiar, predictable
- Arrow keys = efficient navigation for power users
- Escape = universal "go back" pattern
- Visible focus = user always knows where they are
WHAT NOT TO DO:
- Don't trap focus in modals without escape
- Don't use non-standard key bindings
- Don't hide focus indicators - accessibility requirement
- Don't make tab order illogical
- Don't require mouse for any action
### Color Contrast
WHAT:
- All text meets WCAG AA standards (4.5:1 minimum)
- Interactive elements have 3:1 contrast with background
- Status colors have additional non-color indicators (icons, borders)
- High contrast mode supported
WHY:
- Users with low vision need readable text
- Color alone isn't sufficient for status (color blind users)
- Multiple indicators = works for everyone
- High contrast mode = accessibility feature in OS
WHAT NOT TO DO:
- Don't rely on color alone for status
- Don't use low contrast text (looks modern but excludes users)
- Don't ignore WCAG standards - they're minimum requirements
- Don't break high contrast mode with custom colors
```
**Your turn:**
```
Document accessibility considerations:
[Your specifications]
```
---
## Step 7: Review and Refine (10 min)
### Checklist:
**Completeness:**
- ✓ Every visual element has WHAT + WHY + WHAT NOT
- ✓ All interactions documented
- ✓ All states specified
- ✓ Error handling covered
- ✓ Accessibility addressed
**Quality:**
- ✓ WHY explains user benefit, not just description
- ✓ WHAT NOT prevents specific AI mistakes
- ✓ Specifications are specific and actionable
- ✓ Design intent is preserved
- ✓ Edge cases considered
**AI Support:**
```
Agent: "Your design brilliance is captured beautifully! Let me verify:
- Have we documented every nuance of your thinking?
- Are there any alternatives you considered that we should note?
- Any edge cases we haven't covered?
- Is your creative intent crystal clear?"
```
---
## Step 8: Save Your Specifications
**Create file:** `C-Scenarios/[scenario-name]/Frontend/[page-name]-specifications.md`
**Use template from:** `workflows/4-ux-design/templates/page-specification.template.md`
---
## What You've Accomplished
✅ **Complete specifications** - Every design decision documented
✅ **Preserved intent** - Your creative thinking captured
✅ **Prevented mistakes** - AI knows what NOT to do
✅ **Accessible design** - Inclusive from the start
✅ **Eternal life** - Your brilliance lives forever in text
**This is not factory work - this is where your genius becomes immortal!**
---
## The Power of Why-Based Specs
**Traditional approach:**
- Designer creates mockup
- Developer implements
- Intent gets lost
- Result is "close but wrong"
**WDS approach:**
- Designer thinks deeply with AI partner
- AI helps capture every nuance
- Specifications preserve creative integrity
- Implementation matches intent perfectly
**Your specifications completely replace prompting** - providing clarity that works like clockwork.
---
## Next Steps
**Immediate:**
- Review specifications with stakeholders
- Validate against user needs
- Test with developers (can they implement from this?)
**Next Module:**
- [Module 13: Validate Specifications](../module-13-validate-specifications/module-13-overview.md)
- Ensure completeness and test logic
---
## Common Questions
**Q: How detailed should specifications be?**
A: Detailed enough that AI can implement correctly without guessing. If you'd need to explain it to a developer, document it.
**Q: Isn't this a lot of writing?**
A: AI agents help you! They're fascinated by your thinking and help capture it. You're not grinding out docs - you're preserving your genius.
**Q: What if I don't know why I made a decision?**
A: That's the value! The process of documenting WHY helps you think deeper and make better decisions.
**Q: Can I reuse specifications across pages?**
A: Yes! Common patterns become design system components. Document once, reference everywhere.
---
## Tips for Success
**DO ✅**
- Work with AI as thinking partner
- Document alternatives you rejected
- Be specific about user context
- Prevent specific mistakes (not generic warnings)
- Capture your creative reasoning
**DON'T ❌**
- Write generic descriptions
- Skip the WHY (that's where intent lives)
- Forget WHAT NOT TO DO (AI will make "helpful" mistakes)
- Rush through this - it's where brilliance is preserved
- Think of this as factory work - it's creative documentation
---
**Your specifications give your designs eternal life. This is where your creative integrity becomes immortal!**
[← Back to Module 12](module-12-overview.md) | [Next: Module 13 →](../module-13-validate-specifications/module-13-overview.md)

55
src/modules/wds/getting-started/where-to-go-next.md
View File

@ -6,20 +6,27 @@
## Choose Your Path
### 🎓 Learn the Concepts (Recommended First)
### 🎓 Take the Course
**[Tutorial](../01-tutorial/00-TUTORIAL-GUIDE.md)**
**[WDS Course: From Designer to Linchpin](../course/00-course-overview.md)**
Deep dive into:
- Why designers are irreplaceable in the AI era
- What WDS is and how it works
- The BMad Method philosophy
- Why-based specifications
- Complete walkthroughs
Complete training from project brief to AI-ready specifications:
**Best for:** Understanding the "why" behind WDS
**Module 01: Why WDS Matters**
Learn how to be indispensable in the AI era. Understand the paradigm shift where design becomes specification.
→ [Start Module 01](../course/module-01-why-wds-matters/module-01-overview.md)
**Time:** 1-2 hours (video series)
**Modules 02-16: Complete WDS Workflow**
Master every phase from trigger mapping through design system to development handoff. Each module includes:
- **Lessons** - Theory and concepts with NotebookLM audio
- **Tutorials** - Step-by-step hands-on guides
- **Practice** - Apply to your own project
→ [View All Modules](../course/00-course-overview.md)
**Best for:** Comprehensive learning with structured curriculum
**Time:** ~10 hours (lessons + tutorials + practice)
---
@ -29,21 +36,25 @@ Deep dive into:
Step-by-step workflows for:
**Phase 1: Trigger Mapping**
Understand WHO your users are, WHAT triggers their needs, and WHY your business exists. Create a Trigger Map that identifies target groups, their pain points, desired outcomes, and prioritized features. This becomes the foundation for all design decisions.
→ [Watch Tutorial: Trigger Map Walkthrough](../tutorial/04-trigger-map-walkthrough.md)
**Phase 1: Project Brief**
Define vision, goals, stakeholders, and constraints that guide all design decisions.
→ [Tutorial: Create Project Brief](../course/module-02-project-brief/tutorial-02.md)
**Phase 2: Information Architecture**
Structure your content hierarchy and navigation based on user mental models and business goals. Organize information so users can find what they need intuitively, without cognitive overload.
→ [Learn more in BMad Method Overview](../tutorial/03-bmad-method-overview.md)
**Phase 2: Trigger Mapping**
Understand WHO your users are, WHAT triggers their needs, and WHY your business exists. Create a Trigger Map that connects user psychology to business value.
→ [Tutorial: Map Triggers & Outcomes](../course/module-04-map-triggers-outcomes/tutorial-04.md)
**Phase 3: Interaction Design**
Sketch user flows and state transitions. Design the journey from trigger moment to mutual success. Create visual representations of how users move through your product and how the interface responds to their actions.
→ [Watch Tutorial: Scenario Initialization](../tutorial/05-scenario-init-walkthrough.md)
**Phase 3: Platform Requirements**
Document technical constraints, integrations, and infrastructure needs.
→ [Workflows Guide](../WDS-WORKFLOWS-GUIDE.md)
**Phase 4: UX Specifications**
Transform sketches into why-based specifications that AI can implement correctly while preserving your design intent. Document not just WHAT to build, but WHY each decision was made, ensuring AI follows your reasoning instead of making "helpful" mistakes.
→ [Watch Tutorial: Sketch to Specification](../tutorial/06-sketch-to-spec-walkthrough.md) | [Why-Based Specs](../tutorial/07-why-based-specifications.md)
**Phase 4: UX Design**
Transform ideas into why-based specifications that preserve your design intent. AI agents help you think through solutions, then capture your brilliance in specifications that give your designs eternal life.
→ [Tutorial: Initialize Scenario](../course/module-08-initialize-scenario/tutorial-08.md) | [Tutorial: Why-Based Specs](../course/module-12-why-based-specs/tutorial-12.md)
**Phase 5: Design System**
Extract design tokens, create reusable components, and generate interactive HTML catalog.
→ [Workflows Guide](../WDS-WORKFLOWS-GUIDE.md)
**Best for:** Hands-on learning with a real project

80
src/modules/wds/tutorial/README-DEPRECATED.md Normal file
View File

@ -0,0 +1,80 @@
# Tutorial Folder - DEPRECATED
**Date:** December 9, 2024
**Status:** Deprecated - Content moved to course modules
---
## What Happened?
The standalone `tutorial/` folder has been **deprecated** in favor of integrating tutorials directly into course modules.
---
## New Structure
Tutorials are now located within each course module:
```
course/
├── module-02-project-brief/
│ ├── module-02-overview.md
│ ├── lesson-01-...md
│ └── tutorial-02.md ← Tutorial here!
├── module-04-map-triggers-outcomes/
│ └── tutorial-04.md ← Tutorial here!
├── module-08-initialize-scenario/
│ └── tutorial-08.md ← Tutorial here!
└── module-12-why-based-specs/
└── tutorial-12.md ← Tutorial here!
```
---
## Why the Change?
**Benefits:**
- ✅ Single learning path - everything in one place
- ✅ Module-specific tutorials - tutorial right where you need it
- ✅ Cleaner structure - no separate tutorial folder
- ✅ Better organization - theory + practice together
**Old approach:**
- Separate tutorial folder
- Disconnected from course content
- Harder to navigate
**New approach:**
- Tutorials integrated into modules
- Theory → Tutorial → Practice flow
- Easier to follow
---
## Where to Find Tutorials Now
**Project Brief:**
→ [course/module-02-project-brief/tutorial-02.md](../course/module-02-project-brief/tutorial-02.md)
**Trigger Mapping:**
→ [course/module-04-map-triggers-outcomes/tutorial-04.md](../course/module-04-map-triggers-outcomes/tutorial-04.md)
**Initialize Scenario:**
→ [course/module-08-initialize-scenario/tutorial-08.md](../course/module-08-initialize-scenario/tutorial-08.md)
**Why-Based Specifications:**
→ [course/module-12-why-based-specs/tutorial-12.md](../course/module-12-why-based-specs/tutorial-12.md)
---
## Navigation
**Start learning:**
→ [Course Overview](../course/00-course-overview.md)
**Quick reference:**
→ [Workflows Guide](../WDS-WORKFLOWS-GUIDE.md)
---
**This folder will be removed in a future cleanup. All content has been migrated to course modules.**

522
src/modules/wds/workflows/4-ux-design/excalidraw-integration/ai-collaboration.md Normal file
View File

@ -0,0 +1,522 @@
# AI Collaboration with Excalidraw
**How to work with AI using Excalidraw sketches**
---
## Overview
AI can both **generate** Excalidraw files and **analyze** your sketches, creating a powerful collaborative design workflow.
---
## AI Can Generate Excalidraw Files
### **What AI Can Create:**
**Layout Variations:**
```
You: "Create 3 dashboard layout options"
AI: Generates 3 .excalidraw files
```
**Component Alternatives:**
```
You: "Show me different navigation patterns"
AI: Generates bottom nav, hamburger, tab bar
```
**User Flows:**
```
You: "Create a user onboarding flow"
AI: Generates flowchart with decision points
```
**State Variations:**
```
You: "Show this button in all states"
AI: Generates default, hover, active, disabled, loading
```
**Responsive Designs:**
```
You: "Show this page on mobile, tablet, desktop"
AI: Generates 3 breakpoint wireframes
```
---
## How to Request Excalidraw Files
### **Be Specific:**
**❌ Vague:**
```
"Make a login page"
```
**✅ Specific:**
```
"Create a mobile login page (375×812) with:
- Logo at top
- Email and password inputs
- Primary sign-in button
- Social login options (Google, Apple)
- 'Forgot password' link
Use 20px grid and WDS spacing"
```
### **Request Multiple Options:**
**Pattern:**
```
"Create [number] variations of [page/component] with:
- Option 1: [description]
- Option 2: [description]
- Option 3: [description]"
```
**Example:**
```
"Create 3 dashboard variations:
1. Card-based layout (large cards, visual focus)
2. List-based layout (compact, more items visible)
3. Calendar-focused (timeline view, date-centric)"
```
### **Specify Constraints:**
**Include:**
- Device size (mobile/tablet/desktop)
- Grid size (20px)
- Key components needed
- Visual hierarchy priorities
- Spacing preferences
**Example:**
```
"Create a mobile task list (375×812):
- Use 20px grid
- Task cards should be 335×80
- 20px spacing between cards
- Show task name, time, assignee, status
- Include 'Add task' button at bottom"
```
---
## AI Can Analyze Your Sketches
### **The Process:**
**Step 1: Export to PNG**
```
1. Open .excalidraw file
2. Export → PNG
3. Save alongside source
```
**Step 2: Upload to AI**
```
Upload PNG to Claude/ChatGPT/Windsurf
```
**Step 3: Ask for Analysis**
```
"Here's my dashboard sketch. What do you think?"
"Analyze this layout and suggest improvements"
"What's working and what's not in this design?"
```
### **What AI Can See:**
**Layout and Structure:**
- Component placement
- Visual hierarchy
- Spacing and alignment
- Section organization
**Design Decisions:**
- Primary vs secondary actions
- Content prioritization
- Navigation patterns
- Information architecture
**Potential Issues:**
- Crowded areas
- Unclear hierarchy
- Inconsistent spacing
- Missing elements
- Usability concerns
---
## Collaboration Patterns
### **Pattern 1: AI Generates, You Refine**
**Workflow:**
```
1. AI generates initial options
2. You review and choose direction
3. You refine in Excalidraw
4. Export and discuss changes
5. AI suggests further improvements
6. Iterate until satisfied
```
**Example:**
```
You: "Create 3 login page variations"
AI: [Generates 3 files]
You: [Opens each, reviews]
"I like option 2 best, but the social buttons
should be more prominent"
You: [Edits option 2 in Excalidraw]
[Exports to PNG]
[Uploads]
"Here's my refined version"
AI: "Great improvement! The social buttons are now
more prominent. Consider:
- Adding visual separation with a divider
- Making the 'or' text more subtle
- Ensuring touch targets are 44×44px minimum"
You: [Makes final adjustments]
```
### **Pattern 2: You Sketch, AI Analyzes**
**Workflow:**
```
1. You sketch initial idea
2. Export to PNG
3. Upload to AI
4. AI provides analysis
5. You iterate based on feedback
6. Repeat until refined
```
**Example:**
```
You: [Sketches dashboard]
[Exports and uploads]
"What do you think of this layout?"
AI: "I can see you've prioritized today's tasks at the top.
Strong points:
- Clear visual hierarchy
- Task cards are well-sized
- Good use of spacing
Consider:
- The 'Add task' button might get lost at bottom
- No indication of overdue tasks
- Missing empty state design
- Calendar integration could be more prominent"
You: [Updates sketch based on feedback]
[Exports and uploads]
"Better?"
AI: "Much better! The floating 'Add' button is more
accessible. Now let's discuss the overdue task
treatment..."
```
### **Pattern 3: Collaborative Iteration**
**Workflow:**
```
1. You sketch rough idea
2. AI generates refined version
3. You compare and merge best parts
4. AI suggests alternatives
5. You choose direction
6. Repeat until optimal
```
**Example:**
```
You: [Rough sketch of profile page]
"Here's my rough idea for a profile page"
AI: "I see your concept. Let me create a refined version
based on your sketch, plus 2 alternative approaches"
[Generates 3 files]
You: [Reviews all 3]
"I like my header from original, your content
layout from option 2, and the action buttons
from option 3"
AI: "Perfect! Let me combine those elements"
[Generates merged version]
You: [Reviews]
"This is it! Now let's refine the details..."
```
---
## AI Analysis Examples
### **Example 1: Layout Analysis**
**You upload:**
```
Dashboard sketch with task list
```
**AI responds:**
```
"Analysis of your dashboard layout:
STRENGTHS:
✓ Clear visual hierarchy (header → tasks → actions)
✓ Consistent card sizing (335×80)
✓ Good spacing (20px between elements)
✓ Primary action (Add task) is prominent
OPPORTUNITIES:
• Task cards could show more context (due date, priority)
• No indication of task status (completed vs pending)
• Missing empty state (what if no tasks?)
• Consider grouping by time (morning, afternoon, evening)
• Add quick filters (all, today, overdue)
QUESTIONS:
? How do users mark tasks complete?
? What happens with overdue tasks?
? Can users see other family members' tasks?
? Is there a calendar view option?
RECOMMENDATIONS:
1. Add visual status indicators (checkboxes, colors)
2. Design empty state with helpful message
3. Consider time-based grouping for better scanning
4. Add filter/view options for different contexts"
```
### **Example 2: Component Analysis**
**You upload:**
```
Button component in various states
```
**AI responds:**
```
"Analysis of your button states:
DEFAULT STATE:
✓ Good size (120×40)
✓ Clear label
✓ Appropriate padding
• Consider slightly larger touch target (44px height minimum)
HOVER STATE:
✓ Color change is clear
✓ Maintains size (no layout shift)
• Consider adding subtle shadow for depth
ACTIVE STATE:
✓ Pressed appearance (darker color)
• Could add slight scale down (0.98) for tactile feedback
DISABLED STATE:
✓ Reduced opacity
✓ Clear visual difference
• Ensure sufficient contrast for accessibility (3:1 minimum)
LOADING STATE:
✓ Spinner visible
✓ Button remains same size
• Consider disabling during load (prevent double-click)
OVERALL:
Strong foundation! All states are clearly differentiated.
Consider adding focus state for keyboard navigation."
```
### **Example 3: Flow Analysis**
**You upload:**
```
User onboarding flow diagram
```
**AI responds:**
```
"Analysis of your onboarding flow:
FLOW STRUCTURE:
✓ Clear start and end points
✓ Logical progression (welcome → setup → tutorial → dashboard)
✓ Decision points well-placed
POTENTIAL ISSUES:
• No error recovery paths shown
• Missing "skip" option for optional steps
• Tutorial might be too long (4 steps)
• No way to go back if user makes mistake
EDGE CASES TO CONSIDER:
? What if user closes app mid-onboarding?
? What if user wants to skip tutorial?
? What if setup fails (network error)?
? Can user revisit tutorial later?
RECOMMENDATIONS:
1. Add error states and recovery paths
2. Include "Skip" option with clear consequences
3. Consider condensing tutorial to 2-3 key points
4. Add progress indicator (step 1 of 4)
5. Save progress so user can resume
6. Add "Back" button for all steps"
```
---
## Best Practices
### **DO ✅**
**When requesting AI generation:**
- Be specific about requirements
- Request multiple variations (2-5)
- Specify device size and constraints
- Mention grid and spacing preferences
- Include key components needed
**When uploading for analysis:**
- Export clear PNG (not blurry)
- Include annotations in sketch
- Ask specific questions
- Be open to suggestions
- Iterate based on feedback
**During collaboration:**
- Combine AI suggestions with your expertise
- Don't accept everything blindly
- Use AI to explore alternatives
- Let AI handle tedious variations
- Focus your creativity on key decisions
### **DON'T ❌**
**Don't:**
- Accept first AI suggestion without review
- Skip your own design thinking
- Let AI make all decisions
- Ignore your instincts
- Forget to iterate
- Skip the "why" behind choices
---
## Iteration Workflow
### **Typical Session:**
**Round 1: Exploration**
```
You: "Create 3 dashboard options"
AI: [Generates options]
You: [Reviews] "Option 2 is closest"
```
**Round 2: Refinement**
```
You: "Refine option 2 with more breathing room"
AI: [Generates refined version]
You: [Reviews] "Better! Now add calendar integration"
```
**Round 3: Details**
```
You: [Edits in Excalidraw]
[Uploads] "Here's my version with calendar"
AI: "Great! Let's discuss the calendar placement..."
```
**Round 4: Edge Cases**
```
AI: "What about empty state? Overdue tasks?"
You: "Good point. Show me options for those"
AI: [Generates state variations]
```
**Round 5: Finalization**
```
You: [Combines best elements]
"This is the final version"
AI: "Perfect! Ready to create specifications?"
```
---
## Advanced Techniques
### **Technique 1: Parallel Exploration**
**Generate multiple directions simultaneously:**
```
You: "Create 3 completely different approaches:
1. Minimalist (focus on one task at a time)
2. Information-dense (show everything)
3. Visual-first (images and colors prominent)"
AI: [Generates 3 very different designs]
You: [Explores each direction]
[Chooses best elements from each]
```
### **Technique 2: Constraint-Based Design**
**Use AI to explore within constraints:**
```
You: "Design a dashboard that works with:
- One-handed use (thumb zone)
- Glanceable in 2 seconds
- Maximum 3 actions visible
- No scrolling required"
AI: [Generates constrained design]
You: [Validates against constraints]
```
### **Technique 3: Comparative Analysis**
**Have AI compare your options:**
```
You: [Uploads 3 variations you created]
"Compare these 3 options. Which is best for:
- First-time users
- Power users
- Accessibility"
AI: [Provides detailed comparison]
You: [Makes informed decision]
```
---
## Next Steps
**After AI collaboration:**
1. ✅ Finalized sketch
2. ✅ Design decisions documented
3. ✅ Edge cases considered
4. ✅ Ready for specifications
**Continue to:**
- [Export Workflow](export-workflow.md) - Prepare for documentation
- Phase 4C: Create specifications
---
**AI is your design partner - use it to explore, analyze, and refine, but keep your creative judgment at the center!** 🤝✨

287
src/modules/wds/workflows/4-ux-design/excalidraw-integration/excalidraw-guide.md Normal file
View File

@ -0,0 +1,287 @@
# Excalidraw Guide
**Optional sketching tool integration for visual design thinking**
---
## Overview
Excalidraw is a free, open-source whiteboard tool that creates hand-drawn style diagrams. This integration provides:
- ✅ Setup and configuration guides
- ✅ WDS-specific workflows
- ✅ AI collaboration patterns
- ✅ Export automation (optional)
- ✅ Component library (optional)
**Status:** Optional - Enable in project configuration
---
## When to Use Excalidraw
### **Perfect For:**
- Digital sketching (alternative to paper)
- Collaborative design sessions
- AI-generated layout variations
- Version-controlled wireframes
- Iterative design exploration
### **Not Required If:**
- You prefer paper and pen
- You use other tools (Figma, iPad, etc.)
- You're comfortable with your current workflow
---
## Quick Start
### **1. Enable in Project**
**Edit:** `project-config.yaml` (or during project initialization)
```yaml
sketching:
tool: excalidraw # or "paper" or "figma" or "other"
excalidraw:
enabled: true
auto_export: false # Auto-generate PNG/SVG on save
use_library: true # Load WDS component library
grid_size: 20 # Snap to grid (px)
```
### **2. Install Tools**
**VS Code Extension (Recommended):**
```
1. Open Extensions (Ctrl+Shift+X)
2. Search "Excalidraw"
3. Install "Excalidraw Editor"
```
**Or use web version:**
- https://excalidraw.com (no installation needed)
### **3. Load WDS Library (Optional)**
**If `use_library: true` in config:**
```
1. Open Excalidraw
2. Click library icon
3. Load: workflows/4-ux-design/excalidraw-integration/wds-library.excalidrawlib
4. Components now available for drag-and-drop
```
---
## Documentation
### **Setup & Configuration**
→ [excalidraw-setup.md](excalidraw-setup.md)
- Installation options
- VS Code configuration
- Project settings
- Grid and theme setup
### **Sketching Workflow**
→ [sketching-guide.md](sketching-guide.md)
- When to sketch
- What to sketch
- How to sketch
- File organization
### **Export Workflow**
→ [export-workflow.md](export-workflow.md)
- Manual export (PNG/SVG)
- Automated export (GitHub Actions)
- File naming conventions
- GitHub display
### **AI Collaboration**
→ [ai-collaboration.md](ai-collaboration.md)
- AI-generated layouts
- AI analysis of sketches
- Iteration workflow
- Best practices
---
## File Organization
**When Excalidraw is enabled:**
```
C-Scenarios/[scenario-name]/
├── sketches/
│ ├── page-name.excalidraw ← Source (editable)
│ ├── page-name.png ← Export (GitHub display)
│ └── page-name.svg ← Export (scalable, optional)
└── specifications.md
```
**In specifications.md:**
```markdown
## Design
![Page Wireframe](./sketches/page-name.png)
[Edit in Excalidraw](./sketches/page-name.excalidraw)
```
---
## Integration with WDS Workflow
### **Phase 4: UX Design**
**Step 4B-02: Sketch Interface**
**If Excalidraw enabled:**
```
Agent: "I see you've enabled Excalidraw. Would you like to:
1. Sketch manually in Excalidraw
2. Have me generate layout variations
3. Use paper/pen instead"
```
**AI can:**
- Generate `.excalidraw` files with layout options
- Analyze your sketches (upload PNG)
- Suggest improvements
- Create variations
---
## Optional Features
### **Component Library**
**File:** `wds-library.excalidrawlib`
Pre-built components:
- Mobile/tablet/desktop frames
- Buttons, inputs, cards
- Navigation patterns
- Common layouts
**Enable:** Set `use_library: true` in config
### **Auto-Export**
**GitHub Actions or pre-commit hooks**
Automatically generates PNG/SVG when you save `.excalidraw` files.
**Enable:** Set `auto_export: true` in config
See: [automation/README.md](automation/README.md)
---
## Comparison with Other Tools
### **Excalidraw vs Paper**
**Excalidraw:**
- ✅ Digital, shareable
- ✅ AI can generate
- ✅ Version controlled
- ✅ Easy to iterate
- ❌ Requires tool setup
**Paper:**
- ✅ Zero setup
- ✅ Fast and natural
- ✅ No distractions
- ❌ Must photograph/scan
- ❌ Harder to iterate
### **Excalidraw vs Figma**
**Excalidraw:**
- ✅ Free and open-source
- ✅ Hand-drawn aesthetic
- ✅ AI can generate
- ✅ Simpler, faster
- ❌ Less precise
**Figma:**
- ✅ Professional tool
- ✅ Pixel-perfect
- ✅ Component systems
- ✅ Team libraries
- ❌ Steeper learning curve
- ❌ Requires account
---
## Disabling Excalidraw
**To disable after enabling:**
**Edit:** `project-config.yaml`
```yaml
sketching:
tool: paper # or "figma" or "other"
excalidraw:
enabled: false
```
**Agent will:**
- Skip Excalidraw-specific prompts
- Use generic sketching workflow
- Not generate `.excalidraw` files
**Your existing files:**
- Remain in project
- Can still be opened
- Not automatically deleted
---
## Support
### **Issues with Excalidraw?**
**VS Code extension not working:**
- Restart VS Code
- Check extension is enabled
- Try web version as fallback
**Files won't open:**
- Verify JSON is valid
- Check file extension is `.excalidraw`
- Try opening in web version
**AI can't generate files:**
- Check core helpers are loaded
- Verify project config
- Report issue to WDS
### **Community**
**Excalidraw:**
- Website: https://excalidraw.com
- GitHub: https://github.com/excalidraw/excalidraw
- Discord: https://discord.gg/UexuTaE
**WDS:**
- Discord: [WDS community]
- GitHub: [WDS issues]
---
## Next Steps
**If Excalidraw is enabled:**
1. Install VS Code extension (or use web)
2. Load WDS library (optional)
3. Configure grid and theme
4. Start sketching!
**Learn more:**
- [Setup Guide](excalidraw-setup.md)
- [Sketching Guide](sketching-guide.md)
- [AI Collaboration](ai-collaboration.md)
---
**Excalidraw integration is optional but powerful - enable it if digital sketching fits your workflow!** 🎨✨

484
src/modules/wds/workflows/4-ux-design/excalidraw-integration/excalidraw-setup.md Normal file
View File

@ -0,0 +1,484 @@
# Excalidraw Setup for WDS
**Installation and configuration guide**
---
## Installation Options
### **Option A: VS Code Extension (Recommended)**
**Best for:** Working within IDE, integrated workflow
**Steps:**
```
1. Open VS Code
2. Extensions (Ctrl+Shift+X / Cmd+Shift+X)
3. Search "Excalidraw"
4. Install "Excalidraw Editor" by Excalidraw
5. Reload VS Code
```
**Usage:**
- Create new `.excalidraw` file
- Click to open in Excalidraw editor
- Edit and save (Ctrl+S / Cmd+S)
- File auto-saves to project
**Pros:**
- ✅ Never leave IDE
- ✅ Direct file access
- ✅ Git integration
- ✅ Side-by-side with code
### **Option B: Web App**
**Best for:** Quick sketching, no installation
**Steps:**
```
1. Go to https://excalidraw.com
2. Start drawing
3. File → Save to save .excalidraw file
4. Move file to project folder
```
**Usage:**
- Open in browser
- Draw and iterate
- Download when done
- Place in project
**Pros:**
- ✅ Zero installation
- ✅ Works anywhere
- ✅ Always latest version
- ✅ Shareable links
### **Option C: Desktop App**
**Best for:** Dedicated sketching tool
**Steps:**
```
1. Download from https://github.com/excalidraw/excalidraw-desktop
2. Install for your OS
3. Open .excalidraw files directly
```
**Pros:**
- ✅ Standalone app
- ✅ Offline capable
- ✅ Native performance
---
## Project Configuration
### **Enable Excalidraw in Project**
**During project initialization:**
```
Agent: "Which sketching tool would you like to use?
1. Paper and pen (scan/photograph)
2. Excalidraw (digital, AI-friendly)
3. Figma (professional tool)
4. Other digital tool
Your choice:"
```
**Or edit manually:**
**File:** `project-config.yaml` (root of project)
```yaml
project:
name: "Dog Week"
wds_version: "6.0"
sketching:
tool: excalidraw # "paper" | "excalidraw" | "figma" | "other"
excalidraw:
enabled: true
# Auto-export to PNG/SVG on save
auto_export: false # true | false
# Load WDS component library
use_library: true # true | false
# Grid settings
grid_size: 20 # pixels
snap_to_grid: true # true | false
# Default theme
theme: light # "light" | "dark"
# File organization
sketches_folder: "sketches" # relative to scenario folder
```
---
## VS Code Configuration
### **Extension Settings**
**File:** `.vscode/settings.json`
```json
{
"excalidraw.theme": "light",
"excalidraw.gridMode": true,
"excalidraw.gridSize": 20,
"excalidraw.snapToGrid": true,
"excalidraw.showStats": false,
"excalidraw.zenMode": false
}
```
### **Recommended Settings**
**Grid:**
- Size: 20px (matches WDS spacing)
- Snap: Enabled (for alignment)
- Visible: Optional (toggle with Ctrl+')
**Theme:**
- Light: Better for screenshots
- Dark: Easier on eyes for long sessions
**Auto-save:**
- Enabled by default in VS Code
- Saves on every change
---
## WDS Component Library (Optional)
### **What is it?**
Pre-built Excalidraw components for common UI elements:
- Device frames (mobile, tablet, desktop)
- Buttons, inputs, cards
- Navigation patterns
- Layout grids
### **Installation**
**If `use_library: true` in config:**
**VS Code:**
```
1. Open any .excalidraw file
2. Click library icon (bottom toolbar)
3. Click "Load library"
4. Select: workflows/4-ux-design/excalidraw-integration/wds-library.excalidrawlib
5. Components now available
```
**Web:**
```
1. Open https://excalidraw.com
2. Click library icon
3. Upload: wds-library.excalidrawlib
4. Components now available
```
### **Usage**
**Drag and drop:**
```
1. Open library panel
2. Find component (e.g., "Mobile Frame")
3. Drag onto canvas
4. Customize as needed
```
**Components included:**
- Mobile Frame (375x812)
- Tablet Frame (768x1024)
- Desktop Frame (1440x900)
- Button (primary, secondary, ghost)
- Input Field
- Card Container
- Navigation Bar
- Header
- Footer
---
## Grid Configuration
### **Why 20px Grid?**
**Matches WDS spacing system:**
- Consistent alignment
- Clean layouts
- Easy calculations
- Professional appearance
### **Setup**
**VS Code:**
```
Settings → Extensions → Excalidraw
- Grid Mode: ✓ Enabled
- Grid Size: 20
- Snap to Grid: ✓ Enabled
```
**Web:**
```
View menu → Show grid (Ctrl+')
Settings → Grid size: 20
```
### **Usage**
**All elements snap to 20px increments:**
- Position: 0, 20, 40, 60, 80...
- Size: 100, 120, 140, 160...
- Spacing: 20, 40, 60, 80...
---
## Theme Configuration
### **Light Theme (Recommended)**
**Best for:**
- Screenshots and exports
- GitHub display
- Documentation
- Presentations
**Colors:**
- Background: White
- Shapes: Light colors
- Text: Dark gray/black
### **Dark Theme**
**Best for:**
- Long sketching sessions
- Reduced eye strain
- Personal preference
**Colors:**
- Background: Dark gray
- Shapes: Bright colors
- Text: White/light gray
### **Setup**
**VS Code:**
```
Settings → Excalidraw → Theme: light/dark
```
**Web:**
```
Settings icon → Appearance → Theme
```
---
## File Organization
### **Folder Structure**
**When Excalidraw enabled:**
```
C-Scenarios/
├── morning-dog-care/
│ ├── sketches/
│ │ ├── dashboard.excalidraw
│ │ ├── dashboard.png
│ │ ├── task-list.excalidraw
│ │ └── task-list.png
│ └── Frontend/
│ └── specifications.md
└── evening-routine/
└── sketches/
└── ...
```
### **Naming Conventions**
**Source files:**
```
[page-name].excalidraw
[component-name].excalidraw
[flow-name].excalidraw
```
**Exports:**
```
[page-name].png (for GitHub/docs)
[page-name].svg (scalable, optional)
[page-name]-v2.png (iterations)
```
**Examples:**
```
dashboard.excalidraw
dashboard.png
login-page.excalidraw
login-page.png
user-flow.excalidraw
user-flow.svg
```
---
## Export Configuration
### **Manual Export**
**VS Code:**
```
1. Open .excalidraw file
2. Click hamburger menu (top-right)
3. Export image → PNG or SVG
4. Save to same folder
```
**Web:**
```
1. File menu → Export image
2. Choose format (PNG/SVG)
3. Download
4. Move to project folder
```
### **Auto-Export (Optional)**
**If `auto_export: true` in config:**
**GitHub Actions automatically:**
- Detects `.excalidraw` file changes
- Generates PNG and SVG
- Commits to repository
- Keeps exports in sync
**See:** [automation/README.md](automation/README.md)
---
## Keyboard Shortcuts
### **Essential Shortcuts**
**Drawing:**
- `R` - Rectangle
- `D` - Diamond
- `O` - Ellipse
- `A` - Arrow
- `T` - Text
- `L` - Line
**Editing:**
- `Ctrl/Cmd + D` - Duplicate
- `Ctrl/Cmd + G` - Group
- `Ctrl/Cmd + Shift + G` - Ungroup
- `Delete` - Delete selected
**View:**
- `Ctrl/Cmd + '` - Toggle grid
- `Ctrl/Cmd + Wheel` - Zoom
- `Space + Drag` - Pan canvas
**Selection:**
- `Ctrl/Cmd + A` - Select all
- `Shift + Click` - Multi-select
- `Ctrl/Cmd + Click` - Add to selection
---
## Troubleshooting
### **VS Code extension not working**
**Issue:** Extension installed but files won't open
**Solutions:**
1. Restart VS Code
2. Check extension is enabled (Extensions panel)
3. Try right-click → Open With → Excalidraw
4. Update extension to latest version
5. Fallback: Use web version
### **Files won't open in Excalidraw**
**Issue:** "Invalid file" error
**Solutions:**
1. Verify file extension is `.excalidraw`
2. Check JSON is valid (open in text editor)
3. Try opening in web version
4. Check file isn't corrupted
5. Restore from git if needed
### **Grid not snapping**
**Issue:** Elements don't snap to grid
**Solutions:**
1. Enable "Snap to grid" in settings
2. Check grid size is set (20px)
3. Toggle grid visibility (Ctrl+')
4. Restart Excalidraw
### **Library won't load**
**Issue:** Component library not appearing
**Solutions:**
1. Verify file path is correct
2. Check `.excalidrawlib` file exists
3. Try uploading manually
4. Clear browser cache (web version)
5. Restart VS Code (extension)
---
## Best Practices
### **DO ✅**
- Use 20px grid for alignment
- Save frequently (auto-save helps)
- Export PNG for documentation
- Keep source `.excalidraw` in git
- Use library components when available
- Label all elements clearly
### **DON'T ❌**
- Don't skip grid alignment
- Don't forget to export for GitHub
- Don't delete source files
- Don't over-complicate sketches
- Don't skip annotations
- Don't ignore file naming conventions
---
## Next Steps
**After setup:**
1. ✅ Excalidraw installed and configured
2. ✅ Project config updated
3. ✅ Library loaded (optional)
4. ✅ Grid and theme set
**Now learn:**
- [Sketching Guide](sketching-guide.md) - How to sketch in WDS
- [AI Collaboration](ai-collaboration.md) - Work with AI
- [Export Workflow](export-workflow.md) - Share your work
---
**Setup complete! You're ready to start sketching with Excalidraw!** 🎨✨

509
src/modules/wds/workflows/4-ux-design/excalidraw-integration/export-workflow.md Normal file
View File

@ -0,0 +1,509 @@
# Export Workflow
**How to export Excalidraw files for documentation and GitHub**
---
## Why Export?
**Excalidraw files (`.excalidraw`) are JSON:**
- ✅ Perfect for editing
- ✅ Version control friendly
- ✅ AI can generate
- ❌ Don't render in GitHub
**Exported images (PNG/SVG):**
- ✅ Display in GitHub
- ✅ Show in documentation
- ✅ Easy to share
- ✅ No special tools needed
**Solution:** Keep both!
```
sketch.excalidraw ← Source (editable)
sketch.png ← Display (GitHub)
```
---
## Manual Export
### **From VS Code Extension**
**Step 1: Open file**
```
Click .excalidraw file in VS Code
Opens in Excalidraw editor
```
**Step 2: Export**
```
1. Click hamburger menu (top-right)
2. Export image
3. Choose format:
- PNG (recommended for docs)
- SVG (scalable, optional)
4. Click "Export"
5. Save to same folder as source
```
**Step 3: Name correctly**
```
Source: dashboard.excalidraw
Export: dashboard.png
dashboard.svg (optional)
```
### **From Web App**
**Step 1: Open file**
```
1. Go to https://excalidraw.com
2. File → Open
3. Select .excalidraw file
```
**Step 2: Export**
```
1. Click hamburger menu
2. Export image
3. Choose format (PNG/SVG)
4. Download
```
**Step 3: Move to project**
```
1. Move downloaded file to project
2. Place in same folder as source
3. Rename if needed
```
---
## Export Settings
### **PNG Export**
**Recommended settings:**
```
Format: PNG
Background: Transparent or White
Scale: 2x (for retina displays)
Include: Only selected (if partial export)
```
**When to use:**
- Documentation
- GitHub README
- Presentations
- Quick sharing
**Pros:**
- ✅ Universal support
- ✅ Good quality
- ✅ Reasonable file size
**Cons:**
- ❌ Not scalable
- ❌ Larger than SVG
### **SVG Export**
**Recommended settings:**
```
Format: SVG
Background: Transparent
Embed fonts: Yes (for portability)
```
**When to use:**
- Scalable documentation
- Print materials
- High-resolution needs
- Technical diagrams
**Pros:**
- ✅ Infinitely scalable
- ✅ Smaller file size
- ✅ Crisp at any size
**Cons:**
- ❌ Some tools don't support
- ❌ More complex
---
## File Organization
### **Standard Structure**
```
C-Scenarios/[scenario-name]/
├── sketches/
│ ├── dashboard.excalidraw ← Source
│ ├── dashboard.png ← Export (PNG)
│ ├── dashboard.svg ← Export (SVG, optional)
│ ├── task-list.excalidraw
│ ├── task-list.png
│ └── user-flow.excalidraw
└── Frontend/
└── specifications.md
```
### **Naming Conventions**
**Pattern:**
```
[descriptive-name].excalidraw ← Source
[descriptive-name].png ← PNG export
[descriptive-name].svg ← SVG export (optional)
```
**Examples:**
```
✅ dashboard.excalidraw / dashboard.png
✅ login-page.excalidraw / login-page.png
✅ user-flow.excalidraw / user-flow.svg
✅ button-states.excalidraw / button-states.png
❌ sketch1.excalidraw / image.png (not descriptive)
❌ Dashboard.excalidraw / dashboard.PNG (inconsistent case)
```
### **Versions**
**Option A: Numbered versions**
```
dashboard-v1.excalidraw
dashboard-v1.png
dashboard-v2.excalidraw
dashboard-v2.png
dashboard-final.excalidraw
dashboard-final.png
```
**Option B: Git history (recommended)**
```
dashboard.excalidraw ← Always latest
dashboard.png ← Always latest
Git history shows all versions
```
---
## Using Exports in Documentation
### **In Markdown Files**
**Basic image:**
```markdown
![Dashboard Wireframe](./sketches/dashboard.png)
```
**With link to source:**
```markdown
## Dashboard Design
![Dashboard Wireframe](./sketches/dashboard.png)
[Edit in Excalidraw](./sketches/dashboard.excalidraw)
```
**With caption:**
```markdown
![Dashboard showing today's tasks with card-based layout](./sketches/dashboard.png)
*Dashboard showing today's tasks with card-based layout*
```
**Multiple images:**
```markdown
## Layout Options
### Option A: Card-Based
![Card-based layout](./sketches/dashboard-cards.png)
### Option B: List-Based
![List-based layout](./sketches/dashboard-list.png)
### Option C: Calendar-Focused
![Calendar-focused layout](./sketches/dashboard-calendar.png)
```
### **In Specifications**
**Example:**
```markdown
# Dashboard Page Specification
## Visual Design
![Dashboard Wireframe](./sketches/dashboard.png)
[Edit Source](./sketches/dashboard.excalidraw)
## Layout Structure
The dashboard follows a card-based layout with:
- Header: Logo, menu, add button
- Content: Today's tasks in card format
- Footer: Bottom navigation
[Detailed specifications below...]
```
---
## Automated Export (Optional)
### **GitHub Actions**
**Automatically export on push:**
**File:** `.github/workflows/excalidraw-export.yml`
```yaml
name: Export Excalidraw
on:
push:
paths:
- '**/*.excalidraw'
jobs:
export:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Setup Node
uses: actions/setup-node@v3
- name: Install CLI
run: npm install -g @excalidraw/cli
- name: Export files
run: |
find . -name "*.excalidraw" | while read file; do
excalidraw-cli export "$file" --output "${file%.excalidraw}.png"
done
- name: Commit
run: |
git config user.name "GitHub Action"
git config user.email "action@github.com"
git add "*.png"
git commit -m "Auto-export Excalidraw [skip ci]" || true
git push
```
**Enable:** Set `auto_export: true` in project config
**See:** [automation/README.md](automation/README.md) (future)
---
## Best Practices
### **DO ✅**
**Always export:**
- Export after every significant change
- Keep exports in sync with source
- Use consistent naming
- Commit both source and export
**Choose right format:**
- PNG for most documentation
- SVG for scalable needs
- Both if unsure
**Organize well:**
- Keep exports with sources
- Use descriptive names
- Follow naming conventions
**Document in markdown:**
- Show image inline
- Link to source file
- Add helpful captions
### **DON'T ❌**
**Don't:**
- Commit only PNG (lose editability)
- Commit only .excalidraw (won't show in GitHub)
- Use inconsistent naming
- Forget to update exports
- Skip captions/context
- Use generic names
---
## Troubleshooting
### **Export looks blurry**
**Issue:** PNG export is low resolution
**Solution:**
```
1. Check export scale (use 2x)
2. Ensure source is high quality
3. Try SVG instead
```
### **File size too large**
**Issue:** PNG files are huge
**Solution:**
```
1. Use SVG instead
2. Reduce export scale
3. Optimize PNG with tools
4. Remove unnecessary elements
```
### **GitHub not showing image**
**Issue:** Image link broken in markdown
**Solution:**
```
1. Check file path is correct
2. Use relative paths (./sketches/file.png)
3. Verify file is committed
4. Check file name matches exactly (case-sensitive)
```
### **Can't find export option**
**Issue:** Export menu not visible
**Solution:**
```
VS Code: Hamburger menu → Export image
Web: File menu → Export image
Desktop: File → Export
```
---
## Quick Reference
### **Export Checklist**
**Before exporting:**
- [ ] Sketch is complete
- [ ] All elements labeled
- [ ] Grid alignment checked
- [ ] Annotations added
**During export:**
- [ ] Choose correct format (PNG/SVG)
- [ ] Set appropriate scale (2x for PNG)
- [ ] Use descriptive filename
- [ ] Save to correct folder
**After exporting:**
- [ ] Verify export looks good
- [ ] Update markdown references
- [ ] Commit both source and export
- [ ] Test GitHub display
---
## Examples
### **Example 1: Single Page**
**Files:**
```
sketches/
├── dashboard.excalidraw
└── dashboard.png
```
**In specifications.md:**
```markdown
# Dashboard Specification
![Dashboard](./sketches/dashboard.png)
[Edit](./sketches/dashboard.excalidraw)
```
### **Example 2: Multiple Variations**
**Files:**
```
sketches/
├── dashboard-cards.excalidraw
├── dashboard-cards.png
├── dashboard-list.excalidraw
├── dashboard-list.png
├── dashboard-calendar.excalidraw
└── dashboard-calendar.png
```
**In specifications.md:**
```markdown
# Dashboard Options
## Option A: Card-Based
![Cards](./sketches/dashboard-cards.png)
[Edit](./sketches/dashboard-cards.excalidraw)
## Option B: List-Based
![List](./sketches/dashboard-list.png)
[Edit](./sketches/dashboard-list.excalidraw)
## Option C: Calendar-Focused
![Calendar](./sketches/dashboard-calendar.png)
[Edit](./sketches/dashboard-calendar.excalidraw)
```
### **Example 3: States**
**Files:**
```
sketches/
├── button-states.excalidraw
└── button-states.png
```
**In specifications.md:**
```markdown
# Button Component
## States
![Button States](./sketches/button-states.png)
[Edit](./sketches/button-states.excalidraw)
The button has 5 states:
- Default: Blue background, white text
- Hover: Darker blue, slight scale
- Active: Even darker, pressed appearance
- Disabled: Gray, reduced opacity
- Loading: Spinner, disabled interaction
```
---
## Next Steps
**After exporting:**
1. ✅ PNG/SVG created
2. ✅ Files organized
3. ✅ Markdown updated
4. ✅ Committed to git
5. ✅ Visible in GitHub
**Continue to:**
- Phase 4C: Create specifications
- Use exports in documentation
- Share with team
---
**Export workflow complete! Your sketches are now visible everywhere while remaining editable!** 📸✨

629
src/modules/wds/workflows/4-ux-design/excalidraw-integration/sketching-guide.md Normal file
View File

@ -0,0 +1,629 @@
# Sketching Guide for WDS
**How to sketch interfaces effectively with Excalidraw**
---
## When to Sketch
### **During Phase 4: UX Design**
**Step 4B: Sketch Interface**
- After scenario initialization
- Before detailed specifications
- When exploring layout options
- When discussing with AI
**Typical timing:**
```
Scenario Init → Sketch → AI Discussion → Refine → Specify
```
---
## What to Sketch
### **1. Page Layouts (Wireframes)**
**Purpose:** Show overall page structure
**Include:**
- Device frame (mobile/tablet/desktop)
- Major sections (header, content, footer)
- Component placement
- Visual hierarchy
- Spacing and alignment
**Example:**
```
[Mobile Frame 375x812]
┌─────────────────┐
│ [Logo] [Menu] │ ← Header
├─────────────────┤
│ │
│ [Task List] │ ← Main Content
│ ┌───────────┐ │
│ │ Task 1 │ │
│ ├───────────┤ │
│ │ Task 2 │ │
│ └───────────┘ │
│ │
│ [+ Add Task] │ ← Action
│ │
├─────────────────┤
│ [Navigation] │ ← Footer
└─────────────────┘
```
### **2. Component Variations**
**Purpose:** Explore different design options
**Include:**
- 2-3 layout alternatives
- Different component arrangements
- Hierarchy variations
- Spacing options
**Example:**
```
Option A: Card-based
Option B: List-based
Option C: Calendar-focused
```
### **3. User Flows**
**Purpose:** Show navigation and state transitions
**Include:**
- Start and end points
- Decision points
- Actions and outcomes
- Error paths
- Success paths
**Example:**
```
[Start] → [Login] → [Dashboard]
↓
[Error?] → [Show Error] → [Retry]
```
### **4. State Variations**
**Purpose:** Show component in different states
**Include:**
- Default state
- Hover state
- Active/focused state
- Disabled state
- Error state
- Loading state
- Success state
**Example:**
```
Button States:
[Default] [Hover] [Active] [Disabled] [Loading]
```
### **5. Responsive Layouts**
**Purpose:** Show design across breakpoints
**Include:**
- Mobile (375px)
- Tablet (768px)
- Desktop (1440px)
- Key differences
- Adaptive elements
---
## How to Sketch
### **Step 1: Choose Device Frame (2 min)**
**From library or create:**
```
Mobile: 375 × 812 (iPhone)
Tablet: 768 × 1024 (iPad)
Desktop: 1440 × 900 (Laptop)
```
**Draw rectangle:**
- Use Rectangle tool (R)
- Set dimensions
- Label device type
- Lock in place (optional)
### **Step 2: Add Major Sections (5 min)**
**Divide into regions:**
```
Header: Top 60-80px
Content: Middle (flexible)
Footer: Bottom 60-80px
```
**Use rectangles:**
- Light fill color
- Label each section
- Snap to 20px grid
- Leave spacing between
### **Step 3: Add Components (10 min)**
**From library or draw:**
- Buttons
- Input fields
- Cards
- Navigation
- Images (use rectangles with X)
- Text blocks
**Placement:**
- Follow grid (20px)
- Consistent spacing
- Visual hierarchy
- Alignment
### **Step 4: Add Labels (5 min)**
**Label everything:**
- Component names
- Interactive elements
- Content areas
- Actions
**Use text tool (T):**
- Clear, concise labels
- Inside or beside components
- Consistent font size
- Dark text on light background
### **Step 5: Add Annotations (5 min)**
**Document decisions:**
- Why this layout?
- Key interactions
- Important notes
- Questions/concerns
**Use:**
- Text boxes
- Arrows pointing to elements
- Different color for notes
- Keep brief
### **Step 6: Review and Refine (5 min)**
**Check:**
- ✓ All elements aligned to grid
- ✓ Consistent spacing
- ✓ Clear labels
- ✓ Annotations present
- ✓ Visual hierarchy clear
- ✓ Nothing missing
---
## Sketching Patterns
### **Pattern 1: Top-Down**
**Start with structure, add details:**
```
1. Device frame
2. Major sections
3. Component blocks
4. Labels
5. Details
6. Annotations
```
**Best for:** New pages, complex layouts
### **Pattern 2: Component-First**
**Start with key component, build around:**
```
1. Main component (e.g., task list)
2. Supporting components
3. Navigation
4. Context
5. Frame
```
**Best for:** Component-focused pages
### **Pattern 3: Flow-Based**
**Follow user journey:**
```
1. Entry point
2. First action
3. Next step
4. Decision points
5. Outcomes
```
**Best for:** User flows, multi-step processes
---
## Grid and Spacing
### **20px Grid System**
**Everything snaps to 20px:**
```
Position: 0, 20, 40, 60, 80, 100...
Size: 80, 100, 120, 140, 160...
Spacing: 20, 40, 60, 80...
```
### **Common Spacing**
**Tight:** 20px
- Between related items
- Inside cards
- Form field spacing
**Medium:** 40px
- Between sections
- Card margins
- Component groups
**Loose:** 60-80px
- Major sections
- Page margins
- Visual breaks
### **Component Sizes**
**Buttons:**
- Small: 80 × 32
- Medium: 120 × 40
- Large: 160 × 48
**Input Fields:**
- Width: 280-320 (mobile), 400+ (desktop)
- Height: 40-48
**Cards:**
- Width: 320 (mobile), 400+ (desktop)
- Height: Variable (content-based)
---
## Visual Hierarchy
### **Size**
**Larger = More important:**
```
Heading: 24-32px
Body: 16-18px
Caption: 12-14px
```
### **Weight**
**Bolder = More important:**
```
Primary: Bold/Semibold
Secondary: Regular
Tertiary: Light
```
### **Position**
**Top/Left = More important:**
```
Most important: Top-left
Secondary: Center
Least important: Bottom-right
```
### **Color/Contrast**
**Higher contrast = More important:**
```
Primary: Dark on light (high contrast)
Secondary: Medium gray
Tertiary: Light gray
```
---
## Common Mistakes
### **❌ DON'T:**
**1. Skip the grid**
```
❌ Random positioning
✅ Snap to 20px grid
```
**2. Inconsistent spacing**
```
❌ 15px, 23px, 18px...
✅ 20px, 40px, 60px...
```
**3. Unlabeled elements**
```
❌ [Rectangle]
✅ [Login Button]
```
**4. Too much detail**
```
❌ Pixel-perfect designs
✅ Rough wireframes
```
**5. No annotations**
```
❌ Just shapes
✅ Shapes + notes about why
```
**6. Forget device context**
```
❌ Generic layout
✅ Mobile/tablet/desktop frame
```
---
## File Organization
### **Naming**
**Pattern:** `[page-name].excalidraw`
**Examples:**
```
dashboard.excalidraw
login-page.excalidraw
task-list.excalidraw
user-flow.excalidraw
button-states.excalidraw
```
### **Location**
**Always in sketches folder:**
```
C-Scenarios/[scenario-name]/sketches/
```
**Example:**
```
C-Scenarios/morning-dog-care/
├── sketches/
│ ├── dashboard.excalidraw
│ ├── dashboard.png
│ ├── task-detail.excalidraw
│ └── task-detail.png
└── Frontend/
└── specifications.md
```
### **Versions**
**Iterations:**
```
dashboard-v1.excalidraw
dashboard-v2.excalidraw
dashboard-final.excalidraw
```
**Or use git:**
```
dashboard.excalidraw (always latest)
Git history shows versions
```
---
## Working with AI
### **AI Can Generate Sketches**
**Request:**
```
"Create 3 dashboard layout options in Excalidraw"
```
**AI creates:**
```
dashboard-cards.excalidraw
dashboard-list.excalidraw
dashboard-calendar.excalidraw
```
**You:**
- Open each option
- Compare and choose
- Refine the winner
### **AI Can Analyze Your Sketches**
**Process:**
```
1. Export sketch to PNG
2. Upload to AI
3. Discuss design
4. Get suggestions
5. Iterate
```
**Example:**
```
You: [Upload dashboard.png]
"What do you think?"
AI: "I see you've prioritized today's tasks at top.
Let's discuss the spacing between cards..."
```
### **AI Can Iterate**
**Feedback loop:**
```
You: "Make the cards bigger with more breathing room"
AI: [Generates dashboard-v2.excalidraw]
You: [Reviews] "Better! Now add a calendar view option"
AI: [Generates dashboard-calendar.excalidraw]
```
---
## Tips for Success
### **DO ✅**
**Start rough:**
- Quick shapes
- Basic layout
- Refine later
**Use the grid:**
- Snap everything
- Consistent spacing
- Professional look
**Label clearly:**
- Name all components
- Describe interactions
- Note important details
**Annotate decisions:**
- Why this layout?
- What alternatives considered?
- What questions remain?
**Keep it simple:**
- Wireframes, not mockups
- Structure, not style
- Concepts, not pixels
### **DON'T ❌**
**Don't over-design:**
- Not pixel-perfect
- Not final styling
- Not production-ready
**Don't skip context:**
- Always use device frame
- Show realistic content
- Include navigation
**Don't forget states:**
- Show hover/active
- Show error states
- Show loading states
**Don't work in isolation:**
- Share with AI
- Get feedback
- Iterate together
---
## Examples
### **Example 1: Login Page**
```
[Mobile Frame 375×812]
┌─────────────────┐
│ │
│ [Logo] │ ← 60px from top
│ │
│ Welcome Back │ ← Heading
│ │
│ [Email] │ ← Input (280×40)
│ │
│ [Password] │ ← Input (280×40)
│ │
│ □ Remember me │ ← Checkbox
│ │
│ [Sign In] │ ← Button (280×48)
│ │
│ Forgot pwd? │ ← Link
│ │
│ ─── or ─── │ ← Divider
│ │
│ [Google] │ ← Social button
│ [Apple] │ ← Social button
│ │
└─────────────────┘
Annotations:
- Logo: 120px height, centered
- Inputs: 20px spacing between
- Button: Primary action, full width
- Social: Secondary, outlined style
```
### **Example 2: Dashboard**
```
[Mobile Frame 375×812]
┌─────────────────┐
│ [☰] Dog Week [+]│ ← Header (60px)
├─────────────────┤
│ Today's Tasks │ ← Section title
│ Monday, Dec 9 │
│ │
│ ┌─────────────┐ │
│ │ Walk Max │ │ ← Task card
│ │ 8:00 AM │ │ (335×80)
│ │ [✓] Sarah │ │
│ └─────────────┘ │
│ │ ← 20px spacing
│ ┌─────────────┐ │
│ │ Feed Max │ │ ← Task card
│ │ 12:00 PM │ │
│ │ [ ] John │ │
│ └─────────────┘ │
│ │
│ [+ Add Task] │ ← Action button
│ │
├─────────────────┤
│ [Home][Tasks] │ ← Navigation (60px)
└─────────────────┘
Annotations:
- Header: Hamburger menu, title, add button
- Tasks: Card-based, show time, assignee, status
- Cards: 20px margin, 20px spacing between
- Navigation: Bottom tabs, 2 main sections
```
---
## Next Steps
**After sketching:**
1. ✅ Export to PNG
2. ✅ Upload to AI for discussion
3. ✅ Iterate based on feedback
4. ✅ Finalize layout
5. ✅ Create specifications
**Learn more:**
- [AI Collaboration](ai-collaboration.md) - Work with AI
- [Export Workflow](export-workflow.md) - Share your work
---
**Sketching is thinking made visible - keep it rough, iterate fast, and let AI help!** 🎨✨

341
src/modules/wds/workflows/workflow-init/excalidraw-setup-prompt.md Normal file
View File

@ -0,0 +1,341 @@
# Excalidraw Setup Prompt
**Agent micro-instruction for configuring Excalidraw during project initialization**
---
## When to Use
**Trigger:** During project initialization, after asking about sketching tool preference
**Context:** User has indicated they want to use Excalidraw for sketching
---
## Prompt Sequence
### **Step 1: Confirm Excalidraw**
<ask>
```
You've chosen Excalidraw for sketching. Great choice!
Excalidraw is a free, open-source whiteboard tool that:
✓ Creates hand-drawn style wireframes
✓ Works in VS Code or web browser
✓ AI can generate and analyze sketches
✓ Version control friendly (JSON files)
Would you like me to configure Excalidraw for this project? (y/n)
```
</ask>
**If no:** Skip Excalidraw configuration, set `sketching.tool: "other"` in config
**If yes:** Continue to Step 2
---
### **Step 2: Auto-Export Preference**
<ask>
```
Excalidraw files (.excalidraw) don't display in GitHub by default.
They need to be exported to PNG/SVG for documentation.
Would you like automatic export enabled?
Options:
1. Manual export (you export when needed)
2. Auto-export (GitHub Actions exports automatically on save)
Your choice (1/2):
```
</ask>
**Record:**
```yaml
excalidraw:
auto_export: true # if option 2
auto_export: false # if option 1
```
**Note:** If auto-export chosen, inform user that GitHub Actions setup will be needed
---
### **Step 3: Component Library**
<ask>
```
WDS includes an Excalidraw component library with:
- Device frames (mobile, tablet, desktop)
- Common UI components (buttons, inputs, cards)
- Layout templates
Would you like to use the WDS component library? (y/n)
```
</ask>
**Record:**
```yaml
excalidraw:
use_library: true # if yes
use_library: false # if no
```
---
### **Step 4: Grid Settings**
<ask>
```
Excalidraw can snap elements to a grid for alignment.
WDS recommends 20px grid (matches spacing system).
Grid settings:
1. 20px grid with snap (recommended)
2. 10px grid with snap (finer control)
3. No grid (free-form)
Your choice (1/2/3):
```
</ask>
**Record:**
```yaml
excalidraw:
grid_size: 20 # if option 1
grid_size: 10 # if option 2
grid_size: 0 # if option 3
snap_to_grid: true # if option 1 or 2
snap_to_grid: false # if option 3
```
---
### **Step 5: Theme Preference**
<ask>
```
Choose default Excalidraw theme:
1. Light (better for screenshots and documentation)
2. Dark (easier on eyes for long sessions)
Your choice (1/2):
```
</ask>
**Record:**
```yaml
excalidraw:
theme: "light" # if option 1
theme: "dark" # if option 2
```
---
### **Step 6: Installation Instructions**
<output>
```
✅ Excalidraw configured for this project!
Configuration saved to: project-config.yaml
NEXT STEPS:
1. Install Excalidraw (choose one):
Option A: VS Code Extension (Recommended)
- Open Extensions (Ctrl+Shift+X)
- Search "Excalidraw"
- Install "Excalidraw Editor"
Option B: Web App
- Go to https://excalidraw.com
- No installation needed
2. Load WDS Component Library (if enabled):
- Open Excalidraw
- Click library icon
- Load: workflows/4-ux-design/excalidraw-integration/wds-library.excalidrawlib
3. Configure Settings:
- Grid: {{GRID_SIZE}}px
- Snap to grid: {{SNAP_TO_GRID}}
- Theme: {{THEME}}
DOCUMENTATION:
- Setup Guide: workflows/4-ux-design/excalidraw-integration/excalidraw-setup.md
- Sketching Guide: workflows/4-ux-design/excalidraw-integration/sketching-guide.md
- AI Collaboration: workflows/4-ux-design/excalidraw-integration/ai-collaboration.md
Ready to start sketching! 🎨
```
</output>
---
## Configuration Output
**Update project-config.yaml:**
```yaml
sketching:
tool: excalidraw
excalidraw:
enabled: true
auto_export: {{USER_CHOICE}}
use_library: {{USER_CHOICE}}
grid_size: {{USER_CHOICE}}
snap_to_grid: {{USER_CHOICE}}
theme: {{USER_CHOICE}}
sketches_folder: "sketches"
```
---
## If User Declines Excalidraw
<output>
```
No problem! You can use any sketching tool you prefer.
Common alternatives:
- Paper and pen (photograph/scan)
- Figma (professional design tool)
- iPad + Apple Pencil
- Other digital whiteboard tools
WDS works with any sketching method. Just:
1. Create your sketches
2. Export to PNG/JPG
3. Upload to AI for analysis
4. Save in scenario sketches folder
Configuration saved with: sketching.tool: "other"
```
</output>
---
## Integration with Phase 4
**During Phase 4B (Sketch Interface):**
**If Excalidraw enabled:**
```
Agent: "I see you've configured Excalidraw for this project.
Would you like to:
1. Sketch manually in Excalidraw
2. Have me generate layout variations in Excalidraw
3. Use a different tool for this scenario
Your choice:"
```
**If Excalidraw not enabled:**
```
Agent: "Time to sketch the interface.
You can:
1. Sketch on paper (photograph/scan)
2. Use your preferred digital tool
3. Enable Excalidraw now (if you'd like)
Your choice:"
```
---
## Error Handling
### **If user unsure:**
<output>
```
Not sure if Excalidraw is right for you?
PROS:
✓ Free and open-source
✓ Works in VS Code or browser
✓ AI can generate sketches
✓ Version control friendly
✓ Easy to learn
CONS:
✗ Requires tool setup
✗ Not as precise as Figma
✗ Limited styling options
RECOMMENDATION:
Try it! You can always switch tools later.
Configuration can be changed in project-config.yaml.
Would you like to enable Excalidraw? (y/n)
```
</output>
### **If installation fails:**
<output>
```
Having trouble installing Excalidraw?
FALLBACK OPTIONS:
1. Use web version (no installation):
https://excalidraw.com
2. Use different tool temporarily:
- Paper and pen
- Figma
- Other whiteboard tool
3. Skip sketching for now:
- Describe interface verbally
- AI can generate sketches later
Your choice:
```
</output>
---
## Post-Configuration
**Create folder structure:**
```
C-Scenarios/
└── [scenario-name]/
└── sketches/ ← Created automatically
```
**If use_library: true:**
- Verify wds-library.excalidrawlib exists
- Provide path for loading
**If auto_export: true:**
- Check if GitHub Actions can be configured
- Provide setup instructions
- Warn if not possible (e.g., not using GitHub)
---
## Success Criteria
**Configuration complete when:**
- ✓ User choice recorded in project-config.yaml
- ✓ Installation instructions provided
- ✓ Documentation links shared
- ✓ Folder structure created
- ✓ User knows next steps
---
**This prompt ensures smooth Excalidraw setup tailored to user preferences!** ⚙️✨

76
src/modules/wds/workflows/workflow-init/project-config.template.yaml Normal file
View File

@ -0,0 +1,76 @@
# WDS Project Configuration
# Generated: {{DATE}}
project:
name: "{{PROJECT_NAME}}"
description: "{{PROJECT_DESCRIPTION}}"
wds_version: "6.0"
created: "{{DATE}}"
# Design System Configuration
design_system:
enabled: {{DESIGN_SYSTEM_ENABLED}} # true | false
mode: "{{DESIGN_SYSTEM_MODE}}" # "none" | "custom" | "library"
# If mode: custom
figma:
enabled: {{FIGMA_ENABLED}} # true | false
file_url: "{{FIGMA_URL}}" # Figma file URL (if applicable)
# If mode: library
library:
name: "{{LIBRARY_NAME}}" # e.g., "shadcn/ui", "MUI", "Radix"
version: "{{LIBRARY_VERSION}}" # e.g., "1.0.0"
# Sketching Tool Configuration
sketching:
tool: "{{SKETCHING_TOOL}}" # "paper" | "excalidraw" | "figma" | "other"
# If tool: excalidraw
excalidraw:
enabled: {{EXCALIDRAW_ENABLED}} # true | false
# Auto-export to PNG/SVG on save
auto_export: {{AUTO_EXPORT}} # true | false
# Load WDS component library
use_library: {{USE_LIBRARY}} # true | false
# Grid settings
grid_size: {{GRID_SIZE}} # pixels (recommended: 20)
snap_to_grid: {{SNAP_TO_GRID}} # true | false
# Default theme
theme: "{{THEME}}" # "light" | "dark"
# File organization
sketches_folder: "sketches" # relative to scenario folder
# Output Folders
output:
root: "." # Project root
project_brief: "A-Project-Brief"
trigger_map: "B-Trigger-Map"
scenarios: "C-Scenarios"
design_system: "D-Design-System"
# Workflow Preferences
workflow:
# Phase 4: UX Design
ux_design:
sketch_first: {{SKETCH_FIRST}} # true | false
ai_suggestions: {{AI_SUGGESTIONS}} # true | false
# Phase 5: Design System
design_system:
auto_extract: {{AUTO_EXTRACT}} # true | false
similarity_threshold: {{SIMILARITY_THRESHOLD}} # 0.0-1.0 (recommended: 0.7)
# Team Configuration
team:
designer: "{{DESIGNER_NAME}}"
stakeholders: [] # Add stakeholder names
# Notes
notes: |
{{PROJECT_NOTES}}