joint-design-review

Files (12)

• BACKLOG.md
• SKILL.md
• default-bar.md · references/
• evidence.md · references/
• quality-references.md · references/
• report-template.md · references/
• tracking.md · references/
• contention.mjs · scripts/
• findings.mjs · scripts/
• io.mjs · scripts/
• shoot.mjs · scripts/
• static-scan.mjs · scripts/

SKILL.md (first lines)

# Joint design review

A design review is **joint**: the agent audits and fixes; the user rules. Every finding
lands in exactly one of two classes — **standing approval** (fix without asking) or
**ruling required** (park and ask). The cycle is: scope → load the bar → preflight →
audit → report → triage → rulings → materialise → implement.

**One product area per cycle. Never two.** A review that spans areas produces findings
nobody can act on and beads nobody owns.

Four scripts do the mechanical work. Run them; do not reimplement them by eye.

| Script | Step | Does |
| --- | --- | --- |
| `scripts/contention.mjs` | 3 | Resolves the area's data path and fails if any of it is dirty |
| `scripts/static-scan.mjs` | 4 | Deterministic sweep for the checkable Class A candidates |
| `scripts/shoot.mjs` | 4 | Captures every surface and rejects any capture of the wrong page |
| `scripts/findings.mjs` | 5, 7 | Validates the findings tracker; materialises it into real issues |

## 1. Scope

If the user named an area, that is the scope. If not: inventory the app's areas, check
which are contended, and propose an order with a one-line recommendation.
**Done when:** one named area is agreed.

## 2. Load the bar — progressively

Read the repo's `AGENTS.md`, docs entrypoint, and design-system doc first. The repo's
own contracts always win over the generic bar, and a repo-declared frontend skill order
is used verbatim.

When the repo has no `DESIGN.md`, no design-system doc, and no frontend rules in
`AGENTS.md`, load [references/default-bar.md](references/default-bar.md) as the bar
before reading a component. Name it in the report's "bar loaded" line.

Otherwise detect the stack from `package.json` and load skills **at the step that uses
them**, one rule-set in focus at a time. Staged loading is not about tokens: seven
rule-sets at once interfere — near-synonymous terms drift between skills, and a rule
from one bleeds into a dimension another owns.

| When | Load |
| --- | --- |
| Now, before reading a single component | `/impeccable`, plus the stack skill: `/tanstack` on TanStack; `/vercel-react-best-practices` on Next.js or plain React |
| Audit — heuristics and a11y | `/ux-audit` |
| Audit — motion, and any motion fix later | `/emil-design-eng` |
| Audit — reinvention | `/pick-ui-library` |
| Audit — modality pass, and polish during implementation | `/ui-polish` |

Framework-named skills still carry portable React standards — use those parts on any
React stack and discard only the framework-specific rules. Index-style skills stay
index-only: pull the individual rule files a finding touches, never the full expansion.

**Done when:** the bar is loaded before you have read a single component. Loading it
after forming an opinion is not loading it.

## 3. Preflight

1. **The app renders — hard gate.** Load it and confirm a real surface appears. A design
   review without the running app is a code review wearing a costume. If the server is
   down, say so in one sentence and stop. Never start, restart, or kill a server you do
   not own.
2. **Contention — run the script.** `node scripts/contention.mjs <area-paths>`. It
   resolves the area's imports back to the packages it renders from and fails if either
   set is dirty. Checking only the area's own component files is not enough: an area
   whose components are clean can still be served by a query another agent is mid-edit
   on, and the review will spend its effort diagnosing that.
3. **History, and what is deliberate.** Read the prior audits, screenshot sets, and
   design specs for this area. Then ask the question they rarely answer directly:
   **which of this area's current behaviours are deliberate?** A surface that looks
   under-built is often a decision you cannot see from the code. State in the report
   which prior findings you rechecked and their state now.
4. **Pin the tree.** Record the commit SHA and any dirty files. A finding crossing a
   dirty file is **provisional** and is rechecked before it becomes work.

## 4. Audit

**Mechanical sweep first**, before any eyes-on work:

```bash
node scripts/static-scan.mjs <area-paths>     # dirs and files, in any mix
```

Hits are **candidates, not findings** — verify each in context. Record the result,
including a clean one; a skipped scan is a coverage gap.

**Then capture every surface** with `scripts/shoot.mjs` and a config
(see [references/evidence.md](references/evidence.md)). The harness warms up the session
and asserts each capture landed on the page you asked for, then exits non-zero if any
did not. Never reason about an image it rejected.

Then work surface by surface — list, detail, create/edit, empty, loading, error,
permission-denied. Cover desktop and mobile **separately and fully**; optimise each
modality on its own terms rather than accepting a compromise mediocre on both.

Dimensions, all of which the report must account for:

1. **Flow and dead ends** — every reachable state, and whether the user can get out.
2. **Heuristics** — Nielsen per `/ux-audit`; name the heuristic on each finding.
3. **Accessibility** — keyboard path, focus order and visibility, composite-widget
   semantics, contrast, touch targets, colour-only meaning, labels.
4. **Design-system conformance** — judged against the project's own contract.
5. **Motion** — purpose, frequency, easing, duration, press feedback, reduced-motion.
6. **Reinvention** — behaviour hand-rolled that an installed dependency owns.
7. **React and data correctness** — reset boundaries and keys, derived vs stored state,
   subscription lifecycle, waterfalls, re-render cost.
8. **Copy** — plain, and no longer than it needs to be.
9. **Consistency** — one concept rendered one way everywhere.

**When a finding contradicts a deliberate choice**, do not assert breakage. State the
choice, say why it still costs the user, and bring evidence that a better option exists
— a [quality reference](references/quality-references.md) is the strongest form. Split
the artifact from the intent: a sound decision can leave an unsound implementation
behind it, and filing them as one finding makes the whole thing rejectable.

**Done when:** every surface and dimension is covered, each finding has evidence, and
you have also recorded what you traced and cleared. A hit-only audit is not trustworthy.

## 5. Report

From ryangriffinau/skills, MIT.

More from ryangriffinau/skills