An open source design system that's fully customizable and agent ready
schema_version: 3 template_version: 7 kind: component id: component:MobileNav authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-10-26 owners: [cixzhang] review_triggers: [behavior, theming, accessibility] verified_by: [ packages/core/src/MobileNav/MobileNav.test.tsx, packages/core/src/MobileNav/MobileNavToggle.test.tsx, packages/core/src/MobileNav/MobileNavFocus.test.tsx, packages/core/src/MobileNav/MobileNavCloseEdgeCases.test.tsx, packages/core/src/MobileNav/MobileNavCloseVisibility.test.tsx, packages/core/src/MobileNav/MobileNavCloseTiming.test.ts, packages/core/src/MobileNav/MobileNavEntryAnimation.test.tsx, packages/core/src/MobileNav/MobileNavReopen.test.tsx, packages/core/src/MobileNav/MobileNavScrollbarGutter.test.tsx, packages/core/src/MobileNav/MobileNavPinchZoom.a11y.chromium.spec.ts, packages/core/src/Layer/layerDismissalFamilies.test.tsx, packages/core/src/MobileNav/tests/MobileNavWidth.a11y.chromium.spec.ts, packages/core/src/MobileNav/tests/MobileNavTouchPresentation.a11y.chromium.spec.ts, packages/core/src/theme/themingTargets.test.ts, scripts/check-knowledge.mjs, apps/storybook/rtl-audit/targets.json, packages/core/src/tests/modalBackdrop.test.tsx, packages/core/src/tests/ModalBackdrop.a11y.browser.spec.ts, ] modules: [] families: [family:overlay-dismissal] design_specs: [design:bidirectionality, design:reduced-motion] architecture: [ architecture:component-theming-surface, architecture:layer-runtime, architecture:public-component-api, ] contributing: []
system_specs: [spec:AST-094/FR13, spec:AST-094/FR35]
MobileNav component contract
Contract at a glance
| Area | Contract |
|---|---|
| Public contract | MobileNav with isOpen, onOpenChange, header, width (320), side (start, end, auto; default auto), label, and children; target mobile-nav with a side state; MobileNavToggle with label and children. |
| Behavior | A modal native dialog with a drawer that slides in from one inline edge, a header with a Close button, and a scrolling content region. Escape, the backdrop, and Close request closing; the dialog stays open while the drawer starts sliding out and closes within the slide-out (FR5), then focus returns to the opener. |
| End-user impact | Phone users open navigation in a drawer that contains focus, lock the page behind it, close it any usual way, and land back on the control that opened it. |
| Builder impact | None. |
| Compatibility/readiness | Records shipped behavior; no public change. Six implementation gaps: automatic side selection uses physical position, reduced motion still animates, its own top layer, close hold, and backdrop, a caller id disconnects the Toggle, and a caller aria-label and onCancel are dropped (see Current-state impact). |
| Review checks | Reject a non-modal drawer, a close that hides the drawer before its slide-out runs, focus not returned to a connected opener, a backdrop click inside the drawer that closes it, or a Toggle rendered outside an enabled AppShell mobile layout. |
| Governing rules | family:overlay-dismissal; architecture:layer-runtime INV14; component:AppShell FR10–FR13; design:bidirectionality DR7; design:reduced-motion DR1–DR3; architecture:public-component-api INV5, INV7; architecture:component-theming-surface. |
This table is a review projection; the body below is authoritative.
Intent
MobileNav presents mobile navigation in a modal drawer and exports an
AppShell-aware Toggle button for opening and closing it. It owns the drawer's
dialog, placement, motion, close timing, focus return, page scroll lock, and the
Toggle's link to the drawer. Consumer usage lives in MobileNav.doc.mjs.
Compatibility and migration
- Released default preserved:
yes - Compatibility class: records shipped behavior; runtime, DOM, styling, targets, aliases, and public API remain unchanged
- Controlled/uncontrolled behavior:
isOpenandonOpenChangecontrol the drawer; without them it follows the enclosing AppShell's drawer state (FR2) - Migration decision: none
Consumer migration instructions belong in consumer docs and release notes.
Current-state impact
- Automatic side follows physical position. With
side="auto", a trigger whose center is in the left half of the viewport opens the drawer at the inline start, otherwise at the inline end. In a right-to-left layout the inline start is the right edge, so every trigger opens the drawer on the far side.design:bidirectionalityDR7 requires a layered surface to keep its start and end relationship to its trigger. - A caller
iddisconnects the Toggle. A calleridprop, evenundefined, replaces the drawer id on the dialog, so inside AppShell the Toggle'saria-controlsnames no element, breakingcomponent:AppShellFR13 and AR3.architecture:public-component-apiINV5 keeps component-owned accessibility from being overwritten by accident. - A caller
aria-labelis dropped. MobileNav's own name (FR10) replaces a calleraria-labelon the dialog.architecture:public-component-apiINV5 has supported ARIA inputs reach the element. - A caller
onCancelnever runs. MobileNav's own cancel handler replaces a calleronCancelon the dialog.architecture:public-component-apiINV5 and INV7 have supported event inputs reach the element and compose. - MobileNav builds its own top layer, close hold, and backdrop. MobileNav
calls
showModal()itself, keeps the dialog open through its close with its own timer, and paints its own backdrop fade.architecture:layer-runtimeINV14 has a layer use the runtime's top-layer mounting, presentation hold, and backdrop tint rather than building its own. - Motion under reduced motion. Under reduced motion the Drawer's slide and
the backdrop's fade still run, for 0.01 s, rather than changing at once for a
fine pointer or cross-fading for touch.
design:reduced-motionDR2 and DR3 allow no travel and, for a fine pointer, no animated property.
Ownership boundary
Owns
- The Navigation overlay and its current
mobile-navtarget. - Drawer placement and motion, the stable Header and Content regions, and the connection between AppShell state, MobileNav, and MobileNavToggle (FR1–FR12).
- The backdrop's appearance (FR13).
- The drawer's navigation landmark (FR14).
- Canonical anatomy for both exported components.
component:MobileNavis the parent owner; MobileNavToggle has no consumer doc of its own and no separate component contract.
Does not own / non-goals
- The Close and Toggle button surfaces — delegated to
component:Button. - Header or navigation content supplied by the caller.
- A public target for the painted Drawer, Header, or Content region; none exists.
- AppShell responsive policy, when the drawer renders, and its close hold —
owned by
component:AppShell. - Shared Escape and close-request ordering — owned by
family:overlay-dismissal; shared layer hosting — owned byarchitecture:layer-runtime.
Public concepts
| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
|---|---|---|---|---|---|---|---|
| Side | start, end, auto |
The inline edge the drawer enters from; auto picks from the opener's position. |
Every open. | auto |
component:MobileNav |
Stable | TypeScript rejects other values. |
Behavioral and layout contract
| ID | Invariant | Basis |
|---|---|---|
| FR1 | MobileNav renders one native <dialog> Navigation overlay containing a Drawer with a stable Header, Close button, and scrollable Content region. The overlay carries mobile-nav with the resolved side; Drawer, Header, and Content carry no MobileNav public target. |
Current source, docs, and tests |
| FR2 | isOpen and onOpenChange win when given; otherwise the drawer reads and changes the enclosing AppShell's drawer state. The dialog uses AppShell's drawer id when there is one, else its own; a caller id replaces either (Current-state impact). |
Current source and tests |
| FR3 | Opening calls showModal(), and records the focused element as the opener; where focus lands inside the open drawer is uncontracted here. While open, the page's scroller clips its overflow and keeps its scrollbar gutter: the root, or <body> when <body> sets its own overflow and the root's stays visible. Pull-to-refresh and the page's bounce stop, because a scroll lock under a modal holds the page (spec:AST-094 FR19). Closing releases all three. |
Current source and tests |
| FR4 | The native cancel request (Escape) is routed through the shared dismissal stack and requests close only when this drawer is topmost. A click on the overlay outside the Drawer requests close; a click inside does not. The Close button, named by @astryx.mobileNav.closeNavigation, requests close. A caller onClick on the dialog runs before the backdrop check; one that calls preventDefault() cancels that backdrop close. |
Current source and tests |
| FR5 | After a close request the drawer slides out while the dialog stays open, and the dialog closes within its slide-out transition and no later than 250 ms after the request (on the next task, never in the commit that requests it, under reduced motion or a zero-length transition). Reopening before then cancels the close. Unmounting closes the dialog. After the dialog closes, the rest of the slide-out is inert. | Current source and tests |
| FR6 | When the dialog closes, focus returns to the recorded opener if it is still connected and was not the document body; otherwise focus is left alone. A reopen that interrupted a close keeps the original opener. | Current source and tests |
| FR7 | The Drawer enters from its resolved inline edge, from off-screen to on-screen, and the backdrop fades in from transparent, without a reduced-motion preference. Under reduced motion, motion follows design:reduced-motion DR1–DR3 (Current-state impact records today's shortfall). The overlay clips the off-screen drawer without becoming a scroll container and allows pinch zoom. |
Current source and tests |
| FR8 | side="start" or "end" sets the edge. side="auto" MUST keep the drawer's start and end relationship to the element that opened it (design:bidirectionality DR7). Implementation gap: it resolves on each open from the focused element's physical half of the viewport (left half picks start, otherwise end); when nothing is focused at open it keeps its last value, and before any open it is end. |
Current source |
| FR9 | The Drawer is width px wide (default 320), never wider than 85% of the viewport, so a strip of the page stays beside it. |
Current source and tests |
| FR10 | The dialog is named by label, else a string header, else @astryx.mobileNav.navigation; a caller aria-labelledby outranks all three. A string header renders as a level-2 heading; other header content renders as given. |
Current source and tests |
| FR11 | MobileNavToggle renders only while AppShell reports its mobile layout with mobile navigation enabled. It is an icon-only ghost Button named by default by @astryx.mobileNav.toggle.open, with a menu icon unless children replace it; it toggles the drawer, exposes aria-expanded, and its aria-controls carries AppShell's drawer id, which a MobileNav inside that AppShell applies to its dialog unless a caller id replaces it. |
Current source, docs, and tests |
| FR12 | MobileNav forwards its ref, data-testid, other DOM props, className, style, and xstyle to the dialog, except that its own aria-label (FR10) replaces a caller's (Current-state impact), a caller onCancel never runs (Current-state impact), and a caller id replaces its id (FR2). |
Current source and tests |
| FR13 | MobileNav's backdrop is the theme's --color-overlay dim with no blur, on every pointer; under forced colors the drawer keeps a visible edge. |
Owner decision, 2026-10-25: the overlay stays theme-controlled and unblurred on every pointer. |
| FR14 | The Content region is a navigation landmark named like the dialog (FR10), so a person who moves by landmarks finds the drawer's links on a phone as they find SideNav's on a wide screen. Whatever fills it, SideNav items or a TopNav's drawer content, sits inside that one landmark. | Owner decision DEC-1 |
Allowed variation
- AV1 — Drawer edge. The Drawer may resolve to logical start or end through the explicit or trigger-derived side behavior.
- AV2 — Header content. Header may contain a string rendered through Heading, caller-provided content, or only the Close button.
- AV3 — Navigation content. Caller-provided navigation content may vary without becoming MobileNav-owned anatomy.
- AV4 — Toggle presence. Toggle button is absent outside an enabled AppShell mobile context.
Representative states
| State | Required invariant | Allowed variation |
|---|---|---|
| Standalone drawer | Navigation overlay contains Drawer, Header, Close button, and Content. | Caller controls open state and may choose an edge. |
| AppShell drawer | The same drawer anatomy consumes AppShell mobile state. | Header and navigation content remain caller-owned. |
| AppShell mobile toggle | Toggle button controls and references the current drawer. | Custom button content may replace the menu glyph. |
| Non-mobile/disabled host | Toggle button does not render. | MobileNav remains owned by the parent contract. |
| Closing | Dialog stays open while the drawer starts sliding out and closes within the slide-out (FR5); then focus returns. | Duration by theme. |
| Reopen mid-close | Pending close is cancelled; focus stays in the drawer. | — |
Transformation and precedence order
- ORD1 — Open state.
isOpen, then AppShell's drawer state. - ORD2 — Name. A caller
aria-labelledby, thenlabel, then stringheader, then the translated default. - ORD3 — Close delay. Bounded by the dialog's slide-out transition and by 250 ms; the next task under reduced motion or a zero-length transition.
Performance and resources
- PR1 — Cleanup. A pending close timer clears on reopen and unmount, and the page scroller's clip, the overscroll stop and the scrollbar gutter are released on close and unmount.
Accessibility contract
- AR1 — Modal dialog. The open drawer is a modal native dialog with an accessible name (FR3, FR10); the page behind it is inert.
- AR2 — Focus return. FR6.
- AR3 — Toggle wiring. FR11's
aria-expandedandaria-controls. - AR4 — Zoom. Pinch zoom stays available while the drawer is open.
- AR5 — Navigation landmark. FR14.
Design relationships
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|---|---|---|---|---|
| Navigation overlay | Hosts the modal navigation layer and its backdrop. | Current source and public docs | Supporting | FR1, FR4, FR13 |
| Drawer | Paints the sliding mobile navigation surface. | Current source and public docs | Prominent | FR1, FR7–FR9 |
| Header | Arranges optional header content with the persistent Close button. | Current source and public docs | Supporting | FR1, FR10 |
| Content | Provides the scrolling region for caller-supplied navigation content. | Current source and public docs | Prominent | FR1 |
| Close button | Dismisses the current drawer. | component:Button |
Supporting | FR4 |
| Toggle button | Opens or closes the AppShell-owned mobile drawer state. | component:Button |
Supporting | FR11 |
Drawer is the primary painted surface, but the only current MobileNav target is
on the full-viewport dialog overlay. Its none disposition is a factual
reachability gap, not a decision that the Drawer must remain unthemeable. Header
and Content likewise have no current local target. Close and Toggle retain Button
ownership.
Theming anatomy
{
"Navigation overlay": {"target": "mobile-nav"},
"Drawer": {
"none": {
"reason": "reachability-gap: No current public target is applied to the painted drawer panel"
}
},
"Header": {
"none": {
"reason": "reachability-gap: No current public target is applied to the stable header row"
}
},
"Content": {
"none": {
"reason": "reachability-gap: No current public target is applied to the scrollable content region"
}
},
"Close button": {
"delegatesTo": {"owner": "component:Button", "target": "button"}
},
"Toggle button": {
"delegatesTo": {"owner": "component:Button", "target": "button"}
}
}
Family and system relationships
architecture:component-theming-surfaceowns anatomy qualification, target mapping, delegation, and factualnonedispositions.architecture:layer-runtimeINV14 gives the runtime top-layer mounting, close-request delivery, the presentation hold, the shared exit copy, and the backdrop tint; MobileNav decides when it dismisses and how it is presented, including its drawer motion and the backdrop's color (Current-state impact records today's shortfall).design:reduced-motionDR1–DR3 govern the drawer's motion under reduced motion;architecture:public-component-apiINV5 and INV7 govern the calleridandonCancelgaps.family:overlay-dismissalowns shared Escape and platform-close ordering and records MobileNav as an adopter.component:AppShelldecides when the drawer renders and holds it visible through a close.design:bidirectionalityDR7 governs the automatic-side gap.
Verification map
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
|---|---|---|---|---|
| FR1, FR2, FR10, FR12 | MobileNav.test.tsx |
Open and closed; string and no header; caller id on a standalone drawer |
Losing the dialog, name, Close, or forwarded props fails. | audit:MobileNav/anatomy |
| FR2, FR3, FR4 | MobileNav.test.tsx; MobileNavCloseEdgeCases.test.tsx; MobileNavScrollbarGutter.test.tsx; MobileNavRootScrollClaim.test.tsx |
Escape, backdrop, content click, Close | A wrong close source or a lingering scroll lock fails. | audit:MobileNav/behavior |
| FR4 | layerDismissalFamilies.test.tsx MobileNav cases |
Escape over a required Dialog; cancel while topmost and while not | Closing when not topmost, or not closing when topmost, fails. | audit:MobileNav/behavior |
| FR5, ORD3 | MobileNavCloseVisibility.test.tsx; MobileNavCloseEdgeCases.test.tsx; MobileNavCloseTiming.test.ts |
Close, reduced motion, reopen, unmount, the 250 ms bound | Closing before the slide-out or a stuck dialog fails. | audit:MobileNav/behavior |
| FR5 | MobileNavTouchPresentation.a11y.chromium.spec.ts (the slide-out after the close) |
Closed dialog, drawer still sliding out; open drawer | A tap on the leaving drawer reaching it, or the browser's accessibility tree exposing the dialog or its links after the close, fails. | audit:MobileNav/behavior |
| FR6, AR2 | MobileNavFocus.test.tsx |
Standalone, AppShell, Escape, removed opener | Focus not returned, or returned too early, fails. | audit:MobileNav/accessibility |
| FR7 | MobileNavEntryAnimation.test.tsx |
Start and end edges | Missing starting style or a scroll-container overlay fails. | audit:MobileNav/behavior |
| FR11, AR3 | MobileNavToggle.test.tsx; MobileNavReopen.test.tsx |
Closed, open, reopen | Broken expanded state or id link fails. | audit:MobileNav/accessibility |
| AR4 | MobileNavPinchZoom.a11y.chromium.spec.ts |
Open drawer on a touch viewport | Pinch zoom blocked fails. | audit:MobileNav/accessibility |
| FR9 | MobileNav.test.tsx drawer cap test; MobileNavWidth.a11y.chromium.spec.ts |
Default and wide width on a narrow viewport |
A drawer wider than 85% of the viewport fails. | audit:MobileNav/behavior |
| FR14 | Chromium accessibility-tree check of the open drawer with SideNav items and with a TopNav's drawer content | Drawer from SideNav's drawer mode and from a TopNav's drawer | The tree shows no navigation landmark, an unnamed one, a name other than the dialog's, or two nested ones (spec:AST-009 FR3: computed role and name need accessibility-tree evidence) |
audit:MobileNav/accessibility |
| Theming anatomy map | scripts/check-knowledge.mjs; themingTargets.test.ts |
Canonical parent anatomy and current target | Missing, extra, prefixed, stale, or multiply assigned mappings fail repository validation. | audit:MobileNav/theming |
| RTL relation | RTL audit curated D4 target (apps/storybook/rtl-audit/targets.json) on MobileNav / Default (drawer opened) |
The open drawer; LTR and RTL | A drawer that does not move to the mirrored side of the page in RTL fails D4. Evidence gap: the story centres its opener, so the documented side="auto" far-side RTL drawer (FR8) is not observed. |
audit:MobileNav/i18n-rtl |
| FR13 | modalBackdrop.test.tsx; ModalBackdrop.a11y.browser.spec.ts in Chromium and WebKit |
A finger at phone width; a mouse at desktop width; forced colors under either pointer | A backdrop-filter on the backdrop at either width, or no visible edge in forced colors, fails. |
audit:MobileNav/theming |
Read from source, with no focused test yet:
- FR1: the distinct Drawer, Header, and Content elements, and the
mobile-navtarget with itssidestate. - FR2 and FR11: the dialog's own id outside AppShell, and a caller
idreplacing AppShell's drawer id inside AppShell. - FR4: the caller
onClickrunning before the backdrop check, and itspreventDefault()cancellation. - FR8's shipped resolution.
- FR10 and ORD2: the
labelprop, a calleraria-labelledbyoutranking the name, the level-2 heading for a stringheader, and other header content rendering as given. - FR11: rendering only in an enabled AppShell mobile layout, the icon-only
ghost Button, a Toggle
labelreplacing the default name, the menu icon, andchildrenreplacing it. - FR12: the forwarded
refandxstyle, and the replaced calleraria-labelandonCancel.
Decision log
DEC-1 — The drawer's links sit in a navigation landmark
Reference: component:MobileNav/DEC-1
Decider: cixzhang, pending owner review
A phone user who moves by landmarks finds the navigation in the drawer, as a desktop user finds SideNav's. The drawer is a modal dialog, which is not a landmark, so its Content region carries the landmark and takes the dialog's name. One landmark covers whatever fills the drawer.
Rejected: leaving the drawer without a landmark, so landmark navigation on a phone finds no navigation at all.
Open questions
- OQ1 — Should Drawer gain a stable public theming target? (
human-api) The current target reaches the Navigation overlay rather than the primary painted drawer surface; this is an audit gap, not settled intent.
Content boundary
This file does not duplicate consumer prop tables/examples, AppShell responsive policy, shared layer rules, current audit results, or implementation steps. It links to their owners.