@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/TextInput/TextInput.tsx

@@ -17,6 +17,7 @@
  */
 
 import {
+  use,
   useId,
   useOptimistic,
   useTransition,
@@ -48,6 +49,7 @@ import {Spinner} from '../Spinner';
 import {useTooltip} from '../Tooltip';
 import {VisuallyHidden} from '../VisuallyHidden';
 import {getInputARIA, isImeKeyEvent} from '../utils';
+import {joinAriaIDs} from '../utils/inputAria';
 
 const styles = stylex.create({
   input: {
@@ -94,7 +96,7 @@ const sizeStyles = stylex.create({
 
 export type TextInputSize = keyof typeof sizeStyles;
 
-import {groupStyles} from '../InputGroup/groupStyles';
+import {groupStyles, inputGroupItemProps} from '../InputGroup/groupStyles';
 
 // Re-export shared types for convenience
 
@@ -108,11 +110,13 @@ import {useInputContainer} from '../hooks/useInputContainer';
 import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
 import {useResolvedRequired} from '../hooks/useResolvedRequired';
 import {useInputGroup} from '../InputGroup/InputGroupContext';
+import {InputGroupInternalContext} from '../InputGroup/InputGroupInternalContext';
 import type {BaseProps} from '../BaseProps';
 import {
   type FieldInputBaseProps,
   useFieldInputStyling,
 } from '../Field/fieldParts';
+import {inputDisabledFocusStyles} from '../Field/inputDisabledFocus';
 import type {SizeValue} from '../utils/types';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
@@ -156,7 +160,9 @@ export interface TextInputProps extends Omit<
    */
   isRequired?: boolean;
   /**
-   * Whether the input is disabled.
+   * Whether the input is disabled. A disabled input is dimmed, cannot be
+   * edited, and is left out of form submission, but it stays in the tab order
+   * (`aria-disabled`, not the native attribute).
    * @default false
    */
   isDisabled?: boolean;
@@ -164,7 +170,7 @@ export interface TextInputProps extends Omit<
    * Whether the input is read-only.
    * The value is shown at full opacity and still submits with the form, but
    * cannot be edited. Unlike `isDisabled`, a read-only input is not dimmed and
-   * stays in the tab order — use it for a value the user should see and send
+   * keeps its form value — use it for a value the user should see and send
    * but not change. `isDisabled` takes precedence when both are set.
    * @default false
    */
@@ -176,8 +182,8 @@ export interface TextInputProps extends Omit<
    * keyboard and assistive technology. The field cannot be edited (it becomes
    * read-only) while disabled.
    *
-   * Use this instead of wrapping a disabled input in `Tooltip` — disabled
-   * controls don't emit the pointer events an external tooltip needs.
+   * Use this instead of wrapping a disabled input in `Tooltip`, so the reason
+   * is attached to the field itself.
    *
    * @example
    * ```
@@ -294,7 +300,7 @@ export function TextInput({
   description,
   isOptional = false,
   isRequired = false,
-  isDisabled = false,
+  isDisabled: isDisabledProp = false,
   isReadOnly = false,
   disabledMessage,
   startIcon,
@@ -322,8 +328,12 @@ export function TextInput({
   ref,
   id: idProp,
   'aria-describedby': ariaDescribedByProp,
+  'aria-labelledby': ariaLabelledByProp,
   ...restProps
 }: TextInputProps) {
+  const inputGroup = useInputGroup();
+  const inputGroupState = use(InputGroupInternalContext);
+  const isDisabled = isDisabledProp || inputGroupState.isDisabled;
   const {rest, container} = useFieldInputStyling('TextInput', restProps, {
     containerXstyle,
     containerClassName,
@@ -331,16 +341,25 @@ export function TextInput({
   });
   const t = useTranslator();
   const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
+  // A disabled field keeps its tab stop but, like a natively disabled one,
+  // runs no caller event handler other than focus and blur (`spec:AST-085` FR2).
+  const fieldProps = isDisabled
+    ? Object.fromEntries(
+        Object.entries(rest).filter(
+          ([key]) => !/^on[A-Z]/.test(key) || /^on(Focus|Blur)/.test(key),
+        ),
+      )
+    : rest;
   const size = useSize(sizeProp, 'md');
 
   const generatedID = useId();
   const id = idProp ?? generatedID;
+  const fieldLabelID = useId();
   const inputLabelID = useId();
   const descriptionID = useId();
   const statusMessageID = useId();
   const inputRef = useRef<HTMLInputElement | null>(null);
   const containerRef = useRef<HTMLDivElement | null>(null);
-  const inputGroup = useInputGroup();
 
   const [, startTransition] = useTransition();
   const [optimisticValue, setOptimisticValue] = useOptimistic(value);
@@ -349,8 +368,7 @@ export function TextInput({
   // (spec:AST-086 FR8).
   useBusyAnnouncement(isBusy, t('@astryx.spinner.loading'), containerRef);
 
-  // Disabled-reason tooltip. Disabled controls swallow pointer events, so the
-  // tooltip listeners attach to the input container (which already exists) and
+  // Disabled-reason tooltip. The tooltip listeners attach to the input container (which already exists) and
   // the input stays perceivable via aria-disabled instead of the native
   // disabled attribute. The field is made read-only so it can't be typed into,
   // and value mutation is blocked by the isDisabled guard in handleChange.
@@ -386,6 +404,12 @@ export function TextInput({
     ],
     inputGroup,
   );
+  // A caller aria-labelledby names the input together with the field's own
+  // label (the Field label standalone, the group and input labels in a group).
+  const inputLabelledBy =
+    ariaLabelledByProp != null
+      ? joinAriaIDs(ariaLabelledBy ?? fieldLabelID, ariaLabelledByProp)
+      : ariaLabelledBy;
 
   const handleChange = (e: ChangeEvent<HTMLInputElement>) => {
     // Value can't change while showing a disabled message (the field is
@@ -411,11 +435,12 @@ export function TextInput({
       if (!e || e.detail === 0) {
         inputRef.current?.focus();
       } else {
-        // Defer focus restoration past the button's unmount task so iOS Safari
-        // and touch browsers don't jump the page scroll to 0 on tap.
-        requestAnimationFrame(() => {
-          inputRef.current?.focus({preventScroll: true});
-        });
+        // Focus inside the tap: iOS Safari brings up its keyboard only for a
+        // focus made while handling the touch, so a field the tap reaches
+        // unfocused gets its keyboard, as UIKit's clear button makes the
+        // field first responder. `preventScroll` keeps a scrolled page where
+        // it is.
+        inputRef.current?.focus({preventScroll: true});
       }
     },
     [onChange],
@@ -440,6 +465,7 @@ export function TextInput({
       }}
       onClick={handleWrapperClick}
       onMouseUp={handleWrapperMouseUp}
+      {...(inputGroup ? inputGroupItemProps : undefined)}
       {...mergeProps(
         themeProps('text-input', {
           size,
@@ -451,6 +477,7 @@ export function TextInput({
           inputWrapperStyles.base,
           sizeStyles[size],
           isDisabled && inputWrapperStyles.disabled,
+          isDisabled && inputDisabledFocusStyles.ring,
           status && inputStatusBorderStyles[status.type],
           status && !isDisabled && inputStatusHoverShadowStyles[status.type],
           status && inputStatusFocusWithinStyles[status.type],
@@ -463,7 +490,7 @@ export function TextInput({
       {startIcon && renderIconSlot(startIcon, {size: 'sm', color: 'secondary'})}
       {inputGroup && <VisuallyHidden id={inputLabelID}>{label}</VisuallyHidden>}
       <input
-        {...rest}
+        {...fieldProps}
         ref={useMergedRefs(ref, inputRef)}
         id={id}
         name={isDisabled ? undefined : htmlName}
@@ -471,8 +498,15 @@ export function TextInput({
         value={optimisticValue}
         onChange={handleChange}
         onKeyDown={
-          onEnter || onKeyDown
+          isDisabled || onEnter || onKeyDown
             ? e => {
+                if (isDisabled) {
+                  // A read-only field still submits its form on Enter.
+                  if (e.key === 'Enter') {
+                    e.preventDefault();
+                  }
+                  return;
+                }
                 // The composing keydown fires before compositionend, so without
                 // this guard pressing Enter to commit a Japanese/Chinese/Korean
                 // IME conversion would trigger onEnter (submit/save actions)
@@ -486,12 +520,11 @@ export function TextInput({
             : undefined
         }
         placeholder={placeholder}
-        // With a disabledMessage the input keeps focusability via aria-disabled
-        // so the reason is focus-discoverable; readOnly + the handleChange guard
-        // keep the value from changing.
-        disabled={isDisabled && !showsDisabledMessage}
-        aria-disabled={showsDisabledMessage ? 'true' : undefined}
-        readOnly={isReadOnly || showsDisabledMessage || undefined}
+        // A disabled input keeps its place in the tab order (spec:AST-085):
+        // aria-disabled instead of the native attribute, with readOnly + the
+        // handleChange guard keeping the value from changing.
+        aria-disabled={isDisabled ? 'true' : undefined}
+        readOnly={isReadOnly || isDisabled || undefined}
         autoFocus={hasAutoFocus}
         data-autofocus={hasAutoFocus || undefined}
         aria-describedby={
@@ -501,7 +534,7 @@ export function TextInput({
         aria-required={isEffectivelyRequired ? 'true' : undefined}
         aria-invalid={status?.type === 'error' ? 'true' : undefined}
         aria-busy={isBusy || undefined}
-        aria-labelledby={ariaLabelledBy}
+        aria-labelledby={inputLabelledBy}
         {...stylex.props(styles.input, isDisabled && styles.inputDisabled)}
       />
       {hasClear && value !== '' && !isDisabled && !isReadOnly && (
@@ -532,6 +565,7 @@ export function TextInput({
       isLabelHidden={isLabelHidden}
       description={description}
       inputID={id}
+      labelID={ariaLabelledByProp != null ? fieldLabelID : undefined}
       descriptionID={description ? descriptionID : undefined}
       isOptional={isOptional}
       isRequired={isRequired}

package/src/TextInput/__tests__/TextInput.a11y.chromium.spec.ts

@@ -1,4 +1,5 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
+// @pr-a11y release-only
 
 /**
  * @file TextInput.a11y.chromium.spec.ts

package/src/Thumbnail/Thumbnail.doc.mjs

@@ -79,8 +79,7 @@ export const docs = {
     ],
     vars: [
       {name: '--_thumbnail-hit-inset', description: 'Outset of the remove button\'s invisible hit area, applied to a ::after overlay. 0 on a fine pointer; negative on a coarse one, which grows the 20px button to the 24px touch target without changing what is drawn.', default: '0px', private: true},
-      {name: '--_press-overlay', description: 'Fill of the ::after interaction overlay: transparent at rest, the hover overlay token on hover (hover-capable pointers), the pressed overlay token while pressed (`:active` on a mouse; `data-astryx-press="on"` written by the touch press controller under a finger) and the hover token for the release fade. Set on the card element by its own interaction arms.', default: 'transparent', private: true},
-      {name: '--_press-overlay-transition', description: 'Duration of the overlay\'s background-color transition: the fast duration token, except 0s while a believed touch press paints so it lands on the first frame.', default: 'var(--duration-fast)', private: true},
+      {name: '--_press-overlay', description: 'Colour of the ::after interaction overlay for the hover and mouse states: transparent at rest, the hover overlay token on hover (hover-capable pointers), the pressed overlay token while a mouse holds `:active`. A press the touch press controller paints (`data-astryx-press`) is the overlay\'s image instead, at the press\'s strength, and the colour yields to it. Set on the card element by its own interaction arms.', default: 'transparent', private: true},
     ],
   },
   usage: {

package/src/Thumbnail/Thumbnail.spec.md

@@ -0,0 +1,244 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:Thumbnail
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-26
+owners: [cixzhang]
+review_triggers: [public-api, behavior, layout, theming, accessibility]
+verified_by:
+  [
+    packages/core/src/Thumbnail/Thumbnail.test.tsx,
+    packages/core/src/theme/themingTargets.test.ts,
+    apps/storybook/stories/Thumbnail.stories.tsx,
+    .github/visual-baseline/manifest.json,
+  ]
+modules: []
+families: []
+design_specs: []
+architecture:
+  [
+    architecture:component-theming-surface,
+    architecture:interaction-modality,
+    architecture:internationalization,
+    architecture:public-component-api,
+  ]
+contributing: []
+system_specs: [spec:AST-009, spec:AST-085, spec:AST-086]
+---
+
+# Thumbnail component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                             |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Public contract         | A 64px square image preview with `src`, `alt`, `label`, `isLoading`, `isDisabled`, an optional `onClick` open action, and an optional `onRemove` action revealed per `showRemoveOn`. |
+| Behavior                | The preview shows a skeleton, the image, an upload overlay, or a placeholder; it is a named group whose open and remove actions are separate buttons.                                |
+| End-user impact         | Screen-reader users hear the file and image in one group name and reach "Open …" and "Remove …" buttons; keyboard and touch users can always reach a hover-revealed remove button.   |
+| Builder impact          | None; the record describes shipped behavior.                                                                                                                                         |
+| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. Six implementation gaps are listed under Current-state impact.                                            |
+| Review checks           | Reject a hover-only remove button that leaves the tab order, a name on a roleless element, an image exposed without `alt`, or a busy spinner that announces itself.                  |
+| Governing rules         | `spec:AST-085/FR1`; `spec:AST-086/FR8`; WCAG 2.2 2.5.8; `architecture:public-component-api/INV5,INV6,INV8`; `architecture:internationalization/INV1a`.                               |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+Thumbnail previews one image attachment in a compact square, with optional
+open and remove actions. It owns the preview's loading, error, and upload
+states, its accessible group name, and the placement and reveal of its remove
+action.
+
+## 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; image-failure tracking is
+  internal state
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Current-state impact
+
+- **Caller `role` replaces the group role (FR7, AR1).** A caller `role`, such
+  as `none` or `img`, overwrites `role="group"`, leaving the composed name on
+  an element that may not take it, where `architecture:public-component-api`
+  INV5 keeps component-owned semantics from being overwritten.
+- **Joined name outside the catalog (FR3).** With both `label` and `alt`, the
+  group name "{label} — {alt}" is assembled at the call site rather than from
+  one catalog message, so a locale cannot reorder or re-punctuate it
+  (`architecture:internationalization` INV1a).
+- **Remove target below 24px (AR4).** On a fine pointer the remove button's hit
+  area is 20 by 20 CSS pixels and it overlaps the open action, where WCAG 2.2
+  2.5.8 requires 24 by 24 or spacing. On a coarse pointer it is 24 by 24.
+- **Label tooltip not reachable by keyboard (FR3).** The label tooltip
+  attaches to the root group, which is not focusable, so keyboard focus on the
+  open or remove button does not reveal it (WCAG 2.2 2.1.1). The label still
+  reaches assistive technology through the group and button names.
+- **Two focus indicators on Open and Remove (FR4).** The image container
+  outlines whenever it contains keyboard focus, and both the open and the
+  remove button keep their own focus ring, so focusing either draws two
+  indicators, where `architecture:interaction-modality` INV3 allows one per
+  focus move.
+- **Disabled state not reflected on the target (FR6).** The `thumbnail`
+  target reflects no state, so a theme cannot style the disabled state there (`architecture:component-theming-surface` INV6).
+
+## Ownership boundary
+
+**Owns**
+
+- The root group, the square image container, and the Image, Placeholder,
+  Skeleton, Upload overlay, and Remove button parts.
+- The visual-state choice and image-failure retry.
+- The group name, the open-button name, and the remove-button name.
+- The remove button's placement, scrim, hit area, and hover reveal.
+- The upload busy announcement.
+
+**Does not own / non-goals**
+
+- Lightbox or detail view opened by `onClick` — owned by the product callsite.
+- Collections of attachments and upload transport — owned by composing
+  components and the product callsite.
+- Button, Skeleton, Spinner, Icon, and Tooltip internals — owned by those
+  components; Thumbnail composes them.
+- The hover-and-focus reveal mechanism — owned by the shared container-reveal
+  utility.
+
+## Public concepts
+
+| Concept       | Closed values or states                                                   | Meaning                                                                                       | Availability by variant/orientation/state         | Default     | Owner                 | Stability | Invalid-value behavior           |
+| ------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------- | ----------- | --------------------- | --------- | -------------------------------- |
+| Visual state  | skeleton; image or placeholder under the upload scrim; image; placeholder | What the image container shows (FR2).                                                         | Resolved from `src`, `isLoading`, and load errors | placeholder | `component:Thumbnail` | Stable    | —                                |
+| Open action   | present; absent                                                           | `onClick` adds an "Open …" button over the image; inert while loading or disabled (FR4).      | With `onClick`                                    | absent      | `component:Thumbnail` | Stable    | —                                |
+| Remove action | present; absent                                                           | `onRemove` adds a "Remove …" button in the top inline-end corner; inert while disabled (FR5). | With `onRemove`                                   | absent      | `component:Thumbnail` | Stable    | —                                |
+| Remove reveal | `hover`, `always`                                                         | Whether the remove button is shown at rest.                                                   | Only with `onRemove`                              | `hover`     | `component:Thumbnail` | Stable    | TypeScript rejects other values. |
+| Disabled      | enabled; disabled                                                         | Dims the thumbnail; its actions stay focusable and announced as disabled (FR6).               | All states                                        | enabled     | `component:Thumbnail` | Stable    | —                                |
+
+## Behavioral and layout contract
+
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Basis                    |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| FR1 | The root is a 64px-wide, non-shrinking, isolated inline-flex column carrying the `thumbnail` target. It holds a square image container with `--radius-element` corners, clipped overflow, and a `--color-neutral` background.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Current source and tests |
+| FR2 | `isLoading` without `src` shows a Skeleton; `isLoading` with `src` shows the image, or the placeholder glyph if that `src` failed, under an overlay-colored upload scrim holding a small on-media Spinner; `src` without loading shows the image, cover-fitted, with a 1px inset border; no `src`, or a `src` that failed to load, shows a secondary-colored image placeholder glyph. A failure is tracked per `src`, so a changed `src` is tried again.                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Current source and tests |
+| FR3 | The root is `role="group"` named "{label} — {alt}" when both exist, else `label`, else `alt`, else the translated "Thumbnail"; a caller `aria-label` or `aria-labelledby` reaches the root after it and names the group instead. A joined name is one catalog message (`architecture:internationalization` INV1a); implementation gap: "{label} — {alt}" is joined at the call site (Current-state impact). A defined `label` also wraps the thumbnail in a Tooltip showing it, which also sets the label as the group's accessible description; `label` is never rendered inline. A tooltip can be revealed from the keyboard (WCAG 2.2 2.1.1). Implementation gap: the tooltip attaches to the non-focusable root and opens on hover and touch only; focusing the open or remove button does not show it (Current-state impact). In development, a `src` with no `alt`, `label`, `aria-label`, or `aria-labelledby` logs a warning. | Current source and tests |
+| FR4 | With `onClick`, a full-size `button type="button"` named "Open {name}" wraps the image content and calls `onClick`; hover and pressed overlays show for mouse and touch. While loading or disabled, Open stays mounted and inert, so a focused Open keeps focus (`spec:AST-085` FR1, FR4, FR6). Each focus move shows one indicator (`architecture:interaction-modality` INV3): the image container draws the shared focus-visible outline for the open button. Implementation gap: both the open and the remove button keep their own focus ring inside the container outline, so focusing either draws two indicators (Current-state impact).                                                                                                                                                                                                                                                                                       | Current source and tests |
+| FR5 | With `onRemove`, a small icon-only secondary Button named "Remove {name}" sits `--spacing-1` from the top and inline-end edges above the image, painted with the overlay scrim and on-dark icon; a click stops propagation before `onRemove`, so it never opens the thumbnail. With `showRemoveOn="hover"` the button is visually hidden at rest by opacity, stays in the tab order and accessibility tree, and is revealed on container hover, on focus within, and always on touch devices. While disabled, Remove stays mounted and inert, so a focused Remove keeps focus (`spec:AST-085` FR1, FR4).                                                                                                                                                                                                                                                                                                                              | Current source and tests |
+| FR6 | `isDisabled` dims the root to half opacity with pointer events off. Its actions stay mounted, focusable, and announced as disabled (`spec:AST-085` FR1, FR4, FR5), and the disabled state is reflected on the owning target (`architecture:component-theming-surface` INV6). Implementation gap: the `thumbnail` target reflects no state (Current-state impact).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Current source and tests |
+| FR7 | `ref` reaches the root. Supported DOM, ARIA, data, and event props reach the root; `data-testid` reaches the root; `xstyle`, `className`, and `style` merge in that order after component styles. A caller `aria-label` or `aria-labelledby` names the group (FR3). The group role is component-owned semantics (`architecture:public-component-api` INV5). Implementation gap: caller props spread after the role, so a caller `role` replaces it (Current-state impact).                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Current source and tests |
+
+### Allowed variation
+
+- **AV1 — Theme paint.** A theme may restyle `thumbnail` without changing its
+  states, names, or action placement.
+- **AV2 — Image content.** Image dimensions vary; the image always covers the
+  square.
+
+### Representative states
+
+| State                | Required invariant                                                                                                                                    | Allowed variation |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
+| Image, named         | Group named from `label` and `alt`; image exposed with its `alt`.                                                                                     | —                 |
+| Image without alt    | Image `alt=""`, `role="presentation"`, `aria-hidden`.                                                                                                 | —                 |
+| Placeholder or error | Placeholder glyph; a new `src` retries.                                                                                                               | —                 |
+| Loading, no src      | Skeleton; an Open action stays mounted and inert.                                                                                                     | —                 |
+| Uploading            | The image, or the placeholder if it failed, under the scrim with a hidden Spinner; busy start announced once; an Open action stays mounted and inert. | —                 |
+| Openable             | "Open {name}" button; focus outline on the container (the button's own ring is the FR4 gap).                                                          | —                 |
+| Removable, hover     | "Remove {name}" in the tab order, revealed on hover, focus, and touch.                                                                                | —                 |
+| Disabled             | Half opacity; Open and Remove stay mounted, focusable, and inert.                                                                                     | —                 |
+
+### Transformation and precedence order
+
+- **ORD1 — Visual state.** Loading without `src` → loading with `src` (the
+  image, or the placeholder if it failed, under the upload scrim) → image →
+  placeholder (no `src` or load error).
+- **ORD2 — Name.** "{label} — {alt}" → `label` → `alt` → "Thumbnail"; a caller
+  `aria-label` replaces it on the group.
+- **ORD3 — Remove click.** Stop propagation → `onRemove`.
+
+### Performance and resources
+
+- **PR1 — CSS reveal and shared press.** The hover reveal is CSS-only. Every
+  Thumbnail installs the shared document-level press controller on mount, and
+  only an interactive one carries its press marker; the uploading state
+  announces through the shared busy-announcement channel. Thumbnail adds no
+  listener, observer, or timer of its own.
+
+## Accessibility contract
+
+- **AR1 — Group name.** The root is a named group, never a roleless element
+  with a name, so the open and remove buttons inside it stay reachable.
+  Implementation gap: a caller `role` replaces the group role (FR7).
+- **AR2 — Image alternative.** An image with `alt` is exposed with it; without
+  `alt` it is explicitly decorative.
+- **AR3 — Busy state.** The upload Spinner is hidden from assistive technology;
+  Thumbnail announces "Loading" once per busy start through the shared channel,
+  as `spec:AST-086` FR8 requires of a busy owner.
+- **AR4 — Remove target.** The remove target is at least 24 by 24 CSS pixels
+  for every pointer (WCAG 2.2 2.5.8). The button is 20 by 20, with a hit area
+  extended 2px on every side on coarse pointers. Implementation gap: on a fine
+  pointer the target stays 20 by 20.
+- **AR5 — Disabled and loading.** A disabled thumbnail's actions stay mounted,
+  focusable, and announced as disabled, and a loading thumbnail's Open stays
+  mounted and inert, so focus never moves when either state starts
+  (`spec:AST-085` FR1, FR4, FR5, FR6).
+- **AR6 — Reachable remove.** A hover-revealed remove button is never removed
+  from the tab order and appears on keyboard focus and on touch devices.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                                 | Representation authority | Hierarchy role | Component contract |
+| ---------------- | ------------------------------------------------------------------ | ------------------------ | -------------- | ------------------ |
+| Image            | The preview image as a cover-fitted square.                        | Current source and docs  | Prominent      | FR1, FR2, AR2      |
+| Placeholder      | An image silhouette when there is no image.                        | Current source and docs  | Supporting     | FR2                |
+| Remove button    | An overlaid close control on a fixed scrim legible over any image. | Current source and docs  | Supporting     | FR5, AR4, AR6      |
+| Upload overlay   | A scrim with a spinner while an image uploads.                     | Current source and docs  | Supporting     | FR2, AR3           |
+| Skeleton         | A shimmer while loading without an image.                          | Current source and docs  | Supporting     | FR2                |
+
+Theming: the root is the single `thumbnail` target; the parts add no targets.
+The consumer anatomy names no root part, so no anatomy-theming block is
+declared.
+
+## Family and system relationships
+
+- `spec:AST-085` owns focusable disabled controls; AR5 records how Thumbnail applies it.
+- `spec:AST-086` owns busy announcements; AR3 records Thumbnail's conformance.
+- `architecture:internationalization` owns the catalog behind the fallback
+  name and the open and remove names.
+- `architecture:public-component-api` owns ref, passthrough, and styling-input
+  rules; FR7 applies them to the root.
+
+## Verification map
+
+| Contract            | Verification                                                                  | Representative states                                              | Mutation or failure expectation                                                                                                                                                                                                                                                                                                 | Audit section              |
+| ------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
+| FR1                 | `Thumbnail.stories.tsx` in a browser                                          | Every state                                                        | Gap: no test asserts the root width, layout, or the image container's shape, clipping, or paint; they are visible only in the rendered fixture.                                                                                                                                                                                 | `audit:Thumbnail/layout`   |
+| FR2, ORD1           | `Thumbnail.test.tsx` state, error, and retry tests                            | Image, placeholder, skeleton, uploading, failed, changed `src`     | A wrong element for any state, a failed image left showing, or a changed `src` not retried fails. Gap: a failed `src` while uploading, the scrim and placeholder paint and the Spinner's size and shade have no automated check; the cover fit and inset border appear only in the static-image visual baseline.                | `audit:Thumbnail/behavior` |
+| FR3, ORD2, AR1, AR2 | `Thumbnail.test.tsx` naming, role, image, warning, and tooltip tests          | Label, label with alt, alt, neither                                | A missing label or joined name, a missing `group` role, an exposed decorative image, a lost `alt`, a missing or repeated warning, or the label rendered inline fails. Gap: no test asserts the alt-only or default "Thumbnail" name, a caller `aria-label` or `aria-labelledby`, the label description, or the tooltip opening. | `audit:Thumbnail/a11y`     |
+| FR4                 | `Thumbnail.test.tsx` naming, click, loading, disabled, and touch-press tests  | Openable, loading, disabled                                        | A wrong "Open …" name, a lost callback, or a missing touch-press overlay fails. The loading and disabled tests fail if Open unmounts, calls `onClick`, or loses focus or its disabled state. Gap: the full-size button, the hover overlay, and the focus indicators have no automated check.                                    | `audit:Thumbnail/behavior` |
+| FR5, ORD3, AR6      | `Thumbnail.test.tsx` remove and `showRemoveOn` suites                         | Hover, always, default reveal                                      | A lost `onRemove`, a hover-revealed button missing from the DOM, or the same reveal treatment for both values fails. A wrong "Remove …" name also fails. Gap: that a remove click never calls `onClick`, the button's position and paint, and the reveal triggers have no automated check.                                      | `audit:Thumbnail/a11y`     |
+| FR6, AR5            | `Thumbnail.test.tsx` disabled tests                                           | Disabled with actions                                              | The tests fail if a disabled Open or Remove unmounts, loses focus, drops `aria-disabled`, or calls its callback. Gap: the half opacity and pointer-events rule have no automated check.                                                                                                                                         | `audit:Thumbnail/a11y`     |
+| FR7                 | `Thumbnail.test.tsx` ref and test-id tests                                    | Root                                                               | A lost ref or `data-testid` fails. Gap: no test covers DOM passthrough, attribute order, or the styling-input merge.                                                                                                                                                                                                            | `audit:Thumbnail/api`      |
+| AR3                 | `Thumbnail.test.tsx` uploading test; source review against `spec:AST-086` FR8 | Uploading                                                          | An exposed upload Spinner fails. Gap: no automated check fails if the busy state is announced twice.                                                                                                                                                                                                                            | `audit:Thumbnail/a11y`     |
+| AR4                 | `Thumbnail.stories.tsx` in a browser at fine and coarse pointers              | Removable                                                          | Gap: no automated target-size check; the fine-pointer size is the recorded gap.                                                                                                                                                                                                                                                 | `audit:Thumbnail/a11y`     |
+| PR1                 | Source review                                                                 | Removable, openable, uploading                                     | Gap: no automated check fails if Thumbnail adds its own listener, observer, or timer.                                                                                                                                                                                                                                           | `audit:Thumbnail/behavior` |
+| AR1, AR2            | Accessibility-tree evidence (`spec:AST-009` FR3)                              | Named group, open and remove buttons, image with and without `alt` | Gap: no accessibility-tree check proves the group name, button names, or image exposure; the unit tests query the DOM.                                                                                                                                                                                                          | `audit:Thumbnail/a11y`     |
+
+## 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.