@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/AvatarGroup/AvatarGroupOverflow.spec.md

@@ -1,13 +1,13 @@
 ---
 schema_version: 3
-template_version: 4
+template_version: 7
 kind: component
 id: component:AvatarGroupOverflow
-authority: draft
+authority: current
 archive_reason: null
 superseded_by: null
-approved_by: null
-approved_at: null
+approved_by: cixzhang
+approved_at: 2026-10-26
 owners: [cixzhang]
 review_triggers: [public-api, behavior, layout, theming, accessibility]
 verified_by:
@@ -15,186 +15,190 @@ verified_by:
     packages/core/src/AvatarGroup/AvatarGroupOverflow.test.tsx,
     packages/core/src/AvatarGroup/AvatarGroup.test.tsx,
     packages/core/src/theme/themingTargets.test.ts,
-    packages/core/src/theme/derivedVarRegistry.test.ts,
     apps/storybook/rtl-audit/targets.json,
-    scripts/check-knowledge.mjs,
+    apps/storybook/stories/AvatarGroupOverflow.stories.tsx,
   ]
 modules: []
 families: []
 design_specs: []
 architecture:
   [
-    architecture:knowledge-contracts,
     architecture:component-theming-surface,
+    architecture:internationalization,
     architecture:public-component-api,
   ]
 contributing: []
-system_specs: [spec:AST-002, spec:AST-029]
+system_specs: [spec:AST-002, spec:AST-009, spec:AST-038]
 ---
 
 # AvatarGroupOverflow component contract
 
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                            |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | An overflow indicator with a required `count`, optional `onClick`, and optional custom `children` that replace the visible "+N".                                                    |
+| Behavior                | Without `onClick` it is a named image; with `onClick` it is a native button in the group's roving set. Its name is the translated count unless a caller `aria-labelledby` names it. |
+| End-user impact         | Screen-reader users hear how many people are hidden ("5 more"); keyboard users reach a clickable indicator as the last item in the group.                                           |
+| Builder impact          | None; the record describes shipped behavior.                                                                                                                                        |
+| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. Two implementation gaps are listed under Current-state impact.                                           |
+| Review checks           | Reject a negative displayed count, a name taken from custom children, a static indicator in the roving set, or an indicator that ignores the group's size or shape.                 |
+| Governing rules         | `architecture:public-component-api/INV5,INV6,INV8`; `architecture:component-theming-surface/INV2,INV6`; `architecture:internationalization/INV1a`.                                  |
+
+This table is a review projection; the body below is authoritative.
+
 ## Intent
 
-AvatarGroupOverflow presents the current compact overflow amount associated with
-an AvatarGroup. It renders a default count or caller-supplied content and may use
-a native button when the existing activation callback is present. This draft
-records verified shipped behavior only. It does not change runtime behavior,
-public API, compatibility, targets, or product meaning.
+AvatarGroupOverflow tells the reader how many members an AvatarGroup does not
+show, and optionally lets them open the rest. It owns the indicator's count
+label, its static and button forms, and its geometry within the group.
 
 ## Compatibility and migration
 
 - Released default preserved: `yes`
-- Compatibility class: additive observational documentation only; runtime, DOM,
-  accessibility, styling, targets, defaults, and public API remain unchanged
+- Compatibility class: records shipped behavior; no public prop, default, DOM,
+  accessibility, target, 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
+
+- **Default count outside the catalog (FR2).** The visible "+N" is assembled
+  from the raw number, so it is never locale-formatted: the chip shows "+4912"
+  where the name reads "4,912 more", and under a locale with its own digits the
+  digits differ as well (`architecture:internationalization` INV1a).
+- **Overflow button target (AR4).** In a 16px group the clickable indicator is
+  20px tall, below the 24 by 24 CSS pixels of WCAG 2.2 2.5.8.
+
 ## Ownership boundary
 
 **Owns**
 
-- The overflow indicator element and its current `avatar-group-overflow` theming
-  target.
-- The current default visible count content and translated accessible count label.
-- The current static-element and native-button render branches.
-- The standalone presentation fallback used outside AvatarGroup.
+- The indicator element and its `avatar-group-overflow` target.
+- The default visible "+N" content and the translated count name.
+- The static image and native button forms.
+- The medium, circle, no-overlap presentation used outside an AvatarGroup.
 
 **Does not own / non-goals**
 
-- Choosing which avatars are visible or calculating the hidden count; the product
-  callsite supplies the count and Avatar children.
-- Avatar content, image loading, fallback initials, status, and Avatar theming;
-  those remain owned by `component:Avatar` when that contract exists.
-- AvatarGroup's group label, context lifetime, child ordering, or roving-focus
-  algorithm. AvatarGroupOverflow only participates through the current rendered
-  marker when it is interactive.
-- Caller-supplied custom child content beyond rendering it in the current slot.
-- New API meaning, validation, defaults, compatibility promises, or visual
-  treatment.
+- Choosing visible avatars and computing the hidden count — owned by the
+  product callsite.
+- Avatar rendering and theming — owned by `component:Avatar`.
+- The group's name, context, member order, and roving-focus algorithm — owned
+  by `component:AvatarGroup`; a clickable indicator joins through the item
+  marker.
+- Caller-supplied children beyond placing them in the indicator.
 
 ## Public concepts
 
-Consumer syntax remains in `AvatarGroupOverflow.doc.mjs`. This table records the
-current observable concepts rather than duplicating its prop table.
-
-| Concept            | Closed values or states                                | Meaning                                                                                                                            | Availability by variant/orientation/state                       | Default                                             | Owner                                                                                            | Stability                 | Invalid-value behavior                                                                                 |
-| ------------------ | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------- | ------------------------------------------------------------------------------------------------------ |
-| Overflow amount    | Numeric amount supplied by the caller                  | Drives the current translated accessible label and the default visible `+N` content.                                               | Static and interactive branches; inside or outside AvatarGroup. | Required caller input.                              | `component:AvatarGroupOverflow`                                                                  | Observed released surface | Negative values currently normalize to zero; this draft does not specify other runtime-invalid values. |
-| Display content    | Default count content or caller-supplied React content | Selects the visible content inside the indicator without replacing the count-derived accessible label.                             | Both render branches.                                           | Default `+N` content when custom content is absent. | `component:AvatarGroupOverflow` for the default; caller for supplied content                     | Observed released surface | React rendering determines caller-content behavior.                                                    |
-| Activation mode    | Static or clickable                                    | Absence of the current callback renders a span; presence renders a native button and invokes the callback on activation.           | Both standalone and grouped use.                                | Static.                                             | `component:AvatarGroupOverflow`                                                                  | Observed released surface | The typed callback boundary accepts a function or is absent.                                           |
-| Group presentation | Group-provided or standalone fallback                  | Group context currently supplies size, shape, and overlap; standalone use falls back to medium, circle, and no overlap.            | All current size and shape values; LTR and RTL.                 | Standalone medium circle with zero overlap.         | AvatarGroup context for grouped values; `component:AvatarGroupOverflow` for fallback application | Observed released surface | Type-rejected group values are outside this draft.                                                     |
-| DOM extension      | Supported BaseProps inputs and ref                     | Supported DOM, ARIA, data, event, class, style, and StyleX inputs reach the current root; ref reaches the rendered span or button. | Both render branches.                                           | No additional inputs.                               | `architecture:public-component-api`                                                              | Observed released surface | BaseProps omissions remain unsupported.                                                                |
+| Concept         | Closed values or states         | Meaning                                                                         | Availability by variant/orientation/state | Default                  | Owner                           | Stability | Invalid-value behavior                       |
+| --------------- | ------------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------- | ------------------------ | ------------------------------- | --------- | -------------------------------------------- |
+| Count           | A number supplied by the caller | Drives the translated name and the default "+N".                                | Both forms; inside or outside a group     | Required                 | `component:AvatarGroupOverflow` | Stable    | A negative count is shown and named as zero. |
+| Display content | default "+N"; caller children   | The visible content; the name stays count-derived.                              | Both forms                                | "+N"                     | `component:AvatarGroupOverflow` | Stable    | —                                            |
+| Activation      | static; clickable               | `onClick` selects the button form and is called on activation.                  | Both inside and outside a group           | static                   | `component:AvatarGroupOverflow` | Stable    | —                                            |
+| Presentation    | group-supplied; standalone      | Size, shape, and overlap from AvatarGroup, else medium, circle, and no overlap. | All sizes and shapes; both directions     | standalone medium circle | `component:AvatarGroupOverflow` | Stable    | —                                            |
 
 ## Behavioral and layout contract
 
-| ID  | Candidate invariant                                                                                                                                                                                                                                                                                                                                                                                                   | Basis                                                                    | Draft review state                                                               |
-| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
-| FR1 | Without the existing activation callback, the current render uses one span; with the callback, it uses one native `button` with `type="button"` and invokes that callback on native activation.                                                                                                                                                                                                                       | Current source, consumer docs, tests, and rendered evidence              | Verified shipped behavior; no new activation meaning decided                     |
-| FR2 | The current rendered amount never displays a negative value: negative input normalizes to zero before both the translated accessible label and default `+N` content are produced. Caller-supplied child content replaces only the visible default content.                                                                                                                                                            | Current source, docs, and tests                                          | Verified shipped behavior; no new validation policy decided                      |
-| FR3 | Inside AvatarGroup, the indicator currently consumes the group's resolved size, shape, and overlap. Outside a group, it currently uses the medium size, circle shape, and zero overlap.                                                                                                                                                                                                                               | Current source, tests, stories, and browser evidence                     | Verified shipped behavior; no context contract change                            |
-| FR4 | The current root remains at least as wide as the resolved avatar size, grows inline for wider content, keeps the resolved avatar height, and applies the overlap margin in every position; AvatarGroup pads its start edge to match, so a first-child indicator stays inside the group.                                                                                                                               | Current source and browser evidence                                      | Verified shipped layout; no new geometry requirement introduced                  |
-| FR5 | The current root carries the `avatar-group-overflow` target with size and shape reflection, then combines component styles with supported consumer StyleX, class, and style inputs on that same element.                                                                                                                                                                                                              | Current source, docs, target tests, and browser evidence                 | Verified shipped theming and passthrough behavior                                |
-| FR6 | An indicator with the current activation callback carries AvatarGroup's item marker and participates in AvatarGroup's existing roving-focus sequence. The static span branch carries no group item marker and is non-interactive by default; supported caller-provided DOM props such as `tabIndex` still reach that span and may make it programmatically or sequentially focusable according to the supplied value. | Current source, BaseProps passthrough, and AvatarGroup interaction tests | Verified composition and passthrough; AvatarGroup retains roving-focus ownership |
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Basis                                |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------ |
+| FR1 | Without `onClick` the indicator is a `span` with `role="img"`, which a caller `role` replaces. With `onClick` it is a native `button type="button"` that calls `onClick` on activation and draws the shared focus-visible outline and the shared hover and pressed overlays.                                                                                                                                                                                                                                                                                                                                                               | Current source and tests             |
+| FR2 | A negative `count` is clamped to zero before both the name and the default content are produced. The name is the translated "{count} more" in both forms and replaces a caller `aria-label`, while a caller `aria-labelledby` reaches the root and names it instead; caller children replace only the visible "+N". Runtime counts are formatted through the catalog (`architecture:internationalization` INV1a). Implementation gap: the default "+N" is assembled outside the catalog, so the visible count is never locale-formatted: grouping separators, and in some locales the digits, differ from the name (Current-state impact). | Current source and tests             |
+| FR3 | Inside an AvatarGroup in the same layer (`spec:AST-038` FR7, FR8) the indicator uses the group's size, shape, numeric size, and overlap; outside one, including in a layer opened from a group, it uses `md`, `circle`, and no overlap.                                                                                                                                                                                                                                                                                                                                                                                                    | Current source and tests             |
+| FR4 | The indicator is at least the avatar size plus a 2px surface-colored border on each side wide, exactly that tall, grows inline for wider content with `--spacing-2` inline padding, and takes the group's negative inline-start overlap. It paints the neutral color over the surface with secondary text, body family, medium weight, and a font size of the larger of `--text-supporting-size` and 35% of the avatar size. Its radius follows the shape.                                                                                                                                                                                 | Current source, tests, and stories   |
+| FR5 | The root carries the `avatar-group-overflow` target reflecting `size` and `shape`. Supported DOM, ARIA, data, and event props and `ref` reach the root; `xstyle`, `className`, and `style` merge in that order after component styles.                                                                                                                                                                                                                                                                                                                                                                                                     | Current source and tests             |
+| FR6 | The button form carries the `data-avatar-item` marker, so AvatarGroup includes it in its roving set; the static form carries no marker, and a caller `tabIndex` on it is forwarded without adding it to that set.                                                                                                                                                                                                                                                                                                                                                                                                                          | Current source and AvatarGroup tests |
 
 ### Allowed variation
 
-- **AV1 — Amount and content.** The numeric amount and caller-supplied visible
-  content may vary; wider content may grow the indicator inline.
-- **AV2 — Group presentation.** Current AvatarGroup size and shape values may vary
-  while the indicator continues to consume the group's resolved context.
-- **AV3 — Styling inputs.** Supported consumer styling may vary through the current
-  BaseProps and `avatar-group-overflow` target without moving the target to a
-  different element.
+- **AV1 — Count and content.** The count and caller content vary; wider content
+  grows the indicator inline.
+- **AV2 — Theme paint.** A theme may restyle `avatar-group-overflow` per `size`
+  and `shape` without moving the target.
 
 ### Representative states
 
-| State                 | Required invariant                                                                                                                                                                                                                                                          | Allowed variation                                                                                                     |
-| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| Static default count  | One span presents the translated count label and visible `+N` content. It is non-interactive by default and remains outside AvatarGroup's roving-focus item set; supported caller DOM props such as `tabIndex` may make the span focusable according to the supplied value. | Count, group size, group shape, direction, supported consumer DOM/styling props, and resulting focusability may vary. |
-| Static custom content | The span retains the count-derived accessible label while caller content replaces the visible default. Its default interaction and passthrough behavior match the static count branch.                                                                                      | Caller owns the custom React content; supported consumer DOM and styling props may vary.                              |
-| Clickable count       | One native button presents the count-derived accessible label, participates in the group marker when grouped, and invokes the existing callback.                                                                                                                            | Count, content, group presentation, and supported consumer inputs may vary.                                           |
-| Negative count        | Accessible and default visible count content use zero rather than a negative value.                                                                                                                                                                                         | Caller-supplied visible content may still differ because it remains caller-owned.                                     |
-| Wide count            | The indicator grows inline while retaining its resolved height and content.                                                                                                                                                                                                 | Width follows rendered content and current padding.                                                                   |
-| Standalone            | Medium circle and zero-overlap fallbacks apply without AvatarGroup context.                                                                                                                                                                                                 | Count, custom content, activation mode, and consumer styles may vary.                                                 |
-| RTL                   | Logical overlap and item order follow the document direction.                                                                                                                                                                                                               | Count, content, size, shape, and activation may vary.                                                                 |
+| State                 | Required invariant                                                       | Allowed variation   |
+| --------------------- | ------------------------------------------------------------------------ | ------------------- |
+| Static count          | `role="img"` span named "{count} more", showing "+N"; not a roving item. | Count, size, shape. |
+| Static custom content | Count-derived name; caller content visible.                              | Content.            |
+| Clickable             | Button named "{count} more"; last roving item when grouped.              | Count, content.     |
+| Negative count        | Named and shown as zero.                                                 | Caller content.     |
+| Wide count            | Grows inline at the resolved height.                                     | Width.              |
+| Standalone            | `md` circle with no overlap.                                             | Count, activation.  |
+| Right-to-left         | Overlap and order follow the document direction.                         | —                   |
 
 ### Transformation and precedence order
 
-- **ORD1 — Resolve presentation.** AvatarGroup context currently supplies size,
-  shape, numeric size, and overlap; missing context falls back to medium, circle,
-  medium numeric size, and zero overlap.
-- **ORD2 — Resolve content.** The numeric input is clamped at zero, then used for
-  the translated accessible label; caller children replace only the default visible
-  `+N` content.
-- **ORD3 — Resolve root.** Callback presence selects the native-button or span
-  branch. Component-owned semantics and target data remain on that root, and the
-  current merge combines component styles with supported consumer styling inputs.
+- **ORD1 — Presentation.** AvatarGroup context → `md`, `circle`, no overlap.
+- **ORD2 — Content.** Clamp `count` at zero → translated name; caller children
+  → else "+N".
+- **ORD3 — Root attributes.** Static: `role="img"` → caller props → name →
+  component class and styles. Button: `type` and `onClick` → caller props →
+  name and item marker → press markers → component class and styles.
 
 ### Performance and resources
 
-- No new performance or resource constraint is introduced. The observed component
-  owns no state, Effect, listener, observer, timer, portal, or asynchronous resource.
+- **PR1 — No local resources.** The indicator holds no state, listener,
+  observer, or timer of its own. Both forms install the shared document-level
+  press controller on mount; only the button carries its press marker.
 
 ## Accessibility contract
 
-- **AR1 — Current accessible count.** Both current render branches expose the
-  translator-produced count label derived from the normalized numeric amount.
-- **AR2 — Current root semantics.** The activation-callback branch is a native
-  `button` with `type="button"` and the shared focus-visible treatment. The static
-  branch remains a span and is non-interactive by default; supported caller DOM
-  props, including `tabIndex`, are forwarded and may alter its focusability.
-- **AR3 — Current group participation.** The activation-callback branch carries
-  the current AvatarGroup item marker so AvatarGroup's existing roving-focus owner
-  may include it. The static branch carries no such marker even when caller DOM
-  props make its span focusable. This draft does not copy or change AvatarGroup's
-  focus algorithm.
+- **AR1 — Count name.** Both forms are named by the translated count, never by
+  custom children; a caller `aria-labelledby` reaches the root and names either
+  form instead, while a caller `aria-label` is replaced.
+- **AR2 — Roles.** The static form is an image unless the caller supplies a
+  role; the clickable form is a native button with the shared focus-visible
+  outline.
+- **AR3 — Group participation.** Only the clickable form joins AvatarGroup's
+  roving set.
+- **AR4 — Target size.** A clickable indicator's target is at least 24 by 24
+  CSS pixels or has the spacing WCAG 2.2 2.5.8 allows. From `xsm` up the
+  button is at least 24 by 24 and paints above the avatar it overlaps.
+  Implementation gap: in a group sized 16px the button is 20px tall.
 
 ## Design relationships
 
-| Anatomy or state | Design requirement                                                                      | Representation authority            | Hierarchy role    | Component contract |
-| ---------------- | --------------------------------------------------------------------------------------- | ----------------------------------- | ----------------- | ------------------ |
-| Count label      | Presents compact supporting count content on the current indicator surface.             | Current source and consumer docs    | Supporting        | FR2, FR4, AR1      |
-| Button behavior  | Uses the current native-button branch with shared overlay and focus-visible treatments. | Current source and shared utilities | Supporting action | FR1, FR6, AR2, AR3 |
+| Anatomy or state | Design requirement                                               | Representation authority            | Hierarchy role    | Component contract |
+| ---------------- | ---------------------------------------------------------------- | ----------------------------------- | ----------------- | ------------------ |
+| Count label      | Compact supporting count on a neutral chip matching the avatars. | Current source and docs             | Supporting        | FR2, FR4, AR1      |
+| Button behavior  | Native button with shared overlay and focus-visible treatments.  | Current source and shared utilities | Supporting action | FR1, FR6, AR2, AR3 |
 
-This observational draft records the current representation and target placement.
-It does not decide a new density, proportion, state treatment, or visual default.
+Theming: the root is the `avatar-group-overflow` target; the count label
+inherits it. The consumer anatomy names no root part, so no anatomy-theming
+block is declared.
 
 ## Family and system relationships
 
-- `architecture:knowledge-contracts` owns draft/current authority, observational
-  backfill boundaries, exact-head approval, and conflict routing.
-- `architecture:component-theming-surface` owns painting-target qualification,
-  target capability metadata, and size/shape state reflection on the current
-  target.
-- `architecture:public-component-api` owns the released subpath, BaseProps
-  passthrough, styling composition, ref reachability, and compatibility boundary.
-- `spec:AST-002` owns API admission and requires any future public or behavioral
-  delta to identify current authority rather than deriving permission from this
-  observational draft.
-- `spec:AST-029` owns the Night Watch backfill procedure and keeps this draft from
-  settling new behavior or changing product meaning.
+- `component:AvatarGroup` supplies size, shape, and overlap and owns the roving
+  set the clickable form joins.
+- `architecture:component-theming-surface` owns target qualification and
+  reflection.
+- `architecture:public-component-api` owns passthrough, styling composition, and
+  ref rules.
+- `spec:AST-002` owns admission of any change to this public surface.
 
 ## Verification map
 
-| Contract                  | Verification                                                                                         | Representative states                                                                                                     | Mutation or failure expectation                                                                                                                                                                        | Audit section                             |
-| ------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------- |
-| FR1, FR2, AR1, AR2        | `AvatarGroupOverflow.test.tsx` render, callback, content, count, ref, passthrough, and locale suites | Static default, static with caller DOM props, clickable, custom content, zero, negative, large, localized, and standalone | Changing the root branch, callback, normalized count, visible fallback, accessible label, supported DOM passthrough, or ref target fails focused public-interface assertions.                          | `audit:AvatarGroupOverflow/behavior`      |
-| FR3, FR4                  | `AvatarGroupOverflow.test.tsx`, dedicated stories, and browser evidence                              | Every current size and shape, grouped, standalone, wide count, and narrow viewport                                        | Losing context inheritance, fallbacks, shape reflection, standalone sizing, or wide-content containment fails focused assertions or rendered evidence.                                                 | `audit:AvatarGroupOverflow/layout`        |
-| FR5                       | `themingTargets.test.ts`, `derivedVarRegistry.test.ts`, source inspection, and dedicated stories     | Static and interactive roots across sizes and shapes                                                                      | Target metadata, reflected axes, private overlap variable ownership, or painting-root placement drift fails guards or rendered inspection.                                                             | `audit:AvatarGroupOverflow/theming`       |
-| FR6, AR3                  | `AvatarGroup.test.tsx` overflow-button roving-focus suite plus source/passthrough inspection         | Activation-callback branch after an interactive Avatar; static span with and without caller `tabIndex`                    | Removing the marker from the callback branch breaks group participation; adding it to the static branch changes the observed roving set; dropping caller `tabIndex` contradicts BaseProps passthrough. | `audit:AvatarGroupOverflow/accessibility` |
-| RTL relation              | `apps/storybook/rtl-audit/targets.json` D2 target and `AvatarGroupOverflow.stories.tsx`              | Default grouped overflow in LTR and RTL                                                                                   | Failing to mirror the Avatar-to-overflow order fails component-scoped RTL coverage.                                                                                                                    | `audit:AvatarGroupOverflow/i18n-rtl`      |
-| Documentation and surface | `AvatarGroupOverflow.doc.mjs`, block data tests, export checks, and `scripts/check-knowledge.mjs`    | Consumer docs, blocks, package subpath, and this draft                                                                    | Missing or stale docs, exports, required structure, relationships, or anatomy dispositions fail repository validation.                                                                                 | `audit:AvatarGroupOverflow/docs`          |
-
-Current audit scores, screenshots, eligibility, and per-run receipts remain in their
-existing wiki, pull-request, and trusted-check owners rather than this contract.
+| Contract       | Verification                                                                                   | Representative states                            | Mutation or failure expectation                                                                                                                                                                                                                                                                                                                                    | Audit section                             |
+| -------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------- |
+| FR1, AR2       | `AvatarGroupOverflow.test.tsx` render, role, and callback tests                                | Static, caller role, clickable                   | A wrong element, a lost `img` role or caller role, a missing button, or a lost callback fails. Gap: the button's `type="button"`, its focus outline and hover and pressed overlays have no automated check.                                                                                                                                                        | `audit:AvatarGroupOverflow/behavior`      |
+| FR2, AR1, ORD2 | `AvatarGroupOverflow.test.tsx` count, content, and locale tests                                | Zero, negative, large, custom content, localized | A negative count, a wrong default "+N" or name, missing custom content, or an untranslated name fails. Gap: no test asserts the name with custom children, a caller `aria-label` being replaced, a caller `aria-labelledby`, or a locale with its own digits; the large-count test asserts the unformatted "+4912" beside "4,912 more", which is the recorded gap. | `audit:AvatarGroupOverflow/behavior`      |
+| FR3, ORD1      | `AvatarGroupOverflow.test.tsx` size and shape tests                                            | Grouped; standalone                              | Lost group size or shape fails. Gap: no test asserts the standalone `md`, `circle`, and no-overlap fallback, or the layer clause.                                                                                                                                                                                                                                  | `audit:AvatarGroupOverflow/layout`        |
+| FR4            | `AvatarGroup.test.tsx` overlap test; `AvatarGroupOverflow.stories.tsx`                         | Grouped, wide count, every shape                 | A lost overlap margin fails. Gap: the box size, border, inline growth and padding, paint, font-size floor, and radius are visible only in the rendered fixture.                                                                                                                                                                                                    | `audit:AvatarGroupOverflow/layout`        |
+| FR5, ORD3      | `themingTargets.test.ts`; `AvatarGroupOverflow.test.tsx` ref, className, and caller-role tests | Both forms                                       | Target drift, a lost ref, a dropped `className`, or caller props that stop reaching the static form or land before its `role="img"` fail. Gap: no test covers `xstyle`, `style`, the button form's passthrough, or the rest of ORD3's order.                                                                                                                       | `audit:AvatarGroupOverflow/theming`       |
+| FR6, AR3       | `AvatarGroup.test.tsx` overflow roving test                                                    | Button after an interactive avatar               | A button missing from the roving set fails. Gap: no test asserts that the static form carries no marker or that a caller `tabIndex` on it is forwarded.                                                                                                                                                                                                            | `audit:AvatarGroupOverflow/accessibility` |
+| Right-to-left  | `apps/storybook/rtl-audit/targets.json` entry                                                  | Grouped overflow in both directions              | Gap: the audit lists the fixture, but no automated check fails on an unmirrored avatar-to-overflow order.                                                                                                                                                                                                                                                          | `audit:AvatarGroupOverflow/i18n-rtl`      |
+| PR1            | Source review                                                                                  | Both forms                                       | Gap: no automated check fails if the indicator adds state, a listener, an observer, or a timer of its own.                                                                                                                                                                                                                                                         | `audit:AvatarGroupOverflow/behavior`      |
+| AR1, AR2       | Accessibility-tree evidence (`spec:AST-009` FR3)                                               | Static and clickable forms                       | Gap: no accessibility-tree check proves the image or button role and the count name; the unit tests query the DOM.                                                                                                                                                                                                                                                 | `audit:AvatarGroupOverflow/accessibility` |
+| AR4            | `AvatarGroupOverflow.stories.tsx` in a browser                                                 | Clickable indicator in a group                   | Gap: no automated target-size check; the 16px group is the recorded gap.                                                                                                                                                                                                                                                                                           | `audit:AvatarGroupOverflow/accessibility` |
 
 ## Decision log
 
-None. This draft records current facts and introduces no component-local API,
-behavior, accessibility, layout, theming, or design decision.
+None recorded. The record describes shipped behavior.
 
 ## Open questions
 
@@ -202,6 +206,5 @@ None.
 
 ## Content boundary
 
-This file does not duplicate consumer prop tables or examples, current audit
-scores or screenshots, implementation steps, AvatarGroup's focus algorithm, or
-shared API, theming, knowledge, and audit-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.