design-check

name	design-check
description	Anti-generic design enforcement -- catches AI-generated visual antipatterns and verifies brand compliance.

Design Enforcement Check

You have been asked to verify design compliance. Read every section. Apply the checklist to the component or page you are building. Do not skip items.

---

Section 1: AI-Generated AntiPatterns

These are the five most common ways AI-produced UIs look generic. Learn to recognize them so you can actively avoid them.

1.1 Tailwind Default Syndrome

The agent reaches for the same utility classes on every component:

• rounded-lg on everything (buttons, cards, inputs, avatars -- all the same radius)
• bg-gray-50, bg-gray-100, bg-zinc-800 as the only surface colors
• p-4 gap-4 as universal spacing (everything 16px apart, no rhythm)
• shadow-sm or shadow-md on every elevated surface
• text-gray-500 for all secondary text regardless of context

The tell: screenshot any two pages and they look like the same page with different content.

1.2 Typography Flatness

• Inter or system-ui as the only typeface
• Two sizes only: "normal" and "slightly bigger"
• No weight variation within a page (everything is font-medium or font-semibold)
• Headings are just bigger body text -- same font, same weight, same tracking
• No italic, no letter-spacing variation, no typographic personality

The tell: cover the content and you cannot tell if you are on a landing page, a settings panel, or a dashboard.

1.3 Layout Monotony

• Everything in a CSS grid of equal-width cards
• Content centered on every page
• Uniform gap between all elements (no visual grouping through spacing)
• No asymmetric layouts, no sidebar variation, no content that breathes
• Padding is identical on mobile and desktop (just reflowed)

The tell: remove all text and images -- the wireframes of every page are interchangeable.

1.4 Missing Personality

• Button labels: "Submit", "Cancel", "Save", "Delete" -- no voice, no context
• Empty states: "No items found" with a generic illustration
• Loading states: a centered spinner, nothing else
• No micro-interactions (hover states are just color shifts)
• Transitions are either absent or uniform 150ms ease-in-out on everything
• No delight moments anywhere in the flow

The tell: replace the logo and the app could belong to any company in any industry.

1.5 Dark Mode Failures

• Dark mode is light mode with colors inverted
• All surfaces are the same dark shade (no elevation through luminance)
• Pure white (#FFFFFF) text on pure dark (#000000) backgrounds (harsh, not readable)
• Accent colors unchanged from light mode (saturation too high for dark surfaces)
• Borders invisible or too prominent -- no middle ground

The tell: squint at the screen and you see a flat rectangle with no visual hierarchy.

---

Section 2: Design Constraints (Non-Negotiable)

Colors

Use design tokens exclusively. No raw Tailwind color utilities.

/* [CUSTOMIZE] -- replace with your token values */
--color-bg-primary: #0F1117;
--color-bg-elevated: #1A1D27;
--color-bg-surface: #242833;
--color-text-primary: #E8E6F0;
--color-text-secondary: #9B97A8;
--color-accent: #5B7FFF;
--color-accent-hover: #7B9AFF;
--color-success: #34D399;
--color-warning: #FBBF24;
--color-error: #F87171;

Banned: bg-gray-*, bg-zinc-*, bg-slate-*, text-gray-*, text-zinc-*, text-slate-*, border-gray-*. Zero instances permitted.

Typography

[CUSTOMIZE] -- specify your actual font stack.

Role	Font	Fallback	Usage
Display	[Your display font]	serif	Page titles, hero text
Body	[Your body font]	serif	Paragraphs, descriptions
UI	[Your UI font]	sans-serif	Buttons, labels, inputs, nav

Every page must use at least 2 of these 3 roles. A page using only the UI font fails.

Spacing

Every screen must use at least 3 different spacing values. Uniform spacing (all p-4 gap-4) is a failure. Use the design token scale:

--space-1: 4px;    --space-2: 8px;    --space-3: 12px;
--space-4: 16px;   --space-5: 20px;   --space-6: 24px;
--space-8: 32px;   --space-10: 40px;  --space-12: 48px;
--space-16: 64px;

Corner Radii

Vary by component type. Do NOT use rounded-lg on everything.

Component	Radius
Buttons	rounded-md (6px)
Cards / Panels	rounded-xl (12px)
Inputs	rounded-sm (4px)
Avatars	rounded-full
Modals	rounded-2xl (16px)

[CUSTOMIZE] -- adjust radii to match your brand.

Elevation (Dark Backgrounds)

On dark themes, elevation is communicated through luminance, not shadows.

• Level 0 (page background): darkest value
• Level 1 (cards, panels): slightly lighter
• Level 2 (dropdowns, modals): lighter still
• Borders: subtle (1px, low-opacity) to reinforce edges
• shadow-* utilities: use sparingly and only with low-opacity, colored shadows (not black)

---

Section 3: Anti-Generic Checklist

Run every item against the component or page you are building. Mark each PASS or FAIL.

Typography (7 items)

1. Display/heading font is NOT the same as body/UI font.
2. At least 3 distinct font sizes are used on this screen.
3. At least 2 distinct font weights are used on this screen.
4. Letter-spacing varies (tighter on headings, normal on body).
5. Line-height differs between headings and body text.
6. No text uses Tailwind's default text-gray-* colors.
7. Heading hierarchy is clear (H1 > H2 > H3 visually distinct without relying on size alone).

Color (5 items)

8. Zero instances of bg-gray-*, bg-zinc-*, bg-slate-* in this component.
9. Accent color is used intentionally (1-2 focal points per screen, not everywhere).
10. Text contrast meets WCAG AA (4.5:1 for body, 3:1 for large text).
11. Surface colors create visible elevation hierarchy (3+ distinct levels).
12. Interactive elements have distinct hover/focus/active states using the token palette.

Layout (5 items)

13. Spacing is non-uniform (at least 3 different gap/padding values on this screen).
14. Content has visual grouping (related items closer together, sections separated).
15. The layout is NOT a centered column of uniform-width cards.
16. Mobile and desktop layouts differ meaningfully (not just reflowed).
17. Negative space is intentional (some areas have generous whitespace, some are compact).

Interaction (4 items)

18. Buttons have labels specific to their action (not generic "Submit" / "Cancel").
19. At least one micro-interaction exists (hover effect, transition, subtle animation).
20. Loading states are contextual (skeleton matching content shape, not a centered spinner).
21. Empty states have personality (helpful message, suggested action -- not just "No data").

Voice (3 items)

22. No user-facing text says "AI", "model", "generate", or "prompt" (unless that IS the product).
23. Error messages are specific and actionable ("Task title is required" not "Validation error").
24. Placeholder text is realistic (not "Lorem ipsum" or "Enter text here").

Screenshot Verification (3 items)

25. Side-by-side with a competitor: this page is visually distinguishable.
26. Cover the logo: could this page belong to any app, or is the brand evident?
27. View at both mobile (375px) and desktop (1280px): nothing clips, overflows, or collapses.

---

Section 4: Verification Steps

After completing the checklist:

1. Count PASS vs FAIL items.
2. If any item in Typography, Color, or Layout fails, the component is NOT ready to ship. Fix before proceeding.
3. If any item in Interaction or Voice fails, fix if possible; document in your agent memory if deferred.
4. Screenshot Verification items require visual confirmation -- use Playwright or a browser screenshot tool at 375px and 1280px viewports.
5. Record the checklist results in your agent memory.

Minimum passing score: 22/27 (all Typography, Color, and Layout items must pass; up to 5 items in Interaction/Voice/Screenshot may be deferred with justification).

---

[CUSTOMIZE]

Replace Section 2 entirely with your project's design system. Section 1 (antipatterns) and Section 3 (checklist) are universal -- keep them as-is and add project-specific items if needed. Section 4 can be adjusted to match your verification tooling.