avoid-ai-design
Audits AI-generated frontend and rewrites it so it stops looking AI-made: purple-gradient slop and the "tasteful" defaults (cream + terracotta, mono chrome). Zero-dependency scanner included. The design counterpart to avoid-ai-writing.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/funboy322/avoid-ai-design with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/funboy322/avoid-ai-design'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/funboy322--avoid-ai-design)HTML
<a href="/listings/funboy322--avoid-ai-design"><img src="/api/listings/funboy322--avoid-ai-design/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
With the [skills CLI](https://skills.sh), which detects the agents you have installed:
npx skills add funboy322/avoid-ai-design
Or clone into your agent's skills directory. `~/.agents/skills/` is the cross-client convention, so Claude Code, Cursor, Codex, and other compatible tools all pick it up:
git clone https://github.com/funboy322/avoid-ai-design.git ~/.agents/skills/avoid-ai-design
Claude Code also reads `~/.claude/skills/`:
git clone https://github.com/funboy322/avoid-ai-design.git ~/.claude/skills/avoid-ai-design
For a single project instead of globally, clone into `.agents/skills/` (or `.claude/skills/`) under the repo root. Then start (or restart) Claude Code and run `/skills`: you should see `avoid-ai-design` in the list. No build step.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 127 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- ---
- name: avoid-ai-design
- description: Audit and rewrite frontend UI to remove generic AI design patterns ("AI slop"), both the first-order defaults (purple gradients, Inter, a centered hero over three cards, untouched shadcn) and the second-order "tasteful AI" ones (cream with terracotta, near-black with acid green, all-caps mono chrome, one accented headline word, decorative 01/02/03). Use when asked to "de-slop a UI", "make a design look less AI-generated", "audit a page or component for AI design tells", "fix Claude/Codex-generated frontend that looks generic", or keep a multi-page site on one design system. Covers HTML/CSS and React/Tailwind/shadcn. Has a detection-only mode and a zero-dependency scanner (scripts/detect.mjs) for the code-certain tells.
- license: MIT
- compatibility: Works in any agent that reads agentskills.io SKILL.md files (Claude Code, Cursor, Codex CLI, VS Code Copilot and others). Optional, Node 18+ to run scripts/detect.mjs, and a screenshot tool to judge the visual tells.
- metadata:
- author: ungspirit
- version: "0.4.0"
- tags: design ui frontend ai-slop tailwind shadcn react
- agentskills_spec: "1.0"
- ---
- # 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:
- ```bash
- 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.
- ## Context profiles
- Adjust strictness to where the UI lives. Auto-detect from the stack and structure; state which profile you are using.
- | Profile | How to treat it |
- |---|---|
- | `landing` / `artifact` | Full strength. Reward boldness. This is where a real direction matters most. |
- | `marketing-page` | Full strength on type, color, layout, and copy. |
- | `app-component` | Surgical. Fix the tells, keep the component's contract and structure. |
- | `inside-design-system` | Surgical only. Respect existing tokens and primitives. Do not fight the system; flag system-level tells separately as advice. |
- | `dashboard` | Favor density, legibility, and information hierarchy over decoration. |
- ## Guardrails
- - **Never break working code.** Props, state, routing, data fetching, and accessibility survive intact. Behavior is not yours to change.
- - **Do not trade one cliché for another.** A second-order default is still a default. The fix for purple is not cream and terracotta, and the fix for cream is not near-black and lime. Vary across runs and justify every choice by the subject.
- - **The brief wins.** An existing design system, brand guidelines, a named framework, or a font or color the user picked outranks your taste, including when it asks for one of the SD looks. Match it, never override it, and mark it with an ignore comment so the scanner stops flagging it.
- - **Keep one design system across pages.** When the work spans more than one page, lock a single contract (color, type, spacing, radius, nav, footer, shared components) in `DESIGN.md` and reuse it verbatim. Regenerating each page from scratch reverts to the training median, so page two drifts from page one. That is *design-system drift* (catalog **X1**), and it reads as AI as loudly as any single tell. If a token you need does not exist, add it to the contract or ask. Do not invent a one-off.
- - **Evidence, not accusation.** A tell shows a default nobody chose. It never proves a model made the page, and much of it is Tailwind and shadcn as installed. Report defaults; do not speculate about authorship.
- - **Do not manufacture problems.** If the UI is already distinctive and intentional, say so and stop. A clean audit is a valid result.
- - **Keep the copy's meaning.** You may sharpen generic microcopy, but do not invent claims or change what the product says about itself.
- ## Self-reference escape hatch
- When the code is *about* AI design patterns (a demo, a teaching example, a "what not to do" gallery, or this skill's own docs), illustrative slop is intentional. Treat it as exempt only when there is a concrete signal: a sibling comment that marks it (`slop-example`), a path under `examples/`, `fixtures/`, `__mocks__/`, or `stories/`, or text explicitly labeled illustrative. The scanner applies the same rule. Flag patterns in the real interface only.
- ## Beyond HTML and React
- The catalog is written for HTML/CSS and React/Tailwind/shadcn because that is what AI tools emit most. The principle is framework-agnostic: a default left untouched is the tell. Untouched MUI (Roboto and blue), Chakra, Bootstrap (`btn-primary` blue), or Mantine defaults read as AI for the same reason. Apply the same audit, swapping the specific class and token names.
- ## Output format
- ### rewrite mode
- 1. **Audit.** Every tell found, grouped by severity, each with its ID, location, a one-line reason, and a code-certain / rendered / inferred tag. Lead with the scanner summary when you ran it.
- 2. **Plan.** The direction and where it comes from in the subject, the compact token plan, what you revised in the default review (step 6), and one or two alternatives in a sentence. If interactive, this is where you pause.
- 3. **Rewrite.** The edited code, at the calibrated depth, plus `DESIGN.md` for multi-page work.
- 4. **What changed.** A short summary of the meaningful moves, not a line-by-line diff.
- 5. **Re-scan and judgment.** The scanner's second pass, then the four success tests. Fix anything that fails.
- ### detect mode
- 1. **Audit.** Every tell found, grouped by severity (P0/P1/P2), with IDs, locations, and a code-certain / rendered / inferred tag.
- 2. **Assessment.** For each flag, whether it is a clear problem or a judgment call. Some patterns are fine in context (one gradient, used well, is not slop; a cream palette the brief asked for is a choice). Say which to fix and which to leave.
- ## Don't over-design
- The goal is a UI that looks like a person with taste made it for this subject, not a UI that is loud for its own sake. Restraint executed well beats maximalism applied blindly. If the original is already strong, make the few cuts it needs and stop. Match the intensity of the rewrite to the artifact: a settings panel does not need a hero animation.
README.md · README · 248 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- <!-- SEO: title + meta description live in docs/SEO.md -->
- # avoid-ai-design
- **A Claude Code skill that audits AI-generated frontend code and rewrites it so it stops looking AI-generated, including the "tasteful" defaults that replaced the purple gradient.**
- [](LICENSE)
- [](https://agentskills.io)
- [](https://claude.com/claude-code)
- [](#compatibility)
- <p align="center">
- <img src="docs/before-after.png" alt="The same SaaS landing page, before and after. Left, labeled Before: a purple-to-blue gradient hero with gradient headline text, a sparkle pill badge, a glassy chart mock, and three emoji feature cards. Right, labeled After: the same product, sections, and copy, rebuilt around the product's own retention cohort table as the hero, in navy on a cool grey ground with one blue heat ramp, features as table rows, and a totals row for the stats." width="100%">
- </p>
- <p align="center"><sub><i>One real page, run through the skill. Same product, same sections, same copy; only the design changed. The scanner finds 23 tells before and no design tells after. Pages and the full audit: <a href="examples/demo/">examples/demo/</a>.</i></sub></p>
- Ask Claude, Codex, or any model to "build a landing page" and you get the same page every time: a purple-to-blue gradient, Inter for every word, a centered hero over three rounded feature cards, a glassy navbar. Ask it to make that look less AI and you get the *next* same page: warm cream with a terracotta accent, or near-black with one acid-green signal, all-caps monospace labels, one colored word in the headline, features numbered 01 / 02 / 03.
- `avoid-ai-design` catches both. It scans the frontend an AI just produced, flags the patterns that give it away, and rewrites the interface around a direction drawn from your product rather than from a list of looks. On multi-page work it writes that direction down once, in a `DESIGN.md`, so page two cannot drift from page one.
- It is the design counterpart to [`avoid-ai-writing`](https://github.com/conorbronsdon/avoid-ai-writing): same idea, applied to UI instead of prose.
- ---
- ## The problem: AI design converges, twice
- Models are trained toward the average, so their UI clusters around safe defaults you can recognize on sight:
- - **Type** that is always Inter, Roboto, or the system stack, with no pairing and no display face.
- - **Color** that is a purple or indigo gradient fading into blue.
- - **Layout** that centers everything: hero, subhead, two buttons, then a three-card feature grid.
- - **Components** wrapped in `rounded-2xl`, `shadow-lg`, and `backdrop-blur`, straight from the shadcn defaults.
- - **Copy** that opens with "Elevate your workflow" and ends with a "Get Started" button.
- Then the fix converged too. Anthropic's own `frontend-design` skill now lists the clusters AI design gathers around once it avoids the purple: cream with a terracotta accent (Claude's own interface color), near-black with one acid-green or vermilion signal, broadsheet hairlines, the SaaS card kit, and template chrome like tracked all-caps eyebrows and `A · B · C` meta strings. These *second-order defaults* read as AI to anyone who has seen a few hundred generated pages. This skill's own first demo landed in them, which is how v0.4 came to check for them by name.
- ## What it catches
- The full catalog lives in [`references/ai-tells-catalog.md`](references/ai-tells-catalog.md): 67 tells, each with a detection signal, why it reads as AI, a fix for plain HTML/CSS and for React + Tailwind + shadcn, and its sources.
- | Category | Example tells |
- |---|---|
- | **Second-order defaults** | cream + terracotta (the Claude look), near-black + one acid-green accent, broadsheet cosplay, all-caps and mono template chrome, one accented headline word, decorative 01 / 02 / 03, fake window dots, the emerald fallback |
- | **Typography** | Inter everywhere, the "tasteful free font" set (Space Grotesk, Geist, Instrument Serif, Fraunces), a face declared in CSS but never loaded |
- | **Color** | the purple/indigo gradient, gradient headline text, untouched shadcn palettes, one hue pretending to be two, muted text below WCAG AA |
- | **Layout** | the centered hero, three icon cards, the stock section order (hero, logos, features, stats, pricing, CTA), three-tier pricing rings, the four-column footer |
- | **Components** | `rounded-2xl shadow-lg` on everything, reflexive glass, icon-in-a-rounded-square, stock Aceternity / Magic UI effects, missing focus states |
- | **Motion** | the same fade-up on every section, bounce easing, count-up stats, animation that ignores reduced-motion |
- | **Icons, copy, imagery** | the worn Lucide set and the sparkle-for-AI, "Elevate / Seamless / Powerful", arrows welded to CTAs, generic CTA labels, placeholder avatars |
- | **Consistency** | design-system drift: font, color, radius, nav, or footer that changes from page to page, or ignores the design you chose |
- Every tell is ranked by **who notices it**: P0 a layperson, P1 a designer or developer, P2 craft and polish. And the catalog is explicit about what *not* to flag: a tell is evidence of a default nobody chose, never proof that a model made the page.
- ## Scan in one command
- `scripts/detect.mjs` finds the code-certain tells with no model call and no dependencies (Node 18+):
- ```bash
- node ~/.claude/skills/avoid-ai-design/scripts/detect.mjs src/
- ```
- ```
- src/app/page.tsx P0 5 · P1 12 · P2 4
- P0 C1 Purple / indigo gradient L13
- The canonical unchosen gradient (the Tailwind indigo-500 lineage).
- P0 C6 Gradient-filled headline text L13
- bg-clip-text gradients are a 2024-era default flourish that also hurts legibility.
- P0 L1 Pill badge + centered hero L13
- ...
- ```
- - `--json` for machine-readable output, `--min=P1` to hide polish-level findings.
- - Exit code `2` when any P0 or P1 is found, `0` when clean, so it works as a CI gate.
- - It skips `examples/`, `fixtures/`, `stories/`, and files marked `slop-example`, and it honors ignore comments for choices your brief asked for: `avoid-ai-design-ignore: SD1` on a line, or `avoid-ai-design-ignore-file: SD1, SD4` in a file.
- The scanner covers the half of the audit that lives in source. Palette weight, spacing rhythm, hierarchy, and structure-level sameness need a render, and the skill does that part.
- **Optional: check every UI edit in Claude Code.** Add a `PostToolUse` hook to `.claude/settings.json`. When an edit introduces P0 or P1 tells, Claude sees the list right away and can fix it in the same turn:
- ```json
- {
- "hooks": {
- "PostToolUse": [
- {
- "matcher": "Edit|Write|MultiEdit",
- "hooks": [
- { "type": "command", "command": "node ~/.claude/skills/avoid-ai-design/scripts/detect.mjs --hook" }
- ]
- }
- ]
- }
- }
- ```
- ## Two modes
- | Mode | What it does | When to use |
- |---|---|---|
- | `rewrite` *(default)* | Scan, audit, plan a direction, review the plan against the defaults, rewrite, re-scan | You want the UI fixed |
- | `detect` | Scan and audit only, no edits | You want to see the tells and decide yourself, or you are reviewing code you should not change |
- Trigger `detect` with phrases like "just audit", "flag only", "don't change the code", or "scan this for AI tells".
- ## How it works
- 1. **Scope.** What is under review, the stack, the mode, and any design system you already have: a `DESIGN.md`, tokens, sibling pages, or a font and color you chose.
- 2. **Scan.** Run the scanner for the code-certain tells.
- 3. **Render.** Screenshot the UI when a tool is available, judge the visual tells from pixels, and run the silhouette test: shrink the page to a black-and-white block outline and ask whether it could be anyone's.
- 4. **Audit.** Merge everything into one report: each tell with its ID, location, severity, and why it reads as AI.
- 5. **Ground the plan in the subject.** If a system exists, it is the direction. Otherwise, derive one from what the product is made of (its materials, its artifacts, its vernacular) and write it down as 4-6 colors with roles, the faces, a layout idea, and one signature detail.
- 6. **Review the plan against the defaults.** For every move: would you have made it for any similar page? If so, it is a default. Revise it before any code is written. You confirm the plan.
- 7. **Rewrite.** Edit the real files at the right depth: surgical inside a design system, a rebuild for a standalone page. Functionality, props, data flow, accessibility, and the meaning of your copy stay intact. Multi-page work gets a `DESIGN.md` ([template](references/design-md-template.md), Google's open format) that every page is built from.
- 8. **Re-scan and judge.** No P0, no second-order default the brief did not ask for, and four tests: justified, coherent, not a second-order default, consistent across pages.
- ## See it work on a real page
- [`examples/demo/`](examples/demo/) is a real end-to-end run on one generic AI-built SaaS page. Every file holds the same product, sections, and copy; only the design varies.
- **1. The run.** [`slop.html`](examples/demo/slop.html) is the page an AI tool produces unprompted. [`refined.html`](examples/demo/refined.html) is the same page after the skill, grounded in the product's most characteristic artifact: the retention cohort table is the hero, the page is built like a table, and the table's heat ramp is the only color. [`AUDIT.md`](examples/demo/AUDIT.md) is the full run, including an honest section on what the previous version of this demo got wrong. Full-page screenshots: [before](docs/demo-before.png) and [after](docs/demo-after.png).
- **2. More than one right answer.** The same page, rebuilt four ways, each drawn from a different part of the product's world, each scanning clean of first- and second-order defaults:
- <p align="center">
- <img src="docs/variants.png" alt="The AI-generated page next to four rebuilds of it. Cohort: the retention cohort table as the hero, navy on cool grey. Tempo: the week drawn as a step sequencer in black and brass with expanded type. Wallboard: huge signage-face numerals on dark navy with amber live values, built for a wall TV. Funnel: a real signup funnel as the hero, with page sections that narrow like a funnel, in plum and raspberry with a sturdy serif." width="100%">
- </p>
- - [`refined.html`](examples/demo/refined.html): **Cohort**, the retention table.
- - [`after-tempo.html`](examples/demo/after-tempo.html): **Tempo**, the name. A cadence is a rhythm, so the week becomes a step sequencer.
- - [`after-wallboard.html`](examples/demo/after-wallboard.html): **Wallboard**, where the product lives: the TV on the team's wall.
- - [`after-funnel.html`](examples/demo/after-funnel.html): **Funnel**, the question every user asks, and a page that narrows like one.
- **3. One design system, every page.** [`faq.html`](examples/demo/faq.html) is a second page built on `refined.html`'s exact tokens, header, and footer: the same product. [`faq-drift.html`](examples/demo/faq-drift.html) is the same FAQ regenerated from scratch, drifting back to the median.
- <p align="center">
- <img src="docs/consistency.png" alt="Home and FAQ pages of one site on the same design system, grouped under 'Same system, built from one DESIGN.md'. Beside them, the same FAQ regenerated from scratch has drifted into an indigo-gradient Inter template, grouped under 'Regenerated from scratch, design-system drift'." width="100%">
- </p>
- ## Install
- With the [skills CLI](https://skills.sh), which detects the agents you have installed:
- ```bash
- npx skills add funboy322/avoid-ai-design
- ```
- Or clone into your agent's skills directory. `~/.agents/skills/` is the cross-client convention, so Claude Code, Cursor, Codex, and other compatible tools all pick it up:
- ```bash
- git clone https://github.com/funboy322/avoid-ai-design.git ~/.agents/skills/avoid-ai-design
- ```
- Claude Code also reads `~/.claude/skills/`:
- ```bash
- git clone https://github.com/funboy322/avoid-ai-design.git ~/.claude/skills/avoid-ai-design
- ```
- For a single project instead of globally, clone into `.agents/skills/` (or `.claude/skills/`) under the repo root. Then start (or restart) Claude Code and run `/skills`: you should see `avoid-ai-design` in the list. No build step.
- ## Use it
- Once installed, ask in plain language. The skill triggers on intent, not a fixed command:
- ```
- de-slop this landing page
- make this component look less AI-generated
- audit App.tsx for AI design tells, don't change anything
- this site looks like every Claude-made site, fix it
- add a pricing page that matches the rest of the site
- ```
- You can name a direction up front ("rewrite this around our shipping-label look") or let the skill derive one from the product.
- ## Compatibility
- `avoid-ai-design` is a plain [`SKILL.md`](https://agentskills.io) with reference files and one optional script. It needs no APIs or keys, so it runs anywhere the format is supported:
- - Claude Code (CLI, desktop, web, IDE extensions)
- - Cursor
- - OpenAI Codex CLI
- - GitHub Copilot (VS Code)
- - Any other agent that reads the agentskills.io `SKILL.md` format
- The scanner needs Node 18 or newer. Without it, the skill walks the catalog by hand.
- ## How it differs
- **From Anthropic's [`frontend-design`](https://github.com/anthropics/skills/tree/main/skills/frontend-design).** `frontend-design` guides UI *as it is being built*, from a brief. `avoid-ai-design` works on code that **already exists**: it audits, scores, and rewrites output you or another model produced. They share a goal, and this catalog cites `frontend-design`'s list of AI-design clusters directly. Use one to write, the other to check.
- **From the larger anti-slop frameworks** such as [Impeccable](https://github.com/pbakaus/impeccable), [taste-skill](https://github.com/leonxlnx/taste-skill), and [Hallmark](https://github.com/nutlope/hallmark). They cover the whole design workflow with large rule sets, commands, and themes. `avoid-ai-design` stays small on purpose: one audit-and-rewrite pass, a catalog that cites a source for each claim, severity ranked by who notices, a section on what *not* to flag, checks for the second-order defaults by name, and one `DESIGN.md` for multi-page work, in Google's open format that Stitch and a growing set of design tools also use. They compose: generate with any of them, then run this as the check.
- ## FAQ
- **What is "AI slop" in web design?**
- The cluster of default visual choices AI tools reach for unprompted: purple-to-blue gradients, Inter, centered heroes with three feature cards, untouched shadcn, glass everywhere. It is generic because the model averages its training data.
- **Does it also flag the "tasteful" fixes?**
- Yes. Cream with terracotta, near-black with one acid-green accent, all-caps mono labels, one colored headline word, decorative 01 / 02 / 03: these are the second-order defaults, and the skill checks for them by name. If your brief genuinely asks for one, keep it and mark it with an ignore comment.
- **Is a finding proof that AI made my site?**
- No. A tell shows a default nobody chose. Designers shipped rounded cards long before LLMs, and plenty of this is Tailwind and shadcn as installed. The skill reports defaults and fixes them; it never claims authorship.
- **How do I make AI-generated UI look less generic?**
- Start from the product, not from a style. Ask what its world is made of, open with the most characteristic thing in that world, and check each design move against the question "would I have done this for any similar page?" The skill runs that process for you, or flags exactly what to change in `detect` mode.
- **Will it keep my pages consistent?**
- Yes. If a design already exists (other pages, a tokens file, a `DESIGN.md`, a font and color you chose), the skill treats it as the contract. For new multi-page work it writes one `DESIGN.md` and builds every page from it, because regenerating each page from scratch is exactly how "AI design-system drift" happens.
- **Does it work with code from Codex and other models?**
- Yes. The tells are model-agnostic because the convergence is.
- **Will it break my working code?**
- No. The rewrite preserves functionality, props, state, routing, accessibility, and the meaning of your copy. Inside an existing design system it stays surgical. If the UI is already distinctive, it says so and stops.
- **Do I need to install anything else?**
- No. Node 18+ is only needed for the optional scanner.
- ## Repository layout
- ```
- avoid-ai-design/
- ├── SKILL.md # workflow, modes, calibration, severity, output format
- ├── scripts/
- │ ├── detect.mjs # zero-dependency scanner for the code-certain tells
- │ └── detect.test.mjs # regression tests: node --test scripts/detect.test.mjs
- ├── references/
- │ ├── ai-tells-catalog.md # the catalog, with sources and HTML + React fixes
- │ ├── aesthetic-directions.md # grounding questions and a vocabulary of directions
- │ └── design-md-template.md # the multi-page contract, in Google's DESIGN.md format
- ├── examples/
- │ └── demo/ # one AI page, its audit, four grounded rebuilds, a two-page consistency demo
- ├── README.md
- ├── LICENSE
- └── docs/ # images and maintainer notes
- ```
- ## Contributing
- Found a tell the catalog misses? Open a pull request that adds it to [`references/ai-tells-catalog.md`](references/ai-tells-catalog.md) in the existing format: the detection signal, why it reads as AI, a fix for both HTML/CSS and React/Tailwind, and a source. If it is code-certain, add a rule to `scripts/detect.mjs` and a case to `scripts/detect.test.mjs`, and run `node --test scripts/detect.test.mjs`. False positives are bugs; report them with the snippet that triggered one.
- ## License
- [MIT](LICENSE).
- ---
- <sub>**Keywords:** Claude Code skill · remove AI slop · de-slop UI · AI design patterns · generic AI aesthetics · AI-generated website detector · design slop scanner · frontend design audit · DESIGN.md · Tailwind / shadcn / React · Codex · agentskills.io · avoid AI design.</sub>
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.