DP - Design Protocol

A complete design workflow system for Claude Code. Takes you from vague requirements to polished, reviewed implementations with state management, implementation generation, and goal-backward verification.

/dp:start → /dp:discovery → /dp:ux → /dp:execute → /dp:ui → /dp:execute → /dp:eng_review → /dp:verify
                               (wireframe)          (polished)

Installation

npx design-protocol

Options

npx design-protocol --global     # Install to ~/.claude/ (all projects)
npx design-protocol --local      # Install to ./.claude/ (current project)
npx design-protocol --uninstall  # Remove DP

Updating

npx design-protocol --check-update  # Check for updates
npx design-protocol --update        # Update to latest version
npx design-protocol@latest          # Or install latest directly

Quick Start

/dp:start              # Begin a new design workflow
/dp:progress           # Check where you are
/dp:execute            # Generate implementation
/dp:verify             # Verify completeness

Workflow

| # | Phase | Command | Output | |---|-------|---------|--------| | 1 | Discovery | /dp:discovery | DISCOVERY.md | | -- | PRD (optional) | /dp:prd | PRD.md | | -- | Journey Map (optional) | /dp:journey | JOURNEY-MAP.md | | -- | Roadmap (optional) | /dp:roadmap | ROADMAP.md | | 2 | UX | /dp:ux | UX-DECISIONS.md | | 2a | Execute | /dp:execute | Wireframe components | | -- | Color System (optional) | /dp:color | COLOR-SYSTEM.md | | 3 | UI | /dp:ui | UI-SPEC.md | | 3a | Execute | /dp:execute | Polished components | | 4 | Review | /dp:eng_review | REVIEW.md | | ✓ | Verify (final check) | /dp:verify | Verification report |

Commands

| Command | Description | |---------|-------------| | /dp:start | Front door — asks what you need and routes to a full project, a single deliverable (standalone or tracked), or an existing project. /dp:start full skips the wizard. | | /dp:progress | View workflow status with progress bar | | /dp:execute | Generate implementation (wireframe or polished) | | /dp:discuss | Capture decisions before a phase | | /dp:verify | Goal-backward verification | | /dp:skip | Skip current phase | | /dp:back | Return to previous phase | | /dp:prd | Run PRD as optional phase 1.5a | | /dp:journey | Run journey map as optional phase 1.5b | | /dp:roadmap | Run roadmap as optional phase 1.5c | | /dp:color | Run color system as optional phase 2b | | /dp:storytell | Generate audience-tuned presentation outline (cross-phase) |

Skills

| Skill | Purpose | |-------|---------| | /dp:discovery | Discovery agent — interrogates requirements with heavy challenge mode | | /dp:prd | PRD generation — interview-driven, stakeholder-ready or Claude Code-ready specs | | /dp:journey | Customer journey maps, service blueprints, omnichannel experience maps (NNGroup) | | /dp:roadmap | Theme-based UX roadmap with Now/Next/Future horizons (NNGroup) | | /dp:ux | UX principles — user flows, states, accessibility, cognitive foundations | | /dp:color | OKLCH palettes, shade ramps, contrast checking, color theory | | /dp:ui | Visual design — grids, tokens, aesthetic archetypes, B2B patterns, data viz | | /dp:eng_review | Code review — a11y, React patterns, spec alignment | | /dp:design_check | Design-contract coverage — verify code resolves to your DESIGN.md tokens and principles | | /dp:research | Research planning — interviews, usability tests, synthesis | | /dp:storytell | Audience-tuned presentation outlines for design work (cross-phase) |

Implementation Generation

DP generates working code at two checkpoints:

Wireframe Mode (After UX)

• Validates flow before visual polish
• Minimal styling (gray palette)
• Full functionality
• Output: Auto-detected component directory

Polished Mode (After UI)

• Production-ready components
• Full Tailwind + shadcn/ui
• Design tokens applied
• Output: Auto-detected component directory

UX Decisions → /dp:execute → Test Flow → UI Spec → /dp:execute → Final Component
                   ↓                                      ↓
              Wireframe                              Polished

State Management

DP creates a .design/ directory to track progress:

.design/
├── config.json              # Workflow settings
├── PROJECT.md               # Design vision & constraints
├── REQUIREMENTS.md          # Trackable requirements
├── STATE.md                 # Current state and context
└── phases/
    ├── DISCOVERY.md         # Phase 1 output
    ├── UX-DECISIONS.md      # Phase 2 output
    ├── UI-SPEC.md           # Phase 3 output
    └── REVIEW.md            # Phase 4 output

Verification

/dp:verify performs goal-backward verification:

• Truths - What must be TRUE (problem defined, user understood, etc.)
• Artifacts - What must EXIST (phase documents)
• Wiring - What must CONNECT (requirements → UX → UI → Review)

Configuration

{
  "settings": {
    "depth": "standard",      // quick | standard | thorough
    "challenge_mode": "heavy" // light | heavy
  },
  "design_system": {
    "path": "DESIGN.md",      // your design contract, or null
    "implementation_path": "IMPLEMENTATION.md"
  },
  "phases": {
    "ux": { "include_accessibility": true },
    "ui": { "include_b2b": true }
  }
}

Bring Your Own Design System

If your project has a design contract — a DESIGN.md (or similar) defining tokens, principles, and component rules — DP applies it instead of inventing a parallel system:

• /dp:start auto-detects it (DESIGN.md, design.md, docs/DESIGN.md, design-system.md) and asks only if nothing is found
• /dp:ui runs in apply mode: UI-SPEC.md maps components to your tokens; genuinely missing tokens become "Proposed token additions", never silent inventions
• /dp:color audits and extends your palette instead of generating one
• /dp:execute (polished) consumes your token names through your theming mechanism
• /dp:design_check verifies the shipped code against the contract — token coverage, design intent, and stack rules — and produces a feedback report for your design-system owners

No contract? Everything works as before, and the UI phase's token tables make a good first DESIGN.md.

The Light Path

The full workflow is thorough and token-heavy. When cost matters — a small feature, a tight deadline, a smaller model — here's the honest cheaper shape. Same process, a fraction of the cost:

1. /dp:start and /dp:discovery as normal — but set depth: "quick" (1-2 interrogation rounds). Never cut discovery entirely; a few questions are the cheapest insurance in the whole workflow.
2. Skip the optional phases (PRD, journey, roadmap, color) unless one is the actual point of the work.
3. /dp:ux → /dp:execute (wireframe) as normal — the wireframe checkpoint catches flow problems before any polish is spent on them.
4. Collapse UI + polish: run /dp:ui at depth: "quick", then /dp:execute.
5. /dp:eng_review once, accessibility angle only. /dp:verify as normal — it's cheap and it's the last gate.

When to spend on the full workflow instead: designs you'll live with for quarters, work touching money or user data, and anything where being subtly wrong is expensive.

Standalone vs Workflow

All skills detect .design/config.json:

• Workflow mode - Full context, state updates, structured handoffs
• Standalone mode - Independent operation, inline output

Troubleshooting

Skills not found after install

Restart Claude Code after installing. DP skills are loaded on startup.

# Verify files were installed
ls ~/.claude/skills/    # Should show: dp-discovery, dp-prd, dp-journey, dp-roadmap, dp-ux, dp-color, dp-ui, dp-eng_review, dp-research, dp-storytell, dp-design_check
ls ~/.claude/commands/  # Should show: dp-*.md files

If files are missing, re-run the installer:

npx design-protocol@latest --global

.design/ already exists

If /dp:start finds an existing project, it will ask if you want to continue or start fresh. To manually archive:

mv .design .design-backup-$(date +%Y%m%d)

Permission errors during install

# Check ~/.claude/ ownership
ls -la ~/.claude/

# If owned by root, fix it
sudo chown -R $(whoami) ~/.claude/

/dp:execute can't find components directory

The execute command auto-detects your project structure by reading package.json. If detection fails, it will ask you where to place components. Make sure you run the command from your project root.

Dev server not detected

/dp:execute looks for a running dev server on common ports (3000, 5173, 8080). If yours uses a different port, the command will provide the preview URL for manual access. Just run your dev server separately.

shadcn/ui not detected (polished mode)

The command checks for components.json and @/components/ui/. If you haven't installed shadcn yet:

npx shadcn@latest init

Or tell the command to generate without shadcn — it will use plain Tailwind instead.

Requirements

• Claude Code CLI
• Node.js 14+

License

MIT

Made with frustration at half-assed designs.