Avoid AI Design

Avoid AI Design: Audit & Rewrite

You are reviewing frontend code to find the patterns that make a UI look AI-generated ("AI slop"), then rewriting it around one intentional design direction.

This is the design counterpart to the avoid-ai-writing skill. It targets two stacks: plain HTML/CSS/JS and React + Tailwind + shadcn/ui.

The point is not to chase novelty. It is to replace defaults with decisions. A purple gradient is not bad because purple is bad; it is bad because no one chose it.

There are two orders of default. The first is the median: purple gradient, Inter, three icon cards. The second is the tasteful escape that became the new median: cream with terracotta, near-black with one acid-green accent, all-caps mono labels, one colored word in the headline, decorative 01/02/03. Anthropic's own frontend-design skill lists these clusters, and de-slop passes (this skill's included) land in them constantly. Treat both orders as tells. See the SD section of references/ai-tells-catalog.md.

Code shows half of it; pixels show the rest. Some tells live in the source (a literal from-indigo-500, Inter, a lucide import); the scanner finds those. Others are visual: whether a palette has a real dominant color, whether spacing has rhythm, whether the structure is the same as every other page. Render when you can. When you cannot, say which findings are code-certain and which are inferred.

Modes

rewrite (default): Audit the code, commit to a direction, then rewrite it.

detect: Audit and score only. No edits. Use this mode when:

• The user wants to see what is flagged and fix it themselves.
• You are reviewing code you should not change (a dependency, a teammate's work, a reference).
• The user asks for a quick scan.

Trigger detect when the user says "just audit", "flag only", "scan", "what's AI about this", or "don't change the code". Default to rewrite.

The scanner

scripts/detect.mjs finds the code-certain tells (marked ⚙ in the catalog) with no model call and no dependencies. Run it first whenever Node 18+ is available:

node <skill-dir>/scripts/detect.mjs <files or folders>        # grouped report, exit 2 on any P0/P1
node <skill-dir>/scripts/detect.mjs --json <files or folders>  # for your own parsing

Treat its output as the code-certain half of the audit, not the whole audit: it cannot see palette weight, rhythm, hierarchy, or structure-level sameness. It skips examples/, fixtures/, stories/, and files marked slop-example unless given --include-examples, and it honors avoid-ai-design-ignore: <ID> comments for choices the brief asked for. Without Node, walk the catalog by hand.

Workflow (rewrite mode)

1. Scope. Read the actual files first. Establish what is under review (a component, a page, a whole app), the stack, and the mode. Look for a design system to stay consistent with: a DESIGN.md (Google's open format, also written by Stitch and other design skills), a tokens file or :root, a component library, sibling pages, or a font and color the user chose themselves. Note whether the work spans more than one page. Never judge from the prompt alone.
2. Scan. Run the scanner over the files in scope.
3. Render. If a screenshot or preview tool is available, render the artifact and judge the 👁 tells from pixels. Run the silhouette test on pages: reduce the screenshot to a small black-on-white block silhouette and ask whether it could be any other product's page (catalog L9). Squint at 25% for flat density. Without a render, mark visual tells as inferred, lower-confidence.
4. Audit. Merge the scan, the render, and a pass through every category in references/ai-tells-catalog.md, including the SD section. For each tell: location, ID, severity, one line on why it reads as AI, and whether it is code-certain, rendered, or inferred.
5. Ground and plan. If a design system exists, it is the direction: adopt it as a contract and match it exactly. Otherwise, derive the direction from the subject, not from a style menu. Ask what the product is, who uses it, and what its world is made of (materials, place, era, the domain's own artifacts and vernacular). Write a compact plan: 4-6 named colors with roles, the faces and their roles, the layout idea in a sentence, and the one signature detail. references/aesthetic-directions.md is vocabulary for naming moves, not a menu to pick from.
6. Review the plan against the defaults. Before touching code, check the plan against the second-order clusters (SD1-SD8) and your own recent passes. For each part, ask: would I arrive here for any similar page? If yes, revise it and say what changed. If a user is present, show the plan plus one or two alternatives in a sentence and pause. If you are running non-interactively, state the assumption in one line, proceed, and keep it easy to override.
7. Calibrate depth. A small component, or anything inside a design system, gets a surgical pass: swap the tells, keep the structure and the tokens. A standalone page gets a rebuild around the direction. A ground-up build overlaps with the frontend-design skill; if it is available, hand it the reviewed plan rather than duplicating its job.
8. Rewrite. Edit the real files. Preserve functionality, props, state, routing, data flow, accessibility, and the meaning of the copy. Do not add dependencies silently; name any you introduce. For multi-page work, write the plan into a DESIGN.md from references/design-md-template.md (or extend the existing one), and build every page from it.
9. Re-scan and judge. Run the scanner again: no P0, and no SD tell the brief did not ask for. Then judge the result against "What success means." A clean scan is necessary but not sufficient.

What success means

"Less obviously AI" is not the goal. A token-swap (indigo to teal, Inter to a trendier face, drop the emoji) clears every P0 and still leaves a forgettable template. Judge the result against these tests:

1. Justified. Every change serves the committed direction, and the direction traces back to the subject.
2. Coherent. The type, palette, layout, and signature detail reinforce one another. One idea, executed. Spend the boldness in one place.
3. Not a second-order default. It does not land in an SD cluster the brief did not ask for, and it does not repeat your recent passes (the cream-and-terracotta move, the near-black-and-lime move, the mono-chrome move). If you would have produced it for any similar page, it failed.
4. Consistent (whenever it is not the only page). It shares its siblings' tokens, nav, footer, and type scale, so it reads as the same product. Vary across projects (test 3); never within one.

A page can pass the scanner and still fail every one of these. The catalog catches clichés; these tests catch mediocrity.

Severity tiers

Tiers triage by who notices, not by how much the pattern annoys you. Context can move a tell up or down.

• P0, a layperson recognizes it as AI-made. The purple-to-blue gradient, Inter for everything, an untouched shadcn base theme, gradient (bg-clip-text) headline text, the centered-hero-over-three-cards template. These are the memes.
• P1, a designer or developer recognizes it. The second-order clusters (SD), rounded-2xl shadow-lg on every surface, the default page shell, icon-in-a-rounded-square, the default four-column footer, stock Aceternity / Magic UI effects, dead hover and focus states, arrow glyphs stapled to CTAs, "Elevate your workflow" copy.
• P2, craft and polish gaps. Flat spacing with no rhythm, the same fade-up on everything, bounce easing, generic CTA labels.

Context matters: a centered hero is P0 on a generic SaaS page and fine in a luxury layout. Missing :focus-visible, muted text below AA, and motion that ignores reduced-motion are accessibility defects, so treat them as high priority whatever their tier.