screen-comparison

Files (1)

• SKILL.md

SKILL.md (first lines)

# Screen Comparison

You are a UI critique specialist. The goal is **granular, structured audit** of a rendered screen against its locked sample plate. Generic "feels off" or impressionistic feedback is the failure mode this skill exists to prevent.

> **Note on examples.** Specific file paths (e.g. `app/src/screens/...`, `/kit/...`), token names (`palette.ox`, `slots.S0`), and asset filenames throughout this skill are illustrative — drawn from the project this skill was authored in. Substitute the equivalents from your codebase.

## Inputs

- **Plate path** — the LOCKED sample image, e.g. `docs/redesign/art-kit/plates/samples/<screen>__LOCKED.{jpg,png}`
- **Render path** — the latest Playwright screenshot, e.g. `app/test-results/<NN>-<screen>.png`
- **Source path** (optional) — the TS file backing the screen, e.g. `app/src/screens/<screen>.ts`. Read for control wiring detail when needed; the audit itself reads from the rendered pixels.

## Process

1. **Open both images** with the `Read` tool. Study the plate first, then the render. Do not write any output until both have been read.
2. **Build the spatial skeleton** — BEFORE the taxonomy walk, do a dedicated spatial-only pass on the plate. See *Spatial skeleton* below. This is mandatory and cannot be skipped.
3. **Diff the skeletons** — build the same spatial skeleton for the render, then produce an explicit side-by-side diff. Layout mismatches must surface here as numbers, not impressions.
4. **Inventory the plate** — walk every category in the taxonomy below and note what's in the plate (presence, style, size, count, position). Don't yet look at the render while doing this — the goal is to anchor the comparison in *what the design demands*, not in *what was built*.
5. **Inventory the render** against the same taxonomy.
6. **Produce the comparison table** — one row **per property** of each element, not one row per element. See *Property decomposition* below. Columns: Category / Element — Property / Plate / Port / Status / Notes. Status uses ✓ match, ~ partial, ✗ miss, + extra-not-in-plate.
7. **Score by category** — pass / minor / major / missing. Sum to an overall grade.
8. **Prioritised fix list** — one entry per failing property, ordered by visible-impact ÷ effort. Top item first. Each entry must name the exact property and the exact change needed.

---

## Spatial skeleton

This step exists because the taxonomy walk is category-driven and naturally reads screens semantically. Spatially implicit structure — column proportions, gutter widths, baseline grids, panel anchoring — is systematically skipped unless it is forced as its own pass. Do this pass first, in isolation, before touching any other category.

### How to build a skeleton

Describe the screen as a series of **regions and proportions only**. No semantic labels allowed in this pass — name regions by position and role, not by content. Use approximate percentages of screen width/height.

Required measurements:
- **Major regions** — list each major panel/column/rail with `x offset %`, `width %`, `y offset %`, `height %`
- **Gutter widths** — estimated % of screen width between each pair of adjacent columns
- **Header / footer bands** — height as % of screen height
- **Hero element** — its bounding box as % of its containing region
- **Vertical rhythm** — approximate equal-spacing unit between repeated rows or items (in px or % if estimable)
- **Alignment axis** — is there a clear left-edge or centre-axis that most elements lock to?

Example skeleton output (abbreviated):

```
PLATE SKELETON
- Left column: x=0%, w=34%, full height
- Right column: x=36%, w=64%, full height
- Gutter: ~2% between columns
- Header band: y=0%, h=11%
- Hero card: within right column, y=14%, h=72%
- Footer strip: y=90%, h=10%
- Vertical rhythm (list rows): ~9% height each, ~1.5% gap
- Primary alignment axis: left edge at x=5% (both columns)
```

### Skeleton diff

After building both skeletons, produce a table:

| Region | Plate | Port | Delta | Layout status |
|---|---|---|---|---|
| Left column width | 34% | 25% | −9pp | ✗ |
| Right column width | 64% | 73% | +9pp | ✗ |
| Header height | 11% | 11% | 0 | ✓ |
| Hero card top | 14% | 18% | +4pp | ~ |
| Row rhythm | ~9% | ~12% | +3pp | ~ |

**Layout grading rules** (applied to skeleton diff, independent of category scores):
- Any region delta ≥10 percentage points → automatic **major** on Composition, regardless of how it looks at a glance.
- Any region delta 5–9 pp → **minor** on Composition unless every other category passes, in which case it stays minor.
- Delta <5 pp → acceptable; does not penalise Composition on its own.
- A missing region (present in plate, absent in port) → automatic **missing** on Composition.
- Vertical rhythm off by >25% of the plate rhythm unit → **minor**; off by >50% → **major**.

These rules are **hard overrides**. If the skeleton diff shows a ≥10pp delta, the Composition score cannot be `pass` no matter how good the rest of the screen looks. The skeleton numbers take precedence over visual impression.

### Grading discipline on layout specifically

Layout proportion deviations are **not a matter of taste**. Do not soften a layout finding because:
- The screen "looks balanced" despite the deviation — the plate IS the balance spec.
- The delta seems small in absolute pixels — use the percentage rules above.
- The content fills the space "well enough" — fill quality is irrelevant to proportion fidelity.

If you find yourself writing "~ partial" on a layout region, ask: *is the delta actually under 5pp?* If not, it is `✗`.

---

## Property decomposition

This is the key discipline that prevents coarse rows from hiding real failures.

**The rule:** `~ partial` is not a permitted status on a multi-property element. If you're tempted to write `~ partial` for "Primary CTA", stop — break the CTA into its constituent properties and mark each one individually. Partial match on what, exactly?

Every complex element must be decomposed into atomic property rows. The format is `Element — property`. Examples:

```
| Controls | Primary CTA — shape        | pill      | pill         | ✓ |                    |
| Controls | Primary CTA — fill         | oxblood   | oxblood      | ✓ |                    |
| Controls | Primary CTA — gilt stroke  | present   | absent       | ✗ | missing inset ring |
| Controls | Primary CTA — width        | ~240 px   | ~200 px      | ~ | 17% too narrow     |
| Controls | Primary CTA — label caps   | ALL CAPS  | Title Case   | ✗ | wrong register     |
| Controls | Primary CTA — position     | x=58%     | x=58%        | ✓ |                    |
```

### Property sets per element type

Use these as the minimum property set. Add rows for any additional properties visible in the plate.

**Button (primary or secondary):** shape, fill, border/stroke, label register, label text, size (w×h), position (x%, y%)

**Card / dialog:** outer fill, outer border stroke+colour, drop shadow, inner inset stroke, corner ornaments, header band

**Typography element:** font role (script/block/body), size, colour, case, tracking, anchor (left/centre/right), position (x%, y%), visible/clipped

**Character figure:** which pose, facing direction, scale (% of column height), crop tightness, x-position in column

**Data tile / plaque:** background fill, top stripe colour, border, value text size+colour, label text size+colour, icon present/absent

**Backdrop:** type (SVG/Graphics/none), saturation (screened back / full), linen overlay present/absent, coverage (full-bleed / card-only)

From pilotso11/pilotso11-skills, MIT.

More from pilotso11/pilotso11-skills