frontend-design-review

Files (3)

• SKILL.md
• design-laws.md · references/
• scoped-bans.md · references/

SKILL.md (first lines)

# Frontend Design Review

Most AI-generated interfaces fail the same way: they compile, they look plausible
in code, and they render as the average of every landing page in the training
data. Dark blue for a developer tool. Purple gradient for a music app. Three
icon cards in a row. A tiny uppercase eyebrow above every section.

This skill replaces taste-by-vibes with thresholds. It gives Claude a design
contract to lock before writing CSS, numeric laws to satisfy while writing it, a
list of banned defaults with the specific replacement for each, and a
render-and-compare loop so nothing is called done from reading code. It works on
product UI, dashboards, marketing pages, component systems, and app store
assets.

**Core principle:** strip the logo and the surface must still be unmistakably
this product, and render the result before claiming it works.

## When to Use This Skill

- Building a new landing page, dashboard, app shell, or component family and you
  want it to look designed rather than defaulted.
- Reviewing an interface someone (or an agent) already built, and you need
  specific findings with file names, not "looks good."
- Auditing a design system for drift: inconsistent tokens, ad hoc spacing,
  five shades of the same gray, components that disagree with each other.
- Comparing a mock, Figma frame, screenshot, or reference URL against a built
  implementation and reporting the gaps by severity.
- Fixing a UI that feels generic and you cannot articulate why.
- Preparing high-visibility surfaces: launch pages, app store screenshots,
  investor demos, docs sites.

Skip it for backend-only work, or a one-line copy change with no visual
consequence.

## What This Skill Does

1. **Locks a design contract before implementation**: audience, surface job,
   primary action, register (brand vs. product), spacing scale, color roles,
   type roles, copy vocabulary, and acceptance checks. Ambiguity resolved up
   front instead of relitigated in review.
2. **Forces a committed aesthetic direction**: pick one of eight named tonal
   directions (refined minimal, editorial, brutalist, retro-technical, organic,
   maximalist, luxury refined, product-utilitarian) and execute it fully. The
   failure mode is not "too bold" or "too plain," it is uncommitted.
3. **Applies numeric design laws**: color strategy, dark-mode surface lightness
   and contrast floors, fluid type scale with `clamp()`, line measure, layout
   and z-index rules, component laws for forms, modals, tables, navigation, and
   empty states, plus motion curves and durations. See
   [references/design-laws.md](./references/design-laws.md).
4. **Rejects AI-slop defaults with named replacements**: gradient text,
   decorative glass panels, orb backgrounds, ghost cards, over-rounded corners,
   numbered section scaffolding, hero-metric templates, fake statistics. Each
   ban ships with a BEFORE and an AFTER and the narrow case where the exception
   is earned. See [references/scoped-bans.md](./references/scoped-bans.md).
5. **Renders and verifies**: captures desktop and mobile screenshots, compares
   source visual target to implementation in the same pass, and writes a
   `visual-qa-report.md` with findings ordered P0 to P3.
6. **Scores design systems out of 100** across ten dimensions and names the two
   weakest to fix first.
7. **Ends with a ship gate**: `ship`, `ship-with-caveats`, or `hold`, with the
   evidence that supports the verdict.

## How to Use

### Basic Usage

```
Review the design of the dashboard at http://localhost:3000/app and tell me
what is wrong with it. Render it at desktop and mobile before answering.
```

Claude inspects the source, renders the page, checks it against the design laws
and the banned-defaults list, and reports findings with file names and specific
fixes.

### Advanced Usage

```
Redesign our pricing page. Before writing code:
1. Write the design contract (audience, page job, primary action, register).
2. Name the aesthetic direction and the one memorable move, and explain why the
   obvious choice for this category is the wrong one.
3. Propose two approaches with tradeoffs and let me pick.
Then build it, render at 1280x900 and 390x844, and finish with a ship gate.
```

```
Compare ./designs/hero-mock.png against the implementation at
http://localhost:5173 and save visual-qa-report.md with P0-P3 findings.
```

```
Audit our design system in ./src/styles and score it out of 100 across color
consistency, typography hierarchy, spacing rhythm, component consistency,
responsive behavior, dark/light behavior, motion restraint, accessibility,
information density, and polish. Fix the two lowest dimensions.
```

## Example

**User**: "Our analytics dashboard looks like every other analytics dashboard.
Fix it."

**Output**:

```
DESIGN PREFLIGHT
target=./apps/web  surface=/dashboard  register=product
context=partial (no DESIGN.md)  render=pass (1280x900, 390x844)

DIAGNOSIS
The surface is the category average. Three findings explain most of it.

P0  Color is decorative, not semantic. src/styles/tokens.css:14
    Six blues, none of which encode meaning. Threshold breaches, healthy
    ranges, and stale data all render in the same accent.
    Fix: commit to Restrained strategy. Tinted neutrals plus one accent
    under 10% of surface area, reserved for threshold breaches only.

From JasonColapietro/suede-creator-skills, MIT.

More from JasonColapietro/suede-creator-skills