@brunosps00/dev-workflow 0.10.0 → 0.13.0

package/scaffold/skills/dw-ui-discipline/references/anti-slop.md

@@ -0,0 +1,162 @@
+# Anti-slop catalog — 14 patterns + 17 anti-defaults
+
+Every pattern below is a category of slop that LLMs produce when ungrounded. Detection happens in `/dw-code-review` (UI diffs) and design proposals from `/dw-redesign-ui`.
+
+## The 14 patterns
+
+### 1. Visual sameness
+
+**What it looks like:** Every section of the page uses the same card style, same padding, same text size, same emphasis weight. The eye finds no anchor.
+
+**Why it happens:** LLM defaults to "consistent = good," missing that hierarchy needs deliberate variation.
+
+**Fix:** Establish one primary section per scroll-height. Use size, weight, color saturation, or whitespace differential to anchor the eye. Everything else recedes.
+
+**Example violation:** Dashboard with 6 identical-looking metric cards. **Fix:** One hero metric (largest, brightest, top), 3 supporting metrics, 2 minor metrics in a different visual treatment.
+
+### 2. Weak hierarchy
+
+**What it looks like:** Headings barely larger than body. Important CTAs same color as secondary. The user can't tell what to look at first.
+
+**Why it happens:** Defaults to "elegant restraint" without ensuring guidance still works.
+
+**Fix:** Verify hierarchy by squinting at the design (literally) — what jumps out? If nothing jumps out, hierarchy is failing. Increase contrast in size, weight, or color for the primary element by at least 30%.
+
+### 3. Fake interactivity
+
+**What it looks like:** Hover states that change opacity but the click does nothing meaningful. Buttons that look interactive but don't have a job. Cards with subtle hover but no on-click handler.
+
+**Why it happens:** LLM applies hover styles to anything that looks card-shaped.
+
+**Fix:** Hover state ONLY on elements that have an on-click. If it can't be clicked, don't suggest it can. Use cursor: default explicitly on non-interactive shapes.
+
+### 4. Emoji spam
+
+**What it looks like:** 🎯 Goals · 🚀 Launch · ✨ Features · 📊 Analytics · 🔥 Trending — emojis as decoration in headers, CTAs, and section labels where they add no information.
+
+**Why it happens:** LLM training data has tons of "emoji in headers = engaging" patterns.
+
+**Fix:** Use icons (lucide, heroicons, tabler) for semantic meaning; reserve emojis for genuinely emotive contexts (celebrations, errors that need empathy). If you can remove the emoji and the meaning survives, remove it.
+
+### 5. Gradient crutch
+
+**What it looks like:** Hero with diagonal purple-to-pink gradient. Buttons with subtle gradient. Card backgrounds with mesh gradients. Every empty space gets a gradient.
+
+**Why it happens:** Stable Diffusion / midjourney aesthetics leaked into UI; gradients hide weak composition.
+
+**Fix:** A gradient must earn its place — usually for hero zones with poetic copy, never for utility surfaces. Solid colors + good hierarchy beat gradients 9 times out of 10.
+
+### 6. Glass everything
+
+**What it looks like:** Frosted-glass effect on modals, cards, dropdowns, side panels — anywhere a surface can be layered.
+
+**Why it happens:** Apple's macOS aesthetic. Looks "premium" without effort.
+
+**Fix:** Glass only when there's meaningful content visible behind the surface (a hero image, a busy dashboard). Glass on top of plain backgrounds adds blur for no reason.
+
+### 7. Centered all the things
+
+**What it looks like:** Body paragraphs center-aligned. Headlines centered. Forms with labels centered above inputs. Every text block reads center.
+
+**Why it happens:** Marketing-page training data biases toward center-aligned.
+
+**Fix:** Center-align for hero headlines and small CTA labels only. Body text and forms read better left-aligned (in LTR scripts). Tabular data reads in columns, not centered.
+
+### 8. AI gray washing
+
+**What it looks like:** Neutral gray palette everywhere. `slate-50`, `gray-100`, `zinc-200` for backgrounds, borders, text, accents. Nothing has color personality.
+
+**Why it happens:** "Neutral = safe" default, plus shadcn/ui's neutral start.
+
+**Fix:** Establish ONE accent color from the curated defaults or brand. Use it intentionally — primary CTAs, active states, the one place the user looks first. Gray is the canvas, not the painting.
+
+### 9. Generic CTAs
+
+**What it looks like:** "Get Started" · "Learn More" · "Click Here" · "Submit" · "OK" buttons.
+
+**Why it happens:** Default LLM verb library.
+
+**Fix:** Use the verb the user is actually doing. "Approve refund" not "Submit". "Start free trial" not "Get Started". "Schedule a call" not "Contact us". Generic verbs are tells.
+
+### 10. Stock illustration
+
+**What it looks like:** Figure-with-laptop hero art. Diverse-team-around-table illustration. Abstract floating shapes.
+
+**Why it happens:** "Illustration = friendly" default. Cheap to produce, generic to consume.
+
+**Fix:** Either use product screenshots (real screens, real data — sanitized) or skip illustration entirely. A clean hero with strong typography beats a generic illustration every time.
+
+### 11. Drop shadow soup
+
+**What it looks like:** Cards with shadow. Buttons with shadow. Inputs with shadow. Tooltips with shadow on shadows. Borders AND shadows AND gradients on one element.
+
+**Why it happens:** Material Design leftover; depth as decoration.
+
+**Fix:** Pick ONE depth mechanism per layer. If cards have shadow, buttons inside should not. If you're using elevation systematically (Material 3), enforce the elevation hierarchy.
+
+### 12. Loading spinner default
+
+**What it looks like:** Spinner overlay for every async operation, regardless of duration or context.
+
+**Why it happens:** Default fallback in every UI library.
+
+**Fix:**
+- <300ms: don't show anything. Spinner appearing then disappearing instantly is flicker.
+- 300ms-2s: skeleton loader (shape of incoming content).
+- 2s-10s: spinner + status text ("Loading orders...").
+- 10s+: progress bar or step indicator + cancel button.
+
+### 13. Empty state void
+
+**What it looks like:** "No items found." Centered. Nothing else. User has no idea what to do.
+
+**Why it happens:** Empty state treated as edge case, not a real screen.
+
+**Fix:** Every empty state must answer: WHY is it empty (no data yet vs filter excluded everything vs error). WHAT should the user do next (CTA: "Create your first invoice"). Show example/illustration if it helps onboard.
+
+### 14. Notification-soup tray
+
+**What it looks like:** Every UI event becomes a toast. Save successful → toast. Validation error → toast. Network slow → toast. Now there are 5 stacked toasts and the user can't read any.
+
+**Why it happens:** Toast is the default feedback mechanism in component libraries.
+
+**Fix:** Reserve toasts for actions that need confirmation AWAY from the originating surface (background save completed, deletion can be undone). Inline feedback for form validation. Modal/banner for blocking errors. NEVER stack >2 toasts at once.
+
+## The 17 anti-defaults
+
+Specific values that signal "no thought was put in." Avoid unless you can articulate WHY you picked exactly this:
+
+| Anti-default | Why it's a tell |
+|--------------|-----------------|
+| `#3B82F6` (Tailwind blue-500) | The internet's default blue |
+| `rounded-lg` everywhere | Universal default; no surface character |
+| `shadow-md` on every card | Universal default; no depth hierarchy |
+| `bg-gradient-to-br from-purple-500 to-pink-500` | The "AI startup landing page" gradient |
+| Inter font as the only choice | Default font of 60% of new SaaS |
+| `font-bold` for everything emphasized | Bold is a tool, not the only tool |
+| Lucide icons exclusively | One icon family is fine; signature is none |
+| Stock "happy team" hero illustration | Generic placeholder energy |
+| "Get Started" / "Learn More" CTA copy | Verb-less; says nothing |
+| 4px / 8px / 12px / 16px spacing exclusively | The default 4-step scale; no rhythm |
+| `border-gray-200` for every divider | Visual whisper; no intentionality |
+| Sans-serif headlines + sans-serif body | No typographic contrast |
+| Center-aligned everything | See pattern #7 |
+| Animated CSS confetti on success | Cheesy; never matches the brand |
+| `bg-white dark:bg-gray-900` only | No real dark-mode design pass |
+| Single-column form on a wide screen | Vertical scroll where horizontal fits |
+| Modal-for-everything | Most modals should be inline editing |
+
+## How to use this catalog
+
+In `/dw-redesign-ui` step 4 (propose) — before presenting design directions, self-check against this list. Flag any pattern you're consciously using AND say why (sometimes it's the right call; "gradient crutch" can be intentional for a marketing hero).
+
+In `/dw-code-review` UI section — grep the diff for the anti-defaults table values and the patterns. Each hit becomes a finding with `dw-review-rigor` severity:
+- Pattern violations on a NEW surface → `medium` severity.
+- Pattern violations spreading EXISTING surface's slop further → `low` severity (consistency wins).
+- Pattern violations on a redesign that was supposed to fix slop → `high` severity (regression).
+
+## When the rules bend
+
+- **Marketing pages** can use gradients and emojis with more freedom — different surface job.
+- **Brand-mandated** anti-defaults override this list (if the brand IS `#3B82F6`, use it).
+- **Component libraries** like shadcn ship with neutral defaults — the discipline is to ADD character on top, not remove their neutrality.

package/scaffold/skills/dw-ui-discipline/references/curated-defaults.md

@@ -0,0 +1,195 @@
+# Curated defaults — 10 palettes + 10 font pairings + spacing scale
+
+Use this reference when the project has **no design authority** (no `.dw/rules/` design section, no `DESIGN.md`, no Tailwind theme tokens, no component library config).
+
+The values below cover ~90% of cases that need a starting point. Not opinionated branding — neutral, accessible, professional defaults.
+
+## How to use
+
+1. Pick ONE palette + ONE font pairing + the spacing scale.
+2. Commit the choice to the project (`.dw/rules/<frontend>.md` design section OR a new `DESIGN.md`).
+3. From there, the project HAS a design authority; downstream `dw-ui-discipline` invocations defer to that authority.
+
+This is bootstrap, not destination. The goal is to escape "no authority" mode within the first feature.
+
+## The 10 palettes
+
+Each palette below: neutral scale (gray, slate, etc.) + 1 accent + semantic colors. All WCAG 2.2 AA compliant for body text.
+
+### 1. Cool Stone
+- Neutrals: Tailwind `slate` (50-950)
+- Accent: `#3B82F6` (blue-500) — wait, no, see Anti-Slop. Use `#0066CC` instead.
+- Semantic: success `#16A34A`, warning `#D97706`, danger `#DC2626`
+- **Tone:** Calm, corporate, trustworthy. Default for SaaS dashboards.
+
+### 2. Warm Sand
+- Neutrals: Tailwind `stone` (50-950)
+- Accent: `#CA8A04` (warm amber)
+- Semantic: success `#16A34A`, warning `#EA580C`, danger `#DC2626`
+- **Tone:** Approachable, hospitality-adjacent, organic.
+
+### 3. Forest Pine
+- Neutrals: Tailwind `gray` (50-950)
+- Accent: `#15803D` (deep green)
+- Semantic: success `#16A34A`, warning `#D97706`, danger `#B91C1C`
+- **Tone:** Steady, financial, sustainable.
+
+### 4. Plum Velvet
+- Neutrals: Tailwind `zinc` (50-950)
+- Accent: `#7C3AED` (violet-600)
+- Semantic: success `#22C55E`, warning `#EAB308`, danger `#E11D48`
+- **Tone:** Creative, premium, design-tool.
+
+### 5. Coral Reef
+- Neutrals: Tailwind `neutral` (50-950)
+- Accent: `#E11D48` (rose-600)
+- Semantic: success `#16A34A`, warning `#F59E0B`, danger `#B91C1C`
+- **Tone:** Energetic, consumer, retail.
+
+### 6. Steel Blue
+- Neutrals: Tailwind `slate` (50-950)
+- Accent: `#0F766E` (teal-700)
+- Semantic: success `#16A34A`, warning `#D97706`, danger `#DC2626`
+- **Tone:** Technical, infrastructure, devops.
+
+### 7. Burnt Sienna
+- Neutrals: Tailwind `stone` (50-950)
+- Accent: `#C2410C` (orange-700)
+- Semantic: success `#15803D`, warning `#A16207`, danger `#B91C1C`
+- **Tone:** Bold, news, sports.
+
+### 8. Ink and Paper
+- Neutrals: Pure `#000` and `#FFF` with `#E5E5E5` divider
+- Accent: `#000` (no accent — minimal)
+- Semantic: success `#16A34A`, warning `#D97706`, danger `#DC2626`
+- **Tone:** Editorial, brutalist, magazine. Pair with serif body.
+
+### 9. Midnight Indigo
+- Neutrals: Tailwind `slate` dark-mode-first (900-50)
+- Accent: `#6366F1` (indigo-500)
+- Semantic: success `#22C55E`, warning `#FACC15`, danger `#EF4444`
+- **Tone:** Tech-forward, dark-mode-default, on-call tooling.
+
+### 10. Sea Salt
+- Neutrals: Tailwind `gray` cool (50-950)
+- Accent: `#0891B2` (cyan-600)
+- Semantic: success `#10B981`, warning `#F59E0B`, danger `#F43F5E`
+- **Tone:** Fresh, healthcare, education.
+
+## The 10 font pairings
+
+Each pairing: heading font / body font. All available on Google Fonts. Variable fonts where possible.
+
+| # | Headings | Body | Tone |
+|---|----------|------|------|
+| 1 | Inter | Inter | Modern SaaS default. Workhorse pairing. |
+| 2 | Geist Sans | Geist Sans | Vercel-aesthetic; clean, geometric. |
+| 3 | Söhne (or Manrope) | Söhne (or Manrope) | Editorial-modern; replaces Inter when Inter feels overused. |
+| 4 | DM Serif Display | Inter | Editorial-meets-product. Strong headlines, neutral body. |
+| 5 | Fraunces | Inter | Variable serif headlines, sans body. Premium feel. |
+| 6 | Source Serif 4 | Source Sans 3 | Adobe pairing; balanced editorial. |
+| 7 | Space Grotesk | Inter | Slightly quirky headlines, neutral body. Tech with personality. |
+| 8 | IBM Plex Serif | IBM Plex Sans | Industrial, opinionated. Good for enterprise tooling. |
+| 9 | Playfair Display | Manrope | High contrast pairing; hospitality, lifestyle. |
+| 10 | JetBrains Mono | Inter | Code-first products; mono for headlines and accents. |
+
+**Anti-default reminder:** Inter / Inter is fine. Inter / Inter as the ONLY pairing you ever pick is a tell.
+
+## Spacing scale
+
+Use a 4px-base scale with intentional jumps:
+
+```
+0:   0px
+1:   4px   (tight controls, icon padding)
+2:   8px   (compact spacing)
+3:   12px  (default gap in form fields)
+4:   16px  (default gap between blocks)
+6:   24px  (section padding)
+8:   32px  (large section spacing)
+12:  48px  (page header / hero padding)
+16:  64px  (between major sections)
+24:  96px  (hero / landing block separators)
+32:  128px (rare; signature spacing)
+```
+
+**Skip these by default:** 5, 7, 9, 10, 11, 13, 14, 15. Picking exactly 4-6-8-12-16 reads more intentional than 1-2-3-4-5-6-...
+
+## Border radius scale
+
+Pick a "personality" once and use it consistently:
+
+| Radius | Tone |
+|--------|------|
+| 0 (square) | Brutalist, editorial |
+| 2px | Subtle modernist |
+| 4px (Tailwind `rounded`) | Standard |
+| 6px | Slightly friendly |
+| 8px (Tailwind `rounded-lg`) | Default SaaS; **anti-default if used universally** |
+| 12px | Softer, consumer |
+| 16px+ | Rounded everything; friendly/youth-oriented |
+| Full / 9999px | Pills, buttons, avatars only |
+
+Don't mix more than 2 radii in one surface (e.g., 4px for inputs, 8px for cards). Three+ radii = visual noise.
+
+## Type scale
+
+For body=16px baseline:
+
+```
+xs:    12px  (captions, helper text — minimum 11px)
+sm:    14px  (secondary, labels)
+base:  16px  (body)
+lg:    18px  (lead paragraphs)
+xl:    20px  (small headings)
+2xl:   24px  (subheadings)
+3xl:   30px  (section headings)
+4xl:   36px  (page titles)
+5xl:   48px  (hero, marketing)
+6xl+:  60-96px (display, marketing only)
+```
+
+Line-height pairs:
+- Body text: 1.5 to 1.6
+- Headings: 1.1 to 1.25
+- Buttons: 1 (tight)
+
+## How to commit a choice
+
+After picking a palette + pairing + spacing, write `.dw/rules/<frontend>.md` (or `DESIGN.md`) with:
+
+```markdown
+## Design System (bootstrap)
+
+**Source:** Curated default — `dw-ui-discipline/references/curated-defaults.md`, picked Cool Stone + Inter/Inter + 4px-base scale on 2026-05-12.
+
+### Colors
+- Neutrals: Tailwind slate (50-950)
+- Accent: #0066CC (links, primary buttons, focus rings)
+- Success: #16A34A · Warning: #D97706 · Danger: #DC2626
+
+### Typography
+- Headings: Inter, weight 600-700
+- Body: Inter, weight 400-500
+- Mono: JetBrains Mono (code blocks only)
+
+### Spacing
+4px base scale: 4 / 8 / 12 / 16 / 24 / 32 / 48 / 64 / 96.
+
+### Border radius
+4px on inputs, 8px on cards, full on pills/avatars.
+
+### Updates
+This file is the canonical design source. To change a value, propose a PR
+that updates this file FIRST, then propagates through code.
+```
+
+Once written, `dw-ui-discipline` reads this file instead of `curated-defaults.md`. The bootstrap step is done.
+
+## What this catalog is NOT
+
+- Not 161 palettes. Not 57 fonts. By design.
+- Not a substitute for brand work — for a serious product, hire a designer.
+- Not opinionated about industry-specific aesthetics (med-tech, gaming, kids' content). Those need real design pass.
+
+The point is: have ONE intentional starting point so the agent isn't reaching for `#3B82F6` and `rounded-lg`. Project-specific design follows.

package/scaffold/skills/dw-ui-discipline/references/hard-gate.md

@@ -0,0 +1,142 @@
+# The hard-gate protocol — full version
+
+Four checkpoints before any UI work touches code. Each has a concrete output. Don't proceed without finishing the current one.
+
+## Why a gate at all
+
+Training-data defaults are the enemy. An LLM proposing UI without grounding will:
+- Reach for `#3B82F6` blue and `rounded-lg` because they appeared 10M times in training data.
+- Default to glass morphism, gradient backgrounds, and center-aligned everything because those screenshots dominate the web.
+- Skip empty/error states because happy-path screenshots are the most common training signal.
+
+The gate forces grounding in this project's reality before training-data autopilot fires.
+
+## Checkpoint 1: Brand authorities OR curated defaults
+
+**Goal:** know where visual decisions come from. Documented authority, or curated default — never invented.
+
+**How:**
+
+1. Search the project for design source-of-truth:
+   - `.dw/rules/*.md` — look for "Design", "Patterns to Follow", "Naming Conventions" sections.
+   - `DESIGN.md`, `BRAND.md`, `BRANDING.md`, `STYLE_GUIDE.md` at root.
+   - Tailwind `tailwind.config.{ts,js}` — theme tokens.
+   - CSS variables in `globals.css`, `theme.css`, `tokens.css`.
+   - Component library config (shadcn `components.json`, MUI theme, Chakra theme).
+   - Storybook stories — implicit canonical components.
+
+2. If **at least one** authority exists: it wins. Decisions defer to it. If a needed token doesn't exist (e.g., a danger-secondary color), propose adding it to the authority FIRST, not inline.
+
+3. If **none exists**: pick a curated default. Read `curated-defaults.md` in this references folder. Pick one of the 10 palettes + one of the 10 font pairings. Mark the choice in the techspec/PR description:
+
+   > **Design source:** No project authority found. Using curated default "Cool Stone" (neutral grays + electric blue accent) + "Inter / Source Serif" pairing. Recommend establishing `DESIGN.md` to formalize.
+
+**Anti-patterns at this checkpoint:**
+
+- Inventing color hex values inline (`bg-[#FF6B35]`).
+- "I'll use Tailwind defaults" — Tailwind defaults are training-data defaults, not project authority.
+- Copying values from "a site I like" without understanding what it solved.
+
+**Output:** A one-sentence note in the techspec/PR describing the authority consulted.
+
+## Checkpoint 2: Surface job sentence
+
+**Goal:** the user's intent at this surface, stated in one specific sentence.
+
+**Format:** "This surface helps the user **<verb-phrase>** so that **<outcome>**."
+
+**Examples — good:**
+
+- "This surface helps the user filter overdue invoices so they can chase late payers in under 30 seconds."
+- "This surface helps the on-call engineer diagnose which deploy caused the spike so they can roll back without paging the team."
+- "This surface helps the manager approve or reject expense reports without leaving Slack."
+
+**Examples — bad:**
+
+- "This surface displays invoice data." (no user, no outcome)
+- "Settings page for managing the account." (vague, no specificity)
+- "Dashboard." (one word)
+
+**How to push back when the brief is vague:**
+
+If the requester can't articulate the job, the requirements aren't ready. Reply with: "Before I design this surface, I need the job sentence: <example>. Can you fill in the verb-phrase and outcome?"
+
+Designing without this sentence produces generic surfaces — the "just another dashboard" outcome.
+
+**Output:** The one-sentence job, committed to the techspec/PR description.
+
+## Checkpoint 3: Complete state matrix
+
+**Goal:** enumerate every state the surface can be in, BEFORE designing for the happy path.
+
+**Minimum states (always enumerate):**
+
+| State | Trigger | What user sees |
+|-------|---------|---------------|
+| `default` | First load, no interaction | Initial render |
+| `hover` | Cursor over interactive element | Visual feedback |
+| `active` | Click in progress | Pressed/depressed visual |
+| `focus-visible` | Keyboard tab arrived | Distinct outline, not the same as hover |
+| `disabled` | Interaction unavailable | Reduced opacity + cursor change, NO action |
+| `loading` | Async operation in flight | Skeleton, spinner, or progress — context-appropriate |
+| `empty` | No data to show | Guidance on what to do next |
+| `error` | Operation failed | What broke + how to recover |
+| `success` | Operation succeeded | Confirmation that doesn't require ack |
+
+**Add domain-specific states as needed:**
+
+- Read/unread (notifications, messages)
+- Online/offline (chat, collaborative tools)
+- Stale/fresh (dashboards with cached data)
+- Pending/approved/rejected (workflow states)
+- New/saved/dirty (forms)
+
+**Tripwire:** if the design has only `default`, you missed 8 states. If it has `default` + `loading`, you missed 6. The full matrix is non-negotiable.
+
+**Output:** A state matrix table in the techspec or design doc.
+
+## Checkpoint 4: Scene sentence
+
+**Goal:** the physical context the surface lives in.
+
+**Format:** "**<Who>** uses this **<where>** in **<what light>** while **<what mood>**."
+
+**Examples — good:**
+
+- "An on-call engineer uses this on a dark-room laptop at 3am while troubleshooting a fire."
+- "A field nurse uses this on a phone in bright outdoor light while juggling clipboards."
+- "A receptionist uses this on a 24" monitor at a busy front desk while talking to a visitor."
+
+**Why this matters:**
+
+Decisions cascade from the scene:
+- 3am dark room → dark mode, high contrast, no flashing animations.
+- Bright outdoor → minimum 7:1 contrast, larger touch targets, no thin fonts.
+- Busy front desk → glanceable info, no nested menus, big numbers.
+
+Without the scene, defaults take over: light mode, default contrasts, animations, regular touch targets. Production users hate it; you can't articulate why.
+
+**Output:** Scene sentence in the techspec.
+
+## What "passing the gate" looks like
+
+A PR description / techspec UI section that includes:
+
+```markdown
+## UI Discipline Gate
+
+**Authority:** `.dw/rules/frontend.md` design tokens (Tailwind theme + custom CSS vars).
+**Surface job:** Helps on-call engineers diagnose which deploy caused the latency spike so they can roll back without paging the team.
+**State matrix:**
+  - default, hover, active, focus-visible, disabled, loading, empty (no spikes detected), error (metrics API down), success (rollback completed)
+  - Plus: stale (>5min old data) — show timestamp + refresh CTA.
+**Scene:** On-call engineer uses this on a dark-room laptop at 3am while troubleshooting a production fire.
+```
+
+This is the minimum disclosure. Anything less and the gate didn't pass.
+
+## When this gate has been run
+
+The downstream skills (`anti-slop.md`, `state-matrix.md`, `accessibility-floor.md`) assume gate passed. They won't re-verify; if you skipped, you get bad output.
+
+`/dw-code-review` failing verdict on a UI PR where this disclosure is missing.

package/scaffold/skills/dw-ui-discipline/references/state-matrix.md

@@ -0,0 +1,101 @@
+# State matrix — enumerate before designing the happy path
+
+The single biggest UI bug factory: designing for the default state, shipping it, and discovering empty/error/loading at production time. This reference enforces enumeration BEFORE design.
+
+## The mandatory minimum (every interactive surface)
+
+| State | When it fires | Visual rule | Common mistake |
+|-------|---------------|-------------|----------------|
+| `default` | First load, no interaction | Calm baseline; nothing competes with content | Designing only this state |
+| `hover` | Cursor over interactive element | Subtle change signals click affordance | Hover on non-clickable shapes (fake interactivity) |
+| `active` | Click in progress (mouse down) | Distinct from hover; pressed/depressed | Skipping; click feels unresponsive |
+| `focus-visible` | Keyboard tab arrives | Distinct outline, NOT same as hover | Using `outline: none` and not replacing |
+| `disabled` | Interaction unavailable | Reduced opacity + cursor change; no on-click | Looks like enabled, confuses user |
+| `loading` | Async operation in flight | Skeleton/spinner sized to incoming content | Generic spinner regardless of context |
+| `empty` | No data to show | Why-it's-empty + what-to-do-next CTA | "No items found." centered, full stop |
+| `error` | Operation failed | What broke + how to recover + retry CTA | Generic "Something went wrong." |
+| `success` | Operation succeeded | Brief confirmation; auto-dismiss when safe | Toast spam |
+
+## Common domain states
+
+Add these when the surface has matching semantics:
+
+| State | Surfaces | Visual rule |
+|-------|----------|-------------|
+| `read` / `unread` | Notifications, messages, inbox | Weight differential; new is bolder |
+| `online` / `offline` / `connecting` | Chat, presence indicators | Color dot + label; offline is visually quieter |
+| `stale` / `fresh` | Dashboards with cached data | Timestamp + refresh CTA when stale > N min |
+| `pending` / `approved` / `rejected` | Workflow records | Color-coded badges; never color alone (a11y) |
+| `draft` / `saved` / `dirty` | Forms, editors | Indicator near save button; "unsaved changes" |
+| `new` / `existing` | Composers, dialogs | Title and CTA wording differ ("Create" vs "Update") |
+| `partial` / `complete` | Multi-step flows | Progress indicator; remaining steps visible |
+| `selected` / `unselected` | Lists with multi-select | Border + bg change + checkbox mark |
+| `expired` / `active` | Tokens, subscriptions | Visual deemphasis when expired + revocation CTA |
+
+## Loading state granularity (don't just pick "spinner")
+
+| Operation duration | Right loading treatment |
+|--------------------|-------------------------|
+| <300ms | Show nothing. Spinner appearing then vanishing = flicker. |
+| 300ms – 2s | Skeleton loader matching content shape |
+| 2s – 10s | Spinner + status text ("Loading orders...") |
+| 10s – 60s | Progress bar with percentage + cancel button |
+| >60s | Step indicator OR async with notify-when-done |
+
+A spinner that runs forever with no progress info is one of the worst UX patterns. If the operation can take >10s, show progress; if it can take >60s, make it background-able.
+
+## Error state granularity
+
+Errors are not all equal:
+
+| Error type | Treatment |
+|------------|-----------|
+| Validation (client-side, single field) | Inline below field; red text + icon |
+| Validation (form-level) | Summary at top + per-field inline |
+| Authorization (401/403) | Modal or banner; sign-in CTA |
+| Not found (404) | Inline empty-state variant with "go back" |
+| Server error (5xx) | Banner with retry button; preserve user input |
+| Network timeout | Inline message + auto-retry button |
+| Partial data | Show what loaded + indicator for what failed |
+
+Generic "Something went wrong" is the lazy default. Categorize the failure; show actionable guidance.
+
+## Empty state granularity
+
+Empty is not always "no data ever existed":
+
+| Empty reason | Treatment |
+|--------------|-----------|
+| Genuinely first-time empty (new user) | Welcoming illustration + onboarding CTA |
+| Filter excluded everything | Show filter chips + "Clear filters" CTA |
+| Search returned nothing | Echo the query + spelling suggestions / refinement tips |
+| All items completed / archived | Acknowledge + "View archived" CTA |
+| Permissions block visibility | Explain (don't pretend it's empty) + request-access CTA |
+| Loading hasn't completed | This is `loading`, not `empty` — different state |
+
+## Verification checklist
+
+Before declaring the design "done":
+
+- [ ] All 9 minimum states are designed (not just default).
+- [ ] All applicable domain states are designed.
+- [ ] Loading granularity matches operation duration.
+- [ ] Error states are categorized (not all "something went wrong").
+- [ ] Empty states explain WHY and offer WHAT to do.
+- [ ] `disabled` state has visual + cursor differentiation, NO on-click handler.
+- [ ] `focus-visible` is distinct from `hover` (keyboard users need their own affordance).
+- [ ] Color is never the SOLE differentiator (a11y); pair with shape/text/position.
+
+## Integration with `/dw-code-review`
+
+Review fails verdict (REJECTED) on a UI PR when:
+- A new component handles async data but renders only the default state.
+- An interactive element has `:hover` but no `:focus-visible`.
+- An error path falls through to a generic message with no recovery action.
+- Loading state is a spinner where the operation takes >2s (should be progress).
+
+These are not stylistic preferences — they're production bugs waiting to surface.
+
+## Anti-pattern: "We'll add states later"
+
+Empirically: states added later are added under duress (after a user reports). The cost of designing them now is small (15-30 minutes for a component); the cost of finding them in production is large (user trust + incident response). The matrix is non-negotiable.

package/scaffold/templates-overrides-readme.md

@@ -0,0 +1,75 @@
+# Template Overrides
+
+Files in this directory override the corresponding templates in `.dw/templates/`. Use this when your team needs a customized PRD/TechSpec/Task/etc. shape **without** losing the ability to receive `dev-workflow` updates.
+
+## How it works
+
+- During `dev-workflow init` or `dev-workflow update`, the CLI copies templates from the package into `.dw/templates/`.
+- Before writing each file, the CLI checks `.dw/templates/overrides/` for a same-named file.
+- If found, **the override is preserved and the core template is skipped**. Your customization wins.
+- If not found, the core template is installed/updated normally.
+
+## How to override a template
+
+```bash
+# 1. Copy the template you want to customize from .dw/templates/ to .dw/templates/overrides/
+cp .dw/templates/prd-template.md .dw/templates/overrides/prd-template.md
+
+# 2. Edit the override to fit your team's process
+$EDITOR .dw/templates/overrides/prd-template.md
+
+# 3. Commit it. Future updates won't touch this file.
+git add .dw/templates/overrides/prd-template.md
+git commit -m "chore(templates): customize PRD template for our team"
+```
+
+The override takes effect immediately. Commands that consume the template (`/dw-create-prd`, etc.) will read from `.dw/templates/<name>.md`, which is preserved as your edited copy.
+
+## How to revert an override
+
+```bash
+# 1. Delete the override
+rm .dw/templates/overrides/prd-template.md
+
+# 2. Re-run dev-workflow update to restore the core template
+npx @brunosps00/dev-workflow update
+```
+
+## When an override is appropriate
+
+- Adding required sections specific to your industry (compliance, finance, healthcare).
+- Removing sections that don't apply.
+- Renaming sections to match your team's vocabulary.
+- Embedding links to internal tools, dashboards, runbooks.
+
+## When an override is **not** appropriate
+
+- Removing critical-path sections like FR numbering or test plans — downstream commands rely on these.
+- Adding fields that conflict with the YAML frontmatter schema.
+- Anything that breaks `/dw-create-techspec` or `/dw-create-tasks` cross-references.
+
+If in doubt, run the workflow end-to-end after editing — the consistency check at the end of `/dw-create-tasks` will surface most structural breakages.
+
+## Versioning your overrides
+
+When `dev-workflow` releases a new minor version, the core templates may change shape (new sections, renamed fields). Your override will continue to work, but it might lack the new sections.
+
+Recommended cadence: when you upgrade `dev-workflow`, `diff` your override against the new core template:
+
+```bash
+diff .dw/templates/overrides/prd-template.md .dw/templates/prd-template.md
+```
+
+Merge in anything you want from upstream. The override stays canonical; the core template is just a reference.
+
+## Subdirectories
+
+Overrides can mirror the directory structure of `.dw/templates/`. For example, to override a file inside `functional-doc/`:
+
+```
+.dw/templates/overrides/
+└── functional-doc/
+    └── e2e-runbook.md
+```
+
+The resolver descends recursively — each leaf file is checked independently against its corresponding path under `overrides/`.