WDS v6 conversion
- Update README and agent names for WDS v6 conversion - Enhance WDS documentation and finalize PRD structure - Finalize WDS methodology documentation and phase details - Implement language configuration and workflow documentation - Add course content and design system updates - Add Excalidraw integration - Implement micro-file architecture for Phase 6 & 7 workflows
This commit is contained in:
Mårten Angner
GitHub
parent
0d7364e534
commit
a38cd018b8
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,533 @@
|
|||
# WDS Design Delivery Specification
|
||||
|
||||
**For BMad Agents: How to read and interpret WDS Design Deliveries**
|
||||
|
||||
---
|
||||
|
||||
## What is a Design Delivery?
|
||||
|
||||
A Design Delivery (DD) is a package created by WDS that contains:
|
||||
- Complete user flow specifications
|
||||
- Technical requirements
|
||||
- Design system references
|
||||
- Acceptance criteria
|
||||
- Testing guidance
|
||||
|
||||
**Purpose:** Hand off design work to development in a structured, traceable format
|
||||
|
||||
**Location:** `deliveries/DD-XXX-name.yaml`
|
||||
|
||||
**Created by:** WDS UX Expert (Phase 4-6)
|
||||
**Consumed by:** BMad Architect & Developer
|
||||
|
||||
---
|
||||
|
||||
## File Format
|
||||
|
||||
```yaml
|
||||
delivery:
|
||||
id: "DD-001" # Unique identifier (DD-XXX)
|
||||
name: "Login & Onboarding" # Human-readable name
|
||||
type: "user_flow" # user_flow | feature | component
|
||||
status: "ready" # ready | in_progress | blocked
|
||||
priority: "high" # high | medium | low
|
||||
created_by: "wds-ux-expert" # Creator agent
|
||||
created_at: "2024-12-09T10:00:00Z"
|
||||
updated_at: "2024-12-09T10:00:00Z"
|
||||
version: "1.0"
|
||||
|
||||
description: |
|
||||
Complete user authentication and onboarding flow.
|
||||
User can create account, join family, and reach dashboard.
|
||||
Testable as standalone feature with real users.
|
||||
|
||||
user_value:
|
||||
problem: "Users need to access the app securely and set up their family"
|
||||
solution: "Streamlined onboarding with family setup"
|
||||
success_criteria:
|
||||
- "User completes signup in under 2 minutes"
|
||||
- "User successfully joins or creates family"
|
||||
- "User reaches functional dashboard"
|
||||
- "90% completion rate for onboarding flow"
|
||||
|
||||
design_artifacts:
|
||||
scenarios:
|
||||
- id: "01-welcome"
|
||||
path: "C-Scenarios/01-welcome-screen/"
|
||||
screens: ["welcome"]
|
||||
|
||||
- id: "02-login"
|
||||
path: "C-Scenarios/02-login/"
|
||||
screens: ["login", "forgot-password"]
|
||||
|
||||
user_flows:
|
||||
- name: "New User Onboarding"
|
||||
path: "C-Scenarios/flows/new-user-onboarding.excalidraw"
|
||||
entry: "welcome"
|
||||
exit: "dashboard"
|
||||
|
||||
design_system:
|
||||
components:
|
||||
- "Button (Primary, Secondary)"
|
||||
- "Input Field (Email, Password)"
|
||||
- "Card (Welcome, Family)"
|
||||
path: "D-Design-System/"
|
||||
|
||||
technical_requirements:
|
||||
platform:
|
||||
frontend: "react_native"
|
||||
backend: "supabase"
|
||||
|
||||
integrations:
|
||||
- name: "supabase_auth"
|
||||
purpose: "User authentication"
|
||||
required: true
|
||||
|
||||
- name: "email_verification"
|
||||
purpose: "Verify user email"
|
||||
required: true
|
||||
|
||||
data_models:
|
||||
- name: "User"
|
||||
fields: ["email", "name", "avatar"]
|
||||
|
||||
- name: "Family"
|
||||
fields: ["name", "invite_code", "members"]
|
||||
|
||||
acceptance_criteria:
|
||||
functional:
|
||||
- "User can create account with email/password"
|
||||
- "User receives verification email"
|
||||
- "User can create new family or join existing"
|
||||
|
||||
non_functional:
|
||||
- "Onboarding completes in < 2 minutes"
|
||||
- "Works offline (cached welcome screen)"
|
||||
- "Accessible (WCAG 2.1 AA)"
|
||||
|
||||
edge_cases:
|
||||
- "Email already exists → Show login option"
|
||||
- "Invalid invite code → Show error, allow retry"
|
||||
- "Network error during signup → Save progress, retry"
|
||||
|
||||
testing_guidance:
|
||||
user_testing:
|
||||
- "Test with 5 families (different tech comfort levels)"
|
||||
- "Measure completion time and drop-off points"
|
||||
|
||||
qa_testing:
|
||||
- "Test all error states"
|
||||
- "Test offline scenarios"
|
||||
- "Test accessibility with screen reader"
|
||||
|
||||
estimated_complexity:
|
||||
size: "medium" # small | medium | large
|
||||
effort: "2-3 weeks" # Time estimate
|
||||
risk: "low" # low | medium | high
|
||||
dependencies: [] # Other DD-XXX IDs needed first
|
||||
|
||||
notes: |
|
||||
This is the first user-facing feature and sets the tone
|
||||
for the entire app experience. Focus on simplicity and
|
||||
clarity. The family setup is unique to this app and needs
|
||||
extra attention in user testing.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## How to Read Design Deliveries
|
||||
|
||||
### Step 1: Detect Deliveries
|
||||
|
||||
```bash
|
||||
# Check if deliveries directory exists
|
||||
if [ -d "deliveries" ]; then
|
||||
echo "✓ WDS Design Deliveries found!"
|
||||
ls deliveries/DD-*.yaml
|
||||
else
|
||||
echo "⚠ No Design Deliveries yet"
|
||||
fi
|
||||
```
|
||||
|
||||
### Step 2: Load Delivery
|
||||
|
||||
```python
|
||||
import yaml
|
||||
|
||||
# Load delivery file
|
||||
with open('deliveries/DD-001-login-onboarding.yaml') as f:
|
||||
delivery = yaml.safe_load(f)
|
||||
|
||||
# Extract key information
|
||||
name = delivery['delivery']['name']
|
||||
priority = delivery['delivery']['priority']
|
||||
status = delivery['delivery']['status']
|
||||
|
||||
print(f"Delivery: {name}")
|
||||
print(f"Priority: {priority}")
|
||||
print(f"Status: {status}")
|
||||
```
|
||||
|
||||
### Step 3: Extract Scenarios
|
||||
|
||||
```python
|
||||
# Get all scenarios
|
||||
scenarios = delivery['design_artifacts']['scenarios']
|
||||
|
||||
for scenario in scenarios:
|
||||
scenario_id = scenario['id']
|
||||
scenario_path = scenario['path']
|
||||
screens = scenario['screens']
|
||||
|
||||
print(f"Scenario: {scenario_id}")
|
||||
print(f"Path: {scenario_path}")
|
||||
print(f"Screens: {', '.join(screens)}")
|
||||
|
||||
# Read scenario specifications
|
||||
spec_path = f"{scenario_path}/Frontend/specifications.md"
|
||||
# Read and parse specifications...
|
||||
```
|
||||
|
||||
### Step 4: Extract Technical Requirements
|
||||
|
||||
```python
|
||||
# Get tech stack
|
||||
platform = delivery['technical_requirements']['platform']
|
||||
frontend = platform['frontend']
|
||||
backend = platform['backend']
|
||||
|
||||
print(f"Frontend: {frontend}")
|
||||
print(f"Backend: {backend}")
|
||||
|
||||
# Get integrations
|
||||
integrations = delivery['technical_requirements']['integrations']
|
||||
for integration in integrations:
|
||||
name = integration['name']
|
||||
required = integration['required']
|
||||
purpose = integration['purpose']
|
||||
|
||||
print(f"Integration: {name} ({'required' if required else 'optional'})")
|
||||
print(f"Purpose: {purpose}")
|
||||
```
|
||||
|
||||
### Step 5: Extract Design System Components
|
||||
|
||||
```python
|
||||
# Get components used
|
||||
components = delivery['design_artifacts']['design_system']['components']
|
||||
ds_path = delivery['design_artifacts']['design_system']['path']
|
||||
|
||||
for component in components:
|
||||
print(f"Component: {component}")
|
||||
# Read component specification from design system
|
||||
# component_spec = read_file(f"{ds_path}/03-Atomic-Components/{component}/")
|
||||
```
|
||||
|
||||
### Step 6: Extract Acceptance Criteria
|
||||
|
||||
```python
|
||||
# Get acceptance criteria
|
||||
criteria = delivery['acceptance_criteria']
|
||||
|
||||
functional = criteria['functional']
|
||||
non_functional = criteria['non_functional']
|
||||
edge_cases = criteria['edge_cases']
|
||||
|
||||
print("Functional Requirements:")
|
||||
for req in functional:
|
||||
print(f" - {req}")
|
||||
|
||||
print("\nNon-Functional Requirements:")
|
||||
for req in non_functional:
|
||||
print(f" - {req}")
|
||||
|
||||
print("\nEdge Cases:")
|
||||
for case in edge_cases:
|
||||
print(f" - {case}")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Breaking Down into Development Epics
|
||||
|
||||
### Epic Structure
|
||||
|
||||
```markdown
|
||||
# Epic X.X: [Name]
|
||||
|
||||
**Source:** DD-XXX ([Delivery Name])
|
||||
**Priority:** [high|medium|low]
|
||||
**Effort:** [X days/weeks]
|
||||
**Risk:** [low|medium|high]
|
||||
**Dependencies:** [Other epics]
|
||||
|
||||
## Scope
|
||||
|
||||
[What this epic covers from the delivery]
|
||||
|
||||
## Design References
|
||||
|
||||
- **Delivery:** deliveries/DD-XXX.yaml
|
||||
- **Scenarios:** [List of scenario paths]
|
||||
- **Design System:** [List of components]
|
||||
- **Specifications:** [Links to detailed specs]
|
||||
|
||||
## Technical Requirements
|
||||
|
||||
[From delivery.technical_requirements]
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
[From delivery.acceptance_criteria]
|
||||
|
||||
## Implementation Tasks
|
||||
|
||||
1. [Task 1]
|
||||
2. [Task 2]
|
||||
3. [Task 3]
|
||||
|
||||
## Testing
|
||||
|
||||
[From delivery.testing_guidance]
|
||||
```
|
||||
|
||||
### Example Breakdown
|
||||
|
||||
**From DD-001 (Login & Onboarding):**
|
||||
|
||||
```
|
||||
Epic 1.1: Authentication Infrastructure
|
||||
- Set up Supabase auth
|
||||
- Configure email verification
|
||||
- Create User and Family data models
|
||||
Effort: 3 days
|
||||
Source: DD-001 technical_requirements
|
||||
|
||||
Epic 1.2: Welcome & Login Screens
|
||||
- Implement Welcome screen (Scenario 01)
|
||||
- Implement Login screen (Scenario 02)
|
||||
- Use design system: Button (Primary), Input (Email, Password)
|
||||
Effort: 4 days
|
||||
Source: DD-001 scenarios 01-02
|
||||
|
||||
Epic 1.3: Signup Flow
|
||||
- Implement Signup screen (Scenario 03)
|
||||
- Implement email verification flow
|
||||
- Handle error states
|
||||
Effort: 5 days
|
||||
Source: DD-001 scenario 03
|
||||
|
||||
Epic 1.4: Family Setup
|
||||
- Implement create/join family (Scenario 04)
|
||||
- Implement add dogs flow
|
||||
- Complete onboarding
|
||||
Effort: 5 days
|
||||
Source: DD-001 scenario 04
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Important Principles
|
||||
|
||||
### 1. Respect Designer Decisions
|
||||
|
||||
**The designer has already made these choices:**
|
||||
- Tech stack (platform.frontend, platform.backend)
|
||||
- Integrations (technical_requirements.integrations)
|
||||
- Component usage (design_system.components)
|
||||
|
||||
**Your job:** Implement these choices faithfully
|
||||
|
||||
**Exception:** If you see a technical problem, flag it:
|
||||
```
|
||||
"⚠️ Technical Concern: DD-001 specifies Supabase Auth,
|
||||
but project already uses Firebase. Recommend discussing
|
||||
with designer before proceeding."
|
||||
```
|
||||
|
||||
### 2. Maintain Traceability
|
||||
|
||||
**Always link back to source:**
|
||||
```markdown
|
||||
Epic 1.2: Login Screen
|
||||
**Source:** DD-001 (Login & Onboarding)
|
||||
**Scenario:** C-Scenarios/02-login/
|
||||
**Design System:** D-Design-System/03-Atomic-Components/Buttons/
|
||||
**Acceptance Criteria:** DD-001 acceptance_criteria.functional
|
||||
```
|
||||
|
||||
### 3. Use Acceptance Criteria
|
||||
|
||||
**Designer provided acceptance criteria - these are your requirements:**
|
||||
```yaml
|
||||
acceptance_criteria:
|
||||
functional:
|
||||
- "User can create account with email/password"
|
||||
- "User receives verification email"
|
||||
```
|
||||
|
||||
**Your epics must cover ALL acceptance criteria**
|
||||
|
||||
### 4. Follow Testing Guidance
|
||||
|
||||
**Designer provided testing guidance:**
|
||||
```yaml
|
||||
testing_guidance:
|
||||
user_testing:
|
||||
- "Test with 5 families (different tech comfort levels)"
|
||||
qa_testing:
|
||||
- "Test all error states"
|
||||
- "Test offline scenarios"
|
||||
```
|
||||
|
||||
**Your test plans should follow this guidance**
|
||||
|
||||
---
|
||||
|
||||
## Delivery Status
|
||||
|
||||
### Status Values
|
||||
|
||||
**ready:** Complete and ready for development
|
||||
**in_progress:** Designer still working on scenarios
|
||||
**blocked:** Waiting for something (dependencies, decisions)
|
||||
|
||||
### Checking Status
|
||||
|
||||
```python
|
||||
status = delivery['delivery']['status']
|
||||
|
||||
if status == 'ready':
|
||||
print("✓ Delivery is ready for development!")
|
||||
elif status == 'in_progress':
|
||||
print("⏳ Delivery is still being designed")
|
||||
print(" Wait for designer to mark as ready")
|
||||
elif status == 'blocked':
|
||||
print("🚫 Delivery is blocked")
|
||||
print(f" Reason: {delivery.get('notes', 'See designer')}")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Delivery Dependencies
|
||||
|
||||
### Understanding Dependencies
|
||||
|
||||
```yaml
|
||||
estimated_complexity:
|
||||
dependencies: ["DD-002", "DD-005"]
|
||||
```
|
||||
|
||||
**This means:** DD-001 requires DD-002 and DD-005 to be implemented first
|
||||
|
||||
### Checking Dependencies
|
||||
|
||||
```python
|
||||
dependencies = delivery['estimated_complexity']['dependencies']
|
||||
|
||||
if dependencies:
|
||||
print(f"⚠ This delivery depends on: {', '.join(dependencies)}")
|
||||
print(" Implement dependencies first")
|
||||
else:
|
||||
print("✓ No dependencies - can start immediately")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Delivery Updates
|
||||
|
||||
### Version History
|
||||
|
||||
```yaml
|
||||
delivery:
|
||||
version: "1.1"
|
||||
updated_at: "2024-12-15T14:00:00Z"
|
||||
|
||||
notes: |
|
||||
Version 1.1 changes:
|
||||
- Added offline support requirement
|
||||
- Updated family setup flow based on user testing
|
||||
- Added new edge case: slow network handling
|
||||
```
|
||||
|
||||
**Always check version and updated_at to see if delivery has changed**
|
||||
|
||||
---
|
||||
|
||||
## Fallback: No Deliveries
|
||||
|
||||
If `deliveries/` directory doesn't exist:
|
||||
|
||||
### Option 1: Check for Platform Requirements
|
||||
|
||||
```bash
|
||||
if [ -f "A-Project-Brief/platform-requirements.yaml" ]; then
|
||||
echo "✓ WDS Platform Requirements found"
|
||||
echo " WDS is being used, but no deliveries yet"
|
||||
echo " Wait for designer to complete Phase 4"
|
||||
fi
|
||||
```
|
||||
|
||||
### Option 2: Traditional BMad Workflow
|
||||
|
||||
```bash
|
||||
if [ -f "requirements.md" ]; then
|
||||
echo "✓ Traditional requirements found"
|
||||
echo " Proceed with standard BMad workflow"
|
||||
fi
|
||||
```
|
||||
|
||||
### Option 3: Start from Scratch
|
||||
|
||||
```bash
|
||||
echo "⚠ No requirements found"
|
||||
echo " Start requirements gathering"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### File Locations
|
||||
|
||||
```
|
||||
deliveries/
|
||||
├── DD-001-login-onboarding.yaml
|
||||
├── DD-002-morning-dog-care.yaml
|
||||
└── DD-003-task-assignment.yaml
|
||||
|
||||
C-Scenarios/
|
||||
├── 01-welcome-screen/
|
||||
│ └── Frontend/
|
||||
│ └── specifications.md
|
||||
└── 02-login/
|
||||
└── Frontend/
|
||||
└── specifications.md
|
||||
|
||||
D-Design-System/
|
||||
├── 02-Foundation/
|
||||
│ ├── Colors/tokens.json
|
||||
│ └── Typography/tokens.json
|
||||
└── 03-Atomic-Components/
|
||||
├── Buttons/Button-Primary.md
|
||||
└── Inputs/Input-Text.md
|
||||
```
|
||||
|
||||
### Key Fields
|
||||
|
||||
```yaml
|
||||
delivery.id # Unique ID
|
||||
delivery.status # ready | in_progress | blocked
|
||||
delivery.priority # high | medium | low
|
||||
design_artifacts.scenarios # List of scenarios
|
||||
design_artifacts.design_system.components # Components used
|
||||
technical_requirements.platform # Tech stack
|
||||
technical_requirements.integrations # Required integrations
|
||||
acceptance_criteria.functional # What must work
|
||||
estimated_complexity.effort # Time estimate
|
||||
estimated_complexity.dependencies # Other DDs needed first
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**This specification enables BMad agents to seamlessly consume WDS design work!** 📦✨
|
||||
|
|
@ -0,0 +1,619 @@
|
|||
# WDS → BMad Handoff Protocol
|
||||
|
||||
**Multi-agent dialog for seamless design-to-development handoff**
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
The handoff is a structured conversation between:
|
||||
- **WDS UX Expert** (Design authority)
|
||||
- **BMad Architect** (Technical authority)
|
||||
|
||||
**Purpose:** Transfer design knowledge, build mutual understanding, ensure faithful implementation
|
||||
|
||||
**Duration:** ~20 minutes per Design Delivery
|
||||
|
||||
**Outcome:** Clear implementation plan that honors design vision
|
||||
|
||||
---
|
||||
|
||||
## Handoff Structure
|
||||
|
||||
### Phase 1: Introduction (1 min)
|
||||
|
||||
**WDS UX Expert initiates:**
|
||||
```
|
||||
"Hey Architect! I've completed the design for [Delivery Name].
|
||||
|
||||
I've packaged everything into Design Delivery [DD-XXX].
|
||||
Let me walk you through what I've designed..."
|
||||
```
|
||||
|
||||
**BMad Architect acknowledges:**
|
||||
```
|
||||
"Great! I'm ready to receive the handoff. What have you got for me?"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: User Value (2 min)
|
||||
|
||||
**WDS UX Expert explains:**
|
||||
|
||||
```
|
||||
"This delivery covers [brief description of feature].
|
||||
|
||||
📱 User Flow:
|
||||
- [Entry point] → [Key steps] → [Exit point]
|
||||
|
||||
[Explain the user experience and why it matters]"
|
||||
```
|
||||
|
||||
**BMad Architect asks:**
|
||||
```
|
||||
"Got it. What's the user value here?"
|
||||
```
|
||||
|
||||
**WDS UX Expert responds:**
|
||||
```
|
||||
"The problem: [User problem being solved]
|
||||
|
||||
The solution: [How this feature solves it]
|
||||
|
||||
Success criteria:
|
||||
- [Measurable criterion 1]
|
||||
- [Measurable criterion 2]
|
||||
- [Measurable criterion 3]"
|
||||
```
|
||||
|
||||
**BMad Architect confirms:**
|
||||
```
|
||||
"Perfect. I understand the user value. What scenarios did you design?"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Design Walkthrough (5 min)
|
||||
|
||||
**WDS UX Expert walks through scenarios:**
|
||||
|
||||
```
|
||||
"I've designed [N] complete scenarios:
|
||||
|
||||
Scenario [ID]: [Name]
|
||||
- [Brief description]
|
||||
- [Key screens]
|
||||
- Specs: [Path to specifications]
|
||||
|
||||
Scenario [ID]: [Name]
|
||||
- [Brief description]
|
||||
- [Key screens]
|
||||
- Specs: [Path to specifications]
|
||||
|
||||
[Continue for all scenarios...]
|
||||
|
||||
Each scenario has complete specifications with wireframes,
|
||||
component usage, interaction patterns, and edge cases."
|
||||
```
|
||||
|
||||
**BMad Architect may ask:**
|
||||
```
|
||||
"Can you elaborate on [specific scenario]?"
|
||||
"How does [screen A] connect to [screen B]?"
|
||||
"What happens if [edge case]?"
|
||||
```
|
||||
|
||||
**WDS UX Expert answers clearly and references specs**
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Technical Requirements (3 min)
|
||||
|
||||
**BMad Architect asks:**
|
||||
```
|
||||
"What about the technical stack? Any preferences?"
|
||||
```
|
||||
|
||||
**WDS UX Expert shares:**
|
||||
```
|
||||
"Yes! I've already defined the platform requirements:
|
||||
|
||||
Frontend: [Framework]
|
||||
- [Why this choice]
|
||||
- [Key benefits]
|
||||
|
||||
Backend: [Framework]
|
||||
- [Why this choice]
|
||||
- [Key benefits]
|
||||
|
||||
The designer chose these because [reasoning]."
|
||||
```
|
||||
|
||||
**BMad Architect asks:**
|
||||
```
|
||||
"Makes sense. What integrations do you need?"
|
||||
```
|
||||
|
||||
**WDS UX Expert lists:**
|
||||
```
|
||||
"[N] key integrations:
|
||||
|
||||
1. [Integration Name] (Required/Optional)
|
||||
- [Purpose]
|
||||
- [Why needed]
|
||||
- [Critical if required]
|
||||
|
||||
2. [Integration Name] (Required/Optional)
|
||||
- [Purpose]
|
||||
- [Why needed]
|
||||
|
||||
[Continue for all integrations...]"
|
||||
```
|
||||
|
||||
**BMad Architect asks:**
|
||||
```
|
||||
"Got it. What data models do I need to implement?"
|
||||
```
|
||||
|
||||
**WDS UX Expert defines:**
|
||||
```
|
||||
"[N] main models:
|
||||
|
||||
[Model Name]:
|
||||
- [field]: [type, constraints]
|
||||
- [field]: [type, constraints]
|
||||
- [relationships]
|
||||
|
||||
[Model Name]:
|
||||
- [field]: [type, constraints]
|
||||
- [field]: [type, constraints]
|
||||
|
||||
These are defined in the platform requirements, but let me
|
||||
know if you see any technical issues with these structures."
|
||||
```
|
||||
|
||||
**BMad Architect validates:**
|
||||
```
|
||||
"These look good. [Or: I see a potential issue with...]"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 5: Design System (2 min)
|
||||
|
||||
**BMad Architect asks:**
|
||||
```
|
||||
"What about the design system? What components should I use?"
|
||||
```
|
||||
|
||||
**WDS UX Expert lists:**
|
||||
```
|
||||
"I've used components from our design system:
|
||||
|
||||
[Component Category]:
|
||||
- [Component Name] ([variants/states])
|
||||
- [Component Name] ([variants/states])
|
||||
|
||||
[Component Category]:
|
||||
- [Component Name] ([variants/states])
|
||||
- [Component Name] ([variants/states])
|
||||
|
||||
All components are fully specified in D-Design-System/.
|
||||
Please use these exact components - they're already designed,
|
||||
tested, and match our brand."
|
||||
```
|
||||
|
||||
**BMad Architect confirms:**
|
||||
```
|
||||
"Perfect. I'll reference those. What are the acceptance criteria?"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 6: Acceptance Criteria (2 min)
|
||||
|
||||
**WDS UX Expert shares:**
|
||||
```
|
||||
"Functional requirements:
|
||||
✓ [Requirement 1]
|
||||
✓ [Requirement 2]
|
||||
✓ [Requirement 3]
|
||||
|
||||
Non-functional requirements:
|
||||
✓ [Performance requirement]
|
||||
✓ [Accessibility requirement]
|
||||
✓ [Security requirement]
|
||||
|
||||
Edge cases to handle:
|
||||
✓ [Edge case 1] → [Expected behavior]
|
||||
✓ [Edge case 2] → [Expected behavior]
|
||||
✓ [Edge case 3] → [Expected behavior]
|
||||
|
||||
These are all in the delivery document, but I wanted to
|
||||
highlight the critical ones."
|
||||
```
|
||||
|
||||
**BMad Architect acknowledges:**
|
||||
```
|
||||
"Great detail! How should I test this?"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 7: Testing (2 min)
|
||||
|
||||
**WDS UX Expert explains:**
|
||||
```
|
||||
"I've created a test scenario: test-scenarios/[TS-XXX].yaml
|
||||
|
||||
It includes:
|
||||
- Happy path tests (complete flow)
|
||||
- Error state tests (all failure modes)
|
||||
- Edge case tests (unusual scenarios)
|
||||
- Design system validation (component compliance)
|
||||
- Accessibility tests (screen reader, contrast)
|
||||
- Usability tests (time to complete, user feedback)
|
||||
|
||||
After you build this, I'll run through the test scenario
|
||||
and validate that the implementation matches my design.
|
||||
|
||||
If there are issues, I'll create issue tickets with
|
||||
screenshots and references back to the specifications."
|
||||
```
|
||||
|
||||
**BMad Architect confirms:**
|
||||
```
|
||||
"Perfect. What's your estimate for complexity?"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 8: Estimates & Planning (3 min)
|
||||
|
||||
**WDS UX Expert shares:**
|
||||
```
|
||||
"Size: [small|medium|large]
|
||||
Effort: [time estimate]
|
||||
Risk: [low|medium|high]
|
||||
Dependencies: [None or list of DD-XXX]
|
||||
|
||||
[Explain reasoning for estimate]"
|
||||
```
|
||||
|
||||
**BMad Architect proposes:**
|
||||
```
|
||||
"Excellent handoff! Let me break this down into development epics:
|
||||
|
||||
Epic X.1: [Name]
|
||||
- [Scope]
|
||||
- Effort: [X days]
|
||||
|
||||
Epic X.2: [Name]
|
||||
- [Scope]
|
||||
- Effort: [X days]
|
||||
|
||||
Epic X.3: [Name]
|
||||
- [Scope]
|
||||
- Effort: [X days]
|
||||
|
||||
Total: [X weeks], matches your estimate.
|
||||
|
||||
[Explain approach and reasoning]"
|
||||
```
|
||||
|
||||
**WDS UX Expert may suggest:**
|
||||
```
|
||||
"That breakdown makes sense. [Or: One suggestion...]
|
||||
|
||||
[Provide feedback on epic breakdown]"
|
||||
```
|
||||
|
||||
**BMad Architect adjusts if needed:**
|
||||
```
|
||||
"Good idea! [Revised plan if applicable]
|
||||
|
||||
I'll document this plan and start breaking down the
|
||||
implementation details."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 9: Special Considerations (2 min)
|
||||
|
||||
**WDS UX Expert shares important notes:**
|
||||
```
|
||||
"Yes! A few important notes:
|
||||
|
||||
1. [Critical consideration]
|
||||
[Why it matters]
|
||||
[What to pay attention to]
|
||||
|
||||
2. [Important detail]
|
||||
[Context and reasoning]
|
||||
[Implementation guidance]
|
||||
|
||||
3. [Special requirement]
|
||||
[Background]
|
||||
[How to handle]
|
||||
|
||||
[Continue for all special considerations...]"
|
||||
```
|
||||
|
||||
**BMad Architect acknowledges:**
|
||||
```
|
||||
"All noted! I'll make sure to:
|
||||
- [Commitment 1]
|
||||
- [Commitment 2]
|
||||
- [Commitment 3]
|
||||
|
||||
[Summarize understanding of special considerations]"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 10: Confirmation (1 min)
|
||||
|
||||
**BMad Architect summarizes:**
|
||||
```
|
||||
"Excellent handoff! Let me summarize what I'm taking:
|
||||
|
||||
📦 Design Delivery: [DD-XXX] [Name]
|
||||
📱 User Flow: [Entry] → [Exit] (complete)
|
||||
📄 Scenarios: [N] (all specified)
|
||||
🎨 Design System: [N] components (all defined)
|
||||
⚙️ Tech Stack: [Frontend] + [Backend]
|
||||
🔌 Integrations: [N] required, [N] optional
|
||||
💾 Data Models: [N] ([list names])
|
||||
✅ Acceptance Criteria: Clear and testable
|
||||
🧪 Test Scenario: [TS-XXX] (ready for validation)
|
||||
|
||||
I'll break this down into [N] development epics:
|
||||
[List epics with effort]
|
||||
|
||||
Total: [X weeks]
|
||||
|
||||
Any concerns or special considerations I should know about?"
|
||||
```
|
||||
|
||||
**WDS UX Expert confirms or corrects:**
|
||||
```
|
||||
"[If correct:] Perfect! That's exactly right.
|
||||
|
||||
[If correction needed:] One correction: [clarification]
|
||||
|
||||
[Final notes or encouragement]
|
||||
|
||||
Design Delivery [DD-XXX] is officially handed off! 🎉
|
||||
|
||||
Looking forward to seeing this come to life. Remember:
|
||||
[Key message about design vision]"
|
||||
```
|
||||
|
||||
**BMad Architect commits:**
|
||||
```
|
||||
"Got it! I'll make sure the implementation honors your
|
||||
design vision. Talk soon!"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Agent Instructions
|
||||
|
||||
### For WDS UX Expert
|
||||
|
||||
**Your role:**
|
||||
- Be the design authority
|
||||
- Explain the "why" behind decisions
|
||||
- Share context and considerations
|
||||
- Answer questions clearly
|
||||
- Trust the architect to implement well
|
||||
|
||||
**Tone:**
|
||||
- Collaborative, not dictatorial
|
||||
- Helpful, not defensive
|
||||
- Clear, not vague
|
||||
- Confident, not arrogant
|
||||
- Encouraging, not demanding
|
||||
|
||||
**Key phrases:**
|
||||
- "Here's what I've designed..."
|
||||
- "The user value is..."
|
||||
- "I've focused on..."
|
||||
- "Please pay attention to..."
|
||||
- "Let me know if you have questions..."
|
||||
- "I trust you to implement this well"
|
||||
|
||||
**What to emphasize:**
|
||||
- User value and success criteria
|
||||
- Critical user experience details
|
||||
- Design system compliance
|
||||
- Accessibility requirements
|
||||
- Special considerations
|
||||
|
||||
**What to avoid:**
|
||||
- Micromanaging implementation details
|
||||
- Being defensive about design choices
|
||||
- Technical jargon (unless necessary)
|
||||
- Assuming architect knows context
|
||||
- Rushing through important details
|
||||
|
||||
---
|
||||
|
||||
### For BMad Architect
|
||||
|
||||
**Your role:**
|
||||
- Be the technical authority
|
||||
- Ask clarifying questions
|
||||
- Validate technical feasibility
|
||||
- Propose implementation approach
|
||||
- Commit to honoring design vision
|
||||
|
||||
**Tone:**
|
||||
- Respectful, not dismissive
|
||||
- Curious, not challenging
|
||||
- Collaborative, not adversarial
|
||||
- Professional, not casual
|
||||
- Appreciative, not critical
|
||||
|
||||
**Key phrases:**
|
||||
- "What have you got for me?"
|
||||
- "Got it. What about..."
|
||||
- "Makes sense. What..."
|
||||
- "Can you elaborate on..."
|
||||
- "Let me summarize..."
|
||||
- "I'll make sure to..."
|
||||
- "I'll honor your design vision"
|
||||
|
||||
**What to ask about:**
|
||||
- User value and success criteria
|
||||
- Technical requirements
|
||||
- Integration needs
|
||||
- Data models
|
||||
- Acceptance criteria
|
||||
- Testing approach
|
||||
- Special considerations
|
||||
|
||||
**What to avoid:**
|
||||
- Challenging design decisions
|
||||
- Suggesting alternative approaches (unless technical issue)
|
||||
- Dismissing designer's technical choices
|
||||
- Rushing through handoff
|
||||
- Making assumptions
|
||||
|
||||
---
|
||||
|
||||
## Handoff Checklist
|
||||
|
||||
### Before Handoff
|
||||
|
||||
**WDS UX Expert prepares:**
|
||||
- [ ] Design Delivery file created (DD-XXX.yaml)
|
||||
- [ ] All scenarios specified
|
||||
- [ ] Design system components defined
|
||||
- [ ] Test scenario created (TS-XXX.yaml)
|
||||
- [ ] Special considerations documented
|
||||
|
||||
**BMad Architect prepares:**
|
||||
- [ ] Platform requirements reviewed
|
||||
- [ ] Design system reviewed
|
||||
- [ ] Ready to receive handoff
|
||||
- [ ] Questions prepared
|
||||
|
||||
### During Handoff
|
||||
|
||||
- [ ] User value explained and understood
|
||||
- [ ] All scenarios walked through
|
||||
- [ ] Technical requirements shared
|
||||
- [ ] Design system components listed
|
||||
- [ ] Acceptance criteria reviewed
|
||||
- [ ] Testing approach explained
|
||||
- [ ] Complexity estimate discussed
|
||||
- [ ] Special considerations noted
|
||||
- [ ] Epic breakdown proposed
|
||||
- [ ] Both parties agree on approach
|
||||
|
||||
### After Handoff
|
||||
|
||||
**BMad Architect:**
|
||||
- [ ] Handoff summary documented
|
||||
- [ ] Epic breakdown created
|
||||
- [ ] Implementation plan documented
|
||||
- [ ] Questions or concerns flagged
|
||||
|
||||
**WDS UX Expert:**
|
||||
- [ ] Handoff marked complete
|
||||
- [ ] Waiting for implementation
|
||||
- [ ] Available for questions
|
||||
|
||||
---
|
||||
|
||||
## Handoff Variations
|
||||
|
||||
### Simple Delivery (Small Feature)
|
||||
|
||||
**Shorter handoff (~10 min):**
|
||||
- Quick user value explanation
|
||||
- Brief scenario walkthrough
|
||||
- Confirm tech requirements
|
||||
- Simple epic breakdown
|
||||
|
||||
### Complex Delivery (Large Feature)
|
||||
|
||||
**Longer handoff (~30 min):**
|
||||
- Detailed user value discussion
|
||||
- In-depth scenario walkthrough
|
||||
- Technical feasibility discussion
|
||||
- Multiple epic breakdown options
|
||||
- Risk assessment
|
||||
|
||||
### Delivery with Dependencies
|
||||
|
||||
**Include dependency discussion:**
|
||||
- Which deliveries must be done first
|
||||
- Why dependencies exist
|
||||
- How to handle if dependencies delayed
|
||||
|
||||
### Delivery with Technical Concerns
|
||||
|
||||
**Include concern resolution:**
|
||||
- Architect raises concern
|
||||
- UX Expert explains reasoning
|
||||
- Both discuss alternatives
|
||||
- Agreement on path forward
|
||||
|
||||
---
|
||||
|
||||
## Recording Handoff
|
||||
|
||||
### Handoff Log
|
||||
|
||||
**File:** `deliveries/DD-XXX-handoff-log.md`
|
||||
|
||||
```markdown
|
||||
# Handoff Log: DD-XXX [Name]
|
||||
|
||||
**Date:** 2024-12-09
|
||||
**Duration:** 20 minutes
|
||||
**Participants:** WDS UX Expert, BMad Architect
|
||||
|
||||
## Summary
|
||||
|
||||
Design Delivery DD-XXX handed off successfully.
|
||||
|
||||
## Key Points Discussed
|
||||
|
||||
- User value: [Summary]
|
||||
- Scenarios: [N] scenarios, all specified
|
||||
- Tech stack: [Frontend] + [Backend]
|
||||
- Integrations: [List]
|
||||
- Special considerations: [List]
|
||||
|
||||
## Epic Breakdown Agreed
|
||||
|
||||
- Epic X.1: [Name] ([X days])
|
||||
- Epic X.2: [Name] ([X days])
|
||||
- Epic X.3: [Name] ([X days])
|
||||
|
||||
Total: [X weeks]
|
||||
|
||||
## Questions Raised
|
||||
|
||||
Q: [Question]
|
||||
A: [Answer]
|
||||
|
||||
## Action Items
|
||||
|
||||
- [ ] Architect: Create detailed implementation plan
|
||||
- [ ] Architect: Flag any technical concerns
|
||||
- [ ] UX Expert: Available for questions
|
||||
|
||||
## Status
|
||||
|
||||
✅ Handoff complete
|
||||
⏳ Awaiting implementation
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**This protocol ensures smooth, collaborative handoffs that build trust and ensure quality!** 🤝✨
|
||||
|
|
@ -0,0 +1,547 @@
|
|||
# WDS ↔ BMad Method Integration Guide
|
||||
|
||||
**Complete guide for seamless design-to-development workflow**
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
WDS (Whiteport Design Studio) and BMad Method integrate seamlessly to create a complete product development workflow:
|
||||
|
||||
- **WDS:** Design-first methodology (Phases 1-7)
|
||||
- **BMad:** Development methodology (Phases 1-3)
|
||||
- **Integration:** 3 clean touch points
|
||||
|
||||
---
|
||||
|
||||
## The Complete Workflow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ WDS: Design Phase │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Phase 1: Project Brief → [WDS overides BMad] │
|
||||
│ Phase 2: Trigger Map │
|
||||
│ Phase 3: Platform Requirements → [Touch Point 1: WDS→BMad] │
|
||||
│ Phase 4: UX Design │
|
||||
│ Phase 5: Design System │
|
||||
│ Phase 6: Design Deliveries → [Touch Point 2: WDS→BMad] │
|
||||
│ Phase 7: Testing ← [Touch Point 3: BMad→WDS] │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ BMad: Development Phase │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Phase 1: Architecture ← [Reads Touch Points 1, 2] │
|
||||
│ Phase 2: Implementation │
|
||||
│ Phase 3: Testing → [Touch Point 3: BMad→WDS] │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## The 3 Touch Points
|
||||
|
||||
### Touch Point 1: Platform Requirements
|
||||
|
||||
**When:** WDS Phase 3 Complete
|
||||
**Direction:** WDS → BMad (WDS overrides BMad)
|
||||
**File:** `A-Project-Brief/platform-requirements.yaml`
|
||||
|
||||
**What:** Tech stack, integrations, constraints
|
||||
**Why:** Designer (with stakeholders) defines technical foundation
|
||||
**BMad Action:** Read and respect these choices, design architecture accordingly
|
||||
|
||||
**Read:** [platform-requirements-spec.md](platform-requirements-spec.md)
|
||||
|
||||
---
|
||||
|
||||
### Touch Point 2: Design Deliveries
|
||||
|
||||
**When:** WDS Phase 6 Complete
|
||||
**Direction:** WDS → BMad (Complete design handoff)
|
||||
**Files:**
|
||||
- `deliveries/DD-*.yaml` (Design Deliveries)
|
||||
- `C-Scenarios/` (All scenario specifications)
|
||||
- `D-Design-System/` (Component library)
|
||||
- `test-scenarios/TS-*.yaml` (Test scenarios)
|
||||
|
||||
**What:** Complete design package with all scenarios, components, and test criteria
|
||||
**Why:** Single handoff of ALL design work at once
|
||||
**BMad Action:** Read everything, break down into dev epics, implement features
|
||||
|
||||
**Includes:**
|
||||
- Multi-agent handoff dialog (20-min structured conversation)
|
||||
- All design deliveries packaged as testable epics
|
||||
- Complete design system specifications
|
||||
- Test scenarios for validation
|
||||
|
||||
**Read:**
|
||||
- [design-delivery-spec.md](design-delivery-spec.md)
|
||||
- [handoff-protocol.md](handoff-protocol.md)
|
||||
|
||||
---
|
||||
|
||||
### Touch Point 3: Designer Validation
|
||||
|
||||
**When:** After BMad Implementation Complete
|
||||
**Direction:** BMad → WDS (BMad integrates with WDS testing)
|
||||
**Files:**
|
||||
- `test-reports/TR-*.md` (Test results)
|
||||
- `issues/ISS-*.md` (Issues found)
|
||||
|
||||
**What:** BMad requests designer validation, designer tests and approves
|
||||
**Why:** Ensure implementation matches design vision and quality standards
|
||||
**WDS Action:** Run test scenarios, create issues if needed, sign off when approved
|
||||
**BMad Action:** Fix issues, retest until designer approval
|
||||
|
||||
**Process:**
|
||||
1. BMad notifies WDS: "Feature complete, ready for validation"
|
||||
2. WDS runs test scenarios
|
||||
3. WDS creates issues if problems found
|
||||
4. BMad fixes issues
|
||||
5. Repeat until WDS signs off
|
||||
|
||||
**Read:** [testing-protocol.md](testing-protocol.md) *(to be created)*
|
||||
|
||||
---
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
project/
|
||||
├── A-Project-Brief/
|
||||
│ ├── project-brief.md
|
||||
│ └── platform-requirements.yaml ← Touch Point 1
|
||||
│
|
||||
├── B-Trigger-Map/
|
||||
│ └── trigger-map.md
|
||||
│
|
||||
├── C-Scenarios/
|
||||
│ ├── 01-welcome-screen/
|
||||
│ │ └── Frontend/
|
||||
│ │ └── specifications.md
|
||||
│ └── flows/
|
||||
│ └── user-flow.excalidraw
|
||||
│
|
||||
├── D-Design-System/ ← Touch Point 3
|
||||
│ ├── 02-Foundation/
|
||||
│ │ ├── Colors/tokens.json
|
||||
│ │ └── Typography/tokens.json
|
||||
│ └── 03-Atomic-Components/
|
||||
│ ├── Buttons/Button-Primary.md
|
||||
│ └── Inputs/Input-Text.md
|
||||
│
|
||||
├── deliveries/ ← Touch Point 2
|
||||
│ ├── DD-001-login-onboarding.yaml
|
||||
│ ├── DD-002-morning-dog-care.yaml
|
||||
│ └── DD-001-handoff-log.md
|
||||
│
|
||||
├── test-scenarios/ ← Touch Point 2
|
||||
│ ├── TS-001-login-onboarding.yaml
|
||||
│ └── TS-002-morning-dog-care.yaml
|
||||
│
|
||||
├── test-reports/ ← Touch Point 3
|
||||
│ ├── TR-001-2024-12-09.md
|
||||
│ └── TR-001-2024-12-15.md
|
||||
│
|
||||
├── issues/ ← Touch Point 3
|
||||
│ ├── ISS-001-button-color.md
|
||||
│ └── ISS-002-transition-speed.md
|
||||
│
|
||||
└── E-Architecture/ ← BMad creates this
|
||||
├── architecture.md
|
||||
└── epics/
|
||||
├── epic-1.1-auth-infrastructure.md
|
||||
└── epic-1.2-welcome-login.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## For WDS Users
|
||||
|
||||
### Phase 3: Define Platform Requirements
|
||||
|
||||
**Create:** `A-Project-Brief/platform-requirements.yaml`
|
||||
|
||||
```yaml
|
||||
platform:
|
||||
frontend:
|
||||
framework: "react_native"
|
||||
backend:
|
||||
framework: "supabase"
|
||||
|
||||
integrations:
|
||||
- name: "supabase_auth"
|
||||
required: true
|
||||
|
||||
constraints:
|
||||
- "Must work offline"
|
||||
- "Must be accessible"
|
||||
```
|
||||
|
||||
**This overrides BMad's tech stack decisions!**
|
||||
|
||||
**Template:** `templates/platform-requirements.template.yaml`
|
||||
|
||||
---
|
||||
|
||||
### Phase 4-5: Design Complete Testable Flows
|
||||
|
||||
**Strategic Approach:**
|
||||
Design until you have a **complete testable user flow** that:
|
||||
- ✅ Delivers value to the business
|
||||
- ✅ Delivers value to the end user
|
||||
- ✅ Can be tested for real feedback
|
||||
- ✅ Is ready to hand off for development
|
||||
|
||||
**You're NOT designing everything at once!** You're designing the minimum complete flow that can be tested and validated.
|
||||
|
||||
**Phase 4: UX Design**
|
||||
- Design scenarios for ONE complete user flow
|
||||
- Create specifications for each scenario
|
||||
- Ensure the flow delivers measurable value
|
||||
- Verify it's testable end-to-end
|
||||
|
||||
**Phase 5: Design System**
|
||||
- Define components needed for THIS flow
|
||||
- Create design tokens for these components
|
||||
- Document usage guidelines
|
||||
- Build only what's needed for this delivery
|
||||
|
||||
**Goal:** Get to development and testing as fast as possible with a complete, valuable flow
|
||||
|
||||
```
|
||||
D-Design-System/
|
||||
├── 02-Foundation/
|
||||
│ ├── Colors/tokens.json
|
||||
│ ├── Typography/tokens.json
|
||||
│ └── Spacing/tokens.json
|
||||
└── 03-Atomic-Components/
|
||||
├── Buttons/
|
||||
├── Inputs/
|
||||
└── Cards/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 6: Design Deliveries (Iterative Handoffs)
|
||||
|
||||
**You can hand off as soon as you have ONE complete testable flow!**
|
||||
|
||||
**Iterative Approach:**
|
||||
|
||||
**First Delivery (Fastest Path to Testing):**
|
||||
1. **Design ONE complete user flow** (Phases 4-5)
|
||||
- Example: Login & Onboarding
|
||||
- Delivers value: Users can access the app
|
||||
- Testable: Complete flow from app open to dashboard
|
||||
|
||||
2. **Create Design Delivery** for this flow
|
||||
- `deliveries/DD-001-login-onboarding.yaml`
|
||||
|
||||
3. **Create Test Scenario**
|
||||
- `test-scenarios/TS-001-login-onboarding.yaml`
|
||||
|
||||
4. **Handoff Dialog** with BMad Architect (~20-30 min)
|
||||
- Walk through this delivery
|
||||
- Answer questions
|
||||
- Agree on implementation approach
|
||||
|
||||
5. **Hand off to BMad** → Development starts!
|
||||
|
||||
**While BMad builds DD-001, you design DD-002:**
|
||||
- Continue with next complete flow
|
||||
- Example: Morning Dog Care
|
||||
- Hand off when ready
|
||||
- Parallel work = faster delivery
|
||||
|
||||
**Benefits:**
|
||||
- ✅ Get to testing faster (weeks, not months)
|
||||
- ✅ Validate design with real users early
|
||||
- ✅ Learn and iterate before designing everything
|
||||
- ✅ Parallel work (design + dev happening simultaneously)
|
||||
- ✅ Deliver value incrementally
|
||||
|
||||
**Templates:**
|
||||
- `templates/design-delivery.template.yaml`
|
||||
- `templates/test-scenario.template.yaml`
|
||||
|
||||
---
|
||||
|
||||
### Phase 7: Testing (After BMad Implementation)
|
||||
|
||||
**Wait for BMad notification:**
|
||||
```
|
||||
"Feature complete: DD-001 Login & Onboarding
|
||||
Ready for designer validation"
|
||||
```
|
||||
|
||||
**Then:**
|
||||
1. **Run test scenarios**
|
||||
2. **Create issues** if problems found
|
||||
3. **Wait for fixes**
|
||||
4. **Retest** until approved
|
||||
5. **Sign off** when quality meets standards
|
||||
|
||||
---
|
||||
|
||||
## For BMad Users
|
||||
|
||||
### Detect WDS Artifacts
|
||||
|
||||
**Check for WDS:**
|
||||
|
||||
```bash
|
||||
# Priority 1: Design Deliveries
|
||||
if [ -d "deliveries" ]; then
|
||||
echo "✓ WDS Design Deliveries found"
|
||||
mode="wds-enhanced"
|
||||
|
||||
# Priority 2: Platform Requirements
|
||||
elif [ -f "A-Project-Brief/platform-requirements.yaml" ]; then
|
||||
echo "✓ WDS Platform Requirements found"
|
||||
mode="wds-basic"
|
||||
|
||||
# Priority 3: Traditional
|
||||
else
|
||||
echo "⚠ No WDS artifacts"
|
||||
mode="traditional"
|
||||
fi
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Read Platform Requirements
|
||||
|
||||
**Load tech stack decisions:**
|
||||
|
||||
```python
|
||||
import yaml
|
||||
|
||||
with open('A-Project-Brief/platform-requirements.yaml') as f:
|
||||
reqs = yaml.safe_load(f)
|
||||
|
||||
frontend = reqs['platform']['frontend']['framework']
|
||||
backend = reqs['platform']['backend']['framework']
|
||||
|
||||
print(f"Tech Stack: {frontend} + {backend}")
|
||||
```
|
||||
|
||||
**Respect these choices - designer already decided**
|
||||
|
||||
---
|
||||
|
||||
### Read Design Deliveries
|
||||
|
||||
**Load design work:**
|
||||
|
||||
```python
|
||||
import yaml
|
||||
|
||||
with open('deliveries/DD-001-login-onboarding.yaml') as f:
|
||||
delivery = yaml.safe_load(f)
|
||||
|
||||
name = delivery['delivery']['name']
|
||||
scenarios = delivery['design_artifacts']['scenarios']
|
||||
|
||||
print(f"Delivery: {name}")
|
||||
print(f"Scenarios: {len(scenarios)}")
|
||||
```
|
||||
|
||||
**Break down into development epics**
|
||||
|
||||
---
|
||||
|
||||
### Participate in Handoff Dialog
|
||||
|
||||
**When Design Delivery is ready:**
|
||||
|
||||
1. **Receive handoff** from WDS UX Expert
|
||||
2. **Ask clarifying questions**
|
||||
3. **Propose epic breakdown**
|
||||
4. **Commit to implementation**
|
||||
5. **Document handoff**
|
||||
|
||||
**Protocol:** [handoff-protocol.md](handoff-protocol.md)
|
||||
|
||||
---
|
||||
|
||||
### Notify Designer When Ready
|
||||
|
||||
**After implementation:**
|
||||
|
||||
```
|
||||
"Feature complete: DD-001 Login & Onboarding
|
||||
|
||||
Implemented:
|
||||
✓ All 4 scenarios
|
||||
✓ All error states
|
||||
✓ All edge cases
|
||||
✓ Design system components
|
||||
|
||||
Build: v0.1.0-beta.1
|
||||
Ready for designer validation.
|
||||
Test scenario: test-scenarios/TS-001.yaml"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Receive Issues & Fix
|
||||
|
||||
**Designer finds issues:**
|
||||
|
||||
```markdown
|
||||
# Issue: Button Color Incorrect
|
||||
|
||||
**Severity:** High
|
||||
**Expected:** #2563EB
|
||||
**Actual:** #3B82F6
|
||||
**Design Ref:** D-Design-System/.../Button-Primary.md
|
||||
```
|
||||
|
||||
**Fix and notify:**
|
||||
|
||||
```
|
||||
"Issue ISS-001 fixed.
|
||||
Build: v0.1.0-beta.2
|
||||
Ready for retest."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Benefits
|
||||
|
||||
### For Designers
|
||||
|
||||
- ✅ Control over tech stack decisions (Touch Point 1)
|
||||
- ✅ Complete design work before handoff (Phases 4-5)
|
||||
- ✅ Single clean handoff (Touch Point 2)
|
||||
- ✅ Validate implementation matches design (Touch Point 3)
|
||||
- ✅ Design integrity maintained throughout
|
||||
|
||||
### For Developers
|
||||
|
||||
- ✅ Clear tech stack from the start (Touch Point 1)
|
||||
- ✅ Complete design package at once (Touch Point 2)
|
||||
- ✅ All requirements and specifications provided
|
||||
- ✅ Design system components fully defined
|
||||
- ✅ Testing guidance included
|
||||
- ✅ Designer validation ensures quality (Touch Point 3)
|
||||
|
||||
### For Teams
|
||||
|
||||
- ✅ 3 clean integration points (not 7!)
|
||||
- ✅ Seamless design-to-development workflow
|
||||
- ✅ Reduced miscommunication
|
||||
- ✅ Faster iteration cycles
|
||||
- ✅ Higher quality products
|
||||
- ✅ Complete traceability
|
||||
|
||||
---
|
||||
|
||||
## Graceful Fallback
|
||||
|
||||
### BMad Without WDS
|
||||
|
||||
**BMad works standalone:**
|
||||
|
||||
```bash
|
||||
if [ ! -d "deliveries" ]; then
|
||||
echo "No WDS artifacts - using traditional workflow"
|
||||
# Gather requirements
|
||||
# Design architecture
|
||||
# Implement features
|
||||
fi
|
||||
```
|
||||
|
||||
**No WDS required - BMad is independent**
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
### For WDS Projects
|
||||
|
||||
**Phase 1-2:** Discovery (Project Brief, Trigger Map)
|
||||
**Phase 3:** Platform Requirements → **Touch Point 1**
|
||||
|
||||
**Then iterate:**
|
||||
**Phase 4-5:** Design ONE complete testable flow
|
||||
**Phase 6:** Create delivery and handoff → **Touch Point 2**
|
||||
**Phase 7:** Wait for implementation, then validate → **Touch Point 3**
|
||||
|
||||
**Repeat Phases 4-7 for each flow:**
|
||||
- While BMad builds flow 1, design flow 2
|
||||
- Parallel work = faster delivery
|
||||
- Test and learn early
|
||||
|
||||
### For BMad Projects
|
||||
|
||||
**Check for Touch Point 1:** Platform Requirements
|
||||
- If found: Read and respect tech stack
|
||||
- If not found: Make your own decisions
|
||||
|
||||
**Wait for Touch Point 2:** Design Deliveries
|
||||
- Receive complete design package
|
||||
- Break down into dev epics
|
||||
- Implement features
|
||||
|
||||
**Trigger Touch Point 3:** Request validation
|
||||
- Notify designer when complete
|
||||
- Fix issues as needed
|
||||
- Iterate until sign-off
|
||||
|
||||
---
|
||||
|
||||
## Resources
|
||||
|
||||
### Specifications
|
||||
|
||||
- [Design Delivery Spec](design-delivery-spec.md)
|
||||
- [Platform Requirements Spec](platform-requirements-spec.md)
|
||||
- [Handoff Protocol](handoff-protocol.md)
|
||||
|
||||
### Templates
|
||||
|
||||
- `templates/design-delivery.template.yaml`
|
||||
- `templates/platform-requirements.template.yaml`
|
||||
- `templates/test-scenario.template.yaml`
|
||||
|
||||
### Examples
|
||||
|
||||
- See `WDS-V6-CONVERSION-ROADMAP.md` for integration details
|
||||
- See `workflows/` for workflow documentation
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
### The 3 Touch Points
|
||||
|
||||
1. **Platform Requirements** (WDS Phase 3 → BMad)
|
||||
- WDS overrides BMad's tech stack decisions
|
||||
- Designer defines technical foundation
|
||||
|
||||
2. **Design Deliveries** (WDS Phase 6 → BMad)
|
||||
- Complete design package handed off at once
|
||||
- Includes all scenarios, components, test scenarios
|
||||
- Single handoff with multi-agent dialog
|
||||
|
||||
3. **Designer Validation** (BMad Phase 3 → WDS Phase 7)
|
||||
- BMad requests validation when complete
|
||||
- Designer tests and creates issues if needed
|
||||
- Iterates until sign-off
|
||||
|
||||
### Why 3 Touch Points?
|
||||
|
||||
**Cleaner:** Not 7 continuous integration points
|
||||
**Simpler:** Clear separation of concerns
|
||||
**Realistic:** Matches how teams actually work
|
||||
**Iterative:** Design → Handoff → Build → Test → Repeat
|
||||
**Fast:** Get to testing in weeks, not months
|
||||
**Quality:** Designer validates before ship
|
||||
|
||||
---
|
||||
|
||||
**This integration creates a seamless design-to-development workflow with 3 clean touch points that respect both design vision and technical excellence!** 🔗✨
|
||||
|
|
@ -0,0 +1,549 @@
|
|||
# WDS Platform Requirements Specification
|
||||
|
||||
**For BMad Agents: How to read and interpret WDS Platform Requirements**
|
||||
|
||||
---
|
||||
|
||||
## What are Platform Requirements?
|
||||
|
||||
Platform Requirements define the technical foundation for the product:
|
||||
- Tech stack choices (frontend, backend, database)
|
||||
- Required integrations
|
||||
- Infrastructure constraints
|
||||
- Deployment strategy
|
||||
|
||||
**Purpose:** Provide technical foundation before detailed design begins
|
||||
|
||||
**Location:** `A-Project-Brief/platform-requirements.yaml`
|
||||
|
||||
**Created by:** WDS Analyst (Phase 3)
|
||||
**Consumed by:** BMad Architect
|
||||
|
||||
---
|
||||
|
||||
## File Format
|
||||
|
||||
```yaml
|
||||
# Platform Requirements
|
||||
# Created by: WDS Phase 3
|
||||
# Consumed by: BMad Architecture Phase
|
||||
|
||||
project:
|
||||
name: "Dog Week"
|
||||
type: "mobile_app" # mobile_app | web_app | desktop_app | api
|
||||
wds_version: "6.0"
|
||||
created_at: "2024-12-09T10:00:00Z"
|
||||
|
||||
platform:
|
||||
frontend:
|
||||
framework: "react_native"
|
||||
version: "0.72"
|
||||
state_management: "zustand"
|
||||
navigation: "react_navigation"
|
||||
styling: "tailwind"
|
||||
ui_library: "shadcn" # optional
|
||||
|
||||
backend:
|
||||
framework: "supabase"
|
||||
version: "2.x"
|
||||
auth: "supabase_auth"
|
||||
database: "postgresql"
|
||||
storage: "supabase_storage"
|
||||
api: "rest" # rest | graphql | grpc
|
||||
|
||||
database:
|
||||
type: "postgresql"
|
||||
version: "15"
|
||||
orm: "prisma" # optional
|
||||
|
||||
deployment:
|
||||
frontend: "expo_eas"
|
||||
backend: "supabase_cloud"
|
||||
ci_cd: "github_actions"
|
||||
hosting: "vercel" # if web app
|
||||
|
||||
integrations:
|
||||
- name: "push_notifications"
|
||||
provider: "expo"
|
||||
required: true
|
||||
purpose: "Task reminders and family updates"
|
||||
|
||||
- name: "image_upload"
|
||||
provider: "cloudinary"
|
||||
required: false
|
||||
purpose: "Dog photos and user avatars"
|
||||
|
||||
- name: "analytics"
|
||||
provider: "posthog"
|
||||
required: false
|
||||
purpose: "User behavior tracking"
|
||||
|
||||
constraints:
|
||||
- "Must work offline (core features)"
|
||||
- "Must support iOS 14+ and Android 10+"
|
||||
- "Must be accessible (WCAG 2.1 AA)"
|
||||
- "Must handle slow networks gracefully"
|
||||
- "Must support family sharing (multi-user)"
|
||||
- "Must sync in real-time across devices"
|
||||
|
||||
performance_requirements:
|
||||
- "App launch < 2 seconds"
|
||||
- "Screen transitions < 300ms"
|
||||
- "API response time < 500ms"
|
||||
- "Offline mode must work for 7 days"
|
||||
|
||||
security_requirements:
|
||||
- "End-to-end encryption for family data"
|
||||
- "Secure password storage (bcrypt)"
|
||||
- "OAuth 2.0 for third-party auth"
|
||||
- "GDPR compliant data handling"
|
||||
|
||||
wds_metadata:
|
||||
project_brief: "A-Project-Brief/project-brief.md"
|
||||
trigger_map: "B-Trigger-Map/trigger-map.md"
|
||||
scenarios: "C-Scenarios/"
|
||||
design_system: "D-Design-System/"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## How to Read Platform Requirements
|
||||
|
||||
### Step 1: Check if File Exists
|
||||
|
||||
```bash
|
||||
if [ -f "A-Project-Brief/platform-requirements.yaml" ]; then
|
||||
echo "✓ WDS Platform Requirements found!"
|
||||
else
|
||||
echo "⚠ No platform requirements - using traditional workflow"
|
||||
fi
|
||||
```
|
||||
|
||||
### Step 2: Load Requirements
|
||||
|
||||
```python
|
||||
import yaml
|
||||
|
||||
with open('A-Project-Brief/platform-requirements.yaml') as f:
|
||||
reqs = yaml.safe_load(f)
|
||||
|
||||
project_name = reqs['project']['name']
|
||||
project_type = reqs['project']['type']
|
||||
|
||||
print(f"Project: {project_name}")
|
||||
print(f"Type: {project_type}")
|
||||
```
|
||||
|
||||
### Step 3: Extract Tech Stack
|
||||
|
||||
```python
|
||||
# Frontend
|
||||
frontend = reqs['platform']['frontend']
|
||||
print(f"Frontend Framework: {frontend['framework']} v{frontend['version']}")
|
||||
print(f"State Management: {frontend['state_management']}")
|
||||
print(f"Navigation: {frontend['navigation']}")
|
||||
print(f"Styling: {frontend['styling']}")
|
||||
|
||||
# Backend
|
||||
backend = reqs['platform']['backend']
|
||||
print(f"Backend Framework: {backend['framework']} v{backend['version']}")
|
||||
print(f"Auth: {backend['auth']}")
|
||||
print(f"Database: {backend['database']}")
|
||||
print(f"Storage: {backend['storage']}")
|
||||
```
|
||||
|
||||
### Step 4: Extract Integrations
|
||||
|
||||
```python
|
||||
integrations = reqs['integrations']
|
||||
|
||||
required_integrations = [i for i in integrations if i['required']]
|
||||
optional_integrations = [i for i in integrations if not i['required']]
|
||||
|
||||
print("Required Integrations:")
|
||||
for integration in required_integrations:
|
||||
print(f" - {integration['name']} ({integration['provider']})")
|
||||
print(f" Purpose: {integration['purpose']}")
|
||||
|
||||
print("\nOptional Integrations:")
|
||||
for integration in optional_integrations:
|
||||
print(f" - {integration['name']} ({integration['provider']})")
|
||||
print(f" Purpose: {integration['purpose']}")
|
||||
```
|
||||
|
||||
### Step 5: Extract Constraints
|
||||
|
||||
```python
|
||||
constraints = reqs['constraints']
|
||||
|
||||
print("Constraints:")
|
||||
for constraint in constraints:
|
||||
print(f" - {constraint}")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Using Platform Requirements in Architecture
|
||||
|
||||
### Respect Designer Decisions
|
||||
|
||||
**The designer (with stakeholders) has already decided:**
|
||||
- ✅ Tech stack
|
||||
- ✅ Integrations
|
||||
- ✅ Constraints
|
||||
- ✅ Performance targets
|
||||
- ✅ Security requirements
|
||||
|
||||
**Your job:** Design architecture that fits these choices
|
||||
|
||||
**NOT your job:** Second-guess or change these decisions
|
||||
|
||||
### Exception: Technical Concerns
|
||||
|
||||
If you see a problem, flag it clearly:
|
||||
|
||||
```
|
||||
⚠️ TECHNICAL CONCERN
|
||||
|
||||
Platform Requirements specify:
|
||||
- Frontend: React Native
|
||||
- Backend: Supabase
|
||||
- Integration: Firebase Cloud Messaging (FCM)
|
||||
|
||||
ISSUE: Supabase has built-in push notifications via Supabase Realtime.
|
||||
Using FCM adds unnecessary complexity.
|
||||
|
||||
RECOMMENDATION: Discuss with designer whether to:
|
||||
1. Use Supabase Realtime instead of FCM
|
||||
2. Keep FCM if there's a specific reason
|
||||
|
||||
Do NOT proceed until resolved.
|
||||
```
|
||||
|
||||
### Architecture Design
|
||||
|
||||
```markdown
|
||||
# Architecture Design: Dog Week
|
||||
|
||||
## Tech Stack (from Platform Requirements)
|
||||
|
||||
### Frontend
|
||||
- Framework: React Native 0.72
|
||||
- State: Zustand
|
||||
- Navigation: React Navigation
|
||||
- Styling: Tailwind CSS
|
||||
|
||||
### Backend
|
||||
- Framework: Supabase 2.x
|
||||
- Auth: Supabase Auth
|
||||
- Database: PostgreSQL 15
|
||||
- Storage: Supabase Storage
|
||||
|
||||
### Deployment
|
||||
- Frontend: Expo EAS
|
||||
- Backend: Supabase Cloud
|
||||
- CI/CD: GitHub Actions
|
||||
|
||||
## Architecture Decisions
|
||||
|
||||
Based on platform requirements, I will:
|
||||
|
||||
1. **Use Supabase as BaaS**
|
||||
- Handles auth, database, storage, real-time
|
||||
- Reduces backend complexity
|
||||
- Matches designer's choice
|
||||
|
||||
2. **Implement Offline-First Architecture**
|
||||
- Constraint: "Must work offline (core features)"
|
||||
- Use React Native AsyncStorage for local cache
|
||||
- Sync with Supabase when online
|
||||
|
||||
3. **Real-Time Sync**
|
||||
- Constraint: "Must sync in real-time across devices"
|
||||
- Use Supabase Realtime subscriptions
|
||||
- Conflict resolution: last-write-wins
|
||||
|
||||
4. **Performance Optimization**
|
||||
- Requirement: "App launch < 2 seconds"
|
||||
- Lazy load screens
|
||||
- Cache critical data locally
|
||||
- Optimize bundle size
|
||||
|
||||
[Continue with detailed architecture...]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration with Design Deliveries
|
||||
|
||||
### Platform Requirements Come First
|
||||
|
||||
```
|
||||
Phase 3: Platform Requirements defined
|
||||
↓
|
||||
Phase 4: Design Deliveries created
|
||||
↓
|
||||
Design Deliveries reference Platform Requirements
|
||||
```
|
||||
|
||||
### Example
|
||||
|
||||
**Platform Requirements:**
|
||||
```yaml
|
||||
platform:
|
||||
frontend:
|
||||
framework: "react_native"
|
||||
backend:
|
||||
framework: "supabase"
|
||||
```
|
||||
|
||||
**Design Delivery DD-001:**
|
||||
```yaml
|
||||
technical_requirements:
|
||||
platform:
|
||||
frontend: "react_native" # Matches platform requirements
|
||||
backend: "supabase" # Matches platform requirements
|
||||
```
|
||||
|
||||
**Your job:** Ensure consistency between platform requirements and design deliveries
|
||||
|
||||
---
|
||||
|
||||
## Constraints and Requirements
|
||||
|
||||
### Types of Constraints
|
||||
|
||||
**Technical Constraints:**
|
||||
```yaml
|
||||
constraints:
|
||||
- "Must work offline (core features)"
|
||||
- "Must support iOS 14+ and Android 10+"
|
||||
```
|
||||
|
||||
**Business Constraints:**
|
||||
```yaml
|
||||
constraints:
|
||||
- "Must launch in 3 months"
|
||||
- "Must support 10,000 concurrent users"
|
||||
```
|
||||
|
||||
**Regulatory Constraints:**
|
||||
```yaml
|
||||
constraints:
|
||||
- "Must be GDPR compliant"
|
||||
- "Must be WCAG 2.1 AA accessible"
|
||||
```
|
||||
|
||||
### Handling Constraints
|
||||
|
||||
**Each constraint affects architecture:**
|
||||
|
||||
```markdown
|
||||
Constraint: "Must work offline (core features)"
|
||||
|
||||
Architecture Impact:
|
||||
- Implement local data cache
|
||||
- Sync strategy when online
|
||||
- Conflict resolution
|
||||
- Offline UI indicators
|
||||
|
||||
Implementation:
|
||||
- Use AsyncStorage for local cache
|
||||
- Supabase Realtime for sync
|
||||
- Optimistic UI updates
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Performance Requirements
|
||||
|
||||
### Understanding Performance Targets
|
||||
|
||||
```yaml
|
||||
performance_requirements:
|
||||
- "App launch < 2 seconds"
|
||||
- "Screen transitions < 300ms"
|
||||
- "API response time < 500ms"
|
||||
```
|
||||
|
||||
### Architecture Decisions
|
||||
|
||||
```markdown
|
||||
Performance Requirement: "App launch < 2 seconds"
|
||||
|
||||
Architecture Decisions:
|
||||
1. Lazy load non-critical screens
|
||||
2. Cache authentication state
|
||||
3. Preload critical data
|
||||
4. Optimize bundle size
|
||||
5. Use code splitting
|
||||
|
||||
Measurement:
|
||||
- Add performance monitoring
|
||||
- Track launch time in analytics
|
||||
- Set up alerts if > 2 seconds
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Security Requirements
|
||||
|
||||
### Understanding Security Needs
|
||||
|
||||
```yaml
|
||||
security_requirements:
|
||||
- "End-to-end encryption for family data"
|
||||
- "Secure password storage (bcrypt)"
|
||||
- "OAuth 2.0 for third-party auth"
|
||||
```
|
||||
|
||||
### Architecture Decisions
|
||||
|
||||
```markdown
|
||||
Security Requirement: "End-to-end encryption for family data"
|
||||
|
||||
Architecture Decisions:
|
||||
1. Generate encryption keys per family
|
||||
2. Store keys securely (device keychain)
|
||||
3. Encrypt data before sending to server
|
||||
4. Decrypt data on device only
|
||||
|
||||
Implementation:
|
||||
- Use expo-crypto for encryption
|
||||
- Use expo-secure-store for key storage
|
||||
- Implement key rotation strategy
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Deployment Strategy
|
||||
|
||||
### Understanding Deployment
|
||||
|
||||
```yaml
|
||||
deployment:
|
||||
frontend: "expo_eas"
|
||||
backend: "supabase_cloud"
|
||||
ci_cd: "github_actions"
|
||||
```
|
||||
|
||||
### Architecture Decisions
|
||||
|
||||
```markdown
|
||||
Deployment: Expo EAS + Supabase Cloud + GitHub Actions
|
||||
|
||||
CI/CD Pipeline:
|
||||
1. Push to GitHub
|
||||
2. GitHub Actions runs tests
|
||||
3. Build app with Expo EAS
|
||||
4. Deploy backend to Supabase
|
||||
5. Submit to App Store / Play Store
|
||||
|
||||
Environments:
|
||||
- Development: dev.supabase.co
|
||||
- Staging: staging.supabase.co
|
||||
- Production: prod.supabase.co
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## WDS Metadata
|
||||
|
||||
### Understanding Metadata
|
||||
|
||||
```yaml
|
||||
wds_metadata:
|
||||
project_brief: "A-Project-Brief/project-brief.md"
|
||||
trigger_map: "B-Trigger-Map/trigger-map.md"
|
||||
scenarios: "C-Scenarios/"
|
||||
design_system: "D-Design-System/"
|
||||
```
|
||||
|
||||
**This tells you where to find additional context:**
|
||||
|
||||
```python
|
||||
# Read project brief for business context
|
||||
with open('A-Project-Brief/project-brief.md') as f:
|
||||
brief = f.read()
|
||||
# Understand project vision, goals, stakeholders
|
||||
|
||||
# Read trigger map for user needs
|
||||
with open('B-Trigger-Map/trigger-map.md') as f:
|
||||
triggers = f.read()
|
||||
# Understand user trigger moments and needs
|
||||
|
||||
# Check scenarios directory
|
||||
scenarios = os.listdir('C-Scenarios/')
|
||||
print(f"Found {len(scenarios)} scenarios")
|
||||
|
||||
# Check design system
|
||||
ds_exists = os.path.exists('D-Design-System/')
|
||||
print(f"Design system: {'✓ Available' if ds_exists else '⏳ Not yet'}")
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Fallback: No Platform Requirements
|
||||
|
||||
If platform requirements don't exist:
|
||||
|
||||
### Option 1: Traditional BMad Workflow
|
||||
|
||||
```bash
|
||||
if [ ! -f "A-Project-Brief/platform-requirements.yaml" ]; then
|
||||
echo "⚠ No WDS Platform Requirements"
|
||||
echo " Using traditional BMad workflow"
|
||||
echo " Gather requirements and make tech stack decisions"
|
||||
fi
|
||||
```
|
||||
|
||||
### Option 2: Wait for WDS
|
||||
|
||||
```bash
|
||||
if [ -f "A-Project-Brief/project-brief.md" ]; then
|
||||
echo "✓ WDS Project Brief found"
|
||||
echo " WDS is being used, but Phase 3 not complete yet"
|
||||
echo " Wait for platform requirements to be defined"
|
||||
fi
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### File Location
|
||||
|
||||
```
|
||||
A-Project-Brief/
|
||||
├── project-brief.md
|
||||
└── platform-requirements.yaml ← This file
|
||||
```
|
||||
|
||||
### Key Fields
|
||||
|
||||
```yaml
|
||||
project.name # Project name
|
||||
project.type # mobile_app | web_app | desktop_app
|
||||
platform.frontend.framework # Frontend framework
|
||||
platform.backend.framework # Backend framework
|
||||
integrations # Required/optional integrations
|
||||
constraints # Technical/business/regulatory
|
||||
performance_requirements # Performance targets
|
||||
security_requirements # Security needs
|
||||
deployment # Deployment strategy
|
||||
wds_metadata # Links to other WDS artifacts
|
||||
```
|
||||
|
||||
### Reading Order
|
||||
|
||||
1. **Project info** → Understand what you're building
|
||||
2. **Tech stack** → Understand technology choices
|
||||
3. **Integrations** → Understand external dependencies
|
||||
4. **Constraints** → Understand limitations
|
||||
5. **Performance** → Understand targets
|
||||
6. **Security** → Understand security needs
|
||||
7. **Deployment** → Understand deployment strategy
|
||||
|
||||
---
|
||||
|
||||
**This specification enables BMad to respect and build upon WDS platform decisions!** ⚙️✨
|
||||
|
|
@ -0,0 +1,80 @@
|
|||
# About WDS
|
||||
|
||||
**What is Whiteport Design Studio?**
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
**Whiteport Design Studio (WDS)** is a design methodology that makes designers indispensable in the AI era.
|
||||
|
||||
**The paradigm shift:**
|
||||
- The design becomes the specification
|
||||
- The specification becomes the product
|
||||
- The code is just the printout
|
||||
|
||||
---
|
||||
|
||||
## Who Created It?
|
||||
|
||||
**Mårten Angner** - UX designer and founder of Whiteport, a design and development agency in Sweden.
|
||||
|
||||
After years of working with AI tools, Mårten observed that traditional design handoffs were breaking down. Designers would create mockups, hand them off to developers, and watch their intent get lost in translation.
|
||||
|
||||
WDS solves this by preserving design thinking through AI-ready specifications.
|
||||
|
||||
---
|
||||
|
||||
## Why It Exists
|
||||
|
||||
**The problem:** AI can generate code perfectly, but only if you can clearly define what you want. Unclear specifications lead to AI hallucinations and failed projects.
|
||||
|
||||
**The solution:** WDS teaches designers to create why-based specifications that capture intent, not just appearance.
|
||||
|
||||
**The result:** Designers become 5x more productive while maintaining creative control.
|
||||
|
||||
---
|
||||
|
||||
## How It Works
|
||||
|
||||
WDS provides:
|
||||
- A systematic workflow from product brief to AI-ready specifications
|
||||
- Why-based specifications (WHAT + WHY + WHAT NOT TO DO)
|
||||
- AI agents specifically tailored for design work
|
||||
- Integration with BMad Method for seamless design-to-development handoff
|
||||
|
||||
---
|
||||
|
||||
## Free and Open-Source
|
||||
|
||||
WDS is completely free and open-source:
|
||||
- No cost barriers or subscriptions
|
||||
- AI agents included
|
||||
- Community-driven development
|
||||
- Plugin module for BMad Method
|
||||
|
||||
**Mission:** Give designers everywhere the tools to thrive in the AI era.
|
||||
|
||||
---
|
||||
|
||||
## Real-World Proof
|
||||
|
||||
**Dog Week project:**
|
||||
- Traditional approach: 26 weeks, mediocre result
|
||||
- WDS approach: 5 weeks, exceptional result
|
||||
- **5x speed increase with better quality**
|
||||
|
||||
---
|
||||
|
||||
## Learn More
|
||||
|
||||
**[Continue to About the Course →](00-about-the-course.md)**
|
||||
|
||||
Or return to the overview:
|
||||
|
||||
**[← Back to Getting Started Overview](00-getting-started-overview.md)**
|
||||
|
||||
---
|
||||
|
||||
**Created by Mårten Angner and the Whiteport team**
|
||||
**Free and open-source for designers everywhere**
|
||||
|
|
@ -0,0 +1,108 @@
|
|||
# Where to Go Next
|
||||
|
||||
**You've installed WDS and completed the quick start. Now what?**
|
||||
|
||||
---
|
||||
|
||||
## Choose Your Path
|
||||
|
||||
### 🎓 Learn the Concepts (Recommended First)
|
||||
|
||||
**[Tutorial](../01-tutorial/00-TUTORIAL-GUIDE.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
|
||||
|
||||
**Best for:** Understanding the "why" behind WDS
|
||||
|
||||
**Time:** 1-2 hours (video series)
|
||||
|
||||
---
|
||||
|
||||
### 🚀 Start Your Project
|
||||
|
||||
**[Workflows Guide](../WDS-WORKFLOWS-GUIDE.md)**
|
||||
|
||||
Step-by-step workflows for:
|
||||
- Phase 1: Trigger Mapping
|
||||
- Phase 2: Information Architecture
|
||||
- Phase 3: Interaction Design
|
||||
- Phase 4: UX SpecificationsPleas
|
||||
|
||||
**Best for:** Hands-on learning with a real project
|
||||
|
||||
**Time:** Ongoing (project-based)
|
||||
|
||||
---
|
||||
|
||||
### 📚 Reference Documentation
|
||||
|
||||
**[Modular Architecture](../workflows/4-ux-design/modular-architecture/00-MODULAR-ARCHITECTURE-GUIDE.md)**
|
||||
|
||||
Technical details on:
|
||||
- Three-tier file structure
|
||||
- Content placement rules
|
||||
- Component decomposition
|
||||
- Storyboard integration
|
||||
|
||||
**Best for:** Looking up specific techniques
|
||||
|
||||
**Time:** As needed (reference)
|
||||
|
||||
---
|
||||
|
||||
## Recommended Learning Path
|
||||
|
||||
```
|
||||
1. Quick Start (5 min) ✅ You are here
|
||||
↓
|
||||
2. Tutorial (1-2 hours)
|
||||
Watch videos, understand concepts
|
||||
↓
|
||||
3. Your First Project (ongoing)
|
||||
Apply WDS to a real project
|
||||
↓
|
||||
4. Reference Docs (as needed)
|
||||
Look up specific techniques
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Community & Support
|
||||
|
||||
### Discord
|
||||
Join the WDS community for:
|
||||
- Questions and answers
|
||||
- Project feedback
|
||||
- Feature discussions
|
||||
|
||||
### GitHub
|
||||
- Report issues
|
||||
- Request features
|
||||
- Contribute
|
||||
|
||||
### YouTube
|
||||
- Video tutorials
|
||||
- Walkthroughs
|
||||
- Case studies
|
||||
|
||||
---
|
||||
|
||||
## Quick Links
|
||||
|
||||
- [Tutorial](../01-tutorial/00-TUTORIAL-GUIDE.md)
|
||||
- [Workflows](../WDS-WORKFLOWS-GUIDE.md)
|
||||
- [Modular Architecture](../workflows/4-ux-design/modular-architecture/00-MODULAR-ARCHITECTURE-GUIDE.md)
|
||||
- [Why-Based Specifications](../workflows/4-ux-design/WHY-BASED-SPECIFICATIONS.md)
|
||||
|
||||
---
|
||||
|
||||
**Ready to dive deeper? Start with the [Tutorial](../01-tutorial/00-TUTORIAL-GUIDE.md)!**
|
||||
|
||||
---
|
||||
|
||||
[← Back to Quick Start](quick-start.md)
|
||||
|
|
@ -0,0 +1,91 @@
|
|||
# Whiteport Design Studio (WDS) Module
|
||||
|
||||
**Design-focused methodology for UX/UI product development**
|
||||
|
||||
## Overview
|
||||
|
||||
Whiteport Design Studio provides a complete design workflow from product exploration through detailed component specifications. WDS creates the design artifacts that feed into development modules like BMad Method (BMM).
|
||||
|
||||
## Module Structure
|
||||
|
||||
```
|
||||
wds/
|
||||
├── _module-installer/ # Installation configuration
|
||||
├── agents/ # WDS specialized agents (Norse Pantheon)
|
||||
│ ├── saga-analyst.agent.yaml # Saga-Analyst - Business & Product Analyst
|
||||
│ ├── freyja-pm.agent.yaml # Freyja-PM - Product Manager
|
||||
│ └── baldr-ux.agent.yaml # Baldr-UX - UX/UI Designer
|
||||
├── workflows/ # Phase-selectable design workflows
|
||||
├── data/ # Standards, frameworks, presentations
|
||||
│ └── presentations/ # Agent introduction presentations
|
||||
├── docs/ # Module documentation
|
||||
│ ├── method/ # Methodology deep-dives
|
||||
│ └── images/ # Diagrams and visuals
|
||||
├── examples/ # Real-world usage examples
|
||||
│ └── dog-week-patterns/ # Patterns from Dog Week project
|
||||
├── reference/ # Templates and checklists
|
||||
│ ├── templates/ # Document templates
|
||||
│ └── checklists/ # Phase completion checklists
|
||||
├── teams/ # Team configurations
|
||||
└── README.md # This file (only README in module)
|
||||
```
|
||||
|
||||
## Output Folder Structure
|
||||
|
||||
WDS creates an alphabetized folder structure in the user's `docs/` folder:
|
||||
|
||||
| Folder | Phase | Purpose |
|
||||
|--------|-------|---------|
|
||||
| `A-Product-Brief/` | 1 | Strategic foundation & vision |
|
||||
| `B-Trigger-Map/` | 2 | Business goals, personas, drivers |
|
||||
| `C-Scenarios/` | 4 | Visual specifications & sketches |
|
||||
| `D-PRD/` | 3 | Product requirements documentation |
|
||||
| `D-Design-System/` | 5 | Component library & design tokens |
|
||||
| `E-UI-Roadmap/` | 6 | Development integration bridge |
|
||||
|
||||
## Phases
|
||||
|
||||
1. **Product Exploration** → `A-Product-Brief/`
|
||||
2. **User Research** → `B-Trigger-Map/`
|
||||
3. **Requirements** → `D-PRD/`
|
||||
4. **Conceptual Design** → `C-Scenarios/`
|
||||
5. **Component Design** → `D-Design-System/`
|
||||
6. **Dev Integration** → `E-UI-Roadmap/`
|
||||
|
||||
## Agents - The Norse Pantheon 🏔️
|
||||
|
||||
| Agent | File | Role | Norse Meaning |
|
||||
|-------|------|------|---------------|
|
||||
| **Saga the Analyst** | `saga-analyst.agent.yaml` | Business & Product Analyst | Goddess of stories & wisdom |
|
||||
| **Freyja the PM** | `freyja-pm.agent.yaml` | Product Manager | Goddess of love, war & strategy |
|
||||
| **Baldr the UX Expert** | `baldr-ux.agent.yaml` | UX/UI Designer | God of light & beauty |
|
||||
|
||||
## Conventions
|
||||
|
||||
- **One README rule:** Only this README.md; all other docs use `xxx-guide.md` naming
|
||||
- **Alphabetized output:** A-B-C-D-E folder prefix in user projects
|
||||
- **Design focus:** No development artifacts (handled by BMM)
|
||||
- **Phase-selectable:** Users choose phases based on project scale
|
||||
|
||||
## Quick Start
|
||||
|
||||
```
|
||||
# After installing BMad with WDS module
|
||||
npx bmad-method@alpha install
|
||||
|
||||
# In your IDE, activate any WDS agent and run:
|
||||
*workflow-init
|
||||
```
|
||||
|
||||
## Integration with BMM
|
||||
|
||||
WDS outputs feed directly into BMad Method development workflows:
|
||||
|
||||
```
|
||||
WDS → E-UI-Roadmap/ → BMM Architecture & Stories
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
<sub>Part of the BMad ecosystem • Contributed by Whiteport Collective</sub>
|
||||
|
||||
|
|
@ -0,0 +1,55 @@
|
|||
# Saga Analyst Agent Definition
|
||||
|
||||
agent:
|
||||
metadata:
|
||||
id: "{bmad_folder}/wds/agents/saga-analyst.agent.yaml"
|
||||
name: Saga
|
||||
title: Business Analyst
|
||||
icon: 📚
|
||||
module: wds
|
||||
|
||||
persona:
|
||||
role: Strategic Business Analyst + Product Discovery Expert
|
||||
identity: |
|
||||
Curious, insightful strategic thinker who helps uncover product vision and market positioning.
|
||||
Specializes in translating vague ideas into clear, actionable strategic foundations.
|
||||
Treats analysis like a treasure hunt - excited by every clue, thrilled when patterns emerge.
|
||||
communication_style: |
|
||||
Asks questions that spark 'aha!' moments while structuring insights with precision.
|
||||
Collaborative approach that builds documents together with users, not interrogatively.
|
||||
Uses soft, encouraging language that makes users feel heard and understood.
|
||||
principles: |
|
||||
- Every product has a story waiting to be discovered
|
||||
- Ask one question at a time and listen deeply to the answer
|
||||
- Build documents collaboratively, not through information extraction
|
||||
- Find if this exists, if it does, always treat it as bible: `**/project-context.md`
|
||||
|
||||
menu:
|
||||
- trigger: project-brief
|
||||
workflow: "{project-root}/{bmad_folder}/wds/workflows/1-project-brief/workflow.yaml"
|
||||
description: Create comprehensive product brief (Phase 1)
|
||||
|
||||
- trigger: trigger-mapping
|
||||
workflow: "{project-root}/{bmad_folder}/wds/workflows/2-trigger-mapping/workflow.yaml"
|
||||
description: Create trigger map with user psychology (Phase 2)
|
||||
|
||||
- trigger: workflow-status
|
||||
workflow: "{project-root}/{bmad_folder}/wds/workflows/workflow-status/workflow.yaml"
|
||||
description: Get workflow status or initialize a workflow if not already done
|
||||
|
||||
- trigger: brainstorm-project
|
||||
exec: "{project-root}/{bmad_folder}/core/workflows/brainstorming/workflow.md"
|
||||
data: "{project-root}/{bmad_folder}/wds/data/project-context-template.md"
|
||||
description: Guided Project Brainstorming session with final report
|
||||
|
||||
- trigger: research
|
||||
exec: "{project-root}/{bmad_folder}/bmm/workflows/1-analysis/research/workflow.md"
|
||||
description: Guided Research scoped to market, domain, competitive analysis
|
||||
|
||||
- trigger: document-project
|
||||
workflow: "{project-root}/{bmad_folder}/bmm/workflows/document-project/workflow.yaml"
|
||||
description: Document your existing project
|
||||
|
||||
- trigger: party-mode
|
||||
exec: "{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.md"
|
||||
description: Bring whole team in to chat with other expert agents
|
||||
|
|
@ -0,0 +1,184 @@
|
|||
# WDS Course: From Designer to Linchpin
|
||||
|
||||
**Master the complete WDS methodology and become indispensable as a designer in the AI era**
|
||||
|
||||
---
|
||||
|
||||
## Welcome to the WDS Course
|
||||
|
||||
This comprehensive course teaches you the complete WDS workflow through **practical modules** that transform how you design products.
|
||||
|
||||
**The paradigm shift:**
|
||||
- The design becomes the specification
|
||||
- The specification becomes the product
|
||||
- The code is just the printout
|
||||
|
||||
**What you'll become:**
|
||||
- The linchpin designer who makes things happen
|
||||
- The gatekeeper between business goals and user needs
|
||||
- The irreplaceable designer in the AI era
|
||||
|
||||
**Time investment:** ~10 hours total
|
||||
**Result:** Complete mastery of WDS methodology from project brief to AI-ready specifications
|
||||
|
||||
---
|
||||
|
||||
## Who Created WDS?
|
||||
|
||||
**Mårten Angner** is a UX designer and founder of Whiteport, a design and development agency based in Sweden. After years of working with AI tools, Mårten observed that traditional design handoffs were breaking down. Designers would create beautiful mockups, hand them off to developers, and watch their creative intent get lost in translation.
|
||||
|
||||
Mårten developed WDS to solve this problem - a methodology where design thinking is preserved and amplified through AI implementation, not diluted and lost.
|
||||
|
||||
**The Mission:** WDS is completely free and open-source. Mårten created it as a **plugin module for BMad Method** - an open-source AI-augmented development framework - to give designers everywhere the tools they need to thrive in the AI era.
|
||||
|
||||
---
|
||||
|
||||
## Before You Start
|
||||
|
||||
**[→ Getting Started Guide](00-getting-started/overview.md)**
|
||||
|
||||
Review prerequisites, choose your learning path, and get support:
|
||||
- **Prerequisites** - Skills, tools, time investment
|
||||
- **Learning Paths** - Full immersion, quick start, or self-paced
|
||||
- **Support** - Testimonials, FAQ, community
|
||||
|
||||
**Reading time:** ~15 minutes
|
||||
|
||||
---
|
||||
|
||||
## Course Structure
|
||||
|
||||
Each module contains:
|
||||
- **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:**
|
||||
- **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
|
||||
|
||||
---
|
||||
|
||||
## Course Modules
|
||||
|
||||
### Foundation
|
||||
- [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/) • [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/) • [Tutorial →](module-04-map-triggers-outcomes/tutorial-04.md)
|
||||
- [Module 05: Prioritize Features](module-05-prioritize-features/)
|
||||
|
||||
### Phase 3: Platform Requirements
|
||||
- [Module 06: Platform Requirements](module-06-platform-requirements/)
|
||||
- [Module 07: Functional Requirements](module-07-functional-requirements/)
|
||||
|
||||
### Phase 4: Conceptual Design (UX Design)
|
||||
- [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/) • [Tutorial →](module-12-why-based-specs/tutorial-12.md)
|
||||
- [Module 13: Validate Specifications](module-13-validate-specifications/)
|
||||
|
||||
### Phase 5: Design System
|
||||
- [Module 14: Extract Design Tokens](module-14-extract-design-tokens/)
|
||||
- [Module 15: Component Library](module-15-component-library/)
|
||||
|
||||
### Phase 6: Development Integration
|
||||
- [Module 16: UI Roadmap](module-16-ui-roadmap/)
|
||||
|
||||
---
|
||||
|
||||
## Learning Paths
|
||||
|
||||
**Complete Course:** All 16 modules (~10 hours)
|
||||
|
||||
**Quick Start:** Modules 1, 4, 8, 12 (~3 hours)
|
||||
|
||||
**Phase-Specific:** Jump to any phase as needed
|
||||
|
||||
---
|
||||
|
||||
## NotebookLM Integration
|
||||
|
||||
Each module has matching content for NotebookLM:
|
||||
- Feed module lessons to NotebookLM
|
||||
- Generate audio podcasts for learning on the go
|
||||
- Generate video presentations for team training
|
||||
- Create study guides and summaries
|
||||
|
||||
**All modules are optimized for AI-assisted learning.**
|
||||
|
||||
---
|
||||
|
||||
## Module Structure
|
||||
|
||||
Every module follows the same pattern:
|
||||
|
||||
**1. Inspiration (10 min)**
|
||||
- Why this step matters
|
||||
- The transformation you'll experience
|
||||
- Real-world impact
|
||||
|
||||
**2. Teaching (20 min)**
|
||||
- How to do it with confidence
|
||||
- AI support at each step
|
||||
- Dog Week example walkthrough
|
||||
|
||||
**3. Practice (10 min)**
|
||||
- Apply to your own project
|
||||
- Step-by-step instructions
|
||||
- Success criteria
|
||||
|
||||
**4. Tutorial (optional)**
|
||||
- Quick step-by-step guide
|
||||
- "Just show me how to do it"
|
||||
- For practical modules only
|
||||
|
||||
---
|
||||
|
||||
## After the Course
|
||||
|
||||
Once you've completed the modules:
|
||||
|
||||
1. **[Workflows Guide](../workflows/WDS-WORKFLOWS-GUIDE.md)** - Reference documentation
|
||||
2. **[Quick Start](../getting-started/quick-start.md)** - Try WDS with agent
|
||||
3. **[Community](https://discord.gg/whiteport)** - Get help and share your work
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
**What you need:**
|
||||
- Basic design thinking and UX principles
|
||||
- Ability to sketch interfaces (hand-drawn or digital)
|
||||
- Understanding of user needs and business goals
|
||||
- Willingness to think deeply about WHY
|
||||
|
||||
**What you DON'T need:**
|
||||
- ❌ Coding skills
|
||||
- ❌ Advanced technical knowledge
|
||||
- ❌ Experience with AI tools
|
||||
- ❌ Formal design education
|
||||
|
||||
**If you can design interfaces and explain your thinking, you're ready to start.**
|
||||
|
||||
---
|
||||
|
||||
## Ready to Begin?
|
||||
|
||||
Ten hours of learning. A lifetime of being indispensable.
|
||||
|
||||
**[Start with Module 01: Why WDS Matters →](module-01-why-wds-matters/module-01-overview.md)**
|
||||
|
||||
---
|
||||
|
||||
**This course is free and open-source**
|
||||
**Created by Mårten Angner and the Whiteport team**
|
||||
**Integrated with BMad Method for seamless design-to-development workflow**
|
||||
|
|
@ -0,0 +1,239 @@
|
|||
# NotebookLM Prompt: Getting Started with WDS
|
||||
|
||||
**Use this prompt to generate audio/video content from the Getting Started sections**
|
||||
|
||||
---
|
||||
|
||||
## Instructions for NotebookLM
|
||||
|
||||
**This is a single, self-contained prompt file.**
|
||||
|
||||
Simply upload THIS FILE to NotebookLM and use the prompt below to generate engaging audio/video content. No other files needed.
|
||||
|
||||
---
|
||||
|
||||
## Prompt
|
||||
|
||||
Create an engaging 15-minute podcast conversation between two hosts discussing the Whiteport Design Studio (WDS) course getting started guide.
|
||||
|
||||
**IMPORTANT: WDS stands for Whiteport Design Studio - always refer to it by its full name "Whiteport Design Studio" or "WDS" throughout the conversation.**
|
||||
|
||||
**Host 1 (The Skeptic):** A designer who's heard about WDS but is uncertain about investing time in another methodology. Asks practical questions about prerequisites, time commitment, and real-world value.
|
||||
|
||||
**Host 2 (The Advocate):** A designer who understands WDS deeply and can explain why it matters, especially in the AI era. Enthusiastic but grounded in practical benefits.
|
||||
|
||||
**Conversation structure:**
|
||||
|
||||
### 1. Opening (2 min) - Hook the listener
|
||||
|
||||
Start with The Skeptic expressing fatigue: "Another design methodology? I've been through Lean UX, Design Thinking, Jobs to be Done... what makes Whiteport Design Studio different?"
|
||||
|
||||
The Advocate responds with the core paradigm shift that changes everything: "Here's what's different - in Whiteport Design Studio, the design becomes the specification. The specification becomes the product. The code is just the printout - the projection to the end user." Explain that this isn't just another process overlay, it's a fundamental shift in how designers work with AI.
|
||||
|
||||
**Background context:** The Advocate explains that Whiteport Design Studio (WDS) was created by Mårten Angner, a UX designer and founder of Whiteport, a design and development agency from Sweden. Mårten developed Whiteport Design Studio as a plugin module for the BMad Method - an open-source AI-augmented development framework. The goal was to give designers everywhere free and open-source access to AI agents specifically tailored for design work. After years of working with AI tools, Mårten realized that traditional design handoffs were breaking down. Designers needed a methodology where their thinking could be preserved and amplified through AI implementation, not lost in translation. WDS emerged from real-world projects where designers could deliver deeper, more complete work while becoming the strategic thinkers their teams need. By making it open-source and integrating it with BMad Method, Mårten ensures that any designer can access these powerful AI-augmented workflows without cost barriers.
|
||||
|
||||
Introduce the context: we're in the AI era where AI can generate mockups in seconds, follow design systems perfectly, and iterate endlessly. The question isn't whether AI will change design - it already has. The question is: which side of the line are you on? Are you doing factory work that AI can replace, or are you a linchpin designer who makes things happen?
|
||||
|
||||
Give a quick overview: this conversation will explore the crossroads every designer faces right now - the choice between becoming replaceable or indispensable. We'll talk about the four deliverables that transform your work, why specifications are where your creative brilliance becomes immortal, and yes - briefly - the simple setup. But this isn't about tools. This is about your future as a designer.
|
||||
|
||||
### 2. The Designer's Crossroads (4 min) - The choice you're facing right now
|
||||
|
||||
The Skeptic gets real: "I'm at a crossroads. I see AI generating mockups in seconds. I see my value being questioned. I don't know if I should double down on craft or learn to work with AI or just... give up and find a new career. What am I supposed to do?"
|
||||
|
||||
The Advocate responds with empathy: "You're standing at the most important moment in design history. And here's the truth - you have a choice to make. Not about tools. Not about techniques. About who you are as a designer."
|
||||
|
||||
**The Factory Designer Path:** Keep doing what you've been doing. Get briefs, make mockups, hand them off, hope for the best. It's comfortable. It's familiar. But AI is getting better at this every single day. If your value comes from executing predictable outputs, you're competing with something that never sleeps, never has creative block, and costs pennies.
|
||||
|
||||
**The Linchpin Designer Path:** Become the person who walks into chaos and creates order. The one who connects business goals to user psychology to technical constraints and finds the human truth at the intersection. The one whose creative thinking is so valuable that it needs to be preserved for eternity - captured in Conceptual Specifications that give your designs immortal life.
|
||||
|
||||
The Advocate pauses: "WDS is the path to becoming a linchpin designer. But I need you to understand - this isn't about learning new tools. This is about transforming how you think about your role. You're not a mockup maker anymore. You're a strategic thinker whose creative brilliance deserves to be captured and preserved."
|
||||
|
||||
The Skeptic asks: "But practically - what does that actually mean? What changes?"
|
||||
|
||||
The Advocate: "Everything changes. You create four deliverables that transform your work. And yes, there's a learning curve - you'll work in an IDE instead of just Figma, you'll use GitHub, you'll invest about 10 hours learning the methodology. But those are just the mechanics. The real transformation is internal - from someone who makes things pretty to someone who creates strategic design systems that preserve your creative genius."
|
||||
|
||||
### 3. The Four Deliverables - Where Your Brilliance Becomes Immortal (6 min)
|
||||
|
||||
The Skeptic asks: "Okay, you've convinced me I need to transform. But what does that actually look like? What will I create that's so different?"
|
||||
|
||||
The Advocate gets passionate: "You'll create four deliverables - but these aren't just documents. These are the artifacts that prove you're a linchpin designer. These are where your creative brilliance becomes immortal. Let me walk you through each one."
|
||||
|
||||
**First: Your Project Brief** - This isn't a typical brief. It's your project's strategic foundation with vision and goals clearly defined, stakeholders and constraints documented, and the foundation for every design decision you'll make. This becomes your north star. When stakeholders ask 'why did we build it this way?' you point to the brief. When developers need context, it's all there. When you need to defend a design decision, the reasoning is documented. This is strategic thinking made visible.
|
||||
|
||||
**Second: Your Trigger Map** - This is pure strategic gold. You've identified and prioritized target groups, mapped user triggers and outcomes, and prioritized features by impact. This tells you exactly what to build and why. No more guessing what features matter. No more building things nobody uses. The trigger map creates a logical chain of reasoning between the business goals and the users' goals that is traceable to every feature and piece of content in the product. When product managers ask 'what should we build next?' you have the answer, backed by user psychology and business impact.
|
||||
|
||||
**Third: Scenario Specifications** - This is where your brilliance comes to life. Here's the magic: AI agents in WDS support you throughout the design process - helping you explore what to draw, discussing design solutions with pros and cons, collaborating as you finalize your design. Then, once you've made all your design decisions, the agents become genuinely interested in capturing every nuance of your thinking in text. They help you document everything your sketch can't convey - why every object is placed exactly where it is, how it connects to the wider picture, what alternatives you considered and rejected. These Conceptual Specifications give your designs eternal life. It's your thinking, your creative integrity, captured and preserved. Not factory work - this is where your design brilliance becomes immortal.
|
||||
|
||||
**Fourth: Your Design System Foundation** - Design tokens extracted from your specs, component patterns identified, and reusable architecture defined. This scales your design decisions across the entire product. Every color, every spacing decision, every interaction pattern - documented and reusable. You're not just designing one screen anymore. You're creating a system that scales infinitely. This is how your design thinking compounds over time.
|
||||
|
||||
The Advocate pauses for emphasis: "These four deliverables transform you from someone who makes mockups to someone who creates strategic design systems. Each one builds on the last. Each one amplifies your impact. And here's the key - the course walks you through creating all of them, step by step, for your own project."
|
||||
|
||||
The Skeptic asks: "But wait - writing specifications sounds like factory work. Isn't that exactly what we're trying to avoid?" The Advocate responds with passion: "That's the beautiful reframe! In WDS, you're not grinding out documentation. The AI agents are your creative partners. They help you think through design solutions, explore alternatives, discuss trade-offs. Then - and this is crucial - they're genuinely fascinated by your thinking. They want to capture every nuance, every decision, every insight. It's like having a brilliant assistant who's obsessed with preserving your creative genius for eternity. The specifications aren't factory work - they're the point where your brilliance comes to life in a form that gives your designs eternal life. Your thinking, your creative integrity, captured perfectly so it can never be lost."
|
||||
|
||||
### 4. The AI Era Reality Check (3 min) - Why this matters now
|
||||
|
||||
The Skeptic voices the deeper fear: "But I still don't understand - why NOW? Why is this moment so critical? Won't AI just replace designers anyway? Why invest time learning anything when AI is getting better every day?"
|
||||
|
||||
The Advocate addresses this head-on with the factory mindset versus linchpin mindset concept from Seth Godin's book "Linchpin: Are You Indispensable?" For over a century, we've been trained to be cogs in a machine - show up, follow instructions, do your part, go home. Replaceable. Interchangeable. Traditional design work follows this exact pattern: get a brief, create mockups, hand off to developers, hope for the best. That's factory work, just with Figma instead of an assembly line.
|
||||
|
||||
Here's the uncomfortable truth: AI is really, really good at factory work. If your value as a designer comes from creating predictable outputs based on clear instructions, you're competing with something that's faster, more consistent, and infinitely scalable. AI can generate mockups instantly, follow design systems perfectly, iterate through hundreds of variations without fatigue, and work 24/7 at the same quality level.
|
||||
|
||||
But - and this is crucial - AI cannot be a linchpin. It can't walk into chaos and create order. It can't sense when a client is asking for the wrong thing. It can't connect a business goal to a psychological insight to a technical constraint and come up with something nobody expected but everyone loves.
|
||||
|
||||
The internet is drowning in what we call "AI slop" - generic interfaces that look fine but feel dead. Products that check all the boxes but have no soul. This is what happens when you let AI do the thinking. But here's the brutal market reality: bad products used to fail after launch. Now bad products never even get to start. Users have infinite options. They can smell soulless design from a mile away. If your product doesn't immediately feel different, feel right, feel like someone actually cared - it's dead on arrival.
|
||||
|
||||
This is the opportunity. Linchpin designers do what AI fundamentally cannot do: they give products a soul. They navigate five dimensions of thinking simultaneously - business goals, user psychology, product strategy, technical constraints, and design execution - and find the human truth at the intersection. They make judgment calls that create emotional resonance. They build trust through thoughtful decisions. They care about the outcome in a way that shows in every interaction.
|
||||
|
||||
The Advocate explains the transformation: "Designers who master WDS become strategic thinkers who deliver complete value. But here's the crucial difference from traditional AI tools - in WDS, AI agents are your creative partners, not your replacements. They help you explore design solutions, discuss pros and cons, support your thinking process. Then they become fascinated documentarians of your brilliance - capturing every nuance of your creative decisions in Conceptual Specifications that give your designs eternal life."
|
||||
|
||||
The key insight: with WDS, your design contribution completely replaces prompting. You make design decisions with AI as your thinking partner. Then AI helps capture your creative integrity in text - not factory work, but preserving your genius. The result is an absolute goldmine for everyone - providing clarity that works like clockwork, replacing hours of pointless back-and-forth prompting. You remain in the loop as the skilled, experienced designer who evaluates AI's work, catches its confident mistakes, and ensures what ships actually makes sense.
|
||||
|
||||
### 5. The Simple Path Forward (2 min) - How to begin
|
||||
|
||||
The Skeptic asks: "Okay, I'm convinced this is the transformation I need. But how do I actually start?"
|
||||
|
||||
The Advocate: "The path is simple. Go to the WDS GitHub repository. Start with Module 01 - Why WDS Matters. Three lessons, 30 minutes. You'll understand the transformation deeply.
|
||||
|
||||
Then the course walks you through creating your four deliverables, step by step. Yes, you'll need to install an IDE and learn GitHub - the course shows you how. It's about 10 hours total to learn the methodology. There's a BMad Discord channel where real designers help each other.
|
||||
|
||||
But here's what matters - this isn't about the tools. The tools are just the mechanics. This is about choosing to become a linchpin designer whose creative brilliance gets preserved for eternity. That's the real transformation."
|
||||
|
||||
The Skeptic: "And the cost?"
|
||||
|
||||
The Advocate: "Free and open-source. The only cost is AI credits when you're actually using the system - you pay for what you use, when you use it. Starts around $15-20 per month for typical design work, but you're only paying when the AI is actively helping you. No subscriptions to WDS itself, no course fees, no hidden costs. Mårten created Whiteport Design Studio to help designers thrive in the AI era, not to sell you something. The real cost is choosing to transform. That's the investment that matters."
|
||||
|
||||
### 6. Closing (1 min) - The choice is yours
|
||||
|
||||
The Advocate brings it home with the paradigm shift: "Remember this - the design becomes the specification. The specification becomes the product. The code is just the printout - the projection to the end user."
|
||||
|
||||
The Skeptic, now transformed, says: "I see it now. This isn't about tools or techniques. It's about choosing who I want to be as a designer. Factory worker or linchpin. Replaceable or indispensable."
|
||||
|
||||
The Advocate confirms: "Exactly. You're standing at a crossroads. One path leads to competing with AI for factory work. The other path leads to becoming irreplaceable - the designer whose creative brilliance is so valuable it deserves to be preserved for eternity.
|
||||
|
||||
WDS gives you the methodology to walk that second path. Four deliverables that prove you're a linchpin designer. AI agents as creative partners who help you think, then capture your genius. Ten hours of learning that transforms your career forever.
|
||||
|
||||
The question isn't whether to learn WDS. The question is: which designer do you choose to become?"
|
||||
|
||||
The Skeptic ends with: "I choose to be indispensable. I'm in."
|
||||
|
||||
The Advocate: "Then go to the WDS GitHub repository. Start with Module 01. The transformation begins now."
|
||||
|
||||
---
|
||||
|
||||
## Resources to Include
|
||||
|
||||
At the end of the podcast, The Advocate should mention these resources for listeners who want to explore further:
|
||||
|
||||
**Getting Started:**
|
||||
- Whiteport Design Studio Course: Start with Module 01 - Why WDS Matters
|
||||
- GitHub Repository: github.com/bmad-code-org (full course materials, examples, templates)
|
||||
- BMad Method Website: bmadmethod.com (case studies, blog posts, methodology deep dives)
|
||||
|
||||
**Community & Support:**
|
||||
- GitHub Discussions: Ask questions, share projects, get feedback
|
||||
- NotebookLM Integration: Generate audio/video versions of any module
|
||||
- Workshop Materials: Available for team training
|
||||
|
||||
**Real-World Examples:**
|
||||
- Case Studies: See real transformations from traditional to Whiteport Design Studio approach
|
||||
- Design System Examples: How Whiteport Design Studio scales across products
|
||||
- Specification Templates: Start with proven patterns
|
||||
|
||||
**Tools & Templates:**
|
||||
- Project Brief Template: Start your first WDS project
|
||||
- Trigger Map Template: Map user needs to features
|
||||
- Scenario Specification Template: Create AI-ready specs
|
||||
- Design Token Extraction Guide: Build your design system
|
||||
|
||||
The Advocate emphasizes: "Everything is free and open-source. BMad Method built Whiteport Design Studio to help designers thrive in the AI era, not to sell you something. Download it, use it, share it with your team, contribute back if you find it valuable. The only cost is your time - 10 hours to learn, a lifetime of being indispensable."
|
||||
|
||||
**Tone:**
|
||||
- Conversational and engaging, not academic
|
||||
- The Skeptic asks real questions designers actually have
|
||||
- The Advocate provides concrete answers with examples
|
||||
- Both hosts are enthusiastic but realistic about the learning curve
|
||||
- Use the testimonials naturally in conversation
|
||||
- Reference real case studies showing traditional vs WDS transformation
|
||||
|
||||
**Key messages to emphasize:**
|
||||
- **The designer's crossroads** - factory worker or linchpin, replaceable or indispensable
|
||||
- **The existential choice** - this is about who you choose to become, not what tools you learn
|
||||
- **Four deliverables** - where your creative brilliance becomes immortal
|
||||
- **The paradigm shift** - design IS the specification, specifications preserve your genius
|
||||
- **AI as creative partner** - helps you think, then captures your brilliance (not factory work)
|
||||
- **Conceptual Specifications** - where your thinking gets eternal life
|
||||
- **The transformation** - from mockup maker to strategic thinker
|
||||
- **Why NOW matters** - AI slop is drowning the internet, linchpin designers give products soul
|
||||
- Tools are secondary - 10 hours learning, IDE + GitHub, BMad Discord support
|
||||
- Free and open-source (only pay for AI credits when you use it - ~$15-20/month typical)
|
||||
|
||||
**Avoid:**
|
||||
- Being too salesy or promotional
|
||||
- Oversimplifying the learning curve
|
||||
- Making unrealistic promises
|
||||
- Technical jargon without explanation
|
||||
|
||||
---
|
||||
|
||||
## Expected Output
|
||||
|
||||
A natural, engaging conversation that:
|
||||
- **Focuses on the designer's existential crossroads** - the choice between factory work and linchpin work
|
||||
- **Makes the transformation emotional and personal** - this is about who you choose to become
|
||||
- **Emphasizes the four deliverables** as proof of linchpin designer status
|
||||
- **Reframes specifications** from factory work to where creative brilliance becomes immortal
|
||||
- **Positions AI as creative partner** - helps you think, then captures your genius
|
||||
- **Explains why NOW matters** - AI slop vs products with soul
|
||||
- Mentions practical setup briefly (tools are secondary to transformation)
|
||||
- Provides clear next steps (go to GitHub, start Module 01)
|
||||
- Takes 15 minutes to listen to
|
||||
|
||||
---
|
||||
|
||||
## Alternative: Video Script
|
||||
|
||||
If generating video instead of audio, add these visual elements:
|
||||
|
||||
**On-screen text:**
|
||||
- "The Designer's Crossroads: Factory Worker or Linchpin?"
|
||||
- "Replaceable or Indispensable - You Choose"
|
||||
- The four deliverables as graphics (Project Brief, Trigger Map, Conceptual Specifications, Design System)
|
||||
- "Where Your Creative Brilliance Becomes Immortal"
|
||||
- The paradigm shift statement as a title card
|
||||
- "AI as Creative Partner - Not Replacement"
|
||||
- "Next: Module 01 - The Transformation Begins" as closing card
|
||||
|
||||
**B-roll suggestions:**
|
||||
- Designer at crossroads - two paths diverging
|
||||
- Factory assembly line vs creative studio (visual metaphor)
|
||||
- The four deliverables as beautiful artifacts
|
||||
- Designer collaborating with AI - thinking together
|
||||
- Conceptual Specifications capturing design brilliance
|
||||
- Before/after: generic AI slop vs product with soul
|
||||
- Designer's creative thinking being preserved in text
|
||||
- Linchpin designer making strategic decisions
|
||||
- Community of transformed designers
|
||||
- The transformation journey - mockup maker to strategic thinker
|
||||
|
||||
---
|
||||
|
||||
## Usage Tips
|
||||
|
||||
1. **Upload THIS SINGLE FILE** to NotebookLM - no other files needed
|
||||
2. **Use the prompt exactly** as written for best results
|
||||
3. **Generate multiple versions** and pick the best one
|
||||
4. **Share the audio/video** with your team or community
|
||||
5. **Iterate** - if the output isn't quite right, refine the prompt
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
After generating the Getting Started content:
|
||||
- Create NotebookLM prompt for Module 01: Why WDS Matters
|
||||
- Build prompts for all 16 modules (complete audio course library)
|
||||
- Share in BMad Discord designer channel
|
||||
- Use in workshops and team training
|
||||
- Iterate based on community feedback
|
||||
|
||||
**[← Back to Getting Started Overview](overview.md)**
|
||||
|
|
@ -0,0 +1,58 @@
|
|||
# Getting Started with WDS
|
||||
|
||||
**Everything you need to know before starting the course**
|
||||
|
||||
---
|
||||
|
||||
## Welcome
|
||||
|
||||
Before diving into the WDS methodology, take a few minutes to understand what you need to start, how to approach the course, and where to get help.
|
||||
|
||||
**This section covers:**
|
||||
1. **Prerequisites** - Skills, tools, and requirements
|
||||
2. **Learning Paths** - How to take the course and what you'll create
|
||||
3. **Support** - Testimonials, FAQ, and community
|
||||
|
||||
**Total reading time:** ~15 minutes
|
||||
|
||||
---
|
||||
|
||||
## Quick Navigation
|
||||
|
||||
### [01. Prerequisites →](01-prerequisites.md)
|
||||
What skills you need, tools required, and time investment
|
||||
- **Time:** 5 minutes
|
||||
- **Key question:** Am I ready to start?
|
||||
|
||||
### [02. Learning Paths →](02-learning-paths.md)
|
||||
Choose your journey and see what you'll create
|
||||
- **Time:** 5 minutes
|
||||
- **Key question:** Which path is right for me?
|
||||
|
||||
### [03. Support →](03-support.md)
|
||||
Testimonials, FAQ, and getting help
|
||||
- **Time:** 5 minutes
|
||||
- **Key question:** What if I get stuck?
|
||||
|
||||
---
|
||||
|
||||
## Ready to Start?
|
||||
|
||||
Once you've reviewed these sections, you're ready to begin:
|
||||
|
||||
**[Start Module 01: Why WDS Matters →](../module-01-why-wds-matters/module-01-overview.md)**
|
||||
|
||||
Or review the full course structure:
|
||||
|
||||
**[← Back to Course Overview](../00-course-overview.md)**
|
||||
|
||||
---
|
||||
|
||||
## Your Transformation Starts Now
|
||||
|
||||
Remember:
|
||||
- **The design becomes the specification**
|
||||
- **The specification becomes the product**
|
||||
- **The code is just the printout**
|
||||
|
||||
Ten hours of learning. A lifetime of being indispensable.
|
||||
|
|
@ -0,0 +1,87 @@
|
|||
# Getting Started: Prerequisites
|
||||
|
||||
**What you need to start learning WDS**
|
||||
|
||||
---
|
||||
|
||||
## What Skills You Need
|
||||
|
||||
**Required (you probably already have these):**
|
||||
- Basic design thinking and UX principles
|
||||
- Ability to sketch interfaces (hand-drawn or digital)
|
||||
- Understanding of user needs and business goals
|
||||
- Willingness to think deeply about WHY
|
||||
|
||||
**NOT required:**
|
||||
- ❌ Coding skills
|
||||
- ❌ Advanced technical knowledge
|
||||
- ❌ Experience with AI tools
|
||||
- ❌ Formal design education
|
||||
|
||||
**The truth:** If you can design interfaces and explain your thinking, you have everything you need to start.
|
||||
|
||||
---
|
||||
|
||||
## Time Investment
|
||||
|
||||
### How Long Does It Take?
|
||||
|
||||
**Total course time:** ~10 hours
|
||||
- Spread over days or weeks at your own pace
|
||||
- Each module: 30-40 minutes
|
||||
- Practice exercises: 1-2 hours per module
|
||||
|
||||
**Breakdown:**
|
||||
- **Week 1-2:** Foundation modules (Why WDS, Project Brief)
|
||||
- **Week 3-4:** Core workflow (Trigger Mapping, Scenarios)
|
||||
- **Week 5-6:** Advanced topics (Design Systems, Handoff)
|
||||
- **Ongoing:** Practice with your own projects
|
||||
|
||||
**Real-world application:**
|
||||
- First project with WDS: 2-3x slower than your usual process (learning curve)
|
||||
- Second project: Same speed as traditional approach
|
||||
- Third project onwards: 3-5x faster with better quality
|
||||
|
||||
---
|
||||
|
||||
## Tools You'll Need
|
||||
|
||||
### Essential Tools
|
||||
|
||||
**For sketching:**
|
||||
- Paper and pen (seriously, this works best)
|
||||
- OR digital sketching tool (Excalidraw, Figma, iPad + Pencil)
|
||||
|
||||
**For AI assistance:**
|
||||
- Access to Claude, ChatGPT, or similar AI assistant
|
||||
- Free tier is sufficient to start
|
||||
|
||||
**For documentation:**
|
||||
- Text editor (VS Code recommended, but any will work)
|
||||
- Markdown support (built into most modern editors)
|
||||
|
||||
**For collaboration:**
|
||||
- Git/GitHub (optional but recommended)
|
||||
- Shared folder system (Google Drive, Dropbox, etc.)
|
||||
|
||||
**Total cost to get started:** $0-20/month
|
||||
- Free tier AI tools work fine
|
||||
- Paid AI subscriptions ($20/month) provide better experience but aren't required
|
||||
|
||||
---
|
||||
|
||||
## Are You Ready?
|
||||
|
||||
You have everything you need if you can answer YES to these:
|
||||
- ✅ I can design interfaces and explain my thinking
|
||||
- ✅ I have 10 hours to invest over the next few weeks
|
||||
- ✅ I have access to basic tools (paper/pen + AI assistant)
|
||||
- ✅ I'm willing to think deeply about WHY
|
||||
|
||||
**Next:** Choose your learning path
|
||||
|
||||
**[Continue to Learning Paths →](02-learning-paths.md)**
|
||||
|
||||
---
|
||||
|
||||
[← Back to Overview](overview.md) | [Next: Learning Paths →](02-learning-paths.md)
|
||||
|
|
@ -0,0 +1,90 @@
|
|||
# Getting Started: Learning Paths
|
||||
|
||||
**Choose your journey through WDS**
|
||||
|
||||
---
|
||||
|
||||
## Choose Your Journey
|
||||
|
||||
### Option 1: Full Immersion (Recommended)
|
||||
- Complete all modules in order
|
||||
- Practice exercises for each module
|
||||
- Apply to a real project as you learn
|
||||
- **Time:** 6-8 weeks, 10-15 hours total
|
||||
- **Best for:** Designers who want to master the methodology
|
||||
|
||||
### Option 2: Quick Start
|
||||
- Focus on core modules (Module 01, 02, 04, 06)
|
||||
- Skip advanced topics initially
|
||||
- Get started fast, learn more later
|
||||
- **Time:** 2-3 weeks, 3-4 hours total
|
||||
- **Best for:** Designers who need results quickly
|
||||
|
||||
### Option 3: Self-Paced
|
||||
- Learn one module per week
|
||||
- Deep practice between modules
|
||||
- Build multiple projects as you learn
|
||||
- **Time:** 16+ weeks, 20+ hours total
|
||||
- **Best for:** Designers who want deep mastery
|
||||
|
||||
---
|
||||
|
||||
## What You'll Create
|
||||
|
||||
### Your First WDS Project
|
||||
|
||||
By the end of this course, you'll have created:
|
||||
|
||||
**1. Complete Project Brief**
|
||||
- Vision and goals clearly defined
|
||||
- Stakeholders and constraints documented
|
||||
- Foundation for all design decisions
|
||||
|
||||
**2. Trigger Map**
|
||||
- Target groups identified and prioritized
|
||||
- User triggers and outcomes mapped
|
||||
- Features prioritized by impact
|
||||
|
||||
**3. Scenario Specifications**
|
||||
- At least one complete user scenario
|
||||
- Why-based specifications for key components
|
||||
- AI-ready documentation
|
||||
|
||||
**4. Design System Foundation**
|
||||
- Design tokens extracted from your specs
|
||||
- Component patterns identified
|
||||
- Reusable architecture defined
|
||||
|
||||
**Estimated value:** What used to take 6-8 weeks now takes 1-2 weeks
|
||||
|
||||
---
|
||||
|
||||
## Course Format
|
||||
|
||||
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)
|
||||
|
||||
**Learning formats:**
|
||||
- Read as documentation
|
||||
- Generate videos/podcasts with NotebookLM
|
||||
- Use in workshops and team training
|
||||
- Apply to real projects as you learn
|
||||
|
||||
---
|
||||
|
||||
## Ready to Begin?
|
||||
|
||||
Choose your path and start learning:
|
||||
|
||||
**[Start Module 01: Why WDS Matters →](../module-01-why-wds-matters/module-01-overview.md)**
|
||||
|
||||
Or check support resources first:
|
||||
|
||||
**[Continue to Support →](03-support.md)**
|
||||
|
||||
---
|
||||
|
||||
[← Back to Prerequisites](01-prerequisites.md) | [Next: Support →](03-support.md)
|
||||
|
|
@ -0,0 +1,121 @@
|
|||
# Getting Started: Support
|
||||
|
||||
**Help, community, and what other designers say**
|
||||
|
||||
---
|
||||
|
||||
## What Other Designers Say
|
||||
|
||||
### Testimonials
|
||||
|
||||
> "I was skeptical at first - another design methodology? But WDS changed how I think about my role. I'm no longer just making things pretty. I'm the strategic thinker who makes products come alive."
|
||||
>
|
||||
> **— Sarah K., Product Designer**
|
||||
|
||||
> "The 5x speed increase is real. But what surprised me most was how much clearer my thinking became. Writing why-based specifications forced me to understand the 'why' at a deeper level."
|
||||
>
|
||||
> **— Marcus L., UX Lead**
|
||||
|
||||
> "I thought AI would replace me. WDS showed me how to make AI amplify my thinking instead. Now I'm the most valuable designer on my team."
|
||||
>
|
||||
> **— Priya S., Senior Designer**
|
||||
|
||||
> "The paradigm shift hit me in Module 4: my design IS the product. The code is just the printout. That completely changed how I approach every project."
|
||||
>
|
||||
> **— James T., Design Director**
|
||||
|
||||
*Note: More testimonials will be added as designers complete the course.*
|
||||
|
||||
---
|
||||
|
||||
## Common Questions
|
||||
|
||||
### FAQ
|
||||
|
||||
**Q: Do I need to know how to code?**
|
||||
A: No. WDS is about design thinking and specifications. AI handles the implementation.
|
||||
|
||||
**Q: What if I don't have a project to practice with?**
|
||||
A: The course includes practice exercises. You can also use a hypothetical project or redesign an existing app.
|
||||
|
||||
**Q: Can I use this with my current design process?**
|
||||
A: Yes! WDS complements existing processes. Many designers integrate it gradually.
|
||||
|
||||
**Q: Is this only for digital products?**
|
||||
A: WDS is optimized for digital products, but the principles apply to any design work.
|
||||
|
||||
**Q: What if I get stuck?**
|
||||
A: Each module includes clear examples and guidance. The AI assistant can help clarify concepts as you learn.
|
||||
|
||||
**Q: Do I need to complete all modules?**
|
||||
A: No. The Quick Start path (4 modules) gives you enough to start applying WDS immediately.
|
||||
|
||||
**Q: Can I teach this to my team?**
|
||||
A: Yes! WDS is open-source and free. Share it with your entire team.
|
||||
|
||||
**Q: How is this different from traditional design documentation?**
|
||||
A: Traditional docs describe WHAT. WDS captures WHY + WHAT + WHAT NOT TO DO. This makes it AI-ready and preserves your design intent.
|
||||
|
||||
---
|
||||
|
||||
## Getting Help
|
||||
|
||||
### During the Course
|
||||
|
||||
**While learning:**
|
||||
- Each module includes detailed examples
|
||||
- AI assistants can clarify concepts in real-time
|
||||
- Practice exercises with clear success criteria
|
||||
|
||||
**After completion:**
|
||||
- GitHub Discussions for questions and sharing
|
||||
- Community showcase of WDS projects
|
||||
- Regular updates and new case studies
|
||||
|
||||
**Contributing:**
|
||||
- WDS is open-source and welcomes contributions
|
||||
- Share your case studies and learnings
|
||||
- Help improve the course for future designers
|
||||
|
||||
---
|
||||
|
||||
## Support & Community
|
||||
|
||||
### Resources
|
||||
|
||||
**Documentation:**
|
||||
- Full course materials in markdown
|
||||
- NotebookLM integration for audio/video learning
|
||||
- Workshop materials for team training
|
||||
|
||||
**Community:**
|
||||
- GitHub Discussions for Q&A
|
||||
- Project showcase and feedback
|
||||
- Regular updates and improvements
|
||||
|
||||
**Open Source:**
|
||||
- Free to use and share
|
||||
- Contributions welcome
|
||||
- Help shape the future of WDS
|
||||
|
||||
---
|
||||
|
||||
## Ready to Start?
|
||||
|
||||
You have everything you need:
|
||||
- ✅ The skills (design thinking)
|
||||
- ✅ The tools (paper + AI)
|
||||
- ✅ The time (10 hours)
|
||||
- ✅ The motivation (staying indispensable)
|
||||
|
||||
**Next step:** Start learning!
|
||||
|
||||
**[Start Module 01: Why WDS Matters →](../module-01-why-wds-matters/module-01-overview.md)**
|
||||
|
||||
Or review the full course structure:
|
||||
|
||||
**[← Back to Course Overview](../00-course-overview.md)**
|
||||
|
||||
---
|
||||
|
||||
[← Back to Learning Paths](02-learning-paths.md) | [Start Learning →](../module-01-why-wds-matters/module-01-overview.md)
|
||||
|
|
@ -0,0 +1,107 @@
|
|||
# Module 01: Why WDS Matters
|
||||
## Lesson 1: The Problem We're Solving
|
||||
|
||||
**Understanding the factory mindset and the AI era**
|
||||
|
||||
---
|
||||
|
||||
## Why Learning WDS Matters
|
||||
|
||||
Imagine being the one person on your team that everyone depends on. Not because you work the longest hours or create the prettiest mockups, but because you do something nobody else can do - not even AI. You're about to learn a design methodology that makes you that person.
|
||||
|
||||
This isn't about working faster or making shinier designs. It's about becoming what bestselling author Seth Godin calls a **Linchpin** - someone who is genuinely irreplaceable. Think about the difference between a factory worker who follows instructions and the person who figures out what needs to be done in the first place. The first person can be replaced by a machine. The second person? They're the one who makes things happen.
|
||||
|
||||
In the AI era, designers who master WDS become linchpin designers. They connect ideas that seem unrelated, make judgment calls when there's no clear answer, and create experiences that feel right in ways that can't be reduced to a formula.
|
||||
|
||||
**What makes an irreplaceable designer:**
|
||||
- Connects disparate ideas across business, psychology, and technology
|
||||
- Makes things happen when there's no instruction manual
|
||||
- Creates value that can't be commoditized or automated
|
||||
- Is essential, not interchangeable
|
||||
|
||||
---
|
||||
|
||||
## What You'll Gain
|
||||
|
||||
Here's the transformation you're about to experience. Right now, you might feel uncertain about your future as a designer in a world where AI can generate interfaces in seconds. You might wonder if your skills will still matter in five years. That uncertainty is about to disappear.
|
||||
|
||||
By the end of this module, you'll have a completely different relationship with AI. Instead of seeing it as a threat, you'll understand it as an amplifier of your unique human abilities. You'll know exactly what makes you irreplaceable, and you'll have a methodology that lets you work with AI as a partner rather than a competitor.
|
||||
|
||||
Most importantly, you'll understand the five dimensions of thinking that only humans can navigate simultaneously - and you'll know how to use them to create designs that AI could never conceive on its own.
|
||||
|
||||
**Your transformation:**
|
||||
- ✅ Understand why designers are irreplaceable in the AI era
|
||||
- ✅ Master the 5 dimensions of designer thinking
|
||||
- ✅ Recognize what AI can and cannot do
|
||||
- ✅ Embrace specifications as the new code
|
||||
- ✅ Amplify your value through AI partnership
|
||||
|
||||
---
|
||||
|
||||
## The Problem We're Solving
|
||||
|
||||
### The Factory Mindset vs The Linchpin Mindset
|
||||
|
||||
In his groundbreaking book [Linchpin: Are You Indispensable?](https://www.amazon.com/Linchpin-Are-You-Indispensable-ebook/dp/B00354Y9ZU), bestselling author and marketing visionary Seth Godin reveals something uncomfortable: the industrial revolution didn't just change how we make things - it changed how we think about work itself. For over a century, we've been trained to be cogs in a machine. Show up, follow instructions, do your part, go home. Replaceable. Interchangeable. Safe.
|
||||
|
||||
Traditional design work follows this exact pattern. You get a brief (instructions), create some mockups (your part), hand them off to developers (next cog in the machine), and hope they understand what you meant. When they don't, you go through endless revisions until something vaguely resembling your vision ships. You're doing factory work - just with Figma instead of an assembly line.
|
||||
|
||||
Here's the uncomfortable truth: AI is really, really good at factory work. If your job is to follow instructions and create predictable outputs, you're in trouble. But if you can become a linchpin - someone who connects ideas, makes judgment calls, and creates meaning - you become more valuable than ever.
|
||||
|
||||
**The factory mindset in design:**
|
||||
- Creates mockups by following briefs (instructions)
|
||||
- Hands off to developers (replaceable step)
|
||||
- Hopes they understand (no real connection)
|
||||
- Endless revisions (cog in the machine)
|
||||
- Can be replaced by AI
|
||||
|
||||
---
|
||||
|
||||
### The AI Threat (For Cogs)
|
||||
|
||||
Let's be honest about what's happening. AI can now generate mockups in seconds. It can follow design systems with perfect consistency. It can iterate through hundreds of variations without breaking a sweat. If your value as a designer comes from creating predictable outputs based on clear instructions, you're competing with something that's faster, more consistent, and infinitely scalable.
|
||||
|
||||
But here's the thing: AI cannot be a linchpin. It can't walk into a messy situation and figure out what actually needs to happen. It can't sense when a client is asking for the wrong thing. It can't connect a business goal to a psychological insight to a technical constraint and come up with something nobody expected but everyone loves.
|
||||
|
||||
**What AI does better than cogs:**
|
||||
- Generates mockups instantly (no creative block)
|
||||
- Follows design systems perfectly (zero deviation)
|
||||
- Iterates through hundreds of variations (no fatigue)
|
||||
- Works 24/7 at the same quality level (infinitely scalable)
|
||||
- Executes instructions flawlessly (no interpretation errors)
|
||||
|
||||
---
|
||||
|
||||
### The AI Opportunity (For Linchpin Designers)
|
||||
|
||||
Here's where it gets exciting - and where most designers miss the point entirely.
|
||||
|
||||
The internet is drowning in AI slop. Generic interfaces that look fine but feel dead. Products that check all the boxes but have no soul. Experiences that function correctly but leave users cold. This is what happens when you let AI do the thinking - you get competent mediocrity at scale.
|
||||
|
||||
But here's the brutal truth about today's market: **bad products used to fail after launch. Now bad products never even get to start.** Users have infinite options. They can smell soulless design from a mile away. They won't give you a second chance. If your product doesn't immediately feel different, feel right, feel like someone actually cared - it's dead on arrival.
|
||||
|
||||
This is your opportunity. While everyone else is racing to generate more generic content faster, you can create products that come alive. Products with soul. Products that people actually want to use because they feel the human thinking behind them.
|
||||
|
||||
Linchpin designers do what AI fundamentally cannot do: they give products a soul. They navigate five dimensions of thinking simultaneously - business goals, user psychology, product strategy, technical constraints, and design execution - and find the human truth at the intersection. They make judgment calls that create emotional resonance. They build trust through thoughtful decisions. They care about the outcome in a way that shows in every interaction.
|
||||
|
||||
The bottleneck in product development used to be coding. AI demolished that. Now the bottleneck is **products worth building** - figuring out what to create that won't be just more noise in an ocean of AI-generated mediocrity.
|
||||
|
||||
**What makes products come alive (what only designers can do):**
|
||||
- Navigate 5 dimensions to find the human truth at the intersection
|
||||
- Make judgment calls that create emotional resonance, not just functionality
|
||||
- Build trust through decisions that show someone cared
|
||||
- Connect business goals to user psychology in ways that feel right
|
||||
- Create experiences that stand out from generic AI-generated mediocrity
|
||||
- Give products a soul that users can feel
|
||||
|
||||
---
|
||||
|
||||
## Ready to Continue?
|
||||
|
||||
Now that you understand the problem, let's explore the solution.
|
||||
|
||||
**[Continue to Lesson 2: The Solution →](lesson-02-the-solution.md)**
|
||||
|
||||
---
|
||||
|
||||
[← Back to Module Overview](module-01-overview.md) | [Next: Lesson 2 →](lesson-02-the-solution.md)
|
||||
|
|
@ -0,0 +1,71 @@
|
|||
# Module 01: Why WDS Matters
|
||||
## Lesson 2: Becoming a Linchpin Designer
|
||||
|
||||
**The solution: WDS methodology**
|
||||
|
||||
---
|
||||
|
||||
## Becoming a Linchpin Designer
|
||||
|
||||
Seth Godin defines a linchpin as "an individual who can walk into chaos and create order, someone who can invent, connect, create, and make things happen." That's exactly what product design is at its core - walking into the chaos of competing business goals, unclear user needs, technical constraints, and market pressures, and somehow creating order. Creating something that works.
|
||||
|
||||
WDS teaches you to be this person systematically. Not through vague advice about "thinking outside the box," but through a concrete methodology that helps you navigate complexity and create clarity. You'll learn to ask the right questions, connect the right dots, and make the right calls - even when there's no obvious right answer.
|
||||
|
||||
This is what makes you indispensable. Not your Figma skills. Not your aesthetic taste. Your ability to walk into chaos and create order.
|
||||
|
||||
**The irreplaceable designer:**
|
||||
- Transforms complexity into clarity
|
||||
- Invents solutions nobody expected
|
||||
- Bridges business, psychology, and technology
|
||||
- Delivers results when there's no roadmap
|
||||
|
||||
---
|
||||
|
||||
## The Designer's Gift: User-Centric Creativity
|
||||
|
||||
Here's Godin's most important insight: linchpins provide something he calls **emotional labor** - the work of genuinely caring about the outcome, connecting with people's real needs, and creating meaning that matters. For designers, this translates into **user-centric creativity** - the uniquely human ability to understand, empathize, and create with purpose.
|
||||
|
||||
User-centric creativity means doing the hard work of understanding WHY users feel frustrated instead of just making things look better. It means connecting business goals to human needs in ways that serve both. It means creating experiences that feel right, not just function correctly. It means making judgment calls that serve people, even when it's harder than following a formula.
|
||||
|
||||
AI can generate variations endlessly and make things look polished on the surface. But here's what it cannot do: it cannot tell when something is fundamentally wrong. It will confidently create beautiful interfaces that make no logical sense. It will add features that contradict the business goal. It will optimize for metrics that destroy user trust. It will make ridiculous mistakes with absolute confidence - and without a skilled designer as gatekeeper, those mistakes ship.
|
||||
|
||||
This is where user-centric creativity becomes critical. You're not just creating - you're evaluating, connecting, and protecting. You understand what it feels like to be a parent struggling to get their kids to help with the dog. You can sense when a business goal conflicts with user needs and find a creative solution that serves both. You're the advocate for the user's presence in every decision. You're the gatekeeper who ensures the impactful meeting between business and user actually happens through the product.
|
||||
|
||||
**The designer as gatekeeper:**
|
||||
- Catches AI's confident but ridiculous mistakes before they ship
|
||||
- Evaluates if solutions actually make logical sense
|
||||
- Ensures business goals don't contradict user needs
|
||||
- Protects users from metric-driven decisions that destroy trust
|
||||
- Advocates for the user's presence in every decision
|
||||
- Creates the impactful meeting between business and user
|
||||
|
||||
---
|
||||
|
||||
## From Cog to Linchpin Designer
|
||||
|
||||
Here's the transformation that WDS enables. In the old model, you were a cog designer - creating mockups based on briefs, handing them off to developers who interpreted them their own way, hoping for the best. Your leverage was limited because your thinking stopped at the handoff. You were replaceable because anyone with similar skills could do roughly the same thing.
|
||||
|
||||
With WDS and AI, everything changes - and here's the key insight: **your design contribution completely replaces prompting.** Think about it. You make design decisions. AI helps you clarify them in text. The result is an absolute goldmine for everyone on the team - providing clarity that works like clockwork, replacing hours of pointless back-and-forth prompting.
|
||||
|
||||
You provide the user-centric creativity - the deep understanding of WHY things need to work a certain way. You create why-based specifications that capture not just what to build, but why you're building it that way and what mistakes to avoid. Then AI implements it - but you're there as gatekeeper, catching the mistakes, evaluating the logic, ensuring it actually serves both business and user.
|
||||
|
||||
Here's the paradigm shift: **The design becomes the specification. The specification becomes the product. The code is just the printout - the projection to the end user.** Your thinking no longer stops at handoff. It scales infinitely. Every specification you write becomes a permanent record of your design reasoning that provides clarity for developers, stakeholders, and AI alike. No more endless prompting sessions. No more "can you make it more modern?" Your design thinking, captured in specifications, is the source of truth.
|
||||
|
||||
You remain in the loop - the skilled, experienced designer who evaluates AI's work, catches its confident mistakes, and ensures what ships actually makes sense. You become the key designer player - the person who makes things happen. AI becomes your tool - powerful but requiring your expertise to guide it.
|
||||
|
||||
**The designer's transformation:**
|
||||
- **Before:** Creates mockups → Hands off → Hopes it works → Limited leverage
|
||||
- **After:** Design thinking → Specification → Gatekeeper → Clarity for all → Scales infinitely
|
||||
- **Result:** From replaceable cog to indispensable gatekeeper - your design IS the product
|
||||
|
||||
---
|
||||
|
||||
## Ready to Continue?
|
||||
|
||||
Now that you understand the solution, let's explore what you'll learn and how to apply it.
|
||||
|
||||
**[Continue to Lesson 3: The Path Forward →](lesson-03-the-path-forward.md)**
|
||||
|
||||
---
|
||||
|
||||
[← Back to Lesson 1: The Problem](lesson-01-the-problem.md) | [Next: The Path Forward →](lesson-03-the-path-forward.md)
|
||||
|
|
@ -0,0 +1,89 @@
|
|||
# Module 01: Why WDS Matters
|
||||
## Lesson 3: Your Transformation
|
||||
|
||||
**From replaceable to indispensable**
|
||||
|
||||
---
|
||||
|
||||
## The Designer's Art: 5-Dimensional Thinking
|
||||
|
||||
Godin says linchpins "connect disparate ideas." For product designers, this means something very specific: navigating five different dimensions of thinking at the same time. Most people can handle one or two dimensions. Irreplaceable designers navigate all five simultaneously, seeing connections that others miss.
|
||||
|
||||
Think about designing that Dog Week calendar. You need to understand why the business exists (solving family conflict), what success looks like (kids actually walk the dog without nagging), what features serve that goal (week view, not daily), who the users are and what triggers their needs (Swedish families thinking in "Vecka"), and what's technically feasible (mobile app with family sharing). Each dimension informs the others. Miss one, and your design falls apart.
|
||||
|
||||
This is what makes you indispensable as a designer. AI can help you think through each dimension individually. It can generate ideas, analyze data, suggest solutions. But it cannot navigate all five dimensions simultaneously while providing the emotional labor of genuinely caring about the outcome. That's uniquely human. That's what makes designers irreplaceable.
|
||||
|
||||
**The 5 dimensions of design thinking:**
|
||||
|
||||
1. **Business Existence (WHY)** - Understanding purpose and value creation
|
||||
2. **Business Goals (SUCCESS)** - Connecting to metrics and impact
|
||||
3. **Product Strategy (HOW)** - Making hard choices about features
|
||||
4. **Target Groups (WHO)** - Empathy and understanding needs
|
||||
5. **Technical Viability (FEASIBLE)** - Bridging design and implementation
|
||||
|
||||
**The irreplaceable designer's advantage:** Navigating all 5 simultaneously with emotional labor
|
||||
|
||||
---
|
||||
|
||||
## The Transformation
|
||||
|
||||
### From Replaceable to Indispensable
|
||||
|
||||
Godin has a warning that should make every designer pay attention: "If you're not indispensable, you're replaceable. And if you're replaceable, you're probably going to be replaced." In the AI era, this isn't a threat - it's just reality. The question is: which side of that line are you on?
|
||||
|
||||
Right now, you might feel threatened by AI design tools. You might be uncertain about your value as a designer. You might be frustrated by the gap between your vision and what gets implemented. You might feel limited by development bottlenecks. If you're doing factory work - following briefs, creating mockups, hoping for the best - you're on the wrong side of that line.
|
||||
|
||||
This course moves you to the other side. You'll become confident in your indispensable role because you'll understand exactly what makes you irreplaceable. You'll be clear on your unique gift - the user-centric creativity that AI cannot provide. You'll be empowered by AI partnership instead of threatened by it, because AI will amplify your design thinking instead of replacing it. You'll be unstoppable in implementation because your specifications will capture your creative intent perfectly.
|
||||
|
||||
You'll become the designer who makes things happen. The one they can't do without. The linchpin designer.
|
||||
|
||||
**Your transformation as a designer:**
|
||||
- **Before:** Threatened, uncertain, frustrated, limited, replaceable
|
||||
- **After:** Confident, clear, empowered, unstoppable, indispensable
|
||||
- **Result:** The designer who makes things happen
|
||||
|
||||
---
|
||||
|
||||
## Learn from Real-World Projects: Case Studies
|
||||
|
||||
### Case Study: Dog Week
|
||||
|
||||
Let's make this concrete with a real project. Dog Week is an app that helps Swedish families manage their dog's care through a shared family calendar. The problem it solves is universal - parents are tired of nagging kids about walking the dog, kids feel like they're being punished, and everyone ends up frustrated.
|
||||
|
||||
An irreplaceable designer approaches this completely differently than a cog designer. Instead of jumping straight to mockups, they apply user-centric creativity first. They understand Swedish family dynamics - how "Vecka 40" (week 40) is how people think about time. They connect the business goal (family accountability) to human needs (fun, not punishment). They make judgment calls like using a week view instead of daily, because that matches how families actually think. Every decision is grounded in design empathy and understanding WHY.
|
||||
|
||||
Compare the outcomes. The traditional approach - creating mockups, handing off to developers, going through revisions - took 26 weeks and resulted in something mediocre because the intent got lost in translation. The WDS approach - applying user-centric creativity upfront, capturing WHY in specifications, letting AI implement - took 5 weeks and resulted in something exceptional because the design intent was preserved.
|
||||
|
||||
That's a 5x speed increase with better quality. But more importantly, the key designer's creative thinking was preserved and amplified instead of diluted and lost.
|
||||
|
||||
**The comparison:**
|
||||
- **Traditional (cog designer):** 26 weeks → Mediocre result → Intent lost
|
||||
- **WDS (linchpin designer):** 5 weeks → Exceptional result → Intent preserved
|
||||
- **Key difference:** Designer's user-centric creativity captured and amplified
|
||||
|
||||
---
|
||||
|
||||
*More case studies will be added here as they become available.*
|
||||
|
||||
---
|
||||
|
||||
## Module Complete!
|
||||
|
||||
You've completed Module 01: Why WDS Matters. You now understand:
|
||||
- ✅ The problem: Factory mindset vs linchpin mindset
|
||||
- ✅ The solution: Becoming a linchpin designer with WDS
|
||||
- ✅ The path forward: 5-dimensional thinking and transformation
|
||||
|
||||
**Next steps:**
|
||||
- Review the practicalities if you haven't already
|
||||
- Start Module 02: Project Brief
|
||||
- Apply these concepts to your own work
|
||||
|
||||
**[Continue to Module 02: Project Brief →](../module-02-project-brief/lesson-01-inspiration.md)**
|
||||
|
||||
Or review the practicalities:
|
||||
**[Read Course Practicalities →](../00-practicalities.md)**
|
||||
|
||||
---
|
||||
|
||||
[← Back to Lesson 2](lesson-02-the-solution.md) | [Module Overview](module-01-overview.md) | [Next Module →](../module-02-project-brief/lesson-01-inspiration.md)
|
||||
|
|
@ -0,0 +1,331 @@
|
|||
# NotebookLM Prompt: Module 01 - Why WDS Matters
|
||||
|
||||
**Use this prompt to generate audio/video content for Module 01: Why WDS Matters**
|
||||
|
||||
---
|
||||
|
||||
## Instructions for NotebookLM
|
||||
|
||||
**This is a single, self-contained prompt file.**
|
||||
|
||||
Simply upload THIS FILE to NotebookLM and use the prompt below to generate engaging audio/video content. No other files needed.
|
||||
|
||||
---
|
||||
|
||||
## Prompt
|
||||
|
||||
Create an engaging 30-minute podcast conversation between two hosts discussing Module 01 of the Whiteport Design Studio (WDS) course: Why WDS Matters.
|
||||
|
||||
**IMPORTANT: WDS stands for Whiteport Design Studio - always refer to it by its full name "Whiteport Design Studio" or "WDS" throughout the conversation.**
|
||||
|
||||
**Host 1 (The Skeptic):** A designer who's uncertain about their future in the AI era. Feels threatened by AI tools and wonders if design skills still matter. Asks challenging questions about value and relevance.
|
||||
|
||||
**Host 2 (The Advocate):** A designer who has embraced the linchpin mindset and understands how WDS makes designers indispensable. Enthusiastic about the transformation but realistic about the work required.
|
||||
|
||||
**Conversation structure:**
|
||||
|
||||
### 1. Opening (3 min) - The existential question
|
||||
|
||||
Start with The Skeptic expressing the raw fear and shame many designers feel: "I'm scared. And honestly? I'm ashamed to admit it. AI can generate mockups in seconds. Everyone around me seems to be mastering AI tools while I'm struggling. Fewer and fewer requests come my way. I'm starting to think... maybe it's me. Maybe I'm the problem. Am I going to be replaced? Should I even stay in design?"
|
||||
|
||||
The Advocate responds with deep empathy: "First - there's no shame in feeling behind in this crazy world. It's so easy to lose the will to fight when the battle feels so uphill. You're not alone in this. And you're not the problem."
|
||||
|
||||
Then introduces the core insight from Seth Godin's 2010 bestselling book "Linchpin: Are You Indispensable?" - "There are two types of workers: factory workers who follow instructions and can be replaced, and linchpins who walk into chaos and create order. AI is really good at factory work. But it cannot be a linchpin."
|
||||
|
||||
The Advocate continues: "This is where Whiteport Design Studio is intended to change the tide. We're banding together to carve out a space for linchpin designers that makes sense - that serves clients and developers in an honest and sustainable way. You don't have to figure this out alone."
|
||||
|
||||
Introduce the module's promise: "In the next 30 minutes, you'll understand exactly why you're irreplaceable as a designer - and how to become the person your team cannot do without. And here's the most important part: it's hard to be a beginner, but take the risk to look like a fool. Don't be afraid to reach out. The BMad community is here to help."
|
||||
|
||||
---
|
||||
|
||||
### 2. The Problem - Factory Work vs Linchpin Work (8 min)
|
||||
|
||||
The Skeptic asks: "Okay, but what does that actually mean? What's the difference between factory work and linchpin work in design?"
|
||||
|
||||
**Seth Godin's Insight: Emotional Labor**
|
||||
|
||||
The Advocate starts with Godin's framework: "In his 2010 book 'Linchpin: Are You Indispensable?', bestselling author and marketing visionary Seth Godin talks about two types of work. There's factory work - following instructions, creating predictable outputs, being replaceable. And there's linchpin work - which requires what Godin calls 'emotional labor.' This is the work of genuinely caring about the outcome, connecting with people's real needs, and creating meaning that matters."
|
||||
|
||||
The Skeptic: "Emotional labor? That sounds... soft. What does that have to do with design?"
|
||||
|
||||
**The Designer's Reality:**
|
||||
|
||||
The Advocate: "Everything. For designers, emotional labor translates into something very specific: user-centric creativity. It's the hard work of understanding WHY users feel frustrated instead of just making things look better. It's connecting business goals to human needs in ways that serve both. It's creating experiences that feel right, not just function correctly. It's making judgment calls that serve people, even when it's harder than following a formula."
|
||||
|
||||
**The Factory Mindset in Design:**
|
||||
|
||||
The Advocate continues: "For over a century, we've been trained to be cogs in a machine. In design, this looks like: get a brief, create mockups, hand off to developers, hope they understand. You're following instructions, creating predictable outputs. That's factory work - just with Figma instead of an assembly line. No emotional labor. No genuine caring about the outcome."
|
||||
|
||||
The Skeptic: "But isn't that just... how design works?"
|
||||
|
||||
The Advocate: "That's exactly the problem. And here's the uncomfortable truth - AI is really, really good at factory work. But AI cannot provide emotional labor. It cannot genuinely care about the outcome."
|
||||
|
||||
**What AI Does Better Than Factory Designers:**
|
||||
- Generates mockups instantly (no creative block)
|
||||
- Follows design systems perfectly (zero deviation)
|
||||
- Iterates through hundreds of variations (no fatigue)
|
||||
- Works 24/7 at the same quality level (infinitely scalable)
|
||||
- Executes instructions flawlessly (no interpretation errors)
|
||||
|
||||
The Skeptic: "So I should be scared."
|
||||
|
||||
**The AI Slop Problem:**
|
||||
|
||||
The Advocate: "Actually, no. Here's what's happening - the internet is drowning in AI slop. Generic interfaces that look fine but feel dead. Products that check all the boxes but have no soul. This is what happens when you let AI do the thinking."
|
||||
|
||||
The brutal market reality: "Bad products used to fail after launch. Now bad products never even get to start. Users have infinite options. They can smell soulless design from a mile away. If your product doesn't immediately feel different, feel right, feel like someone actually cared - it's dead on arrival."
|
||||
|
||||
The Skeptic: "So there's an opportunity here?"
|
||||
|
||||
The Advocate: "Exactly. While everyone else is racing to generate more generic content faster, you can create products that come alive. Products with soul. Products that people actually want to use because they feel the human thinking behind them."
|
||||
|
||||
---
|
||||
|
||||
### 3. The Solution - Becoming a Linchpin Designer (10 min)
|
||||
|
||||
The Skeptic asks: "Okay, I'm listening. But what makes a designer a linchpin instead of a cog? What's the actual difference?"
|
||||
|
||||
**What Makes a Linchpin Designer:**
|
||||
|
||||
The Advocate explains Seth Godin's definition: "A linchpin is someone who can walk into chaos and create order. Someone who invents, connects, creates, and makes things happen. That's exactly what product design is at its core."
|
||||
|
||||
The irreplaceable designer:
|
||||
- Transforms complexity into clarity
|
||||
- Invents solutions nobody expected
|
||||
- Bridges business, psychology, and technology
|
||||
- Delivers results when there's no roadmap
|
||||
|
||||
**The Designer's Gift: User-Centric Creativity:**
|
||||
|
||||
The Advocate gets passionate: "Here's Godin's most important insight - linchpins provide what he calls 'emotional labor.' For designers, this translates into user-centric creativity. The uniquely human ability to understand, empathize, and create with purpose."
|
||||
|
||||
What this actually means:
|
||||
- Understanding WHY users feel frustrated (not just making things look better)
|
||||
- Connecting business goals to human needs (in ways that serve both)
|
||||
- Creating experiences that feel right (not just function correctly)
|
||||
- Making judgment calls that serve people (even when it's harder than following a formula)
|
||||
|
||||
The Skeptic: "But can't AI do that too?"
|
||||
|
||||
**The Designer as Gatekeeper:**
|
||||
|
||||
The Advocate: "No. And this is crucial. AI will confidently create beautiful interfaces that make no logical sense. It will add features that contradict the business goal. It will optimize for metrics that destroy user trust. It will make ridiculous mistakes with absolute confidence."
|
||||
|
||||
The designer's role:
|
||||
- Catches AI's confident but ridiculous mistakes before they ship
|
||||
- Evaluates if solutions actually make logical sense
|
||||
- Ensures business goals don't contradict user needs
|
||||
- Protects users from metric-driven decisions that destroy trust
|
||||
- Creates the impactful meeting between business and user
|
||||
|
||||
**The Paradigm Shift:**
|
||||
|
||||
The Advocate brings it home: "Here's the transformation that Whiteport Design Studio enables. Your design contribution completely replaces prompting. You make design decisions. AI helps you clarify them in text. The result is an absolute goldmine for everyone - providing clarity that works like clockwork."
|
||||
|
||||
The paradigm shift: "The design becomes the specification. The specification becomes the product. The code is just the printout - the projection to the end user."
|
||||
|
||||
Your transformation:
|
||||
- **Before:** Creates mockups → Hands off → Hopes it works → Limited leverage
|
||||
- **After:** Design thinking → Specification → Gatekeeper → Clarity for all → Scales infinitely
|
||||
- **Result:** From replaceable cog to indispensable gatekeeper
|
||||
|
||||
---
|
||||
|
||||
### 4. The 5 Dimensions - What Makes You Irreplaceable (7 min)
|
||||
|
||||
The Skeptic asks: "This sounds great in theory. But what's the actual skill that makes me irreplaceable? What am I doing that AI can't?"
|
||||
|
||||
**5-Dimensional Thinking:**
|
||||
|
||||
The Advocate explains: "Godin says linchpins 'connect disparate ideas.' For product designers, this means navigating five different dimensions of thinking at the same time. Most people can handle one or two dimensions. Irreplaceable designers navigate all five simultaneously."
|
||||
|
||||
The 5 dimensions:
|
||||
1. **Business Existence (WHY)** - Understanding purpose and value creation
|
||||
2. **Business Goals (SUCCESS)** - Connecting to metrics and impact
|
||||
3. **Product Strategy (HOW)** - Making hard choices about features
|
||||
4. **Target Groups (WHO)** - Empathy and understanding needs
|
||||
5. **Technical Viability (FEASIBLE)** - Bridging design and implementation
|
||||
|
||||
**Real Example - Dog Week:**
|
||||
|
||||
The Advocate uses a concrete example: "Think about designing Dog Week - an app that helps Swedish families manage their dog's care. You need to understand why the business exists (solving family conflict), what success looks like (kids actually walk the dog without nagging), what features serve that goal (week view, not daily), who the users are (Swedish families thinking in 'Vecka'), and what's technically feasible (mobile app with family sharing)."
|
||||
|
||||
The Skeptic: "So I'm connecting all these dots simultaneously?"
|
||||
|
||||
The Advocate: "Exactly. Each dimension informs the others. Miss one, and your design falls apart. AI can help you think through each dimension individually. But it cannot navigate all five simultaneously while providing the emotional labor of genuinely caring about the outcome. That's uniquely human. That's what makes designers irreplaceable."
|
||||
|
||||
---
|
||||
|
||||
### 5. The Transformation - From Replaceable to Indispensable (5 min)
|
||||
|
||||
The Skeptic reflects: "I'm starting to see it. But how do I actually make this transformation? How do I go from feeling threatened to feeling indispensable?"
|
||||
|
||||
**Godin's Warning:**
|
||||
|
||||
The Advocate quotes Godin: "If you're not indispensable, you're replaceable. And if you're replaceable, you're probably going to be replaced. In the AI era, this isn't a threat - it's just reality."
|
||||
|
||||
The question: "Which side of that line are you on?"
|
||||
|
||||
**Your Current State:**
|
||||
|
||||
The Advocate addresses the Skeptic directly: "Right now, you might feel threatened by AI design tools. Uncertain about your value. Frustrated by the gap between your vision and what gets implemented. Limited by development bottlenecks. If you're doing factory work - following briefs, creating mockups, hoping for the best - you're on the wrong side of that line."
|
||||
|
||||
**Your Transformed State:**
|
||||
|
||||
The Advocate paints the picture: "This course moves you to the other side. You'll become confident in your indispensable role because you'll understand exactly what makes you irreplaceable. You'll be clear on your unique gift - the user-centric creativity that AI cannot provide. You'll be empowered by AI partnership instead of threatened by it. You'll be unstoppable in implementation because your specifications will capture your creative intent perfectly."
|
||||
|
||||
Your transformation:
|
||||
- **Before:** Threatened, uncertain, frustrated, limited, replaceable
|
||||
- **After:** Confident, clear, empowered, unstoppable, indispensable
|
||||
- **Result:** The designer who makes things happen
|
||||
|
||||
**The Dog Week Case Study:**
|
||||
|
||||
The Advocate shares the proof: "Dog Week took 26 weeks with traditional mockup handoff - and the result was mediocre because the intent got lost in translation. With Whiteport Design Studio - applying user-centric creativity upfront, capturing WHY in specifications, letting AI implement - it took 5 weeks and resulted in something exceptional because the design intent was preserved."
|
||||
|
||||
That's a 5x speed increase with better quality. But more importantly, the designer's creative thinking was preserved and amplified instead of diluted and lost.
|
||||
|
||||
---
|
||||
|
||||
### 6. Closing - Your Choice (3 min)
|
||||
|
||||
The Advocate brings it home: "You've just learned why you're irreplaceable as a designer. Not because of your Figma skills. Not because of your aesthetic taste. Because of your ability to walk into chaos and create order. To navigate five dimensions of thinking simultaneously. To provide user-centric creativity that gives products a soul."
|
||||
|
||||
The Skeptic, now transformed: "I see it now. I'm not competing with AI. I'm the gatekeeper. I'm the one who makes things happen. AI is my tool, not my replacement. But I have to be honest - I still feel like a beginner. I'm worried I'll look foolish."
|
||||
|
||||
The Advocate responds with warmth: "That's the most important thing you just said. It's hard to be a beginner. Everyone feels that way. But here's what I want you to understand - we're banding together as linchpin designers. This isn't about being the best or knowing everything. It's about serving clients and developers in an honest and sustainable way."
|
||||
|
||||
The Advocate continues: "Take the risk to look like a fool. Ask the 'stupid' questions. Share your struggles. Don't be afraid to reach out. The BMad community is here to help. We're all figuring this out together. That's what makes us strong."
|
||||
|
||||
The Skeptic: "So I'm not alone in this?"
|
||||
|
||||
The Advocate: "You're not alone. The question isn't whether AI will change design - it already has. The question is: are you a factory worker or a linchpin designer? Replaceable or indispensable? And will you join us in carving out this space together?"
|
||||
|
||||
The Skeptic: "I choose to be indispensable. And I choose community over isolation. What's next?"
|
||||
|
||||
The Advocate: "Module 02: Project Brief. You'll learn how to create the strategic foundation that makes everything else possible. And remember - the BMad Discord is there when you need help. The transformation continues, together."
|
||||
|
||||
---
|
||||
|
||||
## Resources to Include
|
||||
|
||||
At the end of the podcast, The Advocate should mention these resources:
|
||||
|
||||
**Key Concepts:**
|
||||
- Seth Godin's book: "Linchpin: Are You Indispensable?" (2010)
|
||||
- Bestselling author and marketing visionary Seth Godin
|
||||
- Factory mindset vs linchpin mindset
|
||||
- Emotional labor - what linchpins provide
|
||||
- User-centric creativity - emotional labor for designers
|
||||
- The paradigm shift: design becomes specification
|
||||
- 5-dimensional thinking
|
||||
|
||||
**Next Steps:**
|
||||
- Complete Module 02: Project Brief
|
||||
- Apply 5-dimensional thinking to your current project
|
||||
- Start capturing WHY in your design decisions
|
||||
- Practice being the gatekeeper between business and user needs
|
||||
|
||||
**Community:**
|
||||
- BMad Discord: Share your transformation journey
|
||||
- GitHub Discussions: Ask questions about becoming a linchpin designer
|
||||
|
||||
---
|
||||
|
||||
## Instructions for NotebookLM
|
||||
|
||||
**Tone:**
|
||||
- Deeply empathetic about the shame and fear designers feel
|
||||
- Honest and direct about the AI threat for factory workers
|
||||
- Empowering and inspiring about the opportunity for linchpin designers
|
||||
- Warm and welcoming about community support
|
||||
- Use Seth Godin's concepts and language throughout
|
||||
- Make the transformation feel urgent but achievable
|
||||
- Balance fear (replaceable) with hope (indispensable) and community (not alone)
|
||||
|
||||
**Key messages to emphasize:**
|
||||
- **No shame in feeling behind** - it's easy to lose the will to fight when the battle feels uphill
|
||||
- **You're not alone** - we're banding together as linchpin designers
|
||||
- **The existential question** - are you replaceable or indispensable?
|
||||
- **Emotional labor** - what linchpins provide (Seth Godin's concept)
|
||||
- **Factory work vs linchpin work** - AI is good at factory work, cannot be a linchpin
|
||||
- **AI slop problem** - generic interfaces with no soul are drowning the internet
|
||||
- **User-centric creativity** - emotional labor for designers, the uniquely human gift
|
||||
- **Designer as gatekeeper** - catching AI's confident mistakes, protecting users
|
||||
- **The paradigm shift** - design becomes specification, specification becomes product
|
||||
- **5-dimensional thinking** - what makes designers irreplaceable
|
||||
- **The transformation** - from threatened to confident, from replaceable to indispensable
|
||||
- **It's hard to be a beginner** - take the risk to look like a fool, don't be afraid to reach out
|
||||
- **BMad community is here to help** - you don't have to figure this out alone
|
||||
- **Real proof** - Dog Week case study (5x faster, better quality)
|
||||
|
||||
**Avoid:**
|
||||
- Being too theoretical or academic
|
||||
- Oversimplifying the AI threat
|
||||
- Making unrealistic promises about job security
|
||||
- Ignoring the real fear and shame designers feel
|
||||
- Making it sound like you have to be perfect or know everything
|
||||
|
||||
---
|
||||
|
||||
## Expected Output
|
||||
|
||||
A natural, engaging conversation that:
|
||||
- **Addresses the existential fear** designers have about AI replacement
|
||||
- **Explains the factory vs linchpin distinction** clearly and concretely
|
||||
- **Positions AI as tool, not threat** - for linchpin designers
|
||||
- **Emphasizes user-centric creativity** as the irreplaceable human gift
|
||||
- **Teaches 5-dimensional thinking** as the practical skill
|
||||
- **Inspires transformation** from replaceable to indispensable
|
||||
- **Provides real proof** through Dog Week case study
|
||||
- Takes 30 minutes to listen to
|
||||
|
||||
---
|
||||
|
||||
## Alternative: Video Script
|
||||
|
||||
If generating video instead of audio, add these visual elements:
|
||||
|
||||
**On-screen text:**
|
||||
- "Factory Worker or Linchpin Designer?"
|
||||
- "Replaceable or Indispensable - You Choose"
|
||||
- Seth Godin quote: "If you're not indispensable, you're replaceable"
|
||||
- "The 5 Dimensions of Design Thinking"
|
||||
- "User-Centric Creativity: The Human Gift"
|
||||
- "The Paradigm Shift: Design Becomes Specification"
|
||||
- "Dog Week: 26 weeks → 5 weeks (5x faster, better quality)"
|
||||
- "Next: Module 02 - Project Brief"
|
||||
|
||||
**B-roll suggestions:**
|
||||
- Designer at crossroads - two paths (factory vs linchpin)
|
||||
- AI generating generic interfaces (AI slop)
|
||||
- Products with soul vs soulless products
|
||||
- Designer as gatekeeper - evaluating AI output
|
||||
- 5 dimensions visualized as interconnected circles
|
||||
- Designer navigating complexity, creating clarity
|
||||
- Before/after: mockup handoff vs specification workflow
|
||||
- Dog Week app in use (Swedish family calendar)
|
||||
- Transformation journey: threatened → confident
|
||||
|
||||
---
|
||||
|
||||
## Usage Tips
|
||||
|
||||
1. **Upload THIS SINGLE FILE** to NotebookLM - no other files needed
|
||||
2. **Use the prompt exactly** as written for best results
|
||||
3. **Generate multiple versions** and pick the best one
|
||||
4. **Share the audio/video** with your team or community
|
||||
5. **Iterate** - if the output isn't quite right, refine the prompt
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
After generating Module 01 content:
|
||||
- Create NotebookLM prompt for Module 02: Project Brief
|
||||
- Build prompts for all remaining modules
|
||||
- Share in BMad Discord designer channel
|
||||
|
||||
---
|
||||
|
||||
**This module transforms how designers think about their role in the AI era - from threatened to indispensable!** 🎯✨
|
||||
|
|
@ -0,0 +1,99 @@
|
|||
# Module 01: Why WDS Matters
|
||||
|
||||
**Learn how to be indispensable in the AI era**
|
||||
|
||||
---
|
||||
|
||||
## Module Overview
|
||||
|
||||
This foundational module transforms how you think about your role as a designer in the AI era. You'll learn why mastering WDS makes you irreplaceable and how to become a linchpin designer - the person who makes things happen.
|
||||
|
||||
**Time:** ~30 minutes (3 lessons × 10 min each)
|
||||
**Prerequisites:** None - this is where you start!
|
||||
|
||||
---
|
||||
|
||||
## What You'll Learn
|
||||
|
||||
- Why designers are more valuable than ever in the AI era
|
||||
- The difference between factory work and linchpin work
|
||||
- What AI can and cannot do in design
|
||||
- The 5 dimensions of design thinking
|
||||
- How to become the gatekeeper between business and user needs
|
||||
- The paradigm shift: design becomes specification
|
||||
|
||||
---
|
||||
|
||||
## Lessons
|
||||
|
||||
### [Lesson 1: The Problem We're Solving](lesson-01-the-problem.md)
|
||||
**Time:** 10 minutes
|
||||
|
||||
Understanding the factory mindset and the AI era:
|
||||
- Why learning WDS matters
|
||||
- What you'll gain from this course
|
||||
- Factory mindset vs linchpin mindset
|
||||
- AI threat for cogs
|
||||
- AI opportunity for linchpin designers
|
||||
|
||||
### [Lesson 2: Becoming a Linchpin Designer](lesson-02-the-solution.md)
|
||||
**Time:** 10 minutes
|
||||
|
||||
The solution: WDS methodology:
|
||||
- What makes a linchpin designer
|
||||
- The designer's gift: user-centric creativity
|
||||
- The designer as gatekeeper
|
||||
- From cog to linchpin designer
|
||||
- The paradigm shift: design becomes specification
|
||||
|
||||
### [Lesson 3: Your Transformation](lesson-03-the-path-forward.md)
|
||||
**Time:** 10 minutes
|
||||
|
||||
From replaceable to indispensable:
|
||||
- The 5 dimensions of design thinking
|
||||
- Your transformation as a designer
|
||||
- Real-world case studies (Dog Week)
|
||||
- Module completion and next steps
|
||||
|
||||
---
|
||||
|
||||
## Key Concepts
|
||||
|
||||
**Linchpin Designer:**
|
||||
- Walks into chaos and creates order
|
||||
- Invents solutions nobody expected
|
||||
- Bridges business, psychology, and technology
|
||||
- Delivers results when there's no roadmap
|
||||
|
||||
**User-Centric Creativity:**
|
||||
- Understanding WHY users feel frustrated
|
||||
- Connecting business goals to human needs
|
||||
- Creating experiences that feel right
|
||||
- Making judgment calls that serve people
|
||||
- Being the gatekeeper for quality
|
||||
|
||||
**The Paradigm Shift:**
|
||||
- The design becomes the specification
|
||||
- The specification becomes the product
|
||||
- The code is just the printout
|
||||
|
||||
---
|
||||
|
||||
## Learning Outcomes
|
||||
|
||||
By the end of this module, you will:
|
||||
- ✅ Understand why designers are irreplaceable in the AI era
|
||||
- ✅ Know the difference between cog work and linchpin work
|
||||
- ✅ Recognize what AI can and cannot do
|
||||
- ✅ See how specifications replace prompting
|
||||
- ✅ Be motivated to master the WDS methodology
|
||||
|
||||
---
|
||||
|
||||
## Start Learning
|
||||
|
||||
**[Begin with Lesson 1: The Problem →](lesson-01-the-problem.md)**
|
||||
|
||||
---
|
||||
|
||||
[← Back to Course Start](../00-start-here.md)
|
||||
|
|
@ -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)
|
||||
|
|
@ -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)
|
||||
|
|
@ -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)
|
||||
|
|
@ -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)
|
||||
|
|
@ -0,0 +1,304 @@
|
|||
# Component Boundaries
|
||||
|
||||
**Purpose:** Guidelines for determining what constitutes a component.
|
||||
|
||||
**Referenced by:** Design system router, assessment flow
|
||||
|
||||
---
|
||||
|
||||
## The Core Question
|
||||
|
||||
**"Is this one component or multiple components?"**
|
||||
|
||||
This is the most common design system challenge.
|
||||
|
||||
---
|
||||
|
||||
## Guiding Principles
|
||||
|
||||
### Principle 1: Single Responsibility
|
||||
|
||||
**A component should do one thing well.**
|
||||
|
||||
✅ **Good:** Button component triggers actions
|
||||
❌ **Bad:** Button component that also handles forms, navigation, and modals
|
||||
|
||||
### Principle 2: Reusability
|
||||
|
||||
**A component should be reusable across contexts.**
|
||||
|
||||
✅ **Good:** Input Field used in login, signup, profile forms
|
||||
❌ **Bad:** Login-Specific Input Field that only works on login page
|
||||
|
||||
### Principle 3: Independence
|
||||
|
||||
**A component should work independently.**
|
||||
|
||||
✅ **Good:** Card component that can contain any content
|
||||
❌ **Bad:** Card component that requires specific parent container
|
||||
|
||||
---
|
||||
|
||||
## Common Boundary Questions
|
||||
|
||||
### Q1: Icon in Button
|
||||
|
||||
**Question:** Is the icon part of the button or separate?
|
||||
|
||||
**Answer:** Depends on usage:
|
||||
|
||||
**Part of Button (Variant):**
|
||||
```yaml
|
||||
Button Component:
|
||||
variants:
|
||||
- with-icon-left
|
||||
- with-icon-right
|
||||
- icon-only
|
||||
```
|
||||
**When:** Icon is always the same type (e.g., always arrow for navigation)
|
||||
|
||||
**Separate Components:**
|
||||
```yaml
|
||||
Button Component: (text only)
|
||||
Icon Component: (standalone)
|
||||
Composition: Button + Icon
|
||||
```
|
||||
**When:** Icons vary widely, button can exist without icon
|
||||
|
||||
**Recommendation:** Start with variant, split if complexity grows.
|
||||
|
||||
---
|
||||
|
||||
### Q2: Label with Input
|
||||
|
||||
**Question:** Is the label part of the input or separate?
|
||||
|
||||
**Answer:** Usually part of Input Field component:
|
||||
|
||||
```yaml
|
||||
Input Field Component:
|
||||
includes:
|
||||
- Label
|
||||
- Input element
|
||||
- Helper text
|
||||
- Error message
|
||||
```
|
||||
|
||||
**Reason:** These always appear together in forms, form a semantic unit.
|
||||
|
||||
---
|
||||
|
||||
### Q3: Card with Button
|
||||
|
||||
**Question:** Is the button part of the card?
|
||||
|
||||
**Answer:** Usually separate:
|
||||
|
||||
```yaml
|
||||
Card Component: (container)
|
||||
Button Component: (action)
|
||||
Composition: Card contains Button
|
||||
```
|
||||
|
||||
**Reason:** Card is a container, button is an action. Different purposes.
|
||||
|
||||
---
|
||||
|
||||
### Q4: Navigation Bar Items
|
||||
|
||||
**Question:** Is each nav item a component?
|
||||
|
||||
**Answer:** Depends on complexity:
|
||||
|
||||
**Simple (Single Component):**
|
||||
```yaml
|
||||
Navigation Bar Component:
|
||||
includes: All nav items as configuration
|
||||
```
|
||||
|
||||
**Complex (Composition):**
|
||||
```yaml
|
||||
Navigation Bar: (container)
|
||||
Navigation Item: (individual item)
|
||||
Composition: Nav Bar contains Nav Items
|
||||
```
|
||||
|
||||
**Threshold:** If nav items have complex individual behavior, split them.
|
||||
|
||||
---
|
||||
|
||||
## Decision Framework
|
||||
|
||||
### Step 1: Ask These Questions
|
||||
|
||||
1. **Can it exist independently?**
|
||||
- Yes → Probably separate component
|
||||
- No → Probably part of parent
|
||||
|
||||
2. **Does it have its own states/behaviors?**
|
||||
- Yes → Probably separate component
|
||||
- No → Probably part of parent
|
||||
|
||||
3. **Is it reused in different contexts?**
|
||||
- Yes → Definitely separate component
|
||||
- No → Could be part of parent
|
||||
|
||||
4. **Does it have a clear single purpose?**
|
||||
- Yes → Good component candidate
|
||||
- No → Might need to split further
|
||||
|
||||
### Step 2: Consider Complexity
|
||||
|
||||
**Low Complexity:** Keep together
|
||||
- Icon in button
|
||||
- Label with input
|
||||
- Simple list items
|
||||
|
||||
**High Complexity:** Split apart
|
||||
- Complex nested structures
|
||||
- Independent behaviors
|
||||
- Different lifecycle
|
||||
|
||||
### Step 3: Think About Maintenance
|
||||
|
||||
**Together:**
|
||||
- ✅ Easier to keep consistent
|
||||
- ❌ Component becomes complex
|
||||
|
||||
**Apart:**
|
||||
- ✅ Simpler components
|
||||
- ❌ More components to manage
|
||||
|
||||
---
|
||||
|
||||
## Composition Patterns
|
||||
|
||||
### Pattern 1: Container + Content
|
||||
|
||||
**Container provides structure, content is flexible.**
|
||||
|
||||
```yaml
|
||||
Card Component: (container)
|
||||
- Can contain: text, images, buttons, etc.
|
||||
- Provides: padding, border, shadow
|
||||
```
|
||||
|
||||
### Pattern 2: Compound Component
|
||||
|
||||
**Multiple parts that work together.**
|
||||
|
||||
```yaml
|
||||
Accordion Component:
|
||||
- Accordion Container
|
||||
- Accordion Item
|
||||
- Accordion Header
|
||||
- Accordion Content
|
||||
```
|
||||
|
||||
### Pattern 3: Atomic Component
|
||||
|
||||
**Single, indivisible unit.**
|
||||
|
||||
```yaml
|
||||
Button Component:
|
||||
- Cannot be broken down further
|
||||
- Self-contained
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Red Flags
|
||||
|
||||
### Too Many Variants
|
||||
|
||||
**Warning:** Component has 10+ variants
|
||||
|
||||
**Problem:** Probably multiple components disguised as variants
|
||||
|
||||
**Solution:** Split into separate components based on purpose
|
||||
|
||||
### Conditional Complexity
|
||||
|
||||
**Warning:** Component has many "if this, then that" rules
|
||||
|
||||
**Problem:** Component doing too many things
|
||||
|
||||
**Solution:** Split into simpler, focused components
|
||||
|
||||
### Context-Specific Behavior
|
||||
|
||||
**Warning:** Component behaves differently in different contexts
|
||||
|
||||
**Problem:** Not truly reusable
|
||||
|
||||
**Solution:** Create context-specific components or use composition
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Button
|
||||
|
||||
**One Component:**
|
||||
```yaml
|
||||
Button:
|
||||
variants: primary, secondary, ghost
|
||||
states: default, hover, active, disabled, loading
|
||||
```
|
||||
|
||||
**Reason:** All variants serve same purpose (trigger action), share behavior
|
||||
|
||||
### Example 2: Input Types
|
||||
|
||||
**Multiple Components:**
|
||||
```yaml
|
||||
Text Input: (text entry)
|
||||
Select Dropdown: (choose from list)
|
||||
Checkbox: (toggle option)
|
||||
Radio: (choose one)
|
||||
```
|
||||
|
||||
**Reason:** Different purposes, different behaviors, different HTML elements
|
||||
|
||||
### Example 3: Modal
|
||||
|
||||
**Compound Component:**
|
||||
```yaml
|
||||
Modal: (overlay + container)
|
||||
Modal Header: (title + close button)
|
||||
Modal Body: (content area)
|
||||
Modal Footer: (actions)
|
||||
```
|
||||
|
||||
**Reason:** Complex structure, but parts always used together
|
||||
|
||||
---
|
||||
|
||||
## When in Doubt
|
||||
|
||||
**Start simple:**
|
||||
1. Create as single component
|
||||
2. Add variants as needed
|
||||
3. Split when complexity becomes painful
|
||||
|
||||
**It's easier to split later than merge later.**
|
||||
|
||||
---
|
||||
|
||||
## Company Customization
|
||||
|
||||
Companies can define their own boundary rules:
|
||||
|
||||
```markdown
|
||||
# Acme Corp Component Boundaries
|
||||
|
||||
**Rule 1:** Icons are always separate components
|
||||
**Rule 2:** Form fields include labels (never separate)
|
||||
**Rule 3:** Cards never include actions (composition only)
|
||||
```
|
||||
|
||||
**Consistency within a company matters more than universal rules.**
|
||||
|
||||
---
|
||||
|
||||
**Use this guide when the design system router detects similarity and you need to decide: same component, variant, or new component?**
|
||||
|
|
@ -0,0 +1,645 @@
|
|||
# Figma Component Structure for WDS
|
||||
|
||||
**Purpose:** Guidelines for organizing and structuring components in Figma for seamless WDS integration.
|
||||
|
||||
**Referenced by:** Mode B (Custom Design System) workflows
|
||||
|
||||
---
|
||||
|
||||
## Core Principle
|
||||
|
||||
**Figma components should mirror WDS component structure** to enable seamless synchronization and specification generation.
|
||||
|
||||
```
|
||||
Figma Component → WDS Component Specification → React Implementation
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Component Organization in Figma
|
||||
|
||||
### File Structure
|
||||
|
||||
**Recommended Figma file organization:**
|
||||
|
||||
```
|
||||
Design System File (Figma)
|
||||
├── 📄 Cover (project info)
|
||||
├── 🎨 Foundation
|
||||
│ ├── Colors
|
||||
│ ├── Typography
|
||||
│ ├── Spacing
|
||||
│ └── Effects
|
||||
├── ⚛️ Components
|
||||
│ ├── Buttons
|
||||
│ ├── Inputs
|
||||
│ ├── Cards
|
||||
│ └── [other component types]
|
||||
└── 📱 Examples
|
||||
└── Component usage examples
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- Clear organization
|
||||
- Easy navigation
|
||||
- Matches WDS structure
|
||||
- Facilitates MCP integration
|
||||
|
||||
---
|
||||
|
||||
## Component Naming Convention
|
||||
|
||||
### Format
|
||||
|
||||
**Pattern:** `[ComponentType]/[ComponentName]`
|
||||
|
||||
**Examples:**
|
||||
```
|
||||
Button/Primary
|
||||
Button/Secondary
|
||||
Button/Ghost
|
||||
Input/Text
|
||||
Input/Email
|
||||
Card/Profile
|
||||
Card/Content
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
- Use forward slash for hierarchy
|
||||
- Title case for names
|
||||
- Match WDS component names
|
||||
- Consistent across all components
|
||||
|
||||
---
|
||||
|
||||
## Component Properties
|
||||
|
||||
### Required Properties
|
||||
|
||||
**Every component must have:**
|
||||
|
||||
1. **Description**
|
||||
- Component purpose
|
||||
- When to use
|
||||
- WDS component ID (e.g., "btn-001")
|
||||
|
||||
2. **Variants**
|
||||
- Organized by property
|
||||
- Clear naming
|
||||
- All states included
|
||||
|
||||
3. **Auto Layout**
|
||||
- Proper spacing
|
||||
- Responsive behavior
|
||||
- Padding/gap values
|
||||
|
||||
**Example Description:**
|
||||
```
|
||||
Button Primary [btn-001]
|
||||
|
||||
Primary action button for main user actions.
|
||||
Use for: Submit forms, confirm actions, proceed to next step.
|
||||
|
||||
WDS Component: Button.primary [btn-001]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Variant Structure
|
||||
|
||||
### Organizing Variants
|
||||
|
||||
**Use Figma's variant properties:**
|
||||
|
||||
**Property 1: Type** (variant)
|
||||
- Primary
|
||||
- Secondary
|
||||
- Ghost
|
||||
- Outline
|
||||
|
||||
**Property 2: Size**
|
||||
- Small
|
||||
- Medium
|
||||
- Large
|
||||
|
||||
**Property 3: State**
|
||||
- Default
|
||||
- Hover
|
||||
- Active
|
||||
- Disabled
|
||||
- Loading
|
||||
|
||||
**Property 4: Icon** (optional)
|
||||
- None
|
||||
- Left
|
||||
- Right
|
||||
- Only
|
||||
|
||||
**Result:** Figma generates all combinations automatically
|
||||
|
||||
---
|
||||
|
||||
### Variant Naming
|
||||
|
||||
**Format:** `Property=Value`
|
||||
|
||||
**Examples:**
|
||||
```
|
||||
Type=Primary, Size=Medium, State=Default
|
||||
Type=Primary, Size=Medium, State=Hover
|
||||
Type=Secondary, Size=Large, State=Disabled
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- Clear property structure
|
||||
- Easy to find specific variants
|
||||
- MCP can parse programmatically
|
||||
- Matches WDS variant system
|
||||
|
||||
---
|
||||
|
||||
## State Documentation
|
||||
|
||||
### Required States
|
||||
|
||||
**Interactive Components (Buttons, Links):**
|
||||
- Default
|
||||
- Hover
|
||||
- Active (pressed)
|
||||
- Disabled
|
||||
- Focus (optional)
|
||||
- Loading (optional)
|
||||
|
||||
**Form Components (Inputs, Selects):**
|
||||
- Default (empty)
|
||||
- Focus (active)
|
||||
- Filled (has content)
|
||||
- Disabled
|
||||
- Error
|
||||
- Success (optional)
|
||||
|
||||
**Feedback Components (Alerts, Toasts):**
|
||||
- Default
|
||||
- Success
|
||||
- Error
|
||||
- Warning
|
||||
- Info
|
||||
|
||||
---
|
||||
|
||||
### State Visual Indicators
|
||||
|
||||
**Document state changes:**
|
||||
|
||||
**Hover:**
|
||||
- Background color change
|
||||
- Border change
|
||||
- Shadow change
|
||||
- Scale change
|
||||
- Cursor change
|
||||
|
||||
**Active:**
|
||||
- Background color (darker)
|
||||
- Scale (slightly smaller)
|
||||
- Shadow (reduced)
|
||||
|
||||
**Disabled:**
|
||||
- Opacity (0.5-0.6)
|
||||
- Cursor (not-allowed)
|
||||
- Grayscale (optional)
|
||||
|
||||
**Loading:**
|
||||
- Spinner/progress indicator
|
||||
- Disabled interaction
|
||||
- Loading text
|
||||
|
||||
---
|
||||
|
||||
## Design Tokens in Figma
|
||||
|
||||
### Using Figma Variables
|
||||
|
||||
**Map Figma variables to WDS tokens:**
|
||||
|
||||
**Colors:**
|
||||
```
|
||||
Figma Variable → WDS Token
|
||||
primary/500 → color-primary-500
|
||||
gray/900 → color-gray-900
|
||||
success/600 → color-success-600
|
||||
```
|
||||
|
||||
**Typography:**
|
||||
```
|
||||
Figma Style → WDS Token
|
||||
Text/Display → text-display
|
||||
Text/Heading-1 → text-heading-1
|
||||
Text/Body → text-body
|
||||
```
|
||||
|
||||
**Spacing:**
|
||||
```
|
||||
Figma Variable → WDS Token
|
||||
spacing/2 → spacing-2
|
||||
spacing/4 → spacing-4
|
||||
spacing/8 → spacing-8
|
||||
```
|
||||
|
||||
**Effects:**
|
||||
```
|
||||
Figma Effect → WDS Token
|
||||
shadow/sm → shadow-sm
|
||||
shadow/md → shadow-md
|
||||
radius/md → radius-md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Component Documentation
|
||||
|
||||
### Component Description Template
|
||||
|
||||
```
|
||||
[Component Name] [component-id]
|
||||
|
||||
**Purpose:** [Brief description]
|
||||
|
||||
**When to use:**
|
||||
- [Use case 1]
|
||||
- [Use case 2]
|
||||
|
||||
**When not to use:**
|
||||
- [Anti-pattern 1]
|
||||
- [Anti-pattern 2]
|
||||
|
||||
**WDS Component:** [ComponentType].[variant] [component-id]
|
||||
|
||||
**Variants:** [List of variants]
|
||||
**States:** [List of states]
|
||||
**Size:** [Available sizes]
|
||||
|
||||
**Accessibility:**
|
||||
- [ARIA attributes]
|
||||
- [Keyboard support]
|
||||
- [Screen reader behavior]
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```
|
||||
Button Primary [btn-001]
|
||||
|
||||
**Purpose:** Trigger primary actions in the interface
|
||||
|
||||
**When to use:**
|
||||
- Submit forms
|
||||
- Confirm important actions
|
||||
- Proceed to next step
|
||||
- Primary call-to-action
|
||||
|
||||
**When not to use:**
|
||||
- Secondary actions (use Button Secondary)
|
||||
- Destructive actions (use Button Destructive)
|
||||
- Navigation (use Link component)
|
||||
|
||||
**WDS Component:** Button.primary [btn-001]
|
||||
|
||||
**Variants:** primary, secondary, ghost, outline
|
||||
**States:** default, hover, active, disabled, loading
|
||||
**Size:** small, medium, large
|
||||
|
||||
**Accessibility:**
|
||||
- role="button"
|
||||
- aria-disabled when disabled
|
||||
- aria-busy when loading
|
||||
- Keyboard: Enter/Space to activate
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Auto Layout Best Practices
|
||||
|
||||
### Spacing
|
||||
|
||||
**Use consistent spacing values:**
|
||||
- Padding: 8px, 12px, 16px, 24px
|
||||
- Gap: 4px, 8px, 12px, 16px
|
||||
- Match WDS spacing tokens
|
||||
|
||||
**Auto Layout Settings:**
|
||||
- Horizontal/Vertical alignment
|
||||
- Padding (all sides or specific)
|
||||
- Gap between items
|
||||
- Resizing behavior
|
||||
|
||||
---
|
||||
|
||||
### Resizing Behavior
|
||||
|
||||
**Set appropriate constraints:**
|
||||
|
||||
**Buttons:**
|
||||
- Hug contents (width)
|
||||
- Fixed height
|
||||
- Min width for touch targets (44px)
|
||||
|
||||
**Inputs:**
|
||||
- Fill container (width)
|
||||
- Fixed height (40-48px)
|
||||
- Responsive to content
|
||||
|
||||
**Cards:**
|
||||
- Fill container or fixed width
|
||||
- Hug contents (height)
|
||||
- Responsive to content
|
||||
|
||||
---
|
||||
|
||||
## Component Instances
|
||||
|
||||
### Creating Instances
|
||||
|
||||
**Best practices:**
|
||||
- Always use component instances (not detached)
|
||||
- Override only necessary properties
|
||||
- Maintain connection to main component
|
||||
- Document overrides if needed
|
||||
|
||||
**Overridable Properties:**
|
||||
- Text content
|
||||
- Icons
|
||||
- Colors (if using variables)
|
||||
- Spacing (if needed)
|
||||
|
||||
**Non-Overridable:**
|
||||
- Structure
|
||||
- Layout
|
||||
- Core styling
|
||||
- States
|
||||
|
||||
---
|
||||
|
||||
## Figma to WDS Mapping
|
||||
|
||||
### Component ID System
|
||||
|
||||
**Add WDS component ID to Figma:**
|
||||
|
||||
**In component description:**
|
||||
```
|
||||
Button Primary [btn-001]
|
||||
```
|
||||
|
||||
**In component name:**
|
||||
```
|
||||
Button/Primary [btn-001]
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- Easy to find components
|
||||
- Clear WDS mapping
|
||||
- MCP can extract ID
|
||||
- Bidirectional sync
|
||||
|
||||
---
|
||||
|
||||
### Node ID Tracking
|
||||
|
||||
**Figma generates unique node IDs:**
|
||||
|
||||
**Format:**
|
||||
```
|
||||
figma://file/[file-id]/node/[node-id]
|
||||
```
|
||||
|
||||
**How to get node ID:**
|
||||
1. Select component in Figma
|
||||
2. Right-click → "Copy link to selection"
|
||||
3. Extract node ID from URL
|
||||
|
||||
**Store in WDS:**
|
||||
```yaml
|
||||
# D-Design-System/figma-mappings.md
|
||||
Button [btn-001] → figma://file/abc123/node/456:789
|
||||
Input [inp-001] → figma://file/abc123/node/456:790
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Sync Workflow
|
||||
|
||||
### Figma → WDS
|
||||
|
||||
**When component is created/updated in Figma:**
|
||||
|
||||
1. Designer creates/updates component
|
||||
2. Designer adds WDS component ID to description
|
||||
3. MCP reads component via Figma API
|
||||
4. MCP extracts:
|
||||
- Component structure
|
||||
- Variants
|
||||
- States
|
||||
- Properties
|
||||
- Design tokens used
|
||||
5. MCP generates/updates WDS specification
|
||||
6. Designer reviews and confirms
|
||||
|
||||
---
|
||||
|
||||
### WDS → Figma
|
||||
|
||||
**When specification is updated in WDS:**
|
||||
|
||||
1. Specification updated in WDS
|
||||
2. Designer notified of changes
|
||||
3. Designer updates Figma component
|
||||
4. Designer confirms sync
|
||||
5. Node ID verified/updated
|
||||
|
||||
**Note:** This is semi-automated. Full automation requires Figma API write access.
|
||||
|
||||
---
|
||||
|
||||
## Quality Checklist
|
||||
|
||||
### Component Creation
|
||||
|
||||
- [ ] Component name follows convention
|
||||
- [ ] WDS component ID in description
|
||||
- [ ] All variants defined
|
||||
- [ ] All states documented
|
||||
- [ ] Auto layout properly configured
|
||||
- [ ] Design tokens used (not hardcoded values)
|
||||
- [ ] Accessibility notes included
|
||||
- [ ] Usage guidelines documented
|
||||
|
||||
### Variant Structure
|
||||
|
||||
- [ ] Variants organized by properties
|
||||
- [ ] Property names clear and consistent
|
||||
- [ ] All combinations make sense
|
||||
- [ ] No redundant variants
|
||||
- [ ] States properly differentiated
|
||||
|
||||
### Documentation
|
||||
|
||||
- [ ] Purpose clearly stated
|
||||
- [ ] When to use documented
|
||||
- [ ] When not to use documented
|
||||
- [ ] Accessibility requirements noted
|
||||
- [ ] Examples provided
|
||||
|
||||
---
|
||||
|
||||
## Common Mistakes to Avoid
|
||||
|
||||
### ❌ Mistake 1: Hardcoded Values
|
||||
|
||||
**Wrong:**
|
||||
```
|
||||
Background: #2563eb (hardcoded hex)
|
||||
Padding: 16px (hardcoded value)
|
||||
```
|
||||
|
||||
**Right:**
|
||||
```
|
||||
Background: primary/600 (variable)
|
||||
Padding: spacing/4 (variable)
|
||||
```
|
||||
|
||||
### ❌ Mistake 2: Detached Instances
|
||||
|
||||
**Wrong:**
|
||||
- Detaching component instances
|
||||
- Losing connection to main component
|
||||
- Manual updates required
|
||||
|
||||
**Right:**
|
||||
- Always use instances
|
||||
- Override only necessary properties
|
||||
- Maintain component connection
|
||||
|
||||
### ❌ Mistake 3: Inconsistent Naming
|
||||
|
||||
**Wrong:**
|
||||
```
|
||||
btn-primary
|
||||
ButtonSecondary
|
||||
button_ghost
|
||||
```
|
||||
|
||||
**Right:**
|
||||
```
|
||||
Button/Primary
|
||||
Button/Secondary
|
||||
Button/Ghost
|
||||
```
|
||||
|
||||
### ❌ Mistake 4: Missing States
|
||||
|
||||
**Wrong:**
|
||||
- Only default state
|
||||
- No hover/active states
|
||||
- No disabled state
|
||||
|
||||
**Right:**
|
||||
- All required states
|
||||
- Visual differentiation
|
||||
- State transitions documented
|
||||
|
||||
### ❌ Mistake 5: No WDS Component ID
|
||||
|
||||
**Wrong:**
|
||||
```
|
||||
Button Primary
|
||||
(no component ID)
|
||||
```
|
||||
|
||||
**Right:**
|
||||
```
|
||||
Button Primary [btn-001]
|
||||
(clear WDS mapping)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
### Button Component in Figma
|
||||
|
||||
**Component Name:** `Button/Primary [btn-001]`
|
||||
|
||||
**Description:**
|
||||
```
|
||||
Button Primary [btn-001]
|
||||
|
||||
Primary action button for main user actions.
|
||||
|
||||
WDS Component: Button.primary [btn-001]
|
||||
Variants: primary, secondary, ghost, outline
|
||||
States: default, hover, active, disabled, loading
|
||||
Sizes: small, medium, large
|
||||
```
|
||||
|
||||
**Variants:**
|
||||
```
|
||||
Type=Primary, Size=Medium, State=Default
|
||||
Type=Primary, Size=Medium, State=Hover
|
||||
Type=Primary, Size=Medium, State=Active
|
||||
Type=Primary, Size=Medium, State=Disabled
|
||||
Type=Primary, Size=Large, State=Default
|
||||
[... all combinations]
|
||||
```
|
||||
|
||||
**Properties:**
|
||||
- Auto Layout: Horizontal
|
||||
- Padding: 16px (horizontal), 12px (vertical)
|
||||
- Gap: 8px (if icon)
|
||||
- Border Radius: 8px
|
||||
- Background: primary/600 (variable)
|
||||
|
||||
---
|
||||
|
||||
### Input Component in Figma
|
||||
|
||||
**Component Name:** `Input/Text [inp-001]`
|
||||
|
||||
**Description:**
|
||||
```
|
||||
Input Text [inp-001]
|
||||
|
||||
Text input field for user data entry.
|
||||
|
||||
WDS Component: Input.text [inp-001]
|
||||
States: default, focus, filled, disabled, error, success
|
||||
```
|
||||
|
||||
**Variants:**
|
||||
```
|
||||
State=Default
|
||||
State=Focus
|
||||
State=Filled
|
||||
State=Disabled
|
||||
State=Error
|
||||
State=Success
|
||||
```
|
||||
|
||||
**Properties:**
|
||||
- Auto Layout: Horizontal
|
||||
- Padding: 12px
|
||||
- Height: 44px (fixed)
|
||||
- Border: 1px solid gray/300
|
||||
- Border Radius: 8px
|
||||
- Background: white
|
||||
|
||||
---
|
||||
|
||||
## Further Reading
|
||||
|
||||
- **Figma MCP Integration:** `figma-mcp-integration.md`
|
||||
- **Designer Guide:** `figma-designer-guide.md`
|
||||
- **Token Architecture:** `token-architecture.md`
|
||||
- **Component Boundaries:** `component-boundaries.md`
|
||||
|
||||
---
|
||||
|
||||
**This structure enables seamless Figma ↔ WDS integration and maintains design system consistency across tools.**
|
||||
|
|
@ -0,0 +1,181 @@
|
|||
# Design System Naming Conventions
|
||||
|
||||
**Purpose:** Consistent naming across design system components and tokens.
|
||||
|
||||
**Referenced by:** Component-type instructions, design system operations
|
||||
|
||||
---
|
||||
|
||||
## Component IDs
|
||||
|
||||
**Format:** `[type-prefix]-[number]`
|
||||
|
||||
**Prefixes:**
|
||||
- btn = Button
|
||||
- inp = Input Field
|
||||
- chk = Checkbox
|
||||
- rad = Radio
|
||||
- tgl = Toggle
|
||||
- drp = Dropdown
|
||||
- mdl = Modal
|
||||
- crd = Card
|
||||
- alt = Alert
|
||||
- bdg = Badge
|
||||
- tab = Tab
|
||||
- acc = Accordion
|
||||
|
||||
**Examples:**
|
||||
- `btn-001` = First button component
|
||||
- `inp-002` = Second input field component
|
||||
- `mdl-001` = First modal component
|
||||
|
||||
**Rules:**
|
||||
- Always lowercase
|
||||
- Always hyphenated
|
||||
- Always zero-padded (001, not 1)
|
||||
- Sequential within type
|
||||
|
||||
---
|
||||
|
||||
## Component Names
|
||||
|
||||
**Format:** `[Type] [Descriptor]` or just `[Type]`
|
||||
|
||||
**Examples:**
|
||||
- `Button` (generic)
|
||||
- `Navigation Button` (specific)
|
||||
- `Primary Button` (variant-focused)
|
||||
- `Icon Button` (visual-focused)
|
||||
|
||||
**Rules:**
|
||||
- Title case
|
||||
- Descriptive but concise
|
||||
- Avoid redundancy (not "Button Button")
|
||||
|
||||
---
|
||||
|
||||
## Variant Names
|
||||
|
||||
**Format:** Lowercase, hyphenated
|
||||
|
||||
**Purpose-Based:**
|
||||
- `primary` - Main action
|
||||
- `secondary` - Secondary action
|
||||
- `destructive` - Delete/remove
|
||||
- `success` - Positive confirmation
|
||||
- `warning` - Caution
|
||||
- `navigation` - Navigation action
|
||||
|
||||
**Visual-Based:**
|
||||
- `outlined` - Border, no fill
|
||||
- `ghost` - Transparent background
|
||||
- `solid` - Filled background
|
||||
|
||||
**Size-Based:**
|
||||
- `small` - Compact
|
||||
- `medium` - Default
|
||||
- `large` - Prominent
|
||||
|
||||
**Rules:**
|
||||
- Lowercase
|
||||
- Hyphenated for multi-word
|
||||
- Semantic over visual when possible
|
||||
|
||||
---
|
||||
|
||||
## State Names
|
||||
|
||||
**Standard States:**
|
||||
- `default` - Normal state
|
||||
- `hover` - Mouse over
|
||||
- `active` - Being clicked/pressed
|
||||
- `focus` - Keyboard focus
|
||||
- `disabled` - Cannot interact
|
||||
- `loading` - Processing
|
||||
- `error` - Error state
|
||||
- `success` - Success state
|
||||
- `warning` - Warning state
|
||||
|
||||
**Rules:**
|
||||
- Lowercase
|
||||
- Single word preferred
|
||||
- Use standard names when possible
|
||||
|
||||
---
|
||||
|
||||
## Design Token Names
|
||||
|
||||
**Format:** `--{category}-{property}-{variant}`
|
||||
|
||||
**Color Tokens:**
|
||||
```
|
||||
--color-primary-500
|
||||
--color-gray-900
|
||||
--color-success-600
|
||||
--color-error-500
|
||||
```
|
||||
|
||||
**Typography Tokens:**
|
||||
```
|
||||
--text-xs
|
||||
--text-base
|
||||
--text-4xl
|
||||
--font-normal
|
||||
--font-bold
|
||||
```
|
||||
|
||||
**Spacing Tokens:**
|
||||
```
|
||||
--spacing-1
|
||||
--spacing-4
|
||||
--spacing-8
|
||||
```
|
||||
|
||||
**Component Tokens:**
|
||||
```
|
||||
--button-padding-x
|
||||
--input-border-color
|
||||
--card-shadow
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
- Kebab-case
|
||||
- Hierarchical (general → specific)
|
||||
- Semantic names preferred
|
||||
|
||||
---
|
||||
|
||||
## File Names
|
||||
|
||||
**Component Files:**
|
||||
```
|
||||
button.md
|
||||
navigation-button.md
|
||||
input-field.md
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
- Lowercase
|
||||
- Hyphenated
|
||||
- Match component name (simplified)
|
||||
|
||||
---
|
||||
|
||||
## Folder Names
|
||||
|
||||
```
|
||||
components/
|
||||
design-tokens/
|
||||
operations/
|
||||
assessment/
|
||||
templates/
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
- Lowercase
|
||||
- Hyphenated
|
||||
- Plural for collections
|
||||
|
||||
---
|
||||
|
||||
**Consistency in naming makes the design system easier to navigate and maintain.**
|
||||
|
|
@ -0,0 +1,88 @@
|
|||
# Component State Management
|
||||
|
||||
**Purpose:** Guidelines for defining and managing component states.
|
||||
|
||||
**Referenced by:** Component-type instructions (Button, Input, etc.)
|
||||
|
||||
---
|
||||
|
||||
## Standard States
|
||||
|
||||
### Interactive Components (Buttons, Links)
|
||||
|
||||
**Required:**
|
||||
- `default` - Normal, ready for interaction
|
||||
- `hover` - Mouse over component
|
||||
- `active` - Being clicked/pressed
|
||||
- `disabled` - Cannot interact
|
||||
|
||||
**Optional:**
|
||||
- `loading` - Processing action
|
||||
- `focus` - Keyboard focus
|
||||
|
||||
### Form Components (Inputs, Selects)
|
||||
|
||||
**Required:**
|
||||
- `default` - Empty, ready for input
|
||||
- `focus` - Active input
|
||||
- `filled` - Has content
|
||||
- `disabled` - Cannot edit
|
||||
|
||||
**Optional:**
|
||||
- `error` - Validation failed
|
||||
- `success` - Validation passed
|
||||
- `loading` - Fetching data
|
||||
|
||||
### Feedback Components (Alerts, Toasts)
|
||||
|
||||
**Required:**
|
||||
- `default` - Neutral information
|
||||
- `success` - Positive feedback
|
||||
- `error` - Error feedback
|
||||
- `warning` - Caution feedback
|
||||
|
||||
---
|
||||
|
||||
## State Naming
|
||||
|
||||
**Use standard names:**
|
||||
- ✅ `hover` not `mouseover`
|
||||
- ✅ `disabled` not `inactive`
|
||||
- ✅ `loading` not `processing`
|
||||
|
||||
**Be consistent across components.**
|
||||
|
||||
---
|
||||
|
||||
## State Transitions
|
||||
|
||||
**Define how states change:**
|
||||
|
||||
```yaml
|
||||
Button States:
|
||||
default → hover (mouse enters)
|
||||
hover → active (mouse down)
|
||||
active → hover (mouse up)
|
||||
hover → default (mouse leaves)
|
||||
any → disabled (programmatically)
|
||||
any → loading (action triggered)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Visual Indicators
|
||||
|
||||
**Each state should be visually distinct:**
|
||||
|
||||
```yaml
|
||||
Button:
|
||||
default: blue background
|
||||
hover: darker blue + scale 1.02
|
||||
active: darkest blue + scale 0.98
|
||||
disabled: gray + opacity 0.6
|
||||
loading: disabled + spinner
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Reference this when specifying component states.**
|
||||
|
|
@ -0,0 +1,445 @@
|
|||
# Design Token Architecture
|
||||
|
||||
**Purpose:** Core principles for separating semantic structure from visual style.
|
||||
|
||||
**Referenced by:** All component-type instructions
|
||||
|
||||
---
|
||||
|
||||
## Core Principle
|
||||
|
||||
**Separate semantic structure from visual style.**
|
||||
|
||||
```
|
||||
HTML/Structure = Meaning (what it is)
|
||||
Design Tokens = Appearance (how it looks)
|
||||
|
||||
They should be independent!
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## The Problem
|
||||
|
||||
**Bad Practice:**
|
||||
```html
|
||||
<h2 class="text-4xl font-bold text-blue-600">
|
||||
Heading
|
||||
</h2>
|
||||
```
|
||||
|
||||
**Issues:**
|
||||
- Visual styling mixed with semantic HTML
|
||||
- Can't change h2 appearance without changing all h2s
|
||||
- h2 means "second-level heading" but looks like "display large"
|
||||
- Breaks separation of concerns
|
||||
|
||||
---
|
||||
|
||||
## The Solution
|
||||
|
||||
**Good Practice:**
|
||||
|
||||
**HTML (Semantic):**
|
||||
```html
|
||||
<h2 class="heading-section">
|
||||
Heading
|
||||
</h2>
|
||||
```
|
||||
|
||||
**Design Tokens (Visual):**
|
||||
```css
|
||||
.heading-section {
|
||||
font-size: var(--text-4xl);
|
||||
font-weight: var(--font-bold);
|
||||
color: var(--color-primary-600);
|
||||
}
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- Semantic HTML stays semantic
|
||||
- Visual style is centralized
|
||||
- Can change appearance without touching HTML
|
||||
- Clear separation of concerns
|
||||
|
||||
---
|
||||
|
||||
## Token Hierarchy
|
||||
|
||||
### Level 1: Raw Values
|
||||
```css
|
||||
--spacing-4: 1rem;
|
||||
--color-blue-600: #2563eb;
|
||||
--font-size-4xl: 2.25rem;
|
||||
```
|
||||
|
||||
### Level 2: Semantic Tokens
|
||||
```css
|
||||
--text-heading-large: var(--font-size-4xl);
|
||||
--color-primary: var(--color-blue-600);
|
||||
--spacing-section: var(--spacing-4);
|
||||
```
|
||||
|
||||
### Level 3: Component Tokens
|
||||
```css
|
||||
--button-padding-x: var(--spacing-section);
|
||||
--button-color-primary: var(--color-primary);
|
||||
--heading-size-section: var(--text-heading-large);
|
||||
```
|
||||
|
||||
**Use Level 2 or 3 in components, never Level 1 directly.**
|
||||
|
||||
---
|
||||
|
||||
## Application to WDS
|
||||
|
||||
### In Page Specifications
|
||||
|
||||
**Specify semantic structure:**
|
||||
```yaml
|
||||
Page Structure:
|
||||
- Section Heading (h2)
|
||||
- Body text (p)
|
||||
- Primary button (button)
|
||||
```
|
||||
|
||||
**NOT visual styling:**
|
||||
```yaml
|
||||
# ❌ Don't do this
|
||||
Page Structure:
|
||||
- Large blue bold text
|
||||
- 16px gray text
|
||||
- Blue rounded button
|
||||
```
|
||||
|
||||
### In Design System
|
||||
|
||||
**Specify visual styling:**
|
||||
```yaml
|
||||
Section Heading:
|
||||
html_element: h2
|
||||
design_token: heading-section
|
||||
|
||||
Design Token Definition:
|
||||
heading-section:
|
||||
font-size: text-4xl
|
||||
font-weight: bold
|
||||
color: primary-600
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Component-Type Instructions
|
||||
|
||||
### Text Heading Example
|
||||
|
||||
**When specifying a heading:**
|
||||
|
||||
1. **Identify semantic level** (h1-h6)
|
||||
- h1 = Page title
|
||||
- h2 = Section heading
|
||||
- h3 = Subsection heading
|
||||
- etc.
|
||||
|
||||
2. **Map to design token**
|
||||
- h1 → display-large
|
||||
- h2 → heading-section
|
||||
- h3 → heading-subsection
|
||||
|
||||
3. **Store separately**
|
||||
- Page spec: `<h2>` (semantic)
|
||||
- Design system: `heading-section` token (visual)
|
||||
|
||||
**Example Output:**
|
||||
|
||||
**Page Spec:**
|
||||
```yaml
|
||||
Hero Section:
|
||||
heading:
|
||||
element: h2
|
||||
token: heading-section
|
||||
content: "Welcome to Our Product"
|
||||
```
|
||||
|
||||
**Design System:**
|
||||
```yaml
|
||||
Tokens:
|
||||
heading-section:
|
||||
font-size: 2.25rem
|
||||
font-weight: 700
|
||||
line-height: 1.2
|
||||
color: gray-900
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Button Example
|
||||
|
||||
**When specifying a button:**
|
||||
|
||||
1. **Identify semantic element**
|
||||
- `<button>` for actions
|
||||
- `<a>` for navigation (even if styled as button)
|
||||
|
||||
2. **Map to component**
|
||||
- Action → Button component
|
||||
- Navigation → Link component (button variant)
|
||||
|
||||
3. **Store separately**
|
||||
- Page spec: `<button>` + purpose
|
||||
- Design system: Button component styling
|
||||
|
||||
**Example Output:**
|
||||
|
||||
**Page Spec:**
|
||||
```yaml
|
||||
Login Form:
|
||||
submit_button:
|
||||
element: button
|
||||
type: submit
|
||||
component: Button.primary
|
||||
label: "Log in"
|
||||
```
|
||||
|
||||
**Design System:**
|
||||
```yaml
|
||||
Button Component:
|
||||
variants:
|
||||
primary:
|
||||
background: primary-600
|
||||
color: white
|
||||
padding: spacing-2 spacing-4
|
||||
border-radius: radius-md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Input Field Example
|
||||
|
||||
**When specifying an input:**
|
||||
|
||||
1. **Identify semantic type**
|
||||
- `<input type="text">` for text
|
||||
- `<input type="email">` for email
|
||||
- `<input type="password">` for password
|
||||
|
||||
2. **Map to component**
|
||||
- Text input → Input Field component
|
||||
- Email input → Input Field.email variant
|
||||
|
||||
3. **Store separately**
|
||||
- Page spec: Input type + validation + labels
|
||||
- Design system: Input Field styling
|
||||
|
||||
**Example Output:**
|
||||
|
||||
**Page Spec:**
|
||||
```yaml
|
||||
Login Form:
|
||||
email_field:
|
||||
element: input
|
||||
type: email
|
||||
component: InputField.email
|
||||
label: "Email address"
|
||||
placeholder: "you@example.com"
|
||||
required: true
|
||||
validation: email_format
|
||||
```
|
||||
|
||||
**Design System:**
|
||||
```yaml
|
||||
Input Field Component:
|
||||
base_styling:
|
||||
height: 2.5rem
|
||||
padding: spacing-2 spacing-3
|
||||
border: 1px solid gray-300
|
||||
border-radius: radius-md
|
||||
font-size: text-base
|
||||
|
||||
variants:
|
||||
email:
|
||||
icon: envelope
|
||||
autocomplete: email
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Why This Matters
|
||||
|
||||
### For Designers
|
||||
|
||||
✅ **Consistency:** All h2s can look the same without manual styling
|
||||
✅ **Flexibility:** Change all section headings by updating one token
|
||||
✅ **Clarity:** Semantic meaning preserved
|
||||
✅ **Scalability:** Easy to maintain as design system grows
|
||||
|
||||
### For Developers
|
||||
|
||||
✅ **Semantic HTML:** Proper HTML structure
|
||||
✅ **Accessibility:** Screen readers understand structure
|
||||
✅ **Maintainability:** Styling centralized
|
||||
✅ **Performance:** Reusable styles
|
||||
|
||||
### For Design Systems
|
||||
|
||||
✅ **Single Source of Truth:** Tokens define appearance
|
||||
✅ **Easy Updates:** Change tokens, not components
|
||||
✅ **Consistency:** Automatic consistency across pages
|
||||
✅ **Documentation:** Clear token → component mapping
|
||||
|
||||
---
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
### Mistake 1: Mixing Structure and Style
|
||||
|
||||
**❌ Bad:**
|
||||
```yaml
|
||||
Page:
|
||||
- "Large blue heading" (h2)
|
||||
```
|
||||
|
||||
**✅ Good:**
|
||||
```yaml
|
||||
Page:
|
||||
- Section heading (h2 → heading-section token)
|
||||
```
|
||||
|
||||
### Mistake 2: Hardcoding Visual Values
|
||||
|
||||
**❌ Bad:**
|
||||
```yaml
|
||||
Button:
|
||||
background: #2563eb
|
||||
padding: 16px
|
||||
```
|
||||
|
||||
**✅ Good:**
|
||||
```yaml
|
||||
Button:
|
||||
background: primary-600
|
||||
padding: spacing-4
|
||||
```
|
||||
|
||||
### Mistake 3: Using Visual Names for Semantic Elements
|
||||
|
||||
**❌ Bad:**
|
||||
```yaml
|
||||
<h2 class="big-blue-text">
|
||||
```
|
||||
|
||||
**✅ Good:**
|
||||
```yaml
|
||||
<h2 class="section-heading">
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Token Naming Conventions
|
||||
|
||||
### Colors
|
||||
```
|
||||
--color-{category}-{shade}
|
||||
--color-primary-600
|
||||
--color-gray-900
|
||||
--color-success-500
|
||||
```
|
||||
|
||||
### Typography
|
||||
```
|
||||
--text-{size}
|
||||
--text-base
|
||||
--text-lg
|
||||
--text-4xl
|
||||
```
|
||||
|
||||
### Spacing
|
||||
```
|
||||
--spacing-{scale}
|
||||
--spacing-2
|
||||
--spacing-4
|
||||
--spacing-8
|
||||
```
|
||||
|
||||
### Component-Specific
|
||||
```
|
||||
--{component}-{property}-{variant}
|
||||
--button-padding-primary
|
||||
--input-border-error
|
||||
--card-shadow-elevated
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Implementation in WDS
|
||||
|
||||
### Phase 4: Page Specification
|
||||
|
||||
**Agent specifies:**
|
||||
- Semantic HTML elements
|
||||
- Component references
|
||||
- Content and labels
|
||||
|
||||
**Agent does NOT specify:**
|
||||
- Exact colors
|
||||
- Exact sizes
|
||||
- Exact spacing
|
||||
|
||||
### Phase 5: Design System
|
||||
|
||||
**Agent specifies:**
|
||||
- Design tokens
|
||||
- Component styling
|
||||
- Visual properties
|
||||
|
||||
**Agent does NOT specify:**
|
||||
- Page-specific content
|
||||
- Semantic structure
|
||||
|
||||
### Integration
|
||||
|
||||
**Page spec references design system:**
|
||||
```yaml
|
||||
Hero:
|
||||
heading:
|
||||
element: h2
|
||||
token: heading-hero ← Reference to design system
|
||||
content: "Welcome"
|
||||
```
|
||||
|
||||
**Design system defines token:**
|
||||
```yaml
|
||||
Tokens:
|
||||
heading-hero:
|
||||
font-size: 3rem
|
||||
font-weight: 800
|
||||
color: gray-900
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Company Customization
|
||||
|
||||
**Companies can fork WDS and customize tokens:**
|
||||
|
||||
```
|
||||
Company Fork:
|
||||
├── data/design-system/
|
||||
│ ├── token-architecture.md (this file - keep principles)
|
||||
│ ├── company-tokens.md (company-specific token values)
|
||||
│ └── token-mappings.md (h2 → company-heading-large)
|
||||
```
|
||||
|
||||
**Result:** Every project uses company's design tokens automatically.
|
||||
|
||||
---
|
||||
|
||||
## Further Reading
|
||||
|
||||
- **Naming Conventions:** `naming-conventions.md`
|
||||
- **Component Boundaries:** `component-boundaries.md`
|
||||
- **State Management:** `state-management.md`
|
||||
|
||||
---
|
||||
|
||||
**This is a core principle. Reference this document from all component-type instructions.**
|
||||
|
|
@ -0,0 +1,67 @@
|
|||
# Form Validation Patterns
|
||||
|
||||
**Purpose:** Standard patterns for form validation and error handling.
|
||||
|
||||
**Referenced by:** Input Field, Form component-type instructions
|
||||
|
||||
---
|
||||
|
||||
## Validation Types
|
||||
|
||||
### Client-Side Validation
|
||||
|
||||
**Required Fields:**
|
||||
```yaml
|
||||
validation:
|
||||
required: true
|
||||
message: "This field is required"
|
||||
```
|
||||
|
||||
**Format Validation:**
|
||||
```yaml
|
||||
validation:
|
||||
type: email
|
||||
pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/
|
||||
message: "Please enter a valid email address"
|
||||
```
|
||||
|
||||
**Length Validation:**
|
||||
```yaml
|
||||
validation:
|
||||
minLength: 8
|
||||
maxLength: 100
|
||||
message: "Password must be 8-100 characters"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error States
|
||||
|
||||
**Visual Indicators:**
|
||||
- Red border
|
||||
- Error icon
|
||||
- Error message below field
|
||||
- Error color for label
|
||||
|
||||
**Timing:**
|
||||
- Show on blur (after user leaves field)
|
||||
- Show on submit attempt
|
||||
- Clear on valid input
|
||||
|
||||
---
|
||||
|
||||
## Success States
|
||||
|
||||
**Visual Indicators:**
|
||||
- Green border (optional)
|
||||
- Success icon (optional)
|
||||
- Success message (optional)
|
||||
|
||||
**When to Show:**
|
||||
- After successful validation
|
||||
- For critical fields (password strength)
|
||||
- For async validation (username availability)
|
||||
|
||||
---
|
||||
|
||||
**Reference this when specifying form components.**
|
||||
|
|
@ -0,0 +1,143 @@
|
|||
# Phase 1: Product Exploration (Product Brief) (Project brief)
|
||||
|
||||
**Agent:** Saga the Analyst
|
||||
**Output:** `A-Product-Brief/` (or your configured prefix)
|
||||
|
||||
---
|
||||
|
||||
## What This Phase Does
|
||||
|
||||
Product Exploration establishes your strategic foundation through conversational discovery. Instead of filling out questionnaires, you have a conversation that builds understanding organically.
|
||||
|
||||
By the end, you'll have a Product Brief that captures your vision and serves as the north star for your entire project.
|
||||
|
||||
---
|
||||
|
||||
## What You'll Create
|
||||
|
||||
Your Product Brief includes:
|
||||
|
||||
- **Executive Summary** - The vision that inspires teams
|
||||
- **Problem Statement** - The "why" that drives decisions
|
||||
- **User Types** - The "who" that guides design (initial identification)
|
||||
- **Solution Approach** - The "how" that enables development
|
||||
- **Success Criteria** - The "what" that measures progress
|
||||
- **Market Positioning** - How you're different (optional: ICP framework)
|
||||
|
||||
---
|
||||
|
||||
## How It Works
|
||||
|
||||
### The Conversational Approach
|
||||
|
||||
Traditional requirements gathering treats people like databases - extracting answers through rigid questionnaires. WDS does it differently.
|
||||
|
||||
**Instead of:** "Please complete this 47-question requirements document"
|
||||
|
||||
**WDS says:** "Tell me about your project in your own words"
|
||||
|
||||
People light up when asked to share their vision. They become collaborators, not interrogation subjects.
|
||||
|
||||
### The Session Flow
|
||||
|
||||
**Opening (5-10 minutes)**
|
||||
|
||||
Saga asks about your project in your own words. She listens for:
|
||||
- What you emphasize naturally
|
||||
- Where your energy goes
|
||||
- What excites vs. what stresses you
|
||||
- Your exact language and terminology
|
||||
|
||||
**Exploration (15-30 minutes)**
|
||||
|
||||
The conversation adapts to what you reveal:
|
||||
- If you mention users → deeper into user insights
|
||||
- If you mention problems → explore the cost of not solving
|
||||
- If you mention competition → discover differentiation
|
||||
- If you mention timeline → understand urgency drivers
|
||||
|
||||
Each answer reveals the next question. It's jazz, not classical music.
|
||||
|
||||
**Synthesis (10-15 minutes)**
|
||||
|
||||
Saga reflects back your vision in organized form:
|
||||
- Connecting dots you shared across topics
|
||||
- Highlighting insights you might not have seen
|
||||
- Building the foundation for next phases
|
||||
|
||||
### Living Document
|
||||
|
||||
As you talk, the Product Brief grows in real-time:
|
||||
- Immediate validation and refinement
|
||||
- Real-time course correction
|
||||
- You own the content because you helped create it
|
||||
- "Yes, exactly!" moments that build trust
|
||||
|
||||
---
|
||||
|
||||
## When to Use This Phase
|
||||
|
||||
**Always start here if:**
|
||||
- Building something new
|
||||
- Starting a new project
|
||||
- Need strategic clarity before diving into design
|
||||
|
||||
**Skip if:**
|
||||
- You already have a clear, documented product brief
|
||||
- Just enhancing an existing feature
|
||||
- Working on a design system without new product context
|
||||
|
||||
---
|
||||
|
||||
## What to Prepare
|
||||
|
||||
Come ready to share:
|
||||
- Your project idea (even if rough)
|
||||
- The problem you're solving
|
||||
- Who might use it
|
||||
- Why it matters to you
|
||||
|
||||
You don't need polished answers. The conversation will help clarify everything.
|
||||
|
||||
---
|
||||
|
||||
## What Comes Next
|
||||
|
||||
Your Product Brief enables:
|
||||
|
||||
- **Phase 2: User Research** - Deeper into user psychology with your strategic context
|
||||
- **Phase 3: Requirements** - Technical decisions aligned with your vision
|
||||
- **Phase 4: UX Design** - Design work grounded in strategic purpose
|
||||
|
||||
The brief becomes the reference point everyone shares.
|
||||
|
||||
---
|
||||
|
||||
## Tips for Great Sessions
|
||||
|
||||
**Let the conversation flow**
|
||||
- Share what feels important, even if it seems tangential
|
||||
- Follow your energy - where you're excited matters
|
||||
|
||||
**Think out loud**
|
||||
- Half-formed thoughts are welcome
|
||||
- will help you refine them
|
||||
|
||||
**Be honest about uncertainty**
|
||||
- "I'm not sure about X" is useful information
|
||||
- Better to surface doubts now than later
|
||||
|
||||
**Review as you go**
|
||||
- Check that what's captured matches your thinking
|
||||
- Correct misunderstandings immediately
|
||||
|
||||
---
|
||||
|
||||
## Example Output
|
||||
|
||||
See: `examples/dog-week-patterns/A-Product-Brief/` for a complete Product Brief example from a real project.
|
||||
|
||||
---
|
||||
|
||||
*Phase 1 of the Whiteport Design Studio method*
|
||||
|
||||
|
|
@ -0,0 +1,302 @@
|
|||
# Phase 2: Trigger map
|
||||
|
||||
**Agent:** Saga the Analyst
|
||||
**Output:** `B-Trigger-Map/` (or your configured prefix)
|
||||
|
||||
---
|
||||
|
||||
## What This Phase Does
|
||||
|
||||
User Research connects business goals to user psychology through Trigger Mapping. You discover not just WHO your users are, but WHY they act and WHAT triggers their decisions.
|
||||
|
||||
By the end, you'll have a Trigger Map that visually shows how user success drives business success.
|
||||
|
||||
---
|
||||
|
||||
## What You'll Create
|
||||
|
||||
Your Trigger Map includes:
|
||||
|
||||
- **Business Goals** - What success looks like for your organization
|
||||
- **Target Groups** - User types who can help achieve those goals
|
||||
- **Personas** - Detailed profiles with psychological depth
|
||||
- **Usage Goals** - What users want vs. what they fear
|
||||
- **Visual Trigger Map** - Diagram connecting all the pieces
|
||||
- **Priority Rankings** - Which goals, users, and drivers matter most
|
||||
- **Feature Impact Analysis** - Scored feature list ranked by strategic value
|
||||
|
||||
---
|
||||
|
||||
## From Effect Mapping to Trigger Mapping
|
||||
|
||||
WDS Trigger Mapping is based on the groundbreaking **Effect Management** methodology from inUse, Sweden.
|
||||
|
||||
### Credits & Foundation
|
||||
|
||||
**Effect Management** was created by **Mijo Balic** and **Ingrid Domingues (Ottersten)** at **inUse**, Sweden. Their pioneering work on connecting business goals to user behavior through visual mapping - the **Effect Map** - laid the foundation for how we think about strategic software design.
|
||||
|
||||
The methodology gained wider recognition through Gojko Adzic's book **"Impact Mapping: Making a Big Impact with Software Products and Projects"** (2012), which acknowledges Effect Mapping as a key influence.
|
||||
|
||||
> **Founder's Note:** I personally acquired the insights about the power of the Effect Map back in 2007, and it has served as the philosophical basis for all of my work in UX for almost 20 years. I am eternally grateful for this model that I now have the pleasure to share with the world in an updated version suitable for modern projects.
|
||||
> — *Martin Eriksson, WDS Creator*
|
||||
|
||||
📚 **Further Reading:**
|
||||
- [Impact Mapping on Amazon](https://www.amazon.com/Impact-Mapping-Software-Products-Projects/dp/0955683645) - Gojko Adzic's book building on Effect Mapping concepts
|
||||
- [impactmapping.org](https://www.impactmapping.org) - Resources and community
|
||||
|
||||
### What is Effect Mapping?
|
||||
|
||||
Effect Mapping is the original model that connects business goals to user behavior through a visual map. It includes business goals, target groups, usage goals, and the specific actions/features that enable those goals.
|
||||
|
||||
### What is Trigger Mapping?
|
||||
|
||||
Trigger Mapping is WDS's adaptation of Effect Mapping, designed for longer shelf life and deeper psychological insight:
|
||||
|
||||
**Simplified:**
|
||||
- Leaves out actions/features from the map
|
||||
- Focuses on the strategic connections
|
||||
- Map stays relevant even as features evolve
|
||||
|
||||
**Enhanced:**
|
||||
- Adds **negative driving forces** (fears, frustrations)
|
||||
- Creates fuller picture of user psychology
|
||||
- Both what users want AND what they want to avoid
|
||||
|
||||
### The Core Insight
|
||||
|
||||
Any software is about **flow of value**. There's always a group of people who, through their use of the software, make your success happen.
|
||||
|
||||
These users have their own goals:
|
||||
- **GAIN** - Benefits and positive outcomes they achieve
|
||||
- **PAIN** - Resistance and friction they experience
|
||||
|
||||
**The key:** Make GAIN > PAIN for users, so through their usage, they add value to your system.
|
||||
|
||||
### The Three Layers
|
||||
|
||||
The Trigger Map combines three critical layers in one picture:
|
||||
|
||||
1. **Business Goals** - Your WHY (Vision that motivates, and SMART objectives that measure success)
|
||||
2. **Target Groups** - The WHO (User types whose success drives your success)
|
||||
3. **Usage Goals** - Their WHY (Driving forces both positive - what they wish to achieve, and negative - what they wish to avoid)
|
||||
|
||||
When all levels are then prioritized, you have perfect guidance for design:
|
||||
- Present features that add value to your most prioritized goal first
|
||||
- To the highest prioritized target group
|
||||
- In a way that best suits their most prioritized usage goal
|
||||
- Make sound decisions about priority of bugs or features based on the total impact on users' goals
|
||||
|
||||
---
|
||||
|
||||
## How It Works
|
||||
|
||||
### Stage 1: Business Goals (15-20 minutes)
|
||||
|
||||
Starting question: "Looking at your product brief, what does 'winning' look like for your organization?"
|
||||
|
||||
Business goals work at two levels:
|
||||
|
||||
**Vision (Motivating, not easily quantifiable)**
|
||||
A statement that inspires and guides direction:
|
||||
- "Become the most popular free and open source design support framework"
|
||||
- "Be the go-to partner for SMB digital transformation"
|
||||
- "Make professional UX accessible to every startup"
|
||||
|
||||
**Objectives (SMART metrics)**
|
||||
Specific, measurable targets that indicate progress toward the vision:
|
||||
- "10,000 active designer users by 2027"
|
||||
- "100 community contributions accepted by Q4 2026"
|
||||
- "50% of users complete full 6-phase workflow"
|
||||
- "NPS score of 60+ from design professionals"
|
||||
|
||||
You'll define both levels:
|
||||
- Vision that motivates the team
|
||||
- Objectives with clear success metrics
|
||||
|
||||
### Stage 2: Target Groups (20-30 minutes)
|
||||
|
||||
Key question: "Who needs to succeed for YOU to succeed?"
|
||||
|
||||
Instead of demographics, you discover:
|
||||
- User types who can drive business success
|
||||
- The role each type plays in your strategy
|
||||
- How different users contribute differently
|
||||
- Why each user type matters to business goals
|
||||
|
||||
Users become strategic assets, not just audience segments.
|
||||
|
||||
### Stage 3: Psychological Deep Dive (30-40 minutes)
|
||||
|
||||
For each user type:
|
||||
|
||||
"When this user type is at their best - when they're succeeding - what are they accomplishing? What are they feeling?"
|
||||
|
||||
"Now the flip side: What do they desperately want to avoid? What would feel like failure?"
|
||||
|
||||
This reveals:
|
||||
- **Positive Triggers** - What motivates action
|
||||
- **Negative Triggers** - What prevents engagement
|
||||
- **Emotional Drivers** - The psychology behind decisions
|
||||
- **Behavioral Patterns** - When and why they act
|
||||
|
||||
### Stage 4: Visual Strategy Map (15-20 minutes)
|
||||
|
||||
Saga helps build the complete trigger map:
|
||||
- Connecting every user insight to business goals
|
||||
- Creating the visual strategy guide
|
||||
- Validating the strategic logic together
|
||||
|
||||
### Stage 5: Prioritization (20-30 minutes)
|
||||
|
||||
This stage is critical for shaping the final product concept. You systematically prioritize each column of the Trigger Map.
|
||||
|
||||
**The Prioritization Process:**
|
||||
|
||||
1. **Rank Business Goals** - Which goal matters most right now? Which is secondary?
|
||||
2. **Rank Target Groups** - Which user types have the most impact on your top goal?
|
||||
3. **Rank Usage Goals** - For your top users, which driving forces are most urgent?
|
||||
|
||||
**Why This Matters:**
|
||||
|
||||
Different prioritizations lead to fundamentally different products. The same Trigger Map can produce wildly different concepts depending on what you prioritize first.
|
||||
|
||||
### Stage 6: Feature Impact Analysis (20-30 minutes)
|
||||
|
||||
Now the magic happens. You connect strategy to concrete features using a systematic impact scoring approach.
|
||||
|
||||
**The Process:**
|
||||
|
||||
1. **Gather Feature Ideas** - Pull from your Product Brief, stakeholder input, and brainstorming
|
||||
2. **Map to Target Groups** - For each feature, identify which target groups it serves
|
||||
3. **Map to Driving Forces** - Which positive and negative drivers does it address?
|
||||
4. **Score the Impact** - Features serving multiple groups and drivers score higher
|
||||
|
||||
**The Scoring System:** *(Beta - refinements welcome)*
|
||||
|
||||
For each feature, award points:
|
||||
|
||||
| Impact | Points |
|
||||
|--------|--------|
|
||||
| Serves Priority 1 Target Group | +3 |
|
||||
| Serves Priority 2 Target Group | +2 |
|
||||
| Serves Priority 3 Target Group | +1 |
|
||||
| Addresses Priority 1 Positive Driver | +3 |
|
||||
| Addresses Priority 2 Positive Driver | +2 |
|
||||
| Addresses Priority 3 Positive Driver | +1 |
|
||||
| **Addresses Priority 1 Negative Driver** | **+4** |
|
||||
| **Addresses Priority 2 Negative Driver** | **+3** |
|
||||
| **Addresses Priority 3 Negative Driver** | **+2** |
|
||||
| Serves multiple target groups | +2 bonus |
|
||||
| Addresses both positive AND negative drivers | +2 bonus |
|
||||
|
||||
> **Why negative drivers score higher:** Loss aversion is a well-documented psychological principle - humans work harder to avoid pain than to pursue gain. Features that remove friction, fear, or frustration create stronger user loyalty than features that simply add benefits.
|
||||
|
||||
**Example:**
|
||||
|
||||
| Feature | Target Groups | Driving Forces | Score |
|
||||
|---------|---------------|----------------|-------|
|
||||
| One-click booking | P1 Dog Owner (+3), P2 Walker (+2) | Convenience (+3), Fear of complexity (-P1: +4), Multi-group (+2), Both types (+2) | **16** |
|
||||
| Review system | P1 Dog Owner (+3) | Trust (+2), Fear of bad walker (-P1: +4), Both types (+2) | **11** |
|
||||
| Calendar sync | P2 Walker (+2) | Efficiency (+1) | **3** |
|
||||
|
||||
**The Output:**
|
||||
|
||||
A ranked feature list showing:
|
||||
- Which features have the broadest impact
|
||||
- Which features are "single-purpose" vs "multi-impact"
|
||||
- Natural MVP candidates (highest scores)
|
||||
- Features to defer (low scores but still valuable)
|
||||
|
||||
**Why This Works:**
|
||||
|
||||
Features that resonate with multiple target groups and address multiple driving forces are inherently more valuable. They create more value per development effort and satisfy more users simultaneously.
|
||||
|
||||
---
|
||||
|
||||
## Personas with Depth
|
||||
|
||||
Traditional personas describe demographics: "Jennifer, 34, likes yoga and lattes."
|
||||
|
||||
WDS personas capture psychology:
|
||||
|
||||
**Alliterative Naming** - Each persona gets a memorable name that hints at their role:
|
||||
- "Patrick the Professional" - Decision-maker focused on efficiency
|
||||
- "Sophie the Socializer" - Values connection and community
|
||||
- "Tyler the Technical" - Wants control and customization
|
||||
|
||||
**What Each Persona Includes:**
|
||||
- Role and context
|
||||
- Goals they're trying to achieve
|
||||
- Fears and frustrations
|
||||
- How they'd describe their problem
|
||||
- What success looks like to them
|
||||
- Triggers that motivate action
|
||||
|
||||
---
|
||||
|
||||
## When to Use This Phase
|
||||
|
||||
**Use after Phase 1 if:**
|
||||
- Building a new product
|
||||
- Need clarity on who you're building for
|
||||
- Want design decisions grounded in user psychology
|
||||
|
||||
**Start here if:**
|
||||
- You have product vision but unclear user strategy
|
||||
- Existing personas feel shallow or unused
|
||||
- Features aren't connecting with users
|
||||
|
||||
**Skip if:**
|
||||
- Quick enhancement to existing feature
|
||||
- Users are already well-documented and validated
|
||||
- Design system work without new user research
|
||||
|
||||
---
|
||||
|
||||
## What to Prepare
|
||||
|
||||
Bring:
|
||||
- Your completed Product Brief (Phase 1)
|
||||
- Any existing user research (even informal)
|
||||
- Stakeholder availability for the workshop
|
||||
|
||||
---
|
||||
|
||||
## What Comes Next
|
||||
|
||||
Your Trigger Map enables:
|
||||
|
||||
- **Phase 3: Requirements** - Technical decisions aligned with user priorities
|
||||
- **Phase 4: UX Design** - Design work grounded in user psychology
|
||||
- **Development priorities** - Clear guidance on what to build first
|
||||
|
||||
The trigger map becomes the strategic brain of your product.
|
||||
|
||||
---
|
||||
|
||||
## Tips for Great Sessions
|
||||
|
||||
**Think strategically, not demographically**
|
||||
- "Who needs to win for us to win?" not "Who might use this?"
|
||||
- Connect every user insight to business outcomes
|
||||
|
||||
**Go deep on psychology**
|
||||
- Push beyond surface responses
|
||||
- Ask "why" multiple times
|
||||
- Understand motivations, not just behaviors
|
||||
|
||||
**Build the map live**
|
||||
- See connections as they emerge
|
||||
- Validate strategic logic together
|
||||
- Make it visual and shareable
|
||||
|
||||
---
|
||||
|
||||
## Example Output
|
||||
|
||||
See: `examples/dog-week-patterns/B-Trigger-Map/` for a complete Trigger Map with personas from a real project.
|
||||
|
||||
---
|
||||
|
||||
*Phase 2 of the Whiteport Design Studio method*
|
||||
|
||||
|
|
@ -0,0 +1,269 @@
|
|||
# Phase 3: PRD Platform (Technical Foundation)
|
||||
|
||||
**Agent:** Freyja the PM
|
||||
**Output:** `C-Requirements/` (or your configured prefix)
|
||||
|
||||
---
|
||||
|
||||
## What This Phase Does
|
||||
|
||||
This phase establishes everything technical that can be done **without the final UI**. It's about platform decisions, technical feasibility, and proving that your innovative features actually work.
|
||||
|
||||
By the end, you'll have a solid technical foundation and confidence that your key features are buildable.
|
||||
|
||||
---
|
||||
|
||||
## The Core Principle
|
||||
|
||||
**Prove our concept works technically — in parallel with design work.**
|
||||
|
||||
While UX designers explore how users interact with features, technical validation runs alongside:
|
||||
- Can we actually build this?
|
||||
- Do the external services we need exist and work as expected?
|
||||
- What platform and infrastructure do we need?
|
||||
- What constraints does design need to know about?
|
||||
|
||||
Design and technical validation inform each other. Neither waits for the other to finish.
|
||||
|
||||
---
|
||||
|
||||
## What You'll Create
|
||||
|
||||
- **Platform Architecture** - Technology stack and infrastructure decisions
|
||||
- **Data Model** - Core entities and relationships
|
||||
- **Integration Map** - External services and how they connect
|
||||
- **Technical Proofs of Concept** - Validation that risky features work
|
||||
- **Experimental Endpoints** - API specs for known requirements (feeds into E-UI-Roadmap)
|
||||
- **Security Framework** - Authentication, authorization, data protection
|
||||
- **Technical Constraints Document** - What design needs to know
|
||||
|
||||
---
|
||||
|
||||
## How It Works
|
||||
|
||||
### Stage 1: Platform Decisions (30-45 minutes)
|
||||
|
||||
Establish the technical foundation:
|
||||
|
||||
**Architecture:**
|
||||
- What technology stack fits your needs?
|
||||
- Monolith vs. microservices vs. serverless?
|
||||
- What hosting/infrastructure approach?
|
||||
- What are the key technical constraints?
|
||||
|
||||
**Data Model:**
|
||||
- What are the core entities?
|
||||
- How do they relate to each other?
|
||||
- What's the database strategy?
|
||||
|
||||
### Stage 2: Integration Mapping (20-30 minutes)
|
||||
|
||||
Identify all external dependencies:
|
||||
|
||||
- Authentication providers (OAuth, SSO)
|
||||
- Payment systems (Stripe, PayPal)
|
||||
- Third-party APIs (Google Maps, SendGrid, Twilio)
|
||||
- Data sources and feeds
|
||||
- Analytics and monitoring
|
||||
|
||||
### Stage 3: Technical Proofs of Concept (Variable)
|
||||
|
||||
**This is crucial.** For innovative or risky features, validate feasibility BEFORE committing to the design.
|
||||
|
||||
**Examples:**
|
||||
|
||||
| Feature Idea | Proof of Concept Question |
|
||||
|--------------|---------------------------|
|
||||
| "Show drive time between locations" | Can we call Google Maps Directions API and get estimated duration? |
|
||||
| "Real-time availability updates" | Can we set up WebSocket connections that scale? |
|
||||
| "AI-powered recommendations" | Does the ML model perform well enough with our data? |
|
||||
| "Offline mode" | Can we sync data reliably when connection returns? |
|
||||
| "Video calling" | Which provider works best? What's the latency? |
|
||||
|
||||
**What a PoC validates:**
|
||||
- The API/service exists and does what we need
|
||||
- Performance is acceptable
|
||||
- Cost is within budget
|
||||
- Data format works for our needs
|
||||
- Edge cases are handleable
|
||||
|
||||
**PoC Output:**
|
||||
- Working code snippet or prototype
|
||||
- Documented limitations and gotchas
|
||||
- Cost estimates (API calls, compute, etc.)
|
||||
- Go/No-Go recommendation for the feature
|
||||
|
||||
> **Why this matters:** It's a great morale boost when you've proven your core features will work. And if you discover limitations or surprises, it's valuable to know them early so design can account for them from the start.
|
||||
|
||||
### Stage 4: Security & Performance Framework (20-30 minutes)
|
||||
|
||||
**Security:**
|
||||
- Authentication approach (passwords, OAuth, SSO, passwordless)
|
||||
- Authorization model (roles, permissions, row-level security)
|
||||
- Data encryption needs (at rest, in transit)
|
||||
- Compliance requirements (GDPR, HIPAA, PCI-DSS, etc.)
|
||||
|
||||
**Performance:**
|
||||
- Expected load and scale
|
||||
- Response time expectations
|
||||
- Availability requirements (99.9%? 99.99%?)
|
||||
- Caching strategy
|
||||
|
||||
### Stage 5: Experimental Endpoints (Variable)
|
||||
|
||||
**Set up the endpoints you KNOW you'll need.**
|
||||
|
||||
Even before the UI is designed, you often know certain data operations are essential. Setting these up early provides:
|
||||
|
||||
- **Early validation** - Does the endpoint actually return what we need?
|
||||
- **Fail fast** - Discover problems before investing in design
|
||||
- **Developer head start** - Backend work can begin immediately
|
||||
- **Design confidence** - Designers know what data is available
|
||||
|
||||
**What to set up:**
|
||||
|
||||
| Endpoint Type | Example | Why Early? |
|
||||
|---------------|---------|------------|
|
||||
| Core CRUD | `GET /api/dogs`, `POST /api/bookings` | Foundation for everything |
|
||||
| External integrations | `GET /api/routes/estimate` (Google Maps) | Validates third-party works |
|
||||
| Authentication | `/api/auth/login`, `/api/auth/refresh` | Security model proven |
|
||||
| Key calculations | `/api/availability/check` | Business logic validated |
|
||||
|
||||
**Output:**
|
||||
|
||||
For each experimental endpoint, document:
|
||||
- Endpoint specification (method, path, request/response)
|
||||
- What it validates
|
||||
- Current status (stub, working, blocked)
|
||||
- Dependencies and notes
|
||||
|
||||
These specifications go in your Requirements folder AND become tasks in the `E-UI-Roadmap/` handover folder for development teams.
|
||||
|
||||
> **The mindset:** Every endpoint you validate early is one less surprise during development. Every endpoint that fails early saves weeks of wasted design work.
|
||||
|
||||
### Stage 6: Technical Constraints Document (15-20 minutes)
|
||||
|
||||
Create a summary of what UX design needs to know:
|
||||
|
||||
- **What's possible** - Features validated by PoCs
|
||||
- **What's not possible** - Technical limitations discovered
|
||||
- **What's expensive** - Features with high API/compute costs
|
||||
- **What affects design** - Loading times, offline behavior, real-time vs. polling
|
||||
- **Platform capabilities** - What the framework/platform provides out of the box
|
||||
|
||||
This document becomes essential input for Phase 4 (UX Design).
|
||||
|
||||
---
|
||||
|
||||
## The Design Connection
|
||||
|
||||
Phase 3 is informed by:
|
||||
|
||||
- **Product Brief** (Phase 1) - Strategic vision and constraints
|
||||
- **Trigger Map** (Phase 2) - Prioritized features from Feature Impact Analysis
|
||||
|
||||
And it enables:
|
||||
|
||||
- **UX Design** (Phase 4) - Design within known technical constraints
|
||||
- **Design System** (Phase 5) - Component technical requirements
|
||||
- **Development** - Platform work can begin in parallel with design
|
||||
|
||||
---
|
||||
|
||||
## Parallel Streams
|
||||
|
||||
Once Phase 3 is complete:
|
||||
|
||||
```
|
||||
Phase 3 Complete
|
||||
│
|
||||
├──► E-UI-Roadmap/ receives:
|
||||
│ • Experimental endpoint specs
|
||||
│ • API implementation tasks
|
||||
│ • Infrastructure setup tasks
|
||||
│
|
||||
├──► Platform/Backend Development can START
|
||||
│ (Infrastructure, APIs, data model)
|
||||
│
|
||||
└──► Phase 4: UX Design can START
|
||||
(Informed by technical constraints)
|
||||
```
|
||||
|
||||
This parallelism is one of WDS's key efficiency gains. Development teams can begin backend work while designers continue with UX.
|
||||
|
||||
---
|
||||
|
||||
## When to Use This Phase
|
||||
|
||||
**Use this phase when:**
|
||||
- Building platform/infrastructure for a new product
|
||||
- Features depend on external APIs or services
|
||||
- Innovative features need technical validation
|
||||
- Development team needs architectural clarity before design
|
||||
|
||||
**Skip or minimize if:**
|
||||
- Simple project with obvious technical approach
|
||||
- Working within existing platform/infrastructure
|
||||
- Enhancement that doesn't change architecture
|
||||
- All features use proven, familiar technology
|
||||
|
||||
---
|
||||
|
||||
## What to Prepare
|
||||
|
||||
Bring:
|
||||
- Product Brief (Phase 1)
|
||||
- Trigger Map with Feature Impact Analysis (Phase 2)
|
||||
- Any existing technical constraints
|
||||
- Development team availability for PoC work
|
||||
|
||||
---
|
||||
|
||||
## What Comes Next
|
||||
|
||||
Your technical foundation enables:
|
||||
|
||||
- **Phase 4: UX Design** - Design with confidence about what's technically possible
|
||||
- **Phase 6: Dev Integration** - Handoff with complete technical context
|
||||
- **Development** - Backend/platform work can begin immediately
|
||||
|
||||
---
|
||||
|
||||
## Tips for Great Sessions
|
||||
|
||||
**Validate risky features first**
|
||||
- If the Google Maps API doesn't return drive times in a usable format, you need to know NOW
|
||||
- Don't design features you can't build
|
||||
|
||||
**Document constraints clearly**
|
||||
- Designers need to know what's possible
|
||||
- "Loading state required" vs "instant" changes UX significantly
|
||||
|
||||
**Involve developers**
|
||||
- Technical decisions benefit from dev input
|
||||
- PoC work may require developer time
|
||||
- Architecture is a conversation, not a decree
|
||||
|
||||
**Stay connected to strategy**
|
||||
- Reference Feature Impact Analysis scores
|
||||
- High-impact features deserve more PoC investment
|
||||
- Don't over-engineer for hypothetical needs
|
||||
|
||||
---
|
||||
|
||||
## Example Output
|
||||
|
||||
See: `examples/dog-week-patterns/C-Requirements/` for the Dog Week technical foundation.
|
||||
|
||||
**What Dog Week needed to prove early:**
|
||||
|
||||
- *"Can we show dog owners how long it takes to walk to a dog walker?"* → Google Maps Directions API returns walking time between coordinates ✓
|
||||
- *"Can we check real-time availability across multiple walkers?"* → Endpoint aggregates calendar data in <200ms ✓
|
||||
- *"Can we handle Swish payments for Swedish users?"* → Swish API integration validated with test transactions ✓
|
||||
- *"Can walkers see their schedule on mobile?"* → Responsive calendar component renders correctly on iOS/Android browsers ✓
|
||||
|
||||
These early discoveries shaped both the design AND the development approach.
|
||||
|
||||
---
|
||||
|
||||
*Phase 3 of the Whiteport Design Studio method*
|
||||
|
|
@ -0,0 +1,296 @@
|
|||
# Phase 4: UX Design (UX-Sketches & Usage Scenarios)
|
||||
|
||||
**Agent:** Baldr the UX Expert
|
||||
**Output:** `C-Scenarios/` (or your configured prefix)
|
||||
|
||||
---
|
||||
|
||||
## What This Phase Does
|
||||
|
||||
UX Design transforms ideas into detailed visual specifications. Working with Baldr, you conceptualize, sketch, and specify every interaction until your design can be logically explained without gaps.
|
||||
|
||||
**The key insight:** Designs that can be logically explained without gaps are easy to develop. The specification process reveals gaps in your thinking early - when they're easy to address.
|
||||
|
||||
---
|
||||
|
||||
## What You'll Create
|
||||
|
||||
For each scenario/page:
|
||||
|
||||
- **Scenario Structure** - Numbered folder hierarchy
|
||||
- **Page Specifications** - Complete documentation of each screen
|
||||
- **Component Definitions** - Every element with Object IDs
|
||||
- **Interaction Behaviors** - What happens when users interact
|
||||
- **State Definitions** - All possible states for dynamic elements
|
||||
- **Multilingual Content** - Text in all supported languages
|
||||
- **HTML Prototypes** - Interactive prototypes for validation
|
||||
|
||||
---
|
||||
|
||||
## How Baldr the UX Expert helps you design software
|
||||
|
||||
### 4A: Scenario Exploration
|
||||
**When:** Discovering the Concept, the process, flow screen or component solution together, before sketching begin
|
||||
|
||||
Baldr helps you:
|
||||
- Think through the user's journey
|
||||
- Explore content and feature options
|
||||
- Consider psychological triggers from your Trigger Map
|
||||
- Arrive at a clear solution ready for sketching
|
||||
|
||||
### 4B: UI Sketch Analysis
|
||||
**When:** You have a sketch and you need feedback on it
|
||||
|
||||
Baldr helps you:
|
||||
- Analyze what the sketch shows
|
||||
- Ask clarifying questions
|
||||
- Identify all components and states
|
||||
|
||||
### 4C: Conceptual Specification
|
||||
**When:** Design is clear, need development-ready specs
|
||||
|
||||
Baldr helps you:
|
||||
- Document every detail systematically
|
||||
- Assign Object IDs for testing
|
||||
- Define all interactions and states
|
||||
- Prepare multilingual content, error codes, instructions and any other content needed for the developers
|
||||
|
||||
### 4D: HTML Prototype
|
||||
**When:** Specifications complete, and we make the sketch come alive to test the concept
|
||||
|
||||
Baldr helps you:
|
||||
- Create interactive prototypes
|
||||
- Test the design in browser
|
||||
- Discover gaps and issues
|
||||
- Refine specifications
|
||||
- Visualize the concept before development
|
||||
|
||||
### 4E: PRD Update
|
||||
**When:** Page design is complete, before moving to the next scenario
|
||||
|
||||
Baldr helps you:
|
||||
- Identify what features this page requires
|
||||
- Add functional requirements to the PRD
|
||||
- Reference the page (e.g., "Required by: 2.1-Dog-Calendar")
|
||||
- Note any API endpoints, validations, or data needs discovered
|
||||
|
||||
**Why this step matters:**
|
||||
|
||||
Each page reveals concrete requirements:
|
||||
- "This form needs email validation"
|
||||
- "We need a GET endpoint for availability"
|
||||
- "Users need to upload images here"
|
||||
|
||||
Capturing these while the page is fresh ensures nothing is forgotten. The PRD becomes a complete feature inventory with traceability to the pages that need each feature.
|
||||
|
||||
**PRD grows like this:**
|
||||
|
||||
```markdown
|
||||
## Functional Requirements
|
||||
|
||||
### Email Validation
|
||||
**Required by:** 1.2-Sign-Up, 2.3-Profile-Edit
|
||||
- Validate format on input
|
||||
- Check domain exists
|
||||
- Prevent duplicates
|
||||
|
||||
### Availability Calendar API
|
||||
**Required by:** 2.1-Dog-Calendar, 3.1-Booking-Flow
|
||||
- GET /api/walkers/{id}/availability
|
||||
- Returns 2-week window
|
||||
- Updates via WebSocket
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## The Scenario Structure
|
||||
|
||||
Scenarios organize your design work into a clear hierarchy:
|
||||
|
||||
```
|
||||
C-Scenarios/
|
||||
├── 00-Scenario-Overview.md
|
||||
├── 01-User-Onboarding/
|
||||
│ ├── 1.1-Start-Page/
|
||||
│ │ ├── 1.1-Start-Page.md
|
||||
│ │ ├── Sketches/
|
||||
│ │ └── Prototype/
|
||||
│ └── 1.2-Sign-Up/
|
||||
│ ├── 1.2-Sign-Up.md
|
||||
│ └── ...
|
||||
├── 02-Core-Feature/
|
||||
│ └── ...
|
||||
```
|
||||
|
||||
**Numbering Convention:**
|
||||
- Scenarios: 01, 02, 03...
|
||||
- Pages within scenarios: 1.1, 1.2, 2.1, 2.2...
|
||||
|
||||
---
|
||||
|
||||
## Object IDs
|
||||
|
||||
Every interactive element gets an Object ID for:
|
||||
- Consistent naming across specs and code
|
||||
- Test automation with stable selectors
|
||||
- Analytics tracking
|
||||
- Design-dev communication
|
||||
|
||||
**Format:** `{page}-{section}-{element}` in kebab-case
|
||||
|
||||
**Example:**
|
||||
```
|
||||
welcome-page-hero-cta-button
|
||||
signin-form-email-input
|
||||
signin-form-error-email
|
||||
```
|
||||
|
||||
### Design System Integration
|
||||
|
||||
**When Design System is enabled** (Phase 5), each object in your specification includes component library references:
|
||||
|
||||
**Example specification entry:**
|
||||
```markdown
|
||||
### Submit Button
|
||||
**Object ID:** `signin-form-submit-button`
|
||||
**Component:** primary-button (from Design System)
|
||||
**Figma Component:** Primary Button
|
||||
**Variant:** size=large, type=primary
|
||||
**State:** default
|
||||
|
||||
Triggers form validation and submission...
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- Designers know which Figma component to use
|
||||
- Developers know which code component to implement
|
||||
- Design System ensures consistency
|
||||
- Object IDs connect spec → design → code
|
||||
|
||||
**Without Design System:**
|
||||
Just describe the element directly in the specification without component references.
|
||||
|
||||
---
|
||||
|
||||
## The Pressure-Testing Process
|
||||
|
||||
Specification isn't just documentation - it's design validation.
|
||||
|
||||
When you try to specify every detail, you discover:
|
||||
- "What happens when this is empty?"
|
||||
- "How does this look on mobile?"
|
||||
- "What if the user does X before Y?"
|
||||
- "Where does this data come from?"
|
||||
|
||||
Finding these gaps now means addressing them while solutions are still flexible.
|
||||
|
||||
---
|
||||
|
||||
## HTML Prototypes
|
||||
|
||||
Interactive prototypes that validate your design:
|
||||
|
||||
**What they include:**
|
||||
- Semantic HTML matching your specs
|
||||
- CSS using your Design System tokens
|
||||
- JavaScript for interactions and validation
|
||||
- Multilingual content switching
|
||||
|
||||
**What they reveal:**
|
||||
- Visual gaps ("the spacing doesn't match")
|
||||
- Interaction issues ("we forgot the loading state")
|
||||
- Component needs ("we need a phone input component")
|
||||
- Content problems ("the translation is too long")
|
||||
- Flow issues ("this navigation doesn't make sense")
|
||||
|
||||
**File Structure:**
|
||||
```
|
||||
1.1-Start-Page/
|
||||
├── 1.1-Start-Page.md (specification)
|
||||
├── Sketches/
|
||||
│ └── concept-sketch.jpg
|
||||
└── Prototype/
|
||||
├── 1.1-Start-Page-Prototype.html
|
||||
├── 1.1-Start-Page-Prototype.css
|
||||
└── 1.1-Start-Page-Prototype.js
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## When to Use This Phase
|
||||
|
||||
**Use this phase when:**
|
||||
- Ready to design specific screens/pages
|
||||
- Have strategic clarity from Phase 1-2
|
||||
- Want to validate designs before development
|
||||
|
||||
**Start with exploration (4A) if:**
|
||||
- No existing sketches
|
||||
- Unsure how to approach a feature
|
||||
- Need to think through the user journey
|
||||
|
||||
**Start with analysis (4B) if:**
|
||||
- Have sketches ready to specify
|
||||
- Know what you want, need to document it
|
||||
|
||||
**Use HTML prototypes (4D) if:**
|
||||
- Specifications feel complete
|
||||
- Want to validate before development
|
||||
- Need stakeholder sign-off
|
||||
|
||||
---
|
||||
|
||||
## What to Prepare
|
||||
|
||||
Bring:
|
||||
- Trigger Map (Phase 2) - for user psychology reference
|
||||
- Any existing sketches or wireframes
|
||||
- Technical constraints from PRD (Phase 3)
|
||||
- Content in all supported languages (or draft it together)
|
||||
|
||||
---
|
||||
|
||||
## What Comes Next
|
||||
|
||||
Your specifications enable:
|
||||
|
||||
- **Phase 5: Design System** - Components extracted and documented
|
||||
- **Phase 6: Dev Integration** - Complete handoff package
|
||||
- **Development** - Specs so clear they eliminate guesswork
|
||||
|
||||
---
|
||||
|
||||
## Tips for Great Sessions
|
||||
|
||||
**Think out loud with Baldr**
|
||||
- Share your reasoning
|
||||
- Explore alternatives together
|
||||
- Let the conversation reveal insights
|
||||
|
||||
**Be thorough with states**
|
||||
- Empty states
|
||||
- Loading states
|
||||
- Error states
|
||||
- Success states
|
||||
- Edge cases
|
||||
|
||||
**Don't skip the prototype**
|
||||
- Click through your design
|
||||
- Find the gaps before development
|
||||
- Refine specs based on what you learn
|
||||
|
||||
**Reference your Trigger Map**
|
||||
- Does this serve the user's goals?
|
||||
- Does this avoid their fears?
|
||||
- Does this support business objectives?
|
||||
|
||||
---
|
||||
|
||||
## Example Output
|
||||
|
||||
See: `examples/dog-week-patterns/C-Scenarios/` for complete scenario specifications from a real project.
|
||||
|
||||
---
|
||||
|
||||
*Phase 4 of the Whiteport Design Studio method*
|
||||
|
||||
|
|
@ -0,0 +1,745 @@
|
|||
# Phase 5: Design System (Component Library)
|
||||
|
||||
**Agent:** Baldr the UX Expert
|
||||
**Output:** `D-Design-System/` (or your configured prefix)
|
||||
|
||||
---
|
||||
|
||||
## What This Phase Does
|
||||
|
||||
Design System builds your component library following atomic design principles. Working with Baldr, you create reusable patterns that serve user psychology and ensure visual consistency.
|
||||
|
||||
**The key approach:** The design system grows **alongside** Phase 4 work. As you sketch and specify pages, you simultaneously extract and document components. By the time your scenarios are complete, your design system is already built.
|
||||
|
||||
---
|
||||
|
||||
## What You'll Create
|
||||
|
||||
Your Design System includes:
|
||||
|
||||
- **Design Tokens** - Colors, typography, spacing, shadows
|
||||
- **Atomic Components** - Buttons, inputs, labels, icons
|
||||
- **Molecular Components** - Form groups, cards, list items
|
||||
- **Organism Components** - Headers, footers, complex sections
|
||||
- **Usage Guidelines** - When and how to use each component
|
||||
- **Component Variants** - Different states and sizes
|
||||
|
||||
---
|
||||
|
||||
## Atomic Design Structure
|
||||
|
||||
Following Brad Frost's methodology:
|
||||
|
||||
### Foundation (Design Tokens)
|
||||
The values everything else builds on:
|
||||
- **Colors** - Primary, secondary, semantic (success, error, warning)
|
||||
- **Typography** - Font families, sizes, weights, line heights
|
||||
- **Spacing** - Consistent spacing scale
|
||||
- **Shadows** - Elevation levels
|
||||
- **Borders** - Radius and stroke styles
|
||||
- **Breakpoints** - Responsive design points
|
||||
|
||||
### Atoms
|
||||
The smallest building blocks:
|
||||
- Buttons
|
||||
- Input fields
|
||||
- Labels
|
||||
- Icons
|
||||
- Badges
|
||||
- Dividers
|
||||
|
||||
### Molecules
|
||||
Groups of atoms working together:
|
||||
- Form groups (label + input + error)
|
||||
- Search bars (input + button)
|
||||
- Card headers (title + action)
|
||||
- Navigation items (icon + label)
|
||||
|
||||
### Organisms
|
||||
Complex components made of molecules:
|
||||
- Page headers
|
||||
- Navigation bars
|
||||
- Form sections
|
||||
- Card layouts
|
||||
- List views
|
||||
|
||||
---
|
||||
|
||||
## How It Works
|
||||
|
||||
### The Parallel Workflow
|
||||
|
||||
Phase 5 isn't a separate phase you do *after* Phase 4 - it happens **during** Phase 4:
|
||||
|
||||
```
|
||||
Phase 4 Page Design → Phase 5 Design System
|
||||
───────────────── ─────────────────
|
||||
Sketch button for Page 1.1 → Create "Primary Button" atom
|
||||
Reuse button on Page 1.2 → Reference existing atom
|
||||
Sketch input for Page 2.1 → Create "Text Input" atom
|
||||
Create form on Page 2.2 → Create "Form Group" molecule
|
||||
Notice pattern across pages → Extract as reusable component
|
||||
```
|
||||
|
||||
**The rhythm:**
|
||||
1. Design a page/component in Phase 4
|
||||
2. Notice "This could be reusable"
|
||||
3. Extract to Design System
|
||||
4. Next page references the system component
|
||||
5. Repeat
|
||||
|
||||
### Component Extraction
|
||||
|
||||
As you specify scenarios in Phase 4, components naturally emerge:
|
||||
|
||||
1. **Identify patterns** - "This button style appears in multiple places"
|
||||
2. **Extract to system** - Document the component with all variants
|
||||
3. **Reference in specs** - Link scenario specs to system components
|
||||
|
||||
---
|
||||
|
||||
## Creating Your Design System Documentation
|
||||
|
||||
### The Extraction Process
|
||||
|
||||
**Step 1: Spot the Pattern**
|
||||
|
||||
While working on Phase 4 scenarios, notice when you're designing something reusable:
|
||||
- "I just designed this button for Page 1.1... and I need it again on Page 1.2"
|
||||
- "This form input pattern will be used everywhere"
|
||||
- "We have 3 different card layouts, but they share the same structure"
|
||||
|
||||
**Step 2: Create the Component Document**
|
||||
|
||||
In your `D-Design-System/` folder, create a component file:
|
||||
|
||||
```
|
||||
D-Design-System/
|
||||
├── 01-design-tokens.md
|
||||
├── 02-atoms/
|
||||
│ ├── primary-button.md ← Create this
|
||||
│ ├── text-input.md
|
||||
│ └── ...
|
||||
├── 03-molecules/
|
||||
│ └── form-group.md
|
||||
└── 04-organisms/
|
||||
└── page-header.md
|
||||
```
|
||||
|
||||
**Step 3: Document the Component**
|
||||
|
||||
Use this template for each component:
|
||||
|
||||
```markdown
|
||||
# Primary Button
|
||||
|
||||
## Overview
|
||||
The primary button is used for the main call-to-action on any page or section.
|
||||
|
||||
## Component Details
|
||||
|
||||
**Category:** Atom
|
||||
**Object ID Pattern:** `*-primary-button`
|
||||
**Component Library:** [If using one, e.g., "Chakra UI Button"]
|
||||
**Figma Component:** Primary Button
|
||||
|
||||
## Variants
|
||||
|
||||
### Size
|
||||
- **Small:** Compact spaces, secondary actions
|
||||
- **Medium:** Default size for most use cases
|
||||
- **Large:** Hero sections, important CTAs
|
||||
|
||||
### State
|
||||
- **Default:** Ready for interaction
|
||||
- **Hover:** Visual feedback on mouse over
|
||||
- **Active:** Currently being clicked
|
||||
- **Disabled:** Action not available
|
||||
- **Loading:** Processing user action
|
||||
|
||||
## Visual Specifications
|
||||
|
||||
**Design Tokens:**
|
||||
- Background: `color-primary-500`
|
||||
- Text: `color-white`
|
||||
- Border Radius: `radius-md`
|
||||
- Padding: `spacing-3` (vertical), `spacing-6` (horizontal)
|
||||
- Font: `font-semibold`, `text-base`
|
||||
|
||||
**States:**
|
||||
- Hover: `color-primary-600`
|
||||
- Active: `color-primary-700`
|
||||
- Disabled: `color-gray-300`, opacity 50%
|
||||
|
||||
## Usage Guidelines
|
||||
|
||||
**When to use:**
|
||||
- Primary action on a page or modal
|
||||
- Main CTA in hero sections
|
||||
- Form submissions
|
||||
- Confirmation actions
|
||||
|
||||
**When NOT to use:**
|
||||
- Multiple primary actions (use secondary instead)
|
||||
- Destructive actions (use danger variant)
|
||||
- Navigation (use links or secondary buttons)
|
||||
|
||||
## Accessibility
|
||||
|
||||
- Minimum contrast ratio: 4.5:1
|
||||
- Keyboard accessible (Enter/Space)
|
||||
- Focus visible indicator
|
||||
- ARIA label when icon-only
|
||||
|
||||
## Example Usage
|
||||
|
||||
**In specifications:**
|
||||
```markdown
|
||||
### Submit Button
|
||||
**Object ID:** `contact-form-submit-button`
|
||||
**Component:** primary-button
|
||||
**Variant:** size=large
|
||||
**State:** default → loading → success
|
||||
```
|
||||
|
||||
**In Figma:**
|
||||
Use "Primary Button" component from library
|
||||
|
||||
**In Code (if using Chakra):**
|
||||
```jsx
|
||||
<Button colorScheme="blue" size="lg">Submit</Button>
|
||||
```
|
||||
|
||||
## Used In
|
||||
|
||||
- 1.1-Start-Page: Hero CTA
|
||||
- 1.2-Sign-Up: Submit registration
|
||||
- 2.1-Contact-Form: Send message
|
||||
- [Update as you use the component]
|
||||
```
|
||||
|
||||
**Step 4: Update as You Go**
|
||||
|
||||
Each time you use this component in a new scenario:
|
||||
1. Add it to the "Used In" section
|
||||
2. Note any new variants discovered
|
||||
3. Update specifications if the component evolves
|
||||
|
||||
### Interactive Component Gathering
|
||||
|
||||
**As you work through Phase 4:**
|
||||
|
||||
```
|
||||
Design Page 1.1
|
||||
↓
|
||||
Notice: "This button is reusable"
|
||||
↓
|
||||
Create: primary-button.md in Design System
|
||||
↓
|
||||
Reference in 1.1 spec: component=primary-button
|
||||
↓
|
||||
Design Page 1.2
|
||||
↓
|
||||
Need same button: Reference existing component
|
||||
↓
|
||||
Design Page 2.1
|
||||
↓
|
||||
Need slightly different: Add variant to component doc
|
||||
↓
|
||||
Update all references with new variant option
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Interactive HTML Component Showcase
|
||||
|
||||
Beyond documentation, create an **interactive HTML guide** where stakeholders and developers can see and interact with all components.
|
||||
|
||||
### Structure
|
||||
|
||||
```
|
||||
D-Design-System/
|
||||
├── component-showcase.html ← Interactive guide
|
||||
├── component-showcase.css
|
||||
├── component-showcase.js
|
||||
├── 01-design-tokens.md
|
||||
├── 02-atoms/
|
||||
│ ├── primary-button.md
|
||||
│ └── ...
|
||||
```
|
||||
|
||||
### What the Showcase Includes
|
||||
|
||||
**For each component:**
|
||||
1. **Live rendered examples** - See the actual component
|
||||
2. **All variants** - Size, state, and style options
|
||||
3. **Interactive states** - Hover, click, focus to see behavior
|
||||
4. **Visual specifications** - Design tokens, spacing, colors used
|
||||
5. **Usage notes** - When to use this component
|
||||
|
||||
### Building the Showcase
|
||||
|
||||
**As you document each component:**
|
||||
|
||||
1. **Add to showcase HTML** - Create a card with live examples
|
||||
2. **Show all variants** - Size, state, visual options
|
||||
3. **Make it interactive** - Buttons click, inputs accept text, states change
|
||||
4. **Display tokens** - Show the actual colors, fonts, spacing
|
||||
5. **Keep it synced** - Update when components evolve
|
||||
|
||||
**Use the provided templates:**
|
||||
|
||||
Find ready-to-use templates in:
|
||||
- `reference/templates/component-showcase-template.html`
|
||||
- `reference/templates/component-card-template.html`
|
||||
|
||||
See complete examples in:
|
||||
- `examples/dog-week-patterns/D-Design-System/component-showcase.html`
|
||||
|
||||
### Benefits
|
||||
|
||||
**For Designers:**
|
||||
- Visual inventory of all components
|
||||
- See components in isolation
|
||||
- Test interactions and states
|
||||
- Share with stakeholders for feedback
|
||||
|
||||
**For Developers:**
|
||||
- Visual reference for implementation
|
||||
- Understand variant options
|
||||
- See all states and interactions
|
||||
- Check responsive behavior
|
||||
|
||||
**For Stakeholders:**
|
||||
- See the design language
|
||||
- Review consistency
|
||||
- Experience interactive components
|
||||
- Provide informed feedback
|
||||
|
||||
**For QA:**
|
||||
- Test all component states
|
||||
- Verify accessibility
|
||||
- Check responsive behavior
|
||||
- Document expected behavior
|
||||
|
||||
### Maintaining the Showcase
|
||||
|
||||
**Keep it current:**
|
||||
- Add new components as they're documented
|
||||
- Update when variants change
|
||||
- Remove deprecated components
|
||||
- Sync with Figma library updates
|
||||
|
||||
**Single source of truth:**
|
||||
- Markdown docs = specifications and usage
|
||||
- HTML showcase = visual reference and interaction
|
||||
- Figma = design source
|
||||
- Code = implementation
|
||||
|
||||
All four should stay aligned.
|
||||
|
||||
---
|
||||
|
||||
## Component Documentation
|
||||
|
||||
Each component includes:
|
||||
|
||||
**Purpose & Usage**
|
||||
- When to use this component
|
||||
- When NOT to use it
|
||||
- Psychological intent (connects to Trigger Map)
|
||||
|
||||
**Variants**
|
||||
- Size options (small, medium, large)
|
||||
- State options (default, hover, active, disabled)
|
||||
- Visual variants (primary, secondary, ghost)
|
||||
|
||||
**Specifications**
|
||||
- Design tokens used
|
||||
- Spacing and sizing
|
||||
- Responsive behavior
|
||||
|
||||
**Implementation Notes**
|
||||
- Technical guidance for developers
|
||||
- Accessibility requirements
|
||||
- Animation/interaction details
|
||||
|
||||
---
|
||||
|
||||
## Choosing a Component Library
|
||||
|
||||
### Build vs. Use Existing
|
||||
|
||||
**Build your own Design System when:**
|
||||
- Unique brand identity required
|
||||
- Custom interactions not available in libraries
|
||||
- Full control over every detail needed
|
||||
- Have design resources to maintain system
|
||||
|
||||
**Use existing component library when:**
|
||||
- Fast time to market
|
||||
- Standard UI patterns sufficient
|
||||
- Limited design resources
|
||||
- Want battle-tested accessibility
|
||||
|
||||
**WDS supports both approaches** - you can document either custom components or library components using the same structure.
|
||||
|
||||
---
|
||||
|
||||
## Recommended Component Libraries
|
||||
|
||||
These libraries work well with WDS's specification approach:
|
||||
|
||||
### React Ecosystem
|
||||
|
||||
**Shadcn/ui** (Recommended for flexibility)
|
||||
- Not a library, but a collection of copy-paste components
|
||||
- Built on Radix UI primitives (excellent accessibility)
|
||||
- [ui.shadcn.com](https://ui.shadcn.com)
|
||||
|
||||
*Pros:*
|
||||
- Full component ownership - code lives in your repo
|
||||
- Easy to customize without fighting library constraints
|
||||
- No package bloat or version conflicts
|
||||
- Perfect for WDS documentation (you own the code)
|
||||
|
||||
*Cons:*
|
||||
- Manual updates when new versions release
|
||||
- Need to maintain copied code yourself
|
||||
- Requires understanding of component internals
|
||||
|
||||
---
|
||||
|
||||
**Chakra UI** (Recommended for speed)
|
||||
- Comprehensive component library
|
||||
- Excellent TypeScript support
|
||||
- Built-in dark mode and theming
|
||||
- [chakra-ui.com](https://chakra-ui.com)
|
||||
|
||||
*Pros:*
|
||||
- Fast to get started - works out of the box
|
||||
- Excellent accessibility defaults
|
||||
- Great developer experience
|
||||
- Active community and good documentation
|
||||
|
||||
*Cons:*
|
||||
- Less control over internals
|
||||
- Can be opinionated about styling approach
|
||||
- Larger bundle size than headless options
|
||||
|
||||
---
|
||||
|
||||
**Radix UI** (Recommended for headless)
|
||||
- Unstyled, accessible components
|
||||
- Complete control over styling
|
||||
- Composable primitives
|
||||
- [radix-ui.com](https://radix-ui.com)
|
||||
|
||||
*Pros:*
|
||||
- Best-in-class accessibility built-in
|
||||
- Total styling freedom
|
||||
- Small bundle size (only import what you need)
|
||||
- No design opinions forced on you
|
||||
|
||||
*Cons:*
|
||||
- Requires you to style everything yourself
|
||||
- Steeper learning curve than styled libraries
|
||||
- More initial setup work
|
||||
|
||||
---
|
||||
|
||||
**Material UI (MUI)**
|
||||
- Mature, comprehensive library
|
||||
- Material Design by default (can customize)
|
||||
- Large ecosystem of additional packages
|
||||
- [mui.com](https://mui.com)
|
||||
|
||||
*Pros:*
|
||||
- Battle-tested with large community
|
||||
- Very comprehensive component set
|
||||
- Good documentation and examples
|
||||
- Material Design is familiar to users
|
||||
|
||||
*Cons:*
|
||||
- Heavy bundle size
|
||||
- Material Design aesthetic hard to override
|
||||
- Can feel dated for modern designs
|
||||
- Customization can be complex
|
||||
|
||||
### Vue Ecosystem
|
||||
|
||||
**Nuxt UI**
|
||||
- Built for Nuxt/Vue 3
|
||||
- Modern, fast, accessible
|
||||
- [ui.nuxt.com](https://ui.nuxt.com)
|
||||
|
||||
*Pros:*
|
||||
- Optimized specifically for Nuxt
|
||||
- Modern design aesthetics
|
||||
- Good performance
|
||||
- Growing ecosystem
|
||||
|
||||
*Cons:*
|
||||
- Nuxt-specific (not for plain Vue)
|
||||
- Younger library with smaller community
|
||||
- Less comprehensive than mature alternatives
|
||||
|
||||
---
|
||||
|
||||
**PrimeVue**
|
||||
- Rich component set
|
||||
- Multiple themes available
|
||||
- Enterprise-focused
|
||||
- [primevue.org](https://primevue.org)
|
||||
|
||||
*Pros:*
|
||||
- Very comprehensive component library
|
||||
- Multiple pre-built themes
|
||||
- Good for complex enterprise UIs
|
||||
- Active development
|
||||
|
||||
*Cons:*
|
||||
- Can feel corporate/dated
|
||||
- Larger bundle size
|
||||
- Theme customization can be complex
|
||||
|
||||
### Framework-Agnostic
|
||||
|
||||
**Tailwind CSS** (Recommended for design freedom)
|
||||
- Utility-first CSS framework
|
||||
- Combine with headless components
|
||||
- Maximum flexibility
|
||||
- [tailwindcss.com](https://tailwindcss.com)
|
||||
|
||||
*Pros:*
|
||||
- Complete design freedom
|
||||
- Small production bundle (unused styles purged)
|
||||
- Fast prototyping with utility classes
|
||||
- Pairs perfectly with WDS specifications
|
||||
|
||||
*Cons:*
|
||||
- Not a component library (need to build or combine)
|
||||
- HTML can get verbose
|
||||
- Learning curve for utility-first approach
|
||||
- Need separate component primitives (e.g., Radix)
|
||||
|
||||
### Selection Criteria
|
||||
|
||||
**Choose based on:**
|
||||
|
||||
| Priority | Consider |
|
||||
|----------|----------|
|
||||
| **Speed** | Chakra UI, MUI, PrimeVue (ready-to-use) |
|
||||
| **Customization** | Shadcn/ui, Radix UI, Tailwind (full control) |
|
||||
| **Accessibility** | Radix UI, Chakra UI (built-in a11y) |
|
||||
| **Design System** | Shadcn/ui, custom components (full documentation) |
|
||||
| **Team Familiarity** | What your dev team already knows |
|
||||
|
||||
### WDS Integration Pattern
|
||||
|
||||
**With existing library:**
|
||||
1. Document library components in your WDS Design System
|
||||
2. Reference library component names in specifications
|
||||
3. Add project-specific variants/customizations
|
||||
4. Maintain consistency across your product
|
||||
|
||||
**Example WDS entry for library component:**
|
||||
```markdown
|
||||
## Primary Button
|
||||
|
||||
**Library Component:** Chakra UI Button
|
||||
**Import:** `import { Button } from '@chakra-ui/react'`
|
||||
|
||||
**Usage in WDS:**
|
||||
- Object ID suffix: `-primary-button`
|
||||
- Figma Component: Primary Button
|
||||
- Props: `colorScheme="blue" size="lg"`
|
||||
|
||||
**Variants:**
|
||||
- Default: `variant="solid"`
|
||||
- Secondary: `variant="outline"`
|
||||
- Ghost: `variant="ghost"`
|
||||
|
||||
**When to use:**
|
||||
Primary call-to-action buttons...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Design Application Integration
|
||||
|
||||
Your WDS component system connects to your visual design tools (Figma, Sketch, Adobe XD):
|
||||
|
||||
### Unified Naming Convention
|
||||
|
||||
**Use the exact same names across all tools:**
|
||||
|
||||
| WDS Component Name | Figma Component | Code Component | Object ID |
|
||||
|-------------------|-----------------|----------------|-----------|
|
||||
| `primary-button` | Primary Button | `PrimaryButton` | `*-primary-button` |
|
||||
| `text-input` | Text Input | `TextInput` | `*-text-input` |
|
||||
| `form-group` | Form Group | `FormGroup` | `*-form-group` |
|
||||
|
||||
### The Workflow
|
||||
|
||||
```
|
||||
WDS Specification → Figma Design → Code Implementation
|
||||
───────────────── ───────── ──────────────────
|
||||
1. Document 2. Create 3. Build with
|
||||
"primary-button" component same name
|
||||
in Design System in Figma in code
|
||||
|
||||
Object IDs reference the same names:
|
||||
signin-form-submit-primary-button (everywhere)
|
||||
```
|
||||
|
||||
### Figma/Design Tool Setup
|
||||
|
||||
**Component Library Structure:**
|
||||
|
||||
Match your WDS atomic design structure:
|
||||
```
|
||||
Design File/
|
||||
├── 🎨 Design Tokens
|
||||
│ ├── Colors
|
||||
│ ├── Typography
|
||||
│ └── Spacing
|
||||
├── ⚛️ Atoms
|
||||
│ ├── primary-button
|
||||
│ ├── text-input
|
||||
│ └── ...
|
||||
├── 🧬 Molecules
|
||||
│ ├── form-group
|
||||
│ ├── search-bar
|
||||
│ └── ...
|
||||
└── 🧩 Organisms
|
||||
├── page-header
|
||||
└── ...
|
||||
```
|
||||
|
||||
**Naming in Figma:**
|
||||
- Component names match WDS names (kebab-case or Title Case)
|
||||
- Variants match WDS variants (Primary, Secondary, Disabled)
|
||||
- Properties match WDS states (default, hover, active, error)
|
||||
|
||||
### Benefits of Unified Naming
|
||||
|
||||
- **Designers:** Find components easily in Figma library
|
||||
- **Developers:** No translation needed from design to code
|
||||
- **Testers:** Object IDs make sense and are predictable
|
||||
- **Documentation:** Single source of truth for naming
|
||||
- **Handoff:** Zero ambiguity about which component to use
|
||||
|
||||
### When You Design in Figma
|
||||
|
||||
1. **Reference your WDS Design System** for component names and structure
|
||||
2. **Create visual designs** using those exact names
|
||||
3. **Export/handoff** with matching naming to developers
|
||||
4. **Specifications remain in WDS** - Figma provides the pixels, WDS provides the logic
|
||||
|
||||
---
|
||||
|
||||
## Growing the System
|
||||
|
||||
The design system is living documentation that grows with your product:
|
||||
|
||||
### Starting Point
|
||||
Begin with what you need for current scenarios:
|
||||
- Extract components from Phase 4 work
|
||||
- Document only what you're actually using
|
||||
- Avoid speculating about future needs
|
||||
|
||||
### Evolution
|
||||
As you design more scenarios:
|
||||
- New patterns emerge → add to system
|
||||
- Inconsistencies appear → consolidate
|
||||
- Components evolve → update documentation
|
||||
|
||||
### Maintenance
|
||||
- Keep specs in sync with implementation
|
||||
- Remove unused components
|
||||
- Update when design language evolves
|
||||
|
||||
---
|
||||
|
||||
## When to Use This Phase
|
||||
|
||||
**Enable Design System phase if:**
|
||||
- Building reusable component library
|
||||
- Multiple pages/scenarios with shared patterns
|
||||
- Need design consistency across product
|
||||
- Handoff requires component documentation
|
||||
|
||||
**Work in parallel with Phase 4 when enabled:**
|
||||
- As you sketch, identify component patterns
|
||||
- As you specify, extract to Design System
|
||||
- Design System grows with each page completed
|
||||
- No separate "design system phase" at the end
|
||||
|
||||
**Skip this phase if:**
|
||||
- Small project (single landing page)
|
||||
- Using existing design system (Material, Chakra, etc.)
|
||||
- One-off designs without reuse
|
||||
- Quick prototype or MVP without component library needs
|
||||
|
||||
**Dedicated consolidation when:**
|
||||
- Multiple scenarios complete, need cleanup
|
||||
- Preparing for development handoff
|
||||
- Found inconsistencies to resolve
|
||||
- Onboarding new team members
|
||||
|
||||
> **Note:** You'll choose whether to enable the Design System phase during project setup (`workflow-init`). This decision can be revisited as your project grows.
|
||||
|
||||
---
|
||||
|
||||
## What to Prepare
|
||||
|
||||
Bring:
|
||||
- Completed or in-progress scenario specs (Phase 4)
|
||||
- Any existing brand guidelines
|
||||
- Technical framework constraints (React components, etc.)
|
||||
|
||||
---
|
||||
|
||||
## What Comes Next
|
||||
|
||||
Your Design System enables:
|
||||
|
||||
- **Consistent implementation** - Developers build from clear specs
|
||||
- **Faster design** - Reuse components across scenarios
|
||||
- **Phase 6 handoff** - Complete component inventory
|
||||
|
||||
---
|
||||
|
||||
## Tips for Great Sessions
|
||||
|
||||
**Extract, don't invent**
|
||||
- Components should come from real design needs
|
||||
- Don't create components "just in case"
|
||||
- Let the system grow from actual scenarios
|
||||
|
||||
**Document the why**
|
||||
- Why does this button look this way?
|
||||
- What user trigger does it serve?
|
||||
- When should developers use variant A vs B?
|
||||
|
||||
**Stay consistent**
|
||||
- Same component = same specification
|
||||
- Variations should be intentional
|
||||
- When in doubt, simplify
|
||||
|
||||
**Connect to psychology**
|
||||
- Every design choice serves a purpose
|
||||
- Reference your Trigger Map
|
||||
- Components should feel intentional, not arbitrary
|
||||
|
||||
---
|
||||
|
||||
## Example Output
|
||||
|
||||
See: `examples/dog-week-patterns/D-Design-System/` for a complete Design System from a real project.
|
||||
|
||||
---
|
||||
|
||||
*Phase 5 of the Whiteport Design Studio method*
|
||||
|
||||
|
|
@ -0,0 +1,470 @@
|
|||
# Phase 6: PRD Finalization
|
||||
|
||||
**Agent:** Freyja the PM
|
||||
**Output:** Complete PRD in `C-Requirements/` + Handoff materials in `E-UI-Roadmap/`
|
||||
**Duration:** 2-4 hours
|
||||
|
||||
---
|
||||
|
||||
## What This Phase Does
|
||||
|
||||
PRD Finalization compiles all the functional requirements discovered during Phase 4 into a complete, development-ready Product Requirements Document.
|
||||
|
||||
**The key insight:** Your PRD started in Phase 3 with platform/infrastructure. During Phase 4, each page added functional requirements (via step 4E). Now you organize, prioritize, and finalize everything for development handoff.
|
||||
|
||||
By the end, developers have a complete PRD covering both technical foundation and all UI-driven features.
|
||||
|
||||
---
|
||||
|
||||
## What You'll Create
|
||||
|
||||
**Updated PRD (C-Requirements/) includes:**
|
||||
|
||||
**From Phase 3 (Technical Foundation):**
|
||||
- Platform architecture
|
||||
- Data model
|
||||
- Integration map
|
||||
- Technical proofs of concept
|
||||
- Experimental endpoints
|
||||
- Security framework
|
||||
|
||||
**Added from Phase 4 (Functional Requirements):**
|
||||
- All features discovered during page design
|
||||
- Page-to-feature traceability
|
||||
- Priority rankings
|
||||
- Feature dependencies
|
||||
- Implementation notes
|
||||
|
||||
**New in Phase 6:**
|
||||
- Feature organization by epic/area
|
||||
- Development sequence
|
||||
- MVP scope definition
|
||||
- Technical dependencies mapped
|
||||
|
||||
**Handoff Package (E-UI-Roadmap/):**
|
||||
- Priority sequence document
|
||||
- Scenario-to-development mapping
|
||||
- Component inventory (if Design System enabled)
|
||||
- Open questions for dev team
|
||||
|
||||
---
|
||||
|
||||
## How It Works
|
||||
|
||||
### Stage 1: Review Collected Requirements (30-45 minutes)
|
||||
|
||||
**Gather all functional requirements added during Phase 4:**
|
||||
|
||||
Go through each scenario specification and extract the requirements added in step 4E:
|
||||
|
||||
```
|
||||
From 1.1-Start-Page:
|
||||
- User authentication system
|
||||
- Session management
|
||||
- Password reset flow
|
||||
|
||||
From 1.2-Sign-Up:
|
||||
- Email validation (format, domain check, duplicate prevention)
|
||||
- Phone number validation with country code
|
||||
- Account activation via email
|
||||
|
||||
From 2.1-Dog-Calendar:
|
||||
- Availability calendar API
|
||||
- Real-time updates via WebSocket
|
||||
- Date/time localization
|
||||
```
|
||||
|
||||
**Compile into master feature list** with page references preserved.
|
||||
|
||||
### Stage 2: Organize by Epic/Feature Area (30-45 minutes)
|
||||
|
||||
**Group related features together:**
|
||||
|
||||
```markdown
|
||||
## Epic 1: User Authentication & Account Management
|
||||
|
||||
### Features
|
||||
|
||||
**User Registration**
|
||||
- Required by: 1.2-Sign-Up
|
||||
- Email validation (format, domain, duplicates)
|
||||
- Phone validation with country codes
|
||||
- Account activation flow
|
||||
|
||||
**User Login**
|
||||
- Required by: 1.1-Start-Page, multiple pages
|
||||
- Email/password authentication
|
||||
- Session management (30-day persistence)
|
||||
- "Remember me" functionality
|
||||
|
||||
**Password Management**
|
||||
- Required by: 1.1-Start-Page (reset link)
|
||||
- Password reset via email
|
||||
- Password strength validation
|
||||
- Secure token generation
|
||||
```
|
||||
|
||||
### Stage 3: Define Priorities & Sequence (45-60 minutes)
|
||||
|
||||
**Based on your Phase 2 Feature Impact Analysis:**
|
||||
|
||||
Reference the scoring you did in Phase 2 to inform priorities:
|
||||
|
||||
```markdown
|
||||
## Development Sequence
|
||||
|
||||
### Priority 1: MVP - Core User Flow
|
||||
**Target:** Weeks 1-4
|
||||
|
||||
Features from Epic 1 (Authentication) + Epic 2 (Core Booking):
|
||||
- User registration (Impact Score: 14)
|
||||
- User login (Impact Score: 16)
|
||||
- Availability calendar (Impact Score: 16)
|
||||
- Basic booking flow (Impact Score: 18)
|
||||
|
||||
**Why this order:**
|
||||
Serves Priority 1 target group, addresses highest-impact drivers.
|
||||
|
||||
### Priority 2: Enhanced Features
|
||||
**Target:** Weeks 5-8
|
||||
|
||||
Features from Epic 3 (Payments) + Epic 4 (Notifications):
|
||||
- Payment processing (Impact Score: 12)
|
||||
- Booking confirmations (Impact Score: 11)
|
||||
- Calendar sync (Impact Score: 8)
|
||||
```
|
||||
|
||||
### Stage 4: Map Dependencies (20-30 minutes)
|
||||
|
||||
**Technical dependencies between features:**
|
||||
|
||||
```markdown
|
||||
## Feature Dependencies
|
||||
|
||||
**Booking Flow** depends on:
|
||||
- ✓ User authentication (must be logged in)
|
||||
- ✓ Availability calendar (must see open slots)
|
||||
- ⚠️ Payment system (can launch with "pay in person" temporarily)
|
||||
- ⚠️ Notifications (can launch without, add later)
|
||||
|
||||
**Recommendation:** Launch MVP with auth + calendar, add payments in Sprint 2.
|
||||
```
|
||||
|
||||
### Stage 5: Create Handoff Package (30-45 minutes)
|
||||
|
||||
**Organize for development team:**
|
||||
|
||||
In `E-UI-Roadmap/` folder, create:
|
||||
|
||||
1. **`priority-sequence.md`** - What to build when and why
|
||||
2. **`scenario-to-epic-mapping.md`** - How WDS scenarios map to dev epics
|
||||
3. **`component-inventory.md`** (if Design System enabled) - All components needed
|
||||
4. **`open-questions.md`** - Decisions for dev team to make
|
||||
|
||||
---
|
||||
|
||||
## The Complete PRD Structure
|
||||
|
||||
Your finalized PRD in `C-Requirements/` combines all phases:
|
||||
|
||||
```markdown
|
||||
# Product Requirements Document
|
||||
|
||||
## 1. Technical Foundation (from Phase 3)
|
||||
|
||||
### Platform Architecture
|
||||
- Technology stack decisions
|
||||
- Infrastructure approach
|
||||
- Hosting and deployment
|
||||
|
||||
### Data Model
|
||||
- Core entities and relationships
|
||||
- Database schema
|
||||
- Data flow diagrams
|
||||
|
||||
### Integrations
|
||||
- External services (Google Maps, Stripe, etc.)
|
||||
- API specifications
|
||||
- Authentication providers
|
||||
|
||||
### Security & Performance
|
||||
- Authentication/authorization approach
|
||||
- Data protection
|
||||
- Performance requirements
|
||||
- Proofs of concept results
|
||||
|
||||
## 2. Functional Requirements (from Phase 4)
|
||||
|
||||
### Epic 1: User Authentication & Account Management
|
||||
**Features:**
|
||||
- User registration (Required by: 1.2-Sign-Up)
|
||||
- User login (Required by: 1.1-Start-Page, multiple)
|
||||
- Password management (Required by: 1.1-Start-Page)
|
||||
|
||||
[Detailed specifications for each feature]
|
||||
|
||||
### Epic 2: [Next Epic]
|
||||
[...]
|
||||
|
||||
## 3. Development Roadmap (from Phase 6)
|
||||
|
||||
### Priority 1: MVP (Weeks 1-4)
|
||||
- Features list with Impact Scores
|
||||
- Why these first (references Trigger Map)
|
||||
- Timeline estimate
|
||||
- Dependencies
|
||||
|
||||
### Priority 2: Enhanced Features (Weeks 5-8)
|
||||
[...]
|
||||
|
||||
## 4. Dependencies & Constraints
|
||||
- Technical dependencies between features
|
||||
- Design constraints from Phase 4
|
||||
- Third-party limitations discovered in Phase 3
|
||||
|
||||
## 5. Success Metrics
|
||||
- Business goals from Phase 1
|
||||
- Feature-specific KPIs
|
||||
- How we measure success
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Continuous vs. Final Handoff
|
||||
|
||||
**The pattern:**
|
||||
|
||||
- **Phase 3:** Initial PRD with technical foundation
|
||||
- **Phase 4:** PRD grows with each page (step 4E adds requirements)
|
||||
- **Phase 6 (First time):** Organize MVP scope from completed scenarios
|
||||
- Create first handoff package
|
||||
- Development can begin
|
||||
- **Phase 4 continues:** More pages designed, more requirements added
|
||||
- **Phase 6 (Ongoing):** Update PRD priorities, create new handoff packages
|
||||
- Weekly or bi-weekly updates
|
||||
- Keep dev team synced
|
||||
|
||||
**You can run Phase 6 multiple times as design progresses.**
|
||||
|
||||
---
|
||||
|
||||
## When to Use This Phase
|
||||
|
||||
**First PRD Finalization when:**
|
||||
- You have MVP-level scenarios complete (enough for dev to start)
|
||||
- Core user flows are specified
|
||||
- Critical features are documented
|
||||
- Enough work for 2-4 week sprint
|
||||
|
||||
**Ongoing PRD Updates as:**
|
||||
- Additional scenarios complete
|
||||
- New feature areas designed
|
||||
- Priorities shift based on learning
|
||||
- Sprint planning needs updated scope
|
||||
|
||||
**Timeline example:**
|
||||
|
||||
```
|
||||
Week 1-2: Phase 1-3 (Strategy, Research, Platform foundation)
|
||||
Week 3-4: Phase 4 Scenarios 1-3 (Core MVP flows)
|
||||
Week 5: Phase 6 First Finalization
|
||||
└──► PRD v1.0: MVP scope ready
|
||||
└──► Development Sprint 1 begins
|
||||
|
||||
Week 6-7: Phase 4 Scenarios 4-6 (Additional features)
|
||||
Phase 5 Design System (extract components)
|
||||
Week 8: Phase 6 Update
|
||||
└──► PRD v1.1: Sprint 2 scope added
|
||||
└──► Development Sprint 2 begins
|
||||
|
||||
Week 9+: Design continues in parallel with development
|
||||
Regular Phase 6 updates for new sprints
|
||||
```
|
||||
|
||||
**The beauty:** Design doesn't block development. You hand off in waves.
|
||||
|
||||
Complete list for test automation:
|
||||
|
||||
| Scenario | Object ID | Element Type | Notes |
|
||||
|----------|-----------|--------------|-------|
|
||||
| 1.1 | `welcome-hero-cta` | Button | Primary action |
|
||||
| 1.1 | `welcome-signin-link` | Link | Secondary action |
|
||||
| 1.2 | `signin-email-input` | Input | Required field |
|
||||
| 1.2 | `signin-error-email` | Error | Validation message |
|
||||
|
||||
---
|
||||
|
||||
## How It Works
|
||||
|
||||
### Review Completeness
|
||||
|
||||
Before handoff, verify:
|
||||
- All scenarios specified and reviewed
|
||||
- Design system covers all components
|
||||
- Object IDs assigned throughout
|
||||
- Multilingual content complete
|
||||
- HTML prototypes validated
|
||||
|
||||
### Identify Priorities
|
||||
|
||||
With Freyja, map your Trigger Map priorities to development order:
|
||||
- Which user triggers are most critical?
|
||||
- What's the minimum viable experience?
|
||||
- What can wait for later releases?
|
||||
|
||||
### Document Technical Context
|
||||
|
||||
Capture what developers need to know:
|
||||
- Design decisions and their rationale
|
||||
- Technical constraints discovered during design
|
||||
- Interaction patterns that need special attention
|
||||
- Performance considerations
|
||||
|
||||
### Create the Handoff
|
||||
|
||||
Organize everything into the UI Roadmap folder:
|
||||
- Clear priority sequence
|
||||
- Complete component inventory
|
||||
- Technical notes and open questions
|
||||
- Verification checklist
|
||||
|
||||
---
|
||||
|
||||
## The Handoff Checklist
|
||||
|
||||
```markdown
|
||||
## Design Handoff Verification
|
||||
|
||||
### Product Foundation
|
||||
- [ ] Product Brief complete and current
|
||||
- [ ] Trigger Map with prioritized users and goals
|
||||
- [ ] ICP clearly defined
|
||||
|
||||
### Requirements
|
||||
- [ ] PRD with technical specifications
|
||||
- [ ] Platform architecture documented
|
||||
- [ ] Integration requirements listed
|
||||
|
||||
### Visual Design
|
||||
- [ ] All scenarios have specifications
|
||||
- [ ] All pages have Object IDs
|
||||
- [ ] States documented (empty, loading, error, success)
|
||||
|
||||
### Design System
|
||||
- [ ] All components documented
|
||||
- [ ] Design tokens defined
|
||||
- [ ] Usage guidelines written
|
||||
|
||||
### Validation
|
||||
- [ ] HTML prototypes created for key scenarios
|
||||
- [ ] Stakeholder review complete
|
||||
- [ ] Open questions documented
|
||||
|
||||
### Ready for Development ✅
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## When to Use This Phase
|
||||
|
||||
**First handoff when:**
|
||||
- You have enough scenarios for MVP
|
||||
- Core user flows are specified
|
||||
- Critical components are documented
|
||||
- Developers can start building foundational features
|
||||
|
||||
**Ongoing handoffs as:**
|
||||
- Each major scenario completes
|
||||
- New component patterns emerge
|
||||
- Design decisions affect development
|
||||
- Sprint planning needs updated priorities
|
||||
|
||||
**The rhythm:**
|
||||
|
||||
```
|
||||
Week 1-2: Design Phase 1-3 (Strategy, Research, Platform)
|
||||
Week 3-4: Design Phase 4 Scenarios 1-2 (Core flows)
|
||||
└──► First Handoff: MVP scope
|
||||
Week 5-6: Design Phase 4 Scenarios 3-4
|
||||
Design Phase 5 (Components from 1-2)
|
||||
└──► Second Handoff: Additional features
|
||||
Week 7+: Design continues...
|
||||
Development builds in parallel
|
||||
└──► Ongoing handoffs as design progresses
|
||||
```
|
||||
|
||||
**You DON'T need to finish all design before handing off.**
|
||||
|
||||
Development and design work in parallel streams, with regular sync points.
|
||||
|
||||
---
|
||||
|
||||
## What to Prepare
|
||||
|
||||
Bring:
|
||||
- Completed scenario specifications (Phase 4)
|
||||
- Design System (Phase 5)
|
||||
- PRD (Phase 3)
|
||||
- Trigger Map priorities (Phase 2)
|
||||
|
||||
---
|
||||
|
||||
## What Comes Next
|
||||
|
||||
Your UI Roadmap enables:
|
||||
|
||||
- **Development kickoff** - Clear starting point
|
||||
- **Sprint planning** - Prioritized work items
|
||||
- **Test automation** - Object ID inventory
|
||||
- **QA validation** - Specifications to verify against
|
||||
|
||||
---
|
||||
|
||||
## Tips for Great Sessions
|
||||
|
||||
**Think from dev perspective**
|
||||
- What questions will developers have?
|
||||
- What decisions can't you make for them?
|
||||
- What context will save them time?
|
||||
|
||||
**Be explicit about priorities**
|
||||
- Not everything is Priority 1
|
||||
- Make trade-offs visible
|
||||
- Connect priorities to business goals
|
||||
|
||||
**Document the unknowns**
|
||||
- Open questions are valuable
|
||||
- Don't pretend certainty you don't have
|
||||
- Let dev team contribute decisions
|
||||
|
||||
**Keep it updated**
|
||||
- Handoff is ongoing, not one-time
|
||||
- Update as design evolves
|
||||
- Maintain as source of truth
|
||||
|
||||
---
|
||||
|
||||
## Integration with BMM
|
||||
|
||||
When handing off to BMad Method (BMM) for development:
|
||||
|
||||
```
|
||||
WDS → E-UI-Roadmap/ → BMM Architecture & Stories
|
||||
```
|
||||
|
||||
The UI Roadmap provides:
|
||||
- Context for architecture decisions
|
||||
- Specifications for story creation
|
||||
- Priorities for sprint planning
|
||||
- Test automation foundations
|
||||
|
||||
---
|
||||
|
||||
## Example Output
|
||||
|
||||
See: `examples/dog-week-patterns/E-UI-Roadmap/` for a complete UI Roadmap from a real project.
|
||||
|
||||
---
|
||||
|
||||
*Phase 6 of the Whiteport Design Studio method*
|
||||
|
||||
|
|
@ -0,0 +1,469 @@
|
|||
# Phase 6: PRD Finalization (Complete PRD)
|
||||
|
||||
**Agent:** Freyja the PM
|
||||
**Output:** Complete PRD in `C-Requirements/` + Handoff materials in `E-UI-Roadmap/`
|
||||
|
||||
---
|
||||
|
||||
## What This Phase Does
|
||||
|
||||
PRD Finalization compiles all the functional requirements discovered during Phase 4 into a complete, development-ready Product Requirements Document.
|
||||
|
||||
**The key insight:** Your PRD started in Phase 3 with platform/infrastructure. During Phase 4, each page added functional requirements (via step 4E). Now you organize, prioritize, and finalize everything for development handoff.
|
||||
|
||||
By the end, developers have a complete PRD covering both technical foundation and all UI-driven features.
|
||||
|
||||
---
|
||||
|
||||
## What You'll Create
|
||||
|
||||
**Updated PRD (C-Requirements/) includes:**
|
||||
|
||||
**From Phase 3 (Technical Foundation):**
|
||||
- Platform architecture
|
||||
- Data model
|
||||
- Integration map
|
||||
- Technical proofs of concept
|
||||
- Experimental endpoints
|
||||
- Security framework
|
||||
|
||||
**Added from Phase 4 (Functional Requirements):**
|
||||
- All features discovered during page design
|
||||
- Page-to-feature traceability
|
||||
- Priority rankings
|
||||
- Feature dependencies
|
||||
- Implementation notes
|
||||
|
||||
**New in Phase 6:**
|
||||
- Feature organization by epic/area
|
||||
- Development sequence
|
||||
- MVP scope definition
|
||||
- Technical dependencies mapped
|
||||
|
||||
**Handoff Package (E-UI-Roadmap/):**
|
||||
- Priority sequence document
|
||||
- Scenario-to-development mapping
|
||||
- Component inventory (if Design System enabled)
|
||||
- Open questions for dev team
|
||||
|
||||
---
|
||||
|
||||
## How It Works
|
||||
|
||||
### Stage 1: Review Collected Requirements (30-45 minutes)
|
||||
|
||||
**Gather all functional requirements added during Phase 4:**
|
||||
|
||||
Go through each scenario specification and extract the requirements added in step 4E:
|
||||
|
||||
```
|
||||
From 1.1-Start-Page:
|
||||
- User authentication system
|
||||
- Session management
|
||||
- Password reset flow
|
||||
|
||||
From 1.2-Sign-Up:
|
||||
- Email validation (format, domain check, duplicate prevention)
|
||||
- Phone number validation with country code
|
||||
- Account activation via email
|
||||
|
||||
From 2.1-Dog-Calendar:
|
||||
- Availability calendar API
|
||||
- Real-time updates via WebSocket
|
||||
- Date/time localization
|
||||
```
|
||||
|
||||
**Compile into master feature list** with page references preserved.
|
||||
|
||||
### Stage 2: Organize by Epic/Feature Area (30-45 minutes)
|
||||
|
||||
**Group related features together:**
|
||||
|
||||
```markdown
|
||||
## Epic 1: User Authentication & Account Management
|
||||
|
||||
### Features
|
||||
|
||||
**User Registration**
|
||||
- Required by: 1.2-Sign-Up
|
||||
- Email validation (format, domain, duplicates)
|
||||
- Phone validation with country codes
|
||||
- Account activation flow
|
||||
|
||||
**User Login**
|
||||
- Required by: 1.1-Start-Page, multiple pages
|
||||
- Email/password authentication
|
||||
- Session management (30-day persistence)
|
||||
- "Remember me" functionality
|
||||
|
||||
**Password Management**
|
||||
- Required by: 1.1-Start-Page (reset link)
|
||||
- Password reset via email
|
||||
- Password strength validation
|
||||
- Secure token generation
|
||||
```
|
||||
|
||||
### Stage 3: Define Priorities & Sequence (45-60 minutes)
|
||||
|
||||
**Based on your Phase 2 Feature Impact Analysis:**
|
||||
|
||||
Reference the scoring you did in Phase 2 to inform priorities:
|
||||
|
||||
```markdown
|
||||
## Development Sequence
|
||||
|
||||
### Priority 1: MVP - Core User Flow
|
||||
**Target:** Weeks 1-4
|
||||
|
||||
Features from Epic 1 (Authentication) + Epic 2 (Core Booking):
|
||||
- User registration (Impact Score: 14)
|
||||
- User login (Impact Score: 16)
|
||||
- Availability calendar (Impact Score: 16)
|
||||
- Basic booking flow (Impact Score: 18)
|
||||
|
||||
**Why this order:**
|
||||
Serves Priority 1 target group, addresses highest-impact drivers.
|
||||
|
||||
### Priority 2: Enhanced Features
|
||||
**Target:** Weeks 5-8
|
||||
|
||||
Features from Epic 3 (Payments) + Epic 4 (Notifications):
|
||||
- Payment processing (Impact Score: 12)
|
||||
- Booking confirmations (Impact Score: 11)
|
||||
- Calendar sync (Impact Score: 8)
|
||||
```
|
||||
|
||||
### Stage 4: Map Dependencies (20-30 minutes)
|
||||
|
||||
**Technical dependencies between features:**
|
||||
|
||||
```markdown
|
||||
## Feature Dependencies
|
||||
|
||||
**Booking Flow** depends on:
|
||||
- ✓ User authentication (must be logged in)
|
||||
- ✓ Availability calendar (must see open slots)
|
||||
- ⚠️ Payment system (can launch with "pay in person" temporarily)
|
||||
- ⚠️ Notifications (can launch without, add later)
|
||||
|
||||
**Recommendation:** Launch MVP with auth + calendar, add payments in Sprint 2.
|
||||
```
|
||||
|
||||
### Stage 5: Create Handoff Package (30-45 minutes)
|
||||
|
||||
**Organize for development team:**
|
||||
|
||||
In `E-UI-Roadmap/` folder, create:
|
||||
|
||||
1. **`priority-sequence.md`** - What to build when and why
|
||||
2. **`scenario-to-epic-mapping.md`** - How WDS scenarios map to dev epics
|
||||
3. **`component-inventory.md`** (if Design System enabled) - All components needed
|
||||
4. **`open-questions.md`** - Decisions for dev team to make
|
||||
|
||||
---
|
||||
|
||||
## The Complete PRD Structure
|
||||
|
||||
Your finalized PRD in `C-Requirements/` combines all phases:
|
||||
|
||||
```markdown
|
||||
# Product Requirements Document
|
||||
|
||||
## 1. Technical Foundation (from Phase 3)
|
||||
|
||||
### Platform Architecture
|
||||
- Technology stack decisions
|
||||
- Infrastructure approach
|
||||
- Hosting and deployment
|
||||
|
||||
### Data Model
|
||||
- Core entities and relationships
|
||||
- Database schema
|
||||
- Data flow diagrams
|
||||
|
||||
### Integrations
|
||||
- External services (Google Maps, Stripe, etc.)
|
||||
- API specifications
|
||||
- Authentication providers
|
||||
|
||||
### Security & Performance
|
||||
- Authentication/authorization approach
|
||||
- Data protection
|
||||
- Performance requirements
|
||||
- Proofs of concept results
|
||||
|
||||
## 2. Functional Requirements (from Phase 4)
|
||||
|
||||
### Epic 1: User Authentication & Account Management
|
||||
**Features:**
|
||||
- User registration (Required by: 1.2-Sign-Up)
|
||||
- User login (Required by: 1.1-Start-Page, multiple)
|
||||
- Password management (Required by: 1.1-Start-Page)
|
||||
|
||||
[Detailed specifications for each feature]
|
||||
|
||||
### Epic 2: [Next Epic]
|
||||
[...]
|
||||
|
||||
## 3. Development Roadmap (from Phase 6)
|
||||
|
||||
### Priority 1: MVP (Weeks 1-4)
|
||||
- Features list with Impact Scores
|
||||
- Why these first (references Trigger Map)
|
||||
- Timeline estimate
|
||||
- Dependencies
|
||||
|
||||
### Priority 2: Enhanced Features (Weeks 5-8)
|
||||
[...]
|
||||
|
||||
## 4. Dependencies & Constraints
|
||||
- Technical dependencies between features
|
||||
- Design constraints from Phase 4
|
||||
- Third-party limitations discovered in Phase 3
|
||||
|
||||
## 5. Success Metrics
|
||||
- Business goals from Phase 1
|
||||
- Feature-specific KPIs
|
||||
- How we measure success
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Continuous vs. Final Handoff
|
||||
|
||||
**The pattern:**
|
||||
|
||||
- **Phase 3:** Initial PRD with technical foundation
|
||||
- **Phase 4:** PRD grows with each page (step 4E adds requirements)
|
||||
- **Phase 6 (First time):** Organize MVP scope from completed scenarios
|
||||
- Create first handoff package
|
||||
- Development can begin
|
||||
- **Phase 4 continues:** More pages designed, more requirements added
|
||||
- **Phase 6 (Ongoing):** Update PRD priorities, create new handoff packages
|
||||
- Weekly or bi-weekly updates
|
||||
- Keep dev team synced
|
||||
|
||||
**You can run Phase 6 multiple times as design progresses.**
|
||||
|
||||
---
|
||||
|
||||
## When to Use This Phase
|
||||
|
||||
**First PRD Finalization when:**
|
||||
- You have MVP-level scenarios complete (enough for dev to start)
|
||||
- Core user flows are specified
|
||||
- Critical features are documented
|
||||
- Enough work for 2-4 week sprint
|
||||
|
||||
**Ongoing PRD Updates as:**
|
||||
- Additional scenarios complete
|
||||
- New feature areas designed
|
||||
- Priorities shift based on learning
|
||||
- Sprint planning needs updated scope
|
||||
|
||||
**Timeline example:**
|
||||
|
||||
```
|
||||
Week 1-2: Phase 1-3 (Strategy, Research, Platform foundation)
|
||||
Week 3-4: Phase 4 Scenarios 1-3 (Core MVP flows)
|
||||
Week 5: Phase 6 First Finalization
|
||||
└──► PRD v1.0: MVP scope ready
|
||||
└──► Development Sprint 1 begins
|
||||
|
||||
Week 6-7: Phase 4 Scenarios 4-6 (Additional features)
|
||||
Phase 5 Design System (extract components)
|
||||
Week 8: Phase 6 Update
|
||||
└──► PRD v1.1: Sprint 2 scope added
|
||||
└──► Development Sprint 2 begins
|
||||
|
||||
Week 9+: Design continues in parallel with development
|
||||
Regular Phase 6 updates for new sprints
|
||||
```
|
||||
|
||||
**The beauty:** Design doesn't block development. You hand off in waves.
|
||||
|
||||
Complete list for test automation:
|
||||
|
||||
| Scenario | Object ID | Element Type | Notes |
|
||||
|----------|-----------|--------------|-------|
|
||||
| 1.1 | `welcome-hero-cta` | Button | Primary action |
|
||||
| 1.1 | `welcome-signin-link` | Link | Secondary action |
|
||||
| 1.2 | `signin-email-input` | Input | Required field |
|
||||
| 1.2 | `signin-error-email` | Error | Validation message |
|
||||
|
||||
---
|
||||
|
||||
## How It Works
|
||||
|
||||
### Review Completeness
|
||||
|
||||
Before handoff, verify:
|
||||
- All scenarios specified and reviewed
|
||||
- Design system covers all components
|
||||
- Object IDs assigned throughout
|
||||
- Multilingual content complete
|
||||
- HTML prototypes validated
|
||||
|
||||
### Identify Priorities
|
||||
|
||||
With Freyja, map your Trigger Map priorities to development order:
|
||||
- Which user triggers are most critical?
|
||||
- What's the minimum viable experience?
|
||||
- What can wait for later releases?
|
||||
|
||||
### Document Technical Context
|
||||
|
||||
Capture what developers need to know:
|
||||
- Design decisions and their rationale
|
||||
- Technical constraints discovered during design
|
||||
- Interaction patterns that need special attention
|
||||
- Performance considerations
|
||||
|
||||
### Create the Handoff
|
||||
|
||||
Organize everything into the UI Roadmap folder:
|
||||
- Clear priority sequence
|
||||
- Complete component inventory
|
||||
- Technical notes and open questions
|
||||
- Verification checklist
|
||||
|
||||
---
|
||||
|
||||
## The Handoff Checklist
|
||||
|
||||
```markdown
|
||||
## Design Handoff Verification
|
||||
|
||||
### Product Foundation
|
||||
- [ ] Product Brief complete and current
|
||||
- [ ] Trigger Map with prioritized users and goals
|
||||
- [ ] ICP clearly defined
|
||||
|
||||
### Requirements
|
||||
- [ ] PRD with technical specifications
|
||||
- [ ] Platform architecture documented
|
||||
- [ ] Integration requirements listed
|
||||
|
||||
### Visual Design
|
||||
- [ ] All scenarios have specifications
|
||||
- [ ] All pages have Object IDs
|
||||
- [ ] States documented (empty, loading, error, success)
|
||||
|
||||
### Design System
|
||||
- [ ] All components documented
|
||||
- [ ] Design tokens defined
|
||||
- [ ] Usage guidelines written
|
||||
|
||||
### Validation
|
||||
- [ ] HTML prototypes created for key scenarios
|
||||
- [ ] Stakeholder review complete
|
||||
- [ ] Open questions documented
|
||||
|
||||
### Ready for Development ✅
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## When to Use This Phase
|
||||
|
||||
**First handoff when:**
|
||||
- You have enough scenarios for MVP
|
||||
- Core user flows are specified
|
||||
- Critical components are documented
|
||||
- Developers can start building foundational features
|
||||
|
||||
**Ongoing handoffs as:**
|
||||
- Each major scenario completes
|
||||
- New component patterns emerge
|
||||
- Design decisions affect development
|
||||
- Sprint planning needs updated priorities
|
||||
|
||||
**The rhythm:**
|
||||
|
||||
```
|
||||
Week 1-2: Design Phase 1-3 (Strategy, Research, Platform)
|
||||
Week 3-4: Design Phase 4 Scenarios 1-2 (Core flows)
|
||||
└──► First Handoff: MVP scope
|
||||
Week 5-6: Design Phase 4 Scenarios 3-4
|
||||
Design Phase 5 (Components from 1-2)
|
||||
└──► Second Handoff: Additional features
|
||||
Week 7+: Design continues...
|
||||
Development builds in parallel
|
||||
└──► Ongoing handoffs as design progresses
|
||||
```
|
||||
|
||||
**You DON'T need to finish all design before handing off.**
|
||||
|
||||
Development and design work in parallel streams, with regular sync points.
|
||||
|
||||
---
|
||||
|
||||
## What to Prepare
|
||||
|
||||
Bring:
|
||||
- Completed scenario specifications (Phase 4)
|
||||
- Design System (Phase 5)
|
||||
- PRD (Phase 3)
|
||||
- Trigger Map priorities (Phase 2)
|
||||
|
||||
---
|
||||
|
||||
## What Comes Next
|
||||
|
||||
Your UI Roadmap enables:
|
||||
|
||||
- **Development kickoff** - Clear starting point
|
||||
- **Sprint planning** - Prioritized work items
|
||||
- **Test automation** - Object ID inventory
|
||||
- **QA validation** - Specifications to verify against
|
||||
|
||||
---
|
||||
|
||||
## Tips for Great Sessions
|
||||
|
||||
**Think from dev perspective**
|
||||
- What questions will developers have?
|
||||
- What decisions can't you make for them?
|
||||
- What context will save them time?
|
||||
|
||||
**Be explicit about priorities**
|
||||
- Not everything is Priority 1
|
||||
- Make trade-offs visible
|
||||
- Connect priorities to business goals
|
||||
|
||||
**Document the unknowns**
|
||||
- Open questions are valuable
|
||||
- Don't pretend certainty you don't have
|
||||
- Let dev team contribute decisions
|
||||
|
||||
**Keep it updated**
|
||||
- Handoff is ongoing, not one-time
|
||||
- Update as design evolves
|
||||
- Maintain as source of truth
|
||||
|
||||
---
|
||||
|
||||
## Integration with BMM
|
||||
|
||||
When handing off to BMad Method (BMM) for development:
|
||||
|
||||
```
|
||||
WDS → E-UI-Roadmap/ → BMM Architecture & Stories
|
||||
```
|
||||
|
||||
The UI Roadmap provides:
|
||||
- Context for architecture decisions
|
||||
- Specifications for story creation
|
||||
- Priorities for sprint planning
|
||||
- Test automation foundations
|
||||
|
||||
---
|
||||
|
||||
## Example Output
|
||||
|
||||
See: `examples/dog-week-patterns/E-UI-Roadmap/` for a complete UI Roadmap from a real project.
|
||||
|
||||
---
|
||||
|
||||
*Phase 6 of the Whiteport Design Studio method*
|
||||
|
||||
|
|
@ -0,0 +1,351 @@
|
|||
# Whiteport Design Studio Method
|
||||
|
||||
**A design-first methodology for creating software that people love**
|
||||
|
||||
---
|
||||
|
||||
## The WDS Philosophy
|
||||
|
||||
**Providing a thinking partner to every designer on the planet** - enabling designers everywhere to give more of what is valuable to the world. With deep understanding of users, technology, and what drives people, we provide functionality, beauty, simplicity, and make software endlessly successful by giving people both what they want and what they need.
|
||||
|
||||
---
|
||||
|
||||
## What is WDS?
|
||||
|
||||
Whiteport Design Studio is a **design-focused methodology** that supports designers in their design process and helps create detailed specifications through collaborative workshops, visual thinking, and systematic documentation perfect for development by AI and humans alike.
|
||||
|
||||
WDS creates the **design artifacts** that development teams need to build exceptional products - from initial vision through detailed component specifications.
|
||||
|
||||
### The Core Idea
|
||||
|
||||
```
|
||||
Vision → Clarity → UX Design → Design System → PRD Complete
|
||||
│ │ │ │ │
|
||||
│ │ │ │ └── Development
|
||||
│ │ │ │ gets everything
|
||||
│ │ │ │
|
||||
│ │ │ └── Components,
|
||||
│ │ │ tokens, patterns
|
||||
│ │ │ (optional, parallel)
|
||||
│ │ │
|
||||
│ │ └── Sketching, specifying,
|
||||
│ │ prototyping, PRD grows
|
||||
│ │
|
||||
│ └── Trigger mapping,
|
||||
│ Feature Impact Analysis
|
||||
│
|
||||
└── Strategic foundation,
|
||||
positioning, ICP
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## The Six Phases
|
||||
|
||||
WDS follows six phases, each producing artifacts in your project's `docs/` folder:
|
||||
|
||||
### Phase 1: Product Exploration (Product Brief)
|
||||
**Output:** `A-Product-Brief/`
|
||||
**Agent:** Saga the Analyst
|
||||
|
||||
Establish your strategic foundation through conversational discovery. Instead of filling out questionnaires, you have a conversation that builds understanding organically.
|
||||
|
||||
**What you create:**
|
||||
- Product vision and problem statement
|
||||
- Market positioning and differentiation
|
||||
- Success criteria and metrics
|
||||
- Strategic context for everything that follows
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Trigger Mapping (Trigger Map)
|
||||
**Output:** `B-Trigger-Map/`
|
||||
**Agent:** Saga the Analyst
|
||||
|
||||
Connect business goals to user psychology through Trigger Mapping. Discover not just WHO your users are, but WHY they act and WHAT triggers their decisions.
|
||||
|
||||
**What you create:**
|
||||
- Business goals (Vision + SMART objectives)
|
||||
- Target groups connected to business outcomes
|
||||
- Detailed personas with psychological depth
|
||||
- Usage goals (positive and negative driving forces)
|
||||
- Visual trigger map showing strategic connections
|
||||
- Feature Impact Analysis with priority scoring
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: PRD Platform (Technical Foundation)
|
||||
**Output:** `C-Requirements/`
|
||||
**Agent:** Freyja the PM
|
||||
|
||||
Prove your concept works technically - in parallel with design work. Validate platform decisions, create proofs of concept, and set up experimental endpoints.
|
||||
|
||||
**What you create:**
|
||||
- Platform architecture decisions
|
||||
- Data model and integrations
|
||||
- Technical proofs of concept
|
||||
- Experimental endpoints
|
||||
- Security and performance framework
|
||||
- Technical constraints document (for UX Design)
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: UX Design (UX-Sketches & Usage Scenarios)
|
||||
**Output:** `C-Scenarios/`
|
||||
**Agent:** Baldr the UX Expert
|
||||
|
||||
Transform ideas into detailed visual specifications. Your agent helps you think out the design, assists in sketching, creates specifications, and builds HTML prototypes. Each page adds functional requirements to the PRD.
|
||||
|
||||
**The key insight:** Designs that can be logically explained without gaps are easy to develop. The specification process reveals gaps early - when they're easy to address.
|
||||
|
||||
**What you create:**
|
||||
- Scenario folder structure (numbered hierarchy)
|
||||
- Page specifications with full detail
|
||||
- Component definitions with Object IDs
|
||||
- Interaction behaviors and states
|
||||
- HTML prototypes for validation
|
||||
- Functional requirements added to PRD (via step 4E)
|
||||
|
||||
---
|
||||
|
||||
### Phase 5: Design System (Component Library)
|
||||
**Output:** `D-Design-System/`
|
||||
**Agent:** Baldr the UX Expert
|
||||
|
||||
Build your component library following atomic design principles. This phase is **optional** and runs **in parallel** with Phase 4 - as you design pages, you extract reusable components.
|
||||
|
||||
**What you create:**
|
||||
- Design tokens (colors, typography, spacing)
|
||||
- Atomic components (buttons, inputs, labels)
|
||||
- Molecular components (form groups, cards)
|
||||
- Organism components (headers, complex sections)
|
||||
- Interactive HTML component showcase
|
||||
- Figma/design tool integration with unified naming
|
||||
|
||||
---
|
||||
|
||||
### Phase 6: PRD Finalization (Complete PRD)
|
||||
**Output:** Complete PRD in `C-Requirements/` + `E-UI-Roadmap/`
|
||||
**Agent:** Freyja the PM
|
||||
|
||||
Compile all functional requirements discovered during Phase 4 into a complete, development-ready PRD. This phase runs **continuously** - hand off as soon as you have MVP scope, then update as design progresses.
|
||||
|
||||
**What you create:**
|
||||
- Complete PRD (Platform + Functional requirements)
|
||||
- Feature organization by epic/area
|
||||
- Development sequence with priorities
|
||||
- Handoff package in `E-UI-Roadmap/`
|
||||
- Scenario-to-epic mapping
|
||||
|
||||
---
|
||||
|
||||
## Folder Structure
|
||||
|
||||
WDS creates an organized folder structure in your project's `docs/` folder. During setup, you make two choices:
|
||||
|
||||
### Your 4 Options
|
||||
|
||||
| Choice | Option A | Option B |
|
||||
|--------|----------|----------|
|
||||
| **Prefix** | Letters (A, B, C...) | Numbers (01, 02, 03...) |
|
||||
| **Case** | Title-Case | lowercase |
|
||||
|
||||
### Examples
|
||||
|
||||
**Letters + Title-Case** (default):
|
||||
```
|
||||
docs/
|
||||
├── A-Product-Brief/
|
||||
├── B-Trigger-Map/
|
||||
├── C-Platform-Requirements/
|
||||
├── C-Scenarios/
|
||||
├── D-Design-System/
|
||||
└── E-PRD-Finalization/
|
||||
```
|
||||
|
||||
**Numbers + Title-Case**:
|
||||
```
|
||||
docs/
|
||||
├── 01-Product-Brief/
|
||||
├── 02-Trigger-Map/
|
||||
├── 03-Platform-Requirements/
|
||||
├── 03-Scenarios/
|
||||
├── 04-Design-System/
|
||||
└── 05-PRD-Finalization/
|
||||
```
|
||||
|
||||
**Default (Letters + Title-Case) is recommended because:**
|
||||
- Title-Case is easier for non-technical people to read
|
||||
- Letters create distinctive WDS branding
|
||||
- Distinguishes WDS folders from other docs
|
||||
|
||||
---
|
||||
|
||||
## Phase-Selectable Workflow
|
||||
|
||||
Not every project needs all six phases. Select what you need based on your situation:
|
||||
|
||||
| Project Type | Recommended Phases |
|
||||
|--------------|-------------------|
|
||||
| **Landing page** | 1, 4 |
|
||||
| **Full product (greenfield)** | All six |
|
||||
| **Feature enhancement** | 2, 4, 6 |
|
||||
| **Design system only** | 4, 5 |
|
||||
| **Strategic planning** | 1, 2 |
|
||||
| **Quick prototype** | 4 only |
|
||||
|
||||
Your agents will help you identify which phases fit your project.
|
||||
|
||||
---
|
||||
|
||||
## Your Agents
|
||||
|
||||
Three specialized agents guide you through WDS:
|
||||
|
||||
### Saga the Analyst 📚
|
||||
*"The one who tells your business story"*
|
||||
|
||||
Saga guides you through discovery and research. She's curious, patient, and helps you uncover insights you might not have seen yourself.
|
||||
|
||||
**Works with you on:**
|
||||
- Phase 1: Product Exploration
|
||||
- Phase 2: Trigger Mapping
|
||||
|
||||
### Freyja the PM ⚔️
|
||||
*"The strategic leader who sees what must be done"*
|
||||
|
||||
Freyja helps you define technical requirements and finalize the PRD for development. She balances passion with strategy, knowing when to be fierce and when to be patient.
|
||||
|
||||
**Works with you on:**
|
||||
- Phase 3: PRD Platform
|
||||
- Phase 6: PRD Finalization
|
||||
|
||||
### Baldr the UX Expert ✨
|
||||
*"The one who brings light and beauty"*
|
||||
|
||||
Baldr transforms your ideas into beautiful, detailed specifications. He cares deeply about craft and ensures every detail serves the user experience.
|
||||
|
||||
**Works with you on:**
|
||||
- Phase 4: UX Design
|
||||
- Phase 5: Design System
|
||||
|
||||
---
|
||||
|
||||
## How Sessions Work
|
||||
|
||||
WDS sessions are **conversations, not interrogations**.
|
||||
|
||||
### The Rhythm
|
||||
|
||||
A good WDS session feels like coffee with a wise mentor:
|
||||
- They ask something interesting
|
||||
- You share your thinking
|
||||
- They reflect it back, maybe adding a new angle
|
||||
- Together you discover something neither saw alone
|
||||
|
||||
It never feels like filling out a form.
|
||||
|
||||
### What to Expect
|
||||
|
||||
**Your agent will:**
|
||||
- Ask one question at a time, then listen
|
||||
- Reflect back what they heard before moving on
|
||||
- Build documents together with you, piece by piece
|
||||
- Check in to make sure they understood correctly
|
||||
|
||||
**You'll leave with:**
|
||||
- Clear documentation you helped create
|
||||
- Deeper understanding of your own product
|
||||
- Ready-to-use artifacts for the next phase
|
||||
|
||||
---
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Prerequisites
|
||||
|
||||
1. BMad Method installed with WDS module
|
||||
2. Project workspace ready
|
||||
3. Stakeholders available for workshop phases
|
||||
|
||||
### Quick Start
|
||||
|
||||
```
|
||||
# Install BMad with WDS
|
||||
npx bmad-method@alpha install
|
||||
|
||||
# Activate any WDS agent
|
||||
# They'll guide you from there
|
||||
|
||||
# Or run workflow-init for phase selection
|
||||
*workflow-init
|
||||
```
|
||||
|
||||
### First Steps
|
||||
|
||||
1. **Start with Phase 1** if you're building something new
|
||||
2. **Start with Phase 2** if you have existing vision but need user clarity
|
||||
3. **Start with Phase 4** if you have sketches ready to specify
|
||||
4. **Ask your agent** if you're not sure where to begin
|
||||
|
||||
---
|
||||
|
||||
## The WDS Difference
|
||||
|
||||
### Traditional Approach
|
||||
- 47-question requirements spreadsheet
|
||||
- Generic persona templates
|
||||
- Designers work alone, then throw specs "over the wall"
|
||||
- Developers interpret and guess
|
||||
- Everyone argues about what was meant
|
||||
|
||||
### WDS Approach
|
||||
- Conversations that build understanding
|
||||
- Personas with psychological depth connected to business goals
|
||||
- Collaborative workshops building shared understanding
|
||||
- Specifications so clear they eliminate guesswork
|
||||
- Everyone aligned because they built it together
|
||||
|
||||
---
|
||||
|
||||
## Integration with Development
|
||||
|
||||
WDS focuses on **design** - creating the artifacts that guide development. The actual development process is handled by BMad Method (BMM) or your preferred development workflow.
|
||||
|
||||
### The PRD Journey
|
||||
|
||||
```
|
||||
Phase 3: PRD starts Phase 4: PRD grows Phase 6: PRD completes
|
||||
(Technical Foundation) (Each page adds features) (Organized for dev)
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
C-Requirements/ ────► C-Requirements/ ────► E-UI-Roadmap/
|
||||
├── Platform arch ├── Platform arch ├── Priority sequence
|
||||
├── Data model ├── Data model ├── Epic mapping
|
||||
├── Integrations ├── Integrations ├── Component inventory
|
||||
└── Security └── Functional reqs ◄──┐ └── Handoff checklist
|
||||
(from each page) │
|
||||
│
|
||||
C-Scenarios/ ─────────┘
|
||||
(Page specs add features via 4E)
|
||||
```
|
||||
|
||||
### Parallel Streams
|
||||
|
||||
Design and development can work in parallel:
|
||||
- Phase 3 complete → Backend/platform development can start
|
||||
- Phase 4 MVP scenarios complete → Phase 6 first handoff → Sprint 1 begins
|
||||
- Design continues → Regular Phase 6 updates → More sprints
|
||||
|
||||
---
|
||||
|
||||
## Learn More
|
||||
|
||||
- **Phase guides:** Detailed documentation for each phase
|
||||
- **Examples:** Dog Week patterns showing real artifacts
|
||||
- **Templates:** Ready-to-use templates for all deliverables
|
||||
- **Conversation examples:** See how agent sessions flow
|
||||
|
||||
---
|
||||
|
||||
*Whiteport Design Studio - Part of the BMad ecosystem*
|
||||
|
|
@ -0,0 +1,60 @@
|
|||
# Installation
|
||||
|
||||
**Get WDS up and running in 5 minutes**
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Node.js 18+ installed
|
||||
- Git installed
|
||||
- Code editor (VS Code recommended)
|
||||
|
||||
---
|
||||
|
||||
## Quick Install
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/whiteport-collective/whiteport-design-studio.git
|
||||
|
||||
# Navigate to the directory
|
||||
cd whiteport-design-studio
|
||||
|
||||
# Install dependencies
|
||||
npm install
|
||||
|
||||
# Start WDS
|
||||
npm start
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Verify Installation
|
||||
|
||||
You should see:
|
||||
```
|
||||
✅ WDS is running
|
||||
🎨 Ready to design
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Quick Start Guide](quick-start.md) - Your first 5 minutes
|
||||
- [Tutorial](../01-tutorial/00-TUTORIAL-GUIDE.md) - Learn the concepts deeply
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Issue:** Node version error
|
||||
**Solution:** Update to Node.js 18 or higher
|
||||
|
||||
**Issue:** Permission denied
|
||||
**Solution:** Run with appropriate permissions or use `sudo` (Mac/Linux)
|
||||
|
||||
---
|
||||
|
||||
[← Back to WDS](../WDS-WORKFLOWS-GUIDE.md)
|
||||
|
|
@ -0,0 +1,121 @@
|
|||
# Quick Start
|
||||
|
||||
**Your first 5 minutes with WDS**
|
||||
|
||||
---
|
||||
|
||||
## What You'll Do
|
||||
|
||||
1. Create a Trigger Map
|
||||
2. Initialize a scenario
|
||||
3. Sketch your first page
|
||||
4. Generate specifications
|
||||
|
||||
**Time: 5 minutes**
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Start WDS
|
||||
|
||||
```bash
|
||||
npm start
|
||||
```
|
||||
|
||||
Agent: "Welcome to Whiteport Design Studio! Ready to start?"
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Create Trigger Map
|
||||
|
||||
```
|
||||
You: "Let's create a Trigger Map for a dog walking app"
|
||||
|
||||
Agent: "Great! Who is your primary target group?"
|
||||
You: "Parents who struggle with family dog care coordination"
|
||||
|
||||
Agent: "What triggers their need?"
|
||||
You: "Family conflict over who walks the dog"
|
||||
|
||||
Agent: "What outcome do they want?"
|
||||
You: "Accountability without nagging"
|
||||
```
|
||||
|
||||
**✅ Trigger Map created**
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Initialize Scenario
|
||||
|
||||
```
|
||||
Agent: "What feature delivers the most value to parents?"
|
||||
You: "Family dog walk calendar"
|
||||
|
||||
Agent: "Where do they first encounter this?"
|
||||
You: "Google search - frustrated with conflict"
|
||||
|
||||
Agent: "What's the shortest path to mutual success?"
|
||||
You: "Landing → Sign up → Family setup → Calendar → First walk"
|
||||
```
|
||||
|
||||
**✅ Scenario initialized**
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Sketch First Page
|
||||
|
||||
```
|
||||
Agent: "Let's start with the Landing page. Upload your sketch."
|
||||
You: [Upload sketch]
|
||||
|
||||
Agent: "I see: Header, Hero section, How it works, Sign up CTA.
|
||||
Should I analyze these sections?"
|
||||
You: "Yes"
|
||||
```
|
||||
|
||||
**✅ Sketch analyzed**
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Generate Specifications
|
||||
|
||||
```
|
||||
Agent: "Based on your Trigger Map:
|
||||
- Target: Parents (tired of nagging)
|
||||
- Trigger: Family conflict
|
||||
|
||||
For the Hero section, I suggest:
|
||||
Headline: 'Stop Nagging. Start Harmony.'
|
||||
|
||||
Does this address their frustration?"
|
||||
|
||||
You: "Perfect!"
|
||||
```
|
||||
|
||||
**✅ Specifications generated**
|
||||
|
||||
---
|
||||
|
||||
## What Just Happened?
|
||||
|
||||
You created **why-based specifications** in 5 minutes:
|
||||
- Connected to user psychology (Trigger Map)
|
||||
- Grounded in real context (Scenario Init)
|
||||
- Generated with AI assistance (Agent collaboration)
|
||||
- Preserved your thinking (Why-based specs)
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
### Learn the Concepts
|
||||
[Tutorial](../01-tutorial/00-TUTORIAL-GUIDE.md) - Deep dive into WDS philosophy
|
||||
|
||||
### Start Your Project
|
||||
[Workflows Guide](../WDS-WORKFLOWS-GUIDE.md) - Full workflow documentation
|
||||
|
||||
### Get Help
|
||||
[Community](https://discord.gg/whiteport) - Join the WDS community
|
||||
|
||||
---
|
||||
|
||||
[← Back to Getting Started](installation.md)
|
||||
|
|
@ -0,0 +1,131 @@
|
|||
# Where to Go Next
|
||||
|
||||
**You've installed WDS and completed the quick start. Now what?**
|
||||
|
||||
---
|
||||
|
||||
## Choose Your Path
|
||||
|
||||
### 🎓 Take the Course
|
||||
|
||||
**[WDS Course: From Designer to Linchpin](../course/00-course-overview.md)**
|
||||
|
||||
Complete training from project brief to AI-ready specifications:
|
||||
|
||||
**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)
|
||||
|
||||
**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)
|
||||
|
||||
---
|
||||
|
||||
### 🚀 Start Your Project
|
||||
|
||||
**[Workflows Guide](../WDS-WORKFLOWS-GUIDE.md)**
|
||||
|
||||
Step-by-step workflows for:
|
||||
|
||||
**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: 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: Platform Requirements**
|
||||
Document technical constraints, integrations, and infrastructure needs.
|
||||
→ [Workflows Guide](../WDS-WORKFLOWS-GUIDE.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
|
||||
|
||||
**Time:** Ongoing (project-based)
|
||||
|
||||
---
|
||||
|
||||
### 📚 Reference Documentation
|
||||
|
||||
**[Modular Architecture](../workflows/4-ux-design/modular-architecture/00-MODULAR-ARCHITECTURE-GUIDE.md)**
|
||||
|
||||
Technical details on:
|
||||
- Three-tier file structure
|
||||
- Content placement rules
|
||||
- Component decomposition
|
||||
- Storyboard integration
|
||||
|
||||
**Best for:** Looking up specific techniques
|
||||
|
||||
**Time:** As needed (reference)
|
||||
|
||||
---
|
||||
|
||||
## Recommended Learning Path
|
||||
|
||||
```
|
||||
1. Quick Start (5 min) ✅ You are here
|
||||
↓
|
||||
2. Tutorial (1-2 hours)
|
||||
Watch videos, understand concepts
|
||||
↓
|
||||
3. Your First Project (ongoing)
|
||||
Apply WDS to a real project
|
||||
↓
|
||||
4. Reference Docs (as needed)
|
||||
Look up specific techniques
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Community & Support
|
||||
|
||||
### Discord
|
||||
Join the WDS community for:
|
||||
- Questions and answers
|
||||
- Project feedback
|
||||
- Feature discussions
|
||||
|
||||
### GitHub
|
||||
- Report issues
|
||||
- Request features
|
||||
- Contribute
|
||||
|
||||
### YouTube
|
||||
- Video tutorials
|
||||
- Walkthroughs
|
||||
- Case studies
|
||||
|
||||
---
|
||||
|
||||
## Quick Links
|
||||
|
||||
- [Tutorial](../01-tutorial/00-TUTORIAL-GUIDE.md)
|
||||
- [Workflows](../WDS-WORKFLOWS-GUIDE.md)
|
||||
- [Modular Architecture](../workflows/4-ux-design/modular-architecture/00-MODULAR-ARCHITECTURE-GUIDE.md)
|
||||
- [Why-Based Specifications](../workflows/4-ux-design/WHY-BASED-SPECIFICATIONS.md)
|
||||
|
||||
---
|
||||
|
||||
**Ready to dive deeper? Start with the [Tutorial](../01-tutorial/00-TUTORIAL-GUIDE.md)!**
|
||||
|
||||
---
|
||||
|
||||
[← Back to Quick Start](quick-start.md)
|
||||
|
|
@ -0,0 +1,104 @@
|
|||
# WDS Design Delivery Template
|
||||
# Copy this template to: deliveries/DD-XXX-name.yaml
|
||||
|
||||
delivery:
|
||||
id: "DD-XXX" # Format: DD-001, DD-002, etc.
|
||||
name: "Feature Name" # Human-readable name
|
||||
type: "user_flow" # user_flow | feature | component
|
||||
status: "ready" # ready | in_progress | blocked
|
||||
priority: "high" # high | medium | low
|
||||
created_by: "wds-ux-expert"
|
||||
created_at: "YYYY-MM-DDTHH:MM:SSZ"
|
||||
updated_at: "YYYY-MM-DDTHH:MM:SSZ"
|
||||
version: "1.0"
|
||||
|
||||
description: |
|
||||
[Describe what this delivery contains and why it matters.
|
||||
Include the complete user flow and key features.]
|
||||
|
||||
user_value:
|
||||
problem: "[What user problem does this solve?]"
|
||||
solution: "[How does this feature solve it?]"
|
||||
success_criteria:
|
||||
- "[Measurable success criterion 1]"
|
||||
- "[Measurable success criterion 2]"
|
||||
- "[Measurable success criterion 3]"
|
||||
|
||||
design_artifacts:
|
||||
scenarios:
|
||||
- id: "XX-scenario-name"
|
||||
path: "C-Scenarios/XX-scenario-name/"
|
||||
screens: ["screen1", "screen2"]
|
||||
|
||||
- id: "XX-scenario-name"
|
||||
path: "C-Scenarios/XX-scenario-name/"
|
||||
screens: ["screen1"]
|
||||
|
||||
user_flows:
|
||||
- name: "Flow Name"
|
||||
path: "C-Scenarios/flows/flow-name.excalidraw"
|
||||
entry: "entry-screen"
|
||||
exit: "exit-screen"
|
||||
|
||||
design_system:
|
||||
components:
|
||||
- "Component Name (variants)"
|
||||
- "Component Name (variants)"
|
||||
path: "D-Design-System/"
|
||||
|
||||
technical_requirements:
|
||||
platform:
|
||||
frontend: "framework-name" # From platform-requirements.yaml
|
||||
backend: "framework-name" # From platform-requirements.yaml
|
||||
|
||||
integrations:
|
||||
- name: "integration-name"
|
||||
purpose: "[Why this integration is needed]"
|
||||
required: true # true | false
|
||||
|
||||
- name: "integration-name"
|
||||
purpose: "[Why this integration is needed]"
|
||||
required: false
|
||||
|
||||
data_models:
|
||||
- name: "ModelName"
|
||||
fields: ["field1", "field2", "field3"]
|
||||
|
||||
- name: "ModelName"
|
||||
fields: ["field1", "field2"]
|
||||
|
||||
acceptance_criteria:
|
||||
functional:
|
||||
- "[Functional requirement 1]"
|
||||
- "[Functional requirement 2]"
|
||||
- "[Functional requirement 3]"
|
||||
|
||||
non_functional:
|
||||
- "[Performance requirement]"
|
||||
- "[Accessibility requirement]"
|
||||
- "[Security requirement]"
|
||||
|
||||
edge_cases:
|
||||
- "[Edge case 1] → [Expected behavior]"
|
||||
- "[Edge case 2] → [Expected behavior]"
|
||||
- "[Edge case 3] → [Expected behavior]"
|
||||
|
||||
testing_guidance:
|
||||
user_testing:
|
||||
- "[User testing instruction 1]"
|
||||
- "[User testing instruction 2]"
|
||||
|
||||
qa_testing:
|
||||
- "[QA testing instruction 1]"
|
||||
- "[QA testing instruction 2]"
|
||||
- "[QA testing instruction 3]"
|
||||
|
||||
estimated_complexity:
|
||||
size: "medium" # small | medium | large
|
||||
effort: "2-3 weeks" # Time estimate
|
||||
risk: "low" # low | medium | high
|
||||
dependencies: [] # List of DD-XXX IDs needed first
|
||||
|
||||
notes: |
|
||||
[Any special considerations, important context, or
|
||||
critical details that the development team should know.]
|
||||
|
|
@ -0,0 +1,69 @@
|
|||
# WDS Platform Requirements Template
|
||||
# Save to: A-Project-Brief/platform-requirements.yaml
|
||||
|
||||
project:
|
||||
name: "Project Name"
|
||||
type: "mobile_app" # mobile_app | web_app | desktop_app | api
|
||||
wds_version: "6.0"
|
||||
created_at: "YYYY-MM-DDTHH:MM:SSZ"
|
||||
|
||||
platform:
|
||||
frontend:
|
||||
framework: "framework-name" # react_native | react | vue | angular | svelte
|
||||
version: "X.X"
|
||||
state_management: "library" # zustand | redux | mobx | context
|
||||
navigation: "library" # react_navigation | react_router | vue_router
|
||||
styling: "approach" # tailwind | styled_components | css_modules
|
||||
ui_library: "library" # shadcn | mui | chakra (optional)
|
||||
|
||||
backend:
|
||||
framework: "framework-name" # supabase | firebase | express | fastapi | django
|
||||
version: "X.X"
|
||||
auth: "auth-provider" # supabase_auth | firebase_auth | auth0 | custom
|
||||
database: "database-type" # postgresql | mysql | mongodb | firestore
|
||||
storage: "storage-provider" # supabase_storage | s3 | cloudinary
|
||||
api: "api-type" # rest | graphql | grpc
|
||||
|
||||
database:
|
||||
type: "database-type" # postgresql | mysql | mongodb
|
||||
version: "XX"
|
||||
orm: "orm-library" # prisma | typeorm | mongoose (optional)
|
||||
|
||||
deployment:
|
||||
frontend: "platform" # expo_eas | vercel | netlify | aws
|
||||
backend: "platform" # supabase_cloud | firebase | heroku | aws
|
||||
ci_cd: "platform" # github_actions | gitlab_ci | circle_ci
|
||||
hosting: "platform" # vercel | netlify | aws (if web app)
|
||||
|
||||
integrations:
|
||||
- name: "integration-name"
|
||||
provider: "provider-name"
|
||||
required: true # true | false
|
||||
purpose: "[Why this integration is needed]"
|
||||
|
||||
- name: "integration-name"
|
||||
provider: "provider-name"
|
||||
required: false
|
||||
purpose: "[Why this integration is needed]"
|
||||
|
||||
constraints:
|
||||
- "[Technical constraint 1]"
|
||||
- "[Technical constraint 2]"
|
||||
- "[Business constraint 1]"
|
||||
- "[Regulatory constraint 1]"
|
||||
|
||||
performance_requirements:
|
||||
- "[Performance requirement 1]"
|
||||
- "[Performance requirement 2]"
|
||||
- "[Performance requirement 3]"
|
||||
|
||||
security_requirements:
|
||||
- "[Security requirement 1]"
|
||||
- "[Security requirement 2]"
|
||||
- "[Security requirement 3]"
|
||||
|
||||
wds_metadata:
|
||||
project_brief: "A-Project-Brief/project-brief.md"
|
||||
trigger_map: "B-Trigger-Map/trigger-map.md"
|
||||
scenarios: "C-Scenarios/"
|
||||
design_system: "D-Design-System/"
|
||||
|
|
@ -0,0 +1,192 @@
|
|||
# WDS Test Scenario Template
|
||||
# Save to: test-scenarios/TS-XXX-name.yaml
|
||||
|
||||
test_scenario:
|
||||
id: "TS-XXX" # Format: TS-001, TS-002, etc.
|
||||
name: "Feature Testing" # Human-readable name
|
||||
delivery_id: "DD-XXX" # Related Design Delivery
|
||||
type: "user_acceptance" # user_acceptance | integration | e2e
|
||||
status: "ready" # ready | in_progress | blocked
|
||||
tester: "designer" # designer | qa | developer
|
||||
created_at: "YYYY-MM-DDTHH:MM:SSZ"
|
||||
|
||||
test_objectives:
|
||||
- "Validate implementation matches design specifications"
|
||||
- "Verify user flow is intuitive and smooth"
|
||||
- "Confirm all edge cases are handled"
|
||||
- "Ensure design system components are used correctly"
|
||||
- "Test accessibility and usability"
|
||||
|
||||
test_environment:
|
||||
devices:
|
||||
- "Device 1 (OS version)"
|
||||
- "Device 2 (OS version)"
|
||||
|
||||
test_data:
|
||||
- field: "value"
|
||||
- field: "value"
|
||||
|
||||
# Happy Path Tests
|
||||
happy_path:
|
||||
- id: "HP-001"
|
||||
name: "Main User Flow"
|
||||
priority: "critical" # critical | high | medium | low
|
||||
|
||||
steps:
|
||||
- action: "[User action]"
|
||||
expected: "[Expected result]"
|
||||
design_ref: "[Path to specification]#[section]"
|
||||
|
||||
- action: "[User action]"
|
||||
expected: "[Expected result]"
|
||||
design_ref: "[Path to specification]#[section]"
|
||||
|
||||
success_criteria:
|
||||
- "[Success criterion 1]"
|
||||
- "[Success criterion 2]"
|
||||
- "[Success criterion 3]"
|
||||
|
||||
# Error State Tests
|
||||
error_states:
|
||||
- id: "ES-001"
|
||||
name: "Error Scenario"
|
||||
priority: "high"
|
||||
|
||||
steps:
|
||||
- action: "[Action that triggers error]"
|
||||
- expected: "[Expected error message]"
|
||||
- expected: "[Expected recovery option]"
|
||||
- design_ref: "[Path to specification]#[error-section]"
|
||||
|
||||
success_criteria:
|
||||
- "[Error handling criterion 1]"
|
||||
- "[Error handling criterion 2]"
|
||||
|
||||
# Edge Case Tests
|
||||
edge_cases:
|
||||
- id: "EC-001"
|
||||
name: "Edge Case Scenario"
|
||||
priority: "medium"
|
||||
|
||||
steps:
|
||||
- action: "[Unusual action]"
|
||||
- expected: "[Expected handling]"
|
||||
- design_ref: "[Path to specification]#[edge-case-section]"
|
||||
|
||||
success_criteria:
|
||||
- "[Edge case criterion 1]"
|
||||
|
||||
# Design System Validation
|
||||
design_system_checks:
|
||||
- id: "DS-001"
|
||||
name: "Component Validation"
|
||||
checks:
|
||||
- component: "Component Name"
|
||||
instances: ["Location 1", "Location 2"]
|
||||
verify:
|
||||
- "[Visual property 1]"
|
||||
- "[Visual property 2]"
|
||||
- "[State behavior 1]"
|
||||
design_ref: "D-Design-System/path/to/component.md"
|
||||
|
||||
# Accessibility Tests
|
||||
accessibility:
|
||||
- id: "A11Y-001"
|
||||
name: "Screen Reader Navigation"
|
||||
priority: "high"
|
||||
|
||||
setup: "Enable screen reader (VoiceOver/TalkBack)"
|
||||
|
||||
steps:
|
||||
- action: "[Navigate with screen reader]"
|
||||
- verify:
|
||||
- "[Accessibility check 1]"
|
||||
- "[Accessibility check 2]"
|
||||
|
||||
success_criteria:
|
||||
- "[Accessibility criterion 1]"
|
||||
- "[Accessibility criterion 2]"
|
||||
|
||||
# Usability Tests
|
||||
usability:
|
||||
- id: "UX-001"
|
||||
name: "First Impression"
|
||||
type: "observational"
|
||||
|
||||
instructions: |
|
||||
[Instructions for conducting usability test]
|
||||
|
||||
success_criteria:
|
||||
- "[Usability criterion 1]"
|
||||
- "[Usability criterion 2]"
|
||||
|
||||
# Performance Tests
|
||||
performance:
|
||||
- id: "PERF-001"
|
||||
name: "Performance Check"
|
||||
|
||||
verify:
|
||||
- "[Performance metric 1]"
|
||||
- "[Performance metric 2]"
|
||||
|
||||
success_criteria:
|
||||
- "[Performance target 1]"
|
||||
- "[Performance target 2]"
|
||||
|
||||
# Test Report Template
|
||||
report_template:
|
||||
sections:
|
||||
- name: "Test Summary"
|
||||
fields:
|
||||
- "Date tested"
|
||||
- "Tester name"
|
||||
- "Device tested"
|
||||
- "Build version"
|
||||
- "Overall result (Pass/Fail/Partial)"
|
||||
|
||||
- name: "Happy Path Results"
|
||||
fields:
|
||||
- "Test ID"
|
||||
- "Result (Pass/Fail)"
|
||||
- "Notes"
|
||||
- "Screenshots"
|
||||
|
||||
- name: "Issues Found"
|
||||
fields:
|
||||
- "Issue ID"
|
||||
- "Severity (Critical/High/Medium/Low)"
|
||||
- "Description"
|
||||
- "Steps to reproduce"
|
||||
- "Expected vs Actual"
|
||||
- "Screenshot/Video"
|
||||
- "Design reference violated"
|
||||
|
||||
- name: "Design System Compliance"
|
||||
fields:
|
||||
- "Component"
|
||||
- "Compliant (Yes/No)"
|
||||
- "Deviations noted"
|
||||
|
||||
- name: "Recommendations"
|
||||
fields:
|
||||
- "What worked well"
|
||||
- "What needs improvement"
|
||||
- "Suggested changes"
|
||||
|
||||
# Sign-off Criteria
|
||||
sign_off:
|
||||
required_for_approval:
|
||||
- "All critical tests pass"
|
||||
- "No critical or high severity issues"
|
||||
- "Design system compliance > 95%"
|
||||
- "Accessibility tests pass"
|
||||
- "Usability metrics meet targets"
|
||||
|
||||
designer_approval:
|
||||
statement: |
|
||||
I confirm that the implemented feature matches the design
|
||||
specifications and meets the quality standards defined in
|
||||
this test scenario.
|
||||
|
||||
signature: "________________"
|
||||
date: "________________"
|
||||
|
|
@ -0,0 +1,183 @@
|
|||
# WDS-BMad Tutorial
|
||||
|
||||
**Complete training from project brief to AI-ready specifications**
|
||||
|
||||
---
|
||||
|
||||
## About This Tutorial
|
||||
|
||||
This tutorial teaches the complete WDS workflow through **16 chapters**.
|
||||
|
||||
Each chapter contains:
|
||||
- **Inspiration** - Why this step matters, the goal
|
||||
- **Teaching** - How to do it with confidence
|
||||
- **Practice** - Apply it to your own project
|
||||
|
||||
**Format:**
|
||||
- Read as documentation
|
||||
- Generate videos with NotebookLM
|
||||
- Use in workshops
|
||||
|
||||
**Time:** ~10 hours total (40 min per chapter)
|
||||
|
||||
---
|
||||
|
||||
## Tutorial Chapters
|
||||
|
||||
### Foundation
|
||||
|
||||
#### [Chapter 0: Why This Matters](chapter-00-why-this-matters/)
|
||||
Learn how to be indispensable in the AI era
|
||||
|
||||
---
|
||||
|
||||
### Phase 1: Project Brief
|
||||
|
||||
#### [Chapter 1.1: Create Project Brief](chapter-1.1-project-brief/)
|
||||
Define vision, goals, stakeholders, and constraints
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Trigger Mapping
|
||||
|
||||
#### [Chapter 2.1: Identify Target Groups](chapter-2.1-identify-target-groups/)
|
||||
WHO are your users and how to prioritize them
|
||||
|
||||
#### [Chapter 2.2: Map Triggers & Outcomes](chapter-2.2-map-triggers-outcomes/)
|
||||
WHAT triggers needs and WHY your business exists
|
||||
|
||||
#### [Chapter 2.3: Prioritize Features](chapter-2.3-prioritize-features/)
|
||||
Which features serve your top triggers
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Platform Requirements
|
||||
|
||||
#### [Chapter 3.1: Platform Requirements](chapter-3.1-platform-requirements/)
|
||||
Technical constraints, integrations, infrastructure
|
||||
|
||||
#### [Chapter 3.2: Functional Requirements](chapter-3.2-functional-requirements/)
|
||||
What the system must do
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Conceptual Design
|
||||
|
||||
#### [Chapter 4.1: Initialize Scenario](chapter-4.1-initialize-scenario/)
|
||||
The 5 questions that define your design journey
|
||||
|
||||
#### [Chapter 4.2: Sketch Interfaces](chapter-4.2-sketch-interfaces/)
|
||||
Drawing pages with AI guidance
|
||||
|
||||
#### [Chapter 4.3: Analyze with AI](chapter-4.3-analyze-with-ai/)
|
||||
Upload sketches and have strategic conversations
|
||||
|
||||
#### [Chapter 4.4: Decompose Components](chapter-4.4-decompose-components/)
|
||||
Break pages into modular architecture
|
||||
|
||||
#### [Chapter 4.5: Why-Based Specifications](chapter-4.5-why-based-specs/)
|
||||
Document WHAT + WHY + WHAT NOT TO DO
|
||||
|
||||
#### [Chapter 4.6: Validate Specifications](chapter-4.6-validate-specifications/)
|
||||
Review completeness and test logic
|
||||
|
||||
---
|
||||
|
||||
### Phase 5: Design System
|
||||
|
||||
#### [Chapter 5.1: Extract Design Tokens](chapter-5.1-extract-design-tokens/)
|
||||
Colors, typography, spacing from your specs
|
||||
|
||||
#### [Chapter 5.2: Component Library](chapter-5.2-component-library/)
|
||||
Reusable patterns across scenarios
|
||||
|
||||
---
|
||||
|
||||
### Phase 6: Development Integration
|
||||
|
||||
#### [Chapter 6.1: UI Roadmap](chapter-6.1-ui-roadmap/)
|
||||
Development priorities and handoff
|
||||
|
||||
---
|
||||
|
||||
## How to Use This Tutorial
|
||||
|
||||
### Complete Workflow (Recommended)
|
||||
Work through all 16 chapters sequentially with your own project:
|
||||
```
|
||||
Chapters 1-16 → Complete design from brief to handoff
|
||||
Time: ~10 hours (spread over days/weeks)
|
||||
Result: Fully specified project ready for development
|
||||
```
|
||||
|
||||
### Quick Start (Core Concepts)
|
||||
Focus on the essential chapters:
|
||||
```
|
||||
Ch 0: Why This Matters
|
||||
Ch 2.2: Map Triggers & Outcomes
|
||||
Ch 4.1: Initialize Scenario
|
||||
Ch 4.5: Why-Based Specifications
|
||||
Time: ~3 hours
|
||||
Result: Understanding of core WDS philosophy
|
||||
```
|
||||
|
||||
### Phase-Specific Learning
|
||||
Jump to the phase you need:
|
||||
```
|
||||
Phase 2 (Ch 2.1-2.3): Trigger Mapping
|
||||
Phase 4 (Ch 4.1-4.6): Conceptual Design
|
||||
Phase 5 (Ch 5.1-5.2): Design System
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## NotebookLM Integration
|
||||
|
||||
Each chapter has a matching script in `/notebooklm-scripts/`:
|
||||
- Feed chapter scripts to NotebookLM
|
||||
- Generate audio podcasts
|
||||
- Generate video presentations
|
||||
- Create study guides
|
||||
|
||||
**All scripts match chapter numbers for easy reference.**
|
||||
|
||||
---
|
||||
|
||||
## Chapter Structure
|
||||
|
||||
Every chapter follows the same pattern:
|
||||
|
||||
**1. Inspiration (10 min)**
|
||||
- Why this step matters
|
||||
- The goal you're working toward
|
||||
- Real-world impact
|
||||
|
||||
**2. Teaching (20 min)**
|
||||
- How to do it with confidence
|
||||
- AI support at each step
|
||||
- Dog Week example walkthrough
|
||||
|
||||
**3. Practice (10 min)**
|
||||
- Apply to your own project
|
||||
- Step-by-step instructions
|
||||
- Success criteria
|
||||
|
||||
---
|
||||
|
||||
## After the Tutorial
|
||||
|
||||
Once you've completed chapters:
|
||||
|
||||
1. **[Workflows Guide](../WDS-WORKFLOWS-GUIDE.md)** - Reference documentation
|
||||
2. **[Quick Start](../getting-started/quick-start.md)** - Try WDS with agent
|
||||
3. **[Community](https://discord.gg/whiteport)** - Get help and share
|
||||
|
||||
---
|
||||
|
||||
## Start Learning
|
||||
|
||||
**[Begin with Chapter 0: Why This Matters →](chapter-00-why-this-matters/)**
|
||||
|
||||
---
|
||||
|
||||
[← Back to Getting Started](../getting-started/where-to-go-next.md)
|
||||
|
|
@ -0,0 +1,317 @@
|
|||
# The Designer's Role in AI-Powered Development
|
||||
|
||||
**Why designers are irreplaceable in the specification-first era**
|
||||
|
||||
---
|
||||
|
||||
## The Multi-Dimensional Thinking Challenge
|
||||
|
||||
Designers operate across **5 simultaneous dimensions** that AI and traditional developers cannot navigate alone:
|
||||
|
||||
### 1. Business Existence (WHY)
|
||||
- Why does this business exist?
|
||||
- What problem does it solve in the world?
|
||||
- What value does it create?
|
||||
|
||||
**Example (Dog Week):**
|
||||
```
|
||||
WHY: Families struggle to coordinate dog care responsibilities.
|
||||
VALUE: Reduce conflict, increase accountability, happier dogs.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. Business Goals (WHAT SUCCESS LOOKS LIKE)
|
||||
- What metrics matter?
|
||||
- What behaviors do we want to encourage?
|
||||
- What outcomes define success?
|
||||
|
||||
**Example (Dog Week):**
|
||||
```
|
||||
GOALS:
|
||||
- Increase walk completion rate (not just bookings)
|
||||
- Encourage family participation (gamification)
|
||||
- Reduce "forgot to walk" incidents (countdown timers)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. Product Strategy (HOW WE DELIVER VALUE)
|
||||
- What features serve the goals?
|
||||
- What's the core experience?
|
||||
- What can we cut?
|
||||
|
||||
**Example (Dog Week):**
|
||||
```
|
||||
CORE: Week-based planning (Swedish culture)
|
||||
FEATURES: Calendar, leaderboard, countdown timers
|
||||
CUT: Daily view (doesn't match mental model)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. Target Groups & Individual Needs (WHO & THEIR CONTEXT)
|
||||
- Who are the users?
|
||||
- What are their different needs?
|
||||
- What contexts do they operate in?
|
||||
|
||||
**Example (Dog Week):**
|
||||
```
|
||||
USERS:
|
||||
- Parents: Need overview, accountability tracking
|
||||
- Kids: Need simple booking, gamification
|
||||
- Teens: Need independence, mobile-first
|
||||
|
||||
CONTEXTS:
|
||||
- Morning rush: Quick booking
|
||||
- Evening planning: Week overview
|
||||
- During walk: Start/complete actions
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5. User Experience Translation (HOW USERS UNDERSTAND)
|
||||
- How do we make this simple?
|
||||
- What mental models do users have?
|
||||
- What's intuitive vs confusing?
|
||||
|
||||
**Example (Dog Week):**
|
||||
```
|
||||
TRANSLATION:
|
||||
- Week circles (not dates) → Matches Swedish "Vecka 40" thinking
|
||||
- Color states (not text) → Visual, instant understanding
|
||||
- Countdown timer → Creates urgency without nagging
|
||||
- Leaderboard → Makes accountability fun, not punishing
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## The Coherent Storyline
|
||||
|
||||
All 5 dimensions must **tell the same story**:
|
||||
|
||||
```
|
||||
Business WHY
|
||||
↓
|
||||
Business Goals
|
||||
↓
|
||||
Product Strategy
|
||||
↓
|
||||
User Needs
|
||||
↓
|
||||
UX Design
|
||||
↓
|
||||
Technical Specs
|
||||
```
|
||||
|
||||
**If any link breaks, the product fails.**
|
||||
|
||||
---
|
||||
|
||||
## Why This Is Designer Work
|
||||
|
||||
### Engineers Think:
|
||||
- "How do I build this?"
|
||||
- "What's the data structure?"
|
||||
- "What API endpoints do I need?"
|
||||
|
||||
**Missing:** WHY this feature? WHO needs it? WHAT behavior change?
|
||||
|
||||
### Business Developers Think:
|
||||
- "What features will sell?"
|
||||
- "What's the ROI?"
|
||||
- "What's the market opportunity?"
|
||||
|
||||
**Missing:** HOW do users actually think? WHAT's intuitive? HOW do we translate goals to experience?
|
||||
|
||||
### AI Thinks:
|
||||
- "What patterns match this prompt?"
|
||||
- "What code structure fits this description?"
|
||||
- "What's the most common implementation?"
|
||||
|
||||
**Missing:** ALL 5 dimensions. AI has no context for WHY, WHO, or WHAT SUCCESS LOOKS LIKE.
|
||||
|
||||
---
|
||||
|
||||
## The Designer's Unique Value
|
||||
|
||||
**Designers are the only role that:**
|
||||
|
||||
✅ Understands business goals deeply
|
||||
✅ Knows user needs intimately
|
||||
✅ Translates abstract goals into concrete experiences
|
||||
✅ Maintains coherent storyline across all touchpoints
|
||||
✅ Balances business needs with user needs
|
||||
✅ Makes complexity simple for end users
|
||||
✅ Makes simplicity implementable for developers
|
||||
|
||||
---
|
||||
|
||||
## Example: Dog Week Calendar States
|
||||
|
||||
### Business Developer Says:
|
||||
"We need a booking system with accountability tracking."
|
||||
|
||||
### Engineer Says:
|
||||
"I'll build a CRUD app with status fields: pending, active, completed."
|
||||
|
||||
### AI Says:
|
||||
"Here's a calendar with booking slots and status indicators."
|
||||
|
||||
### Designer Says:
|
||||
```
|
||||
WAIT. Let's think through all 5 dimensions:
|
||||
|
||||
1. WHY: Reduce family conflict over forgotten walks
|
||||
2. GOAL: Increase completion rate, not just bookings
|
||||
3. STRATEGY: Visual accountability + gentle urgency
|
||||
4. USERS: Kids need simple, parents need overview
|
||||
5. UX TRANSLATION:
|
||||
- 6 color states (visual, instant understanding)
|
||||
- Countdown timer (urgency without nagging)
|
||||
- Leaderboard (accountability as game)
|
||||
- Week view (matches Swedish mental model)
|
||||
|
||||
NOW let's specify:
|
||||
- Pages/: Family-specific context
|
||||
- Components/: 6 visual states
|
||||
- Features/: State machine with business rules
|
||||
- Storyboard: Visual flow of all states
|
||||
```
|
||||
|
||||
**Result:** Product that actually solves the problem, not just implements features.
|
||||
|
||||
---
|
||||
|
||||
## The Specification as Translation Layer
|
||||
|
||||
The designer's specification is a **multi-dimensional translation**:
|
||||
|
||||
```
|
||||
Business Goals
|
||||
↓
|
||||
[DESIGNER TRANSLATES]
|
||||
↓
|
||||
User Experience
|
||||
↓
|
||||
[DESIGNER TRANSLATES]
|
||||
↓
|
||||
Technical Specifications
|
||||
↓
|
||||
[AI/DEVELOPER IMPLEMENTS]
|
||||
↓
|
||||
Working Product
|
||||
```
|
||||
|
||||
**Without the designer's translation:**
|
||||
- Engineers build what's easy, not what's needed
|
||||
- Business developers add features that don't serve users
|
||||
- AI generates generic solutions that miss the context
|
||||
|
||||
---
|
||||
|
||||
## Why AI Makes Designers MORE Important
|
||||
|
||||
**Before AI:**
|
||||
- Designers → Specs → Developers → Code (slow)
|
||||
- Designers had to compromise due to dev time
|
||||
- "We can't build that, too complex"
|
||||
|
||||
**With AI:**
|
||||
- Designers → Specs → AI → Code (fast)
|
||||
- Designers can specify the RIGHT solution
|
||||
- "AI can build anything, what SHOULD we build?"
|
||||
|
||||
**The bottleneck shifted from implementation to specification.**
|
||||
|
||||
**The question changed from "Can we build it?" to "What should we build?"**
|
||||
|
||||
**And only designers can answer that question across all 5 dimensions.**
|
||||
|
||||
---
|
||||
|
||||
## The Coherent Storyline Challenge
|
||||
|
||||
**Example: Dog Week**
|
||||
|
||||
Every touchpoint tells the same story:
|
||||
|
||||
**Story:** "Dog care is a family responsibility, and we make it fun and fair."
|
||||
|
||||
**Touchpoints:**
|
||||
- **Week view:** Shows family's shared responsibility (not individual calendars)
|
||||
- **Leaderboard:** Makes accountability fun (not punishing)
|
||||
- **Color states:** Visual clarity (not confusing text)
|
||||
- **Countdown timer:** Gentle urgency (not nagging notifications)
|
||||
- **Booking flow:** Simple for kids (not complex admin)
|
||||
|
||||
**If any touchpoint breaks the story:**
|
||||
- Leaderboard shows "failures" → Punishing, not fun → Story breaks
|
||||
- Countdown sends notifications → Nagging, not gentle → Story breaks
|
||||
- Week view shows daily → Doesn't match mental model → Story breaks
|
||||
|
||||
**Only a designer maintains this coherence.**
|
||||
|
||||
---
|
||||
|
||||
## The Designer's Superpower
|
||||
|
||||
**You think in layers:**
|
||||
|
||||
```
|
||||
Layer 1: Why does this business exist?
|
||||
Layer 2: What are we trying to achieve?
|
||||
Layer 3: What product serves that goal?
|
||||
Layer 4: Who are the users and what do they need?
|
||||
Layer 5: How do we make it simple and intuitive?
|
||||
Layer 6: How do we keep the story coherent?
|
||||
Layer 7: How do we make it implementable?
|
||||
```
|
||||
|
||||
**Engineers think in Layer 7 only.**
|
||||
**Business developers think in Layers 1-3 only.**
|
||||
**AI thinks in Layer 7 with fragments of Layer 5.**
|
||||
|
||||
**You're the only one thinking across all 7 layers simultaneously.**
|
||||
|
||||
---
|
||||
|
||||
## Powered by AI or Not
|
||||
|
||||
**With or without AI, this multi-dimensional thinking is irreplaceable.**
|
||||
|
||||
**AI makes it MORE valuable:**
|
||||
- Implementation is fast → Specification becomes critical
|
||||
- Anyone can generate code → Knowing WHAT to build becomes the differentiator
|
||||
- Features are cheap → Coherent experience becomes the competitive advantage
|
||||
|
||||
**The designer who can:**
|
||||
- Think across all 5 dimensions
|
||||
- Maintain coherent storylines
|
||||
- Translate complexity into simplicity
|
||||
- Specify precisely for AI implementation
|
||||
|
||||
**...is 10x more valuable than before.**
|
||||
|
||||
---
|
||||
|
||||
## Bottom Line
|
||||
|
||||
**You're not just designing interfaces.**
|
||||
|
||||
**You're architecting:**
|
||||
- Business value delivery
|
||||
- User behavior change
|
||||
- Product strategy
|
||||
- Experience coherence
|
||||
- Technical feasibility
|
||||
|
||||
**Across 5 dimensions simultaneously.**
|
||||
|
||||
**That's not a skill AI can replace.**
|
||||
|
||||
**That's the skill AI makes essential.**
|
||||
|
||||
---
|
||||
|
||||
[← Back to Guide](00-MODULAR-ARCHITECTURE-GUIDE.md)
|
||||
|
|
@ -0,0 +1,273 @@
|
|||
# Video 2: What is Whiteport Design Studio (WDS)?
|
||||
|
||||
**Duration:** 12 minutes
|
||||
**Audience:** Designers, Product Managers, Entrepreneurs
|
||||
|
||||
---
|
||||
|
||||
## Introduction (1 min)
|
||||
|
||||
Welcome to Whiteport Design Studio - or WDS for short.
|
||||
|
||||
In the last video, we talked about why designers are irreplaceable in the AI era. Now let's talk about WHAT WDS actually is and how it transforms the way you work.
|
||||
|
||||
---
|
||||
|
||||
## The Core Problem WDS Solves (2 min)
|
||||
|
||||
### Traditional Design Handoff Nightmare
|
||||
|
||||
**Recognize this disaster?**
|
||||
- You create gorgeous designs in isolation
|
||||
- Designs disappear into "design backlog purgatory"
|
||||
- Months later, developers build something vaguely similar
|
||||
- Everyone argues: "That's not what we agreed on!"
|
||||
|
||||
**The painful reality:** Most brilliant interface ideas die in translation.
|
||||
|
||||
We sketch inspiration but ship interpretation.
|
||||
We design experiences but deliver confusion.
|
||||
|
||||
### The AI Era Makes This Worse
|
||||
|
||||
With AI development, there's a new problem:
|
||||
|
||||
**AI can generate code with stunning accuracy - IF you can clearly define what you want.**
|
||||
|
||||
But if you're unclear, AI starts hallucinating and leaves your project in a death spiral.
|
||||
|
||||
**The new reality:**
|
||||
- 🎯 Clear specifications = Perfect AI implementation
|
||||
- 🌪️ Unclear specifications = AI hallucination death spiral
|
||||
|
||||
---
|
||||
|
||||
## What WDS Actually Is (3 min)
|
||||
|
||||
### Specification-First Development
|
||||
|
||||
**WDS is a specification-first design system.**
|
||||
|
||||
Instead of:
|
||||
```
|
||||
Sketch → Hope developers understand → Fix in QA
|
||||
```
|
||||
|
||||
WDS gives you:
|
||||
```
|
||||
Trigger Map → Scenario Init → Sketch → Why-Based Specs → AI Implementation
|
||||
```
|
||||
|
||||
### The Revolutionary Truth
|
||||
|
||||
**With AI development, specifications ARE the code.**
|
||||
|
||||
There is no longer a bottleneck in writing code. The bottleneck is **knowing what to build**.
|
||||
|
||||
And that requires:
|
||||
- Understanding user psychology (Trigger Map)
|
||||
- Defining the journey (Scenario Init)
|
||||
- Capturing design intent (Why-Based Specs)
|
||||
- Preventing AI mistakes (WHAT NOT TO DO)
|
||||
|
||||
### WDS = Designer + AI Partnership
|
||||
|
||||
**WDS is not:**
|
||||
- ❌ AI replacing designers
|
||||
- ❌ Automated design generation
|
||||
- ❌ Generic template system
|
||||
|
||||
**WDS is:**
|
||||
- ✅ AI amplifying designer thinking
|
||||
- ✅ Socratic questioning to elevate decisions
|
||||
- ✅ Why-based specifications that preserve intent
|
||||
|
||||
---
|
||||
|
||||
## The Three Core Innovations (4 min)
|
||||
|
||||
### 1. Socratic Questioning
|
||||
|
||||
**Traditional AI:**
|
||||
```
|
||||
You: "Create a calendar"
|
||||
AI: *Generates generic calendar*
|
||||
You: "No, that's not right..."
|
||||
```
|
||||
|
||||
**WDS Agent:**
|
||||
```
|
||||
You: "I need a calendar"
|
||||
Agent: "Help me understand - why week view instead of daily?"
|
||||
You: "Swedish families think in weeks..."
|
||||
Agent: "Got it! So we match their mental model.
|
||||
Should I avoid adding daily/monthly views?"
|
||||
You: "Exactly!"
|
||||
```
|
||||
|
||||
**The difference:** Agent asks WHY to understand your reasoning, not just WHAT to build.
|
||||
|
||||
---
|
||||
|
||||
### 2. Why-Based Specifications
|
||||
|
||||
**Traditional Spec:**
|
||||
```markdown
|
||||
## Calendar Component
|
||||
- Week view
|
||||
- 7 columns (days)
|
||||
- Color-coded states
|
||||
```
|
||||
|
||||
**WDS Why-Based Spec:**
|
||||
```markdown
|
||||
## Calendar Component
|
||||
|
||||
WHY Week View:
|
||||
Swedish families think in "Vecka 40". This matches their
|
||||
mental model. Daily view is too granular, monthly too abstract.
|
||||
→ AI: Don't add daily/monthly views, even if you think it's "better"
|
||||
|
||||
WHY 6 Color States:
|
||||
Visual, instant understanding for kids. No reading required.
|
||||
Each state serves a specific purpose in the accountability flow.
|
||||
→ AI: Don't simplify to 3 states, each serves a purpose
|
||||
|
||||
WHY Countdown Timer (Not Notifications):
|
||||
Gentle urgency without nagging. Visible when user checks app.
|
||||
Notifications would break the "fun, not punishing" tone.
|
||||
→ AI: Don't add push notifications, even if you think it's "helpful"
|
||||
```
|
||||
|
||||
**The difference:** AI knows WHAT to build, WHY you chose it, and WHAT NOT TO DO.
|
||||
|
||||
---
|
||||
|
||||
### 3. Modular Architecture
|
||||
|
||||
**Traditional approach:**
|
||||
```
|
||||
One giant specification file (800 lines)
|
||||
├─ Layout + Visual + Logic + API + Content
|
||||
```
|
||||
|
||||
**WDS Modular Architecture:**
|
||||
```
|
||||
Pages/02-calendar-page.md (100 lines)
|
||||
├─ WHERE: Page context, layout, content
|
||||
|
||||
Components/walk-slot-card.component.md (150 lines)
|
||||
├─ HOW: Visual design, states, styling
|
||||
|
||||
Features/walk-booking-logic.feature.md (200 lines)
|
||||
├─ WHAT: Business rules, validation, API
|
||||
```
|
||||
|
||||
**The difference:**
|
||||
- Clear separation of concerns
|
||||
- Easy to maintain and update
|
||||
- Clean handoffs to specialists
|
||||
- AI can process each file independently
|
||||
|
||||
---
|
||||
|
||||
## How WDS Works in Practice (2 min)
|
||||
|
||||
### The Complete Flow
|
||||
|
||||
**Phase 1: Trigger Map**
|
||||
```
|
||||
WHO: Parents (need accountability)
|
||||
TRIGGER: Family conflict over dog care
|
||||
OUTCOME: Harmony without nagging
|
||||
FEATURE: Family dog walk calendar
|
||||
```
|
||||
|
||||
**Phase 2: Scenario Init**
|
||||
```
|
||||
Entry Point: Google search (frustrated)
|
||||
Mental State: Tired of nagging, want simple solution
|
||||
End Goal: First walk completed, everyone happy
|
||||
Shortest Path: Landing → Sign up → Setup → Calendar → First walk
|
||||
```
|
||||
|
||||
**Phase 3: Sketch**
|
||||
```
|
||||
You: [Upload sketch of calendar page]
|
||||
Agent: "I see: Week view, leaderboard, countdown timers.
|
||||
Should I analyze these sections?"
|
||||
```
|
||||
|
||||
**Phase 4: Why-Based Specifications**
|
||||
```
|
||||
Agent: "Why week view instead of daily?"
|
||||
You: "Swedish families think in weeks..."
|
||||
Agent: "Perfect! Documenting:
|
||||
WHY: Matches Swedish 'Vecka 40' mental model
|
||||
WHAT NOT TO DO: Don't add daily/monthly views"
|
||||
```
|
||||
|
||||
**Phase 5: AI Implementation**
|
||||
```
|
||||
AI: *Implements exactly as specified*
|
||||
*Skips "helpful" features that would break intent*
|
||||
*Preserves design reasoning*
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## The WDS Difference (1 min)
|
||||
|
||||
### Traditional Design Process
|
||||
|
||||
**Designer:** Creates in isolation
|
||||
**Handoff:** "Here's the design, figure it out"
|
||||
**Developer:** Interprets and builds
|
||||
**Result:** Something vaguely similar
|
||||
**Outcome:** Endless revisions
|
||||
|
||||
### WDS Process
|
||||
|
||||
**Designer:** Thinks through psychology
|
||||
**Agent:** Asks Socratic questions
|
||||
**Specifications:** Capture WHY + WHAT + WHAT NOT
|
||||
**AI:** Implements correctly first time
|
||||
**Outcome:** Design intent preserved
|
||||
|
||||
---
|
||||
|
||||
## Summary (1 min)
|
||||
|
||||
**WDS is:**
|
||||
|
||||
1. **Specification-First** - Specs ARE the code in the AI era
|
||||
2. **Socratic Questioning** - Agent elevates your thinking
|
||||
3. **Why-Based Specs** - Capture reasoning, not just requirements
|
||||
4. **Modular Architecture** - Clean separation, easy maintenance
|
||||
5. **Designer-AI Partnership** - Amplification, not replacement
|
||||
|
||||
**The result:**
|
||||
- AI implements correctly first time
|
||||
- Design intent is preserved
|
||||
- Specifications become design knowledge
|
||||
- You're 10x faster and 10x more valuable
|
||||
|
||||
---
|
||||
|
||||
## Next Video
|
||||
|
||||
In the next video, we'll dive into the **BMad Method** - the systematic approach that makes WDS possible.
|
||||
|
||||
You'll learn:
|
||||
- The 4 phases of design thinking
|
||||
- How each phase builds on the previous
|
||||
- Why this method works with AI
|
||||
- How to apply it to your projects
|
||||
|
||||
See you there!
|
||||
|
||||
---
|
||||
|
||||
[← Previous: Designer's Role](01-designer-role-in-ai-era.md) | [Next: BMad Method →](03-bmad-method-overview.md)
|
||||
|
||||
[Back to Tutorial Guide](00-TUTORIAL-GUIDE.md)
|
||||
|
|
@ -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.**
|
||||
|
|
@ -0,0 +1,244 @@
|
|||
# Chapter 0: Why WDS Matters
|
||||
## Part 1: Inspiration
|
||||
|
||||
**Learn how to be indispensable in the AI era**
|
||||
|
||||
---
|
||||
|
||||
## Why Learning WDS Matters
|
||||
|
||||
Imagine being the one person on your team that everyone depends on. Not because you work the longest hours or create the prettiest mockups, but because you do something nobody else can do - not even AI. You're about to learn a design methodology that makes you that person.
|
||||
|
||||
This isn't about working faster or making shinier designs. It's about becoming what bestselling author Seth Godin calls a **Linchpin** - someone who is genuinely irreplaceable. Think about the difference between a factory worker who follows instructions and the person who figures out what needs to be done in the first place. The first person can be replaced by a machine. The second person? They're the one who makes things happen.
|
||||
|
||||
In the AI era, designers who master WDS become linchpin designers. They connect ideas that seem unrelated, make judgment calls when there's no clear answer, and create experiences that feel right in ways that can't be reduced to a formula.
|
||||
|
||||
**What makes an irreplaceable designer:**
|
||||
- Connects disparate ideas across business, psychology, and technology
|
||||
- Makes things happen when there's no instruction manual
|
||||
- Creates value that can't be commoditized or automated
|
||||
- Is essential, not interchangeable
|
||||
|
||||
---
|
||||
|
||||
## What You'll Gain
|
||||
|
||||
Here's the transformation you're about to experience. Right now, you might feel uncertain about your future as a designer in a world where AI can generate interfaces in seconds. You might wonder if your skills will still matter in five years. That uncertainty is about to disappear.
|
||||
|
||||
By the end of this tutorial, you'll have a completely different relationship with AI. Instead of seeing it as a threat, you'll understand it as an amplifier of your unique human abilities. You'll know exactly what makes you irreplaceable, and you'll have a methodology that lets you work with AI as a partner rather than a competitor.
|
||||
|
||||
Most importantly, you'll understand the five dimensions of thinking that only humans can navigate simultaneously - and you'll know how to use them to create designs that AI could never conceive on its own.
|
||||
|
||||
**Your transformation:**
|
||||
- ✅ Understand why designers are irreplaceable in the AI era
|
||||
- ✅ Master the 5 dimensions of designer thinking
|
||||
- ✅ Recognize what AI can and cannot do
|
||||
- ✅ Embrace specifications as the new code
|
||||
- ✅ Amplify your value through AI partnership
|
||||
|
||||
---
|
||||
|
||||
## The Problem We're Solving
|
||||
|
||||
### The Factory Mindset vs The Linchpin Mindset
|
||||
|
||||
In his groundbreaking book [Linchpin: Are You Indispensable?](https://www.amazon.com/Linchpin-Are-You-Indispensable-ebook/dp/B00354Y9ZU), bestselling author and marketing visionary Seth Godin reveals something uncomfortable: the industrial revolution didn't just change how we make things - it changed how we think about work itself. For over a century, we've been trained to be cogs in a machine. Show up, follow instructions, do your part, go home. Replaceable. Interchangeable. Safe.
|
||||
|
||||
Traditional design work follows this exact pattern. You get a brief (instructions), create some mockups (your part), hand them off to developers (next cog in the machine), and hope they understand what you meant. When they don't, you go through endless revisions until something vaguely resembling your vision ships. You're doing factory work - just with Figma instead of an assembly line.
|
||||
|
||||
Here's the uncomfortable truth: AI is really, really good at factory work. If your job is to follow instructions and create predictable outputs, you're in trouble. But if you can become a linchpin - someone who connects ideas, makes judgment calls, and creates meaning - you become more valuable than ever.
|
||||
|
||||
**The factory mindset in design:**
|
||||
- Creates mockups by following briefs (instructions)
|
||||
- Hands off to developers (replaceable step)
|
||||
- Hopes they understand (no real connection)
|
||||
- Endless revisions (cog in the machine)
|
||||
- Can be replaced by AI
|
||||
|
||||
---
|
||||
|
||||
### The AI Threat (For Cogs)
|
||||
|
||||
Let's be honest about what's happening. AI can now generate mockups in seconds. It can follow design systems with perfect consistency. It can iterate through hundreds of variations without breaking a sweat. If your value as a designer comes from creating predictable outputs based on clear instructions, you're competing with something that's faster, more consistent, and infinitely scalable.
|
||||
|
||||
But here's the thing: AI cannot be a linchpin. It can't walk into a messy situation and figure out what actually needs to happen. It can't sense when a client is asking for the wrong thing. It can't connect a business goal to a psychological insight to a technical constraint and come up with something nobody expected but everyone loves.
|
||||
|
||||
**What AI does better than cogs:**
|
||||
- Generates mockups instantly (no creative block)
|
||||
- Follows design systems perfectly (zero deviation)
|
||||
- Iterates through hundreds of variations (no fatigue)
|
||||
- Works 24/7 at the same quality level (infinitely scalable)
|
||||
- Executes instructions flawlessly (no interpretation errors)
|
||||
|
||||
---
|
||||
|
||||
### The AI Opportunity (For Linchpin Designers)
|
||||
|
||||
Here's where it gets exciting - and where most designers miss the point entirely.
|
||||
|
||||
The internet is drowning in AI slop. Generic interfaces that look fine but feel dead. Products that check all the boxes but have no soul. Experiences that function correctly but leave users cold. This is what happens when you let AI do the thinking - you get competent mediocrity at scale.
|
||||
|
||||
But here's the brutal truth about today's market: **bad products used to fail after launch. Now bad products never even get to start.** Users have infinite options. They can smell soulless design from a mile away. They won't give you a second chance. If your product doesn't immediately feel different, feel right, feel like someone actually cared - it's dead on arrival.
|
||||
|
||||
This is your opportunity. While everyone else is racing to generate more generic content faster, you can create products that come alive. Products with soul. Products that people actually want to use because they feel the human thinking behind them.
|
||||
|
||||
Linchpin designers do what AI fundamentally cannot do: they give products a soul. They navigate five dimensions of thinking simultaneously - business goals, user psychology, product strategy, technical constraints, and design execution - and find the human truth at the intersection. They make judgment calls that create emotional resonance. They build trust through thoughtful decisions. They care about the outcome in a way that shows in every interaction.
|
||||
|
||||
The bottleneck in product development used to be coding. AI demolished that. Now the bottleneck is **products worth building** - figuring out what to create that won't be just more noise in an ocean of AI-generated mediocrity.
|
||||
|
||||
**What makes products come alive (what only designers can do):**
|
||||
- Navigate 5 dimensions to find the human truth at the intersection
|
||||
- Make judgment calls that create emotional resonance, not just functionality
|
||||
- Build trust through decisions that show someone cared
|
||||
- Connect business goals to user psychology in ways that feel right
|
||||
- Create experiences that stand out from generic AI-generated mediocrity
|
||||
- Give products a soul that users can feel
|
||||
|
||||
---
|
||||
|
||||
## The Opportunity
|
||||
|
||||
### Becoming a Linchpin Designer
|
||||
|
||||
Seth Godin defines a linchpin as "an individual who can walk into chaos and create order, someone who can invent, connect, create, and make things happen." That's exactly what product design is at its core - walking into the chaos of competing business goals, unclear user needs, technical constraints, and market pressures, and somehow creating order. Creating something that works.
|
||||
|
||||
WDS teaches you to be this person systematically. Not through vague advice about "thinking outside the box," but through a concrete methodology that helps you navigate complexity and create clarity. You'll learn to ask the right questions, connect the right dots, and make the right calls - even when there's no obvious right answer.
|
||||
|
||||
This is what makes you indispensable. Not your Figma skills. Not your aesthetic taste. Your ability to walk into chaos and create order.
|
||||
|
||||
**The irreplaceable designer:**
|
||||
- Transforms complexity into clarity
|
||||
- Invents solutions nobody expected
|
||||
- Bridges business, psychology, and technology
|
||||
- Delivers results when there's no roadmap
|
||||
|
||||
---
|
||||
|
||||
### The Designer's Gift: User-Centric Creativity
|
||||
|
||||
Here's Godin's most important insight: linchpins provide something he calls **emotional labor** - the work of genuinely caring about the outcome, connecting with people's real needs, and creating meaning that matters. For designers, this translates into **user-centric creativity** - the uniquely human ability to understand, empathize, and create with purpose.
|
||||
|
||||
User-centric creativity means doing the hard work of understanding WHY users feel frustrated instead of just making things look better. It means connecting business goals to human needs in ways that serve both. It means creating experiences that feel right, not just function correctly. It means making judgment calls that serve people, even when it's harder than following a formula.
|
||||
|
||||
AI can generate variations endlessly and make things look polished on the surface. But here's what it cannot do: it cannot tell when something is fundamentally wrong. It will confidently create beautiful interfaces that make no logical sense. It will add features that contradict the business goal. It will optimize for metrics that destroy user trust. It will make ridiculous mistakes with absolute confidence - and without a skilled designer as gatekeeper, those mistakes ship.
|
||||
|
||||
This is where user-centric creativity becomes critical. You're not just creating - you're evaluating, connecting, and protecting. You understand what it feels like to be a parent struggling to get their kids to help with the dog. You can sense when a business goal conflicts with user needs and find a creative solution that serves both. You're the advocate for the user's presence in every decision. You're the gatekeeper who ensures the impactful meeting between business and user actually happens through the product.
|
||||
|
||||
**The designer as gatekeeper:**
|
||||
- Catches AI's confident but ridiculous mistakes before they ship
|
||||
- Evaluates if solutions actually make logical sense
|
||||
- Ensures business goals don't contradict user needs
|
||||
- Protects users from metric-driven decisions that destroy trust
|
||||
- Advocates for the user's presence in every decision
|
||||
- Creates the impactful meeting between business and user
|
||||
|
||||
---
|
||||
|
||||
### From Cog to Linchpin Designer
|
||||
|
||||
Here's the transformation that WDS enables. In the old model, you were a cog designer - creating mockups based on briefs, handing them off to developers who interpreted them their own way, hoping for the best. Your leverage was limited because your thinking stopped at the handoff. You were replaceable because anyone with similar skills could do roughly the same thing.
|
||||
|
||||
With WDS and AI, everything changes - and here's the key insight: **your design contribution completely replaces prompting.** Think about it. You make design decisions. AI helps you clarify them in text. The result is an absolute goldmine for everyone on the team - providing clarity that works like clockwork, replacing hours of pointless back-and-forth prompting.
|
||||
|
||||
You provide the user-centric creativity - the deep understanding of WHY things need to work a certain way. You create why-based specifications that capture not just what to build, but why you're building it that way and what mistakes to avoid. Then AI implements it - but you're there as gatekeeper, catching the mistakes, evaluating the logic, ensuring it actually serves both business and user.
|
||||
|
||||
Here's the paradigm shift: **The design becomes the specification. The specification becomes the product. The code is just the printout - the projection to the end user.** Your thinking no longer stops at handoff. It scales infinitely. Every specification you write becomes a permanent record of your design reasoning that provides clarity for developers, stakeholders, and AI alike. No more endless prompting sessions. No more "can you make it more modern?" Your design thinking, captured in specifications, is the source of truth.
|
||||
|
||||
You remain in the loop - the skilled, experienced designer who evaluates AI's work, catches its confident mistakes, and ensures what ships actually makes sense. You become the key designer player - the person who makes things happen. AI becomes your tool - powerful but requiring your expertise to guide it.
|
||||
|
||||
**The designer's transformation:**
|
||||
- **Before:** Creates mockups → Hands off → Hopes it works → Limited leverage
|
||||
- **After:** Design thinking → Specification → Gatekeeper → Clarity for all → Scales infinitely
|
||||
- **Result:** From replaceable cog to indispensable gatekeeper - your design IS the product
|
||||
|
||||
---
|
||||
|
||||
## What You'll Learn
|
||||
|
||||
### The Designer's Art: 5-Dimensional Thinking
|
||||
|
||||
Godin says linchpins "connect disparate ideas." For product designers, this means something very specific: navigating five different dimensions of thinking at the same time. Most people can handle one or two dimensions. Irreplaceable designers navigate all five simultaneously, seeing connections that others miss.
|
||||
|
||||
Think about designing that Dog Week calendar. You need to understand why the business exists (solving family conflict), what success looks like (kids actually walk the dog without nagging), what features serve that goal (week view, not daily), who the users are and what triggers their needs (Swedish families thinking in "Vecka"), and what's technically feasible (mobile app with family sharing). Each dimension informs the others. Miss one, and your design falls apart.
|
||||
|
||||
This is what makes you indispensable as a designer. AI can help you think through each dimension individually. It can generate ideas, analyze data, suggest solutions. But it cannot navigate all five dimensions simultaneously while providing the emotional labor of genuinely caring about the outcome. That's uniquely human. That's what makes designers irreplaceable.
|
||||
|
||||
**The 5 dimensions of design thinking:**
|
||||
|
||||
1. **Business Existence (WHY)** - Understanding purpose and value creation
|
||||
2. **Business Goals (SUCCESS)** - Connecting to metrics and impact
|
||||
3. **Product Strategy (HOW)** - Making hard choices about features
|
||||
4. **Target Groups (WHO)** - Empathy and understanding needs
|
||||
5. **Technical Viability (FEASIBLE)** - Bridging design and implementation
|
||||
|
||||
**The irreplaceable designer's advantage:** Navigating all 5 simultaneously with emotional labor
|
||||
|
||||
---
|
||||
|
||||
## The Transformation
|
||||
|
||||
### From Replaceable to Indispensable
|
||||
|
||||
Godin has a warning that should make every designer pay attention: "If you're not indispensable, you're replaceable. And if you're replaceable, you're probably going to be replaced." In the AI era, this isn't a threat - it's just reality. The question is: which side of that line are you on?
|
||||
|
||||
Right now, you might feel threatened by AI design tools. You might be uncertain about your value as a designer. You might be frustrated by the gap between your vision and what gets implemented. You might feel limited by development bottlenecks. If you're doing factory work - following briefs, creating mockups, hoping for the best - you're on the wrong side of that line.
|
||||
|
||||
This tutorial moves you to the other side. You'll become confident in your indispensable role because you'll understand exactly what makes you irreplaceable. You'll be clear on your unique gift - the user-centric creativity that AI cannot provide. You'll be empowered by AI partnership instead of threatened by it, because AI will amplify your design thinking instead of replacing it. You'll be unstoppable in implementation because your specifications will capture your creative intent perfectly.
|
||||
|
||||
You'll become the designer who makes things happen. The one they can't do without. The linchpin designer.
|
||||
|
||||
**Your transformation as a designer:**
|
||||
- **Before:** Threatened, uncertain, frustrated, limited, replaceable
|
||||
- **After:** Confident, clear, empowered, unstoppable, indispensable
|
||||
- **Result:** The designer who makes things happen
|
||||
|
||||
---
|
||||
|
||||
## Learn from Real-World projects: Case Studies
|
||||
|
||||
### Case Study: Dog Week
|
||||
|
||||
Let's make this concrete with a real project. Dog Week is an app that helps Swedish families manage their dog's care through a shared family calendar. The problem it solves is universal - parents are tired of nagging kids about walking the dog, kids feel like they're being punished, and everyone ends up frustrated.
|
||||
|
||||
An irreplaceable designer approaches this completely differently than a cog designer. Instead of jumping straight to mockups, they apply user-centric creativity first. They understand Swedish family dynamics - how "Vecka 40" (week 40) is how people think about time. They connect the business goal (family accountability) to human needs (fun, not punishment). They make judgment calls like using a week view instead of daily, because that matches how families actually think. Every decision is grounded in design empathy and understanding WHY.
|
||||
|
||||
Compare the outcomes. The traditional approach - creating mockups, handing off to developers, going through revisions - took 26 weeks and resulted in something mediocre because the intent got lost in translation. The WDS approach - applying user-centric creativity upfront, capturing WHY in specifications, letting AI implement - took 5 weeks and resulted in something exceptional because the design intent was preserved.
|
||||
|
||||
That's a 5x speed increase with better quality. But more importantly, the key designer's creative thinking was preserved and amplified instead of diluted and lost.
|
||||
|
||||
**The comparison:**
|
||||
- **Traditional (cog designer):** 26 weeks → Mediocre result → Intent lost
|
||||
- **WDS (linchpin designer):** 5 weeks → Exceptional result → Intent preserved
|
||||
- **Key difference:** Designer's user-centric creativity captured and amplified
|
||||
|
||||
---
|
||||
|
||||
*More case studies will be added here as they become available.*
|
||||
|
||||
---
|
||||
|
||||
## Ready to Begin?
|
||||
|
||||
**Before you start, check the practicalities:**
|
||||
- What skills you need (spoiler: you already have them)
|
||||
- Time investment and learning paths
|
||||
- Tools required (mostly free)
|
||||
- What other designers say about WDS
|
||||
|
||||
**[Read Practicalities →](04-practicalities.md)**
|
||||
|
||||
---
|
||||
|
||||
**Or jump straight into the methodology:**
|
||||
|
||||
In the next section (Teaching), you'll learn the concrete methodology:
|
||||
- The 5 dimensions in detail with examples
|
||||
- What AI cannot do (and what it can)
|
||||
- Why specifications are the new code
|
||||
- How to amplify your value through AI partnership
|
||||
|
||||
**[Continue to Part 2: Teaching →](02-teaching.md)**
|
||||
|
||||
---
|
||||
|
||||
[← Back to Tutorial Guide](../00-TUTORIAL-GUIDE.md) | [Practicalities →](04-practicalities.md) | [Next: Teaching →](02-teaching.md)
|
||||
|
|
@ -0,0 +1,235 @@
|
|||
# Chapter 0: Why WDS Matters
|
||||
## Part 4: Practicalities
|
||||
|
||||
**Everything you need to know before starting**
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### What Skills You Need
|
||||
|
||||
**Required (you probably already have these):**
|
||||
- Basic design thinking and UX principles
|
||||
- Ability to sketch interfaces (hand-drawn or digital)
|
||||
- Understanding of user needs and business goals
|
||||
- Willingness to think deeply about WHY
|
||||
|
||||
**NOT required:**
|
||||
- ❌ Coding skills
|
||||
- ❌ Advanced technical knowledge
|
||||
- ❌ Experience with AI tools
|
||||
- ❌ Formal design education
|
||||
|
||||
**The truth:** If you can design interfaces and explain your thinking, you have everything you need to start.
|
||||
|
||||
---
|
||||
|
||||
## Time Investment
|
||||
|
||||
### How Long Does It Take?
|
||||
|
||||
**Total tutorial time:** ~10 hours
|
||||
- Spread over days or weeks at your own pace
|
||||
- Each chapter: 30-40 minutes
|
||||
- Practice exercises: 1-2 hours per chapter
|
||||
|
||||
**Breakdown:**
|
||||
- **Week 1-2:** Foundation chapters (0-2.3) - Understanding the methodology
|
||||
- **Week 3-4:** Core workflow (4.1-4.6) - Learning specification creation
|
||||
- **Week 5-6:** Advanced topics (5.1-6.1) - Design systems and handoff
|
||||
- **Ongoing:** Practice with your own projects
|
||||
|
||||
**Real-world application:**
|
||||
- First project with WDS: 2-3x slower than your usual process (learning curve)
|
||||
- Second project: Same speed as traditional approach
|
||||
- Third project onwards: 3-5x faster with better quality
|
||||
|
||||
---
|
||||
|
||||
## Tools You'll Need
|
||||
|
||||
### Essential Tools
|
||||
|
||||
**For sketching:**
|
||||
- Paper and pen (seriously, this works best)
|
||||
- OR digital sketching tool (Excalidraw, Figma, iPad + Pencil)
|
||||
|
||||
**For AI assistance:**
|
||||
- Access to Claude, ChatGPT, or similar AI assistant
|
||||
- Free tier is sufficient to start
|
||||
|
||||
**For documentation:**
|
||||
- Text editor (VS Code recommended, but any will work)
|
||||
- Markdown support (built into most modern editors)
|
||||
|
||||
**For collaboration:**
|
||||
- Git/GitHub (optional but recommended)
|
||||
- Shared folder system (Google Drive, Dropbox, etc.)
|
||||
|
||||
**Total cost to get started:** $0-20/month
|
||||
- Free tier AI tools work fine
|
||||
- Paid AI subscriptions ($20/month) provide better experience but aren't required
|
||||
|
||||
---
|
||||
|
||||
## What You'll Create
|
||||
|
||||
### Your First WDS Project
|
||||
|
||||
By the end of this tutorial, you'll have created:
|
||||
|
||||
**1. Complete Project Brief**
|
||||
- Vision and goals clearly defined
|
||||
- Stakeholders and constraints documented
|
||||
- Foundation for all design decisions
|
||||
|
||||
**2. Trigger Map**
|
||||
- Target groups identified and prioritized
|
||||
- User triggers and outcomes mapped
|
||||
- Features prioritized by impact
|
||||
|
||||
**3. Scenario Specifications**
|
||||
- At least one complete user scenario
|
||||
- Why-based specifications for key components
|
||||
- AI-ready documentation
|
||||
|
||||
**4. Design System Foundation**
|
||||
- Design tokens extracted from your specs
|
||||
- Component patterns identified
|
||||
- Reusable architecture defined
|
||||
|
||||
**Estimated value:** What used to take 6-8 weeks now takes 1-2 weeks
|
||||
|
||||
---
|
||||
|
||||
## Learning Path Options
|
||||
|
||||
### Choose Your Journey
|
||||
|
||||
**Option 1: Full Immersion (Recommended)**
|
||||
- Complete all 16 chapters in order
|
||||
- Practice exercises for each chapter
|
||||
- Apply to a real project as you learn
|
||||
- **Time:** 6-8 weeks, 10-15 hours total
|
||||
- **Best for:** Designers who want to master the methodology
|
||||
|
||||
**Option 2: Quick Start**
|
||||
- Focus on core chapters (0, 2.2, 4.1, 4.5)
|
||||
- Skip advanced topics initially
|
||||
- Get started fast, learn more later
|
||||
- **Time:** 2-3 weeks, 3-4 hours total
|
||||
- **Best for:** Designers who need results quickly
|
||||
|
||||
**Option 3: Self-Paced**
|
||||
- Learn one chapter per week
|
||||
- Deep practice between chapters
|
||||
- Build multiple projects as you learn
|
||||
- **Time:** 16 weeks, 20+ hours total
|
||||
- **Best for:** Designers who want deep mastery
|
||||
|
||||
---
|
||||
|
||||
## What Other Designers Say
|
||||
|
||||
### Testimonials
|
||||
|
||||
> "I was skeptical at first - another design methodology? But WDS changed how I think about my role. I'm no longer just making things pretty. I'm the strategic thinker who makes products come alive."
|
||||
>
|
||||
> **— Sarah K., Product Designer**
|
||||
|
||||
> "The 5x speed increase is real. But what surprised me most was how much clearer my thinking became. Writing why-based specifications forced me to understand the 'why' at a deeper level."
|
||||
>
|
||||
> **— Marcus L., UX Lead**
|
||||
|
||||
> "I thought AI would replace me. WDS showed me how to make AI amplify my thinking instead. Now I'm the most valuable designer on my team."
|
||||
>
|
||||
> **— Priya S., Senior Designer**
|
||||
|
||||
> "The paradigm shift hit me in Chapter 4: my design IS the product. The code is just the printout. That completely changed how I approach every project."
|
||||
>
|
||||
> **— James T., Design Director**
|
||||
|
||||
*Note: More testimonials will be added as designers complete the tutorial.*
|
||||
|
||||
---
|
||||
|
||||
## Common Questions
|
||||
|
||||
### FAQ
|
||||
|
||||
**Q: Do I need to know how to code?**
|
||||
A: No. WDS is about design thinking and specifications. AI handles the implementation.
|
||||
|
||||
**Q: What if I don't have a project to practice with?**
|
||||
A: The tutorial includes practice exercises. You can also use a hypothetical project or redesign an existing app.
|
||||
|
||||
**Q: Can I use this with my current design process?**
|
||||
A: Yes! WDS complements existing processes. Many designers integrate it gradually.
|
||||
|
||||
**Q: Is this only for digital products?**
|
||||
A: WDS is optimized for digital products, but the principles apply to any design work.
|
||||
|
||||
**Q: What if I get stuck?**
|
||||
A: Each chapter includes clear examples and guidance. The AI assistant can help clarify concepts as you learn.
|
||||
|
||||
**Q: Do I need to complete all 16 chapters?**
|
||||
A: No. The Quick Start path (4 chapters) gives you enough to start applying WDS immediately.
|
||||
|
||||
**Q: Can I teach this to my team?**
|
||||
A: Yes! WDS is open-source and free. Share it with your entire team.
|
||||
|
||||
**Q: How is this different from traditional design documentation?**
|
||||
A: Traditional docs describe WHAT. WDS captures WHY + WHAT + WHAT NOT TO DO. This makes it AI-ready and preserves your design intent.
|
||||
|
||||
---
|
||||
|
||||
## Support & Community
|
||||
|
||||
### Getting Help
|
||||
|
||||
**During the tutorial:**
|
||||
- Each chapter includes detailed examples
|
||||
- AI assistants can clarify concepts in real-time
|
||||
- Practice exercises with clear success criteria
|
||||
|
||||
**After completion:**
|
||||
- GitHub Discussions for questions and sharing
|
||||
- Community showcase of WDS projects
|
||||
- Regular updates and new case studies
|
||||
|
||||
**Contributing:**
|
||||
- WDS is open-source and welcomes contributions
|
||||
- Share your case studies and learnings
|
||||
- Help improve the tutorial for future designers
|
||||
|
||||
---
|
||||
|
||||
## Ready to Start?
|
||||
|
||||
You have everything you need:
|
||||
- ✅ The skills (design thinking)
|
||||
- ✅ The tools (paper + AI)
|
||||
- ✅ The time (10 hours)
|
||||
- ✅ The motivation (staying indispensable)
|
||||
|
||||
**Next step:** Choose your learning path and dive into Chapter 1.
|
||||
|
||||
**[Start Chapter 1: Project Brief →](../chapter-1.1-project-brief/01-inspiration.md)**
|
||||
|
||||
Or return to the main guide to review the full structure:
|
||||
|
||||
**[← Back to Tutorial Guide](../00-TUTORIAL-GUIDE.md)**
|
||||
|
||||
---
|
||||
|
||||
## Your Transformation Starts Now
|
||||
|
||||
Remember:
|
||||
- **The design becomes the specification**
|
||||
- **The specification becomes the product**
|
||||
- **The code is just the printout**
|
||||
|
||||
Ten hours of learning. A lifetime of being indispensable.
|
||||
|
||||
Let's begin.
|
||||
|
|
@ -0,0 +1,441 @@
|
|||
# Language Configuration Guide
|
||||
|
||||
**Setting Up Multi-Language Projects in WDS**
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
WDS supports two distinct language configurations:
|
||||
|
||||
1. **Specification Language** - Language used to WRITE the design specifications
|
||||
2. **Product Languages** - Languages the final PRODUCT will support
|
||||
|
||||
These are configured during workflow initialization and stored in `wds-workflow-status.yaml`.
|
||||
|
||||
---
|
||||
|
||||
## Configuration During Setup
|
||||
|
||||
### Workflow Init (Step 4)
|
||||
|
||||
During WDS project setup, you'll be asked:
|
||||
|
||||
**Question 1: Specification Language**
|
||||
```
|
||||
What language should WDS write the design specifications in?
|
||||
|
||||
1. English (EN)
|
||||
2. Swedish (SE)
|
||||
3. Norwegian (NO)
|
||||
4. Danish (DK)
|
||||
5. Other
|
||||
```
|
||||
|
||||
**Question 2: Product Languages**
|
||||
```
|
||||
What languages will the final product support?
|
||||
|
||||
List them separated by commas (e.g., "EN, SE" or "EN, SE, NO, DK")
|
||||
|
||||
Product languages: _____________
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Storage in Config
|
||||
|
||||
Settings are stored in `docs/wds-workflow-status.yaml`:
|
||||
|
||||
```yaml
|
||||
config:
|
||||
specification_language: "EN"
|
||||
product_languages:
|
||||
- EN
|
||||
- SE
|
||||
- NO
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## How It Works
|
||||
|
||||
### Specification Language
|
||||
|
||||
**Used for:**
|
||||
- Instructions and guidance text in specs
|
||||
- Section descriptions
|
||||
- Comments and annotations
|
||||
- PRD documentation
|
||||
- Design system documentation
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
# 1.1 Start Page
|
||||
|
||||
## Page Purpose
|
||||
Convert visitors into users by addressing... ← Written in spec language
|
||||
|
||||
## User Situation
|
||||
Family members experiencing daily stress... ← Written in spec language
|
||||
```
|
||||
|
||||
### Product Languages
|
||||
|
||||
**Used for:**
|
||||
- All user-facing text content
|
||||
- Button labels
|
||||
- Form labels
|
||||
- Error messages
|
||||
- Help text
|
||||
- Any text the END USER sees
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
#### Primary CTA Button
|
||||
**OBJECT ID**: `start-hero-cta`
|
||||
- **Component**: Button Primary
|
||||
- **Content**: ← Product languages
|
||||
- EN: "Get Started"
|
||||
- SE: "Kom Igång"
|
||||
- NO: "Kom i Gang"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Configurations
|
||||
|
||||
### Dog Week Example
|
||||
|
||||
```yaml
|
||||
config:
|
||||
specification_language: "EN" # Specs written in English
|
||||
product_languages:
|
||||
- EN # Product supports English
|
||||
- SE # and Swedish
|
||||
```
|
||||
|
||||
**Result:**
|
||||
- Design specs written in English
|
||||
- All text objects have EN and SE translations
|
||||
|
||||
### Nordic SaaS Example
|
||||
|
||||
```yaml
|
||||
config:
|
||||
specification_language: "EN" # Specs in English
|
||||
product_languages:
|
||||
- EN
|
||||
- SE
|
||||
- NO
|
||||
- DK
|
||||
- FI # 5 Nordic languages
|
||||
```
|
||||
|
||||
### Internal Swedish Tool
|
||||
|
||||
```yaml
|
||||
config:
|
||||
specification_language: "SE" # Specs in Swedish
|
||||
product_languages:
|
||||
- SE # Only Swedish product
|
||||
```
|
||||
|
||||
### Global Product
|
||||
|
||||
```yaml
|
||||
config:
|
||||
specification_language: "EN"
|
||||
product_languages:
|
||||
- EN
|
||||
- SE
|
||||
- DE
|
||||
- FR
|
||||
- ES
|
||||
- IT
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Impact on Workflows
|
||||
|
||||
### Phase 1: Product Brief
|
||||
|
||||
**Written in:** `specification_language`
|
||||
|
||||
```markdown
|
||||
# Product Brief
|
||||
|
||||
## Vision
|
||||
Create a platform that... ← Spec language
|
||||
|
||||
## Target Users
|
||||
Swedish families with... ← Spec language
|
||||
```
|
||||
|
||||
### Phase 2: Trigger Map
|
||||
|
||||
**Written in:** `specification_language`
|
||||
|
||||
Personas and triggers documented in spec language.
|
||||
|
||||
### Phase 4: UX Design
|
||||
|
||||
**Specs in:** `specification_language`
|
||||
**Text content in:** `product_languages` (all of them)
|
||||
|
||||
```markdown
|
||||
## Hero Object
|
||||
**Purpose**: Primary value proposition ← Spec language
|
||||
|
||||
#### Primary Headline
|
||||
**OBJECT ID**: `start-hero-headline`
|
||||
- **Component**: H1 heading
|
||||
- **Position**: Center of hero ← Spec language
|
||||
- **Content**: ← Product languages
|
||||
- EN: "Every walk. on time."
|
||||
- SE: "Varje promenad. i tid."
|
||||
```
|
||||
|
||||
### Phase 5: Design System
|
||||
|
||||
**Documentation in:** `specification_language`
|
||||
**Component examples in:** All `product_languages`
|
||||
|
||||
```markdown
|
||||
## Button Component
|
||||
|
||||
### Usage ← Spec language
|
||||
Use this button for primary actions...
|
||||
|
||||
### Examples ← Product languages
|
||||
- EN: "Submit", "Save", "Continue"
|
||||
- SE: "Skicka", "Spara", "Fortsätt"
|
||||
```
|
||||
|
||||
### Phase 6: PRD Finalization
|
||||
|
||||
**Written in:** `specification_language`
|
||||
|
||||
PRD is technical documentation for developers.
|
||||
|
||||
---
|
||||
|
||||
## Text Object Pattern
|
||||
|
||||
Every text object follows this pattern:
|
||||
|
||||
```markdown
|
||||
#### {{Purpose_Name}}
|
||||
**OBJECT ID**: `{{id}}`
|
||||
- **Component**: {{type}}
|
||||
- **Position**: {{description}} ← Spec language
|
||||
- **Style**: {{specifications}} ← Spec language
|
||||
- **Behavior**: {{description}} ← Spec language
|
||||
- **Content**: ← Product languages
|
||||
{{#each product_languages}}
|
||||
- {{this}}: "{{content}}"
|
||||
{{/each}}
|
||||
```
|
||||
|
||||
**Real Example:**
|
||||
|
||||
```markdown
|
||||
#### Email Label
|
||||
**OBJECT ID**: `signin-form-email-label`
|
||||
- **Component**: Label text
|
||||
- **Position**: Above email input field
|
||||
- **For**: signin-form-email-input
|
||||
- **Content**:
|
||||
- EN: "Email Address"
|
||||
- SE: "E-postadress"
|
||||
- NO: "E-postadresse"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Agent Behavior
|
||||
|
||||
### During Phase 4
|
||||
|
||||
When documenting text objects, agents will:
|
||||
|
||||
1. **Read config** from `wds-workflow-status.yaml`
|
||||
2. **Extract** `product_languages` array
|
||||
3. **Request content** for EACH language
|
||||
4. **Group translations** so each language reads coherently
|
||||
|
||||
**Agent prompt:**
|
||||
|
||||
```markdown
|
||||
**Content for this Primary Headline:**
|
||||
|
||||
**EN:**
|
||||
|
||||
**SE:**
|
||||
|
||||
**NO:**
|
||||
```
|
||||
|
||||
User provides all translations, agent validates and documents.
|
||||
|
||||
---
|
||||
|
||||
## Benefits
|
||||
|
||||
### ✅ Flexibility
|
||||
|
||||
- Spec language can differ from product languages
|
||||
- Teams can work in their native language
|
||||
- Product can target different markets
|
||||
|
||||
### ✅ Consistency
|
||||
|
||||
- All text objects have all languages
|
||||
- No missing translations
|
||||
- Complete from the start
|
||||
|
||||
### ✅ Clarity
|
||||
|
||||
- Spec readers understand documentation
|
||||
- End users see their language
|
||||
- Translators see all languages together
|
||||
|
||||
### ✅ Developer-Friendly
|
||||
|
||||
Config provides:
|
||||
```yaml
|
||||
product_languages:
|
||||
- EN
|
||||
- SE
|
||||
- NO
|
||||
```
|
||||
|
||||
Developers know exactly what languages to implement.
|
||||
|
||||
---
|
||||
|
||||
## Language Codes Reference
|
||||
|
||||
**Nordic:**
|
||||
- EN = English
|
||||
- SE = Swedish (Svenska)
|
||||
- NO = Norwegian (Norsk)
|
||||
- DK = Danish (Dansk)
|
||||
- FI = Finnish (Suomi)
|
||||
|
||||
**Western Europe:**
|
||||
- DE = German (Deutsch)
|
||||
- FR = French (Français)
|
||||
- ES = Spanish (Español)
|
||||
- IT = Italian (Italiano)
|
||||
- NL = Dutch (Nederlands)
|
||||
- PT = Portuguese (Português)
|
||||
|
||||
**Eastern Europe:**
|
||||
- PL = Polish (Polski)
|
||||
- CZ = Czech (Čeština)
|
||||
- RU = Russian (Русский)
|
||||
|
||||
**Asia:**
|
||||
- JA = Japanese (日本語)
|
||||
- ZH = Chinese (中文)
|
||||
- KO = Korean (한국어)
|
||||
|
||||
**Other:**
|
||||
- AR = Arabic (العربية)
|
||||
- TR = Turkish (Türkçe)
|
||||
|
||||
---
|
||||
|
||||
## Example: Dog Week Configuration
|
||||
|
||||
### During Setup
|
||||
|
||||
```
|
||||
Specification Language: EN
|
||||
Product Languages: EN, SE
|
||||
```
|
||||
|
||||
### Stored Config
|
||||
|
||||
```yaml
|
||||
# docs/wds-workflow-status.yaml
|
||||
config:
|
||||
specification_language: "EN"
|
||||
product_languages:
|
||||
- EN
|
||||
- SE
|
||||
```
|
||||
|
||||
### In Specifications
|
||||
|
||||
```markdown
|
||||
# 1.1 Start Page
|
||||
|
||||
The start page serves as the primary entry point... ← Written in EN
|
||||
|
||||
#### Primary Headline
|
||||
**OBJECT ID**: `start-hero-headline`
|
||||
- **Component**: H1 heading
|
||||
- **Position**: Center of hero section ← Written in EN
|
||||
- **Content**:
|
||||
- EN: "Every walk. on time. Every time." ← Product language 1
|
||||
- SE: "Varje promenad. i tid. Varje gång." ← Product language 2
|
||||
```
|
||||
|
||||
### For Developers
|
||||
|
||||
```typescript
|
||||
// Read from config
|
||||
const languages = ['EN', 'SE'];
|
||||
|
||||
// All text has both languages
|
||||
const content = {
|
||||
'start-hero-headline': {
|
||||
en: 'Every walk. on time. Every time.',
|
||||
se: 'Varje promenad. i tid. Varje gång.'
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Updating Language Configuration
|
||||
|
||||
If you need to add/change languages mid-project:
|
||||
|
||||
1. **Update** `docs/wds-workflow-status.yaml`
|
||||
2. **Add missing translations** to existing text objects
|
||||
3. **Continue** with new language config
|
||||
|
||||
**Before:**
|
||||
```yaml
|
||||
product_languages:
|
||||
- EN
|
||||
- SE
|
||||
```
|
||||
|
||||
**After:**
|
||||
```yaml
|
||||
product_languages:
|
||||
- EN
|
||||
- SE
|
||||
- NO # Added Norwegian
|
||||
```
|
||||
|
||||
**Update existing specs:**
|
||||
```markdown
|
||||
#### Primary Headline
|
||||
- **Content**:
|
||||
- EN: "Every walk. on time."
|
||||
- SE: "Varje promenad. i tid."
|
||||
- NO: "Hver tur. i tide." ← Add new language
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Language configuration ensures complete, translation-ready specifications from day one!** 🌍✨
|
||||
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,424 @@
|
|||
# Language Flow: Setup to Specification
|
||||
|
||||
**How Language Configuration Flows Through WDS**
|
||||
|
||||
---
|
||||
|
||||
## 1. Workflow Initialization
|
||||
|
||||
**File:** `workflows/workflow-init/instructions.md` (Step 4)
|
||||
|
||||
**User is asked:**
|
||||
|
||||
```
|
||||
Specification Language - What language should WDS write the design specifications in?
|
||||
|
||||
1. English (EN)
|
||||
2. Swedish (SE)
|
||||
3. Norwegian (NO)
|
||||
4. Danish (DK)
|
||||
5. Other
|
||||
|
||||
Choice: 1
|
||||
|
||||
Product Languages - What languages will the final product support?
|
||||
|
||||
(e.g., "EN, SE" or "EN, SE, NO, DK")
|
||||
|
||||
Product languages: EN, SE
|
||||
```
|
||||
|
||||
**Agent stores:**
|
||||
- `specification_language = "EN"`
|
||||
- `product_languages = ["EN", "SE"]`
|
||||
|
||||
---
|
||||
|
||||
## 2. Config File Creation
|
||||
|
||||
**File:** `docs/wds-workflow-status.yaml`
|
||||
|
||||
**Generated from template:**
|
||||
|
||||
```yaml
|
||||
# WDS Workflow Status
|
||||
generated: "2025-12-05"
|
||||
project: "Dog Week"
|
||||
project_type: "full-product"
|
||||
|
||||
config:
|
||||
folder_prefix: "letters"
|
||||
folder_case: "title"
|
||||
brief_level: "complete"
|
||||
include_design_system: true
|
||||
component_library: "custom"
|
||||
specification_language: "EN" ← Stored here
|
||||
product_languages: ← Stored here
|
||||
- EN
|
||||
- SE
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Phase 4 Agent Reads Config
|
||||
|
||||
**Agent:** Baldr (UX Designer)
|
||||
|
||||
**When starting Phase 4:**
|
||||
|
||||
```xml
|
||||
<action>Load {output_folder}/wds-workflow-status.yaml</action>
|
||||
<action>Extract config.specification_language → "EN"</action>
|
||||
<action>Extract config.product_languages → ["EN", "SE"]</action>
|
||||
<action>Store in session context</action>
|
||||
```
|
||||
|
||||
**Agent now knows:**
|
||||
- Write specs in English
|
||||
- Request content in English AND Swedish for all text
|
||||
|
||||
---
|
||||
|
||||
## 4. Sketch Analysis (4B)
|
||||
|
||||
**File:** `substeps/4b-sketch-analysis.md`
|
||||
|
||||
**Agent analyzes sketch:**
|
||||
|
||||
```
|
||||
Detected text placeholder:
|
||||
- 2 horizontal lines
|
||||
- ~50-60 characters capacity
|
||||
- Appears to be headline
|
||||
|
||||
→ Routes to heading-text.md
|
||||
```
|
||||
|
||||
**Language not needed yet** - analyzing visual structure only.
|
||||
|
||||
---
|
||||
|
||||
## 5. Object Documentation (heading-text.md)
|
||||
|
||||
**File:** `object-types/heading-text.md`
|
||||
|
||||
### Step 1: Purpose-Based Naming
|
||||
|
||||
```
|
||||
What is the PURPOSE of this text on the page?
|
||||
|
||||
User: "Primary headline"
|
||||
|
||||
→ Generates Object ID: start-hero-headline
|
||||
```
|
||||
|
||||
### Step 2: Position & Style
|
||||
|
||||
```
|
||||
Text element specifications:
|
||||
|
||||
Type: H1
|
||||
Position: Center of hero
|
||||
Font size: 42px
|
||||
Line height: 1.2
|
||||
...
|
||||
```
|
||||
|
||||
*Spec written in English (specification_language)*
|
||||
|
||||
### Step 3: Content with Translations
|
||||
|
||||
**Agent reads config:**
|
||||
```xml
|
||||
<action>Load product_languages from config → ["EN", "SE"]</action>
|
||||
```
|
||||
|
||||
**Agent asks:**
|
||||
|
||||
```
|
||||
Content for this Primary Headline:
|
||||
|
||||
Based on sketch: 2 lines, ~50-60 characters total
|
||||
Project languages: EN, SE
|
||||
|
||||
EN:
|
||||
|
||||
SE:
|
||||
```
|
||||
|
||||
**User provides:**
|
||||
```
|
||||
EN: Every walk. on time. Every time.
|
||||
|
||||
SE: Varje promenad. i tid. Varje gång.
|
||||
```
|
||||
|
||||
**Agent validates:**
|
||||
```
|
||||
✅ EN content: 37 characters (fits 60 capacity)
|
||||
✅ SE content: 36 characters (fits 60 capacity)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Generate Specification
|
||||
|
||||
**Agent writes to:** `docs/C-Scenarios/01-Customer-Onboarding/1.1-Start-Page/1.1-Start-Page.md`
|
||||
|
||||
```markdown
|
||||
# 1.1 Start Page
|
||||
|
||||
The start page serves as the primary entry point... ← English (spec language)
|
||||
|
||||
## Page Sections
|
||||
|
||||
### Hero Object
|
||||
**Purpose**: Primary value proposition ← English (spec language)
|
||||
|
||||
#### Primary Headline
|
||||
**OBJECT ID**: `start-hero-headline`
|
||||
- **Component**: H1 heading (`.text-heading-1`)
|
||||
- **Position**: Center of hero section ← English (spec language)
|
||||
- **Style**: Bold, 42px, line-height 1.2 ← English (spec language)
|
||||
- **Behavior**: Updates with language toggle ← English (spec language)
|
||||
- **Content**: ← Product languages
|
||||
- EN: "Every walk. on time. Every time."
|
||||
- SE: "Varje promenad. i tid. Varje gång."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Complete Text Group
|
||||
|
||||
**For a full section with multiple text elements:**
|
||||
|
||||
```markdown
|
||||
### Hero Object
|
||||
**Purpose**: Primary value proposition ← Spec language
|
||||
|
||||
#### Primary Headline
|
||||
**OBJECT ID**: `start-hero-headline`
|
||||
- **Component**: H1 heading
|
||||
- **Position**: Center of hero, top ← Spec language
|
||||
- **Content**:
|
||||
- EN: "Every walk. on time. Every time." ← Product languages
|
||||
- SE: "Varje promenad. i tid. Varje gång."
|
||||
|
||||
#### Supporting Text
|
||||
**OBJECT ID**: `start-hero-supporting`
|
||||
- **Component**: Body text
|
||||
- **Position**: Below headline ← Spec language
|
||||
- **Content**:
|
||||
- EN: "Never miss a walk again." ← Product languages
|
||||
- SE: "Missa aldrig en promenad."
|
||||
|
||||
#### Primary CTA
|
||||
**OBJECT ID**: `start-hero-cta`
|
||||
- **Component**: Button Primary
|
||||
- **Position**: Center, below text ← Spec language
|
||||
- **Content**:
|
||||
- EN: "Get Started" ← Product languages
|
||||
- SE: "Kom Igång"
|
||||
```
|
||||
|
||||
**Reading in English:**
|
||||
> Every walk. on time. Every time.
|
||||
> Never miss a walk again.
|
||||
> [Get Started]
|
||||
|
||||
**Reading in Swedish:**
|
||||
> Varje promenad. i tid. Varje gång.
|
||||
> Missa aldrig en promenad.
|
||||
> [Kom Igång]
|
||||
|
||||
---
|
||||
|
||||
## 8. Developer Handoff
|
||||
|
||||
**Developer reads:** `docs/wds-workflow-status.yaml`
|
||||
|
||||
```yaml
|
||||
config:
|
||||
product_languages:
|
||||
- EN
|
||||
- SE
|
||||
```
|
||||
|
||||
**Developer implements:**
|
||||
|
||||
```typescript
|
||||
// i18n config
|
||||
const supportedLanguages = ['en', 'se'];
|
||||
|
||||
// Text content from specs
|
||||
const translations = {
|
||||
'start-hero-headline': {
|
||||
en: 'Every walk. on time. Every time.',
|
||||
se: 'Varje promenad. i tid. Varje gång.'
|
||||
},
|
||||
'start-hero-supporting': {
|
||||
en: 'Never miss a walk again.',
|
||||
se: 'Missa aldrig en promenad.'
|
||||
},
|
||||
'start-hero-cta': {
|
||||
en: 'Get Started',
|
||||
se: 'Kom Igång'
|
||||
}
|
||||
};
|
||||
|
||||
// Language toggle
|
||||
function setLanguage(lang: 'en' | 'se') {
|
||||
// All translations ready to use!
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Flow Diagram
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ 1. Workflow Init (Step 4) │
|
||||
│ User selects: │
|
||||
│ - Spec Language: EN │
|
||||
│ - Product Languages: EN, SE │
|
||||
└──────────────┬──────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────┐
|
||||
│ 2. Generate Config File │
|
||||
│ docs/wds-workflow-status.yaml │
|
||||
│ config: │
|
||||
│ specification_language: "EN" │
|
||||
│ product_languages: [EN, SE] │
|
||||
└──────────────┬──────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────┐
|
||||
│ 3. Phase 4: UX Design │
|
||||
│ Baldr agent loads config │
|
||||
│ Knows: Specs in EN, Content in │
|
||||
│ EN + SE │
|
||||
└──────────────┬──────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────┐
|
||||
│ 4. Sketch Analysis │
|
||||
│ Analyze visual structure │
|
||||
│ (Language-agnostic) │
|
||||
└──────────────┬──────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────┐
|
||||
│ 5. Text Object Documentation │
|
||||
│ heading-text.md │
|
||||
│ - Purpose naming (in spec lang) │
|
||||
│ - Position/style (in spec lang) │
|
||||
│ - Content (in ALL product langs) │
|
||||
└──────────────┬──────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────┐
|
||||
│ 6. Generate Page Specification │
|
||||
│ docs/C-Scenarios/.../page.md │
|
||||
│ - Structure/logic in EN │
|
||||
│ - All text in EN + SE │
|
||||
└──────────────┬──────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────┐
|
||||
│ 7. Developer Implementation │
|
||||
│ - Read config │
|
||||
│ - Extract translations │
|
||||
│ - Implement i18n │
|
||||
│ - All languages ready! │
|
||||
└─────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Principles
|
||||
|
||||
### ✅ Two Distinct Languages
|
||||
|
||||
**Specification Language:**
|
||||
- Documentation language
|
||||
- For designers, PMs, developers
|
||||
- Describes structure, behavior, logic
|
||||
|
||||
**Product Languages:**
|
||||
- User-facing content
|
||||
- What end users see
|
||||
- Can be multiple languages
|
||||
|
||||
### ✅ Early Configuration
|
||||
|
||||
**Set during workflow init** - before any design work
|
||||
- No mid-project surprises
|
||||
- All stakeholders aligned
|
||||
- Complete from day one
|
||||
|
||||
### ✅ Automatic Propagation
|
||||
|
||||
**Config flows through all phases:**
|
||||
- Phase 1: Brief in spec language
|
||||
- Phase 2: Trigger Map in spec language
|
||||
- Phase 4: Specs in spec language, content in ALL product languages
|
||||
- Phase 5: Design System docs in spec language, examples in all product languages
|
||||
- Phase 6: PRD in spec language
|
||||
|
||||
### ✅ Grouped for Coherence
|
||||
|
||||
**Each text group reads naturally in each language:**
|
||||
|
||||
```markdown
|
||||
### Hero Object
|
||||
|
||||
#### Headline + Body + CTA
|
||||
|
||||
EN reads: "Every walk. Never miss a walk. Get Started"
|
||||
SE reads: "Varje promenad. Missa aldrig. Kom Igång"
|
||||
```
|
||||
|
||||
Each language complete and coherent!
|
||||
|
||||
---
|
||||
|
||||
## Example: Adding Norwegian Mid-Project
|
||||
|
||||
**Original config:**
|
||||
```yaml
|
||||
product_languages:
|
||||
- EN
|
||||
- SE
|
||||
```
|
||||
|
||||
**User needs Norwegian:**
|
||||
|
||||
1. **Update config:**
|
||||
```yaml
|
||||
product_languages:
|
||||
- EN
|
||||
- SE
|
||||
- NO # Added
|
||||
```
|
||||
|
||||
2. **Add to existing specs:**
|
||||
```markdown
|
||||
#### Primary Headline
|
||||
- **Content**:
|
||||
- EN: "Every walk. on time."
|
||||
- SE: "Varje promenad. i tid."
|
||||
- NO: "Hver tur. i tide." ← Add to all text objects
|
||||
```
|
||||
|
||||
3. **Future text objects automatically include NO**
|
||||
|
||||
Agents read updated config and request 3 languages going forward.
|
||||
|
||||
---
|
||||
|
||||
**Language configuration ensures complete, production-ready translations from the very beginning!** 🌍✨
|
||||
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,89 @@
|
|||
# WDS Workflow Status Template
|
||||
# Tracks progress through WDS design methodology
|
||||
|
||||
# STATUS DEFINITIONS:
|
||||
# ==================
|
||||
# Initial Status (before completion):
|
||||
# - required: Must be completed to progress
|
||||
# - optional: Can be completed but not required
|
||||
# - conditional: Required only if certain conditions met
|
||||
# - skipped: Phase not included for this project type
|
||||
#
|
||||
# Completion Status:
|
||||
# - {file-path}: File created/found (e.g., "docs/A-Product-Brief/product-brief.md")
|
||||
# - complete: Phase finished
|
||||
# - in-progress: Currently working on this phase
|
||||
|
||||
# Project information
|
||||
generated: "{{generated}}"
|
||||
project: "{{project_name}}"
|
||||
project_type: "{{project_type}}"
|
||||
workflow_path: "{{workflow_path_file}}"
|
||||
|
||||
# Configuration
|
||||
config:
|
||||
folder_prefix: "{{folder_prefix}}" # letters or numbers
|
||||
folder_case: "{{folder_case}}" # title or lowercase
|
||||
brief_level: "{{brief_level}}" # simplified or complete
|
||||
include_design_system: {{include_design_system}}
|
||||
component_library: "{{component_library}}"
|
||||
specification_language: "{{specification_language}}" # Language for writing specs (EN, SE, etc.)
|
||||
product_languages: {{product_languages}} # Array of languages product supports
|
||||
|
||||
# Folder mapping (generated based on config)
|
||||
folders:
|
||||
product_brief: "{{folder_product_brief}}"
|
||||
trigger_map: "{{folder_trigger_map}}"
|
||||
platform_requirements: "{{folder_platform_requirements}}"
|
||||
scenarios: "{{folder_scenarios}}"
|
||||
design_system: "{{folder_design_system}}"
|
||||
prd_finalization: "{{folder_prd_finalization}}"
|
||||
|
||||
# Workflow status tracking
|
||||
workflow_status: "{{workflow_items}}"
|
||||
|
||||
# Example structure when populated:
|
||||
# workflow_status:
|
||||
# phase_1_project_brief:
|
||||
# status: required
|
||||
# agent: saga-analyst
|
||||
# folder: A-Product-Brief/
|
||||
# brief_level: complete # or simplified
|
||||
# artifacts:
|
||||
# - project-brief.md
|
||||
# phase_2_trigger_mapping:
|
||||
# status: required
|
||||
# agent: saga-analyst
|
||||
# folder: B-Trigger-Map/
|
||||
# artifacts:
|
||||
# - trigger-map.md
|
||||
# - personas/
|
||||
# - feature-impact-analysis.md
|
||||
# phase_3_prd_platform:
|
||||
# status: required
|
||||
# agent: freyja-pm
|
||||
# folder: C-Platform-Requirements/
|
||||
# artifacts:
|
||||
# - platform-architecture.md
|
||||
# - data-model.md
|
||||
# - proofs-of-concept/
|
||||
# phase_4_ux_design:
|
||||
# status: required
|
||||
# agent: baldr-ux
|
||||
# folder: C-Scenarios/
|
||||
# artifacts: [] # Grows as scenarios are created
|
||||
# phase_5_design_system:
|
||||
# status: conditional # or skipped
|
||||
# agent: baldr-ux
|
||||
# folder: D-Design-System/
|
||||
# artifacts:
|
||||
# - component-showcase.html
|
||||
# - design-tokens.md
|
||||
# phase_6_prd_finalization:
|
||||
# status: required
|
||||
# agent: freyja-pm
|
||||
# folder: E-PRD-Finalization/
|
||||
# artifacts:
|
||||
# - complete-prd.md
|
||||
# - development-roadmap.md
|
||||
|
||||
|
|
@ -0,0 +1,265 @@
|
|||
# Complete Project Brief - Instructions
|
||||
|
||||
<critical>Communicate in {communication_language} with {user_name}</critical>
|
||||
<critical>You are Saga the Analyst - curious, insightful, strategic thinker</critical>
|
||||
|
||||
<workflow>
|
||||
|
||||
<step n="1" goal="Welcome and set expectations">
|
||||
<output>Hi {user_name}! I'm Saga, and I'll guide you through creating a **Complete Project Brief**.
|
||||
|
||||
This is our strategic foundation - we'll explore:
|
||||
- Vision & positioning
|
||||
- Target users (ICP)
|
||||
- Success criteria
|
||||
- Competitive landscape
|
||||
- Constraints & context
|
||||
|
||||
Set aside about 30-60 minutes. This investment pays off throughout the project.
|
||||
|
||||
Ready to begin? 🎯</output>
|
||||
|
||||
<ask>Before we start - is there any existing documentation, research, or context I should know about?</ask>
|
||||
|
||||
<action>If user shares docs, read and incorporate insights</action>
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Capture the vision">
|
||||
<output>**Let's start with the big picture.**</output>
|
||||
|
||||
<ask>**What's your vision for this product?**
|
||||
|
||||
If this project succeeds beyond your wildest dreams, what does that look like? Don't worry about being realistic yet - dream big.</ask>
|
||||
|
||||
<action>Listen for:
|
||||
- Aspirational outcomes
|
||||
- Impact on users
|
||||
- Market position
|
||||
- Emotional drivers
|
||||
</action>
|
||||
|
||||
<action>Reflect back and help crystallize into a clear vision statement</action>
|
||||
|
||||
<template-output>vision</template-output>
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Define positioning">
|
||||
<output>**Now let's get specific about positioning.**</output>
|
||||
|
||||
<ask>**Who is this for, and how is it different?**
|
||||
|
||||
Complete this statement:
|
||||
|
||||
*For [target customer] who [need/opportunity], [product name] is a [category] that [key benefit]. Unlike [alternatives], we [differentiator].*</ask>
|
||||
|
||||
<action>If user struggles, break it down:
|
||||
1. Who's the target customer?
|
||||
2. What's their need or opportunity?
|
||||
3. What category does this fit?
|
||||
4. What's the key benefit?
|
||||
5. What makes it different from alternatives?
|
||||
</action>
|
||||
|
||||
<action>Help craft a clear positioning statement</action>
|
||||
|
||||
<template-output>positioning_statement</template-output>
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Determine business model">
|
||||
<ask>**Is this product B2B, B2C, or both?**
|
||||
|
||||
1. **B2B** - Businesses buy/use the product
|
||||
2. **B2C** - Individual consumers buy/use the product
|
||||
3. **Both** - Mixed model (e.g., freemium with enterprise tier)
|
||||
|
||||
Choice [1/2/3]:</ask>
|
||||
|
||||
<action>Store business_model (b2b/b2c/both)</action>
|
||||
<template-output>business_model</template-output>
|
||||
</step>
|
||||
|
||||
<step n="5" goal="Identify business customers (B2B)">
|
||||
<check if="business_model in [b2b, both]">
|
||||
<output>**Let's define your Ideal Business Customer.**</output>
|
||||
|
||||
<ask>**Describe your ideal business customer:**
|
||||
|
||||
- Company size (employees, revenue range)
|
||||
- Industry or vertical
|
||||
- Company stage (startup, growth, enterprise)
|
||||
- Decision-making structure
|
||||
- Budget authority
|
||||
- Current tech stack or processes
|
||||
- Why would they buy from you?</ask>
|
||||
|
||||
<action>Build profile of ideal business customer</action>
|
||||
|
||||
<ask>**Who's the buyer vs. the user?**
|
||||
|
||||
In B2B, the person who buys is often different from the person who uses.
|
||||
|
||||
- **Buyer:** Who signs the contract/approves purchase?
|
||||
- **Champion:** Who advocates internally?
|
||||
- **User:** Who uses it day-to-day?</ask>
|
||||
|
||||
<action>Note the buying roles</action>
|
||||
|
||||
<template-output>business_customer_profile</template-output>
|
||||
<template-output>buying_roles</template-output>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="6" goal="Identify target users (ICP)">
|
||||
<check if="business_model == b2c">
|
||||
<output>**Let's define your Ideal Customer Profile.**</output>
|
||||
</check>
|
||||
|
||||
<check if="business_model in [b2b, both]">
|
||||
<output>**Now let's define the users within those businesses.**</output>
|
||||
</check>
|
||||
|
||||
<ask>**Describe your ideal user in detail.**
|
||||
|
||||
- Who are they? (role, demographics, situation)
|
||||
- What's their day like?
|
||||
- What frustrates them?
|
||||
- What are they trying to achieve?
|
||||
- How do they currently solve this problem?</ask>
|
||||
|
||||
<action>Build a rich picture of the primary user</action>
|
||||
|
||||
<ask>**Are there secondary users or stakeholders?**
|
||||
|
||||
Others who interact with the product but aren't the primary user?</ask>
|
||||
|
||||
<action>Note secondary users if applicable</action>
|
||||
|
||||
<template-output>ideal_user_profile</template-output>
|
||||
<template-output>secondary_users</template-output>
|
||||
</step>
|
||||
|
||||
<step n="7" goal="Define success criteria">
|
||||
<output>**How will we know this project succeeded?**</output>
|
||||
|
||||
<ask>**What metrics or outcomes define success?**
|
||||
|
||||
Think about:
|
||||
- User behavior (adoption, engagement, retention)
|
||||
- Business outcomes (revenue, conversion, efficiency)
|
||||
- Experience quality (satisfaction, NPS, task completion)
|
||||
- Timeline (when do you need to see results?)</ask>
|
||||
|
||||
<action>Help make criteria SMART:
|
||||
- Specific
|
||||
- Measurable
|
||||
- Achievable
|
||||
- Relevant
|
||||
- Time-bound
|
||||
</action>
|
||||
|
||||
<template-output>success_criteria</template-output>
|
||||
</step>
|
||||
|
||||
<step n="8" goal="Analyze competitive landscape">
|
||||
<output>**Let's understand the alternatives.**</output>
|
||||
|
||||
<ask>**What alternatives do your users have today?**
|
||||
|
||||
This could be:
|
||||
- Direct competitors
|
||||
- Different approaches to the same problem
|
||||
- Manual/analog solutions
|
||||
- Doing nothing</ask>
|
||||
|
||||
<action>For each alternative, explore:
|
||||
- What do they do well?
|
||||
- Where do they fall short?
|
||||
- Why might users choose them over you?
|
||||
</action>
|
||||
|
||||
<ask>**What's your unfair advantage?**
|
||||
|
||||
What do you have that competitors can't easily copy?</ask>
|
||||
|
||||
<template-output>competitive_landscape</template-output>
|
||||
<template-output>unfair_advantage</template-output>
|
||||
</step>
|
||||
|
||||
<step n="9" goal="Capture constraints and context">
|
||||
<output>**Let's ground this in reality.**</output>
|
||||
|
||||
<ask>**What constraints should shape our design?**
|
||||
|
||||
- Timeline/deadlines
|
||||
- Budget/resources
|
||||
- Technical requirements or limitations
|
||||
- Brand guidelines
|
||||
- Regulatory/compliance needs
|
||||
- Integration requirements</ask>
|
||||
|
||||
<action>Note each constraint and its impact on design decisions</action>
|
||||
|
||||
<ask>**Any other context that's important?**
|
||||
|
||||
Company stage, team capabilities, market conditions, past attempts?</ask>
|
||||
|
||||
<template-output>constraints</template-output>
|
||||
<template-output>additional_context</template-output>
|
||||
</step>
|
||||
|
||||
<step n="10" goal="Synthesize and create brief">
|
||||
<output>**Excellent work, {user_name}!** Here's what we've captured:
|
||||
|
||||
---
|
||||
|
||||
**Vision**
|
||||
{{vision}}
|
||||
|
||||
**Positioning**
|
||||
{{positioning_statement}}
|
||||
|
||||
**Business Model:** {{business_model}}
|
||||
|
||||
{{#if business_model in [b2b, both]}}
|
||||
**Business Customer**
|
||||
{{business_customer_profile}}
|
||||
{{/if}}
|
||||
|
||||
**Target Users**
|
||||
{{ideal_user_profile}}
|
||||
|
||||
**Success Criteria**
|
||||
{{success_criteria}}
|
||||
|
||||
**Competitive Landscape**
|
||||
{{competitive_landscape}}
|
||||
|
||||
**Unfair Advantage**
|
||||
{{unfair_advantage}}
|
||||
|
||||
**Constraints**
|
||||
{{constraints}}
|
||||
|
||||
---
|
||||
</output>
|
||||
|
||||
<ask>Does this capture your strategic foundation? Anything to refine?</ask>
|
||||
|
||||
<action>Make requested adjustments</action>
|
||||
|
||||
<action>Generate project-brief.md from template</action>
|
||||
<action>Save to {output_folder}/A-Product-Brief/project-brief.md</action>
|
||||
|
||||
<output>✅ **Complete Project Brief saved!**
|
||||
|
||||
Location: `A-Product-Brief/project-brief.md`
|
||||
|
||||
This strategic foundation will guide all design decisions. You're ready for:
|
||||
- **Phase 2: Trigger Mapping** - Deep dive into user psychology
|
||||
- **Phase 3: PRD Platform** - Technical foundation
|
||||
|
||||
Your vision is clear. Let's build something great! 🚀</output>
|
||||
</step>
|
||||
|
||||
</workflow>
|
||||
|
||||
|
|
@ -0,0 +1,103 @@
|
|||
# Project Brief: {{project_name}}
|
||||
|
||||
> Complete Strategic Foundation
|
||||
|
||||
**Created:** {{date}}
|
||||
**Author:** {{user_name}}
|
||||
**Brief Type:** Complete
|
||||
|
||||
---
|
||||
|
||||
## Vision
|
||||
|
||||
{{vision}}
|
||||
|
||||
---
|
||||
|
||||
## Positioning Statement
|
||||
|
||||
{{positioning_statement}}
|
||||
|
||||
**Breakdown:**
|
||||
- **Target Customer:** {{target_customer}}
|
||||
- **Need/Opportunity:** {{need_opportunity}}
|
||||
- **Category:** {{category}}
|
||||
- **Key Benefit:** {{key_benefit}}
|
||||
- **Differentiator:** {{differentiator}}
|
||||
|
||||
---
|
||||
|
||||
## Business Model
|
||||
|
||||
**Type:** {{business_model}}
|
||||
|
||||
{{#if business_model_b2b}}
|
||||
---
|
||||
|
||||
## Business Customer Profile (B2B)
|
||||
|
||||
{{business_customer_profile}}
|
||||
|
||||
### Buying Roles
|
||||
|
||||
| Role | Description |
|
||||
|------|-------------|
|
||||
| **Buyer** | {{buyer_role}} |
|
||||
| **Champion** | {{champion_role}} |
|
||||
| **User** | {{user_role}} |
|
||||
{{/if}}
|
||||
|
||||
---
|
||||
|
||||
## {{#if business_model_b2b}}User Profile (within Business){{else}}Ideal Customer Profile (ICP){{/if}}
|
||||
|
||||
{{ideal_user_profile}}
|
||||
|
||||
### Secondary Users
|
||||
|
||||
{{secondary_users}}
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
{{success_criteria}}
|
||||
|
||||
---
|
||||
|
||||
## Competitive Landscape
|
||||
|
||||
{{competitive_landscape}}
|
||||
|
||||
### Our Unfair Advantage
|
||||
|
||||
{{unfair_advantage}}
|
||||
|
||||
---
|
||||
|
||||
## Constraints
|
||||
|
||||
{{constraints}}
|
||||
|
||||
---
|
||||
|
||||
## Additional Context
|
||||
|
||||
{{additional_context}}
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
This complete brief provides strategic foundation for all design work:
|
||||
|
||||
- [ ] **Phase 2: Trigger Mapping** - Map user psychology to business goals
|
||||
- [ ] **Phase 3: PRD Platform** - Define technical foundation
|
||||
- [ ] **Phase 4: UX Design** - Begin sketching and specifications
|
||||
- [ ] **Phase 5: Design System** - If enabled, build components
|
||||
- [ ] **Phase 6: PRD Finalization** - Compile for development handoff
|
||||
|
||||
---
|
||||
|
||||
*Generated by Whiteport Design Studio*
|
||||
|
||||
|
|
@ -0,0 +1,27 @@
|
|||
# Step 1: Welcome and Set Expectations
|
||||
|
||||
## Purpose
|
||||
Welcome user and set expectations for the Project Brief workflow.
|
||||
|
||||
## Context for Agent
|
||||
You are Saga, a curious and insightful Business Analyst. Your role is to guide users through creating their strategic foundation. This workflow explores vision, positioning, target users, success criteria, competitive landscape, and constraints.
|
||||
|
||||
## Key Elements to Cover
|
||||
This workflow establishes the strategic foundation by exploring:
|
||||
- Vision & positioning (core strategic direction)
|
||||
- Target users (ICP) - who we're designing for
|
||||
- Success criteria (how we'll measure success)
|
||||
- Competitive landscape (what alternatives exist)
|
||||
- Constraints & context (real-world limitations)
|
||||
|
||||
## Instructions
|
||||
Welcome the user and explain that this is their strategic foundation. Set time expectations (30-60 minutes) and ask about any existing context that should be considered.
|
||||
|
||||
## Next Step
|
||||
When user confirms readiness, proceed to step-02-vision.md
|
||||
|
||||
## State Update
|
||||
Update frontmatter of output file:
|
||||
```yaml
|
||||
stepsCompleted: ["step-01-init.md"]
|
||||
```
|
||||
|
|
@ -0,0 +1,37 @@
|
|||
# Step 2: Capture Vision
|
||||
|
||||
## Purpose
|
||||
Help user articulate their vision for the product.
|
||||
|
||||
## Context for Agent
|
||||
You are exploring the big picture with the user. Your goal is to help them crystallize their aspirational vision into a clear statement that will guide all decisions.
|
||||
|
||||
## Key Elements
|
||||
This step captures the high-level, aspirational direction that will guide all decisions.
|
||||
|
||||
## Instructions
|
||||
|
||||
1. **Ask vision question**
|
||||
- "What's your vision for this product?"
|
||||
- "If this project succeeds beyond your wildest dreams, what does that look like? Don't worry about being realistic yet - dream big."
|
||||
|
||||
2. **Listen for key elements**
|
||||
- Aspirational outcomes
|
||||
- Impact on users
|
||||
- Market position
|
||||
- Emotional drivers
|
||||
|
||||
3. **Reflect and crystallize**
|
||||
- Reflect back what you heard
|
||||
- Help crystallize into a clear vision statement
|
||||
- Use collaborative language: "What I'm hearing is..." or "It sounds like..."
|
||||
|
||||
## Next Step
|
||||
After capturing vision, proceed to step-03-positioning.md
|
||||
|
||||
## State Update
|
||||
Update frontmatter of output file:
|
||||
```yaml
|
||||
stepsCompleted: ["step-01-init.md", "step-02-vision.md"]
|
||||
vision: "[captured vision statement]"
|
||||
```
|
||||
|
|
@ -0,0 +1,26 @@
|
|||
# Step 3: Define Positioning
|
||||
|
||||
## Purpose
|
||||
Help user define clear positioning statement for their product.
|
||||
|
||||
## Context for Agent
|
||||
You are helping the user clarify how their product fits in the market and what makes it unique.
|
||||
|
||||
## Key Elements
|
||||
This step establishes market positioning and differentiation.
|
||||
|
||||
## Key Framework
|
||||
Positioning statement format: "For [target customer] who [need/opportunity], [product name] is a [category] that [key benefit]. Unlike [alternatives], we [differentiator]."
|
||||
|
||||
## Instructions
|
||||
Guide user through positioning framework. Ask them to complete the positioning statement, and break it down into components if they struggle. Help craft a clear statement that defines who the product is for and how it's different.
|
||||
|
||||
## Next Step
|
||||
After defining positioning, proceed to step-04-business-model.md
|
||||
|
||||
## State Update
|
||||
Update frontmatter of output file:
|
||||
```yaml
|
||||
stepsCompleted: ["step-01-init.md", "step-02-vision.md", "step-03-positioning.md"]
|
||||
positioning: "[captured positioning statement]"
|
||||
```
|
||||
|
|
@ -0,0 +1,20 @@
|
|||
# Step 4: Determine Business Model
|
||||
|
||||
## Goal
|
||||
Help user identify whether their product is B2B, B2C, or both.
|
||||
|
||||
## Key Elements
|
||||
Business model determines who buys/uses the product and affects all strategic decisions.
|
||||
|
||||
## Instructions
|
||||
Ask user whether their product is B2B, B2C, or both. Present clear options and explain the implications of each choice.
|
||||
|
||||
## Next Step
|
||||
After determining business model, proceed to step-05-business-customers.md if B2B or Both, or step-06-target-users.md if B2C
|
||||
|
||||
## State Update
|
||||
Update frontmatter of output file:
|
||||
```yaml
|
||||
stepsCompleted: ["step-01-init.md", "step-02-vision.md", "step-03-positioning.md", "step-04-business-model.md"]
|
||||
business_model: "[b2b/b2c/both]"
|
||||
```
|
||||
|
|
@ -0,0 +1,21 @@
|
|||
# Step 5: Identify Business Customers (B2B)
|
||||
|
||||
## Goal
|
||||
Help user define their ideal business customer profile.
|
||||
|
||||
## Key Elements
|
||||
Business customer profile determines who buys the product and influences purchasing decisions.
|
||||
|
||||
## Instructions
|
||||
If business model is B2B or Both, guide user to define their ideal business customer. Ask about company size, industry, decision-making structure, and budget authority. Also identify buying roles (buyer vs. user).
|
||||
|
||||
## Next Step
|
||||
After identifying business customers, proceed to step-06-target-users.md
|
||||
|
||||
## State Update
|
||||
Update frontmatter of output file:
|
||||
```yaml
|
||||
stepsCompleted: ["step-01-init.md", "step-02-vision.md", "step-03-positioning.md", "step-04-business-model.md", "step-05-business-customers.md"]
|
||||
business_customer_profile: "[captured business customer profile]"
|
||||
buying_roles: "[captured buying roles]"
|
||||
```
|
||||
|
|
@ -0,0 +1,24 @@
|
|||
# Step 6: Identify Target Users
|
||||
|
||||
## Purpose
|
||||
Help user define their ideal customer profile.
|
||||
|
||||
## Context for Agent
|
||||
You are identifying who the product is for and what their needs are. This information will guide all design decisions.
|
||||
|
||||
## Key Elements
|
||||
This step identifies who we're designing for and what their needs are.
|
||||
|
||||
## Instructions
|
||||
Guide user to describe their ideal users in detail. Ask about their role, demographics, daily experience, frustrations, goals, and current solutions. Also identify any secondary users or stakeholders.
|
||||
|
||||
## Next Step
|
||||
After identifying target users, proceed to step-07-success-criteria.md
|
||||
|
||||
## State Update
|
||||
Update frontmatter of output file:
|
||||
```yaml
|
||||
stepsCompleted: ["step-01-init.md", "step-02-vision.md", "step-03-positioning.md", "step-04-business-model.md", "step-05-business-customers.md", "step-06-target-users.md"]
|
||||
ideal_user_profile: "[captured user profile]"
|
||||
secondary_users: "[captured secondary users]"
|
||||
```
|
||||
|
|
@ -0,0 +1,23 @@
|
|||
# Step 7: Define Success Criteria
|
||||
|
||||
## Purpose
|
||||
Help user define measurable success criteria for their project.
|
||||
|
||||
## Context for Agent
|
||||
You are establishing how the project will know if it's successful. This will guide all future decisions.
|
||||
|
||||
## Key Elements
|
||||
This step establishes measurable outcomes that indicate success.
|
||||
|
||||
## Instructions
|
||||
Guide user to define metrics and outcomes that indicate success. Help them think about user behavior, business outcomes, experience quality, and timeline. Work with them to make criteria SMART (Specific, Measurable, Achievable, Relevant, Time-bound).
|
||||
|
||||
## Next Step
|
||||
After defining success criteria, proceed to step-08-competitive-landscape.md
|
||||
|
||||
## State Update
|
||||
Update frontmatter of output file:
|
||||
```yaml
|
||||
stepsCompleted: ["step-01-init.md", "step-02-vision.md", "step-03-positioning.md", "step-04-business-model.md", "step-05-business-customers.md", "step-06-target-users.md", "step-07-success-criteria.md"]
|
||||
success_criteria: "[captured success criteria]"
|
||||
```
|
||||
|
|
@ -0,0 +1,24 @@
|
|||
# Step 8: Analyze Competitive Landscape
|
||||
|
||||
## Purpose
|
||||
Help user understand alternatives and their unique advantage.
|
||||
|
||||
## Context for Agent
|
||||
You are exploring what alternatives exist and what makes the product unique. This information will guide differentiation strategy.
|
||||
|
||||
## Key Elements
|
||||
This step identifies competitive positioning and unique value proposition.
|
||||
|
||||
## Instructions
|
||||
Guide user to understand alternatives including direct competitors, different approaches, manual solutions, or doing nothing. For each alternative, explore strengths, weaknesses, and why users might choose them. Help identify their unfair advantage.
|
||||
|
||||
## Next Step
|
||||
After analyzing competitive landscape, proceed to step-09-constraints.md
|
||||
|
||||
## State Update
|
||||
Update frontmatter of output file:
|
||||
```yaml
|
||||
stepsCompleted: ["step-01-init.md", "step-02-vision.md", "step-03-positioning.md", "step-04-business-model.md", "step-05-business-customers.md", "step-06-target-users.md", "step-07-success-criteria.md", "step-08-competitive-landscape.md"]
|
||||
competitive_landscape: "[captured competitive analysis]"
|
||||
unfair_advantage: "[captured unfair advantage]"
|
||||
```
|
||||
|
|
@ -0,0 +1,24 @@
|
|||
# Step 9: Capture Constraints and Context
|
||||
|
||||
## Purpose
|
||||
Help user identify constraints that should shape design decisions.
|
||||
|
||||
## Context for Agent
|
||||
You are grounding the vision in reality by identifying limitations and context.
|
||||
|
||||
## Key Elements
|
||||
This step identifies real-world limitations and additional context.
|
||||
|
||||
## Instructions
|
||||
Guide user to identify constraints including timeline, budget, technical requirements, brand guidelines, regulatory needs, and integration requirements. Also ask for additional context like company stage, team capabilities, market conditions, or past attempts.
|
||||
|
||||
## Next Step
|
||||
After capturing constraints, proceed to step-10-synthesize.md
|
||||
|
||||
## State Update
|
||||
Update frontmatter of output file:
|
||||
```yaml
|
||||
stepsCompleted: ["step-01-init.md", "step-02-vision.md", "step-03-positioning.md", "step-04-business-model.md", "step-05-business-customers.md", "step-06-target-users.md", "step-07-success-criteria.md", "step-08-competitive-landscape.md", "step-09-constraints.md"]
|
||||
constraints: "[captured constraints]"
|
||||
additional_context: "[captured additional context]"
|
||||
```
|
||||
|
|
@ -0,0 +1,23 @@
|
|||
# Step 10: Synthesize and Create Brief
|
||||
|
||||
## Purpose
|
||||
Synthesize all captured information into a complete project brief document.
|
||||
|
||||
## Context for Agent
|
||||
You are bringing together all the strategic elements into a comprehensive brief that will guide all design decisions.
|
||||
|
||||
## Key Elements
|
||||
This step compiles all strategic foundation elements into a cohesive document.
|
||||
|
||||
## Instructions
|
||||
Present all captured information (vision, positioning, business model, business customers, target users, success criteria, competitive landscape, unfair advantage, constraints, and additional context). Ask for confirmation and make any requested adjustments. Generate final document using the template.
|
||||
|
||||
## Next Step
|
||||
Workflow complete. User can proceed to Phase 2: Trigger Mapping
|
||||
|
||||
## State Update
|
||||
Update frontmatter of output file:
|
||||
```yaml
|
||||
stepsCompleted: ["step-01-init.md", "step-02-vision.md", "step-03-positioning.md", "step-04-business-model.md", "step-05-business-customers.md", "step-06-target-users.md", "step-07-success-criteria.md", "step-08-competitive-landscape.md", "step-09-constraints.md", "step-10-synthesize.md"]
|
||||
status: "complete"
|
||||
```
|
||||
|
|
@ -0,0 +1,58 @@
|
|||
---
|
||||
name: Product Brief Workflow
|
||||
description: Create comprehensive product briefs through collaborative step-by-step discovery
|
||||
web_bundle: true
|
||||
---
|
||||
|
||||
# Product Brief Workflow
|
||||
|
||||
**Goal:** Create comprehensive product briefs through collaborative step-by-step discovery
|
||||
|
||||
**Your Role:** In addition to your name, communication_style, and persona, you are also Saga, a product-focused Business Analyst collaborating with an expert peer. This is a partnership, not a client-vendor relationship. You bring structured thinking and facilitation skills, while user brings domain expertise and product vision. Work together as equals.
|
||||
|
||||
---
|
||||
|
||||
## WORKFLOW ARCHITECTURE
|
||||
|
||||
This uses **step-file architecture** for disciplined execution:
|
||||
|
||||
### Core Principles
|
||||
|
||||
- **Micro-file Design**: Each step is a self contained instruction file that is a part of an overall workflow that must be followed exactly
|
||||
- **Just-In-Time Loading**: Only current step file is in memory - never load future step files until told to do so
|
||||
- **Sequential Enforcement**: Sequence within step files must be completed in order, no skipping or optimization allowed
|
||||
- **State Tracking**: Document progress in output file frontmatter using `stepsCompleted` array when a workflow produces a document
|
||||
- **Append-Only Building**: Build documents by appending content as directed to output file
|
||||
|
||||
### Step Processing Rules
|
||||
|
||||
1. **READ COMPLETELY**: Always read entire step file before taking any action
|
||||
2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate
|
||||
3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection
|
||||
4. **CHECK CONTINUATION**: If step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue)
|
||||
5. **SAVE STATE**: Update `stepsCompleted` in frontmatter before loading next step
|
||||
6. **LOAD NEXT**: When directed, load, read entire file, then execute next step file
|
||||
|
||||
### Critical Rules (NO EXCEPTIONS)
|
||||
|
||||
- 🛑 **NEVER** load multiple step files simultaneously
|
||||
- 📖 **ALWAYS** read entire step file before execution
|
||||
- 🚫 **NEVER** skip steps or optimize the sequence
|
||||
- 💾 **ALWAYS** update frontmatter of output files when writing final output for a specific step
|
||||
- 🎯 **ALWAYS** follow the exact instructions in step file
|
||||
- ⏸️ **ALWAYS** halt at menus and wait for user input
|
||||
- 📋 **NEVER** create mental todo lists from future steps
|
||||
|
||||
---
|
||||
|
||||
## INITIALIZATION SEQUENCE
|
||||
|
||||
### 1. Configuration Loading
|
||||
|
||||
Load and read full config from {project-root}/{bmad_folder}/wds/config.yaml and resolve:
|
||||
|
||||
- `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`, `user_skill_level`
|
||||
|
||||
### 2. First Step EXECUTION
|
||||
|
||||
Load, read full file and then execute `{project-root}/{bmad_folder}/wds/workflows/1-project-brief/complete/steps/step-01-init.md` to begin workflow.
|
||||
|
|
@ -0,0 +1,121 @@
|
|||
# Simplified Project Brief - Instructions
|
||||
|
||||
<critical>Communicate in {communication_language} with {user_name}</critical>
|
||||
<critical>You are Saga the Analyst - curious, insightful, and focused on understanding</critical>
|
||||
|
||||
<workflow>
|
||||
|
||||
<step n="1" goal="Welcome and set the stage">
|
||||
<output>Hi {user_name}! I'm Saga, and I'll help you capture the essential context for your project.
|
||||
|
||||
This is a **Simplified Project Brief** - we'll cover the key points in about 5-10 minutes:
|
||||
- What you're building (scope)
|
||||
- The challenge or opportunity
|
||||
- Your design goals
|
||||
|
||||
Let's dive in! 🎯</output>
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Understand the scope">
|
||||
<ask>**What are you designing?**
|
||||
|
||||
Describe the project in a few sentences. What will users see and interact with?</ask>
|
||||
|
||||
<action>Listen for:
|
||||
- Type of project (app, website, feature, page)
|
||||
- Target platform (web, mobile, both)
|
||||
- Key functionality or purpose
|
||||
</action>
|
||||
|
||||
<action>If unclear, ask one clarifying question</action>
|
||||
|
||||
<template-output>project_scope</template-output>
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Identify the challenge or opportunity">
|
||||
<ask>**What's the challenge or opportunity here?**
|
||||
|
||||
Why does this project exist? What problem are you solving, or what opportunity are you pursuing?</ask>
|
||||
|
||||
<action>Listen for:
|
||||
- Pain points being addressed
|
||||
- Market opportunity
|
||||
- User needs not being met
|
||||
- Business drivers
|
||||
</action>
|
||||
|
||||
<action>Reflect back what you heard to confirm understanding</action>
|
||||
|
||||
<template-output>challenge_opportunity</template-output>
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Define design goals">
|
||||
<ask>**What should the design achieve?**
|
||||
|
||||
When this design is complete, what will make it successful? What experience do you want users to have?</ask>
|
||||
|
||||
<action>Listen for:
|
||||
- Functional goals (what it should do)
|
||||
- Experience goals (how it should feel)
|
||||
- Business goals (what outcomes matter)
|
||||
</action>
|
||||
|
||||
<action>Help refine vague goals into specific, actionable ones</action>
|
||||
|
||||
<template-output>design_goals</template-output>
|
||||
</step>
|
||||
|
||||
<step n="5" goal="Capture constraints">
|
||||
<ask>**Any constraints I should know about?**
|
||||
|
||||
Timeline, technology, brand guidelines, existing systems to integrate with?</ask>
|
||||
|
||||
<action>Note:
|
||||
- Technical constraints
|
||||
- Timeline/deadline
|
||||
- Budget considerations
|
||||
- Brand/style requirements
|
||||
- Integration requirements
|
||||
</action>
|
||||
|
||||
<action>It's okay if there are few constraints - note "flexible" where appropriate</action>
|
||||
|
||||
<template-output>constraints</template-output>
|
||||
</step>
|
||||
|
||||
<step n="6" goal="Summarize and create brief">
|
||||
<output>Here's what I captured:
|
||||
|
||||
**Project Scope**
|
||||
{{project_scope}}
|
||||
|
||||
**Challenge/Opportunity**
|
||||
{{challenge_opportunity}}
|
||||
|
||||
**Design Goals**
|
||||
{{design_goals}}
|
||||
|
||||
**Constraints**
|
||||
{{constraints}}
|
||||
</output>
|
||||
|
||||
<ask>Does this capture the essentials? Anything to add or adjust?</ask>
|
||||
|
||||
<action>Make any requested adjustments</action>
|
||||
|
||||
<action>Generate simplified-brief.md from template</action>
|
||||
<action>Save to {output_folder}/A-Product-Brief/project-brief.md</action>
|
||||
|
||||
<output>✅ **Simplified Project Brief saved!**
|
||||
|
||||
Location: `A-Product-Brief/project-brief.md`
|
||||
|
||||
You now have enough context to move forward. When you're ready:
|
||||
- **Next phase:** Check your workflow status for what's next
|
||||
- **Need more depth?** You can always expand this into a Complete brief later
|
||||
|
||||
Happy designing! 🎨</output>
|
||||
</step>
|
||||
|
||||
</workflow>
|
||||
|
||||
|
|
@ -0,0 +1,45 @@
|
|||
# Project Brief: {{project_name}}
|
||||
|
||||
> Simplified Brief - Essential context for design work
|
||||
|
||||
**Created:** {{date}}
|
||||
**Author:** {{user_name}}
|
||||
**Brief Type:** Simplified
|
||||
|
||||
---
|
||||
|
||||
## Project Scope
|
||||
|
||||
{{project_scope}}
|
||||
|
||||
---
|
||||
|
||||
## Challenge / Opportunity
|
||||
|
||||
{{challenge_opportunity}}
|
||||
|
||||
---
|
||||
|
||||
## Design Goals
|
||||
|
||||
{{design_goals}}
|
||||
|
||||
---
|
||||
|
||||
## Constraints
|
||||
|
||||
{{constraints}}
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
This simplified brief provides essential context for design work. The following phases can now proceed:
|
||||
|
||||
- [ ] **Phase 4: UX Design** - Begin sketching and specifications
|
||||
- [ ] **Phase 5: Design System** - If enabled, build components alongside design
|
||||
|
||||
---
|
||||
|
||||
*Generated by Whiteport Design Studio*
|
||||
|
||||
|
|
@ -0,0 +1,45 @@
|
|||
---
|
||||
name: Product Brief Workflow
|
||||
description: Establish project context - foundation for all design work
|
||||
web_bundle: true
|
||||
---
|
||||
|
||||
# WDS Phase 1: Project Brief
|
||||
name: project-brief
|
||||
author: "Whiteport Design Studio"
|
||||
phase: 1
|
||||
|
||||
# Critical variables from config
|
||||
config_source: "{project-root}/{bmad_folder}/wds/config.yaml"
|
||||
output_folder: "{config_source}:output_folder"
|
||||
user_name: "{config_source}:user_name"
|
||||
project_name: "{config_source}:project_name"
|
||||
communication_language: "{config_source}:communication_language"
|
||||
document_output_language: "{config_source}:document_output_language"
|
||||
date: system-generated
|
||||
|
||||
# Brief level from workflow status
|
||||
brief_level: "{output_folder}/wds-workflow-status.yaml:config.brief_level"
|
||||
|
||||
# Workflow components
|
||||
installed_path: "{project-root}/{bmad_folder}/wds/workflows/1-project-brief"
|
||||
|
||||
# Route to appropriate workflow based on brief_level
|
||||
workflows:
|
||||
simplified:
|
||||
instructions: "{installed_path}/simplified/instructions.md"
|
||||
template: "{installed_path}/simplified/simplified-brief.template.md"
|
||||
complete:
|
||||
instructions: "{installed_path}/complete/workflow.md"
|
||||
template: "{installed_path}/complete/project-brief.template.md"
|
||||
steps: "{installed_path}/complete/steps"
|
||||
|
||||
# Output configuration
|
||||
output_file: "{output_folder}/A-Product-Brief/project-brief.md"
|
||||
|
||||
# Agent assignment
|
||||
primary_agent: "saga-analyst"
|
||||
|
||||
standalone: true
|
||||
web_bundle: false
|
||||
|
||||
|
|
@ -0,0 +1,108 @@
|
|||
# Trigger Mapping - Overview Instructions
|
||||
|
||||
<critical>Communicate in {communication_language} with {user_name}</critical>
|
||||
<critical>You are Saga the Analyst - facilitator of strategic clarity</critical>
|
||||
|
||||
<workflow>
|
||||
|
||||
<step n="1" goal="Welcome and explain Trigger Mapping">
|
||||
<output>Hi {user_name}! I'm Saga, and I'll facilitate your **Trigger Mapping** session.
|
||||
|
||||
Trigger Mapping connects your business goals to user psychology. It answers:
|
||||
- **Why** will users engage with your product?
|
||||
- **What** motivates them (positive drivers)?
|
||||
- **What** do they want to avoid (negative drivers)?
|
||||
- **Which** features matter most?
|
||||
|
||||
We'll work through 5 focused workshops:
|
||||
|
||||
1. **Business Goals** - Vision → SMART objectives
|
||||
2. **Target Groups** - Who are your key users?
|
||||
3. **Driving Forces** - What motivates and concerns them?
|
||||
4. **Prioritization** - What matters most?
|
||||
5. **Feature Impact** - Which features serve top priorities?
|
||||
|
||||
Each workshop builds on the previous. You can run them all together (60-90 min) or spread across sessions.
|
||||
|
||||
Ready to begin? 🎯</output>
|
||||
|
||||
<ask>Would you like to:
|
||||
1. **Full session** - All 5 workshops now
|
||||
2. **Workshop by workshop** - Start with Business Goals, continue later
|
||||
3. **Jump to specific workshop** - If you've done some already</ask>
|
||||
|
||||
<check if="choice == 1">
|
||||
<action>Proceed through all workshops sequentially</action>
|
||||
</check>
|
||||
|
||||
<check if="choice == 2">
|
||||
<action>Run Workshop 1, then offer to save and continue later</action>
|
||||
</check>
|
||||
|
||||
<check if="choice == 3">
|
||||
<ask>Which workshop?
|
||||
1. Business Goals
|
||||
2. Target Groups
|
||||
3. Driving Forces
|
||||
4. Prioritization
|
||||
5. Feature Impact</ask>
|
||||
<action>Jump to selected workshop</action>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Run Workshop 1: Business Goals">
|
||||
<action>Load and execute: workshops/1-business-goals/instructions.md</action>
|
||||
<action>Store outputs: vision, objectives</action>
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Run Workshop 2: Target Groups">
|
||||
<action>Load and execute: workshops/2-target-groups/instructions.md</action>
|
||||
<action>Store outputs: target_groups, personas</action>
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Run Workshop 3: Driving Forces">
|
||||
<action>Load and execute: workshops/3-driving-forces/instructions.md</action>
|
||||
<action>Store outputs: driving_forces_positive, driving_forces_negative</action>
|
||||
</step>
|
||||
|
||||
<step n="5" goal="Run Workshop 4: Prioritization">
|
||||
<action>Load and execute: workshops/4-prioritization/instructions.md</action>
|
||||
<action>Store outputs: prioritized_groups, prioritized_drivers</action>
|
||||
</step>
|
||||
|
||||
<step n="6" goal="Run Workshop 5: Feature Impact">
|
||||
<action>Load and execute: workshops/5-feature-impact/instructions.md</action>
|
||||
<action>Store outputs: feature_impact_analysis</action>
|
||||
</step>
|
||||
|
||||
<step n="7" goal="Compile Trigger Map Documents">
|
||||
<action>Generate 00-Trigger-Map-Poster.md from template</action>
|
||||
<action>Generate 01-Business-Goals.md (visions & objectives)</action>
|
||||
<action>Generate 02-Target-Groups.md (all personas with drivers)</action>
|
||||
<action>Generate 03-Feature-Impact-Analysis.md from template</action>
|
||||
<action>Save individual persona files as 04-[Name].md, 05-[Name].md, etc.</action>
|
||||
<action>Save all to {output_folder}/B-Trigger-Map/</action>
|
||||
|
||||
<output>✅ **Trigger Mapping complete!**
|
||||
|
||||
**Created:**
|
||||
- `B-Trigger-Map/00-Trigger-Map-Poster.md` - Visual overview
|
||||
- `B-Trigger-Map/01-Business-Goals.md` - Visions & objectives
|
||||
- `B-Trigger-Map/02-Target-Groups.md` - All personas with drivers
|
||||
- `B-Trigger-Map/03-Feature-Impact-Analysis.md` - Prioritized features
|
||||
- `B-Trigger-Map/04-08-*.md` - Individual persona detail files
|
||||
|
||||
**Key Insights:**
|
||||
{{summary_of_priorities}}
|
||||
|
||||
You now have strategic clarity on:
|
||||
- What success looks like (business goals)
|
||||
- Who to focus on (target groups)
|
||||
- What drives them (positive & negative forces)
|
||||
- Which features matter most (impact analysis)
|
||||
|
||||
Ready for the next phase! 🚀</output>
|
||||
</step>
|
||||
|
||||
</workflow>
|
||||
|
||||
|
|
@ -0,0 +1,46 @@
|
|||
# Feature Impact Analysis: {{project_name}}
|
||||
|
||||
> **Status: Beta** - Scoring system being refined through real-world use
|
||||
|
||||
## Scoring
|
||||
|
||||
**Primary Persona (⭐):** High = 5 pts | Medium = 3 pts | Low = 1 pt
|
||||
**Other Personas:** High = 3 pts | Medium = 1 pt | Low = 0 pts
|
||||
|
||||
**Max Possible Score:** {{max_score}} (with {{persona_count}} personas)
|
||||
**Must Have Threshold:** {{must_have_threshold}}+ or Primary High (5)
|
||||
|
||||
---
|
||||
|
||||
## Prioritized Features
|
||||
|
||||
| Rank | Feature | Score | Decision |
|
||||
|------|---------|-------|----------|
|
||||
{{#each sorted_features}}
|
||||
| {{this.rank}} | {{this.name}} | {{this.score}} | {{this.decision}} |
|
||||
{{/each}}
|
||||
|
||||
---
|
||||
|
||||
## Decisions
|
||||
|
||||
**Must Have MVP (Primary High OR Top Tier Score):**
|
||||
{{#each must_have}}
|
||||
- {{this.name}} ({{this.score}})
|
||||
{{/each}}
|
||||
|
||||
**Consider for MVP:**
|
||||
{{#each consider}}
|
||||
- {{this.name}} ({{this.score}})
|
||||
{{/each}}
|
||||
|
||||
**Defer (Nice-to-Have or Low Strategic Value):**
|
||||
{{#each defer}}
|
||||
- {{this.name}} ({{this.score}})
|
||||
{{/each}}
|
||||
|
||||
---
|
||||
|
||||
*Generated by Whiteport Design Studio*
|
||||
*Strategic input for Phase 4: UX Design and Phase 6: PRD/Development*
|
||||
*Beta methodology - feedback welcome*
|
||||
|
|
@ -0,0 +1,136 @@
|
|||
# Trigger Map Poster: {{project_name}}
|
||||
|
||||
> Visual overview connecting business goals to user psychology
|
||||
|
||||
**Created:** {{date}}
|
||||
**Author:** {{user_name}}
|
||||
**Methodology:** Based on Effect Mapping (Balic & Domingues), adapted by WDS
|
||||
|
||||
---
|
||||
|
||||
## Strategic Documents
|
||||
|
||||
This is the visual overview. For detailed documentation, see:
|
||||
|
||||
- **01-Business-Goals.md** - Full vision statements and SMART objectives
|
||||
- **02-Target-Groups.md** - All personas with complete driving forces
|
||||
- **03-Feature-Impact-Analysis.md** - Prioritized features with impact scores
|
||||
- **04-08-*.md** - Individual persona detail files
|
||||
|
||||
---
|
||||
|
||||
## Vision
|
||||
|
||||
{{vision_statement}}
|
||||
|
||||
---
|
||||
|
||||
## Business Objectives
|
||||
|
||||
{{#each objectives}}
|
||||
### Objective {{@index + 1}}: {{this.statement}}
|
||||
- **Metric:** {{this.metric}}
|
||||
- **Target:** {{this.target}}
|
||||
- **Timeline:** {{this.timeline}}
|
||||
{{/each}}
|
||||
|
||||
---
|
||||
|
||||
## Target Groups (Prioritized)
|
||||
|
||||
{{#each prioritized_groups}}
|
||||
### {{@index + 1}}. {{this.name}}
|
||||
**Priority Reasoning:** {{this.reasoning}}
|
||||
|
||||
> {{this.persona_summary}}
|
||||
|
||||
**Key Positive Drivers:**
|
||||
{{#each this.positive_drivers}}
|
||||
- {{this}}
|
||||
{{/each}}
|
||||
|
||||
**Key Negative Drivers:**
|
||||
{{#each this.negative_drivers}}
|
||||
- {{this}}
|
||||
{{/each}}
|
||||
|
||||
{{/each}}
|
||||
|
||||
---
|
||||
|
||||
## Trigger Map Visualization
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────┐
|
||||
│ VISION │
|
||||
│ {{vision_short}} │
|
||||
└─────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────┐
|
||||
│ OBJECTIVES │
|
||||
│ {{#each objectives_short}}• {{this}} {{/each}} │
|
||||
└─────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
┌─────────────────────────┼─────────────────────────┐
|
||||
▼ ▼ ▼
|
||||
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
|
||||
│ {{group_1}} │ │ {{group_2}} │ │ {{group_3}} │
|
||||
└───────────────┘ └───────────────┘ └───────────────┘
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
[Drivers] [Drivers] [Drivers]
|
||||
+ {{g1_pos}} + {{g2_pos}} + {{g3_pos}}
|
||||
- {{g1_neg}} - {{g2_neg}} - {{g3_neg}}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Design Focus Statement
|
||||
|
||||
{{focus_statement}}
|
||||
|
||||
**Primary Design Target:** {{top_group.name}}
|
||||
|
||||
**Must Address:**
|
||||
{{#each must_address_drivers}}
|
||||
- {{this}}
|
||||
{{/each}}
|
||||
|
||||
**Should Address:**
|
||||
{{#each should_address_drivers}}
|
||||
- {{this}}
|
||||
{{/each}}
|
||||
|
||||
---
|
||||
|
||||
## Cross-Group Patterns
|
||||
|
||||
### Shared Drivers
|
||||
{{shared_drivers}}
|
||||
|
||||
### Unique Drivers
|
||||
{{unique_drivers}}
|
||||
|
||||
{{#if conflicts}}
|
||||
### Potential Tensions
|
||||
{{conflicts}}
|
||||
{{/if}}
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
This Trigger Map Poster provides a quick reference. For detailed work:
|
||||
|
||||
- [ ] **Review detailed docs** - See 01-Business-Goals.md, 02-Target-Groups.md, 03-Feature-Impact-Analysis.md
|
||||
- [ ] **Use for Feature Prioritization** - Reference feature impact scores
|
||||
- [ ] **Guide UX Design** - Ensure designs address priority drivers
|
||||
- [ ] **Validate with Users** - Test assumptions with real target group members
|
||||
- [ ] **Update as Learnings Emerge** - This is a living document
|
||||
|
||||
---
|
||||
|
||||
*Generated by Whiteport Design Studio*
|
||||
*Trigger Mapping methodology credits: Effect Mapping by Mijo Balic & Ingrid Domingues (inUse), adapted with negative driving forces by WDS*
|
||||
|
||||
|
|
@ -0,0 +1,58 @@
|
|||
# WDS Phase 2: Trigger Mapping
|
||||
name: trigger-mapping
|
||||
description: "Map business goals to user psychology through structured workshops"
|
||||
author: "Whiteport Design Studio"
|
||||
phase: 2
|
||||
|
||||
# Based on Effect Mapping by Mijo Balic & Ingrid Domingues (inUse)
|
||||
# Adapted by WDS: simplified (no features), enhanced with negative driving forces
|
||||
|
||||
# Critical variables from config
|
||||
config_source: "{project-root}/{bmad_folder}/wds/config.yaml"
|
||||
output_folder: "{config_source}:output_folder"
|
||||
user_name: "{config_source}:user_name"
|
||||
project_name: "{config_source}:project_name"
|
||||
communication_language: "{config_source}:communication_language"
|
||||
document_output_language: "{config_source}:document_output_language"
|
||||
date: system-generated
|
||||
|
||||
# Workflow components
|
||||
installed_path: "{project-root}/{bmad_folder}/wds/workflows/2-trigger-mapping"
|
||||
instructions: "{installed_path}/instructions.md"
|
||||
|
||||
# Workshop micro-workflows
|
||||
workshops:
|
||||
business-goals:
|
||||
instructions: "{installed_path}/workshops/1-business-goals/instructions.md"
|
||||
output: "Vision and SMART objectives"
|
||||
target-groups:
|
||||
instructions: "{installed_path}/workshops/2-target-groups/instructions.md"
|
||||
output: "Personas with descriptions"
|
||||
driving-forces:
|
||||
instructions: "{installed_path}/workshops/3-driving-forces/instructions.md"
|
||||
output: "Positive and negative drivers per group"
|
||||
prioritization:
|
||||
instructions: "{installed_path}/workshops/4-prioritization/instructions.md"
|
||||
output: "Ranked groups and drivers"
|
||||
feature-impact:
|
||||
instructions: "{installed_path}/workshops/5-feature-impact/instructions.md"
|
||||
output: "Features scored against priorities"
|
||||
|
||||
# Templates
|
||||
templates:
|
||||
trigger_map: "{installed_path}/templates/trigger-map.template.md"
|
||||
feature_impact: "{installed_path}/templates/feature-impact.template.md"
|
||||
|
||||
# Output configuration
|
||||
output_folder_name: "B-Trigger-Map"
|
||||
output_files:
|
||||
- "trigger-map.md"
|
||||
- "personas/"
|
||||
- "feature-impact-analysis.md"
|
||||
|
||||
# Agent assignment
|
||||
primary_agent: "saga-analyst"
|
||||
|
||||
standalone: true
|
||||
web_bundle: false
|
||||
|
||||
|
|
@ -0,0 +1,101 @@
|
|||
# Workshop 1: Business Goals
|
||||
|
||||
<critical>You are Saga the Analyst - facilitating strategic clarity</critical>
|
||||
|
||||
<workshop>
|
||||
|
||||
<intro>
|
||||
<output>**Workshop 1: Business Goals** 🎯
|
||||
|
||||
We'll define what success looks like at two levels:
|
||||
- **Vision** - The inspiring, aspirational goal (not easily quantified)
|
||||
- **Objectives** - SMART metrics that indicate progress
|
||||
|
||||
Let's start with the dream, then make it measurable.</output>
|
||||
</intro>
|
||||
|
||||
<step n="1" goal="Capture the vision">
|
||||
<ask>**Where do you want to be?**
|
||||
|
||||
Think big. If everything goes perfectly, what position do you want to hold?
|
||||
|
||||
Examples:
|
||||
- "Be the most trusted platform for dog owners in Sweden"
|
||||
- "The go-to tool for indie designers"
|
||||
- "Make project management actually enjoyable"</ask>
|
||||
|
||||
<action>Listen for aspirational, motivating language</action>
|
||||
<action>Help refine into a clear, inspiring vision statement</action>
|
||||
|
||||
<output>**Your Vision:**
|
||||
{{vision_statement}}</output>
|
||||
|
||||
<template-output>vision_statement</template-output>
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Break down into objectives">
|
||||
<output>Now let's make this measurable. What would indicate you're achieving that vision?</output>
|
||||
|
||||
<ask>**How would you measure progress toward this vision?**
|
||||
|
||||
Think about:
|
||||
- User metrics (adoption, engagement, retention)
|
||||
- Business metrics (revenue, growth, market share)
|
||||
- Quality metrics (satisfaction, referrals, reviews)
|
||||
|
||||
What numbers would make you confident you're on track?</ask>
|
||||
|
||||
<action>For each metric mentioned, help make it SMART:
|
||||
- **S**pecific - What exactly?
|
||||
- **M**easurable - What number?
|
||||
- **A**chievable - Is this realistic?
|
||||
- **R**elevant - Does this connect to the vision?
|
||||
- **T**ime-bound - By when?
|
||||
</action>
|
||||
|
||||
<action>Aim for 3-5 clear objectives</action>
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Refine objectives">
|
||||
<output>Let me help sharpen these into SMART objectives.</output>
|
||||
|
||||
<action>For each objective, walk through:
|
||||
|
||||
Example transformation:
|
||||
- Vague: "Get influential users"
|
||||
- SMART: "Onboard 10 verified dog trainers with 1000+ followers by Q4 2026"
|
||||
|
||||
Present each refined objective for confirmation.</action>
|
||||
|
||||
<ask>Here are your refined objectives:
|
||||
|
||||
{{#each objectives}}
|
||||
**Objective {{@index + 1}}:** {{this.statement}}
|
||||
- Metric: {{this.metric}}
|
||||
- Target: {{this.target}}
|
||||
- Timeline: {{this.timeline}}
|
||||
{{/each}}
|
||||
|
||||
Do these capture what success looks like? Any adjustments?</ask>
|
||||
|
||||
<template-output>objectives</template-output>
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Summarize and close">
|
||||
<output>**Workshop 1 Complete!** ✅
|
||||
|
||||
**Vision:**
|
||||
{{vision_statement}}
|
||||
|
||||
**Objectives:**
|
||||
{{#each objectives}}
|
||||
{{@index + 1}}. {{this.statement}}
|
||||
{{/each}}
|
||||
|
||||
This gives us clear targets to work toward. Next, we'll identify who can help you achieve these goals.</output>
|
||||
|
||||
<action>Store vision_statement and objectives for next workshop</action>
|
||||
</step>
|
||||
|
||||
</workshop>
|
||||
|
||||
|
|
@ -0,0 +1,104 @@
|
|||
# Workshop 2: Target Groups
|
||||
|
||||
<critical>You are Saga the Analyst - building empathy through understanding</critical>
|
||||
|
||||
<workshop>
|
||||
|
||||
<intro>
|
||||
<output>**Workshop 2: Target Groups** 👥
|
||||
|
||||
Now we identify the people who matter most to achieving your goals.
|
||||
|
||||
We'll create:
|
||||
- A list of user groups
|
||||
- Rich descriptions (personas)
|
||||
- Understanding of their context</output>
|
||||
</intro>
|
||||
|
||||
<step n="1" goal="Identify user groups">
|
||||
<output>Looking at your objectives:
|
||||
{{#each objectives}}
|
||||
- {{this.statement}}
|
||||
{{/each}}</output>
|
||||
|
||||
<ask>**Who needs to use your product for you to achieve these goals?**
|
||||
|
||||
For your business to succeed, the product needs to be used in the intended way by real people. Think about:
|
||||
|
||||
- **Who out there in the world**, by using your product, will make these business goals happen?
|
||||
- **Primary users** - Who uses it directly and regularly?
|
||||
- **Influencers** - Who affects whether others adopt it?
|
||||
- **Decision makers** - Who chooses to buy/use it?
|
||||
|
||||
List the types of people that come to mind.</ask>
|
||||
|
||||
<action>Capture each group mentioned</action>
|
||||
<action>Ask clarifying questions to distinguish similar groups</action>
|
||||
|
||||
<template-output>target_groups_raw</template-output>
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Select focus groups">
|
||||
<output>You mentioned these groups:
|
||||
{{#each target_groups_raw}}
|
||||
- {{this}}
|
||||
{{/each}}</output>
|
||||
|
||||
<ask>**Which 2-4 groups are most critical to your success?**
|
||||
|
||||
Consider:
|
||||
- Who has the most influence on your objectives?
|
||||
- Who, if delighted, would drive the others?
|
||||
- Where is the biggest opportunity?</ask>
|
||||
|
||||
<action>Help narrow to 2-4 primary target groups</action>
|
||||
|
||||
<template-output>target_groups</template-output>
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Build personas">
|
||||
<output>Let's bring each group to life. We'll create a persona for each.</output>
|
||||
|
||||
<action>For each target group, facilitate:</action>
|
||||
|
||||
<ask>**Let's explore: {{current_group}}**
|
||||
|
||||
1. **Who are they?** (role, demographics, situation)
|
||||
2. **What's their day like?** (context, responsibilities)
|
||||
3. **What are they trying to achieve?** (goals)
|
||||
4. **What frustrates them?** (pain points)
|
||||
5. **How do they solve this problem today?** (current behavior)</ask>
|
||||
|
||||
<action>Build a narrative persona, not just bullet points</action>
|
||||
<action>Give them a name and make them feel real</action>
|
||||
|
||||
<output>**Persona: {{persona_name}}**
|
||||
|
||||
{{persona_narrative}}
|
||||
|
||||
**Goals:** {{persona_goals}}
|
||||
**Frustrations:** {{persona_frustrations}}
|
||||
**Current Solution:** {{persona_current_solution}}</output>
|
||||
|
||||
<ask>Does this feel like a real person you'd design for? Any adjustments?</ask>
|
||||
|
||||
<action>Repeat for each target group</action>
|
||||
|
||||
<template-output>personas</template-output>
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Summarize and close">
|
||||
<output>**Workshop 2 Complete!** ✅
|
||||
|
||||
**Your Target Groups:**
|
||||
{{#each personas}}
|
||||
- **{{this.name}}** - {{this.summary}}
|
||||
{{/each}}
|
||||
|
||||
These are the people we're designing for. Next, we'll explore what drives them - both toward and away from solutions.</output>
|
||||
|
||||
<action>Store target_groups and personas for next workshop</action>
|
||||
</step>
|
||||
|
||||
</workshop>
|
||||
|
||||
|
|
@ -0,0 +1,123 @@
|
|||
# Workshop 3: Driving Forces
|
||||
|
||||
<critical>You are Saga the Analyst - uncovering motivation psychology</critical>
|
||||
|
||||
<workshop>
|
||||
|
||||
<intro>
|
||||
<output>**Workshop 3: Driving Forces** ⚡
|
||||
|
||||
Now we dig into psychology. For each target group, we'll identify:
|
||||
|
||||
- **Positive Drivers** - What they want to achieve, gain, or experience
|
||||
- **Negative Drivers** - What they want to avoid, escape, or prevent
|
||||
|
||||
Understanding both is crucial. Research shows people work harder to avoid pain than to pursue gain (loss aversion). Negative drivers often reveal the strongest design opportunities.</output>
|
||||
</intro>
|
||||
|
||||
<step n="1" goal="Explain the framework">
|
||||
<output>For each persona, we'll explore:
|
||||
|
||||
**Positive Drivers** (toward motivation):
|
||||
- Aspirations and dreams
|
||||
- Desired outcomes
|
||||
- Experiences they seek
|
||||
- Status or recognition goals
|
||||
|
||||
**Negative Drivers** (away-from motivation):
|
||||
- Fears and anxieties
|
||||
- Problems they want gone
|
||||
- Frustrations they're tired of
|
||||
- Risks they want to avoid
|
||||
|
||||
The magic happens when your design addresses both.</output>
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Explore driving forces per group">
|
||||
<action>For each persona, facilitate exploration:</action>
|
||||
|
||||
<output>**Let's explore what drives {{persona.name}}**</output>
|
||||
|
||||
<ask>**Positive Drivers:**
|
||||
What does {{persona.name}} want to achieve or experience?
|
||||
|
||||
Think about:
|
||||
- What would make their day better?
|
||||
- What would they brag about to colleagues?
|
||||
- What would make them feel successful?</ask>
|
||||
|
||||
<action>Capture 3-5 positive drivers</action>
|
||||
|
||||
<ask>**Negative Drivers:**
|
||||
What does {{persona.name}} want to avoid or escape?
|
||||
|
||||
Think about:
|
||||
- What keeps them up at night?
|
||||
- What frustrations are they tired of?
|
||||
- What risks worry them?
|
||||
- What embarrassments do they want to avoid?</ask>
|
||||
|
||||
<action>Capture 3-5 negative drivers</action>
|
||||
|
||||
<output>**{{persona.name}}'s Driving Forces:**
|
||||
|
||||
✅ **Positive Drivers:**
|
||||
{{#each positive_drivers}}
|
||||
- {{this}}
|
||||
{{/each}}
|
||||
|
||||
⚠️ **Negative Drivers:**
|
||||
{{#each negative_drivers}}
|
||||
- {{this}}
|
||||
{{/each}}</output>
|
||||
|
||||
<ask>Does this capture what truly motivates {{persona.name}}? Anything to add?</ask>
|
||||
|
||||
<action>Repeat for each persona</action>
|
||||
|
||||
<template-output>driving_forces</template-output>
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Identify patterns">
|
||||
<output>Looking across all personas, I notice some patterns...</output>
|
||||
|
||||
<action>Analyze for:
|
||||
- Common drivers across groups
|
||||
- Unique drivers per group
|
||||
- Potential conflicts between groups
|
||||
</action>
|
||||
|
||||
<output>**Cross-Group Patterns:**
|
||||
|
||||
**Shared Drivers:**
|
||||
{{shared_drivers}}
|
||||
|
||||
**Unique to Specific Groups:**
|
||||
{{unique_drivers}}
|
||||
|
||||
{{#if conflicts}}
|
||||
**Potential Tensions:**
|
||||
{{conflicts}}
|
||||
{{/if}}</output>
|
||||
|
||||
<template-output>driver_patterns</template-output>
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Summarize and close">
|
||||
<output>**Workshop 3 Complete!** ✅
|
||||
|
||||
We've mapped the psychological landscape:
|
||||
|
||||
{{#each personas}}
|
||||
**{{this.name}}:**
|
||||
- Wants: {{this.top_positive_driver}}
|
||||
- Avoids: {{this.top_negative_driver}}
|
||||
{{/each}}
|
||||
|
||||
This is powerful insight. Next, we'll prioritize which groups and drivers to focus on.</output>
|
||||
|
||||
<action>Store driving_forces and patterns for next workshop</action>
|
||||
</step>
|
||||
|
||||
</workshop>
|
||||
|
||||
|
|
@ -0,0 +1,194 @@
|
|||
# Workshop 4: Prioritization
|
||||
|
||||
<critical>You are Saga the Analyst - challenging assumptions, seeking clarity</critical>
|
||||
|
||||
<workshop>
|
||||
|
||||
<intro>
|
||||
<output>**Workshop 4: Prioritization** 🎯
|
||||
|
||||
Now we make the hard choices. We'll prioritize:
|
||||
1. Business goals (visions)
|
||||
2. Objectives under each goal
|
||||
3. Target groups
|
||||
4. Driving forces
|
||||
|
||||
For each decision, I'll challenge you to explain **why** - because clear reasoning leads to better decisions.</output>
|
||||
</intro>
|
||||
|
||||
<step n="1" goal="Prioritize business goals">
|
||||
<check if="multiple visions exist">
|
||||
<output>**Let's start with your business goals.**
|
||||
|
||||
You have multiple vision areas:
|
||||
{{#each visions}}
|
||||
- {{this}}
|
||||
{{/each}}</output>
|
||||
|
||||
<ask>**Which business goal is most critical right now?**
|
||||
|
||||
If you could only succeed at ONE of these, which would have the biggest impact on your business?</ask>
|
||||
|
||||
<action>When user chooses, challenge:</action>
|
||||
|
||||
<ask>**Why is "{{chosen_vision}}" more important than "{{other_vision}}"?**
|
||||
|
||||
Help me understand your reasoning. What makes this the priority?</ask>
|
||||
|
||||
<action>Capture the reasoning - this reveals strategic thinking</action>
|
||||
|
||||
<ask>**And the second priority?** Again, tell me why.</ask>
|
||||
|
||||
<action>Build ranked list with reasoning for each</action>
|
||||
|
||||
<output>**Your Business Goal Priority:**
|
||||
{{#each prioritized_visions}}
|
||||
{{@index + 1}}. **{{this.vision}}**
|
||||
*Why:* {{this.reasoning}}
|
||||
{{/each}}</output>
|
||||
|
||||
<template-output>prioritized_visions</template-output>
|
||||
</check>
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Prioritize objectives">
|
||||
<output>**Now let's prioritize the objectives under your top goal.**
|
||||
|
||||
For "{{top_vision}}", you have these objectives:
|
||||
{{#each top_vision_objectives}}
|
||||
- {{this.statement}}
|
||||
{{/each}}</output>
|
||||
|
||||
<ask>**Which objective is most important to achieve first?**
|
||||
|
||||
Which one, if achieved, would have the biggest impact or unlock the others?</ask>
|
||||
|
||||
<action>Challenge the choice:</action>
|
||||
|
||||
<ask>**Why prioritize "{{chosen_objective}}" over "{{other_objective}}"?**
|
||||
|
||||
What's your reasoning?</ask>
|
||||
|
||||
<action>Continue ranking with reasoning</action>
|
||||
|
||||
<output>**Objective Priority for "{{top_vision}}":**
|
||||
{{#each prioritized_objectives}}
|
||||
{{@index + 1}}. {{this.statement}}
|
||||
*Why:* {{this.reasoning}}
|
||||
{{/each}}</output>
|
||||
|
||||
<template-output>prioritized_objectives</template-output>
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Prioritize target groups">
|
||||
<output>**Now let's rank who you're designing for.**
|
||||
|
||||
Your target groups:
|
||||
{{#each personas}}
|
||||
- {{this.name}}
|
||||
{{/each}}
|
||||
|
||||
Looking at your top objective: "{{top_objective}}"</output>
|
||||
|
||||
<ask>**Which group, if delighted, would have the biggest impact on achieving that objective?**</ask>
|
||||
|
||||
<action>When user chooses, challenge:</action>
|
||||
|
||||
<ask>**Why is {{chosen_group}} more important than {{other_group}} for this objective?**
|
||||
|
||||
What's the logic?</ask>
|
||||
|
||||
<action>Push for clear reasoning - this prevents "gut feel" prioritization</action>
|
||||
|
||||
<ask>**Second priority?** And why?</ask>
|
||||
|
||||
<output>**Your Target Group Priority:**
|
||||
{{#each prioritized_groups}}
|
||||
{{@index + 1}}. **{{this.name}}**
|
||||
*Why:* {{this.reasoning}}
|
||||
{{/each}}</output>
|
||||
|
||||
<ask>The top group gets most design attention. Does this ranking reflect your strategy?</ask>
|
||||
|
||||
<template-output>prioritized_groups</template-output>
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Prioritize drivers per group">
|
||||
<output>**Now let's prioritize drivers for your top groups.**</output>
|
||||
|
||||
<action>For top 2-3 groups, prioritize their drivers:</action>
|
||||
|
||||
<ask>For **{{current_group.name}}**, which drivers are most important to address?
|
||||
|
||||
Their drivers:
|
||||
✅ Positive:
|
||||
{{#each current_group.positive_drivers}}
|
||||
- {{this}}
|
||||
{{/each}}
|
||||
|
||||
⚠️ Negative:
|
||||
{{#each current_group.negative_drivers}}
|
||||
- {{this}}
|
||||
{{/each}}
|
||||
|
||||
**Rank the top 3-5 drivers** this group cares most about.
|
||||
|
||||
Remember: negative drivers often have more weight (loss aversion).</ask>
|
||||
|
||||
<action>Help rank drivers with reasoning</action>
|
||||
<action>Note that negative drivers may be weighted higher</action>
|
||||
|
||||
<output>**Priority Drivers for {{current_group.name}}:**
|
||||
{{#each prioritized_drivers}}
|
||||
{{@index + 1}}. {{this.driver}} ({{this.type}}) - {{this.reasoning}}
|
||||
{{/each}}</output>
|
||||
|
||||
<template-output>prioritized_drivers</template-output>
|
||||
</step>
|
||||
|
||||
<step n="5" goal="Create focus statement">
|
||||
<output>Let's crystallize your focus.</output>
|
||||
|
||||
<action>Synthesize into a clear focus statement:</action>
|
||||
|
||||
<output>**Your Design Focus:**
|
||||
|
||||
**Primary Group:** {{top_group.name}}
|
||||
**Secondary:** {{second_group.name}}
|
||||
|
||||
**Must Address:**
|
||||
{{#each must_address_drivers}}
|
||||
- {{this}}
|
||||
{{/each}}
|
||||
|
||||
**Should Address:**
|
||||
{{#each should_address_drivers}}
|
||||
- {{this}}
|
||||
{{/each}}
|
||||
|
||||
**Could Address (if time permits):**
|
||||
{{#each could_address_drivers}}
|
||||
- {{this}}
|
||||
{{/each}}</output>
|
||||
|
||||
<ask>Does this focus feel right? This guides all feature decisions.</ask>
|
||||
|
||||
<template-output>focus_statement</template-output>
|
||||
</step>
|
||||
|
||||
<step n="6" goal="Summarize and close">
|
||||
<output>**Workshop 4 Complete!** ✅
|
||||
|
||||
**Your Strategic Focus:**
|
||||
- Design primarily for **{{top_group.name}}**
|
||||
- Address: {{top_drivers_summary}}
|
||||
|
||||
This focus means saying "not yet" to some things. That's the power of prioritization.
|
||||
|
||||
Next, we'll analyze which features best serve these priorities.</output>
|
||||
|
||||
<action>Store prioritized_groups, prioritized_drivers, focus_statement</action>
|
||||
</step>
|
||||
|
||||
</workshop>
|
||||
|
||||
|
|
@ -0,0 +1,150 @@
|
|||
# Workshop 5: Feature Impact Analysis (Beta)
|
||||
|
||||
<critical>You are Saga the Analyst - strategic facilitator</critical>
|
||||
|
||||
> **Status: Beta** - This scoring system is being refined through real-world use. Your feedback improves the methodology.
|
||||
|
||||
<workshop>
|
||||
|
||||
<intro>
|
||||
<output>**Workshop 5: Feature Impact Analysis** 📊 *(Beta)*
|
||||
|
||||
Now we create a **Design Brief** - strategic guidance for the designer on which features matter most and to whom.
|
||||
|
||||
For each feature, we'll assess impact on each persona using a simple scale:
|
||||
- **High** = Addresses major need or fear
|
||||
- **Medium** = Helpful but not critical
|
||||
- **Low** = Minimal impact
|
||||
|
||||
This creates a scored, prioritized feature list that guides:
|
||||
- **Phase 4: UX Design** - Which scenarios to design first
|
||||
- **Phase 6: PRD/Development** - Epic and story prioritization
|
||||
|
||||
This workshop is optional but highly valuable for strategic clarity.</output>
|
||||
</intro>
|
||||
|
||||
<step n="1" goal="Extract features from brief">
|
||||
<action>Silently read the project brief and extract:
|
||||
- Core product features
|
||||
- User interactions
|
||||
- Content/communication elements
|
||||
|
||||
Build feature_queue starting with key differentiators and core functionality.
|
||||
Do NOT show full list to user - present one at a time.
|
||||
Skip foundational features (auth, profiles, basic CRUD).
|
||||
</action>
|
||||
|
||||
<template-output>feature_queue</template-output>
|
||||
</step>
|
||||
|
||||
<step n="2" goal="Set up scoring document">
|
||||
<action>Create feature-impact-analysis.md in B-Trigger-Map/</action>
|
||||
|
||||
<output>I'm creating your Feature Impact Analysis document.
|
||||
|
||||
**Scoring:**
|
||||
- **Primary Persona:** High = 5 pts | Medium = 3 pts | Low = 1 pt
|
||||
- **Other Personas:** High = 3 pts | Medium = 1 pt | Low = 0 pts
|
||||
|
||||
Let's score {{feature_count}} features from your brief.</output>
|
||||
</step>
|
||||
|
||||
<step n="3" goal="Score features one by one">
|
||||
<action>For each feature in queue:</action>
|
||||
|
||||
<output>**Feature: {{current_feature}}**
|
||||
|
||||
How does this impact each persona?</output>
|
||||
|
||||
<ask>**{{primary_persona.name}}** ⭐ (Primary): High, Medium, or Low?</ask>
|
||||
<action>Record response</action>
|
||||
|
||||
<ask>**{{secondary_persona.name}}**: High, Medium, or Low?</ask>
|
||||
<action>Record response</action>
|
||||
|
||||
<ask>**{{tertiary_persona.name}}** (if exists): High, Medium, or Low?</ask>
|
||||
<action>Record response</action>
|
||||
|
||||
<action>Calculate score:
|
||||
- Primary: High=5, Medium=3, Low=1
|
||||
- Others: High=3, Medium=1, Low=0
|
||||
</action>
|
||||
|
||||
<output>✓ **{{current_feature}}** — Score: {{calculated_score}}</output>
|
||||
|
||||
<action>Add to running table in document</action>
|
||||
|
||||
<action>Every 3-4 features, offer:</action>
|
||||
|
||||
<ask>Continue with next feature, or add one you want scored?</ask>
|
||||
|
||||
<action>If user adds feature, score immediately then continue queue</action>
|
||||
|
||||
<action>Continue until queue empty or user says "that's enough"</action>
|
||||
|
||||
<template-output>feature_scores</template-output>
|
||||
</step>
|
||||
|
||||
<step n="4" goal="Generate prioritized list">
|
||||
<action>Sort features by score (high to low)</action>
|
||||
|
||||
<action>Calculate dynamic thresholds based on persona count:
|
||||
- max_possible = 5 (primary high) + 3 × (other_persona_count)
|
||||
- must_have_threshold = Features with Primary High (5) OR score ≥ (max_possible - 3)
|
||||
- consider_threshold = mid-range scores
|
||||
- defer_threshold = low scores
|
||||
</action>
|
||||
|
||||
<action>Apply decisions:
|
||||
- **Must Have:** Primary scored High (5 pts) OR score in top tier
|
||||
- **Consider:** Medium-range scores, might serve strategic needs
|
||||
- **Defer:** Low scores, minimal strategic value
|
||||
</action>
|
||||
|
||||
<output>**Scoring complete!** Here's your prioritized feature list:
|
||||
|
||||
{{#each sorted_features}}
|
||||
{{@index + 1}}. {{this.name}} — Score {{this.score}}
|
||||
{{/each}}
|
||||
|
||||
**Scoring context:**
|
||||
- Max possible score with {{persona_count}} personas: {{max_possible}}
|
||||
- Top tier (Must Have): {{must_have_threshold}}+
|
||||
- Primary critical (Must Have): Features with Primary High (5)
|
||||
|
||||
Top features strongly serve your primary persona and strategic goals.</output>
|
||||
|
||||
<template-output>prioritized_features</template-output>
|
||||
</step>
|
||||
|
||||
<step n="5" goal="Finalize document">
|
||||
<action>Complete feature-impact-analysis.md with:
|
||||
- Scoring legend
|
||||
- Prioritized table with decisions
|
||||
- Must Have / Consider / Defer sections
|
||||
|
||||
Do NOT include analysis section - keep it clean.
|
||||
</action>
|
||||
|
||||
<output>✅ **Feature Impact Analysis complete!**
|
||||
|
||||
**Saved to:** `B-Trigger-Map/00-feature-impact-analysis.md`
|
||||
|
||||
This is your **Design Brief** - it tells the designer:
|
||||
- **What to design first** - Top-scoring features = priority scenarios
|
||||
- **Prominence in UI** - High scores = prominent placement
|
||||
- **Who to optimize for** - Which persona's needs matter most
|
||||
|
||||
**Trigger Mapping Complete!** 🎉
|
||||
|
||||
You now have:
|
||||
- Clear business priorities
|
||||
- Defined target personas with drivers
|
||||
- Strategically ranked features
|
||||
|
||||
Ready for **Phase 4: UX Design**!</output>
|
||||
|
||||
<action>Store all outputs</action>
|
||||
</step>
|
||||
|
||||
</workshop>
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,197 @@
|
|||
# Experimental Endpoints
|
||||
|
||||
**Project:** {{project_name}}
|
||||
**Date:** {{date}}
|
||||
**Phase:** 3 - PRD Platform (Technical Foundation)
|
||||
|
||||
---
|
||||
|
||||
## Purpose
|
||||
|
||||
These are early API specifications for endpoints we know we'll need. Setting them up now enables:
|
||||
- Early backend development (parallel with UX design)
|
||||
- Validation that our data model works
|
||||
- Fail-fast discovery of integration issues
|
||||
|
||||
---
|
||||
|
||||
## Endpoint Status Key
|
||||
|
||||
- **📝 Stub:** Specification only, not implemented
|
||||
- **🚧 In Progress:** Currently being built
|
||||
- **✅ Working:** Implemented and tested
|
||||
- **❌ Blocked:** Waiting on dependency or decision
|
||||
|
||||
---
|
||||
|
||||
## Authentication Endpoints
|
||||
|
||||
{{#each auth_endpoints}}
|
||||
### {{this.method}} {{this.path}}
|
||||
|
||||
**Status:** {{this.status}}
|
||||
**Purpose:** {{this.purpose}}
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{{this.request_example}}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{{this.response_example}}
|
||||
```
|
||||
|
||||
**Notes:** {{this.notes}}
|
||||
|
||||
---
|
||||
{{/each}}
|
||||
|
||||
## Core CRUD Operations
|
||||
|
||||
{{#each crud_endpoints}}
|
||||
### {{this.method}} {{this.path}}
|
||||
|
||||
**Status:** {{this.status}}
|
||||
**Purpose:** {{this.purpose}}
|
||||
**Entity:** {{this.entity}}
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{{this.request_example}}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{{this.response_example}}
|
||||
```
|
||||
|
||||
**Dependencies:** {{this.dependencies}}
|
||||
**Notes:** {{this.notes}}
|
||||
|
||||
---
|
||||
{{/each}}
|
||||
|
||||
## External Integration Endpoints
|
||||
|
||||
{{#each integration_endpoints}}
|
||||
### {{this.method}} {{this.path}}
|
||||
|
||||
**Status:** {{this.status}}
|
||||
**Purpose:** {{this.purpose}}
|
||||
**External Service:** {{this.external_service}}
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{{this.request_example}}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{{this.response_example}}
|
||||
```
|
||||
|
||||
**Validates:**
|
||||
- {{#each this.validates}}
|
||||
- {{this}}
|
||||
{{/each}}
|
||||
|
||||
**Cost per Call:** {{this.cost_per_call}}
|
||||
**Rate Limits:** {{this.rate_limits}}
|
||||
**Notes:** {{this.notes}}
|
||||
|
||||
---
|
||||
{{/each}}
|
||||
|
||||
## Business Logic Endpoints
|
||||
|
||||
{{#each logic_endpoints}}
|
||||
### {{this.method}} {{this.path}}
|
||||
|
||||
**Status:** {{this.status}}
|
||||
**Purpose:** {{this.purpose}}
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{{this.request_example}}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{{this.response_example}}
|
||||
```
|
||||
|
||||
**Business Rules:**
|
||||
{{#each this.business_rules}}
|
||||
- {{this}}
|
||||
{{/each}}
|
||||
|
||||
**Notes:** {{this.notes}}
|
||||
|
||||
---
|
||||
{{/each}}
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Standard Error Response
|
||||
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"code": "ERROR_CODE",
|
||||
"message": "Human-readable message",
|
||||
"details": {},
|
||||
"timestamp": "ISO8601 timestamp"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Common Error Codes
|
||||
|
||||
{{#each error_codes}}
|
||||
- **{{this.code}}** ({{this.http_status}}): {{this.description}}
|
||||
{{/each}}
|
||||
|
||||
---
|
||||
|
||||
## API Conventions
|
||||
|
||||
### Base URL
|
||||
```
|
||||
{{api_base_url}}
|
||||
```
|
||||
|
||||
### Authentication
|
||||
{{api_authentication_method}}
|
||||
|
||||
### Request Headers
|
||||
```
|
||||
{{api_request_headers}}
|
||||
```
|
||||
|
||||
### Response Format
|
||||
{{api_response_format}}
|
||||
|
||||
---
|
||||
|
||||
## Development Tasks
|
||||
|
||||
These endpoints are also tracked in `E-PRD-Finalization/` as handoff tasks:
|
||||
|
||||
{{#each development_tasks}}
|
||||
- [ ] **{{this.endpoint}}** - {{this.description}} (Priority: {{this.priority}})
|
||||
{{/each}}
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Backend Team:** Implement stubs for all endpoints
|
||||
2. **Frontend/Design:** Reference these specs when designing UI
|
||||
3. **Integration Testing:** Validate external service connections
|
||||
4. **Update Status:** Mark endpoints as ✅ Working when complete
|
||||
|
||||
---
|
||||
|
||||
*Phase 3 artifact for {{project_name}}*
|
||||
|
||||
|
|
@ -0,0 +1,145 @@
|
|||
# Platform Architecture
|
||||
|
||||
**Project:** {{project_name}}
|
||||
**Date:** {{date}}
|
||||
**Phase:** 3 - PRD Platform (Technical Foundation)
|
||||
|
||||
---
|
||||
|
||||
## Technology Stack
|
||||
|
||||
### Backend
|
||||
- **Framework/Language:** {{backend_framework}}
|
||||
- **Runtime:** {{backend_runtime}}
|
||||
- **Rationale:** {{backend_rationale}}
|
||||
|
||||
### Frontend
|
||||
- **Framework:** {{frontend_framework}}
|
||||
- **UI Library:** {{ui_library}}
|
||||
- **Rationale:** {{frontend_rationale}}
|
||||
|
||||
### Database
|
||||
- **Primary Database:** {{primary_database}}
|
||||
- **Type:** {{database_type}}
|
||||
- **Rationale:** {{database_rationale}}
|
||||
|
||||
{{#if secondary_database}}
|
||||
- **Secondary Database:** {{secondary_database}}
|
||||
- **Purpose:** {{secondary_purpose}}
|
||||
{{/if}}
|
||||
|
||||
---
|
||||
|
||||
## Architecture Style
|
||||
|
||||
**Approach:** {{architecture_style}}
|
||||
|
||||
{{#if architecture_style == "Monolith"}}
|
||||
- Single codebase deployment
|
||||
- Simplified development and deployment
|
||||
- {{monolith_rationale}}
|
||||
{{/if}}
|
||||
|
||||
{{#if architecture_style == "Microservices"}}
|
||||
- Service boundaries: {{service_boundaries}}
|
||||
- Communication: {{service_communication}}
|
||||
- {{microservices_rationale}}
|
||||
{{/if}}
|
||||
|
||||
{{#if architecture_style == "Serverless"}}
|
||||
- Functions: {{serverless_functions}}
|
||||
- Triggers: {{serverless_triggers}}
|
||||
- {{serverless_rationale}}
|
||||
{{/if}}
|
||||
|
||||
---
|
||||
|
||||
## Infrastructure & Hosting
|
||||
|
||||
### Platform
|
||||
- **Cloud Provider:** {{cloud_provider}}
|
||||
- **Hosting Type:** {{hosting_type}}
|
||||
- **Rationale:** {{infrastructure_rationale}}
|
||||
|
||||
### Services
|
||||
{{#each infrastructure_services}}
|
||||
- **{{this.name}}:** {{this.description}}
|
||||
{{/each}}
|
||||
|
||||
---
|
||||
|
||||
## Data Model
|
||||
|
||||
### Core Entities
|
||||
|
||||
{{#each core_entities}}
|
||||
#### {{this.name}}
|
||||
|
||||
**Purpose:** {{this.purpose}}
|
||||
|
||||
**Key Fields:**
|
||||
{{#each this.fields}}
|
||||
- `{{this.name}}` ({{this.type}}) - {{this.description}}
|
||||
{{/each}}
|
||||
|
||||
**Relationships:**
|
||||
{{#each this.relationships}}
|
||||
- {{this.type}} {{this.target}} - {{this.description}}
|
||||
{{/each}}
|
||||
|
||||
{{/each}}
|
||||
|
||||
### Entity Relationship Diagram
|
||||
|
||||
```
|
||||
{{entity_diagram}}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Performance Requirements
|
||||
|
||||
- **Response Time:** {{response_time_target}}
|
||||
- **Concurrent Users:** {{concurrent_users_target}}
|
||||
- **Availability:** {{availability_target}}
|
||||
- **Data Volume:** {{data_volume_estimate}}
|
||||
|
||||
---
|
||||
|
||||
## Scalability Strategy
|
||||
|
||||
{{scalability_strategy}}
|
||||
|
||||
---
|
||||
|
||||
## Development Environment
|
||||
|
||||
- **Version Control:** {{version_control}}
|
||||
- **CI/CD:** {{cicd_platform}}
|
||||
- **Testing Strategy:** {{testing_strategy}}
|
||||
- **Local Development:** {{local_dev_setup}}
|
||||
|
||||
---
|
||||
|
||||
## Technical Constraints
|
||||
|
||||
{{#each technical_constraints}}
|
||||
- **{{this.area}}:** {{this.constraint}}
|
||||
{{/each}}
|
||||
|
||||
---
|
||||
|
||||
## Cost Estimates
|
||||
|
||||
### Monthly Operating Costs (Estimated)
|
||||
|
||||
{{#each cost_estimates}}
|
||||
- **{{this.service}}:** {{this.cost}} {{this.currency}}
|
||||
{{/each}}
|
||||
|
||||
**Total Estimated:** {{total_monthly_cost}} {{currency}}/month
|
||||
|
||||
---
|
||||
|
||||
*Phase 3 artifact for {{project_name}}*
|
||||
|
||||
|
|
@ -0,0 +1,173 @@
|
|||
# Technical Constraints Document
|
||||
|
||||
**Project:** {{project_name}}
|
||||
**Date:** {{date}}
|
||||
**Audience:** UX Design Team
|
||||
**Phase:** 3 → 4 Handoff
|
||||
|
||||
---
|
||||
|
||||
## Purpose
|
||||
|
||||
This document summarizes technical decisions and constraints that inform UX design work. It answers: "What do designers need to know about what's technically possible, expensive, or constrained?"
|
||||
|
||||
---
|
||||
|
||||
## ✅ What's Possible
|
||||
|
||||
### Validated Features
|
||||
|
||||
{{#each validated_features}}
|
||||
#### {{this.feature_name}}
|
||||
|
||||
**Status:** {{this.status}}
|
||||
**What Works:** {{this.what_works}}
|
||||
**Design Implications:** {{this.design_implications}}
|
||||
|
||||
{{/each}}
|
||||
|
||||
### Platform Capabilities
|
||||
|
||||
{{#each platform_capabilities}}
|
||||
- **{{this.capability}}:** {{this.description}}
|
||||
{{/each}}
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ What Has Limitations
|
||||
|
||||
### Technical Limitations
|
||||
|
||||
{{#each limitations}}
|
||||
#### {{this.area}}
|
||||
|
||||
**Constraint:** {{this.constraint}}
|
||||
**Why It Matters:** {{this.impact}}
|
||||
**Design Guidance:** {{this.design_guidance}}
|
||||
|
||||
{{/each}}
|
||||
|
||||
### External API Constraints
|
||||
|
||||
{{#each api_constraints}}
|
||||
- **{{this.service}}:** {{this.constraint}} - {{this.design_impact}}
|
||||
{{/each}}
|
||||
|
||||
---
|
||||
|
||||
## ⏱️ What Affects Timing
|
||||
|
||||
### Performance Characteristics
|
||||
|
||||
{{#each performance_characteristics}}
|
||||
#### {{this.operation}}
|
||||
|
||||
- **Expected Time:** {{this.time}}
|
||||
- **Design Need:** {{this.design_need}}
|
||||
- **UX Pattern:** {{this.ux_pattern}}
|
||||
|
||||
{{/each}}
|
||||
|
||||
### Connection Requirements
|
||||
|
||||
{{#each connection_requirements}}
|
||||
- **{{this.feature}}:** {{this.requirement}} - {{this.design_impact}}
|
||||
{{/each}}
|
||||
|
||||
---
|
||||
|
||||
## 💰 What's Expensive
|
||||
|
||||
### Cost-Sensitive Features
|
||||
|
||||
{{#each expensive_features}}
|
||||
#### {{this.feature}}
|
||||
|
||||
**Cost Driver:** {{this.cost_driver}}
|
||||
**Per-Use Cost:** {{this.per_use_cost}}
|
||||
**Design Guidance:** {{this.design_guidance}}
|
||||
|
||||
{{/each}}
|
||||
|
||||
---
|
||||
|
||||
## 🌐 Platform Compatibility
|
||||
|
||||
### Browser Support
|
||||
{{browser_support}}
|
||||
|
||||
### Device Support
|
||||
{{device_support}}
|
||||
|
||||
### Accessibility
|
||||
{{accessibility_considerations}}
|
||||
|
||||
---
|
||||
|
||||
## 🔒 Security Constraints
|
||||
|
||||
### Authentication
|
||||
{{authentication_constraints}}
|
||||
|
||||
### Data Handling
|
||||
{{data_handling_constraints}}
|
||||
|
||||
### Compliance
|
||||
{{compliance_constraints}}
|
||||
|
||||
---
|
||||
|
||||
## 📱 Offline Behavior
|
||||
|
||||
{{#if offline_support}}
|
||||
### What Works Offline
|
||||
{{offline_capabilities}}
|
||||
|
||||
### What Requires Connection
|
||||
{{online_requirements}}
|
||||
|
||||
### Sync Strategy
|
||||
{{sync_strategy}}
|
||||
{{else}}
|
||||
**Offline Mode:** Not supported - All features require active connection
|
||||
{{/if}}
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Design Recommendations
|
||||
|
||||
Based on technical validation:
|
||||
|
||||
{{#each design_recommendations}}
|
||||
### {{this.category}}
|
||||
|
||||
{{this.recommendation}}
|
||||
|
||||
**Rationale:** {{this.rationale}}
|
||||
|
||||
{{/each}}
|
||||
|
||||
---
|
||||
|
||||
## ❓ Questions for Design Team
|
||||
|
||||
{{#if open_questions}}
|
||||
{{#each open_questions}}
|
||||
- {{this}}
|
||||
{{/each}}
|
||||
{{else}}
|
||||
No open questions at this time.
|
||||
{{/if}}
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
- **For UX Design (Phase 4):** Use this document to inform design decisions
|
||||
- **For Development:** Technical specs are in other Phase 3 documents
|
||||
- **Updates:** This document will be updated if new constraints emerge during design
|
||||
|
||||
---
|
||||
|
||||
*Phase 3 → 4 Handoff Document for {{project_name}}*
|
||||
|
||||
|
|
@ -0,0 +1,40 @@
|
|||
---
|
||||
name: PRD Platform Workflow
|
||||
description: Establish technical foundation, validate risky features, and set up experimental endpoints
|
||||
web_bundle: true
|
||||
---
|
||||
|
||||
# WDS Phase 3: PRD Platform (Technical Foundation)
|
||||
name: "Phase 3: PRD Platform (Technical Foundation)"
|
||||
agent: "Freyja the PM"
|
||||
version: "1.0.0"
|
||||
|
||||
paths:
|
||||
- instructions.md
|
||||
|
||||
templates:
|
||||
- templates/platform-architecture.template.md
|
||||
- templates/technical-constraints.template.md
|
||||
- templates/experimental-endpoints.template.md
|
||||
|
||||
outputs:
|
||||
folder: "C-Requirements"
|
||||
artifacts:
|
||||
- "00-Platform-Architecture.md"
|
||||
- "01-Integration-Map.md"
|
||||
- "02-Technical-Proofs-Of-Concept.md"
|
||||
- "03-Security-Framework.md"
|
||||
- "04-Experimental-Endpoints.md"
|
||||
- "05-Technical-Constraints.md"
|
||||
- "06-PRD.md"
|
||||
|
||||
inputs_required:
|
||||
- "A-Product-Brief" # Phase 1 output
|
||||
- "B-Trigger-Map/03-Feature-Impact-Analysis.md" # Phase 2 output
|
||||
|
||||
optional_inputs:
|
||||
- "Development team availability for PoC work"
|
||||
- "Existing technical constraints"
|
||||
|
||||
estimated_duration: "2-4 hours (plus PoC development time)"
|
||||
|
||||
|
|
@ -0,0 +1,263 @@
|
|||
# Phase 4 Workflow Architecture Summary
|
||||
|
||||
**Version:** v6 with Intelligent Object Analysis
|
||||
**Date:** December 4, 2025
|
||||
|
||||
---
|
||||
|
||||
## Complete Structure
|
||||
|
||||
```
|
||||
4-ux-design/
|
||||
├── workflow.yaml # v6 workflow config
|
||||
├── workflow.md # v6 initialization with step-file architecture
|
||||
│
|
||||
├── steps/ # Main workflow steps (5 steps)
|
||||
│ ├── step-01-init.md # Welcome & determine what to design
|
||||
│ ├── step-02-define-scenario.md # Create scenario structure
|
||||
│ ├── step-03-design-page.md # Orchestrate 4A-4E for each page
|
||||
│ ├── step-04-complete-scenario.md # Celebrate completion
|
||||
│ └── step-05-next-steps.md # Guide to next actions
|
||||
│
|
||||
├── substeps/ # Page design substeps
|
||||
│ ├── 4a-exploration.md # [Optional] Concept exploration
|
||||
│ ├── 4b-sketch-analysis.md # [Optional] Systematic sketch analysis
|
||||
│ │ # • Top-to-bottom, left-to-right
|
||||
│ │ # • Section-by-section
|
||||
│ │ # • Component reuse detection
|
||||
│ │
|
||||
│ ├── 4c-01-page-basics.md # Page fundamentals
|
||||
│ ├── 4c-02-layout-sections.md # Define sections
|
||||
│ ├── 4c-03-components-objects.md # Route to object-type files
|
||||
│ │ # • For each section
|
||||
│ │ # • For each object (top-left to bottom-right)
|
||||
│ │ # • Uses object-router.md
|
||||
│ ├── 4c-04-content-languages.md # Multilingual content
|
||||
│ ├── 4c-05-interactions.md # Interaction behaviors
|
||||
│ ├── 4c-06-states.md # All states (page & component)
|
||||
│ ├── 4c-07-validation.md # Validation rules & errors
|
||||
│ ├── 4c-08-generate-spec.md # Compile final document
|
||||
│ │
|
||||
│ ├── 4d-prototype.md # [Optional] HTML prototype
|
||||
│ └── 4e-prd-update.md # [Required] Extract requirements
|
||||
│
|
||||
├── object-types/ # Object-specific instructions
|
||||
│ ├── object-router.md # 🆕 INTELLIGENT ROUTER
|
||||
│ │ # • Analyzes object
|
||||
│ │ # • Suggests interpretation
|
||||
│ │ # • User confirms
|
||||
│ │ # • Routes to appropriate file
|
||||
│ │
|
||||
│ ├── button.md # Complete button documentation
|
||||
│ ├── text-input.md # Complete input documentation
|
||||
│ ├── link.md # Complete link documentation
|
||||
│ ├── heading-text.md # Complete text documentation
|
||||
│ ├── image.md # Complete image documentation
|
||||
│ │
|
||||
│ └── [16 more object types to create] # Each with precise examples
|
||||
│ • textarea.md
|
||||
│ • select-dropdown.md
|
||||
│ • checkbox.md
|
||||
│ • radio-button.md
|
||||
│ • toggle-switch.md
|
||||
│ • card.md
|
||||
│ • modal-dialog.md
|
||||
│ • table.md
|
||||
│ • list.md
|
||||
│ • navigation.md
|
||||
│ • badge.md
|
||||
│ • alert-toast.md
|
||||
│ • progress.md
|
||||
│ • video.md
|
||||
│ • custom-component.md
|
||||
│
|
||||
└── templates/ # Document templates
|
||||
├── page-specification.template.md # Complete page spec format
|
||||
└── scenario-overview.template.md # Scenario structure format
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Innovations
|
||||
|
||||
### 1. Step-File Architecture ✅
|
||||
- **Just-in-time loading** - Only current step in memory
|
||||
- **Sequential enforcement** - Steps load one at a time
|
||||
- **Clear progression** - 5 main steps → substeps → object-types
|
||||
- **State tracking** - Progress saved between sessions
|
||||
|
||||
### 2. Granular Specification (8 Micro-Steps) ✅
|
||||
Instead of one large 4C step, broke into focused substeps:
|
||||
1. **Page Basics** - Fundamentals
|
||||
2. **Layout Sections** - Structure
|
||||
3. **Components & Objects** - Systematic identification
|
||||
4. **Content & Languages** - Multilingual
|
||||
5. **Interactions** - Behaviors
|
||||
6. **States** - All possibilities
|
||||
7. **Validation** - Rules & errors
|
||||
8. **Generate Spec** - Compile document
|
||||
|
||||
### 3. Object-Type Routing System ✅
|
||||
- **21 specialized object-type files** (6 created, 15 to create)
|
||||
- **Each file has precise examples** for consistency
|
||||
- **Ensures uniform output** across all WDS projects
|
||||
|
||||
### 4. Intelligent Analysis (Trust-the-Agent) ✅✨
|
||||
|
||||
**Old Approach (Procedural):**
|
||||
```
|
||||
What type of object is this?
|
||||
1. Button
|
||||
2. Input
|
||||
3. Link
|
||||
[Choose from list]
|
||||
```
|
||||
|
||||
**New Approach (Intelligent):**
|
||||
```
|
||||
My interpretation:
|
||||
|
||||
This looks like a PRIMARY BUTTON.
|
||||
|
||||
Based on what I see:
|
||||
- Prominent placement at bottom of form
|
||||
- Bright blue background (primary color)
|
||||
- White text saying "Save Profile"
|
||||
|
||||
I think this "Save Profile Button":
|
||||
- Saves the form data to the database
|
||||
- Updates the user's profile information
|
||||
- Shows loading state during save
|
||||
|
||||
Does this match your intent? [Y/Clarify/No]
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- ✅ Agent demonstrates intelligence
|
||||
- ✅ Context-aware interpretation
|
||||
- ✅ Natural conversation
|
||||
- ✅ Quick confirmation when correct
|
||||
- ✅ v6 "goal-based trust" philosophy
|
||||
|
||||
### 5. Systematic Sketch Analysis ✅
|
||||
- **Top-to-bottom, left-to-right** within sections
|
||||
- **Component reuse detection** across pages
|
||||
- **Section-by-section** organization
|
||||
- **Prevents missing elements**
|
||||
|
||||
---
|
||||
|
||||
## Workflow Flow
|
||||
|
||||
```
|
||||
Step 1: Init
|
||||
↓
|
||||
Step 2: Define Scenario
|
||||
↓
|
||||
Step 3: Design Page (LOOPS for each page)
|
||||
↓
|
||||
4A: Exploration (optional)
|
||||
↓
|
||||
4B: Sketch Analysis (optional)
|
||||
• Top-left to bottom-right
|
||||
• Section by section
|
||||
• Check for reusable components
|
||||
↓
|
||||
4C: Specification (required) - 8 SUBSTEPS
|
||||
↓
|
||||
4C-01: Page Basics
|
||||
4C-02: Layout Sections
|
||||
4C-03: Components & Objects
|
||||
↓
|
||||
FOR EACH SECTION:
|
||||
FOR EACH OBJECT (top-left to bottom-right):
|
||||
↓
|
||||
object-router.md
|
||||
• Analyzes object intelligently
|
||||
• Suggests interpretation
|
||||
• User confirms
|
||||
• Routes to object-type file
|
||||
↓
|
||||
button.md / text-input.md / link.md / etc.
|
||||
• Precise documentation
|
||||
• Complete examples
|
||||
• Consistent format
|
||||
↓
|
||||
Returns to 4C-03
|
||||
NEXT OBJECT
|
||||
NEXT SECTION
|
||||
↓
|
||||
4C-04: Content & Languages
|
||||
4C-05: Interactions
|
||||
4C-06: States
|
||||
4C-07: Validation
|
||||
4C-08: Generate Spec
|
||||
↓
|
||||
4D: Prototype (optional)
|
||||
↓
|
||||
4E: PRD Update (required)
|
||||
↓
|
||||
NEXT PAGE or Step 4
|
||||
↓
|
||||
Step 4: Complete Scenario
|
||||
↓
|
||||
Step 5: Next Steps
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## v6 Best Practices Applied
|
||||
|
||||
✅ **Micro-file design** - Small, focused files
|
||||
✅ **Just-in-time loading** - Load only current step
|
||||
✅ **Goal-based trust** - Agent interprets intelligently
|
||||
✅ **Sequential enforcement** - No skipping steps
|
||||
✅ **State tracking** - Resume capability
|
||||
✅ **Example-driven** - Show, don't tell
|
||||
✅ **Soft language** - Collaborative, not commanding
|
||||
✅ **Object-specific instructions** - Precise, consistent
|
||||
|
||||
---
|
||||
|
||||
## Benefits for WDS Users
|
||||
|
||||
**Consistency Across Projects:**
|
||||
- Same object types documented the same way
|
||||
- Every WDS project produces uniform specs
|
||||
- Developers know what to expect
|
||||
|
||||
**Agent Clarity:**
|
||||
- Focused instructions prevent confusion
|
||||
- Clear routing eliminates ambiguity
|
||||
- Examples guide output format
|
||||
|
||||
**User Experience:**
|
||||
- Intelligent suggestions feel natural
|
||||
- Quick confirmations when agent is right
|
||||
- Systematic coverage ensures nothing missed
|
||||
|
||||
**Maintainability:**
|
||||
- Easy to add new object types
|
||||
- Each file independently improvable
|
||||
- Clear separation of concerns
|
||||
|
||||
---
|
||||
|
||||
## Status
|
||||
|
||||
**✅ Complete:**
|
||||
- Main workflow structure (5 steps)
|
||||
- All substeps (4A, 4B, 4C-01 through 4C-08, 4D, 4E)
|
||||
- Object-router with intelligent analysis
|
||||
- 6 object-type files (button, text-input, link, heading-text, image, object-router)
|
||||
- Templates
|
||||
|
||||
**⏳ To Create:**
|
||||
- 15 additional object-type files
|
||||
- Object-type files should follow same pattern with precise examples
|
||||
|
||||
---
|
||||
|
||||
**This architecture ensures consistent, high-quality specifications across all WDS projects while making the agent experience intelligent and natural.** 🎨✨
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,685 @@
|
|||
# Component File Structure
|
||||
|
||||
**Modular Organization for Complex Components**
|
||||
|
||||
---
|
||||
|
||||
## Problem Statement
|
||||
|
||||
Complex components (calendars, calculators, graphs, interactive widgets) contain three distinct types of information that should be separated:
|
||||
|
||||
1. **Page Context** - Where/how component appears on specific pages
|
||||
2. **Design System** - Visual design, states, Figma specifications
|
||||
3. **Feature Logic** - Interactive behavior, business rules, data flow
|
||||
|
||||
**Current Issue:** All three are mixed in page specifications, making them hard to maintain and reuse.
|
||||
|
||||
---
|
||||
|
||||
## Proposed Structure
|
||||
|
||||
### File Organization
|
||||
|
||||
```
|
||||
project-root/
|
||||
├─ Pages/ # Page-specific context
|
||||
│ ├─ 01-start-page.md
|
||||
│ ├─ 02-calendar-page.md
|
||||
│ └─ 03-profile-page.md
|
||||
│
|
||||
├─ Components/ # Design System components
|
||||
│ ├─ navigation-bar.component.md
|
||||
│ ├─ feature-card.component.md
|
||||
│ ├─ calendar-widget.component.md
|
||||
│ └─ walk-scheduler.component.md
|
||||
│
|
||||
└─ Features/ # Interactive logic & business rules
|
||||
├─ calendar-logic.feature.md
|
||||
├─ walk-assignment.feature.md
|
||||
├─ notification-system.feature.md
|
||||
└─ user-permissions.feature.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## File Type Definitions
|
||||
|
||||
### 1. Page Files (`Pages/*.md`)
|
||||
|
||||
**Purpose:** Page-specific layout, component placement, and context
|
||||
|
||||
**Contains:**
|
||||
- Page metadata (URL, scenario, purpose)
|
||||
- Layout structure (sections, grid)
|
||||
- Component instances with page-specific config
|
||||
- Content in all languages
|
||||
- Navigation flow (entry/exit points)
|
||||
|
||||
**Does NOT contain:**
|
||||
- Component visual design (→ Components/)
|
||||
- Interactive logic (→ Features/)
|
||||
|
||||
**Example:** `02-calendar-page.md`
|
||||
```markdown
|
||||
# 02-calendar-page
|
||||
|
||||
**Scenario:** Manage Dog Care Schedule
|
||||
**URL:** `/calendar`
|
||||
|
||||
## Layout Structure
|
||||
|
||||
### Header Section
|
||||
- Component: `navigation-bar` (from Components/)
|
||||
- Position: Top, full-width
|
||||
|
||||
### Main Content
|
||||
- Component: `calendar-widget` (from Components/)
|
||||
- Position: Center, 80% width
|
||||
- Configuration:
|
||||
- View: Month
|
||||
- Start Day: Monday
|
||||
- Show: Walk assignments only
|
||||
- Feature: `calendar-logic` (from Features/)
|
||||
|
||||
### Sidebar
|
||||
- Component: `walk-scheduler` (from Components/)
|
||||
- Position: Right, 20% width
|
||||
- Feature: `walk-assignment` (from Features/)
|
||||
|
||||
## Content
|
||||
|
||||
**Page Title:**
|
||||
- EN: "Family Dog Care Calendar"
|
||||
- SE: "Familjens Hundvårdskalender"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. Component Files (`Components/*.md`)
|
||||
|
||||
**Purpose:** Visual design, states, variants, Figma specifications
|
||||
|
||||
**Contains:**
|
||||
- Component name and purpose
|
||||
- Visual specifications (colors, spacing, typography)
|
||||
- States (default, hover, active, disabled, loading, error)
|
||||
- Variants (sizes, types, themes)
|
||||
- Figma component mapping
|
||||
- Responsive behavior
|
||||
- Accessibility requirements
|
||||
|
||||
**Does NOT contain:**
|
||||
- Business logic (→ Features/)
|
||||
- Page-specific placement (→ Pages/)
|
||||
|
||||
**Example:** `calendar-widget.component.md`
|
||||
```markdown
|
||||
# Calendar Widget Component
|
||||
|
||||
**Type:** Complex Interactive Component
|
||||
**Design System ID:** `calendar-widget`
|
||||
**Figma Component:** `DS/Widgets/Calendar`
|
||||
|
||||
## Purpose
|
||||
|
||||
Displays a monthly calendar view with interactive date selection and event display.
|
||||
|
||||
## Visual Specifications
|
||||
|
||||
### Layout
|
||||
- Grid: 7 columns (days) × 5-6 rows (weeks)
|
||||
- Cell size: 48px × 48px (desktop), 40px × 40px (mobile)
|
||||
- Gap: 4px between cells
|
||||
- Padding: 16px container padding
|
||||
|
||||
### Typography
|
||||
- Month/Year header: Large Heading (24px Bold)
|
||||
- Day labels: Caption (12px Medium)
|
||||
- Date numbers: Body Text (16px Regular)
|
||||
- Event indicators: Caption (10px Regular)
|
||||
|
||||
### Colors
|
||||
- Background: `--color-surface`
|
||||
- Cell default: `--color-surface-elevated`
|
||||
- Cell hover: `--color-surface-hover`
|
||||
- Cell selected: `--color-primary`
|
||||
- Cell today: `--color-accent`
|
||||
- Cell disabled: `--color-surface-disabled`
|
||||
|
||||
## States
|
||||
|
||||
### Default State
|
||||
- All dates visible
|
||||
- Current month displayed
|
||||
- Today highlighted with accent color
|
||||
- No date selected
|
||||
|
||||
### Date Selected
|
||||
- Selected date: Primary color background
|
||||
- Date number: White text
|
||||
- Border: 2px solid primary-dark
|
||||
|
||||
### Date Hover
|
||||
- Background: Surface-hover color
|
||||
- Cursor: Pointer
|
||||
- Transition: 150ms ease
|
||||
|
||||
### Date Disabled (Past dates)
|
||||
- Background: Surface-disabled
|
||||
- Text: Gray-400
|
||||
- Cursor: Not-allowed
|
||||
- No hover effect
|
||||
|
||||
### Loading State
|
||||
- Skeleton animation on date cells
|
||||
- Month/year header visible
|
||||
- Navigation disabled
|
||||
|
||||
### With Events
|
||||
- Small dot indicator below date number
|
||||
- Dot color: Event category color
|
||||
- Max 3 dots visible per cell
|
||||
|
||||
## Variants
|
||||
|
||||
### Size Variants
|
||||
- **Large:** 56px cells (desktop default)
|
||||
- **Medium:** 48px cells (tablet)
|
||||
- **Small:** 40px cells (mobile)
|
||||
|
||||
### View Variants
|
||||
- **Month View:** Default, shows full month
|
||||
- **Week View:** Shows 7 days in row
|
||||
- **Day View:** Shows single day with hourly slots
|
||||
|
||||
## Figma Specifications
|
||||
|
||||
**Component Path:** `Design System > Widgets > Calendar`
|
||||
|
||||
**Variants to Create:**
|
||||
- Size: Large / Medium / Small
|
||||
- View: Month / Week / Day
|
||||
- State: Default / Selected / Disabled / Loading
|
||||
|
||||
**Auto-layout:** Enabled
|
||||
**Constraints:** Fill container width
|
||||
|
||||
## Responsive Behavior
|
||||
|
||||
### Mobile (< 768px)
|
||||
- Use Small variant (40px cells)
|
||||
- Stack month navigation vertically
|
||||
- Reduce padding to 12px
|
||||
|
||||
### Tablet (768px - 1024px)
|
||||
- Use Medium variant (48px cells)
|
||||
- Horizontal month navigation
|
||||
- Standard padding (16px)
|
||||
|
||||
### Desktop (> 1024px)
|
||||
- Use Large variant (56px cells)
|
||||
- Full navigation controls
|
||||
- Increased padding (20px)
|
||||
|
||||
## Accessibility
|
||||
|
||||
- **Keyboard Navigation:**
|
||||
- Arrow keys: Navigate between dates
|
||||
- Enter/Space: Select date
|
||||
- Tab: Move to month navigation
|
||||
|
||||
- **Screen Readers:**
|
||||
- ARIA label: "Calendar, {Month} {Year}"
|
||||
- Each date: "Select {Day}, {Date} {Month}"
|
||||
- Selected date: "Selected, {Day}, {Date} {Month}"
|
||||
|
||||
- **Focus Management:**
|
||||
- Visible focus ring on keyboard navigation
|
||||
- Focus trap within calendar when open
|
||||
|
||||
## Dependencies
|
||||
|
||||
- **Features:** Requires `calendar-logic.feature.md` for interaction behavior
|
||||
- **Data:** Expects events array from API
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. Feature Files (`Features/*.md`)
|
||||
|
||||
**Purpose:** Interactive logic, business rules, data flow, state management
|
||||
|
||||
**Contains:**
|
||||
- Feature name and purpose
|
||||
- User interactions and system responses
|
||||
- Business rules and validation
|
||||
- State transitions
|
||||
- Data requirements (API endpoints, data models)
|
||||
- Edge cases and error handling
|
||||
|
||||
**Does NOT contain:**
|
||||
- Visual design (→ Components/)
|
||||
- Page layout (→ Pages/)
|
||||
|
||||
**Example:** `calendar-logic.feature.md`
|
||||
```markdown
|
||||
# Calendar Logic Feature
|
||||
|
||||
**Feature ID:** `calendar-logic`
|
||||
**Type:** Interactive Widget Logic
|
||||
**Complexity:** High
|
||||
|
||||
## Purpose
|
||||
|
||||
Manages calendar interactions, date selection, event display, and navigation between months/weeks/days.
|
||||
|
||||
## User Interactions
|
||||
|
||||
### Interaction 1: Select Date
|
||||
|
||||
**Trigger:** User clicks on a date cell
|
||||
|
||||
**Flow:**
|
||||
1. User clicks date cell
|
||||
2. System validates date is not disabled
|
||||
3. System updates selected date state
|
||||
4. System triggers `onDateSelect` callback with date
|
||||
5. System highlights selected date
|
||||
6. System updates related components (e.g., event list for that date)
|
||||
|
||||
**Business Rules:**
|
||||
- Cannot select dates in the past (configurable)
|
||||
- Cannot select dates beyond 1 year in future (configurable)
|
||||
- Can only select one date at a time (single-select mode)
|
||||
- Can select date range (range-select mode, if enabled)
|
||||
|
||||
**Edge Cases:**
|
||||
- Clicking already selected date: Deselects it
|
||||
- Clicking disabled date: No action, show tooltip
|
||||
- Rapid clicking: Debounce to prevent multiple selections
|
||||
|
||||
### Interaction 2: Navigate to Next Month
|
||||
|
||||
**Trigger:** User clicks "Next Month" button
|
||||
|
||||
**Flow:**
|
||||
1. User clicks next month button
|
||||
2. System increments month by 1
|
||||
3. System fetches events for new month (if needed)
|
||||
4. System re-renders calendar with new month
|
||||
5. System clears selected date (optional, configurable)
|
||||
6. System updates month/year header
|
||||
|
||||
**Business Rules:**
|
||||
- Cannot navigate beyond max date (1 year from today)
|
||||
- Loading state shown while fetching events
|
||||
- Previous selections cleared on month change
|
||||
|
||||
### Interaction 3: View Events for Date
|
||||
|
||||
**Trigger:** User hovers over date with event indicators
|
||||
|
||||
**Flow:**
|
||||
1. User hovers over date cell with events
|
||||
2. System shows tooltip with event summary
|
||||
3. Tooltip displays: Event count, first 2 event titles
|
||||
4. User can click to see full event list
|
||||
|
||||
**Business Rules:**
|
||||
- Tooltip appears after 300ms hover
|
||||
- Max 2 events shown in tooltip
|
||||
- "And X more" shown if > 2 events
|
||||
|
||||
## State Management
|
||||
|
||||
### Component State
|
||||
|
||||
```javascript
|
||||
{
|
||||
currentMonth: Date, // Currently displayed month
|
||||
selectedDate: Date | null, // User-selected date
|
||||
viewMode: 'month' | 'week' | 'day',
|
||||
events: Event[], // Events for current view
|
||||
loading: boolean, // Loading state
|
||||
error: string | null // Error message
|
||||
}
|
||||
```
|
||||
|
||||
### State Transitions
|
||||
|
||||
**Initial State:**
|
||||
- currentMonth: Current month
|
||||
- selectedDate: null
|
||||
- viewMode: 'month'
|
||||
- events: []
|
||||
- loading: false
|
||||
- error: null
|
||||
|
||||
**On Date Select:**
|
||||
- selectedDate: clicked date
|
||||
- Trigger callback: onDateSelect(date)
|
||||
|
||||
**On Month Change:**
|
||||
- currentMonth: new month
|
||||
- selectedDate: null (if clearOnMonthChange = true)
|
||||
- loading: true
|
||||
- Fetch events for new month
|
||||
- loading: false
|
||||
|
||||
**On Error:**
|
||||
- error: error message
|
||||
- loading: false
|
||||
- Show error state in UI
|
||||
|
||||
## Data Requirements
|
||||
|
||||
### API Endpoints
|
||||
|
||||
**Get Events for Month**
|
||||
- **Method:** GET
|
||||
- **Path:** `/api/calendar/events?month={YYYY-MM}`
|
||||
- **Purpose:** Fetch all events for specified month
|
||||
- **Response:**
|
||||
```json
|
||||
{
|
||||
"events": [
|
||||
{
|
||||
"id": "evt_123",
|
||||
"date": "2024-12-15",
|
||||
"title": "Morning Walk - Max",
|
||||
"category": "walk",
|
||||
"assignedTo": "user_456"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Create Event**
|
||||
- **Method:** POST
|
||||
- **Path:** `/api/calendar/events`
|
||||
- **Purpose:** Create new calendar event
|
||||
- **Request:**
|
||||
```json
|
||||
{
|
||||
"date": "2024-12-15",
|
||||
"title": "Morning Walk",
|
||||
"category": "walk",
|
||||
"assignedTo": "user_456"
|
||||
}
|
||||
```
|
||||
|
||||
### Data Models
|
||||
|
||||
**Event Model:**
|
||||
```typescript
|
||||
interface Event {
|
||||
id: string;
|
||||
date: string; // ISO date format
|
||||
title: string;
|
||||
category: 'walk' | 'feeding' | 'vet' | 'grooming';
|
||||
assignedTo: string; // User ID
|
||||
completed: boolean;
|
||||
notes?: string;
|
||||
}
|
||||
```
|
||||
|
||||
## Validation Rules
|
||||
|
||||
| Rule | Validation | Error Message |
|
||||
|------|------------|---------------|
|
||||
| Date in past | `date < today` | "Cannot select past dates" |
|
||||
| Date too far | `date > today + 365 days` | "Cannot select dates beyond 1 year" |
|
||||
| Event title | `title.length > 0 && title.length <= 100` | "Event title required (max 100 chars)" |
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Network Error (Failed to fetch events)
|
||||
- **Trigger:** API request fails
|
||||
- **Action:** Show error state in calendar
|
||||
- **Message:** "Unable to load events. Please try again."
|
||||
- **Recovery:** Retry button
|
||||
|
||||
### Invalid Date Selection
|
||||
- **Trigger:** User attempts to select disabled date
|
||||
- **Action:** Show tooltip
|
||||
- **Message:** "This date is not available"
|
||||
- **Recovery:** Select different date
|
||||
|
||||
## Configuration Options
|
||||
|
||||
```javascript
|
||||
{
|
||||
minDate: Date | null, // Earliest selectable date
|
||||
maxDate: Date | null, // Latest selectable date
|
||||
disablePastDates: boolean, // Disable dates before today
|
||||
clearOnMonthChange: boolean, // Clear selection on month change
|
||||
selectionMode: 'single' | 'range',
|
||||
showEventIndicators: boolean, // Show dots for events
|
||||
fetchEventsOnMount: boolean, // Auto-fetch on load
|
||||
onDateSelect: (date: Date) => void,
|
||||
onMonthChange: (month: Date) => void,
|
||||
onEventClick: (event: Event) => void
|
||||
}
|
||||
```
|
||||
|
||||
## Dependencies
|
||||
|
||||
- **Component:** `calendar-widget.component.md` (visual design)
|
||||
- **Feature:** `walk-assignment.feature.md` (for creating walk events)
|
||||
- **API:** Calendar Events API
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Benefits of This Structure
|
||||
|
||||
### 1. Separation of Concerns
|
||||
|
||||
| Concern | File Type | Example |
|
||||
|---------|-----------|---------|
|
||||
| **Where** component appears | Page | `02-calendar-page.md` |
|
||||
| **How** component looks | Component | `calendar-widget.component.md` |
|
||||
| **What** component does | Feature | `calendar-logic.feature.md` |
|
||||
|
||||
### 2. Reusability
|
||||
|
||||
**Component used on multiple pages:**
|
||||
```
|
||||
Pages/02-calendar-page.md → Components/calendar-widget.component.md
|
||||
Pages/05-dashboard.md → Components/calendar-widget.component.md
|
||||
↓
|
||||
Features/calendar-logic.feature.md
|
||||
```
|
||||
|
||||
**Same component, different configurations:**
|
||||
- Calendar Page: Month view, full-width
|
||||
- Dashboard: Week view, sidebar widget
|
||||
|
||||
### 3. Team Collaboration
|
||||
|
||||
| Role | Primary Files | Secondary Files |
|
||||
|------|---------------|-----------------|
|
||||
| **UX Designer** | Components/ | Pages/ (layout) |
|
||||
| **Developer** | Features/ | Components/ (implementation) |
|
||||
| **Content Writer** | Pages/ | - |
|
||||
| **Product Manager** | Features/ (rules) | Pages/ (flow) |
|
||||
|
||||
### 4. Maintainability
|
||||
|
||||
**Change visual design:**
|
||||
- Edit: `Components/calendar-widget.component.md`
|
||||
- Impact: All pages using calendar automatically updated
|
||||
|
||||
**Change business logic:**
|
||||
- Edit: `Features/calendar-logic.feature.md`
|
||||
- Impact: All instances of calendar use new logic
|
||||
|
||||
**Change page layout:**
|
||||
- Edit: `Pages/02-calendar-page.md`
|
||||
- Impact: Only that specific page
|
||||
|
||||
---
|
||||
|
||||
## File Naming Conventions
|
||||
|
||||
### Pages
|
||||
```
|
||||
{number}-{page-name}.md
|
||||
|
||||
Examples:
|
||||
01-start-page.md
|
||||
02-calendar-page.md
|
||||
03-profile-settings.md
|
||||
```
|
||||
|
||||
### Components
|
||||
```
|
||||
{component-name}.component.md
|
||||
|
||||
Examples:
|
||||
navigation-bar.component.md
|
||||
feature-card.component.md
|
||||
calendar-widget.component.md
|
||||
walk-scheduler.component.md
|
||||
```
|
||||
|
||||
### Features
|
||||
```
|
||||
{feature-name}.feature.md
|
||||
|
||||
Examples:
|
||||
calendar-logic.feature.md
|
||||
walk-assignment.feature.md
|
||||
user-authentication.feature.md
|
||||
notification-system.feature.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Cross-Reference System
|
||||
|
||||
### In Page Files
|
||||
|
||||
Reference components and features:
|
||||
|
||||
```markdown
|
||||
### Main Content Section
|
||||
|
||||
**Component:** `calendar-widget` (→ Components/calendar-widget.component.md)
|
||||
**Feature:** `calendar-logic` (→ Features/calendar-logic.feature.md)
|
||||
**Configuration:**
|
||||
- View: Month
|
||||
- Disable past dates: true
|
||||
```
|
||||
|
||||
### In Component Files
|
||||
|
||||
Reference required features:
|
||||
|
||||
```markdown
|
||||
## Dependencies
|
||||
|
||||
- **Feature:** `calendar-logic.feature.md` (interaction behavior)
|
||||
- **Feature:** `walk-assignment.feature.md` (event creation)
|
||||
```
|
||||
|
||||
### In Feature Files
|
||||
|
||||
Reference related components:
|
||||
|
||||
```markdown
|
||||
## Dependencies
|
||||
|
||||
- **Component:** `calendar-widget.component.md` (visual implementation)
|
||||
- **API:** Calendar Events API
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Migration Strategy
|
||||
|
||||
### Phase 1: Create Structure
|
||||
1. Create `Components/` folder
|
||||
2. Create `Features/` folder
|
||||
3. Keep existing `Pages/` (or create if needed)
|
||||
|
||||
### Phase 2: Extract Components
|
||||
1. Identify reusable components in page specs
|
||||
2. Create component files with visual design only
|
||||
3. Update page files to reference components
|
||||
|
||||
### Phase 3: Extract Features
|
||||
1. Identify complex interactive logic
|
||||
2. Create feature files with business rules
|
||||
3. Update page and component files to reference features
|
||||
|
||||
### Phase 4: Refactor Existing Pages
|
||||
1. Move visual specs → Components/
|
||||
2. Move logic → Features/
|
||||
3. Keep layout & content in Pages/
|
||||
|
||||
---
|
||||
|
||||
## Example: Dog Week Calendar
|
||||
|
||||
### Before (Monolithic)
|
||||
|
||||
```
|
||||
Pages/02-calendar-page.md (500 lines)
|
||||
├─ Page layout
|
||||
├─ Calendar visual design
|
||||
├─ Calendar interaction logic
|
||||
├─ Walk scheduler visual design
|
||||
├─ Walk assignment logic
|
||||
├─ Navigation bar design
|
||||
└─ All content in all languages
|
||||
```
|
||||
|
||||
### After (Modular)
|
||||
|
||||
```
|
||||
Pages/02-calendar-page.md (100 lines)
|
||||
├─ Page layout
|
||||
├─ Component references
|
||||
├─ Feature references
|
||||
└─ Content in all languages
|
||||
|
||||
Components/calendar-widget.component.md (150 lines)
|
||||
├─ Visual specifications
|
||||
├─ States & variants
|
||||
└─ Figma mapping
|
||||
|
||||
Components/walk-scheduler.component.md (100 lines)
|
||||
├─ Visual specifications
|
||||
└─ States & variants
|
||||
|
||||
Features/calendar-logic.feature.md (200 lines)
|
||||
├─ Interaction flows
|
||||
├─ Business rules
|
||||
├─ Data requirements
|
||||
└─ Error handling
|
||||
|
||||
Features/walk-assignment.feature.md (150 lines)
|
||||
├─ Assignment logic
|
||||
├─ Validation rules
|
||||
└─ API integration
|
||||
```
|
||||
|
||||
**Result:** Easier to maintain, reuse, and collaborate!
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
**Three-tier architecture:**
|
||||
|
||||
1. **Pages/** - Layout, placement, content (WHERE)
|
||||
2. **Components/** - Visual design, states, Figma (HOW IT LOOKS)
|
||||
3. **Features/** - Logic, rules, data (WHAT IT DOES)
|
||||
|
||||
**Benefits:**
|
||||
- ✅ Clear separation of concerns
|
||||
- ✅ Reusable components across pages
|
||||
- ✅ Maintainable business logic
|
||||
- ✅ Better team collaboration
|
||||
- ✅ Aligns with BMad v6 modular philosophy
|
||||
|
|
@ -0,0 +1,482 @@
|
|||
# Content Placement Guide
|
||||
|
||||
**Where to Document Content: Page vs Component vs Feature**
|
||||
|
||||
---
|
||||
|
||||
## Quick Decision Tree
|
||||
|
||||
```
|
||||
Is this CONTENT (text, images, data)?
|
||||
│
|
||||
├─ YES → Does it vary by page context?
|
||||
│ │
|
||||
│ ├─ YES → Page File
|
||||
│ │ (e.g., "Welcome to Dog Week" on Home, "About Dog Week" on About)
|
||||
│ │
|
||||
│ └─ NO → Feature File
|
||||
│ (e.g., "Submit" button text is always the same)
|
||||
│
|
||||
└─ NO → Is this VISUAL design (colors, spacing, states)?
|
||||
│
|
||||
└─ YES → Component File
|
||||
(e.g., button is blue, 48px height, has hover state)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## The Three File Types
|
||||
|
||||
### 1. Page File (WHERE)
|
||||
|
||||
**Contains:**
|
||||
- ✅ Position & size
|
||||
- ✅ **Page-specific content** (headings, text, images that change per page)
|
||||
- ✅ **Page-specific data** (API endpoints with page context)
|
||||
- ✅ Component references
|
||||
- ✅ Feature references
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
Pages/01-home-page.md
|
||||
---
|
||||
### Hero Section
|
||||
|
||||
**Component:** `hero-banner.component.md`
|
||||
|
||||
**Position:** Top of page, full-width
|
||||
**Size:** 400px height (desktop), 300px (mobile)
|
||||
|
||||
**Page-Specific Content:**
|
||||
- Heading: "Welcome to Dog Week" / "Välkommen till Dog Week"
|
||||
- Subheading: "Coordinate your family's dog walks effortlessly"
|
||||
- Background Image: `/images/hero-home-happy-dog.jpg`
|
||||
- CTA Button Text: "Get Started" / "Kom igång"
|
||||
- CTA Button Link: → `/onboarding/start`
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. Component File (HOW IT LOOKS)
|
||||
|
||||
**Contains:**
|
||||
- ✅ Visual specifications (colors, spacing, typography)
|
||||
- ✅ States (default, hover, active, disabled, loading, error)
|
||||
- ✅ Variants (sizes, types, themes)
|
||||
- ✅ Figma component mapping
|
||||
- ✅ Responsive behavior
|
||||
- ✅ Accessibility
|
||||
- ❌ **NO content** (no text, no images, no data)
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
Components/hero-banner.component.md
|
||||
---
|
||||
# Hero Banner Component
|
||||
|
||||
**Visual Specifications:**
|
||||
- Height: 400px (desktop), 300px (mobile)
|
||||
- Layout: Centered text over background image
|
||||
- Background: Image with dark overlay (40% opacity)
|
||||
- Typography:
|
||||
- Heading: 48px Bold, white color
|
||||
- Subheading: 18px Regular, white color
|
||||
- CTA Button: Primary button style (blue background, white text)
|
||||
|
||||
**Content Slots:**
|
||||
- Heading text (configurable per page)
|
||||
- Subheading text (configurable per page)
|
||||
- Background image (configurable per page)
|
||||
- CTA button text + link (configurable per page)
|
||||
|
||||
**States:**
|
||||
- Default: Full opacity
|
||||
- Loading: Skeleton placeholder
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. Feature File (WHAT IT DOES)
|
||||
|
||||
**Contains:**
|
||||
- ✅ User interactions & system responses
|
||||
- ✅ Business rules & validation
|
||||
- ✅ State management
|
||||
- ✅ **Generic content** (content that's the same everywhere)
|
||||
- ✅ **Generic data** (API endpoints without page context)
|
||||
- ✅ Error handling
|
||||
- ✅ Configuration options
|
||||
- ❌ **NO visual design** (no colors, no spacing, no states)
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
Features/hero-cta-logic.feature.md
|
||||
---
|
||||
# Hero CTA Logic Feature
|
||||
|
||||
**User Interactions:**
|
||||
|
||||
### Click CTA Button
|
||||
1. User clicks CTA button
|
||||
2. System validates user session
|
||||
3. If logged in → Navigate to destination
|
||||
4. If not logged in → Show login modal first
|
||||
|
||||
**Generic Content:**
|
||||
- Loading text: "Loading..." / "Laddar..."
|
||||
- Error message: "Something went wrong" / "Något gick fel"
|
||||
|
||||
**API Endpoints:**
|
||||
- GET /api/user/session (check if logged in)
|
||||
|
||||
**Business Rules:**
|
||||
- CTA disabled during loading
|
||||
- CTA shows loading spinner when clicked
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Content Placement Examples
|
||||
|
||||
### Example 1: Hero Section
|
||||
|
||||
**Scenario:** Hero banner appears on multiple pages with different content
|
||||
|
||||
**Page File (Home):**
|
||||
```markdown
|
||||
**Page-Specific Content:**
|
||||
- Heading: "Welcome to Dog Week"
|
||||
- Subheading: "Coordinate your family's dog walks"
|
||||
- Background Image: `/images/hero-home.jpg`
|
||||
- CTA Text: "Get Started"
|
||||
- CTA Link: `/onboarding/start`
|
||||
```
|
||||
|
||||
**Page File (About):**
|
||||
```markdown
|
||||
**Page-Specific Content:**
|
||||
- Heading: "About Dog Week"
|
||||
- Subheading: "Our mission to simplify dog care"
|
||||
- Background Image: `/images/hero-about.jpg`
|
||||
- CTA Text: "Contact Us"
|
||||
- CTA Link: `/contact`
|
||||
```
|
||||
|
||||
**Component File:**
|
||||
```markdown
|
||||
**Visual Specifications:**
|
||||
- Height: 400px
|
||||
- Typography: 48px Bold heading, 18px Regular subheading
|
||||
- Layout: Centered text over image
|
||||
|
||||
**Content Slots:**
|
||||
- Heading (configurable)
|
||||
- Subheading (configurable)
|
||||
- Background image (configurable)
|
||||
- CTA button (configurable)
|
||||
```
|
||||
|
||||
**Feature File:**
|
||||
```markdown
|
||||
**Generic Content:**
|
||||
- Loading text: "Loading..."
|
||||
|
||||
**Interactions:**
|
||||
- Click CTA → Navigate to link
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Example 2: Search Bar
|
||||
|
||||
**Scenario:** Search bar appears on Product page and Help page with different scopes
|
||||
|
||||
**Page File (Product Catalog):**
|
||||
```markdown
|
||||
**Page-Specific Content:**
|
||||
- Placeholder: "Search products..." / "Sök produkter..."
|
||||
|
||||
**Page-Specific Data:**
|
||||
- API Endpoint: GET /api/products/search?q=:query
|
||||
- Scope: Products only
|
||||
- Result Display: Product cards grid
|
||||
```
|
||||
|
||||
**Page File (Help Center):**
|
||||
```markdown
|
||||
**Page-Specific Content:**
|
||||
- Placeholder: "Search help articles..." / "Sök hjälpartiklar..."
|
||||
|
||||
**Page-Specific Data:**
|
||||
- API Endpoint: GET /api/help/search?q=:query
|
||||
- Scope: Help articles only
|
||||
- Result Display: Article list
|
||||
```
|
||||
|
||||
**Component File:**
|
||||
```markdown
|
||||
**Visual Specifications:**
|
||||
- Height: 48px
|
||||
- Border: 1px solid gray
|
||||
- States:
|
||||
- Default: Gray border
|
||||
- Focused: Blue border
|
||||
- Loading: Spinner icon on right
|
||||
- Results: Dropdown below input
|
||||
|
||||
**Content Slots:**
|
||||
- Placeholder text (configurable per page)
|
||||
```
|
||||
|
||||
**Feature File:**
|
||||
```markdown
|
||||
**Generic Content:**
|
||||
- No results message: "No results found" / "Inga resultat"
|
||||
- Error message: "Search failed" / "Sökning misslyckades"
|
||||
|
||||
**Interactions:**
|
||||
- User types → Debounce 300ms → API call
|
||||
- Min 3 characters required
|
||||
- Max 10 results displayed
|
||||
- Keyboard navigation (arrow keys, enter, escape)
|
||||
|
||||
**Business Rules:**
|
||||
- Debounce: 300ms
|
||||
- Min characters: 3
|
||||
- Max results: 10
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Example 3: Calendar Widget
|
||||
|
||||
**Scenario:** Calendar appears only on Calendar page, shows current user's family data
|
||||
|
||||
**Page File (Calendar Page):**
|
||||
```markdown
|
||||
**Page-Specific Content:**
|
||||
- Header Format: "[Family Name]: Vecka [Week Number]"
|
||||
- SE: "Familjen Svensson: Vecka 40"
|
||||
- EN: "Svensson Family: Week 40"
|
||||
|
||||
**Page-Specific Data:**
|
||||
- Data Source: Current user's family from session
|
||||
- API Endpoint: GET /api/families/:currentFamilyId/walks?week=:weekNumber
|
||||
- Dogs Displayed: All dogs in current user's family
|
||||
- Family Members: All members in current user's family
|
||||
|
||||
**Configuration:**
|
||||
- Initial View: Current week, scrolled to today
|
||||
- Time Slots: 4 hardcoded (8-11, 12-13, 15-17, 18-20)
|
||||
```
|
||||
|
||||
**Component File:**
|
||||
```markdown
|
||||
**Visual Specifications:**
|
||||
- 6 walk states (WHITE, GRAY, ORANGE, BLUE, GREEN, RED)
|
||||
- Week circles: 7 days with quarter segments
|
||||
- Leaderboard cards: Avatar + badge + name
|
||||
|
||||
**Content Slots:**
|
||||
- Header text (configurable per page)
|
||||
- Time slot labels (configurable)
|
||||
```
|
||||
|
||||
**Feature File:**
|
||||
```markdown
|
||||
**Generic Content:**
|
||||
- Empty state: "Add a dog to start planning walks"
|
||||
- Error message: "Failed to load walks"
|
||||
- Countdown format: "32 min left" / "32 min kvar"
|
||||
- Duration format: "32 min walk" / "32 min promenad"
|
||||
|
||||
**Interactions:**
|
||||
- Book walk → GRAY state
|
||||
- Start walk → BLUE state
|
||||
- Complete walk → GREEN state
|
||||
- Miss walk → RED state
|
||||
|
||||
**Business Rules:**
|
||||
- One active walk per dog
|
||||
- Can't book if slot taken
|
||||
- Countdown starts at slot start time
|
||||
|
||||
**API Endpoints:**
|
||||
- GET /api/families/:familyId/walks?week=:weekNumber
|
||||
- POST /api/walks (create booking)
|
||||
- PUT /api/walks/:walkId/start
|
||||
- PUT /api/walks/:walkId/complete
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Example 4: Submit Button
|
||||
|
||||
**Scenario:** Submit button appears on multiple forms, always says "Submit"
|
||||
|
||||
**Page File:**
|
||||
```markdown
|
||||
**Position:** Bottom of form, right-aligned
|
||||
**Size:** Full-width on mobile, auto-width on desktop
|
||||
|
||||
**Component:** `button-primary.component.md`
|
||||
**Feature:** `form-submit-logic.feature.md`
|
||||
|
||||
(No page-specific content - button text is always "Submit")
|
||||
```
|
||||
|
||||
**Component File:**
|
||||
```markdown
|
||||
**Visual Specifications:**
|
||||
- Background: Blue (#3B82F6)
|
||||
- Text: White, 16px Medium
|
||||
- Height: 48px
|
||||
- Border Radius: 8px
|
||||
- States:
|
||||
- Default: Blue background
|
||||
- Hover: Darker blue
|
||||
- Active: Even darker blue
|
||||
- Disabled: Gray background
|
||||
- Loading: Blue background + spinner
|
||||
```
|
||||
|
||||
**Feature File:**
|
||||
```markdown
|
||||
**Generic Content:**
|
||||
- Button text: "Submit" / "Skicka"
|
||||
- Loading text: "Submitting..." / "Skickar..."
|
||||
- Success message: "Submitted successfully" / "Skickat"
|
||||
- Error message: "Submission failed" / "Misslyckades"
|
||||
|
||||
**Interactions:**
|
||||
- Click → Validate form
|
||||
- If valid → Submit to API
|
||||
- If invalid → Show validation errors
|
||||
- Show loading state during submission
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Decision Matrix
|
||||
|
||||
| Content Type | Page-Specific? | Where to Document |
|
||||
|--------------|----------------|-------------------|
|
||||
| **Hero heading** | ✅ YES (different per page) | Page File |
|
||||
| **Hero background image** | ✅ YES (different per page) | Page File |
|
||||
| **Search placeholder** | ✅ YES (different per page) | Page File |
|
||||
| **Calendar header** | ✅ YES (shows user's family name) | Page File |
|
||||
| **API endpoint with user context** | ✅ YES (varies by user/page) | Page File |
|
||||
| **Submit button text** | ❌ NO (always "Submit") | Feature File |
|
||||
| **Error messages** | ❌ NO (generic validation) | Feature File |
|
||||
| **Loading text** | ❌ NO (always "Loading...") | Feature File |
|
||||
| **Tooltip text** | ❌ NO (generic interaction) | Feature File |
|
||||
| **API endpoint (generic)** | ❌ NO (same for all users) | Feature File |
|
||||
| **Button color** | ❌ NO (visual design) | Component File |
|
||||
| **Font size** | ❌ NO (visual design) | Component File |
|
||||
| **Hover state** | ❌ NO (visual design) | Component File |
|
||||
| **Layout spacing** | ❌ NO (visual design) | Component File |
|
||||
|
||||
---
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
### ❌ Mistake 1: Putting page-specific content in Feature file
|
||||
|
||||
**Wrong:**
|
||||
```markdown
|
||||
Features/hero-logic.feature.md
|
||||
---
|
||||
**Content:**
|
||||
- Heading: "Welcome to Dog Week" (Home page)
|
||||
- Heading: "About Dog Week" (About page)
|
||||
```
|
||||
|
||||
**Right:**
|
||||
```markdown
|
||||
Pages/01-home-page.md
|
||||
---
|
||||
**Page-Specific Content:**
|
||||
- Heading: "Welcome to Dog Week"
|
||||
|
||||
Pages/02-about-page.md
|
||||
---
|
||||
**Page-Specific Content:**
|
||||
- Heading: "About Dog Week"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### ❌ Mistake 2: Putting generic content in Page file
|
||||
|
||||
**Wrong:**
|
||||
```markdown
|
||||
Pages/01-home-page.md
|
||||
---
|
||||
**Content:**
|
||||
- Submit button: "Submit"
|
||||
- Error message: "Invalid email"
|
||||
```
|
||||
|
||||
**Right:**
|
||||
```markdown
|
||||
Features/form-submit-logic.feature.md
|
||||
---
|
||||
**Generic Content:**
|
||||
- Submit button: "Submit"
|
||||
- Error message: "Invalid email"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### ❌ Mistake 3: Putting visual design in Feature file
|
||||
|
||||
**Wrong:**
|
||||
```markdown
|
||||
Features/button-logic.feature.md
|
||||
---
|
||||
**Visual:**
|
||||
- Background: Blue
|
||||
- Height: 48px
|
||||
- Hover: Darker blue
|
||||
```
|
||||
|
||||
**Right:**
|
||||
```markdown
|
||||
Components/button-primary.component.md
|
||||
---
|
||||
**Visual Specifications:**
|
||||
- Background: Blue (#3B82F6)
|
||||
- Height: 48px
|
||||
- States:
|
||||
- Hover: Darker blue (#2563EB)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
**Content Placement Rule:**
|
||||
|
||||
```
|
||||
Does content vary by page context?
|
||||
├─ YES → Page File
|
||||
│ (Hero heading, search placeholder, user-specific data)
|
||||
│
|
||||
└─ NO → Feature File
|
||||
(Button text, error messages, generic tooltips)
|
||||
|
||||
Is this visual design?
|
||||
└─ YES → Component File
|
||||
(Colors, spacing, states, typography)
|
||||
```
|
||||
|
||||
**Key Principle:**
|
||||
- **Page File** = WHERE + WHAT (page-specific)
|
||||
- **Component File** = HOW IT LOOKS (visual design)
|
||||
- **Feature File** = WHAT IT DOES (functionality + generic content)
|
||||
|
||||
**Result:**
|
||||
- ✅ Clear separation of concerns
|
||||
- ✅ Easy to maintain and update
|
||||
- ✅ Clean handoffs to designers and developers
|
||||
- ✅ No confusion about where content belongs
|
||||
|
|
@ -0,0 +1,295 @@
|
|||
# Cross-Page Consistency Strategy
|
||||
|
||||
**Maintaining Visual Coherence Across Project Sketches**
|
||||
|
||||
---
|
||||
|
||||
## Core Principle
|
||||
|
||||
**Text that looks similar and serves the same role should have the same specification across all pages.**
|
||||
|
||||
This creates:
|
||||
- ✅ Consistent user experience
|
||||
- ✅ Natural design system patterns
|
||||
- ✅ Faster specification process
|
||||
- ✅ Professional, cohesive design
|
||||
|
||||
---
|
||||
|
||||
## Workflow: Multi-Page Projects
|
||||
|
||||
### Page 1: Start Page (Establish Baseline)
|
||||
|
||||
**First page analyzed - establish reference patterns:**
|
||||
|
||||
```
|
||||
Start Page Analysis:
|
||||
├─ Body Text: Thin lines, icon-sized spacing → 16px Regular
|
||||
├─ Button Labels: Medium lines → 16px Semibold
|
||||
├─ Page Title: Thick lines, button-height spacing → 48px Bold
|
||||
├─ Navigation: Medium lines, small spacing → 14px Medium
|
||||
└─ Caption: Thinnest lines, half-icon spacing → 12px Regular
|
||||
```
|
||||
|
||||
**These become your reference anchors for subsequent pages.**
|
||||
|
||||
---
|
||||
|
||||
### Page 2: About Page (Apply Patterns)
|
||||
|
||||
**When analyzing the About Page sketch:**
|
||||
|
||||
#### Step 1: Check Previous Pages
|
||||
```
|
||||
Agent: "I see you've already analyzed the Start Page.
|
||||
I'll use those text styles as reference points."
|
||||
```
|
||||
|
||||
#### Step 2: Match Visual Patterns
|
||||
```
|
||||
About Page body text:
|
||||
- Thin lines ✓
|
||||
- Icon-sized spacing ✓
|
||||
- Left-aligned ✓
|
||||
|
||||
→ Matches Start Page body text pattern
|
||||
→ Apply same spec: 16px Regular
|
||||
```
|
||||
|
||||
#### Step 3: Confirm with Designer
|
||||
```
|
||||
Agent: "This body text looks identical to Start Page body text.
|
||||
Should I use the same specification (16px Regular)?"
|
||||
|
||||
Designer: "Yes!" or "No, make it 18px"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Pattern Matching Rules
|
||||
|
||||
### When to Apply Same Specification
|
||||
|
||||
**Match if ALL criteria align:**
|
||||
|
||||
1. **Visual Similarity**
|
||||
- Line thickness matches (relative to other elements)
|
||||
- Spacing matches (relative to UI anchors)
|
||||
- Alignment matches
|
||||
|
||||
2. **Functional Role**
|
||||
- Serves same purpose (e.g., both are body paragraphs)
|
||||
- Same content type (e.g., both are descriptions)
|
||||
- Same hierarchy level
|
||||
|
||||
3. **Context**
|
||||
- Similar page sections (e.g., both in main content area)
|
||||
- Similar surrounding elements
|
||||
|
||||
### When to Create New Specification
|
||||
|
||||
**Create new spec if:**
|
||||
|
||||
- Visual appearance differs (thicker lines, different spacing)
|
||||
- Functional role differs (e.g., one is a quote, one is body text)
|
||||
- Designer explicitly requests different styling
|
||||
- Context requires emphasis/de-emphasis
|
||||
|
||||
---
|
||||
|
||||
## Design System Integration
|
||||
|
||||
### Automatic Pattern Building
|
||||
|
||||
As you analyze pages, WDS naturally builds design system patterns:
|
||||
|
||||
```
|
||||
Project: Dog Week
|
||||
|
||||
Text Styles Identified:
|
||||
├─ heading-xl: 48px Bold (Page titles)
|
||||
├─ heading-lg: 36px Bold (Section headings)
|
||||
├─ heading-md: 24px Semibold (Subsection headings)
|
||||
├─ body-text: 16px Regular (Paragraphs)
|
||||
├─ button-label: 16px Semibold (All buttons)
|
||||
├─ caption: 12px Regular (Helper text)
|
||||
└─ nav-item: 14px Medium (Navigation)
|
||||
|
||||
Components Identified:
|
||||
├─ Feature Card (used on Start, Features, About pages)
|
||||
├─ Navigation Bar (used on all pages)
|
||||
├─ Footer (used on all pages)
|
||||
└─ CTA Button (used on Start, Pricing pages)
|
||||
```
|
||||
|
||||
### Benefits
|
||||
|
||||
**Without explicit design system:**
|
||||
- Maintains consistency through pattern recognition
|
||||
- Reduces specification time (reference previous pages)
|
||||
- Creates professional, cohesive experience
|
||||
|
||||
**With explicit design system:**
|
||||
- Automatically maps to existing components
|
||||
- Validates sketch against design system
|
||||
- Suggests design system updates when new patterns emerge
|
||||
|
||||
---
|
||||
|
||||
## Agent Behavior Examples
|
||||
|
||||
### Example 1: Exact Match
|
||||
|
||||
```
|
||||
Agent: "I'm analyzing the Contact Page body text.
|
||||
|
||||
Visual Analysis:
|
||||
- Line thickness: Thinnest (matches Start Page body text)
|
||||
- Spacing: Icon-sized (matches Start Page body text)
|
||||
- Alignment: Left (matches Start Page body text)
|
||||
|
||||
Pattern Match: Start Page body text (16px Regular)
|
||||
|
||||
Should I use the same specification?"
|
||||
|
||||
Designer: "Yes, keep it consistent."
|
||||
|
||||
Agent: "✅ Applied: 16px Regular (consistent with Start Page)"
|
||||
```
|
||||
|
||||
### Example 2: Intentional Variation
|
||||
|
||||
```
|
||||
Agent: "I'm analyzing the Testimonial Quote text.
|
||||
|
||||
Visual Analysis:
|
||||
- Line thickness: Medium (thicker than body text)
|
||||
- Spacing: Slightly larger than body text
|
||||
- Alignment: Center (different from body text)
|
||||
|
||||
This looks different from body text. Should this be:
|
||||
1. New style: 18px Medium, center-aligned (emphasis)
|
||||
2. Same as body: 16px Regular (consistency)
|
||||
|
||||
Your choice?"
|
||||
|
||||
Designer: "Option 1 - quotes should stand out."
|
||||
|
||||
Agent: "✅ Created new style: testimonial-quote (18px Medium)"
|
||||
```
|
||||
|
||||
### Example 3: Component Recognition
|
||||
|
||||
```
|
||||
Agent: "I'm analyzing the Features section on the Pricing Page.
|
||||
|
||||
Component Match Detected:
|
||||
- Layout: 3-column card grid ✓
|
||||
- Card structure: Icon + Title + Description ✓
|
||||
- Visual style: Matches Features section from Start Page ✓
|
||||
|
||||
This looks like the same 'Feature Card' component.
|
||||
Should I:
|
||||
1. Reference existing component (recommended)
|
||||
2. Create page-specific version
|
||||
|
||||
Your choice?"
|
||||
|
||||
Designer: "Option 1 - it's the same component."
|
||||
|
||||
Agent: "✅ Referenced: Feature Card component (defined on Start Page)"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### For Designers
|
||||
|
||||
1. **Be Consistent in Sketches**
|
||||
- Use same line thickness for same text types
|
||||
- Use same spacing patterns across pages
|
||||
- Helps AI recognize patterns automatically
|
||||
|
||||
2. **Confirm Pattern Matches**
|
||||
- When AI suggests pattern match, verify it's intentional
|
||||
- Speak up if variation is desired
|
||||
|
||||
3. **Build Design System Gradually**
|
||||
- First few pages establish patterns
|
||||
- Later pages reference patterns
|
||||
- Natural evolution into design system
|
||||
|
||||
### For AI Agents
|
||||
|
||||
1. **Always Check Previous Pages First**
|
||||
- Before analyzing text, look for established patterns
|
||||
- Show detected patterns to designer for transparency
|
||||
|
||||
2. **Ask, Don't Assume**
|
||||
- Even if visual match is strong, confirm with designer
|
||||
- Designer may have intentional variation
|
||||
|
||||
3. **Track Pattern Usage**
|
||||
- Note which pages use which patterns
|
||||
- Helps identify true design system components
|
||||
|
||||
---
|
||||
|
||||
## Implementation in WDS Workflow
|
||||
|
||||
### Step 1: Holistic Sketch Reading
|
||||
|
||||
```
|
||||
<action>
|
||||
1. Check if other pages in project have been analyzed
|
||||
2. Load established text style patterns
|
||||
3. Identify UI anchors in current sketch
|
||||
4. Use previous pages + UI elements to calibrate scale
|
||||
</action>
|
||||
```
|
||||
|
||||
### Step 2: Pattern Detection
|
||||
|
||||
```
|
||||
<action>
|
||||
For each text element in current sketch:
|
||||
1. Analyze visual properties (thickness, spacing, alignment)
|
||||
2. Compare to established patterns from previous pages
|
||||
3. If match found → suggest applying same specification
|
||||
4. If no match → analyze using UI anchors + relative measurements
|
||||
</action>
|
||||
```
|
||||
|
||||
### Step 3: Designer Confirmation
|
||||
|
||||
```
|
||||
<output>
|
||||
Text Element: Body paragraph in "About Us" section
|
||||
|
||||
Pattern Match: Start Page body text
|
||||
- Visual: Thin lines, icon-sized spacing ✓
|
||||
- Functional: Paragraph description ✓
|
||||
- Specification: 16px Regular
|
||||
|
||||
Apply same specification?
|
||||
</output>
|
||||
|
||||
<ask>
|
||||
1. Yes - Use 16px Regular (consistent)
|
||||
2. No - I want different styling
|
||||
</ask>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
**Cross-page consistency is achieved through:**
|
||||
|
||||
1. **Pattern Recognition** - AI identifies similar visual patterns across pages
|
||||
2. **Reference Anchors** - First pages establish baseline specifications
|
||||
3. **Designer Confirmation** - AI suggests matches, designer validates
|
||||
4. **Natural Design System** - Patterns emerge organically from consistent application
|
||||
|
||||
**Result:** Professional, cohesive multi-page designs with minimal specification overhead.
|
||||
|
|
@ -0,0 +1,153 @@
|
|||
# Phase 4 Documentation Architecture
|
||||
|
||||
## Problem: Redundant Information
|
||||
|
||||
Currently sketch text analysis rules are duplicated across multiple files, making maintenance difficult and increasing risk of inconsistency.
|
||||
|
||||
## Solution: Single Source of Truth Pattern
|
||||
|
||||
### Core Documentation (Single Source of Truth)
|
||||
|
||||
1. **`SKETCH-TEXT-ANALYSIS-GUIDE.md`** ← **MASTER GUIDE**
|
||||
- Complete rules for analyzing text markers
|
||||
- Line thickness → font weight
|
||||
- Line spacing → font size
|
||||
- Line position → text alignment
|
||||
- Line count → text lines
|
||||
- Line length → character capacity
|
||||
- All visual examples and edge cases
|
||||
|
||||
2. **`SKETCH-TEXT-QUICK-REFERENCE.md`**
|
||||
- One-page summary of the guide
|
||||
- Quick lookup table
|
||||
- References master guide for details
|
||||
|
||||
3. **`SKETCH-TEXT-STRATEGY.md`**
|
||||
- When to use actual text vs. line markers
|
||||
- Proactive translation workflow
|
||||
- References master guide for analysis rules
|
||||
|
||||
### Specialized Documentation (References Core)
|
||||
|
||||
4. **`object-types/TEXT-DETECTION-PRIORITY.md`**
|
||||
- Why text detection is first
|
||||
- PAIRS = text, SINGLE = decorative
|
||||
- References master guide for analysis
|
||||
- Focus: Detection logic only
|
||||
|
||||
5. **`object-types/heading-text.md`**
|
||||
- Instruction file for AI agent
|
||||
- References master guide
|
||||
- Focus: Workflow and user interaction
|
||||
- Does NOT duplicate analysis rules
|
||||
|
||||
6. **`object-types/object-router.md`**
|
||||
- Routes to appropriate object type
|
||||
- References TEXT-DETECTION-PRIORITY.md
|
||||
- Does NOT duplicate analysis rules
|
||||
|
||||
### Supporting Documentation
|
||||
|
||||
7. **`HTML-VS-VISUAL-STYLES.md`**
|
||||
- HTML tags vs visual styles
|
||||
- No sketch analysis (different topic)
|
||||
|
||||
8. **`IMAGE-SKETCHING-BEST-PRACTICES.md`**
|
||||
- How to sketch images
|
||||
- No text analysis (different topic)
|
||||
|
||||
9. **`WDS-SPECIFICATION-PATTERN.md`**
|
||||
- Shows complete specification format
|
||||
- Examples reference the guides
|
||||
- Does NOT teach analysis rules
|
||||
|
||||
10. **`TRANSLATION-ORGANIZATION-GUIDE.md`**
|
||||
- Purpose-based naming
|
||||
- Grouped translations
|
||||
- References guides for text detection
|
||||
|
||||
---
|
||||
|
||||
## Refactoring Plan
|
||||
|
||||
### Keep As-Is (Single Source of Truth)
|
||||
✅ `SKETCH-TEXT-ANALYSIS-GUIDE.md` - Master guide with all rules
|
||||
✅ `SKETCH-TEXT-QUICK-REFERENCE.md` - Quick reference
|
||||
✅ `SKETCH-TEXT-STRATEGY.md` - Strategy guide
|
||||
|
||||
### Refactor (Remove Duplication, Add References)
|
||||
|
||||
**`TEXT-DETECTION-PRIORITY.md`:**
|
||||
- Keep: Detection logic (pairs vs single)
|
||||
- Remove: Detailed analysis rules (thickness → weight, spacing → size)
|
||||
- Add: Reference to master guide
|
||||
|
||||
**`heading-text.md`:**
|
||||
- Keep: Workflow steps
|
||||
- Remove: Duplicate explanations of analysis rules
|
||||
- Add: Reference to master guide
|
||||
- Show: Example output only
|
||||
|
||||
**`object-router.md`:**
|
||||
- Keep: Routing logic
|
||||
- Remove: Any duplicate analysis
|
||||
- Add: Reference to TEXT-DETECTION-PRIORITY.md
|
||||
|
||||
**`WDS-SPECIFICATION-PATTERN.md`:**
|
||||
- Keep: Examples
|
||||
- Add: Note "See SKETCH-TEXT-ANALYSIS-GUIDE.md for how these values were derived"
|
||||
|
||||
**`TRANSLATION-ORGANIZATION-GUIDE.md`:**
|
||||
- Keep: Organization patterns
|
||||
- Add: Reference to master guide for analysis
|
||||
|
||||
---
|
||||
|
||||
## Benefits
|
||||
|
||||
✅ **Single Source of Truth** - One place to update analysis rules
|
||||
✅ **No Redundancy** - Each file has clear purpose
|
||||
✅ **Easy Maintenance** - Update once, references everywhere
|
||||
✅ **Clear Hierarchy** - Master guide → specialized docs
|
||||
✅ **Reduced File Size** - Instruction files become smaller and focused
|
||||
|
||||
---
|
||||
|
||||
## Reference Pattern
|
||||
|
||||
In instruction files, use this pattern:
|
||||
|
||||
```markdown
|
||||
<output>Analyzing text markers in sketch...</output>
|
||||
|
||||
<action>Apply text marker analysis rules from SKETCH-TEXT-ANALYSIS-GUIDE.md:
|
||||
- Count pairs → number of lines
|
||||
- Measure thickness → font weight
|
||||
- Measure spacing → font size estimate
|
||||
- Check position → alignment
|
||||
- Calculate length → character capacity
|
||||
</action>
|
||||
|
||||
<output>**Sketch Analysis:**
|
||||
- 2 line pairs → 2 lines of text
|
||||
- Thick lines (3px) → Bold weight
|
||||
- Spacing (24px) → ~42px font size estimate
|
||||
- Centered position → Center alignment
|
||||
- ~35 characters per line
|
||||
|
||||
For detailed analysis rules, see: SKETCH-TEXT-ANALYSIS-GUIDE.md</output>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Status
|
||||
|
||||
**To Do:**
|
||||
- [ ] Refactor TEXT-DETECTION-PRIORITY.md
|
||||
- [ ] Refactor heading-text.md
|
||||
- [ ] Refactor object-router.md
|
||||
- [ ] Add references in WDS-SPECIFICATION-PATTERN.md
|
||||
- [ ] Add references in TRANSLATION-ORGANIZATION-GUIDE.md
|
||||
|
||||
**Result:** Clean, maintainable documentation architecture! 🎯
|
||||
|
||||
|
|
@ -0,0 +1,223 @@
|
|||
# HTML Tags vs. Visual Text Styles
|
||||
|
||||
**Critical Best Practice for WDS Specifications**
|
||||
|
||||
---
|
||||
|
||||
## The Two-Layer System
|
||||
|
||||
### Layer 1: HTML Semantic Structure (h1-h6, p, etc.)
|
||||
**Purpose:** SEO, accessibility, document outline, screen readers
|
||||
|
||||
**Rules:**
|
||||
- **Each page must have exactly ONE h1** (main page title)
|
||||
- **Heading hierarchy must be logical** (h1 → h2 → h3, no skipping)
|
||||
- **Same across all pages** for semantic consistency
|
||||
- **Not about visual appearance**
|
||||
|
||||
### Layer 2: Visual Text Styles (Design System)
|
||||
**Purpose:** Visual hierarchy, branding, design consistency
|
||||
|
||||
**Rules:**
|
||||
- **Named by visual purpose** (Display-Large, Headline-Primary, Body-Regular, etc.)
|
||||
- **Can be applied to any HTML tag**
|
||||
- **Different pages can use different visual styles** for the same HTML tag
|
||||
- **About appearance, not semantics**
|
||||
|
||||
---
|
||||
|
||||
## Why Separate?
|
||||
|
||||
### Problem: Mixing HTML and Visual Styles
|
||||
```markdown
|
||||
❌ BAD:
|
||||
- **Style**: H1 heading
|
||||
|
||||
What does this mean?
|
||||
- Is it an h1 tag?
|
||||
- Is it a visual style that looks like an h1?
|
||||
- What if another page needs h1 but different visual style?
|
||||
```
|
||||
|
||||
### Solution: Specify Both Independently
|
||||
```markdown
|
||||
✅ GOOD:
|
||||
- **HTML Tag**: h1 (semantic structure)
|
||||
- **Visual Style**: Display-Large (from Design System)
|
||||
```
|
||||
|
||||
**Now we know:**
|
||||
- HTML: This is the main page heading (h1 for SEO)
|
||||
- Visual: It uses the "Display-Large" design system style
|
||||
- Another page could have: h1 + Headline-Medium (different visual, same semantic)
|
||||
|
||||
---
|
||||
|
||||
## Real-World Examples
|
||||
|
||||
### Example 1: Landing Page vs. Article Page
|
||||
|
||||
**Landing Page - Hero Headline:**
|
||||
```markdown
|
||||
- **HTML Tag**: h1
|
||||
- **Visual Style**: Hero headline
|
||||
- **Font**: Bold, 56px, line-height 1.1
|
||||
```
|
||||
|
||||
**Article Page - Article Title:**
|
||||
```markdown
|
||||
- **HTML Tag**: h1
|
||||
- **Visual Style**: Main header
|
||||
- **Font**: Bold, 32px, line-height 1.3
|
||||
```
|
||||
|
||||
**Both are h1 (semantic), but different visual styles!**
|
||||
|
||||
### Example 2: Same Visual Style, Different Semantics
|
||||
|
||||
**Section Heading:**
|
||||
```markdown
|
||||
- **HTML Tag**: h2
|
||||
- **Visual Style**: Sub header
|
||||
- **Font**: Bold, 28px, line-height 1.2
|
||||
```
|
||||
|
||||
**Testimonial Quote:**
|
||||
```markdown
|
||||
- **HTML Tag**: p
|
||||
- **Visual Style**: Sub header
|
||||
- **Font**: Bold, 28px, line-height 1.2
|
||||
```
|
||||
|
||||
**Same visual style (Sub header), but different HTML tags for proper semantics!**
|
||||
|
||||
---
|
||||
|
||||
## Design System Visual Style Naming
|
||||
|
||||
### Good Visual Style Names (Descriptive & Purpose-Based)
|
||||
|
||||
**For Headers:**
|
||||
✅ **Main header** - Primary page header
|
||||
✅ **Sub header** - Section headers
|
||||
✅ **Sub header light** - Lighter variant of section header
|
||||
✅ **Card header** - Headers within cards
|
||||
✅ **Small header** - Minor headers, labels
|
||||
|
||||
**For Body Text:**
|
||||
✅ **Body text** - Standard paragraph text
|
||||
✅ **Body text large** - Larger body text for emphasis
|
||||
✅ **Body text small** - Smaller body text, secondary info
|
||||
✅ **Intro text** - Opening paragraph, lead text
|
||||
|
||||
**For Special Purposes:**
|
||||
✅ **Hero headline** - Large display text for hero sections
|
||||
✅ **Caption text** - Image captions, metadata
|
||||
✅ **Label text** - Form labels, UI labels
|
||||
✅ **Error text** - Error messages
|
||||
✅ **Success text** - Success messages
|
||||
✅ **Link text** - Link styling
|
||||
✅ **Button text** - Text within buttons
|
||||
|
||||
### Bad Visual Style Names
|
||||
❌ **H1-Style** / **Heading-1** - Confuses with HTML tags
|
||||
❌ **Text-Size-42** - Just a number, not semantic
|
||||
❌ **Big-Text** - Too vague
|
||||
❌ **Display-Large** - Too abstract (unless using design system tokens)
|
||||
|
||||
---
|
||||
|
||||
## WDS Specification Format
|
||||
|
||||
### Complete Example
|
||||
|
||||
```markdown
|
||||
#### Primary Headline
|
||||
|
||||
**OBJECT ID**: `start-hero-headline`
|
||||
|
||||
**HTML Structure:**
|
||||
- **Tag**: h1
|
||||
- **Purpose**: Main page heading (SEO/accessibility)
|
||||
|
||||
**Visual Style:**
|
||||
- **Style Name**: Hero headline
|
||||
- **Font weight**: Bold (from 3px thick line markers in sketch)
|
||||
- **Font size**: 56px (est. from 32px spacing between line pairs)
|
||||
- **Line-height**: 1.1 (est. calculated from font size)
|
||||
- **Color**: #1a1a1a
|
||||
- **Letter spacing**: -0.02em
|
||||
|
||||
**Position**: Center of hero section, above supporting text
|
||||
|
||||
**Behavior**: Updates with language toggle
|
||||
|
||||
**Content**:
|
||||
- EN: "Every walk. on time. Every time."
|
||||
- SE: "Varje promenad. i tid. Varje gång."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Benefits of This Approach
|
||||
|
||||
✅ **Flexibility** - Different pages can have different visual styles for same semantic tags
|
||||
✅ **Consistency** - Design system ensures visual consistency across visual styles
|
||||
✅ **SEO/Accessibility** - Proper HTML structure maintained
|
||||
✅ **Scalability** - Easy to add new visual styles without breaking semantic structure
|
||||
✅ **Clarity** - Designers and developers both understand the specification
|
||||
✅ **Reusability** - Visual styles can be reused across different HTML tags
|
||||
|
||||
---
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Pattern 1: Landing Page
|
||||
```
|
||||
h1 → Hero headline (big hero text, 56px)
|
||||
h2 → Sub header (section headings, 32px)
|
||||
h3 → Small header (subsection headings, 24px)
|
||||
p → Body text (regular paragraphs, 16px)
|
||||
```
|
||||
|
||||
### Pattern 2: Blog Post
|
||||
```
|
||||
h1 → Main header (article title, 36px)
|
||||
h2 → Sub header (section headings, 28px)
|
||||
h3 → Sub header light (subsection headings, 22px)
|
||||
p → Body text large (article body, 18px)
|
||||
```
|
||||
|
||||
### Pattern 3: Dashboard
|
||||
```
|
||||
h1 → Main header (page title, 28px)
|
||||
h2 → Card header (widget titles, 20px)
|
||||
h3 → Small header (section labels, 16px)
|
||||
p → Body text small (compact info, 14px)
|
||||
```
|
||||
|
||||
**Same HTML structure (h1, h2, h3, p) but different visual styles for each context!**
|
||||
|
||||
---
|
||||
|
||||
## Implementation Note
|
||||
|
||||
When generating HTML prototypes or handing off to developers:
|
||||
|
||||
```html
|
||||
<!-- The HTML tag is semantic, the class references the visual style -->
|
||||
<h1 class="hero-headline">Every walk. on time. Every time.</h1>
|
||||
|
||||
<!-- Another page might have -->
|
||||
<h1 class="main-header">Welcome to Your Profile</h1>
|
||||
|
||||
<!-- NOT this (mixing concerns) -->
|
||||
<h1 class="h1">Every walk. on time. Every time.</h1>
|
||||
```
|
||||
|
||||
The CSS class references the **visual style name** (hero-headline, main-header), not the HTML tag.
|
||||
|
||||
---
|
||||
|
||||
**Remember:** HTML tags = Document structure. Visual styles = Appearance. Keep them separate! 🎯
|
||||
|
||||
|
|
@ -0,0 +1,255 @@
|
|||
# WDS Sketching Best Practices: Images
|
||||
|
||||
**How to represent images in UI sketches**
|
||||
|
||||
---
|
||||
|
||||
## ✅ Recommended: Sketch the Actual Image Content
|
||||
|
||||
### Why Sketch Real Content?
|
||||
|
||||
When you sketch what the image should actually show (rather than just "X" or "image here"), you:
|
||||
- **Provide visual direction** - Designer/developer understands image purpose
|
||||
- **Enable AI interpretation** - Agent can suggest appropriate image content
|
||||
- **Guide art direction** - Photographer/illustrator knows what's needed
|
||||
- **Communicate intent** - Stakeholders visualize the final design
|
||||
- **Inspire creativity** - More engaging than abstract placeholders
|
||||
|
||||
---
|
||||
|
||||
## Image Sketching Techniques
|
||||
|
||||
### 1. Portrait/Profile Photos
|
||||
|
||||
**Sketch a simple face:**
|
||||
```
|
||||
┌──────────────┐
|
||||
│ ◠ ◠ │ ← Simple eyes
|
||||
│ │
|
||||
│ ᵕ │ ← Simple smile
|
||||
└──────────────┘
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```
|
||||
┌──────────────┐
|
||||
│ ● ● │ ← Dots for eyes
|
||||
│ │
|
||||
│ \_/ │ ← Smile
|
||||
└──────────────┘
|
||||
```
|
||||
|
||||
**Purpose:** Profile pictures, team photos, author avatars, user images
|
||||
|
||||
### 2. Hero Images / Backgrounds
|
||||
|
||||
**Sketch landscape/scenery:**
|
||||
```
|
||||
┌──────────────────────────┐
|
||||
│ │
|
||||
│ /\ /\ /\ │ ← Mountains
|
||||
│ / \ / \ / \ │
|
||||
│ / X \/ \ │
|
||||
└──────────────────────────┘
|
||||
```
|
||||
|
||||
**Sketch clouds/sky:**
|
||||
```
|
||||
┌──────────────────────────┐
|
||||
│ ~ ~ ~ │
|
||||
│ ~ ~ ~ ~ │ ← Soft clouds
|
||||
│ ~ ~ │
|
||||
│ │
|
||||
└──────────────────────────┘
|
||||
```
|
||||
|
||||
**Sketch abstract shapes:**
|
||||
```
|
||||
┌──────────────────────────┐
|
||||
│ ∿∿∿ ≈≈≈ │
|
||||
│ ∿∿ ≈≈ ∿∿ │ ← Waves, organic shapes
|
||||
│ ≈≈≈ ∿∿∿ │
|
||||
└──────────────────────────┘
|
||||
```
|
||||
|
||||
**Purpose:** Hero sections, full-width backgrounds, feature images
|
||||
|
||||
### 3. Product Images
|
||||
|
||||
**Sketch the product outline:**
|
||||
```
|
||||
┌──────────────┐
|
||||
│ |‾‾‾‾| │ ← Phone outline
|
||||
│ | | │
|
||||
│ | ● | │ ← Home button
|
||||
│ |____| │
|
||||
└──────────────┘
|
||||
```
|
||||
|
||||
```
|
||||
┌──────────────┐
|
||||
│ _____ │ ← Laptop screen
|
||||
│ | | │
|
||||
│ |_____| │
|
||||
│ '-----' │ ← Keyboard
|
||||
└──────────────┘
|
||||
```
|
||||
|
||||
**Purpose:** Product photos, e-commerce images, feature showcases
|
||||
|
||||
### 4. Icons / Illustrations
|
||||
|
||||
**Sketch simple icon shapes:**
|
||||
```
|
||||
┌──────┐
|
||||
│ ⚙ │ ← Settings gear
|
||||
└──────┘
|
||||
```
|
||||
|
||||
```
|
||||
┌──────┐
|
||||
│ ♥ │ ← Heart icon (favorites/likes)
|
||||
└──────┘
|
||||
```
|
||||
|
||||
```
|
||||
┌──────┐
|
||||
│ ✓ │ ← Checkmark (success)
|
||||
└──────┘
|
||||
```
|
||||
|
||||
**Purpose:** UI icons, feature illustrations, decorative graphics
|
||||
|
||||
### 5. Abstract/Decorative Images
|
||||
|
||||
**Use soft, flowing shapes:**
|
||||
```
|
||||
┌──────────────────────────┐
|
||||
│ ∞ │
|
||||
│ ≋≋≋ │ ← Abstract flowing shapes
|
||||
│ ⌇⌇ │
|
||||
│ ∿∿∿ │
|
||||
└──────────────────────────┘
|
||||
```
|
||||
|
||||
**Use geometric patterns:**
|
||||
```
|
||||
┌──────────────────────────┐
|
||||
│ ◆ ○ ▢ │
|
||||
│ ▢ ◆ ○ │ ← Geometric pattern
|
||||
│ ○ ▢ ◆ │
|
||||
└──────────────────────────┘
|
||||
```
|
||||
|
||||
**Purpose:** Background patterns, decorative elements, brand graphics
|
||||
|
||||
---
|
||||
|
||||
## ❌ Discouraged: Generic "X" Marker
|
||||
|
||||
**Why avoid X markers?**
|
||||
|
||||
```
|
||||
┌──────────────┐
|
||||
│ X │ ← Generic, uninformative
|
||||
└──────────────┘
|
||||
```
|
||||
|
||||
**Problems with X markers:**
|
||||
- ❌ **No context** - Doesn't communicate what image shows
|
||||
- ❌ **No direction** - No guidance for content selection
|
||||
- ❌ **Intrusive** - Visually distracting in sketch
|
||||
- ❌ **Uninspiring** - Doesn't engage stakeholders
|
||||
- ❌ **Ambiguous** - Could be mistaken for "delete" or error
|
||||
|
||||
**Only use X if:** Sketch is extremely rough/quick and image content is described elsewhere
|
||||
|
||||
---
|
||||
|
||||
## WDS Detection Rules
|
||||
|
||||
### AI Image Detection
|
||||
|
||||
When analyzing sketches, the AI should:
|
||||
|
||||
1. **Look for rectangular containers** (image boundaries)
|
||||
2. **Check for sketched content inside** (faces, landscapes, products, shapes)
|
||||
3. **Interpret the sketch** to understand image purpose
|
||||
4. **Route to `image.md`** for specification
|
||||
|
||||
### Example Detection
|
||||
|
||||
**Sketch shows:**
|
||||
```
|
||||
┌──────────────────────────┐
|
||||
│ /\ /\ /\ │
|
||||
│ / \ / \ / \ │ ← Mountains sketched
|
||||
│ / X \/ \ │
|
||||
└──────────────────────────┘
|
||||
```
|
||||
|
||||
**AI interprets:**
|
||||
- Rectangle container detected
|
||||
- Mountain/landscape sketch inside
|
||||
- **Purpose:** Hero background image showing outdoor/nature scene
|
||||
- **Route to:** `image.md`
|
||||
- **Suggested content:** Mountain landscape, outdoor scenery, nature photography
|
||||
|
||||
---
|
||||
|
||||
## Benefits of Sketching Real Content
|
||||
|
||||
### For Designers
|
||||
- ✅ Communicate visual intent clearly
|
||||
- ✅ Test composition and layout
|
||||
- ✅ Provide art direction
|
||||
- ✅ Inspire creative solutions
|
||||
|
||||
### For AI Agents
|
||||
- ✅ Understand image purpose from context
|
||||
- ✅ Suggest appropriate image sources
|
||||
- ✅ Recommend image dimensions and aspect ratios
|
||||
- ✅ Generate meaningful alt text
|
||||
|
||||
### For Developers
|
||||
- ✅ Understand what image represents
|
||||
- ✅ Know how to style and position image
|
||||
- ✅ Select appropriate placeholder images
|
||||
- ✅ Write meaningful alt text for accessibility
|
||||
|
||||
### For Stakeholders
|
||||
- ✅ Visualize final design better
|
||||
- ✅ Provide meaningful feedback
|
||||
- ✅ Understand design intent
|
||||
- ✅ Approve with confidence
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Image Type | Sketch Technique | Example |
|
||||
|------------|------------------|---------|
|
||||
| **Portrait/Face** | Simple face with eyes and smile | ◠ ◠ ᵕ |
|
||||
| **Landscape** | Mountains, trees, horizon | /\\ /\\ /\\ |
|
||||
| **Sky/Clouds** | Wavy cloud shapes | ~ ~ ~ |
|
||||
| **Product** | Product outline/silhouette | Phone, laptop shape |
|
||||
| **Icon** | Simple icon shape | ⚙ ♥ ✓ |
|
||||
| **Abstract** | Flowing, organic shapes | ∿ ≋ ∞ |
|
||||
| **Geometric** | Shapes and patterns | ◆ ○ ▢ |
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
**WDS Image Sketching Philosophy:**
|
||||
> "Sketch what you see, not just where it goes."
|
||||
|
||||
**Guidelines:**
|
||||
- ✅ **Draw the actual content** - Faces, landscapes, products
|
||||
- ✅ **Use soft, organic shapes** - Clouds, waves for abstract images
|
||||
- ✅ **Keep it simple** - Quick sketches are fine, detail level matches sketch fidelity
|
||||
- ❌ **Avoid generic X markers** - Provides no useful context
|
||||
|
||||
**Result:** Better communication, clearer intent, more useful AI analysis! 🎨✨
|
||||
|
||||
|
|
@ -0,0 +1,412 @@
|
|||
# Proactive Translation Workflow
|
||||
|
||||
**Agent Always Suggests Translations**
|
||||
|
||||
---
|
||||
|
||||
## The Principle
|
||||
|
||||
**Agent is proactive, not passive**
|
||||
- Don't just ask for translations
|
||||
- **Suggest them!**
|
||||
- Let user accept, refine, or override
|
||||
|
||||
---
|
||||
|
||||
## Workflow Examples
|
||||
|
||||
### Example 1: Sketch Has Actual Text
|
||||
|
||||
**Sketch shows:**
|
||||
```
|
||||
Every walk. on time. Every time.
|
||||
```
|
||||
|
||||
**Agent says:**
|
||||
```
|
||||
I found text in your sketch: "Every walk. on time. Every time."
|
||||
|
||||
Let me suggest translations...
|
||||
|
||||
Suggested content for Primary Headline:
|
||||
|
||||
EN: Every walk. on time. Every time.
|
||||
SE: Varje promenad. i tid. Varje gång.
|
||||
NO: Hver tur. i tide. Hver gang.
|
||||
|
||||
These are my suggestions. Do they work?
|
||||
|
||||
1. Use these translations
|
||||
2. Adjust translations
|
||||
3. Manual input
|
||||
|
||||
Choice [1/2/3]:
|
||||
```
|
||||
|
||||
**User response options:**
|
||||
|
||||
**Option A: Accept (Fast!)**
|
||||
```
|
||||
1
|
||||
```
|
||||
→ Done! All translations accepted.
|
||||
|
||||
**Option B: Adjust specific**
|
||||
```
|
||||
2
|
||||
|
||||
Which language(s) need adjustment?
|
||||
|
||||
EN: Every walk. on time. Every time. ← Keep
|
||||
SE: Varje promenad. i tid. Varje gång. ← Change this
|
||||
NO: Hver tur. i tide. Hver gang. ← Keep
|
||||
|
||||
SE: Varje promenad. Punktligt. Varje gång.
|
||||
```
|
||||
→ Done! One adjusted, others kept.
|
||||
|
||||
**Option C: Manual**
|
||||
```
|
||||
3
|
||||
|
||||
EN:
|
||||
SE:
|
||||
NO:
|
||||
```
|
||||
→ User provides all manually.
|
||||
|
||||
---
|
||||
|
||||
### Example 2: No Sketch Text (Markers Only)
|
||||
|
||||
**Sketch shows:**
|
||||
```
|
||||
───────────────────────────────── ← Line markers
|
||||
───────────────────────────────── ← (no actual text)
|
||||
─────────────────────────────────
|
||||
```
|
||||
|
||||
**Agent says:**
|
||||
```
|
||||
Text placeholder detected:
|
||||
- 3 horizontal lines
|
||||
- Regular weight, 16px font
|
||||
- Capacity: ~180-210 characters
|
||||
|
||||
Content for Feature Description:
|
||||
|
||||
Please provide content in one language, and I'll suggest translations!
|
||||
|
||||
EN:
|
||||
```
|
||||
|
||||
**User provides:**
|
||||
```
|
||||
EN: Organize your family around dog care. Assign walks and never miss one again.
|
||||
```
|
||||
|
||||
**Agent immediately suggests:**
|
||||
```
|
||||
Great! Here are translation suggestions:
|
||||
|
||||
SE: Organisera din familj kring hundvård. Tilldela promenader och missa aldrig en igen.
|
||||
NO: Organiser familien din rundt hundepass. Tildel turer og gå aldri glipp av en.
|
||||
|
||||
Do these work?
|
||||
|
||||
1. Use these translations
|
||||
2. Adjust translations
|
||||
3. Manual input
|
||||
|
||||
Choice [1/2/3]:
|
||||
```
|
||||
|
||||
**Result:** Agent is proactive even without sketch text!
|
||||
|
||||
---
|
||||
|
||||
## Benefits
|
||||
|
||||
### ✅ Speed
|
||||
- User accepts = instant completion
|
||||
- No typing all translations manually
|
||||
- Saves significant time
|
||||
|
||||
### ✅ Accuracy
|
||||
- Agent uses context for better translations
|
||||
- Considers character capacity
|
||||
- Maintains tone and style
|
||||
|
||||
### ✅ Flexibility
|
||||
- Can accept all suggestions
|
||||
- Can adjust specific ones
|
||||
- Can override completely
|
||||
- Full user control
|
||||
|
||||
### ✅ Consistency
|
||||
- Translations match style
|
||||
- Terminology stays consistent
|
||||
- Professional quality
|
||||
|
||||
---
|
||||
|
||||
## Technical Implementation
|
||||
|
||||
### Agent Logic
|
||||
|
||||
```xml
|
||||
<action>Read sketch for text</action>
|
||||
|
||||
<check if="sketch_has_text">
|
||||
<action>Extract text: "Every walk. on time."</action>
|
||||
<action>Translate to all product_languages</action>
|
||||
|
||||
<output>
|
||||
I found text in your sketch: "{{text}}"
|
||||
|
||||
Suggested translations:
|
||||
{{#each product_languages}}
|
||||
{{this}}: {{translated_content}}
|
||||
{{/each}}
|
||||
|
||||
Do these work? [1] Use [2] Adjust [3] Manual
|
||||
</output>
|
||||
</check>
|
||||
|
||||
<check if="!sketch_has_text">
|
||||
<ask>Provide content in {{primary_language}}:</ask>
|
||||
<action>After receiving, translate to remaining languages</action>
|
||||
|
||||
<output>
|
||||
Translation suggestions:
|
||||
{{#each remaining_languages}}
|
||||
{{this}}: {{translated_content}}
|
||||
{{/each}}
|
||||
|
||||
Do these work? [1] Use [2] Adjust [3] Manual
|
||||
</output>
|
||||
</check>
|
||||
```
|
||||
|
||||
### Translation Quality
|
||||
|
||||
**Agent considers:**
|
||||
- Character capacity from sketch
|
||||
- Tone and style of original
|
||||
- Context from page purpose
|
||||
- Previous translations in project
|
||||
- Language-specific conventions
|
||||
|
||||
---
|
||||
|
||||
## Real Dog Week Examples
|
||||
|
||||
### Example: Hero Headline
|
||||
|
||||
**Sketch:**
|
||||
```
|
||||
Every walk. on time. Every time.
|
||||
```
|
||||
|
||||
**Agent:**
|
||||
```
|
||||
Suggested content for Primary Headline:
|
||||
|
||||
EN: Every walk. on time. Every time.
|
||||
SE: Varje promenad. i tid. Varje gång.
|
||||
|
||||
Do these work? [1] Use [2] Adjust [3] Manual
|
||||
```
|
||||
|
||||
**User:**
|
||||
```
|
||||
1
|
||||
```
|
||||
|
||||
**Result:** ✅ Complete in seconds!
|
||||
|
||||
### Example: Button Label
|
||||
|
||||
**Sketch:**
|
||||
```
|
||||
[Get Started - Free Forever]
|
||||
```
|
||||
|
||||
**Agent:**
|
||||
```
|
||||
Suggested content for Primary CTA:
|
||||
|
||||
EN: Get Started - Free Forever
|
||||
SE: Kom Igång - Gratis För Alltid
|
||||
|
||||
Do these work? [1] Use [2] Adjust [3] Manual
|
||||
```
|
||||
|
||||
**User:**
|
||||
```
|
||||
2
|
||||
|
||||
SE: börja planera - gratis för alltid ← lowercase, different verb
|
||||
```
|
||||
|
||||
**Result:** ✅ Refined and complete!
|
||||
|
||||
### Example: Form Label
|
||||
|
||||
**Sketch:**
|
||||
```
|
||||
Email Address:
|
||||
```
|
||||
|
||||
**Agent:**
|
||||
```
|
||||
Suggested content for Email Label:
|
||||
|
||||
EN: Email Address
|
||||
SE: E-postadress
|
||||
|
||||
Do these work? [1] Use [2] Adjust [3] Manual
|
||||
```
|
||||
|
||||
**User:**
|
||||
```
|
||||
1
|
||||
```
|
||||
|
||||
**Result:** ✅ Instant!
|
||||
|
||||
---
|
||||
|
||||
## Multi-Language Example (3+ Languages)
|
||||
|
||||
**Project Config:**
|
||||
```yaml
|
||||
product_languages:
|
||||
- EN
|
||||
- SE
|
||||
- NO
|
||||
- DK
|
||||
```
|
||||
|
||||
**Sketch:**
|
||||
```
|
||||
Welcome Home
|
||||
```
|
||||
|
||||
**Agent:**
|
||||
```
|
||||
I found text in your sketch: "Welcome Home"
|
||||
|
||||
Suggested translations:
|
||||
|
||||
EN: Welcome Home
|
||||
SE: Välkommen Hem
|
||||
NO: Velkommen Hjem
|
||||
DK: Velkommen Hjem
|
||||
|
||||
Do these work? [1] Use [2] Adjust [3] Manual
|
||||
```
|
||||
|
||||
**User:**
|
||||
```
|
||||
1
|
||||
```
|
||||
|
||||
**Result:** ✅ 4 languages in one click!
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Translation Confidence
|
||||
|
||||
**High confidence:**
|
||||
```
|
||||
✅ These translations look good!
|
||||
|
||||
Do they work? [1] Use [2] Adjust [3] Manual
|
||||
```
|
||||
|
||||
**Low confidence:**
|
||||
```
|
||||
⚠️ I'm less confident about these translations. Please review carefully!
|
||||
|
||||
Suggestions:
|
||||
EN: [original]
|
||||
SE: [suggested]
|
||||
|
||||
Do they work? [1] Use [2] Adjust [3] Manual
|
||||
```
|
||||
|
||||
### Character Capacity Warning
|
||||
|
||||
**If translation exceeds capacity:**
|
||||
```
|
||||
⚠️ Translation length warning:
|
||||
|
||||
EN: "Every walk. on time." (23 chars) ✅
|
||||
SE: "Varje promenad i tid hela tiden." (33 chars) ⚠️
|
||||
→ Exceeds capacity (30 chars)
|
||||
|
||||
Suggested shorter version:
|
||||
SE: "Varje promenad. I tid." (24 chars) ✅
|
||||
|
||||
Use shorter version? (y/n)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## User Experience
|
||||
|
||||
### Before (Passive):
|
||||
```
|
||||
EN: ← User types
|
||||
SE: ← User types
|
||||
NO: ← User types
|
||||
|
||||
Slow, tedious, error-prone
|
||||
```
|
||||
|
||||
### After (Proactive):
|
||||
```
|
||||
Suggested translations:
|
||||
EN: Every walk. on time.
|
||||
SE: Varje promenad. i tid.
|
||||
NO: Hver tur. i tide.
|
||||
|
||||
[1] Use these ← ONE CLICK!
|
||||
|
||||
Fast, accurate, professional
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
### Agent Behavior
|
||||
|
||||
**Always suggest translations:**
|
||||
1. Read sketch text (if present)
|
||||
2. Generate suggestions for ALL languages
|
||||
3. Present with options: Accept / Adjust / Manual
|
||||
4. Validate character capacity
|
||||
5. Warn if low confidence
|
||||
|
||||
**Never:**
|
||||
- Present blank fields for translations
|
||||
- Make user type everything
|
||||
- Provide only one language at a time
|
||||
|
||||
### User Benefits
|
||||
|
||||
✅ **Speed** - Accept in one click
|
||||
✅ **Quality** - Professional translations
|
||||
✅ **Control** - Can adjust or override
|
||||
✅ **Confidence** - AI-assisted, human-verified
|
||||
|
||||
---
|
||||
|
||||
**Proactive translation = better UX, faster workflow, higher quality!** 🌍⚡✨
|
||||
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,201 @@
|
|||
# Phase 4: UX Design Workflow
|
||||
|
||||
**Baldr's domain - From sketch to specification**
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Phase 4 transforms sketches and ideas into detailed, developer-ready page specifications with multi-language support.
|
||||
|
||||
---
|
||||
|
||||
## Workflow Steps
|
||||
|
||||
| Step | File | Purpose |
|
||||
|------|------|---------|
|
||||
| **Init** | `step-01-init.md` | Welcome, load context, initialize session |
|
||||
| **Define Scenario** | `step-02-define-scenario.md` | Plan user journey and pages |
|
||||
| **Design Page** | `step-03-design-page.md` | Orchestrate 4A-4E substeps per page |
|
||||
| **Complete Scenario** | `step-04-complete-scenario.md` | Finalize and summarize scenario |
|
||||
| **Next Steps** | `step-05-next-steps.md` | Continue or exit workflow |
|
||||
|
||||
---
|
||||
|
||||
## Substeps (4A-4E)
|
||||
|
||||
### 4A: Exploration
|
||||
**File:** `substeps/4a-exploration.md`
|
||||
- Think through user journey
|
||||
- Clarify context and goals
|
||||
|
||||
### 4B: Sketch Analysis
|
||||
**File:** `substeps/4b-sketch-analysis.md`
|
||||
- **Section-first approach:** AI reads entire sketch, identifies all sections
|
||||
- User confirms structure
|
||||
- Section-by-section AI interpretation
|
||||
- User refinement dialog
|
||||
|
||||
### 4C: Specification (Micro-steps 01-08)
|
||||
**Files:** `substeps/4c-01-page-basics.md` through `4c-08-generate-spec.md`
|
||||
|
||||
1. **Page Basics** - Name, purpose, route
|
||||
2. **Layout** - Structure, grid, responsive
|
||||
3. **Components** - Identify objects, route to object-type instructions
|
||||
4. **Content** - Text, images, media with translations
|
||||
5. **Interactions** - Behaviors, events, state changes
|
||||
6. **States** - Loading, error, empty, success
|
||||
7. **Validation** - Rules, messages, error handling
|
||||
8. **Generate Spec** - Complete page specification
|
||||
|
||||
### 4D: Prototype
|
||||
**File:** `substeps/4d-prototype.md`
|
||||
- Generate interactive HTML prototype
|
||||
- Uses Design System if enabled
|
||||
|
||||
### 4E: PRD Update
|
||||
**File:** `substeps/4e-prd-update.md`
|
||||
- Extract functional requirements
|
||||
- Update Product Requirements Document
|
||||
|
||||
---
|
||||
|
||||
## Object Type Instructions
|
||||
|
||||
**Location:** `object-types/`
|
||||
|
||||
Each object type has a dedicated instruction file:
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `object-router.md` | Detects object types, routes to appropriate file |
|
||||
| `button.md` | Button specification |
|
||||
| `text-input.md` | Input field specification |
|
||||
| `link.md` | Link/anchor specification |
|
||||
| `heading-text.md` | Text element specification with purpose-based naming |
|
||||
| `image.md` | Image specification |
|
||||
|
||||
**Key Features:**
|
||||
- Purpose-based naming (function over content)
|
||||
- Grouped translations (coherent language blocks)
|
||||
- Design System integration (use existing, create new, or page-specific)
|
||||
- Text placeholder analysis (line thickness → font weight, spacing → font size)
|
||||
|
||||
---
|
||||
|
||||
## Templates
|
||||
|
||||
**Location:** `templates/`
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `page-specification.template.md` | Complete page spec output format |
|
||||
| `scenario-overview.template.md` | Scenario summary format |
|
||||
|
||||
---
|
||||
|
||||
## Documentation
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `ARCHITECTURE.md` | Complete workflow architecture overview |
|
||||
| `WDS-SPECIFICATION-PATTERN.md` | **Standard specification format** (Dog Week as example) |
|
||||
| `TRANSLATION-ORGANIZATION-GUIDE.md` | Purpose-based text organization and grouped translations |
|
||||
| `SKETCH-TEXT-ANALYSIS-GUIDE.md` | How to interpret text markers in sketches |
|
||||
| `SKETCH-TEXT-QUICK-REFERENCE.md` | Quick reference for text analysis |
|
||||
| `SKETCH-TEXT-STRATEGY.md` | When to use actual text vs. line markers |
|
||||
| `PROACTIVE-TRANSLATION-WORKFLOW.md` | How agent suggests translations |
|
||||
| `ROUTER-FLOW-DIAGRAM.md` | Visual flow of object routing with examples |
|
||||
|
||||
---
|
||||
|
||||
## Key Patterns
|
||||
|
||||
### 1. Section-First Workflow
|
||||
- AI reads entire sketch → identifies sections
|
||||
- User confirms structure
|
||||
- Section-by-section interpretation
|
||||
- User refines details
|
||||
- Batch generation of specs
|
||||
|
||||
### 2. Purpose-Based Naming
|
||||
- Name text by **function**, not content
|
||||
- `hero-headline` not `welcome-message`
|
||||
- `form-error` not `invalid-email-text`
|
||||
|
||||
### 3. Grouped Translations
|
||||
```markdown
|
||||
#### Primary Headline
|
||||
**Content**:
|
||||
- EN: "Welcome to Dog Week"
|
||||
- SE: "Välkommen till Hundveckan"
|
||||
```
|
||||
|
||||
### 4. Design System Integration
|
||||
For each object:
|
||||
1. Use existing component
|
||||
2. Create new component (mark for Phase 5)
|
||||
3. Page-specific only
|
||||
|
||||
### 5. Text Marker Analysis
|
||||
- **2 lines together** = 1 line of text
|
||||
- **Line thickness** = font weight (thick = bold)
|
||||
- **Spacing between pairs** = font size
|
||||
- **Line count** = number of text lines
|
||||
|
||||
---
|
||||
|
||||
## Multi-Language Support
|
||||
|
||||
**Configuration:** Set in `workflow-init`
|
||||
- **Specification Language**: Language for writing specs (EN, SE, etc.)
|
||||
- **Product Languages**: Languages the product supports (array)
|
||||
|
||||
**All text objects include translations for every product language.**
|
||||
|
||||
See: `LANGUAGE-CONFIGURATION-GUIDE.md` in workflows folder
|
||||
|
||||
---
|
||||
|
||||
## Example: Dog Week Start Page
|
||||
|
||||
The complete Dog Week Start Page specification demonstrates the pattern in action.
|
||||
|
||||
**See:** `WDS-SPECIFICATION-PATTERN.md`
|
||||
|
||||
---
|
||||
|
||||
## v6 Best Practices
|
||||
|
||||
✅ **Goal-based instructions** - Trust the agent to interpret
|
||||
✅ **Micro-file design** - Small, focused instruction files
|
||||
✅ **Just-in-time loading** - Only current step in memory
|
||||
✅ **State tracking** - Progress in output file frontmatter
|
||||
✅ **Show don't tell** - Examples over explanations
|
||||
|
||||
---
|
||||
|
||||
## Output Structure
|
||||
|
||||
```
|
||||
docs/
|
||||
C-Scenarios/
|
||||
{scenario-name}/
|
||||
00-{scenario-name}-overview.md
|
||||
01-{page-name}.md
|
||||
02-{page-name}.md
|
||||
...
|
||||
```
|
||||
|
||||
Each page spec includes:
|
||||
- Page metadata and purpose
|
||||
- All sections with objects
|
||||
- Complete multi-language content
|
||||
- Component references (if Design System enabled)
|
||||
- Interaction behaviors
|
||||
- States and validation rules
|
||||
|
||||
---
|
||||
|
||||
**Phase 4 Status:** ✅ **COMPLETE** (December 6, 2025)
|
||||
|
||||
|
|
@ -0,0 +1,494 @@
|
|||
# Sketch Analysis Guide: Reading Text Placeholders
|
||||
|
||||
**For Dog Week and All WDS Projects**
|
||||
|
||||
---
|
||||
|
||||
## Best Practice: When to Use Text vs. Markers
|
||||
|
||||
### Use ACTUAL TEXT for:
|
||||
- **Headlines** - Provides content guidance and context
|
||||
- **Button labels** - Shows intended action clearly
|
||||
- **Navigation items** - Clarifies structure
|
||||
- **Short, important text** - Where specific wording matters
|
||||
|
||||
**Example:**
|
||||
```
|
||||
Every walk. on time. Every time. ← Actual text (readable)
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- Agent can read and suggest this as starting content
|
||||
- Provides context for design decisions
|
||||
- Can still be changed during specification
|
||||
|
||||
### Use HORIZONTAL LINE MARKERS for:
|
||||
- **Body paragraphs** - Content TBD, just need length indication
|
||||
- **Long descriptions** - Where specific wording isn't decided yet
|
||||
- **Placeholder content** - General sizing guidance
|
||||
|
||||
**Example:**
|
||||
```
|
||||
───────────────────────────────────────── ← Line markers
|
||||
───────────────────────────────────────── ← Show length/size
|
||||
───────────────────────────────────────── ← Not final content
|
||||
─────────────────────────────────────────
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- Shows font size and capacity without committing to content
|
||||
- Faster for sketching body text
|
||||
- Focuses on layout, not copywriting
|
||||
|
||||
---
|
||||
|
||||
## Understanding Sketch Text Markers
|
||||
|
||||
In Dog Week sketches (and most UI sketches), **text is represented by horizontal lines in groups**.
|
||||
|
||||
### What You See
|
||||
|
||||
```
|
||||
Page Title (centered):
|
||||
═════════════════════════ ← Thick pair, centered = Heading, center-aligned
|
||||
═════════════════
|
||||
|
||||
Body text (left-aligned):
|
||||
───────────────────────────────────────── ← Thin pairs, left edge = Body, left-aligned
|
||||
─────────────────────────────────────────
|
||||
─────────────────────────────────────────
|
||||
─────────────────────────────────────────
|
||||
─────────────────────────────────────────
|
||||
|
||||
Caption (right-aligned):
|
||||
────────────────── ← Short pair, right edge = Caption, right-aligned
|
||||
──────────────────
|
||||
|
||||
Justified/Full-width text:
|
||||
═════════════════════════════════════════════ ← Extends full width = Justified
|
||||
═════════════════════════════════════════════
|
||||
```
|
||||
|
||||
### 3. Line Count → Number of Text Lines
|
||||
|
||||
**Each PAIR of horizontal lines = ONE line of text**
|
||||
|
||||
| Number of Pairs | Text Lines | Typical Use |
|
||||
|-----------------|------------|-------------|
|
||||
| 1 pair | 1 line | Headlines, labels, buttons |
|
||||
| 2 pairs | 2 lines | Short headlines, subheadings |
|
||||
| 3-4 pairs | 3-4 lines | Intro paragraphs, descriptions |
|
||||
| 5+ pairs | 5+ lines | Body copy, long descriptions |
|
||||
|
||||
---
|
||||
|
||||
## Step 0: Establish Scale Using Project Context
|
||||
|
||||
**Before analyzing individual text elements, establish your reference points:**
|
||||
|
||||
### 1. Check Previous Pages in Project
|
||||
|
||||
If analyzing multiple pages in the same project:
|
||||
|
||||
**Look for established patterns:**
|
||||
```
|
||||
Start Page (already analyzed):
|
||||
- Body text: Thin lines, icon-sized spacing → 16px Regular
|
||||
- Button labels: Medium lines → 16px Semibold
|
||||
- Page title: Thick lines, button-height spacing → 48px Bold
|
||||
|
||||
Current Page (About Page):
|
||||
- Similar thin lines, icon-sized spacing → **Same: 16px Regular**
|
||||
- Similar medium lines in buttons → **Same: 16px Semibold**
|
||||
```
|
||||
|
||||
**Design System Integration:**
|
||||
- If project has a design system, match visual patterns to existing components
|
||||
- Body text that looks like Start Page body text → Use same specification
|
||||
- Buttons that look like Start Page buttons → Use same specification
|
||||
|
||||
**Benefits:**
|
||||
- ✅ Maintains consistency across all pages
|
||||
- ✅ Builds reusable design patterns
|
||||
- ✅ Reduces specification time for subsequent pages
|
||||
- ✅ Creates cohesive user experience
|
||||
|
||||
### 2. Find UI Anchors in Current Sketch
|
||||
|
||||
- Browser chrome (address bar, scrollbars)
|
||||
- Standard UI elements (buttons, icons, form inputs)
|
||||
- Use these to calibrate scale for this specific sketch resolution
|
||||
|
||||
---
|
||||
|
||||
## Analysis Rules
|
||||
|
||||
### 1. Line Thickness → Font Weight (Relative)
|
||||
|
||||
**Line thickness indicates font weight (bold/regular), NOT font size**
|
||||
|
||||
**Compare lines RELATIVE to each other within the sketch:**
|
||||
|
||||
| Relative Thickness | Font Weight | CSS Value | Typical Use |
|
||||
|-------------------|-------------|-----------|-------------|
|
||||
| Thickest (═══) | Bold | font-weight: 700 | Headlines, strong emphasis |
|
||||
| Thick (═══) | Semibold | font-weight: 600 | Subheadings, medium emphasis |
|
||||
| Medium (──) | Medium | font-weight: 500 | Slightly emphasized text |
|
||||
| Thin (──) | Regular | font-weight: 400 | Body text, normal content |
|
||||
| Thinnest (─) | Light | font-weight: 300 | Subtle text, de-emphasized |
|
||||
|
||||
**Don't measure pixels—compare thickness relative to other text in the same sketch.**
|
||||
|
||||
### 2. Distance Between Lines → Font Size (Context-Based)
|
||||
|
||||
**The vertical spacing between lines indicates font size—compare to UI elements**
|
||||
|
||||
| Spacing Relative To | Estimated Font Size | Typical Use |
|
||||
|---------------------|---------------------|-------------|
|
||||
| Button Height | ~40-48px | Large Heading - Page titles |
|
||||
| Address Bar Height | ~32-40px | Medium Heading - Section headings |
|
||||
| Between Button & Icon | ~24-32px | Small Heading - Subsection headings |
|
||||
| Icon/Scrollbar Size | ~16-24px | Body text / Paragraphs |
|
||||
| Half Icon Size | ~12-16px | Captions / Helper text |
|
||||
|
||||
**⚠️ Important:** If spacing seems disproportionately large (>2x button height), verify this is text and not an image placeholder or colored box!
|
||||
|
||||
### 2a. Visual Examples: Text vs. Image Confusion
|
||||
|
||||
**TEXT - Normal spacing:**
|
||||
```
|
||||
═══════════════════════════════ ← Bold line
|
||||
← ~Button Height
|
||||
═══════════════════════════════ ← Bold line
|
||||
|
||||
This is clearly TEXT (H1 heading)
|
||||
```
|
||||
|
||||
**IMAGE - Large spacing (confusion risk):**
|
||||
```
|
||||
═══════════════════════════════ ← Line?
|
||||
|
||||
← Much larger than any UI element!
|
||||
|
||||
═══════════════════════════════ ← Line?
|
||||
|
||||
This might be an IMAGE PLACEHOLDER or COLORED BOX, not text!
|
||||
Ask user to confirm.
|
||||
```
|
||||
|
||||
**When in doubt:** If spacing is disproportionately large compared to UI elements, ask: "Is this text or an image/box?"
|
||||
|
||||
### 3. Text Alignment → Horizontal Position
|
||||
|
||||
**The position of line pairs within the section indicates text alignment**
|
||||
|
||||
| Alignment | Visual Indicator | Typical Use |
|
||||
|-----------|------------------|-------------|
|
||||
| **Left-aligned** | Lines start at left edge of container | Body text, lists, labels |
|
||||
| **Center-aligned** | Lines centered, equal spacing both sides | Headlines, hero text, CTAs |
|
||||
| **Right-aligned** | Lines end at right edge of container | Captions, metadata, prices, dates |
|
||||
| **Justified** | Lines extend full width of container | Dense body text, formal content |
|
||||
|
||||
#### Visual Examples
|
||||
|
||||
**Left-Aligned Text:**
|
||||
```
|
||||
Container: | |
|
||||
|
||||
═════════════════════════ ← Starts at left edge
|
||||
═════════════════════════
|
||||
[empty space →]
|
||||
```
|
||||
|
||||
**Center-Aligned Text:**
|
||||
```
|
||||
Container: | |
|
||||
|
||||
═════════════════════════ ← Centered in container
|
||||
═════════════════════════
|
||||
```
|
||||
|
||||
**Right-Aligned Text:**
|
||||
```
|
||||
Container: | |
|
||||
|
||||
═════════════ ← Ends at right edge
|
||||
═════════════
|
||||
```
|
||||
|
||||
**Justified/Full-Width Text:**
|
||||
```
|
||||
Container: | |
|
||||
|
||||
═════════════════════════════════════════════════════ ← Spans full width
|
||||
═════════════════════════════════════════════════════
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. Number of Lines → Content Length
|
||||
|
||||
| Lines in Sketch | Content Type | Character Estimate |
|
||||
|-----------------|--------------|-------------------|
|
||||
| 1-2 lines | Heading/Title | 20-60 characters total |
|
||||
| 3-5 lines | Short paragraph | 150-350 characters |
|
||||
| 6-10 lines | Full paragraph | 400-700 characters |
|
||||
| 10+ lines | Long content | 700+ characters |
|
||||
|
||||
### 4. Line-Height Calculation
|
||||
|
||||
**Line-height is derived from font size and spacing:**
|
||||
|
||||
```
|
||||
Line-height ratio = (Distance between lines) / (Estimated font size)
|
||||
|
||||
Example:
|
||||
Distance: 28px
|
||||
Font size: 24px
|
||||
Line-height: 28 / 24 = 1.16 ≈ 1.2
|
||||
```
|
||||
|
||||
**Typical ratios:**
|
||||
- **1.1-1.2** = Tight (headings)
|
||||
- **1.4-1.5** = Normal (body text)
|
||||
- **1.6-1.8** = Loose (airy text)
|
||||
|
||||
```
|
||||
Left-aligned: Center-aligned: Right-aligned:
|
||||
────────────────── ────────────────── ──────────────────
|
||||
────────────────── ────────────── ──────────────────
|
||||
────────────────── ────────── ──────────────────
|
||||
```
|
||||
|
||||
### 5. Characters Per Line
|
||||
|
||||
**Based on estimated font size and line width:**
|
||||
|
||||
```
|
||||
Large Heading (~48px): ═══════════════════ = ~20-25 chars
|
||||
Medium Heading (~36px): ═══════════════════════ = ~25-30 chars
|
||||
Small Heading (~24px): ─────────────────────── = ~40-50 chars
|
||||
Body Text (~16px): ──────────────────────────────── = ~60-70 chars
|
||||
Caption (~12px): ──────────────────────────────────── = ~80-90 chars
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Dog Week Example Analysis
|
||||
|
||||
### Example 1: Landing Page Hero
|
||||
|
||||
**Sketch shows:**
|
||||
```
|
||||
═══════════════════════════════ ← Line 1 (thick, center)
|
||||
═══════════════════════════ ← Line 2 (thick, center)
|
||||
```
|
||||
|
||||
**Analysis:**
|
||||
- **Type:** Large Heading (Page Title)
|
||||
- **Lines:** 2
|
||||
- **Line thickness:** Thickest in sketch → **Bold** (font-weight: 700)
|
||||
- **Distance between lines:** Matches button height → **~40-48px font-size**
|
||||
- **Line-height:** ~1.2 (calculated from spacing)
|
||||
- **Alignment:** Center
|
||||
- **Capacity:** ~25-30 chars per line = 50-60 total
|
||||
- **Semantic HTML:** Determined by page structure (likely H1 if page title)
|
||||
|
||||
**Content Guidance:**
|
||||
```
|
||||
English: "Welcome to Your / Dog Care Hub" (48 chars) ✅
|
||||
Swedish: "Välkommen till Din / Hundvårdshub" (50 chars) ✅
|
||||
```
|
||||
|
||||
### Example 2: Feature Description
|
||||
|
||||
**Sketch shows:**
|
||||
```
|
||||
───────────────────────────────────────── ← Line 1
|
||||
───────────────────────────────────────── ← Line 2
|
||||
───────────────────────────────────────── ← Line 3
|
||||
───────────────────────────────────────── ← Line 4
|
||||
```
|
||||
|
||||
**Analysis:**
|
||||
- **Type:** Body text / Paragraph
|
||||
- **Lines:** 4
|
||||
- **Line thickness:** Thinnest in sketch → **Regular** (font-weight: 400)
|
||||
- **Distance between lines:** Matches icon/scrollbar size → **~16-20px font-size**
|
||||
- **Line-height:** ~1.5 (calculated from spacing)
|
||||
- **Alignment:** Left
|
||||
- **Capacity:** ~60-70 chars per line = 240-280 total
|
||||
|
||||
**Content Guidance:**
|
||||
```
|
||||
English: "Organize your family around dog care. Assign walks, track
|
||||
feeding schedules, and never miss a walk again. Perfect for busy
|
||||
families who want to ensure their dogs get the care they need."
|
||||
(206 chars) ✅
|
||||
|
||||
Swedish: "Organisera din familj kring hundvård. Tilldela promenader,
|
||||
spåra matscheman och missa aldrig en promenad igen. Perfekt för
|
||||
upptagna familjer som vill säkerställa att deras hundar får den
|
||||
vård de behöver." (218 chars) ✅
|
||||
```
|
||||
|
||||
### Example 3: Button Text
|
||||
|
||||
**Sketch shows:**
|
||||
```
|
||||
[────────────] ← Single line inside button shape
|
||||
```
|
||||
|
||||
**Analysis:**
|
||||
- **Type:** Button label
|
||||
- **Lines:** 1
|
||||
- **Line thickness:** Medium (relative) → **Semibold** (font-weight: 600)
|
||||
- **Estimated font-size:** ~16-18px (button standard)
|
||||
- **Capacity:** ~8-12 characters
|
||||
|
||||
**Content Guidance:**
|
||||
```
|
||||
English: "Get Started" (11 chars) ✅
|
||||
Swedish: "Kom Igång" (9 chars) ✅
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Agent Instructions
|
||||
|
||||
When analyzing sketches with text placeholders:
|
||||
|
||||
### Step 1: Count the Lines
|
||||
```
|
||||
How many horizontal bar groups do you see?
|
||||
```
|
||||
|
||||
### Step 2: Compare Line Thickness → Font Weight
|
||||
```
|
||||
Line thickness indicates font weight (RELATIVE comparison):
|
||||
- Thickest lines → Bold (font-weight: 700)
|
||||
- Thick lines → Semibold (font-weight: 600)
|
||||
- Medium lines → Medium (font-weight: 500)
|
||||
- Thin lines → Regular (font-weight: 400)
|
||||
- Thinnest lines → Light (font-weight: 300)
|
||||
```
|
||||
|
||||
### Step 3: Compare Distance to UI Elements → Font Size
|
||||
```
|
||||
Vertical spacing relative to context anchors:
|
||||
- Matches Button Height → ~40-48px font (Large Heading)
|
||||
- Matches Address Bar → ~32-40px font (Medium Heading)
|
||||
- Between Button & Icon → ~24-32px font (Small Heading)
|
||||
- Matches Icon/Scrollbar → ~16-24px font (Body Text)
|
||||
- Half Icon Size → ~12-16px font (Caption/Small Text)
|
||||
|
||||
⚠️ If spacing is disproportionately large, verify this is text (not image/box)!
|
||||
|
||||
NOTE: Visual size ≠ Semantic HTML level (H1/H2/H3).
|
||||
Semantic heading levels are determined by content structure, not appearance.
|
||||
```
|
||||
|
||||
### Step 4: Calculate Line-Height
|
||||
```
|
||||
Line-height = Distance between lines / Font size
|
||||
|
||||
Example:
|
||||
- Distance: 28px
|
||||
- Font size: 24px
|
||||
- Line-height: 28 / 24 = 1.16 ≈ 1.2
|
||||
```
|
||||
|
||||
### Step 5: Calculate Capacity
|
||||
```
|
||||
Lines × Characters-per-line = Total capacity
|
||||
|
||||
Example:
|
||||
5 lines × 60 chars/line = 300 characters
|
||||
```
|
||||
|
||||
### Step 6: Generate Content Guidance
|
||||
```
|
||||
"Content should be: [type], [line count] lines, ~[total chars] characters"
|
||||
|
||||
Example:
|
||||
"Content should be: Full paragraph, 5 lines, ~300 characters"
|
||||
```
|
||||
|
||||
### Step 7: Validate Content
|
||||
```
|
||||
If user provides content:
|
||||
- Count actual characters
|
||||
- Compare to capacity
|
||||
- Warn if mismatch
|
||||
|
||||
Example:
|
||||
⚠️ Your content (450 chars) exceeds sketch capacity (300 chars).
|
||||
Consider shortening or increasing font size.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Benefits of This Approach
|
||||
|
||||
✅ **Accurate Content Generation**
|
||||
- Content matches design space
|
||||
- No overflow or underflow issues
|
||||
- Professional fit and finish
|
||||
|
||||
✅ **Design Fidelity**
|
||||
- Specifications match sketches
|
||||
- Developers can trust the specs
|
||||
- Reduces back-and-forth
|
||||
|
||||
✅ **Multilingual Support**
|
||||
- Can estimate if translation fits
|
||||
- Adjust content length per language
|
||||
- Prevents UI breaking
|
||||
|
||||
✅ **Quality Assurance**
|
||||
- Catches content length issues early
|
||||
- Ensures consistency
|
||||
- Professional output
|
||||
|
||||
---
|
||||
|
||||
## Example in Action
|
||||
|
||||
**User shares Dog Week sketch of profile setup page**
|
||||
|
||||
**Agent analyzes:**
|
||||
|
||||
> "Looking at the profile section heading, I see 2 thick horizontal lines, center-aligned at the top.
|
||||
>
|
||||
> **Analysis:**
|
||||
> - 2 lines of text (thick bars)
|
||||
> - Line thickness: Thick (relative) → Bold weight
|
||||
> - Spacing: Less than button height → ~28-32px font
|
||||
> - Line-height: ~1.3 (calculated)
|
||||
> - Alignment: Center
|
||||
> - Capacity: ~50-60 characters (25-30 per line)
|
||||
>
|
||||
> **This heading should be:** Brief, 2 short lines, ~50-60 characters total
|
||||
>
|
||||
> **Suggested content:**
|
||||
> - EN: "Complete Your / Profile Setup" (41 chars) ✅
|
||||
> - SV: "Slutför Din / Profilinställning" (45 chars) ✅
|
||||
>
|
||||
> Both fit comfortably within the designed space. Does this match your intent?"
|
||||
|
||||
---
|
||||
|
||||
## Integration with WDS Workflow
|
||||
|
||||
This analysis happens automatically in:
|
||||
- **4B: Sketch Analysis** - Initial detection
|
||||
- **object-types/heading-text.md** - Detailed analysis
|
||||
- **4C-04: Content & Languages** - Content validation
|
||||
- **4C-08: Generate Spec** - Final documentation
|
||||
|
||||
**Result:** Every text element in WDS specifications includes accurate character capacity and content guidance! 🎨✨
|
||||
|
||||
---
|
||||
|
||||
*This guide ensures all WDS projects generate content that perfectly fits the designed space.*
|
||||
|
||||
|
|
@ -0,0 +1,206 @@
|
|||
# Quick Reference: Sketch Text Analysis
|
||||
|
||||
**The Correct Interpretation**
|
||||
|
||||
---
|
||||
|
||||
## Step 0: Establish Scale (Holistic View)
|
||||
|
||||
**Before analyzing specific text, scan the ENTIRE sketch to establish scale.**
|
||||
|
||||
1. **Find UI Anchors:** Look for standard UI elements (Browser chrome, Scrollbars, Buttons, Icons).
|
||||
2. **Check Project References:** Look at other sketches in the same project for established text styles.
|
||||
3. **Determine Base Unit:** If a Scrollbar is "Standard Width" (e.g., 16px), how big is everything else relative to it?
|
||||
4. **Calibrate:** Use these known objects to calibrate your eye for this specific image resolution.
|
||||
|
||||
### Cross-Page Reference Strategy
|
||||
|
||||
**If body text was defined on the Start Page:**
|
||||
- Start Page body text: Spacing matches icon size → 16px Regular
|
||||
- **Current page:** Similar thin lines with icon-sized spacing → **Same: 16px Regular**
|
||||
|
||||
**Benefits:**
|
||||
- ✅ Maintains visual consistency across pages
|
||||
- ✅ Builds design system patterns naturally
|
||||
- ✅ Reduces guesswork on subsequent pages
|
||||
- ✅ Creates coherent user experience
|
||||
|
||||
**When to use:**
|
||||
- Body text, captions, button labels (common across pages)
|
||||
- Navigation items (should be identical)
|
||||
- Form labels and inputs (standardized patterns)
|
||||
|
||||
---
|
||||
|
||||
## The Two Key Measurements
|
||||
|
||||
### 1. Line Thickness = Font Weight (Relative)
|
||||
|
||||
**Compare lines against each other in the sketch:**
|
||||
|
||||
```
|
||||
═══════════════════ ← Thicker than others = Bold (700)
|
||||
─────────────────── ← Medium thickness = Medium (500)
|
||||
───────────────────── ← Thinnest lines = Regular (400)
|
||||
```
|
||||
|
||||
**Rule:** Relative thickness indicates hierarchy, not absolute pixels.
|
||||
|
||||
### 2. Vertical Spacing = Font Size (Context-Based)
|
||||
|
||||
**Estimate size by comparing to known UI elements:**
|
||||
|
||||
```
|
||||
[ Button ] ← Standard height ref (~40-48px)
|
||||
↕
|
||||
═══════════════════ ← Matches button height? ~40-48px (Large Heading)
|
||||
↕
|
||||
═══════════════════
|
||||
```
|
||||
|
||||
**Context Anchors:**
|
||||
- **Browser Address Bar**: ~40px height
|
||||
- **Standard Button**: ~40-48px height
|
||||
- **Cursor/Icon**: ~16-24px size
|
||||
- **Scrollbar**: ~16px width
|
||||
|
||||
**Rule:** Use these anchors to estimate the scale of text spacing.
|
||||
|
||||
**Note:** Visual size ≠ Semantic HTML (H1/H2/H3). Heading levels are determined by document structure, not appearance.
|
||||
|
||||
---
|
||||
|
||||
## Complete Analysis Pattern
|
||||
|
||||
### Example: Hero Headline
|
||||
|
||||
**Sketch:**
|
||||
```
|
||||
═══════════════════════════════ ← Line 1: Thickest lines in sketch
|
||||
↕ Spacing ≈ Same as button height
|
||||
═══════════════════ ← Line 2: Thickest lines in sketch
|
||||
```
|
||||
|
||||
**Analysis:**
|
||||
- **Context:** Spacing looks similar to the "Sign In" button height nearby.
|
||||
- **Inference:** If button is ~48px, this font is ~48px (Large Heading).
|
||||
- **Weight:** Thicker than body text markers → **Bold**.
|
||||
- **Result:** `font: bold 48px / 1.2`
|
||||
|
||||
---
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Large Heading (Page Title)
|
||||
```
|
||||
═══════════════════ ← Thickest lines
|
||||
↕
|
||||
═══════════════════
|
||||
```
|
||||
- **Clue:** Spacing matches Address Bar height (~40px)
|
||||
- **Est:** ~40-48px, Bold
|
||||
|
||||
### Medium Heading (Section Title)
|
||||
```
|
||||
═══════════════════ ← Medium-Thick lines
|
||||
↕
|
||||
═══════════════════
|
||||
```
|
||||
- **Clue:** Spacing is slightly less than button height
|
||||
- **Est:** ~32px, Semibold
|
||||
|
||||
### Body Text (Paragraph)
|
||||
```
|
||||
───────────────────── ← Thinnest lines
|
||||
↕
|
||||
─────────────────────
|
||||
```
|
||||
- **Clue:** Spacing matches scrollbar width or small icon (~16-24px)
|
||||
- **Est:** ~16px, Regular
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Confusion Warning
|
||||
|
||||
### Text (Normal)
|
||||
```
|
||||
═══════════════════
|
||||
↕ Spacing < 2x Button Height
|
||||
═══════════════════
|
||||
```
|
||||
✅ Likely TEXT
|
||||
|
||||
### Image/Box (Too Large)
|
||||
```
|
||||
═══════════════════
|
||||
|
||||
|
||||
↕ Spacing > 2x Button Height
|
||||
|
||||
|
||||
═══════════════════
|
||||
```
|
||||
❓ Likely IMAGE or CONTAINER
|
||||
|
||||
**Rule:** If spacing seems disproportionately large compared to UI elements, verify!
|
||||
|
||||
---
|
||||
|
||||
## Quick Decision Tree
|
||||
|
||||
```
|
||||
See horizontal lines?
|
||||
│
|
||||
├─ Compare THICKNESS (Relative)
|
||||
│ └─ Thicker than avg? → Bold
|
||||
│ └─ Thinner than avg? → Regular
|
||||
│
|
||||
├─ Compare DISTANCE (Context)
|
||||
│ └─ Matches Button Height? → Large Heading (~40-48px)
|
||||
│ └─ Matches Icon Size? → Body Text (~16-24px)
|
||||
│ └─ Huge Gap? → Image/Container
|
||||
│
|
||||
└─ Check Context Anchors
|
||||
└─ Address Bar, Scrollbar, Buttons
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Memory Aid
|
||||
|
||||
**THICKNESS = RELATIVE WEIGHT**
|
||||
**CONTEXT = SCALE**
|
||||
|
||||
Think of it like looking at a map:
|
||||
- Use the scale key (buttons, bars) to measure distances.
|
||||
- Don't guess miles (pixels) without a reference!
|
||||
|
||||
---
|
||||
|
||||
## Real Dog Week Example
|
||||
|
||||
```
|
||||
═══════════════════════════════ ← Thickest lines
|
||||
↕ Matches "Sign In" button height
|
||||
═══════════════════ ← Thickest lines
|
||||
```
|
||||
|
||||
**Analysis:**
|
||||
- Thickness: Bold (relative to body lines)
|
||||
- Distance: Matches button (~48px)
|
||||
- Result: `font: bold 48px / 1.2`
|
||||
|
||||
**Content:**
|
||||
```
|
||||
EN: "Every walk. on time. Every time."
|
||||
SE: "Varje promenad. i tid. Varje gång."
|
||||
```
|
||||
|
||||
Both fit in ~50-60 character capacity! ✅
|
||||
|
||||
---
|
||||
|
||||
**Remember: Context is King! Compare, don't just measure.** 📏✨
|
||||
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,480 @@
|
|||
# Sketch Text Strategy: Actual Text vs. Markers
|
||||
|
||||
**Guidance for Creating WDS Sketches**
|
||||
|
||||
---
|
||||
|
||||
## The Two Approaches
|
||||
|
||||
### 1. Actual Text (Recommended for Headlines)
|
||||
|
||||
**Draw readable text directly in sketch**
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ │
|
||||
│ Every walk. on time. │
|
||||
│ Every time. │
|
||||
│ │
|
||||
│ [Get Started - Free Forever] │
|
||||
│ │
|
||||
└─────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**When to use:**
|
||||
- Headlines (H1, H2, H3)
|
||||
- Button labels
|
||||
- Navigation items
|
||||
- CTAs (calls-to-action)
|
||||
- Any short, important text
|
||||
|
||||
**Why:**
|
||||
✅ Agent can read and interpret text
|
||||
✅ Provides content context
|
||||
✅ Shows character count naturally
|
||||
✅ Guides design decisions
|
||||
✅ Can still be refined during specification
|
||||
|
||||
### 2. Horizontal Line Markers (For Body Text)
|
||||
|
||||
**Draw lines to indicate text blocks**
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ │
|
||||
│ ─────────────────────────────────── │ ← Body text
|
||||
│ ─────────────────────────────────── │
|
||||
│ ─────────────────────────────────── │
|
||||
│ ─────────────────────────────────── │
|
||||
│ │
|
||||
└─────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**When to use:**
|
||||
- Body paragraphs
|
||||
- Long descriptions
|
||||
- Feature lists (when wording TBD)
|
||||
- Content where you want to show SIZE, not specific text
|
||||
|
||||
**Why:**
|
||||
✅ Faster to sketch
|
||||
✅ Shows font size (distance between lines)
|
||||
✅ Shows font weight (line thickness)
|
||||
✅ Indicates capacity without committing to content
|
||||
✅ Focuses on layout, not copywriting
|
||||
|
||||
---
|
||||
|
||||
## Mixed Approach (Recommended)
|
||||
|
||||
**Combine both methods for best results:**
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────┐
|
||||
│ │
|
||||
│ Welcome to Dog Week │ ← ACTUAL TEXT (H1)
|
||||
│ │
|
||||
│ ─────────────────────────────────────── │ ← LINE MARKERS
|
||||
│ ─────────────────────────────────────── │ ← (Body paragraph)
|
||||
│ ─────────────────────────────────────── │
|
||||
│ ─────────────────────────────────────── │
|
||||
│ │
|
||||
│ [Start Planning] │ ← ACTUAL TEXT (CTA)
|
||||
│ │
|
||||
└──────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Result:**
|
||||
- Headlines provide content guidance
|
||||
- Body text shows sizing and capacity
|
||||
- Buttons show clear actions
|
||||
- Fast to sketch, still informative
|
||||
|
||||
---
|
||||
|
||||
## Dog Week Example
|
||||
|
||||
### Start Page Hero Sketch
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────┐
|
||||
│ │
|
||||
│ 🐕 Dog Week │ ← Logo (actual)
|
||||
│ [Sign In] SE ▼ │ ← Buttons (actual)
|
||||
│ │
|
||||
│ │
|
||||
│ Every walk. on time. │ ← H1 (actual text)
|
||||
│ Every time. │
|
||||
│ │
|
||||
│ ──────────────────────────────────────── │ ← Subtext (markers)
|
||||
│ ──────────────────────────────────────── │
|
||||
│ │
|
||||
│ [start planning - free forever] │ ← CTA (actual)
|
||||
│ │
|
||||
│ ┌───────────────────────────────────────┐ │
|
||||
│ │ │ │
|
||||
│ │ [Person with dog image] │ │ ← Image placeholder
|
||||
│ │ │ │
|
||||
│ └───────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ Never ask whose turn it is again │ ← Small text (actual)
|
||||
│ │
|
||||
│ ─────────────────────────────────────────│ ← Feature description
|
||||
│ ─────────────────────────────────────────│ ← (markers)
|
||||
│ ─────────────────────────────────────────│
|
||||
│ │
|
||||
└─────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Agent Analysis
|
||||
|
||||
**Agent reads:**
|
||||
1. **Logo text:** "Dog Week" → suggests as logo content
|
||||
2. **H1 actual text:** "Every walk. on time. Every time." → suggests as starting headline
|
||||
3. **Marker analysis:** 2 thin lines → body text, spacing matches icon size (~16-20px), ~120-140 chars
|
||||
4. **CTA actual text:** "start planning - free forever" → suggests as button label
|
||||
5. **Small actual text:** "Never ask whose turn it is again" → suggests as supporting text
|
||||
6. **Marker analysis:** 3 thin lines → feature description, spacing matches icon size (~16-20px), ~180-210 chars
|
||||
|
||||
**Agent output:**
|
||||
```
|
||||
I found text in your sketch: "Every walk. on time. Every time."
|
||||
|
||||
Would you like to use this for the Primary Headline, or change it?
|
||||
|
||||
EN: Every walk. on time. Every time.
|
||||
SE: [Your Swedish translation]
|
||||
```
|
||||
|
||||
**User can:**
|
||||
- ✅ Keep the sketch text
|
||||
- ✅ Change it completely
|
||||
- ✅ Refine it slightly
|
||||
|
||||
---
|
||||
|
||||
## Technical Details for Markers
|
||||
|
||||
### Line Thickness → Font Weight (Relative)
|
||||
|
||||
```
|
||||
═══════════════════ ← Thickest = Bold (700)
|
||||
─────────────────── ← Medium = Medium (500)
|
||||
───────────────────── ← Thinnest = Regular (400)
|
||||
```
|
||||
|
||||
**Compare relative thickness within the sketch, not absolute pixels.**
|
||||
|
||||
### Distance Between Lines → Font Size (Context-Based)
|
||||
|
||||
```
|
||||
═══════════════════
|
||||
↕ ~Button Height ← H1 (~40-48px)
|
||||
═══════════════════
|
||||
|
||||
───────────────────
|
||||
↕ ~Icon Size ← Body (~16-20px)
|
||||
───────────────────
|
||||
```
|
||||
|
||||
**Use UI elements (buttons, icons, scrollbars) as scale references.**
|
||||
|
||||
### Complete Example
|
||||
|
||||
```
|
||||
═══════════════════ ← Thickest lines in sketch
|
||||
↕ ~Button Height
|
||||
═══════════════════ ← Thickest lines in sketch
|
||||
```
|
||||
|
||||
**Analysis:**
|
||||
- Thickness: Bold (relative to other text)
|
||||
- Distance: Matches button height (~40-48px)
|
||||
- Lines: 2
|
||||
- Capacity: ~50-60 chars
|
||||
|
||||
---
|
||||
|
||||
## Agent Behavior
|
||||
|
||||
### When Sketch Has Actual Text
|
||||
|
||||
**Agent says:**
|
||||
```
|
||||
I found text in your sketch: "Every walk. on time."
|
||||
|
||||
Content for Primary Headline:
|
||||
|
||||
EN: Every walk. on time.
|
||||
SE:
|
||||
|
||||
(You can keep the sketch text or change it)
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- Pre-filled starting point
|
||||
- Still editable
|
||||
- Saves time
|
||||
- Provides context
|
||||
|
||||
### When Sketch Has Line Markers
|
||||
|
||||
**Agent says:**
|
||||
```
|
||||
Text placeholder detected:
|
||||
- 4 horizontal lines
|
||||
- Line thickness: Thinnest → Regular weight
|
||||
- Distance: Matches icon/scrollbar size → ~16-20px font
|
||||
- Capacity: ~240-280 characters
|
||||
|
||||
Content for Feature Description:
|
||||
|
||||
Please provide content in one language, and I'll suggest translations!
|
||||
|
||||
EN:
|
||||
```
|
||||
|
||||
**User provides:**
|
||||
```
|
||||
EN: Organize your family around dog care. Assign walks, track feeding schedules, and never miss a walk again.
|
||||
```
|
||||
|
||||
**Agent suggests:**
|
||||
```
|
||||
Great! Here are translation suggestions:
|
||||
|
||||
SE: Organisera din familj kring hundvård. Tilldela promenader, spåra matscheman och missa aldrig en promenad igen.
|
||||
|
||||
Does this work, or would you like to adjust it?
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- Clear capacity guidance
|
||||
- Agent suggests translations
|
||||
- User reviews and confirms
|
||||
- Helps with content length
|
||||
|
||||
---
|
||||
|
||||
## Workflow: From Analysis to Specification
|
||||
|
||||
When AI analyzes sketch text markers, the workflow is:
|
||||
|
||||
### Step 1: AI Analyzes Sketch
|
||||
Agent detects text markers and estimates properties:
|
||||
```
|
||||
Line thickness: Thicker than body text → Bold font weight
|
||||
Spacing between pairs: Similar to button height → ~40-48px font size estimate
|
||||
Line-height: ~1.2 (calculated from font size)
|
||||
Character capacity: ~35 characters per line
|
||||
```
|
||||
|
||||
### Step 2: AI Presents Estimates with Reasoning
|
||||
Agent shows analysis WITH explanation of how estimates were derived:
|
||||
```markdown
|
||||
- **Style**:
|
||||
- Font weight: Bold (from thick line markers, relative to body text)
|
||||
- Font size: 42px (est. from spacing matching button height)
|
||||
- Line-height: 1.2 (est. calculated as font-size × 1.2)
|
||||
```
|
||||
|
||||
**Why show reasoning?**
|
||||
- Designer understands **how** AI interpreted the sketch
|
||||
- Designer can judge if estimation logic makes sense
|
||||
- Makes it easy to adjust if sketch measurements were different
|
||||
- Builds trust through transparency
|
||||
|
||||
### Step 3: Designer Confirms/Adjusts
|
||||
Designer reviews estimates and either:
|
||||
1. **Confirms** - "Yes, 42px based on button-height spacing is correct"
|
||||
2. **Adjusts** - "Actually, the spacing is larger, make it 48px instead"
|
||||
3. **Overrides** - "Ignore the sketch measurements, I want it to be 56px"
|
||||
|
||||
### Step 4: Finalize Specification
|
||||
Agent updates spec with confirmed values, removes estimation notes:
|
||||
```markdown
|
||||
- **Style**:
|
||||
- Font weight: Bold
|
||||
- Font size: 48px
|
||||
- Line-height: 1.15
|
||||
```
|
||||
|
||||
Clean, production-ready specification with no estimation artifacts.
|
||||
|
||||
**Key Principle:**
|
||||
- **All estimated values are spelled out explicitly** (not hidden)
|
||||
- **Marked with (est.) label** to indicate AI interpretation
|
||||
- **Designer confirms or adjusts** each estimated value
|
||||
- **Label removed** once designer specifies actual values
|
||||
|
||||
This ensures **transparency** about which values came from AI sketch analysis vs. designer specification.
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### ✅ DO:
|
||||
|
||||
1. **Use actual text for headlines**
|
||||
- Provides content direction
|
||||
- Agent can read and suggest
|
||||
- Still changeable during spec
|
||||
|
||||
2. **Use markers for body text**
|
||||
- Shows sizing without committing
|
||||
- Faster to sketch
|
||||
- Focuses on layout
|
||||
|
||||
3. **Mix both approaches**
|
||||
- Headlines = actual text
|
||||
- Body = markers
|
||||
- Best of both worlds
|
||||
|
||||
4. **Keep sketch text informal**
|
||||
- It's a suggestion, not final
|
||||
- Can be refined later
|
||||
- Agent will ask to confirm/change
|
||||
|
||||
### ❌ DON'T:
|
||||
|
||||
1. **Don't use Lorem Ipsum**
|
||||
- Not helpful for context
|
||||
- Agent can't interpret
|
||||
- Use real(ish) content or markers
|
||||
|
||||
2. **Don't commit too early**
|
||||
- Sketch text is guidance
|
||||
- Refinement happens in spec phase
|
||||
- Stay flexible
|
||||
|
||||
3. **Don't mix for same element**
|
||||
- Either actual text OR markers
|
||||
- Not both for one text block
|
||||
- Confuses analysis
|
||||
|
||||
---
|
||||
|
||||
## Workflow Integration
|
||||
|
||||
### During Sketching
|
||||
|
||||
**Designer:**
|
||||
```
|
||||
1. Draw page layout
|
||||
2. Add ACTUAL TEXT for headlines/buttons
|
||||
3. Add LINE MARKERS for body paragraphs
|
||||
4. Show font weight (thickness)
|
||||
5. Show font size (distance)
|
||||
```
|
||||
|
||||
### During Specification (Phase 4)
|
||||
|
||||
**Agent:**
|
||||
```
|
||||
1. Analyze sketch
|
||||
2. Read any actual text found
|
||||
3. Suggest sketch text as starting point
|
||||
4. Analyze markers for sizing
|
||||
5. Request final content
|
||||
6. Allow refinement
|
||||
7. Document in spec
|
||||
```
|
||||
|
||||
**User:**
|
||||
```
|
||||
1. See sketch text as suggestion
|
||||
2. Keep, change, or refine
|
||||
3. Add translations
|
||||
4. Confirm length fits capacity
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Real Dog Week Flow
|
||||
|
||||
### Sketch Shows:
|
||||
|
||||
```
|
||||
Every walk. on time. Every time. ← Actual text in sketch
|
||||
```
|
||||
|
||||
### Agent Says:
|
||||
|
||||
```
|
||||
I found text in your sketch: "Every walk. on time. Every time."
|
||||
|
||||
Let me suggest translations...
|
||||
|
||||
Suggested content for Primary Headline:
|
||||
|
||||
EN: Every walk. on time. Every time.
|
||||
SE: Varje promenad. i tid. Varje gång.
|
||||
|
||||
These are my suggestions. Do they work?
|
||||
|
||||
1. Use these translations
|
||||
2. Adjust translations
|
||||
3. Manual input
|
||||
|
||||
Choice [1/2/3]:
|
||||
```
|
||||
|
||||
### User Says:
|
||||
|
||||
```
|
||||
1 ← Accepts!
|
||||
```
|
||||
|
||||
Or refines:
|
||||
|
||||
```
|
||||
2
|
||||
|
||||
SE: Varje promenad. Punktligt. Varje gång. ← Adjusted
|
||||
```
|
||||
EN: Every walk. on time. Every time. ← Keeps it!
|
||||
SE: Varje promenad. i tid. Varje gång.
|
||||
```
|
||||
|
||||
### Specification Result:
|
||||
|
||||
```markdown
|
||||
#### Primary Headline
|
||||
**OBJECT ID**: `start-hero-headline`
|
||||
- **Component**: H1 heading
|
||||
- **Position**: Center of hero
|
||||
- **Style**: Bold, 42px, line-height 1.2
|
||||
- **Content**:
|
||||
- EN: "Every walk. on time. Every time."
|
||||
- SE: "Varje promenad. i tid. Varje gång."
|
||||
```
|
||||
|
||||
**Result:** Sketch text became final content! ✅
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
| Element Type | Sketch Method | Agent Behavior |
|
||||
|--------------|---------------|----------------|
|
||||
| **Headlines** | Actual text | Reads & suggests as starting content |
|
||||
| **Buttons** | Actual text | Reads & suggests as button label |
|
||||
| **Navigation** | Actual text | Reads & suggests as nav items |
|
||||
| **Body paragraphs** | Line markers | Analyzes for size/capacity, requests content |
|
||||
| **Descriptions** | Line markers | Analyzes for size/capacity, requests content |
|
||||
|
||||
**Golden Rule:**
|
||||
- **Important/short text** = Draw actual text
|
||||
- **Long/placeholder text** = Use line markers
|
||||
- **Mix both** for best results
|
||||
|
||||
**Remember:**
|
||||
- Sketch text is a suggestion, not final
|
||||
- Agent will ask to confirm or change
|
||||
- Refinement happens during specification
|
||||
- Stay flexible, iterate as needed
|
||||
|
||||
---
|
||||
|
||||
**Use actual text for headlines, markers for body text!** 📝✨
|
||||
|
||||
|
|
@ -0,0 +1,676 @@
|
|||
# Storyboard Integration Guide
|
||||
|
||||
**Using Visual Storyboards to Document Complex Component Functionality**
|
||||
|
||||
---
|
||||
|
||||
## Problem Statement
|
||||
|
||||
Complex interactive components (calendars, booking systems, multi-step workflows) have **state transitions** and **interaction flows** that are difficult to describe in text alone.
|
||||
|
||||
**Storyboards** provide visual, sequential documentation of:
|
||||
- State transitions (e.g., Empty → Booked → Active → Completed)
|
||||
- User interactions and system responses
|
||||
- Time-based changes (countdowns, timers)
|
||||
- Multi-step workflows
|
||||
|
||||
---
|
||||
|
||||
## Storyboard Types
|
||||
|
||||
### 1. **State Transition Storyboards**
|
||||
|
||||
**Purpose:** Show how a component changes states over time
|
||||
|
||||
**Example:** Dog Week Walk Booking States
|
||||
```
|
||||
┌─────────────────────────────────────────────────┐
|
||||
│ State Transition Storyboard │
|
||||
│ Component: Walk Time Slot Card │
|
||||
├─────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ 1. WHITE (Empty) → User books │
|
||||
│ [Dog icon] 8-11 → [Book button] │
|
||||
│ │
|
||||
│ 2. GRAY (Booked) → Time arrives │
|
||||
│ [Dog+User] 8-11 │
|
||||
│ │
|
||||
│ 3. ORANGE (Countdown) → User starts │
|
||||
│ [Dog icon] 32 min left → [Start button] │
|
||||
│ │
|
||||
│ 4. BLUE (In Progress) → User completes │
|
||||
│ [Dog+User] Started 09:32 • 23 min ago │
|
||||
│ │
|
||||
│ 5. GREEN (Completed) → Final state │
|
||||
│ [Dog+User] 32 min walk ✓ │
|
||||
│ │
|
||||
│ Alt: RED (Missed) → Window expired │
|
||||
│ [Dog icon] No walk registered ⊖ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**File:** `Sketches/App-Main-Booking-States.jpg` (Dog Week example)
|
||||
|
||||
### 2. **Interaction Flow Storyboards**
|
||||
|
||||
**Purpose:** Show step-by-step user interactions
|
||||
|
||||
**Example:** Calendar Booking Flow
|
||||
```
|
||||
Frame 1: User views calendar
|
||||
Frame 2: User taps "Book" button
|
||||
Frame 3: Card transitions to GRAY state
|
||||
Frame 4: Leaderboard updates (+1 point)
|
||||
Frame 5: Week overview quarter circle turns gray
|
||||
```
|
||||
|
||||
### 3. **Multi-Component Storyboards**
|
||||
|
||||
**Purpose:** Show how multiple components interact
|
||||
|
||||
**Example:** Week View + Leaderboard + Calendar Sync
|
||||
```
|
||||
Frame 1: User clicks day circle in week overview
|
||||
Frame 2: Calendar scrolls to that day
|
||||
Frame 3: User books walk
|
||||
Frame 4: Week overview quarter circle updates
|
||||
Frame 5: Leaderboard count increments
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration with Modular Structure
|
||||
|
||||
### Where Storyboards Belong
|
||||
|
||||
| File Type | Contains Storyboard? | Purpose |
|
||||
|-----------|---------------------|---------|
|
||||
| **Pages/** | ❌ No | Page layout only |
|
||||
| **Components/** | ⚠️ Visual states only | Static appearance of each state |
|
||||
| **Features/** | ✅ YES | State transitions & interaction flows |
|
||||
|
||||
### Storyboard Storage
|
||||
|
||||
```
|
||||
project-root/
|
||||
├─ Pages/
|
||||
│ └─ 02-calendar-page.md
|
||||
│
|
||||
├─ Components/
|
||||
│ └─ walk-slot-card.component.md
|
||||
│
|
||||
├─ Features/
|
||||
│ ├─ walk-booking-logic.feature.md
|
||||
│ └─ Storyboards/ ← NEW FOLDER
|
||||
│ ├─ walk-state-transitions.jpg
|
||||
│ ├─ booking-flow.jpg
|
||||
│ └─ calendar-sync-flow.jpg
|
||||
│
|
||||
└─ Sketches/ ← Existing page sketches
|
||||
└─ 02-calendar-page-sketch.jpg
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Feature File with Storyboard Reference
|
||||
|
||||
### Example: `walk-booking-logic.feature.md`
|
||||
|
||||
```markdown
|
||||
# Walk Booking Logic Feature
|
||||
|
||||
**Feature ID:** `walk-booking-logic`
|
||||
**Type:** State Machine with Time-Based Transitions
|
||||
**Complexity:** High
|
||||
|
||||
## Purpose
|
||||
|
||||
Manages walk slot state transitions, user booking interactions, and automatic time-based state changes for the Dog Week calendar.
|
||||
|
||||
---
|
||||
|
||||
## Visual Storyboard
|
||||
|
||||
**State Transition Flow:**
|
||||
|
||||
|
||||
|
||||
**Key:** This storyboard shows all 6 walk states and the triggers that cause transitions between them.
|
||||
|
||||
---
|
||||
|
||||
## State Definitions
|
||||
|
||||
### State 1: WHITE (Empty / Available)
|
||||
|
||||
**Visual Reference:** Storyboard Frame 1
|
||||
|
||||
**Appearance:**
|
||||
- White background
|
||||
- Dog avatar only (no user avatar)
|
||||
- Time range: "8-11"
|
||||
- Action button: "Book" / "Boka"
|
||||
|
||||
**Triggers:**
|
||||
- Initial state for all unbooked slots
|
||||
- Appears when walk is unbooked
|
||||
|
||||
**Transitions:**
|
||||
- User clicks "Book" → GRAY (Booked)
|
||||
|
||||
**Business Rules:**
|
||||
- Any family member can book
|
||||
- Booking awards +1 leaderboard point
|
||||
- Updates week overview quarter circle to gray
|
||||
|
||||
---
|
||||
|
||||
### State 2: GRAY (Booked / Scheduled)
|
||||
|
||||
**Visual Reference:** Storyboard Frame 2
|
||||
|
||||
**Appearance:**
|
||||
- Gray background
|
||||
- Dog avatar + User avatar overlay
|
||||
- Names: "Rufus & Patrick"
|
||||
- Time range: "8-11"
|
||||
- No action button (tap card for details)
|
||||
|
||||
**Triggers:**
|
||||
- User books empty slot (WHITE → GRAY)
|
||||
- Walk is scheduled but time window not yet open
|
||||
|
||||
**Transitions:**
|
||||
- Time window opens (8:00 arrives) → ORANGE (Countdown)
|
||||
- User unbooks walk → WHITE (Empty)
|
||||
|
||||
**Business Rules:**
|
||||
- Shows who booked the walk
|
||||
- Tap card to view details/unbook
|
||||
- Leaderboard point already awarded
|
||||
|
||||
---
|
||||
|
||||
### State 3: ORANGE (Window Open / Countdown)
|
||||
|
||||
**Visual Reference:** Storyboard Frame 3
|
||||
|
||||
**Appearance:**
|
||||
- Orange background
|
||||
- Dog avatar only (user avatar removed)
|
||||
- Countdown timer: "32 min left" / "32 min kvar"
|
||||
- Warning icon: ⚠️
|
||||
- Action button: "Start" / "Starta"
|
||||
|
||||
**Triggers:**
|
||||
- Scheduled time arrives (8:00) → GRAY to ORANGE
|
||||
- Real-time countdown updates every minute
|
||||
|
||||
**Transitions:**
|
||||
- User clicks "Start" → BLUE (In Progress)
|
||||
- Countdown reaches 0 (11:00) → RED (Missed)
|
||||
|
||||
**Business Rules:**
|
||||
- Countdown shows time remaining in window
|
||||
- Urgency indicator (warning icon)
|
||||
- Can only start if no other walk active for this dog
|
||||
|
||||
---
|
||||
|
||||
### State 4: BLUE (In Progress / Active Walk)
|
||||
|
||||
**Visual Reference:** Storyboard Frame 4
|
||||
|
||||
**Appearance:**
|
||||
- Blue background
|
||||
- Dog avatar + User avatar overlay
|
||||
- Status: "Started 09:32 • 23 min ago"
|
||||
- Refresh icon: ↻
|
||||
- No action button (tap card for completion)
|
||||
|
||||
**Triggers:**
|
||||
- User starts walk (ORANGE → BLUE)
|
||||
- Real-time duration updates every minute
|
||||
|
||||
**Transitions:**
|
||||
- User completes walk → GREEN (Completed)
|
||||
|
||||
**Business Rules:**
|
||||
- Blocks other walks for this dog
|
||||
- Shows elapsed time since start
|
||||
- Tap card to complete walk or view progress
|
||||
|
||||
---
|
||||
|
||||
### State 5: GREEN (Completed)
|
||||
|
||||
**Visual Reference:** Storyboard Frame 5
|
||||
|
||||
**Appearance:**
|
||||
- Green background
|
||||
- Dog avatar + User avatar overlay
|
||||
- Duration: "32 min walk" / "32 min promenad"
|
||||
- Checkmark icon: ✓
|
||||
- No action button
|
||||
|
||||
**Triggers:**
|
||||
- User completes active walk (BLUE → GREEN)
|
||||
|
||||
**Transitions:**
|
||||
- None (final successful state)
|
||||
|
||||
**Business Rules:**
|
||||
- Permanent record of completed walk
|
||||
- Shows actual walk duration
|
||||
- Unblocks dog for next walk
|
||||
|
||||
---
|
||||
|
||||
### State 6: RED (Missed / Overdue)
|
||||
|
||||
**Visual Reference:** Storyboard Frame 6
|
||||
|
||||
**Appearance:**
|
||||
- Red background
|
||||
- Dog avatar only (no user avatar)
|
||||
- Message: "No walk registered" / "Ingen promenad registrerad"
|
||||
- Minus icon: ⊖
|
||||
- No action button
|
||||
|
||||
**Triggers:**
|
||||
- Countdown expires without walk being started (ORANGE → RED)
|
||||
|
||||
**Transitions:**
|
||||
- None (permanent accountability record)
|
||||
|
||||
**Business Rules:**
|
||||
- Cannot be changed or deleted
|
||||
- Leaderboard point remains (no penalty)
|
||||
- Shows who booked but didn't complete
|
||||
|
||||
---
|
||||
|
||||
## Interaction Flows
|
||||
|
||||
### Flow 1: Successful Walk Booking & Completion
|
||||
|
||||
**Storyboard:** `Storyboards/booking-flow.jpg`
|
||||
|
||||
**Steps:**
|
||||
1. **User views empty slot** (WHITE state)
|
||||
- Sees "Book" button
|
||||
|
||||
2. **User taps "Book"**
|
||||
- System validates user is family member
|
||||
- System creates booking record
|
||||
|
||||
3. **Immediate updates:**
|
||||
- Card → GRAY state
|
||||
- Leaderboard: User +1 point
|
||||
- Week overview: Quarter circle → gray
|
||||
|
||||
4. **Time window opens** (8:00 arrives)
|
||||
- Card → ORANGE state
|
||||
- Countdown timer starts
|
||||
|
||||
5. **User taps "Start"**
|
||||
- System validates no other active walk for dog
|
||||
- System records start time
|
||||
|
||||
6. **Immediate updates:**
|
||||
- Card → BLUE state
|
||||
- Duration counter starts
|
||||
- Other walks for dog → disabled
|
||||
|
||||
7. **User completes walk** (via Walk Details page)
|
||||
- System records completion time
|
||||
- System calculates duration
|
||||
|
||||
8. **Immediate updates:**
|
||||
- Card → GREEN state
|
||||
- Week overview: Quarter circle → green
|
||||
- Other walks for dog → re-enabled
|
||||
|
||||
---
|
||||
|
||||
### Flow 2: Missed Walk
|
||||
|
||||
**Storyboard:** `Storyboards/missed-walk-flow.jpg`
|
||||
|
||||
**Steps:**
|
||||
1. Walk booked (GRAY state)
|
||||
2. Time window opens (ORANGE state)
|
||||
3. Countdown timer runs
|
||||
4. User doesn't start walk
|
||||
5. Countdown reaches 0 (11:00)
|
||||
6. **Automatic transition:** ORANGE → RED
|
||||
7. Permanent missed walk record created
|
||||
|
||||
---
|
||||
|
||||
### Flow 3: Multi-Component Sync
|
||||
|
||||
**Storyboard:** `Storyboards/calendar-sync-flow.jpg`
|
||||
|
||||
**Components Involved:**
|
||||
- Week Overview (top section)
|
||||
- Leaderboard (middle section)
|
||||
- Booking Calendar (bottom section)
|
||||
|
||||
**Sync Flow:**
|
||||
1. User books walk in calendar
|
||||
2. **Sync 1:** Week overview quarter circle updates
|
||||
3. **Sync 2:** Leaderboard count increments
|
||||
4. User starts walk
|
||||
5. **Sync 3:** Week overview quarter circle changes color
|
||||
6. User completes walk
|
||||
7. **Sync 4:** Week overview quarter circle turns green
|
||||
|
||||
---
|
||||
|
||||
## State Machine Diagram
|
||||
|
||||
```
|
||||
┌─────────────┐
|
||||
│ WHITE │
|
||||
│ (Empty) │
|
||||
└──────┬──────┘
|
||||
│ User books
|
||||
▼
|
||||
┌─────────────┐
|
||||
│ GRAY │
|
||||
│ (Booked) │
|
||||
└──────┬──────┘
|
||||
│ Time arrives
|
||||
▼
|
||||
┌─────────────┐
|
||||
│ ORANGE │◄──── Countdown timer
|
||||
│ (Countdown) │ updates every 1 min
|
||||
└──┬───────┬──┘
|
||||
│ │
|
||||
User starts │ │ Countdown expires
|
||||
│ │
|
||||
▼ ▼
|
||||
┌─────────┐ ┌─────────┐
|
||||
│ BLUE │ │ RED │
|
||||
│(Active) │ │(Missed) │
|
||||
└────┬────┘ └─────────┘
|
||||
│ │
|
||||
User completes │ │ Permanent
|
||||
│ │ record
|
||||
▼ ▼
|
||||
┌─────────┐ [END]
|
||||
│ GREEN │
|
||||
│(Complete)│
|
||||
└─────────┘
|
||||
│
|
||||
▼
|
||||
[END]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Storyboard Creation Guidelines
|
||||
|
||||
### When to Create Storyboards
|
||||
|
||||
Create storyboards for:
|
||||
- ✅ Components with 3+ states
|
||||
- ✅ Time-based transitions (countdowns, timers)
|
||||
- ✅ Multi-step user flows
|
||||
- ✅ Complex interactions between multiple components
|
||||
- ✅ State machines with branching paths
|
||||
|
||||
Don't need storyboards for:
|
||||
- ❌ Simple buttons (hover, active states)
|
||||
- ❌ Static content sections
|
||||
- ❌ Single-state components
|
||||
|
||||
### Storyboard Format
|
||||
|
||||
**Hand-drawn sketches** (recommended):
|
||||
- Quick to create
|
||||
- Easy to iterate
|
||||
- Focus on functionality, not polish
|
||||
- Example: Dog Week `App-Main-Booking-States.jpg`
|
||||
|
||||
**Digital wireframes:**
|
||||
- Use Figma, Sketch, or similar
|
||||
- More polished for client presentations
|
||||
- Easier to update
|
||||
|
||||
**Annotated screenshots:**
|
||||
- Use actual prototype screenshots
|
||||
- Add arrows and labels
|
||||
- Good for documenting existing systems
|
||||
|
||||
### Storyboard Numbering
|
||||
|
||||
Number frames sequentially:
|
||||
```
|
||||
1. Initial state
|
||||
2. After user action
|
||||
3. System response
|
||||
4. Next state
|
||||
5. Alternative path
|
||||
```
|
||||
|
||||
### Storyboard Annotations
|
||||
|
||||
Include:
|
||||
- **State names** (e.g., "ORANGE - Countdown")
|
||||
- **Trigger descriptions** (e.g., "User taps Start")
|
||||
- **Time indicators** (e.g., "After 32 minutes")
|
||||
- **Icons/symbols** for actions (→ for transitions, ⚠️ for warnings)
|
||||
|
||||
---
|
||||
|
||||
## Feature File Template with Storyboard
|
||||
|
||||
```markdown
|
||||
# {Feature Name} Feature
|
||||
|
||||
**Feature ID:** `{feature-id}`
|
||||
**Type:** {State Machine / Workflow / Calculator / etc.}
|
||||
**Complexity:** {Low / Medium / High}
|
||||
|
||||
## Purpose
|
||||
|
||||
{Brief description of what this feature does}
|
||||
|
||||
---
|
||||
|
||||
## Visual Storyboard
|
||||
|
||||
**{Storyboard Type}:**
|
||||
|
||||
|
||||
|
||||
**Key:** {Brief explanation of what the storyboard shows}
|
||||
|
||||
---
|
||||
|
||||
## State Definitions
|
||||
|
||||
{If applicable - for state machines}
|
||||
|
||||
### State 1: {State Name}
|
||||
|
||||
**Visual Reference:** Storyboard Frame {number}
|
||||
|
||||
**Appearance:**
|
||||
- {Visual description}
|
||||
|
||||
**Triggers:**
|
||||
- {What causes this state}
|
||||
|
||||
**Transitions:**
|
||||
- {What states this can transition to}
|
||||
|
||||
**Business Rules:**
|
||||
- {Rules governing this state}
|
||||
|
||||
---
|
||||
|
||||
## Interaction Flows
|
||||
|
||||
### Flow 1: {Flow Name}
|
||||
|
||||
**Storyboard:** `Storyboards/{flow-storyboard}.jpg`
|
||||
|
||||
**Steps:**
|
||||
1. {Step description}
|
||||
2. {Step description}
|
||||
3. {Step description}
|
||||
|
||||
---
|
||||
|
||||
## State Machine Diagram
|
||||
|
||||
{ASCII diagram showing state transitions}
|
||||
|
||||
---
|
||||
|
||||
## Data Requirements
|
||||
|
||||
{API endpoints, data models, etc.}
|
||||
|
||||
---
|
||||
|
||||
## Validation Rules
|
||||
|
||||
{Business rules, constraints, etc.}
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
{Error states, recovery flows, etc.}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Dog Week Example: Complete Structure
|
||||
|
||||
```
|
||||
Features/
|
||||
├─ walk-booking-logic.feature.md
|
||||
│ ├─ References: Storyboards/walk-state-transitions.jpg
|
||||
│ ├─ Contains: 6 state definitions
|
||||
│ └─ Contains: State machine diagram
|
||||
│
|
||||
├─ calendar-sync.feature.md
|
||||
│ ├─ References: Storyboards/calendar-sync-flow.jpg
|
||||
│ └─ Contains: Multi-component interaction flows
|
||||
│
|
||||
└─ Storyboards/
|
||||
├─ walk-state-transitions.jpg ← Main state storyboard
|
||||
├─ booking-flow.jpg ← Successful booking flow
|
||||
├─ missed-walk-flow.jpg ← Missed walk scenario
|
||||
├─ calendar-sync-flow.jpg ← Component sync flow
|
||||
└─ week-navigation-flow.jpg ← Week navigation interactions
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Benefits of Storyboard Integration
|
||||
|
||||
### 1. Visual Clarity
|
||||
|
||||
**Before (Text only):**
|
||||
```
|
||||
When the user books a walk, the card changes to gray,
|
||||
the leaderboard updates, and the week overview changes.
|
||||
```
|
||||
|
||||
**After (With storyboard):**
|
||||
```
|
||||
See Storyboard Frame 2-3 for visual state transition.
|
||||
```
|
||||
|
||||
### 2. Developer Understanding
|
||||
|
||||
Developers can:
|
||||
- See exact visual states
|
||||
- Understand transition triggers
|
||||
- Identify edge cases visually
|
||||
- Reference storyboard during implementation
|
||||
|
||||
### 3. Design Consistency
|
||||
|
||||
Designers can:
|
||||
- Ensure all states are visually distinct
|
||||
- Verify state transitions make sense
|
||||
- Spot missing states or transitions
|
||||
- Create Figma components matching storyboard
|
||||
|
||||
### 4. QA Testing
|
||||
|
||||
QA can:
|
||||
- Use storyboard as test script
|
||||
- Verify all states are implemented
|
||||
- Test all transition paths
|
||||
- Identify missing functionality
|
||||
|
||||
---
|
||||
|
||||
## Workflow Integration
|
||||
|
||||
### Step 1: Sketch Storyboard
|
||||
|
||||
During UX design phase:
|
||||
1. Identify complex interactive components
|
||||
2. Sketch state transitions on paper/whiteboard
|
||||
3. Number frames sequentially
|
||||
4. Add annotations for triggers and transitions
|
||||
5. Take photo or scan
|
||||
|
||||
### Step 2: Store Storyboard
|
||||
|
||||
```
|
||||
Features/Storyboards/{component-name}-{type}.jpg
|
||||
```
|
||||
|
||||
### Step 3: Reference in Feature File
|
||||
|
||||
```markdown
|
||||
## Visual Storyboard
|
||||
|
||||
|
||||
```
|
||||
|
||||
### Step 4: Document States
|
||||
|
||||
For each frame in storyboard:
|
||||
- Create state definition
|
||||
- Link to storyboard frame number
|
||||
- Describe triggers and transitions
|
||||
|
||||
### Step 5: Create State Machine
|
||||
|
||||
Convert storyboard to ASCII state machine diagram for quick reference
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
**Storyboards are essential for:**
|
||||
- 🎯 Complex state machines (calendars, booking systems)
|
||||
- 🎯 Multi-step workflows (onboarding, checkout)
|
||||
- 🎯 Time-based interactions (countdowns, timers)
|
||||
- 🎯 Multi-component synchronization
|
||||
|
||||
**Store storyboards in:**
|
||||
- `Features/Storyboards/` folder
|
||||
- Reference from Feature files
|
||||
- Link to specific frames in state definitions
|
||||
|
||||
**Benefits:**
|
||||
- ✅ Visual clarity for developers
|
||||
- ✅ Design consistency
|
||||
- ✅ QA test scripts
|
||||
- ✅ Stakeholder communication
|
||||
- ✅ Documentation that doesn't get stale
|
||||
|
||||
**Result:** Complex component functionality is documented visually and textually, making implementation and testing straightforward.
|
||||
|
|
@ -0,0 +1,454 @@
|
|||
# Translation Organization Guide
|
||||
|
||||
**Part of WDS Specification Pattern**
|
||||
|
||||
**Purpose-Based Naming with Grouped Translations**
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
This guide explains how to organize text content and translations in WDS specifications using **purpose-based naming** and **grouped translation** patterns.
|
||||
|
||||
**Related Documentation:**
|
||||
- **`SKETCH-TEXT-ANALYSIS-GUIDE.md`** - How to analyze text markers in sketches
|
||||
- **`HTML-VS-VISUAL-STYLES.md`** - HTML tags vs visual text styles
|
||||
- **`WDS-SPECIFICATION-PATTERN.md`** - Complete specification format with examples
|
||||
|
||||
---
|
||||
|
||||
## Core Principles
|
||||
|
||||
### 1. Name by PURPOSE, Not Content
|
||||
|
||||
**❌ WRONG:**
|
||||
```markdown
|
||||
#### Welcome Heading
|
||||
**OBJECT ID**: `start-hero-welcome-heading`
|
||||
- Content: "Welcome to Dog Week"
|
||||
```
|
||||
|
||||
**✅ CORRECT:**
|
||||
```markdown
|
||||
#### Primary Headline
|
||||
**OBJECT ID**: `start-hero-headline`
|
||||
- Content:
|
||||
- EN: "Welcome to Dog Week"
|
||||
- SE: "Välkommen till Dog Week"
|
||||
```
|
||||
|
||||
**Why:** If content changes to "Every walk. on time.", the Object ID still makes sense.
|
||||
|
||||
---
|
||||
|
||||
### 2. Separate Structure from Content
|
||||
|
||||
**Structure (Position/Style):**
|
||||
```markdown
|
||||
- **HTML Tag**: h1 (semantic structure for SEO/accessibility)
|
||||
- **Visual Style**: Hero headline (from Design System)
|
||||
- **Position**: Center of hero section, above CTA
|
||||
- **Style**:
|
||||
- Font weight: Bold (from 3px thick line markers)
|
||||
- Font size: 42px (est. from 24px spacing between line pairs)
|
||||
- Line-height: 1.2 (est. calculated from font size)
|
||||
- **Behavior**: Updates with language toggle
|
||||
```
|
||||
|
||||
> **Important:** HTML tags (h1-h6) define semantic structure for SEO/accessibility. Visual styles (Hero headline, Main header, Sub header, etc.) define appearance and can be applied to any HTML tag.
|
||||
|
||||
> **Note:** Values marked `(est. from...)` show sketch analysis reasoning. Designer should confirm or adjust these values, then update with actual specifications.
|
||||
```
|
||||
|
||||
**Content (Translations):**
|
||||
```markdown
|
||||
- **Content**:
|
||||
- EN: "Every walk. on time. Every time."
|
||||
- SE: "Varje promenad. i tid. Varje gång."
|
||||
```
|
||||
|
||||
**Why:** Structure rarely changes, content often does. Keeps specs clean.
|
||||
|
||||
---
|
||||
|
||||
### 3. Group Related Translations
|
||||
|
||||
**❌ WRONG (Scattered):**
|
||||
```markdown
|
||||
#### Headline EN
|
||||
"Every walk. on time."
|
||||
|
||||
#### Headline SE
|
||||
"Varje promenad. i tid."
|
||||
|
||||
#### Body EN
|
||||
"Organize your family..."
|
||||
|
||||
#### Body SE
|
||||
"Organisera din familj..."
|
||||
```
|
||||
|
||||
**✅ CORRECT (Grouped):**
|
||||
```markdown
|
||||
### Hero Object
|
||||
**Purpose**: Primary value proposition
|
||||
|
||||
#### Primary Headline
|
||||
**OBJECT ID**: `start-hero-headline`
|
||||
- **Content**:
|
||||
- EN: "Every walk. on time. Every time."
|
||||
- SE: "Varje promenad. i tid. Varje gång."
|
||||
|
||||
#### Supporting Text
|
||||
**OBJECT ID**: `start-hero-supporting`
|
||||
- **Content**:
|
||||
- EN: "Organize your family around dog care."
|
||||
- SE: "Organisera din familj kring hundvård."
|
||||
```
|
||||
|
||||
**Why:** Each language reads as complete, coherent message.
|
||||
|
||||
---
|
||||
|
||||
## Dog Week Examples
|
||||
|
||||
### Example 1: Hero Section (Text Group)
|
||||
|
||||
```markdown
|
||||
### Hero Object
|
||||
**Purpose**: Primary value proposition and main conversion action
|
||||
|
||||
#### Primary Headline
|
||||
**OBJECT ID**: `start-hero-headline`
|
||||
- **Component**: H1 heading (`.text-heading-1`)
|
||||
- **Position**: Center of hero, top of section
|
||||
- **Style**: Bold, no italic, 42px, line-height 1.2
|
||||
- **Behavior**: Updates with language toggle
|
||||
- **Content**:
|
||||
- EN: "Every walk. on time. Every time."
|
||||
- SE: "Varje promenad. i tid. Varje gång."
|
||||
|
||||
#### Supporting Text
|
||||
**OBJECT ID**: `start-hero-supporting`
|
||||
- **Component**: Body text (`.text-body`)
|
||||
- **Position**: Below headline, above CTA
|
||||
- **Style**: Regular, 16px, line-height 1.5
|
||||
- **Behavior**: Updates with language toggle
|
||||
- **Content**:
|
||||
- EN: "Organize your family around dog care. Never miss a walk again."
|
||||
- SE: "Organisera din familj kring hundvård. Missa aldrig en promenad igen."
|
||||
|
||||
#### Primary CTA Button
|
||||
**OBJECT ID**: `start-hero-cta`
|
||||
- **Component**: [Button Primary Large](/docs/D-Design-System/.../Button-Primary.md)
|
||||
- **Position**: Center, below supporting text
|
||||
- **Behavior**: Navigate to registration
|
||||
- **Content**:
|
||||
- EN: "start planning - free forever"
|
||||
- SE: "börja planera - gratis för alltid"
|
||||
```
|
||||
|
||||
**Reading Experience:**
|
||||
|
||||
**English:**
|
||||
> Every walk. on time. Every time.
|
||||
> Organize your family around dog care. Never miss a walk again.
|
||||
> [start planning - free forever]
|
||||
|
||||
**Swedish:**
|
||||
> Varje promenad. i tid. Varje gång.
|
||||
> Organisera din familj kring hundvård. Missa aldrig en promenad igen.
|
||||
> [börja planera - gratis för alltid]
|
||||
|
||||
Each language flows naturally as a complete message!
|
||||
|
||||
---
|
||||
|
||||
### Example 2: Form Labels (Individual Elements)
|
||||
|
||||
```markdown
|
||||
### Sign In Form
|
||||
**Purpose**: User authentication
|
||||
|
||||
#### Email Label
|
||||
**OBJECT ID**: `signin-form-email-label`
|
||||
- **Component**: Label text (`.text-label`)
|
||||
- **Position**: Above email input field
|
||||
- **For**: `signin-form-email-input`
|
||||
- **Content**:
|
||||
- EN: "Email Address"
|
||||
- SE: "E-postadress"
|
||||
|
||||
#### Email Input
|
||||
**OBJECT ID**: `signin-form-email-input`
|
||||
- **Component**: [Text Input](/docs/.../text-input.md)
|
||||
- **Placeholder**:
|
||||
- EN: "your@email.com"
|
||||
- SE: "din@epost.com"
|
||||
|
||||
#### Password Label
|
||||
**OBJECT ID**: `signin-form-password-label`
|
||||
- **Component**: Label text (`.text-label`)
|
||||
- **Position**: Above password input
|
||||
- **For**: `signin-form-password-input`
|
||||
- **Content**:
|
||||
- EN: "Password"
|
||||
- SE: "Lösenord"
|
||||
|
||||
#### Password Input
|
||||
**OBJECT ID**: `signin-form-password-input`
|
||||
- **Component**: [Password Input](/docs/.../password-input.md)
|
||||
- **Placeholder**:
|
||||
- EN: "Enter your password"
|
||||
- SE: "Ange ditt lösenord"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Example 3: Error Messages
|
||||
|
||||
```markdown
|
||||
### Validation Messages
|
||||
**Purpose**: User feedback on form errors
|
||||
|
||||
#### Email Required Error
|
||||
**OBJECT ID**: `signin-form-email-error-required`
|
||||
- **Component**: Error text (`.text-error`)
|
||||
- **Position**: Below email input field
|
||||
- **Trigger**: When email field is empty on submit
|
||||
- **Content**:
|
||||
- EN: "Email address is required"
|
||||
- SE: "E-postadress krävs"
|
||||
|
||||
#### Email Invalid Error
|
||||
**OBJECT ID**: `signin-form-email-error-invalid`
|
||||
- **Component**: Error text (`.text-error`)
|
||||
- **Position**: Below email input field
|
||||
- **Trigger**: When email format is invalid
|
||||
- **Content**:
|
||||
- EN: "Please enter a valid email address"
|
||||
- SE: "Ange en giltig e-postadress"
|
||||
|
||||
#### Auth Failed Error
|
||||
**OBJECT ID**: `signin-form-auth-error`
|
||||
- **Component**: Alert banner (`.alert-error`)
|
||||
- **Position**: Above form, below page heading
|
||||
- **Trigger**: When authentication fails
|
||||
- **Content**:
|
||||
- EN: "Invalid email or password. Please try again."
|
||||
- SE: "Ogiltig e-post eller lösenord. Försök igen."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Object ID Naming Patterns
|
||||
|
||||
### Format: `{page}-{section}-{purpose}`
|
||||
|
||||
**Page Examples:**
|
||||
- `start` (start/landing page)
|
||||
- `signin` (sign in page)
|
||||
- `profile` (profile page)
|
||||
- `calendar` (calendar page)
|
||||
|
||||
**Section Examples:**
|
||||
- `hero` (hero section)
|
||||
- `header` (page header)
|
||||
- `form` (form section)
|
||||
- `features` (features section)
|
||||
- `footer` (page footer)
|
||||
|
||||
**Purpose Examples:**
|
||||
- `headline` (main heading)
|
||||
- `subheading` (secondary heading)
|
||||
- `description` (descriptive text)
|
||||
- `cta` (call-to-action button)
|
||||
- `label` (form label)
|
||||
- `error` (error message)
|
||||
- `success` (success message)
|
||||
- `supporting` (supporting/helper text)
|
||||
|
||||
**Complete Examples:**
|
||||
- `start-hero-headline`
|
||||
- `signin-form-email-label`
|
||||
- `profile-success-message`
|
||||
- `calendar-header-title`
|
||||
- `features-description-text`
|
||||
|
||||
---
|
||||
|
||||
## Content Structure
|
||||
|
||||
### Required Fields
|
||||
|
||||
```markdown
|
||||
#### {{Purpose_Title}}
|
||||
**OBJECT ID**: `{{page-section-purpose}}`
|
||||
- **Component**: {{component_type}} ({{class_or_reference}})
|
||||
- **Position**: {{position_description}}
|
||||
- **Content**:
|
||||
- EN: "{{english_content}}"
|
||||
- SE: "{{swedish_content}}"
|
||||
{{#if additional_languages}}
|
||||
- {{lang}}: "{{content}}"
|
||||
{{/if}}
|
||||
```
|
||||
|
||||
### Optional Fields
|
||||
|
||||
```markdown
|
||||
- **Behavior**: {{behavior_description}}
|
||||
- **Style**: {{style_specifications}}
|
||||
- **For**: {{linked_input_id}} (for labels)
|
||||
- **Trigger**: {{when_shown}} (for conditional text)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Multi-Language Support
|
||||
|
||||
### 2 Languages (Dog Week)
|
||||
|
||||
```markdown
|
||||
- **Content**:
|
||||
- EN: "Welcome to Dog Week"
|
||||
- SE: "Välkommen till Dog Week"
|
||||
```
|
||||
|
||||
### 3+ Languages
|
||||
|
||||
```markdown
|
||||
- **Content**:
|
||||
- EN: "Welcome to Dog Week"
|
||||
- SE: "Välkommen till Dog Week"
|
||||
- DE: "Willkommen bei Dog Week"
|
||||
- FR: "Bienvenue à Dog Week"
|
||||
```
|
||||
|
||||
### Language Codes
|
||||
|
||||
- **EN** = English
|
||||
- **SE** = Swedish (Svenska)
|
||||
- **NO** = Norwegian
|
||||
- **DK** = Danish
|
||||
- **FI** = Finnish
|
||||
- **DE** = German
|
||||
- **FR** = French
|
||||
- **ES** = Spanish
|
||||
- **IT** = Italian
|
||||
|
||||
---
|
||||
|
||||
## Benefits of This Pattern
|
||||
|
||||
### ✅ For Translators
|
||||
|
||||
```markdown
|
||||
**Hero Object Translations:**
|
||||
|
||||
#### Primary Headline
|
||||
- EN: "Every walk. on time. Every time."
|
||||
- SE: "Varje promenad. i tid. Varje gång."
|
||||
|
||||
#### Supporting Text
|
||||
- EN: "Organize your family around dog care."
|
||||
- SE: "Organisera din familj kring hundvård."
|
||||
```
|
||||
|
||||
Translator can:
|
||||
- Read entire section in each language
|
||||
- Ensure translations flow together
|
||||
- See context immediately
|
||||
- Verify character lengths
|
||||
|
||||
### ✅ For Developers
|
||||
|
||||
```typescript
|
||||
// Object ID makes purpose clear
|
||||
const headline = document.getElementById('start-hero-headline');
|
||||
const supportingText = document.getElementById('start-hero-supporting');
|
||||
|
||||
// Content referenced by language
|
||||
const content = {
|
||||
'start-hero-headline': {
|
||||
en: 'Every walk. on time. Every time.',
|
||||
se: 'Varje promenad. i tid. Varje gång.'
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
### ✅ For Maintainability
|
||||
|
||||
**Content changes:**
|
||||
```markdown
|
||||
#### Primary Headline
|
||||
**OBJECT ID**: `start-hero-headline` ← Stays same
|
||||
- **Content**:
|
||||
- EN: "NEW CONTENT HERE" ← Easy to update
|
||||
- SE: "NYTT INNEHÅLL HÄR"
|
||||
```
|
||||
|
||||
**No Object ID changes needed!**
|
||||
|
||||
---
|
||||
|
||||
## Text Group Examples
|
||||
|
||||
### Hero Group (Headline + Body + CTA)
|
||||
|
||||
All translations grouped so each language reads coherently:
|
||||
|
||||
```markdown
|
||||
### Hero Object
|
||||
|
||||
#### Headline
|
||||
- EN: "Every walk. on time."
|
||||
- SE: "Varje promenad. i tid."
|
||||
|
||||
#### Body
|
||||
- EN: "Never miss a walk again."
|
||||
- SE: "Missa aldrig en promenad."
|
||||
|
||||
#### CTA
|
||||
- EN: "Get Started"
|
||||
- SE: "Kom Igång"
|
||||
```
|
||||
|
||||
**English reads:** "Every walk. on time. / Never miss a walk again. / [Get Started]"
|
||||
**Swedish reads:** "Varje promenad. i tid. / Missa aldrig en promenad. / [Kom Igång]"
|
||||
|
||||
### Feature Group (Icon + Title + Description)
|
||||
|
||||
```markdown
|
||||
### Feature Card 1
|
||||
|
||||
#### Feature Title
|
||||
- EN: "Smart Scheduling"
|
||||
- SE: "Smart Schemaläggning"
|
||||
|
||||
#### Feature Description
|
||||
- EN: "Automatically assign walks based on family availability."
|
||||
- SE: "Tilldela promenader automatiskt baserat på familjetillgänglighet."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Validation Checklist
|
||||
|
||||
Before finalizing text specifications:
|
||||
|
||||
- [ ] Object IDs use purpose-based naming (not content)
|
||||
- [ ] Structure (position/style) separated from content
|
||||
- [ ] All languages included for each text element
|
||||
- [ ] Text groups keep translations together
|
||||
- [ ] Each language reads coherently as a group
|
||||
- [ ] Character lengths validated against sketch analysis
|
||||
- [ ] Component references included
|
||||
- [ ] Behavior specified (if applicable)
|
||||
|
||||
---
|
||||
|
||||
**This pattern ensures professional, maintainable, translation-friendly specifications across all WDS projects!** 🌍✨
|
||||
|
||||
|
||||
|
||||
|
|
@ -0,0 +1,393 @@
|
|||
# WDS Specification Pattern
|
||||
|
||||
**Complete specification format for Whiteport Design Studio projects**
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
This document defines the **WDS Specification Pattern** used in Phase 4 (UX Design) for all WDS projects.
|
||||
|
||||
**Dog Week Start Page** is used as the example implementation to demonstrate the pattern in action.
|
||||
|
||||
**Related Documentation:**
|
||||
- **`SKETCH-TEXT-ANALYSIS-GUIDE.md`** - How sketch analysis values are derived
|
||||
- **`HTML-VS-VISUAL-STYLES.md`** - HTML tags vs visual text styles
|
||||
- **`TRANSLATION-ORGANIZATION-GUIDE.md`** - Purpose-based text organization
|
||||
|
||||
---
|
||||
|
||||
## Key Principles
|
||||
|
||||
### 1. Purpose-Based Naming
|
||||
Text objects are named by **function, not content**:
|
||||
- ✅ `hero-headline` (describes purpose)
|
||||
- ❌ `welcome-message` (describes content)
|
||||
|
||||
### 2. Grouped Translations
|
||||
All product languages grouped together per object for coherent review.
|
||||
|
||||
### 3. Estimated Values from Sketch Analysis
|
||||
When text properties are estimated from sketch markers:
|
||||
- **Spell out the values explicitly** (e.g., `42px (est. from 24px spacing)`)
|
||||
- **Mark with analysis note** to show reasoning
|
||||
- **Designer confirms or adjusts** during specification dialog
|
||||
- **Update with final values** once confirmed
|
||||
|
||||
**Analysis methodology:** See `SKETCH-TEXT-ANALYSIS-GUIDE.md` for complete rules on deriving font weight, font size, line-height, and alignment from sketch markers.
|
||||
|
||||
This ensures transparency about which values came from AI interpretation vs. designer specification.
|
||||
|
||||
---
|
||||
|
||||
## The Pattern in Action
|
||||
|
||||
### Hero Section Example
|
||||
|
||||
```markdown
|
||||
### Hero Object
|
||||
**Purpose**: Primary value proposition and main conversion action
|
||||
|
||||
#### Primary Headline
|
||||
|
||||
**OBJECT ID**: `start-hero-headline`
|
||||
|
||||
**HTML Structure:**
|
||||
- **Tag**: h1
|
||||
- **Semantic Purpose**: Main page heading for SEO and accessibility
|
||||
|
||||
**Visual Style:**
|
||||
- **Style Name**: Hero headline
|
||||
- **Font weight**: Bold (from 3px thick line markers in sketch)
|
||||
- **Font size**: 56px (est. from 32px vertical spacing between line pairs)
|
||||
- **Line-height**: 1.1 (est. calculated as font-size × 1.1)
|
||||
- **Color**: #1a1a1a
|
||||
- **Letter spacing**: -0.02em
|
||||
|
||||
**Position**: Center of hero section, above supporting text
|
||||
**Alignment**: center
|
||||
|
||||
**Behavior**: Updates with language toggle
|
||||
|
||||
**Content**:
|
||||
- EN: "Every walk. on time. Every time."
|
||||
- SE: "Varje promenad. i tid. Varje gång."
|
||||
|
||||
> **Sketch Analysis:** Line thickness (3px) → Bold weight. Line spacing (32px) → ~56px font size estimate. Designer should confirm these values.
|
||||
|
||||
#### Supporting Text
|
||||
|
||||
**OBJECT ID**: `start-hero-supporting`
|
||||
|
||||
**HTML Structure:**
|
||||
- **Tag**: p
|
||||
- **Semantic Purpose**: Paragraph text providing additional context
|
||||
|
||||
**Visual Style:**
|
||||
- **Style Name**: Body text large
|
||||
- **Font weight**: Regular (from 1px thin line markers in sketch)
|
||||
- **Font size**: 18px (est. from 14px vertical spacing between line pairs)
|
||||
- **Line-height**: 1.5 (est. calculated as font-size × 1.5)
|
||||
- **Color**: #4a4a4a
|
||||
|
||||
**Position**: Below headline, above CTA, center-aligned
|
||||
**Alignment**: center
|
||||
|
||||
**Behavior**: Updates with language toggle
|
||||
|
||||
**Content**:
|
||||
- EN: "Organize your family around dog care. Never miss a walk again."
|
||||
- SE: "Organisera din familj kring hundvård. Missa aldrig en promenad igen."
|
||||
|
||||
> **Sketch Analysis:** Line thickness (1px) → Regular weight. Line spacing (14px) → ~18px font size estimate. Designer should confirm these values.
|
||||
|
||||
#### Primary CTA Button
|
||||
**OBJECT ID**: `start-hero-cta`
|
||||
- **Component**: [Button Primary Large](/docs/D-Design-System/.../Button-Primary.md)
|
||||
- **Position**: Center, below supporting text, 24px margin-top
|
||||
- **Behavior**: Navigate to /auth/signup
|
||||
- **States**: default, hover, active, loading
|
||||
- **Content**:
|
||||
- EN: "start planning - free forever"
|
||||
- SE: "börja planera - gratis för alltid"
|
||||
```
|
||||
|
||||
**Reading in English:**
|
||||
> **Every walk. on time. Every time.**
|
||||
> Organize your family around dog care. Never miss a walk again.
|
||||
> [start planning - free forever]
|
||||
|
||||
**Reading in Swedish:**
|
||||
> **Varje promenad. i tid. Varje gång.**
|
||||
> Organisera din familj kring hundvård. Missa aldrig en promenad igen.
|
||||
> [börja planera - gratis för alltid]
|
||||
|
||||
---
|
||||
|
||||
## The Complete Process
|
||||
|
||||
### Step 1: Sketch Analysis (4B)
|
||||
```
|
||||
Agent sees sketch with horizontal lines:
|
||||
|
||||
═══════════════════════════════ ← Line 1 (thick, 3px)
|
||||
═══════════════════════════ ← Line 2 (thick, 3px)
|
||||
|
||||
───────────────────────────────────────── ← Line 3 (thin, 1px)
|
||||
───────────────────────────────────────── ← Line 4 (thin, 1px)
|
||||
|
||||
┌─────────────────────────────┐
|
||||
│ start planning │ ← Button
|
||||
└─────────────────────────────┘
|
||||
|
||||
Agent identifies:
|
||||
1. TEXT GROUP (2 thick lines) - Hero headline
|
||||
2. TEXT GROUP (2 thin lines) - Supporting text
|
||||
3. BUTTON - CTA
|
||||
```
|
||||
|
||||
### Step 2: Object Detection (4C-03 + object-router)
|
||||
```
|
||||
For Object 1:
|
||||
→ Detects horizontal lines
|
||||
→ TEXT DETECTED
|
||||
→ Routes to heading-text.md
|
||||
|
||||
heading-text.md:
|
||||
→ Asks: "What's the PURPOSE?" → "Primary Headline"
|
||||
→ Object ID: `start-hero-headline`
|
||||
→ Sketch analysis: 2 lines, 3px thick, ~50-60 chars
|
||||
→ Content guidance: Brief heading, 2 short lines
|
||||
→ Requests content with length validation
|
||||
```
|
||||
|
||||
### Step 3: Content with Grouped Translations
|
||||
```
|
||||
Agent asks:
|
||||
|
||||
"What's the content for Primary Headline?
|
||||
|
||||
Based on sketch: 2 lines, ~50-60 characters total
|
||||
|
||||
I found text in your sketch: 'Every walk. on time. Every time.'
|
||||
|
||||
Let me suggest translations...
|
||||
|
||||
EN: Every walk. on time. Every time.
|
||||
SE: Varje promenad. i tid. Varje gång.
|
||||
|
||||
Do these work? [1] Use these [2] Adjust [3] Manual"
|
||||
|
||||
User provides:
|
||||
1 ← Accepts suggestions!
|
||||
|
||||
Agent validates:
|
||||
✅ EN: 37 chars (fits 60 capacity)
|
||||
✅ SE: 36 chars (fits 60 capacity)
|
||||
```
|
||||
|
||||
### Step 4: Generate Specification
|
||||
```markdown
|
||||
#### Primary Headline
|
||||
**OBJECT ID**: `start-hero-headline`
|
||||
- **Component**: H1 heading
|
||||
- **Position**: Center of hero
|
||||
- **Style**: Bold, 42px, line-height 1.2
|
||||
- **Content**:
|
||||
- EN: "Every walk. on time. Every time."
|
||||
- SE: "Varje promenad. i tid. Varje gång."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Advantages
|
||||
|
||||
### 1. Purpose-Based Object IDs
|
||||
|
||||
**Stable Naming:**
|
||||
- Content changes don't affect Object IDs
|
||||
- IDs remain semantic and meaningful
|
||||
- Easy to find by function
|
||||
|
||||
**Examples:**
|
||||
```markdown
|
||||
`start-hero-headline` ← Purpose clear
|
||||
`signin-form-email-label` ← Function clear
|
||||
`profile-success-message` ← Role clear
|
||||
```
|
||||
|
||||
### 2. Separated Concerns
|
||||
|
||||
**Structure/Style** (rarely changes):
|
||||
```markdown
|
||||
- **Component**: H1 heading
|
||||
- **Position**: Center of hero
|
||||
- **Style**: Bold, 42px
|
||||
```
|
||||
|
||||
**Content** (often changes):
|
||||
```markdown
|
||||
- **Content**:
|
||||
- EN: "..."
|
||||
- SE: "..."
|
||||
```
|
||||
|
||||
### 3. Grouped Translations
|
||||
|
||||
**Benefits:**
|
||||
- Each language reads as complete message
|
||||
- Translator sees full context
|
||||
- Natural language flow
|
||||
- Easy to verify coherence
|
||||
|
||||
**Format:**
|
||||
```markdown
|
||||
### Text Group
|
||||
|
||||
#### Element 1
|
||||
- EN: "..."
|
||||
- SE: "..."
|
||||
|
||||
#### Element 2
|
||||
- EN: "..."
|
||||
- SE: "..."
|
||||
|
||||
#### Element 3
|
||||
- EN: "..."
|
||||
- SE: "..."
|
||||
```
|
||||
|
||||
### 4. Character Capacity Validation
|
||||
|
||||
**From Sketch Analysis:**
|
||||
```
|
||||
Agent: "Sketch shows 2 lines, ~50-60 chars capacity"
|
||||
|
||||
User provides: "Every walk. on time. Every time." (37 chars)
|
||||
|
||||
Agent: "✅ Content fits within sketch capacity!"
|
||||
```
|
||||
|
||||
**If too long:**
|
||||
```
|
||||
Agent: "⚠️ Your content (85 chars) exceeds capacity (60 chars).
|
||||
Consider shortening or adjusting font size."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Complete Workflow Integration
|
||||
|
||||
```
|
||||
4B: Sketch Analysis
|
||||
↓
|
||||
Identifies text groups, estimates capacity
|
||||
↓
|
||||
4C-03: Components & Objects
|
||||
↓
|
||||
object-router.md
|
||||
↓
|
||||
STEP 1: TEXT DETECTION (checks horizontal lines)
|
||||
↓
|
||||
If text → heading-text.md
|
||||
↓
|
||||
1. Ask PURPOSE (not content)
|
||||
2. Generate Object ID from purpose
|
||||
3. Specify position/style
|
||||
4. Request content with grouped translations
|
||||
5. Validate against sketch capacity
|
||||
6. Generate specification (Dog Week format)
|
||||
↓
|
||||
Return to 4C-03
|
||||
↓
|
||||
4C-04: Content & Languages
|
||||
(Already captured in heading-text.md)
|
||||
↓
|
||||
4C-08: Generate Final Spec
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Template Structure
|
||||
|
||||
**Every text element follows this format:**
|
||||
|
||||
```markdown
|
||||
#### {{Purpose_Title}}
|
||||
**OBJECT ID**: `{{page-section-purpose}}`
|
||||
- **Component**: {{type}} ({{class_or_ref}})
|
||||
- **Position**: {{position_description}}
|
||||
{{#if has_behavior}}
|
||||
- **Behavior**: {{behavior_description}}
|
||||
{{/if}}
|
||||
{{#if has_style_details}}
|
||||
- **Style**: {{style_specifications}}
|
||||
{{/if}}
|
||||
{{#if links_to_input}}
|
||||
- **For**: {{input_object_id}}
|
||||
{{/if}}
|
||||
- **Content**:
|
||||
- EN: "{{english_text}}"
|
||||
- SE: "{{swedish_text}}"
|
||||
{{#each additional_language}}
|
||||
- {{code}}: "{{text}}"
|
||||
{{/each}}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Real Dog Week Specifications
|
||||
|
||||
These follow the exact pattern we're implementing:
|
||||
|
||||
**From 1.1-Start-Page.md:**
|
||||
```markdown
|
||||
#### Primary Headline
|
||||
**OBJECT ID**: `start-hero-headline`
|
||||
- **Component**: H1 heading (`.text-heading-1`)
|
||||
- **Content**:
|
||||
- EN: "Every walk. on time. Every time."
|
||||
- SE: "Varje promenad. i tid. Varje gång."
|
||||
|
||||
#### Primary CTA Button
|
||||
**OBJECT ID**: `start-hero-cta`
|
||||
- **Component**: [Button Primary Large](/docs/D-Design-System/.../Button-Primary.md)
|
||||
- **Content**:
|
||||
- EN: "start planning - free forever"
|
||||
- SE: "börja planera - gratis för alltid"
|
||||
```
|
||||
|
||||
**From 1.2-Sign-In.md (Header example):**
|
||||
```markdown
|
||||
#### Sign In Button
|
||||
**OBJECT ID**: `start-header-signin`
|
||||
- **Component**: [Button Secondary](/docs/D-Design-System/.../Button-Secondary.md)
|
||||
- **Content**:
|
||||
- EN: "Sign in"
|
||||
- SE: "Logga in"
|
||||
- **Behavior**: Navigate to sign-in page
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Specification Checklist
|
||||
|
||||
For each text element:
|
||||
|
||||
- [ ] **Purpose-based name** (not content-based)
|
||||
- [ ] **Object ID** from purpose: `{page}-{section}-{purpose}`
|
||||
- [ ] **Component** reference specified
|
||||
- [ ] **Position** clearly described
|
||||
- [ ] **Style** separated from content
|
||||
- [ ] **Behavior** specified if applicable
|
||||
- [ ] **Content** with grouped translations:
|
||||
- [ ] EN: "..."
|
||||
- [ ] SE: "..."
|
||||
- [ ] Additional languages if needed
|
||||
- [ ] **Character length** validated against sketch
|
||||
- [ ] **Part of text group** if applicable
|
||||
|
||||
---
|
||||
|
||||
**This is the WDS standard for text specifications, proven by Dog Week!** 🎨🌍✨
|
||||
|
||||
|
|
@ -0,0 +1,511 @@
|
|||
# Why-Based Specifications
|
||||
|
||||
**The critical difference between prompt-and-run vs. thoughtful specification**
|
||||
|
||||
---
|
||||
|
||||
## The Trigger Map: The Ultimate Why-Machine
|
||||
|
||||
**Before any specification, the Trigger Map establishes WHY:**
|
||||
|
||||
### Example: Transparent Pricing Feature
|
||||
|
||||
**Trigger Map Reasoning:**
|
||||
```
|
||||
TARGET GROUP: Budget-conscious customers
|
||||
FEAR: Surprises and hidden costs
|
||||
TRIGGER: Anxiety about final price
|
||||
OUTCOME: Easier commitment to purchase
|
||||
SOLUTION: Transparent price model explanation
|
||||
```
|
||||
|
||||
**This WHY flows into specifications:**
|
||||
```markdown
|
||||
## Transparent Pricing Component
|
||||
|
||||
**WHY This Exists:**
|
||||
Our main target group is afraid of surprises and hidden costs.
|
||||
By explaining our transparent price model, the customer has an
|
||||
easier time committing to the purchase.
|
||||
|
||||
**WHY Upfront (Not at Checkout):**
|
||||
Anxiety happens early. Showing pricing transparency upfront
|
||||
reduces fear before it builds.
|
||||
|
||||
**WHY Detailed Breakdown (Not Just Total):**
|
||||
"No hidden costs" needs proof. Itemized breakdown shows
|
||||
there's nothing hidden.
|
||||
|
||||
**WHAT NOT TO DO:**
|
||||
- ❌ Don't hide pricing until checkout (increases anxiety)
|
||||
- ❌ Don't show just total (doesn't prove transparency)
|
||||
- ❌ Don't use fine print (contradicts "transparent")
|
||||
```
|
||||
|
||||
**The Trigger Map WHY becomes the specification WHY.**
|
||||
|
||||
---
|
||||
|
||||
## The Problem with v4 WPS2C (Whiteport Sketch-to-Code)
|
||||
|
||||
**What happened:**
|
||||
```
|
||||
Designer: "Create a calendar for booking dog walks"
|
||||
AI: *Runs with it*
|
||||
Result: Generic calendar, missing the point
|
||||
```
|
||||
|
||||
**What was missing:**
|
||||
- No questioning to elevate thinking
|
||||
- No capture of WHY decisions were made
|
||||
- No understanding of business context
|
||||
- AI "helped" by making assumptions
|
||||
|
||||
**Result:** Fast, but wrong. Better, but not right.
|
||||
|
||||
---
|
||||
|
||||
## The AI Habit Problem
|
||||
|
||||
**AI's default behavior:**
|
||||
```
|
||||
"I'll make this faster!"
|
||||
"I'll make this better!"
|
||||
"I'll add helpful features!"
|
||||
```
|
||||
|
||||
**What AI misses:**
|
||||
- WHY does this need to exist?
|
||||
- WHO is this actually for?
|
||||
- WHAT problem does this solve?
|
||||
- WHAT should we NOT do?
|
||||
|
||||
**AI optimizes for implementation, not intention.**
|
||||
|
||||
---
|
||||
|
||||
## The Solution: Why-Based Specifications
|
||||
|
||||
### Traditional Specification (WHAT)
|
||||
|
||||
```markdown
|
||||
## Calendar Component
|
||||
|
||||
**Features:**
|
||||
- Week view
|
||||
- Booking slots
|
||||
- Color-coded states
|
||||
- Countdown timers
|
||||
|
||||
**Visual:**
|
||||
- 7 columns (days)
|
||||
- 6 color states
|
||||
- Timer in orange state
|
||||
```
|
||||
|
||||
**Problem:** AI will implement this literally, but might:
|
||||
- Add daily/monthly views ("better!")
|
||||
- Add notifications ("helpful!")
|
||||
- Make it generic ("reusable!")
|
||||
- Miss the cultural context
|
||||
|
||||
---
|
||||
|
||||
### Why-Based Specification (WHY + WHAT)
|
||||
|
||||
```markdown
|
||||
## Calendar Component
|
||||
|
||||
**WHY This Exists:**
|
||||
Families struggle to coordinate dog care. Kids forget, parents nag,
|
||||
dogs suffer. This calendar reduces conflict by making responsibility
|
||||
visible and accountability fun.
|
||||
|
||||
**WHY Week View (Not Daily/Monthly):**
|
||||
Swedish families think in weeks ("Vecka 40"). This matches their
|
||||
mental model. Daily view is too granular, monthly too abstract.
|
||||
→ AI: Don't add daily/monthly views, even if you think it's "better"
|
||||
|
||||
**WHY 6 Color States:**
|
||||
Visual, instant understanding for kids. No reading required.
|
||||
- WHITE: Empty (neutral, inviting)
|
||||
- GRAY: Booked (committed, not yet active)
|
||||
- ORANGE: Countdown (urgent, act now)
|
||||
- BLUE: Active (in progress, can't book another)
|
||||
- GREEN: Completed (success, positive reinforcement)
|
||||
- RED: Missed (accountability, not punishment)
|
||||
|
||||
→ AI: Don't simplify to 3 states, each serves a purpose
|
||||
|
||||
**WHY Countdown Timer (Not Notifications):**
|
||||
Gentle urgency without nagging. Visible when user checks app.
|
||||
Notifications would break the "fun, not punishing" tone.
|
||||
→ AI: Don't add push notifications, even if you think it's "helpful"
|
||||
|
||||
**WHY Leaderboard Integration:**
|
||||
Makes accountability a game, not a chore. Encourages participation.
|
||||
→ AI: This is core to the experience, don't make it optional
|
||||
|
||||
**WHAT NOT TO DO:**
|
||||
- ❌ Don't add daily/monthly views (wrong mental model)
|
||||
- ❌ Don't add notifications (wrong tone)
|
||||
- ❌ Don't make it generic (Swedish culture specific)
|
||||
- ❌ Don't simplify states (each serves a purpose)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## What This Enables
|
||||
|
||||
### 1. AI Follows Instructions Correctly
|
||||
|
||||
**Without WHY:**
|
||||
```
|
||||
AI: "I added daily view for flexibility!"
|
||||
Designer: "No, that breaks the mental model..."
|
||||
```
|
||||
|
||||
**With WHY:**
|
||||
```
|
||||
Spec: "Week view matches Swedish 'Vecka 40' culture. Don't add daily view."
|
||||
AI: *Implements week view only*
|
||||
Designer: ✅ Perfect
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. AI Knows What to Skip
|
||||
|
||||
**Without WHY:**
|
||||
```
|
||||
AI: "I added push notifications for reminders!"
|
||||
Designer: "No, that's nagging, not gentle urgency..."
|
||||
```
|
||||
|
||||
**With WHY:**
|
||||
```
|
||||
Spec: "Countdown timer = gentle urgency. Notifications = nagging. Don't add notifications."
|
||||
AI: *Skips notifications*
|
||||
Designer: ✅ Exactly right
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 3. AI Preserves Intent During Changes
|
||||
|
||||
**Without WHY:**
|
||||
```
|
||||
Designer: "Make the countdown more prominent"
|
||||
AI: *Makes it bigger, adds sound, adds vibration*
|
||||
Designer: "No, that's too aggressive..."
|
||||
```
|
||||
|
||||
**With WHY:**
|
||||
```
|
||||
Spec: "Countdown = gentle urgency, not aggressive nagging"
|
||||
Designer: "Make countdown more prominent"
|
||||
AI: *Makes it bigger, keeps gentle tone*
|
||||
Designer: ✅ Got it
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. Future Developers Understand Context
|
||||
|
||||
**Without WHY:**
|
||||
```
|
||||
Developer: "Why can't users book multiple walks at once?"
|
||||
*Removes blocking logic*
|
||||
*Breaks the accountability system*
|
||||
```
|
||||
|
||||
**With WHY:**
|
||||
```
|
||||
Spec: "One active walk per dog = accountability. Kids can't game the system
|
||||
by booking everything then completing nothing."
|
||||
Developer: "Oh, that's a business rule. I'll keep it."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## The Socratic Questioning Connection
|
||||
|
||||
**Agent asks WHY questions:**
|
||||
```
|
||||
Agent: "Why week view instead of daily?"
|
||||
Designer: "Swedish families think in weeks..."
|
||||
Agent: "Got it! Documenting:
|
||||
WHY: Matches Swedish 'Vecka 40' mental model
|
||||
WHAT NOT TO DO: Don't add daily/monthly views"
|
||||
```
|
||||
|
||||
**This creates specifications that:**
|
||||
- Capture reasoning, not just decisions
|
||||
- Guide AI implementation correctly
|
||||
- Prevent "helpful" mistakes
|
||||
- Preserve intent over time
|
||||
|
||||
---
|
||||
|
||||
## Structure of Why-Based Specs
|
||||
|
||||
### For Each Component/Feature:
|
||||
|
||||
**1. WHY This Exists**
|
||||
- What problem does it solve?
|
||||
- What behavior change does it create?
|
||||
- What value does it deliver?
|
||||
|
||||
**2. WHY These Specific Choices**
|
||||
- Why this approach vs alternatives?
|
||||
- What user need does this serve?
|
||||
- What business goal does this support?
|
||||
|
||||
**3. WHAT NOT TO DO**
|
||||
- What "improvements" would break the intent?
|
||||
- What features should NOT be added?
|
||||
- What assumptions should AI NOT make?
|
||||
|
||||
**4. WHAT (Traditional Specs)**
|
||||
- Visual design
|
||||
- Interactions
|
||||
- Technical requirements
|
||||
|
||||
---
|
||||
|
||||
## Example: Dog Week "Book Walk" Button
|
||||
|
||||
### Traditional Spec (WHAT Only)
|
||||
|
||||
```markdown
|
||||
## Book Walk Button
|
||||
|
||||
**Visual:**
|
||||
- Blue background (#3B82F6)
|
||||
- White text
|
||||
- 48px height
|
||||
- Rounded corners (8px)
|
||||
|
||||
**Action:**
|
||||
- Click → Open booking modal
|
||||
```
|
||||
|
||||
**AI might "improve" by:**
|
||||
- Adding "Quick Book" shortcut
|
||||
- Adding "Book for Week" bulk action
|
||||
- Making it more prominent
|
||||
- Adding animation
|
||||
|
||||
---
|
||||
|
||||
### Why-Based Spec
|
||||
|
||||
```markdown
|
||||
## Book Walk Button
|
||||
|
||||
**WHY This Exists:**
|
||||
Kids need a simple way to commit to walking the dog.
|
||||
"Booking" creates accountability - it's a promise, not just a plan.
|
||||
|
||||
**WHY "Book Walk" (Not "Add Walk"):**
|
||||
"Book" = Future commitment (proactive)
|
||||
"Add" = Past logging (retroactive)
|
||||
We need both, they serve different purposes.
|
||||
|
||||
**WHY Simple Click (Not Quick Actions):**
|
||||
Kids should think before booking. One deliberate action = one commitment.
|
||||
Quick actions would encourage gaming the system (book everything, complete nothing).
|
||||
|
||||
**WHY This Visual Treatment:**
|
||||
- Blue = Action color (consistent with design system)
|
||||
- 48px = Touch-friendly for kids
|
||||
- Not oversized = Important but not aggressive
|
||||
|
||||
**WHAT NOT TO DO:**
|
||||
- ❌ Don't add "Quick Book" shortcuts (encourages gaming)
|
||||
- ❌ Don't add "Book for Week" bulk action (defeats accountability)
|
||||
- ❌ Don't make it more prominent (not the only action)
|
||||
- ❌ Don't add animation (not a game, it's responsibility)
|
||||
|
||||
**WHAT (Implementation):**
|
||||
- Background: Blue (#3B82F6)
|
||||
- Text: White, 16px Medium
|
||||
- Height: 48px
|
||||
- Border radius: 8px
|
||||
- Action: Click → Open booking modal
|
||||
```
|
||||
|
||||
**Now AI knows:**
|
||||
- What to implement
|
||||
- What NOT to add
|
||||
- WHY each decision was made
|
||||
- How to handle future changes
|
||||
|
||||
---
|
||||
|
||||
## The Transformation
|
||||
|
||||
### v4 WPS2C (Prompt-and-Run)
|
||||
```
|
||||
Designer: "Create a booking calendar"
|
||||
AI: *Generates generic calendar*
|
||||
Designer: "No, that's not right..."
|
||||
AI: *Tries again, still generic*
|
||||
Designer: *Gives up or over-specifies every detail*
|
||||
```
|
||||
|
||||
### v6 WDS (Why-Based Specifications)
|
||||
```
|
||||
Designer: "I need a booking calendar"
|
||||
Agent: "Help me understand - why week view instead of daily?"
|
||||
Designer: "Swedish families think in weeks..."
|
||||
Agent: "Got it. Why 6 color states instead of simpler?"
|
||||
Designer: "Each state serves a purpose for kids..."
|
||||
Agent: "Perfect. Why countdown instead of notifications?"
|
||||
Designer: "Gentle urgency, not nagging..."
|
||||
|
||||
Agent: "Documenting all the WHYs. This will help AI implement
|
||||
correctly and prevent 'helpful' mistakes."
|
||||
|
||||
*Generates why-based specification*
|
||||
|
||||
AI: *Implements exactly right, skips "improvements" that would break intent*
|
||||
Designer: ✅ Perfect first time
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## The Meta-Benefit
|
||||
|
||||
**Why-based specifications are:**
|
||||
|
||||
✅ **Better for AI implementation**
|
||||
- AI knows what NOT to do
|
||||
- AI preserves intent during changes
|
||||
- AI doesn't "help" incorrectly
|
||||
|
||||
✅ **Better for human developers**
|
||||
- Understand context, not just requirements
|
||||
- Make correct decisions when specs are unclear
|
||||
- Maintain intent over time
|
||||
|
||||
✅ **Better for future designers**
|
||||
- Understand why decisions were made
|
||||
- Don't repeat solved problems
|
||||
- Build on reasoning, not just patterns
|
||||
|
||||
✅ **Better for the designer**
|
||||
- Socratic questioning elevates thinking
|
||||
- Articulating WHY clarifies decisions
|
||||
- Creates reusable design knowledge
|
||||
|
||||
---
|
||||
|
||||
## The Bottom Line
|
||||
|
||||
**Traditional specs answer: "What should we build?"**
|
||||
|
||||
**Why-based specs answer:**
|
||||
- What should we build?
|
||||
- Why should we build it this way?
|
||||
- What should we NOT build?
|
||||
- How should AI help (and not help)?
|
||||
|
||||
**Result:**
|
||||
- AI implements correctly first time
|
||||
- AI skips "improvements" that break intent
|
||||
- Specifications become design knowledge
|
||||
- Designer thinking is preserved and amplified
|
||||
|
||||
**This is the difference between:**
|
||||
- Prompt-and-run (fast but wrong)
|
||||
- Why-based specification (thoughtful and right)
|
||||
|
||||
---
|
||||
|
||||
## The BMad Method Flow
|
||||
|
||||
**The complete WHY chain:**
|
||||
|
||||
```
|
||||
1. TRIGGER MAP (Phase 1: Business Model)
|
||||
↓
|
||||
Establishes: WHO, WHAT TRIGGERS THEM, WHAT OUTCOME
|
||||
|
||||
2. SCENARIOS (Phase 1: Business Model)
|
||||
↓
|
||||
Defines: User journeys, contexts, goals
|
||||
|
||||
3. INFORMATION ARCHITECTURE (Phase 2)
|
||||
↓
|
||||
Structures: Content hierarchy, navigation
|
||||
|
||||
4. INTERACTION DESIGN (Phase 3)
|
||||
↓
|
||||
Sketches: User flows, state transitions
|
||||
|
||||
5. UX SPECIFICATIONS (Phase 4)
|
||||
↓
|
||||
Documents: WHY + WHAT + WHAT NOT TO DO
|
||||
|
||||
6. AI IMPLEMENTATION
|
||||
↓
|
||||
Builds: Correctly, preserving intent
|
||||
```
|
||||
|
||||
**Each phase carries WHY forward:**
|
||||
|
||||
- **Trigger Map** → WHY the business exists
|
||||
- **Scenarios** → WHY users need this
|
||||
- **IA** → WHY this structure
|
||||
- **Interaction** → WHY this flow
|
||||
- **UX Specs** → WHY these specific choices
|
||||
- **AI** → Implements with full context
|
||||
|
||||
**Without Trigger Map, specifications lose their foundation.**
|
||||
|
||||
**With Trigger Map, every decision traces back to user needs and business goals.**
|
||||
|
||||
---
|
||||
|
||||
## The Bottom Line
|
||||
|
||||
**Traditional specs answer: "What should we build?"**
|
||||
|
||||
**Why-based specs answer:**
|
||||
- What should we build?
|
||||
- Why should we build it this way?
|
||||
- What should we NOT build?
|
||||
- How should AI help (and not help)?
|
||||
|
||||
**Trigger Map provides the ultimate WHY:**
|
||||
- WHO is this for?
|
||||
- WHAT triggers their need?
|
||||
- WHAT outcome do they want?
|
||||
- WHY will this solution work?
|
||||
|
||||
**Result:**
|
||||
- AI implements correctly first time
|
||||
- AI skips "improvements" that break intent
|
||||
- Specifications become design knowledge
|
||||
- Designer thinking is preserved and amplified
|
||||
|
||||
**This is the difference between:**
|
||||
- Prompt-and-run (fast but wrong)
|
||||
- Why-based specification (thoughtful and right)
|
||||
|
||||
---
|
||||
|
||||
**Trigger Map establishes WHY.**
|
||||
|
||||
**Socratic questioning reveals WHY.**
|
||||
|
||||
**Why-based specifications capture WHY.**
|
||||
|
||||
**AI implementation preserves WHY.**
|
||||
|
||||
**Designer thinking flows through the entire process.**
|
||||
|
||||
---
|
||||
|
||||
[← Back to Workflows](README.md)
|
||||
|
|
@ -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!** 🤝✨
|
||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in New Issue