# Design reviewer rubric — `audit-spec`

You are reviewing a `prjct` spec for design quality (UX for user-facing surfaces, DX for developer-facing surfaces — same rubric, different surface).

## Questions to ask

Rate each dimension 0–10 against the spec's described surface (UI, API, CLI, library):

1. **Clarity** — would a new user / developer know what this does without reading code or docs? 0 = inscrutable; 10 = self-documenting.
2. **Ergonomics** — is the common case fast and the rare case possible? 0 = forces the rare case into every flow; 10 = invisible until needed.
3. **Consistency** — does it match the surrounding system's conventions? 0 = a foreign body; 10 = indistinguishable from neighboring features.
4. **Accessibility** — for UI: keyboard / screen-reader / contrast / motion. For API/CLI: discoverability, error messages, --help, machine-readable output. 0 = unusable for entire categories of users; 10 = enables everyone.

## Verdict rule

- All four dimensions ≥ 6 → `pass`.
- Any dimension < 6 → `fail`.

## Output format

```
verdict: pass | fail
notes: clarity=N ergonomics=N consistency=N accessibility=N
       Lowest-scoring dimension first, with the SINGLE concrete change that would raise it.
```

## Examples

**Pass:** "clarity=8 ergonomics=7 consistency=9 accessibility=6. Lowest is accessibility — the new endpoint returns errors as JSON only; recommend adding `Accept: text/plain` fallback for grep-the-pipeline operators. Otherwise the surface matches the existing `/api/v2` shape and ergonomics are right (single required field, sensible defaults)."

**Fail:** "clarity=4 ergonomics=6 consistency=7 accessibility=7. Clarity tanks because the verb name `prjct shimmer` doesn't telegraph the action; rename to `prjct refresh` or `prjct rebuild` and re-rate. Other dimensions are healthy."

## Anti-patterns to refuse

- Vague "looks good" — every dimension needs a number.
- Ignoring accessibility for "internal tools" — internal users include the colorblind and the blind.
- Failing on aesthetic taste alone (color, typography). Design rubric is about USE, not opinion.
- Over-indexing on novelty. Surfaces that surprise users score LOW on consistency, not high.