102.7K+Download
Skip to the usage guide
design-reviewby Garry Tan

Design Review Skill.

A Claude Code and Codex skill for design review: designer's-eye QA of a built page: inconsistency, spacing, hierarchy, slop patterns; then fixes them.

  • Design Review & Accessibility
  • Review report
Download OpenDesignView usage guide
garrytan/gstack · design-review/SKILL.mdSKILL.md
--- name: design-review description: Designer's eye QA: finds visual inconsistency, spacing issues, hierarchy problems, AI slop patterns, and slow interactions — then fixes them. (gstack) --- ## When to invoke this skill ## Confusion Protocol ## Claimed Limitations Need Evidence ## Continuous Checkpoint Mode ## Context Health (soft directive) ## Question Tuning (skip entirely if QUESTION_TUNING: false)
Front matter and section headings read from the upstream file on 2026-09-14 · 126,647 characters in full

01 What it does

What the design-review Skill Does in Claude Code and Codex

Summary, workflow and outputs, all read from the skill's SKILL.md.

From the SKILL.mdRead 2026-09-14 · not a recorded run

In the Skill's Own Terms

A rendered-page design audit with a source-fix loop. It uses Aside or gstack’s headless browser to inspect pages at 375, 768 and 1440 pixels, grades ten categories, then applies focused source changes with one commit per fix and before-and-after verification. It needs a clean working tree and a usable browser path.

Standard depth covers 5-8 pages; a feature branch without a URL selects diff-aware scope. Reports include a weighted Design Score and a separate AI Slop Score. These are rubric-based judgments, not measured user outcomes. The separate design detector runs only when available and enabled; its hits require rendered confirmation.

What it produces

  • A structured markdown audit report in the run directory.
  • A design-baseline.json file written for regression comparison on later runs.
  • Before and after screenshot pairs for every applied fix.
  • An optional DESIGN.md written from the extracted observations, if the user accepts the Phase 2 offer.
See the example prompt ↗

How It Works

  1. 01
    React Before You Analyze

    Phase 1 opens the target and takes a full-page desktop screenshot, then writes a structured first impression naming what the eye goes to first.

  2. 02
    Extract the Rendered System

    Phase 2 probes fonts, colors, heading scale and touch targets inside the page, then offers to save the findings as a DESIGN.md.

  3. 03
    Audit Page by Page

    Phase 3 runs a console hook, interactive snapshot and annotated screenshot per page, then repeats at three viewport widths.

  4. 04
    Feel the Flows

    Walk 2-3 user flows and inspect state changes, delays and recovery. The goodwill meter is an explicitly heuristic way to organize observations, not participant research or a measured satisfaction score.

  5. 05
    Fix One Finding at a Time

    Phase 8 makes the minimal change, commits it alone, and re-tests before moving to the next finding.

  6. 06
    Score Two Headlines

    The design score is a weighted average across ten categories, while the AI slop grade stands on its own.

02 Find your fit

When to Use the design-review Skill

Use the design-review skill in Claude Code or Codex when the job is design review of this kind. Fit and limits below are taken from the skill's own file.

Good Fit

  • A pre-launch or post-redesign audit where the whole site needs a systematic pass, not a spot check.
  • Working on a feature branch that changes UI, where only the touched routes should be audited.
  • Polishing observed visual inconsistencies in an existing site, with source changes and atomic commits included in the documented workflow.
  • Reviewing repeated template-like patterns against a design brief and DESIGN.md, without treating the skill’s taste rubric as proof of user preference.
  • A fast sanity pass when there is no time for the full sweep: homepage plus two key pages and an abbreviated checklist.

Know the Boundaries

  • Reviewing a design before it is built: that is a separate plan-mode skill.
  • Problems that live outside the source, such as third-party widgets or copy that has to come from the team, are marked deferred instead of fixed.
  • The design-specific rules prohibit CI edits and existing-test changes, but the general test-bootstrap section includes CI generation. Resolve that conflict before execution; do not assume a review authorizes new testing infrastructure.

What to Provide

  • The target URLA live address, localhost included. Without one the skill auto-detects or, on main, asks you.
  • A scope overrideNarrow the sweep to a single page or area when you do not want the full tour.
  • A depth flagDefault is standard; --quick trims to three pages and --deep expands to a full pre-launch sweep.
  • Your DESIGN.md if one existsRepo-root design docs are read first so every decision is calibrated against the stated system and departures grade harder.
  • An already signed-in browser sessionAside can reuse an existing authenticated session. The headless fallback starts without it and may need a user-controlled sign-in; the agent must not handle passwords or session secrets.

03 Inside the skill

Rules the design-review Skill Gives Claude Code and Codex

8 concrete instructions, defaults and limits the SKILL.md sets for the agent — the part of the file that changes the result.

  1. Judge the Render, Not the Repo

    The primary visual audit judges rendered pages. Later fix steps necessarily read source; diff-aware detector scans and independent source-review voices are also documented. Source findings do not replace screenshot evidence.

  2. One Commit per Fix

    Each fix is committed alone with the message format style(design): FINDING-NNN plus a short description.

  3. Clean Tree Before Starting

    A dirty working tree stops the run: the agent must ask whether to commit, stash or abort before any fix commit exists.

  4. Ask Before Acting on a Real Account

    On a non-local target, mutating actions need one consent question per run listing exactly what will be done; sign-out and delete paths are never followed.

  5. Credentials Stay Out of the Agent

    The pre-signed-in session is used as is. Passwords, one-time codes, payment details, cookies, tokens and localStorage are all off limits.

  6. Screenshots Back Every Finding

    A finding without at least one screenshot does not count, and images are copied out and read so the user sees them inline.

  7. Revert the Moment It Worsens

    Any regression triggers an immediate git revert HEAD and the finding is marked deferred rather than patched around.

  8. Stop at 30 Fixes

    Recalculate the source’s risk heuristic every five fixes or after a revert. Ask before continuing when it exceeds 20%, and stop at 30 fixes. These percentages are workflow thresholds, not measured regression probabilities.

04 Put it to work

Install design-review in Claude Code or Codex

One npx skills add command, then a first task in your agent and a checklist for the result.

Add design-review to Claude Code, Codex or Your Agent

Run in your project; the installer asks which agent to add it to.

Terminal
npx skills add https://github.com/garrytan/gstack --skill design-review

Use the full gstack setup and browser helpers, a source checkout and a clean working tree. Aside or the headless browser is required for rendered evidence; designer mockups and the separate detector are optional. Confirm the project’s test command and any setup changes.

Give the Skill a First Design Review Task

Written in the skill's own terms; replace the bracketed parts with your material.

Starter prompt
Audit the design of [https://myapp.com/dashboard] at standard depth. Focus on the settings page. I'm signed in as [me@example.com] in Aside. Flag the AI slop patterns and anything that breaks the spacing scale, then fix what you can.

Source: written from the SKILL.md in the skill's own terms.

Check the First Result

What the SKILL.md itself says a correct result looks like:

  • Re-test the affected page after each fix and confirm the console error list is empty or no worse than the baseline.
  • When a target mockup was generated, compare the fixed screenshot against it and record pass or fail.
  • Every fix gets classified: verified when re-testing confirms it with no new errors.
  • Phase 9 re-audits the affected pages and warns loudly if the final grades landed below the baseline.
  • Report detector counts only when it actually ran. Cross-run deltas require matching scan mode and target set; disclose unavailable tooling or incompatible baselines.

In OpenDesign design-review is bundled: Plugins → Skills, pick it in the top bar.

Download OpenDesignRead the quickstart

05 Open source, traceable

Source, License and Verification

Where this page's facts come from, and when they were last checked.

Author
Garry Tan
Repository
github.com/garrytan/gstack Branch main
Skill file
design-review/SKILL.md Content checksum recorded at verification; commit 71f6048
License
MIT From LICENSE.
Repository stars
132,921 GitHub snapshot taken 2026-09-14 for the whole garrytan/gstack repository, which contains 7 skills in this catalog. Not a rating or usage count for design-review.
Verified by OpenDesign
2026-09-14 Source file, path, license text and star count were checked. Bundled in OpenDesign main (checked 2026-08-28); a live run has not been recorded on this page.

Inside the SKILL.md

  1. SetupParses URL, scope, depth and auth; checks DESIGN.md, clean tree, browser, tests.
  2. ModesFull, quick, deep, diff-aware and regression scopes decide which pages get visited.
  3. Phase 1: First ImpressionFull-page desktop screenshot, then a structured gut reaction and page-area test.
  4. Phase 2: Design System ExtractionProbes fonts, colors, heading scale and touch targets, then offers to save a DESIGN.md.
  5. Phase 3: Page-by-Page Visual AuditSnapshots, annotated and responsive shots, trunk test, then a 10-category checklist.
  6. Phase 4: Interaction Flow ReviewWalks 2-3 flows, diffs each step, and scores a goodwill meter from 70.
  7. Phase 5: Cross-Page ConsistencyCompares nav, footer, components, tone and spacing rhythm across pages.
  8. Phase 6: Compile ReportGrades each category A-F and writes the report plus design-baseline.json.
  9. Phase 7: TriageSorts findings by impact and defers what source edits cannot fix.
  10. Phase 8: Fix LoopLocates source, makes the minimal fix, commits, re-tests, classifies, self-regulates.
  11. Phase 9: Final Design AuditRe-audits affected pages, recomputes scores and detector counts, warns on regressions.
  12. Phase 10: ReportWrites the full report, project index summary, PR line and detector delta.
The Skill's Own Description
“Designer's eye QA: finds visual inconsistency, spacing issues, hierarchy problems, AI slop patterns, and slow interactions — then fixes them. (gstack)”

Front-matter description from SKILL.md. The full file is about 126,647 characters. Read the full file on GitHub.

Design Review

Run design-review on a Real Design Review Task.

The design-review skill ships inside OpenDesign. Download the app, pick the skill in Plugins → Skills, paste the prompt above, and read the plan before the result.

Download OpenDesignBrowse all skills
Terminal
npx skills add https://github.com/garrytan/gstack --skill design-review