detections/.cursor/skills/ui-design/references/anti-patterns.md

Anti-Patterns — AI Slop Prevention

Read this file before generating any HTML/CSS. These are explicit instructions for what NOT to do.

Typography Anti-Patterns

• Do NOT default to Inter or Roboto. These are the #1 signal of AI-generated UI. Choose a font that matches the atmosphere from design-vocabulary.md. Only use Inter/Roboto if the user explicitly requests them.
• Do NOT use the same font weight everywhere. Establish a clear weight hierarchy: 600-700 for headings, 400 for body, 500 for UI elements.
• Do NOT set body text smaller than 14px (0.875rem). Prefer 16px (1rem) for body.
• Do NOT skip heading levels. Go h1 → h2 → h3, never h1 → h3.
• Do NOT use placeholder-only form fields. Labels above inputs are mandatory; placeholders are hints only.

Color Anti-Patterns

• Do NOT default to purple or indigo accent colors. Purple/indigo is the second-biggest AI-slop signal. Use the accent color from DESIGN.md tokens.
• Do NOT use more than 1 strong accent color in the same view. Secondary accents should be muted or derived from the primary.
• Do NOT use gray text on colored backgrounds without checking contrast. WCAG AA requires 4.5:1 for normal text, 3:1 for large text.
• Do NOT use rainbow color coding for categories. Limit to 5-6 carefully chosen, distinguishable colors.
• Do NOT apply background gradients to text (gradient text is fragile and often unreadable).

Layout Anti-Patterns

• Do NOT create "card soup" — rows of identical cards with no visual break. Vary layout patterns: full-width sections, split layouts, featured items, asymmetric grids.
• Do NOT center everything. Left-align body text. Center only headings, short captions, and CTAs.
• Do NOT use fixed pixel widths for layout. Use relative units (%, fr, auto, minmax).
• Do NOT nest excessive containers. Avoid "div soup" — use semantic elements (nav, main, section, article, aside, footer).
• Do NOT ignore mobile. Design mobile-first; every component must work at 375px width.

Component Anti-Patterns

• Do NOT make all buttons equal weight. Establish clear hierarchy: one primary (filled), secondary (outline), ghost (text-only) per visible area.
• Do NOT use spinners for content with known layout. Use skeleton loaders that match the shape of the content.
• Do NOT put a modal inside a modal. If you need nested interaction, use a slide-over or expand the current modal.
• Do NOT disable buttons without explanation. Every disabled button needs a title attribute or adjacent text explaining why.
• Do NOT use "Click here" as link text. Links should describe the destination: "View documentation", "Download report".
• Do NOT show hamburger menus on desktop. Hamburgers are for mobile only; use full navigation on desktop.
• Do NOT use equal-weight buttons in a pair. One must be visually primary, the other secondary.

Interaction Anti-Patterns

• Do NOT skip hover states on interactive elements. Every clickable element needs a visible hover change.
• Do NOT skip focus states. Keyboard users need visible focus indicators on every interactive element.
• Do NOT omit loading states. If data loads asynchronously, show a skeleton or progress indicator.
• Do NOT omit empty states. When a list or section has no data, show an illustration + explanation + action CTA.
• Do NOT omit error states. Form validation errors need inline messages below the field with an icon.
• Do NOT use bare alert() for messages. Use toast notifications or inline banners.

Decoration Anti-Patterns

• Do NOT over-decorate. Restraint over decoration. Every visual element must earn its place.
• Do NOT apply shadows AND borders AND background fills simultaneously on the same element. Pick one or two.
• Do NOT use generic stock-photo placeholder images. Use SVG illustrations, solid color blocks with icons, or real content.
• Do NOT use decorative backgrounds that reduce text readability.
• Do NOT animate everything. Use motion sparingly and purposefully: transitions for state changes (200-300ms), not decorative animation.

Spacing Anti-Patterns

• Do NOT use inconsistent spacing. Stick to the spacing scale from DESIGN.md (multiples of 4px or 8px base unit).
• Do NOT use zero padding inside containers. Minimum 12-16px padding for any content container.
• Do NOT crowd elements. When in doubt, add more whitespace, not less.
• Do NOT use different spacing systems in different parts of the same page. One scale for the whole page.

Accessibility Anti-Patterns

• Do NOT rely on color alone to convey information. Add icons, text, or patterns.
• Do NOT use thin font weights (100-300) for body text. Minimum 400 for readability.
• Do NOT create custom controls without proper ARIA attributes. Prefer native HTML elements.
• Do NOT trap keyboard focus outside of modals. Only modals should have focus traps.
• Do NOT auto-play media without user consent and a visible stop/mute control.