@astryxdesign/core 0.6.2 → 0.6.3-canary.01fa439

package/src/Kbd/Kbd.doc.mjs

@@ -27,7 +27,7 @@ export const docs = {
       name: 'keys',
       type: 'string',
       description:
-        'Keyboard shortcut string. Use "+" to separate keys. Special keys: mod (Cmd on Mac), ctrl, alt, shift, enter, backspace, escape, tab, up, down, left, right.',
+        'Keyboard shortcut string. Use "+" to separate keys. Special keys: mod (Cmd on Mac), ctrl, alt, shift, enter, backspace, escape, tab, up, down, left, right, plus. Aliases: esc for escape and return for enter.',
       required: true,
     },
     {
@@ -72,7 +72,7 @@ export const docsZh = {
       name: 'keys',
       type: 'string',
       description:
-        '键盘快捷键字符串。使用 "+" 分隔各按键。特殊按键：mod（Mac 上为 Cmd）、ctrl、alt、shift、enter、backspace、escape、tab、up、down、left、right。',
+        '键盘快捷键字符串。使用 "+" 分隔各按键。特殊按键：mod（Mac 上为 Cmd）、ctrl、alt、shift、enter、backspace、escape、tab、up、down、left、right、plus。别名：esc 等同于 escape，return 等同于 enter。',
       required: true,
     },
     {
@@ -122,7 +122,7 @@ export const docsDense = {
     ],
   },
   propDescriptions: {
-    keys: 'Shortcut string. "+" separates keys. Special: mod (Cmd on Mac), ctrl, alt, shift, enter, backspace, escape, tab, up, down, left, right.',
+    keys: 'Shortcut string. "+" separates keys. Special: mod (Cmd on Mac), ctrl, alt, shift, enter, backspace, escape, tab, up, down, left, right, plus. Aliases: esc for escape, return for enter.',
     xstyle: 'StyleX styles for layout customization. Must be stylex.create() value.',
     className: 'CSS class for root element. Prefer xstyle; className for non-StyleX integration.',
     style: 'Inline styles for root element. Prefer xstyle; inline styles bypass StyleX optimization.',

package/src/Kbd/Kbd.test.tsx

@@ -10,13 +10,14 @@
  */
 
 import {render, screen} from '@testing-library/react';
-import {describe, it, expect, afterEach} from 'vitest';
+import {describe, it, expect, afterEach, vi} from 'vitest';
 import {Kbd} from './Kbd';
 
 describe('Kbd', () => {
   const originalPlatform = navigator.platform;
 
   afterEach(() => {
+    vi.restoreAllMocks();
     // Restore platform after any test that spoofs it \u2014 ensures no
     // test pollution even if an assertion fails mid-test.
     Object.defineProperty(navigator, 'platform', {
@@ -72,6 +73,61 @@ describe('Kbd', () => {
     expect(screen.getByText('Esc')).toBeInTheDocument();
   });
 
+  it.each([
+    {alias: 'esc', display: 'Esc', label: 'Escape'},
+    {alias: 'return', display: '\u21B5', label: 'Enter'},
+  ])('normalizes the $alias key alias', ({alias, display, label}) => {
+    render(<Kbd keys={alias} />);
+    expect(screen.getByText(display)).toBeInTheDocument();
+    expect(screen.getByRole('img')).toHaveAttribute('aria-label', label);
+  });
+
+  it.each([
+    {alias: 'esc', canonical: 'escape'},
+    {alias: 'return', canonical: 'enter'},
+  ])('$alias renders identically to $canonical', ({alias, canonical}) => {
+    const {container, rerender} = render(<Kbd keys={canonical} />);
+    const text = container.textContent;
+    const label = screen.getByRole('img').getAttribute('aria-label');
+    rerender(<Kbd keys={alias} />);
+    expect(container.textContent).toBe(text);
+    expect(screen.getByRole('img').getAttribute('aria-label')).toBe(label);
+  });
+
+  it.each([
+    {keys: 'ctrl + ESC', display: 'Esc', label: 'Control + Escape'},
+    {keys: 'shift + RETURN', display: '\u21B5', label: 'Shift + Enter'},
+  ])('normalizes aliases inside the $keys combo', ({keys, display, label}) => {
+    render(<Kbd keys={keys} />);
+    expect(screen.getByText(display)).toBeInTheDocument();
+    expect(screen.getByRole('img')).toHaveAttribute('aria-label', label);
+  });
+
+  it('keeps child keys unique after alias normalization', () => {
+    const consoleError = vi
+      .spyOn(console, 'error')
+      .mockImplementation(() => {});
+    const {container} = render(
+      <Kbd keys="escape+esc+ESC+enter+return+return" />,
+    );
+    expect(consoleError).not.toHaveBeenCalled();
+    expect(
+      Array.from(container.querySelectorAll('kbd'), key => key.textContent),
+    ).toEqual(['Esc', 'Esc', 'Esc', '↵', '↵', '↵']);
+  });
+
+  it.each(['constructor', '__proto__'])(
+    'renders the unknown %s key without consulting object prototypes',
+    key => {
+      render(<Kbd keys={key} />);
+      expect(screen.getByText(key.toUpperCase())).toBeInTheDocument();
+      expect(screen.getByRole('img')).toHaveAttribute(
+        'aria-label',
+        key.toUpperCase(),
+      );
+    },
+  );
+
   it('exposes a spoken accessible name and hides the glyphs (obs-1)', () => {
     render(<Kbd keys="mod+shift+k" />);
     // The wrapper carries a screen-reader name built from spoken key labels

package/src/Kbd/Kbd.tsx

@@ -4,8 +4,8 @@
 
 /**
  * @file Kbd.tsx
- * @input Uses React, StyleX, theme tokens
- * @output Exports Kbd component and KbdProps
+ * @input Uses React, StyleX, theme tokens, shortcut key names and aliases
+ * @output Exports Kbd component and KbdProps with canonical shortcut labels
  * @position Core implementation; renders styled keyboard shortcut indicators
  *
  * SYNC: When modified, update:
@@ -61,20 +61,25 @@ const styles = stylex.create({
  * Note: `mod` is not in this map — it resolves dynamically via platform
  * detection inside the component.
  */
-const KEY_DISPLAY: Record<string, string> = {
-  ctrl: '\u2303', // ⌃
-  alt: '\u2325', // ⌥
-  shift: '\u21E7', // ⇧
-  enter: '\u21B5', // ↵
-  backspace: '\u232B', // ⌫
-  escape: 'Esc',
-  tab: '\u21E5', // ⇥
-  up: '\u2191',
-  down: '\u2193',
-  left: '\u2190',
-  right: '\u2192',
-  plus: '+',
-};
+const KEY_DISPLAY = new Map<string, string>([
+  ['ctrl', '\u2303'], // ⌃
+  ['alt', '\u2325'], // ⌥
+  ['shift', '\u21E7'], // ⇧
+  ['enter', '\u21B5'], // ↵
+  ['backspace', '\u232B'], // ⌫
+  ['escape', 'Esc'],
+  ['tab', '\u21E5'], // ⇥
+  ['up', '\u2191'],
+  ['down', '\u2193'],
+  ['left', '\u2190'],
+  ['right', '\u2192'],
+  ['plus', '+'],
+]);
+
+const KBD_KEY_ALIASES = new Map<string, string>([
+  ['esc', 'escape'],
+  ['return', 'enter'],
+]);
 
 /**
  * Resolves a key name to its display string. Handles the platform-aware
@@ -85,7 +90,7 @@ function getKeyDisplay(key: string, isMac: boolean): string {
   if (key === 'mod') {
     return isMac ? '\u2318' : 'Ctrl';
   }
-  return KEY_DISPLAY[key] ?? key.toUpperCase();
+  return KEY_DISPLAY.get(key) ?? key.toUpperCase();
 }
 
 /**
@@ -93,26 +98,26 @@ function getKeyDisplay(key: string, isMac: boolean): string {
  * (⌘, ⇧, ↵, …) that assistive tech cannot announce meaningfully, so the
  * accessible name for the shortcut is built from these words instead.
  */
-const KEY_LABEL: Record<string, string> = {
-  ctrl: 'Control',
-  alt: 'Alt',
-  shift: 'Shift',
-  enter: 'Enter',
-  backspace: 'Backspace',
-  escape: 'Escape',
-  tab: 'Tab',
-  up: 'Up arrow',
-  down: 'Down arrow',
-  left: 'Left arrow',
-  right: 'Right arrow',
-  plus: 'Plus',
-};
+const KEY_LABEL = new Map<string, string>([
+  ['ctrl', 'Control'],
+  ['alt', 'Alt'],
+  ['shift', 'Shift'],
+  ['enter', 'Enter'],
+  ['backspace', 'Backspace'],
+  ['escape', 'Escape'],
+  ['tab', 'Tab'],
+  ['up', 'Up arrow'],
+  ['down', 'Down arrow'],
+  ['left', 'Left arrow'],
+  ['right', 'Right arrow'],
+  ['plus', 'Plus'],
+]);
 
 function getKeyLabel(key: string, isMac: boolean): string {
   if (key === 'mod') {
     return isMac ? 'Command' : 'Control';
   }
-  return KEY_LABEL[key] ?? key.toUpperCase();
+  return KEY_LABEL.get(key) ?? key.toUpperCase();
 }
 
 function subscribeToPlatformChanges(): () => void {
@@ -127,7 +132,9 @@ export interface KbdProps extends BaseProps<HTMLSpanElement> {
   ref?: React.Ref<HTMLSpanElement>;
   /**
    * Keyboard shortcut string. Use "+" to separate keys.
-   * Special keys: mod (Cmd on Mac), ctrl, alt, shift, enter, backspace, escape.
+   * Special keys: mod (Cmd on Mac), ctrl, alt, shift, enter, backspace, escape,
+   * tab, up, down, left, and right.
+   * Aliases: "esc" for "escape" and "return" for "enter".
    * Use "plus" to render a literal "+" key (e.g. "shift+plus").
    *
    * @example
@@ -163,11 +170,24 @@ export function Kbd({keys, ref, xstyle, className, style, ...rest}: KbdProps) {
     getServerPlatformSnapshot,
   );
 
-  const parts = keys.split('+').map(key => key.trim().toLowerCase());
+  const keyOccurrences = new Map<string, number>();
+  const parts = keys
+    .split('+')
+    .map(key => key.trim().toLowerCase())
+    .map(sourceKey => {
+      const occurrence = keyOccurrences.get(sourceKey) ?? 0;
+      keyOccurrences.set(sourceKey, occurrence + 1);
+      return {
+        key: KBD_KEY_ALIASES.get(sourceKey) ?? sourceKey,
+        reactKey: `${sourceKey}:${occurrence}`,
+      };
+    });
 
   // Screen-reader name: the joined spoken labels (e.g. "Command + K"), since
   // the visual glyphs below are announced meaninglessly by assistive tech.
-  const accessibleName = parts.map(key => getKeyLabel(key, isMac)).join(' + ');
+  const accessibleName = parts
+    .map(({key}) => getKeyLabel(key, isMac))
+    .join(' + ');
 
   return (
     <span
@@ -181,8 +201,8 @@ export function Kbd({keys, ref, xstyle, className, style, ...rest}: KbdProps) {
         className,
         style,
       )}>
-      {parts.map(key => (
-        <kbd key={key} aria-hidden="true" {...stylex.props(styles.kbd)}>
+      {parts.map(({key, reactKey}) => (
+        <kbd key={reactKey} aria-hidden="true" {...stylex.props(styles.kbd)}>
           {getKeyDisplay(key, isMac)}
         </kbd>
       ))}

package/src/Layout/LayoutFooter.doc.mjs

@@ -8,6 +8,23 @@ export const docs = {
   displayName: 'Layout Footer',
   isHiddenFromOverview: true,
   description: 'Bottom bar for action bars, pagination, and status bars.',
+  playground: {
+    defaults: {
+      children: 'Footer content: status bar or actions',
+      hasDivider: true,
+    },
+    wrapper: {
+      component: 'Layout',
+      slotProp: 'footer',
+      props: {
+        content: {
+          __element: 'LayoutContent',
+          props: {},
+          children: 'Main content area',
+        },
+      },
+    },
+  },
   props: [
     {
       name: 'children',

package/src/Link/Link.doc.mjs

@@ -164,6 +164,17 @@ export const docs = {
     },
   ],
   usage: {
+    accessibility: [
+      {
+        name: 'Link text',
+        category: 'Color contrast',
+        criterion: '1.4.3 Contrast (Minimum)',
+        requirement: '4.5:1',
+        states: ['Rest', 'Hover', 'Pointer down'],
+        description:
+          'Link text must have at least 4.5:1 contrast with the background behind it. For Pointer down, measure against the pressed overlay the link paints behind its text.',
+      },
+    ],
     description:
       'A styled anchor for inline and standalone text navigation. Supports external links, underline variants, tooltips, and custom link components for router integration. Use it for navigating between pages or to external URLs.',
     bestPractices: [

package/src/Link/Link.test.tsx

@@ -12,6 +12,7 @@
 import {describe, it, expect, vi} from 'vitest';
 import {fireEvent, render, screen} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
+import {hasPressedArm} from '../__tests__/pressState';
 import {Link} from './Link';
 import {LinkProvider} from './LinkProvider';
 
@@ -417,3 +418,26 @@ describe('Link', () => {
     expect(link).toHaveAttribute('data-color', 'secondary');
   });
 });
+
+describe('pressed state', () => {
+  it('paints the pressed overlay behind a link while it is pressed', () => {
+    render(<Link href="/docs">Docs</Link>);
+    expect(hasPressedArm(screen.getByRole('link', {name: 'Docs'}))).toBe(true);
+  });
+
+  it('paints it on the button form too', () => {
+    render(<Link onClick={() => {}}>Open</Link>);
+    expect(hasPressedArm(screen.getByRole('button', {name: 'Open'}))).toBe(
+      true,
+    );
+  });
+
+  it('does not press a disabled link', () => {
+    render(
+      <Link href="/docs" isDisabled>
+        Docs
+      </Link>,
+    );
+    expect(hasPressedArm(screen.getByText('Docs').closest('a')!)).toBe(false);
+  });
+});

package/src/Link/Link.tsx

@@ -45,6 +45,7 @@ import {computeTargetAndRel} from './computeTargetAndRel';
 import {useInteractiveRole} from '../hooks/useInteractiveRole';
 import {themeProps} from '../utils/themeProps';
 import {focusOutlineProps} from '../utils/focusOutline.stylex';
+import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
 import {useTranslator} from '../i18n';
 
 /**
@@ -368,6 +369,9 @@ export function Link({
             styles.base,
             styles.buttonReset,
             linkColorStyles[color],
+            // The system's pressed overlay behind the text; the hover stays the
+            // colour change above, so a press is the one background it paints.
+            !isDisabled && interactionOverlayStyles.pressedBackgroundColor,
             hasUnderline && styles.hasUnderline,
             isStandalone && styles.standalone,
             isDisabled && styles.disabled,
@@ -427,6 +431,7 @@ export function Link({
           focusOutlineProps.focusVisible(
             styles.base,
             linkColorStyles[color],
+            !isDisabled && interactionOverlayStyles.pressedBackgroundColor,
             hasUnderline && styles.hasUnderline,
             isStandalone && styles.standalone,
             isDisabled && styles.disabled,

package/src/List/List.spec.md

@@ -0,0 +1,200 @@
+---
+schema_version: 3
+template_version: 5
+kind: component
+id: component:List
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-09-21
+owners: [cixzhang]
+review_triggers: [public-api, behavior, layout, theming]
+verified_by:
+  [
+    packages/core/src/List/List.test.tsx,
+    packages/core/src/Item/Item.test.tsx,
+    packages/core/src/theme/derivedVarRegistry.test.ts,
+    packages/core/src/theme/generateThemeRules.test.ts,
+    apps/storybook/stories/List.stories.tsx,
+    scripts/check-knowledge.mjs,
+  ]
+modules: []
+families: []
+design_specs: []
+architecture:
+  [architecture:container-padding, architecture:public-component-api]
+contributing: [contributing:api-conventions]
+system_specs: [spec:AST-002/DEC-1, spec:AST-002/DEC-2]
+---
+
+# List component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                         |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Public contract         | Add optional `edgeCompensation?: 'inline'`; omission preserves current layout.                                                                                                                   |
+| Behavior                | Every ListItem row moves its content toward a neutral host's inline content edges, reaching them when the host inset is at least the Item inset, while retaining Item-owned interaction padding. |
+| End-user impact         | List content can reduce or remove the extra inset beside its optional header and adjacent content without shrinking hover, press, selection, or focus paint.                                     |
+| Builder impact          | Builders opt in only when the List is placed directly in an eligible container-padding host state.                                                                                               |
+| Compatibility/readiness | Additive API; implementation and required real-browser evidence are pending.                                                                                                                     |
+| Review checks           | Reject header movement, unbounded negative margins, duplicated padding values, physical-edge logic, automatic opt-in, or a ListItem-level public prop.                                           |
+| Governing rules         | `architecture:container-padding/INV9–INV11`; `spec:AST-002/DEC-1–DEC-2`.                                                                                                                         |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+List owns collection-wide edge alignment because its optional header is not
+horizontally inset while every ListItem retains Item's inline padding. The caller
+knows whether the List is placed in a neutral host where these content lines
+should align; List cannot derive that design relationship from its children.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`; omission keeps current List and ListItem geometry.
+- Compatibility class: additive optional prop with no default behavior change.
+- Controlled/uncontrolled behavior: not applicable.
+- Migration decision: `component:List/DEC-1` and `component:List/DEC-2`.
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Ownership boundary
+
+**Owns**
+
+- The collection-wide `edgeCompensation` opt-in and its propagation to every
+  ListItem row.
+- Keeping the optional header in place while moving row content toward its line.
+- The supported relationship between ListItem row geometry and Item's normal
+  density- and theme-aware inline inset.
+
+**Does not own / non-goals**
+
+- Container padding values, nesting, or overlay resets — owned by
+  `architecture:container-padding`.
+- A ListItem-level compensation prop, automatic host detection, full bleed, or
+  arbitrary margin controls.
+- TabList or Button projections.
+
+## Public concepts
+
+| Concept           | Closed values or states | Meaning                                                                                               | Availability by variant/orientation/state               | Default | Owner            | Stability                        | Invalid-value behavior                       |
+| ----------------- | ----------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | ------- | ---------------- | -------------------------------- | -------------------------------------------- |
+| Edge compensation | omitted, `inline`       | Move row content toward both logical host content edges while retaining row-local interaction padding | Every List density and marker style in an eligible host | omitted | `component:List` | accepted; implementation pending | Other values are rejected by the public type |
+
+## Behavioral and layout contract
+
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                         | Basis                                                               | Status                                    |
+| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ----------------------------------------- |
+| FR1 | List MUST own `edgeCompensation?: 'inline'`; ListItem MUST NOT expose a parallel public prop.                                                                                                                                                                                                                                                                     | `component:List/DEC-1`                                              | Accepted contract; implementation pending |
+| FR2 | Omission MUST preserve current header, list, and row geometry. Enabling `inline` MUST leave the optional header in place and apply one compensation policy to every ListItem, including non-interactive rows.                                                                                                                                                     | Owner direction                                                     | Accepted contract; implementation pending |
+| FR3 | Each row MUST resolve each logical margin independently as the negative smaller of its own component-owned inline inset and the matching available host inset. Missing host inset MUST resolve to zero. Content reaches the host line only when the host inset is at least the row inset; otherwise it moves toward that line without crossing the host boundary. | `architecture:container-padding/INV9–INV10`; `component:List/DEC-2` | Accepted contract; implementation pending |
+| FR4 | The retained row inset MUST come from the same private density- and theme-derived source as Item's applied inline padding. A consumer override of row padding through `xstyle`, `className`, or `style` is outside the alignment guarantee; `edgeCompensation` MUST NOT mirror or infer that arbitrary CSS.                                                       | Shared two-owner geometry contract                                  | Accepted contract; implementation pending |
+| FR5 | Compensation MUST preserve Item's hover, press, selection, focus, content, semantics, and hit target. It MUST NOT make the row a full-bleed surface or pull it past either available host edge.                                                                                                                                                                   | Owner direction                                                     | Accepted contract; implementation pending |
+| FR6 | The opt-in is valid only under a host state whose published inline inset matches its applied padding and whose relevant boundary is visually neutral. Current automatic LayoutContent/LayoutPanel states with known publication mismatch are not eligible until that conformance gap is fixed.                                                                    | `architecture:container-padding/INV8–INV11`                         | Accepted contract; implementation pending |
+
+### Allowed variation
+
+- Density and `item.paddingInline` theme overrides may change the retained inset;
+  compensation follows the same derived value.
+- Container padding may be uniform, asymmetric, zero, or absent; each logical
+  edge resolves independently.
+- Labels, descriptions, markers, start/end content, interactivity, and selection
+  may vary without changing the collection-wide alignment rule.
+
+### Representative states
+
+| State                                | Required invariant                                                                      | Allowed variation                                         |
+| ------------------------------------ | --------------------------------------------------------------------------------------- | --------------------------------------------------------- |
+| Default/omitted                      | Header and every row keep current geometry.                                             | Any current List content and density.                     |
+| Host inset at least Item inset       | Row content reaches the host content line; row-local paint keeps Item padding.          | Uniform or asymmetric inline padding.                     |
+| Smaller, zero, or missing host inset | The row moves only by the available inset and is never pulled beyond the host boundary. | Either logical edge may independently be smaller or zero. |
+| LTR or RTL                           | Logical start/end mapping follows direction without changing the `inline` meaning.      | Writing direction.                                        |
+| Themed Item padding                  | Row padding and compensation move together.                                             | Supported `item.paddingInline` value.                     |
+
+### Transformation and precedence order
+
+- **ORD1 — Host bound.** Read the matching published host inset for each selected
+  logical edge, with missing values falling back to zero.
+- **ORD2 — Local inset.** Resolve Item's component-owned inline inset from density
+  and theme through the same private value that supplies applied padding.
+- **ORD3 — Compensation.** Apply the negative minimum of those values to the row;
+  then compose supported consumer styles without claiming alignment for a consumer
+  override of row inline padding.
+
+### Performance and resources
+
+- **PR1 — CSS geometry only.** Edge compensation MUST add no measurement,
+  observer, listener, state, Effect, or render pass.
+
+## Accessibility contract
+
+- **AR1 — Interaction geometry remains local.** Compensation MUST NOT change the
+  interactive element, accessible role/name/state, focus target, tab order, or
+  hit target.
+- **AR2 — Direction remains logical.** The same `inline` value MUST produce the
+  corresponding mirrored geometry under RTL without changing DOM order.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                                                                          | Representation authority | Hierarchy role     | Component contract |
+| ---------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------ | ------------------ | ------------------ |
+| Optional header  | Stays on the host content line and is not moved by row compensation.                                        | `component:List/DEC-1`   | Context            | FR2                |
+| ListItem row     | Retains local interaction paint and hit-target padding.                                                     | Item composition         | Supporting surface | FR3–FR5            |
+| Row content      | Moves toward each host content line and reaches it only when the host inset can fully absorb the row inset. | `component:List/DEC-2`   | Prominent          | FR2–FR5            |
+
+## Family and system relationships
+
+- `architecture:container-padding` owns host publication, the shared
+  `edgeCompensation` vocabulary, eligibility, logical-edge semantics, and overlay
+  reset.
+- `architecture:public-component-api` and `spec:AST-002` own public API admission.
+- Item remains the implementation owner of row padding and interaction paint;
+  List owns only the collection-level opt-in and row application.
+
+## Verification map
+
+| Contract         | Verification                                                 | Representative states                                                                                                               | Mutation or failure expectation                                                                          | Audit section       |
+| ---------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ------------------- |
+| FR1–FR4          | List, Item, and theme-registry tests                         | omitted/enabled; all densities; theme override; static/interactive rows                                                             | Removing context propagation, duplicating a padding value, or using one host edge for both margins fails | `audit:List/layout` |
+| FR2–FR6, AR1–AR2 | Real-browser List geometry evidence                          | header; LTR/RTL; uniform/asymmetric/zero/missing host inset; host inset smaller/equal/larger than Item inset; hover/selection/focus | Header movement, over-pull, wrong bounded movement, or lost row-local paint fails                        | `audit:List/visual` |
+| Documentation    | `List.doc.mjs`, Storybook, and `scripts/check-knowledge.mjs` | public prop/default and representative composition                                                                                  | Missing or stale contract, docs, or example fails                                                        | `audit:List/docs`   |
+
+## Decision log
+
+### DEC-1 — List owns the collection-wide opt-in
+
+**Reference:** `component:List/DEC-1`
+
+**Decider:** cixzhang, 2026-09-21
+
+The List header and ListItem rows otherwise begin on different content lines.
+Only the caller knows when the containing composition requires alignment, while
+List can apply one consistent decision to every row without exposing Item-level
+configuration.
+
+### DEC-2 — Compensation is row-local and bounded
+
+**Reference:** `component:List/DEC-2`
+
+**Decider:** cixzhang, 2026-09-21
+
+Each row cancels no more than its own component-owned inline inset or the
+matching host inset. When the host inset is at least the row inset, content
+reaches the host content line. When it is smaller, content moves toward that line
+without pulling row paint beyond the host boundary.
+
+Rejected: `isFullBleed`, because the row may stop inside the host padding and the
+name would promise outer-edge bleed that the component does not provide.
+
+## Open questions
+
+None.
+
+## Content boundary
+
+This claim-scoped contract does not duplicate List's complete prop table,
+container-padding internals, consumer examples, implementation steps, or future
+TabList/Button projections. Those remain with their named owners.