An open source design system that's fully customizable and agent ready
schema_version: 3 template_version: 7 kind: component id: component:MetadataListItem 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, 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]
MetadataListItem component contract
Contract at a glance
| Area | Contract |
|---|---|
| Public contract | label (a string), children (the value), optional icon, root BaseProps, and a ref. |
| Behavior | One label and value pair, rendered as a dt and dd either side by side in the list's grid or stacked inside a wrapper. |
| End-user impact | People read each fact's label next to or above its value, and assistive technology pairs them. |
| 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 pair that is not dt and dd, a wrapper in the side-by-side layout, or caller props that move off the element carrying the ref. |
| Governing rules | architecture:public-component-api INV5–INV8; architecture:component-theming-surface; WCAG 2.2 SC 1.3.1. |
This table is a review projection; the body below is authoritative.
Intent
MetadataListItem is one key and value entry inside a MetadataList. It owns the entry's term and definition markup and their type; the caller owns the label, icon, and value.
Consumer syntax and examples belong in MetadataListItem.doc.mjs.
Compatibility and migration
- Released default preserved:
yes— side by side outside a stacked list. - Compatibility class: records shipped behavior; no public prop, default, DOM, target, or styling output changes.
- Controlled/uncontrolled behavior: not applicable
- Migration decision: none
Consumer migration instructions belong in consumer docs and release notes.
Ownership boundary
Owns
- The entry's
dtanddd, the stacked wrapper, and themetadata-list-itemtarget thatcomponent:MetadataListmaps. - Label and value type, the icon slot, and where caller inputs land.
Does not own / non-goals
- Label position, columns, and orientation — owned by
component:MetadataList. - The label, icon, and value content — owned by the caller.
Public concepts
| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
|---|---|---|---|---|---|---|---|
| Label | string | The entry's key. | Always | — | caller | Stable | — |
| Value | ReactNode (children) |
The entry's value. | Always | — | caller | Stable | — |
| Icon | ReactNode; unset | Content shown before the label. | Always | unset | caller | Stable | — |
| Layout | side by side; stacked | Set by the parent list, not by the item. | Always | side by side | component:MetadataList |
Stable | — |
Behavioral and layout contract
| ID | Invariant | Basis |
|---|---|---|
| FR1 | Side by side (labels at the start, or outside a MetadataList), the item renders a dt holding the icon and label, then a dd holding the value, as direct children of the list's grid. The dt carries the metadata-list-item target, the ref, and the caller's props and styling inputs; a data-testid becomes <id>-label on the dt and <id>-value on the dd. Both cells are at least 24px tall and break long words. |
Current source and tests |
| FR2 | Stacked (labels on top, or a horizontal list), the item renders a div wrapper carrying the metadata-list-item target, the ref, data-testid, and the caller's props and styling inputs, holding the dt above the dd with a --spacing-0-5 gap. |
Current source and tests |
| FR3 | The label uses medium-weight body type in secondary text color; the value uses body type in primary text color. An icon sits before the label with a --spacing-2 gap. |
Current source and docs |
| FR4 | xstyle, className, and style compose after component styles on the element carrying the target, and caller props reach that element after the component's own attributes. |
Current source and tests; architecture:public-component-api INV5–INV8 |
Allowed variation
- AV1 — Content. Any string may be the label; any ReactNode may be the icon or value.
Representative states
| State | Required invariant | Allowed variation |
|---|---|---|
| Side by side | dt and dd as grid siblings; target, ref, and props on the dt. |
Content. |
| Stacked | One wrapper with the target, ref, and props, holding dt over dd. |
Content. |
| With icon | The icon precedes the label inside the dt. |
Icon. |
Transformation and precedence order
- ORD1 — Layout. The parent list's horizontal orientation or
toplabel position → stacked; otherwise side by side.
Performance and resources
- PR1 — No resources. MetadataListItem reads its parent list's label position and orientation and holds no state.
Accessibility contract
- AR1 — Term and definition. The label is a
dtand the value itsdd, so assistive technology pairs them (WCAG 2.2 SC 1.3.1). The icon adds no semantics of its own.
Design relationships
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|---|---|---|---|---|
| Label | Secondary-color medium key. | Current source and docs | Supporting | FR1–FR3 |
| Metadata | Primary-color value. | Current source and docs | Prominent | FR1–FR3 |
Theming: the dt (side by side) or the wrapper (stacked) carries the
metadata-list-item target, which MetadataList.doc.mjs declares and
component:MetadataList maps. MetadataListItem.doc.mjs declares no anatomy of
its own, so no anatomy-theming block is declared here.
Family and system relationships
component:MetadataListowns layout, label position, and the target mapping.architecture:public-component-apiowns caller-input routing; FR4 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 | MetadataList.test.tsx item, label-width, and pass-through-target tests |
Side by side | A missing label or value, a dt or dd that is not a direct child of the dl, wrong -label and -value test ids, or props or click handling that leave the dt, fails. Gap: no test attaches a ref, and the 24px minimum height has no check. No check fails if the side-by-side dt loses the metadata-list-item target. |
audit:MetadataListItem/layout |
| FR2 | MetadataList.test.tsx stacked and stacked pass-through tests |
Stacked | A missing wrapper, dt, or dd, or props that leave the wrapper, fails. Gap: the stacked gap has no check. No test attaches a ref to the stacked wrapper. |
audit:MetadataListItem/layout |
| FR3 | MetadataList.test.tsx icon test |
With icon | A missing icon fails. Gap: label and value type and color and the icon gap have no automated check. | audit:MetadataListItem/design |
| FR4 | MetadataList.test.tsx pass-through tests |
aria-label, id, data; click |
A dropped attribute or handler fails. Gap: no test covers className, style, or the xstyle merge order. |
audit:MetadataListItem/api |
| AR1 | MetadataList.test.tsx role queries |
Term and definition | A missing term or definition role in the DOM fails. Gap: no accessibility-tree check proves the pairing (spec:AST-009 FR3). |
audit:MetadataListItem/a11y |
| PR1 | Source review | Every state | Gap: no automated check fails if MetadataListItem adds state. | audit:MetadataListItem/behavior |
| RTL relation | RTL audit curated D2 target (apps/storybook/rtl-audit/targets.json) on MetadataList / Basic |
Side label and value; LTR and RTL | A label that is not at the inline start of its value fails D2. | audit:MetadataListItem/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 list layout rules. It links to their owners.