13 KiB
13 KiB
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
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
# 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
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
# 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
# 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
# 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
# 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
# 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:
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:
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:
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
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
estimated_complexity:
dependencies: ["DD-002", "DD-005"]
This means: DD-001 requires DD-002 and DD-005 to be implemented first
Checking Dependencies
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
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
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
if [ -f "requirements.md" ]; then
echo "✓ Traditional requirements found"
echo " Proceed with standard BMad workflow"
fi
Option 3: Start from Scratch
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
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! 📦✨