An open source design system that's fully customizable and agent ready
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, apps/storybook/rtl-audit/targets.json, ] 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-listtarget, the optional title, thedl, 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→topformultior 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
dtandddpairs inside onedl, 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:MetadataListItemowns entry markup and reads the label position this record resolves.architecture:component-theming-surfaceowns target and anatomy mapping.architecture:public-component-apiowns caller-input routing; FR5 applies it.spec:AST-009owns 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 |
| RTL relation | RTL audit curated D2 target (apps/storybook/rtl-audit/targets.json) on MetadataList / Basic |
Side labels; LTR and RTL | A label column that is not at the inline start of the value column fails D2. | audit:MetadataList/i18n-rtl |
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.