# Design Knowledge: Components, Pages & Anti-Patterns

Compiled from MUI, Headless UI, W3C WAI-ARIA, GoodUI, LukeW Form Design, Refactoring UI, Linear, and award-winning site analysis.

---

## 7. Component Design

### Buttons

RULE: When designing buttons, apply minimum touch target 44x44px (Apple) / 48x48dp (Material) because mobile users need sufficient tap area. Fitts's Law confirms larger targets are acquired faster.

RULE: When building a button system, apply three-tier hierarchy: primary (filled, highest emphasis, main action), secondary (outlined, medium emphasis, alternative actions), ghost/text (low emphasis, tertiary actions) because users need visual cues about which action matters most.

RULE: When a button has icon + text, apply 8px horizontal spacing between icon and label with vertical center-alignment because misaligned icon+text pairs signal poor quality. Icon-only buttons require `aria-label`.

RULE: When designing button states, apply distinct visual treatments: hover (subtle background shift), active/pressed (inset shadow or deeper color), focus (visible ring, 2px+ offset, `:focus-visible`), disabled (40-50% opacity, `pointer-events: none`), loading (spinner replaces text, `aria-busy="true"`).

RULE: When choosing border-radius for buttons, apply 6-8px for standard buttons and full-round (9999px) only for icon buttons or chip-style buttons because extreme rounding on text buttons reduces perceived clickability.

RULE: When writing button copy, apply verb+object pattern ("Save Changes", "Delete Account") that describes the outcome because users scan for what will happen. Avoid generic "Submit" or "OK".

### Cards

RULE: When choosing cards vs lists, apply cards for visually distinct content with images, varied heights, or actions; apply lists for homogeneous text-based data because cards impose visual overhead that slows scanning of uniform data.

RULE: When designing card padding, apply 16-24px because less feels cramped and more wastes space without proportionally improving readability.

RULE: When distinguishing cards from background, apply either shadow (elevated feel), border (contained feel), or background color shift (subtle grouping) — but never all three because stacking shadow + border + background creates visual noise.

RULE: When adding hover effects to cards, apply subtle elevation increase (shadow deepens) or very slight scale (1.01-1.02x) because dramatic transforms feel jarring. Only apply hover to clickable cards.

RULE: When designing image cards, apply consistent aspect ratio: 16:9 for landscape content, 4:3 for products, 1:1 for avatars. Use `object-fit: cover` to prevent distortion.

### Navigation

RULE: When designing top nav bars, apply 56-64px height on desktop and 48-56px on mobile because below 48px fails touch target guidelines and above 64px wastes vertical space.

RULE: When placing a logo, apply left-alignment (LTR layouts) with logo linking to homepage because eye-tracking shows users look top-left first.

RULE: When spacing nav items, apply minimum 16px horizontal padding per item with 8px between items because cramped nav causes accidental clicks.

RULE: When implementing mobile hamburger, apply it only below 768px breakpoint because prematurely hiding nav reduces discoverability. Hamburger icon minimum 44x44px.

RULE: When choosing sticky vs fixed vs static nav, apply sticky for content-heavy pages, fixed for web apps with persistent controls, static for short pages.

### Forms

RULE: When placing form labels, apply top-aligned labels (above input) for fastest completion because they reduce eye movement to a single direction. Left-aligned only for settings pages where users scan without filling.

RULE: When sizing inputs, apply minimum 44px height with consistent width within a form because inconsistent sizes signal different importance.

RULE: When displaying validation, apply inline real-time feedback next to the field rather than post-submit summaries because inline lets users correct immediately.

RULE: When designing form layout, apply single-column because multi-column breaks top-to-bottom scanning. Exception: short paired fields like "First Name" / "Last Name".

RULE: When spacing form fields, apply 16-24px between fields because less blurs fields together and more loses visual connection.

RULE: When using dropdown selects, apply them as last resort. Use radio groups for 2-5 options, steppers for small numeric ranges, toggle switches for binary choices.

RULE: When possible, pre-fill fields with smart defaults (country from IP, date to today) because every pre-filled field removes work and increases conversion.

### Modals/Dialogs

RULE: When building modals, apply backdrop overlay rgba(0,0,0,0.4-0.5) because lighter fails to separate and heavier feels oppressive.

RULE: When sizing modals, apply max-width 480-540px for simple dialogs and 720-800px for complex content because wider modals lose the "focused overlay" feel.

RULE: When implementing close behavior, apply three methods: visible X button, Escape key, backdrop click. Do not prevent backdrop dismissal unless mandatory decision required.

RULE: When managing focus in modals, apply focus trapping (Tab cycles only through modal elements) because allowing focus to escape into background is a critical accessibility failure. Return focus to trigger on close.

RULE: When layering z-index, apply z-index 40-50 for backdrop, 50-60 for modal, 90-100 for toasts. Avoid z-index above 9999.

### Toasts/Notifications

RULE: When positioning toasts, apply bottom-center or bottom-right because top positions conflict with nav bars.

RULE: When setting toast duration, apply 4-5s for info, 7-8s for errors, never auto-dismiss toasts with actions.

RULE: When animating toasts, apply slide-in + fade-in for appearance (200-300ms) and fade-out for dismissal (150-200ms). No bounce or scale.

### Tables

RULE: When aligning table columns, apply left-alignment for text and right-alignment for numbers because right-aligned numbers enable magnitude comparison.

RULE: When setting row density, apply 48-56px (standard), 36-40px (compact/dashboards), 64px+ (touch). Never below 32px.

RULE: When indicating sort state, show arrow only on currently sorted column because arrows on every header creates noise.

### Badges/Tags

RULE: When sizing badges, apply 20-24px height (standard), 16-18px (compact). Horizontal padding 8-12px, text 11-13px.

RULE: When color-coding badges, apply semantic colors (green=success, red=error, yellow=warning, blue=info) with WCAG AA contrast. Always include text labels, never color alone.

---

## 8. Page-Level Design

### Landing Page Structure
RULE: When structuring a landing page, apply this order: (1) Hero with value prop, (2) Social proof, (3) Problem/pain points, (4) Features/benefits, (5) How it works, (6) Pricing, (7) Final CTA, (8) Footer because this mirrors the persuasion arc: attention → credibility → empathy → solution → proof → commitment.

RULE: When deciding page length, apply long-form (5+ sections) for unfamiliar products needing education, short-form (hero + proof + CTA) for well-understood products.

### Hero Section
RULE: When designing the hero, apply: [Headline: outcome] + [Subheadline: clarification] + [Primary CTA] + [Secondary link] because this answers "What is this?", "Is it for me?", "What do I do?" in order.

RULE: When choosing hero background, apply solid/gradient for copy-driven products, real photography for physical products, screenshots for software, abstract/code for developer tools.

RULE: When allocating hero vertical space, apply 70-85vh because <50vh feels insignificant and >90vh creates false bottoms.

RULE: When selecting hero visuals, apply one strong visual rather than multiple competing images. Avoid generic stock photos.

### Feature Presentation
RULE: When presenting features, apply alternating left-right layout for 3-5 features rather than 3-column icon grid because alternating sections force specificity and visual variety.

RULE: When the product has one killer feature, apply full-width showcase with detailed explanation because your most important feature deserves more than 33% of a row.

RULE: When listing features, apply benefit-first framing ("Ship faster" not "CI/CD pipeline automation") because users decide based on outcomes.

### Social Proof
RULE: When displaying social proof, apply logo bar immediately below hero because this catches users deciding whether to keep reading. Logos should be grayscale.

RULE: When designing testimonials, apply quote + name + title + photo because testimonials without attribution are not credible. Limit to 2-3 sentences.

RULE: When showing numbers, apply specific figures ("2,847 teams") not round estimates ("thousands") because specificity implies accuracy.

### Pricing Pages
RULE: When designing pricing, apply 3-column layout with recommended tier highlighted (scaled up 2-4%, distinct border, "Most Popular" badge) because highlighting reduces decision paralysis.

RULE: When offering annual billing, apply monthly/annual toggle with annual savings displayed ("Save 20%") because explicit savings trigger loss aversion.

### Documentation Layout
RULE: When laying out docs, apply three-zone: left sidebar (240-280px), content (720-760px max), optional right TOC because wider content creates lines too long for reading.

RULE: When placing docs search, apply visible input at top of sidebar (not just an icon) because docs search is primary navigation.

### Above the Fold
RULE: When designing above-the-fold, apply the 5-second test: hero must communicate (1) what the product is, (2) who it's for, (3) what action to take — all without scrolling.

RULE: When deciding fold content, show at minimum the top of the next section to signal more content below and avoid false bottoms.

### CTA Design
RULE: When writing CTA copy, apply first-person outcome text ("Start building for free", "Get my report") rather than system text ("Sign up", "Submit").

RULE: When placing CTAs on long pages, apply primary CTA minimum three times: hero, after features/pricing, and at page bottom.

RULE: When a page has multiple CTAs, apply ONE primary per section (filled button) and make others secondary (outline) because competing primary CTAs create paralysis.

---

## 9. Design Anti-Patterns ("AI Slop" Taxonomy)

### 1. Purple Gradient on White
ANTI-PATTERN: Why it happens: AI models learned purple-to-blue gradients on white = safest "modern" choice. Signals innovation without committing to brand identity. What to do instead: Choose brand colors rooted in product personality. Use single accent color for primary actions, not gradients. Principle violated: Deliberate brand personality.

### 2. The 3-Column Icon+Heading+Text Grid
ANTI-PATTERN: Why it happens: Lowest-effort way to fill space. Creates false completeness without requiring prioritization. AI defaults to it because it's structurally balanced. What to do instead: Alternating left-right sections with real screenshots for top 2-3 features, or bento grid with different-sized cells. Principle violated: Meaningful hierarchy.

### 3. "Transform Your [X] with [Y]" Hero Copy
ANTI-PATTERN: Why it happens: AI language defaults to aspirational broad language because it's statistically safe. "Transform", "revolutionize", "streamline", "empower", "leverage" are most overrepresented AI verbs. What to do instead: State concrete outcome ("Ship issues 2x faster") or specific mechanism. Specificity converts; vagueness bounces. Principle violated: Clarity over cleverness.

### 4. Inter/Roboto/system-ui as Only Font
ANTI-PATTERN: Why it happens: Default in Tailwind, Google Fonts, and most starters. Safe and readable = signals "I used the defaults." What to do instead: Choose font reinforcing personality — DM Sans/Geist for professional, Merriweather/Lora for editorial, JetBrains Mono/IBM Plex for technical, Playfair/Instrument Serif for premium. At minimum, pair with distinct display font. Principle violated: Choosing a personality.

### 5. Auto-Rotating Testimonial Carousel
ANTI-PATTERN: Why it happens: Shows many testimonials in limited space, feels dynamic. AI templates include by default. What to do instead: Show 2-3 static testimonials with real names, photos, companies. Carousels suffer banner blindness. Principle violated: User control over content.

### 6. Perfect Symmetry on Every Section
ANTI-PATTERN: Why it happens: Symmetric layouts are mathematically easy and never look "broken." Grid tools and AI generators produce them by default. What to do instead: Deliberate asymmetry (60/40 split) creates visual interest. Offset images. Inconsistent section heights. Asymmetry signals human choice. Principle violated: Visual hierarchy through contrast.

### 7. Abstract People Shapes / Isometric Office Scenes
ANTI-PATTERN: Why it happens: AI image generators and stock libraries produce these by default. Inoffensive and "modern" = communicate nothing specific. What to do instead: Real product screenshots, real team photos, custom domain-specific illustrations. Principle violated: Content-specificity over decoration.

### 8. Unthinking 3-Equal-Column Pricing Table
ANTI-PATTERN: Why it happens: Valid pattern copied without the decision architecture. Treats all tiers equal with no guidance. What to do instead: Highlight recommended tier with visual distinction. Include feature comparison. Show annual savings. The pattern works when done right. Principle violated: Guiding user's decision.

### 9. Floating Device Mockup Hero (MacBook/iPhone)
ANTI-PATTERN: Why it happens: Device mockups in nearly every template. Instantly communicates "software." Visual equivalent of stock photos. What to do instead: Show actual product UI full-width or as interactive demo. Device frames shrink visible content by 40%. Principle violated: Content over container.

### 10. Gradient Text on Dark Backgrounds
ANTI-PATTERN: Why it happens: Looks "modern" with zero effort. Only needs `background-clip: text`. Impressive in screenshots. What to do instead: Solid white/light text on dark backgrounds with maximum contrast. Reserve gradients for decorative elements, not readable text. Principle violated: Readability over decoration, WCAG 1.4.3.

### 11. 6-9 Feature Cards with Icons in a Grid
ANTI-PATTERN: Why it happens: Fills space efficiently. No creative decisions needed — just list everything. What to do instead: Prioritize 2-3 differentiating features with story-level depth. Move full list to dedicated page. Principle violated: Prioritization over completeness.

### 12. "Trusted by" Logo Wall of Unknown Companies
ANTI-PATTERN: Why it happens: Templates include it by default. Early products feel pressure to show social proof without recognizable customers. What to do instead: If no recognizable logos, omit entirely. Use user counts, GitHub stars, or single detailed testimonial. Unknown logos hurt credibility. Principle violated: Authenticity.
