Accessibility

WCAG 2.2 quick reference

Level AA requirements (the standard target):

• Color contrast: 4.5:1 normal text, 3:1 large text (18px+ or 14px bold+)
• Touch targets: minimum 24x24px (44x44px recommended)
• Focus indicators: visible, 2px+ ring, 3:1 contrast against background
• Text resize: page must work at 200% zoom
• Motion: respect prefers-reduced-motion

Semantic HTML (do this first)

Use the right element for the job - this gets you a11y for free.

• Use <button> for actions, <a href> for navigation. NEVER <div>/<span> with onClick
• Use <nav>, <main>, <header>, <footer>, <aside> landmarks
• Use <h1>-<h6> in order, never skip levels
• Use <ul>/<ol> for lists, <table> for tabular data
• Use <label> with for= attribute for every form input
• Use <fieldset> + <legend> for radio/checkbox groups

<!-- Bad -->
<div class="btn" onClick={handleSave}>Save</div>
<span onClick={goHome}>Home</span>

<!-- Good -->
<button type="button" onClick={handleSave}>Save</button>
<a href="/">Home</a>

ARIA patterns

Only add ARIA when semantic HTML is not enough.

Icon-only buttons

<button type="button" aria-label="Close dialog">
  <svg aria-hidden="true" focusable="false">...</svg>
</button>

Expandable toggles / accordions

<button aria-expanded="false" aria-controls="section-1">
  Section title
</button>
<div id="section-1" hidden>...</div>

Update aria-expanded and toggle hidden on click.

Dynamic content announcements

<!-- Polite: announces after current speech finishes (toasts, status) -->
<div aria-live="polite" aria-atomic="true" class="sr-only">
  Form saved successfully
</div>

<!-- Assertive: interrupts immediately (errors only) -->
<div aria-live="assertive" role="alert">
  Session expired. Please log in again.
</div>

Modal dialogs

<div
  role="dialog"
  aria-modal="true"
  aria-labelledby="dialog-title"
  aria-describedby="dialog-desc"
>
  <h2 id="dialog-title">Confirm deletion</h2>
  <p id="dialog-desc">This action cannot be undone.</p>
  ...
</div>

Navigation current page

<nav aria-label="Main">
  <a href="/" aria-current="page">Home</a>
  <a href="/about">About</a>
</nav>

Decorative elements

<!-- Decorative icon: hide from screen readers -->
<svg aria-hidden="true" focusable="false">...</svg>

<!-- Decorative image -->
<img src="divider.png" alt="" />

Keyboard navigation

• Tab order must match visual order - never use positive tabindex (only 0 or -1)
• All interactive elements must be reachable by keyboard
• Escape closes modals, dropdowns, popovers, and drawers
• Enter/Space activates buttons; Enter follows links
• Arrow keys navigate within components (tabs, menus, radio groups, sliders)
• Focus trap inside modals: Tab cycles through focusable elements within the modal only
• Provide a "Skip to main content" link as the first focusable element on the page

<!-- Skip link: visually hidden until focused -->
<a href="#main-content" class="skip-link">Skip to main content</a>

<main id="main-content" tabindex="-1">...</main>

.skip-link {
  position: absolute;
  top: -100%;
  left: 0;
}
.skip-link:focus {
  top: 0;
}

Focus trap implementation (modals)

function trapFocus(modalEl) {
  const focusable = modalEl.querySelectorAll(
    'a[href], button:not([disabled]), input, select, textarea, [tabindex="0"]'
  );
  const first = focusable[0];
  const last = focusable[focusable.length - 1];

  modalEl.addEventListener('keydown', (e) => {
    if (e.key !== 'Tab') return;
    if (e.shiftKey) {
      if (document.activeElement === first) { e.preventDefault(); last.focus(); }
    } else {
      if (document.activeElement === last) { e.preventDefault(); first.focus(); }
    }
  });

  first.focus(); // move focus into modal on open
}

Focus styles

/* Modern focus-visible approach: only show ring for keyboard users */
:focus-visible {
  outline: 2px solid var(--color-primary-500);
  outline-offset: 2px;
  border-radius: 2px;
}

/* Remove focus ring for mouse/pointer users */
:focus:not(:focus-visible) {
  outline: none;
}

/* High contrast mode support */
@media (forced-colors: active) {
  :focus-visible {
    outline: 2px solid ButtonText;
  }
}

prefers-reduced-motion

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
    scroll-behavior: auto !important;
  }
}

In JavaScript, check before animating:

const prefersReduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
if (!prefersReduced) {
  element.animate([...], { duration: 300 });
}

Form accessibility

<!-- Every input needs a visible label -->
<label for="email">Email address <span aria-hidden="true">*</span></label>
<input
  id="email"
  type="email"
  aria-required="true"
  aria-describedby="email-error"
/>
<span id="email-error" role="alert" aria-live="polite">
  <!-- Populated by JS on validation -->
</span>

<!-- Group related fields -->
<fieldset>
  <legend>Notification preferences</legend>
  <label><input type="checkbox" name="email-notif" /> Email</label>
  <label><input type="checkbox" name="sms-notif" /> SMS</label>
</fieldset>

Rules:

• Placeholder is NOT a label - always use <label>
• Link error message to input with aria-describedby
• Mark required fields with aria-required="true" AND a visible indicator
• Provide inline validation, not just on submit
• On submit errors, move focus to an error summary at top of form

Image accessibility

<!-- Informative image: describe what it conveys, not what it looks like -->
<img src="chart.png" alt="Q3 revenue grew 24% year-over-year to $4.2M" />

<!-- Decorative image: empty alt, not omitted -->
<img src="hero-bg.jpg" alt="" />

<!-- Complex image: link to long description -->
<img src="org-chart.png" alt="Company org chart" aria-describedby="org-desc" />
<p id="org-desc">The CEO reports to the board. Three VPs report to the CEO: ...</p>

<!-- Meaningful icon -->
<svg role="img" aria-label="Warning">...</svg>

Color and contrast

• Never use color alone to convey information - add icons, patterns, or text labels
• Test with color blindness simulators (Chrome DevTools > Rendering > Emulate vision)
• Contrast ratios:
  • Normal text (< 18px, or < 14px bold): 4.5:1 minimum
  • Large text (18px+ or 14px+ bold): 3:1 minimum
  • UI components and focus rings: 3:1 minimum

/* Accessible error state: color + icon + text, not color alone */
.input-error {
  border-color: #d93025; /* red, but also accompanied by error text below */
}
/* Pair with: <span>Error: ...</span> */

Tools: Chrome DevTools contrast checker, axe DevTools browser extension, Colour Contrast Analyser app.

Screen reader testing

Screen reader	Platform	Shortcut
VoiceOver	macOS	Cmd+F5
VoiceOver	iOS	Triple-click home/side
NVDA (free)	Windows	Install from nvaccess.org
TalkBack	Android	Volume up + down hold

Common things to verify:

• All images have meaningful alt text
• All buttons and links have descriptive labels (not just "click here")
• Heading order is logical (h1 > h2 > h3)
• Dynamic content changes are announced via aria-live
• Reading order matches visual order

Common accessibility mistakes

Mistake	Problem	Fix
<div onClick={...}>	Not keyboard accessible, no role announced	Use <button>
Placeholder as label	Disappears on input, fails contrast	Add visible <label>
tabindex="2"	Breaks natural tab order	Only use tabindex="0" or tabindex="-1"
aria-label on <div>	ARIA label has no effect without a role	Add role or use semantic element
Missing alt attribute	Screen reader reads file name	Always set alt="" at minimum
Color-only error state	Color-blind users miss errors	Add icon or text alongside color
Auto-playing animation	Triggers vestibular disorders	Respect prefers-reduced-motion
Focus moves to top on modal close	Confusing for keyboard users	Return focus to the trigger element
aria-hidden on focused element	Removes element from a11y tree while still focusable	Remove aria-hidden or tabindex="-1"
Tooltip on hover only	Not accessible by keyboard or touch	Trigger on focus as well as hover

Animation Libraries & Advanced Techniques

Companion to micro-animations.md - this reference covers JavaScript animation libraries, spring physics, and production patterns for complex motion work.

---

1. Standard Easing Library

Material Design easing curves as CSS custom properties:

:root {
  /* Material Design standard curves */
  --ease-standard:   cubic-bezier(0.4, 0.0, 0.2, 1);   /* default for most */
  --ease-decelerate: cubic-bezier(0.0, 0.0, 0.2, 1);   /* entering elements */
  --ease-accelerate: cubic-bezier(0.4, 0.0, 1.0, 1);   /* exiting elements */

  /* Expressive curves */
  --ease-spring:     cubic-bezier(0.34, 1.56, 0.64, 1); /* playful overshoot */
  --ease-bounce:     cubic-bezier(0.68, -0.55, 0.27, 1.55); /* cartoon bounce */
  --ease-snappy:     cubic-bezier(0.2, 0, 0, 1);        /* quick, decisive */

  /* Duration tokens */
  --duration-instant: 100ms;  /* button press, toggle */
  --duration-fast:    150ms;  /* hover, color change */
  --duration-normal:  250ms;  /* modal open, dropdown */
  --duration-slow:    350ms;  /* page transition, complex animation */
  --duration-slower:  500ms;  /* orchestrated sequence max */
}

When to use each:

• --ease-standard - state changes, most transitions
• --ease-decelerate - elements entering the screen (ease-out)
• --ease-accelerate - elements leaving the screen (ease-in)
• --ease-spring - playful UI, toggle states, card interactions
• --ease-snappy - decisive actions, tab switches, nav highlights

---

2. Spring Physics Parameters

For Framer Motion and CSS spring():

// Framer Motion spring configs
const springs = {
  // Gentle - tooltips, subtle movements
  gentle: { type: "spring", stiffness: 120, damping: 20 },

  // Default - most UI interactions
  default: { type: "spring", stiffness: 300, damping: 25 },

  // Snappy - toggles, switches, quick feedback
  snappy: { type: "spring", stiffness: 500, damping: 30 },

  // Bouncy - playful interactions, celebrations
  bouncy: { type: "spring", stiffness: 400, damping: 15 },

  // Heavy - large elements, page transitions
  heavy: { type: "spring", stiffness: 200, damping: 35 },
};

Rules of thumb:

• Higher stiffness = faster movement
• Higher damping = less oscillation (bounce)
• stiffness: 300-500, damping: 25-35 covers 90% of UI needs
• Ratio matters: stiffness/damping > 15 = noticeable bounce

---

3. Framer Motion Patterns (React)

Enter/Exit with AnimatePresence

import { motion, AnimatePresence } from "framer-motion";

// Modal with enter/exit
function Modal({ isOpen, children }) {
  return (
    <AnimatePresence>
      {isOpen && (
        <>
          {/* Backdrop */}
          <motion.div
            className="backdrop"
            initial={{ opacity: 0 }}
            animate={{ opacity: 1 }}
            exit={{ opacity: 0 }}
            transition={{ duration: 0.2 }}
          />
          {/* Modal content */}
          <motion.div
            className="modal"
            initial={{ opacity: 0, scale: 0.95, y: 10 }}
            animate={{ opacity: 1, scale: 1, y: 0 }}
            exit={{ opacity: 0, scale: 0.95, y: 10 }}
            transition={{ type: "spring", stiffness: 300, damping: 25 }}
          >
            {children}
          </motion.div>
        </>
      )}
    </AnimatePresence>
  );
}

Layout Animations

Auto-animate position and size changes:

// List with automatic reorder animation
function List({ items }) {
  return (
    <ul>
      {items.map((item) => (
        <motion.li
          key={item.id}
          layout           /* enables layout animation */
          initial={{ opacity: 0 }}
          animate={{ opacity: 1 }}
          exit={{ opacity: 0 }}
          transition={{ layout: { type: "spring", stiffness: 300, damping: 30 } }}
        >
          {item.name}
        </motion.li>
      ))}
    </ul>
  );
}

Staggered Children

const container = {
  hidden: {},
  show: { transition: { staggerChildren: 0.05 } },
};
const item = {
  hidden: { opacity: 0, y: 12 },
  show: { opacity: 1, y: 0 },
};

function StaggeredList({ items }) {
  return (
    <motion.ul variants={container} initial="hidden" animate="show">
      {items.map((i) => (
        <motion.li key={i.id} variants={item}>{i.name}</motion.li>
      ))}
    </motion.ul>
  );
}

Framer Motion Gotchas

• AnimatePresence requires a unique key on each direct child
• layout animations can conflict with CSS transforms - avoid both on same element
• Clean up animation subscriptions in useEffect returns
• exit animations only work when the component is a direct child of AnimatePresence

---

4. GSAP Basics

For complex timeline sequences:

import { gsap } from "gsap";

// Simple timeline
const tl = gsap.timeline({ defaults: { ease: "power2.out", duration: 0.5 } });

tl.from(".hero__title", { y: 30, opacity: 0 })
  .from(".hero__subtitle", { y: 20, opacity: 0 }, "-=0.3") // overlap by 0.3s
  .from(".hero__cta", { y: 20, opacity: 0, scale: 0.95 }, "-=0.2")
  .from(".hero__visual", { x: 40, opacity: 0 }, "-=0.4");

Scroll-Driven Animation

import { ScrollTrigger } from "gsap/ScrollTrigger";
gsap.registerPlugin(ScrollTrigger);

gsap.from(".section__content", {
  scrollTrigger: {
    trigger: ".section",
    start: "top 80%",
  },
  y: 40,
  opacity: 0,
  duration: 0.6,
  stagger: 0.1,
});

When GSAP > Framer Motion

• Complex multi-step timelines with precise overlap control
• Scroll-driven animations with scrubbing
• Animating SVG paths, morphing
• When you need .from(), .to(), .fromTo() flexibility

When Framer Motion > GSAP

• React component enter/exit animations
• Layout animations (automatic position/size)
• Gesture-driven interactions (drag, hover, tap)
• When you want declarative animation in JSX

---

5. Performance Rules

• Only animate transform and opacity for 60fps - everything else triggers layout/paint
• will-change hints: use sparingly, only on elements about to animate, remove after
• CSS transitions for simple state changes, JS animation for complex sequences
• On mobile: reduce animation complexity, disable parallax, respect prefers-reduced-motion
• GSAP cleanup: always kill() timelines and ScrollTriggers on component unmount

// React cleanup pattern for GSAP
useEffect(() => {
  const ctx = gsap.context(() => {
    // all GSAP animations here
  }, containerRef);

  return () => ctx.revert(); // kills all animations in scope
}, []);

// Reduced motion media query hook
function usePrefersReducedMotion() {
  const [reduced, setReduced] = useState(false);
  useEffect(() => {
    const mq = window.matchMedia("(prefers-reduced-motion: reduce)");
    setReduced(mq.matches);
    const handler = (e) => setReduced(e.matches);
    mq.addEventListener("change", handler);
    return () => mq.removeEventListener("change", handler);
  }, []);
  return reduced;
}

Atmosphere and Texture

Why Flat Backgrounds Feel Generic

Solid white or gray backgrounds are the number one tell of AI-generated UI. Every default template, every quick prototype, every "just ship it" screen lands on #ffffff or #f5f5f5 and calls it done. The result: an interface that feels like a wireframe someone forgot to finish.

Real designed interfaces use subtle texture, gradients, or patterns to create atmosphere. The background is not just a container - it sets the emotional tone. Compare any Stripe page to a generic SaaS template. The difference is almost entirely in the background treatment.

The goal: make backgrounds feel intentional and crafted without distracting from content.

---

Gradient Meshes

Layer multiple radial-gradient or conic-gradient calls to create organic, mesh-like backgrounds. The key is low opacity and wide spread so blobs blend softly.

Cool tone (default/professional)

.gradient-mesh-cool {
  background:
    radial-gradient(at 20% 80%, hsla(210, 100%, 70%, 0.3) 0%, transparent 50%),
    radial-gradient(at 80% 20%, hsla(340, 100%, 70%, 0.2) 0%, transparent 50%),
    radial-gradient(at 50% 50%, hsla(260, 100%, 80%, 0.15) 0%, transparent 60%),
    hsl(220, 20%, 97%);
}

Warm tone (creative/friendly)

.gradient-mesh-warm {
  background:
    radial-gradient(at 30% 70%, hsla(30, 100%, 70%, 0.25) 0%, transparent 50%),
    radial-gradient(at 70% 30%, hsla(350, 90%, 65%, 0.2) 0%, transparent 50%),
    radial-gradient(at 60% 80%, hsla(45, 100%, 75%, 0.15) 0%, transparent 55%),
    hsl(35, 25%, 97%);
}

Dark mode mesh

.gradient-mesh-dark {
  background:
    radial-gradient(at 20% 80%, hsla(210, 100%, 50%, 0.15) 0%, transparent 50%),
    radial-gradient(at 80% 20%, hsla(280, 80%, 50%, 0.1) 0%, transparent 50%),
    radial-gradient(at 50% 50%, hsla(200, 100%, 40%, 0.08) 0%, transparent 60%),
    hsl(220, 25%, 8%);
}

Tips:

• Keep individual blob opacity between 0.08 and 0.3
• Place blobs at different positions (20/80, 80/20, 50/50) to avoid symmetry
• The final solid color in the stack is your fallback - always include it

---

Noise and Grain Overlays

Grain adds analog warmth. Two techniques:

SVG filter approach (inline, no external files)

.grain-filter {
  position: relative;
  isolation: isolate;
}

.grain-filter::after {
  content: '';
  position: absolute;
  inset: 0;
  filter: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.8' numOctaves='4' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)' opacity='0.03'/%3E%3C/svg%3E");
  opacity: 0.03;
  pointer-events: none;
  mix-blend-mode: overlay;
  z-index: 1;
}

SVG data URI approach (repeating tile)

.grain-tile::after {
  content: '';
  position: absolute;
  inset: 0;
  background: url("data:image/svg+xml,%3Csvg viewBox='0 0 256 256' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.65' numOctaves='3' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)'/%3E%3C/svg%3E") repeat;
  background-size: 256px 256px;
  opacity: 0.04;
  pointer-events: none;
  mix-blend-mode: overlay;
}

Combining grain with gradient mesh

.atmosphere {
  position: relative;
  background:
    radial-gradient(at 20% 80%, hsla(210, 100%, 70%, 0.3) 0%, transparent 50%),
    radial-gradient(at 80% 20%, hsla(340, 100%, 70%, 0.2) 0%, transparent 50%),
    hsl(220, 20%, 97%);
}

.atmosphere::after {
  content: '';
  position: absolute;
  inset: 0;
  background: url("data:image/svg+xml,%3Csvg viewBox='0 0 256 256' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.65' numOctaves='3' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)'/%3E%3C/svg%3E") repeat;
  background-size: 256px 256px;
  opacity: 0.03;
  pointer-events: none;
  mix-blend-mode: overlay;
}

---

Glassmorphism and Layered Transparencies

Beyond basic backdrop-filter: blur(10px) - here is how to make glass panels look real.

Frosted glass with tinted background

.glass-panel {
  background: rgba(255, 255, 255, 0.05);
  backdrop-filter: blur(20px) saturate(1.5);
  -webkit-backdrop-filter: blur(20px) saturate(1.5);
  border: 1px solid rgba(255, 255, 255, 0.1);
  border-radius: 16px;
  box-shadow: 0 8px 32px rgba(0, 0, 0, 0.12);
}

Light mode glass (tinted white)

.glass-light {
  background: rgba(255, 255, 255, 0.6);
  backdrop-filter: blur(16px) saturate(1.8);
  -webkit-backdrop-filter: blur(16px) saturate(1.8);
  border: 1px solid rgba(255, 255, 255, 0.7);
  border-radius: 12px;
  box-shadow:
    0 4px 16px rgba(0, 0, 0, 0.06),
    inset 0 1px 0 rgba(255, 255, 255, 0.5);
}

Multiple transparency layers for depth

.layered-glass {
  position: relative;
}

.layered-glass::before {
  content: '';
  position: absolute;
  inset: -1px;
  background: linear-gradient(
    135deg,
    rgba(255, 255, 255, 0.15) 0%,
    rgba(255, 255, 255, 0.05) 100%
  );
  border-radius: inherit;
  z-index: -1;
  mask: linear-gradient(#fff 0 0) content-box, linear-gradient(#fff 0 0);
  mask-composite: exclude;
  padding: 1px;
}

Key details:

• Always include -webkit-backdrop-filter for Safari
• saturate(1.5) makes colors behind the glass pop - without it, blur looks washed out
• The 1px solid rgba(255, 255, 255, 0.1) border creates a visible edge on the glass
• inset 0 1px 0 rgba(255, 255, 255, 0.5) adds a highlight line on the top edge

---

Geometric Patterns as Backgrounds

CSS-only patterns that add structure without images.

Dot grid

.dot-grid {
  background-image: radial-gradient(circle, #00000008 1px, transparent 1px);
  background-size: 24px 24px;
}

/* Dark mode */
.dark .dot-grid {
  background-image: radial-gradient(circle, #ffffff06 1px, transparent 1px);
}

Line grid

.line-grid {
  background-image:
    linear-gradient(to right, #00000006 1px, transparent 1px),
    linear-gradient(to bottom, #00000006 1px, transparent 1px);
  background-size: 40px 40px;
}

Diagonal stripes

.diagonal-stripes {
  background-image: repeating-linear-gradient(
    -45deg,
    transparent,
    transparent 10px,
    #00000004 10px,
    #00000004 11px
  );
}

Combining pattern with gradient

.patterned-hero {
  background:
    radial-gradient(circle, #00000008 1px, transparent 1px),
    radial-gradient(at 30% 70%, hsla(210, 100%, 70%, 0.2) 0%, transparent 50%),
    hsl(220, 20%, 97%);
  background-size: 24px 24px, 100% 100%, 100% 100%;
}

---

Dramatic Shadows for Depth

Move beyond generic gray shadows. Colored shadows and large diffuse spreads create real depth.

Colored shadows matching content

.hero-image {
  box-shadow:
    0 20px 60px -10px rgba(var(--brand-rgb), 0.3),
    0 40px 100px -20px rgba(0, 0, 0, 0.15);
}

/* For a blue-themed element */
.card-blue {
  box-shadow:
    0 10px 40px -8px rgba(59, 130, 246, 0.25),
    0 4px 12px -2px rgba(0, 0, 0, 0.08);
}

Large diffuse shadows for hero sections

.hero-element {
  box-shadow:
    0 0 0 1px rgba(0, 0, 0, 0.03),
    0 2px 4px rgba(0, 0, 0, 0.04),
    0 12px 24px rgba(0, 0, 0, 0.06),
    0 48px 80px -12px rgba(0, 0, 0, 0.12);
}

Glow effect for dark mode CTAs

.dark .cta-button {
  box-shadow:
    0 0 20px rgba(99, 102, 241, 0.4),
    0 0 60px rgba(99, 102, 241, 0.15);
  transition: box-shadow 0.3s ease;
}

.dark .cta-button:hover {
  box-shadow:
    0 0 30px rgba(99, 102, 241, 0.5),
    0 0 80px rgba(99, 102, 241, 0.2);
}

---

Dark Mode Atmosphere

Dark mode is where texture shines most because contrast works in your favor.

Subtle colored glow behind key elements

.dark .feature-card {
  position: relative;
}

.dark .feature-card::before {
  content: '';
  position: absolute;
  inset: -20px;
  background: radial-gradient(
    ellipse at center,
    hsla(210, 100%, 50%, 0.08) 0%,
    transparent 70%
  );
  z-index: -1;
  pointer-events: none;
}

Gradient borders using background-clip

.gradient-border {
  position: relative;
  background: hsl(220, 25%, 10%);
  border-radius: 12px;
}

.gradient-border::before {
  content: '';
  position: absolute;
  inset: 0;
  border-radius: inherit;
  padding: 1px;
  background: linear-gradient(
    135deg,
    hsla(210, 100%, 70%, 0.3),
    hsla(280, 100%, 70%, 0.1),
    transparent 60%
  );
  mask: linear-gradient(#fff 0 0) content-box, linear-gradient(#fff 0 0);
  mask-composite: exclude;
  -webkit-mask-composite: xor;
  pointer-events: none;
}

Ambient light effect on page

.dark-page {
  background:
    radial-gradient(ellipse 80% 60% at 50% -10%, hsla(220, 80%, 50%, 0.12) 0%, transparent 60%),
    hsl(220, 25%, 6%);
  min-height: 100vh;
}

---

When Texture Helps vs When Clean is Better

Context	Recommendation	Reason
Marketing / landing pages	Texture strongly recommended	Character and brand personality
Hero sections	Gradient mesh + grain	Sets the visual tone for the page
Onboarding / empty states	Subtle pattern or gradient	Makes empty space feel intentional
Blog / content pages	Minimal - maybe a faint gradient	Content is the focus
Dense data UIs (dashboards)	Keep clean, no texture	Texture competes with data density
Tables and forms	No texture	Readability is paramount
Modals and dialogs	Glass or subtle background	Creates layered depth
Dark mode in general	Texture adds the most value	Flat dark surfaces feel like voids

Rule of thumb: texture should be felt, not seen. If you notice it consciously, it is too much.

---

Common Texture Mistakes

Mistake	Problem	Fix
Grain opacity above 0.06	Visible noise, looks like a rendering artifact	Keep opacity between 0.02 and 0.05
Gradient blobs too saturated	Background competes with content for attention	Keep individual blob opacity under 0.3
Mixing too many techniques	Gradient + grain + pattern + glass = visual chaos	Pick one primary technique, one subtle accent
Not testing on low-contrast displays	Subtle effects vanish or bloom unpredictably	Test on a low-quality laptop screen
Texture behind text without contrast	Text becomes hard to read over gradients	Ensure WCAG AA contrast at every point in the gradient
Using texture on every surface	Feels overwhelming, loses the intentional quality	Reserve texture for hero areas and backgrounds, keep content surfaces clean
Forgetting pointer-events: none on overlays	Grain or pattern pseudo-elements block clicks	Always add pointer-events: none to decorative overlays
Skipping -webkit-backdrop-filter	Glass effects break in Safari	Always include the prefixed version alongside the standard property
Animation on gradient meshes	Constant movement is distracting and costly	Static meshes work - animate only on hover or scroll if at all

Buttons and Icons

Button hierarchy

• 3 levels: Primary (filled), Secondary (outlined), Ghost (text-only)
• Only 1 primary button per visual section
• Destructive buttons: red variant of primary, use sparingly
• Size scale: sm (32-36px height), md (40px), lg (48px)
• Padding formula: vertical = (height - lineHeight) / 2, horizontal = height * 0.5
• Min-width: 80px to prevent tiny buttons

Button states (ALL required)

All 5 states must be covered - missing any one of them is a bug, not a style choice.

Default

Base appearance. Background, border, text color all at resting values.

Hover

Darken background by 1 shade (e.g. bg-blue-600 -> bg-blue-700). For outlined/ghost, add a light background fill.

Active / Pressed

Scale down slightly + darken one more shade: transform: scale(0.98) + bg-blue-800. Gives tactile feedback.

Focus-visible

Use outline, not box-shadow, for accessibility (box-shadow is clipped by overflow:hidden parents).

/* Correct */
button:focus-visible {
  outline: 2px solid #3b82f6;
  outline-offset: 2px;
}

/* Wrong - gets clipped */
button:focus-visible {
  box-shadow: 0 0 0 2px #3b82f6;
}

Disabled

button:disabled {
  opacity: 0.5;
  cursor: not-allowed;
  pointer-events: none;
}

Complete CSS example - primary button

.btn-primary {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  gap: 6px;
  min-width: 80px;
  height: 40px;
  padding: 0 20px;
  border: none;
  border-radius: 6px;
  background-color: #2563eb; /* blue-600 */
  color: #ffffff;
  font-size: 14px;
  font-weight: 500;
  line-height: 1;
  cursor: pointer;
  transition: background-color 120ms ease, transform 80ms ease;
}

.btn-primary:hover {
  background-color: #1d4ed8; /* blue-700 */
}

.btn-primary:active {
  background-color: #1e40af; /* blue-800 */
  transform: scale(0.98);
}

.btn-primary:focus-visible {
  outline: 2px solid #3b82f6; /* blue-500 */
  outline-offset: 2px;
}

.btn-primary:disabled {
  opacity: 0.5;
  cursor: not-allowed;
  pointer-events: none;
}

Icon sizing

Quick rule: icon size = text line-height. If your text has a 24px line-height, make icons 24px. This ensures perfect vertical alignment without fiddling. Most icons are too large by default - match them to line-height, not font-size.

Detailed matching for optical balance:

Text size	Icon size	Stroke width
12px	14px	2px
14px	16px	2px
16px	20px	2px
20px	24px	1.5px

• Icon-only buttons need a minimum 44x44px touch target even if the icon itself is 20px - use padding to expand the hit area
• Stroke width: 1.5px for 24px icons, 2px for 20px and smaller
• Popular libraries: Lucide React (recommended), Heroicons, Phosphor, React Icons, Font Awesome
• Never use unicode emojis as icons (e.g. ✅, ⚡, 🔥, 📊, ❌). Emojis render inconsistently across OS and browsers, cannot be styled with CSS (no color, size, or stroke control), and hurt accessibility. Always use SVG icons from a real icon library

Icon + text pairing

• Icon goes LEFT of text for actions: Save, Delete, Edit, Add
• Icon goes RIGHT for navigation/direction: Next, External link, Dropdown arrow
• Gap between icon and text: 6px for sm/md buttons, 8px for lg buttons
• Always center vertically with flexbox - never use manual margin/padding to nudge icons

/* Correct */
.btn {
  display: inline-flex;
  align-items: center;
  gap: 6px;
}

/* Wrong - brittle, breaks on different line heights */
.btn svg {
  margin-top: 2px;
}

• Icon color: inherit from text color by default (currentColor), or use a slightly muted tone for decorative icons

Chips / Tags

Chips are NOT buttons. They're thinner, never use primary CTA color, and serve as filters, breadcrumbs, or status indicators.

Sizing rule: vertical padding = 1/2 or 1/4 of horizontal padding. If horizontal is 16px, vertical is 4-8px. This keeps chips visibly thinner than buttons. Use auto-layout (flexbox) so chips adapt to content length.

.chip {
  display: inline-flex;
  align-items: center;
  gap: 6px;
  padding: 4px 12px;        /* vertical = 1/3 of horizontal */
  border-radius: 9999px;    /* pill shape */
  font-size: 13px;
  font-weight: 500;
  background: var(--color-bg-tertiary);
  color: var(--color-text-secondary);
}
.chip--active {
  background: var(--color-primary-50);
  color: var(--color-primary-600);
}

Button groups

Connected (segmented control style):

.btn-group .btn:not(:first-child):not(:last-child) {
  border-radius: 0;
}
.btn-group .btn:first-child {
  border-radius: 6px 0 0 6px;
}
.btn-group .btn:last-child {
  border-radius: 0 6px 6px 0;
}
/* Collapse double borders */
.btn-group .btn + .btn {
  margin-left: -1px;
}

Separated:

.btn-group-separated {
  display: flex;
  gap: 8px;
}

• Icon-only button groups: keep all buttons equal width, consistent icon sizing across all

Loading state buttons

• Replace text with spinner, but keep the button the same width - use min-width set to the button's natural width
• Disable pointer events and interaction during loading
• Spinner size: 16px for sm/md, 20px for lg, always centered
• Pattern: keep original label visible, add spinner to the left, hide the icon if one was present

<!-- Default -->
<button class="btn-primary">
  <SaveIcon size={16} />
  Save changes
</button>

<!-- Loading -->
<button class="btn-primary" disabled>
  <Spinner size={16} />
  Save changes
</button>

Tailwind examples

Primary button

<button class="inline-flex items-center justify-content-center gap-1.5 min-w-[80px] h-10 px-5 rounded-md bg-blue-600 text-white text-sm font-medium transition-colors hover:bg-blue-700 active:bg-blue-800 active:scale-[0.98] focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-blue-500 disabled:opacity-50 disabled:cursor-not-allowed disabled:pointer-events-none">
  Save
</button>

Secondary (outlined) button

<button class="inline-flex items-center justify-center gap-1.5 min-w-[80px] h-10 px-5 rounded-md border border-gray-300 bg-white text-gray-700 text-sm font-medium transition-colors hover:bg-gray-50 hover:border-gray-400 active:bg-gray-100 active:scale-[0.98] focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-blue-500 disabled:opacity-50 disabled:cursor-not-allowed disabled:pointer-events-none">
  Cancel
</button>

Ghost button

<button class="inline-flex items-center justify-center gap-1.5 min-w-[80px] h-10 px-5 rounded-md bg-transparent text-gray-700 text-sm font-medium transition-colors hover:bg-gray-100 active:bg-gray-200 active:scale-[0.98] focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-blue-500 disabled:opacity-50 disabled:cursor-not-allowed disabled:pointer-events-none">
  Learn more
</button>

Icon-only button

<!-- 44x44px touch target, 20px icon -->
<button class="inline-flex items-center justify-center w-11 h-11 rounded-md text-gray-600 transition-colors hover:bg-gray-100 hover:text-gray-900 active:bg-gray-200 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-blue-500 disabled:opacity-50 disabled:cursor-not-allowed disabled:pointer-events-none" aria-label="Settings">
  <SettingsIcon size={20} />
</button>

Button with icon + text

<!-- Action: icon on the left -->
<button class="inline-flex items-center justify-center gap-1.5 h-10 px-5 rounded-md bg-blue-600 text-white text-sm font-medium hover:bg-blue-700 active:bg-blue-800 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-blue-500">
  <PlusIcon size={16} />
  Add item
</button>

<!-- Navigation: icon on the right -->
<button class="inline-flex items-center justify-center gap-1.5 h-10 px-5 rounded-md bg-blue-600 text-white text-sm font-medium hover:bg-blue-700 active:bg-blue-800 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-blue-500">
  Next
  <ArrowRightIcon size={16} />
</button>

Disabled state

<button class="... opacity-50 cursor-not-allowed pointer-events-none" disabled>
  Submit
</button>

Loading state

<button class="inline-flex items-center justify-center gap-1.5 min-w-[120px] h-10 px-5 rounded-md bg-blue-600 text-white text-sm font-medium opacity-80 cursor-not-allowed pointer-events-none" disabled>
  <Spinner size={16} class="animate-spin" />
  Saving...
</button>

Common mistakes

• Buttons too small: under 36px height fails usability; under 44px fails touch target guidelines (WCAG 2.5.5)
• Color alone for hierarchy: primary vs secondary must differ structurally (filled vs outlined) - color alone is insufficient for accessibility
• Missing focus-visible: skipping focus styles breaks keyboard navigation; :focus alone fires on click too, use :focus-visible
• <a> styled as button or <button> styled as link: use the correct element - <button> for actions, <a> for navigation
• Inconsistent border-radius: buttons must match the radius used across the rest of the UI (cards, inputs, modals)
• No transition: state changes (hover, active) without transition feel jarring; use transition-colors 120ms ease
• Icon and text misaligned: always use display: flex; align-items: center - never nudge with margin-top
• Loading state changes button width: set min-width equal to the resting button width to prevent layout shift
• Using emojis as icons or status indicators: emojis are images controlled by the OS, not the app - they break theming, dark mode, consistent sizing, and screen reader announcements. Use SVG icons from Lucide, Heroicons, Phosphor, React Icons, or Font Awesome instead

Cards and Lists

Card anatomy

• Container: border OR shadow (not both), border-radius, consistent padding 16-24px
• Title: 16-18px semibold; Description: 14px regular, secondary color, 2-3 lines max
• Metadata: 12-13px muted; Actions: bottom

.card { border-radius: 8px; padding: 20px; background: #fff; display: flex; flex-direction: column; gap: 8px; }
.card__title { font-size: 17px; font-weight: 600; line-height: 1.4; color: #111827; margin: 0; }
.card__description { font-size: 14px; color: #6b7280; line-height: 1.5; display: -webkit-box; -webkit-line-clamp: 3; -webkit-box-orient: vertical; overflow: hidden; margin: 0; }
.card__meta { font-size: 12px; color: #9ca3af; display: flex; align-items: center; gap: 6px; }
.card__actions { margin-top: auto; padding-top: 12px; display: flex; gap: 8px; }

Card variants

/* Flat - border only */
.card--flat { border: 1px solid #e5e7eb; box-shadow: none; }

/* Raised - shadow only */
.card--raised { border: none; box-shadow: 0 1px 3px rgba(0,0,0,0.1), 0 1px 2px rgba(0,0,0,0.06); }

/* Image top */
.card--image { padding: 0; overflow: hidden; border: 1px solid #e5e7eb; }
.card--image .card__image { width: 100%; aspect-ratio: 16 / 9; object-fit: cover; display: block; }
.card--image .card__body { padding: 16px 20px 20px; display: flex; flex-direction: column; gap: 8px; }

/* Horizontal - image left, content right */
.card--horizontal { flex-direction: row; padding: 0; overflow: hidden; border: 1px solid #e5e7eb; }
.card--horizontal .card__image { width: 120px; min-width: 120px; object-fit: cover; display: block; }
.card--horizontal .card__body { padding: 16px; display: flex; flex-direction: column; gap: 6px; flex: 1; min-width: 0; }

/* Interactive - entire card clickable */
.card--interactive { cursor: pointer; text-decoration: none; color: inherit; display: flex; flex-direction: column; transition: box-shadow 200ms ease, transform 200ms ease; }
.card--interactive:hover { box-shadow: 0 4px 12px rgba(0,0,0,0.12), 0 2px 4px rgba(0,0,0,0.08); transform: translateY(-2px); }
.card--interactive .card__link { pointer-events: none; } /* avoid nested interactive elements */

/* Stat/metric */
.card--stat { padding: 20px 24px; border: 1px solid #e5e7eb; }
.card__stat-value { font-size: 32px; font-weight: 700; color: #111827; line-height: 1; margin: 0 0 4px; }
.card__stat-label { font-size: 13px; color: #6b7280; font-weight: 500; margin: 0; }
.card__stat-trend { font-size: 12px; font-weight: 600; margin-top: 8px; }
.card__stat-trend--up { color: #16a34a; }
.card__stat-trend--down { color: #dc2626; }

Card grid layouts

/* Auto-fill responsive */
.card-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(min(100%, 300px), 1fr)); gap: 20px; }

/* Fixed 3-column with breakpoints */
.card-grid--fixed { display: grid; grid-template-columns: repeat(3, 1fr); gap: 20px; }
@media (max-width: 1024px) { .card-grid--fixed { grid-template-columns: repeat(2, 1fr); } }
@media (max-width: 640px) { .card-grid--fixed { grid-template-columns: 1fr; } }

/* Masonry via CSS columns */
.card-grid--masonry { columns: 3 280px; column-gap: 20px; }
.card-grid--masonry > .card { break-inside: avoid; margin-bottom: 20px; }

List views

/* Simple border-bottom list */
.list { list-style: none; margin: 0; padding: 0; }
.list__item { border-bottom: 1px solid #e5e7eb; }
.list__item:last-child { border-bottom: none; }

/* Card list - each item is a horizontal card */
.list--card { display: flex; flex-direction: column; gap: 12px; list-style: none; margin: 0; padding: 0; }
.list--card .list__item { border: 1px solid #e5e7eb; border-radius: 8px; }

/* Compact */
.list--compact .list__item-inner { padding: 8px 12px; font-size: 13px; }

/* Selectable */
.list__item--selectable { display: flex; align-items: center; gap: 12px; padding: 12px 16px; cursor: pointer; transition: background 150ms ease; }
.list__item--selectable:hover { background: #f9fafb; }
.list__item--selectable[aria-selected="true"] { background: #eff6ff; }

List item anatomy

/* Three-zone layout: left (avatar/icon) | content (title+desc) | right (meta/action) */
.list-item { display: flex; align-items: center; gap: 12px; padding: 12px 16px; min-height: 64px; }
.list-item__left { flex: 0 0 40px; width: 40px; height: 40px; display: flex; align-items: center; justify-content: center; }
.list-item__content { flex: 1; min-width: 0; } /* min-width: 0 enables text truncation */
.list-item__title { font-size: 14px; font-weight: 500; color: #111827; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; margin: 0; }
.list-item__desc { font-size: 13px; color: #6b7280; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; margin: 2px 0 0; }
.list-item__right { flex: 0 0 auto; display: flex; align-items: center; gap: 8px; font-size: 12px; color: #9ca3af; }

Infinite scroll

const sentinel = document.querySelector('#load-more-sentinel');
const observer = new IntersectionObserver(
  (entries) => {
    if (entries[0].isIntersecting && !isLoading && !isExhausted) loadMore();
  },
  { rootMargin: '200px' }
);
observer.observe(sentinel);

.load-sentinel { height: 1px; width: 100%; }
.load-more-indicator { text-align: center; padding: 20px; font-size: 14px; color: #6b7280; }
.load-end-message { text-align: center; padding: 24px; font-size: 13px; color: #9ca3af; border-top: 1px solid #f3f4f6; }

Virtualized lists

• Only render visible items + buffer (3-5 above/below viewport)
• Libraries: react-virtual, @tanstack/virtual
• Virtualize when: >100 items or complex per-item rendering
• Set explicit itemHeight for best performance

Load more patterns

Pattern	Best for
"Load more" button	Search results, directories - user-controlled, better SEO
Pagination	Data tables, admin views - predictable, bookmarkable
Infinite scroll	Social feeds, media galleries - passive consumption

.btn-load-more { display: block; margin: 24px auto 0; padding: 10px 24px; font-size: 14px; font-weight: 500; border: 1px solid #d1d5db; border-radius: 6px; background: #fff; color: #374151; cursor: pointer; transition: background 150ms ease, border-color 150ms ease; }
.btn-load-more:hover { background: #f9fafb; border-color: #9ca3af; }

Card hover effects - pick ONE, do not combine

/* 1. Shadow increase */
.card--hover-shadow { box-shadow: 0 1px 3px rgba(0,0,0,0.1); transition: box-shadow 200ms ease; }
.card--hover-shadow:hover { box-shadow: 0 4px 12px rgba(0,0,0,0.15), 0 2px 4px rgba(0,0,0,0.08); }

/* 2. Lift */
.card--hover-lift { transition: transform 200ms ease, box-shadow 200ms ease; }
.card--hover-lift:hover { transform: translateY(-2px); box-shadow: 0 4px 12px rgba(0,0,0,0.12); }

/* 3. Image zoom - scale inside overflow:hidden */
.card--hover-zoom .card__image-wrap { overflow: hidden; }
.card--hover-zoom .card__image { transition: transform 300ms ease; }
.card--hover-zoom:hover .card__image { transform: scale(1.03); }

/* 4. Border color */
.card--hover-border { border: 1px solid #e5e7eb; transition: border-color 200ms ease; }
.card--hover-border:hover { border-color: #3b82f6; }

Card skeleton loading

@keyframes skeleton-pulse { 0%, 100% { opacity: 1; } 50% { opacity: 0.4; } }

.skeleton-card { border: 1px solid #e5e7eb; border-radius: 8px; overflow: hidden; }
.skeleton-card__image { width: 100%; aspect-ratio: 16 / 9; background: #e5e7eb; animation: skeleton-pulse 1.5s ease-in-out infinite; }
.skeleton-card__body { padding: 16px 20px 20px; display: flex; flex-direction: column; gap: 10px; }
.skeleton-bar { height: 12px; border-radius: 4px; background: #e5e7eb; animation: skeleton-pulse 1.5s ease-in-out infinite; }
.skeleton-bar--title { height: 16px; width: 60%; }
.skeleton-bar--desc-1 { width: 100%; }
.skeleton-bar--desc-2 { width: 80%; }
.skeleton-bar--meta { height: 10px; width: 40%; }

Empty collection state

.empty-state { display: flex; flex-direction: column; align-items: center; justify-content: center; padding: 48px 24px; text-align: center; color: #6b7280; }
.empty-state__illustration { width: 80px; height: 80px; margin-bottom: 16px; opacity: 0.5; }
.empty-state__title { font-size: 16px; font-weight: 600; color: #374151; margin: 0 0 6px; }
.empty-state__body { font-size: 14px; color: #6b7280; margin: 0 0 20px; max-width: 320px; }

Scenarios: No items yet (CTA to add), no search results (adjust filters), error loading (retry button).

Responsive card behavior

@media (max-width: 640px) {
  .card-grid { grid-template-columns: 1fr; }
  .card--horizontal { flex-direction: column; }
  .card--horizontal .card__image { width: 100%; height: 160px; }

  /* Horizontal scroll carousel on mobile */
  .card-carousel { display: flex; gap: 16px; overflow-x: auto; scroll-snap-type: x mandatory; -webkit-overflow-scrolling: touch; scrollbar-width: none; }
  .card-carousel::-webkit-scrollbar { display: none; }
  .card-carousel > .card { flex: 0 0 280px; scroll-snap-align: start; }
}

Common card/list mistakes

• Varying card heights in a grid - use min-height on card body or fixed aspect-ratio for images
• No hover state on interactive cards - every clickable card must have a visible hover effect
• Clickable card with links inside - nested interactive elements break accessibility
• No loading state - content popping in without skeletons feels broken
• Too much text on cards - use -webkit-line-clamp: 3 to enforce 2-3 line max
• Inconsistent card padding - pick one value and apply everywhere
• No empty state - a blank grid leaves users confused

Color and Theming

The 60-30-10 Rule

• 60% dominant - background, neutral surfaces
• 30% secondary - cards, sidebars, secondary surfaces
• 10% accent - CTAs, active states, links

:root {
  /* 60% - dominant backgrounds */
  --color-bg-primary: #f8fafc;       /* slate-50 */
  --color-bg-secondary: #f1f5f9;     /* slate-100 */

  /* 30% - secondary surfaces */
  --color-surface-card: #ffffff;
  --color-surface-sidebar: #f1f5f9;

  /* 10% - accent */
  --color-accent: #4f46e5;           /* indigo-600 */
  --color-accent-hover: #4338ca;     /* indigo-700 */
}

Color Boldness

Timid, evenly-distributed palettes are the hallmark of AI-generated UIs. Bold design uses dominant colors with sharp accents.

The AI slop palette: light gray background, indigo/purple primary, generic blue links, faint pastel accents. You've seen it on every AI-generated landing page. Don't do this.

Rules for distinctive color:

• Commit to a dominant hue - let it be felt. A teal-dominant dashboard, a warm amber editorial site, a deep forest green SaaS. The 60% should have personality, not just be gray.
• Sharp accents over soft gradients - a single high-saturation accent color against muted surroundings creates more visual punch than gradient washes
• Context-specific palettes - a finance app should feel different from a creative tool. A health product different from a developer tool. Let the domain inform the palette.
• Vary between projects - if your last 3 projects all used indigo/purple, you're in a rut. Try warm tones (amber, terracotta, olive), cool tones (teal, cyan, slate-blue), or neutrals with a single bright accent.

/* AVOID: the generic AI palette */
--primary: #6366f1;     /* indigo - every AI project uses this */
--bg: #f9fafb;          /* gray-50 - zero personality */

/* BETTER: context-specific, bold */
/* Finance/Trust: deep navy + gold accent */
--primary: #1e3a5f;
--accent: #d4a843;
--bg: #f5f3ef;

/* Creative tool: warm coral + teal */
--primary: #e85d4a;
--accent: #2a9d8f;
--bg: #faf6f1;

/* Developer tool: forest green + lime */
--primary: #1a4a3a;
--accent: #84cc16;
--bg: #f0f4f1;

Tailwind shortcut for tinted backgrounds (impossible to mess up): light mode = use the 50 shade as bg + 500 as accent. Dark mode = 950 as bg + 300 as accent. Works for every Tailwind color. Example: blue-50 bg + blue-500 accent in light mode; blue-950 bg + blue-300 accent in dark mode.

---

Building a Palette

Use HSL (or OKLCH), not hex/RGB. Hex and RGB make shade creation guesswork. HSL makes it math: fix hue and saturation, vary lightness. Three similar grays in hex look random in code; in HSL they're obviously related.

Quick neutral palette from scratch: set saturation to 0 (pure neutral). For dark mode backgrounds: 0% lightness (base), 5% (cards/surfaces), 10% (raised elements). Lighter = elevated = more important. For text: ~90% lightness for headings (not 100% - pure white is harsh), ~60% for secondary. To create light mode: subtract each lightness from 100 as a starting point, then manually adjust. Swap layer order - the base should be darkest in dark mode, lightest in light mode.

Name tokens by relative weight, not by mode: use bg-dark (deepest layer) and bg-light (raised surface) - these names work in both dark and light themes.

Quick color harmony formula: pick your primary hue, then move ±60° on the color wheel for tertiary/accent colors. This creates a 120° arc - the natural distance between primary colors. Example: primary at 220° → tertiary at 160° (teal) and accent at 280° (purple). Change just the hue value to test entirely different palettes in seconds.

Brand color shades - start with ONE brand hue and generate 10 shades using HSL:

• Fix the hue (e.g., 243 for indigo)
• 50-400: keep saturation moderate, increase lightness toward 100%
• 500: base color, full saturation
• 600-900: increase saturation slightly, decrease lightness toward 10%

HSL formulas for a brand hue of 243:

Shade	HSL	Hex	Usage
50	hsl(243, 60%, 97%)	#f5f3ff	Page backgrounds, tints
100	hsl(243, 65%, 93%)	#ede9fe	Hover backgrounds
200	hsl(243, 68%, 85%)	#c4b5fd	Focus rings, subtle fill
300	hsl(243, 72%, 74%)	#a78bfa	Decorative, disabled icons
400	hsl(243, 76%, 63%)	#818cf8	Links in dark mode
500	hsl(243, 80%, 55%)	#6366f1	Base brand color
600	hsl(243, 83%, 47%)	#4f46e5	Primary CTA, links
700	hsl(243, 86%, 40%)	#4338ca	Hover state on CTA
800	hsl(243, 88%, 30%)	#3730a3	Active/pressed state
900	hsl(243, 90%, 20%)	#312e81	Text on light backgrounds

Neutral gray (tinted, not pure): use your brand hue at 3-5% saturation.

/* Pure gray: hsl(0, 0%, L%) - AVOID */
/* Tinted neutral: hsl(243, 4%, L%) - USE THIS */

--neutral-50:  hsl(243, 4%, 98%);   /* #f8f8fb */
--neutral-100: hsl(243, 4%, 95%);   /* #f1f1f6 */
--neutral-200: hsl(243, 4%, 89%);   /* #e2e2ea */
--neutral-300: hsl(243, 4%, 78%);   /* #c5c5d0 */
--neutral-400: hsl(243, 4%, 63%);   /* #9e9eac */
--neutral-500: hsl(243, 4%, 48%);   /* #787885 */
--neutral-600: hsl(243, 4%, 36%);   /* #5a5a65 */
--neutral-700: hsl(243, 5%, 26%);   /* #403f4c */
--neutral-800: hsl(243, 6%, 16%);   /* #272631 */
--neutral-900: hsl(243, 7%, 10%);   /* #17161f */

---

Semantic Color Tokens

Map palette values to semantic names. Never use raw palette tokens in components - always go through semantic tokens.

:root {
  /* Backgrounds */
  --color-bg-primary:    #f8f8fb;   /* neutral-50 */
  --color-bg-secondary:  #f1f1f6;   /* neutral-100 */
  --color-bg-tertiary:   #e2e2ea;   /* neutral-200 */

  /* Text */
  --color-text-primary:   #17161f;  /* neutral-900 */
  --color-text-secondary: #5a5a65;  /* neutral-600 */
  --color-text-tertiary:  #9e9eac;  /* neutral-400 */

  /* Borders */
  --color-border:        #e2e2ea;   /* neutral-200 */
  --color-border-strong: #c5c5d0;   /* neutral-300 */

  /* Status */
  --color-success: #16a34a;   /* green-600  */
  --color-warning: #d97706;   /* amber-600  */
  --color-error:   #dc2626;   /* red-600    */
  --color-info:    #2563eb;   /* blue-600   */
}

---

Product Design Color Depth

Product UIs need more neutrals than landing pages. Minimum: 4 background layers, 2 stroke colors, 3 text variants. Plus hover states.

• Borders: use ~85% white, not black - defines edges without overpowering. Black borders are harsh; subtle gray strokes are professional.
• Button darkness = importance - ghost (lightest) → secondary (~90-95% white) → primary (brand) → black with white text (most important). Hierarchy through value, not hue.
• OKLCH for chart palettes - set constant lightness + chroma, increment hue by 25-30° per color. Gets perceptually uniform brightness across the spectrum. Solves "bright green looks more neon than bright blue."
• OKLCH theming shortcut - for any neutral: drop lightness 0.03, increase chroma 0.02, set hue to desired color. Instant themed version of any design.

Dark Mode Implementation

Rules:

• NEVER just invert colors - inversion breaks hue relationships and contrast
• Double the distance - light mode backgrounds differ by ~2% brightness. Dark mode needs 4-6% between layers because dark colors look more similar. Reflecting your light palette directly will lose all distinction.
• Use dark blue-grays for backgrounds, not pure black (#000000)
• Reduce text brightness to #f1f5f9, not #ffffff (prevents eye strain)
• Increase shadow opacity from 0.1 to 0.3-0.5
• Surfaces always get lighter as they elevate - no exceptions in dark mode
• Use lighter border colors - borders need more contrast on dark surfaces
• Slightly reduce image brightness: filter: brightness(0.9) contrast(0.95)

Dark backgrounds to use:

• #0f172a (slate-950) - deepest background layer
• #1e293b (slate-800) - primary page background
• #334155 (slate-700) - cards, elevated surfaces
• #475569 (slate-600) - hover states, secondary surfaces

[data-theme="dark"],
@media (prefers-color-scheme: dark) {
  /* Backgrounds */
  --color-bg-primary:    #1e293b;   /* slate-800 */
  --color-bg-secondary:  #0f172a;   /* slate-950 */
  --color-bg-tertiary:   #334155;   /* slate-700 */

  /* Text - reduced brightness, never pure white */
  --color-text-primary:   #f1f5f9;  /* slate-100 */
  --color-text-secondary: #94a3b8;  /* slate-400 */
  --color-text-tertiary:  #64748b;  /* slate-500 */

  /* Borders - more visible on dark */
  --color-border:        #334155;   /* slate-700 */
  --color-border-strong: #475569;   /* slate-600 */

  /* Status - shift to lighter shades for contrast on dark */
  --color-success: #4ade80;   /* green-400  */
  --color-warning: #fbbf24;   /* amber-400  */
  --color-error:   #f87171;   /* red-400    */
  --color-info:    #60a5fa;   /* blue-400   */

  /* Shadows need more opacity in dark mode */
  --shadow-sm: 0 1px 2px hsl(0 0% 0% / 0.4);
  --shadow-md: 0 4px 6px hsl(0 0% 0% / 0.45);
  --shadow-lg: 0 10px 15px hsl(0 0% 0% / 0.5);

  /* Slightly dim images */
  img {
    filter: brightness(0.9) contrast(0.95);
  }
}

Card depth recipe (dark mode): combine a lighter top border ("highlight" - simulates light from above), a gradient using your bg shades, and dual-layer shadows (darker+shorter + lighter+longer). This sells the illusion of physical depth:

.card-depth {
  background: linear-gradient(to bottom, var(--bg-light), var(--bg-mid));
  border: 1px solid var(--border);
  border-top-color: var(--highlight);  /* lighter top edge = light from above */
  box-shadow:
    0 2px 4px rgba(0, 0, 0, 0.3),    /* darker, shorter */
    0 8px 16px rgba(0, 0, 0, 0.15);   /* lighter, longer */
}

In light mode, the highlight becomes white (lightness: 100%), the border blends into the card background, and the shadow becomes the primary depth cue.

---

Theme Switching

Structure: :root defines light defaults, [data-theme="dark"] overrides, @media is the fallback.

/* 1. Light defaults on :root */
:root {
  --color-bg-primary: #f8f8fb;
  --color-text-primary: #17161f;
  /* ... full token set */
}

/* 2. Manual dark override via data attribute */
[data-theme="dark"] {
  --color-bg-primary: #1e293b;
  --color-text-primary: #f1f5f9;
  /* ... full dark token set */
}

/* 3. System preference fallback (no JS required) */
@media (prefers-color-scheme: dark) {
  :root:not([data-theme="light"]) {
    --color-bg-primary: #1e293b;
    --color-text-primary: #f1f5f9;
    /* ... full dark token set */
  }
}

// Theme toggle - store preference, respect system default
const STORAGE_KEY = 'theme-preference';

function getPreferredTheme() {
  const stored = localStorage.getItem(STORAGE_KEY);
  if (stored) return stored;
  return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
}

function applyTheme(theme) {
  document.documentElement.setAttribute('data-theme', theme);
  localStorage.setItem(STORAGE_KEY, theme);
}

function toggleTheme() {
  const current = document.documentElement.getAttribute('data-theme');
  applyTheme(current === 'dark' ? 'light' : 'dark');
}

// On page load - apply before paint to prevent flash
applyTheme(getPreferredTheme());

// Listen for system changes when no manual preference is set
window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', (e) => {
  if (!localStorage.getItem(STORAGE_KEY)) {
    applyTheme(e.matches ? 'dark' : 'light');
  }
});

---

Contrast and Readability

WCAG requirements:

• AA (minimum): 4.5:1 for normal text, 3:1 for large text (18px+ regular, or 14px+ bold)
• AAA (enhanced): 7:1 for normal text, 4.5:1 for large text

Perceptually uniform manipulation: use oklch() or oklab() instead of hsl() when fine-tuning accessible contrast - HSL is not perceptually uniform so equal lightness steps look unequal.

/* oklch(lightness chroma hue) - perceptually uniform */
--color-accent-light: oklch(0.95 0.02 264);  /* very light */
--color-accent-base:  oklch(0.55 0.18 264);  /* 4.5:1 on white */
--color-accent-dark:  oklch(0.35 0.15 264);  /* 7:1 on white */

Common failing combos - never use these:

• #9ca3af (gray-400) on #ffffff - ratio ~2.7:1, fails AA
• #fbbf24 (amber-400) on #ffffff - ratio ~2.1:1, fails AA
• #60a5fa (blue-400) on #ffffff - ratio ~3.0:1, fails AA for normal text
• #d1d5db (gray-300) on #ffffff - ratio ~1.6:1, fails everything

Safe swap: shift to -600 variants in light mode and -400 variants in dark mode to reliably clear AA.

---

OKLCH: The Modern Color Format

HSL's biggest flaw: lightness steps don't look uniform. A 10% lightness jump at high saturation looks different than at low saturation. OKLCH fixes this with perceptually uniform steps - Tailwind v4 uses it as the default.

OKLCH values: oklch(lightness chroma hue)

• Lightness: 0 (black) to 1 (white) - perceptually uniform
• Chroma: 0 (gray) to ~0.4 (max saturation) - for UI work, rarely above 0.15-0.2
• Hue: 0 to 360, same as HSL

/* Neutral palette in OKLCH */
--bg-dark:    oklch(0.15 0 0);   /* base layer */
--bg-mid:     oklch(0.20 0 0);   /* cards, surfaces */
--bg-light:   oklch(0.25 0 0);   /* raised elements */
--text-primary:   oklch(0.90 0 0);   /* headings - not 1.0, too harsh */
--text-secondary: oklch(0.65 0 0);   /* body text */

/* Adding brand hue - just set chroma > 0 */
--bg-dark:    oklch(0.15 0.01 250);  /* barely tinted */
--primary:    oklch(0.55 0.18 250);  /* full brand color */
--accent:     oklch(0.70 0.15 30);   /* warm accent */

When to use OKLCH over HSL: generating shade ramps (more uniform steps), fine-tuning contrast ratios, or when using Tailwind v4+. HSL is fine for quick prototyping and simple palettes.

---

Color in Context

Context	Light mode	Hex	Dark mode	Hex
Links	primary-600	#4f46e5	primary-400	#818cf8
Link hover	primary-700	#4338ca	primary-300	#a78bfa
Success	green-600	#16a34a	green-400	#4ade80
Error	red-600	#dc2626	red-400	#f87171
Warning	amber-600	#d97706	amber-400	#fbbf24
Info	blue-600	#2563eb	blue-400	#60a5fa
Disabled text	gray-400	#9ca3af	gray-600	#4b5563
Disabled bg	gray-100	#f3f4f6	gray-800	#1f2937

Notes:

• Success: use green-600/green-400, never neon green (#00ff00)
• Error: use muted red, not bright red - red-600 is #dc2626, not #ff0000
• Warning: amber reads better than yellow - yellow fails contrast on white at any shade

---

Neutral Balance and Color Restraint

Just like whitespace lets elements breathe, using mostly neutrals lets the few colored elements stand out. This is "neutral balance."

• Backgrounds should stay in the background - almost never use bright colors for backgrounds. Start with neutral gray bg + white/light foreground.
• Icons need no color by default - their job is to be recognizable symbols. Reserve icon color only for status: active tab, selected state, notification dot.
• Extending a limited brand palette - if you only have one brand color, rotate ±30° on the hue wheel for analogous colors, or go across for complementary. This gives you a chart palette, chip colors, and accent variations from a single starting hue.
• Element states through color alone - hover: slightly lighter/brighter. Active/pressed: slightly darker. Disabled: desaturate. Often no other visual cue is needed.
• When card backgrounds add clutter, use borders instead - a simple 1px border on white/transparent cards is often cleaner than colored backgrounds competing for attention.

Common Color Mistakes

1. Too many hues - stick to 1 brand hue + 1 neutral + status colors. More than 3 hues looks unfocused.

2. Pure gray neutrals - hsl(0, 0%, 50%) looks flat and disconnected from your brand. Always add 3-5% saturation of your brand hue.

3. Same shade, different purpose - if your border and your disabled text both use gray-300, they will compete. Assign distinct shades to distinct roles.

4. Skipping contrast checks - use the browser DevTools accessibility panel or whocanuse.com before shipping. Check all state variants (hover, focus, disabled).

5. Dark mode as afterthought - if you define tokens once and invert at the end, you will break contrast relationships. Define dark mode tokens alongside light from the start.

6. Hardcoding hex in components - always reference --color-text-primary, never #17161f directly. Tokens are the contract; components consume them.

7. Defaulting to indigo/purple - it's the #1 AI-generated color choice. #6366f1 and #4f46e5 appear in almost every AI-built interface. If you catch yourself reaching for indigo as the brand color without a specific reason, stop and pick something that serves the project's actual context and audience.