codebyplan 1.5.0 → 1.8.0

package/templates/skills/cbp-checkpoint-update/SKILL.md

@@ -0,0 +1,115 @@
+---
+scope: org-shared
+name: cbp-checkpoint-update
+description: Update checkpoint state (activate, update context, etc.)
+argument-hint: [checkpoint-number]
+effort: high
+---
+
+# Checkpoint Update Command
+
+Update checkpoint status, context, or other fields.
+
+## Instructions
+
+### Step 0.5: Parse `$ARGUMENTS`
+
+Parse the argument:
+
+| Shape | Regex | Resolves to |
+|-------|-------|-------------|
+| `{chk}` (e.g. `108`) | `^[0-9]+$` | Target CHK-{chk} |
+| _(empty)_ | — | Use MCP `get_current_task` to find the active checkpoint |
+
+Anything else is malformed — surface this error and stop:
+
+```
+checkpoint-update: invalid argument `{value}`. Expected:
+  108    → CHK-108
+  (empty) → active checkpoint
+```
+
+#### Worked examples
+
+- `checkpoint-update 108` → CHK-108
+- `checkpoint-update` (no arg) → active checkpoint via `get_current_task`
+- `checkpoint-update abc` → error: malformed
+- `checkpoint-update 108-1` → error: malformed (that is task-start's shape)
+
+### Step 1: Get Current Checkpoint
+
+Given the parse from Step 0.5:
+
+| Parse | Resolution path |
+|-------|-----------------|
+| `{chk}` | MCP `get_checkpoints(repo_id)` → filter `number === {chk}` (must exist). |
+| _(empty)_ | MCP `get_current_task` with repo_id (and worktree_id resolved via `npx codebyplan resolve-worktree`) to find the active checkpoint. If no active checkpoint, use MCP `get_checkpoints` filtered by `pending` status to find pending ones. |
+
+### Step 1.5: Detect Entry Context (from `/cbp-task-complete` expand path)
+
+When invoked with a preamble naming `Triggered from /cbp-task-complete with intent: expand`, the user just completed the last task in the checkpoint and chose Option B "Expand checkpoint with more tasks" per `task-complete/reference/checkpoint-done-branching.md`.
+
+In that case, lead with explicit guidance:
+
+```
+You're expanding [CHK-NNN]: [title]
+The checkpoint has no remaining tasks; you chose to add more before shipping.
+
+Recommended sequence:
+  1. (here) update context — record any new decisions / discoveries / scope clarifications driving the expansion
+  2. (next) `/cbp-task-create` — add the specific tasks the expansion calls for
+
+You can skip the context update (Steps 2–3) if the expansion is purely additive with no scope change. Run `/cbp-task-create` directly in that case.
+```
+
+When invoked WITHOUT this preamble (direct user invocation), skip the guidance and proceed normally.
+
+### Step 2: Determine Update
+
+Ask user via AskUserQuestion what to update:
+- **Activate**: Change pending → active (starts development)
+- **Update context**: Add decisions, discoveries, constraints
+- **Update goal**: Refine the checkpoint goal
+- **Update deadline**: Change the deadline
+
+When the entry context is "expand from task-complete", `Update context` is the recommended default.
+
+### Step 3: Apply Update
+
+Use MCP `update_checkpoint` with the appropriate fields.
+
+**For activation:**
+```
+update_checkpoint(checkpoint_id, status: "active")
+```
+
+**For context updates:**
+Read current checkpoint to get existing context, merge new data, then:
+```
+update_checkpoint(checkpoint_id, context: merged_context)
+```
+
+### Step 4: Show Result and Route
+
+```
+## Checkpoint Updated
+
+**CHK-[NNN]**: [Title]
+**Status**: [new status]
+**Updated**: [what changed]
+```
+
+When the entry context was "expand from task-complete", append:
+
+```
+**Next:**
+Run `/cbp-task-create` to add the new task(s) under this checkpoint.
+```
+
+Otherwise, no follow-up directive — the user is back in control.
+
+## Integration
+
+- **Reads**: MCP `get_current_task`, `get_checkpoints`
+- **Writes**: MCP `update_checkpoint`
+- **Triggered by**: User directly, OR `/cbp-task-complete` Step 9c (expand path) — see `task-complete/reference/checkpoint-done-branching.md`

package/templates/skills/cbp-frontend-a11y/SKILL.md

@@ -0,0 +1,109 @@
+---
+scope: org-shared
+name: cbp-frontend-a11y
+description: Pre-implementation accessibility playbook loaded BEFORE writing UI / styling code. Produces a per-component checklist of WCAG 2.1 AA obligations from semantic HTML, ARIA roles/states, keyboard patterns, and contrast requirements.
+effort: xhigh
+---
+
+# Frontend Accessibility (Pre-Implementation Playbook)
+
+Loaded by `round-executor` Step 2.6 BEFORE any UI or styling file is written, AFTER `frontend-design` has committed to an aesthetic direction. Produces a concrete pre-write checklist — not a post-implementation audit.
+
+## When this skill fires
+
+Invoked when the wave's `skill_preloads[]` contains `"frontend-a11y"` (set by planner Phase 5.6 when `wave.files[]` includes UI-bearing paths). See `rules/frontend-accessibility-invocation.md` for the trigger gate.
+
+If none of the wave files are UI-bearing, skip — proceed to Step 3.
+
+## Phase 1: Read tokens and sibling components
+
+1. Identify design tokens from the plan's context or `frontend-design` output — colour tokens are needed for contrast checks.
+2. Glob for sibling components in the same directory as files being authored. Read 1-2 examples to understand existing `aria-*` usage, `role` attributes, keyboard handlers, focus management patterns.
+3. Note the established a11y posture: does the codebase already use `role="dialog"` patterns? Does it trap focus in modals? Are there custom keyboard handlers?
+
+## Phase 2: Detect the stack
+
+Read the planner's `test_strategy.platform` or grep for signal files:
+
+| Signal | Stack |
+|--------|-------|
+| `next.config.ts` | Next.js (App Router) |
+| `expo` in deps | React Native / Expo |
+| `tauri.conf.json` | Tauri web view |
+
+Load the matching reference doc from `reference/` (relative to this SKILL.md):
+
+- Next.js / web: read `reference/semantic-html.md`, `reference/aria-roles-states.md`, `reference/keyboard-patterns.md`, `reference/contrast-visual.md`
+- React Native: read `reference/aria-roles-states.md`, `reference/contrast-visual.md` (semantic HTML n/a for RN)
+- Tauri web view: same as Next.js / web
+
+## Phase 3: Load reference docs
+
+For the detected stack, read EACH applicable reference doc in sequence. Do not skip — the pre-write checklist is derived from their combined content.
+
+Reference docs (paths relative to this SKILL.md):
+
+- `reference/semantic-html.md` — landmark roles, heading hierarchy, element semantics, anti-patterns
+- `reference/aria-roles-states.md` — role table, aria-label vs aria-labelledby, live regions, expanded/pressed/hidden
+- `reference/keyboard-patterns.md` — focus management, tab order, Esc, arrow keys, focus traps, type-ahead
+- `reference/contrast-visual.md` — WCAG 2.1 AA ratios, focus-visible, colour-only state, reduced-motion, touch targets
+
+## Phase 4: Commit to per-component obligations
+
+For each component or element type in `wave.files[]`, derive explicit obligations from the reference docs. Group by component:
+
+```
+Component: <ComponentName> (<path>)
+  - Semantic: [e.g. "use <button> not <div onClick>"]
+  - ARIA: [e.g. "aria-expanded on disclosure trigger"]
+  - Keyboard: [e.g. "Esc closes; focus returns to trigger"]
+  - Contrast: [e.g. "border token needs 3:1 vs background — verify"]
+  - Touch: [e.g. "min 44x44px tap target on mobile"]
+```
+
+Unknown component types get the universal checklist from Phase 5.
+
+## Phase 5: Universal guidelines (applied to every component)
+
+Regardless of component type, every UI component must satisfy:
+
+1. Every interactive element is keyboard-reachable and activatable (Enter/Space for buttons, Enter for links)
+2. Focus-visible is never removed via `outline: none` without a custom indicator meeting 3:1 contrast
+3. No state conveyed via colour alone — icon + text + colour
+4. `prefers-reduced-motion` media query wraps any animation
+5. Touch targets ≥ 44×44 CSS px
+6. Images have `alt` text (decorative images use `alt=""`)
+7. Form inputs have associated `<label htmlFor>` or `aria-label`
+
+## Phase 6: Output pre-write checklist
+
+Produce a flat checklist in `round.context.frontend_a11y_checklist`:
+
+```yaml
+frontend_a11y_checklist:
+  - component: "<ComponentName>"
+    file: "<path>"
+    items:
+      - "[Semantic] use <button> not <div onClick>"
+      - "[ARIA] aria-expanded on trigger; aria-controls referencing panel id"
+      - "[Keyboard] Esc closes panel; focus returns to trigger"
+      - "[Contrast] verify focus ring token meets 3:1 vs background"
+      - "[Touch] min 44x44px on mobile breakpoint"
+```
+
+The executor consults this checklist when authoring each component in Step 3.
+
+## Output back to round-executor
+
+```yaml
+round.context.frontend_a11y_loaded: true
+round.context.frontend_a11y_checklist: [per-component checklist items]
+```
+
+## Integration
+
+- **Invoked by**: `round-executor` Step 2.6 (when `"frontend-a11y"` in `wave.skill_preloads[]`)
+- **Reads**: `reference/semantic-html.md`, `reference/aria-roles-states.md`, `reference/keyboard-patterns.md`, `reference/contrast-visual.md`
+- **Output consumed by**: `round-executor` Step 3 (implementation guidance)
+- **Pairs with**: `frontend-design` (invoked first in Step 2.6), `frontend-ui` + `frontend-ux` (post-implementation Step 3.8)
+- **Trigger rule**: `rules/frontend-accessibility-invocation.md`

package/templates/skills/cbp-frontend-a11y/reference/aria-roles-states.md

@@ -0,0 +1,130 @@
+# ARIA Roles, States, and Properties Reference
+
+**Golden rule**: Prefer native HTML semantics. ARIA fills gaps — it does not replace semantic elements. An `<input type="checkbox">` is always better than `<div role="checkbox">`.
+
+## When to Add a Role
+
+Use `role` ONLY when no native HTML element maps to the semantic need:
+
+| Pattern | Native element | ARIA role (fallback) |
+|---------|---------------|----------------------|
+| Dialog / modal | — | `role="dialog"` + `aria-modal="true"` |
+| Alerting status message | — | `role="status"` or `role="alert"` |
+| Tab list | — | `role="tablist"`, `role="tab"`, `role="tabpanel"` |
+| Custom listbox | — | `role="listbox"`, `role="option"` |
+| Progress indicator | `<progress>` | `role="progressbar"` if `<progress>` unstyled |
+| Tooltip | `title` attr (limited) | `role="tooltip"` + `aria-describedby` |
+
+## aria-label vs aria-labelledby vs aria-describedby
+
+| Attribute | Use when | Priority |
+|-----------|----------|----------|
+| `aria-labelledby` | A visible text element names this element | Highest — overrides aria-label and native label |
+| `aria-label` | No visible text label exists (icon buttons, close buttons) | Medium |
+| `aria-describedby` | Additional descriptive text supplements the label | Lowest — supplementary, not a primary name |
+
+Examples:
+```jsx
+// Icon button — no visible label
+<button aria-label="Close dialog">
+  <Icon name="x" aria-hidden="true" />
+</button>
+
+// Element labelled by visible heading
+<section aria-labelledby="billing-heading">
+  <h2 id="billing-heading">Billing</h2>
+</section>
+
+// Field with hint text
+<input id="password" aria-describedby="password-hint" />
+<span id="password-hint">Must be at least 8 characters</span>
+```
+
+## Live Regions
+
+Announce dynamic content changes to screen readers without moving focus.
+
+| Role / Attribute | Urgency | Use for |
+|-----------------|---------|---------|
+| `aria-live="polite"` | Waits for user to be idle | Status messages, form validation summaries, search result counts |
+| `aria-live="assertive"` | Interrupts immediately | Critical errors, session timeout warnings |
+| `role="status"` | Same as `aria-live="polite"` | Status messages (shorthand) |
+| `role="alert"` | Same as `aria-live="assertive"` | Error alerts (shorthand) |
+
+Anti-pattern: using `role="alert"` for non-urgent messages — screen reader interruptions are disruptive. Reserve for true emergencies.
+
+```jsx
+// Status (polite)
+<div role="status" aria-live="polite">{statusMessage}</div>
+
+// Error (assertive)
+<div role="alert">{errorMessage}</div>
+```
+
+## Common State Attributes
+
+| Attribute | Values | Use for |
+|-----------|--------|---------|
+| `aria-expanded` | `true` / `false` | Disclosure triggers (accordion, dropdown, menu) |
+| `aria-pressed` | `true` / `false` / `"mixed"` | Toggle buttons (bold, like, mute) |
+| `aria-hidden` | `true` | Decorative elements, icon-only images — removes from accessibility tree |
+| `aria-checked` | `true` / `false` / `"mixed"` | Custom checkbox/radio when not using `<input type="checkbox">` |
+| `aria-disabled` | `true` | Visually disabled but still focusable (use sparingly) |
+| `aria-selected` | `true` / `false` | Selected tab, selected option in listbox |
+| `aria-current` | `"page"` / `"step"` / `true` | Current item in nav, current step in wizard |
+
+```jsx
+// Accordion trigger
+<button
+  aria-expanded={isOpen}
+  aria-controls="panel-1"
+>
+  Section title
+</button>
+<div id="panel-1" hidden={!isOpen}>...</div>
+
+// Toggle button
+<button
+  aria-pressed={isBold}
+  onClick={() => setIsBold(!isBold)}
+>
+  Bold
+</button>
+
+// Decorative icon
+<svg aria-hidden="true" focusable="false">...</svg>
+```
+
+## aria-hidden Usage Rules
+
+- `aria-hidden="true"` removes element and ALL descendants from accessibility tree
+- Never place `aria-hidden="true"` on a focusable element (keyboard users still reach it)
+- Common correct uses: decorative icons, background images, duplicate visible text (when the accessible name comes from aria-label)
+
+```jsx
+// Correct: icon inside labelled button
+<button aria-label="Delete">
+  <TrashIcon aria-hidden="true" />
+</button>
+
+// Wrong: aria-hidden on focusable element
+<button aria-hidden="true">...</button>  // users can still Tab to it
+```
+
+## Dialog Pattern
+
+```jsx
+<dialog
+  role="dialog"
+  aria-modal="true"
+  aria-labelledby="dialog-title"
+  aria-describedby="dialog-description"
+>
+  <h2 id="dialog-title">Confirm deletion</h2>
+  <p id="dialog-description">This action cannot be undone.</p>
+  <button onClick={onConfirm}>Delete</button>
+  <button onClick={onClose}>Cancel</button>
+</dialog>
+```
+
+Focus must move INTO the dialog on open and RETURN to the trigger on close. See `keyboard-patterns.md` for focus trap implementation.

package/templates/skills/cbp-frontend-a11y/reference/contrast-visual.md

@@ -0,0 +1,122 @@
+# Contrast and Visual Accessibility Reference
+
+## WCAG 2.1 AA Contrast Requirements
+
+All text and UI components must meet these minimum contrast ratios:
+
+| Content type | Minimum ratio | Standard |
+|-------------|--------------|---------|
+| Normal text (< 18pt / < 14pt bold) | **4.5:1** | WCAG 2.1 AA SC 1.4.3 |
+| Large text (≥ 18pt / ≥ 14pt bold) | **3:1** | WCAG 2.1 AA SC 1.4.3 |
+| UI components (borders, icons, form controls) | **3:1** | WCAG 2.1 AA SC 1.4.11 |
+| Graphical objects (data chart elements, icons conveying meaning) | **3:1** | WCAG 2.1 AA SC 1.4.11 |
+
+**Decorative** elements (purely ornamental, no meaning) are EXEMPT.
+
+### Verification
+
+Use design tokens from `packages/design-tokens/` to derive hex values, then verify with a contrast checker:
+
+- Browser DevTools Accessibility panel
+- `npx @accessibility-checker/cli` against the rendered component
+- Design-tool plugins (Figma Contrast, Stark)
+
+If a token pair is new, record the ratio in a comment in the SCSS: `/* contrast: 5.2:1 vs --color-surface */`.
+
+## Focus Visible
+
+Focus indicators must NEVER be suppressed via `outline: none` or `outline: 0` without providing a replacement that meets **3:1 contrast** against adjacent colour:
+
+```scss
+// Anti-pattern — removes all visible focus indicator
+&:focus {
+  outline: none; // WCAG failure
+}
+
+// Correct — custom focus ring that meets 3:1 contrast
+&:focus-visible {
+  outline: 2px solid var(--color-focus-ring);   // 3:1 minimum
+  outline-offset: 2px;
+}
+```
+
+Use `:focus-visible` (not `:focus`) for the custom ring — `:focus-visible` suppresses the ring for mouse clicks while preserving it for keyboard navigation.
+
+The WCAG 2.2 enhanced criterion (SC 2.4.11, AAA) requires 3:1 contrast + 2px outline area. Target this for new components.
+
+## Colour-Only State Communication
+
+State conveyed through colour alone is a WCAG 2.1 AA failure (SC 1.4.1). Always pair colour with at least one of: icon, text label, pattern, or shape.
+
+| Anti-pattern | Fix |
+|-------------|-----|
+| Red border = error (colour only) | Red border + error icon + "Invalid email" text |
+| Green = online (colour only) | Green dot + "Online" text label |
+| Yellow = warning (colour only) | Yellow background + warning icon + descriptive text |
+| Active nav item is blue (colour only) | Blue + `aria-current="page"` + underline or bold weight |
+
+## prefers-reduced-motion
+
+Users with vestibular disorders may configure `prefers-reduced-motion: reduce` in their OS. Honour it:
+
+```scss
+@keyframes slideIn {
+  from { transform: translateX(-100%); }
+  to   { transform: translateX(0); }
+}
+
+.panel {
+  animation: slideIn 300ms ease-out;
+
+  @media (prefers-reduced-motion: reduce) {
+    animation: none;
+    // Provide instant appearance or a fade (no translate/scale/spin)
+  }
+}
+```
+
+For JavaScript-driven animations:
+
+```ts
+const prefersReduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+if (!prefersReduced) {
+  // run animation
+}
+```
+
+Transitions that solely affect `opacity` (fade) are generally safe — opacity changes do not trigger vestibular responses. Transforms (`translate`, `scale`, `rotate`) and large motion sweeps are the primary triggers.
+
+## Touch Target Size
+
+Interactive elements must have a minimum tap target of **44 × 44 CSS px** (Apple HIG / WCAG 2.5.5 AAA, de-facto standard):
+
+```scss
+.icon-button {
+  min-width: 44px;
+  min-height: 44px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+```
+
+When the visible icon is smaller (e.g. 24px), expand the tap target with padding:
+
+```scss
+.icon-button {
+  padding: 10px; // 24px icon + 2×10px padding = 44px touch target
+}
+```
+
+On mobile breakpoints specifically, verify that adjacent interactive elements have at least 8px spacing between tap target edges to prevent accidental activation.
+
+## Text Resizing
+
+Users who increase browser text size up to 200% must be able to read and use all content without horizontal scroll (WCAG 1.4.4). Use relative units:
+
+- `font-size`: `rem` (relative to browser root, respects user preference)
+- `line-height`: unitless (e.g. `1.5`) or `em`
+- Container widths: `max-width` in `ch` or `%`, never fixed `px` for reading columns
+- Spacing: `em` for component-internal spacing; `rem` for layout spacing
+
+Avoid `px` for font sizes on text elements that users may need to scale.

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

@@ -0,0 +1,154 @@
+# 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.