@astryxdesign/core 0.7.6-canary.f73623d → 0.7.6-canary.f77aaf2

package/src/Card/Card.spec.md

@@ -1,205 +0,0 @@
----
-schema_version: 3
-template_version: 7
-kind: component
-id: component:Card
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-10-28
-owners: [cixzhang]
-review_triggers: [public-api, behavior, layout, theming, accessibility]
-verified_by:
-  [
-    .github/visual-baseline/manifest.json,
-    packages/core/src/Card/Card.test.tsx,
-    packages/core/src/theme/themingTargets.test.ts,
-    packages/core/src/theme/extensibleAxes.test.ts,
-    apps/storybook/stories/Card.stories.tsx,
-    scripts/check-knowledge.mjs,
-  ]
-modules: []
-families: []
-design_specs: []
-architecture:
-  [
-    architecture:component-theming-surface,
-    architecture:container-padding,
-    architecture:public-component-api,
-  ]
-contributing: []
-system_specs: []
----
-
-# Card component contract
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                                                                                 |
-| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | A container with sizing props, `padding` on the spacing scale, a theme-extensible `variant`, and a resting `elevation`.                                                                                  |
-| Behavior                | Card paints a rounded surface, publishes its padding to descendants through the container-padding protocol, and only the `default` variant draws a border.                                               |
-| End-user impact         | Readers see grouped content on a consistent surface; with the default border and theme border width, content insets stay on the spacing scale whether or not a border is drawn, except at zero padding.  |
-| Builder impact          | None; the record describes shipped behavior.                                                                                                                                                             |
-| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. One implementation gap is listed under Current-state impact.                                                                  |
-| Review checks           | Reject a card that holds its track at min-content width, a variant that falls through to another variant, a lost padding publication, or a published inset that drifts further from the applied padding. |
-| Governing rules         | `architecture:container-padding` (container publisher); `architecture:component-theming-surface/INV6,INV14`; `architecture:public-component-api/INV5,INV6,INV8`.                                         |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-Card groups related content on a contained surface. It owns the surface's
-paint, border, radius, and elevation, its sizing, and the padding it publishes
-so Layout and other descendants align to it.
-
-## Compatibility and migration
-
-- Released default preserved: `yes`
-- Compatibility class: records shipped behavior; no public prop, default, DOM,
-  or styling output changes
-- Controlled/uncontrolled behavior: not applicable
-- Migration decision: none
-
-Consumer migration instructions belong in consumer docs and release notes.
-
-## Current-state impact
-
-- **Published inset exceeds applied padding (FR3).** At nonzero padding a
-  `default` card applies padding reduced by its border width but publishes
-  border plus padding (at `padding={0}` the two match). Every child that bleeds
-  to the published inset, on any edge — a full-bleed Divider, a Layout, or a
-  List `outset` or `bleed` box — overshoots the padding edge by the border
-  width. A fixed-height card holding such a child scrolls by that amount on
-  each axis the child bleeds on (both for a Layout) and becomes an unnamed tab
-  stop even when its content fits: in Chromium when it holds nothing
-  focusable, in Firefox even when it holds a focusable child. `architecture:container-padding` INV11
-  has a host publish its applied padding, and `component:List` FR8 counts a
-  Card's content area as such a host, so a `default` card at nonzero padding
-  does not yet meet List FR8: List `outset` and `bleed` lists cross its padding edge by the border width, and `bleed` rows with them.
-
-## Ownership boundary
-
-**Owns**
-
-- The Container: surface paint, border, radius, elevation, sizing, and
-  clipping.
-- Resolving and publishing card padding as a container publisher.
-
-**Does not own / non-goals**
-
-- Content structure inside the card — owned by the caller and Layout.
-- Interaction — owned by `component:ClickableCard` and
-  `component:SelectableCard`, which compose Card.
-- The padding protocol itself — owned by `architecture:container-padding`.
-
-## Public concepts
-
-| Concept   | Closed values or states                                                                                                                  | Meaning                                                 | Availability by variant/orientation/state | Default            | Owner            | Stability | Invalid-value behavior                                                                              |
-| --------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | ----------------------------------------- | ------------------ | ---------------- | --------- | --------------------------------------------------------------------------------------------------- |
-| Variant   | `default`, `transparent`, `muted`, `blue`, `cyan`, `gray`, `green`, `orange`, `pink`, `purple`, `red`, `teal`, `yellow`; theme additions | Surface paint; only `default` draws a border.           | Always                                    | `default`          | `component:Card` | Stable    | A theme-added value is reflected on `card` and renders the base surface with no fill and no border. |
-| Elevation | `none`, `low`, `med`, `high`                                                                                                             | Resting shadow from the shadow token scale.             | Always                                    | `none`             | `component:Card` | Stable    | TypeScript rejects other values.                                                                    |
-| Padding   | Spacing steps 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10; omitted                                                                              | Uniform padding; omitted uses the theme's card padding. | Always                                    | theme card padding | `component:Card` | Stable    | TypeScript rejects other values.                                                                    |
-| Sizing    | `width`, `height`, `maxWidth`, `minHeight`: numbers in pixels or CSS strings                                                             | The card's box size.                                    | Always                                    | unset              | `component:Card` | Stable    | Strings pass through as CSS.                                                                        |
-
-## Behavioral and layout contract
-
-| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Basis                    |
-| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
-| FR1 | Card renders one `div` carrying the `card` target, which reflects `variant` and `elevation`, with `--radius-container` corners and a box shadow composed of the selection ring and the elevation shadow.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Current source and tests |
-| FR2 | `default` paints `--color-background-card` with a `--border-width` solid `--color-border` border; `transparent` paints nothing; `muted` paints `--color-background-muted`; each palette variant paints its `--color-background-<name>` tint. A theme-added variant falls through to the base surface, never to another variant.                                                                                                                                                                                                                                                                                                                                                                                                                                            | Current source and tests |
-| FR3 | Card resolves padding as a container publisher: an omitted `padding` uses the theme's card padding (spacing step 4 with no theme), and a step applies uniformly to every edge. With the `default` border, each edge's padding is reduced by the global `--border-width` token (stopping at zero), so border plus padding matches the borderless inset. The published inset matches the padding the card applies (`architecture:container-padding` INV11). Implementation gap: at nonzero padding a `default` card publishes border plus padding, one border width more than its applied padding, so a full-bleed child overshoots the padding edge, a fixed-height card scrolls by that width, and the card does not yet meet `component:List` FR8 (Current-state impact). | Current source and tests |
-| FR4 | Card has zero minimum width, so it yields to its track instead of holding it at its min-content width, and clips overflow without becoming a scroll container. A `height` other than `auto` makes it scroll. `width`, `height`, `maxWidth`, and `minHeight` apply as given, and a caller minimum can win over `width`.                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Current source and tests |
-| FR5 | `elevation` sets the elevation shadow to none or the low, medium, or high shadow token.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Current source and tests |
-| FR6 | `ref` reaches the `div`. Supported DOM, ARIA, data, and event props reach the element carrying the target; `xstyle`, `className`, and `style` merge in that order after component styles, and a caller `className` joins the target class rather than replacing it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Current source and tests |
-
-### Allowed variation
-
-- **AV1 — Theme paint and padding.** A theme may restyle `card` per `variant`
-  and `elevation`, including border width and color, and set the card padding.
-- **AV2 — Content.** Any content may fill the card.
-
-### Representative states
-
-| State               | Required invariant                                                                                 | Allowed variation |
-| ------------------- | -------------------------------------------------------------------------------------------------- | ----------------- |
-| Default             | Card surface with border; inset equals the theme card padding.                                     | Content.          |
-| Borderless variant  | No border; same inset as `default` except at `padding={0}`, where `default` adds its border width. | Variant.          |
-| Theme-added variant | Base surface; `data-variant` names the added value.                                                | Theme paint.      |
-| Fixed height        | Scrolls its content; still yields in its track.                                                    | Height.           |
-| Elevated            | Elevation shadow alongside any ring.                                                               | Elevation.        |
-
-### Transformation and precedence order
-
-- **ORD1 — Padding.** `padding` step → theme card padding → spacing step 4;
-  then subtract the border width per edge for `default`, stopping at zero.
-- **ORD2 — Shadow.** Ring and elevation compose in one shadow list; neither
-  replaces the other.
-
-### Performance and resources
-
-- **PR1 — Static render.** Card holds no state and uses no hooks.
-
-## Accessibility contract
-
-- **AR1 — No semantics added.** Card adds no role, name, or tab stop of its own;
-  its content's semantics pass through. Exception: a fixed-height card whose
-  content overflows is a scroll container (FR4), and browsers may make it an
-  unnamed tab stop so keyboard users can scroll it (Chromium when it holds
-  nothing focusable; Firefox even when it holds a focusable child).
-
-## Design relationships
-
-| Anatomy or state | Design requirement                                           | Representation authority | Hierarchy role | Component contract |
-| ---------------- | ------------------------------------------------------------ | ------------------------ | -------------- | ------------------ |
-| Container        | A rounded surface with background, optional border, padding. | Current source and docs  | Supporting     | FR1–FR5            |
-| Content          | Caller content inside the published inset.                   | Current source and docs  | Prominent      | FR3, AR1           |
-
-### Theming anatomy
-
-<!-- anatomy-theming:v1 -->
-
-```json
-{
-  "Container": {"target": "card"},
-  "Content": {
-    "none": {
-      "reason": "intentional: caller content keeps its own styling and has no component-owned paint target"
-    }
-  }
-}
-```
-
-## Family and system relationships
-
-- `architecture:container-padding` names Card a container publisher; FR3 records
-  how Card resolves and publishes its padding.
-- `component:ClickableCard` and `component:SelectableCard` compose Card; a
-  selection ring composes with Card's elevation shadow (ORD2).
-- `architecture:component-theming-surface` sets the rules the `card` target
-  follows (INV6) and qualifies `variant` as a theme-extensible axis (INV14).
-
-## Verification map
-
-| Contract            | Verification                                                                                                                                                                            | Representative states                                         | Mutation or failure expectation                                                                                                                                                                                                                                                                                                                                                                                  | Audit section         |
-| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
-| FR1, FR2, FR5, ORD2 | `Card.test.tsx` reflection, built-in variant, elevation, and theme-added variant tests; stable visual baselines `core-card--default` and `core-card--theme-added-variant` (probe theme) | Every built-in variant; elevations; added value; default card | A lost reflection, an elevation without its own class, or a theme-added value falling through to another variant fails; a changed default surface, border, radius, or rest shadow, or a theme-added card that loses its theme paint, comes back changed for review. Gap: the palette tints, the elevation shadow values, and the ring-and-shadow composition have no automated check beyond those two baselines. | `audit:Card/theming`  |
-| FR3                 | `Card.stories.tsx` in a browser                                                                                                                                                         | Default and borderless variants; padding steps                | Gap: no unit test asserts padding publication or the border subtraction; an inset mismatch is visible only in the rendered fixture. The full-bleed overshoot in a default card has no automated check.                                                                                                                                                                                                           | `audit:Card/layout`   |
-| FR4                 | `Card.test.tsx` sizing suite                                                                                                                                                            | Every variant; fixed height; caller minimum                   | A held min-content width, a scroll container without fixed height, or a lost caller minimum fails.                                                                                                                                                                                                                                                                                                               | `audit:Card/layout`   |
-| FR6                 | `Card.test.tsx` ref, passthrough, and className tests                                                                                                                                   | Ref; extra props; className                                   | A ref on another element, a prop on an element other than the target, or a replaced target class fails. Gap: no test asserts the `xstyle`, `className`, `style` merge order.                                                                                                                                                                                                                                     | `audit:Card/behavior` |
-| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                                                                                                           | Consumer anatomy and current target                           | Missing, extra, or stale mappings fail repository validation.                                                                                                                                                                                                                                                                                                                                                    | `audit:Card/theming`  |
-| AR1, PR1            | Source review                                                                                                                                                                           | Every variant                                                 | Gap: no automated check fails if Card adds a role, tab stop, state, or hook. No test covers the fixed-height overflow tab stop, with or without focusable content. No test covers the tab stop a fixed-height default card gains from a bleeding child's overshoot.                                                                                                                                              | `audit:Card/behavior` |
-
-## 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 family/system rules. It links to their owners.

package/src/Card/Card.test.tsx

@@ -1,202 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-import {createRef} from 'react';
-import {describe, it, expect} from 'vitest';
-import {render} from '@testing-library/react';
-import * as stylex from '@stylexjs/stylex';
-import {Card} from './Card';
-import type {CardVariant} from './Card';
-
-describe('Card', () => {
-  it('renders children', () => {
-    const {getByText} = render(<Card>Hello</Card>);
-    expect(getByText('Hello')).toBeInTheDocument();
-  });
-
-  describe('in a flex row or grid track', () => {
-    it('yields to its track instead of holding it at its min-content width', () => {
-      const {getByTestId} = render(<Card data-testid="card">C</Card>);
-      // Without this, `overflow: clip` keeps the automatic minimum size, so a
-      // long unbroken value widens the row or a `1fr` track past its parent.
-      expect(getComputedStyle(getByTestId('card')).minWidth).toBe('0');
-    });
-
-    it('clips rather than scrolls, so it never becomes a scroll container', () => {
-      const {getByTestId} = render(<Card data-testid="card">C</Card>);
-      const style = getComputedStyle(getByTestId('card'));
-      // A scroll container would capture sticky descendants and become an
-      // unnamed keyboard tab stop whenever its content overflows.
-      expect(style.overflow).toBe('clip');
-      expect(style.overflowX).not.toBe('auto');
-    });
-
-    it('yields the same way for every variant and elevation', () => {
-      const {getByTestId} = render(
-        <>
-          <Card data-testid="muted" variant="muted" elevation="high">
-            C
-          </Card>
-          <Card data-testid="transparent" variant="transparent">
-            C
-          </Card>
-        </>,
-      );
-      expect(getComputedStyle(getByTestId('muted')).minWidth).toBe('0');
-      expect(getComputedStyle(getByTestId('transparent')).minWidth).toBe('0');
-    });
-
-    it('still scrolls a fixed-height card and lets it yield', () => {
-      const {getByTestId} = render(
-        <Card data-testid="card" height={200}>
-          C
-        </Card>,
-      );
-      const style = getComputedStyle(getByTestId('card'));
-      expect(style.overflow).toBe('auto');
-      expect(style.minWidth).toBe('0');
-    });
-
-    it('keeps width as the preferred size and lets a consumer minimum win', () => {
-      const overrides = stylex.create({hold: {minWidth: 240}});
-      const {getByTestId} = render(
-        <>
-          <Card data-testid="sized" width={320}>
-            C
-          </Card>
-          <Card data-testid="held" width={320} xstyle={overrides.hold}>
-            C
-          </Card>
-        </>,
-      );
-      // An explicit width does not become a floor: in a narrow row the card
-      // still yields, and a consumer minimum is the way to hold it.
-      expect(getComputedStyle(getByTestId('sized')).minWidth).toBe('0');
-      expect(getComputedStyle(getByTestId('held')).minWidth).toBe('240px');
-    });
-  });
-
-  it('forwards ref to the rendered element', () => {
-    const ref = createRef<HTMLDivElement>();
-    const {container} = render(<Card ref={ref}>C</Card>);
-    expect(ref.current).toBe(container.firstElementChild);
-  });
-
-  it('spreads unknown props onto the same element that carries the theme target', () => {
-    const {getByTestId} = render(
-      <Card data-testid="card" id="promo" aria-label="Promotion">
-        C
-      </Card>,
-    );
-    const root = getByTestId('card');
-    expect(root).toHaveAttribute('id', 'promo');
-    expect(root).toHaveAttribute('aria-label', 'Promotion');
-    expect(root.className).toContain('astryx-card');
-  });
-
-  it('merges a consumer className instead of replacing the theme target', () => {
-    const {container} = render(<Card className="promo">C</Card>);
-    const root = container.firstElementChild!;
-    expect(root.className).toContain('astryx-card');
-    expect(root.className).toContain('promo');
-  });
-
-  it('reflects variant as a theme data attribute', () => {
-    const {container} = render(<Card variant="muted">C</Card>);
-    expect(container.firstElementChild).toHaveAttribute(
-      'data-variant',
-      'muted',
-    );
-  });
-
-  it('reflects elevation as a theme data attribute', () => {
-    const {container} = render(<Card elevation="high">C</Card>);
-    expect(container.firstElementChild).toHaveAttribute(
-      'data-elevation',
-      'high',
-    );
-  });
-
-  it('defaults to the default variant at rest elevation', () => {
-    const {container} = render(<Card>C</Card>);
-    const root = container.firstElementChild!;
-    expect(root).toHaveAttribute('data-variant', 'default');
-    expect(root).toHaveAttribute('data-elevation', 'none');
-  });
-
-  it('applies a distinct class for each elevation level', () => {
-    const classFor = (elevation: 'none' | 'low' | 'med' | 'high') => {
-      const {container} = render(<Card elevation={elevation}>C</Card>);
-      return container.firstElementChild!.className;
-    };
-    const classes = (['none', 'low', 'med', 'high'] as const).map(classFor);
-    expect(new Set(classes).size).toBe(4);
-  });
-
-  // Deriving the prop from CardVariantMap must not change which values it
-  // accepts. A key added to or dropped from the map fails to type-check here:
-  // a missing one against Record<CardVariant, true>, an extra one as an excess
-  // property.
-  const builtInVariants: Record<CardVariant, true> = {
-    default: true,
-    transparent: true,
-    muted: true,
-    blue: true,
-    cyan: true,
-    gray: true,
-    green: true,
-    orange: true,
-    pink: true,
-    purple: true,
-    red: true,
-    teal: true,
-    yellow: true,
-  };
-
-  it('accepts exactly the thirteen built-in variants, each reflected', () => {
-    const variants = Object.keys(builtInVariants) as CardVariant[];
-    expect(variants).toHaveLength(13);
-    for (const variant of variants) {
-      const {container} = render(<Card variant={variant}>C</Card>);
-      expect(container.firstElementChild).toHaveAttribute(
-        'data-variant',
-        variant,
-      );
-    }
-  });
-
-  describe('a variant a theme added', () => {
-    // The cast stands in for the module augmentation `astryx theme build`
-    // emits; that the augmentation itself widens the prop is covered by
-    // packages/cli/clients/cli/commands/build-theme.variants.test.mjs.
-    const themeAdded = 'brand' as CardVariant;
-
-    const classesFor = (variant: CardVariant) => {
-      const {container} = render(<Card variant={variant}>C</Card>);
-      return new Set(container.firstElementChild!.className.split(' '));
-    };
-
-    it('renders the selector a theme rule needs', () => {
-      const {container} = render(<Card variant={themeAdded}>C</Card>);
-      const root = container.firstElementChild!;
-      expect(root).toHaveAttribute('data-variant', 'brand');
-      expect(root.className).toContain('astryx-card');
-      expect(root).toHaveAttribute('data-variant', 'brand');
-    });
-
-    it('falls through to base styles instead of another variant', () => {
-      const muted = classesFor('muted');
-      const blue = classesFor('blue');
-      const brand = classesFor(themeAdded);
-
-      const variantOwned = [
-        ...[...muted].filter(c => !blue.has(c)),
-        ...[...blue].filter(c => !muted.has(c)),
-      ];
-      const shared = [...muted].filter(c => blue.has(c));
-
-      expect(variantOwned.length).toBeGreaterThan(0);
-      expect(variantOwned.filter(c => brand.has(c))).toEqual([]);
-      expect(shared.filter(c => !brand.has(c))).toEqual([]);
-    });
-  });
-});

package/src/Carousel/Carousel.spec.md

@@ -1,146 +0,0 @@
----
-schema_version: 3
-template_version: 7
-kind: component
-id: component:Carousel
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-10-22
-owners: [cixzhang]
-review_triggers: [behavior, accessibility]
-verified_by:
-  [
-    packages/core/src/Carousel/Carousel.test.tsx,
-    packages/core/src/Carousel/__tests__/Carousel.a11y.chromium.spec.ts,
-  ]
-modules: []
-families: [family:buttons]
-design_specs: []
-architecture: [architecture:interaction-modality]
-contributing: []
-system_specs: [spec:AST-085, spec:AST-025]
----
-
-# Carousel component contract
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                                                                                                                                                 |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Public contract         | None changes.                                                                                                                                                                                                                                                            |
-| Behavior                | An edge scroll button whose direction has run out is hidden and takes no tab stop. When the focused edge button runs out, focus moves to the scroll area.                                                                                                                |
-| End-user impact         | A keyboard user who scrolls to the first or last item stays inside the carousel instead of landing on the page body or on an invisible control. The scroll area is a group named like the carousel (`spec:AST-025` FR12), so screen-reader users hear where they landed. |
-| Builder impact          | None.                                                                                                                                                                                                                                                                    |
-| Compatibility/readiness | No API change. Shipped Carousel and its current tests still use native `disabled` and hand focus to the opposite button; they change with conformance work.                                                                                                              |
-| Review checks           | Reject focus left on a hidden edge button, focus dropped to the page body, or an edge handoff that moves focus to anything but the scroll area.                                                                                                                          |
-| Governing rules         | `spec:AST-085` FR1, FR4; `spec:AST-025` FR12; `architecture:interaction-modality` INV1.                                                                                                                                                                                  |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-Carousel shows a horizontally scrolling row of items inside a labelled region,
-with optional scroll buttons at each edge. This record covers only what the edge
-scroll buttons do when their direction runs out. Other Carousel behavior is
-uncontracted until this record grows.
-
-## Compatibility and migration
-
-- Released default preserved: yes, except where focus lands at an edge.
-- Compatibility class: behavior correction; no API change.
-- Controlled/uncontrolled behavior: unchanged.
-- Migration decision: DEC-1.
-
-Consumer migration instructions belong in consumer docs and release notes.
-
-## Ownership boundary
-
-**Owns**
-
-- Edge scroll button visibility, tab order, and the focus destination when one
-  runs out.
-
-**Does not own / non-goals**
-
-- Scroll area keyboard access and naming — `spec:AST-025`.
-- Disabled control semantics in general — `spec:AST-085`.
-- Button naming, sizing, and activation — `family:buttons`.
-- Looping, snapping, edge fades, and slide semantics — uncontracted.
-
-## Public concepts
-
-| Concept            | Closed values or states | Meaning                                            | Availability by variant/orientation/state | Default | Owner                | Stability | Invalid-value behavior |
-| ------------------ | ----------------------- | -------------------------------------------------- | ----------------------------------------- | ------- | -------------------- | --------- | ---------------------- |
-| Edge scroll button | available, run out      | Whether content remains in that button's direction | Both edges when the carousel overflows    | —       | `component:Carousel` | stable    | not applicable         |
-
-## Behavioral and layout contract
-
-| ID  | Candidate invariant                                                                                                                                                                                                                                                                                                    | Basis                                    | Draft review state |
-| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | ------------------ |
-| FR1 | An edge scroll button whose direction has run out is hidden. While hidden it takes no tab stop and is not exposed to assistive technology. It stays mounted so layout does not shift. This is removal under `spec:AST-085` FR4, not a disabled control.                                                                | DEC-1                                    | settled            |
-| FR2 | When the focused edge scroll button runs out, focus moves to the scroll area without scrolling it. This holds when the content no longer overflows and the scroll area is out of the tab order (`spec:AST-025` FR12): it still takes focus programmatically. Focus never lands on the page body or on a hidden button. | DEC-1; `spec:AST-085` FR4                | settled            |
-| FR3 | The handoff happens once per edge transition, and only while the edge button held focus. An edge reached by swipe, resize, or wheel while focus is elsewhere moves nothing.                                                                                                                                            | `architecture:interaction-modality` INV8 | settled            |
-| FR4 | An edge scroll button that is available behaves as an ordinary Button.                                                                                                                                                                                                                                                 | `family:buttons`                         | settled            |
-
-### Representative states
-
-| State                                  | Required invariant                                              | Allowed variation       |
-| -------------------------------------- | --------------------------------------------------------------- | ----------------------- |
-| Mid-scroll                             | Both edge buttons available                                     | Loop keeps both enabled |
-| Focused "Scroll right" reaches the end | Button hides; focus is on the scroll area; no extra scroll      | Reduced motion          |
-| Edge reached by swipe, focus elsewhere | Button hides; focus does not move                               | —                       |
-| Content shrinks to fit                 | Both buttons hidden; a focused one hands off to the scroll area | —                       |
-
-## Accessibility contract
-
-- **AR1 — No invisible tab stops.** A hidden edge button is not focusable and is
-  not exposed to assistive technology (FR1).
-- **AR2 — Focus stays in the region.** The edge handoff keeps focus inside the
-  labelled carousel region (FR2), and the keyboard focus indicator follows
-  `architecture:interaction-modality` INV1.
-
-## Design relationships
-
-No design record governs Carousel yet. Edge button visuals stay in code and
-visual evidence.
-
-## Family and system relationships
-
-- `spec:AST-085` FR4 lets a component name a focus destination for a control it
-  removes; FR2 names the scroll area.
-- `spec:AST-025` FR12 owns the scroll area's tab stop and naming.
-- `family:buttons` owns the edge buttons' behavior while available.
-
-## Verification map
-
-| Contract | Verification                            | Representative states                                    | Mutation or failure expectation                                                | Audit section                  |
-| -------- | --------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------ |
-| FR1, AR1 | Unit and accessibility-tree tests       | at rest at each edge; no overflow                        | A hidden button that is focusable or exposed fails                             | `audit:Carousel/accessibility` |
-| FR2, AR2 | Real-browser keyboard test              | Enter on "Scroll right" until the end; same on the start | Focus on the page body, a hidden button, or the opposite button fails          | `audit:Carousel/accessibility` |
-| FR3      | Real-browser test with swipe and resize | edge reached with focus outside the carousel             | Focus moving without an edge-button press, or moving twice for one edge, fails | `audit:Carousel/accessibility` |
-
-## Decision log
-
-### DEC-1 — The scroll area receives focus when an edge button runs out
-
-**Reference:** `component:Carousel/DEC-1`
-**Decider:** cixzhang, 2026-10-22
-
-Carousel hides an edge button whose direction has run out, so keeping focus on
-it would leave a keyboard user on an invisible control. The scroll area is always
-mounted inside the labelled region and can take focus whether or not it is in the
-tab order, so focus moving there keeps the user in place inside the carousel.
-
-Rejected: the opposite edge button — it may be hidden too, and focus would jump
-across the carousel.
-
-## 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.