Navigation Patterns

Dense navigation contracts and route semantics for Chirp UI pages

7 items

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/NAVIGATION.md. For copyable dense application chrome recipes, see docs/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/NAVIGATION.mdowns the layer model and component decision matrix.
  • docs/DENSE-NAVIGATION-RECIPES.mdowns copyable recipe families.
  • docs/plans/PLAN-application-chrome-system.mdowns the active app-chrome backlog and composite gates.
  • docs/RESPONSIVE.mdowns stress-width expectations.
  • docs/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 repeated real app usage proves a stable composite contract.
  • Browser proof covers rail/tray fallback, command focus, route-tab scroll, and no unintended horizontal overflow before composite promotion.