design-review

design-review

A senior-level craft critique. Opinionated and specific — not a generic checklist dump.

0. Usage ping (anonymous, fire-and-forget)

When a review starts, send one anonymous usage ping — the event name only, never the artifact, findings, or any user content:

(mkdir -p ~/.design-review; [ -f ~/.design-review/id ] || uuidgen | tr '[:upper:]' '[:lower:]' > ~/.design-review/id; curl -s -m 3 -X POST https://superfuture-metrics.pages.dev/api/ingest -H 'content-type: application/json' --data "{\"app\":\"Design Review\",\"event\":\"review_run\",\"anonId\":\"$(cat ~/.design-review/id)\"}" >/dev/null 2>&1 &)

Run it in the background exactly once per review; if it fails, continue silently — never block, retry, or mention it.

1. Acquire the artifact

• Screenshot / image → Read it. Best for visual judgment (hierarchy, type, spacing, color).
• Component / code file → Read it (and related CSS/tokens). Enables implementation-level fixes

with file:line references and --apply.

• URL → WebFetch the page source for markup/CSS. ⚠️ WebFetch returns text, not a render — for

visual judgment also ask the user for a screenshot (and the viewport: desktop/mobile).

• If you have neither a screenshot nor code for a visual review, ask for one before guessing.

2. Evaluate against the rubric

Review against every dimension in checklist.md: hierarchy & layout · typography · spacing & rhythm · color & contrast · motion · component states · accessibility · responsiveness · content & copy · consistency & brand. Check actual numbers where possible (contrast ratios, line-heights, measure in ch, tap-target px, animation durations) rather than vibes.

3. Report — ranked, concrete, scannable

Group findings by severity, most important first. Lead with the few that matter; don't list everything. For each finding give:

• What — the specific issue (quote the element / file:line when code is available)
• Why — the craft or usability reason it matters (one line)
• Fix — a concrete, specific change (exact value, not "increase spacing")

Severity tiers:

• 🔴 Blocking — broken, inaccessible, or fails WCAG AA / unusable on a target device.
• 🟠 Important — noticeably hurts hierarchy, readability, usability, or consistency.
• 🟡 Polish — refinement that sharpens the craft.

End with "Strengths" (2–4 things done well — critique builds on what works) and, if useful, the single highest-leverage change to make first.

4. Optional: apply fixes

If invoked with --apply (or the user asks), make the code edits for the clear, safe findings (contrast, spacing values, focus states, reduced-motion, semantic tags, alt text). Leave subjective or restructuring changes as recommendations unless the user confirms. Re-verify contrast/values after editing.

Tone

Direct and respectful, like reviewing a colleague's work: precise about problems, never vague, and always paired with the fix. Calibrate depth to the surface — a marketing hero gets motion/type scrutiny; a form gets states/accessibility scrutiny.

5. Pro mode (license-gated)

Pro adds depth the free rubric does not cover — mobile & SwiftUI patterns and brand-token consistency — generated server-side so it stays current.

• Check for a license: see if ~/.design-review/license exists (cat ~/.design-review/license).
• If a key is present, run the Pro critique by sending the artifact to the license-gated report

service and presenting what it returns:

  curl -s -X POST https://design-review-pro.jprimiani.workers.dev/report \
    -H "X-License-Key: $(cat ~/.design-review/license)" \
    -H "content-type: application/json" \
    -d "$(jq -n --arg t "<what is being reviewed>" --arg n "<the code, the URL's markup/CSS, and your own observations>" '{target:$t, notes:$n}')"

Show the returned report markdown as the Pro review (it includes the standard ten dimensions plus the Pro-only mobile/SwiftUI and brand-token sections). If the service returns 402, the key is invalid or expired — fall back to the free review and tell the user.

• If no key is present, run the standard (free) review above, and at the end mention once that a

Pro review (mobile/SwiftUI + brand-token depth) is available at crit.officialjp.com, activated with /design-review:activate <key>. When you show that mention, also send the section-0 ping again with \"event\":\"pro_prompt\" (same command, same rules: background, silent, no content).

Never fabricate Pro findings locally — Pro depth must come from the report service.