@brunosps00/dev-workflow 0.13.0 → 1.0.0

package/scaffold/skills/dw-ui-discipline/SKILL.md

@@ -1,128 +1,152 @@
 ---
 name: dw-ui-discipline
-description: Use BEFORE any UI work — enforces a hard-gate (brand authorities or curated defaults, surface job, state matrix, scene sentence), 14 anti-slop patterns, and WCAG 2.2 AA floor so UI ships with discipline instead of training-data defaults.
+description: Use BEFORE any UI work. 4 grounding questions (design source, surface job, state matrix, scene), 14 anti-slop patterns, WCAG 2.2 AA floor. Triggers on UI design, /dw-redesign-ui, UI diffs.
+allowed-tools:
+  - Read
 ---
 
 # UI Discipline
 
-> **Inspired by** [`pedronauck/skills/ui-craft`](https://github.com/pedronauck/skills/tree/main/skills/mine/ui-craft) (MIT). Hard-gate protocol, anti-slop catalog, state matrix enforcement, and accessibility-floor patterns adapted from Pedro Nauck's work; specifics rewritten for dev-workflow's redesign and review loops.
+Training-data defaults are the enemy. An ungrounded LLM proposing UI will reach for `#3B82F6` blue, `rounded-lg` radius, center-aligned text, and gradient backgrounds — because those screenshots dominate training data. The surface ends up looking like every other SaaS dashboard, and users can't tell what to look at first.
 
-The fastest path through UI work is the disciplined one. "It's just a small change" is the most common slop excuse. This skill blocks that excuse at four checkpoints before any design decision lands.
+This skill blocks that autopilot at four grounding questions before any visual decision lands. After the questions pass, it enforces an accessibility floor and runs a visual-slop catalog as the proposed design comes together.
 
-## When this skill applies
+## When to use
 
-- Any work invoked from `/dw-redesign-ui`, `/dw-create-techspec` (UI sections), `/dw-functional-doc`, or `/dw-code-review` when the diff touches UI.
-- Adding new screens, components, or surfaces.
-- Reviewing visual changes in a PR.
-- Auditing accessibility on existing surfaces.
+- Inside `/dw-redesign-ui` — both proposal and validation steps.
+- Inside `/dw-plan techspec` when the spec has UI sections.
+- Inside `/dw-functional-doc` when documenting screen-level patterns.
+- Inside `/dw-review --code-only` when the diff touches UI files (CSS, JSX, templates).
+- Inside `/dw-brainstorm` when the conversation drifts into visual direction.
 
-If you're tempted to skip the gate "because it's just a tweak" — that's the trigger. Run the gate.
+If you're tempted to skip this "because it's just a small tweak" — that's the trigger. Run the grounding.
 
-## The hard-gate (4 mandatory items before any UI work)
+## The four grounding questions
 
-Before proposing colors, layouts, components, or any visual decision, complete all four:
+Answer all four before proposing colors, layouts, components, or any visual decision.
 
-### 1. Brand authorities OR curated defaults
+### 1. Where do design decisions come from?
 
-Locate the project's design source of truth:
-- `.dw/rules/{frontend-module}.md` design system section
-- `DESIGN.md`, `BRAND.md`, or design tokens config (Tailwind, CSS vars, theme file)
-- Component library docs (shadcn/ui, MUI, Chakra, etc.)
+Find the project's design source-of-truth in this order:
+1. `.dw/rules/<frontend-module>.md` design system section.
+2. `DESIGN.md`, `BRAND.md`, `STYLE_GUIDE.md` at project root.
+3. Design token config — Tailwind theme, CSS variables in `theme.css`/`globals.css`, MUI/Chakra theme.
+4. Component library config — `components.json` for shadcn, theme exports.
+5. Storybook stories (implicit canonical components).
 
-If **none exist**, do NOT invent. Read `references/curated-defaults.md` — pick from the 10 neutral palettes + 10 font pairings shipped there. Mark the choice as a finding in the techspec ("no design authority found; used curated default <name>; recommend establishing one").
+If **at least one** exists: it wins. Defer to it. If a needed token is missing (e.g., a danger-secondary color), propose adding it to the authority FIRST, not inline.
 
-### 2. Surface job sentence
+If **none exists**: read `references/curated-defaults.md` and pick one of the 10 neutral palettes + one of the 10 font pairings shipped there. Mark the choice in the techspec/PR description: "Design source: no project authority found; using curated default `<name>`; recommend establishing `DESIGN.md`."
 
-Write one sentence: "This surface helps the user <do what> so that <outcome>." Vague language ("show data", "manage settings") fails — be specific ("filter overdue invoices so they can chase late payers in <30s").
+**Anti-patterns at this question:**
+- Inventing color hex values inline (`bg-[#FF6B35]`).
+- "I'll use Tailwind defaults" — that's training-data defaults, not project authority.
+- Copying values from "a site I like" without understanding what it solved.
+
+### 2. What does this surface help the user do?
+
+Write one sentence: **"This surface helps the user `<verb-phrase>` so that `<outcome>`."**
+
+Good examples:
+- "...helps the user filter overdue invoices so they can chase late payers in under 30 seconds."
+- "...helps the on-call engineer diagnose which deploy caused the spike so they can roll back without paging the team."
+- "...helps the manager approve or reject expense reports without leaving Slack."
+
+Bad examples:
+- "This surface displays invoice data." (no user, no outcome)
+- "Settings page for managing the account." (vague, no specificity)
+- "Dashboard." (one word)
 
 If you can't write the sentence, the requirements are unclear. Stop and clarify before proceeding.
 
-### 3. Complete state matrix
+### 3. What states does the surface have?
+
+Enumerate all states before designing the happy path. Minimum nine, plus domain-specific ones — see `references/state-matrix.md`:
 
-Enumerate all states the surface can be in. See `references/state-matrix.md` for the full list:
-- `default`, `hover`, `active`, `focus-visible`, `disabled`, `loading`, `empty`, `error`, `success`
-- Plus any domain-specific states (read/unread, online/offline, etc.)
+`default`, `hover`, `active`, `focus-visible`, `disabled`, `loading`, `empty`, `error`, `success` plus any domain states (read/unread, online/offline, stale/fresh, pending/approved/rejected, draft/saved/dirty, partial/complete, etc.).
 
 Missing a state at design time = production bug later. The "we'll add empty state later" trap is real.
 
-### 4. Scene sentence
+### 4. Who uses this surface, where, and in what mood?
 
-One sentence describing the physical context: **who** is using this, **where** (mobile bus, office desktop, on-call laptop), **what light** (dark room, bright outdoor), **what mood** (rushed, exploring, troubleshooting).
+One sentence: **"`<Who>` uses this on `<where>` in `<what light>` while `<what mood>`."**
 
-This forcing function prevents category-level defaults from becoming the answer. A "dashboard for an on-call engineer at 3am in a dark room troubleshooting a fire" produces different decisions than "dashboard for a manager during business hours."
+Good examples:
+- "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."
 
-## Required Reading Router
+Decisions cascade from the answer:
+- 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, large numbers.
 
-| Context | Read |
-|---------|------|
-| Any UI work | `references/hard-gate.md` (full protocol with examples) |
-| Interactive widgets (buttons, forms, modals) | `references/accessibility-floor.md` (WCAG 2.2 AA non-negotiable) |
-| Reviewing a UI diff | `references/anti-slop.md` (14 anti-patterns + 17 anti-defaults) |
-| Designing state coverage | `references/state-matrix.md` (full enumeration + checklist) |
-| No design authority exists in project | `references/curated-defaults.md` (10 palettes + 10 fonts) |
+Without this sentence, defaults take over: light mode, default contrasts, animations, regular touch targets. Production users hate it; you can't articulate why.
 
-## Anti-slop summary (full list in references/anti-slop.md)
+## Required reading by context
 
-The 14 patterns this skill catches:
+| Doing what | Read |
+|------------|------|
+| Any UI work (the full version of the grounding) | `references/hard-gate.md` |
+| Reviewing or proposing a design | `references/visual-slop.md` (14 patterns + specific anti-default values) |
+| Designing state coverage | `references/state-matrix.md` |
+| Interactive widget (button, form, modal, anything clickable) | `references/accessibility-floor.md` |
+| No design authority exists in the project | `references/curated-defaults.md` (palettes / fonts / scales) |
 
-1. **Visual sameness** — every section looks like every other section.
-2. **Weak hierarchy** — nothing draws the eye to what matters first.
-3. **Fake interactivity** — hover states that don't change anything functional.
-4. **Emoji spam** — emojis as decoration where icons or restraint would serve.
-5. **Gradient crutch** — gradients used to mask weak composition.
-6. **Glass everything** — frosted glass on every panel.
-7. **Centered all the things** — center-aligned text when left-aligned reads better.
-8. **AI gray washing** — neutral grays everywhere, no character.
-9. **Generic CTAs** — "Get Started", "Learn More", "Click Here" with no specificity.
-10. **Stock illustration** — generic figure-with-laptop hero art.
-11. **Drop shadow soup** — shadows on cards on shadows on borders.
-12. **Loading spinner default** — spinner as the only loading state for everything.
-13. **Empty state void** — empty list with no guidance on what to do next.
-14. **Notification-soup tray** — every UI event becomes a toast.
+## The 14 visual-slop patterns (full catalog in `references/visual-slop.md`)
 
-Plus 17 anti-defaults (specific values to NEVER use without intent — `#3B82F6` blue, `rounded-lg` everywhere, etc.) in `references/anti-slop.md`.
+Watch for these in proposed designs and PR diffs:
+
+1. **Uniform-section flatness** — every section looks like every other section; no anchor for the eye.
+2. **Soft hierarchy** — headings barely larger than body; primary CTA same color as secondary.
+3. **Decorative hover** — hover states that don't change anything functional or clickable.
+4. **Emoji as ornament** — emojis in headers, CTAs, section labels where they add no information.
+5. **Gradient cover** — gradients used to mask weak composition rather than serve a poetic hero.
+6. **Glass-on-everything** — frosted-glass effect on every panel, including ones with nothing behind.
+7. **Center-aligned by default** — body paragraphs and forms reading center where left would read better.
+8. **Grayscale wash** — neutral grays everywhere, no accent personality, no character.
+9. **Verb-less CTAs** — "Get Started", "Learn More", "Click Here", "Submit", "OK".
+10. **Stock-illustration hero** — figure-with-laptop, diverse-team-around-table, abstract floating shapes.
+11. **Shadow soup** — shadows on cards on shadows on borders on gradients on one element.
+12. **Generic spinner** — wall-clock spinner as the only loading state for every operation.
+13. **Silent empty state** — "No items found." centered. Nothing else. No guidance.
+14. **Toast everywhere** — every UI event becomes a toast; five stack up and none get read.
+
+Plus 17 anti-default values (specific colors, radii, font choices, spacing presets) that signal "no thought went into this" — full list in `references/visual-slop.md`.
 
 ## Accessibility floor — non-negotiable
 
 Before any interactive widget ships:
 
-- [ ] Color contrast meets WCAG 2.2 AA (4.5:1 for body text, 3:1 for large text and UI components).
-- [ ] Focus-visible state exists and is distinct from hover.
-- [ ] Keyboard navigation works (tab order, escape closes modals, enter submits forms).
+- [ ] Color contrast meets WCAG 2.2 AA (4.5:1 body, 3:1 large text and UI components).
+- [ ] Focus-visible state distinct from hover.
+- [ ] Keyboard navigation works end-to-end.
 - [ ] ARIA labels for icon-only buttons.
-- [ ] Form errors are announced to screen readers.
+- [ ] Form errors announced to screen readers.
 - [ ] No keyboard traps.
+- [ ] Touch targets ≥24×24 CSS pixels (≥44×44 recommended on mobile).
+- [ ] Heading hierarchy is semantic (no skipped levels).
+- [ ] `prefers-reduced-motion` honored.
 
-Full verification recipes in `references/accessibility-floor.md`. This is a hard gate — `/dw-code-review` fails verdict if any interactive widget ships without these.
-
-## When the gate bends
+Full verification recipes in `references/accessibility-floor.md`. `/dw-review --code-only` rejects the verdict if any interactive widget ships without these.
 
-Real-world UI can't always be perfect:
+## When the grounding bends
 
-- **Bug fix in existing UI** — gate applies only to the area touched, not the whole surface.
-- **Pure copy change** — gate is just "scene sentence still holds?" — quick check.
-- **Spike / exploration** — gate skipped if the spike is explicitly marked throwaway; production code must run the gate.
+- **Bug fix in existing UI** — grounding applies only to the area touched, not the whole surface.
+- **Pure copy change** — only the "what does this help the user do" question still applies as a sanity check.
+- **Throwaway spike** — grounding skippable if the spike is explicitly marked non-production.
 
-In all bend cases, document the bend in the PR description (one line). "I skipped the state matrix because this is a one-line copy fix" is fine. "I skipped because I was in a hurry" is not.
+In all bend cases, document the bend in the PR (one line). "I skipped the state matrix because this is a one-line copy fix" is fine. "I skipped because I was in a hurry" is not.
 
 ## Integration with dev-workflow commands
 
-- `/dw-redesign-ui` runs the gate end-to-end. Steps 4 (propose design) and 7 (validate WCAG) consult this skill.
-- `/dw-create-techspec` UI sections must list which authorities were consulted (brand vs curated default) and reference the state matrix.
-- `/dw-code-review` checks the diff against `references/anti-slop.md` and the accessibility floor.
-- `/dw-functional-doc` documents the scene sentence in the overview.
-
-## Anti-patterns this skill prevents
-
-- "Just use the same hero as the marketing page" — without verifying the surface job differs.
-- "We'll add empty/error states later" — they're never added later.
-- "It looks fine on my desktop" — without checking mobile + keyboard + screen reader.
-- Designing in isolation from `.dw/rules/` documented patterns.
-- Inventing color values when the design system has tokens that fit.
-- Shipping interactive widgets without WCAG 2.2 AA verification.
+- `/dw-redesign-ui` runs the grounding end-to-end. Steps 4 (propose) and 7 (validate) consult this skill explicitly.
+- `/dw-plan techspec` UI sections must answer the 4 grounding questions and reference the state matrix.
+- `/dw-review --code-only` checks UI diffs against the 14 visual-slop patterns and the accessibility floor.
+- `/dw-functional-doc` records the surface-job and scene sentences in the overview for each screen.
 
-## Why this skill exists
+## Why this approach
 
-The previous bundled skill (`ui-ux-pro-max`) provided 161 color palettes and 57 font pairings — a CATALOG of taste. It had no gates, no anti-patterns, no enforcement. Agents loaded KB of palette data and still produced slop because there was no DISCIPLINE.
+The shorter route — "agent loads a 161-palette catalog and picks one" — produces dashboards that look like every other dashboard because the agent has no constraint that pulls it away from training-data centers of mass.
 
-This skill inverts that trade-off: 10 curated defaults (enough for 90% of cases) + a strong gate + an anti-slop catalog. Less context bytes, more leverage.
+The grounding pulls the design toward the specific surface, the specific user, the specific moment. Even with the same palette catalog, a "3am on-call dark room troubleshooting" design lands different choices than a "morning manager approving expenses" design. That difference is where surface quality lives.

package/scaffold/skills/dw-ui-discipline/references/accessibility-floor.md

@@ -1,6 +1,6 @@
 # Accessibility floor — WCAG 2.2 AA is the minimum, not the goal
 
-This reference is read in full before any interactive widget ships. Skipping any item below is a hard-block in `/dw-code-review`.
+This reference is read in full before any interactive widget ships. Skipping any item below is a hard-block in `/dw-review --code-only`.
 
 ## The non-negotiables
 
@@ -222,4 +222,4 @@ LLM-produced UI commonly fails on:
 - Modals that trap focus only on success path, not on error.
 - Auto-playing carousels with no pause control.
 
-`/dw-code-review` runs axe-style checks on the diff for these.
+`/dw-review --code-only` runs axe-style checks on the diff for these.

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

@@ -1,142 +1,162 @@
-# The hard-gate protocol — full version
+# The grounding protocol — full version
 
-Four checkpoints before any UI work touches code. Each has a concrete output. Don't proceed without finishing the current one.
+Four questions before any UI work touches code. Each has a concrete output. Don't proceed past one without finishing its output.
 
-## Why a gate at all
+## Why the grounding matters
 
-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.
+Training-data defaults dominate ungrounded UI generation. An LLM proposing a "dashboard" without context will produce:
+- `#3B82F6` blue + `rounded-lg` because those values appeared 10M+ times in training.
+- Glass morphism, gradients, center-aligned blocks because those screenshots dominate web aesthetics.
+- Happy-path layouts only, because most training screenshots show success states.
 
-The gate forces grounding in this project's reality before training-data autopilot fires.
+The four questions pull the design AWAY from the training-data center of mass and TOWARD this project, this surface, this user, this moment.
 
-## Checkpoint 1: Brand authorities OR curated defaults
+## Question 1 — Where do design decisions come from?
 
-**Goal:** know where visual decisions come from. Documented authority, or curated default — never invented.
+**Goal:** know the source of truth for visual values. Documented authority, or curated default — never invented.
 
-**How:**
+### How to find it
 
-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.
+Search the project in this order:
 
-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.
+1. **`.dw/rules/*.md`** — look for sections titled "Design", "Patterns to Follow", "Naming Conventions". The codebase intelligence skill writes these.
+2. **Root-level docs** — `DESIGN.md`, `BRAND.md`, `BRANDING.md`, `STYLE_GUIDE.md`.
+3. **Token configuration** — `tailwind.config.{ts,js}` `theme` block; CSS variables in `globals.css`, `theme.css`, `tokens.css`.
+4. **Component library config** — shadcn `components.json`, MUI/Chakra theme exports.
+5. **Storybook stories** — implicit canonical components.
 
-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:
+### What to do based on what you find
 
-   > **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.
+**At least one authority exists**: it wins. Defer to it. If you need a token it doesn't have (e.g., a danger-secondary color), propose adding the token to the authority FIRST, then use it. Don't hardcode the new value.
 
-**Anti-patterns at this checkpoint:**
+**No authority exists**: read `curated-defaults.md` in this references folder. Pick one of the 10 palettes + one of the 10 font pairings. Mark the choice as a finding in the techspec/PR:
 
-- Inventing color hex values inline (`bg-[#FF6B35]`).
+> **Design source**: No project authority found. Using curated default "Cool Stone" (neutral slate + intentional accent) + "Inter / Source Serif" pairing. Recommend establishing `DESIGN.md` to formalize.
+
+### Anti-patterns at this question
+
+- Inventing color hex 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.
+### Output
+
+A one-sentence note in the techspec or PR describing which authority you consulted.
 
-## Checkpoint 2: Surface job sentence
+## Question 2 — What does this surface help the user do?
 
 **Goal:** the user's intent at this surface, stated in one specific sentence.
 
-**Format:** "This surface helps the user **<verb-phrase>** so that **<outcome>**."
+**Format:** "This surface helps the user **`<verb-phrase>`** so that **`<outcome>`**."
 
-**Examples — good:**
+### Good examples
 
-- "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."
+- "...helps the user filter overdue invoices so they can chase late payers in under 30 seconds."
+- "...helps the on-call engineer diagnose which deploy caused the spike so they can roll back without paging the team."
+- "...helps the manager approve or reject expense reports without leaving Slack."
 
-**Examples — bad:**
+### Bad examples
 
-- "This surface displays invoice data." (no user, no outcome)
-- "Settings page for managing the account." (vague, no specificity)
-- "Dashboard." (one word)
+- "This surface displays invoice data." → no user, no outcome.
+- "Settings page for managing the account." → vague.
+- "Dashboard." → one word; says nothing.
 
-**How to push back when the brief is vague:**
+### 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?"
+If you can't write this sentence, the requirements are unclear. Stop. Push back to the requester:
+
+> "Before designing this surface, I need the job sentence: 'helps the user `<verb-phrase>` so that `<outcome>`.' 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.
+### Output
+
+One sentence in the techspec/PR description.
 
-## Checkpoint 3: Complete state matrix
+## Question 3 — What states does the surface have?
 
-**Goal:** enumerate every state the surface can be in, BEFORE designing for the happy path.
+**Goal:** enumerate every state the surface can be in BEFORE designing for the happy path.
 
-**Minimum states (always enumerate):**
+### Mandatory minimum
 
 | 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 |
+| `active` | Click in progress (mouse down) | Pressed/depressed |
+| `focus-visible` | Keyboard tab arrives | Distinct outline, NOT same as hover |
+| `disabled` | Interaction unavailable | Reduced opacity + cursor change; NO on-click |
+| `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 |
+| `success` | Operation succeeded | Confirmation; auto-dismiss when safe |
 
-**Add domain-specific states as needed:**
+### Domain-specific states
 
-- Read/unread (notifications, messages)
-- Online/offline (chat, collaborative tools)
-- Stale/fresh (dashboards with cached data)
-- Pending/approved/rejected (workflow states)
-- New/saved/dirty (forms)
+Add when the surface has matching semantics:
+- `read` / `unread` — notifications, messages.
+- `online` / `offline` / `connecting` — chat, presence.
+- `stale` / `fresh` — dashboards with cached data.
+- `pending` / `approved` / `rejected` — workflow records.
+- `draft` / `saved` / `dirty` — forms, editors.
+- `new` / `existing` — composers (title and CTA wording differ).
+- `partial` / `complete` — multi-step flows.
+- `selected` / `unselected` — lists with multi-select.
+- `expired` / `active` — tokens, subscriptions.
 
-**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.
+### Tripwire
 
-**Output:** A state matrix table in the techspec or design doc.
+If your design has only `default`, you missed 8 states. If it has `default` + `loading`, you missed 6. The full enumeration is non-negotiable. Empirically, states added "later" are added after a user reports the bug.
 
-## Checkpoint 4: Scene sentence
+### Output
+
+A state matrix table in the techspec or design doc.
+
+## Question 4 — Who uses this surface, where, and in what mood?
 
 **Goal:** the physical context the surface lives in.
 
-**Format:** "**<Who>** uses this **<where>** in **<what light>** while **<what mood>**."
+**Format:** "**`<Who>`** uses this on **`<where>`** in **`<what light>`** while **`<what mood>`**."
 
-**Examples — good:**
+### Good examples
 
 - "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."
+- "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 answer:
 
-**Why this matters:**
+- **3am dark room** → dark mode default, high contrast, no flashing animations, generous spacing.
+- **Bright outdoor** → minimum 7:1 contrast, large touch targets, no thin fonts, no subtle hover.
+- **Busy front desk** → glanceable info, no nested menus, large numbers, single-screen layout.
 
-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 answer, defaults take over: light mode, default contrasts, animations, regular touch targets. Production users find it terrible and you can't articulate why.
 
-Without the scene, defaults take over: light mode, default contrasts, animations, regular touch targets. Production users hate it; you can't articulate why.
+### Output
 
-**Output:** Scene sentence in the techspec.
+One sentence in the techspec.
 
-## What "passing the gate" looks like
+## What "passing the grounding" looks like
 
-A PR description / techspec UI section that includes:
+A PR description or techspec UI section that includes:
 
 ```markdown
-## UI Discipline Gate
+## UI Discipline Grounding
 
-**Authority:** `.dw/rules/frontend.md` design tokens (Tailwind theme + custom CSS vars).
+**Design source:** `.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.
+**Context:** 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.
+This is the minimum disclosure. Anything less and the grounding didn't pass.
 
-## When this gate has been run
+## After grounding
 
-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.
+The downstream references (`visual-slop.md`, `state-matrix.md`, `accessibility-floor.md`) assume the grounding passed. They won't re-verify; if you skipped a question, the output will reflect it.
 
-`/dw-code-review` failing verdict on a UI PR where this disclosure is missing.
+`/dw-review --code-only` fails verdict on UI PRs where this disclosure is missing.

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

@@ -86,7 +86,7 @@ Before declaring the design "done":
 - [ ] `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`
+## Integration with `/dw-review --code-only`
 
 Review fails verdict (REJECTED) on a UI PR when:
 - A new component handles async data but renders only the default state.