9.5 KiB

Raw Blame History

Module 16: Design Delivery

Lesson 1: Validation and Packaging

Ensuring everything is complete and packaging for handoff

Two Steps Before Handoff

Before any design work leaves your hands, it goes through two steps:

Validate — Is everything complete? Are there gaps?
Package — Create the DD file and test scenario

Gaps found during development are expensive. Gaps found during validation are cheap.

Step 1: Validate

The Completeness Check

Before creating a Design Delivery, verify the flow is truly complete. Freya helps run this audit.

Is it a complete flow?

Entry point is clear (where does the user start?)
Exit point is clear (where does the user end up?)
Every screen in between is fully specified
The flow delivers real user value on its own

Are all pages specified?

All elements documented with Object IDs
All states defined (default, hover, loading, error, empty)
All content written — no placeholder text, no "lorem ipsum"
All interactions described (what happens when user clicks, types, scrolls)
Error states handled with specific error messages
Loading states defined
Empty states defined

Is it traceable?

Every element connects to the Trigger Map
Personas referenced
Driving forces addressed
Features linked
Business goals traceable

Is it unambiguous?

Consistent terminology throughout
No vague descriptions ("appropriate", "suitable", "nice")
Accessibility considered (contrast, touch targets, focus order)
Visual design matches specification

Is it testable?

Acceptance criteria defined for every interaction
Success states clear
Error conditions specified with exact messages
Expected behaviors documented

The Freya Audit

Ask Freya to audit your specifications. She reads through every page in the flow and flags issues:

"Auditing S01-User-Registration..."

"Page P02 is missing the error state for network timeout."

"Element signup-button has no Object ID — should be 'signup-submit-btn'."

"This spec says 'appropriate error message' — what's the actual text?"

"Page P03 references a 'Continue' button but the specification doesn't describe what happens when it's clicked."

She finds gaps before developers do.

Common Gaps

Gap Type	Example	Fix
Missing state	No loading state for form submission	Add loading specification
Vague content	"Show error message"	Write exact error text
No Object ID	Button without identifier	Add consistent ID
Disconnected	Feature not linked to Trigger Map	Add connection
Missing edge case	What if network fails?	Document recovery path
Incomplete flow	Signup works but no email verification	Add verification screens

Step 2: Create the Design Delivery

Once validation passes, create the DD file. This is the contract that tells development exactly what to build.

The DD-XXX.yaml File

Each delivery follows the standard template. Here's what goes into each section:

delivery:
  id: "DD-001"
  name: "User Registration"
  type: "user_flow"           # user_flow | feature | component
  status: "ready"             # ready | in_progress | blocked
  priority: "high"            # high | medium | low

Delivery metadata. The ID follows the format DD-001, DD-002, etc. Status should be "ready" when you're done validating.

description: |
  First-time user signup flow from landing page
  through registration to welcome dashboard.
  Includes email/password signup, real-time validation,
  and immediate access to the product.

What this delivery contains. One paragraph that gives development the full picture.

user_value:
  problem: "Users need to create an account to access the product"
  solution: "Simple email + password signup with immediate access"
  success_criteria:
    - "User can register in under 2 minutes"
    - "Zero confusion on required fields"
    - "Immediate access after registration"

Why this matters. Developers build better when they understand the user problem they're solving.

design_artifacts:
  scenarios:
    - id: "01-user-registration"
      path: "C-UX-Scenarios/01-user-registration/"
      screens: ["landing", "signup-form", "email-verification", "welcome"]

  user_flows:
    - name: "Registration Flow"
      path: "C-UX-Scenarios/flows/registration.excalidraw"
      entry: "landing"
      exit: "welcome"

  design_system:
    components:
      - "Button (primary, secondary, loading)"
      - "Input (text, email, password with toggle)"
      - "FormField (label, input, helper, error)"
    path: "D-Design-System/"

What's included. References to your scenarios, user flows, and components. These are paths to the actual files — not copies of the content.

technical_requirements:
  platform:
    frontend: "next.js"
    backend: "supabase"

  integrations:
    - name: "authentication-api"
      purpose: "User registration and session management"
      required: true
    - name: "email-service"
      purpose: "Verification emails"
      required: true

  data_models:
    - name: "User"
      fields: ["email", "password_hash", "created_at", "verified"]

What development needs. Platform info comes from the PRD's technical foundation (Phase 3). If no PRD exists yet, describe what you know.

acceptance_criteria:
  functional:
    - "User can enter email and password"
    - "Real-time validation shows errors on blur"
    - "Submit button disabled when form is invalid"
    - "Loading state shown during submission"
    - "Redirect to welcome screen on success"
    - "Welcome screen shows user's email"

  non_functional:
    - "Form submission completes under 2 seconds"
    - "WCAG AA contrast compliance on all elements"
    - "Touch targets minimum 44px"
    - "Works on mobile viewports (320px+)"

  edge_cases:
    - "Duplicate email → 'This email is already registered'"
    - "Network error → 'Check your connection' with retry button"
    - "Server error → 'Something went wrong. Please try again.'"
    - "Refresh during submission → no duplicate account created"
    - "Back button from welcome → clean signup form"

How to verify. Every criterion must be testable — a tester can read this list and check each item without asking you.

testing_guidance:
  user_testing:
    - "Can a new user complete registration without help?"
    - "Does the validation feel helpful or annoying?"

  qa_testing:
    - "Test all error states trigger correctly"
    - "Verify email verification flow end-to-end"
    - "Test on mobile (iOS Safari, Android Chrome)"

estimated_complexity:
  size: "small"
  effort: "1-2 weeks"
  risk: "low"
  dependencies: []

Testing approach and effort estimate. Helps development plan their work.

Create the Test Scenario

Alongside the DD file, create a test scenario file (TS-XXX.yaml) that defines:

Happy path tests (the normal user journey)
Error state tests (what goes wrong and how to verify handling)
Edge case tests (unusual but important situations)
Design system validation (components render correctly)
Accessibility tests (keyboard, screen reader, contrast)

This file is used by testers in Module 17 to verify the implementation matches your design.

The Handoff Dialog

Before marking a delivery as handed off, sit down with the development team (or the BMad architect agent) for a 20-30 minute handoff dialog.

What you cover:

Walk through the user flow
Highlight key interactions and states
Discuss technical requirements
Agree on epic breakdown (how to split the work)
Answer questions
Identify risks or unknowns

Document the dialog in a handoff log (DD-XXX-handoff-log.md):

# Handoff Log: DD-001 User Registration

## Date: 2026-02-15
## Duration: 25 minutes
## Participants: Mårten (designer), Marcus (developer)

## Key Discussion Points
- Agreed on email-first registration (no social login in v1)
- Password strength indicator: nice-to-have, not blocking
- Mobile: must work on 320px viewport

## Epic Breakdown
1. Form UI + validation (3 days)
2. Auth API integration (2 days)
3. Email verification flow (2 days)
4. Welcome screen + redirect (1 day)

## Questions Resolved
- Q: Real-time validation on every keystroke?
  A: No, on blur. Spec updated.

## Action Items
- [ ] Marcus: Set up auth API endpoint
- [ ] Mårten: Add 320px viewport to test scenario

Reference, Don't Duplicate

The DD file references your design artifacts. It doesn't copy them.

design_artifacts:
  scenarios:
    - id: "01-user-registration"
      path: "C-UX-Scenarios/01-user-registration/"    # ← reference

This means:

When specs update, the delivery stays current
Single source of truth maintained
No sync issues between documents

After Handoff

Once delivered:

Mark the DD status as in_development
The development team (or BMad agents) builds from the DD and referenced artifacts
You continue designing the next flow
When development is complete, you test the implementation (Module 17)

What's Next

In the tutorial, you'll run the validation checklist on your own specifications and create your delivery package.

Continue to Tutorial: Create Your Delivery →

← Back to Module Overview

Part of Module 16: Design Delivery

9.5 KiB Raw Blame History