agentleFS
DrBradStanfieldDrBradStanfield/roadmap/.claude/skills/design-review/SKILL.md

design-review

Skill11 starsChanged 6 days agoMITView on GitHub

A fresh-eye design review of a UI change from screenshots, ranked and fixed before Brad sees it. Use after any visible UI change, on the web widget or the iPhone app, before showing Brad or deploying, and when asked to "make it beautiful", "check the design" or "does this look right". Phone widths first. Adapted from Benji Taylor's Stageshow skill (MIT).

167 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use team-level, team-audio and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • CoralGameSkill

    team-level

    Orchestrate level design team: level-designer + narrative-director + world-builder + art-director + systems-designer + qa-tester for complete area/level creation.

    Also in 13 projects that use this

  • CoralGameSkill

    team-audio

    Orchestrate audio team: audio-director + sound-designer + technical-artist + gameplay-programmer for full audio pipeline from direction to implementation.

    Also in 14 projects that use this

  • lilangMaxSkill

    asset-spec

    Generate per-asset visual specifications and AI generation prompts from GDDs, level docs, or character profiles. Produces structured spec files and updates the master asset manifest. Run after art bible and GDD/level design are approved, before production begins.

    Also in 11 projects that use this

  • lilangMaxSkill

    create-control-manifest

    After architecture is complete, produces a flat actionable rules sheet for programmers — what you must do, what you must never do, per system and per layer. Extracted from all Accepted ADRs, technical preferences, and engine reference docs. More immediately actionable than ADRs (which explain why).

    Also in 11 projects that use this

  • julianoczkowskiSkill

    brief-to-tasks

    Break a design brief into an ordered checklist of independently buildable tasks using vertical slices. Saves as a markdown checklist. Use when user wants to break down work, create tasks from a brief, plan implementation order, or mentions "tasks" or "breakdown".

    Also in 7 projects that use this

  • +4 more from lilangMax
  • +3 more from CoralGame

The file

We split this skill into the rules it gives an agent

8 rules. 0 are common, 8 are distinctive, and 0 are very specific to this project.

  • 0

    Common

    Most of the 139 edited versions we read keep these.

  • 8

    Distinctive

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    After a UI change on the web widget or the iPhone app, before Brad sees it.

    line 17
  2. Distinctive:

    Not for copy-only or clinical text changes.

    line 19
  3. Distinctive:

    Use a throwaway demo record.

    line 29
  4. Distinctive:

    Look the way an exacting designer would: find the one thing you'd screenshot and send back with "what is this?".

    line 42
  5. Distinctive:

    Don't soften a finding because the build is nearly there.

    line 46
  6. Distinctive:

    No empty bands, no voids under a list, no content stopping short of its panel.

    line 62
  7. Distinctive:

    No near-tangents: edges 1 to 3px apart look accidental.

    line 78
  8. Distinctive:

    No redundant borders: try the fill alone first.

    line 90

“Common” is measured: kept by at least 6 in 10 of the 139 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Design review

Tests prove a screen works. This review asks whether it looks right: calm, clear, the iPhone app's sibling. Brad wants the product beautiful on a phone first.

Adapted from the review and craft rules in Benji Taylor's Stageshow skill (github.com/benjitaylor/skills, MIT, 2026). We kept what applies to a real product and dropped the faux-UI parts (filler bars, cursors, framing a still).

When

  • After a UI change on the web widget or the iPhone app, before Brad sees it.
  • Again on the live page after a deploy (theme CSS only reproduces live).
  • Not for copy-only or clinical text changes.

How

  1. Shoot. Real screenshots, never a guess from code.
    • Web: the Shopify-like localhost (npm run dev:shopify, port 5174) or the live page, in real WebKit (tools/webkit-verify.mjs) at 375 and 390 wide, and desktop at 1440 and 1200. Every state: empty, onboarding, a full record with an urgent card, each section, settings, every sheet or form.
    • iPhone: simulator screenshots (light, dark, the largest Dynamic Type).
    • Use a throwaway demo record. Never Brad's phone, never real data.
  2. Review with fresh eyes. Spawn a fresh adversary. Give it this file, the screenshot paths and a one-line brief. Not the builder's plan or reasons. It reads every image and returns the ranked list below. It edits nothing.
  3. Fix the findings, worst first, then shoot again.
  4. Show Brad the screenshots that matter, with what changed.

Round cap as for every review (docs/review-format.md): one full review and one fix-scoped re-check. Then Brad.

The reviewer's rules

  • Judge the picture, from screenshots. Every finding names the screenshot.
  • Look the way an exacting designer would: find the one thing you'd screenshot and send back with "what is this?". Then the next.
  • Rank by how much of the screen it spoils, not how easy it is to fix: layout and hierarchy first, then density and spacing, then polish.
  • Don't soften a finding because the build is nearly there. Say what you could not check.
  • First question: does this look like one calm product, the iPhone app's sibling, or a generic dashboard? A layout nobody shaped is a finding.
  • A full-page capture shows fixed bars mid-page. That is the capture, not a finding.

Checklist

Hierarchy and restraint

  • The eye lands first on what matters: the section title, the value, an urgent card. Not on chrome, borders or labels.
  • One number is big per row; the rest are quiet.
  • Say it once: no feature or finding signalled in three places.
  • Hierarchy comes from space, size and one weight step, not more boxes and borders. A stack of identical bordered cards is flat.
  • No empty bands, no voids under a list, no content stopping short of its panel.
  • A control row (sign in, settings) never takes a row of its own on a phone when it can sit on the title line.

Type

  • One family (the theme's or the system's). Sentence case.
  • Phone text 13 to 17px; small text line height at least 1.3.
  • A title over its subtitle reads as one item: 4 to 6px apart; the air comes from the row's padding.

Spacing and alignment

  • Words keep at least 12px from a card edge (under 8px is a fault).
  • Row padding about 12px; a one-line row three times taller than its words is fat.
  • Text never touches a neighbour: a fixed 8 to 12px gap.
  • Nested shapes pad evenly; outer radius = inner radius + padding.
  • Columns line up across rows: fixed tracks; values right-aligned on one edge.
  • No near-tangents: edges 1 to 3px apart look accidental. Align them or part them by 8px or more.
  • Dots, badges and focus rings sit inside the content edge.
  • A title sits closer to its own content than to the next section.
  • A control hugs its content. A label beside an icon or in a pill is centred on its letters.

Icons and colour

  • One icon set, one size, one stroke weight. No hand-drawn glyphs, no emoji as icons.
  • A few inks and one accent (the teal). Red and amber mean status and nothing else.
  • No redundant borders: try the fill alone first.
  • Quiet is not faint: text and controls pass contrast (4.5:1) on the real ground.
  • An urgent card is lifted the way the product lifts things, not ringed in a glow.
  • A filled button keeps its colour on hover. Nothing translucent overlaps.

Phone

  • A fresh load at 375 and 390, and a resize between.
  • Tap targets 44px or more. No sideways scroll. Nothing under a fixed bar.
  • A phone layout is its own design, not the desktop squeezed.

The report

A ranked list. Each item: the screenshot, what is wrong, the fix in one line. Then the top three changes for the phone and the top three for desktop. If nothing: say "nothing" and list the screenshots looked at.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.