# 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)
