design-protocol 1.0.0

package/skills/dp-ui/references/visual-design-principles.md

@@ -0,0 +1,237 @@
+# Visual Design Principles
+
+The foundational rules behind polished, professional interfaces.
+
+## Grid Systems
+
+### The 8px Grid
+All spacing, sizing, and positioning should use multiples of 8px:
+- **4px** — Fine adjustments only (icon padding, border radius)
+- **8px** — Minimum spacing unit
+- **16px** — Common element padding
+- **24px** — Section spacing
+- **32px** — Major section breaks
+- **48px, 64px** — Large spacing, hero areas
+
+**Why 8px?** Divisible by 2 and 4, scales well, aligns with common screen sizes.
+
+### Column Grids
+```
+┌──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┬──┐
+│1 │2 │3 │4 │5 │6 │7 │8 │9 │10│11│12│  ← 12-column grid
+└──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┴──┘
+```
+- **12 columns** — Most flexible (divisible by 2, 3, 4, 6)
+- **Gutters** — 16px (compact), 24px (standard), 32px (spacious)
+- **Margins** — Consistent left/right page margins (16-64px depending on viewport)
+
+### Responsive Breakpoints
+```
+Mobile:     320px - 767px    (1-4 columns)
+Tablet:     768px - 1023px   (6-8 columns)
+Desktop:    1024px - 1439px  (12 columns)
+Large:      1440px+          (12 columns, max-width container)
+```
+
+## Visual Hierarchy
+
+### Size Scale
+Establish a type scale with clear hierarchy:
+```
+Display:    32-48px  — Hero headlines
+H1:         24-32px  — Page titles
+H2:         20-24px  — Section headers
+H3:         16-18px  — Subsection headers
+Body:       14-16px  — Primary content
+Caption:    12-13px  — Secondary info, metadata
+Micro:      10-11px  — Badges, labels (use sparingly)
+```
+
+### Weight Hierarchy
+- **Bold (600-700)** — Headlines, emphasis, primary labels
+- **Medium (500)** — Subheadings, interactive elements
+- **Regular (400)** — Body text, secondary content
+- **Light (300)** — Use rarely, only for large display text
+
+### Creating Hierarchy
+```
+┌─────────────────────────────────────┐
+│  MOST IMPORTANT                     │  ← Largest, boldest, highest contrast
+│                                     │
+│  Secondary Information              │  ← Medium size, regular weight
+│                                     │
+│  Supporting details and metadata    │  ← Smaller, lighter, lower contrast
+└─────────────────────────────────────┘
+```
+
+**The Squint Test**: Blur your vision — can you still identify what's most important?
+
+## Gestalt Principles
+
+### Proximity
+Items close together are perceived as related.
+```
+Good:                          Bad:
+┌────────┐ ┌────────┐         ┌────────┐
+│ Name   │ │ Email  │         │ Name   │
+│ [____] │ │ [____] │         │ [____] │
+└────────┘ └────────┘         │        │
+                              │ Email  │
+┌────────┐ ┌────────┐         │ [____] │
+│ City   │ │ Zip    │         │        │
+│ [____] │ │ [____] │         │ City   │
+└────────┘ └────────┘         └────────┘
+```
+
+### Similarity
+Similar-looking elements are perceived as related.
+- Same color = same category/type
+- Same shape = same function
+- Same size = same importance
+
+### Continuity
+Eyes follow lines, edges, and curves.
+- Align elements to create visual flow
+- Use consistent left edges for forms
+- Horizontal rules guide scanning
+
+### Closure
+The mind completes incomplete shapes.
+- Progress indicators don't need full circles
+- Icons can be simplified/abstracted
+- Negative space can define shapes
+
+### Figure/Ground
+Clear separation between content (figure) and background (ground).
+- Sufficient contrast between layers
+- Cards/panels create figure separation
+- Shadows establish depth hierarchy
+
+## Typography
+
+### Font Pairing
+- **One family** often enough — Use weight/size for variation
+- **Two families max** — Display + body (e.g., serif headlines + sans body)
+- **Contrast is key** — If pairing, make them clearly different
+
+### Line Length
+- **Optimal**: 50-75 characters per line
+- **Minimum**: 45 characters
+- **Maximum**: 90 characters
+- Too wide = hard to track back to next line
+- Too narrow = choppy, awkward breaks
+
+### Line Height
+- **Body text**: 1.4-1.6 (150% is safe default)
+- **Headlines**: 1.1-1.3 (tighter for large text)
+- **Dense UI**: 1.3-1.4 (tables, lists)
+
+### Letter Spacing
+- **Body**: 0 (default)
+- **Headlines**: -0.5 to -2% (slightly tighter)
+- **ALL CAPS**: +2 to +5% (more spacing needed)
+- **Small text**: +1 to +2% (improves legibility)
+
+## Color Theory
+
+### Color Roles
+```
+Primary:    Brand color, primary actions
+Secondary:  Supporting actions, accents
+Neutral:    Text, borders, backgrounds (gray scale)
+Success:    Confirmations, positive states (green)
+Warning:    Caution, attention needed (yellow/orange)
+Error:      Problems, destructive actions (red)
+Info:       Informational states (blue)
+```
+
+### Color Application
+- **60-30-10 Rule**: 60% dominant, 30% secondary, 10% accent
+- **Backgrounds**: Neutral, low saturation
+- **Text**: High contrast against background
+- **Interactive**: Consistent color for clickable elements
+- **Status**: Reserved colors for semantic meaning
+
+### Creating Depth
+```
+Background layers (light theme):
+Layer 0:    #FFFFFF (white)     — Base
+Layer 1:    #F9FAFB (gray-50)   — Subtle sections
+Layer 2:    #F3F4F6 (gray-100)  — Cards, panels
+Layer 3:    #E5E7EB (gray-200)  — Hover states
+```
+
+### Dark Mode Considerations
+- Don't just invert — redesign surfaces
+- Reduce contrast slightly (not pure white on black)
+- Desaturate colors slightly
+- Shadows become less visible — use borders instead
+- Elevation through lighter surfaces, not shadows
+
+## Alignment & Consistency
+
+### The Alignment Principle
+**Everything should align to something.**
+- Create invisible lines that elements follow
+- Left-align most content (for LTR languages)
+- Center only for short, focused content
+- Right-align numbers in columns
+
+### Consistency Rules
+- Same spacing for same relationships
+- Same size for same importance level
+- Same color for same meaning
+- Same component for same function
+- If breaking consistency, do it dramatically (not subtly)
+
+## Motion & Interaction
+
+### Timing Guidelines
+- **Instant (0-100ms)**: Hovers, micro-interactions.
+- **Fast (200-300ms)**: Dropdowns, toggles, small transitions.
+- **Natural (300-500ms)**: Page transitions, large movements.
+
+### Easing
+- **Ease-out (Decelerate)**: Elements entering view (feels natural).
+- **Ease-in (Accelerate)**: Elements exiting view.
+- **Linear**: Loaders and color changes only.
+
+## Elevation & Depth
+
+### Shadow Scale
+- **Level 1 (Pressed/Low)**: `0 1px 2px rgba(0,0,0,0.05)` — Cards, controls
+- **Level 2 (Dropdowns)**: `0 4px 6px -1px rgba(0,0,0,0.1)` — Popovers
+- **Level 3 (Sticky)**: `0 10px 15px -3px rgba(0,0,0,0.1)` — Header, dock
+- **Level 4 (Modal)**: `0 20px 25px -5px rgba(0,0,0,0.1)` — Dialogs, drawers
+
+### Z-Index Layers
+- **0-99**: Content layers
+- **100-199**: Navigation (Sticky headers)
+- **200-299**: Dropdowns & Popovers
+- **300-399**: Overlays (Backdrops)
+- **400-499**: Modals
+- **500+**: Toasts and Tooltips
+
+## Accessibility Standards
+
+### WCAG AA Compliance
+- **Comparison**: 4.5:1 ratio for normal text, 3:1 for large text.
+- **UI Elements**: 3:1 contrast for borders on inputs/buttons.
+- **Focus Indicators**: Visible outline (2px recommended) for keyboard navigation.
+
+### Semantic Structure
+- Use real `<button>` and `<a>` tags.
+- Headings (`h1`-`h6`) must be in descending order.
+- Meaningful `alt` text for informational images.
+
+## Visual Polish Checklist
+
+- [ ] All elements align to the grid
+- [ ] Spacing is consistent (8px multiples)
+- [ ] Type scale is defined and followed
+- [ ] Colors are from a defined palette
+- [ ] Visual hierarchy is clear (squint test)
+- [ ] Related items are grouped (proximity)
+- [ ] Similar items look similar (consistency)
+- [ ] Sufficient contrast for accessibility
+- [ ] Details are refined (borders, shadows, radius)

package/skills/dp-ux/SKILL.md

@@ -0,0 +1,414 @@
+---
+name: dp-ux
+description: Apply UX/UI design principles for intuitive, accessible interfaces. Use with "/dp:ux", UX review, usability improvements, or user-centered design. Phase 2 of DP workflow.
+---
+
+# UX/UI Design Excellence
+
+Create interfaces that feel as polished as Linear, Stripe, Notion, and Vercel — products where every interaction feels intentional and effortless.
+
+---
+
+## DP Workflow Integration
+
+This skill is Phase 2 of the DP (Design Protocol) workflow. It automatically detects and integrates with the workflow when present.
+
+### Detecting Workflow Mode
+
+At the start of any `/dp:ux` invocation:
+
+1. **Check for `.design/config.json`**
+2. **If found** (workflow mode):
+   - Load `.design/phases/DISCOVERY.md` for context
+   - Load `.design/REQUIREMENTS.md` for requirements to address
+   - Check for `02-CONTEXT.md` if `/dp:discuss` was run first
+   - Announce: "Loading context from discovery phase..."
+   - Display summary: "Working on: [problem statement]"
+3. **If not found** (standalone mode):
+   - Run with default behavior
+   - Ask: "What would you like me to review for UX principles?"
+
+### Context Loading (Workflow Mode)
+
+When `.design/phases/DISCOVERY.md` exists, extract and display:
+
+```
+DP WORKFLOW ACTIVE
+────────────────────────────────────────────────────────────────────────────────
+Project: [name]
+Phase: 2 of 4 (UX)
+Previous: Discovery complete
+
+From Discovery:
+• Problem: [problem statement one-liner]
+• User: [primary user role]
+• Goals: [user goals]
+• Key Requirements:
+  - [Must-have 1]
+  - [Must-have 2]
+  - [Must-have 3]
+
+Your Focus This Phase:
+Apply UX principles to design user flows and component states.
+────────────────────────────────────────────────────────────────────────────────
+
+Ready to proceed? Or /dp:back to revisit discovery.
+```
+
+### Context Sources
+
+| From Discovery | Used For |
+|----------------|----------|
+| Problem statement | Focus area for UX work |
+| Primary user | Persona context for decisions |
+| User goals | Flow design targets |
+| Requirements | Constraint checklist |
+| Constraints | Design boundaries |
+| Open questions | Items to address |
+| Journey map | Starting point for flows |
+
+---
+
+## Workflow
+
+1. **Always combine with frontend-design skill** — Read and apply both skills together
+2. **Audit against UX principles** — Check references/usability-principles.md
+3. **Verify accessibility** — Check references/accessibility-checklist.md
+4. **Apply proven patterns** — Check references/dp:ux-patterns.md for states, feedback, navigation
+5. **Benchmark against excellence** — Check references/product-excellence.md for inspiration
+
+---
+
+## Core UX Principles
+
+### Clarity Over Cleverness
+
+- One primary action per screen/component
+- Labels over icons alone (or icon + tooltip minimum)
+- Show, don't tell — progressive disclosure over upfront complexity
+
+### Respect Cognitive Load
+
+- Chunk information (7±2 items max in lists/groups)
+- Sensible defaults — users shouldn't configure before starting
+- Recognition over recall — show options, don't make users remember
+
+### Feedback & Responsiveness
+
+- Every action needs visible feedback (< 100ms perceived)
+- Optimistic UI for common actions
+- Clear system status — loading, success, error states always visible
+
+### Error Prevention > Error Messages
+
+- Disable invalid actions, don't just error on them
+- Inline validation as users type, not on submit
+- Undo over confirmation dialogs when possible
+
+### Consistency & Predictability
+
+- Same action = same result everywhere
+- Standard patterns for standard tasks (don't reinvent navigation)
+- Spatial consistency — elements don't jump between states
+
+### Mobile-First Thinking
+
+- Touch targets minimum 44×44px
+- Thumb-zone awareness for primary actions
+- Content hierarchy must work at 320px width
+
+---
+
+## State Coverage Matrix
+
+**Every interactive component needs ALL of these states defined:**
+
+| State | Description | Required? |
+|-------|-------------|-----------|
+| **Default** | Normal resting state | Yes |
+| **Hover** | Mouse over (desktop) | Yes |
+| **Focus** | Keyboard focus (visible ring) | Yes |
+| **Active/Pressed** | Being clicked/tapped | Yes |
+| **Disabled** | Cannot interact | When applicable |
+| **Loading** | Async operation in progress | For async actions |
+| **Error** | Something went wrong | For forms/inputs |
+| **Empty** | No content/data | For lists/tables |
+| **Success** | Operation completed | For confirmations |
+
+**In workflow mode, explicitly document each state for key components.**
+
+---
+
+## Implementation Checklist
+
+Before finalizing any UI:
+
+- [ ] Can a new user complete the primary task without instructions?
+- [ ] Are all interactive states covered? (see matrix above)
+- [ ] Does it work with keyboard only?
+- [ ] Is color not the only indicator of meaning?
+- [ ] Are error messages actionable? (what happened + how to fix)
+- [ ] Does it feel fast? (perceived performance)
+- [ ] Is the most important action visually dominant?
+
+---
+
+## Output Structure (Workflow Mode)
+
+When in workflow mode, produce structured output:
+
+### UX-DECISIONS.md Structure
+
+```yaml
+---
+phase: ux
+skill: ux
+completed: YYYY-MM-DDTHH:MM:SSZ
+context_loaded:
+  - DISCOVERY.md
+  - 02-CONTEXT.md (if existed)
+requirements_addressed:
+  - REQ-01
+  - REQ-02
+components_specified:
+  - ComponentName1
+  - ComponentName2
+---
+
+# UX Decisions: [Feature Name]
+
+## User Flow
+
+[Flow diagram or description]
+
+```
+[Entry Point] → [Step 1] → [Decision Point] → [Step 2a/2b] → [Success State]
+                              ↓
+                         [Error Path]
+```
+
+## Usability Principles Applied
+
+| Principle | Application | Rationale |
+|-----------|-------------|-----------|
+| Clarity | [How applied] | [Why] |
+| Cognitive Load | [How applied] | [Why] |
+| ... | ... | ... |
+
+## Key UX Decisions
+
+| Decision | Options Considered | Chosen | Rationale |
+|----------|-------------------|--------|-----------|
+| [Decision 1] | A, B, C | B | [Why B was chosen] |
+| ... | ... | ... | ... |
+
+## Component Behaviors
+
+### [Component 1]
+
+**Purpose:** [What it does]
+
+**States:**
+| State | Behavior | Visual Indicator |
+|-------|----------|------------------|
+| Default | [behavior] | [visual] |
+| Hover | [behavior] | [visual] |
+| Focus | [behavior] | [visual] |
+| Active | [behavior] | [visual] |
+| Disabled | [behavior] | [visual] |
+| Loading | [behavior] | [visual] |
+| Error | [behavior] | [visual] |
+| Empty | [behavior] | [visual] |
+| Success | [behavior] | [visual] |
+
+**Interactions:**
+- Click: [what happens]
+- Keyboard: [what keys do what]
+- Touch: [mobile behavior]
+
+### [Component 2]
+...
+
+## Accessibility Requirements
+
+| Requirement | WCAG | Implementation |
+|-------------|------|----------------|
+| Keyboard navigation | 2.1.1 | [How] |
+| Focus visibility | 2.4.7 | [How] |
+| Color independence | 1.4.1 | [How] |
+| Label association | 1.3.1 | [How] |
+| Touch targets | 2.5.5 | [How] |
+
+## Error Handling
+
+| Error Scenario | User Message | Recovery Action |
+|----------------|--------------|-----------------|
+| [Scenario 1] | [Message] | [What user can do] |
+| ... | ... | ... |
+
+## Empty States
+
+| Empty State | What Shows | User Action |
+|-------------|------------|-------------|
+| No data | [Message + visual] | [CTA] |
+| No results | [Message] | [Suggestions] |
+| First use | [Onboarding] | [Getting started] |
+
+## Loading States
+
+| Operation | Loading Indicator | Placement |
+|-----------|-------------------|-----------|
+| Page load | [Skeleton/Spinner] | [Where] |
+| Form submit | [Button state] | [In button] |
+| Data fetch | [Placeholder] | [In container] |
+
+## Requirements Coverage
+
+| Requirement | Addressed By | Notes |
+|-------------|--------------|-------|
+| REQ-01: [text] | [Component/Flow] | |
+| REQ-02: [text] | [Component/Flow] | |
+
+## Handoff Notes for UI Phase
+
+- Key visual direction: [guidance]
+- Critical interactions: [list]
+- Accessibility priorities: [list]
+- Open visual questions: [list]
+```
+
+---
+
+## State Updates (Workflow Mode)
+
+After completing UX analysis:
+
+1. **Write output to `.design/phases/UX-DECISIONS.md`**
+
+2. **Update `.design/STATE.md`**:
+```markdown
+## Current Position
+Phase: 2 of 4 (UX)
+Status: completed
+Progress: [█████░░░░░] 50%
+
+### Last Activity
+- **Date:** [TIMESTAMP]
+- **Action:** Completed UX phase with /dp:ux
+- **User:** [session user]
+
+### Accumulated Context
+...
+#### Major Decisions Made
+| Phase | Decision | Impact |
+|-------|----------|--------|
+| Discovery | [decision] | [impact] |
+| UX | [key UX decision 1] | [impact] |
+| UX | [key UX decision 2] | [impact] |
+```
+
+3. **Update `.design/config.json`**:
+```json
+{
+  "workflow": {
+    "current_phase": 3,
+    "phases_completed": ["discovery", "ux"],
+    "workflow_status": "in_progress"
+  }
+}
+```
+
+4. **Update `.design/REQUIREMENTS.md`** with addressed requirements
+
+---
+
+## Handoff (Workflow Mode)
+
+```
+═══════════════════════════════════════════════════════════════════════════════
+UX DECISIONS COMPLETE
+═══════════════════════════════════════════════════════════════════════════════
+
+Output: .design/phases/UX-DECISIONS.md
+
+Summary:
+• User flow documented with [N] steps
+• [M] components specified with full state coverage
+• [P] accessibility requirements documented
+• Requirements addressed: [list]
+
+Progress: [█████░░░░░] 50%
+
+Ready for Next Phase?
+────────────────────────────────────────────────────────────────────────────────
+→ /dp:ui to continue to visual design (recommended)
+→ /dp:discuss to capture visual direction first
+
+Or:
+→ /dp:progress to review full status
+→ /dp:back to revisit discovery
+
+═══════════════════════════════════════════════════════════════════════════════
+```
+
+---
+
+## Standalone Mode Behavior
+
+When no `.design/` directory exists:
+
+1. Output UX analysis inline (current behavior)
+2. Ask standard handoff question:
+   > "Would you like me to run `/dp:ui` for visual design principles?"
+3. Optionally offer: "Or start a full DP workflow with `/dp:start`?"
+
+---
+
+## Reference Files
+
+Load these as needed for detailed guidance:
+
+- **references/usability-principles.md** — Nielsen's heuristics + modern interpretations
+- **references/accessibility-checklist.md** — Essential WCAG compliance
+- **references/dp:ux-patterns.md** — Patterns for states, feedback, navigation, forms
+- **references/product-excellence.md** — What makes Linear, Stripe, Notion exceptional
+
+---
+
+## Config Integration
+
+Respects these settings from `.design/config.json`:
+```json
+{
+  "phases": {
+    "ux": {
+      "enabled": true,
+      "includeAccessibility": true,
+      "includeAllStates": true
+    }
+  }
+}
+```
+
+When `includeAccessibility: true`, always include accessibility requirements section.
+When `includeAllStates: true`, require full state matrix for all components.
+
+---
+
+## Workflow Navigation
+
+```
+                                         ┌─────────┐
+/dp:start    →    /dp:discovery    →       │ YOU ARE  │    →    /dp:execute    →    /dp:ui    →    /dp:execute    →    /dp:eng_review    →    /dp:verify
+                    Phase 1              │  HERE   │         (wireframe)          Phase 3      (polished)          Phase 4
+                                         │ Phase 2 │
+                                         └─────────┘
+```
+
+| | |
+|---|---|
+| **Previous** | `/dp:discovery` — Discovery & requirements (Phase 1) |
+| **Current** | `/dp:ux` — UX principles & states (Phase 2) |
+| **Next** | `/dp:execute` — Generate wireframe implementation |
+| **Related** | `/dp:discuss` — Capture context before this phase |
+| | `/dp:back` — Return to discovery if requirements changed |