An open source design system that's fully customizable and agent ready
schema_version: 3 template_version: 7 kind: component id: component:TopNav authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-10-25 owners: [cixzhang] review_triggers: [public-api, behavior, layout, theming, accessibility] verified_by: [ packages/core/src/TopNav/TopNav.test.tsx, packages/core/src/TopNav/tests/TopNavMobileLongHeading.a11y.chromium.spec.ts, packages/core/src/TopNav/tests/TopNavTextSize.interaction.browser.spec.ts, packages/core/src/AppShell/AppShell.test.tsx, apps/storybook/stories/TopNav.stories.tsx, apps/storybook/rtl-audit/targets.json, ] modules: [] families: [] design_specs: [] architecture: [architecture:component-theming-surface, architecture:public-component-api] contributing: []
system_specs: []
TopNav component contract
Contract at a glance
| Area | Contract |
|---|---|
| Public contract | TopNav with heading, startContent (alias children), centerContent, endContent, and label; target top-nav with a mode state. |
| Behavior | A labeled navigation landmark with start, optional center, and end regions. Inside AppShell's mobile layout it becomes a compact bar (heading, end content, and, while auto toggles are on, a drawer toggle) and its start and center content move into a drawer. |
| End-user impact | Screen-reader users get a named navigation landmark; phone-width users keep the product heading, end controls, and, while auto toggles are on, a drawer toggle in view while the navigation items move into the drawer. |
| Builder impact | None. Callers fill slots; children is accepted so nav items are not dropped. |
| Compatibility/readiness | Records shipped behavior; no prop, default, target, or export changes. Two implementation gaps (see Current-state impact). |
| Review checks | Reject dropping children when startContent is absent, dropping the three-region layout when centerContent is present, an unlabeled landmark, or a mobile bar that hides the toggle while drawer content exists and auto toggles are on (FR5). |
| Governing rules | component:AppShell FR9–FR10 select the render mode; MobileNav owns the drawer dialog; architecture:component-theming-surface. |
This table is a review projection; the body below is authoritative.
Intent
TopNav is the horizontal navigation bar of an application header. It owns the
bar's landmark, its slot layout, and how the bar and its content render in each
of the three modes AppShell selects: the full bar, the mobile bar, and the
drawer. Consumer usage lives in TopNav.doc.mjs.
Compatibility and migration
- Released default preserved:
yes - Compatibility class: records shipped behavior; no public prop, default, target, or export changes
- Controlled/uncontrolled behavior: not applicable
- Migration decision: none
Consumer migration instructions belong in consumer docs and release notes.
Current-state impact
- Caller props can replace the landmark's role and name. Other DOM props
spread onto the
<nav>afterroleandaria-label, so a callerroleoraria-labelreplaces them.architecture:public-component-apiINV5 keeps component-owned accessibility from being overwritten by accident. - Wide end content shifts the center. End content wider than its share widens the end region and moves the center content toward the start.
Ownership boundary
Owns
- The navigation landmark and its default name (FR1, AR1).
- Slot resolution and the flex and three-region layouts (FR2–FR4).
- The mobile-bar and drawer renderings of the bar itself (FR5, FR6).
- The
<nav>'s positioning and styling inputs (FR8, FR9). - The slot each descendant sits in, which TopNav menus read for popover alignment (FR7).
Does not own / non-goals
- Each item's rendering in each mode — owned by
component:TopNavItem,component:TopNavMenu,component:TopNavMegaMenu,component:TopNavMegaMenuItem,component:TopNavMegaMenuFeaturedCard, andcomponent:TopNavHeading. - Which render mode applies and when — owned by
component:AppShell. - The drawer dialog, its header, focus behavior, and dismissal — owned by
MobileNav; the toggle is MobileNav's
MobileNavToggle. - The exported
TopNavRenderContextanduseTopNavRenderMode— an uncontracted module; this record covers only how TopNav responds to the mode.
Public concepts
| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
|---|---|---|---|---|---|---|---|
| Render mode | default, mobile-bar, drawer |
Full bar, compact phone bar, or drawer content. | Set by AppShell or the exported context. | default |
component:AppShell |
Stable | TypeScript rejects other values. |
| Slot | start, center, end |
The region a descendant renders in. | default mode. |
start |
component:TopNav |
Stable | Not caller-settable; set by TopNav. |
Behavioral and layout contract
| ID | Invariant | Basis |
|---|---|---|
| FR1 | In default and mobile-bar modes TopNav renders one <nav role="navigation"> named by label, or by the translated @astryx.topNav.landmarkLabel ("Top navigation") when label is omitted. It carries top-nav, the forwarded ref, and other DOM props; mobile-bar adds data-mode="mobile-bar". |
Current source and tests |
| FR2 | startContent wins over children; children render as start content only when startContent is null or undefined. |
Current source and tests |
| FR3 | Without centerContent the bar is a flex row: heading then start content at the inline start, end content pushed to the inline end. No region overlaps another; when the regions do not fit one row, the bar wraps and the end content moves to a second line, and a region wider than the whole bar wraps its own items (spec:AST-102 FR4). |
Current source and tests |
| FR4 | With centerContent the bar has three regions that center the center content while the start and end regions each fit their equal share of one row; when they do not fit one row, the bar wraps as FR3 describes. |
Current source and tests |
| FR5 | mobile-bar mode renders the heading, then the end content and, when drawer content exists and auto toggles are on, the mobile nav toggle at the inline end. Start and center content do not render. The heading yields width first so end content and the toggle stay on screen. Drawer content exists when start or center content is present or AppShell passes side nav content. |
Current source and tests |
| FR6 | drawer mode renders a MobileNav whose header is heading and whose body is start then center content in a vertical list, a divider when items and side nav content are both present, then any side nav content AppShell passes. With neither, TopNav renders nothing. |
Current source and tests |
| FR7 | In default mode TopNav tells start, center, and end descendants which slot they are in. |
Current source |
| FR8 | The <nav> itself is not a positioned element, so it creates no stacking context. |
Current source and tests |
| FR9 | className, style, and xstyle merge onto the <nav> after component styles in default and mobile-bar modes. |
Current source |
Allowed variation
- AV1 — Slot content. Caller content varies without becoming TopNav anatomy.
- AV2 — Theme styling. Themes may restyle
top-navper mode without changing regions, order, or the landmark.
Representative states
| State | Required invariant | Allowed variation |
|---|---|---|
| Heading and items, no center | Flex row; end content at the inline end. | Gaps and padding. |
| Center content present | Three regions; center centered while each side fits its share (FR4). | Column content. |
| Mobile bar with a long heading | With auto toggles on, toggle and end content stay inside the bar. | Heading truncation. |
| Mobile bar with no drawer content | No toggle. | — |
| Drawer with items and side nav | Items, divider, side nav content. | Item modes. |
Transformation and precedence order
- ORD1 — Start content.
startContent, thenchildren(FR2).
Performance and resources
- PR1 — No measurement. TopNav observes no size and registers no listener.
Accessibility contract
- AR1 — Named landmark. Every rendered bar is a navigation landmark with an accessible name (FR1).
- AR2 — Toggle reachable. In
mobile-barmode with drawer content and auto toggles on, the toggle stays fully on screen, and inside the opened drawer the close button stays fully in the viewport, even with a long heading.
Design relationships
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|---|---|---|---|---|
| Product icon and name | Heading slot at the inline start. | Current source and public docs | Prominent | FR3, FR5 |
| Navigation items | Start or center content. | Current source and public docs | Prominent | FR2–FR4, FR6 |
| More menu | A caller-placed menu; TopNav renders none itself. | Public docs | Supporting | FR2 |
| Flex area | End content for search, actions, or profile. | Current source and public docs | Supporting | FR3, FR5 |
No anatomy-theming map is recorded yet; the block is optional during migration. Mapping TopNav's four anatomy parts against the family's seven targets, by delegation where a part belongs to a sub-component, is deferred. Each family component's record names its own target.
Family and system relationships
component:AppShellselects the render mode and passes side nav content.- MobileNav renders the drawer TopNav fills.
architecture:component-theming-surfaceowns target qualification.
Verification map
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
|---|---|---|---|---|
| FR1, AR1 | TopNav.test.tsx landmark tests |
Default and mobile-bar; default and custom name | A missing role or name fails. | audit:TopNav/accessibility |
| FR2–FR4, FR8 | TopNav.test.tsx slot tests |
Each slot; all slots; center without start/end | A dropped slot, wrong precedence, or positioned nav fails. | audit:TopNav/layout |
| FR3, FR4 wrap | TopNavTextSize.interaction.browser.spec.ts at 1280 px and 100%, 200% and 250% default font size |
Full Example; Centered With Start Content | A navigation item covered by another region, a page that scrolls sideways, or a changed layout at 100% fails. | audit:TopNav/layout |
| FR5, FR6 | AppShell.test.tsx mobile suites |
Heading-only; items; items with side nav | A missing toggle or duplicated items fails. | audit:TopNav/behavior |
| AR2 | TopNavMobileLongHeading.a11y.chromium.spec.ts |
Long heading at phone width | The toggle or close button leaves the viewport. | audit:TopNav/accessibility |
| RTL relation | RTL audit curated D2 target (apps/storybook/rtl-audit/targets.json) on TopNav / Full example |
Heading and first navigation item; LTR and RTL | A heading that is not at the inline start of the navigation items fails D2. | audit:TopNav/i18n-rtl |
Read from source, with no focused test yet: the mobile bar's part order (FR5); the drawer's heading header (FR6); other DOM props reaching the <nav> (FR1); the auto-toggle condition (FR5); rendering nothing in drawer mode with no content (FR6); the top-nav target and its mode state (FR1); the flex and three-region layout geometry at the default text size (FR3, FR4); that start and center content do not render in the mobile bar (FR5); the drawer's content order and divider (FR6); FR7; and FR9.
Decision log
No component-local decision is recorded.
Open questions
None.
Content boundary
This file does not duplicate consumer prop tables, examples, item behavior, or the drawer's dialog behavior. It links to their owners.