An open source design system that's fully customizable and agent ready
schema_version: 3 template_version: 7 kind: component id: component:TopNavHeading 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, family:overlay-dismissal, family:action-groups, ] design_specs: [] architecture: [ architecture:component-style-authoring, architecture:interaction-modality, architecture:public-component-api, architecture:component-theming-surface, ] contributing: []
system_specs: []
TopNavHeading component contract
Contract at a glance
| Area | Contract |
|---|---|
| Public contract | TopNavHeading with logo, logoLabel, heading, superheading, subheading, their *Href links, headerEndContent, menu, and as; target top-nav-heading. |
| Behavior | The product identity block. Which parts are links and which part opens the menu follows from which *Href props and menu are set (FR2). |
| End-user impact | Users reach product, suite, and account destinations and a product switcher menu; screen-reader users hear a named logo link and a named menu. |
| Builder impact | None. |
| Compatibility/readiness | Shipping FR5 delays the first hover-open for mouse and pen users; no public API change. Six implementation gaps (see Current-state impact). |
| Review checks | Reject a logo link without an accessible name, a menu popup wrapped in a modal dialog, or a heading button placed inside role="menu". |
| Governing rules | architecture:public-component-api INV5; architecture:interaction-modality (shared focus indicator); architecture:component-theming-surface. |
This table is a review projection; the body below is authoritative.
Intent
TopNavHeading presents the product's logo and name, with optional suite and
account lines, in the TopNav heading slot. It owns how those parts become links
or a menu trigger and the product menu popover. Consumer usage lives in
TopNavHeading.doc.mjs.
Compatibility and migration
- Released default preserved:
no; shipping FR5 delays the first hover-open for mouse and pen users - Compatibility class: records shipped behavior except FR5's first-open delay; no public API change
- Controlled/uncontrolled behavior: the menu's open state is internal
- Migration decision: none
Consumer migration instructions belong in consumer docs and release notes.
Current-state impact
Heading menu entry delay (FR5). The menu opens on the first hover with no entry delay. FR5 requires the shared delay, with no wait only for a hand-off from another open menu in the same navigation.
Menu configurations drop DOM props. When
menuis set, other DOM props passed to TopNavHeading (beyonddata-testid,className,style,xstyle, andref) do not reach any element.architecture:public-component-apiINV5 requires accepted DOM, data, ARIA, and event inputs to reach the owning element.Browser default focus rings. The chevron menu button, the whole-heading link, the linked logo, the logo-only link, the menu-configuration heading link, and the popover's heading button do not use the shared focus outline; keyboard focus on them paints the browser's default ring.
architecture:interaction-modalityprovides the shared focus indicator these controls bypass.NavHeadingMenu nests a second menu. The heading wraps
menuin its ownrole="menu"; NavHeadingMenu, the documentedmenucontent, adds anotherrole="menu"inside it. WAI-ARIA 1.2 allows amenuto own onlymenuitem-family items and groups.Links nested in the popover's heading button. In the links-plus-trigger configuration, the popover's heading button repeats the superheading, heading, and subheading links inside itself, so interactive content is nested inside a button. HTML forbids interactive content inside a
<button>.The open menu repeats the identity row. While the menu is open, its heading button repeats the logo and text that stay mounted in the bar's block, so that content renders twice.
architecture:component-style-authoringINV7 has content render once.
Ownership boundary
Owns
- The identity block layout and its link and trigger configurations (FR1–FR6, FR11).
- The product menu popover and its close behavior (FR7–FR9).
Does not own / non-goals
- Destination acceptance and blocking for every
hrefthis component renders — owned byfamily:navigation-destinations. - Menu content — owned by the caller; NavHeadingMenu items read the close action this component provides (NavHeadingMenu).
- The logo artwork — owned by the caller, typically NavIcon.
- The TopNav heading slot and mobile-bar placement — owned by
component:TopNav. - Popover positioning and layer hosting — owned by the shared popover and layer runtime.
Public concepts
| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
|---|---|---|---|---|---|---|---|
| Configuration | logo only, plain, whole link, independent links, whole trigger, links plus trigger | Derived from which *Href props and menu are set (FR2). |
All. | Plain | component:TopNavHeading |
Stable | Not applicable. |
Behavioral and layout contract
| ID | Invariant | Basis |
|---|---|---|
| FR1 | The root carries top-nav-heading and shows, in order: the logo, a text column (superheading, a heading row, subheading; plain-text lines and the menu-configuration heading link stay on one line with ellipsis, while lines rendered through the Link component wrap), and headerEndContent at the inline end. With menu, the heading row holds the heading then the chevron button; without menu there is no chevron. When the start region is crowded, a heading text column holding independent links keeps its longest word and wraps, and the row wraps before any link is clipped; a heading with no links still truncates first. The logo never shrinks. |
Current source and tests |
| FR2 | Configuration: no heading and no menu → logo only, a link named by logoLabel when headingHref is set, else a div; headingHref alone without menu → the whole block is one link; other *Href props without menu → each line with an href is its own link and a linked logo is named by logoLabel, else heading; menu without any href → the whole block opens the menu; menu with hrefs → the links stay independent, and the chevron button and the rest of the block open the menu; otherwise a plain div. |
Current source and tests |
| FR3 | The logo link, the whole-heading link, the logo-only link, and the menu-configuration heading link use the as component, else the LinkProvider link, else <a>. Supporting lines, and the heading line in the independent-links configuration, use the Link component, which does not receive as. |
Current source and tests |
| FR4 | In both menu configurations, the chevron is a button named by the translated @astryx.topNav.heading.openMenu that toggles the menu; it is at least 28 by 28 px. |
Current source and tests |
| FR5 | On a hover-capable pointer, a first hover-open of the block waits the menu hover delay (150 ms by default, as in TopNavMenu), and moving to it from another open menu in the same navigation opens it at once (architecture:interaction-modality INV11; owner decision, Nov 6 2026 (Cindy); proposed in design:motion DEC-1). A hover-open does not move focus. A click within 500 ms of a hover-open keeps the menu open and moves focus to the first menu item, and a later click closes it. |
Cindy, 2026-11-06 |
| FR6 | Clicking a link inside a menu configuration navigates without toggling the menu. | Current source |
| FR7 | The menu is a non-modal popover below the block, aligned to its start and overlapping it. It contains a heading button that closes the menu (see Current-state impact for its content), then a role="menu" region named by heading (or @astryx.topNav.heading.dialogLabel) that holds menu. |
Current source and tests |
| FR8 | Escape closes the menu and returns focus to the trigger. | Current source and tests |
| FR9 | Descendants of menu receive a close action, which NavHeadingMenu items call on selection. |
Current source |
| FR10 | In the product menu's role="menu" region, a press (finger, pen or mouse) that lands on an enabled item and slides across the items acts on the one it lifts on, once, through that item's own activation, with the highlight following the pointer; a lift outside acts on nothing, and a mouse released outside closes the menu. The menu adopts module:DropdownMenu/useMenuPress for this (family:action-groups FR1–FR5; module:DropdownMenu/useMenuPress DEC-7). A press on caller content that is not an item, and a Ctrl-, Cmd- or Shift-click or a middle click on a link item, stays that content's or the browser's own, and keyboard and assistive-technology behavior is unchanged. |
Current source and tests |
| FR11 | In both menu configurations, the chevron button's accessible name contains the visible heading when one is set, so a person who identifies the control by the product or workspace name they see hears that name (family:buttons FR1; WCAG 2.2 Label in Name). The name is one translated message, @astryx.topNav.heading.openMenu: "Acme, Open menu" in English for the heading "Acme". With no heading, or an empty one, it is the translated generic action, "Open menu", with no separator. Every shipped locale's message carries {heading} unchanged. |
Current source and tests |
Allowed variation
- AV1 — Logo artwork and lines. Any combination of lines may be present; the block keeps its order.
Representative states
| State | Required invariant | Allowed variation |
|---|---|---|
Heading with headingHref |
One link wrapping logo and text. | — |
| Suite and product links | Independent links; logo link named. | Line content. |
| Menu, no hrefs | Whole block triggers; chevron button named. | Menu content. |
| Menu with hrefs | Links independent; chevron and the rest of the block trigger. | Menu content. |
| Logo only with href | Link named by logoLabel. |
Artwork. |
Transformation and precedence order
- ORD1 — Logo link name.
logoLabel, thenheading.
Performance and resources
- No resource rule.
Accessibility contract
- AR1 — Named links. A linked logo without adjacent link text is named by
logoLabelorheading. - AR2 — Menu semantics. The popup is not a modal dialog;
role="menu"wraps only the menu content, never the popover's heading button. - AR3 — Named trigger. The chevron button has a translated name and exposes the popover's expanded state.
Design relationships
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|---|---|---|---|---|
| Logo | Leading product mark. | Current source and public docs | Prominent | FR1, FR2 |
| Heading lines | Superheading, heading, subheading; plain lines stay on one line (FR1). | Current source and public docs | Prominent | FR1 |
| Menu popover | Overlaps the block; a heading button closes it. | Current source | Supporting | FR7 |
TopNavHeading.doc.mjs declares no anatomy of its own, so no anatomy-theming map
is recorded.
Family and system relationships
family:overlay-dismissalowns Escape and close-request ordering for this component's popover.family:navigation-destinationsowns the accept/block decision for each destination this component renders.component:TopNavplaces the heading in its heading slot and mobile bar.- NavHeadingMenu items close this menu through the provided close action.
architecture:public-component-apiINV5 andarchitecture:interaction-modalitygovern the gaps under Current-state impact.
Verification map
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
|---|---|---|---|---|
| FR1–FR3, AR1 | TopNav.test.tsx TopNavHeading render and logo-name tests |
Each configuration | A wrong element or unnamed logo link fails. | audit:TopNavHeading/behavior |
| FR4, FR7, AR2–AR3 | TopNav.test.tsx menu popover semantics tests |
Whole trigger; links plus trigger | A modal wrapper or misplaced menu role fails. | audit:TopNavHeading/accessibility |
| FR5, FR8 | TopNav.test.tsx hover/click guard tests. Evidence gap: no test of FR5's first-open delay or the hand-off |
Hover-open, click, late click, Escape | Losing the guard or focus return fails. | audit:TopNavHeading/behavior |
| FR10 | TopNav.test.tsx TopNavHeading menu-popover suite (touch and mouse slides) |
Touch and mouse slides across items | Removing the adoption fails the slide tests. | — |
| FR11 | TopNav.test.tsx TopNavHeading cases "includes the visible heading in the menu trigger name without hrefs", "includes the heading in the translated menu trigger name with independent links", and "keeps the translated generic menu trigger name when the optional heading is absent or empty" (Korean catalog) |
Whole trigger; links plus trigger; no heading; empty heading | A name without the heading, a translated name that drops it, or a dangling separator without a heading fails. | audit:TopNavHeading/accessibility |
| RTL relation | RTL audit curated D2 and D8 target (apps/storybook/rtl-audit/targets.json) on TopNav / Full example |
Heading logo and title, with 0px start and 8px end padding; LTR and RTL | A logo that is not at the inline start of the title, or an end padding that stays on the same physical side in RTL, fails D2 or D8. | audit:TopNavHeading/i18n-rtl |
Read from source, with no focused test yet: that clicking the block itself opens the menu in the menu-without-hrefs configuration (FR2); the dialogLabel fallback name of the menu (FR7); that the rest of the block opens the menu in the links-plus-trigger configuration (FR2); the top-nav-heading target (FR1); line truncation, part order, and headerEndContent (FR1); as and LinkProvider rendering (FR3); the chevron button's size (FR4); FR6; the popover's placement (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, or popover mechanics. It links to their owners.