design-shit-properly

v2.8.6

Published

a month ago

Design Shit Properly - A complete design workflow system for Claude Code with state management, implementation generation, and goal-backward verification.

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
                              [/dsp:journey]                  (wireframe)     (optional)              (polished)
                              [/dsp:roadmap]
                              (all optional)

Cross-phase (invoke anytime):  /dsp:research   /dsp:storytell

Installation

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

That's it. Restart Claude Code to load DSP.

Updating

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

No re-running the installer. No prompts. Just update and go.

If tools don't appear after restart

npx design-shit-properly --verify     # Check what's installed and what's missing

This prints a per-file status — green ✓ for installed, red ✗ for missing, yellow ⚠ for broken symlinks. If anything is missing, re-run the installer.

Other Install Options

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

Note: copy-based installs require re-running the command on every update.

What's New in v2.8.5

Three new /dsp:ui references — typography.md, motion.md, ux-writing.md. Deep craft guidance that hardens the UI phase against AI monoculture (Inter/Roboto defaults, pure gray neutrals, ease easing, bounce curves, "OK/Submit" buttons, "Click here" links). Each reference synthesizes anti-slop tactical rigor with principles from the canon — Bringhurst, Lupton, Spiekermann, Ruder, Coles on typography; Disney's 12 principles and Val Head on motion; Nielsen scannability, GOV.UK plain language, and Podmajersky voice frameworks on copy. /dsp:ui output is now substantially deeper on vertical rhythm, measure (66ch target), historical-voice font selection, letterform anatomy, motion-that-communicates (relationship/causality/feedback/continuity), spatial grammar, the two laws of UX copy (users scan; write copy before layout), and label/instruction/placeholder distinction.

Three new skills — /dsp:journey (customer journey maps, service blueprints, omnichannel maps), /dsp:roadmap (theme-based UX roadmaps with Now/Next/Future horizons), /dsp:storytell (audience-tuned presentation outlines for design work). Grounded in NNGroup methodology (Kaplan, Salazar, Gibbons, Kaley, Flaherty) plus Minto Pyramid, Duarte Sparkline, Heath SUCCESs, and Greever's response process.
dsp-ux enriched with cognitive foundations — 7 cognitive domains (Memory, Attention, Mental Models, Perception, Language, Emotion, Thinking & Decision-Making) plus designer biases to guard against. Every UX decision now articulates its cognitive basis.
Workflow state machine hardened — New workflow.current_optional_phase tracks in-flight optional subphases. New workflow.phases_skipped parallel array keeps phases_completed a homogeneous string array for downstream .includes() consumers. Main phases are non-exemptable for complete (skipping Discovery/UX/UI/Review keeps the workflow at gaps).
/dsp:back collision-safe archiving — Rolls back cleanly without clobbering prior .vN.md history, archives later canonical artifacts to prevent silent reclassification, filters selectable labels to strictly earlier than current position.
--verify hardened — Auto-detects whichever install (global/local) exists, walks nested skill files (not just SKILL.md), uses lstat so broken symlinks are surfaced instead of hidden, exits non-zero on failure. Install-time verification now rolls back written paths on failure instead of leaving a partial state.
/dsp:discuss supports every phase — Explicit phase selector with question branches for Discovery, PRD, Journey, Roadmap, UX, Color System, UI, Review, and Storytelling.
114-test regression suite — Up from 53. Every state-machine invariant, schema contract, and cross-command consistency rule now has locked-in coverage.

Silent overwrites — No more per-skill y/N prompts on install. npx design-shit-properly --global just works.
Symlink install mode — New --link flag creates symlinks instead of copying files. Pair with npm install -g for instant updates via npm update -g — no re-running the installer.

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 | | -- | Journey Map (optional) | /dsp:journey | JOURNEY-MAP.md | | -- | Roadmap (optional) | /dsp:roadmap | ROADMAP.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 | | /dsp:journey | Run journey map as optional phase (cross-phase) | | /dsp:roadmap | Run roadmap as optional phase (cross-phase) | | /dsp:storytell | Generate audience-tuned presentation outline (cross-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:journey | Customer journey maps, service blueprints, omnichannel experience maps (NNGroup) | | /dsp:roadmap | Theme-based UX roadmap with Now/Next/Future horizons (NNGroup) | | /dsp:ux | UX principles - user flows, states, accessibility, cognitive foundations | | /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 | | /dsp:storytell | Audience-tuned presentation outlines for design work (cross-phase) |

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
    ├── JOURNEY-MAP.md       # Optional: customer journey map
    ├── ROADMAP.md           # Optional: UX roadmap
    ├── UX-DECISIONS.md      # Phase 2 output
    ├── COLOR-SYSTEM.md      # Optional: color tokens & palettes
    ├── UI-SPEC.md           # Phase 3 output
    ├── REVIEW.md            # Phase 4 output
    └── PRESENTATION-*.md    # Optional: storytell output(s)

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" },
    "journey": { "enabled": false, "map_type": "journey" },
    "roadmap": { "enabled": false, "horizon": "now-next-future" },
    "color_system": { "enabled": true, "accessibility_level": "AA", "include_dark_mode": true },
    "research": { "enabled": false },
    "storytell": { "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-prd, dsp-journey, dsp-roadmap, dsp-ux, dsp-color, dsp-ui, dsp-eng_review, dsp-research, dsp-storytell
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.