Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
38.6 KB
Raw Blame

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 activeId and onActiveIdChange, or uncontrolled and tracked from scroll.
  • Migration decision: none

Consumer migration instructions belong in consumer docs and release notes.

Current-state impact

  • Caller aria-label replaced (FR1). Caller props spread before the component's aria-label, so a caller aria-label is replaced by label or the localized default; only the label prop names the navigation, where architecture:public-component-api INV5 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-motion DR1–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-motion DR1–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 outline target, the list, the heading links and their outline-item target, the labels, the indicator track, and the active indicator and its outline-indicator target.
  • 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 items from markdown — owned by module: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 nav is named by a caller's explicit aria-label, else by label or 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-020 FR15).

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/parseOutlineFromMarkdown builds items from markdown.
  • architecture:interaction-modality owns focus indication; FR7 applies it.
  • architecture:component-theming-surface owns target mapping, inherited parts, and unsettled dispositions.
  • architecture:public-component-api owns caller-input routing; FR1 records the aria-label gap and FR8 applies the rest.
  • spec:AST-009 owns 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-020 FR15 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.