design-protocol 1.0.0

package/skills/dp-ux/references/accessibility-checklist.md

@@ -0,0 +1,128 @@
+# Accessibility Checklist
+
+Essential WCAG 2.1 AA compliance for production interfaces.
+
+## Keyboard Navigation
+
+- [ ] All interactive elements reachable via Tab
+- [ ] Logical tab order (follows visual flow)
+- [ ] Focus indicator visible on all focusable elements
+- [ ] Custom focus styles (not just browser default)
+- [ ] Skip links for main content on complex pages
+- [ ] No keyboard traps (can always Tab out)
+- [ ] Modal focus trapping (Tab cycles within modal)
+- [ ] Escape closes modals/dropdowns
+- [ ] Arrow keys for menu/option navigation
+- [ ] Enter/Space activates buttons and links
+
+## Color & Contrast
+
+- [ ] Text contrast ratio ≥ 4.5:1 (normal text)
+- [ ] Text contrast ratio ≥ 3:1 (large text, 18px+ or 14px bold)
+- [ ] UI component contrast ≥ 3:1 against background
+- [ ] Focus indicators have ≥ 3:1 contrast
+- [ ] Color is never the ONLY indicator of meaning
+- [ ] Error states use icon/text + color, not just red
+- [ ] Links distinguishable from body text (underline or 3:1 contrast)
+
+## Text & Typography
+
+- [ ] Base font size ≥ 16px
+- [ ] Line height ≥ 1.5 for body text
+- [ ] Text resizable up to 200% without breaking layout
+- [ ] No text in images (except logos)
+- [ ] Language attribute set on HTML element
+- [ ] Avoid justified text (uneven spacing)
+
+## Images & Media
+
+- [ ] All images have alt text (or alt="" for decorative)
+- [ ] Complex images have extended descriptions
+- [ ] Icons with meaning have accessible labels
+- [ ] Decorative icons hidden from screen readers (aria-hidden="true")
+- [ ] Video has captions
+- [ ] Audio has transcript
+
+## Forms
+
+- [ ] All inputs have associated labels (not just placeholder)
+- [ ] Labels are visible (not visually hidden unless icon is clear)
+- [ ] Required fields marked and announced
+- [ ] Error messages linked to inputs (aria-describedby)
+- [ ] Error messages are specific and helpful
+- [ ] Form validation announced to screen readers
+- [ ] Autocomplete attributes for common fields
+- [ ] Input type matches expected data (email, tel, etc.)
+
+## Interactive Elements
+
+- [ ] Buttons use `<button>`, not `<div onClick>`
+- [ ] Links use `<a>` with href, not `<span onClick>`
+- [ ] Custom components have appropriate ARIA roles
+- [ ] aria-expanded for collapsible sections
+- [ ] aria-selected for tabs/selections
+- [ ] aria-live regions for dynamic content
+- [ ] Loading states announced (aria-busy or live region)
+- [ ] Disabled states use `disabled` attribute or aria-disabled
+
+## Motion & Animation
+
+- [ ] Respect prefers-reduced-motion media query
+- [ ] No auto-playing video/audio
+- [ ] Animations can be paused
+- [ ] No flashing content (< 3 flashes/second)
+- [ ] Essential information not conveyed only through motion
+
+## Touch & Mobile
+
+- [ ] Touch targets ≥ 44×44px
+- [ ] Adequate spacing between touch targets (≥ 8px)
+- [ ] Gestures have alternative controls
+- [ ] Pinch-to-zoom not disabled
+- [ ] Orientation not locked (unless essential)
+
+## Screen Reader Essentials
+
+```html
+<!-- Landmark regions -->
+<header role="banner">
+<nav role="navigation">
+<main role="main">
+<footer role="contentinfo">
+
+<!-- Headings hierarchy -->
+<h1> (one per page)
+  <h2>
+    <h3>
+
+<!-- Live regions for dynamic updates -->
+<div aria-live="polite">Status updates here</div>
+<div aria-live="assertive">Critical alerts here</div>
+
+<!-- Hide decorative elements -->
+<span aria-hidden="true">🎉</span>
+
+<!-- Accessible names -->
+<button aria-label="Close dialog">×</button>
+<input aria-describedby="hint-id">
+<span id="hint-id">Password must be 8+ characters</span>
+```
+
+## Testing Checklist
+
+1. **Keyboard only** — Unplug mouse, complete all tasks
+2. **Screen reader** — Test with VoiceOver (Mac) or NVDA (Windows)
+3. **Zoom** — Test at 200% browser zoom
+4. **Color blindness** — Use simulator (Stark, Sim Daltonism)
+5. **Reduced motion** — Enable in OS settings, verify animations reduce
+6. **Contrast checker** — Use WebAIM contrast checker or Figma plugin
+
+## Quick Wins
+
+If limited time, prioritize these high-impact items:
+1. Keyboard navigation works for all interactions
+2. All form inputs have visible labels
+3. Color contrast meets minimums
+4. Focus indicators are visible
+5. Images have alt text
+6. Buttons are `<button>`, links are `<a>`

package/skills/dp-ux/references/product-excellence.md

@@ -0,0 +1,149 @@
+# Product Excellence
+
+What separates great products from good ones. Learn from the best.
+
+## Linear — Speed as a Feature
+
+**Philosophy**: Software should feel instant. Every interaction should respond in milliseconds.
+
+**Key UX decisions**:
+- **Optimistic updates everywhere** — Actions feel instant, sync in background
+- **Keyboard-first** — Every action has a shortcut, power users never touch mouse
+- **Command palette (Cmd+K)** — Single entry point to everything
+- **Minimal UI chrome** — Content takes center stage, UI fades away
+- **Animations are fast** — 150-200ms transitions, never sluggish
+- **Offline-capable** — Works without network, syncs when available
+
+**Steal these patterns**:
+- Sub-100ms response to all interactions
+- Global keyboard shortcuts with discoverability (Cmd+/)
+- Dense but scannable information display
+- Smooth, fast animations (ease-out, short duration)
+
+## Stripe — Clarity in Complexity
+
+**Philosophy**: Complex systems should feel simple. Guide users through sophisticated workflows without overwhelming them.
+
+**Key UX decisions**:
+- **Progressive disclosure** — Show basics first, reveal complexity on demand
+- **Inline documentation** — Help text right where you need it, not in separate docs
+- **Real-time validation** — Card fields validate as you type with clear feedback
+- **Test mode everywhere** — Safe sandbox to experiment without consequences
+- **Consistent patterns** — Once you learn one part, you understand the whole
+
+**Steal these patterns**:
+- Inline validation with specific, helpful messages
+- Contextual help (?) icons with popovers
+- Clear success/error states with next steps
+- Dashboard overviews that answer "what should I do now?"
+
+## Notion — Flexibility Without Chaos
+
+**Philosophy**: One tool that adapts to any workflow. Blocks as universal building blocks.
+
+**Key UX decisions**:
+- **Slash commands** — Universal entry point for all content types
+- **Blocks** — Everything is a draggable, transformable block
+- **Templates** — Reduce blank page anxiety with starting points
+- **Gentle onboarding** — Learn by using, not by reading
+- **Multiplayer presence** — See who's here, what they're doing
+
+**Steal these patterns**:
+- Slash commands for contextual actions
+- Drag-and-drop for organization
+- Template galleries for common use cases
+- Inline @mentions for collaboration
+
+## Vercel — Developer Experience as UX
+
+**Philosophy**: Developers are users too. Reduce friction to zero.
+
+**Key UX decisions**:
+- **Zero-config defaults** — Works out of box, configure only when needed
+- **Preview deployments** — Every PR gets a live URL automatically
+- **Real-time logs** — See what's happening instantly
+- **Git-centric workflow** — Meets developers where they are
+- **Beautiful CLI** — Even terminal output is designed
+
+**Steal these patterns**:
+- Smart defaults that handle 80% of cases
+- Live previews of changes
+- Clear deployment/build status visualization
+- One-click actions for common tasks
+
+## Figma — Collaborative by Default
+
+**Philosophy**: Design is a team sport. Real-time collaboration changes everything.
+
+**Key UX decisions**:
+- **Multiplayer cursors** — Always know who's here and where
+- **Browser-based** — No install, share via URL
+- **Components & variants** — Single source of truth for design systems
+- **Comments in context** — Feedback attached to what it's about
+- **Prototyping built-in** — Design and prototype in one tool
+
+**Steal these patterns**:
+- Real-time presence indicators
+- Shareable URLs for everything
+- Comment threads attached to specific elements
+- Version history with named checkpoints
+
+## Apple — Invisible Technology
+
+**Philosophy**: Technology should disappear. The best interface is no interface.
+
+**Key UX decisions**:
+- **Sensible defaults** — Works perfectly out of box
+- **Reduce options** — One obvious way to do things
+- **Direct manipulation** — Touch, drag, pinch — interact naturally
+- **System-wide consistency** — Learn once, use everywhere
+- **Delight in details** — Polish that makes you smile
+
+**Steal these patterns**:
+- Haptic feedback for physical confirmation
+- Smooth, physics-based animations
+- Limited but powerful feature sets
+- Empty states that guide, not just inform
+
+## Common Patterns Across Great Products
+
+### Speed
+- < 100ms for feedback on any interaction
+- Optimistic UI for perceived performance
+- Skeleton screens, not spinners
+- Background sync, not blocking operations
+
+### Keyboard-First
+- All actions have keyboard shortcuts
+- Command palette (Cmd+K) as universal entry point
+- Tab navigation works logically
+- Shortcut hints in UI
+
+### Progressive Disclosure
+- Simple by default, powerful when needed
+- Advanced options tucked away but findable
+- Contextual help, not separate documentation
+- Learn by doing, not by reading
+
+### Status & Feedback
+- Always show system status
+- Clear success/error/loading states
+- Undo for mistakes, not confirmation dialogs
+- Non-blocking notifications
+
+### Polish
+- Consistent spacing and alignment
+- Smooth, purposeful animations
+- Attention to empty states
+- Error messages that help
+
+## Anti-Patterns to Avoid
+
+- **Modal abuse** — Modals interrupt flow; use sheets, drawers, or inline expansion
+- **Confirmation dialogs for routine actions** — Provide undo instead
+- **Spinners for content loading** — Use skeleton screens
+- **Error codes without explanation** — Always explain what went wrong and how to fix
+- **Hidden navigation** — Don't make users hunt for common actions
+- **Requiring signup before value** — Show the product first
+- **Feature overload** — Not every feature needs to be visible always
+- **Inconsistent patterns** — Same action should work same way everywhere

package/skills/dp-ux/references/usability-principles.md

@@ -0,0 +1,140 @@
+# Usability Principles
+
+## Nielsen's 10 Heuristics (with Modern Interpretations)
+
+### 1. Visibility of System Status
+**Classic**: Keep users informed about what's going on through appropriate feedback within reasonable time.
+
+**Modern application**:
+- Skeleton screens during loading (not spinners for content)
+- Progress indicators for multi-step processes
+- Real-time sync status (saved, saving, offline)
+- Subtle toast notifications for background operations
+- Network/connection status indicators
+
+**Examples**: Linear shows "Saving..." → "Saved" transitions. Figma shows multiplayer cursors and selection states.
+
+### 2. Match Between System and Real World
+**Classic**: Use words, phrases, and concepts familiar to the user, not system-oriented jargon.
+
+**Modern application**:
+- Domain-specific language matching user's mental model
+- Metaphors that make sense (folder, trash, archive)
+- Date/time in user's locale and relative terms ("2 hours ago")
+- Currency and number formatting per locale
+- Avoid technical errors ("Error 500") — translate to human impact
+
+### 3. User Control and Freedom
+**Classic**: Provide a clearly marked "emergency exit" to leave unwanted states.
+
+**Modern application**:
+- Undo everywhere (Cmd+Z should work)
+- Non-destructive operations by default (soft delete, archive)
+- Easy escape from modals (click outside, Escape key)
+- Clear back/cancel paths in flows
+- Bulk undo for batch operations
+- Draft auto-save so users never lose work
+
+**Examples**: Gmail's "Undo Send", Notion's version history, Linear's Cmd+Z for almost everything.
+
+### 4. Consistency and Standards
+**Classic**: Follow platform conventions — users shouldn't wonder if different words/actions mean the same thing.
+
+**Modern application**:
+- Platform-native keyboard shortcuts (Cmd on Mac, Ctrl on Windows)
+- Standard icon meanings (gear = settings, X = close)
+- Consistent terminology throughout the app
+- Design tokens for spacing, colors, typography
+- Component behavior consistency (all dropdowns work the same)
+
+### 5. Error Prevention
+**Classic**: Eliminate error-prone conditions or present users with a confirmation option.
+
+**Modern application**:
+- Disable invalid actions, don't just error afterward
+- Smart defaults that minimize required input
+- Inline validation as users type
+- Format hints and input masks for structured data
+- Confirmation only for truly destructive/irreversible actions
+- Autosuggest to prevent typos
+
+**Examples**: Stripe's inline card validation, Linear's smart date parsing.
+
+### 6. Recognition Rather Than Recall
+**Classic**: Minimize memory load by making objects, actions, and options visible.
+
+**Modern application**:
+- Command palette with searchable actions (Cmd+K)
+- Recent items and frequently used at the top
+- Contextual actions in right-click menus
+- Autocomplete with recent/suggested options
+- Visual affordances for draggable/interactive elements
+- Breadcrumbs for deep navigation
+
+### 7. Flexibility and Efficiency of Use
+**Classic**: Accelerators — unseen by novices — speed up interaction for experts.
+
+**Modern application**:
+- Keyboard shortcuts for power users
+- Command palette (Cmd+K) for everything
+- Bulk operations and multi-select
+- Quick actions and hover menus
+- Customizable workflows and views
+- API/integrations for automation
+
+**Examples**: Notion's slash commands, Linear's keyboard-first design, Figma's plugins.
+
+### 8. Aesthetic and Minimalist Design
+**Classic**: Don't include information that is irrelevant or rarely needed.
+
+**Modern application**:
+- Progressive disclosure — show advanced options on demand
+- Information hierarchy — most important content is most prominent
+- Whitespace as a design element, not wasted space
+- Reduce visual noise — every element should earn its place
+- Contextual UI that adapts to current task
+
+### 9. Help Users Recognize, Diagnose, and Recover from Errors
+**Classic**: Error messages should be expressed in plain language, precisely indicate the problem, and constructively suggest a solution.
+
+**Modern application**:
+- Error format: What happened → Why → How to fix
+- Inline errors next to the field, not at page top
+- Suggested fixes and one-click resolution when possible
+- Link to help docs for complex errors
+- Never show stack traces or error codes alone
+
+**Example**: "This email is already registered. [Log in instead] or [Reset password]"
+
+### 10. Help and Documentation
+**Classic**: Provide help and documentation that is easy to search and focused on user tasks.
+
+**Modern application**:
+- Contextual help (? icons, tooltips) over manual hunting
+- Searchable help within the app
+- Interactive tutorials and onboarding
+- Empty states as teaching moments
+- Keyboard shortcut cheat sheets (Cmd+/)
+
+## Additional Modern Principles
+
+### Performance is a Feature
+- First contentful paint < 1.5s
+- Time to interactive < 3s
+- Perceived performance through optimistic UI
+- Skeleton screens and progressive loading
+- Offline-capable when relevant
+
+### Mobile is Not Desktop Shrunk Down
+- Touch targets 44×44px minimum
+- Thumb-zone optimized primary actions
+- Swipe gestures for common actions
+- Pull-to-refresh where expected
+- Bottom sheets over modals on mobile
+
+### Accessibility is Not Optional
+- Keyboard navigable
+- Screen reader compatible
+- Sufficient color contrast
+- Focus indicators visible
+- Motion-reduced alternatives

package/skills/dp-ux/references/ux-patterns.md

@@ -0,0 +1,221 @@
+# UX Patterns
+
+Proven patterns for common UI challenges.
+
+## Component States
+
+Every interactive component needs these states designed:
+
+### Button States
+```
+Default → Hover → Focus → Active (pressed) → Disabled → Loading
+```
+- **Loading**: Replace label with spinner, maintain button width, disable interaction
+- **Disabled**: Reduce opacity (50-60%), remove hover effects, `cursor: not-allowed`
+- **Focus**: Visible ring (not just browser default), works on dark and light backgrounds
+
+### Input States
+```
+Empty → Focused → Filled → Error → Disabled → Read-only
+```
+- **Focused**: Border color change + subtle shadow/glow
+- **Error**: Red border + error icon + message below (not just red border)
+- **Filled**: Subtle distinction from empty (optional, for complex forms)
+
+### Card/Item States
+```
+Default → Hover → Selected → Dragging → Drop target
+```
+- **Hover**: Subtle lift (shadow) or background shift
+- **Selected**: Checkmark + background color + border (multiple indicators)
+- **Dragging**: Reduced opacity on original, cursor change
+
+## Empty States
+
+Never leave users staring at blank space.
+
+**Good empty state includes**:
+1. Clear message about why it's empty
+2. Visual element (illustration or icon)
+3. Primary action to remedy the emptiness
+4. Secondary context (optional)
+
+**Examples**:
+```
+[Illustration of inbox]
+No messages yet
+When you receive messages, they'll appear here.
+[Compose message] ← Primary CTA
+```
+
+```
+[Search icon]
+No results for "quarterly reports"
+Try adjusting your search or filters.
+[Clear filters] [Browse all]
+```
+
+## Loading States
+
+### Skeleton Screens (preferred for content)
+- Match layout of expected content
+- Animate with subtle shimmer (left to right)
+- Transition smoothly to loaded state
+
+### Spinners (for actions)
+- Use for button loading states
+- Use for discrete operations (save, submit)
+- Include timeout/retry for long operations
+
+### Progress Bars (for known duration)
+- File uploads, multi-step processes
+- Show percentage or steps remaining
+- Include cancel option for long operations
+
+### Optimistic UI (for fast actions)
+- Show success immediately, reconcile in background
+- Have rollback plan for failures
+- Example: Toggling a like shows instantly, syncs async
+
+## Error Handling
+
+### Inline Validation
+```
+[Email input with red border]
+✗ Please enter a valid email address
+```
+- Validate on blur (not on every keystroke)
+- Clear error when user starts fixing
+- Show success state when corrected ✓
+
+### Error Messages Formula
+```
+What happened + Why + How to fix
+```
+
+**Bad**: "Error 422: Unprocessable entity"
+**Good**: "We couldn't save your changes. The file is too large (max 10MB). Try compressing it or choosing a smaller file."
+
+### Error Message Placement
+- Form errors: Below the input, not at page top
+- System errors: Toast notification or banner
+- Critical errors: Full-screen with recovery options
+
+### Error Recovery
+- Preserve user input on error (never clear the form)
+- Offer one-click retry
+- Suggest alternatives when primary path fails
+
+## Feedback & Confirmation
+
+### Toast Notifications
+- Position: Top-right or bottom-center
+- Auto-dismiss: 3-5 seconds for success, persist for errors
+- Include undo action when relevant
+- Stack if multiple (limit to 3 visible)
+
+### Success Feedback
+- Checkmark animation (200-300ms)
+- Brief toast: "Saved" / "Sent" / "Done"
+- Don't overdo it — success should feel lightweight
+
+### Destructive Action Confirmation
+**Use confirmation dialog when**:
+- Action is irreversible
+- Data loss would occur
+- Significant impact on others
+
+**Avoid confirmation when**:
+- Undo is available
+- Action is easily recoverable
+- Frequent/routine action
+
+**Confirmation dialog pattern**:
+```
+Delete "Q3 Report"?
+This will permanently delete the file and cannot be undone.
+[Cancel] [Delete] ← Destructive action in red, on right
+```
+
+## Navigation Patterns
+
+### Breadcrumbs
+- Use for hierarchical content (> 2 levels deep)
+- Current page is last item, not clickable
+- Truncate middle items on mobile: Home > ... > Current
+
+### Tabs
+- Use for same-level, parallel content
+- One tab active at a time
+- Content changes, URL optionally changes
+- Tab count: 2-7 (more = consider different pattern)
+
+### Command Palette (Cmd+K)
+- Search across all actions, pages, items
+- Recent/frequent items first
+- Keyboard navigable (arrows, enter)
+- Show keyboard shortcuts in results
+
+### Back Navigation
+- Back button returns to previous view/state
+- Preserve scroll position and filters when returning
+- Clear navigation history mental model
+
+## Form Patterns
+
+### Single Column Layout
+- One column for most forms (fastest to complete)
+- Only use multi-column for related short fields (First/Last name)
+
+### Logical Grouping
+- Group related fields with subtle visual separator
+- Limit groups to 5-7 fields each
+- Progressive disclosure for optional/advanced fields
+
+### Smart Defaults
+- Pre-fill from context (timezone from location, etc.)
+- Remember user preferences
+- Select most common option by default
+
+### Required vs Optional
+- If most fields required: Mark optional ones "(optional)"
+- If most fields optional: Mark required ones with asterisk *
+- Never mark both — redundant
+
+### Form Submission
+```
+[Idle] → [Submitting...] → [Success ✓] or [Error]
+```
+- Disable submit button while processing
+- Show inline errors on validation failure
+- Success: Navigate away or show clear confirmation
+
+## Mobile-Specific Patterns
+
+### Bottom Sheet
+- Prefer over modals on mobile
+- Drag handle at top
+- Swipe down to dismiss
+- Multiple breakpoints (peek, half, full)
+
+### Pull to Refresh
+- Use for feed/list content
+- Loading spinner at top
+- Release threshold before triggering
+
+### Swipe Actions
+- Swipe to reveal actions (delete, archive)
+- Show action preview during swipe
+- Snap back if not completed
+
+### Thumb Zone
+```
+┌─────────────────┐
+│   Hard to reach │
+│                 │
+│    Okay reach   │
+│                 │
+│    Easy reach   │ ← Primary actions here
+└─────────────────┘
+```
+Primary actions (FAB, main nav) in bottom third.

package/templates/config.json

@@ -0,0 +1,55 @@
+{
+  "version": "2.1",
+  "created": "",
+  "project_name": "",
+  "workflow": {
+    "current_phase": 0,
+    "phases_completed": [],
+    "workflow_status": "not_started",
+    "executions": {
+      "wireframe": {
+        "completed": false,
+        "timestamp": null,
+        "output_dir": null
+      },
+      "polished": {
+        "completed": false,
+        "timestamp": null,
+        "output_dir": null
+      }
+    }
+  },
+  "settings": {
+    "depth": "standard",
+    "challenge_mode": "heavy"
+  },
+  "phases": {
+    "discovery": {
+      "enabled": true,
+      "challenge_mode": "heavy",
+      "depth": "standard"
+    },
+    "ux": {
+      "enabled": true,
+      "include_accessibility": true,
+      "include_all_states": true
+    },
+    "ui": {
+      "enabled": true,
+      "include_b2b": false,
+      "include_data_viz": false,
+      "grid_system": "8px"
+    },
+    "review": {
+      "enabled": true,
+      "severity_threshold": "moderate",
+      "include_spec_alignment": true
+    }
+  },
+  "optional_phases": {
+    "research": {
+      "enabled": false,
+      "methods": []
+    }
+  }
+}