# TopBar

> Brand, search and actions across the top of a page without a rail.

- **Level**: molecule · **Status**: stable · **Role**: navigation
- **Import**: `import { TopBar, TopBarSearchTrigger } from "@rrios-forge/ui/molecules/top-bar";`
- **Source**: `packages/ui/src/molecules/top-bar`

Page-level command bar that hosts the brand mark on the left, a search/command pill in the centre, and an actions cluster on the right. Compose with `<PageShell>` for the editorial frame, or render alone above any full-page surface.

## 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"`)

## Axes

| Axis | Part | Values | Default | Meaning |
|---|---|---|---|---|
| `size` | — | `sm` `md` | `md` | Ergonomic scale, in three families (control, text, container). |

## Stories

- [Playground](/?path=/story/components-molecules-topbar--playground) · frame: `/iframe.html?id=components-molecules-topbar--playground&viewMode=story`
- [Brand only](/?path=/story/components-molecules-topbar--brand-only) · frame: `/iframe.html?id=components-molecules-topbar--brand-only&viewMode=story`
- [Search only](/?path=/story/components-molecules-topbar--search-only) · frame: `/iframe.html?id=components-molecules-topbar--search-only&viewMode=story`
- [Actions only](/?path=/story/components-molecules-topbar--actions-only) · frame: `/iframe.html?id=components-molecules-topbar--actions-only&viewMode=story`
- [Compact (mobile)](/?path=/story/components-molecules-topbar--compact) · frame: `/iframe.html?id=components-molecules-topbar--compact&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-013 — PageShell: mobile-nav polymorphism
- ADR-014 — PageShell: Apple Mail / macOS Big Sur visual register
- ADR-016 — NotificationCenter v2: Popover → Drawer + Provider/Hooks
- ADR-022 — The material family: `solid` and `vibrant`
- ADR-030 — Axis vocabulary: one name, one meaning
- 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).