@astryxdesign/core 0.7.5 → 0.7.6-canary.0d71e8d

package/src/Link/__tests__/Link.a11y.chromium.spec.ts

@@ -113,17 +113,27 @@ async function runState(
   });
 }
 
-test('every Link expectation is exercised by at least one Link state', async ({
-  page,
-}) => {
-  // Mounts every state in one test, so it gets every state's time budget.
-  test.setTimeout(30_000 * LINK_A11Y_STATES.length);
-  const cdp = await page.context().newCDPSession(page);
+// Checking coverage runs every state again, which on a loaded runner nears
+// the per-test timeout as one test. It runs as one serial part per state,
+// sharing their results, then one check over all of them.
+test.describe('every Link expectation is exercised by at least one Link state', () => {
+  test.describe.configure({mode: 'serial'});
   const results: BindingResult[] = [];
+
   for (const state of LINK_A11Y_STATES) {
-    results.push(await runState(page, cdp, state));
+    test(`runs ${state.id}`, async ({page}) => {
+      const cdp = await page.context().newCDPSession(page);
+      results.push(await runState(page, cdp, state));
+    });
   }
-  expect(neverExercised(results)).toEqual([]);
+
+  test('no expectation is left unexercised', () => {
+    // Every part ran in this worker; this test alone proves nothing.
+    expect(results.map(result => result.state).sort()).toEqual(
+      LINK_A11Y_STATES.map(state => state.id).sort(),
+    );
+    expect(neverExercised(results)).toEqual([]);
+  });
 });
 
 for (const state of LINK_A11Y_STATES) {

package/src/Link/__tests__/Link.truncation.a11y.chromium.spec.ts

@@ -0,0 +1,58 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y scope ^(packages/core/src/Link/|packages/core/src/Text/|apps/storybook/stories/Link\.stories)
+
+/**
+ * Real-browser evidence for `component:Link` FR6 with `component:Text` FR4: a
+ * Link with `maxLines={1}` in a fixed-width line, as an anchor and as a
+ * button, stops at the line and its label overflows with an ellipsis.
+ */
+
+import {expect, test} from '@playwright/test';
+import {
+  DEFAULT_STORYBOOK_DIR,
+  serveStorybook,
+  type StaticServer,
+} from '@astryxdesign/a11y-spec/storybook';
+
+let storybook: StaticServer;
+
+test.beforeAll(async () => {
+  storybook = await serveStorybook(
+    process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,
+  );
+});
+
+test.afterAll(async () => storybook?.close());
+
+for (const form of ['anchor', 'button'] as const) {
+  test(`a ${form} Link with maxLines={1} truncates inside a fixed-width line`, async ({
+    page,
+  }) => {
+    await page.goto(
+      `${storybook.origin}/iframe.html?id=core-link--truncated-in-constrained-line&viewMode=story`,
+    );
+    const line = page.locator(`[data-truncation-line="${form}"]`);
+    await expect(line).toBeVisible();
+    const measured = await line.evaluate(el => {
+      const root = el.firstElementChild as HTMLElement;
+      const label = root.firstElementChild as HTMLElement;
+      const style = getComputedStyle(label);
+      return {
+        tag: root.tagName,
+        line: el.getBoundingClientRect().width,
+        root: root.getBoundingClientRect().width,
+        labelClient: label.clientWidth,
+        labelScroll: label.scrollWidth,
+        textOverflow: style.textOverflow,
+      };
+    });
+    expect(measured.tag, 'the Link renders its own element').toBe(
+      form === 'anchor' ? 'A' : 'BUTTON',
+    );
+    // The root stops at the line instead of growing to its whole text.
+    expect(measured.root).toBeLessThanOrEqual(measured.line + 0.5);
+    // The label itself overflows and draws the ellipsis.
+    expect(measured.labelScroll).toBeGreaterThan(measured.labelClient);
+    expect(measured.textOverflow).toBe('ellipsis');
+  });
+}

package/src/List/List.tsx

@@ -29,7 +29,7 @@ import {
   type ListEdge,
   type ListMarkerStyle,
 } from './ListContext';
-import {mergeProps} from '../utils';
+import {mergeProps} from '../utils/mergeProps';
 import {themeProps} from '../utils/themeProps';
 import {useDevWarning} from '../hooks/useDevWarning';
 

package/src/List/ListItem.spec.md

@@ -0,0 +1,205 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:ListItem
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-31
+owners: [cixzhang]
+review_triggers: [public-api, behavior, layout, theming]
+verified_by:
+  [
+    packages/core/src/List/List.test.tsx,
+    packages/core/src/theme/themingTargets.test.ts,
+    scripts/check-knowledge.mjs,
+  ]
+modules: []
+families: [family:navigation-destinations]
+design_specs: []
+architecture:
+  [
+    architecture:component-style-authoring,
+    architecture:component-theming-surface,
+    architecture:public-component-api,
+  ]
+contributing: []
+system_specs: [spec:AST-057, spec:AST-103]
+---
+
+# ListItem component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                                                                                                                                                                                           |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Public contract         | `ListItem` with `label`, `description`, `startContent`, `endContent`, `onClick`, `interactiveRef`, `href`, `target`, `rel`, `align`, `isDisabled`, `isSelected`, `swipeActions`, `swipeBehavior`, `xstyle`, `className`, `style`, and `ref`; the row carries `component:List`'s `list-item` target. `itemKey` (`spec:AST-103` DEC-4) is specified but not shipped. |
+| Behavior                | One `<li>` row rendered by `component:Item`, which receives every row prop. Inside a List the row takes the list's density, dividers, edge treatment, and marker; outside a List it uses Item's defaults and draws no marker.                                                                                                                                      |
+| End-user impact         | Each list entry reads as one list item, with the list's bullet, number, or task checkbox before it and the same interaction Item gives any row.                                                                                                                                                                                                                    |
+| Builder impact          | None.                                                                                                                                                                                                                                                                                                                                                              |
+| Compatibility/readiness | Records shipped behavior; no public change. Two implementation gaps, listed under Current-state impact.                                                                                                                                                                                                                                                            |
+| Review checks           | Reject a row that is not an `<li>`, a ListItem-level edge, density, or divider prop, a marker drawn outside a marked List, or a dropped Item prop.                                                                                                                                                                                                                 |
+| Governing rules         | `component:Item` (`align` for start and end content); `component:List`; `family:navigation-destinations`; `spec:AST-057`; `spec:AST-103`; `architecture:component-theming-surface`; `architecture:component-style-authoring` INV7.                                                                                                                                 |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+ListItem is the row a List renders for each entry. It owns turning a row into
+a list item: the `<li>` element, what it reads from its List, the marker drawn
+before it, and how it applies `component:List`'s `list-item` target. Everything a row does as a row comes
+from `component:Item`. Consumer usage lives in `ListItem.doc.mjs`.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: records shipped behavior; no public change
+- Controlled/uncontrolled behavior: not applicable; `isSelected` and
+  `isDisabled` are caller-owned
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Current-state impact
+
+- **Markers are extra elements.** A bullet marker is drawn as two decorative
+  `span` elements, and a number marker as one `span` carrying a counter
+  pseudo-element, beside the row's content. `architecture:component-style-authoring`
+  INV7 carries decoration with no semantic role on a pseudo-element rather than
+  an added element.
+- **ListItem has no `itemKey` yet.** `spec:AST-103` DEC-4 and `component:List`
+  FR12 have each reorderable row name its item through an `itemKey` prop;
+  ListItem does not accept one yet.
+
+## Ownership boundary
+
+**Owns**
+
+- Rendering the row as an `<li>` through `component:Item` and passing it every
+  row prop (FR1).
+- Reading density, dividers, edge treatment, and marker from the enclosing
+  List, and the defaults outside one (FR2, FR3).
+- Drawing the marker or a task item's read-only checkbox (FR4).
+- Applying `component:List`'s `list-item` target to the row (FR5).
+
+**Does not own / non-goals**
+
+- `align`, the start and end content's alignment — owned by `component:Item`; swipe actions — owned by
+  `spec:AST-057`; link destinations — owned by
+  `family:navigation-destinations`, of which ListItem is a member.
+- Item's label, description, slots, invisible button, delegated activation,
+  and disabled and selected semantics — Item's shipped behavior, uncontracted
+  here.
+- What each edge treatment does to row geometry and the row inset, the touch
+  target, press paint, row motion, and row menus — owned by `component:List`.
+- The `ListMarkerScope` that sets a marker or task state for Markdown's nested
+  lists — internal and uncontracted here.
+- Whole number markers and text alignment for Markdown lists — owned by
+  `spec:AST-061` FR11 and `component:List` DEC-5.
+
+## Public concepts
+
+No component-local concept beyond the consumer props; row props are
+`component:Item`'s.
+
+## Behavioral and layout contract
+
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                               | Basis                    |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| FR1 | ListItem renders `component:Item` as an `<li>` and passes `label`, `description`, `startContent`, `endContent`, `onClick`, `interactiveRef`, `href`, `target`, `rel`, `align`, `isDisabled`, `isSelected`, `swipeActions`, `swipeBehavior`, and `ref` to it unchanged, with other DOM and data props reaching the row.                                                                                                                                  | Current source and tests |
+| FR2 | Inside a List, the row takes the list's `density`, its `hasDividers` setting, which draws a divider between rows with no extra element and square corners, and its `edge` treatment.                                                                                                                                                                                                                                                                    | Current source and tests |
+| FR3 | Outside a List, the row uses `balanced` density, no dividers, the `padded` treatment, and no marker, keeping Item's inline inset.                                                                                                                                                                                                                                                                                                                       | Current source and tests |
+| FR4 | In a List whose `listStyle` is `disc`, `circle`, or `decimal`, the row draws that marker before its content: a disc or circle shape, or a counter number. A task state set for the row draws a read-only, labelled checkbox in the marker's place. Each marker and the task checkbox sit on the label's first line. A List whose `listStyle` is `none` draws neither. Other markers, set internally for Markdown's nested lists, are uncontracted here. | Current source and tests |
+| FR5 | The row carries `component:List`'s `list-item` target, merged with the caller's `className` and `style`; `xstyle` applies after ListItem's own styles.                                                                                                                                                                                                                                                                                                  | Current source           |
+
+### Allowed variation
+
+- **AV1 — Row content.** Label, description, and slot content vary.
+- **AV2 — Theme styling.** Themes restyle `list-item`.
+
+### Representative states
+
+| State                | Required invariant                               | Allowed variation |
+| -------------------- | ------------------------------------------------ | ----------------- |
+| Static row in a List | One `<li>`; no button or anchor.                 | Content.          |
+| Interactive row      | Item's invisible button or anchor; one tab stop. | Content.          |
+| Divided list         | A divider between rows; square corners.          | Density.          |
+| Numbered list        | A counter number before each row.                | Number style.     |
+| Task row             | A read-only checkbox in the marker's place.      | Checked state.    |
+| Row outside a List   | Item's inline inset; no marker.                  | Content.          |
+
+### Transformation and precedence order
+
+- **ORD1 — Marker.** No marker when the List's `listStyle` is `none`; otherwise
+  a task checkbox when the row has a task state, then the marker.
+- **ORD2 — Styling.** ListItem's own styles, then the caller's `xstyle`.
+
+### Performance and resources
+
+- No resource rule.
+
+## Accessibility contract
+
+- **AR1 — List semantics.** Inside a List, each row is an `<li>` in the List's
+  `<ul>` or `<ol>` (FR1).
+- **AR2 — Row semantics.** Item's interaction, disabled, and selected semantics
+  apply unchanged; they are Item's shipped behavior, uncontracted here.
+- **AR3 — Task state.** A task row's checkbox is read-only and labelled (FR4).
+
+## Design relationships
+
+| Anatomy or state | Design requirement                              | Representation authority | Hierarchy role | Component contract |
+| ---------------- | ----------------------------------------------- | ------------------------ | -------------- | ------------------ |
+| Row              | Presents one list entry through Item.           | `component:Item`         | Prominent      | FR1, FR5           |
+| Marker           | Shows the list's bullet, number, or task state. | Current source           | Supporting     | FR4                |
+
+No anatomy-theming map is recorded yet; the block is optional during
+migration, so the map is deferred.
+
+## Family and system relationships
+
+- `component:Item` owns `align`, the start and end content's alignment; its
+  other row behavior is
+  uncontracted. `spec:AST-057` owns swipe actions and
+  `family:navigation-destinations` owns link destinations.
+- `component:List` owns the edge treatment and its row geometry and inset;
+  its record leaves the density, divider, and marker-style settings
+  uncontracted, and FR2 and FR4 here cover what a row does with them.
+- `architecture:component-theming-surface` owns target qualification;
+  `component:List` owns the `list-item` target, and FR5 covers how the row
+  applies it.
+
+## Verification map
+
+| Contract | Verification                                                                     | Representative states                          | Mutation or failure expectation                        | Audit section                  |
+| -------- | -------------------------------------------------------------------------------- | ---------------------------------------------- | ------------------------------------------------------ | ------------------------------ |
+| FR1, AR1 | `List.test.tsx` row element, align, data attribute, and swipe pass-through tests | Static and interactive rows                    | A row that is not an `<li>`, or a dropped prop, fails. | `audit:ListItem/behavior`      |
+| FR2      | `List.test.tsx` density, divider, radius, and edge treatment tests               | Each density; dividers on and off; each edge   | A row that ignores its List's settings fails.          | `audit:ListItem/layout`        |
+| FR3      | `List.test.tsx` "keeps the inset of a ListItem outside a List"                   | Row outside a List                             | A row outside a List that loses its inset fails.       | `audit:ListItem/layout`        |
+| FR4, AR3 | `List.test.tsx` marker and ListMarkerScope tests                                 | Presence of a marker, none, scope marker, task | A missing, extra, or unlabelled marker fails.          | `audit:ListItem/anatomy`       |
+| AR2      | `List.test.tsx` invisible button, anchor, disabled, and selection tests          | Click, href, disabled, selected                | Lost row semantics fail.                               | `audit:ListItem/accessibility` |
+
+Read from source, with no focused test yet:
+
+- FR1: `interactiveRef`, `rel`, and `ref` reaching the Item row.
+- FR2: the divider border and square corners.
+- FR4: each marker and the task checkbox sitting on the label's first line.
+- FR3: `balanced` density, no dividers, and no marker outside a List.
+- FR4: the shape of each bullet marker (the disc's fill, the circle's ring),
+  and the number marker and its counter.
+- FR5: the `list-item` target, and `xstyle` applying after ListItem's styles.
+
+## Decision log
+
+No component-local decision is recorded.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables, Item's row behavior, or
+List's edge and geometry rules. It links to their owners.

package/src/List/ListItem.tsx

@@ -39,9 +39,9 @@ import {
 } from '../theme/tokens.stylex';
 import type {BaseProps} from '../BaseProps';
 import {ListContext, type ListMarker} from './ListContext';
-import {CheckboxInput} from '../CheckboxInput';
-import {mergeProps} from '../utils';
-import {Item} from '../Item';
+import {CheckboxInput} from '../CheckboxInput/CheckboxInput';
+import {mergeProps} from '../utils/mergeProps';
+import {Item} from '../Item/Item';
 import {ItemMarkerColumnsContext} from '../Item/ItemMarkerColumnsContext';
 import type {ItemAlign, ItemSwipeActions, ItemSwipeBehavior} from '../Item';
 import {themeProps} from '../utils/themeProps';

package/src/Markdown/plugins/headingLinks.a11y.chromium.spec.ts

@@ -21,7 +21,7 @@ import {
   type StaticServer,
 } from '@astryxdesign/a11y-spec/storybook';
 
-const STORY = 'core-markdown-plugins-heading-links--overview';
+const STORY = 'core-markdown--heading-links';
 const OUTPUT = path.resolve('test-results/markdown-heading-links');
 const GEOMETRY_TOLERANCE_PX = 1;
 let storybook: StaticServer;

package/src/MetadataList/MetadataList.spec.md

@@ -0,0 +1,187 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:MetadataList
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-31
+owners: [cixzhang]
+review_triggers: [public-api, behavior, layout, theming, accessibility]
+verified_by:
+  [
+    packages/core/src/MetadataList/MetadataList.test.tsx,
+    packages/core/src/theme/themingTargets.test.ts,
+    .github/visual-baseline/manifest.json,
+    scripts/check-knowledge.mjs,
+  ]
+modules: []
+families: []
+design_specs: []
+architecture:
+  [architecture:component-theming-surface, architecture:public-component-api]
+contributing: []
+system_specs: [spec:AST-009]
+---
+
+# MetadataList component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                           |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | `children` (MetadataListItem entries), `columns`, `label` (`position`, `width`), `maxNumOfItems`, `orientation`, `title`, root `BaseProps`, `ref`. |
+| Behavior                | A description list of label and value pairs in one column, several columns, or a wrapping row, with an optional show more and show less toggle.    |
+| End-user impact         | People scan labelled facts in a predictable grid, and assistive technology reads each label with its value.                                        |
+| Builder impact          | None; the record describes shipped behavior.                                                                                                       |
+| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes.                                                                         |
+| Review checks           | Reject a list that is not a `dl`, a toggle without its expanded state or controlled list, an unlocalized toggle label, or overridable reflection.  |
+| Governing rules         | `architecture:public-component-api` INV5–INV8; `architecture:component-theming-surface`; WCAG 2.2 SC 1.3.1 and 4.1.2.                              |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+MetadataList presents read-only key and value facts as a description list. It
+owns the arrangement of its entries, the label placement it passes to them, and
+the optional disclosure that collapses a long list; callers own the facts.
+
+Consumer syntax and examples belong in `MetadataList.doc.mjs`.
+
+## Compatibility and migration
+
+- Released default preserved: `yes` — one column, vertical, labels at the
+  start, no collapse.
+- Compatibility class: records shipped behavior; no public prop, default, DOM,
+  target, or styling output changes.
+- Controlled/uncontrolled behavior: the expanded state of the disclosure is
+  uncontrolled.
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The root, its `metadata-list` target, the optional title, the `dl`, and
+  the show more and show less toggle.
+- Column layout, orientation, and the label position and width its entries
+  read.
+
+**Does not own / non-goals**
+
+- Each entry's label and value markup — owned by `component:MetadataListItem`.
+- The facts shown and their formatting — owned by the caller.
+- Editable fields — owned by form components.
+
+## Public concepts
+
+| Concept        | Closed values or states            | Meaning                                                                                                   | Availability by variant/orientation/state            | Default                                                  | Owner                    | Stability | Invalid-value behavior                                              |
+| -------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | -------------------------------------------------------- | ------------------------ | --------- | ------------------------------------------------------------------- |
+| Columns        | `single`; `multi`; positive number | One column, auto-filling columns, or exactly N columns.                                                   | Vertical only                                        | `single`                                                 | `component:MetadataList` | Stable    | 1 acts as `single`; a number below 1 falls to the `multi` template. |
+| Orientation    | `vertical`; `horizontal`           | A grid of entries, or one wrapping row of stacked entries.                                                | Always                                               | `vertical`                                               | `component:MetadataList` | Stable    | Closed union; rejected by types.                                    |
+| Label position | `start`; `top`                     | Label beside its value, or stacked above it.                                                              | Vertical only                                        | `top` for `multi` or a number above 1, otherwise `start` | `component:MetadataList` | Stable    | Horizontal always stacks.                                           |
+| Label width    | number (px); CSS length string     | The label track's width; on `multi` it replaces the auto-fill grid with one label and value pair per row. | Vertical with start labels, at one column or `multi` | content width                                            | `component:MetadataList` | Stable    | —                                                                   |
+| Collapse       | positive number; unset             | Entries shown before a show more toggle.                                                                  | Vertical only                                        | unset                                                    | `component:MetadataList` | Stable    | Ignored when horizontal.                                            |
+| Title          | ReactNode; unset                   | Content shown above the list.                                                                             | Always                                               | unset                                                    | `component:MetadataList` | Stable    | —                                                                   |
+
+## Behavioral and layout contract
+
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Basis                                                                   |
+| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| FR1 | MetadataList renders a root `div` carrying the `metadata-list` target, which reflects `columns` and `orientation`, holding the optional title, a `dl` of the entries, and, when the list collapses, a toggle button. The title renders above the list with a `--spacing-3` gap as plain content; it is not a heading and does not name the list.                                                                                                                                                                                                                                                                                                                                          | Current source and tests                                                |
+| FR2 | Vertical, one column with start labels is a two-track grid (label `auto`, value `minmax(0, 1fr)`) with `--spacing-2` row and `--spacing-4` column gaps and baseline alignment; a label `width` replaces the label track, and on `multi` with start labels a `width` replaces the auto-fill grid with the same two tracks. One column with top labels is a single track with a `--spacing-3` gap. `multi` auto-fills 280px-minimum columns with a `--spacing-4` gap. A number N above 1 makes exactly N columns, each `1fr` with top labels or a label `auto` and value `minmax(0, 1fr)` pair with start labels, ignoring a label `width`; a number below 1 falls to the `multi` template. | Current source and tests                                                |
+| FR3 | Label position defaults to `top` for `multi` or a number above 1 and to `start` otherwise (including a number below 1), and a caller `position` wins. Horizontal orientation lays entries in one wrapping row with a `--spacing-4` gap, stacks every label above its value, and ignores `columns` and `maxNumOfItems`.                                                                                                                                                                                                                                                                                                                                                                    | Current source and tests                                                |
+| FR4 | When vertical and the entries exceed `maxNumOfItems`, only the first `maxNumOfItems` render, followed by a native button labelled with the localized "Show more", with `aria-expanded="false"` and `aria-controls` naming the `dl`. Activating it renders every entry and switches to "Show less" with `aria-expanded="true"`; activating it again collapses. Focus stays on the button.                                                                                                                                                                                                                                                                                                  | Current source and tests; `architecture:public-component-api`           |
+| FR5 | `ref`, DOM, data, ARIA, and event props, `xstyle`, `className`, and `style` reach or compose on the root; the reflected `data-columns` and `data-orientation` replace a caller's values.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Current source and tests; `architecture:public-component-api` INV5–INV8 |
+
+### Allowed variation
+
+- **AV1 — Facts.** Any MetadataListItem content may fill the list.
+- **AV2 — Title.** Any ReactNode, including a caller's heading, may be the
+  title.
+
+### Representative states
+
+| State      | Required invariant                                                   | Allowed variation |
+| ---------- | -------------------------------------------------------------------- | ----------------- |
+| One column | Label and value tracks; labels at the start.                         | Label width.      |
+| N columns  | Exactly N columns; labels on top by default.                         | N.                |
+| Horizontal | One wrapping row; labels stacked; no toggle.                         | —                 |
+| Collapsed  | First `maxNumOfItems` entries; "Show more"; `aria-expanded="false"`. | Locale.           |
+| Expanded   | Every entry; "Show less"; `aria-expanded="true"`.                    | Locale.           |
+
+### Transformation and precedence order
+
+- **ORD1 — Label position.** Horizontal → top; otherwise caller `position` →
+  `top` for `multi` or a number above 1 → `start`.
+- **ORD2 — Columns.** Horizontal → no grid; N above 1 → exactly N columns (N tracks with top labels, N label and value pairs with start labels); a
+  start-label `width` → that label track; otherwise the static template.
+
+### Performance and resources
+
+- **PR1 — Local state only.** MetadataList holds one expanded flag and one
+  generated id, and adds no listener, observer, timer, or measurement.
+
+## Accessibility contract
+
+- **AR1 — Description list semantics.** Entries are `dt` and `dd` pairs inside
+  one `dl`, so assistive technology reads each label with its value
+  (WCAG 2.2 SC 1.3.1).
+- **AR2 — Disclosure state.** The toggle is a native button exposing its
+  expanded state and the list it controls (WCAG 2.2 SC 4.1.2).
+- **AR3 — Localized labels.** The toggle's text comes from the translation
+  catalog, never assembled in the component.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                          | Representation authority     | Hierarchy role | Component contract |
+| ---------------- | ------------------------------------------- | ---------------------------- | -------------- | ------------------ |
+| Title            | Optional content above the list.            | Current source and docs      | Supporting     | FR1                |
+| Label            | The key of each entry.                      | `component:MetadataListItem` | Supporting     | FR2, FR3           |
+| Metadata         | The value of each entry.                    | `component:MetadataListItem` | Prominent      | FR2, FR3           |
+| Disclosure       | Show more or show less in the accent color. | Current source and docs      | Supporting     | FR4                |
+
+Theming: the root carries the `metadata-list` target, which reflects `columns`
+and `orientation`, and each entry carries the `metadata-list-item` target
+(`component:MetadataListItem`). `MetadataList.doc.mjs` names no root anatomy
+part for the `metadata-list` target, so no anatomy-theming block is declared
+here; the Title, value cell, and Disclosure carry no target.
+
+## Family and system relationships
+
+- `component:MetadataListItem` owns entry markup and reads the label position
+  this record resolves.
+- `architecture:component-theming-surface` owns target and anatomy mapping.
+- `architecture:public-component-api` owns caller-input routing; FR5 applies
+  it.
+- `spec:AST-009` owns accessibility-tree evidence; the verification map names
+  its gap.
+
+## Verification map
+
+| Contract        | Verification                                                                                                                                   | Representative states                                      | Mutation or failure expectation                                                                                                                                                                                                                                                                                                   | Audit section                 |
+| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
+| FR1, AR1        | `MetadataList.test.tsx` description-list, `dl`, and title tests; stable visual baselines `core-metadatalist--basic` (neutral and probe themes) | Items; title                                               | A missing `dl`, `dt`, or `dd`, or a missing title, fails; a changed default layout comes back changed for review. Gap: no accessibility-tree check proves the term and definition pairing (`spec:AST-009` FR3).                                                                                                                   | `audit:MetadataList/a11y`     |
+| FR2, ORD2       | `MetadataList.test.tsx` numeric-column and label-width tests                                                                                   | N columns with top and start labels; `multi`; custom width | A wrong inline grid template for N columns or a label width, or a `repeat(` inline template for `multi`, fails. Gap: the static one-column and `multi` templates and the gaps have no unit check beyond the default baseline. No test covers a width beside N columns with start labels, a width on `multi`, or a number below 1. | `audit:MetadataList/layout`   |
+| FR3, ORD1       | `MetadataList.test.tsx` orientation and default-position tests                                                                                 | Horizontal; omitted position; `columns={2}`                | A horizontal list without stacked labels or with a toggle, or a wrong default position, fails. No test covers `multi`'s top-label default or a number below 1's start-label default.                                                                                                                                              | `audit:MetadataList/layout`   |
+| FR4, AR2, AR3   | `MetadataList.test.tsx` show more, toggle, and localization tests                                                                              | Collapsed; expanded; French catalog                        | A missing toggle, hidden entries that render, a toggle that does not expand and collapse, or English text under a French catalog fails. Gap: no test asserts `aria-expanded`, `aria-controls`, or that focus stays on the button.                                                                                                 | `audit:MetadataList/behavior` |
+| FR5             | `MetadataList.test.tsx` root pass-through, event, and owned-metadata tests                                                                     | `aria-label`, `id`, data; click; colliding reflection      | A dropped attribute or handler, or a caller `data-columns` or `data-orientation` that wins, fails. Gap: no test covers `ref`, `className`, `style`, or the `xstyle` merge order.                                                                                                                                                  | `audit:MetadataList/api`      |
+| PR1             | Source review                                                                                                                                  | Every state                                                | Gap: no automated check fails if MetadataList adds a listener, timer, or measurement.                                                                                                                                                                                                                                             | `audit:MetadataList/behavior` |
+| Theming targets | `themingTargets.test.ts`                                                                                                                       | Root and item targets                                      | A renamed or undocumented target fails. Gap: no check fails if the side-by-side `dt` loses the `metadata-list-item` target.                                                                                                                                                                                                       | `audit:MetadataList/theming`  |
+
+## Decision log
+
+None recorded. The record describes shipped behavior.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, current audit
+results, implementation steps, or entry markup. It links to their owners.