An open source design system that's fully customizable and agent ready
schema_version: 3 template_version: 7 kind: component id: component:TopNavItem authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-10-25 owners: [cixzhang] review_triggers: [public-api, behavior, accessibility] verified_by: [ packages/core/src/TopNav/TopNav.test.tsx, apps/storybook/stories/TopNav.stories.tsx, apps/storybook/rtl-audit/targets.json, ] modules: [] families: [family:navigation-destinations] design_specs: [design:reduced-motion] architecture: [ architecture:interaction-modality, architecture:public-component-api, architecture:component-theming-surface, ] contributing: []
system_specs: [spec:AST-085]
TopNavItem component contract
Contract at a glance
| Area | Contract |
|---|---|
| Public contract | TopNavItem with label, href, target, as, isSelected, isDisabled, isIconOnly, icon, children, and size; target top-nav-item with mode and selected states. |
| Behavior | A link in the TopNav bar or drawer. Selected marks the current page; disabled drops the destination; in the drawer, activating it closes the drawer. |
| End-user impact | Users see and hear which destination is current; a disabled item cannot navigate by any input; drawer users return to the page after choosing a destination. |
| Builder impact | None. |
| Compatibility/readiness | Records shipped behavior; no prop, default, target, or export changes. Two implementation gaps (see Current-state impact). |
| Review checks | Reject a disabled item that keeps an href or fires onClick, a selected item without aria-current="page", an icon-only item without an accessible name, or a drawer item that leaves the drawer open after navigating. |
| Governing rules | component:TopNav render modes; spec:AST-085 (disabled items); architecture:interaction-modality (shared focus indicator); architecture:component-theming-surface. |
This table is a review projection; the body below is authoritative.
Intent
TopNavItem is one destination link inside TopNav. It owns the link's selected,
disabled, and icon-only states and its rendering in the bar and in the mobile
drawer. Consumer usage lives in TopNavItem.doc.mjs.
Compatibility and migration
- Released default preserved:
yes - Compatibility class: records shipped behavior; no public change
- Controlled/uncontrolled behavior: not applicable; selection is caller-owned
- Migration decision: none
Consumer migration instructions belong in consumer docs and release notes.
Current-state impact
- Caller props can replace item state. Other DOM props spread onto the link
after
aria-current,aria-disabled, andtabIndex, so a caller value replaces them; a calleraria-disabledcan hide a disabled item's state.architecture:public-component-apiINV5 keeps component-owned accessibility from being overwritten by accident. - Color transition under reduced motion. The bar link's background and text
color still animate when reduced motion is requested;
design:reduced-motionDR3 allows no animated property for a fine pointer.
Ownership boundary
Owns
- The link element, its selected, disabled, and icon-only states, and its bar and drawer renderings (FR1–FR7).
Does not own / non-goals
- Destination acceptance and blocking for every
hrefthis component renders — owned byfamily:navigation-destinations. - Which item is selected — owned by the caller.
- The bar's slots and render mode — owned by
component:TopNavandcomponent:AppShell. - Router link rendering — owned by
LinkProviderand theascomponent.
Public concepts
| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
|---|---|---|---|---|---|---|---|
| Selected | true, false |
The item is the current page. | All modes. | false |
component:TopNavItem |
Stable | Not applicable. |
| Disabled | true, false |
The item cannot navigate. | All modes. | false |
component:TopNavItem |
Stable | Not applicable. |
| Icon only | true, false |
Hides the visible text; label names the link. |
All modes. | false |
component:TopNavItem |
Stable | Without icon the link is empty. |
| Size | sm, md, lg |
Drawer row height and padding. | Drawer mode only; no effect in the bar. | md |
component:TopNavItem |
Stable | TypeScript rejects other values. |
Behavioral and layout contract
| ID | Invariant | Basis |
|---|---|---|
| FR1 | An enabled item renders the as component, else the LinkProvider link component, else <a>, with href and target, the forwarded ref, and other DOM props. It shows icon, then children if given, else label. |
Current source and tests |
| FR2 | isSelected sets aria-current="page" and the selected treatment; the selected fill stays under hover and touch press with no overlay. |
Current source and tests |
| FR3 | isDisabled renders a plain <a> with no href and no target and aria-disabled="true", and suppresses clicks, so no input can navigate or fire onClick. A disabled item MUST keep the tab stop it has when enabled (spec:AST-085 FR1). |
Current source and tests |
| FR4 | isIconOnly hides the text and sets aria-label to label. |
Current source and tests |
| FR5 | In default and mobile-bar modes the item is a horizontal bar link with top-nav-item. In drawer mode it is a full-width row sized by size, carries data-mode="drawer", and on activation calls onClick and then closes the AppShell drawer. |
Current source and tests |
| FR6 | Both renderings paint the shared focus outline on keyboard focus and use the shared press feedback. | Current source |
| FR7 | className, style, and xstyle merge after component styles. |
Current source |
Allowed variation
- AV1 — Theme styling. Themes may restyle
top-nav-itemper mode and selected state.
Representative states
| State | Required invariant | Allowed variation |
|---|---|---|
| Rest | Link with label. | Theme styling. |
| Selected | aria-current="page"; selected fill. |
Fill color. |
| Disabled | No href, no click; keeps its tab stop. |
Muted styling. |
| Icon only | aria-label from label; no visible text. |
Icon. |
| Drawer | Full-width row; activation closes the drawer. | Row size. |
Transformation and precedence order
- ORD1 — Root element. Disabled
<a>, thenas, thenLinkProvider, then<a>. - ORD2 — Content.
children, thenlabel.
Performance and resources
- No resource rule.
Accessibility contract
- AR1 — Current page. The selected item exposes
aria-current="page". - AR2 — Disabled. A disabled item is exposed as disabled and keeps its tab
stop (
spec:AST-085FR1, FR5). - AR3 — Name. An icon-only item is named by
label.
Design relationships
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|---|---|---|---|---|
| Link | Label with optional leading icon. | Current source and public docs | Prominent | FR1, FR4 |
| Selected state | Neutral fill and stronger text. | Current source | Prominent | FR2 |
TopNavItem.doc.mjs declares no anatomy of its own, so no anatomy-theming map
is recorded.
Family and system relationships
family:navigation-destinationsowns the accept/block decision for each destination this component renders.component:TopNavsupplies the render mode;component:AppShellsupplies the drawer close action.architecture:interaction-modalityprovides the shared focus indicator.
Verification map
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
|---|---|---|---|---|
| FR1, ORD1 | TopNav.test.tsx TopNavItem anchor, as, LinkProvider tests |
Default, as, provider |
Wrong element or lost precedence fails. | audit:TopNavItem/behavior |
| FR2–FR4, AR1–AR3 | TopNav.test.tsx TopNavItem state tests |
Selected, disabled, icon only | Missing attribute or a navigating disabled item fails. | audit:TopNavItem/accessibility |
| FR5 | TopNav.test.tsx disabled-navigation tests in both modes |
Default and drawer | Lost click forwarding or href handling fails. | audit:TopNavItem/behavior |
| RTL relation (FR1) | RTL audit curated D2 target (apps/storybook/rtl-audit/targets.json) on TopNav / Full example |
The Dashboard item's leading icon; LTR and RTL |
A leading icon that is not at the inline start of its item fails D2. | audit:TopNavItem/i18n-rtl |
Read from source, with no focused test yet: the disabled plain <a> taking precedence over as and LinkProvider (ORD1, FR3); other DOM props reaching the link (FR1); the top-nav-item target and its mode and selected states (FR5); the selected fill under hover and press (FR2); the drawer row size, data-mode="drawer", and closing the drawer on activation (FR5); FR6; and FR7.
Decision log
No component-local decision is recorded.
Open questions
None.
Content boundary
This file does not duplicate consumer prop tables or examples. It links to their owners.