Skip to content
Back to search

ai-design-check

Design rules and a zero-dependency checker for interfaces built with AI coding agents. English and Turkish.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/enmerasoftware--ai-design-check/badge.svg)](/listings/enmerasoftware--ai-design-check)

HTML

<a href="/listings/enmerasoftware--ai-design-check"><img src="/api/listings/enmerasoftware--ai-design-check/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

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.

.claude-plugin/marketplace.json · Manifest · 17 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "ai-design-check",
  3. "owner": {
  4. "name": "Enmera Software",
  5. "email": "info@enmera.com.tr"
  6. },
  7. "plugins": [
  8. {
  9. "name": "ai-design-check",
  10. "source": "./plugin",
  11. "description": "Find and fix what makes an AI-built interface look generated, on the web and in mobile apps."
  12. }
  13. ],
  14. "metadata": {
  15. "description": "Design rules and a repair skill for interfaces built with AI agents."
  16. }
  17. }
README.md · README · 457 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # ai-design-check
  2. **Find what makes an AI-built interface look generated, fix it, and keep it from coming back.**
  3. [![npm version](https://img.shields.io/npm/v/@enmera/ai-design-check)](https://www.npmjs.com/package/@enmera/ai-design-check)
  4. [![license: MIT](https://img.shields.io/npm/l/@enmera/ai-design-check)](LICENSE)
  5. [Türkçe](README.tr.md) · [日本語](README.ja.md)
  6. For anyone building with Claude Code, Cursor or Codex: 147 design rules, a checker with no dependencies and no API key, and
  7. an agent skill that repairs the screen. It reads web projects (React, Vue, Svelte, Laravel Blade, HTML; Tailwind, Bootstrap or plain
  8. CSS) and SwiftUI, Jetpack Compose, Flutter and React Native apps. Finding needs no agent, and neither do the mechanical fixes.
  9. ## Start in three steps
  10. **1. Check your project.**
  11. ```bash
  12. npx @enmera/ai-design-check
  13. ```
  14. ```
  15. Accessibility (1)
  16. src/pages/dashboard.tsx
  17. 31 error Never remove the focus ring without a replacement: outline-none focus-ring-removed
  18. Style (3)
  19. src/pages/dashboard.tsx
  20. 42 error Font sizes from the scale only: text-[10px] type-scale
  21. 88 warn No tracked uppercase labels: tracking-wide uppercase no-decorative-uppercase
  22. lang/tr.json
  23. 812 error Translation in Title Case: "Sıra Takibi" (Rank tracking) sentence-case
  24. 1 accessibility, 3 style: 3 errors, 1 warnings, 0 notes.
  25. ```
  26. **2. Fix what has one answer, with no agent.**
  27. ```bash
  28. npx @enmera/ai-design-check --fix --dry-run
  29. ```
  30. This lists the changes; drop `--dry-run` to make them. Spacing and corners move to the nearest step of your scale, and very
  31. heavy type becomes bold. Tap sizes, colours, emoji, words and hierarchy stay in the report, since they take a decision.
  32. Add `--nearest-type` to move `text-[Npx]` sizes to the nearest theme size as well (`lg:text-[64px]` → `lg:text-6xl`).
  33. **3. Let your agent fix the rest.**
  34. ```bash
  35. npx skills add enmerasoftware/ai-design-check
  36. ```
  37. Then ask: *"fix the design of this screen"*. The agent measures the screen, writes a short brief from your product, repairs
  38. it, and shows the count before and after. Features, data and words stay.
  39. <p align="center">
  40. <img src="examples/before-after-web.webp" width="860" alt="The same dashboard before and after: 266 findings down to 0">
  41. </p>
  42. <p align="center"><sub>The same dashboard, before and after. Open <a href="examples/dashboard.html">before</a> and <a href="examples/dashboard.fixed.html">after</a>, or watch <a href="examples/story-dashboard.mp4">the video</a>.</sub></p>
  43. ## What's in the package
  44. | Tool | What it answers | Run it |
  45. |---|---|---|
  46. | **Checker** | What is wrong, in which file and on which line? | `npx @enmera/ai-design-check` |
  47. | **Fix skill** | Can an agent repair this screen and prove it? | `npx skills add enmerasoftware/ai-design-check` |
  48. | **`scan`** | What does the running page really show? Contrast, sizes, what covers what, script errors | `npx @enmera/ai-design-check scan http://localhost:3000` |
  49. | **`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` |
  50. | **`inventory`** | How many different buttons, inputs, headings and cards do we have? | `npx @enmera/ai-design-check inventory` |
  51. | **`narrow`** | What breaks on a phone or in a long language? | `npx @enmera/ai-design-check narrow page.html` |
  52. | **`system`** | What fonts, type and colours should a new product start with? | `npx @enmera/ai-design-check system --brand "#1E5A63"` |
  53. | **`story`** | Can I share the change as a video? | `npx @enmera/ai-design-check story before.html after.html` |
  54. ## What it catches
  55. 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
  56. 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).
  57. | Area | Examples |
  58. |---|---|
  59. | Accessibility | Focus rings never removed without a replacement, icon-only buttons have a name, tap targets |
  60. | Phone browsers | Pinch zoom stays on, 16 px text in fields, `dvh` beside fixed `100vh`, nothing hidden until hover |
  61. | Type and shape | One type scale with 11 px as the floor, one radius per level, no cards inside cards |
  62. | Writing and copy | Sentence case, no tracked uppercase labels, no buzzwords, buttons that say what they do, errors that say what to do |
  63. | Components | Buttons and inputs from shared components, no outside styling, repeated markup becomes a component |
  64. | Layout | Spacing on a 4 px grid with one gap per level, wide tables span the page, room for each cell on a phone |
  65. | Visual language | Line icons instead of emoji, no gradient text or purple gradients, no side stripes, no coloured shadows, glow only in charts |
  66. | Motion | No `transition-all`, no bounce, reduced motion respected, pulse only for live data, answers within 300 ms, no endless loops |
  67. | Data | Numbers carry their comparison, tabular numerals, empty states |
  68. | Localisation | Locale-aware case changes (Turkish i/İ), numbers through the formatter, real plurals |
  69. | Selectors and navigation | One selector language, menu grouped by job, moved URLs redirect |
  70. The rules come from screens we shipped at [Enmera](https://enmera.com.tr) and [Searvia](https://searvia.com): what read as
  71. generated, what broke at narrow widths, what people did not understand. We then compared them with 16 highly rated
  72. dashboard designs. Method and findings: [RESEARCH.md](RESEARCH.md).
  73. **How well it tells them apart.** [BENCHMARK.md](BENCHMARK.md) runs every rule on 72 pages that four Claude and two
  74. GPT models generated, in Tailwind and in Bootstrap, and on 34 sites people designed. Some rules separate the two clearly: a
  75. 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
  76. human site does. GPT and Claude leave different marks: GPT pages set small text on every page and crush heading letter
  77. spacing on 88% of them. Others no longer tell, purple gradients among them, and their severity follows that evidence.
  78. ## The running page and the redesign
  79. `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
  80. show: real contrast, sizes, what covers what, broken images, script errors, content that never appears. It reads every colour
  81. Chrome computes, Tailwind 4's `oklch()` included, and the habits of a generated page: an accent word in the headline,
  82. coloured shadows, an arrow on every call to action, lists strung on middle dots, a badge pill above the headline.
  83. 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
  84. 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
  85. `AI_DESIGN_CHECK_COOKIE` and `AI_DESIGN_CHECK_HEADERS` to keep them out of shell history and CI logs. Both go only to the
  86. page's own origin, never to the other hosts it loads from. `--allow-redirect` and
  87. `--allow-status 404` check such a page on purpose. Several URLs are scanned in one run. Add `--format github`
  88. for pull requests. With `designSystem` in the config (`fonts`, `sizes`, `radii`, `colors`) it also names what drifts.
  89. To check one part of a page, such as a CMS module rendered inside the app's own shell, pass
  90. `--scope "[data-block-type=module-1]"`: only what is inside a match is checked, and `redesign` measures and plans only that
  91. part. `--ignore "nav"` leaves a part out. Both work for `scan`, `narrow` and `redesign` and can be given more than once;
  92. several scopes are one area. A scope that matches nothing stops the run with exit 2 instead of passing as clean. Sideways
  93. scrolling caused outside the scope is not reported; script errors are, since they belong to the whole page. Text under `aria-hidden="true"`,
  94. such as a faded code rain behind the headline, is decoration: contrast, size and the other reading rules leave it alone,
  95. while the visual tells (gradients, glows, endless loops) still look at it.
  96. `redesign` is the one part that needs your agent (Claude Code or Codex), because deciding what a page should show takes
  97. judgement. The agent studies the screenshots, the code and the subject, and writes one card per section: what it says, what
  98. is wrong, the idea that comes from its own content, the colours it uses from your site. Those cards are checked against the
  99. measured page. Then the numbered fixes and the cards are applied pass by pass on a new git branch, and a pass that loses
  100. content, adds rule errors or looks worse is thrown away. `--plan` stops after the cards so you can read and edit them;
  101. `--brief` builds them. It starts only on a clean working tree (commit or stash first), and Ctrl-C puts back the pass in
  102. progress.
  103. Before any card the study decides how much to change: `heavy` (many tells, rebuilt section by section), `polish` (mostly
  104. designed: at most two sections change the look, each on a measured tell, and bigger ideas become suggestions) or `none`
  105. (it works; a few refinements are suggested and nothing is built). Then it writes a direction from your product: what it is
  106. in one sentence, its character in two or three concrete words (not clean, modern, sleek, minimal or premium), the world
  107. it belongs to, the one or two moments on the screen that carry the richness, and one signature detail. Each card says
  108. whether it changes the look, and what a visitor will see differently; `--plan` and `BRIEF.md` label every card "changes
  109. 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
  110. show the proof of its claim. After the craft pass the visual check asks, card by card, whether that change is in the after
  111. screenshot; a card that looks the same gets one more try, then the pass is thrown away. A `brief.json` from an earlier
  112. version still works with `--brief`, as `heavy` with no direction.
  113. `--in-place` makes no branch and no commits, and runs on a tree with uncommitted work (yours, or another session's): a pass
  114. that is thrown away goes back to exactly the state before it, your edits included, and a kept pass stays as uncommitted
  115. changes with its patch saved, so `git apply -R <patch>` undoes it; the run ends with the changed files and the undo
  116. commands, newest first. `--files "resources/views/home.blade.php,resources/css/**"` limits every pass to those paths or
  117. globs: a pass that changes any other file is thrown away. `--out <dir>` puts the plan, screenshots, logs and patches
  118. somewhere else (default `.ai-design-check/redesign`, which git ignores; a folder outside the project works too). For a
  119. page behind a sign-in when you would rather not hand over a cookie, save it and pass the file: `redesign ./page.html` (or
  120. `--html page.html`). With `--build "<command>"` the passes edit your sources and the command writes the file again; without
  121. 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.
  122. The study starts from what you already know. A `PRODUCT.md` in the project root (purpose, audience, voice, what to
  123. avoid, rivals) and a `DESIGN.md` (the visual system you keep) go into the study and the craft prompt, quoted as your notes;
  124. `--product <file>` and `--design <file>` point elsewhere. Without a `PRODUCT.md` the study writes a draft to the `--out`
  125. folder from the README, the package description and the pages, and the run says in one line to review it and move it to
  126. the root; the tool never writes there itself. `--intent "<text>"` says what you want from this run: it leads the study and
  127. the cards, and is kept in `brief.json`. `--degree heavy|polish|none` chooses how far the run goes instead of leaving it
  128. to the study, which then has to write that degree (a `--brief` brief takes it). Heavy rebuilds every section that is not
  129. kept, composes the first screen as one picture with a real product surface, turns repeated identical cards into
  130. content-specific pictures and keeps the logo, brand colour, fonts, words and section order; its cards may use tints and
  131. shades of the site's colours (the same hue within 8 degrees, or a neutral grey), while polish and none use exactly the
  132. site's colours. `--images openai|gemini` lets cards ask for generated photos or illustrations (a hero scene,
  133. one photo per sector in place of identical icon cards): at most 1 per card and `--images-max` per run (default 6, up to
  134. 12). The key is read from `OPENAI_API_KEY` or `GEMINI_API_KEY` only and never printed; a missing one stops the run
  135. before any agent starts. After the study the run lists each image with an estimated cost (an estimate: check your
  136. provider's pricing) and generates nothing without a yes at the terminal or `--yes`. The images go to
  137. `<out>/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`,
  138. `competitors`, `avoid`, or one of your own) reaches both prompts. Each card that changes the look picks a layout from its
  139. content (`split`, `product`, `photo`, `place`, `editorial`, `statement`, `collage`, or `centred` for a short section with
  140. no visual) with a line saying why; a centred hero with a visual, or two changing sections side by side with one layout, is
  141. sent back. `"only": ["exact heading"]` in `brief.json` limits the work to those sections, and the rest stays untouched. A
  142. card may list `addsText` and `replacesText` (`{ "from": "text on the page", "to": "new text" }`); those are the only text
  143. changes a pass may make. Before anything is applied the run prints the degree, direction, intent and cards; at a terminal
  144. it asks `Apply these passes? [y/N]` and stops with nothing changed unless you say yes, printing the command that goes on
  145. (`--brief <out>/brief.json --yes`). Agents and CI get the summary and the run goes on.
  146. For a page that only exists once a command draws it, such as a CMS module behind a sign-in written into static HTML:
  147. `redesign module-1.html --serve dist --render "php artisan module:export 1"`. `--serve <dir>` serves that folder on
  148. 127.0.0.1 at a free port (no listing, nothing outside it) and the page is a path inside it; `--render "<command>"` runs
  149. before the first measurement and after every pass, after `--build`, and a failure throws the pass away as a failed build
  150. does. `--build-minutes <n>` sets the time limit for both (default 10).
  151. Work that is thrown away stays within reach. Every run ends with `compare.html` in the `--out` folder: each pass's before
  152. and after screenshots side by side, whether it was kept or thrown away and why. A thrown-away pass leaves
  153. `pass-N-<name>.rejected.patch`, and `npx @enmera/ai-design-check redesign apply <patch>` puts it into the working tree
  154. (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
  155. undo command. The word check counts only reading text: text under `aria-hidden="true"`, or in a positioned layer that
  156. takes no clicks (`pointer-events: none`, behind the content), is decoration a pass may replace. A card whose idea replaces,
  157. removes or rewrites visible text has to list it in `addsText` or `replacesText`, or the study is sent back. The pass
  158. prompts carry the `shot` command for the page (the served address with `--serve`) and, with `--build` or `--render`, the
  159. command that draws it again, so the agent looks at its own work before it reports. When a test forbids what a card asks
  160. for, the agent changes that test and names it; tests a pass changed are listed apart in the log, the summary and
  161. `result.json` (`testsChanged`).
  162. ## Mobile apps
  163. 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
  164. off the scale, fixed text that ignores Dynamic Type, heavy headings, purple gradients, `sparkles` for AI, emoji in strings,
  165. Title Case labels, heavy shadows, big blurs, looping animations, and tap targets under 44 pt / 48 dp.
  166. ```bash
  167. npx @enmera/ai-design-check Cebbin/Views
  168. ```
  169. <p align="center">
  170. <img src="examples/before-after-ios.webp" width="520" alt="The Cebbin iOS home screen before and after">
  171. </p>
  172. <p align="center"><sub>Our iOS app Cebbin, live on the App Store, on the simulator with the same data. <a href="examples/redesign-cebbin-swiftui.mp4">Watch the 16 fixes</a>, each with the SwiftUI line behind it, or <a href="examples/story-cebbin-swiftui.mp4">the first run</a> from 23 findings to 0.</sub></p>
  173. ## Use it in your project
  174. ### Give your agent the rules
  175. The package ships two skills, both installed by `npx skills add enmerasoftware/ai-design-check`:
  176. - **ai-design-check** has the agent read the rules before touching a screen and run the checker afterwards.
  177. - **ai-design-fix** repairs a screen that already looks generated. It measures gaps and radii, writes a four-line brief (job,
  178. claim, proof, keep), works through the screen in order of harm, and reports before and after. It never removes content
  179. to lower the count, and never silences a finding without a reason.
  180. In Claude Code the same skills install as a plugin: `/plugin marketplace add enmerasoftware/ai-design-check`, then
  181. `/plugin install ai-design-check@ai-design-check`. In Codex: `codex plugin marketplace add enmerasoftware/ai-design-check`.
  182. Without skills, point your agent's instructions (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules`) at
  183. `node_modules/@enmera/ai-design-check/RULES.md`.
  184. ### Show findings right after each edit
  185. A hook checks the file an agent just changed and hands the findings back to it. In Claude Code's `.claude/settings.json`:
  186. ```json
  187. {
  188. "hooks": {
  189. "PostToolUse": [
  190. { "matcher": "Edit|Write|MultiEdit", "hooks": [{ "type": "command", "command": "npx -y @enmera/ai-design-check hook" }] }
  191. ]
  192. }
  193. }
  194. ```
  195. The same command works for any agent hook that passes `tool_input.file_path` or `file_path` as JSON on stdin. A clean file
  196. exits silently; findings exit 2 on stderr.
  197. ### Add it to CI
  198. ```yaml
  199. - run: npx @enmera/ai-design-check
  200. ```
  201. 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
  202. is wrong, so a mistyped path cannot pass. `--json` prints for machines, and `--format github` writes pull
  203. request annotations.
  204. ### Start from an existing project
  205. Record today's findings, and from then on only new ones are reported:
  206. ```bash
  207. npx @enmera/ai-design-check --write-baseline
  208. ```
  209. Ignore one place, always with a reason after `--`. An ignore without a reason does not count:
  210. ```tsx
  211. {/* ai-design-check-ignore-next-line type-scale -- hero display size, see DESIGN.md */}
  212. // ai-design-check-ignore-file use-shared-components -- this file is the Button component
  213. ```
  214. Among JSX children the comment goes in braces, as above. Directly after `=> (` or `return (` there are no children
  215. yet, so `{/* */}` there breaks the JSX: use a `//` line comment instead.
  216. ```tsx
  217. {items.map((item) => (
  218. // ai-design-check-ignore-next-line type-scale -- hero display size, see DESIGN.md
  219. <h2 className="text-[56px]">{item.title}</h2>
  220. ))}
  221. ```
  222. On a running page (`scan`), mark the element instead. A finding on it or inside it is not reported for the rules listed,
  223. separated by spaces; `*` or an empty value means every rule:
  224. ```html
  225. <div class="faq" data-ai-design-check-ignore="no-invisible-content text-not-covered">…</div>
  226. <section data-ai-design-check-ignore="*">…</section>
  227. ```
  228. ## Commands
  229. ### `inventory`: one look per element
  230. ```
  231. Buttons 726 uses · 149 different looks · 147 without a shared component
  232. 115× <Button variant=outline size=sm> src/pages/projects/show.tsx:212
  233. 9× <button> bg-brand-400 font-semibold px-4 py-2 rounded-full text-on-brand text-sm src/pages/home.tsx:91
  234. Headings 229 uses · 69 different looks · 229 without a shared component
  235. ```
  236. Use it before a cleanup to see the drift and afterwards to see it gone. Layout classes are ignored, so two copies that differ
  237. only in where they sit count as one look.
  238. ### `narrow`: phones and long languages
  239. ```bash
  240. npx @enmera/ai-design-check narrow examples/narrow-de.html --width 320
  241. ```
  242. Renders the page in your Chrome at phone and desktop width and reports what only a rendered page shows: sideways scrolling
  243. and what causes it, text cut off, text shrunk to fit, and content hidden on phones. Run it with your longest language; German
  244. labels are often 30–40 % longer than English. Try [the broken example](examples/narrow-de.html) and
  245. [the fixed one](examples/narrow-de.fixed.html).
  246. Add `--stress` to run it again with worst-case data: long names, large numbers and text 40 % longer. It tests the layout;
  247. grammar such as "1 member" still needs a look at the screen with real data.
  248. ### `system`: a design system from your brand
  249. ```bash
  250. npx @enmera/ai-design-check system --character calm --brand "#1E5A63" --kind app --out design-system
  251. ```
  252. For a new product or one with no tokens. Give it a character (`calm`, `precise`, `friendly`, `warm`, `bold`, `editorial`,
  253. `luxurious`, `playful`, `technical`, `trustworthy`), a brand colour and a kind of screen (`dashboard`, `app`, `marketing`,
  254. `reading`).
  255. | You get | Details |
  256. |---|---|
  257. | Fonts | UI, display, numbers and code, from a library of 50. `fonts --character calm` lists the options |
  258. | Type scale | Eight roles that map to Dynamic Type and Material 3 |
  259. | Colours | Light and dark; every text and background pair passes WCAG 2 at 4.5:1, status pills and buttons included |
  260. | Shape | A 4 px spacing scale, radii that nest, control heights, card padding |
  261. | Files | `tokens.css`, Tailwind `theme.css`, Bootstrap `bootstrap.css` and `_variables.scss`, `tokens.json`, `DesignSystem.swift`, `DesignSystem.kt`, `preview.html` |
  262. With Bootstrap 5.3, link `bootstrap.css` after Bootstrap's own CSS: light is the default and dark applies under
  263. `data-bs-theme="dark"`. It also replaces the blue Bootstrap compiles into fields, checks, menus, pagination and the rest. A
  264. build from source imports `_variables.scss` before Bootstrap.
  265. ### `shot`: look at a page
  266. ```bash
  267. npx @enmera/ai-design-check shot http://localhost:3000 --width 390 --out look.png --full
  268. ```
  269. One screenshot as Chrome draws it, and nothing changed: for an agent to look at its own work after an edit. `--full` takes
  270. the whole page, `--scope` clips to that part and `--ignore` hides one; `--cookie` and `--header` work as for `scan`.
  271. ### `story`: a before/after video
  272. ```bash
  273. npx @enmera/ai-design-check story screen.before.html screen.html --out story.mp4 --music track.mp3 --still frame.png
  274. ```
  275. A square 12 second video: every finding marked one by one, a wipe to the new screen while the count falls, and an end card.
  276. It takes files or URLs, and needs only your Chrome and ffmpeg.
  277. `--style swarm` tells the change another way: labelled agents (layout, type, colour) fly over the new screen, frame
  278. each block with its live size, type the headings and text in and build the rest, while the count falls
  279. ([example](examples/story-dashboard-swarm.mp4)).
  280. ### Other commands
  281. ```bash
  282. npx @enmera/ai-design-check rules # list the rules (--tr for Turkish)
  283. npx @enmera/ai-design-check init # write a config with the defaults
  284. ```
  285. <details>
  286. <summary><strong>Configuration</strong></summary>
  287. `ai-design-check.json` (or `.design-rules.json`) in the project root:
  288. ```json
  289. {
  290. "include": ["resources/js", "lang"],
  291. "ignore": ["resources/js/vendor/**"],
  292. "i18n": { "files": ["lang/*.json"], "keysAreSource": true, "framework": ["Reset Password"] },
  293. "properNouns": ["Brand Studio", "Core Web Vitals", "Privacy Policy"],
  294. "componentDirs": ["**/components/ui/**"],
  295. "components": { "button": "Button", "input": "Input" },
  296. "sharedComponents": ["Button", "Badge", "Input", "Card"],
  297. "looks": { "badge": "StatusBadge", "card": "Tile or SectionCard", "heading": "Heading", "link": "LinkButton" },
  298. "rules": { "pulse-for-live-only": "off" },
  299. "spacing": { "base": 6 },
  300. "allow": {
  301. "type-scale": ["src/marketing/hero.tsx:text-[44px]"],
  302. "glow-in-charts-only": ["src/components/charts/**"]
  303. }
  304. }
  305. ```
  306. | Key | Meaning |
  307. |---|---|
  308. | `i18n.files` | JSON dictionaries. With `keysAreSource` the keys are the English source and are checked too. `framework` lists keys you cannot rename |
  309. | `properNouns` | Names that keep their capitals |
  310. | `allow` | Per rule, `"glob"` or `"glob:exact match"` |
  311. | `spacing` | The spacing scale: `6`, `[4, 6, 8, 12]` or `{ "base": 4, "values": [18], "native": { "base": 8 } }`. See below |
  312. | `rules` | `"off"`, `"info"`, `"warn"` or `"error"` per rule id |
  313. | `componentDirs` | Where raw `<button>` and `<input>` are allowed |
  314. | `components` | Raw element → the shared component to use instead |
  315. | `sharedComponents` | Components whose look comes from props; `className` may only place them |
  316. | `looks` | The component that owns each hand-written look. `false` turns one kind off |
  317. **Spacing scale.** `spacing-scale` judges a value against the first of these it can read, and the report names which one it
  318. used:
  319. 1. `spacing` in the config file.
  320. 2. Tailwind 4 `@theme`: `--spacing` is the grid, `--spacing-*` add steps.
  321. 3. `tailwind.config.*`, read as text and never run: `theme.spacing` replaces the steps, `theme.extend.spacing` adds to the
  322. 4 px grid. A function, a variable, a spread or a preset cannot be read that way.
  323. 4. Bootstrap's `$spacer` and `$spacers` in your SCSS, read as text: their steps join the 4 px grid.
  324. 5. `:root` variables: `--spacing` is the grid, `--space-*` and `--spacing-*` add steps to the 4 px grid and never remove any.
  325. 6. The 4 px grid.
  326. A source that exists but cannot be read (`calc()`, `clamp()`, two files that disagree, a root font size that is not one
  327. number) leaves the 4 px grid and a note in the report. It is not guessed, and later sources are not tried. Set `spacing` to
  328. decide it yourself. With a list and no `base`, margins, paddings and gaps must be on the list; widths, heights and offsets
  329. only have to fit the list's common divisor.
  330. App code (SwiftUI, Compose, Flutter, React Native) uses `spacing` from the config file (`native` when it differs from the web)
  331. or 4 pt/dp. It reads nothing else: constants in app code have no shared place to look, and a web theme next to an app says
  332. nothing about the app.
  333. </details>
  334. <details>
  335. <summary><strong>What the checker reads</strong></summary>
  336. `.tsx`, `.jsx`, `.vue`, `.svelte`, `.html`, Blade, CSS and SCSS, i18n JSON, SwiftUI (`.swift`) and Jetpack Compose (`.kt`). It
  337. runs on plain Node 20+. Class rules read class strings only (`class`, `className`, `cn()`, `clsx()`, `cva()`, `twMerge()`), so
  338. comments and copy do not match; they know Tailwind's classes and Bootstrap's. CSS rules read stylesheets, `<style>` blocks and
  339. `style=""` attributes declaration by declaration. A framework's own stylesheet copied into the project (Bootstrap, Tailwind's
  340. output and others, known by their licence banner) is skipped: its values are the framework's choices, not yours.
  341. </details>
  342. <details>
  343. <summary><strong>Adding a rule</strong></summary>
  344. Rules live in [`rules.json`](rules.json): `id`, `area`, `severity`, and `title`, `rule`, `why` and `fix` in `en` and `tr`, plus an
  345. optional `check`:
  346. - `class`: a pattern on class strings (or a list of them), with `unless`, `with`, `exceptElements`, `unlessBefore`, and `css`:
  347. a pattern on stylesheets, or entries read declaration by declaration (`property`, `value`, `scale`, `gradient` with `hue`,
  348. `selector`, `unless`, `unlessRule`)
  349. - `native`: one pattern per platform under `swift` and `kt`, with `notMultipleOf`, `min`, `max`, `unlessBefore`, `unlessAfter`
  350. and `onlyIf`
  351. - `regex`: a pattern on code with comments excluded, with `flags` and `files`
  352. - or a structural check
  353. Run `npm run docs` to regenerate RULES.md and RULES.tr.md, and `npm test` before opening a pull request.
  354. </details>
  355. ## License
  356. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.