# NavGroup

> Gathers related navigation rows into one group, with or without a title.

- **Level**: molecule · **Status**: stable · **Role**: navigation
- **Import**: `import { NavGroup } from "@rrios-forge/ui/molecules/nav-group";`
- **Source**: `packages/ui/src/molecules/nav-group`

Gathers related navigation rows into one group. The title is optional, and a collapsible group lets people fold it away. In the rail an app has a single untitled group; titled groups live in the panel a rail row opens.

## Use it for

- App frame / navigation → **The rail that peeks (ADR-044) — the default and the recommendation.** `PageShell` (defaults: `sidebarMode="rail"`, `sidebarPresentation="inset"`, `mobileNav="tabs"`) + `SidebarSection aria-label` + ONE untitled `NavGroup`: home, search, the rooms, settings — same size, same gap. Wrap every `NavItem` in `PageShell.RailPeek` and compose its panel with `PageShell.PeekHeader` / `PeekFacts` / `PeekLinks`. Search is a button row opening `CommandMenu` (⌘K); settings' peek holds the quick controls; phones get `PageShell.MobileTabBar` (≤ 5). No `TopBar` in an app frame. Opt-ins only when a product needs them: the labelled panel (`sidebarMode="auto"`, ⌘\\ collapse, ADR-040), `island`/`column` (ADR-025), the bubble (`mobileNav="bubble"`)

## Stories

- [Playground](/?path=/story/components-molecules-navgroup--playground) · frame: `/iframe.html?id=components-molecules-navgroup--playground&viewMode=story`
- [Basic](/?path=/story/components-molecules-navgroup--basic) · frame: `/iframe.html?id=components-molecules-navgroup--basic&viewMode=story`
- [Collapsible](/?path=/story/components-molecules-navgroup--collapsible) · frame: `/iframe.html?id=components-molecules-navgroup--collapsible&viewMode=story`
- [With badges](/?path=/story/components-molecules-navgroup--with-badges) · frame: `/iframe.html?id=components-molecules-navgroup--with-badges&viewMode=story`

## Decisions that name it

- ADR-009 — Editorial Frame: PageShell v3 + new `TopBar` molecule
- ADR-010 — PageShell v4: bottom dock + mobile floating bubble
- ADR-011 — PageShell v5: adaptive lateral sidebar + mobile nav bubble
- ADR-014 — PageShell: Apple Mail / macOS Big Sur visual register
- ADR-044 — Navigation is a rail that peeks

## Always

- Tokens only (R04); variants are semantic axes, never appearance (R02).
- Typography and actions are Poesía atoms, never raw HTML with utilities.
- Vibrant panes need a ground and never nest (ADR-027).