@enmera/ai-design-check

Türkçe

Finds and fixes what makes interfaces built with AI coding agents (Claude Code, Cursor, Codex) look generated: 76 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, and for SwiftUI and Jetpack Compose apps.

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
npx @enmera/ai-design-check system --brand "#1E5A63"  # fonts, type and colours that pass contrast

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, looping animations and tap targets under 44 pt / 48 dp (a small .frame on a button label or a .size() on a clickable; padding or an outer frame around a small icon passes). Point it at the app folder:

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

Unslopping a SwiftUI app: our own iOS app, Cebbin, live on the App Store. The home screen goes through 16 fixes one at a time (spacing, one accent, decoration, copy, hierarchy, layout); every frame is the real app on the simulator and the card under it shows the SwiftUI line that changed. The first run took the same screen from 23 findings to 0.

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 scroll