@astryxdesign/core 0.7.1 → 0.7.2-canary.151434a

package/src/Field/Field.test.tsx

@@ -2,7 +2,7 @@
 
 /**
  * @file Field.test.tsx
- * @input Uses vitest, @testing-library/react, Field component
+ * @input Uses Vitest, Testing Library, StyleX, Field, FormLayoutContext
  * @output Unit tests for Field component behavior
  * @position Testing; validates Field.tsx implementation
  *
@@ -10,11 +10,18 @@
  */
 
 import {describe, it, expect, vi, afterEach} from 'vitest';
-import {render, screen, waitFor} from '@testing-library/react';
+import {render, screen, waitFor, fireEvent} from '@testing-library/react';
+import * as stylex from '@stylexjs/stylex';
 import {Field} from './Field';
 import {FormLayoutContext} from '../FormLayout/FormLayoutContext';
 import {__resetLiveRegionsForTest} from '../hooks/useAnnounce';
 
+const testStyles = stylex.create({
+  root: {
+    minWidth: '123px',
+  },
+});
+
 function politeRegion(): HTMLElement | null {
   return document.querySelector('[data-astryx-live-region="polite"]');
 }
@@ -572,6 +579,57 @@ describe('Field', () => {
       </FormLayoutContext>
     );
 
+    it('composes root props without letting callers replace layout semantics', () => {
+      const onClick = vi.fn();
+      const expectedXstyleClass = stylex.props(testStyles.root).className;
+      if (expectedXstyleClass == null) {
+        throw new Error('Expected the test xstyle to produce a class name.');
+      }
+
+      render(
+        <Field
+          label="Name"
+          inputID="name-input"
+          data-testid="field"
+          data-layout="consumer"
+          data-owner="consumer"
+          className="consumer-class"
+          style={{width: '321px'}}
+          xstyle={testStyles.root}
+          onClick={onClick}>
+          <input id="name-input" />
+        </Field>,
+        {wrapper: horizontalLabelsWrapper},
+      );
+
+      const field = screen.getByTestId('field');
+      expect(field).toHaveClass('astryx-field', 'consumer-class');
+      expect(field).toHaveClass(expectedXstyleClass);
+      expect(field).toHaveAttribute('data-layout', 'horizontal-labels');
+      expect(field).toHaveAttribute('data-owner', 'consumer');
+      expect(field).toHaveStyle({width: '321px'});
+      fireEvent.click(field);
+      expect(onClick).toHaveBeenCalledOnce();
+    });
+
+    it('visually hides the description in horizontal-label mode when the label is hidden', () => {
+      render(
+        <Field
+          label="Search"
+          inputID="search-input"
+          isLabelHidden
+          description="Search for items"
+          descriptionID="search-desc">
+          <input id="search-input" aria-describedby="search-desc" />
+        </Field>,
+        {wrapper: horizontalLabelsWrapper},
+      );
+
+      const description = screen.getByText('Search for items');
+      expect(description.className).toContain('visuallyHidden');
+      expect(description).toHaveAttribute('id', 'search-desc');
+    });
+
     it('applies display:contents when in horizontal-labels context', () => {
       const {container} = render(
         <Field label="Name" inputID="name-input">

package/src/Field/Field.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file Field.tsx
- * @input Uses React, HTMLAttributes, ReactNode, FieldLabel, IconType, useFieldStatusAnnouncement
+ * @input Uses React, StyleX, BaseProps, FieldLabel/FieldStatus, FormLayoutContext, Text, VisuallyHidden, theme/status utilities
  * @output Exports Field component, FieldProps
  * @position Core implementation; consumed by index.ts, tested by Field.test.tsx
  *
@@ -30,6 +30,7 @@ import {mergeProps} from '../utils';
 import {useDevWarning} from '../hooks/useDevWarning';
 import {FormLayoutContext} from '../FormLayout/FormLayoutContext';
 import {Text} from '../Text';
+import {VisuallyHidden} from '../VisuallyHidden';
 import {themeProps} from '../utils/themeProps';
 
 const styles = stylex.create({
@@ -298,20 +299,28 @@ export function Field({
     return (
       <div
         ref={ref}
+        {...props}
         {...mergeProps(
           themeProps('field', {layout: 'horizontal-labels'}),
           stylex.props(styles.horizontalLabels, xstyle),
           className,
           style,
-        )}
-        {...props}>
+        )}>
         <div {...stylex.props(styles.horizontalLabelAlign)}>{labelNode}</div>
         <div {...stylex.props(styles.inputStatusWrapper)}>
-          {description && (
-            <Text type="supporting" display="block" id={resolvedDescriptionID}>
-              {description}
-            </Text>
-          )}
+          {description &&
+            (isLabelHidden ? (
+              <VisuallyHidden id={resolvedDescriptionID}>
+                {description}
+              </VisuallyHidden>
+            ) : (
+              <Text
+                type="supporting"
+                display="block"
+                id={resolvedDescriptionID}>
+                {description}
+              </Text>
+            ))}
           {children}
           {statusNode}
         </div>

package/src/HoverCard/HoverCard.test.tsx

@@ -109,6 +109,64 @@ describe('useHoverCard identity', () => {
   });
 });
 
+// A card closed while the pointer rests on it unmounts without a mouseleave,
+// so the hook must not keep believing the pointer is over the card: if it
+// does, the next open of the same trigger never closes on leave.
+describe('useHoverCard closing while the pointer is on the card', () => {
+  function Harness() {
+    const card = useHoverCard({delay: 0, hideDelay: 0});
+    return (
+      <div>
+        <span ref={card.ref}>Trigger</span>
+        <output data-testid="state">{card.isOpen ? 'open' : 'closed'}</output>
+        {card.renderHoverCard(
+          <button type="button" onClick={card.hide}>
+            Pick
+          </button>,
+        )}
+      </div>
+    );
+  }
+
+  async function openThenRestOnCard() {
+    const state = screen.getByTestId('state');
+    fireEvent.mouseEnter(screen.getByText('Trigger'));
+    await waitFor(() => expect(state).toHaveTextContent('open'));
+    const pick = screen.getByRole('button', {name: 'Pick', hidden: true});
+    fireEvent.mouseLeave(screen.getByText('Trigger'));
+    fireEvent.mouseEnter(pick.parentElement!);
+    return {state, pick};
+  }
+
+  async function expectNextOpenClosesOnLeave(state: HTMLElement) {
+    const trigger = screen.getByText('Trigger');
+    fireEvent.mouseEnter(trigger);
+    await waitFor(() => expect(state).toHaveTextContent('open'));
+    fireEvent.mouseLeave(trigger);
+    await waitFor(() => expect(state).toHaveTextContent('closed'));
+  }
+
+  it('closes the next open on leave after hide() from inside the card', async () => {
+    render(<Harness />);
+    const {state, pick} = await openThenRestOnCard();
+
+    fireEvent.click(pick);
+    await waitFor(() => expect(state).toHaveTextContent('closed'));
+
+    await expectNextOpenClosesOnLeave(state);
+  });
+
+  it('closes the next open on leave after Escape dismisses the card', async () => {
+    render(<Harness />);
+    const {state} = await openThenRestOnCard();
+
+    fireEvent.keyDown(document.body, {key: 'Escape'});
+    await waitFor(() => expect(state).toHaveTextContent('closed'));
+
+    await expectNextOpenClosesOnLeave(state);
+  });
+});
+
 describe('HoverCard', () => {
   it('renders trigger element', () => {
     render(

package/src/HoverCard/useHoverCard.tsx

@@ -345,6 +345,14 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
     hideLayer();
   }, [clearTimeouts, hideLayer]);
 
+  // The imperative hide. A card closed while the pointer rests on it unmounts
+  // without a mouseleave, so the content-hover latch is cleared here; left set,
+  // it would keep the trigger's next hover-open from closing on leave.
+  const hide = useCallback(() => {
+    isHoveringContentRef.current = false;
+    hideLayer();
+  }, [hideLayer]);
+
   const {
     isTouchPointerRef,
     isTouchInteraction,
@@ -508,7 +516,7 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
           ? null
           : document.getElementById(layerId);
       const hadFocus = card?.contains(document.activeElement) ?? false;
-      hideLayer();
+      hide();
       if (hadFocus) {
         isEscapeDismissingRef.current = true;
         triggerRef.current?.focus();
@@ -720,6 +728,6 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
     isOpen: isLayerOpen,
     renderHoverCard,
     show: showLayer,
-    hide: hideLayer,
+    hide,
   };
 }

package/src/IconButton/IconButton.doc.mjs

@@ -46,7 +46,7 @@ export const docs = {
     {
       name: 'isLoading',
       type: 'boolean',
-      description: 'Shows a loading spinner and disables interaction.',
+      description: 'Shows a loading spinner and blocks re-activation while staying focusable (aria-busy + aria-disabled, not native disabled).',
       default: 'false',
     },
     {
@@ -141,7 +141,7 @@ export const docsDense = {
     variant: 'visual style variant',
     size: 'size variant',
     elevation: 'resting shadow depth: none|low|med|high; raise for a floating action button (FAB)',
-    isLoading: 'shows loading spinner + disables interaction',
+    isLoading: 'shows loading spinner, blocks re-activation but stays focusable (aria-disabled, not native disabled)',
     isDisabled: 'disables button',
     tooltip: 'tooltip text shown on hover',
     onClick: 'standard click handler',

package/src/IconButton/IconButton.test.tsx

@@ -124,7 +124,9 @@ describe('IconButton', () => {
   it('shows loading state', () => {
     render(<IconButton label="Save" icon={<span>💾</span>} isLoading />);
     const button = screen.getByRole('button');
-    expect(button).toBeDisabled();
+    // Busy is aria-disabled (focusable), not native disabled — see #4871.
+    expect(button).not.toBeDisabled();
+    expect(button).toHaveAttribute('aria-disabled', 'true');
   });
 
   it('forwards ref correctly', () => {

package/src/Item/Item.doc.mjs

@@ -49,7 +49,7 @@ export const docs = {
       {
         name: '--_item-inset-inline',
         description:
-          'Inline inset of the row. Item derives its paddingInline from this variable, and List reads it to cancel the inset when edgeCompensation="inline". Set paddingInline on `item` in a theme and both stay in sync.',
+          'Inline inset of the row. Item derives its paddingInline from this variable, and List reads it to place rows for its edge treatments (edge="flush", "outset", and "bleed"). Set paddingInline on `item` in a theme and both stay in sync.',
         default: 'var(--spacing-2) (var(--spacing-3) for density="spacious")',
         private: true,
       },
@@ -118,8 +118,9 @@ export const docs = {
         },
         {
           name: 'align',
-          type: "'center' | 'start'",
-          description: 'Vertical alignment of start/end content slots.',
+          type: "'center' | 'start' | 'first-line'",
+          description:
+            "Vertical alignment of start/end content slots. 'center' centers each slot on the whole text block; 'start' lines up slot tops with the text's top; 'first-line' centers each slot on the label's first line, so a small mark stays level with the first line of a wrapped label. A slot taller than that line moves the text down. The `item` theme target reflects the value as `align`.",
           default: "'center'",
         },
         {
@@ -248,7 +249,7 @@ export const docs = {
       {
         guidance: true,
         description:
-          'Use align="start" when start or end content is taller than a single line of text.',
+          'Use align="first-line" when a wrapping label sits beside a small mark (a status dot, a radio, a timestamp) that belongs to its first line. Use align="start" to line up the tops of a tall slot and the text.',
       },
       {
         guidance: true,
@@ -321,7 +322,8 @@ export const docsZh = {
         endContent:
           '在标签/描述区域之后渲染的内容，例如徽章、元数据、时间戳或操作按钮。',
         as: '根元素的 HTML 元素。',
-        align: '起始/结束内容插槽的垂直对齐方式。',
+        align:
+          "起始/结束内容插槽的垂直对齐方式：'center'（默认）、'start'（顶部对齐）或 'first-line'（以标签第一行为中心）。",
         density:
           '间距密度。"compact" 使用 4px 块内距，"balanced" 使用 8px，"spacious" 使用 12px 块内距和内联内距。',
         labelLines: '标签截断前的最大行数。',
@@ -363,7 +365,8 @@ export const docsZh = {
       },
       {
         guidance: true,
-        description: '当起始或结束内容高于单行文本时使用 align="start"。',
+        description:
+          '当换行标签旁边是属于其第一行的小标记（状态点、单选按钮、时间戳）时，使用 align="first-line"。使用 align="start" 让较高插槽与文本顶部对齐。',
       },
       {
         guidance: false,
@@ -426,7 +429,7 @@ export const docsDense = {
       {
         guidance: true,
         description:
-          'align="start" when start/end content is taller than one text line.',
+          'align="first-line" for a small mark beside a wrapping label; align="start" to top-align a tall slot with the text.',
       },
       {
         guidance: false,
@@ -458,7 +461,8 @@ export const docsDense = {
         endContent:
           'Content after label/description: badges, timestamps, actions.',
         as: 'Root HTML element.',
-        align: 'Vertical alignment of start/end content slots.',
+        align:
+          "Start/end slot alignment: 'center' (default), 'start' (tops), or 'first-line' (centered on the label's first line).",
         density:
           'Spacing: "compact" (4px), "balanced" (8px), or "spacious" (12px).',
         labelLines: 'Max label lines before truncation.',

package/src/Item/Item.spec.md

@@ -0,0 +1,226 @@
+---
+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/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
+
+<!-- Describe the system, not the project: present tense, what it does. No proposals, history, pull requests, or research in the record; see docs/contributing/spec-writing.md and report its rubric results in the pull request. -->
+
+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`; omitted `align` resolves to `center`.
+- 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 `align` axis: its values, default, and the geometry of each value for
+  the start and end content slots.
+- Reflecting the resolved alignment on the `item` theme target.
+- The forwarding rule for rows that compose Item and expose `align`.
+
+**Does not own / non-goals**
+
+- The `marker` slot'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. No new target, state, or theme-level default is added.                                                                            | `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            |
+
+### 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-line` a row may be taller than the same
+  row under `center` when 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 `align` on a composing row forwards to
+  Item unchanged; Item resolves an omitted value to `center`; the resolved value
+  drives both geometry and the `item` target'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-line` MUST
+  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-057` owns Item's swipe actions and their panels; alignment does
+  not change them, because the panels sit outside the row's flow.
+- `family:navigation-destinations` owns Item's link and navigation semantics;
+  alignment does not change them.
+- `architecture:component-theming-surface` owns how visual axes reach theme
+  targets; this record adds one value to Item's existing `align` axis.
+- `architecture:public-component-api` owns prop admission; FR8 types an existing
+  runtime pass-through rather than adding a parallel concept.
+- `architecture:internationalization` owns logical-direction behavior; FR6
+  applies it.
+- `spec:AST-017/FR3` classifies this as a non-breaking feature: it adds a value
+  and a typed prop, narrows nothing, and a caller who never sets `align` sees 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`    |
+| 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
+
+<!-- Record the boundary or requirement, not how it was reached. A rejected alternative is at most one line here, kept only when it is consequential and likely to recur. -->
+
+### 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.

package/src/Item/Item.test.tsx

@@ -531,6 +531,67 @@ describe('Item', () => {
     expect(screen.getByTestId('item')).toBeInTheDocument();
   });
 
+  it('reflects the resolved alignment on the item theme target', () => {
+    const {rerender} = render(<Item label="Item" data-testid="item" />);
+    expect(screen.getByTestId('item')).toHaveAttribute('data-align', 'center');
+    for (const align of ['center', 'start', 'first-line'] as const) {
+      rerender(<Item label="Item" align={align} data-testid="item" />);
+      const item = screen.getByTestId('item');
+      expect(item).toHaveClass('astryx-item');
+      expect(item).toHaveAttribute('data-align', align);
+    }
+  });
+
+  it('aligns the row on first baselines only under first-line', () => {
+    const {rerender} = render(<Item label="Item" data-testid="item" />);
+    const declares = (value: string) =>
+      rulesDeclaredFor(screen.getByTestId('item')).some(rule =>
+        rule.includes(`align-items: ${value}`),
+      );
+    expect(declares('baseline')).toBe(false);
+    rerender(<Item label="Item" align="start" data-testid="item" />);
+    expect(declares('baseline')).toBe(false);
+    rerender(<Item label="Item" align="first-line" data-testid="item" />);
+    expect(declares('baseline')).toBe(true);
+  });
+
+  it('gives each first-line slot a strut with no accessible text', () => {
+    render(
+      <Item
+        label="Item"
+        align="first-line"
+        startContent={<span data-testid="start">S</span>}
+        endContent={<span data-testid="end">E</span>}
+      />,
+    );
+    for (const id of ['start', 'end']) {
+      const slot = screen.getByTestId(id).parentElement!;
+      const before = rulesDeclaredFor(slot).filter(rule =>
+        rule.slice(0, rule.indexOf('{')).includes('::before'),
+      );
+      expect(before.some(rule => rule.includes('/ ""'))).toBe(true);
+    }
+  });
+
+  it('leaves center and start slots without a strut', () => {
+    const {rerender} = render(
+      <Item label="Item" startContent={<span data-testid="start">S</span>} />,
+    );
+    const hasStrut = () =>
+      rulesDeclaredFor(screen.getByTestId('start').parentElement!).some(rule =>
+        rule.slice(0, rule.indexOf('{')).includes('::before'),
+      );
+    expect(hasStrut()).toBe(false);
+    rerender(
+      <Item
+        label="Item"
+        align="start"
+        startContent={<span data-testid="start">S</span>}
+      />,
+    );
+    expect(hasStrut()).toBe(false);
+  });
+
   // ===========================================================================
   // Description rendering
   // ===========================================================================