83.3K+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

Designer's-eye QA of a live site. It opens pages in the user's own browser, screenshots them at 375, 768 and 1440, grades ten categories from visual hierarchy to interaction states, then edits source to fix what it found, one commit per fix, re-verifying with before and after screenshots.

Depth defaults to 5-8 pages; with no URL on a feature branch it goes diff-aware. Readers get two headline grades, a weighted Design Score and a standalone AI Slop Score, plus 30 named detector rules such as [kicker-above-heading] and [gradient-text] behind the judgment calls.

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

    Phase 4 walks 2-3 user flows, diffing the snapshot after each action and tracking a goodwill score for friction and repair.

  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.
  • When you mention visual inconsistencies or want to polish a live site, the skill should suggest itself.
  • Judging whether a shipped page reads as AI-generated, which most developers cannot assess on their own.
  • 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.
  • It will not touch your CI setup, and existing tests are off limits; only new regression test files may be created.

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 sessionThe audit works inside the session the user already has, so authenticated pages need no login flow.

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 audit never reads implementation files: findings must come from the rendered page. The one exception is writing DESIGN.md from extracted observations.

  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

    The loop escalates every five fixes and halts outright once the design-fix risk passes 20% or the fix count hits 30.

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

Generic skills CLI form for design-review/SKILL.md; the repository may document its own path.

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 [[email protected]] 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.
  • The report states the detector count as a start-to-finish delta, or says the detector was not installed or off.

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