Skip to content

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

TypeScript

docs(spec): Toolbar records its shipped contract as current (#8715)

Cindy Zhang327dd846b7d6
diff --git a/packages/core/src/Toolbar/Toolbar.spec.md b/packages/core/src/Toolbar/Toolbar.spec.md
index eeedcd1c58..7f8ee78b14 100644
--- a/packages/core/src/Toolbar/Toolbar.spec.md
+++ b/packages/core/src/Toolbar/Toolbar.spec.md
@@ -1,54 +1,90 @@
---
schema_version: 3
-template_version: 3
+template_version: 7
kind: component
id: component:Toolbar
-authority: draft
+authority: current
archive_reason: null
superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: cixzhang
+approved_at: 2026-10-27
owners: [cixzhang]
review_triggers: [layout, theming, accessibility]
verified_by:
[
packages/core/src/Toolbar/Toolbar.test.tsx,
+ packages/core/src/Toolbar/__tests__/Toolbar.a11y.test.tsx,
+ packages/core/src/Toolbar/__tests__/Toolbar.a11y.chromium.spec.ts,
packages/core/src/Section/Section.test.tsx,
packages/core/src/theme/themingTargets.test.ts,
scripts/check-knowledge.mjs,
]
modules: []
families: [family:layout-regions]
-design_specs: []
+design_specs: [design:reduced-motion]
architecture:
[
architecture:component-theming-surface,
architecture:container-padding,
+ architecture:component-size-cascade,
+ architecture:interaction-modality,
architecture:public-component-api,
]
contributing: []
-system_specs: []
+system_specs: [spec:AST-020]
---
# Toolbar component contract
+## Contract at a glance
+
+| Area | Contract |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract | `Toolbar` with `label`, `startContent`, `centerContent`, `endContent`, `size` (`md`), `gap` (`1`), `orientation` (`horizontal`), `variant` (`transparent`), and `dividers`; target `toolbar` with `size`. |
+| Behavior | A Section-wrapped `role="toolbar"` row with start, optional center, and end lanes. The row is one tab stop; arrow keys, Home, and End move focus among its controls along its orientation. |
+| End-user impact | Keyboard users Tab into the toolbar once and move between its controls with arrows, without losing text-caret keys inside an input or arrow keys inside an open menu; screen-reader users hear a named toolbar and its orientation. |
+| Builder impact | None. |
+| Compatibility/readiness | Records shipped behavior; no public change. Four implementation gaps (see Current-state impact). |
+| Review checks | Reject more than one tab stop, arrows that steal caret keys from a text input mid-line, caller props that replace `role`, `aria-label`, or `aria-orientation`, or moving outer chrome into Toolbar. |
+| Governing rules | `family:layout-regions`; `spec:AST-020` (toolbar pattern binding); `architecture:container-padding`. |
+
+This table is a review projection; the body below is authoritative.
+
## Intent
Toolbar presents a named contextual action region with one semantic toolbar row
-inside Section-owned outer chrome. This draft records the current consumer
-anatomy and theming ownership without changing layout, keyboard behavior,
-targets, or public API.
+inside Section-owned outer chrome. It owns the row's semantics, lane layout,
+keyboard model, and size cascade. Consumer usage lives in `Toolbar.doc.mjs`.
## Compatibility and migration
- Released default preserved: `yes`
-- Compatibility class: additive documentation only; runtime, DOM, styling,
+- Compatibility class: records shipped behavior; runtime, DOM, styling,
targets, and public API remain unchanged
- Controlled/uncontrolled behavior: not applicable
- Migration decision: none
Consumer migration instructions belong in consumer docs and release notes.
+## Current-state impact
+
+- **The keyboard hint fades under reduced motion.** The arrow-key hint (FR6)
+ fades out over 150 ms (it appears at once) even when reduced motion is
+ requested;
+ `design:reduced-motion` DR3 allows no animated property for a fine pointer.
+- **A vertical toolbar with center content stays side by side.** With
+ `orientation="vertical"` and `centerContent`, the three lanes stay in one row
+ while `aria-orientation` is vertical and ArrowDown and ArrowUp move between
+ them, so the visual order and the announced axis disagree.
+- **The tab stop does not follow a pointer click.** After a click on a control
+ that does not hold the stop, the stop stays on the earlier control, so
+ Shift+Tab from the clicked control lands on that earlier control inside the
+ toolbar before leaving it.
+- **Links and some fields keep their own tab stops.** A link (such as a Button
+ with `href`), `textarea`, or `select` in the row is outside the roving stop:
+ it keeps its own tab stop and the arrow keys skip it. The APG toolbar pattern
+ makes the toolbar a single tab stop.
+
## Ownership boundary
**Owns**
@@ -59,25 +95,29 @@ Consumer migration instructions belong in consumer docs and release notes.
**Does not own / non-goals**
- The painted outer chrome, variant, block padding, and selected divider edges —
- delegated to `component:Section`.
+ owned by Section and uncontracted here.
- Content supplied through the three layout slots — owned by the caller or its
rendered components.
- A general arbitrary-child layout primitive contract.
-- New runtime behavior, targets, props, or target placement.
+- Arrow-key handling inside composed menus or popovers — owned by those
+ components.
## Public concepts
-No new public concept is introduced. Consumer props, slots, and usage remain
-documented in `Toolbar.doc.mjs`; `family:layout-regions` owns the shared
-structural-region boundary.
+No component-local concept beyond the consumer props; `family:layout-regions`
+owns the shared structural-region boundary.
## Behavioral and layout contract
-| ID | Candidate invariant | Basis | Draft review state |
-| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | -------------------------------------------------- |
-| FR1 | The current render contains Section-owned Outer chrome around one named Toolbar carrying `role="toolbar"` and the current `toolbar` target. | Current source, docs, tests, and family | Verified current behavior; no new behavior decided |
-| FR2 | The Toolbar uses its current two-lane layout without center content and its current three-lane layout when center content is supplied. | Current source and focused structure tests | Verified current behavior; no layout change |
-| FR3 | Variant, selected divider edges, and outer padding remain delegated to Section, while Toolbar retains toolbar semantics, keyboard behavior, and internal layout. | Current source, docs, and family contract | Verified current ownership; no target change |
+| ID | Invariant | Basis |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
+| FR1 | The render contains Section-owned Outer chrome around one Toolbar carrying `role="toolbar"`, `aria-label` from `label`, `aria-orientation`, and the `toolbar` target with `size`. Caller `role`, `aria-label`, and `aria-orientation` are dropped; other DOM props reach the toolbar row; `ref`, `className`, `style`, and `xstyle` reach the Section. | Current source, docs, tests, and family |
+| FR2 | Without center content the Toolbar is a flex line of the present start and end lanes, a row when horizontal and a column of lanes when vertical; with center content it is a three-lane grid whose lanes sit side by side in either orientation. Each lane lays its controls out in a row. No lane clips its content, and the center lane can shrink below its content width. `gap` spaces controls within and between lanes. | Current source and focused structure tests |
+| FR3 | Variant (default `transparent`), selected divider edges, and block padding by size remain delegated to Section, while Toolbar retains toolbar semantics, keyboard behavior, and internal layout. | Current source, docs, and family contract |
+| FR4 | The row MUST be a single tab stop. ArrowRight and ArrowLeft (horizontal) or ArrowDown and ArrowUp (vertical) move focus between its controls, wrapping at the ends and skipping disabled controls; Home and End move to the first and last. Implementation gap: only buttons, inputs, and elements with `tabindex` share the stop, so links, `textarea`, and `select` keep their own tab stops, and a pointer click does not move the stop (Current-state impact). Arrows do not move focus out of a text input whose caret is mid-line, and inside an open composed menu arrow keys belong to the menu. The toolbar keeps its tab stop after a composed menu is dismissed from outside, and keeps its own arrow movement when rendered inside a popover. | APG toolbar pattern; current source and tests |
+| FR5 | Caller `onKeyDown`, `onFocus`, and `onBlur` run first; when the caller cancels the event, the built-in handling is skipped. | Current source and tests |
+| FR6 | Keyboard focus entering the row can show a brief, self-dismissing hint for its arrow-key axis. | Current source |
+| FR7 | `size` (default `md`) is provided to descendant controls as their default size; Toolbar starts its own size scope and does not inherit an outer size provider (`architecture:component-size-cascade` INV7). | Current source and tests |
### Allowed variation
@@ -88,33 +128,33 @@ structural-region boundary.
### Representative states
-| State | Required invariant | Allowed variation |
-| ----------------- | ------------------------------------------------------- | --------------------------------------------------- |
-| Empty toolbar | Outer chrome and named Toolbar remain rendered. | No caller slot content. |
-| Two-lane layout | Start and/or end content use the current flex layout. | Either lane may be absent. |
-| Three-lane layout | Center content selects the current three-column layout. | Start or end content may be absent. |
-| Vertical toolbar | Toolbar semantics and target remain unchanged. | Layout and keyboard movement use the vertical axis. |
+| State | Required invariant | Allowed variation |
+| ----------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| Empty toolbar | Outer chrome and named Toolbar remain rendered. | No caller slot content. |
+| Two-lane layout | Start and/or end content use the current flex layout. | Either lane may be absent. |
+| Three-lane layout | Center content selects the current three-column layout. | Start or end content may be absent. |
+| Vertical toolbar | Toolbar semantics and target remain unchanged. | Keyboard movement uses the vertical axis; lanes stack only without center content. |
### Transformation and precedence order
-- No new slot, layout, edge-compensation, padding, or event precedence rule is
- introduced.
+- **ORD1 — Events.** Caller handler, then the built-in handler unless cancelled
+ (FR5).
### Performance and resources
-- No new performance or resource rule is introduced.
+- No resource rule.
## Accessibility contract
-This draft does not change or extend Toolbar's current accessible name,
-orientation, roving-tabindex, keyboard-hint, caret-guard, or event-composition
-behavior.
+- **AR1 — Named toolbar.** FR1's role, name, and orientation.
+- **AR2 — Keyboard.** FR4 follows the APG toolbar pattern, apart from FR4's
+ implementation gap.
## Design relationships
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
| ---------------- | -------------------------------------------------------------------------------- | ----------------------------------------- | -------------- | ------------------ |
-| Outer chrome | Supplies the painted surface, padding, and selected boundaries around the row. | `component:Section` | Supporting | FR1, FR3 |
+| Outer chrome | Supplies the painted surface, padding, and selected boundaries around the row. | Section | Supporting | FR1, FR3 |
| Toolbar | Presents the named toolbar semantics and current two- or three-lane arrangement. | Current source, docs, and family contract | Prominent | FR1, FR2, FR3 |
The slot contents are caller-owned content inside Toolbar's layout. They do not
@@ -141,27 +181,40 @@ become additional Toolbar-owned anatomy or targets.
geometry used by the composed Section and Toolbar.
- `architecture:component-theming-surface` owns anatomy qualification, local
target mapping, and component delegation.
-- `architecture:public-component-api` owns the stable prop and slot surface; this
- documentation adds no API.
+- `architecture:public-component-api` owns the stable prop and slot surface.
+- `spec:AST-020` binds the toolbar accessibility pattern exercised by the
+ Toolbar a11y tests.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| ------------------- | --------------------------------------------------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | ----------------------- |
-| FR1 | `Toolbar.test.tsx` role, name, pass-through, and Section suites | Empty and populated Toolbar | Removing the role/name, Toolbar target, Section composition, or delegated Section target fails current evidence. | `audit:Toolbar/anatomy` |
-| FR2 | `Toolbar.test.tsx` slot and child-count suites | Start-only, end-only, two-lane, and three-lane | Changing current slot presence or two-/three-lane structure fails focused assertions. | `audit:Toolbar/layout` |
-| FR3 | Toolbar and Section source plus their focused tests | Variant, divider, size, and orientation states | Moving outer chrome ownership into Toolbar or moving toolbar semantics onto Section contradicts source and coverage. | `audit:Toolbar/theming` |
-| Target inventory | `packages/core/src/theme/themingTargets.test.ts` | Toolbar and delegated Section targets | Runtime and documented target metadata drift fails target validation. | `audit:Toolbar/theming` |
-| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and current local target | Missing, extra, prefixed, or stale mappings fail repository validation. | `audit:Toolbar/theming` |
-
-Existing tests assert the semantic row, slot structure, and Section composition.
-They do not prove computed inset or edge-compensation geometry for every parent
-padding state; this documentation does not claim that coverage.
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ------------------- | ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ----------------------------- |
+| FR1 | `Toolbar.test.tsx` role, name, pass-through, and Section suites | Empty and populated Toolbar | Removing the role/name, Toolbar target, Section composition, or delegated Section target fails current evidence. | `audit:Toolbar/anatomy` |
+| FR2 | `Toolbar.test.tsx` slot and child-count suites | Start-only, end-only, two-lane, and three-lane | Changing current slot presence or two-/three-lane structure fails focused assertions. | `audit:Toolbar/layout` |
+| FR3 | `Toolbar.test.tsx` variant and block-inset tests | Default and passed variant | A variant that no longer reaches Section fails. | `audit:Toolbar/theming` |
+| FR4, FR5, AR1–AR2 | `Toolbar.test.tsx` keyboard and composition suites; `Toolbar.a11y.test.tsx`; `Toolbar.a11y.chromium.spec.ts` | Horizontal, vertical, text input, MoreMenu, popover | Extra tab stops, stolen caret keys, or ignored caller cancellation fails. | `audit:Toolbar/accessibility` |
+| Target inventory | `packages/core/src/theme/themingTargets.test.ts` | Toolbar and delegated Section targets | Runtime and documented target metadata drift fails target validation. | `audit:Toolbar/theming` |
+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and current local target | Missing, extra, prefixed, or stale mappings fail repository validation. | `audit:Toolbar/theming` |
+
+Read from source, with no focused test yet:
+
+- FR1: caller `role`, `aria-label`, and `aria-orientation` being dropped, and
+ `className`, `style`, and `xstyle` reaching Section.
+- FR2: the flex and grid layouts themselves, and `gap` spacing.
+- FR3: divider edges.
+- FR5: caller `onFocus` and `onBlur` running first and their cancellation.
+- FR4: links, `textarea`, and `select` keeping their own tab stops, and the stop
+ staying put after a pointer click.
+- FR6.
+- FR7: descendant controls taking `size` as their default, and the fresh size
+ scope.
+
+Computed inset and edge-compensation geometry for each parent padding state is
+not claimed.
## Decision log
-None. This draft records current facts and introduces no component-local design,
-layout, accessibility, or API decision.
+No component-local decision is recorded.
## Open questions