App keyboard shortcuts: theme flip and a help dialog #175

Goal

Add two app chords and a read-only help dialog. Theme click already fades. This issue does not change that fade.

Why now

Theme change motion ships on its own. The chords and the help surface wait here so the fade can land first.

Locked decisions

Do not re-derive these. Staff already measured them.

• Theme chord is Mod+\. Do not use Notion Mod+Shift+L. TipTap TextAlign already binds Mod-Shift-l even with empty types.
• Help chord is Mod+/ only. Never a bare ?.
• The key flips the current family (Light ↔ Dark, Graphite, Paper). It never returns System or High Contrast.
• Signed-out header click stays Light → Dark → System. Do not unify click and key. Do not describe them as one action.
• Help is a GlobalDialog titled Keyboard shortcuts. No /shortcuts route. No Settings tab.
• Help lists the two app keys only. No Editor table. No remap. No footer.
• Help runs only where GlobalDialog already mounts (/, pad, /editor, private gate). Skip /privacy, /terms, /unsubscribe. Do not add a host in _app.tsx or on legal pages.
• If this help dialog is open, Mod+/ closes it. If another GlobalDialog is open, the key does nothing.
• Match help with e.key === '/'. Do not match e.code === 'Slash' alone (that steals zoom on DE/FR).
• Match backslash with e.key === '\\' or '¥' or e.code === 'Backslash'.
• Live region: one polite role="status" outside .ProseMirror, hotkey path only. Radio click does not speak.
• Discover later: Appearance kbd on desktop only, plus a Keyboard shortcuts link at every breakpoint. PadTitle tooltip names the click. aria-label also names the key.

What to build

One complete path: both chords work, help opens and closes, and Appearance plus the signed-out header teach the two different actions.

1. Add a zero-dep label map and a pure family flip on the theme config. Picker lists read that map. System stays local.
2. Put chords, labels, matchers, the theme run, and the announce bind in one shortcut module. No React. No dialog import.
3. Help dialog reads that list only. Mount a host next to the toaster: window listener plus the live region.
4. Appearance arrows already skip the fade ({ motion: false }). Keep that. Add the kbd hint and the help button.
5. PadTitle click cycle stays the three-step loop. Update tooltip and aria-label only.

Local plan (untracked): Notes/superpowers/plans/2026-08-21-theme-transition-and-shortcuts.md Task 1 and Task 3. Do not treat that path as public docs.

Out of scope

• Changing the theme fade, boot script, or theme-color meta.
• Remap, a command palette, an Editor help table, or composer tooltip fixes.
• Unifying the signed-out click with the family flip.
• A Settings tab, a /shortcuts route, or a hotkeys library.
• Playground, admin-dashboard, TipTap extension keymaps.

Acceptance criteria

• Mod+\ flips the current family and fades on / and the desktop pad. Instant on html.m_mobile.
• Caret stays in the editor. Radio click does not speak. The key speaks once.
• Mod+/ opens and toggles help on / and the pad. Esc and Close restore focus.
• A confirm dialog plus Mod+/ leaves the confirm in place.
• /privacy: help does nothing. The theme key still works.
• Appearance arrows stay instant. Appearance click still fades.
• Help button visible on mobile Settings. kbd desktop only.
• Light and dark walked on / and a desktop pad.

Blocked by

None. Can start after the theme fade change is on main. Naming is already locked on this issue.