Skip to content

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

TypeScript

docs(core): record layout component anatomy (#5764)

Cindy Zhang42584aaf87bc
diff --git a/packages/core/src/Grid/Grid.doc.mjs b/packages/core/src/Grid/Grid.doc.mjs
index c64bb982dc..39d7183dea 100644
--- a/packages/core/src/Grid/Grid.doc.mjs
+++ b/packages/core/src/Grid/Grid.doc.mjs
@@ -1,5 +1,21 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+ {
+ name: 'Grid container',
+ required: true,
+ description:
+ 'Two-dimensional layout container that arranges caller-supplied items in rows and columns.',
+ },
+ {
+ name: 'Spanning item',
+ required: false,
+ description:
+ "Optional GridSpan wrapper that changes one item's column or row participation.",
+ },
+];
+
/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
export const docs = {
@@ -9,6 +25,7 @@ export const docs = {
category: 'Layout',
keywords: ["grid","columns","responsive","auto-fill","auto-fit","masonry","tiles","row","col","simplegrid","responsive grid","card grid"],
usage: {
+ anatomy,
description:
'A CSS grid layout container for arranging children in rows and columns. Use Grid for card galleries, dashboards, and any multi-column layout. Supports fixed column counts and responsive columns that reflow based on available width.',
bestPractices: [
@@ -99,6 +116,7 @@ export const docs = {
/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
export const docsZh = {
usage: {
+ anatomy,
description:
'A CSS grid layout container for arranging children in rows and columns. Use Grid for card galleries, dashboards, and any multi-column layout. Supports fixed column counts and responsive columns that reflow based on available width.',
bestPractices: [
@@ -116,6 +134,7 @@ export const docsZh = {
export const docsDense = {
description: 'CSS Grid-based layout w/ responsive column support.',
usage: {
+ anatomy,
description: 'A CSS grid layout container for arranging children in rows and columns. Use Grid for card galleries, dashboards, and any multi-column layout. Supports fixed column counts and responsive columns that reflow based on available width.',
bestPractices: [
{ guidance: true, description: 'Use responsive columns for layouts that should adapt to screen size: columns={{minWidth: 280}}.' },
diff --git a/packages/core/src/Grid/Grid.spec.md b/packages/core/src/Grid/Grid.spec.md
new file mode 100644
index 0000000000..113a46c46a
--- /dev/null
+++ b/packages/core/src/Grid/Grid.spec.md
@@ -0,0 +1,161 @@
+---
+schema_version: 1
+template_version: 3
+kind: component
+id: component:Grid
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [layout, theming]
+verified_by:
+ [
+ packages/core/src/Grid/Grid.test.tsx,
+ packages/core/src/theme/themingTargets.test.ts,
+ scripts/check-knowledge.mjs,
+ ]
+families: [family:layout-primitives]
+design_specs: []
+architecture:
+ [architecture:component-theming-surface, architecture:public-component-api]
+contributing: []
+system_specs: []
+---
+
+# Grid component contract
+
+## Intent
+
+Grid arranges caller-supplied items in two-dimensional tracks. GridSpan
+optionally wraps one item to control its row or column participation. This draft
+records the current consumer anatomy and theming ownership without changing
+layout, targets, or public API.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: additive documentation only; 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.
+
+## Ownership boundary
+
+**Owns**
+
+- The Grid container and its current `grid` theming target.
+- The optional GridSpan wrapper and its current `grid-span` theming target.
+- Grid track construction and GridSpan row/column participation.
+
+**Does not own / non-goals**
+
+- Content supplied to Grid or GridSpan — owned by the caller.
+- Structural page-region or surface semantics.
+- New responsive behavior, layout props, targets, or target placement.
+
+## Public concepts
+
+No new public concept is introduced. Consumer props and usage remain documented
+in the canonical `Grid.doc.mjs` and the subordinate `GridSpan.doc.mjs`;
+`family:layout-primitives` owns the shared composition vocabulary.
+
+## Behavioral and layout contract
+
+| ID | Candidate invariant | Basis | Draft review state |
+| --- | ----------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | -------------------------------------------------- |
+| FR1 | Grid renders one Grid container carrying the current `grid` target and arranges caller content using the current track model. | Current source, docs, tests, and family | Verified current behavior; no new behavior decided |
+| FR2 | GridSpan renders one optional Spanning item wrapper carrying the current `grid-span` target. | Current source, docs, and tests | Verified current behavior; no target change |
+| FR3 | GridSpan's current `columns` and `rows` inputs affect only the wrapped item's participation in its parent grid. | Current source, tests, and family | Verified current behavior; no layout change |
+
+### Allowed variation
+
+- Grid may use fixed or intrinsic responsive tracks without changing Grid
+ container ownership.
+- Caller content may render directly in Grid or inside optional GridSpan wrappers.
+- A Spanning item may span columns, rows, both, or neither while retaining the
+ same target.
+
+### Representative states
+
+| State | Required invariant | Allowed variation |
+| -------------- | --------------------------------------------------------- | ----------------------------------------------------- |
+| Fixed Grid | Grid container owns the current `grid` target. | Positive fixed column count and spacing may vary. |
+| Intrinsic Grid | The same container owns responsive track construction. | Fill/fit mode, minimum width, and count cap may vary. |
+| Direct item | Caller content participates without a Grid-owned wrapper. | Caller owns its element and styling. |
+| Spanning item | GridSpan owns one wrapper and the `grid-span` target. | Column and row span values may vary. |
+
+### Transformation and precedence order
+
+- No new track construction, gap, alignment, sizing, or span precedence rule is
+ introduced.
+
+### Performance and resources
+
+- No new performance or resource rule is introduced.
+
+## Accessibility contract
+
+This draft does not add semantic roles to Grid or GridSpan or change their
+current DOM forwarding and caller-owned content semantics.
+
+## Design relationships
+
+| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
+| ---------------- | ------------------------------------------------------------------ | ----------------------------------------- | -------------- | ------------------ |
+| Grid container | Presents the current two-dimensional layout container. | Current source, docs, and family contract | Supporting | FR1 |
+| Spanning item | Optionally changes one item's row or column participation in Grid. | Current source, docs, and family contract | Supporting | FR2, FR3 |
+
+Direct caller content is not an additional Grid-owned anatomy part.
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+ "Grid container": {"target": "grid"},
+ "Spanning item": {"target": "grid-span"}
+}
+```
+
+## Family and system relationships
+
+- `family:layout-primitives` owns the shared spacing, sizing, alignment, and item
+ participation vocabulary for Grid and GridSpan.
+- `architecture:component-theming-surface` owns anatomy qualification and the
+ two current local target mappings.
+- `architecture:public-component-api` owns the stable prop surface; this
+ documentation adds no API.
+
+## Verification map
+
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ------------------- | ------------------------------------------------------------ | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| FR1 | `Grid.test.tsx` track, sizing, alignment, and content suites | Fixed, default, fill, fit, capped, and sized | Changing current track output or removing the container/content fails exact style-variable, inline-style, or content checks. | `audit:Grid/anatomy` |
+| FR2, FR3 | `Grid.test.tsx` GridSpan suites | Column, full-row, row, combined, and no span | Changing wrapper rendering or span values fails exact inline-style and content assertions. | `audit:GridSpan/anatomy` |
+| Target inventory | Source inspection and `themingTargets.test.ts` | Grid and GridSpan targets | Runtime and documented target metadata drift fails target validation. | `audit:Grid/theming` |
+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and both current targets | Missing, extra, prefixed, or stale mappings fail repository validation. | `audit:Grid/theming` |
+
+Grid tests pin track and span output, content rendering, and prop forwarding.
+They do not assert both target classes in focused component tests; target
+placement is source-inspected and the global inventory checks the runtime/docs
+relationship.
+
+## Decision log
+
+None. This draft records current facts and introduces no component-local design,
+layout, accessibility, or API decision.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables, examples, family layout
+rules, track algorithms, implementation steps, or system rules. It links to
+their owners.
diff --git a/packages/core/src/NavMenu/NavHeadingMenu.spec.md b/packages/core/src/NavMenu/NavHeadingMenu.spec.md
new file mode 100644
index 0000000000..39191a4758
--- /dev/null
+++ b/packages/core/src/NavMenu/NavHeadingMenu.spec.md
@@ -0,0 +1,205 @@
+---
+schema_version: 1
+template_version: 3
+kind: component
+id: component:NavHeadingMenu
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [behavior, theming, accessibility]
+verified_by:
+ [
+ packages/core/src/NavMenu/NavHeadingMenu.test.tsx,
+ packages/core/src/Icon/Icon.test.tsx,
+ packages/core/src/Text/Text.test.tsx,
+ packages/core/src/theme/themingTargets.test.ts,
+ scripts/check-knowledge.mjs,
+ ]
+families: []
+design_specs: []
+architecture:
+ [
+ architecture:component-theming-surface,
+ architecture:icon-resolution-and-component-slots,
+ architecture:layer-runtime,
+ architecture:public-component-api,
+ ]
+contributing: []
+system_specs: []
+---
+
+# NavHeadingMenu component contract
+
+## Intent
+
+NavHeadingMenu presents selectable actions inside a SideNavHeading or
+TopNavHeading popover. This draft records the current consumer anatomy and
+theming ownership without changing rendering, keyboard behavior, layer
+lifecycle, targets, or public API.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: additive documentation only; runtime, DOM, styling,
+ targets, and public API remain unchanged
+- Controlled/uncontrolled behavior: unchanged
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The Menu container, menu semantics, keyboard movement, typeahead, and current
+ `nav-heading-menu` target.
+- Each Item's action/link row, selection handling, size treatment, and current
+ `nav-heading-menu-item` target.
+- The content layout that contains either the text-rendered or caller-rendered
+ label path and the optional description.
+
+**Does not own / non-goals**
+
+- Icon artwork and the `icon` target — delegated to `component:Icon` for values
+ rendered through Icon.
+- String label and description typography and their `text` target — delegated to
+ `component:Text`.
+- Non-string label content — owned by the caller.
+- The SideNavHeading or TopNavHeading trigger, popup surface, positioning,
+ dismissal lifecycle, or close-state ownership.
+- New NavHeadingMenu targets for either label path or Item description, or any
+ runtime, API, target, or DOM change.
+
+## Public concepts
+
+No new public concept is introduced. The canonical `NavMenu.doc.mjs` continues
+to document NavHeadingMenu and NavHeadingMenuItem together.
+
+## Behavioral and layout contract
+
+| ID | Candidate invariant | Basis | Draft review state |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | ------------------------------------------------------- |
+| FR1 | NavHeadingMenu renders one Menu carrying `role="menu"` and the current `nav-heading-menu` target. | Current source, docs, and tests | Verified current behavior; no new behavior decided |
+| FR2 | NavHeadingMenuItem renders one Item carrying `role="menuitem"` and the current `nav-heading-menu-item` target as a link when `href` is supplied and a div otherwise. | Current source, docs, and tests | Verified current behavior; no target change |
+| FR3 | An optional Icon-rendered icon delegates to Icon's `icon` target. String labels and all descriptions render through Text's `text` target; non-string labels render directly as caller-owned content. | Current source and target docs | Verified current ownership; focused evidence is partial |
+| FR4 | The parent nav heading supplies the close callback and owns its popup runtime; NavHeadingMenu consumes that callback for Escape and successful Item selection. | Current source and tests | Verified current relationship; no layer change |
+
+### Allowed variation
+
+- Items may render as links or callback actions and may be enabled or disabled
+ without changing anatomy ownership.
+- Icon may be absent. A label may take the string path rendered through Text or
+ the non-string path rendered directly as caller-owned content. Item
+ description may be absent and, when present, renders through Text.
+- Menu size and minimum width may vary without creating separate anatomy parts
+ or targets.
+
+### Representative states
+
+| State | Required invariant | Allowed variation |
+| ----------------- | ----------------------------------------------------------------- | --------------------------------------------------------- |
+| Link Item | Item is an anchor with menuitem semantics and its current target. | Destination, text, description, and icon may vary. |
+| Action Item | Item is a div with menuitem semantics and its current target. | Selection callback may vary. |
+| Disabled Item | Item remains present and reflects disabled semantics. | It is skipped by keyboard navigation and typeahead. |
+| String-label Item | Text-rendered item label delegates to Text's current target. | Label value, destination, description, and icon may vary. |
+| Custom-label Item | Caller-rendered item label remains caller-owned. | Caller controls the non-string label content. |
+| Described Item | Item description delegates to Text's current target. | Description content may vary or be absent. |
+
+### Transformation and precedence order
+
+- No new focus, typeahead, activation, close, size, or styling precedence rule
+ is introduced.
+
+### Performance and resources
+
+- No new performance or resource rule is introduced.
+
+## Accessibility contract
+
+This draft does not change or extend the current menu/menuitem roles, disabled
+state, arrow/Home/End/Escape movement, typeahead, keyboard activation, or caller
+labeling behavior.
+
+## Design relationships
+
+| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
+| -------------------------- | ------------------------------------------------------------------------- | ------------------------------ | ----------------- | ------------------ |
+| Menu | Groups nav-heading actions with menu semantics and keyboard navigation. | Current source and public docs | Prominent | FR1, FR4 |
+| Item | Presents one selectable action or navigation destination. | Current source and public docs | Prominent | FR2 |
+| Icon | Presents optional Icon-owned artwork before the label. | `component:Icon` | Supporting | FR3 |
+| Text-rendered item label | Presents a string label through Text's body treatment. | `component:Text` | Prominent | FR2, FR3 |
+| Caller-rendered item label | Presents a non-string label directly through caller-owned content. | Caller-supplied content | Context-dependent | FR2, FR3 |
+| Item description | Presents optional supporting content through Text's supporting treatment. | `component:Text` | Supporting | FR2, FR3 |
+
+The menu is popup content, not the popup host. SideNavHeading or TopNavHeading
+owns the layer lifecycle and supplies the close callback through context.
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+ "Menu": {"target": "nav-heading-menu"},
+ "Item": {"target": "nav-heading-menu-item"},
+ "Icon": {
+ "delegatesTo": {"owner": "component:Icon", "target": "icon"}
+ },
+ "Text-rendered item label": {
+ "delegatesTo": {"owner": "component:Text", "target": "text"}
+ },
+ "Caller-rendered item label": {
+ "none": {
+ "reason": "intentional: Non-string label content is rendered directly and remains caller-owned"
+ }
+ },
+ "Item description": {
+ "delegatesTo": {"owner": "component:Text", "target": "text"}
+ }
+}
+```
+
+## Family and system relationships
+
+- `architecture:component-theming-surface` owns anatomy qualification, local
+ target mapping, component delegation, and factual `none` dispositions.
+- `architecture:icon-resolution-and-component-slots` owns Icon slot resolution;
+ this draft records the current Icon delegation without changing slot behavior.
+- `architecture:layer-runtime` owns the shared popup host lifecycle used by the
+ parent nav heading. NavHeadingMenu owns only its menu behavior and consumes the
+ heading-provided close callback.
+- `architecture:public-component-api` owns the stable props and subcomponent
+ surface; this documentation adds no API.
+- NavHeadingMenu has no current family contract.
+
+## Verification map
+
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------- |
+| FR1, FR2 | `NavHeadingMenu.test.tsx` role, render, link, and disabled suites | Menu with link, action, and disabled Items | Removing menu/item semantics, content, or current rendering branches fails existing role, tag, attribute, and text checks. | `audit:NavHeadingMenu/anatomy` |
+| FR3 | NavHeadingMenuItem source inspection plus Icon and Text target metadata | Icon, string label, caller-rendered label, and description paths | Source proves Icon-slot delegation, conditional label rendering, and Text-wrapped description; focused tests assert string and description content but not target placement or custom-label ownership. | `audit:NavHeadingMenu/theming` |
+| FR4 | `NavHeadingMenu.test.tsx` context and keyboard suites | Selection, Escape, arrows, Home/End, typeahead | Breaking close callback consumption or keyboard behavior fails focused interaction assertions. | `audit:NavHeadingMenu/behavior` |
+| Target inventory | Source inspection and `themingTargets.test.ts` | Menu, Item, and delegated Icon targets | Runtime and documented target metadata drift fails target validation. | `audit:NavHeadingMenu/theming` |
+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and both current local targets | Missing, extra, prefixed, or stale mappings fail repository validation. | `audit:NavHeadingMenu/theming` |
+
+Existing tests prove menu/item roles, string-label and description content,
+interaction, and the heading-provided close callback. The conditional non-string
+label path, Icon target placement, Text target placement, and both local target
+placements remain source-inspected rather than pinned by focused assertions.
+
+## Decision log
+
+None. This draft records current facts and introduces no component-local design,
+behavior, accessibility, layer, or API decision.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables, examples, keyboard or layer
+algorithms, implementation steps, or system rules. It links to their owners.
diff --git a/packages/core/src/NavMenu/NavMenu.doc.mjs b/packages/core/src/NavMenu/NavMenu.doc.mjs
index 0b8feb620c..7a86cf83f0 100644
--- a/packages/core/src/NavMenu/NavMenu.doc.mjs
+++ b/packages/core/src/NavMenu/NavMenu.doc.mjs
@@ -1,5 +1,40 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+ {
+ name: 'Menu',
+ required: true,
+ description:
+ 'Menu container for nav-heading actions, with menu semantics and keyboard navigation.',
+ },
+ {
+ name: 'Item',
+ required: true,
+ description: 'Selectable action or navigation link inside the Menu.',
+ },
+ {
+ name: 'Icon',
+ required: false,
+ description: 'Optional Icon-rendered artwork shown before an Item label.',
+ },
+ {
+ name: 'Text-rendered item label',
+ required: false,
+ description: 'String Item label rendered through Text.',
+ },
+ {
+ name: 'Caller-rendered item label',
+ required: false,
+ description: 'Non-string Item label content rendered directly by the caller.',
+ },
+ {
+ name: 'Item description',
+ required: false,
+ description: 'Optional supporting description rendered through Text.',
+ },
+];
+
/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
export const docs = {
@@ -11,6 +46,7 @@ export const docs = {
hidden: false,
keywords: ['nav', 'menu', 'navigation', 'heading', 'menu-item', 'popover'],
usage: {
+ anatomy,
description:
'Accessible menu container and items for nav heading popovers. ' +
'NavHeadingMenu provides role="menu" with keyboard navigation; ' +
@@ -44,6 +80,7 @@ export const docs = {
export const docsDense = {
description: 'Accessible menu container + items for nav heading popovers. NavHeadingMenu = role="menu" w/ keyboard nav; NavHeadingMenuItem renders selectable items.',
usage: {
+ anatomy,
description:
'Accessible menu container + items for nav heading popovers. NavHeadingMenu provides role="menu" w/ keyboard navigation; NavHeadingMenuItem renders individual selectable items. Pass as menu prop of SideNavHeading or TopNavHeading.',
},
diff --git a/packages/core/src/Toolbar/Toolbar.doc.mjs b/packages/core/src/Toolbar/Toolbar.doc.mjs
index eebd60781f..79f9a2e928 100644
--- a/packages/core/src/Toolbar/Toolbar.doc.mjs
+++ b/packages/core/src/Toolbar/Toolbar.doc.mjs
@@ -1,5 +1,21 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+ {
+ name: 'Outer chrome',
+ required: true,
+ description:
+ 'Section-owned container that supplies the toolbar surface, padding, and selected divider edges.',
+ },
+ {
+ name: 'Toolbar',
+ required: true,
+ description:
+ 'Named toolbar row that owns toolbar semantics and the start, optional center, and end layout.',
+ },
+];
+
/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
export const docs = {
@@ -147,6 +163,7 @@ export const docs = {
], },
],
usage: {
+ anatomy,
description:
'Toolbar is a horizontal bar with left, center, and right areas. Use it for contextual actions within a content area (above a table, inside a card, or in a panel), not as a page-level header. Set the size once on the toolbar and all buttons, inputs, and tabs inside it match automatically.',
bestPractices: [
@@ -182,6 +199,7 @@ export const docsZh = {
},
],
usage: {
+ anatomy,
description:
'Toolbar is a horizontal bar with left, center, and right areas. Use it for contextual actions within a content area (above a table, inside a card, or in a panel), not as a page-level header. Set the size once on the toolbar and all buttons, inputs, and tabs inside it match automatically.',
bestPractices: [
@@ -200,6 +218,7 @@ export const docsZh = {
export const docsDense = {
description: 'Horizontal bar w/ left, center, right areas. For contextual actions in content, not page headers. Size cascades to children.',
usage: {
+ anatomy,
description:
'Horizontal bar w/ left, optional center, right. For contextual actions within content (tables, cards, panels), not page-level headers. Size cascades to children.',
bestPractices: [
diff --git a/packages/core/src/Toolbar/Toolbar.spec.md b/packages/core/src/Toolbar/Toolbar.spec.md
new file mode 100644
index 0000000000..b1ce3ea04d
--- /dev/null
+++ b/packages/core/src/Toolbar/Toolbar.spec.md
@@ -0,0 +1,173 @@
+---
+schema_version: 1
+template_version: 3
+kind: component
+id: component:Toolbar
+authority: draft
+archive_reason: null
+superseded_by: null
+approved_by: null
+approved_at: null
+owners: [cixzhang]
+review_triggers: [layout, theming, accessibility]
+verified_by:
+ [
+ packages/core/src/Toolbar/Toolbar.test.tsx,
+ packages/core/src/Section/Section.test.tsx,
+ packages/core/src/theme/themingTargets.test.ts,
+ scripts/check-knowledge.mjs,
+ ]
+families: [family:layout-regions]
+design_specs: []
+architecture:
+ [
+ architecture:component-theming-surface,
+ architecture:container-padding,
+ architecture:public-component-api,
+ ]
+contributing: []
+system_specs: []
+---
+
+# Toolbar component contract
+
+## 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.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: additive documentation only; 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.
+
+## Ownership boundary
+
+**Owns**
+
+- The named toolbar row, toolbar semantics, start/optional-center/end layout,
+ keyboard movement, size cascade, and current `toolbar` target.
+
+**Does not own / non-goals**
+
+- The painted outer chrome, variant, block padding, and selected divider edges —
+ delegated to `component:Section`.
+- 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.
+
+## 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.
+
+## 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 |
+
+### Allowed variation
+
+- Caller content may be absent or supplied in the start, center, and end slots
+ without changing Outer chrome or Toolbar ownership.
+- Size and orientation may change the current row geometry and keyboard axis
+ without creating separate anatomy parts or targets.
+
+### 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. |
+
+### Transformation and precedence order
+
+- No new slot, layout, edge-compensation, padding, or event precedence rule is
+ introduced.
+
+### Performance and resources
+
+- No new performance or resource rule is introduced.
+
+## 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.
+
+## 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 |
+| 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
+become additional Toolbar-owned anatomy or targets.
+
+### Theming anatomy
+
+<!-- anatomy-theming:v1 -->
+
+```json
+{
+ "Outer chrome": {
+ "delegatesTo": {"owner": "component:Section", "target": "section"}
+ },
+ "Toolbar": {"target": "toolbar"}
+}
+```
+
+## Family and system relationships
+
+- `family:layout-regions` owns the structural-region vocabulary and records
+ Toolbar as a Section-backed contextual action region.
+- `architecture:container-padding` owns the inherited inset and edge-compensation
+ 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.
+
+## 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.
+
+## Decision log
+
+None. This draft records current facts and introduces no component-local design,
+layout, accessibility, or API decision.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables, examples, family layout
+rules, container-padding mechanics, keyboard algorithms, implementation steps,
+or system rules. It links to their owners.