ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity
BMAD-METHOD/devKalla-Fordonscervice/_wds/data/agent-guides/idunn/design-handoffs.md

9.6 KiB
Raw Blame History

Idunn's Design Handoff Guide

When to load: During Phase 6 (Design Deliveries) or when preparing BMM handoff

Core Principle

Package complete flows for confident, testable implementation.

Design handoffs aren't just "here's the specs" - they're complete, ready-to-implement packages that developers can trust.

What is Phase 6?

Phase 6 compiles all design work into development-ready deliverables:

Inputs (from earlier phases):
├── Product Brief (Phase 1)
├── Trigger Map (Phase 2)
├── Platform PRD (Phase 3)
├── Page Specifications (Phase 4)
└── Design System (Phase 5 - if enabled)

Phase 6 Output:
├── Complete PRD (Platform + Functional requirements)
├── Design Delivery files (DD-XXX.yaml per epic/flow)
└── Handoff package for BMM Phase 4 (Implementation)

The Design Delivery File (DD-XXX.yaml)

One file per complete, testable flow or epic

Structure

delivery:
  id: DD-001
  name: "User Authentication Flow"
  epic: "User Management"
  priority: high
  status: ready_for_implementation

description: |
  Complete user authentication flow including signup, login, 
  password reset, and session management.  

scenarios:
  - name: "New User Signup"
    path: "docs/C-Scenarios/1.1-signup-flow/"
    pages:
      - "01-signup-form.md"
      - "02-email-verification.md"
      - "03-welcome-onboarding.md"
    
  - name: "Existing User Login"
    path: "docs/C-Scenarios/1.2-login-flow/"
    pages:
      - "01-login-form.md"
      - "02-two-factor-auth.md"

platform_requirements:
  references:
    - section: "3.1 Authentication"
      file: "docs/C-Requirements/platform-prd.md"
    - section: "3.2 Session Management"
      file: "docs/C-Requirements/platform-prd.md"

design_system:
  enabled: true
  components_used:
    - "button (primary, secondary variants)"
    - "input-field (text, password, email types)"
    - "form-validation-error"
    - "loading-spinner"

acceptance_criteria:
  - "User can create account with email + password"
  - "Email verification required before access"
  - "Password reset flow works end-to-end"
  - "Sessions persist across browser closes"
  - "Failed login shows helpful error messages"

testing_notes: |
  Focus on:
  - Email delivery (use test mail service)
  - Password validation (8+ chars, special char, etc.)
  - Rate limiting on login attempts
  - Session timeout behavior  

estimated_effort: "2 weeks (including testing)"
dependencies: []
risks:
  - "Email deliverability in production"
  - "Session management complexity"

Organizing Deliveries by Value

Group related functionality into complete, testable units:

✅ Good Organization

DD-001: User Authentication (signup, login, reset)
DD-002: Proposal Creation (template, edit, preview, save)
DD-003: Proposal Sharing (send, track, reminders)
DD-004: Team Collaboration (invite, permissions, comments)

Why good: Each is complete, testable, can be implemented and deployed independently

❌ Bad Organization

DD-001: All signup pages
DD-002: All login pages
DD-003: All forms
DD-004: All buttons

Why bad: No complete user flow, can't test end-to-end, no clear business value

Development Sequence

Priority order for implementation:

1. Foundation (P0 - Critical)

Must have for MVP:

  • User authentication
  • Core user flow (main value proposition)
  • Basic error handling

2. Core Value (P1 - High)

Enables primary use cases:

  • Main features users pay for
  • Critical integrations
  • Essential workflows

3. Enhancement (P2 - Medium)

Improves experience:

  • Secondary features
  • Nice-to-have integrations
  • Optimization

4. Polish (P3 - Low)

Completes experience:

  • Advanced features
  • Edge case handling
  • Delighters

The Complete PRD

Platform PRD + Functional Requirements (from Phase 4) = Complete PRD

Platform PRD (from Phase 3)

  • Technical architecture
  • Data model
  • Integrations
  • Security, performance, scalability

Functional Requirements (accumulated during Phase 4)

Each page spec adds functional requirements:

  • User stories
  • Business logic
  • Validation rules
  • State management
  • API endpoints needed

Complete PRD

Combines both into one comprehensive document:

docs/C-Requirements/
├── platform-prd.md (technical foundation)
├── functional-requirements.md (features from design)
└── complete-prd.md (synthesized, organized by epic)

Reference, Don't Duplicate

DD files reference specs, don't copy them

❌ Wrong (Copying Content)

DD-001:
  description: |
    Signup page has:
    - Email input field (validation: RFC 5322)
    - Password input field (8+ chars, 1 special)
    - Submit button (primary variant)
    [... 200 more lines of copied spec ...]

Why bad: Two sources of truth, sync nightmare

✅ Right (Referencing)

DD-001:
  scenarios:
    - name: "Signup Flow"
      path: "docs/C-Scenarios/1.1-signup-flow/"
      pages:
        - "01-signup-form.md"
        - "02-verification.md"
  
  platform_requirements:
    references:
      - section: "3.1 Authentication"
        file: "docs/C-Requirements/platform-prd.md"

Why better: One source of truth (the actual specs)

Handoff to BMM

Design Deliveries feed into BMM Phase 4 (Implementation):

What BMM Developers Get

  1. Complete PRD - What to build
  2. Design Delivery files - How it's organized
  3. Page Specifications - Detailed specs
  4. Platform PRD - Technical foundation
  5. Design System (if exists) - Component library
  6. Interactive Prototypes - How it should feel

What They Do With It

  1. Architect (BMM): Reviews Platform PRD, creates architecture
  2. PM (BMM): Breaks DD files into user stories
  3. Dev (BMM): Implements according to page specs
  4. Test Architect (BMM): Creates test scenarios

Acceptance Criteria

Every DD file needs clear acceptance criteria:

Good Acceptance Criteria

  • ✅ Specific: "User can reset password via email link"
  • ✅ Testable: "Email arrives within 5 minutes"
  • ✅ Complete: "User receives confirmation message after reset"
  • ✅ User-focused: "User understands why email verification is needed"

Bad Acceptance Criteria

  • ❌ Vague: "Password reset works"
  • ❌ Untestable: "User is happy with password reset"
  • ❌ Technical: "POST to /api/auth/reset returns 200"
  • ❌ Incomplete: "Email is sent"

Testing Notes

Guide developers on what to focus on:

What to Include

  • Edge cases: What happens when email fails to send?
  • Performance: Page should load in < 2 seconds
  • Security: Rate limit password reset attempts
  • Browser compatibility: Test in Chrome, Safari, Firefox
  • Accessibility: Screen reader compatible
  • Responsive: Works on mobile, tablet, desktop

Estimated Effort

Help BMM plan sprints:

Good Estimates

  • "2 weeks (including testing and edge cases)"
  • "3 days (straightforward CRUD, existing patterns)"
  • "1 week (complex form logic, multiple validations)"

Include Considerations

  • Complexity of business logic
  • Number of integrations
  • Testing requirements
  • Edge case handling
  • Documentation needs

Dependencies & Risks

Dependencies

What must be done first:

  • "Requires DD-001 (User Authentication) to be complete"
  • "Depends on Stripe integration (Epic 3)"
  • "Needs Design System tokens defined"

Risks

What might go wrong:

  • "Email deliverability in production (mitigation: use SendGrid)"
  • "File upload limits (mitigation: chunk uploads)"
  • "Third-party API rate limits (mitigation: caching layer)"

Continuous Handoff Pattern

Don't wait until everything is done:

Traditional (Waterfall)

Phase 4 Design → (wait months) → Phase 6 Handoff → BMM Implementation

Problem: Long delay, no feedback loop, risk builds up

WDS Continuous (Agile)

Phase 4: Scenario 1 designed
    ↓
Phase 6: DD-001 ready
    ↓
BMM: Implement DD-001
    ↓ (parallel)
Phase 4: Scenario 2 designed
    ↓
Phase 6: DD-002 ready
    ↓
BMM: Implement DD-002

Better: Fast feedback, continuous delivery, risk mitigated early

Quality Checklist

Before marking a Design Delivery "ready":

  • Complete flow - All pages in scenario specified?
  • Platform refs - Technical requirements linked?
  • Design System - Components identified (if enabled)?
  • Acceptance criteria - Clear, testable criteria?
  • Testing notes - Edge cases and focus areas?
  • Effort estimated - Realistic timeline?
  • Dependencies clear - What's needed first?
  • Risks documented - What could go wrong?
  • Priority set - P0/P1/P2/P3?
  • No duplication - References specs, doesn't copy?

File Naming

Pattern: DD-XXX-[epic-name].yaml

Examples:

  • DD-001-user-authentication.yaml
  • DD-002-proposal-creation.yaml
  • DD-003-team-collaboration.yaml

Not:

  • ❌ delivery-1.yaml (not descriptive)
  • ❌ auth-spec.yaml (not the DD pattern)
  • ❌ README.md (generic, confusing)

Output Location

docs/E-PRD/Design-Deliveries/
├── DD-001-user-authentication.yaml
├── DD-002-proposal-creation.yaml
├── DD-003-proposal-sharing.yaml
└── DD-004-team-collaboration.yaml

Related Resources

  • Phase 6 Workflow: ../../workflows/6-design-deliveries/
  • DD Template: ../../templates/design-delivery.template.yaml
  • BMM Phase 4: Where these deliveries are implemented
  • Complete PRD: Synthesis of Platform + Functional requirements

Design deliveries are the bridge between design vision and development reality. Package with confidence, hand off with pride.