An open source design system that's fully customizable and agent ready
schema_version: 3 template_version: 7 kind: component id: component:Item authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-10-16 owners: [cixzhang] review_triggers: [public-api, layout, theming] verified_by: [ packages/core/src/Item/Item.test.tsx, packages/core/src/hooks/nestedTouchPress.adopters.test.tsx, packages/core/src/List/List.test.tsx, packages/core/src/RadioList/RadioList.test.tsx, packages/core/src/CheckboxList/CheckboxList.test.tsx, apps/storybook/stories/Item.stories.tsx, scripts/check-knowledge.mjs, ] modules: [] families: [family:navigation-destinations] design_specs: [] architecture: [ architecture:component-theming-surface, architecture:public-component-api, architecture:internationalization, ] contributing: [contributing:api-conventions]
system_specs: [spec:AST-017/FR3, spec:AST-057]
Item component contract
This record governs how Item aligns its start and end content against the
label. Item's swipe actions are governed by spec:AST-057, and its link and
navigation semantics by family:navigation-destinations; other Item behavior
remains described by its source, tests, and Item.doc.mjs until a record
claims it.
Contract at a glance
| Area | Contract |
|---|---|
| Public contract | align?: 'center' | 'start' | 'first-line' on Item, ListItem, RadioListItem, and CheckboxListItem; default center. |
| Behavior | first-line centers each start and end slot on the label's first line, for any slot height; a slot taller than that line moves the text down rather than leaving the row. |
| End-user impact | A small status dot, radio, or age stays level with the first line of a wrapped label instead of drifting to the middle of the row (center) or riding above the line (start). |
| Builder impact | None by default. A builder opts in per row with align="first-line"; theme authors may style the item target's first-line alignment. |
| Compatibility/readiness | Additive: a new value on an existing closed axis and typed forwarding of an existing runtime pass-through. Rows that omit align are unchanged. |
| Review checks | Reject a changed default, changed center/start geometry, JavaScript measurement, a slot pushed outside the row, a second theme target, or a composing row that drops the value. |
| Governing rules | FR1–FR8 below; architecture:component-theming-surface/INV6; spec:AST-017/FR3. |
This table is a review projection; the body below is authoritative.
Intent
Item is the shared row behind lists, menus, pickers, and option rows. Its label can wrap, while its start and end content is often a single-line-sized mark: a status dot, a radio or checkbox, an icon, a short timestamp. Those marks belong to the first line of text they annotate. Item owns the alignment because only Item knows where its label's first line sits; a caller cannot place a slot against it without copying Item's typography.
Compatibility and migration
- Released default preserved:
yes; omittedalignresolves tocenter. - Compatibility class: additive closed-axis value; additive typed prop on three composing rows that already forward unknown props to Item at runtime.
- Controlled/uncontrolled behavior: not applicable.
- Migration decision:
component:Item/DEC-1.
Consumer migration instructions belong in consumer docs and release notes.
Ownership boundary
Owns
- The
alignaxis: its values, default, and the geometry of each value for the start and end content slots. - Reflecting the resolved alignment on the
itemtheme target. - Reflecting highlighted, selected, and disabled state on the
itemtheme target. - The forwarding rule for rows that compose Item and expose
align.
Does not own / non-goals
- The
markerslot's alignment — owned by whoever renders the marker; ListItem positions its own markers against the first line. - Typography of caller content inside
label— owned by the caller. - A theme-wide default alignment — themes style values; they do not choose a
component's prop default (
architecture:component-theming-surface). - Alignment inside a slot's own content (for example, an avatar stack) — owned by that content.
Public concepts
| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
|---|---|---|---|---|---|---|---|
| Alignment | center, start, first-line |
center: slots centered on the whole text block. start: slot tops on the text block's top. first-line: slot centers on the first line's center. |
Every density, layout, interaction mode, and direction; start and end slots | center |
component:Item |
stable | Other values are rejected by the public type |
Behavioral and layout contract
| ID | Invariant | Basis | Draft review state |
|---|---|---|---|
| FR1 | Item MUST accept align with exactly center, start, and first-line, and MUST resolve an omitted value to center. The geometry of center and start MUST NOT change. |
component:Item/DEC-1 |
settled |
| FR2 | Under first-line, the block-axis center of each rendered start-content and end-content slot MUST coincide with the block-axis center of the label's first line box, for every slot block size. |
Owner direction | settled |
| FR3 | Under first-line, a slot taller than the label's first line MUST stay inside the row's content box: the label and description move down by the difference, and the row grows to fit. No slot is clipped or painted into the row's block padding. |
Owner direction | settled |
| FR4 | A row whose label renders a single line and which has no description MUST render identically under first-line and center, for every slot block size. |
Follows from FR2 and FR3 | settled |
| FR5 | The first line box is the label line as Item styles it, from the active theme's body text size and leading. A theme that changes those tokens moves the alignment with them. Caller content inside label that sets its own font size or line height is outside the FR2 guarantee. |
Shared typography source | settled |
| FR6 | first-line MUST hold in every density, in stacked and inline layouts, with labelLines truncation, and in plain, button, link, link-root, delegated, and parent-role rows. In right-to-left text it MUST produce the same block-axis placement with the slots mirrored by logical order and no DOM reordering. |
architecture:internationalization |
settled |
| FR7 | The item theme target MUST reflect the resolved alignment as its existing align selector axis, including first-line, and Item's public theming metadata MUST list that value. The alignment axis adds no new target or theme-level default. |
architecture:component-theming-surface/INV6; component:Item/DEC-2 |
settled |
| FR8 | ListItem, RadioListItem, and CheckboxListItem MUST expose align with Item's values and default and forward it unchanged to the Item row they render. A composing row MUST NOT drop, remap, or narrow the value. |
Owner direction | settled |
| FR9 | An interactive row (an onClick row, an href row, or a delegated row with interactiveRef) shows its touch pressed paint only for a press that would activate it: a finger press on the row's surface or on its own action (its invisible button or link, or the control it delegates to) paints the row, and a finger press that starts on another interactive element inside the row paints none. In a row with a parent-supplied role, or a row whose root is a link, a press on a nested control activates the row, so it paints. A mouse press keeps the row's :active paint. |
Owner direction, 2026-11-03: no pressed state on a container for a press that does not activate it | settled |
| FR10 | The item theme target MUST reflect a highlighted, selected, or disabled row as data-highlighted, data-selected, and data-disabled, each present only while its state holds, with the names CommandPaletteItem uses. A row that composes Item reflects the states it passes to Item. |
architecture:component-theming-surface/INV6; shipped source and focused tests, not owner-reviewed |
settled; not owner-reviewed |
Allowed variation
- AV1 — Slot content. Any slot content and size may appear; FR2 holds for each slot independently, so a start slot and an end slot of different heights each center on the first line.
- AV2 — Theme typography. Body text size and leading may vary by theme; the first line box follows them (FR5).
- AV3 — Row height. Under
first-linea row may be taller than the same row undercenterwhen a slot is taller than the first line and a description or second label line is present (FR3).
Representative states
| State | Required invariant | Allowed variation |
|---|---|---|
| Wrapped label, 6px dot start, short-text end | Both slot centers on the first line's center. | Density, theme typography, direction. |
| One-line label, no description, any slot | Identical to center. |
Slot size. |
| Label and description, 40px avatar start | Avatar center on the first line's center; text moves down; row grows. | Avatar size. |
| Radio or checkbox row with a wrapped label | The control centers on the first line. | Control size by Field size. |
| Right-to-left | Same block-axis placement; slots mirrored by logical order. | Writing direction. |
Omitted align |
Identical to today's center. |
None. |
Transformation and precedence order
- ORD1 — Resolution. An explicit
alignon a composing row forwards to Item unchanged; Item resolves an omitted value tocenter; the resolved value drives both geometry and theitemtarget's selector axis, so the two never disagree.
Performance and resources
- PR1 — CSS geometry only. Every alignment value MUST be achieved in CSS: no measurement, observer, listener, state, Effect, or extra render pass.
Accessibility contract
- AR1 — Presentation only. Alignment MUST NOT change the DOM order, role, accessible name or description, focus target, tab order, or hit target of the row or its slots.
- AR2 — No exposed text. Any construct that implements
first-lineMUST contribute no text to the accessibility tree.
Design relationships
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|---|---|---|---|---|
| Start and end content | Annotates the first line of the label it sits beside. | Owner direction | Supporting | FR2–FR4 |
| Label first line | The reference line the slots align to. | Item typography | Prominent | FR5 |
Family and system relationships
spec:AST-057owns Item's swipe actions and their panels; alignment does not change them, because the panels sit outside the row's flow.family:navigation-destinationsowns Item's link and navigation semantics; alignment does not change them.architecture:component-theming-surfaceowns how visual axes reach theme targets; this record adds one value to Item's existingalignaxis.architecture:public-component-apiowns prop admission; FR8 types an existing runtime pass-through rather than adding a parallel concept.architecture:internationalizationowns logical-direction behavior; FR6 applies it.spec:AST-017/FR3classifies this as a non-breaking feature: it adds a value and a typed prop, narrows nothing, and a caller who never setsalignsees no change.
Verification map
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
|---|---|---|---|---|
| FR1, FR7 | Item.test.tsx alignment and theme-reflection suites; public type test |
Omitted, center, start, first-line |
A changed default, a missing data-align="first-line", or a widened type fails. |
audit:Item/api |
| FR2–FR6 | Real-Chromium geometry assertions over the Item alignment stories | Wrapped label with dot and age; avatar; densities; RTL; theme | A slot center off the first line center by more than 0.5px, or a clipped slot, fails. | audit:Item/layout |
| FR8 | List.test.tsx, RadioList.test.tsx, CheckboxList.test.tsx forwarding cases |
Each composing row with align="first-line" |
A row whose Item root lacks data-align="first-line" fails. |
audit:Item/api |
| FR9 | nestedTouchPress.adopters.test.tsx; Item.nestedPress.test.tsx |
A finger on the delegated control; a finger on another control in the row | A row painted for a press on another control, or not painted for a press on its delegated control, fails. | audit:Item/behavior |
| FR10 | Item.test.tsx "reflects highlighted, selected, and disabled on the item theme target" |
Plain, highlighted only, selected only, disabled only, and all three together | A missing attribute, or an attribute left on a row whose state does not hold, fails. | audit:Item/theming |
| AR1, AR2 | Accessibility-tree snapshot of a first-line row against a center row |
Plain and option rows | Any difference in name, role, description, or order fails. | audit:Item/a11y |
| PR1 | Source review of Item's alignment styles | All values | A ref, observer, or Effect added for alignment fails review. | audit:Item/layout |
Decision log
DEC-1 — first-line is an opt-in value; center stays the default
Reference: component:Item/DEC-1
Decider: cixzhang, 2026-10-16
A wrapped label with a single-line-sized mark needs the mark on its first line,
and neither existing value does that: center drops the mark to the middle of
the row and start pins its top, which leaves a small mark above the line's
center. A new value fixes those rows without moving any row that relies on
today's default.
Rejected: making first-line the default, because a slot sized to the whole
text block, such as an avatar beside a label and description, is correct under
center.
DEC-2 — The theme setting is the item target's alignment axis
Reference: component:Item/DEC-2
Decider: cixzhang, 2026-10-16
Themes reach first-line rows through the item target's existing align
selector axis, the same way they reach center and start. A theme can style
those rows; it does not choose which value a row receives.
Open questions
None.
Content boundary
This file does not duplicate consumer prop tables/examples, current audit results, implementation steps, or family/system rules. It links to their owners.