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

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

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

Match icon optical size to text size - mixing sizes creates visual imbalance:

• 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

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

.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 */
}

Building a Palette

Start with ONE brand color and generate 10 shades using HSL manipulation.

Strategy:

• 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:

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   */
}

Dark Mode Implementation

Rules:

• NEVER just invert colors - inversion breaks hue relationships and contrast
• 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
• 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);
  }
}

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.

Color in Context

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

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.

Dashboards

Dashboard layout

• Sidebar (240-280px) + main content area
• Main content: top bar (filters, date range, title) + grid of widgets
• Widget grid: CSS Grid with auto-fill, varied sizes
• Max content width: 1440px; padding: 24-32px around content area

.dashboard-shell { display: flex; min-height: 100vh; background-color: #f4f5f7; }

.dashboard-sidebar {
  width: 260px;
  flex-shrink: 0;
  background-color: #1e2235;
  color: #c8ccd8;
  display: flex;
  flex-direction: column;
  transition: width 0.2s ease;
}
.dashboard-sidebar.collapsed { width: 64px; }

.dashboard-main { flex: 1; min-width: 0; display: flex; flex-direction: column; max-width: 1440px; }
.dashboard-content { padding: 24px 32px; flex: 1; }

KPI / stat cards

• Number: 28-32px, font-weight 700, color #111827
• Label: 12px, color #6b7280, font-weight 600, uppercase + letter-spacing
• Trend: green (#16a34a) up, red (#dc2626) down; grid: repeat(4,1fr) desktop

.kpi-grid { display: grid; grid-template-columns: repeat(4, 1fr); gap: 20px; margin-bottom: 28px; }

.kpi-card {
  background: #fff;
  border: 1px solid #e5e7eb;
  border-radius: 12px;
  padding: 20px 24px;
  display: flex;
  flex-direction: column;
  gap: 8px;
}

.kpi-label { font-size: 12px; font-weight: 600; color: #6b7280; text-transform: uppercase; letter-spacing: 0.06em; }
.kpi-value { font-size: 30px; font-weight: 700; color: #111827; line-height: 1; }
.kpi-trend { display: inline-flex; align-items: center; gap: 4px; font-size: 13px; font-weight: 500; }
.kpi-trend--up { color: #16a34a; }
.kpi-trend--down { color: #dc2626; }
.kpi-trend__label { font-size: 12px; color: #9ca3af; margin-left: 4px; font-weight: 400; }

Chart containers

• Title: 16px font-weight 600, subtitle: 13px #6b7280; chart area: min-height 200px
• Same border/radius as KPI cards; skeleton on load, empty state when no data

.chart-card {
  background: #fff;
  border: 1px solid #e5e7eb;
  border-radius: 12px;
  padding: 20px 24px;
  display: flex;
  flex-direction: column;
  gap: 4px;
}
.chart-card__header { display: flex; justify-content: space-between; align-items: flex-start; margin-bottom: 16px; }
.chart-card__title { font-size: 16px; font-weight: 600; color: #111827; }
.chart-card__subtitle { font-size: 13px; color: #6b7280; margin-top: 2px; }
.chart-card__area { min-height: 200px; flex: 1; }
.chart-card__legend { display: flex; flex-wrap: wrap; gap: 12px; margin-top: 12px; font-size: 12px; color: #6b7280; }
.chart-card__legend-item { display: flex; align-items: center; gap: 6px; }
.chart-card__legend-dot { width: 8px; height: 8px; border-radius: 50%; flex-shrink: 0; }

.chart-skeleton {
  background: linear-gradient(90deg, #f3f4f6 25%, #e5e7eb 50%, #f3f4f6 75%);
  background-size: 200% 100%;
  animation: skeleton-sweep 1.4s ease infinite;
  border-radius: 8px;
  min-height: 200px;
}
@keyframes skeleton-sweep {
  0% { background-position: 200% 0; }
  100% { background-position: -200% 0; }
}

.chart-empty { min-height: 200px; display: flex; flex-direction: column; align-items: center; justify-content: center; gap: 8px; color: #9ca3af; font-size: 14px; }

Data widgets

• Activity list: 36px avatar, 13px description, 11px timestamp #9ca3af
• Notification: unread dot 8px #3b82f6; "View all" link 13px #3b82f6 at bottom

.activity-item { display: flex; align-items: flex-start; gap: 12px; padding: 12px 0; border-bottom: 1px solid #f3f4f6; }
.activity-item:last-child { border-bottom: none; padding-bottom: 0; }
.activity-avatar { width: 36px; height: 36px; border-radius: 50%; flex-shrink: 0; background-color: #e5e7eb; overflow: hidden; }
.activity-body { flex: 1; min-width: 0; }
.activity-description { font-size: 13px; color: #374151; line-height: 1.4; }
.activity-description strong { font-weight: 600; color: #111827; }
.activity-timestamp { font-size: 11px; color: #9ca3af; margin-top: 2px; }

.notification-unread-dot { width: 8px; height: 8px; border-radius: 50%; background-color: #3b82f6; flex-shrink: 0; margin-top: 5px; }

.widget-footer-link { display: block; text-align: center; font-size: 13px; font-weight: 500; color: #3b82f6; padding-top: 12px; border-top: 1px solid #f3f4f6; margin-top: 8px; text-decoration: none; }
.widget-footer-link:hover { color: #2563eb; }

Filter bar

• Horizontal bar, sticky top, 48px height, background #fff, border-bottom #e5e7eb
• Applied filter chips: background #eff6ff, color #1d4ed8, border #bfdbfe, border-radius 8px

.filter-bar {
  display: flex;
  align-items: center;
  gap: 12px;
  padding: 10px 32px;
  background: #fff;
  border-bottom: 1px solid #e5e7eb;
  flex-wrap: wrap;
  position: sticky;
  top: 0;
  z-index: 20;
}

.filter-chip { display: inline-flex; align-items: center; gap: 6px; height: 28px; padding: 0 10px; background-color: #eff6ff; color: #1d4ed8; font-size: 12px; font-weight: 500; border-radius: 8px; border: 1px solid #bfdbfe; white-space: nowrap; }
.filter-chip__remove { width: 14px; height: 14px; border-radius: 50%; cursor: pointer; opacity: 0.6; transition: opacity 0.15s; }
.filter-chip__remove:hover { opacity: 1; }
.filter-clear-all { font-size: 13px; color: #6b7280; background: none; border: none; cursor: pointer; text-decoration: underline; }
.filter-clear-all:hover { color: #374151; }

Date range controls

• Presets: Today / Last 7d / Last 30d / This month / Custom
• Active preset: background #1d4ed8 color #fff; inactive: border #d1d5db

.date-range-selector { display: flex; align-items: center; gap: 4px; background: #f9fafb; border: 1px solid #e5e7eb; border-radius: 8px; padding: 3px; }
.date-range-preset { font-size: 12px; font-weight: 500; color: #374151; padding: 5px 10px; border-radius: 6px; border: none; background: transparent; cursor: pointer; white-space: nowrap; transition: background 0.15s, color 0.15s; }
.date-range-preset:hover { background: #e5e7eb; }
.date-range-preset.active { background: #1d4ed8; color: #fff; }
.date-range-custom-inputs input[type="date"] { font-size: 12px; border: 1px solid #d1d5db; border-radius: 6px; padding: 4px 8px; color: #111827; }

Dashboard grid patterns

/* Equal auto-fill grid */
.widget-grid--equal { display: grid; grid-template-columns: repeat(auto-fill, minmax(300px, 1fr)); gap: 20px; }

/* Mixed-size grid */
.widget-grid--mixed { display: grid; grid-template-columns: repeat(4, 1fr); grid-auto-rows: minmax(180px, auto); gap: 20px; }
.widget--wide { grid-column: span 2; }
.widget--tall { grid-row: span 2; }
.widget--full { grid-column: 1 / -1; }

/* Named areas (3-col) */
.widget-grid--named {
  display: grid;
  grid-template-columns: repeat(3, 1fr);
  gap: 20px;
  grid-template-areas:
    "kpi1 kpi2 kpi3"
    "chart chart activity"
    "table table map";
}
.widget--kpi1 { grid-area: kpi1; } .widget--kpi2 { grid-area: kpi2; } .widget--kpi3 { grid-area: kpi3; }
.widget--chart { grid-area: chart; } .widget--activity { grid-area: activity; }
.widget--table { grid-area: table; } .widget--map { grid-area: map; }

/* Masonry with fixed row tracks */
.widget-grid--masonry { display: grid; grid-template-columns: repeat(3, 1fr); grid-auto-rows: 80px; gap: 16px; }
.widget--masonry-sm { grid-row: span 2; }
.widget--masonry-md { grid-row: span 3; }
.widget--masonry-lg { grid-row: span 4; }

Responsive dashboard

@media (max-width: 1023px) {
  .dashboard-sidebar { width: 64px; }
  .dashboard-sidebar .nav-label { display: none; }
  .kpi-grid { grid-template-columns: repeat(2, 1fr); }
  .widget-grid--mixed { grid-template-columns: repeat(2, 1fr); }
}

@media (max-width: 767px) {
  .dashboard-shell { flex-direction: column; }
  .dashboard-sidebar { width: 100%; height: 56px; flex-direction: row; align-items: center; padding: 0 16px; }
  .dashboard-content { padding: 16px; }
  .kpi-grid { grid-template-columns: 1fr; }
  .kpi-grid--scroll-mobile { display: flex; overflow-x: auto; gap: 12px; padding-bottom: 8px; scrollbar-width: none; }
  .kpi-grid--scroll-mobile::-webkit-scrollbar { display: none; }
  .kpi-grid--scroll-mobile .kpi-card { min-width: 180px; flex-shrink: 0; }
  .widget-grid--mixed { grid-template-columns: 1fr; }
  .widget--wide, .widget--tall { grid-column: span 1; grid-row: span 1; }
  .filter-bar { padding: 8px 16px; }
}

Real-time updates

@keyframes flash-positive {
  0%, 60% { background-color: #dcfce7; color: #15803d; }
  100% { background-color: transparent; color: inherit; }
}
@keyframes flash-negative {
  0%, 60% { background-color: #fee2e2; color: #b91c1c; }
  100% { background-color: transparent; color: inherit; }
}
.kpi-value--updated-up { animation: flash-positive 1.2s ease forwards; border-radius: 4px; padding: 0 4px; }
.kpi-value--updated-down { animation: flash-negative 1.2s ease forwards; border-radius: 4px; padding: 0 4px; }

@keyframes pulse-dot {
  0%, 100% { opacity: 1; transform: scale(1); }
  50% { opacity: 0.4; transform: scale(0.75); }
}
.live-indicator { display: inline-flex; align-items: center; gap: 6px; font-size: 11px; color: #9ca3af; }
.live-indicator__dot { width: 7px; height: 7px; border-radius: 50%; background-color: #22c55e; animation: pulse-dot 2s ease-in-out infinite; }
.updated-label { font-size: 12px; color: #9ca3af; }

Dashboard header

• Height: 60px; sticky top z-index 30; left: title 20px/700 + breadcrumb; right: action buttons + 32px avatar

.dashboard-header { height: 60px; display: flex; align-items: center; justify-content: space-between; padding: 0 32px; background: #fff; border-bottom: 1px solid #e5e7eb; flex-shrink: 0; position: sticky; top: 0; z-index: 30; }
.dashboard-header__title { font-size: 20px; font-weight: 700; color: #111827; line-height: 1; }
.dashboard-header__breadcrumb { font-size: 12px; color: #6b7280; display: flex; align-items: center; gap: 4px; }
.dashboard-header__action-btn { display: flex; align-items: center; gap: 6px; font-size: 13px; font-weight: 500; color: #374151; background: #f9fafb; border: 1px solid #e5e7eb; border-radius: 8px; padding: 6px 14px; cursor: pointer; transition: background 0.15s; }
.dashboard-header__action-btn:hover { background: #f3f4f6; }
.dashboard-header__avatar { width: 32px; height: 32px; border-radius: 50%; background-color: #e5e7eb; cursor: pointer; overflow: hidden; }

Empty / error states

.dashboard-empty { display: flex; flex-direction: column; align-items: center; justify-content: center; padding: 80px 24px; text-align: center; gap: 12px; }
.dashboard-empty__icon { width: 48px; height: 48px; color: #d1d5db; }
.dashboard-empty__heading { font-size: 20px; font-weight: 600; color: #111827; }
.dashboard-empty__description { font-size: 14px; color: #6b7280; max-width: 360px; line-height: 1.5; }
.dashboard-empty__cta { margin-top: 8px; padding: 10px 20px; font-size: 14px; font-weight: 600; background: #1d4ed8; color: #fff; border-radius: 8px; border: none; cursor: pointer; }
.dashboard-empty__cta:hover { background: #1e40af; }

.widget-error { display: flex; flex-direction: column; align-items: center; justify-content: center; gap: 8px; min-height: 140px; color: #9ca3af; font-size: 13px; }
.widget-error__retry { font-size: 13px; font-weight: 500; color: #3b82f6; background: none; border: none; cursor: pointer; padding: 4px 8px; border-radius: 4px; }
.widget-error__retry:hover { background: #eff6ff; }

Common dashboard mistakes

• Too many KPIs (max 4-6 on first view)
• Charts without context (no comparison, no trend)
• No loading states per widget (whole-page spinner is bad)
• Fixed layouts that break on tablet
• Tiny text to fit more data (use scrollable widgets instead)
• No date range context shown to user

Design Tokens and Theming Architecture

What are design tokens

• Named values for design decisions (colors, spacing, typography, shadows)
• Single source of truth - change once, update everywhere
• Enable theming (light/dark, multi-brand); in CSS: custom properties

Token naming convention

Three-tier naming:

1. Global/primitive: raw values (--blue-500: #3b82f6)
2. Semantic/alias: purpose-based (--color-primary: var(--blue-500))
3. Component: scoped (--btn-bg: var(--color-primary))

Rules: always use semantic tokens in components (never primitives directly). Pattern: --{category}-{property}-{variant}-{state}

Complete token system

Color tokens - Primitives

:root {
  /* Gray scale */
  --gray-50: #f9fafb;  --gray-100: #f3f4f6;  --gray-200: #e5e7eb;  --gray-300: #d1d5db;
  --gray-400: #9ca3af; --gray-500: #6b7280;  --gray-600: #4b5563;  --gray-700: #374151;
  --gray-800: #1f2937; --gray-900: #111827;

  /* Primary (indigo) */
  --primary-50: #eef2ff;  --primary-100: #e0e7ff;  --primary-200: #c7d2fe;
  --primary-300: #a5b4fc; --primary-400: #818cf8;  --primary-500: #6366f1;
  --primary-600: #4f46e5; --primary-700: #4338ca;  --primary-800: #3730a3; --primary-900: #312e81;

  /* Red */
  --red-50: #fef2f2;  --red-100: #fee2e2;  --red-400: #f87171;
  --red-500: #ef4444; --red-600: #dc2626;  --red-700: #b91c1c;

  /* Green */
  --green-50: #f0fdf4;   --green-100: #dcfce7; --green-400: #4ade80;
  --green-500: #22c55e;  --green-600: #16a34a; --green-700: #15803d;

  /* Amber */
  --amber-50: #fffbeb;   --amber-100: #fef3c7; --amber-400: #fbbf24;
  --amber-500: #f59e0b;  --amber-600: #d97706; --amber-700: #b45309;

  /* Blue */
  --blue-50: #eff6ff;   --blue-100: #dbeafe; --blue-400: #60a5fa;
  --blue-500: #3b82f6;  --blue-600: #2563eb; --blue-700: #1d4ed8;
}

Color tokens - Semantic (light theme)

:root {
  --color-bg-primary: #ffffff;  --color-bg-secondary: var(--gray-50);  --color-bg-tertiary: var(--gray-100);
  --color-text-primary: var(--gray-900);  --color-text-secondary: var(--gray-600);
  --color-text-tertiary: var(--gray-400);  --color-text-inverted: #ffffff;
  --color-border: var(--gray-200);  --color-border-strong: var(--gray-400);
  --color-ring: var(--primary-500);
  --color-surface: #ffffff;  --color-surface-elevated: #ffffff;
  --color-interactive-primary: var(--primary-600);
  --color-interactive-primary-hover: var(--primary-700);
  --color-interactive-primary-active: var(--primary-800);
  --color-interactive-destructive: var(--red-600);
  --color-interactive-destructive-hover: var(--red-700);
  --color-success: var(--green-600);    --color-success-bg: var(--green-50);    --color-success-text: var(--green-700);
  --color-warning: var(--amber-500);    --color-warning-bg: var(--amber-50);    --color-warning-text: var(--amber-700);
  --color-error: var(--red-600);        --color-error-bg: var(--red-50);        --color-error-text: var(--red-700);
  --color-info: var(--blue-600);        --color-info-bg: var(--blue-50);        --color-info-text: var(--blue-700);
}