Design Incident Response

/design-incident-response — Triage what to fix first

/design-reviewer measures the design. This skill decides what to fix first. The pairing matters: an audit that scores 5 dimensions and surfaces 12 findings is not a remediation plan — it's a list. This skill is the decision tree.

Required pre-input: either a fresh /design-reviewer report OR a symptom report (the user describes what feels wrong; e.g., "this card section looks like AI slop").

For the pairing contract → see .claude/rules/audit-triage-pairing.md.

Workflow at a glance

The first action is non-negotiable per branch. The full sequence is the recommended order; deviate only if the symptom report names a different priority explicitly.

The 5 incident branches

Branch 1 — Banned pattern detected

Symptoms. /design-reviewer flagged one or more banned-pattern hits from anti-patterns.md. Top offenders by frequency: gradient text (background-clip: text with a gradient), side-stripe borders (border-left ≥2px as a colored stripe), generic drop shadows on rounded rectangles, hero-metric template layouts (giant number + tiny label as the hero), icon-tile-above-heading template layouts, glassmorphism (backdrop-filter: blur(...)) on arbitrary surfaces, cardocalypse (3+ nested cards), centered prose paragraphs (>1 sentence centered).

First action (Day-0, <30 min). Pick the SINGLE most visible offender on the homepage / hero / landing-page-above-fold. Remove it. Don't replace it yet — just remove. Take a before/after screenshot. Commit: fix(design): remove {pattern} from {component}.

Day-0 (rest). Sweep the rest of the homepage for the same pattern. Remove all instances. One commit per component, with before/after screenshot.

Day-1. Sweep the remaining pages (pricing, product, blog template). Apply the same sweep. Re-run /design-reviewer on the homepage to confirm the branch is closed.

Day-14. Add the banned pattern to the project's CI lint (CSS lint rule, eslint rule, or stylelint plugin) so the pattern can't be reintroduced. Cite anti-patterns.md in the lint rule comment.

Hand-off. Back to /design-reviewer for re-measurement. If new patterns surface, re-enter this branch.

Branch 2 — Contrast / a11y fail

Symptoms. /design-reviewer flagged WCAG AA contrast violations (text below 4.5:1 for normal, 3:1 for large), missing focus-visible outlines on interactive elements, "gray on color" findings (light label on accent background), color-only meaning (status indicated by hue alone).

First action (Day-0, <30 min). Run the page through a contrast checker (Stark, axe DevTools, or mcp__chrome-devtools__lighthouse_audit) and identify the WORST contrast violation (lowest ratio, most-visible component). Fix that one element. Screenshot before/after. Commit: fix(a11y): contrast {component} {old-ratio}→{new-ratio}.

Day-0 (rest). Fix every violation below 3:1. These are not WCAG AA failures only — they're often illegible to a sighted user too.

Day-1. Fix violations between 3:1 and 4.5:1 (large-text-safe but normal-text-failing). Add a :focus-visible style to every interactive element. Re-run /design-reviewer to confirm a11y dimension passes.

Day-14. Add automated a11y testing (axe-core, pa11y, or Lighthouse CI) to the deploy pipeline. Target: 0 contrast violations on PR. Document the policy in docs/a11y-policy.md.

Hand-off. Back to /design-reviewer for re-measurement. If the brand's tokens themselves are the problem (e.g., the brand's default body-on-surface fails 4.5:1), hand off to /brand-kit to revise the token values.

Branch 3 — Cardocalypse (nested cards)

Symptoms. /design-reviewer flagged 3+ levels of nested cards. Symptom report: "this page feels visually noisy / busy / claustrophobic." Common cause: card-in-card-in-card pattern from a UI library default + a "make it more designed" iteration.

First action (Day-0, <30 min). Pick the deepest-nested card stack on the most-visible page. Flatten ONE level — promote the innermost card's content to a section with whitespace separation; delete the innermost card border / background. Screenshot before/after. Commit: fix(design): flatten card nesting in {component}.

Day-0 (rest). Walk the rest of the homepage. For each card stack >2 levels deep: flatten to ≤2 levels. Use whitespace, dividers, or section spacing instead of additional card frames.

Day-1. Sweep all pages. Establish a project-wide rule: max 2 levels of containment. Document in docs/design-rules.md.

Day-14. Audit the design system / token file. If the Card component defaults encourage nesting (e.g., the Card variant ships with internal padding that nests Cards visibly), revise the variant to discourage it.

Hand-off. /landing-page-wireframe or /website-build if the underlying layout decision needs rework. Otherwise back to /design-reviewer.

Branch 4 — Motion overload

Symptoms. /design-reviewer flagged >3 motion moments per visible screen, or bounce easing (cubic-bezier(...,1.55)) on routine state transitions (hover/click on standard buttons), or motion durations >200ms on state transitions, or animations triggering simultaneously on scroll.

First action (Day-0, <30 min). Disable bounce easing on every routine state transition (hover, click, focus). Replace with standard ease (e.g., cubic-bezier(0.4, 0, 0.2, 1)) at 150ms duration. Screenshot before/after a hover state. Commit: fix(motion): replace bounce easing on routine state transitions.

Day-0 (rest). Audit the page for motion-on-scroll triggers. Disable everything except a single hero entrance (if any). Keep entry/exit motion for modal/drawer surfaces — those are functional, not decorative.

Day-1. Set project-wide motion budget: ≤3 motion moments per screen, all routine state transitions ≤200ms, only entry/exit motion may run 300–600ms. Document in docs/motion-rules.md (or extend `design-reviewer/the premium reference into the project repo).

Day-14. Add a prefers-reduced-motion media query that disables non-essential motion entirely. Re-run /design-reviewer on the homepage and a feature page to confirm motion dimension passes.

Hand-off. /video-frames if the issue is in a video composition. /vibe-coding if the motion is in shipped code. Otherwise back to /design-reviewer.

Remedial preference hierarchy (delete first). When you pick a fix for a motion finding, reach for the earliest move that resolves it before any later one:

1. Delete — high-frequency, no purpose, or keyboard-triggered motion. Removing it is the fix.
2. Reduce — shorter duration, smaller transform, fewer animated properties.
3. Fix the easing — swap ease-in → ease-out or a strong custom curve; drop bounce on routine states.
4. Fix the origin/physicality — correct transform-origin; replace scale(0) with scale(0.95) + opacity.
5. Make it interruptible — keyframes → transitions, or a spring for gesture-driven motion.
6. Move it to the GPU — layout props → transform/opacity; Framer Motion shorthand → the full transform string.
7. Asymmetric timing — slow the deliberate phase, snap the response.
8. Polish — blur to mask crossfades, stagger groups, @starting-style for entry.
9. Accessibility and cohesion — add reduced-motion and hover gating; tune to the component's personality.

Delete beats reduce; reduce beats re-tuning. Most motion-overload findings close at steps 1–3.

Before / After findings. Record each motion fix as a row, not a paragraph — one line per issue, so the commit log reads as a diff of intent:

Verdict — block or approve. Close the branch with an explicit call:

• Block while any of these stand — bounce on a routine state transition, motion on a keyboard or 100+/day action, a UI transition over 300ms with no reason, scale(0) or ease-in on UI, or a layout-property animation with an easy GPU fix.
• Approve once bounce is gone from routine states, the screen sits under three motion moments, state transitions run under 300ms on ease-out, rapidly-triggered motion is interruptible, and prefers-reduced-motion is respected.

Branch 5 — Token drift (hardcoded values)

Symptoms. /design-reviewer flagged hex codes / font names / radii hardcoded in component code instead of referencing DESIGN.md tokens ({colors.primary} etc.). Symptom report: "I tried to change the brand color but it only changed in three places."

First action (Day-0, <30 min). Find the SINGLE most-used hardcoded hex in the codebase (grep -rE '#[0-9a-fA-F]{6}'). If the hex matches a DESIGN.md token, replace every occurrence with a var(--token-name) or Tailwind utility. Screenshot before/after a component using the color. Commit: fix(tokens): replace hardcoded {hex} with var({token-name}).

Day-0 (rest). Continue grep-and-replace for the top 3 hardcoded hex codes. Do not yet handle font / radius drift — colors first.

Day-1. Audit font-family declarations and border-radius values. Replace hardcoded values with token references. Verify Tailwind config maps utilities to the right CSS variables (see design-production.md "Web rendering path — Step 4").

Day-14. Add a stylelint rule banning hardcoded hex / font-family / border-radius values in component code (allow only var(--*) or Tailwind utilities). Document the new rule in docs/design-rules.md.

Hand-off. /vibe-coding if the codebase is small and Claude can sweep it. /website-build if the codebase needs structural refactor. /brand-kit if the underlying DESIGN.md tokens are missing the values being hardcoded (i.e., the codebase is hardcoding because the token doesn't exist yet).

Multi-branch incidents (when more than one branch fires)

Common case: /design-reviewer flagged 8 findings across 3 branches. Sequencing rule:

1. Branch 2 (a11y) first, always. A11y is the only branch where the cost of NOT fixing is legal/regulatory, not just aesthetic. Day-0 a11y fixes precede everything else.
2. Branch 5 (token drift) second. Token drift makes every subsequent fix harder — you can't fix banned patterns or cardocalypse cleanly if the tokens are also wrong.
3. Branch 1 (banned patterns) third. Most visible to the user; closes the "is this AI slop" perception fastest.
4. Branch 3 (cardocalypse) fourth. Often correlated with banned patterns; fixing those first usually drops the card-stack depth as a side effect.
5. Branch 4 (motion) last. Motion overload is usually a polish-pass issue; fix it after structural problems are resolved.

If two branches share a Day-0 window, split: one engineer takes Branch 2, another takes Branch 5. Don't try to triage motion overload while contrast is still failing.

Atomic-commit + before/after screenshot pattern

Every fix is one commit. Every commit message includes:

fix(design): {branch}: {component} — {one-line description}

Before: [link to screenshot or inline base64]
After: [link to screenshot or inline base64]
Branch: {1-5}
Severity: P{0-3}
Re-run: /design-reviewer expects {dimension} to move from {x} to {y}

Screenshots can be:

• Saved to docs/design-review-screenshots/{commit-sha-prefix}-{component}.png
• Or inline base64 in the commit message body (small images only)
• Or linked from a GitHub Issue / PR comment

The point is: a future reviewer can read the commit log and see the visual evolution without re-running the audit.

Anti-Hallucination Guardrails

1. Never skip the audit. If no /design-reviewer output exists, run it first. Don't triage off vibes.
2. First action must be visible. A Day-0 fix that the user can't see in <30 min is the wrong fix. Pick the most-visible offender, not the cleanest.
3. One commit per fix. Bundling 5 fixes into one commit makes review impossible and re-measurement misleading.
4. Don't re-measure after every commit. Run /design-reviewer only after Day-0 completes — re-measuring after each commit is noise.
5. If the brand's tokens are wrong, stop. Hand off to /brand-kit. Triage cannot fix bad tokens by working around them.

Integration with other skills

This skill is a decision tree, not an executor. It tells you what to fix and in what order; the actual code/design changes happen in the hand-off target.

Quality checks (pre-output)

• Symptom mapped to exactly one branch (or sequenced if multi-branch)
• First action is specific (named component, named pattern, named fix)
• Day-0 / Day-1 / Day-14 actions all named with concrete checklist items
• Hand-off target is a real existing skill (not invented)
• Atomic-commit pattern documented with example
• Re-measurement plan named

Attribution

This skill's structure is conceptually attributed to the Designer-Who-Codes pattern documented in nexu-io/open-design/skills/design-review (Apache-2.0, snapshot 2026-05-13) and its upstream source garrytan/gstack. Both upstreams are catalogue-stub references in the Open Design repo; the actual workflow content here is Genesys-authored against our existing audit-triage-pairing.md rule.

The atomic-commit + before/after-screenshot pattern is from the same source.

Branch 4's motion depth — the delete-first remedial preference hierarchy, the Before/After findings table, and the block/approve close — is adapted from Emil Kowalski's animation review method (animations.dev), MIT © 2026 Emil Kowalski. As with /design-reviewer (which carries the full 10-standard lens), that review method — non-negotiable standards, escalation triggers, and a remedial hierarchy — is itself adapted from aggressive code-quality review.