@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/SideNav/railMotion.ts

@@ -0,0 +1,315 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file railMotion.ts
+ * @input The rail's outer element, the animated-layout module's handle,
+ *   motion and in-place swap (motion/animatedLayout.ts)
+ * @output Exports `SideNavShellContext` (what AppShell lends its SideNav),
+ *   `createRailLayout`, `snapshotRail` and `playRail`: the rail's collapse
+ *   motion
+ * @position Internal to SideNav (`component:SideNav` FR6, DEC-2); AppShell's
+ *   content area moves through the context (`component:AppShell` FR17)
+ *
+ * Collapsing or expanding the rail plays one motion on one clock, the
+ * `springs.settle` role the animated-layout module reads (`spec:AST-105`
+ * FR4):
+ * - Layout snaps to the final rail width at once; nothing animates a width.
+ * - A collapse covers the old rail by a clip: the module's in-place swap
+ *   (`spec:AST-105` FR8) holds the old, expanded rail as one transient copy
+ *   and the clip closes it to the new width. The copy's text fades over the
+ *   first 40%; the real collapsed rail, raised above the copy, fades in over
+ *   the last 30%, so the real rail, icons only, is all that remains.
+ * - An expand reveals the real rail by a clip from the old width, its text
+ *   fading in over the last 60% so no label shows at the collapsed width,
+ *   under the old, collapsed rail held by the same swap, which fades over the
+ *   first 60%: the first frame is the frame before the click.
+ * - In AppShell the rail's edge rides the content column's glide, frame by
+ *   frame, so the two never part, also when a change interrupts a running
+ *   one; the copy is laid in the row that holds both.
+ * - A change made during a running motion starts from what the rail shows:
+ *   its width, its labels' opacity and its collapsed icons' opacity, so the
+ *   rail stays continuous.
+ * - Every starting clip applies in the commit's layout effect, before the
+ *   first frame paints.
+ * - Under Reduce Motion it follows `design:reduced-motion`: opacity only
+ *   under a coarse primary pointer (DR2), an immediate change otherwise
+ *   (DR3). Without Web Animations, the change lands at once.
+ *
+ * SYNC: When modified, update SideNav.tsx, AppShell.tsx and
+ * SideNavRailMotion.test.tsx.
+ */
+
+import {createContext} from 'react';
+import {
+  createAnimatedLayout,
+  holdLayoutSwap,
+  layoutMotionFor,
+  playLayoutFrames,
+  playLayoutSwap,
+  type AnimatedLayout,
+  type LayoutSwap,
+} from '../motion/animatedLayout';
+
+/** What AppShell lends its SideNav; outside AppShell, nothing. */
+export interface SideNavShell {
+  /** AppShell's own handle, whose area holds the rail and the content. */
+  readonly animatedLayout: AnimatedLayout;
+  /** The rail's outer element, which paints its background. */
+  rail(): HTMLElement | null;
+  /** The content column beside the rail, which glides. */
+  column(): HTMLElement | null;
+  /** In the commit, before the DOM changes: the content measures itself. */
+  beforeRailChange(): void;
+  /** After it, before paint: the content moves; returns what ends it. */
+  afterRailChange(): () => void;
+  /** The content lands where it is laid out, ending any running glide. */
+  landContent(): void;
+}
+
+export const SideNavShellContext = createContext<SideNavShell | null>(null);
+SideNavShellContext.displayName = 'SideNavShellContext';
+
+/** A SideNav outside AppShell holds its own handle over its parent. */
+export function createRailLayout(
+  rail: () => HTMLElement | null,
+): AnimatedLayout {
+  return createAnimatedLayout(() => rail()?.parentElement ?? null);
+}
+
+/** What a rail shows: at rest, or partway through a motion. */
+export interface RailShown {
+  readonly width: number;
+  /** The labels' opacity. */
+  readonly labels: number;
+  /** The collapsed rail's opacity (its icons). */
+  readonly collapsed: number;
+}
+
+export interface RailSnapshot {
+  readonly rail: HTMLElement;
+  readonly railRect: DOMRect;
+  /** What the rail shows when the change lands. */
+  readonly shown: RailShown;
+  /** The old rail, held by the swap. */
+  readonly swap: LayoutSwap | null;
+}
+
+/** A playing rail motion. */
+export interface RailMotion {
+  /** Ends it at once (a new change, an unmount). */
+  end(): void;
+  /** What the rail shows now, or null once it has settled. */
+  shown(): RailShown | null;
+}
+
+/**
+ * Before the change commits: the old rail, where it was, and what it shows,
+ * from a running motion or at rest.
+ */
+export function snapshotRail(
+  rail: HTMLElement | null,
+  handle: AnimatedLayout,
+  running: RailShown | null,
+  isCollapsed: boolean,
+): RailSnapshot | null {
+  if (rail == null || typeof rail.animate !== 'function') {
+    return null;
+  }
+  const railRect = rail.getBoundingClientRect();
+  return {
+    rail,
+    railRect,
+    shown: running ?? {
+      width: railRect.width,
+      labels: isCollapsed ? 0 : 1,
+      collapsed: isCollapsed ? 1 : 0,
+    },
+    swap: holdLayoutSwap(handle, rail),
+  };
+}
+
+const clamp = (value: number) => Math.min(1, Math.max(0, value));
+
+/** The rail's own text: elements that hold a run of text directly. */
+function textElements(rail: HTMLElement): Element[] {
+  return Array.from(rail.querySelectorAll('*')).filter(element =>
+    Array.from(element.childNodes).some(
+      node => node.nodeType === 3 && node.textContent?.trim(),
+    ),
+  );
+}
+
+/** `element`'s ancestor (or itself) that sits directly in `host`. */
+function childOf(host: Element, element: HTMLElement): HTMLElement | null {
+  let node: HTMLElement | null = element;
+  while (node != null && node.parentElement !== host) {
+    node = node.parentElement;
+  }
+  return node;
+}
+
+const AT_REST: RailMotion = {end: () => {}, shown: () => null};
+
+/**
+ * After the change commits, before paint: play the rail's motion from the
+ * snapshot, on the module's motion. With a `column` (in AppShell), the rail's
+ * edge rides its glide.
+ */
+export function playRail(
+  snapshot: RailSnapshot,
+  current: HTMLElement | null,
+  handle: AnimatedLayout,
+  column: HTMLElement | null = null,
+): RailMotion {
+  const {railRect, swap, shown: from} = snapshot;
+  // The rail as it is now: a resizable rail's nav remounts when its resize
+  // wrapper comes and goes with the collapse.
+  const rail = current?.isConnected === true ? current : snapshot.rail;
+  if (!rail.isConnected) {
+    return AT_REST;
+  }
+  const motion = layoutMotionFor(rail);
+  const next = rail.getBoundingClientRect();
+  if (motion.kind === 'instant' || Math.abs(next.width - from.width) < 0.5) {
+    return AT_REST;
+  }
+  const isCollapse = next.width < from.width;
+  // The labels and the collapsed icons over the motion's progress, from what
+  // the rail showed.
+  const labelsAt = (p: number) =>
+    isCollapse
+      ? from.labels * (1 - clamp(p / 0.4))
+      : from.labels + (1 - from.labels) * clamp((p - 0.4) / 0.6);
+  const collapsedAt = (p: number) =>
+    isCollapse
+      ? from.collapsed + (1 - from.collapsed) * clamp((p - 0.7) / 0.3)
+      : from.collapsed * (1 - clamp(p / 0.6));
+  const rtl = getComputedStyle(rail).direction === 'rtl';
+  const sign = rtl ? -1 : 1;
+  const inset = (px: number) =>
+    rtl ? `inset(0px 0px 0px ${px}px)` : `inset(0px ${px}px 0px 0px)`;
+  // The row that holds the rail and the column, or the rail's parent.
+  const host =
+    column?.parentElement != null && column.parentElement.contains(rail)
+      ? column.parentElement
+      : rail.parentElement;
+  // Riding needs the swap: its frames carry the column's travel. Without one
+  // (old content that cannot be copied) the clip follows the motion's curve.
+  const rides = host != null && column?.parentElement === host && swap != null;
+  // The width the rail shows over the motion: on the column's glide (its
+  // travel so far added to where it started), or on the motion's curve.
+  const widthAt = (p: number, ride: {x: number}) =>
+    rides
+      ? from.width + sign * ride.x
+      : from.width + (next.width - from.width) * p;
+  const now = () => Number(rail.ownerDocument.timeline?.currentTime ?? 0);
+  const startedAt = now();
+  const durationMs =
+    motion.kind === 'spring' ? motion.progress.durationMs : motion.durationMs;
+  const shown = (): RailShown | null => {
+    const elapsed = now() - startedAt;
+    if (elapsed >= durationMs) {
+      return null;
+    }
+    const p =
+      motion.kind === 'spring' ? 1 - motion.progress.remaining(elapsed) : 0;
+    let width = from.width + (next.width - from.width) * p;
+    if (rides && column != null) {
+      // The rail's edge is the column's: read it where it shows.
+      const edge = column.getBoundingClientRect();
+      const own = rail.getBoundingClientRect();
+      width = rtl ? own.right - edge.right : edge.left - own.left;
+    }
+    return {width, labels: labelsAt(p), collapsed: collapsedAt(p)};
+  };
+  const rideWith =
+    rides && column != null
+      ? {
+          element: column,
+          travel: {x: sign * (from.width - next.width), y: 0},
+          isCopyMoved: false,
+        }
+      : undefined;
+  // The copy keeps the rail's inline-start edge where the rail is now, so it
+  // meets the real rail wherever SideNav sits (a centered rail moves).
+  const at = DOMRect.fromRect({
+    x: rtl ? next.right - railRect.width : next.left,
+    y: next.top,
+    width: railRect.width,
+    height: railRect.height,
+  });
+
+  if (isCollapse) {
+    // A collapse covers the old rail, held by the swap, from the width it
+    // shows down to the new one; the real, collapsed rail fades in above it.
+    if (swap == null || host == null) {
+      return AT_REST;
+    }
+    const raised = childOf(host, rail);
+    const restore =
+      raised == null
+        ? null
+        : {
+            position: raised.style.position,
+            zIndex: raised.style.zIndex,
+          };
+    if (raised != null) {
+      if (getComputedStyle(raised).position === 'static') {
+        raised.style.position = 'relative';
+      }
+      raised.style.zIndex = '2';
+    }
+    const end = playLayoutSwap(
+      {...swap, rect: at},
+      {
+        host,
+        isOpaque: true,
+        copy: (p, ride) => ({
+          clipPath: inset(railRect.width - widthAt(p, ride)),
+          opacity: 1 - clamp((p - 0.7) / 0.3),
+        }),
+        copyText: labelsAt,
+        rideWith,
+        onEnd: () => {
+          if (raised != null && restore != null) {
+            raised.style.position = restore.position;
+            raised.style.zIndex = restore.zIndex;
+          }
+        },
+        incoming: [{element: rail, frames: p => ({opacity: collapsedAt(p)})}],
+      },
+    );
+    return {end, shown};
+  }
+
+  // An expand reveals the real rail from the width it showed, its text fading
+  // in late, under the old, collapsed rail fading early.
+  const incoming = [
+    {
+      element: rail,
+      frames: (p: number, ride: {x: number}) => ({
+        clipPath: inset(next.width - widthAt(p, ride)),
+      }),
+    },
+    ...textElements(rail).map(element => ({
+      element,
+      frames: (p: number) => ({opacity: labelsAt(p)}),
+    })),
+  ];
+  const end =
+    swap != null && host != null
+      ? playLayoutSwap(
+          {...swap, rect: at},
+          {
+            host,
+            isOpaque: true,
+            copy: p => ({opacity: collapsedAt(p)}),
+            rideWith,
+            incoming,
+          },
+        )
+      : playLayoutFrames(handle, incoming);
+  return {end, shown};
+}

package/src/Skeleton/Skeleton.spec.md

@@ -1,40 +1,59 @@
 ---
 schema_version: 3
-template_version: 3
+template_version: 7
 kind: component
 id: component:Skeleton
-authority: draft
+authority: current
 archive_reason: null
 superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: cixzhang
+approved_at: 2026-10-25
 owners: [cixzhang]
-review_triggers: [theming]
+review_triggers: [public-api, behavior, layout, theming, accessibility]
 verified_by:
-  [packages/core/src/Skeleton/Skeleton.test.tsx, scripts/check-knowledge.mjs]
+  [
+    packages/core/src/Skeleton/Skeleton.test.tsx,
+    packages/core/src/theme/themingTargets.test.ts,
+    apps/storybook/stories/Skeleton.stories.tsx,
+    scripts/check-knowledge.mjs,
+  ]
 modules: []
 families: []
 design_specs: []
 architecture:
   [architecture:component-theming-surface, architecture:public-component-api]
 contributing: []
-system_specs: []
+system_specs: [spec:AST-009]
 ---
 
 # Skeleton component contract
 
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                               |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Public contract         | A placeholder block with `width`, `height`, `radius`, and a stagger `index`.                                                                           |
+| Behavior                | The block is hidden from assistive technology, waits one second, then pulses its opacity in ten steps; reduced motion keeps it static.                 |
+| End-user impact         | Sighted users see the shape of content that is loading; screen-reader users are not given empty placeholders; high-contrast users still see the block. |
+| Builder impact          | None; the record describes shipped behavior.                                                                                                           |
+| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. No implementation gap is recorded.                                          |
+| Review checks           | Reject an exposed-by-default placeholder, a `steps()` timing function, a pulse under reduced motion, or a block that disappears under forced colors.   |
+| Governing rules         | `architecture:component-theming-surface/INV2`; `architecture:public-component-api/INV5,INV6,INV8`.                                                     |
+
+This table is a review projection; the body below is authoritative.
+
 ## Intent
 
-Skeleton renders a placeholder shape while surrounding content loads. This draft
-records the component's current consumer anatomy and theming ownership without
-changing its runtime contract.
+Skeleton stands in for content while it loads, so a page keeps its layout and
+shows where content will appear. It owns the placeholder's shape, paint, pulse,
+and its exclusion from the accessibility tree.
 
 ## Compatibility and migration
 
 - Released default preserved: `yes`
-- Compatibility class: additive documentation only; runtime, DOM, styling,
-  targets, and public API remain unchanged
-- Controlled/uncontrolled behavior: not applicable
+- Compatibility class: records shipped behavior; no public prop, default, DOM,
+  styling, or target output changes
+- Controlled/uncontrolled behavior: not applicable; Skeleton holds no state
 - Migration decision: none
 
 Consumer migration instructions belong in consumer docs and release notes.
@@ -43,51 +62,85 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 **Owns**
 
-- The rendered placeholder shape and its existing `skeleton` theming target.
+- The placeholder block, its `skeleton` theming target, size, and radius.
+- Its paint in normal, increased-contrast, and forced-color modes.
+- The delayed, staggered opacity pulse and its reduced-motion suppression.
+- Its default exclusion from the accessibility tree.
 
 **Does not own / non-goals**
 
-- The surrounding content's loading state, layout, or replacement timing — owned
-  by the product callsite.
+- The surrounding region's loading state, busy semantics, layout, and when real
+  content replaces the placeholder — owned by the product callsite.
+- Indeterminate progress without a known shape — owned by
+  `component:Spinner`.
 
 ## Public concepts
 
-No new public concept is introduced. Consumer props and usage remain documented
-in `Skeleton.doc.mjs`.
+| Concept | Closed values or states                                 | Meaning                                             | Availability by variant/orientation/state | Default | Owner                | Stability | Invalid-value behavior                      |
+| ------- | ------------------------------------------------------- | --------------------------------------------------- | ----------------------------------------- | ------- | -------------------- | --------- | ------------------------------------------- |
+| Size    | `width` and `height`: a number of pixels or a CSS value | The block's dimensions.                             | Always                                    | `100%`  | `component:Skeleton` | Stable    | A string passes through as CSS.             |
+| Radius  | `none`, `0`, `1`, `2`, `3`, `4`, `rounded`              | Corner radius from the radius scale.                | Always                                    | `3`     | `component:Skeleton` | Stable    | TypeScript rejects other values.            |
+| Stagger | non-negative integer `index`                            | Delays the pulse so sequential placeholders ripple. | Always                                    | `0`     | `component:Skeleton` | Stable    | Any number is applied in the delay formula. |
 
 ## Behavioral and layout contract
 
-| ID  | Candidate invariant                                                                 | Basis                           | Draft review state                                 |
-| --- | ----------------------------------------------------------------------------------- | ------------------------------- | -------------------------------------------------- |
-| FR1 | The current render contains one painted placeholder carrying the `skeleton` target. | Current source, docs, and tests | Verified current behavior; no new behavior decided |
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                   | Basis                    |
+| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| FR1 | Skeleton renders one childless `div` carrying the `skeleton` target, sized by `width` and `height` (numbers in pixels, strings as CSS), default `100%` each.                                                                                                                                                                                                                                                | Current source and tests |
+| FR2 | `radius` maps `none` to no radius, `0` to `--radius-none`, `1` to `--radius-inner`, `2` to `--radius-element`, `3` and `4` to `--radius-container`, and `rounded` to `--radius-full`; the default is `3`.                                                                                                                                                                                                   | Current source           |
+| FR3 | The block paints `--color-skeleton` at opacity 0.25. Under `prefers-contrast: more` it paints that color mixed 30% toward primary text. Under `forced-colors: active` it paints `GrayText`, which wins over the contrast rule, at full opacity while no pulse runs; with motion allowed the FR4 pulse still varies its opacity.                                                                             | Current source and tests |
+| FR4 | The block pulses its opacity from 0.25 to 0.925 in ten equal held steps and back, alternating indefinitely, each climb and each fall taking `--duration-medium-max` as the theme sets it before `tempo` scales it (`spec:AST-108` FR4), with a linear timing function and no `steps()`. The pulse starts after 1000 ms plus 100 ms times `index`. Under `prefers-reduced-motion: reduce` there is no pulse. | Current source and tests |
+| FR5 | `ref` reaches the block. Supported DOM, ARIA, data, and event props, including `data-testid`, reach the block after the default `aria-hidden`; `xstyle`, `className`, and `style` merge in that order after component styles.                                                                                                                                                                               | Current source and tests |
 
 ### Allowed variation
 
-- This documentation does not constrain behavior beyond the factual anatomy and
-  target relationship recorded here.
+- **AV1 — Theme paint.** A theme may change the block's visual properties through
+  `skeleton` without changing its anatomy or accessibility exclusion.
+- **AV2 — Shape.** Width, height, and radius vary per callsite to match the
+  content they stand in for.
 
 ### Representative states
 
-- The anatomy and target relationship is the same for the documented size,
-  radius, and animation inputs.
+| State             | Required invariant                                                                                                | Allowed variation |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------- | ----------------- |
+| Default           | `aria-hidden` block at 0.25 opacity, pulsing after one second.                                                    | Size and radius.  |
+| Staggered         | Each block's pulse starts 100 ms after the previous index.                                                        | Number of blocks. |
+| Reduced motion    | Static block at 0.25 opacity.                                                                                     | —                 |
+| Forced colors     | `GrayText` block at full opacity while no pulse runs; with motion allowed the FR4 pulse varies its opacity (AR2). | —                 |
+| Exposed by caller | `aria-hidden={false}` reaches the block.                                                                          | —                 |
 
 ### Transformation and precedence order
 
-- No new ordering rule is introduced.
+- **ORD1 — Paint.** Default skeleton color → increased-contrast mix → forced
+  colors `GrayText`.
+- **ORD2 — Attributes.** `aria-hidden="true"` and `data-testid` → component
+  class → component styles → `xstyle` → `className` → `style` → caller props.
 
 ### Performance and resources
 
-- No new performance or resource rule is introduced.
+- **PR1 — Off-main-thread pulse.** The pulse changes only opacity and uses no
+  stepped timing function, so supported engines can run it without main-thread
+  repaint. Skeleton adds no listener, observer, or timer.
 
 ## Accessibility contract
 
-This draft does not change or extend Skeleton's existing accessibility behavior.
+- **AR1 — Hidden by default.** The block is `aria-hidden="true"`, so
+  assistive technology does not announce empty placeholders; a caller may pass
+  `aria-hidden={false}`. The surrounding region conveys busy state.
+- **AR2 — Forced-color and increased-contrast paint.** The placeholder is
+  decorative. In forced-color mode it paints `GrayText` so it stays visible
+  where the browser would strip its fill, at full opacity while no pulse runs;
+  with motion allowed the FR4 pulse still varies its opacity from 0.25 to
+  0.925. Under increased contrast its color moves 30% toward the primary text
+  color.
+- **AR3 — Reduced motion.** The pulse is removed when the reader asks for
+  reduced motion.
 
 ## Design relationships
 
-| Anatomy or state | Design requirement                         | Representation authority       | Hierarchy role | Component contract |
-| ---------------- | ------------------------------------------ | ------------------------------ | -------------- | ------------------ |
-| Placeholder      | Represents the current painted loading UI. | Current source and public docs | Supporting     | FR1                |
+| Anatomy or state | Design requirement                                       | Representation authority       | Hierarchy role | Component contract |
+| ---------------- | -------------------------------------------------------- | ------------------------------ | -------------- | ------------------ |
+| Placeholder      | Previews the shape of loading content with a soft pulse. | Current source and public docs | Supporting     | FR1–FR4, AR1–AR3   |
 
 ### Theming anatomy
 
@@ -101,21 +154,25 @@ This draft does not change or extend Skeleton's existing accessibility behavior.
 
 ## Family and system relationships
 
-This draft references the current shared owners without restating their rules:
-`architecture:component-theming-surface` and
-`architecture:public-component-api`.
+- `architecture:component-theming-surface` owns target qualification for the
+  `skeleton` target.
+- `architecture:public-component-api` owns ref, passthrough, and styling-input
+  rules; FR5 applies them to the block.
 
 ## Verification map
 
-| Contract            | Verification                     | Representative states                | Mutation or failure expectation                                         | Audit section            |
-| ------------------- | -------------------------------- | ------------------------------------ | ----------------------------------------------------------------------- | ------------------------ |
-| FR1                 | `Skeleton.test.tsx` render suite | A rendered placeholder               | Removing the placeholder fails the existing render assertion.           | `audit:Skeleton/anatomy` |
-| Theming anatomy map | `scripts/check-knowledge.mjs`    | Canonical anatomy and current target | Missing, extra, prefixed, or stale mappings fail repository validation. | `audit:Skeleton/theming` |
+| Contract            | Verification                                                          | Representative states                             | Mutation or failure expectation                                                                                                                                                                                                                                               | Audit section            |
+| ------------------- | --------------------------------------------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| FR1, FR5, AR1       | `Skeleton.test.tsx` render and a11y tests                             | Default; caller `aria-hidden={false}`             | Removing the block, the default `aria-hidden`, or the caller override fails. Gap: no test covers the ref, the default `100%` size, or the styling-input order.                                                                                                                | `audit:Skeleton/a11y`    |
+| FR4, PR1, AR3       | `Skeleton.test.tsx` pulse suite                                       | Compiled keyframes and timing                     | A `steps()` timing function or changed opacity steps fails. Gap: the duration, opacity-only keyframes, the start delay, the per-index stagger, and the reduced-motion removal have no automated check.                                                                        | `audit:Skeleton/motion`  |
+| FR3, AR2            | `Skeleton.test.tsx` forced-colors suite                               | Forced colors                                     | Dropping the `GrayText` or full-opacity override from the compiled CSS fails. Gap: the increased-contrast mix, and which rule wins when both media features apply, have no automated check, forced-colors rendering, including the pulse there, is not verified in a browser. | `audit:Skeleton/a11y`    |
+| FR1–FR3             | `Skeleton.stories.tsx` Shapes and StaggeredList fixtures in a browser | Radii `rounded`, `3`, `2`, `none`; staggered list | Gap: no unit test asserts size, radius, or the increased-contrast paint, and no fixed story renders radius `0`, `1`, or `4` or increased-contrast mode; other values are visible only in the rendered fixtures.                                                               | `audit:Skeleton/layout`  |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                         | Canonical anatomy and current target              | Missing, extra, prefixed, or stale mappings fail repository validation.                                                                                                                                                                                                       | `audit:Skeleton/theming` |
+| AR1                 | Accessibility-tree evidence (`spec:AST-009` FR3)                      | Default and exposed placeholder                   | Gap: no accessibility-tree check proves the placeholder is absent from the tree; the unit test asserts the attribute.                                                                                                                                                         | `audit:Skeleton/a11y`    |
 
 ## Decision log
 
-None. This draft records current facts and introduces no component-local design
-decision.
+None recorded. The record describes shipped behavior.
 
 ## Open questions
 
@@ -123,5 +180,5 @@ None.
 
 ## Content boundary
 
-This file does not duplicate consumer prop tables, examples, implementation
-steps, or system rules. It links to their owners.
+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/Skeleton/Skeleton.test.tsx

@@ -3,7 +3,63 @@
 import {describe, it, expect} from 'vitest';
 import {render, screen} from '@testing-library/react';
 import {Skeleton} from './Skeleton';
-import {getForcedColorsRules} from '../__tests__/forcedColors';
+import {
+  getAllInjectedCss,
+  getForcedColorsRules,
+} from '../__tests__/forcedColors';
+
+/** The declarations the element's atomic classes carry, as `prop: value`. */
+function declarationsOf(el: Element, css: string): string[] {
+  const out: string[] = [];
+  for (const cls of Array.from(el.classList)) {
+    const re = new RegExp(`\\.${cls}\\b[^{]*\\{([^}]*)\\}`, 'g');
+    for (const match of css.matchAll(re)) {
+      out.push(
+        ...match[1]
+          .split(';')
+          .map(d => d.trim())
+          .filter(Boolean),
+      );
+    }
+  }
+  return out;
+}
+
+/** The whole `@keyframes <name> { … }` rule, braces matched. */
+function keyframesRule(css: string, name: string): string {
+  const start = css.search(new RegExp(`@keyframes ${name}\\b`, 'i'));
+  expect(start).toBeGreaterThanOrEqual(0);
+  let depth = 0;
+  for (let i = css.indexOf('{', start); i < css.length; i += 1) {
+    if (css[i] === '{') {
+      depth += 1;
+    }
+    if (css[i] === '}' && --depth === 0) {
+      return css.slice(start, i + 1);
+    }
+  }
+  throw new Error(`unterminated @keyframes ${name}`);
+}
+
+/** The named animation's opacity keyframes as [offset 0..1, opacity], in order. */
+function opacityKeyframes(css: string, name: string): [number, number][] {
+  return Array.from(
+    keyframesRule(css, name).matchAll(/([\d.]+)%\s*\{\s*opacity:\s*([\d.]+)/g),
+    m => [Number(m[1]) / 100, Number(m[2])] as [number, number],
+  );
+}
+
+/** Opacity at iteration progress x, linear between keyframes. */
+function opacityAt(frames: [number, number][], x: number): number {
+  for (let i = 1; i < frames.length; i += 1) {
+    const [x0, y0] = frames[i - 1];
+    const [x1, y1] = frames[i];
+    if (x <= x1) {
+      return x1 === x0 ? y1 : y0 + ((y1 - y0) * (x - x0)) / (x1 - x0);
+    }
+  }
+  return frames[frames.length - 1][1];
+}
 
 describe('Skeleton', () => {
   it('renders a placeholder element', () => {
@@ -25,6 +81,57 @@ describe('Skeleton', () => {
   });
 });
 
+describe('pulse', () => {
+  function pulse() {
+    render(<Skeleton width={200} height={20} data-testid="sk" />);
+    const css = getAllInjectedCss();
+    const declarations = declarationsOf(screen.getByTestId('sk'), css);
+    const value = (prop: string) =>
+      declarations
+        .filter(d => d.startsWith(`${prop}:`))
+        .map(d => d.slice(prop.length + 1).trim());
+    return {css, value};
+  }
+
+  // WebKit runs no animation with a steps() timing function on the
+  // compositor, so a stepped pulse would freeze in Safari while a script runs.
+  it('keeps steps() out of the timing function so every engine can composite it', () => {
+    const {css, value} = pulse();
+    expect(value('animation-timing-function')).toEqual(['linear']);
+    expect(value('animation-direction')).toEqual(['alternate']);
+    expect(value('animation-iteration-count')).toEqual(['infinite']);
+    const name = value('animation-name').find(v => v !== 'none');
+    expect(name).toBeTruthy();
+    const rule = keyframesRule(css, name ?? '');
+    expect(rule).toMatch(/opacity/);
+    expect(rule).not.toMatch(/steps\(|animation-timing-function/);
+  });
+
+  it('climbs and falls through the same ten opacity steps at the same times', () => {
+    const {css, value} = pulse();
+    const name = value('animation-name').find(v => v !== 'none') ?? '';
+    const frames = opacityKeyframes(css, name);
+    expect(frames[0]).toEqual([0, 0.25]);
+    // The previous pulse: 0.25 → 1 through steps(10, end), played back down
+    // by `alternate`. Sample each tenth away from its edges.
+    for (let step = 0; step < 10; step += 1) {
+      for (const within of [0.02, 0.5, 0.98]) {
+        const x = (step + within) / 10;
+        const expected = 0.25 + 0.75 * (step / 10);
+        expect(opacityAt(frames, x)).toBeCloseTo(expected, 6);
+      }
+    }
+    // Each change between steps takes 0.01% of an iteration.
+    for (let i = 1; i < frames.length; i += 1) {
+      const [x0, y0] = frames[i - 1];
+      const [x1, y1] = frames[i];
+      if (y1 !== y0) {
+        expect(x1 - x0).toBeCloseTo(0.0001, 6);
+      }
+    }
+  });
+});
+
 // jsdom cannot emulate forced-colors rendering, so these assert that the
 // compiled output includes the forced-colors rules; visual behavior needs
 // manual verification under Windows High Contrast.