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.mjsindex 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mjsindex 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.mjsindex 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.mdnew file mode 100644index 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.