omnidesign 1.0.0

package/recipes/components/forms.md

@@ -0,0 +1,238 @@
+# Form Patterns
+
+Comprehensive form component patterns including input states (default, focus, error, disabled, loading), error message styling, helper text, and label positioning strategies.
+
+## When to Use
+
+**Use form patterns for:**
+- User input collection (login, signup, contact)
+- Data entry and validation
+- Search interfaces
+- Filter and sort controls
+- Multi-step wizards
+
+**Don't use for:**
+- Simple yes/no questions (use toggle or checkbox)
+- Single-field searches (use search input pattern)
+- Read-only data display (use text, not form fields)
+
+## Component Anatomy
+
+```
+┌─────────────────────────────────────────┐
+│  [Label]                                │
+│  [Input Field]                          │
+│  [Helper Text / Error Message]          │
+│                                         │
+│  Input States:                          │
+│  - Default: Neutral appearance          │
+│  - Focus: Border highlight, shadow      │
+│  - Error: Red border, error icon        │
+│  - Disabled: Grayed out, no interaction │
+│  - Loading: Spinner, disabled state     │
+└─────────────────────────────────────────┘
+```
+
+## State Matrix
+
+| State | Visual Treatment | Tokens Used |
+|-------|------------------|-------------|
+| **Default** | Border `color.border.default`, background `color.surface.sunken`, text `color.text.default` | `color.border.default`, `color.surface.sunken`, `color.text.default` |
+| **Focus** | Border `color.interactive.primary`, shadow with blue tint, outline none | `color.interactive.primary`, `color.focus.ring`, `motion.hover` |
+| **Error** | Border `color.status.error`, background tinted red, error icon visible | `color.status.error`, `color.surface.sunken`, `color.text.default` |
+| **Disabled** | Border `color.border.subtle`, background `color.surface.sunken`, text `color.text.muted`, cursor not-allowed | `color.border.subtle`, `color.text.muted` |
+| **Loading** | Spinner icon visible, input disabled, opacity 80% | `color.interactive.primary`, `motion.hover` |
+| **Success** | Border `color.status.success`, checkmark icon visible | `color.status.success` |
+
+## Token Usage
+
+### Colors
+- **Default Border**: `color.border.default` (neutral 200)
+- **Focus Border**: `color.interactive.primary` (blue 500)
+- **Error Border**: `color.status.error` (red 500)
+- **Success Border**: `color.status.success` (green 500)
+- **Input Background**: `color.surface.sunken` (neutral 50)
+- **Label Text**: `color.text.default` (neutral 900)
+- **Helper Text**: `color.text.muted` (neutral 500)
+- **Error Text**: `color.status.error` (red 500)
+
+### Spacing
+- **Label Margin**: `space.stackSm` (2px) below label
+- **Input Padding**: `space.inputPadding` (3px) internal padding
+- **Form Field Gap**: `space.formGap` (4px) between label and input
+- **Error Message Margin**: `space.stackSm` (2px) above error text
+- **Helper Text Margin**: `space.stackSm` (2px) above helper text
+
+### Typography
+- **Label**: `typography.ui.label` (sm, medium)
+- **Input**: `typography.body.default` (base, normal)
+- **Helper Text**: `typography.ui.caption` (xs, normal)
+- **Error Text**: `typography.ui.caption` (xs, normal) with `color.status.error`
+
+### Shadows & Radii
+- **Input Radius**: `radius.button` for rounded corners
+- **Focus Shadow**: Subtle shadow with blue tint (0 0 0 3px rgba(59, 130, 246, 0.1))
+
+## Implementation Notes
+
+### CSS/HTML Approach
+
+**Structure:**
+```
+<div class="form-field">
+  <label for="email" class="form-field__label">Email Address</label>
+  <div class="form-field__input-wrapper">
+    <input 
+      type="email" 
+      id="email" 
+      class="form-field__input" 
+      placeholder="you@example.com"
+      aria-describedby="email-helper"
+      required
+    >
+    <span class="form-field__icon"></span>
+  </div>
+  <p id="email-helper" class="form-field__helper">We'll never share your email</p>
+</div>
+
+<!-- Error state -->
+<div class="form-field form-field--error">
+  <label for="password" class="form-field__label">Password</label>
+  <div class="form-field__input-wrapper">
+    <input 
+      type="password" 
+      id="password" 
+      class="form-field__input" 
+      aria-describedby="password-error"
+      aria-invalid="true"
+    >
+    <span class="form-field__icon form-field__icon--error"></span>
+  </div>
+  <p id="password-error" class="form-field__error">Password must be at least 8 characters</p>
+</div>
+```
+
+**Key CSS patterns:**
+- Use `display: flex; flex-direction: column` for vertical label-input stacking
+- Apply `border: 1px solid color.border.default` to input
+- Use `padding: space.inputPadding` for internal spacing
+- Implement focus state with `border-color: color.interactive.primary` and `box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.1)`
+- Use `transition: border-color 200ms ease-out, box-shadow 200ms ease-out` for smooth focus
+- Apply `background: color.surface.sunken` for input background
+- Use `color: color.text.muted` for placeholder text
+- Implement error state with `border-color: color.status.error` and `color: color.status.error` for error text
+- Use `cursor: not-allowed; opacity: 0.6` for disabled state
+- Implement loading state with spinner icon and `pointer-events: none`
+
+**Validation patterns:**
+- Show error message only when field is invalid AND touched (not on initial load)
+- Use `aria-invalid="true"` to announce error state to screen readers
+- Use `aria-describedby` to link input to helper or error text
+- Validate on blur (not on every keystroke) to avoid overwhelming user
+
+**Label positioning:**
+- Default: Label above input (vertical stack)
+- Alternative: Label inside input (floating label) — requires more complex CSS
+- Alternative: Label to left of input (horizontal) — use for compact forms
+
+### React Approach
+
+**Component structure:**
+- Create `<FormField>` wrapper managing label, input, helper text, and error state
+- Create `<Input>` component accepting `type`, `placeholder`, `error`, `disabled`, `loading` props
+- Use `useState` for input value and touched state
+- Implement `onBlur` to set touched state and trigger validation
+- Use `useCallback` for validation logic
+
+**State management:**
+- Track input value with `useState`
+- Track touched state with `useState` (show errors only when touched)
+- Track validation errors with `useState` or validation library (Zod, Yup)
+- Use `useEffect` to validate on value change (debounced)
+
+**Validation:**
+- Validate on blur (not on every keystroke)
+- Show error message only when field is touched AND invalid
+- Use validation library (Zod, React Hook Form) for consistency
+- Provide real-time feedback for async validation (email availability, username)
+
+**Accessibility:**
+- Use `<label>` with `htmlFor` attribute
+- Use `aria-invalid="true"` when field has error
+- Use `aria-describedby` to link input to helper or error text
+- Use `aria-required="true"` for required fields
+- Implement focus management for error messages
+
+## Acceptance Criteria
+
+- [ ] Label uses `typography.ui.label` token
+- [ ] Input uses `typography.body.default` token
+- [ ] Default border uses `color.border.default` token
+- [ ] Focus border uses `color.interactive.primary` token
+- [ ] Error border uses `color.status.error` token
+- [ ] Input background uses `color.surface.sunken` token
+- [ ] Input padding uses `space.inputPadding` token
+- [ ] Form field gap uses `space.formGap` token
+- [ ] Helper text uses `typography.ui.caption` token
+- [ ] Error text uses `color.status.error` token
+- [ ] Focus ring visible with 3px blue shadow
+- [ ] Error message shows only when field is touched AND invalid
+- [ ] Disabled state shows cursor not-allowed and reduced opacity
+- [ ] Loading state shows spinner and disables input
+- [ ] Respects `prefers-reduced-motion` (instant state changes)
+- [ ] All text passes color contrast ratio (4.5:1 for body, 3:1 for large text)
+
+## Accessibility
+
+### ARIA & Semantics
+- Use `<label>` with `htmlFor` attribute (not placeholder-only labels)
+- Use `<input>` with appropriate `type` attribute (email, password, number, etc.)
+- Use `aria-invalid="true"` when field has validation error
+- Use `aria-describedby` to link input to helper or error text
+- Use `aria-required="true"` for required fields
+- Use `aria-label` for icon-only inputs (if no visible label)
+
+### Keyboard Navigation
+- Tab order: Label (not focusable) → Input → Helper/Error text (not focusable)
+- Focus ring must be visible with 3px shadow, `color.focus.ring`
+- Ensure focus ring has sufficient contrast against input background
+- Support arrow keys for number inputs
+- Support Escape to clear input (optional)
+
+### Screen Readers
+- Label text must be descriptive and associated with input
+- Error message must be announced when field becomes invalid
+- Helper text must be announced to provide context
+- Required field must be announced with `aria-required="true"`
+- Input type must be announced (email, password, etc.)
+
+### Color & Contrast
+- Text must meet WCAG AA (4.5:1 for body, 3:1 for large text)
+- Error color must have sufficient contrast against background
+- Don't rely on color alone to indicate error (use icon + text)
+- Ensure sufficient contrast between input text and background
+
+### Motion
+- Respect `prefers-reduced-motion: reduce` by disabling animations
+- Focus transition should be instant if reduced motion is preferred
+- Loading spinner should not animate if reduced motion is preferred
+
+### Touch Targets
+- Input minimum height 44px for touch targets
+- Label minimum 44px tall for touch targets
+- Ensure sufficient spacing between form fields for touch accuracy
+
+### Validation Patterns
+- Show errors only when field is touched (not on initial load)
+- Provide clear, actionable error messages
+- Suggest corrections when possible (e.g., "Did you mean...?")
+- Allow user to submit form even with errors (show summary at top)
+- Validate on blur, not on every keystroke
+- Support async validation (email availability, username) with loading state
+
+### Mobile Considerations
+- Use appropriate input types (email, tel, number) for mobile keyboards
+- Ensure input height minimum 44px for touch
+- Avoid auto-capitalization for email/username fields
+- Disable auto-zoom on focus (use font-size >= 16px)
+- Test on actual mobile devices for keyboard behavior

package/recipes/components/hero-section.md

@@ -0,0 +1,161 @@
+# Hero Section
+
+A cinematic landing page hero with compelling typography hierarchy, dual call-to-action buttons, and atmospheric background treatment. Designed to capture attention and drive conversion.
+
+## When to Use
+
+**Use hero sections for:**
+- Landing page above-the-fold content
+- Product launch announcements
+- Campaign entry points
+- High-impact page introductions
+
+**Don't use for:**
+- Secondary pages or internal tools
+- Content-heavy pages requiring immediate scrolling
+- Mobile-first experiences with limited viewport height
+- Accessibility-critical interfaces (use simpler patterns)
+
+## Component Anatomy
+
+```
+┌─────────────────────────────────────────┐
+│  [Gradient/Atmospheric Background]      │
+│                                         │
+│         [Hero Heading]                  │
+│      (typography.heading.hero)          │
+│                                         │
+│      [Subtitle/Subheading]              │
+│    (typography.body.large, muted)       │
+│                                         │
+│      [Body Copy - Optional]             │
+│    (typography.body.default, muted)     │
+│                                         │
+│  [Primary CTA] [Secondary CTA]          │
+│                                         │
+│  [Background Image/Gradient Overlay]    │
+└─────────────────────────────────────────┘
+```
+
+## State Matrix
+
+| State | Visual Treatment | Tokens Used |
+|-------|------------------|-------------|
+| **Default** | Hero text centered, CTAs at standard opacity, background at full saturation | `color.text.default`, `color.interactive.primary`, `color.surface.default` |
+| **Hover (CTA)** | Primary CTA background darkens, secondary CTA gains border, slight scale (1.02x) | `color.interactive.primary.hover`, `motion.hover` |
+| **Focus (CTA)** | 2px focus ring around button, keyboard navigation visible | `color.focus.ring`, `space.inlineSm` |
+| **Reduced Motion** | No scale/translate animations, instant opacity changes | `motion.hover` (duration: 0ms) |
+| **Dark Mode** | Text inverted to `color.text.inverted`, background darkened, contrast maintained | `color.text.inverted`, `color.surface.overlay` |
+
+## Token Usage
+
+### Typography
+- **Hero Heading**: `typography.heading.hero` — 6xl, bold, tight line-height for maximum impact
+- **Subtitle**: `typography.body.large` with `color.text.muted` — supports hero without overwhelming
+- **Body Copy**: `typography.body.default` with `color.text.muted` — optional supporting text, max 120 characters
+
+### Colors
+- **Text**: `color.text.default` for primary heading, `color.text.muted` for supporting copy
+- **Buttons**: Primary uses `color.interactive.primary`, secondary uses `color.interactive.secondary` with border
+- **Background**: Gradient from `color.surface.default` to semi-transparent overlay
+
+### Spacing
+- **Section Padding**: `space.sectionY` (16px) top/bottom, `space.sectionX` (6px) horizontal
+- **Text Stack**: `space.stackLg` (6px) between heading and subtitle, `space.stackMd` (4px) between subtitle and body
+- **Button Gap**: `space.inlineMd` (4px) between primary and secondary CTA
+
+### Shadows & Radii
+- **Button Radius**: `radius.button` for CTA buttons
+- **Card Shadow** (optional): `shadow.card` if hero contains a card element
+
+## Implementation Notes
+
+### CSS/HTML Approach
+
+**Structure:**
+```
+<section class="hero">
+  <div class="hero__background"></div>
+  <div class="hero__content">
+    <h1 class="hero__heading">Main message</h1>
+    <p class="hero__subtitle">Supporting message</p>
+    <p class="hero__body">Optional body copy</p>
+    <div class="hero__ctas">
+      <button class="button button--primary">Primary CTA</button>
+      <button class="button button--secondary">Secondary CTA</button>
+    </div>
+  </div>
+</section>
+```
+
+**Key CSS patterns:**
+- Use `position: relative` on hero container, `position: absolute` on background for layering
+- Apply `background: linear-gradient(135deg, color1, color2)` or `background-image: url()` with overlay
+- Center content with `display: flex; flex-direction: column; align-items: center; justify-content: center`
+- Use `max-width: space.containerMax` (24rem/384px) for text content to maintain readability
+- Apply `prefers-reduced-motion: reduce` media query to disable animations
+
+**Responsive considerations:**
+- Desktop: Full viewport height (min-height: 100vh), centered content
+- Tablet (768px): Reduce heading size to `typography.heading.page`, maintain full height
+- Mobile (375px): Reduce to 60-70vh height, stack CTAs vertically, use `typography.heading.section` for heading
+
+### React Approach
+
+**Component structure:**
+- Create a `<Hero>` wrapper component accepting `heading`, `subtitle`, `body`, `primaryCta`, `secondaryCta` props
+- Use `<img>` or CSS background for background image with proper `alt` text or `aria-hidden`
+- Implement CTA buttons as separate `<Button>` components with variant props (primary/secondary)
+- Use CSS modules or Tailwind for styling to maintain token consistency
+- Wrap in `<section>` with proper ARIA landmarks
+- Consider using `IntersectionObserver` for scroll-triggered animations (fade-in on viewport entry)
+
+**State management:**
+- Track hover state on CTAs for visual feedback
+- Use CSS `:hover` and `:focus-visible` for button states (prefer CSS over React state)
+- Implement `prefers-reduced-motion` detection for animation preferences
+
+## Acceptance Criteria
+
+- [ ] Hero heading uses `typography.heading.hero` token
+- [ ] Subtitle uses `typography.body.large` with `color.text.muted`
+- [ ] Primary CTA uses `color.interactive.primary` with hover state
+- [ ] Secondary CTA has visible border and hover treatment
+- [ ] Focus ring visible on keyboard navigation (2px, `color.focus.ring`)
+- [ ] Responsive: Full height on desktop, 60-70vh on mobile
+- [ ] Text content max-width 384px (space.containerMax) for readability
+- [ ] Background image has proper contrast with text (WCAG AA minimum)
+- [ ] Respects `prefers-reduced-motion` media query
+- [ ] All text passes color contrast ratio (4.5:1 for body, 3:1 for large text)
+
+## Accessibility
+
+### ARIA & Semantics
+- Use `<section>` with `role="region"` and `aria-label="Hero section"` for landmark navigation
+- Heading must be `<h1>` (only one per page)
+- CTAs must be `<button>` or `<a>` with clear, descriptive text (not "Click here")
+
+### Keyboard Navigation
+- Tab order: Heading (not focusable) → Subtitle (not focusable) → Primary CTA → Secondary CTA
+- Focus ring must be visible with minimum 2px width, `color.focus.ring`
+- Ensure focus ring has sufficient contrast against background
+
+### Screen Readers
+- Provide `alt` text for background images or use `aria-hidden="true"` if decorative
+- CTA text must be descriptive: "Get Started" not "Click"
+- Use `aria-label` for icon-only buttons if present
+
+### Color & Contrast
+- Text must meet WCAG AA (4.5:1 for body, 3:1 for large text)
+- Don't rely on color alone to convey information
+- Ensure sufficient contrast between text and background gradient
+- Test with tools like WebAIM Contrast Checker
+
+### Motion
+- Respect `prefers-reduced-motion: reduce` by disabling animations
+- Animations should not auto-play; trigger on user interaction
+- Avoid flashing or rapid animations (>3 per second)
+
+### Touch Targets
+- CTAs must be minimum 48px × 48px (touch-friendly)
+- Maintain `space.inlineMd` (4px) gap between buttons for touch accuracy

package/recipes/components/navbar.md

@@ -0,0 +1,214 @@
+# Navigation Bar
+
+A responsive header component with transparent-to-solid background transition on scroll, active link styling, mobile hamburger menu, and flexible logo/nav/CTA layout.
+
+## When to Use
+
+**Use navbar for:**
+- Primary site navigation on all pages
+- Persistent header across page sections
+- Brand/logo placement and recognition
+- Call-to-action button placement
+- Mobile menu access
+
+**Don't use for:**
+- Breadcrumb navigation (use separate component)
+- Pagination (use separate component)
+- Sidebar navigation (use separate component)
+- Floating action buttons (use separate pattern)
+
+## Component Anatomy
+
+```
+┌─────────────────────────────────────────────────────┐
+│  [Logo]  [Nav Items]  [Secondary CTA]  [Mobile Menu]│
+│                                                     │
+│  Desktop Layout:                                    │
+│  Logo (left) | Nav Items (center) | CTA (right)   │
+│                                                     │
+│  Mobile Layout:                                    │
+│  Logo (left) | Hamburger Menu (right)             │
+│  [Expanded Menu Overlay]                           │
+│    - Nav Items (stacked)                           │
+│    - Secondary CTA                                 │
+└─────────────────────────────────────────────────────┘
+```
+
+## State Matrix
+
+| State | Visual Treatment | Tokens Used |
+|-------|------------------|-------------|
+| **Default (Transparent)** | Background transparent, text `color.text.default`, no shadow | `color.surface.default` (transparent), `color.text.default` |
+| **Scrolled (Solid)** | Background `color.surface.raised`, shadow applied, text remains `color.text.default` | `color.surface.raised`, `shadow.card`, `motion.hover` |
+| **Active Link** | Text color `color.interactive.primary`, underline or bottom border | `color.interactive.primary`, `color.border.strong` |
+| **Hover Link** | Text color `color.interactive.primary.hover`, slight opacity increase | `color.interactive.primary.hover`, `motion.hover` |
+| **Focus Link** | Focus ring around link (2px), keyboard navigation visible | `color.focus.ring`, `space.inlineSm` |
+| **Mobile Menu Open** | Overlay background `color.surface.overlay` with 80% opacity, menu slides in from right | `color.surface.overlay`, `motion.enter` |
+
+## Token Usage
+
+### Colors
+- **Background (Transparent)**: `color.surface.default` with 0% opacity initially
+- **Background (Solid)**: `color.surface.raised` after scroll threshold
+- **Text**: `color.text.default` for nav items, `color.text.muted` for secondary text
+- **Active/Hover**: `color.interactive.primary` and `color.interactive.primary.hover`
+- **Mobile Overlay**: `color.surface.overlay` with 80% opacity
+
+### Spacing
+- **Navbar Height**: 64px (desktop), 56px (mobile) — standard touch target
+- **Horizontal Padding**: `space.sectionX` (6px) on left/right
+- **Nav Item Gap**: `space.inlineMd` (4px) between nav items
+- **Logo Margin**: `space.inlineLg` (6px) right margin from nav items
+
+### Typography
+- **Logo**: `typography.heading.card` (xl, semibold) or custom brand font
+- **Nav Items**: `typography.ui.button` (base, medium) for consistency
+- **Mobile Menu Items**: `typography.body.default` for readability
+
+### Shadows & Radii
+- **Navbar Shadow**: `shadow.card` applied when scrolled (solid state)
+- **Mobile Menu**: No radius on overlay, but menu content can use `radius.card`
+
+## Implementation Notes
+
+### CSS/HTML Approach
+
+**Structure:**
+```
+<nav class="navbar" role="navigation" aria-label="Main navigation">
+  <div class="navbar__container">
+    <a href="/" class="navbar__logo">Logo</a>
+    
+    <ul class="navbar__items">
+      <li><a href="/about" class="navbar__link">About</a></li>
+      <li><a href="/products" class="navbar__link">Products</a></li>
+      <li><a href="/blog" class="navbar__link">Blog</a></li>
+    </ul>
+    
+    <button class="navbar__cta">Get Started</button>
+    
+    <button class="navbar__toggle" aria-label="Toggle menu" aria-expanded="false">
+      <span class="navbar__hamburger"></span>
+    </button>
+  </div>
+  
+  <div class="navbar__mobile-menu" hidden>
+    <ul class="navbar__mobile-items">
+      <li><a href="/about">About</a></li>
+      <li><a href="/products">Products</a></li>
+      <li><a href="/blog">Blog</a></li>
+      <li><button class="navbar__cta">Get Started</button></li>
+    </ul>
+  </div>
+</nav>
+```
+
+**Key CSS patterns:**
+- Use `position: fixed` or `sticky` for navbar positioning
+- Apply `background: transparent` initially, transition to `color.surface.raised` on scroll
+- Use `transition: background-color 200ms ease-out` for smooth background change
+- Implement scroll detection with `window.addEventListener('scroll', ...)` or `IntersectionObserver`
+- Use `display: flex` for horizontal layout, `justify-content: space-between` for spacing
+- Hide nav items on mobile with `display: none`, show hamburger menu
+- Implement mobile menu with `position: fixed`, `right: 0`, `top: navbar-height`, `width: 100vw`
+- Use `transform: translateX(100%)` for off-screen menu, `translateX(0)` when open
+
+**Scroll detection threshold:**
+- Trigger solid background after 50-100px scroll (adjust based on design)
+- Use `IntersectionObserver` on a sentinel element below navbar for better performance
+
+**Active link styling:**
+- Compare current URL with nav item `href` to determine active state
+- Apply `color.interactive.primary` and bottom border (2px, `color.border.strong`)
+- Update on page load and route changes
+
+### React Approach
+
+**Component structure:**
+- Create `<Navbar>` wrapper managing scroll state and mobile menu visibility
+- Create `<NavItem>` component for individual nav links with active state detection
+- Use `useLocation()` or similar router hook to determine active link
+- Implement `useEffect` with scroll listener for background transition
+- Use `useState` for mobile menu open/close state
+
+**State management:**
+- Track scroll position with `useEffect` and `window.addEventListener('scroll')`
+- Use `useCallback` to debounce scroll handler (throttle to 16ms for 60fps)
+- Track mobile menu open state with `useState`
+- Use `useLocation()` to detect active nav item
+
+**Responsive behavior:**
+- Use `useMediaQuery` hook to detect mobile breakpoint (768px)
+- Show/hide nav items and hamburger menu based on breakpoint
+- Adjust navbar height and padding for mobile
+
+**Accessibility:**
+- Use `<nav>` with `role="navigation"` and `aria-label="Main navigation"`
+- Use `<a>` for nav items with proper `href` attributes
+- Implement `aria-current="page"` for active link
+- Use `aria-expanded` on hamburger button to indicate menu state
+- Manage focus when mobile menu opens (trap focus inside menu)
+
+## Acceptance Criteria
+
+- [ ] Navbar uses `position: fixed` or `sticky` for persistent positioning
+- [ ] Background transitions from transparent to `color.surface.raised` on scroll
+- [ ] Scroll threshold is 50-100px (configurable)
+- [ ] Active link styled with `color.interactive.primary` and bottom border
+- [ ] Hover state uses `color.interactive.primary.hover` with `motion.hover`
+- [ ] Focus ring visible on keyboard navigation (2px, `color.focus.ring`)
+- [ ] Mobile menu hidden by default, visible on hamburger click
+- [ ] Mobile menu overlay uses `color.surface.overlay` with 80% opacity
+- [ ] Navbar height: 64px desktop, 56px mobile
+- [ ] Horizontal padding uses `space.sectionX` token
+- [ ] Nav item gap uses `space.inlineMd` token
+- [ ] Logo uses `typography.heading.card` or custom brand font
+- [ ] Nav items use `typography.ui.button` token
+- [ ] Respects `prefers-reduced-motion` (instant background change)
+- [ ] All text passes color contrast ratio (4.5:1 for body, 3:1 for large text)
+
+## Accessibility
+
+### ARIA & Semantics
+- Use `<nav>` with `role="navigation"` and `aria-label="Main navigation"`
+- Use `<a>` for nav items with descriptive link text
+- Use `<button>` for hamburger menu toggle with `aria-label="Toggle menu"`
+- Implement `aria-expanded="true/false"` on hamburger button
+- Use `aria-current="page"` for active nav item
+
+### Keyboard Navigation
+- Tab order: Logo (not focusable) → Nav items → CTA → Hamburger menu
+- Focus ring must be visible with 2px width, `color.focus.ring`
+- Ensure focus ring has sufficient contrast against navbar background
+- Hamburger menu must be keyboard accessible
+- Mobile menu must be closable with Escape key
+
+### Screen Readers
+- Nav item text must be descriptive (not "Click here")
+- Logo link must have descriptive text or `aria-label`
+- Hamburger button must have `aria-label="Toggle menu"`
+- Active nav item must be announced with `aria-current="page"`
+- Mobile menu items must be announced when menu opens
+
+### Color & Contrast
+- Text must meet WCAG AA (4.5:1 for body, 3:1 for large text)
+- Active link color must have sufficient contrast
+- Ensure sufficient contrast between text and background (both transparent and solid states)
+- Test with WebAIM Contrast Checker
+
+### Motion
+- Respect `prefers-reduced-motion: reduce` by disabling animations
+- Background transition should be instant if reduced motion is preferred
+- Mobile menu should slide without animation if reduced motion is preferred
+
+### Touch Targets
+- Navbar height minimum 56px for touch targets
+- Nav items minimum 48px × 48px for touch targets
+- Hamburger menu button minimum 48px × 48px
+- Maintain `space.inlineMd` (4px) gap between nav items for touch accuracy
+
+### Mobile Considerations
+- Ensure navbar doesn't obscure important content
+- Mobile menu should not auto-close on link click (let user decide)
+- Implement focus trap in mobile menu (Tab cycles within menu)
+- Close menu when user navigates to new page