codebyplan 1.13.49 → 1.13.50

package/templates/skills/cbp-frontend-a11y/reference/keyboard-patterns.md

@@ -1,154 +0,0 @@
-# Keyboard Interaction Patterns Reference
-
-Every interactive component must be fully operable with a keyboard alone. Mouse-only patterns are WCAG 2.1 AA failures (Success Criterion 2.1.1).
-
-## Focus Management
-
-### On Mount (Dialog / Modal / Drawer)
-
-When a dialog, modal, or drawer opens:
-
-1. Move focus to the FIRST interactive element inside (or to the dialog container if no interactive element exists — ensure `tabindex="0"` on the container in that case)
-2. For modals with a clear primary action: move focus to the primary action button
-3. For forms: move focus to the first form field
-
-```jsx
-// Using useEffect + ref
-const modalRef = useRef<HTMLDivElement>(null);
-
-useEffect(() => {
-  if (isOpen) {
-    // Focus the first focusable element inside
-    const firstFocusable = modalRef.current?.querySelector<HTMLElement>(
-      'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
-    );
-    firstFocusable?.focus();
-  }
-}, [isOpen]);
-```
-
-### On Close (Dialog / Modal / Drawer)
-
-When a dialog, modal, or drawer closes:
-
-1. Return focus to the element that TRIGGERED the opening (save a ref to it before opening)
-2. If the trigger no longer exists (deleted row), focus the nearest logical element
-
-```jsx
-const triggerRef = useRef<HTMLButtonElement>(null);
-
-const handleClose = () => {
-  setIsOpen(false);
-  // Return focus to trigger
-  triggerRef.current?.focus();
-};
-```
-
-## Tab Order
-
-- Tab order must follow the logical reading/interaction order — typically top-left to bottom-right
-- Never use `tabindex > 0` — it creates a separate tab order before natural DOM order, confusing all keyboard users
-- `tabindex="0"` adds a non-interactive element to natural tab order (use sparingly — prefer interactive elements)
-- `tabindex="-1"` removes from natural tab order but allows programmatic `.focus()` (correct for modal containers)
-
-## Esc Key
-
-Any overlay, popover, dropdown, or modal MUST close on `Escape`:
-
-```jsx
-useEffect(() => {
-  const handleKeyDown = (e: KeyboardEvent) => {
-    if (e.key === 'Escape') {
-      onClose();
-    }
-  };
-  if (isOpen) {
-    document.addEventListener('keydown', handleKeyDown);
-    return () => document.removeEventListener('keydown', handleKeyDown);
-  }
-}, [isOpen, onClose]);
-```
-
-## Arrow Key Navigation
-
-For composite widgets (menu, listbox, radio group, tabs, grid), arrow keys navigate BETWEEN items — Tab moves focus OUT of the widget entirely.
-
-| Widget | Keys |
-|--------|------|
-| Menu / dropdown | `↑`/`↓` between items, `Home`/`End` to first/last |
-| Tabs | `←`/`→` between tabs (horizontal) or `↑`/`↓` (vertical) |
-| Listbox | `↑`/`↓` between options, `Home`/`End` |
-| Grid | `↑`/`↓`/`←`/`→` between cells |
-| Radio group | `↑`/`↓` or `←`/`→` between radios; selection follows focus |
-
-## Focus Traps (Modal)
-
-While a modal is open, Tab and Shift+Tab must cycle WITHIN the modal — not escape to the page behind:
-
-```jsx
-const FOCUSABLE_SELECTORS =
-  'button:not([disabled]), [href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
-
-const handleTabKey = (e: KeyboardEvent) => {
-  const focusableEls = Array.from(
-    modalRef.current?.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTORS) ?? []
-  );
-  const first = focusableEls[0];
-  const last = focusableEls[focusableEls.length - 1];
-
-  if (e.shiftKey && document.activeElement === first) {
-    e.preventDefault();
-    last.focus();
-  } else if (!e.shiftKey && document.activeElement === last) {
-    e.preventDefault();
-    first.focus();
-  }
-};
-```
-
-Library alternative: `focus-trap-react` handles this pattern with accessibility compliance. If it is already in `package.json`, use it.
-
-## Type-Ahead (Listbox / Menu)
-
-When a user types a character while focus is inside a listbox or menu, focus jumps to the first item whose label starts with that character. Implement only when `role="listbox"` or `role="menu"` is used with custom keyboard handling — native `<select>` has this built in.
-
-## Enter and Space Activation
-
-| Element | Enter | Space |
-|---------|-------|-------|
-| `<button>` | Activates | Activates |
-| `<a href>` | Follows link | Scrolls page (native browser) |
-| `<input type="checkbox">` | n/a | Toggles |
-| `role="button"` | Must activate | Must activate |
-| `role="menuitem"` | Activates | Activates |
-
-For custom `role="button"` on a non-button element:
-```jsx
-<div
-  role="button"
-  tabIndex={0}
-  onKeyDown={(e) => {
-    if (e.key === 'Enter' || e.key === ' ') {
-      e.preventDefault();
-      handleActivate();
-    }
-  }}
-  onClick={handleActivate}
->
-  Custom button
-</div>
-```
-
-Prefer `<button>` — it handles Enter/Space natively and avoids this boilerplate.
-
-## Skip Links
-
-For pages with repeated navigation (header nav present on every page), provide a skip-to-main-content link as the first focusable element:
-
-```jsx
-<a href="#main-content" className={styles.skipLink}>
-  Skip to main content
-</a>
-```
-
-Visible on focus (via CSS), hidden otherwise. The `<main id="main-content">` is the target.

package/templates/skills/cbp-frontend-a11y/reference/semantic-html.md

@@ -1,111 +0,0 @@
-# Semantic HTML Reference
-
-Use native HTML semantics first. ARIA is a gap-filler for when no native element meets the need — not a replacement.
-
-## Landmark Roles
-
-| Element | Role | Notes |
-|---------|------|-------|
-| `<main>` | `main` | Exactly ONE per page |
-| `<nav>` | `navigation` | Multiple allowed; each needs an `aria-label` |
-| `<header>` | `banner` (at page scope) | In a sectioning element it becomes generic |
-| `<footer>` | `contentinfo` (at page scope) | |
-| `<aside>` | `complementary` | |
-| `<section>` | `region` (only when it has an `aria-labelledby`) | Without label, it's generic |
-
-Anti-pattern: `<div role="main">` — use `<main>` instead.
-
-## Heading Hierarchy
-
-- One `<h1>` per page — the page title or primary content heading
-- Never skip levels: `h1 → h2 → h3`, not `h1 → h3`
-- Headings convey structure, not visual size — use CSS for size; use the correct level for hierarchy
-- Empty headings (`<h2></h2>`) violate WCAG 2.4.6
-
-## `<button>` vs `<a>`
-
-| Use | Element |
-|-----|---------|
-| Triggers an action (submit, open modal, toggle) | `<button>` |
-| Navigates to a URL | `<a href="...">` |
-| Downloads a file | `<a href="..." download>` |
-
-Anti-patterns:
-- `<div onClick={doAction}>` — not keyboard accessible; use `<button>`
-- `<button onClick={() => router.push('/path')}>` — use `<a href="/path">`; or `<Link href="/path">` in Next.js
-- `<a href="#">` with an onClick — use `<button>` if no real URL
-
-## Form Elements
-
-```html
-<!-- Correct: explicit association -->
-<label htmlFor="email-input">Email</label>
-<input id="email-input" type="email" name="email" />
-
-<!-- Correct: implicit wrapping -->
-<label>
-  Email
-  <input type="email" name="email" />
-</label>
-
-<!-- Anti-pattern: no association -->
-<span>Email</span>
-<input type="email" name="email" />
-```
-
-For fieldsets with radio/checkbox groups:
-```html
-<fieldset>
-  <legend>Preferred contact method</legend>
-  <label><input type="radio" name="contact" value="email" /> Email</label>
-  <label><input type="radio" name="contact" value="phone" /> Phone</label>
-</fieldset>
-```
-
-## Lists
-
-Use `<ul>/<ol>/<li>` for lists of items — screen readers announce item count and position.
-
-Anti-pattern: `<div class="list"><div class="item">...</div></div>` — no count/position announced.
-
-Exception: `list-style: none` on `<ul>` removes list semantics in Safari/VoiceOver. Add `role="list"` when list-style is suppressed:
-```jsx
-<ul role="list" style={{ listStyle: 'none' }}>
-```
-
-## Tables
-
-For data tables (not layout):
-```html
-<table>
-  <caption>Monthly sales by region</caption>
-  <thead>
-    <tr>
-      <th scope="col">Region</th>
-      <th scope="col">Sales</th>
-    </tr>
-  </thead>
-  <tbody>
-    <tr>
-      <th scope="row">North</th>
-      <td>$12,000</td>
-    </tr>
-  </tbody>
-</table>
-```
-
-`<caption>` is the table's accessible name. `scope="col"/"row"` associates headers with cells.
-
-Never use `<table>` for visual layout — use CSS Grid or Flexbox.
-
-## Anti-Pattern Quick-Reference
-
-| Anti-pattern | Fix |
-|-------------|-----|
-| `<div onClick>` | `<button>` or `<a>` |
-| `<span onClick>` | `<button>` |
-| `<img>` missing `alt` | Add `alt="description"` or `alt=""` for decorative |
-| `<input>` missing label | Add `<label htmlFor>` or `aria-label` |
-| `<h1>` used for styling | Use CSS; pick correct heading level |
-| `<table>` for layout | Use CSS Grid/Flexbox |
-| Empty `<button>` (icon only) | Add `aria-label="Close"` |