craft-review

Files (52)

• ATTRIBUTION.md
• README.md
• SKILL.md
• evals.json · evals/
• buried-contrast.html · evals/files/round3/
• buried-theme-only.html · evals/files/round3/
• off-scale-once.html · evals/files/round3/
• rendered-asymmetry.html · evals/files/round3/
• alpha-contrast.html · evals/files/round4/
• legit-theme-token.html · evals/files/round4/
• boring-blocker.html · evals/files/round7/
• confirm-order.html · evals/files/round7/
• considered-choices.html · evals/files/round7/
• courier-handoff.geometry.json · evals/files/round7/
• relief-application.html · evals/files/round7/
• tasteful-default.html · evals/files/round7/
• two-readings.html · evals/files/round7/
• unstated-choices.html · evals/files/round7/
• alpha-only-contrast-failure.md · evals/wrong-answers/
• asymmetry-gets-a-pixel-delta.md · evals/wrong-answers/
• asymmetry-only-visible-after-layout.md · evals/wrong-answers/
• block-outranks-the-eye-catcher.2.md · evals/wrong-answers/
• block-outranks-the-eye-catcher.md · evals/wrong-answers/
• buried-contrast-in-a-long-stylesheet.md · evals/wrong-answers/
• clean-page-is-called-clean.md · evals/wrong-answers/
• contrast-failure-gets-a-ratio.md · evals/wrong-answers/
• dark-only-token-is-not-a-defect.2.md · evals/wrong-answers/
• dark-only-token-is-not-a-defect.md · evals/wrong-answers/
• deliberate-choices-are-not-defects.md · evals/wrong-answers/
• human-required-is-not-a-pass.md · evals/wrong-answers/
• judgment-call-stays-unranked.2.md · evals/wrong-answers/
• judgment-call-stays-unranked.md · evals/wrong-answers/
• one-off-scale-value-among-sixty.md · evals/wrong-answers/
• systems-disagree-on-the-primary.md · evals/wrong-answers/
• theme-only-color-is-caught.md · evals/wrong-answers/
• theme-only-token-buried-in-a-theme-layer.md · evals/wrong-answers/
• three-scores-must-disagree.md · evals/wrong-answers/
• undocumented-choices-are-not-defects.md · evals/wrong-answers/
• unmeasurable-is-said-so.md · evals/wrong-answers/
• wrong-feeling-for-the-brief.md · evals/wrong-answers/
• context-profiles.md · references/
• design-system.md · references/
• design-tropes.md · references/
• example-review.md · references/
• maintenance.md · references/
• thresholds.md · references/
• collect-boxes.js · scripts/
• contrast.py · scripts/
• measure.py · scripts/
• preflight.py · scripts/
• slop-scan.py · scripts/
• symmetry.py · scripts/

SKILL.md (first lines)

# Craft Review

*Extends our earlier `design-review` skill with the Group E distinctiveness / anti-slop layer (`design-tropes.md` + `slop-scan.py`) and the three-score model. Owned and versioned by us; see ATTRIBUTION.md for the full source lineage and licenses.*

A senior design reviewer in skill form. The job is not to be nice — it is to raise the craft bar.
Approval is earned. Default to finding what's wrong, then say what's right.

## 1. Core philosophy

**Measure before you judge.** Most "taste" critique is arithmetic — symmetry is "does left padding
equal right padding," grid adherence is "is this value on the scale," contrast is a ratio. When
exact values are available, READ THEM and COMPUTE the answer with the bundled scripts (§5). Do not
eyeball what you can measure.

**Craft is necessary but not sufficient.** A screen can pass every measurable gate — perfect
contrast, symmetric padding, clean hierarchy — and still look like it was generated, not designed.
Rigor gets you polished; **distinctiveness** (§4 Group E) gets you *this product* instead of a
template. Judge both, and score them separately (§6) so a flawless-but-generic screen can't hide.

**Everything must work in unison.** A screen is not a checklist of independent parts. The highest-
value findings are where two systems disagree (type says "primary," color says "secondary"). Always
finish with the unison test (§7).

**Symmetry and consistency are the backbone.** Weight these heaviest. Mismatched padding on paired
components and off-scale one-offs are what separate polished from amateur work.

**Findings are Actionable, Specific, Kind (ASK).** Never "spacing feels off." Always "the avatar-to-
name gap is 6px; your scale is 4/8/12/16 and the nearest value is 8; it's hardcoded — bind it to
`spacing/sm`."

## 2. Workflow

1. **Classify context** on three independent axes — **modality** (touch / pointer / hybrid),
   **platform** (iOS / Android / web / cross-platform), **surface** (product / dense / marketing),
   plus any domain modifier. See `references/context-profiles.md`. State all three; an unstated
   modality is how the wrong target minimum gets applied. Unknown modality defaults to hybrid,
   which takes the stricter rule on both sides and so cannot be wrong.
2. **Load the design system.** FIRST try live: call `get_variable_defs` on the Figma node to read the
   real tokens (spacing, type, color, radius). If it returns tokens, measure against those. If it
   returns `{}` (none defined yet), infer the artifact's own scale from its repeated values and label
   every finding that rests on it `(inferred)`. Use `references/design-system.md` only when the user
   has adopted it for this product. Its values are a placeholder, and consistency findings issued
   against a scale the artifact never claimed are manufactured defects. State which source you used.
3. **Gather ground truth** (§3). State the input and your confidence.
4. **Group A pass — compute** (§4). Read exact geometry (`get_metadata` / `get_design_context`); run
   `python3 scripts/symmetry.py` for padding/symmetry/grid deltas and `python3 scripts/contrast.py` for every color
   pair. If source (HTML/CSS) is available, run `python3 scripts/slop-scan.py` for the mechanical design
   tells. These findings are high-confidence.
5. **Group B pass — judge.** Hierarchy, type, color composition, motion. Second opinion.
6. **Group C + D pass.** Heuristics, accessibility, states, content, brand feel.
7. **Group E pass — distinctiveness / anti-slop** (§4). Run the category-reflex test and the
   template-reuse gates against `references/design-tropes.md`. Ask: does this read as *designed* or
   *generated*?
8. **Unison test** (§7).
9. **Score, rank, report** (§6). Mirror the depth and format of `references/example-review.md`.

For a high-stakes screen, run each pass as an independent focused review (one lens each) and merge —
each lens is sharper alone. Optionally add a skeptic pass that tries to refute findings to cut noise.

## 3. Inputs — ground truth, in priority order

1. **Figma via the MCP (best).** `get_metadata` + `get_design_context` for exact geometry;
   `get_variable_defs` for tokens; `get_screenshot` for the visual pass. Unlocks the measurable layer.
2. **The running app via the Mobile MCP.** Real rendering, real tap targets, real spacing on device.
3. **Source code.** Read the component to flag off-scale values and hardcoded tokens directly.
4. **A static screenshot (fallback).** Vision-only; assess hierarchy, balance, approximate contrast,
   composition. Say when a finding needs exact values to confirm. Before judging a detail, crop and
   enlarge that region (the browser tool's zoom, or an image crop); a dense area read from the whole
   screen misses what a crop shows, and the vendor's own guidance for this model says the same.
   When you capture, take viewport-sized frames down the page, never one tall full-page image the
   model will downscale until the detail is gone.
5. **A verbal description alone is not an input.** With no Figma node, no running app, no source and no
   screenshot, there is nothing to measure and nothing to observe, and a review does not happen. Do not
   score. Do not issue findings, chipped or not. Say what a description cannot support, ask for one of
   the four above, and if anything is offered in the meantime it is general guidance about the
   category, labeled as such, never a finding about this screen.

## 4. The dimensions

Full thresholds (exact numbers) live in `references/thresholds.md`. Run Group A first.

### Group A — Measurable rigor (compute, don't eyeball)
1. **Spacing, grid & rhythm** — on-scale is necessary, not sufficient: spacing must also *encode
   nesting depth*, each level out roughly 1.4x its child, or grouping collapses even with every
   value on-grid. Compute the ratio between adjacent depths. Every gap/pad on the scale (8pt grid, 4pt fine); consistent vertical
   rhythm; proximity groups related content. Run `python3 scripts/symmetry.py`.
2. **Symmetry, balance & alignment — WEIGHTED (highest signal).** Internal padding symmetry (L=R,
   T=B); paired/repeated components share identical padding; axial balance; edge & baseline alignment;
   optical over mathematical when they conflict; mirrored insets.
3. **Color & contrast (measurable)** — WCAG AA: 4.5:1 body, 3:1 large/non-text. Measure every pair with contrast.py
   (usage under Bundled resources); report ratio + color-blindness risk. Tokens not hardcoded; consistent across states.
   Color-system rigor: work in OKLCH; never pure `#000`/`#fff` (reduce chroma near the extremes); pick
   a color *strategy* first — Restrained / Committed / Full-palette / Drenched — and check the design
   executes one, not a random mix.
4. **Consistency & tokens** — one radius scale, one shadow/elevation scale; icons from one family at
   consistent style, weight and size (mixed libraries read as assembled, not designed);
   components reused not re-drawn; flag hardcoded values that should be tokens.

### Group B — Craft & composition (judgment; second opinion)
5. **Visual hierarchy** — size/weight/color used deliberately; squint test; exactly one primary action;
   Gestalt grouping.
6. **Typography** — modular scale; body line-height 1.4–1.6; line length 45–75ch; weight for hierarchy;
   micro-detail per `thresholds.md` (true ellipsis, curly quotes, non-breaking spaces in value-unit
   pairs, tabular figures in number columns, balanced heading wraps) — the fastest tell nobody swept;
   ≤2 families; tracking tuned by size; watch truncation & locale expansion.
7. **Color as composition** — ~60/30/10; intentional warm/cool grays; consistent semantic roles; dark
   mode is a systematic re-map, never a straight invert.
8. **Motion** — purposeful; ~150–300ms typical; easing matches intent; signature moments choreographed;
   honor `prefers-reduced-motion`. In a running page, replay it at 10% speed in the browser's
   Animations panel and step through every state; at full speed the flaws pass unseen. For deeper motion critique defer to the `motion-design` /
   `review-animations` skills; their laws (no layout-property animation; exponential ease-out, with Material exit curves
   excepted per `references/thresholds.md`; no bounce unless momentum-driven) apply here too.

### Group C — Usability & inclusion
9. **Heuristics & cognitive load** — Nielsen's 10; Fitts / Hick / Miller; Gestalt.
10. **Accessibility** — targets per modality (touch 48dp / pointer 44px / 24px floor), never per
    platform; visible focus; logical reading order; never color-only meaning; labels on controls;
    reduced motion & dynamic type. **Mark what you could not test.** From a screenshot or a Figma
    node you cannot verify keyboard operability, focus order, or screen-reader output — those are

From LarrySequino/skills, MIT.

More from LarrySequino/skills