Skip to content

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

TypeScript

docs(spec): Breadcrumbs records its shipped contract as current (#8560)

Cindy Zhangef6d25b715d9
diff --git a/packages/core/src/Breadcrumbs/BreadcrumbItem.spec.md b/packages/core/src/Breadcrumbs/BreadcrumbItem.spec.md
index a41a6e01ad..4cac1c5cd2 100644
--- a/packages/core/src/Breadcrumbs/BreadcrumbItem.spec.md
+++ b/packages/core/src/Breadcrumbs/BreadcrumbItem.spec.md
@@ -1,25 +1,27 @@
---
schema_version: 3
-template_version: 4
+template_version: 7
kind: component
id: component:BreadcrumbItem
-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: [public-api, behavior, layout, theming, accessibility]
verified_by:
[
packages/core/src/Breadcrumbs/Breadcrumbs.test.tsx,
+ packages/core/src/Breadcrumbs/__tests__/Breadcrumbs.a11y.test.tsx,
+ packages/core/src/Breadcrumbs/__tests__/Breadcrumbs.a11y.chromium.spec.ts,
apps/storybook/stories/BreadcrumbItem.stories.tsx,
packages/core/src/theme/themingTargets.test.ts,
scripts/check-knowledge.mjs,
]
modules: []
families: [family:navigation-destinations, family:overlay-dismissal]
-design_specs: []
+design_specs: [design:bidirectionality]
architecture:
[
architecture:component-style-authoring,
@@ -31,28 +33,52 @@ architecture:
architecture:react-component-runtime,
]
contributing: [contributing:api-conventions]
-system_specs: [spec:AST-002, spec:AST-005, spec:AST-029]
+system_specs: [spec:AST-002, spec:AST-005]
---
# BreadcrumbItem component contract
+## Contract at a glance
+
+| Area | Contract |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract | `BreadcrumbItem` with `children`, `href`, `as`, `onClick`, `isCurrent`, `startIcon`, `menu`, and `menuSize`; targets `breadcrumb-item`, `breadcrumb-item-menu-trigger`, and `breadcrumb-menu`. |
+| Behavior | One crumb: a link, a link-styled button, plain text, the current page, or a sibling-menu trigger, chosen by ORD1. It renders its own decorative separator, hidden on the first crumb. The last crumb becomes current when no crumb says otherwise. |
+| End-user impact | Users move up the hierarchy, open sibling destinations from a crumb's menu, and hear which crumb is the current page. |
+| Builder impact | None. |
+| Compatibility/readiness | Records shipped behavior; no public change. Two implementation gaps: automatic current-page state is applied after render, and can land on the list item (see Current-state impact). |
+| Review checks | Reject a current item without `aria-current="page"` on its content owner (apart from the recorded `<li>` fallback), an exposed separator, a menu without its name, state, and control link, or menu closing that steals valid outside focus. |
+| Governing rules | `component:Breadcrumbs`; `family:navigation-destinations`; `family:overlay-dismissal`; `component:Popover`; `design:bidirectionality` DR4; `architecture:react-component-runtime` INV1. |
+
+This table is a review projection; the body below is authoritative.
+
## Intent
-BreadcrumbItem presents one destination, action, current location, or sibling-menu
-trigger inside a Breadcrumbs trail. This observational draft records verified
-released behavior and current shared obligations without changing public API,
-defaults, or the component's visual design.
+BreadcrumbItem presents one destination, action, current location, or
+sibling-menu trigger inside a Breadcrumbs trail. Consumer usage lives in
+`BreadcrumbItem.doc.mjs`.
## Compatibility and migration
- Released default preserved: `yes`
-- Compatibility class: additive observational documentation plus bug fixes that
- preserve the released public surface
+- Compatibility class: records shipped behavior; no public change
- Controlled/uncontrolled behavior: not applicable
- Migration decision: none
Consumer migration instructions belong in consumer docs and release notes.
+## Current-state impact
+
+- **Automatic current state is repaired after render.** When no crumb sets
+ `isCurrent`, the last crumb first renders without `aria-current` and an
+ Effect then inspects the sibling list in the DOM and adds `aria-current="page"`.
+ `architecture:react-component-runtime` INV1 requires rendered output to start
+ from a valid state rather than be repaired in a follow-up Effect.
+- **Auto-current can land on the list item.** When the last crumb renders
+ through a custom `as` or `LinkProvider` link that does not forward its ref,
+ the auto-current repair sets `aria-current="page"` on the `<li>` and none on
+ the link, so the link is not announced as the current page (FR3, AR2).
+
## Ownership boundary
**Owns**
@@ -81,33 +107,30 @@ Consumer migration instructions belong in consumer docs and release notes.
## Public concepts
-| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
-| ------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------- | ---------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------ |
-| Item content | required `ReactNode` | Supplies the visible item label and may contain caller-owned content. | Every item branch | Required | `component:BreadcrumbItem` | Released | React renders the supplied node. |
-| Destination | supplied or absent `href` | Selects the shared link path when the item is not explicitly current and has no menu. | Default and supporting variants | Absent | `family:navigation-destinations` | Released | Shared link handling decides accepted destinations. |
-| Action | supplied or absent `onClick` | Selects a native link-styled button when no destination or menu is supplied, or augments the link path when `href` is supplied. | Non-current items | Absent | `component:BreadcrumbItem` | Released | `menu` currently suppresses this input and warns in development. |
-| Current page | `true`, `false`, or omitted | `true` explicitly marks the item current; `false` opts it out; omission makes the item an auto-current candidate. | Every branch, including a menu trigger | Omitted | `component:BreadcrumbItem` | Released observation; intent review pending | When no item is explicitly current, the omitted final item receives `aria-current="page"`. |
-| Link renderer | per-item `as`, provider renderer, or native anchor | Selects the component that receives an accepted destination. | Non-current link path | Provider renderer, then native anchor | `family:navigation-destinations` | Released | Explicitly current and menu paths do not use it. |
-| Start content | supplied or absent `startIcon` | Renders caller content before the item label. | Every item branch | Absent | Caller | Released | Caller content remains caller-owned. |
-| Sibling menu | data array, composed menu content, or absent | Replaces the link/action content branch with a menu button and menu surface. | Current or non-current item | Absent | `component:BreadcrumbItem`; menu rows delegate | Released observation; precedence review pending | Currently suppresses `href` or `onClick` and warns in development. |
-| Menu size | `sm`, `md`, or `lg` | Selects the delegated menu-row size. | Menu branch | `sm` for supporting Breadcrumbs; otherwise `md` | `component:BreadcrumbItem` | Released | TypeScript rejects unsupported values. |
+| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
+| ------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ----------------------------------------------- | ---------------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------- |
+| Item content | required `ReactNode` | Supplies the visible item label and may contain caller-owned content. | Every item branch | Required | `component:BreadcrumbItem` | Released | React renders the supplied node. |
+| Destination | supplied or absent `href` | Selects the shared link path when the item is not explicitly current and has no menu. | Default and supporting variants | Absent | `family:navigation-destinations` | Released | Shared link handling decides accepted destinations. |
+| Action | supplied or absent `onClick` | Selects a native link-styled button when no destination or menu is supplied, or augments the link path when `href` is supplied. | Non-current items | Absent | `component:BreadcrumbItem` | Released | `menu` currently suppresses this input and warns in development. |
+| Current page | `true`, `false`, or omitted | `true` explicitly marks the item current; `false` opts it out; omission makes the item an auto-current candidate. | Every branch, including a menu trigger | Omitted | `component:BreadcrumbItem` | Released | When no item is explicitly current, the last crumb receives `aria-current="page"` when it omits the prop. |
+| Link renderer | per-item `as`, provider renderer, or native anchor | Selects the component that receives an accepted destination. | Non-current link path | Provider renderer, then native anchor | `family:navigation-destinations` | Released | Explicitly current and menu paths do not use it. |
+| Start content | supplied or absent `startIcon` | Renders caller content before the item label. | Every item branch | Absent | Caller | Released | Caller content remains caller-owned. |
+| Sibling menu | data array, composed menu content, or absent | Replaces the link/action content branch with a menu button and menu surface. | Current or non-current item | Absent | `component:BreadcrumbItem`; menu rows delegate | Released | Currently suppresses `href` or `onClick` and warns in development. |
+| Menu size | `sm`, `md`, or `lg` | Selects the delegated menu-row size. | Menu branch | `sm` for supporting Breadcrumbs; otherwise `md` | `component:BreadcrumbItem` | Released | TypeScript rejects unsupported values. |
## Behavioral and layout contract
-Draft requirements identify their basis so observed code is not mistaken for an
-intentional decision.
-
-| ID | Candidate invariant | Basis | Draft review state |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
-| FR1 | The item root MUST remain one `<li>` carrying the public ref, item theme target, variant reflection, styling escape hatches, and neutral DOM pass-throughs. | Released types, source, docs, and tests; `architecture:public-component-api` | Verified current behavior; no API change proposed |
-| FR2 | A non-current item with `href` and no menu MUST use the shared link renderer; an item with only `onClick` MUST use a native button; an item with neither MUST render text content. | Released source, docs, and tests | Verified current behavior |
-| FR3 | Explicit `isCurrent=true` MUST expose `aria-current="page"`; explicit `false` MUST opt out; when every item omits the prop, the final item MUST receive the same current-page state. | Released source, docs, and tests | Verified current behavior; whether auto-detection remains the intended long-term default needs owner review |
-| FR4 | Every item MUST render one decorative separator container; the first item hides it. The built-in slash mirrors exactly once in RTL, while caller-provided separators remain caller-owned. | Source, focused tests, and objective bidi behavior | Verified current behavior |
-| FR5 | A menu item MUST expose one named menu button, current expanded state, control relationship, and one named `role="menu"` surface. Click, Enter, Space, and ArrowDown open it and focus its first item; Escape and selection close it. | APG Menu Button pattern, current Popover contract, source, tests, and browser evidence | Settled objective behavior |
-| FR6 | Closing the menu MUST preserve a newly focused outside control. Focus returns to the trigger only when the closing surface would otherwise strand focus. | `component:Popover/AR4` and browser focus behavior | Settled objective behavior |
-| FR7 | The menu branch MUST delegate item rendering, selection, typeahead, row focus, and submenu content to the shared DropdownMenu pipeline. | Released source and focused tests | Verified current behavior; DropdownMenu's draft contract remains context only |
-| FR8 | Omitted `menuSize` MUST resolve from the parent variant before entering DropdownMenu context. | Released source and consumer docs | Verified current behavior |
-| FR9 | The current local targets MUST remain `breadcrumb-item`, `breadcrumb-item-menu-trigger`, and `breadcrumb-menu`, each on its current visible style owner with `variant` reflected where applicable. | Released docs, source, and theming tests | Verified current inventory; no target change proposed |
+| ID | Invariant | Basis |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------- |
+| FR1 | The item root is one `<li>` carrying the public ref, the `breadcrumb-item` target with the trail's variant, `data-testid`, styling escape hatches, and other DOM props. | Released types, source, docs, and tests; `architecture:public-component-api` |
+| FR2 | A non-current item with `href` and no menu uses the shared link renderer, with `onClick` on the link; an item with only `onClick` uses a native button styled as a link; an item with neither renders text content. | Released source, docs, and tests |
+| FR3 | Explicit `isCurrent=true` renders the content as text (or the menu trigger) carrying `aria-current="page"` and ignores `href` and `onClick`; explicit `false` opts out; when no item in the list carries `aria-current="page"`, the list's last child, if it omits the prop, receives it on its content owner (Current-state impact records the fallback to the `<li>`); a trail whose last child sets `isCurrent={false}` has no current crumb. | Released source, docs, and tests |
+| FR4 | Every item renders one `aria-hidden` separator container before its content, hidden on the first item. The built-in `/` mirrors exactly once in RTL; caller-provided separators render as given. | Source, focused tests, and `design:bidirectionality` DR4 |
+| FR5 | A menu item exposes one menu button with `aria-haspopup="menu"`, its expanded state, and `aria-controls`, and one `role="menu"` surface labelled by the trigger, including non-string trigger content. Click, Enter, Space, and ArrowDown open it and focus its first item; Escape, Tab, and selection close it; arrows move between items without wrapping, and typeahead jumps to a matching item. | APG Menu Button pattern, `component:Popover`, source, tests, and browser evidence |
+| FR6 | Closing the menu preserves a newly focused outside control. Focus returns to the trigger only when the closing surface would otherwise strand focus. | `component:Popover` and browser focus behavior |
+| FR7 | The menu branch delegates item rendering, selection, row focus, and submenu content to the shared DropdownMenu item pipeline, from a data array or composed children. With `menu`, `href` and `onClick` are ignored and a development warning is logged. | Released source and focused tests |
+| FR8 | Omitted `menuSize` resolves to `sm` under the `supporting` variant and `md` otherwise before entering the menu pipeline. | Released source and consumer docs |
+| FR9 | The local targets are `breadcrumb-item` on the `<li>`, `breadcrumb-item-menu-trigger` on the menu button, and `breadcrumb-menu` on the menu surface; the first two reflect the trail's variant. Link, button, and menu trigger paint the shared focus outline. | Released docs, source, and theming tests |
### Allowed variation
@@ -122,15 +145,15 @@ intentional decision.
### Representative states
-| State | Required invariant | Allowed variation |
-| ---------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
-| Destination link | Shared link path, visible keyboard focus, and accepted destination behavior remain available. | Native or custom router renderer; optional start content. |
-| Action button | Native button semantics and supplied click handling remain available. | Default or supporting typography. |
-| Explicit current | Current-page state is exposed on the rendered content owner. | Plain content or menu trigger. |
-| Auto-current | The final omitted item receives current-page state only when no explicit current item exists. | Link or text content remains in its released branch. |
-| Closed menu | Trigger exposes `aria-haspopup="menu"`, controls the menu, and reports collapsed state. | Data-driven or composed rows; current or non-current trigger. |
-| Open menu | Named menu is top-layer reachable and focus enters its first eligible row. | Row kinds, submenu content, and explicit menu size. |
-| Dismissed menu | One dismissal closes the surface; valid outside focus is preserved and stranded focus returns to the trigger. | Escape, selection, Tab, or native light dismiss. |
+| State | Required invariant | Allowed variation |
+| ---------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| Destination link | Shared link path, visible keyboard focus, and accepted destination behavior remain available. | Native or custom router renderer; optional start content. |
+| Action button | Native button semantics and supplied click handling remain available. | Default or supporting typography. |
+| Explicit current | Current-page state is exposed on the rendered content owner. | Plain content or menu trigger. |
+| Auto-current | The last crumb, when it omits the prop, receives current-page state only when no explicit current item exists. | Link or text content remains in its released branch. |
+| Closed menu | Trigger exposes `aria-haspopup="menu"`, controls the menu, and reports collapsed state. | Data-driven or composed rows; current or non-current trigger. |
+| Open menu | Named menu is top-layer reachable and focus enters its first eligible row. | Row kinds, submenu content, and explicit menu size. |
+| Dismissed menu | One dismissal closes the surface; valid outside focus is preserved and stranded focus returns to the trigger. | Escape, selection, Tab, or native light dismiss. |
### Transformation and precedence order
@@ -148,10 +171,10 @@ intentional decision.
- **PR1 — Delegated layer resources.** BreadcrumbItem creates no independent global
listeners or observers; menu lifecycle and focus resources remain delegated to
Popover and shared menu hooks.
-- **PR2 — Auto-current reconciliation.** Current source reconciles omitted current
- state by inspecting the rendered sibling list after render. This is a known
- runtime-authority gap under `architecture:react-component-runtime`, not an
- approved implementation requirement.
+- **PR2 — Auto-current reconciliation.** Current source resolves omitted current
+ state by inspecting the rendered sibling list after render. This is the gap
+ recorded under Current-state impact, not an approved implementation
+ requirement.
## Accessibility contract
@@ -159,6 +182,8 @@ intentional decision.
aggregate breadcrumb semantics; each item remains one list item.
- **AR2 — Current state.** The content owner for a current item exposes
`aria-current="page"`; the list-item wrapper does not duplicate it.
+ Implementation gap: auto-current falls back to the `<li>` when a custom link
+ does not forward its ref (Current-state impact).
- **AR3 — Native interaction.** Links use link semantics, action-only items use a
native button, and menu items use the APG Menu Button relationship.
- **AR4 — Menu name.** The menu surface is labelled by its trigger, including when
@@ -182,6 +207,8 @@ intentional decision.
## Family and system relationships
+- `component:Breadcrumbs` supplies the separator and variant.
+- `design:bidirectionality` DR4 governs the built-in separator's mirroring.
- `family:navigation-destinations` owns destination inspection and handoff for
native and custom link paths. BreadcrumbItem composes the shared link owner.
- `family:overlay-dismissal` owns topmost Escape/platform-close routing.
@@ -195,19 +222,29 @@ intentional decision.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| ---------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- | --------------------------------------------- |
-| FR1–FR3, AR1–AR3 | `Breadcrumbs.test.tsx` branch, ref, pass-through, and current-state suites | Link, action, explicit current, omitted final, explicit false | A branch changes semantic element, loses current state, or moves the public root contract. | `audit:BreadcrumbItem/api-behavior` |
-| FR4, AR6 | `Breadcrumbs.test.tsx`, `BreadcrumbItem.stories.tsx`, and RTL audit | Built-in slash, bidi-mirrored glyph, explicit icon mirror, LTR and RTL | A contextual separator fails to mirror exactly once or becomes exposed to AT. | `audit:BreadcrumbItem/rtl` |
-| FR5–FR8, AR3–AR5 | `Breadcrumbs.test.tsx` plus real-browser story evidence | String and ReactNode labels, click/keyboard open, rows, selection, Escape, outside dismiss | A menu loses its name/state, focus enters the wrong owner, or dismissal steals valid outside focus. | `audit:BreadcrumbItem/accessibility-behavior` |
-| FR9 | `themingTargets.test.ts`, source inspection, and rendered theme evidence | Item, menu trigger, menu surface; default/supporting | A target disappears, moves to non-painting plumbing, or loses variant reflection. | `audit:BreadcrumbItem/theming` |
-| Draft structure | `scripts/check-knowledge.mjs` | Required schema and current relationship links | Missing sections, stale links, or accidental current authority fail validation. | `audit:BreadcrumbItem/knowledge` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ---------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- | --------------------------------------------- |
+| FR1–FR3, AR1–AR3 | `Breadcrumbs.test.tsx` branch, test-id, and current-state suites | Link, action, explicit current, omitted last crumb | A branch changes semantic element, loses current state, or moves the public root contract. | `audit:BreadcrumbItem/api-behavior` |
+| FR4, AR6 | `Breadcrumbs.test.tsx` separator, mirror-style class, and custom-separator tests | Built-in slash, custom separator | A contextual separator fails to mirror exactly once or becomes exposed to AT. | `audit:BreadcrumbItem/rtl` |
+| FR5–FR8, AR3–AR5 | `Breadcrumbs.test.tsx` menu suites | String and ReactNode labels, click/keyboard open, rows, selection, Escape, outside dismiss | A menu loses its name/state, focus enters the wrong owner, or dismissal steals valid outside focus. | `audit:BreadcrumbItem/accessibility-behavior` |
+| FR9 | `Breadcrumbs.test.tsx` theme-target tests; `themingTargets.test.ts` | Item, menu trigger, menu surface; default/supporting | A target disappears, moves to non-painting plumbing, or loses variant reflection. | `audit:BreadcrumbItem/theming` |
+| AR1–AR2 | `Breadcrumbs.a11y.test.tsx` and `Breadcrumbs.a11y.chromium.spec.ts` | Trail, explicit current, auto current, opt-out | A role, name, state, or focus expectation regresses. | `audit:BreadcrumbItem/accessibility-behavior` |
+
+Read from source, with no focused test yet:
+
+- FR1: the item `ref` and other DOM props on the `<li>`.
+- FR3: a last crumb with `isCurrent={false}` leaving the trail with no current
+ crumb.
+- FR4: the built-in slash mirroring exactly once in a right-to-left layout.
+- FR5: Enter and Space opening the menu, a click focusing the first row, Tab
+ closing the menu, arrows stopping at the ends without wrapping, and typeahead.
+- FR7: `onClick` being ignored beside `menu`.
+- FR8.
+- FR9: the shared focus outline on the link, button, and menu trigger.
## Decision log
-None. This draft records observed released behavior and objective shared
-requirements; it makes no component-local API, default, compatibility, ownership,
-or visual-design decision.
+No component-local decision is recorded.
## Open questions
diff --git a/packages/core/src/Breadcrumbs/Breadcrumbs.spec.md b/packages/core/src/Breadcrumbs/Breadcrumbs.spec.md
new file mode 100644
index 0000000000..8b779c985c
--- /dev/null
+++ b/packages/core/src/Breadcrumbs/Breadcrumbs.spec.md
@@ -0,0 +1,165 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:Breadcrumbs
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-27
+owners: [cixzhang]
+review_triggers: [public-api, behavior, layout, theming, accessibility]
+verified_by:
+ [
+ packages/core/src/Breadcrumbs/Breadcrumbs.test.tsx,
+ packages/core/src/Breadcrumbs/__tests__/Breadcrumbs.a11y.test.tsx,
+ packages/core/src/Breadcrumbs/__tests__/Breadcrumbs.a11y.chromium.spec.ts,
+ apps/storybook/stories/Breadcrumbs.stories.tsx,
+ ]
+modules: []
+families: []
+design_specs: [design:bidirectionality]
+architecture:
+ [architecture:component-theming-surface, architecture:public-component-api]
+contributing: []
+system_specs: [spec:AST-038]
+---
+
+# Breadcrumbs component contract
+
+## Contract at a glance
+
+| Area | Contract |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Public contract | `Breadcrumbs` with `children`, `separator` (default `/`), `variant` (`default`, `supporting`, or an augmented value; default `default`), and `label`; target `breadcrumbs` with `variant`. |
+| Behavior | A labeled navigation landmark holding an ordered list of BreadcrumbItem children; it tells every item in its own surface the separator and variant to use. |
+| End-user impact | Screen-reader users find the trail as a named "Breadcrumb" landmark and hear it as an ordered list; sighted users see one consistent separator and size across the trail. |
+| Builder impact | None. |
+| Compatibility/readiness | Records shipped behavior; no public change. |
+| Review checks | Reject an unlabeled landmark, a trail that is not an ordered list, or items in the trail's own surface that ignore its separator or variant. |
+| Governing rules | `component:BreadcrumbItem` (each item); `design:bidirectionality` DR4 (separator mirroring); `architecture:component-theming-surface`. |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+Breadcrumbs shows where a page sits in a hierarchy. It owns the trail's
+landmark, list, label, separator, and variant; each crumb's behavior belongs to
+BreadcrumbItem. Consumer usage lives in `Breadcrumbs.doc.mjs`.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: records shipped behavior; no public change
+- Controlled/uncontrolled behavior: not applicable
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The navigation landmark, its label, the ordered list, its wrapping layout, and
+ the separator and variant every item in its own surface receives (FR1–FR4).
+
+**Does not own / non-goals**
+
+- Each crumb's element, current-page state, separator rendering, menu, and the
+ `breadcrumb-item`, `breadcrumb-item-menu-trigger`, and `breadcrumb-menu`
+ targets — owned by `component:BreadcrumbItem`.
+- Destination handling — owned by `family:navigation-destinations` through
+ BreadcrumbItem.
+- Truncating or collapsing long trails — not provided; the list wraps.
+
+## Public concepts
+
+| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
+| --------- | ----------------------------------------- | ----------------------------------------------- | ----------------------------------------- | --------- | ----------------------- | --------- | ------------------------------------------------------------- |
+| Variant | `default`, `supporting`, augmented values | Body or supporting text size for every item. | Whole trail. | `default` | `component:Breadcrumbs` | Stable | A value other than `supporting` gets default sizing on items. |
+| Separator | any node; `/` by default | Glyph shown before every item except the first. | Whole trail. | `/` | `component:Breadcrumbs` | Stable | Rendered as given. |
+
+## Behavioral and layout contract
+
+| ID | Invariant | Basis |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| FR1 | Breadcrumbs renders one `<nav>` named by `label`, else the translated `@astryx.breadcrumbs.label` ("Breadcrumb"); a caller `aria-label` or `aria-labelledby` replaces that name. It carries `breadcrumbs` with `variant`, the forwarded `ref`, `data-testid`, and other DOM props. | Current source and tests |
+| FR2 | The `<nav>` contains one `<ol>` that holds `children`; the list has no markers or inset and lays items out in a row that wraps. | Current source and tests |
+| FR3 | Every descendant BreadcrumbItem in the trail's own surface receives the trail's `separator` and `variant`; a crumb rendered inside a layer gets the defaults, as `spec:AST-038` FR7 requires. | Current source and tests |
+| FR4 | `className`, `style`, and `xstyle` merge onto the `<nav>` after component styles. | Current source |
+
+### Allowed variation
+
+- **AV1 — Separator.** Any node may replace `/`.
+- **AV2 — Theme styling.** Themes restyle `breadcrumbs` per variant.
+
+### Representative states
+
+| State | Required invariant | Allowed variation |
+| ------------------ | --------------------------------------------- | ----------------- |
+| Default trail | Named landmark; ordered list; `/` separators. | Item content. |
+| Supporting variant | Items use supporting size. | — |
+| Custom separator | Items show the given separator. | Glyph. |
+| Narrow container | Items wrap onto more lines. | Line count. |
+
+### Transformation and precedence order
+
+- **ORD1 — Label.** A caller `aria-label` or `aria-labelledby`, then `label`,
+ then the translated default.
+
+### Performance and resources
+
+- No resource rule.
+
+## Accessibility contract
+
+- **AR1 — Landmark and list.** FR1 and FR2: one named navigation landmark with
+ an ordered list of crumbs.
+
+## Design relationships
+
+| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
+| ---------------- | -------------------------------- | ------------------------------ | -------------- | ------------------ |
+| Trail | Wrapping row of crumbs. | Current source and public docs | Supporting | FR1, FR2 |
+| Item | One crumb. | `component:BreadcrumbItem` | Supporting | FR3 |
+| Separator | Trail-wide glyph between crumbs. | `component:BreadcrumbItem` | Supporting | FR3 |
+| Icon | Optional crumb start content. | `component:BreadcrumbItem` | Supporting | — |
+
+No anatomy-theming map is recorded yet; the block is optional during migration.
+Mapping the four anatomy parts against the four targets `Breadcrumbs.doc.mjs`
+lists, three of which BreadcrumbItem owns, by delegation, is deferred.
+
+## Family and system relationships
+
+- `component:BreadcrumbItem` renders each crumb and its separator.
+- `design:bidirectionality` DR4 governs the default separator's mirroring, which
+ BreadcrumbItem implements.
+
+## Verification map
+
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| -------- | ------------------------------------------------------------------ | ------------------------------------- | ------------------------------------------ | --------------------------------- |
+| FR1, AR1 | `Breadcrumbs.test.tsx` landmark tests; `Breadcrumbs.a11y.test.tsx` | Default and custom label | A missing landmark or name fails. | `audit:Breadcrumbs/accessibility` |
+| FR2 | `Breadcrumbs.test.tsx` ordered-list test | Several items | A non-list trail fails. | `audit:Breadcrumbs/anatomy` |
+| FR3 | `Breadcrumbs.test.tsx` separator and variant tests | Default, custom separator, supporting | Items that ignore the trail settings fail. | `audit:Breadcrumbs/behavior` |
+| FR1 | `Breadcrumbs.test.tsx` ref and test-id tests | Root props | Dropped ref or test id fails. | `audit:Breadcrumbs/api` |
+
+Read from source, with no focused test yet: crumbs inside a layer getting the
+defaults (FR3); the `breadcrumbs` target and its
+`variant` state, other DOM props, and a caller `aria-label` or
+`aria-labelledby` replacing the name (FR1); the list's markers, inset, and
+wrapping row (FR2); and FR4.
+
+## Decision log
+
+No component-local decision is recorded.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables, examples, or item behavior. It
+links to their owners.