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.mdindex 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: 7kind: componentid: component:BreadcrumbItem-authority: draft+authority: currentarchive_reason: nullsuperseded_by: null-approved_by: null-approved_at: null+approved_by: cixzhang+approved_at: 2026-10-27owners: [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: noneConsumer 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 globallisteners or observers; menu lifecycle and focus resources remain delegated toPopover 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 anative 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 fornative 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 questionsdiff --git a/packages/core/src/Breadcrumbs/Breadcrumbs.spec.md b/packages/core/src/Breadcrumbs/Breadcrumbs.spec.mdnew file mode 100644index 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.