alirezarezvani/claude-skills / product-team/skills/design-qa
design-qa
VerifiedUse when a UI screen, page or component is about to be called done, handed off or shipped, or when generated UI looks generic or half-finished. Gates the rendered result, not the design file - finds controls that do nothing, placeholder copy, removed focus rings, missing loading/empty/error states, low contrast, small targets, hidden focus and broken reflow measured in the real browser, and flags template defaults without blocking on taste.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.5 KB |
| assets/capture_snapshot.mjs | script | 3.4 KB |
| assets/collect_snapshot.js | script | 9.6 KB |
| assets/finish_signoff.md | markdown | 1.8 KB |
| assets/snapshot.example.json | config | 3.1 KB |
| assets/states.example.csv | other | 1.2 KB |
| assets/waivers.example.csv | other | 263 B |
| references/generic_ui_defaults.md | markdown | 6.4 KB |
| references/interaction_states.md | markdown | 5.9 KB |
| references/rendered_checks_wcag22.md | markdown | 6.7 KB |
| scripts/finish_lint.py | script | 17.8 KB |
| scripts/rendered_audit.py | script | 16.9 KB |
| scripts/state_matrix_checker.py | script | 11.8 KB |
references/generic_ui_defaults.md
View on GitHub# Unfinished work and template defaults
`finish_lint.py` separates two kinds of findings, and the separation is the
point of the design:
- **Unfinished work blocks.** A handler that does nothing, a link to `#`,
"Lorem ipsum" on screen, or a removed focus ring is a defect, whatever the
brief says.
- **Template defaults only warn.** A purple gradient or a row of identical
cards is a choice. It is wrong only when nobody made it. The brief may ask
for exactly that look, and then it is right.
Confidence markers: π’ a standard or the source's own words Β· π‘ widely
documented practice Β· π΄ opinion, labelled as such.
## Unfinished work (blocking)
| Code | Pattern | Why it ships |
|---|---|---|
| `INERT_HANDLER` | `onClick={() => {}}`, `onClick={undefined}`, a handler that only logs or alerts, `@click=""`, `TODO` inside the handler | Scaffolding that a generated or hurried screen leaves behind. It looks finished in every screenshot. |
| `DEAD_LINK` | `<a href="#">`, `href=""`, `href="javascript:β¦"` with no handler | The same thing for links. If it performs an action it should be a `<button>`. |
| `PLACEHOLDER_COPY` | lorem ipsum, TODO, TBD, `[Insert β¦]`, "your text here", `$XX`, "Coming soon" | Copy is written last and often not at all. Empty and error states are where it usually survives. |
| `FOCUS_REMOVED` | `outline: none` or `outline-none` with no `:focus-visible`, ring or box-shadow replacement | Removing the default ring "because it looks ugly" is the commonest way to fail WCAG 2.4.7. π’ |
| `BUTTON_NO_ACTION` (HIGH) | `<button>` with no handler, no submit/reset type and no enclosing form | Often wired elsewhere (a ref, a parent handler), so it is HIGH, not BLOCKER. Suppress it with a reason when it is. |
Suppress one line when it is intentional:
`{/* design-qa: allow PLACEHOLDER_COPY (legal copy pending, ticket LEG-12) */}`.
Use a reason a reviewer can check. A suppression without one is a defect deferred.
## Template defaults (warn only)
Anthropic's `frontend-design` skill lists the traits that AI-generated design
clusters around today. The list is useful because it names concrete
defaults, not because those defaults are bad. π’ (the source's own list)
1. A warm cream background with a high-contrast serif and a terracotta accent.
2. A near-black background with a single acid-green or vermilion accent.
3. A broadsheet layout with hairline rules and zero border radius.
4. **The SaaS card kit**: content chopped into identical rounded cards, one radius
everywhere, the same soft grey shadow (`rgba(0,0,0,.1)`), and gradient
washes as decoration.
5. **Template chrome**: a tracked-out ALL-CAPS eyebrow above every heading,
meta strings joined with middle dots, "WORD β fragment" labels, `#111` for
black, a monospace face for small labels, and `β` appended to links and buttons.
The same source also names the motion and layout defaults: a fade-and-slide-up
on every section and a hover transition on every card "read as AI-generated";
numbered `01 / 02 / 03` markers are right only for real sequences; and "a big
number with a small label, supporting stats, and a gradient accent is the
default" hero. π’
What the linter detects mechanically (each trait is one `TEMPLATE_DEFAULT`
warning, so the count means something):
| Trait key | Detected from |
|---|---|
| `gradient_wash` | Tailwind `from-/via-/to-` in the purple, violet, indigo, fuchsia and pink families; CSS gradients with those colours |
| `card_kit` | `rounded-xl/2xl/3xl` with `shadow-md/lg/xl`; `box-shadow β¦ rgba(0,0,0,.1)` |
| `eyebrow_caps` | `uppercase` with `tracking-wide/wider/widest`, or `text-transform: uppercase` with `letter-spacing` |
| `arrow_suffix` | `β` before a closing tag |
| `middot_meta` | two or more ` Β· ` separators in one text run |
| `numbered_markers` | `01`, `02`, `03` as standalone text |
| `entrance_motion` | `fade-in-up`, `data-aos="fade-up"`, Framer `initial={{ opacity: 0, y: β¦ }}` |
| `hover_lift` | `hover:-translate-y-*`, `hover:scale-102β¦105` |
| `hero_cliche` | "unlock the power", "supercharge", "revolutionise", "seamless", "elevate your", "next-gen", "all-in-one", "effortless" |
`generic_risk` is LOW (0β1 traits), MEDIUM (2β3) or HIGH (4 or more). π΄ The
thresholds are a convention for this skill, not research. They tell you when
to stop and ask whether anyone chose this look, nothing more.
**What to do with a HIGH:** compare it with the brief. If the brief asks for the
look, record that in the sign-off and move on. If it does not, pick one
trait and replace it with a choice specific to the subject, such as the
product's own data, its users' vocabulary or a real photograph. Changing one
deliberate thing beats sanding down nine. π΄
## Token drift (warn)
Many distinct raw hex values in component files (outside files named
`tokens`, `theme`, `colors` or `tailwind.config`) mean the screen has drifted
from the design system. The default limit is 12, which is roughly a neutral
ramp plus brand and semantic colours. Raise it with `--max-raw-colors` for
illustration-heavy pages. π΄ Refactoring UI makes the underlying point: define
the palette first, including about 8β10 shades per colour, and pick from it
rather than inventing values per screen. π‘
## Sources
1. Anthropic, `frontend-design` skill, `SKILL.md` (anthropics/skills, main branch, read 2026-10-30): the five trait clusters, the motion and hero defaults, and the error and empty-state guidance quoted above. https://github.com/anthropics/skills/tree/main/skills/frontend-design
2. W3C, *WCAG 2.2*, SC 2.4.7 Focus Visible, and *Understanding 2.4.7* failure F78 (styling that removes or obscures the focus indicator). https://www.w3.org/WAI/WCAG22/Understanding/focus-visible.html
3. Wathan, A. & Schoger, S. (2018). *Refactoring UI*: "Define your shades up front", limited palettes and system-first spacing. https://www.refactoringui.com/
4. Nielsen Norman Group, *Aesthetic-Usability Effect* (Moran, 2017): why a polished but generic screen gets an easy pass in review. https://www.nngroup.com/articles/aesthetic-usability-effect/
5. MDN Web Docs, `:focus-visible`: the replacement pattern for removed outlines. https://developer.mozilla.org/en-US/docs/Web/CSS/:focus-visible
6. GitHub issue #962 in this repository: the community request for a rendered-UI finish gate (generic AI UI, missing states, inert controls), which this skill answers. https://github.com/alirezarezvani/claude-skills/issues/962
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |