DSP - Design Shit Properly

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.

/dsp:start → /dsp:discovery → [/dsp:prd] → /dsp:ux → /dsp:execute → [/dsp:color] → /dsp:ui → /dsp:execute → /dsp:eng_review → /dsp:verify
                               (optional)            (wireframe)      (optional)              (polished)

Installation

npx design-shit-properly

Options

npx design-shit-properly --global     # Install to ~/.claude/ (copies files)
npx design-shit-properly --local      # Install to ./.claude/ (current project)
npx design-shit-properly --uninstall  # Remove DSP

Symlink Install (recommended)

For painless updates, install globally with symlinks. Future updates via npm update -g take effect instantly — no re-running the installer.

npm install -g design-shit-properly   # Install package globally
dsp --global --link                   # Symlink to ~/.claude/

Updating

# Symlink install:
npm update -g design-shit-properly    # Instant — symlinks point to new version

# Copy install:
npx design-shit-properly@latest       # Re-downloads and overwrites
npx design-shit-properly --update     # Or check + update interactively

What's New in v2.6

• Aesthetic Direction System — New archetype-based visual direction that flows through the entire pipeline. Choose from 5 archetypes during /dsp:start or /dsp:discovery: Dark & Dense (Linear, Raycast), Light & Luxurious (Stripe, Clerk), Minimal & Stark (Vercel, Supabase), Warm & Approachable (Airbnb, Notion), Bold & Expressive (Spotify, Discord)
• Standalone Quick-Start — /dsp:ui without a workflow now presents an archetype picker for rapid prototyping. Pick a direction and get a custom design system guided by real-world principles
• New reference: aesthetic-archetypes.md — Distilled patterns from 55+ production interfaces across 6 design dimensions (typography, color, depth, radius, spacing, dark mode). Principles, not brand-specific tokens — the final system is always custom
• Discovery captures visual direction — New "Aesthetic & Visual Direction" questions in the discovery interrogation, with structured output in DISCOVERY.md frontmatter that flows to the UI phase

• Unified dsp: namespace — All skills now live under the dsp: prefix for a consistent, discoverable workflow. Renames: /ux-jesus → /dsp:discovery, /ux → /dsp:ux, /ui → /dsp:ui, /design-engineer → /dsp:eng_review, /color-theorist → /dsp:color, /prd-generator → /dsp:prd, /ux-research → /dsp:research
• Every command is now /dsp:* — No more mixed naming. The full workflow reads: /dsp:start → /dsp:discovery → /dsp:ux → /dsp:ui → /dsp:eng_review → /dsp:verify

• PRD Generator skill — New /dsp:prd skill for creating industry-standard Product Requirements Documents through a guided interview process. Supports multiple output formats (Markdown, HTML, .docx) and dual-audience output (stakeholder-ready or Claude Code-ready specs). Includes 3 reference files for interview questions, section templates, and Claude Code spec format
• PRD as optional workflow phase — /dsp:prd is now a formal optional phase (Phase 1.5) between Discovery and UX. When enabled, it pre-fills interview answers from DISCOVERY.md instead of re-interviewing from scratch, and outputs PRD.md to .design/phases/
• Workflow integration — /dsp:start asks about PRD needs, /dsp:progress shows PRD status, /dsp:skip and /dsp:back handle PRD navigation, /dsp:verify checks PRD.md artifacts and Discovery-to-PRD / PRD-to-UX wiring
• 53-test suite — Up from 50, now validates prd-generator skill, frontmatter, and optional phase config

• Color Theorist skill — New /dsp:color skill for OKLCH palette generation, APCA/WCAG contrast checking, shade ramps (25-900), gamut management, and design token export. Includes 6 reference files and a Python token export script
• Color System as optional workflow phase — /dsp:color is now a formal optional sub-phase between UX and UI with full state tracking, context loading, COLOR-SYSTEM.md output, and automatic handoff to /dsp:ui
• Enriched UI skill — Restructured with 7 reference files covering design tokens & theming, component visual specs, modern CSS (container queries, view transitions, fluid type), visual design principles, B2B enterprise patterns, data visualization, and a pre-delivery quality checklist
• 50-test suite — Up from 47, now validates color-theorist skill and optional phase config
• Workflow integration — /dsp:start asks about color system needs, /dsp:progress shows color system status, /dsp:verify checks COLOR-SYSTEM.md artifacts and Color-to-UI wiring

• Project auto-detection — /dsp:execute detects your framework, component directory, and dev server instead of assuming Next.js
• State validation — Commands validate config.json on load and offer to repair corrupted state
• 47-test suite — Automated checks run before every publish (version sync, file integrity, no hardcoded paths)
• --verbose flag — Troubleshoot installs with npx design-shit-properly --verbose
• Workflow navigation — Every skill and command shows where you are in the pipeline and what comes next
• Installer hardening — Symlink protection, depth limits, clear error messages with file-level context

Quick Start

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

Workflow

| # | Phase | Command | Output | |---|-------|---------|--------| | 1 | Discovery | /dsp:discovery | DISCOVERY.md | | -- | PRD (optional) | /dsp:prd | PRD.md | | 2 | UX | /dsp:ux | UX-DECISIONS.md | | 2a | Execute | /dsp:execute | Wireframe components | | -- | Color System (optional) | /dsp:color | COLOR-SYSTEM.md | | 3 | UI | /dsp:ui | UI-SPEC.md | | 3a | Execute | /dsp:execute | Polished components | | 4 | Review | /dsp:eng_review | REVIEW.md | | 5 | Verify | /dsp:verify | Verification report |

Commands

| Command | Description | |---------|-------------| | /dsp:start | Initialize a new design project | | /dsp:progress | View workflow status with progress bar | | /dsp:execute | Generate implementation (wireframe or polished) | | /dsp:discuss | Capture decisions before a phase | | /dsp:verify | Goal-backward verification | | /dsp:skip | Skip current phase | | /dsp:back | Return to previous phase |

Skills

| Skill | Purpose | |-------|---------| | /dsp:discovery | Discovery agent - interrogates requirements with heavy challenge mode | | /dsp:prd | PRD generation - interview-driven, stakeholder-ready or Claude Code-ready specs | | /dsp:ux | UX principles - user flows, states, accessibility | | /dsp:color | OKLCH palettes, shade ramps, contrast checking, color theory | | /dsp:ui | Visual design - grids, tokens, aesthetic archetypes, B2B patterns, data viz | | /dsp:eng_review | Code review - a11y, React patterns, spec alignment | | /dsp:research | Research planning - interviews, usability tests, synthesis |

Implementation Generation

DSP 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

Discovery → [PRD] → UX Decisions → /dsp:execute → Test Flow → [/dsp:color] → UI Spec → /dsp:execute → Final Component
           (opt.)                      ↓                        (optional)                        ↓
                                  Wireframe                                                  Polished

State Management

DSP 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
    ├── PRD.md               # Optional: formal PRD
    ├── UX-DECISIONS.md      # Phase 2 output
    ├── COLOR-SYSTEM.md      # Optional: color tokens & palettes
    ├── UI-SPEC.md           # Phase 3 output
    └── REVIEW.md            # Phase 4 output

Verification

/dsp: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
  },
  "phases": {
    "ux": { "include_accessibility": true },
    "ui": { "include_b2b": true, "aesthetic_direction": "minimal-stark" }
  },
  "optional_phases": {
    "prd": { "enabled": false, "format": "markdown", "audience": "mixed" },
    "color_system": { "enabled": true, "accessibility_level": "AA", "include_dark_mode": true },
    "research": { "enabled": false }
  }
}

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. DSP skills are loaded on startup.

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

If files are missing, re-run the installer:

npx design-shit-properly@latest --global

.design/ already exists

If /dsp: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/

/dsp: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

/dsp: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.