341 lines
9.5 KiB
Markdown
341 lines
9.5 KiB
Markdown
# 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:
|
|
|
|
1. **Validate** — Is everything complete? Are there gaps?
|
|
2. **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:
|
|
|
|
```yaml
|
|
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.
|
|
|
|
---
|
|
|
|
```yaml
|
|
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.
|
|
|
|
---
|
|
|
|
```yaml
|
|
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.
|
|
|
|
---
|
|
|
|
```yaml
|
|
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.
|
|
|
|
---
|
|
|
|
```yaml
|
|
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.
|
|
|
|
---
|
|
|
|
```yaml
|
|
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.
|
|
|
|
---
|
|
|
|
```yaml
|
|
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`):
|
|
|
|
```markdown
|
|
# 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.
|
|
|
|
```yaml
|
|
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 →](tutorial-16.md)**
|
|
|
|
---
|
|
|
|
[← Back to Module Overview](module-16-design-delivery-overview.md)
|
|
|
|
*Part of Module 16: Design Delivery*
|