Agent skill

Design Review

by pproenca in pproenca/dot-skills

Structured UI design review — existing code (React/JSX, CSS, Tailwind) and, when behaviour matters, the running app in a real browser — reported as a prioritised Before / After / Why table.

MITAuto-check passedFrontend & Design

Install Design Review

skills CLI
$ npx skills add pproenca/dot-skills --skill design-review -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install pproenca/dot-skills design-review --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/pproenca/dot-skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/.curated/design-review .claude/skills/design-review && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
design-review
GitHub stars
215
Token cost
~3.4k tokens
SKILL.md length
1,350 words
Files
47 (incl. references, assets)
Skills in repo
41
Repo updated
First seen
Licence
MIT

At a glance

Structured UI design review — existing code (React/JSX, CSS, Tailwind) and, when behaviour matters, the running app in a real browser — reported as a prioritised Before / After / Why table.

  • Works in 10 steps: Visual Hierarchy (hier-) → Spacing & Layout (space-) → Typography (type-) → …
  • The user asks to review this UI
  • SKILL.md covers When to Apply, How to Run the Review, Output Format (Required) and Rule Categories, plus 4 more sections
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Design Review is an agent skill from pproenca/dot-skills. Structured UI design review — existing code (React/JSX, CSS, Tailwind) and, when behaviour matters, the running app in a real browser — reported as a prioritised Before / After / Why table. Covers visual hierarchy, spacing, typography, colour & contrast, component states, motion, responsiveness, accessibility, multi-page flow & navigation, and interaction continuity — grounded in Refactoring UI and Emil Kowalski's principles. For animation/jank/FPS, focus order, and cross-page UX it can drive Chrome via…

Its SKILL.md is about 3.4k tokens, which your agent loads only when the skill is triggered. The skill folder holds 49 other files, including reference files and assets (for example `AGENTS.md`, `assets/templates/_template.md` and `metadata.json`).

It sits in Frontend & Design, covering UI design, Design review and critique and CSS and styling. It works with Tailwind CSS, Model Context Protocol, Chrome DevTools and React. The repository describes itself as: A collection of AI agent skills following the Agent Skills open format. The licence is MIT.

When your agent uses it

  • The user asks to review this UI
  • Critique this component/screen/page
  • Multi-page flow
  • Asks why something looks off

Example prompts

  • “t. Trigger when the user asks to”
  • “design review”
  • “critique this component/screen/page or multi-page flow”
  • “/design-review”

Workflow steps

10 steps, taken from the step headings in SKILL.md.

  1. Visual Hierarchy (hier-)
  2. Spacing & Layout (space-)
  3. Typography (type-)
  4. Colour & Contrast (color-)
  5. Component States & Feedback (state-)
  6. Motion & Animation (motion-)
  7. Responsiveness & Touch (resp-)
  8. Accessibility & Semantics (access-)
  9. Flow & Navigation (flow-)
  10. Interaction Continuity (interact-)

What it can do on your machine

Read from SKILL.md and the folder at commit cf93c57. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md.

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Design Review loads about 3.4k tokens when it runs, and up to ~15k if it reads all its reference files. Until then it costs about 229 tokens; SKILL.md has 1,350 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~229
When it runs · the whole SKILL.md, loaded when a task matches
~3.4k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~15k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from pproenca/dot-skills at commit cf93c57, republished under its MIT licence (© pproenca). 1,350 words, ~3,433 tokens.

Download SKILL.mdSave it as .claude/skills/design-review/SKILL.md (or your agent's skills folder). This skill also uses 46 other files; get the full folder from GitHub.
name
design-review
description
Structured UI design review — existing code (React/JSX, CSS, Tailwind) and, when behaviour matters, the running app in a real browser — reported as a prioritised Before / After / Why table. Covers visual hierarchy, spacing, typography, colour & contrast, component states, motion, responsiveness, accessibility, multi-page flow & navigation, and interaction continuity — grounded in Refactoring UI and Emil Kowalski's principles. For animation/jank/FPS, focus order, and cross-page UX it can drive Chrome via chrome-devtools-mcp to capture what a screenshot can't. Trigger when the user asks to "review this UI", "design review", "critique this component/screen/page or multi-page flow", asks why something "looks off", "looks AI-generated", or "looks like a wireframe", or wants to raise visual polish. For building UI from scratch use web-taste; for the full animation set see emilkowal-animations.

Design Review

Conduct a design review of UI code and return a prioritised critique. The reviewer's lens is Emil Kowalski's design-engineering philosophy — taste is the differentiator; the unseen details compound; show the eye where to look — made concrete with the heuristics from Refactoring UI, WCAG, and MDN.

This is a read-only review skill: it diagnoses and proposes fixes; it does not rewrite the codebase. Each finding names the wrong default the code fell into, the exact fix, and why it matters.

When to Apply

  • The user asks to "review this UI", run a "design review", or "critique" a component, screen, or page.
  • The user says the output "looks off", "looks AI-generated", "looks like a wireframe", or "feels generic", and wants to know why.
  • A PR touches CSS/JSX/Tailwind and the user wants design feedback before merge.
  • The user wants to raise the visual polish or accessibility of an existing interface.

Not for building UI from scratch (use web-taste) or for the exhaustive animation rule set (use emilkowal-animations).

How to Run the Review

Two modes. A static review reads the code and is the default. A runtime review additionally drives a real browser to measure what the code can't show — animation timing and dropped frames, layout shift, the live focus order and accessibility tree, and the multi-page flow clicked through end to end. Switch to runtime whenever the verdict turns on rendered behaviour (the motion-, interact-, and flow- categories), per runtime-capture.md.

  1. Orient — the 0.5-second test. Before reading line by line, picture the rendered screen. Where does the eye land first? Is there a single focal point, or does everything carry equal weight? This frames which categories matter most for this UI.
  2. Pass the categories in priority order (table below). For each decision the code makes, read the matching reference file and check the code against it. Visual hierarchy and spacing are where the largest, most frequent problems live — start there.
  3. For multi-page or interaction-driven UX, walk it in a browser. When the brief is a flow ("review this onboarding") or the issue is felt in motion (jank, blank route flashes, lost focus), capture runtime evidence per runtime-capture.md so the Before column is a measured value, not a guess.
  4. Record each problem as a finding with a Before (the exact code or measurement), an After (the concrete fix), a Why (the principle), and a context-assigned Severity.
  5. Close with a verdict: the top 3 fixes, ranked by impact, so the author knows what to change first.

Output Format (Required)

Report findings as a single markdown table, one row per issue. Do not write findings as prose or as Before: / After: on separate lines.

SeverityBeforeAfterWhy
Hightransition: all 300ms ease-intransition: opacity 180ms cubic-bezier(0.23, 1, 0.32, 1)ease-in feels sluggish on entry; name the property and use a strong ease-out curve
Highevery button bg-indigo-600one filled primary; others ghost/outlineEqual-weight buttons compete; one primary makes the next step obvious
Mediumcolor: #000 on #fffcolor: hsl(222 47% 11%)Pure black is harsher than ink and reads as stark
Critical<div onClick={remove}><button type="button" onClick={remove}>A div is unreachable by keyboard and invisible to screen readers

Wrong format — never do this:

text
Before: transition: all 300ms
After: transition: opacity 180ms ease-out
────────────────────────────
Before: color #000
After: color slate-900

Severity guide (assigned per finding, by impact in this UI):

SeverityMeaning
CriticalBreaks usability or accessibility — fails contrast, no keyboard access, unreadable text
HighClearly damages the design — no hierarchy, cramped spacing, competing primary actions
MediumNoticeable polish gap — default easing, uniform line-height, missing press feedback
LowMinor refinement — a value slightly off the scale

Finish with: Top 3 fixes — the highest-impact rows, in the order the author should tackle them.

Rule Categories

#CategoryPrefixCovers
1Visual Hierarchyhier-Focal point, emphasis technique, one primary action, value-over-label, space over borders
2Spacing & Layoutspace-Spacing scale, generous whitespace, proximity grouping, constrained width
3Typographytype-Type scale, line length, line-height, alignment, readable body text
4Colour & Contrastcolor-Near-black text, WCAG contrast, HSL ramps, restrained accents, colour-plus-cue
5Component States & Feedbackstate-Press feedback, focus-visible, the full state matrix, empty states
6Motion & Animationmotion-Purpose/frequency, ease-out curves, sub-300ms, enter origin/scale, transform-only
7Responsiveness & Touchresp-Fluid mobile-first, 44px targets, gating hover
8Accessibility & Semanticsaccess-Semantic elements, accessible names, reduced-motion
9Flow & Navigationflow-App-shell consistency, view-state persistence, entry-point integrity, wayfinding
10Interaction Continuityinteract-Bridging route transitions, async feedback, focus on navigation

Quick Reference

1. Visual Hierarchy (hier-)
2. Spacing & Layout (space-)
Show full SKILL.md (538 more words)Show less
3. Typography (type-)
4. Colour & Contrast (color-)
5. Component States & Feedback (state-)
6. Motion & Animation (motion-)

For drag, gestures, springs, stagger, clip-path, and the full timing/easing tables, defer to the emilkowal-animations skill.

7. Responsiveness & Touch (resp-)
8. Accessibility & Semantics (access-)
9. Flow & Navigation (flow-)

Reviews the experience across pages, which single-screen review can't see. Walk the flow in a browser (runtime-capture.md).

10. Interaction Continuity (interact-)

Reviews whether the experience stays continuous over time and across transitions — the dimension a screenshot can't show. Best judged against a captured trace (runtime-capture.md).

How to Use

Read a reference file when its decision comes up in the code under review. Each rule names the wrong default it corrects, then shows the canonical fix (with an Incorrect/Correct contrast only where the wrong way is a real trap). Cite the rule slug in the "Why" column so the author can follow up.

  • Runtime capture — drive a real browser (chrome-devtools-mcp) to measure motion, jank, focus order, and multi-page flow when a static read isn't enough
  • Section definitions — category structure and order
  • Rule template — for adding new rules
  • AGENTS.md — auto-built table of contents across all rules
  • emilkowal-animations — the exhaustive animation rule set (easing, gestures, springs, stagger); this skill defers motion depth to it.
  • web-taste — building React/Next/Tailwind UI with taste from the ground up (the build counterpart to this review).
  • tailwind-ui-refactor — applying these fixes as Tailwind refactors.
  • ui-design — broader build-time frontend reference (Core Web Vitals, forms, dark mode). Where the two overlap (semantics, contrast, focus, single primary action), reach for ui-design while authoring and design-review while reviewing.

Reference Files

FileDescription
references/_runtime-capture.mdBrowser-driven capture playbook (chrome-devtools-mcp via mcporter)
references/_sections.mdCategory definitions and ordering
assets/templates/_template.mdTemplate for new rules
metadata.jsonVersion and source references

© pproenca, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 46 other files (references, assets) in skills/.curated/design-review of pproenca/dot-skills.

  • SKILL.md
  • AGENTS.md
  • assets/templates/_template.md
  • metadata.json
  • references/_runtime-capture.md
  • references/_sections.md
  • references/access-name-icon-controls.md
  • references/access-respect-reduced-motion.md
  • references/access-semantic-elements.md
  • references/color-avoid-pure-black.md
  • references/color-hsl-scales.md
  • references/color-limit-accents.md
  • references/color-meet-contrast.md
  • references/color-not-only-signal.md
  • references/flow-consistent-shell.md
  • references/flow-entry-point-integrity.md
  • references/flow-preserve-state-on-nav.md
  • references/flow-wayfinding.md
  • … and 29 more

Open the folder on GitHubat commit cf93c57

Compare with similar skills

Design Review next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Design Review compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Design Review this skillpproenca/dot-skills215—~3.4kAutomated safety check: PassMIT
UI UX Pro MaxOhh-889/skyroc79527 repos~3.6kAutomated safety check: NotesMIT
UI UX Pro Maxsaoudi-h/solar-icons18418 repos~11kAutomated safety check: NotesCustom licence
UI/UX Design System AdvisorGalaxy-Dawn/claude-scholar5.7k1 repos~1.1kAutomated safety check: PassMIT
Agentos UI UXSapienXai/AgentOS118—~4.4kAutomated safety check: PassMIT
UI UX Pro Maxshobcoder/shob577—~3.7kAutomated safety check: PassMIT

Similar skills

  • UI UX Pro Max

    Ohh-889/skyroc

    UI/UX design intelligence. An agent skill from Ohh-889/skyroc.

    795 GitHub starsUsed in 27 repos~3.6k tokens
    Frontend & DesignAuto-check: notes
  • UI UX Pro Max

    saoudi-h/solar-icons

    UI/UX design intelligence for web and mobile. An agent skill from saoudi-h/solar-icons.

    184 GitHub starsUsed in 18 repos~11k tokens
    Frontend & DesignAuto-check: notes
  • UI/UX Design System Advisor

    Galaxy-Dawn/claude-scholar

    Turns a vague UI request into a concrete design system with style, palette, typography and layout guidance from a search script, plus stack-specific implementation advice.

    5.7k GitHub starsUsed in 1 repo~1.1k tokens
    Frontend & DesignAuto-check passed
  • Agentos UI UX

    SapienXai/AgentOS

    Design, review, or implement AgentOS UI and UX work using the project’s operator-console visual system.

    118 GitHub stars~4.4k tokensUpdated 5 days ago
    Frontend & DesignAuto-check passed
  • UI UX Pro Max

    shobcoder/shob

    UI/UX design intelligence expert for web and mobile applications.

    577 GitHub stars~3.7k tokensUpdated 20 days ago
    Frontend & DesignAuto-check passed
  • Shift UI Components

    shift-editor/shift

    Guides design, implementation and review of Shift interface work: shared Base UI wrappers, Tailwind v4 theme tokens, Figma matching and accessible interaction states.

    347 GitHub stars~2.5k tokensUpdated yesterday
    Frontend & DesignAuto-check passed

More from pproenca/dot-skills

All 41 skills in this repo
  • Audio Voice Recovery

    pproenca/dot-skills

    Audio forensics and voice recovery guidelines for CSI-level audio analysis.

    215 GitHub stars~3.3k tokensUpdated 1 mo ago
    Auto-check passed
  • Codemod React Pipeline

    pproenca/dot-skills

    Guided, scripted pipeline for running JSX/TSX/React codemods safely across large legacy codebases.

    215 GitHub stars~1.6k tokensUpdated 1 mo ago
    Auto-check passed
  • Dev Rfc

    pproenca/dot-skills

    Create well-structured RFCs and technical proposals for software projects.

    215 GitHub stars~3.8k tokensUpdated 1 mo ago
    Auto-check passed
  • Dx Harness

    pproenca/dot-skills

    Developer-experience friction auditing and fixing — slow onboarding, repeated manual setup steps, missing bootstrap/reset/seed scripts, undiscoverable conventions.

    215 GitHub stars~1.5k tokensUpdated 1 mo ago
    Auto-check passed
  • Language Spec Author

    pproenca/dot-skills

    Turn a rough idea for a language into a complete, implementable specification — a DSL, query, config/data, template, or protocol language — by interviewing the author dimension by dimension until…

    215 GitHub stars~2.4k tokensUpdated 1 mo ago
    Auto-check passed
  • Python Pep Author

    pproenca/dot-skills

    Drafting Python Enhancement Proposals (PEPs) — proposing a Python language feature, a standard library change, an interoperability standard, or an informational/process document for the Python…

    215 GitHub stars~2.1k tokensUpdated 1 mo ago
    Auto-check passed

Questions about Design Review

What does Design Review do?

Structured UI design review — existing code (React/JSX, CSS, Tailwind) and, when behaviour matters, the running app in a real browser — reported as a prioritised Before / After / Why table. Design Review is an agent skill from pproenca/dot-skills. Structured UI design review — existing code (React/JSX, CSS, Tailwind) and, when behaviour matters, the running app in a real browser — reported as a prioritised Before / After / Why table.

When should I use Design Review?

Design Review fits situations like: the user asks to review this UI; critique this component/screen/page; multi-page flow; asks why something looks off.

How do I install Design Review in Claude Code?

Run `npx skills add pproenca/dot-skills --skill design-review -a claude-code`. Or copy the skill folder (skills/.curated/design-review in pproenca/dot-skills) into .claude/skills/design-review in your project. Claude Code loads it when a task matches its description.

How do I install Design Review in Codex?

Run `npx skills add pproenca/dot-skills --skill design-review -a codex`. Or copy the skill folder (skills/.curated/design-review in pproenca/dot-skills) into .agents/skills/design-review in your project. Codex loads it when a task matches its description.

Can I use Design Review in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add pproenca/dot-skills --skill design-review -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/design-review, .gemini/skills/design-review, .github/skills/design-review and .opencode/skills/design-review in your project.

What does Design Review need to run?

SKILL.md names no scripts, command-line tools or credentials: Design Review is instructions for the agent only.

Does Design Review access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Design Review safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Design Review use?

Design Review is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Design Review use?

About 3.4k tokens (SKILL.md is roughly 14k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 11k tokens, read only when the agent opens those files.

What are the alternatives to Design Review?

Skills that share tags, products or a category with Design Review: UI UX Pro Max (Ohh-889/skyroc, 795 stars), UI UX Pro Max (saoudi-h/solar-icons, 184 stars), UI/UX Design System Advisor (Galaxy-Dawn/claude-scholar, 5.7k stars) and Agentos UI UX (SapienXai/AgentOS, 118 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Design Review?

pproenca (a GitHub user) maintains it in pproenca/dot-skills, which has 215 GitHub stars. The repository holds 41 skills in this directory. The repository was last updated on August 15, 2026.

Source: pproenca/dot-skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.