refactor(a11y): apply Phase 10 review findings

code-reviewer / pr-test-analyzer / ux-reviewer:

Contrast (completes the token migration):
- Replace the remaining hardcoded #2196f3 literals across the new-page stylesheets
  with var(--color-primary) (now #1565c0) so primary buttons/borders actually meet
  AA — the contrast test guarded the token but components bypassed it. Update the
  stale contrast comment block in AnimalEditorStepper.scss.

A11y (ux-reviewer must-fixes):
- ?-opened help now focuses the header trigger first, so the shared Modal returns
  focus there on close (no dropped focus).
- DayEditor form inputs keep a visible :focus-visible outline (was outline:none).
- AnimalEditor Alt+N now opens the add-electrode-group dialog (was a silent no-op
  while the help advertised it); aria-atomic on its step announcer; drop redundant
  role="navigation".
- ElectrodeGroups table: status badge is now an aria-labelled icon (not emoji-only,
  WCAG 1.4.1) with a stable class key; Edit buttons get a disambiguating aria-label.
- Shortcuts trigger: title tooltip ("press ?") + :focus-visible ring.

Tests (pr-test-analyzer gaps):
- AnimalEditor stepper Alt+Arrow + Alt+N + aria-current; Alt+N no-op on a no-add
  step; shortcuts ignored while the help dialog is open; saveNow success + error
  paths. Document the jsdom <details> keyboard-activation limitation inline.

Deferred (overview.md): Alt+Arrow vs browser Back/Forward on Windows/Linux.

Baselines 125/125; full suite 3006 passed / 0 skipped; lint 0 errors.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: edeno

.claude/docs/plans/v3-workspace-cutover/overview.md

@@ -229,6 +229,13 @@ not executed here.
      relative/human-readable day labels for animals with 60–200+ days, and an explicit
      success confirmation. Deferred to the [Phase 10](phase-10-a11y-keyboard.md) pass.
 
+- **Phase 10 review item deferred.** The `Alt+←` / `Alt+→` stepper shortcuts (the
+  chord the phase spec prescribed) collide with the browser's Back/Forward navigation
+  on Windows/Linux; the handler `preventDefault`s, so in-app it advances the stepper
+  rather than navigating history. **Follow-up:** consider `Alt+PageUp/PageDown` (or
+  `Alt+Shift+Arrow`) for cross-platform safety, or add a platform note in the shortcuts
+  help. Kept as specified for now; revisit before v3.0.0 if user feedback warrants.
+
 ## Plan revisions
 
 - **2026-06-03 — parity model corrected; a byte-parity phase inserted after export.** Pre-Phase-5

src/__tests__/integration/aria-landmarks.test.jsx

@@ -216,6 +216,8 @@ describe('ARIA Landmarks', () => {
       expect(container.querySelectorAll('[role="banner"], header')).toHaveLength(1);
       expect(container.querySelectorAll('[role="contentinfo"], footer')).toHaveLength(1);
       expect(screen.getByRole('link', { name: /back to workspace/i })).toBeInTheDocument();
+      // Exactly one step is marked current for assistive tech.
+      expect(container.querySelectorAll('[aria-current="step"]')).toHaveLength(1);
     });
 
     it('keeps the default route (#/) on the legacy form even with flags enabled', () => {

src/__tests__/integration/keyboard-navigation.test.jsx

@@ -198,7 +198,10 @@ describe('Keyboard Navigation Accessibility', () => {
       firstSummary.focus();
       expect(document.activeElement).toBe(firstSummary);
 
-      // Activating the summary (Enter/click on a native disclosure) expands it.
+      // Activating the summary expands it. jsdom does not toggle <details> on a
+      // synthetic Enter/Space keydown (it implements activation only via click), so
+      // we assert keyboard *focusability* above and activation via click here; the
+      // real Enter/Space toggle is browser-native and covered by the e2e lane.
       await user.click(firstSummary);
       await waitFor(() => expect(details.open).toBe(true));
     });

src/__tests__/integration/shortcuts.integration.test.jsx

@@ -81,4 +81,46 @@ describe('global shortcuts + help (integration)', () => {
     fireEvent.keyDown(document.body, { key: 'n', altKey: true });
     expect(await screen.findByRole('dialog', { name: /add task/i })).toBeInTheDocument();
   });
+
+  it('Alt+N is a no-op on a step with no add target (Overview)', async () => {
+    await renderRoute(`#/day/${DAY_ID}`);
+    await screen.findByRole('heading', { name: /session metadata/i });
+
+    fireEvent.keyDown(document.body, { key: 'n', altKey: true });
+    await act(async () => { await Promise.resolve(); });
+    // No dialog appears and the view is unchanged.
+    expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
+    expect(screen.getByRole('heading', { name: /session metadata/i })).toBeInTheDocument();
+  });
+
+  it('further shortcuts are ignored while the help dialog is open', async () => {
+    await renderRoute(`#/day/${DAY_ID}`);
+    await screen.findByRole('heading', { name: /session metadata/i });
+
+    fireEvent.keyDown(document.body, { key: '?' });
+    expect(await screen.findByRole('dialog', { name: /keyboard shortcuts/i })).toBeInTheDocument();
+
+    // With a modal open, Alt+N must not open another dialog and Alt+Arrow must not
+    // navigate the stepper underneath.
+    fireEvent.keyDown(document.body, { key: 'n', altKey: true });
+    fireEvent.keyDown(document.body, { key: 'ArrowRight', altKey: true });
+    await act(async () => { await Promise.resolve(); });
+    expect(screen.getAllByRole('dialog')).toHaveLength(1);
+    expect(screen.getByRole('dialog', { name: /keyboard shortcuts/i })).toBeInTheDocument();
+  });
+
+  it('Alt+ArrowRight and Alt+N drive the AnimalEditor stepper', async () => {
+    await renderRoute('#/animal/remy/editor');
+    await screen.findByRole('heading', { name: /step 1: electrode groups/i });
+
+    // Alt+N on step 1 opens the add-electrode-group dialog.
+    fireEvent.keyDown(document.body, { key: 'n', altKey: true });
+    expect(await screen.findByRole('dialog', { name: /add electrode group/i })).toBeInTheDocument();
+    fireEvent.keyDown(document, { key: 'Escape' });
+    await act(async () => { await Promise.resolve(); });
+
+    // Alt+ArrowRight advances to Channel Maps.
+    fireEvent.keyDown(document.body, { key: 'ArrowRight', altKey: true });
+    expect(await screen.findByRole('heading', { name: /step 2: channel maps/i })).toBeInTheDocument();
+  });
 });

src/components/CalendarDayCreator/CalendarDayCreator.css

@@ -65,16 +65,16 @@
   padding: 0.375rem 0.75rem;
   font-size: 0.875rem;
   font-weight: 500;
-  color: var(--color-primary, #2196f3);
+  color: var(--color-primary, var(--color-primary));
   background-color: var(--color-white, #ffffff);
-  border: 1px solid var(--color-primary, #2196f3);
+  border: 1px solid var(--color-primary, var(--color-primary));
   border-radius: 4px;
   cursor: pointer;
   transition: background-color 0.2s, color 0.2s;
 }
 
 .btn-today:hover {
-  background-color: var(--color-primary, #2196f3);
+  background-color: var(--color-primary, var(--color-primary));
   color: var(--color-white, #ffffff);
 }
 
@@ -130,7 +130,7 @@
 }
 
 .calendar-day:focus {
-  outline: 2px solid var(--color-primary, #2196f3);
+  outline: 2px solid var(--color-primary, var(--color-primary));
   outline-offset: 2px;
 }
 
@@ -140,14 +140,14 @@
 }
 
 .calendar-day--today {
-  border: 2px solid var(--color-primary, #2196f3);
+  border: 2px solid var(--color-primary, var(--color-primary));
   font-weight: 600;
 }
 
 .calendar-day--selected {
-  background-color: var(--color-primary, #2196f3);
+  background-color: var(--color-primary, var(--color-primary));
   color: var(--color-white, #ffffff);
-  border-color: var(--color-primary, #2196f3);
+  border-color: var(--color-primary, var(--color-primary));
 }
 
 .calendar-day--selected:hover {
@@ -221,7 +221,7 @@
 }
 
 .legend-indicator--selected {
-  background-color: var(--color-primary, #2196f3);
+  background-color: var(--color-primary, var(--color-primary));
 }
 
 .legend-indicator--existing {
@@ -230,7 +230,7 @@
 }
 
 .legend-indicator--today {
-  border: 2px solid var(--color-primary, #2196f3);
+  border: 2px solid var(--color-primary, var(--color-primary));
   background-color: var(--color-white, #ffffff);
 }
 
@@ -260,7 +260,7 @@
 
 .btn-primary {
   color: var(--color-white, #ffffff);
-  background-color: var(--color-primary, #2196f3);
+  background-color: var(--color-primary, var(--color-primary));
 }
 
 .btn-primary:hover:not(:disabled) {

src/components/ShortcutsHelp/ShortcutsHelp.scss

@@ -50,3 +50,8 @@
 .shortcuts-trigger:hover {
   background: #f5f5f5;
 }
+
+.shortcuts-trigger:focus-visible {
+  outline: 2px solid var(--color-primary);
+  outline-offset: 2px;
+}

src/layouts/AppLayout.jsx

@@ -103,9 +103,16 @@ export function AppLayout() {
   // navigation / add are broadcast to whichever stepper is on screen; help opens a
   // dialog; Ctrl/Cmd+S flushes the workspace save.
   const [shortcutsOpen, setShortcutsOpen] = useState(false);
+  const shortcutsTriggerRef = useRef(null);
+  // Open help; focus the trigger first so that when `?` opens the dialog (no element
+  // focused), the Modal captures a real opener and returns focus to it on close.
+  const openShortcuts = () => {
+    shortcutsTriggerRef.current?.focus();
+    setShortcutsOpen(true);
+  };
   useGlobalShortcuts({
     onSave: persistence.saveNow,
-    onShowHelp: () => setShortcutsOpen(true),
+    onShowHelp: openShortcuts,
     onNextStep: () => emitStepperShortcut('next'),
     onPrevStep: () => emitStepperShortcut('prev'),
     onAdd: () => emitStepperShortcut('add'),
@@ -204,11 +211,13 @@ export function AppLayout() {
           <img src={logo} alt="Loren Frank Lab logo" />
         </a>
         <button
+          ref={shortcutsTriggerRef}
           type="button"
           className="shortcuts-trigger"
           onClick={() => setShortcutsOpen(true)}
           aria-label="Keyboard shortcuts"
           aria-haspopup="dialog"
+          title="Keyboard shortcuts (press ?)"
         >
           <span aria-hidden="true">⌨</span>
           <span className="visually-hidden">Keyboard shortcuts</span>

src/pages/AnimalEditor/AnimalEditorStepper.jsx

@@ -72,8 +72,15 @@ export default function AnimalEditorStepper() {
   // early returns below to satisfy the Rules of Hooks; the step count is filled in
   // once `steps` is built further down (stepCountRef.current = steps.length).
   const stepCountRef = useRef(1);
+  // The current step's "add" handler (Alt+N), or null when the step has no add
+  // target. Filled in below once the handlers + active step are known.
+  const addHandlerRef = useRef(null);
   useStepperShortcut(
     useCallback((action) => {
+      if (action === 'add') {
+        addHandlerRef.current?.();
+        return;
+      }
       setActiveStep((cur) => {
         if (action === 'next') return Math.min(cur + 1, stepCountRef.current - 1);
         if (action === 'prev') return Math.max(cur - 1, 0);
@@ -562,9 +569,11 @@ export default function AnimalEditorStepper() {
 
   // Check if we're on the final step
   const isOnFinalStep = activeStep === steps.length - 1;
-  // Keep the shortcut handler's step count current (the ref + hook are declared up
-  // top, before the early returns, to satisfy the Rules of Hooks).
+  // Keep the shortcut handler's step count + add target current (the ref + hook are
+  // declared up top, before the early returns, to satisfy the Rules of Hooks). Alt+N
+  // adds an electrode group on the Electrode Groups step (0); other steps have no add.
   stepCountRef.current = steps.length;
+  addHandlerRef.current = activeStep === 0 ? handleAddGroup : null;
 
   return (
     <div className="animal-editor-stepper">
@@ -582,7 +591,7 @@ export default function AnimalEditorStepper() {
       </div>
 
       {/* Step indicators */}
-      <nav className="animal-editor-step-nav" role="navigation" aria-label="Configuration steps">
+      <nav className="animal-editor-step-nav" aria-label="Configuration steps">
         <ul className="step-indicators">
           {steps.map((step, index) => (
             <li
@@ -615,7 +624,7 @@ export default function AnimalEditorStepper() {
 
       {/* Announce the active step to screen readers on change (matches the
           DayEditor route announcer pattern). */}
-      <div className="visually-hidden" role="status" aria-live="polite">
+      <div className="visually-hidden" role="status" aria-live="polite" aria-atomic="true">
         {`Step ${activeStep + 1} of ${steps.length}: ${steps[activeStep].label}`}
       </div>
 

src/pages/AnimalEditor/AnimalEditorStepper.scss

@@ -43,22 +43,22 @@
   padding: 0.5rem 1rem;
   font-size: 0.875rem;
   font-weight: 500;
-  color: #2196f3;
+  color: var(--color-primary);
   background-color: transparent;
-  border: 1px solid #2196f3;
+  border: 1px solid var(--color-primary);
   border-radius: 4px;
   text-decoration: none;
   transition: background-color 0.2s ease, color 0.2s ease;
   white-space: nowrap;
   cursor: pointer;
 
   &:hover {
-    background-color: #2196f3;
+    background-color: var(--color-primary);
     color: #fff;
   }
 
   &:focus {
-    outline: 2px solid #2196f3;
+    outline: 2px solid var(--color-primary);
     outline-offset: 2px;
   }
 }
@@ -107,7 +107,7 @@
   }
 
   &:focus {
-    outline: 2px solid #2196f3;
+    outline: 2px solid var(--color-primary);
     outline-offset: -2px;
     z-index: 1;
   }
@@ -135,13 +135,13 @@
 /* Active step */
 .step-indicator.active {
   .step-indicator-button {
-    border-bottom-color: #2196f3;
+    border-bottom-color: var(--color-primary);
     background-color: #e3f2fd;
     font-weight: 600;
   }
 
   .step-number {
-    background-color: #2196f3;
+    background-color: var(--color-primary);
     color: #fff;
   }
 }
@@ -194,7 +194,7 @@
   font-family: inherit;
 
   &:focus {
-    outline: 2px solid #2196f3;
+    outline: 2px solid var(--color-primary);
     outline-offset: 2px;
   }
 
@@ -220,7 +220,7 @@
 
 .btn-next,
 .btn-save {
-  background-color: #2196f3;
+  background-color: var(--color-primary);
   color: #fff;
 
   &:hover:not(:disabled) {
@@ -277,7 +277,7 @@
   font-family: inherit;
 
   &:focus {
-    outline: 2px solid #2196f3;
+    outline: 2px solid var(--color-primary);
     outline-offset: 2px;
   }
 
@@ -288,7 +288,7 @@
 }
 
 .btn-primary {
-  background-color: #2196f3;
+  background-color: var(--color-primary);
   color: #fff;
 
   &:hover:not(:disabled) {
@@ -405,7 +405,7 @@ input[type="file"] {
   }
 
   .step-indicator.active .step-indicator-button {
-    border-left-color: #2196f3;
+    border-left-color: var(--color-primary);
   }
 
   .animal-editor-footer {
@@ -478,11 +478,11 @@ input[type="file"] {
 
 /* ===== WCAG AA Compliance Notes ===== */
 /*
- * Color contrast ratios verified:
- * - Primary blue (#2196f3) on white: 3.15:1 (AA for large text)
- * - Primary dark (#1976d2) on white: 4.58:1 (AA)
- * - Error red (#d32f2f) on white: 4.52:1 (AA)
- * - Success green (#2e7d32) on white: 4.56:1 (AA)
+ * Color contrast ratios verified (see src/__tests__/unit/a11y/contrast.test.js):
+ * - Primary (--color-primary #1565c0) on white: 5.75:1 (AA)
+ * - Warning (--color-warning #bf360c) on white: 5.60:1 (AA)
+ * - Error (--color-error #c62828) on white: 5.62:1 (AA)
+ * - Success green (#2e7d32) on white: 5.13:1 (AA)
  * - Grey 600 (#666) on white: 5.74:1 (AA)
  * - Grey 900 (#333) on white: 12.6:1 (AAA)
  *