Design

/dotclaude:design — design discipline kit

You are setting up design-discipline for the user's project. The output is a .claude/ subset tuned to design / IA / UX / a11y / visual quality — agents that audit, skills that pre-empt, rules that anchor.

This is the showpiece flow. Most Claude Code plugins focus on engineering (CI, testing, refactoring). Design / IA / UX / a11y is a near-empty niche — your user's expertise in this area is what makes dotclaude unique. Treat this flow as the differentiator.

Phase 1 — Read the project's UI shape

Before any question. The goal is to enter the interview already knowing what the project ships, how it's structured, what discipline already exists. The richer Phase 1, the fewer questions the interview needs — and the more grounded the authored agents will be.

Run these 10 reads. Each gives a data point the interview leverages.

1.1 — Stack signal

# Stack identity
cat README.md 2>/dev/null | head -40
cat package.json 2>/dev/null | head -60
cat pyproject.toml Cargo.toml go.mod composer.json 2>/dev/null | head -20

Read for: framework, language, target platform. Mobile? Web? Desktop? Both?

1.2 — Top-level structure (2 levels deep)

ls -la
ls -la src/ app/ lib/ components/ pages/ routes/ 2>/dev/null

Read for: where does UI code live? Is there a clear components/ directory? app/ (Next/Expo Router)? routes/ (SvelteKit/Remix)?

1.3 — Existing project conventions

ls -la CLAUDE.md AGENTS.md CONTRIBUTING.md STYLE_GUIDE.md BRAND.md docs/ 2>/dev/null
find . -maxdepth 3 -name "CLAUDE.md" -o -name "AGENTS.md" 2>/dev/null

Read every found doc fully. Conventions in these files override anything you'd otherwise author. The user's existing docs win every conflict.

1.4 — Design system source

find . -path ./node_modules -prune -o \( \
  -name "tokens.*" -o -name "theme.*" -o -name "design-system.*" \
  -o -name "*.tokens.json" -o -name "tailwind.config.*" \
  -o -name "globals.css" -o -name "variables.scss" \
\) -print 2>/dev/null

If found, read the file. Note: token naming convention (semantic vs palette), dark-mode support, the scale of the system (10 tokens vs 200).

1.5 — Component library inventory

ls components/ src/components/ src/ui/ lib/ui/ app/components/ 2>/dev/null

Sample 5-8 component files. Read for: naming convention (kebab vs PascalCase), prop API patterns, styling approach (CSS modules / Tailwind / styled-components / inline). The authored design-token-auditor needs to know which patterns to sweep.

1.6 — Route / screen inventory

# Next/Expo Router (file-based)
find . -path ./node_modules -prune -o \( -name "page.tsx" -o -name "page.jsx" -o -name "+page.svelte" -o -name "index.tsx" \) -print | head -20
# React Router / explicit
grep -rn "Route\|createBrowserRouter\|router\.get\|Stack\.Screen" src/ app/ 2>/dev/null | head -20

Count routes. Identify: is this single-screen, multi-screen, multi-section (tabs / dashboard sections / docs sidebar)? This determines whether flow-auditor and pages-audit agents apply.

1.7 — CI + scripts

ls .github/workflows/ scripts/ 2>/dev/null
cat package.json 2>/dev/null | grep -A 30 '"scripts"'

Read for: existing visual-verification machinery (Playwright config? Maestro flows? Storybook? Chromatic?). Existing lint config. Build/test/dev scripts. The authored visual-verification.md rule references whatever exists; don't invent new ones.

1.8 — Git history mining (PRE-INTERVIEW)

git log --oneline -30
git log --oneline --grep="fix:" -30
git log --oneline -E --grep="design|UX|style|color|spacing|a11y|layout|copy|tone|chrome|polish" -30

Identify the 2-3 most design-flavored commits by subject line. These are what you'll ask about by SHA in interview Phase D. Do this before the interview, not during — you want to enter the interview already armed with the SHAs.

1.9 — Assertions / lint config

ls .eslintrc* .prettierrc* tsconfig.json biome.json 2>/dev/null
find . -maxdepth 3 -name "jest.config.*" -o -name "vitest.config.*" -o -name "playwright.config.*" -o -name ".maestro" 2>/dev/null

Read for: existing test infrastructure (Jest / Vitest / Playwright / Maestro). Lint rules already covering tokens / hex / a11y. The authored agents should integrate with what exists, not replace it.

1.10 — Dev loop signal

From package.json scripts (already read in 1.7): identify the dev command (dev, start, serve), the test command, the build command, the e2e command if present. The authored visual-verification.md and the ux-reviewer agent's capture procedure reference these explicitly.

---

At end of Phase 1, write a one-paragraph mental-model summary to yourself:

> Primary surface: . Stack: . Existing conventions doc: . Design-system maturity: . Multi-screen or single-screen: . CI maturity: . Visual-verification path already wired: . War-story SHAs to ask about: .

This is the substrate the interview adapts to. Skip questions whose answer is already in the summary.

Phase 2 — Interview

Open interview.md (same directory). The interview is structured as 10 phases (A–J) driving 53 configuration knobs — the calibration target inherited from docs/design-stack-analysis.md. Adaptive: ~25 knobs auto-populate from Phase 1's scan; the interview drives the remaining ~28 via ~17-18 sub-questions batchable into 5-6 super-questions per turn.

The most important questions (the ones to fight for if the user resists):

• Q-B1 / Q-B2 / Q-B3 — Tier 1 (chrome) + Tier 2 (domain, with dimension) + anti-references. Without named benchmarks, every authored agent grades on vibes.
• Q-C1 → Q-C4 — voice + assistant character + brand voice reference + forbidden phrases. Gates whether persona-testing + forbidden-phrases ship.
• Q-D1 / Q-D2 — multi-screen arcs + multi-section primary surface. Gates whether flow-audit / flow-continuity-review / iterative-polish-autoloop / pages-audit apply.
• Q-I1 — git-mined commit confirmation. Transforms generic textbook anti-patterns into project-specific ones.
• Q-E3 — demo audience + quality posture. Defines what "shipped well" means.

Phase 3 — Read the principles

Read these from ../../principles/ SELECTIVELY based on what the project actually has:

Always read (universal design discipline):

• design-benchmarking.md — picks Tier 1 + Tier 2 references + per-surface chrome reference table convention
• visual-verification.md — see-what-you-built discipline
• quality-rubric.md — S/A/B/C/D anchored on the user's benchmarks + claim-of-done preconditions (5-item checklist)
• audit-routing.md — which audit fires for which question + cheapest-tier-wins discipline
• design-system-reference-skill.md — design-system entry-point skill the project ships (always read; the broad reference for tokens / primitives / motion / status / gotchas)

Read if project is in design / spec / IA phase (new features incoming):

• product-designer.md — senior-IC IA / flow / multi-screen designer agent

Read if project has multi-screen UI (most non-trivial UIs):

• ux-audit.md — single-screen audit
• a11y-audit.md — accessibility
• interaction-audit.md — semantic chrome-vs-handler
• design-token-audit.md — token discipline sweep
• journey-mapping.md — prior-surface mapping before any new screen design (DUAL LOAD — design + audit time)
• element-reuse.md — Gate A reuse verdict (DUAL LOAD — design + audit time)
• persona-testing.md — outside-eyes lens on copy (DUAL LOAD — design + audit time)

Read if project has multi-section primary surface (tabs / dashboard sections / docs sidebar):

• pages-audit.md — cross-section consistency

Read if project has multi-screen arcs (onboarding, wizard, checkout):

• flow-audit.md — whole-arc audit (deep, infrequent — produces canonical flow doc + dated gap report)
• flow-continuity-review.md — lightweight series grader (frequent, takes pre-captured manifest, grades 6 flow-level dimensions)

Read if user wants iterative polish to award-tier (capture harness + reviewer + fixture reset all present):

• iterative-polish-autoloop.md — continuous polish loop with 3-layer scrutiny (reviewer / composition scan / backend-truth probe)

Read if project has a CLAUDE.md / vision doc (drift detection wanted):

• product-direction-validator.md — vision-alignment guardian / drift detector / agent coordinator

Read if project has product voice (any user-facing copy):

• forbidden-phrases.md — voice discipline

Phase 4 — Author the kit

Based on what applied + the interview answers, author these in .claude-staging/. Each artifact must cite the user's actual code paths, name THEIR benchmarks, reference THEIR past bugs.

Calibration target: the 53-knob configuration captured by the interview (per docs/design-stack-analysis.md). Every authored artifact's frontmatter + body must thread the relevant knobs. The interview's purpose is exactly this calibration; if an authored artifact still reads like a template, the interview didn't drive enough knobs through.

Agents (in .claude-staging/agents/)

• ux-reviewer.md — single-screen visual audit
• Frontmatter: description:
• Body: screenshot procedure for THEIR device target (iOS sim? Playwright? screenshot script?), grading rubric anchored to THEIR named benchmarks (e.g. "S = looks like Linear or Stripe" if those are their picks), composition pitfalls grounded in screenshots they showed in interview
• Include the IN_PRODUCT_ASSISTANT_CHARACTER daily-driver trap check if Q-C2 said yes
• Reference quality-bar skill

• a11y-audit.md — accessibility (only if UI is user-facing-end-user, not internal-only)
• 4+1 dimensions adapted to THEIR platform (VoiceOver for iOS, screen reader for web, equivalent for desktop)
• Hit-target sizes per platform (44pt iOS, 48dp Android, 44×44px web touch)
• Contrast computed from THEIR TOKEN values, not screenshot-estimated (per principle's core methodology)
• Dynamic Type / rem-scaling per platform

• interaction-audit.md — semantic chrome integrity
• The affordance-vs-behavior table
• Pattern catalog (dead chrome / redundant affordance / optical-group disconnect)
• Project-specific examples from THEIR codebase if found in Phase 1 git log (Q-I1 confirmations)

• design-token-auditor.md — token discipline regex sweep
• Targets: THEIR design system source file (which you found in Phase 1)
• Sweep patterns: hex / rgba / hsla / Tailwind arbitrary values
• Override convention: // allow-color:
• Tier: haiku model (cheap) per design-token-audit.md principle

• flow-auditor.md (if multi-screen arcs) — whole-arc audit
• 8-class gap rubric from flow-audit.md principle
• Arc inventory: list THEIR known arcs (signup, onboarding, checkout, etc.) — derive from Q-D1 + Phase 1 routes
• Owner / Fix-by handoff column convention in findings table

• pages-audit.md (if multi-section primary surface) — cross-section consistency
• Shared-component grep first, pixel measurement last
• List THEIR primary sections (read from Q-D2 + Phase 1 routes/tabs)

• product-designer.md (if user wants design phase support — Q-J1 + general posture)
• Per product-designer.md principle — 8-step procedure
• Reference THEIR spec doc convention (Q-H1), capability map path if any (Q-J1), prototype gates if any (Q-J1)
• Self-audit checklist verbatim

• flow-ux-reviewer.md (if multi-screen arcs + capture harness)
• Per flow-continuity-review.md principle — manifest-driven series grader
• 6 flow-level dimensions
• Bridge reference apps from Q-B2

• product-compass.md (if vision docs exist — Q-J1)
• Per product-direction-validator.md principle — Vision Health verdict + drift detection + agent coordination

Skills (in .claude-staging/skills/)

• design-system/SKILL.md — design-system entry-point skill per design-system-reference-skill.md principle (11 sections — north-star / native primitives / tokens / styling API / semantic colors / surface hierarchy / motion / shadows / status / quality tiers / library gotchas + i18n)
• journey-audit/SKILL.md — prior-surface mapping skill (DUAL LOAD — fires at design AND audit time)
• element-reuse-check/SKILL.md — Gate A reuse verdict matrix (DUAL LOAD)
• persona-lens/SKILL.md — Gate B day-30 / partner / stranger lens (DUAL LOAD; adapt triad: for B2C use day-30/partner/stranger; for CLI tool maybe first-run/power-user/regression-debugger; for docs-site skimmer/focused/reference)
• quality-bar/SKILL.md — S-tier rubric + composition pitfalls + demo test + claim-of-done preconditions (5-item checklist), anchored to THEIR benchmarks
• ruthless-ux-autoloop/SKILL.md (if user wants iterative polish) — per iterative-polish-autoloop.md principle — 3-layer scrutiny + iteration cap + safety invariants

Rules (in .claude-staging/rules/)

• design-north-star.md — explicitly names THEIR Tier 1 + Tier 2 benchmarks; quotes specific anti-patterns the user mentioned in interview; per-surface chrome reference table (the row-per-surface convention from design-benchmarking.md)
• audit-routing.md — the pipeline order + when-to-dispatch table, scoped to the agents you just authored; cheapest-tier-wins discipline explicit (hook , run `"*) — without it, generated tokens drift from source.
• product-compass.md agent ships with the agent coordination table (situation → recommended-agent), not just prose.

Depth checklist (MANDATORY per authored agent)

Every agent / skill / rule you author in Phase 4 MUST contain ALL of these 10 structural elements, or the artifact is shallow and the user will reject it. This checklist is the difference between a "v0.1 sketch" and a "battle-tested kit." Treat it as binding.

Calibration target: the 53-knob configuration from the interview (see docs/design-stack-analysis.md for the full knob map; the interview drives them). Each authored artifact's depth signature is achieved by threading the relevant subset of knobs into its body — not by adding length. A 250-LOC agent body with 12 project-specific knob references beats a 400-LOC body of generic methodology.

1. Named benchmarks — specific Tier 1 + Tier 2 apps from the interview, with WHY each is the benchmark. "Apple-like" or "modern apps" is NOT a benchmark. "Linear for keyboard speed" or "Apple iOS 26 Settings + Telegram for chrome" is.

1. 5+ inspection dimensions — each with a concrete method (grep pattern, command, manual check). Vague "look for issues" fails this check. "Sweep #[0-9a-fA-F]{3,8} across src/**/*.tsx excluding theme.ts" passes.

1. Rubric anchored per grade — S/A/B/C/D/F with each grade referencing a NAMED benchmark. "S = a Linear engineer would compliment this; A = ships at Linear quality with one polish pass; B = ships at competent SaaS quality; C = ships but visibly behind; D = embarrassing next to Linear; F = block ship." Each tier mentions the actual app.

1. Report-format sections — explicit named sections (not "describe findings" but ## Strengths / ## Critical issues / ## Verdict / ## Highest-ROI move). The agent must produce predictable output the user can scan.

1. Cross-references — at least 2 other artifacts (skills / rules / agents) this composes with. The artifact says "runs AFTER interaction-audit," "consumes the journey map from journey-audit/SKILL.md," etc. Composability is what makes a kit a kit.

1. Numbered non-negotiable rules — 5-10 rules with rationale per rule, not just a list of "do this." "1. Never grade without a captured screenshot — pixel review is the contract; reading code is not a substitute." The rationale clause is what makes the rule stic

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: vindm
• Source: vindm/dotclaude
• License: MIT
• Homepage: https://github.com/vindm/dotclaude

Install and usage instructions live in the source repository linked above.