Navigation Patterns

Dense navigation contracts and route semantics for Chirp UI pages

Page actions AI-ready formats and sharing
Open LLM text
Share with AI
Ask Claude Ask ChatGPT Ask Gemini Ask Copilot

Navigation in Chirp UI is layered. A compact control can be a route link, tab panel switch, disclosure, command launcher, or search entry, and those jobs have different semantics.

Use the canonical repository guide for the full decision model: docs/patterns/navigation.md. For copyable dense application chrome recipes, see docs/patterns/dense-navigation-recipes.md. For current roadmap status, see docs/plans/PLAN-application-chrome-system.md.

Source Of Truth

This page is a published bridge. The repository docs remain the contract for component semantics, application chrome layering, and promotion decisions:

  • docs/patterns/navigation.mdowns the layer model and component decision matrix.
  • docs/patterns/dense-navigation-recipes.mdowns copyable recipe families.
  • docs/plans/PLAN-application-chrome-system.mdowns the active app-chrome backlog and composite gates.
  • docs/fundamentals/responsive.mdowns stress-width expectations.
  • docs/patterns/visual-audit-showcase.mdowns rhythm and visual proof expectations.

Do not add a published-only application chrome API here. New public macros, parameters, emitted classes, or manifest facts must ship through the registry, templates, generated CSS, generated component options, examples, and tests.

Use This When

  • A page needs global app or site movement.
  • An object page needs breadcrumbs, title metadata, actions, and local routes.
  • A docs or workspace surface has nested section navigation.
  • A dense topbar needs search, jump, command, status, or overflow controls.

Blessed Surfaces

  • site_header, navbar, primary_nav, sidebar, and nav_treefor broad navigation.
  • drawer and trayfor phone fallback, inspectors, and supplemental overlay chrome when persistent rails would starve the main surface.
  • breadcrumbsand page headers for object or path context.
  • render_route_tabs / route_tabsfor URL-backed local views.
  • tabs_panelsonly for in-place tab panel switching.
  • command_palette_trigger plus command_palettefor search and jump.
  • command_bar, filter_bar, and action_stripfor page-local tools.

Checks

  • Route navigation stays link-native with realhrefvalues.
  • Current pages usearia-current="page".
  • Route tabs are not modeled as ARIA tabs.
  • Ordinary disclosure navigation is not modeled as an ARIA menu.
  • Dense nav reserves room for expected badge counts.
  • Mobile layouts keep context and primary actions reachable.
  • Application chrome remains recipe-first until deliberate reference implementations prove a stable composite contract.
  • Browser proof covers rail/tray fallback, command focus, route-tab scroll, and no unintended horizontal overflow before composite promotion.

Current Status

Private evidence is complete for page actions, linked nav/sidebar semantics, shell response/OOB branching, and compact header/page hero comparison. That evidence proves current composition patterns, not public API promotion.

The next qualifying step is deliberately built reference implementation repetition: a non-Bengal page-action, linked-branch, or compact docs/reference/catalog implementation, or a third scenario-complete hand-written route family outsidemount_pages()for shell response/OOB helper pressure. Until that exists, keep these surfaces recipe-first and do not add application_chrome(), docs_shell, catalog_shell, compact_page_header, page_actions, or shell response helper APIs.