npm - whiteport-design-studio - Versions diffs - 0.2.2 → 0.3.0 - Mend

whiteport-design-studio 0.2.2 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (582) hide show

package/docs/learn-wds/module-12-conceptual-specs/tutorial-12.md DELETED Viewed

@@ -1,734 +0,0 @@
-# Tutorial 12: Write Conceptual 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 conceptual 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 Conceptual 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)