mirror of
https://github.com/azaion/annotations.git
synced 2026-04-22 21:46:30 +00:00
Oleksandr Bezdieniezhnykh
70 lines
5.0 KiB
Markdown
70 lines
5.0 KiB
Markdown
# 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.
|