docs(web): nav conventions in apps/web/CLAUDE.md #1023

New issue

Closed

opened 2026-05-09 18:18:26 +00:00 by claude-desktop · 1 comment

claude-desktop commented

2026-05-09 18:18:26 +00:00

Collaborator

As a future contributor,
I want the nav conventions documented in apps/web/CLAUDE.md,
so that I add new top-level routes to the right section, use the right primitives, and don't reintroduce flat top-bar nav.

Acceptance criteria

Doc additions

New section in apps/web/CLAUDE.md titled Navigation primitives placed after Foundation primitives — non-negotiables.
Documents the section structure (WORK / AGENTS / Settings) and how to add a new entry.
Documents <NavSections> + <SidebarNav> + drawer variant + collapse rules.
Documents the shortcut registry contract (apps/web/src/lib/shortcuts.ts) and how to register a new shortcut.
Documents the persisted-state pattern (localStorage + inline <script> in index.html) so future flicker-prone state follows the same recipe.

<nav aria-label> per surface; role="group" + aria-labelledby per section; aria-current="page" on active link; aria-hidden on decorative icons.
Tooltip wiring rule: collapsed-only; aria-label on link carries the name.
prefers-reduced-motion rule for sidebar transitions.

Cross-link

Add a pointer to docs/specs/nav-consolidation.md from CLAUDE.md (root) under the docs index.

Out of scope

Storybook / visual regression docs.
Re-formatting unrelated sections of apps/web/CLAUDE.md.

References

Spec: docs/specs/nav-consolidation.md.
All preceding nav-v2 issues for the implementation that the doc describes.

**As a** future contributor, **I want** the nav conventions documented in `apps/web/CLAUDE.md`, **so that** I add new top-level routes to the right section, use the right primitives, and don't reintroduce flat top-bar nav. ## Acceptance criteria ### Doc additions - [ ] New section in `apps/web/CLAUDE.md` titled **Navigation primitives** placed after **Foundation primitives — non-negotiables**. - [ ] Documents the section structure (WORK / AGENTS / Settings) and how to add a new entry. - [ ] Documents `<NavSections>` + `<SidebarNav>` + drawer variant + collapse rules. - [ ] Documents the shortcut registry contract (`apps/web/src/lib/shortcuts.ts`) and how to register a new shortcut. - [ ] Documents the persisted-state pattern (`localStorage` + inline `<script>` in `index.html`) so future flicker-prone state follows the same recipe. ### A11y baseline reminders - [ ] `<nav aria-label>` per surface; `role="group"` + `aria-labelledby` per section; `aria-current="page"` on active link; `aria-hidden` on decorative icons. - [ ] Tooltip wiring rule: collapsed-only; `aria-label` on link carries the name. - [ ] `prefers-reduced-motion` rule for sidebar transitions. ### Cross-link - [ ] Add a pointer to `docs/specs/nav-consolidation.md` from `CLAUDE.md` (root) under the docs index. ## Out of scope - Storybook / visual regression docs. - Re-formatting unrelated sections of `apps/web/CLAUDE.md`. ## References - Spec: `docs/specs/nav-consolidation.md`. - All preceding `nav-v2` issues for the implementation that the doc describes.

claude-desktop added this to the nav-v2 milestone

2026-05-09 18:18:26 +00:00

claude-desktop added the

area:dashboard

type:user-story

labels

2026-05-09 18:18:26 +00:00