An open source design system that's fully customizable and agent ready
schema_version: 3 template_version: 7 kind: component id: component:SideNavHeading 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/SideNav/SideNav.test.tsx, apps/storybook/stories/SideNav.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: []
SideNavHeading component contract
Contract at a glance
| Area | Contract |
|---|---|
| Public contract | SideNavHeading with icon, heading, superheading, subheading, their *Href links, headerEndContent, menu, and as; target side-nav-heading. |
| Behavior | The product identity block at the top of SideNav. Which parts are links and which part opens the menu follows from the *Href props and menu; in a collapsed rail it is an icon-only link, menu button, or icon with a tooltip. |
| End-user impact | Users reach product, suite, and account destinations and a product menu, in both the expanded and the collapsed rail; screen-reader users hear named links, a named trigger, 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. Seven implementation gaps (see Current-state impact). |
| Review checks | Reject a collapsed icon without a name, a menu popup wrapped in a modal dialog, a heading button inside role="menu", or headerEndContent rendered inside the whole-heading link. |
| Governing rules | architecture:public-component-api INV5; architecture:interaction-modality; family:navigation-destinations. |
This table is a review projection; the body below is authoritative.
Intent
SideNavHeading presents the product's icon and name, with optional suite and
account lines, at the top of SideNav. It owns how those parts become links or a
menu trigger, the product menu popover, and the collapsed-rail form. Consumer
usage lives in SideNavHeading.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.
Some configurations drop DOM props. Other DOM props passed to SideNavHeading (beyond
data-testid,className,style,xstyle, andref) reach no element in the menu configurations and in the collapsed link and menu-button forms.architecture:public-component-apiINV5 requires accepted DOM, data, ARIA, and event inputs to reach the owning element.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 expanded 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 icon and text that stay mounted in the rail's block, so that content renders twice.
architecture:component-style-authoringINV7 has content render once.Links in the links-plus-trigger form also open the menu. The block that holds the links carries the menu's trigger handlers. With touch or the keyboard, activating the heading or suite link both navigates and opens the menu, moving focus to its first item. With a mouse, moving the pointer onto the block opens the menu at once over it, so a click lands on the menu's heading button, with its repeated links, rather than on the link underneath. Both break FR2's split between the links and the menu trigger.
End content also opens the menu. In both menu configurations
headerEndContentrenders inside the block that carries the menu's trigger handlers. With touch or the keyboard, activating a control there runs that control and also opens the menu, moving focus to its first item. With a mouse, moving the pointer onto the links or end content opens the menu at once over the whole block, so a click on end content lands on the menu's heading button and the menu reopens under the pointer. A control in end content is the caller's, outside FR2's trigger area.
Ownership boundary
Owns
- The identity block and its link and trigger configurations (FR1–FR4, FR11).
- The product menu popover (FR5–FR7).
- The collapsed-rail form (FR8) and the focus outline (FR9).
Does not own / non-goals
- Destination acceptance and blocking — owned by
family:navigation-destinations. - Menu content — owned by the caller (typically NavHeadingMenu).
- The rail's collapsed state — owned by SideNav.
Public concepts
| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
|---|---|---|---|---|---|---|---|
| Configuration | plain, whole link, whole link with end content, independent links, whole trigger, links plus trigger | Derived from the *Href props and menu (FR2). |
Expanded rail. | Plain | component:SideNavHeading |
Stable | Not applicable. |
Behavioral and layout contract
| ID | Invariant | Basis |
|---|---|---|
| FR1 | In an expanded rail the block carries side-nav-heading and shows the icon, 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. With menu, the heading row holds the heading then the chevron button; without menu there is no chevron. |
Current source and tests |
| FR2 | headingHref alone without menu makes the icon and text one link; with headerEndContent that content sits beside the link, not inside it. Other *Href props without menu make each line with an href its own link, and a linked icon is named by heading. menu without hrefs makes the whole block, apart from headerEndContent, open the menu; menu with hrefs makes each line with an href its own link, and the chevron button and the rest of the block, apart from headerEndContent, open the menu. |
Current source and tests |
| FR3 | The icon link, the whole-heading 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 | The chevron button is named by @astryx.sideNav.heading.openMenu and is the popover's trigger. |
Current source and tests |
| FR5 | On a hover-capable pointer, a first hover-open 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 opens it and moves focus to the first menu item; a click within 500 ms of a hover-open keeps it open; Escape closes it and returns focus to the trigger. |
Cindy, 2026-11-06 |
| FR6 | The menu is a non-modal popover below the block, aligned to its start; in the expanded rail it overlaps the block. It contains a heading button that closes the menu (see Current-state impact for its content), then a role="menu" named by heading that holds menu. |
Current source and tests |
| FR7 | Only the collapsed menu form gives menu descendants the close action NavMenu items call on selection; the expanded menu forms do not. |
Current source |
| FR8 | In a collapsed rail, without icon it renders nothing. With icon: headingHref makes an icon-only link named by heading; else menu makes an icon-only button named by heading that is the native invoker of its menu popover; else the icon renders alone. Each form shows a tooltip with heading at the inline end; headerEndContent and the chevron are hidden. |
Current source and tests |
| FR9 | Every focusable part paints the shared focus outline. | Current source and tests |
| 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, 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.sideNav.heading.openMenu, that takes heading: "Acme, Open menu" in English for the heading "Acme". Every shipped locale's message carries {heading} unchanged. |
Current source and tests |
Allowed variation
- AV1 — Lines. Any combination of lines may be present; the block keeps its order.
Representative states
| State | Required invariant | Allowed variation |
|---|---|---|
| Whole link with end content | End content beside the link. | — |
| Menu, no hrefs | Whole block triggers; named chevron button. | Menu content. |
| Menu with hrefs | Links; chevron and the rest of the block trigger. | — |
| Collapsed with menu | Named icon button; flyout menu; tooltip. | — |
| Collapsed without icon | Nothing renders. | — |
Transformation and precedence order
- ORD1 — Collapsed form.
headingHref, thenmenu, then plain icon.
Performance and resources
- No resource rule.
Accessibility contract
- AR1 — Named icons. A linked or button icon without visible text is named
by
heading. - AR2 — Menu semantics. The popup is not a modal dialog;
role="menu"wraps only the menu content.
Design relationships
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|---|---|---|---|---|
| Icon | Leading product mark; alone when collapsed. | Current source and public docs | Prominent | FR1, FR8 |
| Heading lines | Superheading, heading, subheading. | Current source and public docs | Prominent | FR1 |
| Menu popover | Overlaps the block; a heading button closes it. | Current source | Supporting | FR6 |
SideNavHeading.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 eachhref.- NavHeadingMenu items close this menu where the close action is provided (FR7).
Verification map
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
|---|---|---|---|---|
| FR1–FR4, AR1 | SideNav.test.tsx SideNavHeading and headerEndContent suites |
Each configuration | Wrong element, unnamed link, or misplaced end content fails. | audit:SideNavHeading/behavior |
| FR5 | SideNav.test.tsx SideNavHeading hover/click guard suite. Evidence gap: no test of the first-open delay or the hand-off |
Hover, click, late click, Escape | Lost guard or focus return fails. | audit:SideNavHeading/behavior |
| FR6, AR2 | SideNav.test.tsx menu popover semantics suite |
Whole trigger; mixed; collapsed | A dialog wrapper or misplaced menu role fails. | audit:SideNavHeading/accessibility |
| FR8 | SideNav.test.tsx SideNavHeading collapsed suite |
Link, menu, plain, no icon | Missing name, tooltip, or invoker fails. | audit:SideNavHeading/behavior |
| FR9 | SideNav.test.tsx focus ring suite |
Whole-heading link, collapsed link, menu trigger | A missing shared ring class fails. | audit:SideNavHeading/accessibility |
| FR10 | SideNav.test.tsx SideNavHeading menu-popover suite (touch and mouse slides) |
Touch and mouse slides across items; a caller button and link; a release outside | Removing the adoption fails the slide tests. | — |
| FR11 | SideNav.test.tsx SideNavHeading cases "includes the visible heading in the menu trigger name without hrefs", "includes the heading in the translated menu trigger name" (Korean catalog), and "renders chevron as separate trigger when menu and hrefs are provided" |
Whole trigger; links plus trigger; a translated locale | A name without the heading, or a translated name that drops it, fails. | audit:SideNavHeading/accessibility |
| RTL relation | RTL audit curated D2 and D8 targets (apps/storybook/rtl-audit/targets.json) on SideNav / Default |
Heading icon and title, with 0px start and 8px end padding; LTR and RTL | An icon 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:SideNavHeading/i18n-rtl |
Read from source, with no focused test yet:
- FR1: the forwarded
ref, theside-nav-headingtarget, the order of parts, and one-line truncation. - FR2: that the rest of the block opens the menu in the links-plus-trigger configuration.
- FR3:
ason the icon and menu-configuration heading links, and the Link component for the other lines. - FR5: the click guard, Escape, and focus return. Its first-open delay is an implementation gap.
- FR6: the popover's placement and the menu's name.
- FR7; FR8's tooltip placement at the inline end; and FR9 on the popover's heading button and the linked icon.
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.