An open source design system that's fully customizable and agent ready
schema_version: 3 template_version: 7 kind: component id: component:Outline authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-10-31 owners: [cixzhang] review_triggers: [public-api, behavior, layout, theming, accessibility, interaction] verified_by: [ packages/core/src/Outline/Outline.test.tsx, packages/core/src/Outline/OutlineFocus.a11y.chromium.spec.ts, packages/core/src/theme/themingTargets.test.ts, .github/visual-baseline/manifest.json, scripts/check-knowledge.mjs, ] modules: [module:Outline/parseOutlineFromMarkdown] families: [] design_specs: [design:reduced-motion] architecture: [ architecture:component-theming-surface, architecture:interaction-modality, architecture:public-component-api, ] contributing: []
system_specs: [spec:AST-009, spec:AST-020]
Outline component contract
Contract at a glance
| Area | Contract |
|---|---|
| Public contract | items, activeId, onActiveIdChange, label, density, onNavigateStart, onNavigateEnd, offset, scrollContainerRef, hasScrollOnClick, root BaseProps, ref. |
| Behavior | A labelled navigation list of same-page heading links with keyboard movement, a scroll-tracked current heading, and a sliding indicator. |
| End-user impact | People see where they are in a long page and jump to any heading by pointer or keyboard, landing below a fixed header. |
| Builder impact | A builder's explicit aria-label is meant to name the navigation; today label or the localized default replaces it (FR1 gap). |
| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. Four implementation gaps are listed under Current-state impact. |
| Review checks | Reject a link left out of the Tab order or arrow-key movement added without a named exception, a dead link for a missing target, a callback that fires twice, or a lost focus outline. |
| Governing rules | architecture:interaction-modality; architecture:component-theming-surface; architecture:public-component-api INV5–INV8; spec:AST-020 FR15; design:reduced-motion DR1–DR3; WCAG 2.2 SC 1.3.1, 2.1.1, 2.4.3, 2.4.7. |
This table is a review projection; the body below is authoritative.
Intent
Outline presents same-page heading navigation: heading links with labels, a vertical indicator track, and a sliding active indicator that follows the heading the reader is on. The document owns the headings.
Consumer syntax and examples belong in Outline.doc.mjs.
Compatibility and migration
- Released default preserved:
yes— localized "Table of contents" label, default density, no offset, the nearest scrollable ancestor (else the window) as the scroll root, smooth scroll on click. - Compatibility class: records shipped behavior; no public prop, default, DOM, target, or styling output changes.
- Controlled/uncontrolled behavior: the current heading is controlled with
activeIdandonActiveIdChange, or uncontrolled and tracked from scroll. - Migration decision: none
Consumer migration instructions belong in consumer docs and release notes.
Current-state impact
- Caller
aria-labelreplaced (FR1). Caller props spread before the component'saria-label, so a calleraria-labelis replaced bylabelor the localized default; only thelabelprop names the navigation, wherearchitecture:public-component-apiINV5 lets a caller's explicit input reach the element. - Focus stays on the Outline after navigating (FR4). Activating a link scrolls to the section but leaves focus on the link, so the next Tab moves past the Outline, usually back toward the top of the content, instead of into the chosen section, where a native in-page link moves the sequential focus starting point (WCAG 2.2 SC 2.4.3).
- The indicator slides under reduced motion (FR6). The indicator's move
and resize transition has no reduced-motion branch, where
design:reduced-motionDR1–DR3 have it change at once on a fine pointer and cross-fade in 200 ms or less on a coarse one. - Navigation scrolls smoothly under reduced motion (FR4). Following a link
always smooth-scrolls to the heading, where
design:reduced-motionDR1–DR3 have a scroll the component starts land at once on a fine pointer and cross-fade in 200 ms or less on a coarse one.
Ownership boundary
Owns
- The navigation landmark and its
outlinetarget, the list, the heading links and theiroutline-itemtarget, the labels, the indicator track, and the active indicator and itsoutline-indicatortarget. - Keyboard focus within the list, scroll tracking, click and keyboard navigation, and the navigate callbacks.
Does not own / non-goals
- The destination headings and their content — owned by the document or product callsite.
- Building
itemsfrom markdown — owned bymodule:Outline/parseOutlineFromMarkdown.
Public concepts
| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
|---|---|---|---|---|---|---|---|
| Items | {id, label, level} list |
The headings, in order, with heading level 1–6. | Always | — | caller | Stable | Levels clamp to four indents. |
| Current heading | controlled activeId; scroll-tracked |
The heading marked current. | Always | scroll-tracked | component:Outline |
Stable | — |
| Label | string | The navigation's accessible name. | Always | localized default | component:Outline |
Stable | — |
| Density | default; compact |
Link padding. | Always | default |
component:Outline |
Stable | Closed union; rejected by types. |
| Scroll scope | offset; scrollContainerRef; hasScrollOnClick |
Activation line and landing offset; the scrolled container (else the nearest scrollable ancestor, else the window); whether clicks scroll. | Always | 0; nearest scrollable ancestor; true |
component:Outline |
Stable | — |
| Navigate events | onNavigateStart; onNavigateEnd |
Fired when a link navigation starts and when its scroll settles. | Always | none | caller | Stable | — |
Behavioral and layout contract
| ID | Invariant | Basis |
|---|---|---|
| FR1 | Outline renders a nav carrying the outline target, which reflects density, named by label or the localized "Table of contents", holding a ul (role="list") of li items, each with a link to #<id> whose label truncates with an ellipsis, then an aria-hidden indicator track and an aria-hidden active indicator. A caller's explicit aria-label reaches the nav (architecture:public-component-api INV5). Implementation gap: the component's aria-label replaces it (Current-state impact). |
Current source and tests |
| FR2 | Each link carries the outline-item target, which reflects level and, for the current heading, active; the current link has aria-current="location", primary text color, and semibold weight. Heading levels 1 and 2 share the first indent, and levels 3, 4, and 5–6 take the second, third, and fourth. |
Current source and tests |
| FR3 | Each link is in the normal Tab order, and Outline adds no arrow, Home, or End movement between links unless this record names an exception (spec:AST-020 FR15); Tab leaves the list after its last link. |
Current source and tests; spec:AST-020 FR15; WCAG 2.2 SC 2.1.1 |
| FR4 | A click, Enter, or Space on a link whose target exists pushes #<id> to history and smoothly scrolls to the heading: at offset 0 every scrollable ancestor, the window included, scrolls the heading to the top; with a non-zero offset only the scroll root (scrollContainerRef, else the nearest scrollable ancestor, else the window) scrolls, landing offset pixels plus the heading's own scroll margin below its top; onNavigateStart fires when the navigation starts and onNavigateEnd exactly once when the scroll settles or the reader interrupts it with a manual scroll, falling back to a timeout when no scroll end arrives; a second navigation ends the first at once, and onNavigateEnd does not fire after Outline unmounts mid-scroll. Under reduced motion the navigation scroll does not travel: it lands at once on a fine pointer (design:reduced-motion DR3) and cross-fades in 200 ms or less on a coarse pointer (DR2). With hasScrollOnClick={false} nothing scrolls: the hash is pushed, the heading marked current, and onNavigateEnd fires at once. A click or Enter on a missing target, or any modifier chord, is left to the browser; Space on a missing target does nothing. Following a link moves the sequential focus starting point to the destination, as a native in-page link does (WCAG 2.2 SC 2.4.3). Implementation gaps: the scroll is smooth under reduced motion too; and focus stays on the Outline link, so the next Tab continues after the Outline instead of inside the chosen section (Current-state impact). |
Current source and tests |
| FR5 | Uncontrolled, the current heading follows the reader's scroll position in the scroll root (scrollContainerRef, else the nearest scrollable ancestor, else the window), using an activation line shifted by offset and each heading's own scroll margin; the first heading is current before any heading passes the line, and the last heading is current once the scroll root reaches its end; a click marks its heading current once the scroll settles. Uncontrolled, onActiveIdChange reports each change of the current heading, from scroll or a click; controlled, the Outline does not track scroll, activeId decides, and onActiveIdChange reports the heading a click selects. Keyboard focus movement and the component's own navigation scroll are not treated as manual scrolling. |
Current source and tests |
| FR6 | The active indicator is a 2px --color-icon-primary bar over a 2px --color-border track at the inline start, positioned against the current link with CSS anchor positioning and moving with a fast standard transition. Under reduced motion the indicator does not travel: on a fine pointer it changes at once (design:reduced-motion DR3), and on a coarse pointer it cross-fades in 200 ms or less (DR2). Implementation gap: the transition has no reduced-motion branch, so the indicator still slides (Current-state impact). |
Current source and tests |
| FR7 | The keyboard-focused link shows the shared focus outline in every supported context. | Current source; browser evidence; architecture:interaction-modality |
| FR8 | ref, DOM, data, and event props, xstyle, className, and style reach or compose on the nav; data-testid reaches it. |
Current source and tests; architecture:public-component-api INV5–INV8 |
Allowed variation
- AV1 — Headings. Heading count, labels, levels, and the current heading vary without changing the anatomy.
- AV2 — Density. Default and compact density use the same anatomy and targets.
Representative states
| State | Required invariant | Allowed variation |
|---|---|---|
| Uncontrolled scrolling | The current heading follows scroll; onActiveIdChange reports it. |
Offset. |
| Controlled | activeId decides; clicks report through onActiveIdChange. |
— |
| Keyboard | Tab visits each link; Enter and Space navigate; no arrow, Home, or End movement. | — |
| Missing target | A click or Enter behaves as a plain link; Space does nothing; no callbacks. | — |
| Empty | Track and indicator render; no links and so no tab stop. | — |
Transformation and precedence order
- ORD1 — Current heading. Controlled
activeId→ scroll position. - ORD2 — Activation. Modifier chord, or a click or Enter on a missing target → browser default; Space on a missing target → nothing; otherwise push the hash, scroll, and fire the callbacks.
Performance and resources
- PR1 — Scroll tracking. While uncontrolled, Outline listens to scroll on its scroll root while mounted; navigation waits for scroll end with a timeout fallback; Outline installs the shared press controller.
Accessibility contract
- AR1 — Navigation landmark. The
navis named by a caller's explicitaria-label, else bylabelor the localized default (FR1 gap), and the list and items keep list semantics (WCAG 2.2 SC 1.3.1). - AR2 — Current location. The current link exposes
aria-current="location"; the indicator and track are hidden from assistive technology. - AR3 — Links in Tab order with real focus. Every link takes keyboard focus
through the normal Tab order and keeps real DOM focus, not
aria-activedescendant(spec:AST-020FR15).
Design relationships
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|---|---|---|---|---|
| Outline | Groups heading navigation and the indicator. | Current source and docs | Supporting | FR1 |
| Heading link | Navigates to one heading and carries level and active state. | Current source and docs | Prominent | FR2–FR4 |
| Label | Heading text inside its link, truncated with an ellipsis. | Current source and docs | Prominent | FR1, FR2 |
| Indicator track | The vertical rule behind the active marker. | Current source and docs | Supporting | FR6 |
| Active indicator | The marker aligned to the current link. | Current source and docs | Supporting | FR6 |
The Label sits inside the outline-item target and inherits its text
treatment. The Indicator track's target exposure is unsettled (OQ2).
Theming anatomy
{
"Outline": {"target": "outline"},
"Heading link": {"target": "outline-item"},
"Label": {"inherits": "outline-item"},
"Indicator track": {
"none": {
"reason": "unsettled: No current public target reaches this part"
}
},
"Active indicator": {"target": "outline-indicator"}
}
Family and system relationships
module:Outline/parseOutlineFromMarkdownbuildsitemsfrom markdown.architecture:interaction-modalityowns focus indication; FR7 applies it.architecture:component-theming-surfaceowns target mapping, inherited parts, and unsettled dispositions.architecture:public-component-apiowns caller-input routing; FR1 records thearia-labelgap and FR8 applies the rest.spec:AST-009owns accessibility-tree evidence; the verification map names its gap.
Verification map
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
|---|---|---|---|---|
| FR1, AR1 | Outline.test.tsx labelled-nav, default-label, class, and track tests; stable visual baselines core-outline--basic (neutral and probe themes) |
Items; default label; track and indicator | A missing nav name, link, or indicator, or a lost outline class, fails; a changed default outline comes back changed for review. Gap: the track test matches any aria-hidden element, so a missing track passes; no test covers the Label wrapper or its truncation, or a caller aria-label; and no accessibility-tree check proves the landmark name (spec:AST-009 FR3). |
audit:Outline/a11y |
| FR2, AR2 | Outline.test.tsx controlled aria-current, item class, and active-anchor tests |
Controlled current; active ordering | A missing aria-current, outline-item class, active class, or data-level, or an active link after the indicator, fails. Gap: the level indents have no unit check. |
audit:Outline/theming |
| FR3, AR3 | Outline.test.tsx keyboard suite; OutlineFocus.a11y.chromium.spec.ts Tab path |
Every link in the Tab order; real focus; no arrow, Home, or End movement; Tab out after the last link; one and zero items | A link left out of the Tab order, a tabindex on a link, aria-activedescendant use, an arrow, Home, or End key that moves focus, or a Tab that stays in the list after its last link fails. |
audit:Outline/keyboard |
| FR4, ORD2 | Outline.test.tsx navigate-callback and scroll-scoping suites |
Click, Enter, Space; settle; timeout; double settle; interruption; missing target; modifier; hasScrollOnClick={false}; offset landing |
A navigation that does not scroll, a callback that fires zero or twice, or a missing target or modifier chord that is intercepted fails. No test covers where focus goes after navigating. No test covers the reduced-motion navigation scroll. No test covers a second navigation ending the first, onNavigateEnd not firing after an unmount mid-scroll, or Space on a missing target. No test checks the hash push after a successful navigation. |
audit:Outline/behavior |
| FR5, ORD1 | Outline.test.tsx scroll-tracking, controlled, offset, scroll-margin, and scoped-container tests |
Uncontrolled scroll; controlled API; offset; scroll margin; container; keyboard and own scroll | A current heading that ignores the offset or scroll margin, tracks the wrong container, or treats keyboard focus or its own scroll as manual fails. No test dispatches a scroll event, so the scroll-event path of tracking has no check. |
audit:Outline/behavior |
| FR6 | Outline.test.tsx indicator tests |
Indicator present; active anchor order | A missing indicator fails (a missing track does not; see FR1). Gap: indicator position, size, color, and motion have no automated check beyond the baselines. No test covers the reduced-motion outcome. | audit:Outline/design |
| FR7 | OutlineFocus.a11y.chromium.spec.ts |
Every supported context | A focused link without a visible outline fails in Chromium. | audit:Outline/a11y |
| FR8 | Outline.test.tsx class tests; source review |
Caller class | Gap: no test covers ref, DOM props, style, or the xstyle merge order. |
audit:Outline/api |
| PR1 | Outline.test.tsx settle tests; source review |
Settle and fallback | A callback after the fallback and scroll end both elapse fails. Gap: listener cleanup has no check. | audit:Outline/behavior |
| Theming anatomy map | scripts/check-knowledge.mjs |
Canonical anatomy and current targets | Missing, extra, or stale mappings fail repository validation. | audit:Outline/theming |
Decision log
None recorded. The record describes shipped behavior.
Open questions
- OQ1 — Should Outline adopt a named
spec:AST-020FR15 exception: one Tab stop for a long heading list, with arrow, Home, and End movement? (human-api) Without it, a long heading list costs one Tab stop per link (FR3). - OQ2 — Should Indicator track gain a stable public theming target?
(
human-api) Target exposure is unsettled; the current lack of reachability does not decide the answer.
Content boundary
This file does not duplicate consumer prop tables/examples, current audit results, implementation steps, or system rules. It links to their owners.