@enmera/ai-design-check

Türkçe

Finds and fixes what makes interfaces built with AI coding agents (Claude Code, Cursor, Codex) look generated:
74 design rules, a zero-dependency checker that marks every finding, and an agent skill that fixes the screen and
proves it by checking again. For dashboards, admin panels, SaaS screens and landing pages.

npx @enmera/ai-design-check                    # check the project (or: ai-design-check src lang)
npx skills add enmerasoftware/ai-design-check  # the rules and the fix skill for your agent

Then ask your agent to "fix the design of this screen". It measures, proposes a direction from your product, fixes
spacing, colour, icons, copy, type, layout, components and motion in passes, and shows the count before and after.
Fixing is what most tools stop at; the checker keeps the next agent edit from bringing the slop back.

The rules come from real screens shipped by Enmera and Searvia:
what read as "generated", what broke at narrow widths, what people did not understand. They were then compared with 16
high-rated dashboard designs on Dribbble and Behance: the patterns the strongest work shared became rules (stat card
anatomy, one card header, one highlighted chart series, flat buttons, surface steps instead of shadows), and where the
popular shots themselves show the tells (half of them open with "Welcome back 👋") the rule stayed. Method and
findings: RESEARCH.md. Each rule says what,
why and how to fix it, in English and Turkish.

npx @enmera/ai-design-check inventory  # how many different buttons, inputs, headings, badges, cards you have
npx @enmera/ai-design-check rules      # list the rules (--tr for Turkish)
npx @enmera/ai-design-check init       # write a config with the defaults
npx @enmera/ai-design-check story before.html after.html  # a square before/after video, like the one above

No LLM, no API key, no dependencies: it catches measurable defects (a focus ring removed, an icon button with no
name, a font size off the scale, spacing off the 4 px grid, a raw <button> next to your Button, emoji as icons,
"Welcome back, Alex!", a Turkish toUpperCase()), and leaves taste to you and the fix skill.

What it covers

The full list with reasons: RULES.md.

Mobile apps

The same rules read SwiftUI and Jetpack Compose: spacing off the 4 pt grid (.padding(13), 10.dp), radii off the
scale, fixed .system(size:) text that ignores Dynamic Type, .heavy and FontWeight.Black headings, purple
gradients, sparkles for AI, emoji in strings, Title Case labels, exclamation copy, heavy shadows, big blurs and
looping animations. Point it at the app folder:

npx @enmera/ai-design-check Cebbin/Views

A real run on the Cebbin iOS home screen: 23 findings to 0 in four passes,
each frame taken from the simulator after the code change.

The checker

Plain Node (20+), no dependencies. It reads .tsx, .jsx, .vue, .svelte, .html, Blade, CSS and i18n JSON, and native app code:
SwiftUI (.swift) and Jetpack Compose (.kt). It reports rule ids with file and line. Rules that need judgement (layout, selectors, empty states) are marked review
and are left to people and agents.

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

2 errors, 1 warning, 0 notes.

Exit code 1 on errors (--strict: also on warnings). --json for machines, --format github for pull request
annotations. Class rules read class strings only (class, className, cn(), clsx(), cva(), twMerge()), so
comments and copy do not match.

One look per element: inventory

Buttons  726 uses · 149 different looks · 147 without a shared component
   115×  <Button variant=outline size=sm>                       src/pages/projects/show.tsx:212
     9×  <button> bg-brand-400 font-semibold px-4 py-2 rounded-full text-on-brand text-sm   src/pages/home.tsx:91
Headings  229 uses · 69 different looks · 229 without a shared component

Layout classes (width, margin, position) are ignored, so two copies that differ only in where they sit count as one
look. Use it before a cleanup to see the drift and after to see it gone. repeated-markup reports the same long class
list repeated three or more times, with every place, so it can become one component.

Existing projects: baseline and ignores

npx @enmera/ai-design-check --write-baseline   # record today's findings in .ai-design-check-baseline.json
npx @enmera/ai-design-check                    # from now on only new findings are reported

Ignore one place, always with a reason after -- (an ignore without a reason is not honoured):

{/* 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

Configuration

ai-design-check.json (or the dotfile .design-rules.json) in the project root:

{
    "include": ["resources/js", "lang"],
    "ignore": ["resources/js/vendor/**"],
    "i18n": { "files": ["lang/*.json"], "keysAreSource": true, "framework": ["Reset Password"] },
    "properNouns": ["Brand Studio", "Core Web Vitals", "Privacy Policy"],
    "componentDirs": ["**/components/ui/**"],
    "components": { "button": "Button", "input": "Input" },
    "sharedComponents": ["Button", "Badge", "Input", "Card"],
    "looks": { "badge": "StatusBadge", "card": "Tile or SectionCard", "heading": "Heading", "link": "LinkButton" },
    "rules": { "pulse-for-live-only": "off" },
    "allow": {
        "type-scale": ["src/marketing/hero.tsx:text-[44px]"],
        "glow-in-charts-only": ["src/components/charts/**"]
    }
}

• i18n.files: JSON dictionaries. With keysAreSource the keys are the English source text and are checked too.
  framework lists keys owned by a framework that you cannot rename.
• properNouns: names that keep their capitals ("Google Business Profile" is recognised from the brand list).
• allow: per rule, "glob" or "glob:exact match".
• rules: "off", "info", "warn" or "error" per rule id.
• componentDirs: where raw <button>/<input> are allowed (the components themselves).
• components: raw element → the shared component to use instead. sharedComponents: components whose look comes
  from props; className on them may only place them (width, margin, grid position).
• looks: the component that owns each hand-written look found by use-shared-looks (a span styled as a badge, a
  div styled as a card, a heading with size classes, a link styled as a button). false turns one kind off.

In CI

- run: npx @enmera/ai-design-check

For AI coding agents

The package ships two skills:

• ai-design-check tells an agent to read the rules before touching UI and to run the checker after.
• ai-design-fix fixes a screen that already looks generated: measure, pick a direction from the product (who,
  world, one accent, one moment), fix in passes across the whole screen, then check again and report before → after.
  It keeps features, data and content; it never silences a finding without a reason.

npx skills add enmerasoftware/ai-design-check

Phones and long languages: narrow

npx @enmera/ai-design-check narrow examples/narrow-de.html --width 320

Renders the page at phone width and at desktop width in your Chrome and reports what only a rendered page shows:
the page scrolling sideways (and which elements push it), text cut off, text made smaller to fit, and content shown on
desktop but hidden on phones. Run it with your longest locale; German labels are often 30–40 % longer than English.
examples/narrow-de.html breaks all four at 320 px,
examples/narrow-de.fixed.html fixes them without hiding content or shrinking text.

Before/after video: story

npx @enmera/ai-design-check story screen.before.html screen.html --out story.mp4 --music track.mp3 --still frame.png

A square 12 second video for sharing: the before screen with every finding marked one by one, a wipe to the after
screen while the count falls, and an end card. --music lays a track under it, cut to length and faded out. Files or URLs. It drives your installed Chrome over the DevTools
protocol and encodes with ffmpeg; nothing to install from npm. Try it on examples/dashboard.html
and examples/dashboard.fixed.html.

Make the agent see findings right after each edit with a hook. Claude Code, in .claude/settings.json:

{
    "hooks": {
        "PostToolUse": [
            { "matcher": "Edit|Write|MultiEdit", "hooks": [{ "type": "command", "command": "npx -y @enmera/ai-design-check hook" }] }
        ]
    }
}

hook reads the edited file from the hook input, checks only that file and exits 2 with the findings on stderr, which
Claude Code hands back to the agent; a clean file exits 0 silently. The same command works for any agent hook that
passes tool_input.file_path or file_path as JSON on stdin.

Or point your agent's instructions (CLAUDE.md, AGENTS.md, .cursor/rules) at
node_modules/@enmera/ai-design-check/RULES.md.

Adding a rule

Rules live in rules.json: id, area, severity, and title / rule / why / fix in en and
tr, plus an optional check: class (pattern on class strings, with unless, exceptElements, unlessBefore,
css), regex (pattern on code, comments excluded, with flags and files) or a structural check. Run npm run docs to regenerate
RULES.md and RULES.tr.md and npm test before opening a pull request.

Inspired in part by Impeccable, unslop by Damir Sokolovsky and Anthropic's frontend-design skill.

License

MIT