A horizontal application header that aligns persistent identity or context, optional top-level navigation, and existing action controls. It owns the row and its regions — while AppShell or another parent owns the surrounding surface, boundary, placement, and responsive handoff.
The regions stay semantically distinct: the brand slot aligns left, destinations stay centered against the whole bar in a named navigation landmark, and global commands align right as existing icon Buttons. Current navigation stays interactive, while every icon’s accessible name remains visible through the existing Tooltip component.
Three equal grid regions keep the canonical BrandAsset left, navigation truly centered, and global actions right. Every icon action shares the sm + ghost + icon-only + rounded recipe. Click a destination to move aria-current="page"; hover or focus an icon to reveal its Tooltip.
The same lockup artwork, dimensions, and circular action silhouette survive a colored context. Only currentColor and the complete ds-on-surface role set change with the host; identity and control geometry do not.
Only the horizontal content regions belong to Topbar. Navigation is optional rather than implied by the component name, and the actions region composes controls instead of restyling them.
| Part | Element | Requirement | Rule |
|---|---|---|---|
| Root | header.ds-topbar | Required | Structural row; parent owns surface, width, placement, and responsive behavior |
| Start | div.ds-topbar__start | Optional | Leading cluster rendered only when brand or persistent context belongs here |
| Brand | ds-topbar__brand | Optional | Canonical BrandAsset lockup, stepping down to mark below its minimum; never live text or an interface icon |
| Context | ds-topbar__context | Optional | One short workspace or product-area label; truncates instead of wrapping |
| Navigation | nav.ds-topbar__nav | Optional | One distinctly named landmark for top-level destinations |
| Nav link | a.ds-topbar__link | 1 or more with nav | Native destination; current route carries aria-current="page" |
| Actions | div.ds-topbar__actions | Optional | End-aligned existing controls; no Topbar-specific control behavior |
| Icon action | button.ds-topbar__icon-action | When used | Composed sm + ghost + icon-only + rounded Button with an accessible name |
Top navigation links use the same compact 32px destination rhythm as SidebarNav. Current changes background and text color only, keeping every label at the resting weight so route changes cannot shift the row.
| Example | State | Driver | Roles | Usage |
|---|---|---|---|---|
| Projects | Rest | — | text.secondary | An available top-level destination |
| Projects | Hover | :hover | control.bg-hovertext.primary | Pointer preview |
| Projects | Active | :active | control.bg-activetext.primary | Press confirmation |
| Projects | Focus | :focus-visible | focus.ring | Shared offset ring around the destination |
| Projects | Current | [aria-current="page"] | selection.bgtext.primary | Current route, still linked and metrically unchanged |
Topbar carries persistent application chrome, not whichever controls happen to fit in a horizontal row.
| Verdict | Rule |
|---|---|
| Do | Use Topbar for persistent application identity, scope, top-level navigation, and global or contextual actions. |
| Do | Render at least one meaningful region; use the optional start region only when brand or persistent context belongs in Topbar. |
| Do | Use one distinctly named navigation landmark, native destination links, and exactly one aria-current="page" without a weight change. |
| Do | Compose existing controls in the actions region; use ds-topbar__icon-action for the canonical circular icon Button and wrap interactive Avatars in a real control. |
| Do | Use the canonical BrandAsset lockup in every Topbar, stepping down to the mark only when its minimum width no longer fits. |
| Don’t | Add a background, border, shadow, width, sticky positioning, z-index, or breakpoint behavior; the parent and AppShell own those decisions. |
| Don’t | Render destinations as Buttons or commands as navigation links; navigation moves somewhere and actions do something. |
| Don’t | Turn Topbar into a second page header with arbitrary titles, breadcrumbs, filters, or dense page-specific actions. |
| Don’t | Hide, collapse, or reorder regions inside the component; AppShell owns responsive priority and Sheet owns transient navigation. |
| Don’t | Replace the brand with an i-* interface icon, retype its wordmark, or switch global icon actions between rounded-square and circular silhouettes. |