# ai-design-check **Find what makes an AI-built interface look generated, fix it, and keep it from coming back.** [![npm version](https://img.shields.io/npm/v/@enmera/ai-design-check)](https://www.npmjs.com/package/@enmera/ai-design-check) [![license: MIT](https://img.shields.io/npm/l/@enmera/ai-design-check)](LICENSE) [Türkçe](README.tr.md) · [日本語](README.ja.md) For anyone building with Claude Code, Cursor or Codex: 147 design rules, a checker with no dependencies and no API key, and an agent skill that repairs the screen. It reads web projects (React, Vue, Svelte, Laravel Blade, HTML; Tailwind, Bootstrap or plain CSS) and SwiftUI, Jetpack Compose, Flutter and React Native apps. Finding needs no agent, and neither do the mechanical fixes. ## Start in three steps **1. Check your project.** ```bash npx @enmera/ai-design-check ``` ``` Accessibility (1) src/pages/dashboard.tsx 31 error Never remove the focus ring without a replacement: outline-none focus-ring-removed Style (3) src/pages/dashboard.tsx 42 error Font sizes from the scale only: text-[10px] type-scale 88 warn No tracked uppercase labels: tracking-wide uppercase no-decorative-uppercase lang/tr.json 812 error Translation in Title Case: "Sıra Takibi" (Rank tracking) sentence-case 1 accessibility, 3 style: 3 errors, 1 warnings, 0 notes. ``` **2. Fix what has one answer, with no agent.** ```bash npx @enmera/ai-design-check --fix --dry-run ``` This lists the changes; drop `--dry-run` to make them. Spacing and corners move to the nearest step of your scale, and very heavy type becomes bold. Tap sizes, colours, emoji, words and hierarchy stay in the report, since they take a decision. Add `--nearest-type` to move `text-[Npx]` sizes to the nearest theme size as well (`lg:text-[64px]` → `lg:text-6xl`). **3. Let your agent fix the rest.** ```bash npx skills add enmerasoftware/ai-design-check ``` Then ask: *"fix the design of this screen"*. The agent measures the screen, writes a short brief from your product, repairs it, and shows the count before and after. Features, data and words stay.

The same dashboard before and after: 266 findings down to 0

The same dashboard, before and after. Open before and after, or watch the video.

## What's in the package | Tool | What it answers | Run it | |---|---|---| | **Checker** | What is wrong, in which file and on which line? | `npx @enmera/ai-design-check` | | **Fix skill** | Can an agent repair this screen and prove it? | `npx skills add enmerasoftware/ai-design-check` | | **`scan`** | What does the running page really show? Contrast, sizes, what covers what, script errors | `npx @enmera/ai-design-check scan http://localhost:3000` | | **`redesign`** | Can my agent study this page and redo it on a branch, proving each step? | `npx @enmera/ai-design-check redesign http://localhost:3000` | | **`inventory`** | How many different buttons, inputs, headings and cards do we have? | `npx @enmera/ai-design-check inventory` | | **`narrow`** | What breaks on a phone or in a long language? | `npx @enmera/ai-design-check narrow page.html` | | **`system`** | What fonts, type and colours should a new product start with? | `npx @enmera/ai-design-check system --brand "#1E5A63"` | | **`story`** | Can I share the change as a video? | `npx @enmera/ai-design-check story before.html after.html` | ## What it catches 68 rules read your code (34 of them in app code too) and 61 read the running page (`scan`), some of them both. The other 33 need eyes on the screen, so they are marked *review* and left to you and the fix skill. Each rule says what to do, why and how to fix it, in English and Turkish: [RULES.md](RULES.md). | Area | Examples | |---|---| | Accessibility | Focus rings never removed without a replacement, icon-only buttons have a name, tap targets | | Phone browsers | Pinch zoom stays on, 16 px text in fields, `dvh` beside fixed `100vh`, nothing hidden until hover | | Type and shape | One type scale with 11 px as the floor, one radius per level, no cards inside cards | | Writing and copy | Sentence case, no tracked uppercase labels, no buzzwords, buttons that say what they do, errors that say what to do | | Components | Buttons and inputs from shared components, no outside styling, repeated markup becomes a component | | Layout | Spacing on a 4 px grid with one gap per level, wide tables span the page, room for each cell on a phone | | Visual language | Line icons instead of emoji, no gradient text or purple gradients, no side stripes, no coloured shadows, glow only in charts | | Motion | No `transition-all`, no bounce, reduced motion respected, pulse only for live data, answers within 300 ms, no endless loops | | Data | Numbers carry their comparison, tabular numerals, empty states | | Localisation | Locale-aware case changes (Turkish i/İ), numbers through the formatter, real plurals | | Selectors and navigation | One selector language, menu grouped by job, moved URLs redirect | The rules come from screens we shipped at [Enmera](https://enmera.com.tr) and [Searvia](https://searvia.com): what read as generated, what broke at narrow widths, what people did not understand. We then compared them with 16 highly rated dashboard designs. Method and findings: [RESEARCH.md](RESEARCH.md). **How well it tells them apart.** [BENCHMARK.md](BENCHMARK.md) runs every rule on 72 pages that four Claude and two GPT models generated, in Tailwind and in Bootstrap, and on 34 sites people designed. Some rules separate the two clearly: a cream page ground shows on 40% of the AI pages against 3% of the sites; on phones 35% of the AI pages scroll sideways and no human site does. GPT and Claude leave different marks: GPT pages set small text on every page and crush heading letter spacing on 88% of them. Others no longer tell, purple gradients among them, and their severity follows that evidence. ## The running page and the redesign `scan` opens the page in your Chrome at desktop and phone width, with no model and no API key. It reads what the source can't show: real contrast, sizes, what covers what, broken images, script errors, content that never appears. It reads every colour Chrome computes, Tailwind 4's `oklch()` included, and the habits of a generated page: an accent word in the headline, coloured shadows, an arrow on every call to action, lists strung on middle dots, a badge pill above the headline. A page that did not load, answers with an error, sends the browser to a sign-in page or draws a sign-in form in its own place stops the scan with exit 2 instead of passing as clean. For a page behind a sign-in, pass `--cookie "name=value"` or `--header "Name: value"`, or set `AI_DESIGN_CHECK_COOKIE` and `AI_DESIGN_CHECK_HEADERS` to keep them out of shell history and CI logs. Both go only to the page's own origin, never to the other hosts it loads from. `--allow-redirect` and `--allow-status 404` check such a page on purpose. Several URLs are scanned in one run. Add `--format github` for pull requests. With `designSystem` in the config (`fonts`, `sizes`, `radii`, `colors`) it also names what drifts. To check one part of a page, such as a CMS module rendered inside the app's own shell, pass `--scope "[data-block-type=module-1]"`: only what is inside a match is checked, and `redesign` measures and plans only that part. `--ignore "nav"` leaves a part out. Both work for `scan`, `narrow` and `redesign` and can be given more than once; several scopes are one area. A scope that matches nothing stops the run with exit 2 instead of passing as clean. Sideways scrolling caused outside the scope is not reported; script errors are, since they belong to the whole page. Text under `aria-hidden="true"`, such as a faded code rain behind the headline, is decoration: contrast, size and the other reading rules leave it alone, while the visual tells (gradients, glows, endless loops) still look at it. `redesign` is the one part that needs your agent (Claude Code or Codex), because deciding what a page should show takes judgement. The agent studies the screenshots, the code and the subject, and writes one card per section: what it says, what is wrong, the idea that comes from its own content, the colours it uses from your site. Those cards are checked against the measured page. Then the numbered fixes and the cards are applied pass by pass on a new git branch, and a pass that loses content, adds rule errors or looks worse is thrown away. `--plan` stops after the cards so you can read and edit them; `--brief` builds them. It starts only on a clean working tree (commit or stash first), and Ctrl-C puts back the pass in progress. Before any card the study decides how much to change: `heavy` (many tells, rebuilt section by section), `polish` (mostly designed: at most two sections change the look, each on a measured tell, and bigger ideas become suggestions) or `none` (it works; a few refinements are suggested and nothing is built). Then it writes a direction from your product: what it is in one sentence, its character in two or three concrete words (not clean, modern, sleek, minimal or premium), the world it belongs to, the one or two moments on the screen that carry the richness, and one signature detail. Each card says whether it changes the look, and what a visitor will see differently; `--plan` and `BRIEF.md` label every card "changes the look" or "fixes only" and say so in one line when none changes it. The first screen's card has to change the look and show the proof of its claim. After the craft pass the visual check asks, card by card, whether that change is in the after screenshot; a card that looks the same gets one more try, then the pass is thrown away. A `brief.json` from an earlier version still works with `--brief`, as `heavy` with no direction. `--in-place` makes no branch and no commits, and runs on a tree with uncommitted work (yours, or another session's): a pass that is thrown away goes back to exactly the state before it, your edits included, and a kept pass stays as uncommitted changes with its patch saved, so `git apply -R ` undoes it; the run ends with the changed files and the undo commands, newest first. `--files "resources/views/home.blade.php,resources/css/**"` limits every pass to those paths or globs: a pass that changes any other file is thrown away. `--out ` puts the plan, screenshots, logs and patches somewhere else (default `.ai-design-check/redesign`, which git ignores; a folder outside the project works too). For a page behind a sign-in when you would rather not hand over a cookie, save it and pass the file: `redesign ./page.html` (or `--html page.html`). With `--build ""` the passes edit your sources and the command writes the file again; without it the passes edit the file itself, and a file git does not keep is put back from a copy when a pass is thrown away. The study starts from what you already know. A `PRODUCT.md` in the project root (purpose, audience, voice, what to avoid, rivals) and a `DESIGN.md` (the visual system you keep) go into the study and the craft prompt, quoted as your notes; `--product ` and `--design ` point elsewhere. Without a `PRODUCT.md` the study writes a draft to the `--out` folder from the README, the package description and the pages, and the run says in one line to review it and move it to the root; the tool never writes there itself. `--intent ""` says what you want from this run: it leads the study and the cards, and is kept in `brief.json`. `--degree heavy|polish|none` chooses how far the run goes instead of leaving it to the study, which then has to write that degree (a `--brief` brief takes it). Heavy rebuilds every section that is not kept, composes the first screen as one picture with a real product surface, turns repeated identical cards into content-specific pictures and keeps the logo, brand colour, fonts, words and section order; its cards may use tints and shades of the site's colours (the same hue within 8 degrees, or a neutral grey), while polish and none use exactly the site's colours. `--images openai|gemini` lets cards ask for generated photos or illustrations (a hero scene, one photo per sector in place of identical icon cards): at most 1 per card and `--images-max` per run (default 6, up to 12). The key is read from `OPENAI_API_KEY` or `GEMINI_API_KEY` only and never printed; a missing one stops the run before any agent starts. After the study the run lists each image with an estimated cost (an estimate: check your provider's pricing) and generates nothing without a yes at the terminal or `--yes`. The images go to `/images/`, and the craft pass copies them into the page's own image folder with real alt text. Any other field you put in `product` (`context`, `audience`, `voice`, `competitors`, `avoid`, or one of your own) reaches both prompts. Each card that changes the look picks a layout from its content (`split`, `product`, `photo`, `place`, `editorial`, `statement`, `collage`, or `centred` for a short section with no visual) with a line saying why; a centred hero with a visual, or two changing sections side by side with one layout, is sent back. `"only": ["exact heading"]` in `brief.json` limits the work to those sections, and the rest stays untouched. A card may list `addsText` and `replacesText` (`{ "from": "text on the page", "to": "new text" }`); those are the only text changes a pass may make. Before anything is applied the run prints the degree, direction, intent and cards; at a terminal it asks `Apply these passes? [y/N]` and stops with nothing changed unless you say yes, printing the command that goes on (`--brief /brief.json --yes`). Agents and CI get the summary and the run goes on. For a page that only exists once a command draws it, such as a CMS module behind a sign-in written into static HTML: `redesign module-1.html --serve dist --render "php artisan module:export 1"`. `--serve ` serves that folder on 127.0.0.1 at a free port (no listing, nothing outside it) and the page is a path inside it; `--render ""` runs before the first measurement and after every pass, after `--build`, and a failure throws the pass away as a failed build does. `--build-minutes ` sets the time limit for both (default 10). Work that is thrown away stays within reach. Every run ends with `compare.html` in the `--out` folder: each pass's before and after screenshots side by side, whether it was kept or thrown away and why. A thrown-away pass leaves `pass-N-.rejected.patch`, and `npx @enmera/ai-design-check redesign apply ` puts it into the working tree (3-way when it no longer fits as it is; a patch that does not apply cleanly changes nothing) and prints the files and the undo command. The word check counts only reading text: text under `aria-hidden="true"`, or in a positioned layer that takes no clicks (`pointer-events: none`, behind the content), is decoration a pass may replace. A card whose idea replaces, removes or rewrites visible text has to list it in `addsText` or `replacesText`, or the study is sent back. The pass prompts carry the `shot` command for the page (the served address with `--serve`) and, with `--build` or `--render`, the command that draws it again, so the agent looks at its own work before it reports. When a test forbids what a card asks for, the agent changes that test and names it; tests a pass changed are listed apart in the log, the summary and `result.json` (`testsChanged`). ## Mobile apps Point it at the app folder. It reads SwiftUI and Jetpack Compose: spacing off the scale (4 pt unless `spacing` is set; `.padding(13)`, `10.dp`), radii off the scale, fixed text that ignores Dynamic Type, heavy headings, purple gradients, `sparkles` for AI, emoji in strings, Title Case labels, heavy shadows, big blurs, looping animations, and tap targets under 44 pt / 48 dp. ```bash npx @enmera/ai-design-check Cebbin/Views ```

The Cebbin iOS home screen before and after

Our iOS app Cebbin, live on the App Store, on the simulator with the same data. Watch the 16 fixes, each with the SwiftUI line behind it, or the first run from 23 findings to 0.

## Use it in your project ### Give your agent the rules The package ships two skills, both installed by `npx skills add enmerasoftware/ai-design-check`: - **ai-design-check** has the agent read the rules before touching a screen and run the checker afterwards. - **ai-design-fix** repairs a screen that already looks generated. It measures gaps and radii, writes a four-line brief (job, claim, proof, keep), works through the screen in order of harm, and reports before and after. It never removes content to lower the count, and never silences a finding without a reason. In Claude Code the same skills install as a plugin: `/plugin marketplace add enmerasoftware/ai-design-check`, then `/plugin install ai-design-check@ai-design-check`. In Codex: `codex plugin marketplace add enmerasoftware/ai-design-check`. Without skills, point your agent's instructions (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules`) at `node_modules/@enmera/ai-design-check/RULES.md`. ### Show findings right after each edit A hook checks the file an agent just changed and hands the findings back to it. In Claude Code's `.claude/settings.json`: ```json { "hooks": { "PostToolUse": [ { "matcher": "Edit|Write|MultiEdit", "hooks": [{ "type": "command", "command": "npx -y @enmera/ai-design-check hook" }] } ] } } ``` The same command works for any agent hook that passes `tool_input.file_path` or `file_path` as JSON on stdin. A clean file exits silently; findings exit 2 on stderr. ### Add it to CI ```yaml - run: npx @enmera/ai-design-check ``` It exits 1 on errors, and on warnings too with `--strict`. It exits 2 when nothing could be checked or an option or the config is wrong, so a mistyped path cannot pass. `--json` prints for machines, and `--format github` writes pull request annotations. ### Start from an existing project Record today's findings, and from then on only new ones are reported: ```bash npx @enmera/ai-design-check --write-baseline ``` Ignore one place, always with a reason after `--`. An ignore without a reason does not count: ```tsx {/* ai-design-check-ignore-next-line type-scale -- hero display size, see DESIGN.md */} // ai-design-check-ignore-file use-shared-components -- this file is the Button component ``` Among JSX children the comment goes in braces, as above. Directly after `=> (` or `return (` there are no children yet, so `{/* */}` there breaks the JSX: use a `//` line comment instead. ```tsx {items.map((item) => ( // ai-design-check-ignore-next-line type-scale -- hero display size, see DESIGN.md

{item.title}

))} ``` On a running page (`scan`), mark the element instead. A finding on it or inside it is not reported for the rules listed, separated by spaces; `*` or an empty value means every rule: ```html
…
…
``` ## Commands ### `inventory`: one look per element ``` Buttons 726 uses · 149 different looks · 147 without a shared component 115×