@minhduydev/mdpi 0.4.0 → 0.5.0

package/dist/template/.pi/skills/design-taste-frontend/SKILL.md

@@ -3,6 +3,8 @@ name: design-taste-frontend
 description: Use when building any web UI as the BASE aesthetic layer to override default LLM design biases. Enforces strict typography, color, spacing, and component architecture rules. Load BEFORE frontend-design when premium visual quality is required.
 ---
 
+**Aesthetic Context:** This is a premium aesthetic layer. Read `.pi/DESIGN.md` first to internalize the project's visual identity — every typographic, color, and spacing rule here is shaped by that mood. Design taste means the design feels intentional, not AI-generated.
+
 ## When to Use
 
 - When building any web UI that needs to override default LLM design biases
@@ -15,7 +17,7 @@ description: Use when building any web UI as the BASE aesthetic layer to overrid
 - For non-UI tasks (backend, CLI, data processing)
 
 
-# High-Agency Frontend Skill
+# Design Taste Frontend
 
 ## 1. ACTIVE BASELINE CONFIGURATION
 * DESIGN_VARIANCE: 8 (1=Perfect Symmetry, 10=Artsy Chaos)
@@ -43,7 +45,6 @@ Unless the user explicitly specifies a different stack, adhere to these structur
   * **Grid over Flex-Math:** NEVER use complex flexbox percentage math (`w-[calc(33%-1rem)]`). ALWAYS use CSS Grid (`grid grid-cols-1 md:grid-cols-3 gap-6`) for reliable structures.
 * **Icons:** You MUST use exactly `@phosphor-icons/react` or `@radix-ui/react-icons` as the import paths (check installed version). Standardize `strokeWidth` globally (e.g., exclusively use `1.5` or `2.0`).
 
-
 ## 3. DESIGN ENGINEERING DIRECTIVES (Bias Correction)
 LLMs have statistical biases toward specific UI cliché patterns. Proactively construct premium interfaces using these engineered rules:
 
@@ -55,7 +56,7 @@ LLMs have statistical biases toward specific UI cliché patterns. Proactively co
 
 **Rule 2: Color Calibration**
 * **Constraint:** Max 1 Accent Color. Saturation < 80%.
-* **THE LILA BAN:** The "AI Purple/Blue" aesthetic is strictly BANNED. No purple button glows, no neon gradients. Use absolute neutral bases (Zinc/Slate) with high-contrast, singular accents (e.g. Emerald, Electric Blue, or Deep Rose).
+* **THE LILA BAN:** The "AI Purple/Blue" aesthetic is strictly BANNED. No purple button glows, no neon gradients. Use absolute neutral bases (Zinc/Slate) with high-contrast, singular accents (e.g., Emerald, Electric Blue, or Deep Rose).
 * **COLOR CONSISTENCY:** Stick to one palette for the entire output. Do not fluctuate between warm and cool grays within the same project.
 
 **Rule 3: Layout Diversification**
@@ -106,36 +107,50 @@ To actively combat generic AI designs, systematically implement these high-end c
 * **4-7 (Daily App Mode):** Normal spacing for standard web apps.
 * **8-10 (Cockpit Mode):** Tiny paddings. No card boxes; just 1px lines to separate data. Everything is packed. **Mandatory:** Use Monospace (`font-mono`) for all numbers.
 
-## 7. AI TELLS (Forbidden Patterns)
-To guarantee a premium, non-generic output, you MUST strictly avoid these common AI design signatures unless explicitly requested:
+## 7. Don't
 
 ### Visual & CSS
-* **NO Neon/Outer Glows:** Do not use default `box-shadow` glows or auto-glows. Use inner borders or subtle tinted shadows.
-* **NO Pure Black:** Never use `#000000`. Use Off-Black, Zinc-950, or Charcoal.
-* **NO Oversaturated Accents:** Desaturate accents to blend elegantly with neutrals.
-* **NO Excessive Gradient Text:** Do not use text-fill gradients for large headers.
-* **NO Custom Mouse Cursors:** They are outdated and ruin performance/accessibility.
+
+| Pattern | Replacement | Because |
+|---------|-------------|---------|
+| Neon/outer box-shadow glows | Inner borders or subtle tinted shadows | Glows are an instant AI-design signature |
+| Pure black `#000000` | Off-black, Zinc-950, or Charcoal | Pure black destroys visual depth |
+| Oversaturated accent colors | Desaturated accents blending with neutrals | High-saturation colors look amateurish |
+| Gradient text on large headers | Single solid heading color | Gradient text is an AI design cliché |
+| Custom mouse cursors | Default system cursor | Custom cursors hurt performance and accessibility |
 
 ### Typography
-* **NO Inter Font:** Banned. Use `Geist`, `Outfit`, `Cabinet Grotesk`, or `Satoshi`.
-* **NO Oversized H1s:** The first heading should not scream. Control hierarchy with weight and color, not just massive scale.
-* **Serif Constraints:** Use Serif fonts ONLY for creative/editorial designs. **NEVER** use Serif on clean Dashboards.
+
+| Pattern | Replacement | Because |
+|---------|-------------|---------|
+| Inter as display typeface | Geist, Outfit, Cabinet Grotesk, or Satoshi | Inter signals default AI-generated output |
+| Oversized H1 (>40px without reason) | Control hierarchy with weight and color, not just massive scale | Giant headings scream without communicating |
+| Serif fonts on dashboards or data UIs | Sans-serif for data; serif only for editorial/creative contexts | Serifs on dashboards feel out of place |
 
 ### Layout & Spacing
-* **Align & Space Perfectly:** Ensure padding and margins are mathematically perfect. Avoid floating elements with awkward gaps.
-* **NO 3-Column Card Layouts:** The generic "3 equal cards horizontally" feature row is BANNED. Use a 2-column Zig-Zag, asymmetric grid, or horizontal scrolling approach instead.
 
-### Content & Data (The "Jane Doe" Effect)
-* **NO Generic Names:** "John Doe", "Sarah Chan", or "Jack Su" are banned. Use highly creative, realistic-sounding names.
-* **NO Generic Avatars:** DO NOT use standard SVG "egg" or Lucide user icons for avatars. Use creative, believable photo placeholders or specific styling.
-* **NO Fake Numbers:** Avoid predictable outputs like `99.99%`, `50%`, or basic phone numbers (`1234567`). Use organic, messy data (`47.2%`, `+1 (312) 847-1928`).
-* **NO Startup Slop Names:** "Acme", "Nexus", "SmartFlow". Invent premium, contextual brand names.
-* **NO Filler Words:** Avoid AI copywriting clichés like "Elevate", "Seamless", "Unleash", or "Next-Gen". Use concrete verbs.
+| Pattern | Replacement | Because |
+|---------|-------------|---------|
+| 3-column identical card layouts | 2-column zig-zag, asymmetric grid, or horizontal scroll | Three equal cards is the #1 AI UI tell |
+| Floating elements with awkward gaps | Mathematically perfect padding and margin alignment | Misaligned spacing reads as sloppy |
+
+### Content & Data
 
-### External Resources & Components
-* **NO Broken Unsplash Links:** Do not use Unsplash. Use absolute, reliable placeholders like `https://picsum.photos/seed/{random_string}/800/600` or SVG UI Avatars.
-* **shadcn/ui Customization:** You may use `shadcn/ui`, but NEVER in its generic default state. You MUST customize the radii, colors, and shadows to match the high-end project aesthetic.
-* **Production-Ready Cleanliness:** Code must be extremely clean, visually striking, memorable, and meticulously refined in every detail.
+| Pattern | Replacement | Because |
+|---------|-------------|---------|
+| Generic placeholder names (John Doe, Sarah Chan) | Creative, realistic-sounding names (Dr. Sarah Chen, Marcus Okonkwo) | Generic names feel fake and unprofessional |
+| Emoji avatars or Lucide user icons | Creative photo placeholders or styled SVGs | Emoji avatars degrade perceived quality |
+| Fake or predictable numbers (`99.99%`, `50%`, `$99/mo`) | Organic, messy data (`47.2%`, `$12,450`, `+18.3%`) | Round numbers look fabricated |
+| Startup slop names (Acme, Nexus, SmartFlow) | Premium, contextual brand names | Startup-slop names are a dead AI giveaway |
+| Filler words (Elevate, Seamless, Unleash, Next-Gen) | Concrete, specific verbs and descriptions | AI copywriting clichés destroy credibility |
+| Unsplash URLs in image sources | `picsum.photos/seed/{seed}/800/600` or SVG placeholders | Unsplash links break and leave broken images |
+| Default shadcn/ui appearance | Customized radii, colors, and shadows | Default shadcn reads as AI-generated |
+
+### Code Quality
+
+| Pattern | Replacement | Because |
+|---------|-------------|---------|
+| Sloppy output — misaligned elements, poor spacing, generic feel | Meticulously refined, visually striking, memorable output | Production-ready cleanliness is non-negotiable for premium UI |
 
 ## 8. THE CREATIVE ARSENAL (High-End Inspiration)
 Do not default to generic UI. Pull from this library of advanced concepts to ensure the output is visually striking and memorable. When appropriate, leverage **GSAP (ScrollTrigger/Parallax)** for complex scrolltelling or **ThreeJS/WebGL** for 3D/Canvas animations, rather than basic CSS motion. **CRITICAL:** Never mix GSAP/ThreeJS with Framer Motion in the same component tree. Default to Framer Motion for UI/Bento interactions. Use GSAP/ThreeJS EXCLUSIVELY for isolated full-page scrolltelling or canvas backgrounds, wrapped in strict useEffect cleanup blocks.
@@ -143,7 +158,7 @@ Do not default to generic UI. Pull from this library of advanced concepts to ens
 ### The Standard Hero Paradigm
 * Stop doing centered text over a dark image. Try asymmetric Hero sections: Text cleanly aligned to the left or right. The background should feature a high-quality, relevant image with a subtle stylistic fade (darkening or lightening gracefully into the background color depending on if it is Light or Dark mode).
 
-### Navigation & Menüs
+### Navigation & Menus
 * **Mac OS Dock Magnification:** Nav-bar at the edge; icons scale fluidly on hover.
 * **Magnetic Button:** Buttons that physically pull toward the cursor.
 * **Gooey Menu:** Sub-items detach from the main button like a viscous liquid.
@@ -237,19 +252,15 @@ Evaluate your code against this matrix before outputting. This is the **last** f
 - [ ] Are cards omitted in favor of spacing where possible?
 - [ ] Did you strictly isolate CPU-heavy perpetual animations in their own Client Components?
 
-## Common Rationalizations
-
-| Rationalization | Reality |
-|---|---|
-| "Default LLM styles are acceptable" | Default LLM styles are generic. Aesthetic intent signals craftsmanship. |
-| "Typography doesn't matter for functionality" | Typography is 95% of web design. Bad type ruins even good layouts. |
-| "I'll refine the design later" | Design debt compounds like technical debt. Fix it in the first pass. |
-| "Users won't notice the details" | Users may not articulate it, but they feel quality. Details accumulate into perception. |
-
-## Red Flags
-
-- Default LLM spacing and typography used without adjustment
-- No explicit font pairing decisions documented
-- Color palette not extracted from project context
-- Components lack hover/focus/active state differentiation
-- Visual hierarchy is flat — everything looks equally important
+## Verification
+
+- [ ] Aesthetic baseline config (DESIGN_VARIANCE, MOTION_INTENSITY, VISUAL_DENSITY) respected throughout output
+- [ ] No banned fonts (Inter, Roboto, Arial, system-ui) used as display font
+- [ ] No AI purple/blue gradients, no neon glows, no pure black (`#000000`)
+- [ ] No centered Hero/H1 when DESIGN_VARIANCE > 4
+- [ ] No 3-column identical card layouts
+- [ ] All interactive states (loading, empty, error) implemented
+- [ ] Mobile layout collapse verified at 320px, 768px
+- [ ] `min-h-[100dvh]` used instead of `h-screen` for full-height sections
+- [ ] No emojis in code, markup, or alt text
+- [ ] Perpetual animations isolated in their own Client Components

package/dist/template/.pi/skills/fixing-accessibility/SKILL.md

@@ -0,0 +1,509 @@
+---
+name: fixing-accessibility
+description: Actionable WCAG 2.1 AA accessibility fixes — not just audit, but concrete code fixes with before/after examples
+---
+
+# Fixing Accessibility
+
+## When to Use
+
+- After building UI components — run this as a quality gate before merging
+- When fixing accessibility issues found by axe-core, Lighthouse, or manual testing
+- When adding keyboard navigation, ARIA labels, focus management, or screen reader support
+- When retrofitting accessibility onto existing components
+- During code review of UI changes — check for common accessibility regressions
+
+## When NOT to Use
+
+- For accessibility audits without implementation (use `ui-quality-audit` instead)
+- When building non-interactive content (static markup with no dynamic behavior)
+- When the only user of the application is yourself and you don't need assistive tech
+
+---
+
+## Priority Categories
+
+### 1. Keyboard Navigation
+
+**Why it matters:** ~25% of web users rely on keyboard navigation. If they can't tab through your interface, it's unusable.
+
+**Common issues:**
+- Interactive elements aren't focusable
+- Custom components (select, dropdown, menu) trap or skip focus
+- Tab order doesn't match visual order
+- No visible focus indicator
+
+**Fixes:**
+
+```tsx
+// BEFORE — custom dropdown not keyboard-accessible
+<div className="relative">
+  <div onClick={() => setOpen(!open)}>Select option</div>
+  {open && items.map(item => (
+    <div key={item} onClick={() => select(item)}>{item}</div>
+  ))}
+</div>
+
+// AFTER — proper button + listbox pattern
+<div className="relative">
+  <button
+    type="button"
+    onClick={() => setOpen(!open)}
+    aria-expanded={open}
+    aria-haspopup="listbox"
+    className="..."
+  >
+    {selected || 'Select option'}
+  </button>
+  {open && (
+    <ul role="listbox" className="absolute ...">
+      {items.map(item => (
+        <li
+          key={item}
+          role="option"
+          tabIndex={-1}
+          onClick={() => select(item)}
+          onKeyDown={(e) => { if (e.key === 'Enter') select(item); }}
+          aria-selected={item === selected}
+          className="..."
+        >
+          {item}
+        </li>
+      ))}
+    </ul>
+  )}
+</div>
+```
+
+```tsx
+// BEFORE — missing focus indicator on interactive card
+<div onClick={() => navigate(id)} className="rounded-lg p-4 cursor-pointer">
+  <h3>{title}</h3>
+  <p>{desc}</p>
+</div>
+
+// AFTER — focusable with visible ring
+<button
+  type="button"
+  onClick={() => navigate(id)}
+  className="rounded-lg p-4 text-left w-full focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-2"
+>
+  <h3>{title}</h3>
+  <p className="text-muted-foreground">{desc}</p>
+</button>
+```
+
+**Quick check:** Tab through the entire page. Every interactive element should receive focus in a logical order. You should never get stuck in a focus trap.
+
+---
+
+### 2. Focus Management
+
+**Why it matters:** Users must know where they are at all times. Lost focus = lost user.
+
+**Common issues:**
+- Focus doesn't move to newly opened modal/dialog
+- Focus gets reset to top of page after dynamic content change
+- Focus outline is removed via `outline: none` without alternative
+
+**Fixes:**
+
+```tsx
+// BEFORE — modal opens, focus stays on trigger button
+function Modal({ open, onClose, children }) {
+  if (!open) return null;
+  return (
+    <div className="fixed inset-0 bg-black/50">
+      <div className="...">
+        {children}
+      </div>
+    </div>
+  );
+}
+
+// AFTER — auto-focus dialog and Escape to close (for full focus-trap, see `frontend-design` interaction patterns)
+function Modal({ open, onClose, children }) {
+  const dialogRef = useRef(null);
+
+  useEffect(() => {
+    if (open) {
+      // Focus the dialog container
+      dialogRef.current?.focus();
+    }
+  }, [open]);
+
+  // Handle Escape key
+  useEffect(() => {
+    if (!open) return;
+    const handler = (e) => { if (e.key === 'Escape') onClose(); };
+    document.addEventListener('keydown', handler);
+    return () => document.removeEventListener('keydown', handler);
+  }, [open, onClose]);
+
+  if (!open) return null;
+  return (
+    <div
+      role="dialog"
+      aria-modal="true"
+      ref={dialogRef}
+      tabIndex={-1}
+      className="fixed inset-0 bg-black/50 flex items-center justify-center"
+      onKeyDown={(e) => { if (e.key === 'Escape') onClose(); }}
+    >
+      <div className="bg-white rounded-lg p-6">
+        {children}
+      </div>
+    </div>
+  );
+}
+```
+
+```css
+/* BEFORE — removes focus outline entirely (DO NOT DO THIS) */
+*:focus {
+  outline: none;
+}
+
+/* AFTER — custom focus ring that's visible */
+*:focus-visible {
+  outline: 2px solid var(--color-primary);
+  outline-offset: 2px;
+}
+
+/* Remove outline only for mouse clicks, keep keyboard focus visible */
+*:focus:not(:focus-visible) {
+  outline: none;
+}
+```
+
+---
+
+### 3. ARIA Labels
+
+**Why it matters:** ARIA labels provide screen reader context that visual users take for granted.
+
+**Common issues:**
+- Icon-only buttons without labels
+- Dynamic content changes not announced
+- Incorrect or redundant ARIA (overriding semantic HTML)
+
+**Fixes:**
+
+```tsx
+// BEFORE — icon button with no label
+<button onClick={onDelete}>
+  <TrashIcon className="h-5 w-5" />
+</button>
+
+// AFTER — labeled for screen readers
+<button onClick={onDelete} aria-label="Delete item">
+  <TrashIcon className="h-5 w-5" aria-hidden="true" />
+</button>
+```
+
+```tsx
+// BEFORE — dynamic content without announcement
+<div>
+  {items.length === 0 && <p>No results found</p>}
+</div>
+
+// AFTER — announces content changes
+<div aria-live="polite" aria-atomic="true">
+  {items.length === 0 && <p>No results found</p>}
+</div>
+```
+
+**Rule of thumb:** If it has no visible text label, it needs `aria-label`. If it has a visible label, use `aria-labelledby` pointing to the label's `id`.
+
+---
+
+### 4. Color Contrast
+
+**Why it matters:** WCAG 2.1 AA requires 4.5:1 for normal text, 3:1 for large text (18px+ bold or 24px+ regular).
+
+**Common issues:**
+- Gray text on white backgrounds (e.g., `text-gray-400` on white)
+- Low-contrast placeholder text
+- Links that only differ by color
+- Disabled buttons with insufficient contrast
+
+**Fixes:**
+
+```tsx
+// BEFORE — insufficient contrast
+<p className="text-gray-400 text-sm">Supporting text</p>
+
+// AFTER — meets 4.5:1
+<p className="text-gray-600 text-sm">Supporting text</p>
+```
+
+```tsx
+// BEFORE — link only distinguishable by color
+<span className="text-gray-600">
+  Terms of <a href="/service" className="text-blue-500">Service</a>
+</span>
+
+// AFTER — link has underline (non-color cue)
+<span className="text-gray-600">
+  Terms of <a href="/service" className="text-blue-500 underline">Service</a>
+</span>
+```
+
+**Quick check:** Use the browser DevTools color picker — it shows contrast ratio. Check body text first, then small text, then placeholder text.
+
+---
+
+### 5. Heading Hierarchy
+
+**Why it matters:** Screen reader users navigate pages by heading structure. Bad hierarchy means they can't understand the page layout.
+
+**Common issues:**
+- Skipping levels (h1 → h3)
+- Multiple h1s on one page
+- Headings selected by visual size, not semantic level
+- No h1 on the page
+
+**Fixes:**
+
+```tsx
+// BEFORE — skipped level, no h1
+<div className="text-3xl font-bold">Product Page</div>
+<h3 className="text-xl">Reviews</h3>
+<h4 className="text-lg">User Review</h4>
+
+// AFTER — proper hierarchy
+<h1 className="text-3xl font-bold">Product Page</h1>
+<h2 className="text-xl">Reviews</h2>
+<h3 className="text-lg">User Review</h3>
+```
+
+**Quick check:** Run the WAVE browser extension or use your browser's accessibility panel to view heading structure. It should read like a table of contents: one h1, logical nesting.
+
+---
+
+### 6. Form Labels
+
+**Why it matters:** Every form input needs an associated label for screen readers and click target expansion.
+
+**Common issues:**
+- Placeholder as label (disappears on input)
+- Missing `for`/`id` association
+- Error messages not associated with inputs
+- Required fields not indicated programmatically
+
+**Fixes:**
+
+```tsx
+// BEFORE — placeholder-only label
+<input
+  type="email"
+  placeholder="Email address"
+  className="..."
+/>
+
+// AFTER — proper label association
+<label htmlFor="email" className="block text-sm font-medium">
+  Email address
+</label>
+<input
+  id="email"
+  type="email"
+  placeholder="you@example.com"
+  aria-required="true"
+  className="mt-1 ..."
+/>
+```
+
+```tsx
+// BEFORE — error message not associated
+<div>
+  <label htmlFor="name">Name</label>
+  <input id="name" />
+  <p className="text-red-500">Name is required</p>
+</div>
+
+// AFTER — error message linked via aria-describedby
+<div>
+  <label htmlFor="name">Name</label>
+  <input
+    id="name"
+    aria-invalid={!!error}
+    aria-describedby={error ? 'name-error' : undefined}
+  />
+  {error && (
+    <p id="name-error" className="text-red-500 text-sm" role="alert">
+      {error}
+    </p>
+  )}
+</div>
+```
+
+---
+
+### 7. Image Alt Text
+
+**Why it matters:** Without alt text, screen readers read the image filename or say "image" — zero information.
+
+**Common issues:**
+- Missing `alt` on informative images
+- Redundant `alt=""` on images that should be described
+- Alt text that duplicates adjacent text
+- Decorative images missing `alt=""`
+
+**Fixes:**
+
+```tsx
+// BEFORE — informative image without alt
+<img src="/team/maria.jpg" className="rounded-full" />
+
+// AFTER — describes the image content
+<img src="/team/maria.jpg" alt="Maria Chen, Head of Design" className="rounded-full" />
+```
+
+```tsx
+// BEFORE — decorative icon without alt="" (screen reader reads filename)
+<img src="/decorative-divider.svg" className="h-4 w-full" />
+
+// AFTER — explicitly decorative
+<img src="/decorative-divider.svg" alt="" role="presentation" className="h-4 w-full" />
+```
+
+**Rule of thumb:**
+- Informative → describe the content/function
+- Decorative → `alt=""` (empty string)
+- Link → describe the link destination
+- Complex (chart/diagram) → link to a text description nearby
+
+---
+
+### 8. Touch Targets
+
+**Why it matters:** WCAG 2.1 requires touch targets ≥ 44×44px. Small targets frustrate all users, especially on mobile.
+
+**Common issues:**
+- Small icon buttons (24×24 or smaller)
+- Closely packed links in nav or footer
+- Small form inputs on mobile
+
+**Fixes:**
+
+```tsx
+// BEFORE — 28×28 icon button, hard to tap
+<button className="p-1">
+  <XIcon className="h-5 w-5" />
+</button>
+
+// AFTER — padded to 44×44 minimum
+<button
+  className="p-2.5"
+  style={{ minWidth: '44px', minHeight: '44px' }}
+  aria-label="Close"
+>
+  <XIcon className="h-5 w-5" aria-hidden="true" />
+</button>
+```
+
+```css
+/* BEFORE — nav links with no spacing */
+.nav-link { display: inline; }
+
+/* AFTER — each link has 44px minimum hit area */
+.nav-link {
+  display: inline-flex;
+  align-items: center;
+  min-height: 44px;
+  padding: 8px 12px;
+}
+```
+
+**Quick check:** On mobile viewport (375px), try tapping each interactive element. If you miss or hit the wrong thing, the target is too small or too close.
+
+---
+
+### 9. Screen Reader Content
+
+**Why it matters:** Screen readers linearize content. Off-screen content, live regions, and status messages must be handled explicitly.
+
+**Common issues:**
+- Loading states not announced
+- Sort/filter changes not announced
+- Off-screen/navigable content not hidden from screen readers
+- Status messages without `role="status"` or `aria-live`
+
+**Fixes:**
+
+```tsx
+// BEFORE — loading not announced
+{loading && <Spinner />}
+{!loading && <DataGrid data={items} />}
+
+// AFTER — loading announced via aria-live
+<div aria-live="polite" aria-atomic="true">
+  {loading && (
+    <div role="status">
+      <span className="sr-only">Loading data...</span>
+      <Spinner aria-hidden="true" />
+    </div>
+  )}
+  {!loading && <DataGrid data={items} />}
+</div>
+```
+
+```tsx
+// BEFORE — sort change not announced
+<button onClick={() => setSort('date')}>Sort by date</button>
+
+// AFTER — sort change announced
+<button onClick={() => { setSort('date'); setAnnounce(`Sorted by date`); }}>
+  Sort by date
+</button>
+<div aria-live="polite" aria-atomic="true" className="sr-only">
+  {announcement}
+</div>
+```
+
+---
+
+## Tool Boundaries
+
+| Tool | Can detect | Cannot detect |
+|------|-----------|---------------|
+| **axe-core / Lighthouse** | Missing alt text, color contrast, heading gaps, missing labels, ARIA errors | Focus order correctness, screen reader flow, real-world keyboard usability |
+| **Manual keyboard test** | Tab order, focus traps, focus visibility | ARIA correctness, label quality, contrast ratios |
+| **Screen reader (VoiceOver/NVDA)** | Announcement quality, label clarity, live region behavior | Color contrast (programmatic), specific WCAG violations |
+| **Color contrast analyzer** | Exact contrast ratios, WCAG pass/fail | Functional usability, real-world readability |
+
+**Recommended workflow:**
+
+1. Run `axe-core` / Lighthouse — fix all detected issues
+2. Tab through the page — fix focus order and visibility
+3. Test with screen reader on — fix announcement quality
+4. Check contrast on all text/background pairs — fix failures
+5. Zoom to 200% / 400% — fix content reflow issues
+
+## Don't
+
+| Pattern | Replacement | Because |
+|---------|-------------|---------|
+| Custom interactive elements not keyboard-accessible | Use native `<button>`, `<a>`, or implement proper ARIA + keyboard handlers | ~25% of users rely on keyboard navigation |
+| Removing focus outlines with `outline: none` | Use `:focus-visible` with a visible focus ring | Lost focus indicator makes site unusable for keyboard users |
+| Icon-only buttons without `aria-label` | Add `aria-label` describing the action | Screen readers cannot convey the action |
+| Placeholder as only form label | Associate `<label>` with `htmlFor`/`id` | Placeholder disappears on input, breaking assistive tech |
+| Missing `alt` text on informative images | Describe content or function in `alt` attribute | Screen reader reads filename instead |
+| Touch targets under 44×44px | Pad interactive elements to 44px minimum hit area | WCAG 2.1 requires 44px for touch targets |
+| Skipping heading levels (h1 → h3) | Maintain sequential hierarchy (h1 → h2 → h3) | Screen reader navigation relies on heading structure |
+
+## Verification
+
+- [ ] Tab through every interactive element — logical order, visible focus, no traps
+- [ ] All icon-only buttons have `aria-label`
+- [ ] All form inputs have associated `<label>` elements
+- [ ] All images have appropriate `alt` text (informative or decorative `alt=""`)
+- [ ] No `outline: none` without `:focus-visible` fallback
+- [ ] Color contrast ≥ 4.5:1 for normal text, ≥ 3:1 for large text
+- [ ] Heading hierarchy is logical (single h1, no skipped levels)
+- [ ] Touch targets ≥ 44×44px on all interactive elements
+- [ ] Dynamic content changes are announced via `aria-live` regions
+- [ ] Modals/dialogs trap focus and return focus on close
+- [ ] Error messages associated with inputs via `aria-describedby`
+- [ ] Page works zoomed to 200% without horizontal scroll or content loss