@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/Avatar/AvatarStatusDot.spec.md

@@ -1,13 +1,13 @@
 ---
 schema_version: 3
-template_version: 4
+template_version: 7
 kind: component
 id: component:AvatarStatusDot
-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: [public-api, behavior, layout, theming, accessibility]
 verified_by:
@@ -24,119 +24,140 @@ families: []
 design_specs: []
 architecture:
   [
-    architecture:knowledge-contracts,
     architecture:component-theming-surface,
     architecture:component-style-authoring,
     architecture:public-component-api,
     architecture:theme-tokens,
   ]
 contributing: []
-system_specs: [spec:AST-002, spec:AST-029]
+system_specs: [spec:AST-002, spec:AST-009, spec:AST-038]
 ---
 
 # AvatarStatusDot component contract
 
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                        |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | A status dot for Avatar's `status` slot with `variant` (default `success`), optional `label`, and optional `icon`.                              |
+| Behavior                | The dot sizes itself from the owning Avatar in three tiers, pairs each built-in variant with a distinct shape, and reports its label to Avatar. |
+| End-user impact         | Screen-reader users hear the status in the avatar's name; sighted users can tell statuses apart by shape as well as color.                      |
+| Builder impact          | None; the record describes shipped behavior.                                                                                                    |
+| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. One implementation gap is listed under Current-state impact.         |
+| Review checks           | Reject a built-in variant that differs only by color, an exposed glyph or icon, or a label that stops reaching the owning Avatar.               |
+| Governing rules         | `architecture:component-theming-surface/INV2,INV6,INV14`; `architecture:public-component-api/INV5,INV6,INV8`; WCAG 2.2 1.4.1.                   |
+
+This table is a review projection; the body below is authoritative.
+
 ## Intent
 
-AvatarStatusDot renders the compact status indicator currently composed through
-Avatar's `status` slot. This draft records verified shipped behavior only. It does
-not change runtime behavior, public API, compatibility, target names, defaults, or
-visual meaning.
+AvatarStatusDot renders the compact status indicator composed through Avatar's
+`status` slot. It owns the dot's size tiers, its built-in non-color marks, and
+reporting its label into the owning Avatar's accessible name.
 
 ## Compatibility and migration
 
 - Released default preserved: `yes`
-- Compatibility class: additive observational documentation and story coverage;
-  runtime behavior, DOM, targets, defaults, and public API remain unchanged
+- Compatibility class: records shipped behavior; no public prop, default, DOM,
+  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
+
+- **Augmented variant without a fallback (FR6).** `AvatarStatusDotVariantMap`
+  admits theme-added names, but a name with no built-in rule renders the dot's
+  geometry and `data-variant` with no fill, ink, or glyph. A caller `icon` with
+  a `style` color covers the medium and large tiers, but the small tier drops
+  the icon, and nothing paints a theme-independent baseline.
+  `architecture:component-theming-surface` INV14 requires an extensible visual
+  axis to have a safe theme-independent baseline.
+
 ## Ownership boundary
 
 **Owns**
 
-- The painted status-dot root and its current `avatar-status-dot` target.
-- The current built-in filled, ring, and minus visual branches.
-- Current size-tier resolution from Avatar's resolved numeric size.
+- The painted status-dot root and its `avatar-status-dot` target.
+- The built-in filled, ring, and minus visual branches and the
+  `avatar-status-dot-glyph` target.
+- Size-tier resolution from Avatar's resolved numeric size.
 - Reporting its optional status label into Avatar's accessible name.
 
 **Does not own / non-goals**
 
-- Avatar identity, image fallback, shape, status placement, or interactive behavior;
-  those remain with `component:Avatar` when that contract exists.
+- Avatar identity, image fallback, shape, status placement, or interactive behavior
+  — owned by `component:Avatar`.
 - The meaning or artwork of caller-supplied icon content.
-- A new status vocabulary, visual default, or compatibility promise.
 
 ## Public concepts
 
-Consumer syntax remains in `AvatarStatusDot.doc.mjs`. The table records current
-observable concepts rather than replacing that prop reference.
+Consumer syntax remains in `AvatarStatusDot.doc.mjs`.
 
-| Concept        | Closed values or states                                                               | Meaning                                                             | Availability by variant/orientation/state | Default               | Owner                                                                                  | Stability                 | Invalid-value behavior                                                                                                               |
-| -------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ----------------------------------------- | --------------------- | -------------------------------------------------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| Status variant | Built-ins `success`, `neutral`, `error`; the released map also admits augmented names | Selects the current plate color and built-in non-color mark.        | All size tiers; LTR and RTL.              | `success`             | `component:AvatarStatusDot` for built-ins; the unmatched augmented path is legacy debt | Observed released surface | An augmented name with no matching built-in rule keeps root geometry and `data-variant` but has no reliable color-and-icon fallback. |
-| Status label   | String or absent                                                                      | Names a standalone dot and is reported into the owning Avatar name. | Every variant and size.                   | Absent                | Caller supplies meaning; component exposes and reports it                              | Observed released surface | Empty or absent label emits no role or accessible name on the dot and reports no status name.                                        |
-| Custom icon    | Renderable React content or absent                                                    | Replaces the built-in glyph where the current size tier has room.   | Medium and large tiers; hidden on small.  | Absent                | Caller owns artwork; component owns placement and suppression rules                    | Observed released surface | Booleans and empty strings are ignored; a component that renders no DOM still suppresses the built-in glyph.                         |
-| DOM extension  | Supported BaseProps inputs and ref                                                    | Extends the current root and combines consumer styles.              | Every render branch.                      | 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                                                                                                              |
+| -------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ----------------------------------------- | --------------------- | ------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| Status variant | Built-ins `success`, `neutral`, `error`; the released map also admits augmented names | Selects the plate color and built-in non-color mark.                | All size tiers; LTR and RTL.              | `success`             | `component:AvatarStatusDot`                                         | Stable    | An augmented name is reflected as `data-variant` and keeps a safe theme-independent baseline (FR6); today it has none, the FR6 gap. |
+| Status label   | String or absent                                                                      | Names a standalone dot and is reported into the owning Avatar name. | Every variant and size.                   | Absent                | Caller supplies meaning; component exposes and reports it           | Stable    | Empty or absent label emits no role or accessible name on the dot and reports no status name.                                       |
+| Custom icon    | Renderable React content or absent                                                    | Replaces the built-in glyph where the size tier has room.           | Medium and large tiers; hidden on small.  | Absent                | Caller owns artwork; component owns placement and suppression rules | Stable    | Booleans and empty strings are ignored; a component that renders no DOM still suppresses the built-in glyph.                        |
+| DOM extension  | Supported BaseProps inputs and ref                                                    | Extends the root and combines consumer styles.                      | Every render branch.                      | No additional inputs. | `architecture:public-component-api`                                 | Stable    | BaseProps omissions remain unsupported.                                                                                             |
 
 ## Behavioral and layout contract
 
-| ID  | Candidate invariant                                                                                                                                                                                                                                                                                               | Basis                                                                                                      | Draft review state                                                                           |
-| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
-| FR1 | Avatar sizes up to 36px currently resolve a 10px dot with 1px border and no custom icon; 40–72px resolve 20px/2px/12px; 96px and above resolve 32px/4px/18px. Standalone use reads AvatarSizeContext's current 36px default.                                                                                      | Current source, tests, stories, and browser evidence                                                       | Verified shipped geometry; no new threshold or size meaning decided                          |
-| FR2 | `success` currently paints a filled semantic-success plate without an inner glyph; `neutral` paints a surface plate with a ring; `error` paints a semantic-error plate with a minus.                                                                                                                              | Current source, tests, consumer docs, and rendered evidence                                                | Verified built-in behavior; no new status vocabulary decided                                 |
-| FR3 | At medium and large tiers, renderable `icon` content replaces the built-in glyph and is centered in an assistive-technology-hidden wrapper. At the small tier the icon is omitted and the built-in glyph branch remains.                                                                                          | Current source, tests, and rendered evidence                                                               | Verified shipped behavior; icon meaning remains caller-owned                                 |
-| FR4 | A non-empty `label` currently adds `role="img"` and `aria-label` to the dot. The callback ref reports the same label through AvatarStatusLabelContext before paint and withdraws it on detach.                                                                                                                    | Current source and Avatar integration tests                                                                | Verified shipped behavior; this audit does not alter requiredness                            |
-| FR5 | The root currently carries `avatar-status-dot` with `variant`; ring and minus SVGs carry `avatar-status-dot-glyph` with `shape`. Supported consumer styling and ref inputs reach the root.                                                                                                                        | Current source, docs, target tests, and ref/passthrough inspection                                         | Verified shipped theming and DOM surface                                                     |
-| FR6 | The released `AvatarStatusDotVariantMap` currently admits augmented names. For an unmatched name, root geometry and reflected `data-variant` remain while built-in fill, ink, and glyph are absent. The current surface provides no reliable caller-configurable path that supplies both color and icon fallback. | Current source, docs, focused test, `architecture:component-theming-surface/INV14`, and owner confirmation | Pre-existing current-authority conformance gap; this audit records but does not remediate it |
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Basis                                                                                  |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
+| FR1 | Avatar sizes up to 36px resolve a 10px dot with a 1px border and no custom icon; 40–72px resolve a 20px dot, 2px border, and 12px icon; 96px and above resolve a 32px dot, 4px border, and 18px icon. The border is the surface color. Outside an Avatar in the same layer (`spec:AST-038` FR7, FR8) the dot uses the 36px tier.                                                                                                                                                                                                                                   | Current source, tests, and stories                                                     |
+| FR2 | `success` paints a filled `--color-success` plate with no inner glyph; `neutral` paints a surface plate with a ring in secondary text color; `error` paints a `--color-error` plate with a minus bar in `--color-on-error`, and `success` sets `--color-on-success` as its ink. Glyphs are stroked in `currentColor` at 1, 1.5, or 2px by tier; the minus spans 75% of the inner field with round caps. The plates are the strong status fills and their ink is the matching content role (`architecture:theme-tokens` INV11).                                     | Current source, tests, and consumer docs                                               |
+| FR3 | At medium and large tiers, renderable `icon` content replaces the built-in glyph and is centered in an assistive-technology-hidden wrapper sized to the tier's icon size. At the small tier the icon is omitted and the built-in glyph remains. Booleans and empty strings are not renderable.                                                                                                                                                                                                                                                                     | Current source and tests                                                               |
+| FR4 | A non-empty `label` adds `role="img"` and `aria-label` to the dot. The dot reports the same label to the owning Avatar before paint, at any wrapper depth, and withdraws it when it unmounts.                                                                                                                                                                                                                                                                                                                                                                      | Current source and Avatar integration tests                                            |
+| FR5 | The root carries `avatar-status-dot` with `variant`; ring and minus SVGs carry `avatar-status-dot-glyph` with `shape`. Supported consumer props and ref reach the root; the dot's own role, name, and styling apply after caller props, and `xstyle`, `className`, and `style` merge in that order.                                                                                                                                                                                                                                                                | Current source, docs, and target tests                                                 |
+| FR6 | The released `AvatarStatusDotVariantMap` admits augmented names, and an extensible visual axis has a safe theme-independent baseline (`architecture:component-theming-surface` INV14). For an unmatched name, root geometry and reflected `data-variant` remain while built-in fill, ink, and glyph are absent; at the medium and large tiers a caller `icon` with a `style` color supplies a color and a mark, and at the small tier the icon is not rendered. Implementation gap: no theme-independent baseline paints an unmatched name (Current-state impact). | Current source, docs, focused test, and `architecture:component-theming-surface/INV14` |
 
 ### Allowed variation
 
 - **AV1 — Identity and meaning.** The status label and caller icon artwork may vary.
-- **AV2 — Theme output.** Current targets and reflected axes may vary through the
-  public theming system without moving target ownership.
-- **AV3 — Consumer styling.** Supported BaseProps inputs may vary on the current
-  root while component-owned size and reporting behavior remain.
+- **AV2 — Theme output.** Targets and reflected axes may vary through the public
+  theming system without moving target ownership.
+- **AV3 — Consumer styling.** Supported BaseProps inputs may vary on the root
+  while component-owned size and reporting behavior remain.
 
 ### Representative states
 
-| State                  | Required invariant                                                                                        | Allowed variation                                                                         |
-| ---------------------- | --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
-| Built-in variants      | Current fill/ring/minus branches and reflected `variant` remain.                                          | Label, Avatar content, size, theme, and direction may vary.                               |
-| Small tier             | Dot and built-in shape remain; custom icon is omitted.                                                    | Built-in variant and label may vary.                                                      |
-| Medium and large tiers | Current dimensions apply; renderable custom icon replaces the glyph.                                      | Icon artwork, variant, label, and theme may vary.                                         |
-| Labelled               | Dot exposes its label and reports it to Avatar.                                                           | The caller-authored label may vary.                                                       |
-| Unlabelled             | Dot has no current role/name and reports no status label.                                                 | Visual variant and icon may still render.                                                 |
-| Augmented variant      | Root geometry and reflected `data-variant` render; unmatched built-in fill, ink, and glyph remain absent. | The current released surface has no reliable fallback path supplying both color and icon. |
-| RTL                    | Dot content is direction-neutral; Avatar owns logical corner placement.                                   | Theme, variant, size, label, and icon may vary.                                           |
+| State                  | Required invariant                                                                                     | Allowed variation                                           |
+| ---------------------- | ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------- |
+| Built-in variants      | Fill, ring, and minus branches and reflected `variant` remain.                                         | Label, Avatar content, size, theme, and direction may vary. |
+| Small tier             | Dot and built-in shape remain; custom icon is omitted.                                                 | Built-in variant and label may vary.                        |
+| Medium and large tiers | Tier dimensions apply; renderable custom icon replaces the glyph.                                      | Icon artwork, variant, label, and theme may vary.           |
+| Labelled               | Dot exposes its label and reports it to Avatar.                                                        | The caller-authored label may vary.                         |
+| Unlabelled             | Dot has no role or name and reports no status label.                                                   | Visual variant and icon may still render.                   |
+| Augmented variant      | Root geometry and reflected `data-variant` render; built-in fill, ink, and glyph are absent (FR6 gap). | A theme may paint the added name.                           |
+| RTL                    | Dot content is direction-neutral; Avatar owns logical corner placement.                                | Theme, variant, size, label, and icon may vary.             |
 
 ### Transformation and precedence order
 
-- **ORD1 — Resolve size.** Read AvatarSizeContext, then select the current discrete
-  size tier and dimensions.
+- **ORD1 — Resolve size.** Take the owning Avatar's resolved size (36px outside
+  an Avatar in the same layer), then select the discrete size tier and dimensions.
 - **ORD2 — Resolve mark.** A renderable icon wins when the tier permits it;
   otherwise the built-in variant glyph is selected when one exists.
-- **ORD3 — Resolve root.** Component target/style output is combined with supported
-  consumer StyleX, class, and style inputs on the current root.
+- **ORD3 — Resolve root.** Caller props → role and name → component target and
+  styles → `xstyle` → `className` → `style`.
 
 ### Performance and resources
 
-- **PR1 — Commit-phase label reporting.** The current callback-ref path reports and
-  withdraws the label without adding a state mirror, Effect, observer, listener,
-  timer, or second render.
+- **PR1 — Reporting without re-rendering.** Reporting or withdrawing the label
+  causes no extra render of the dot or the avatar and leaves no listener,
+  observer, or timer behind.
 
 ## Accessibility contract
 
-- **AR1 — Current accessible name.** A non-empty `label` names a standalone dot and
-  is composed into Avatar's name through the current context report.
+- **AR1 — Accessible name.** A non-empty `label` names a standalone dot and is
+  composed into the owning Avatar's name.
 - **AR2 — Decorative visual marks.** The built-in SVG and custom-icon wrapper are
   hidden from assistive technology because the root or Avatar name carries status.
-- **AR3 — Current built-in non-color cues.** The three built-in variants use filled,
-  ring, and minus topologies in addition to semantic color. Replacing that mark with
-  caller content may change the non-color distinction; this draft records rather
-  than resolves that public seam.
+- **AR3 — Built-in non-color cues.** The three built-in variants use filled,
+  ring, and minus topologies in addition to semantic color (WCAG 2.2 1.4.1). A
+  caller icon replaces that mark at medium and large tiers, so the non-color
+  distinction then depends on the caller using a different icon per status.
 
 ## Design relationships
 
@@ -146,17 +167,11 @@ observable concepts rather than replacing that prop reference.
 | Built-in glyph   | Ring or minus supplements color for neutral/error.             | WCAG 2.2 SC 1.4.1 plus current shipped representation                | Meaningful non-text cue    | FR2, AR3           |
 | Custom icon      | Caller artwork replaces the built-in mark where space permits. | Caller owns artwork; current source owns placement                   | Conditional meaningful cue | FR3, AR2, AR3      |
 
-This observational draft does not select new glyphs, proportions, density, status
-semantics, or prominence treatment.
-
 ## Family and system relationships
 
-- `architecture:knowledge-contracts` owns draft/current authority, conflict routing,
-  and observational-record boundaries.
 - `architecture:component-theming-surface` owns painting-target qualification,
   reflected axes, and the reliable theme-independent fallback required for an
-  extensible visual axis. This audit records the current violation and leaves the
-  public surface unchanged.
+  extensible visual axis; FR6 records the gap against it.
 - `architecture:component-style-authoring` owns StyleX lowering and permits the
   component-owned non-glyph SVG shapes used here.
 - `architecture:public-component-api` owns the released subpath, BaseProps
@@ -164,24 +179,23 @@ semantics, or prominence treatment.
 - `architecture:theme-tokens` owns the semantic color and radius vocabulary.
 - `spec:AST-002` owns API admission and requires future public behavior or default
   changes to identify current authority.
-- `spec:AST-029` owns this Night Watch observational backfill and keeps it from
-  settling new product meaning.
 
 ## Verification map
 
-| Contract                  | Verification                                                                               | Representative states                                                | Mutation or failure expectation                                                                                               | Audit section                         |
-| ------------------------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
-| FR1–FR3, AR2, AR3         | `AvatarStatusDot.test.tsx` plus dedicated Storybook browser matrix                         | Three size tiers, three built-ins, custom icon present/absent        | Size-tier, mark-selection, hidden-icon, or built-in-shape drift fails focused assertions or rendered receipts.                | `audit:AvatarStatusDot/behavior`      |
-| FR4, AR1                  | `Avatar.test.tsx` status-name suites and `AvatarStatusDot.test.tsx`                        | Direct/wrapped/changing/removed labels; labelled and unlabelled dots | Losing the standalone or composed status name, commit-phase update, or cleanup fails role/name assertions.                    | `audit:AvatarStatusDot/accessibility` |
-| FR5                       | Theming target and extensible-axis tests plus source inspection                            | Built-in and augmented variants, glyph ring/minus, consumer styling  | Missing target metadata/reflection, target movement, or dropped supported DOM/style inputs fails checks or inspection.        | `audit:AvatarStatusDot/theming`       |
-| FR6                       | Focused augmented-variant unit test and source/docs inspection                             | Augmented name without a matching built-in rule                      | The base-only output remains visible while the missing reliable color-and-icon fallback stays recorded as pre-existing debt.  | `audit:AvatarStatusDot/api`           |
-| RTL relation              | Dedicated RTL audit coverage and receipted LTR/RTL browser frames                          | Built-ins across current sizes                                       | New directional glyph, physical positioning, or unmatched transform produces a coverage or render difference.                 | `audit:AvatarStatusDot/i18n-rtl`      |
-| Documentation and surface | Consumer docs, blocks, dedicated stories, export checks, and `scripts/check-knowledge.mjs` | Props, package subpath, blocks, story states, and this draft         | Missing/stale docs, exports, required structure, relationships, or story coverage fail repository checks or audit inspection. | `audit:AvatarStatusDot/docs`          |
+| Contract          | Verification                                                              | Representative states                                                | Mutation or failure expectation                                                                                                                                        | Audit section                         |
+| ----------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- |
+| FR1–FR3, AR2, AR3 | `AvatarStatusDot.test.tsx` and `AvatarStatusDot.stories.tsx` in a browser | Three size tiers, three built-ins, custom icon present/absent        | Size-tier, mark-selection, hidden-icon, or built-in-shape drift fails focused assertions or the rendered fixture.                                                      | `audit:AvatarStatusDot/behavior`      |
+| FR4, AR1          | `Avatar.test.tsx` status-name suites and `AvatarStatusDot.test.tsx`       | Direct/wrapped/changing/removed labels; labelled and unlabelled dots | Losing the standalone or composed status name, commit-phase update, or cleanup fails role/name assertions.                                                             | `audit:AvatarStatusDot/accessibility` |
+| FR5               | `themingTargets.test.ts` and `extensibleAxes.test.ts`                     | Built-in and augmented variants, glyph ring/minus                    | Missing target metadata or axis wiring fails the structural checks. Gap: no test renders the dot to check that consumer props, ref, and styling inputs reach the root. | `audit:AvatarStatusDot/theming`       |
+| FR6               | `AvatarStatusDot.test.tsx` augmented-variant test                         | Augmented name without a matching built-in rule                      | A glyph appearing for an unmatched name fails. Gap: a fill appearing, and the caller `icon` path, have no automated check.                                             | `audit:AvatarStatusDot/api`           |
+| RTL relation      | `AvatarStatusDot.stories.tsx` in a browser in both directions             | Built-ins across all size tiers                                      | New directional glyph, physical positioning, or unmatched transform is visible in the rendered fixture.                                                                | `audit:AvatarStatusDot/i18n-rtl`      |
+| Record structure  | `scripts/check-knowledge.mjs`                                             | This record                                                          | Missing required structure or relationships fails repository validation.                                                                                               | `audit:AvatarStatusDot/docs`          |
+| PR1               | `Avatar.test.tsx` no-extra-render test                                    | Wrapped status label                                                 | An extra render or a reporting loop fails.                                                                                                                             | `audit:AvatarStatusDot/behavior`      |
+| AR1, AR2          | Accessibility-tree evidence (`spec:AST-009` FR3)                          | Labelled and unlabelled standalone dots                              | Gap: no accessibility-tree check proves the standalone image role and name or the hidden marks; the unit tests query the DOM.                                          | `audit:AvatarStatusDot/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
 

package/src/Avatar/AvatarStatusDot.test.tsx

@@ -198,6 +198,28 @@ describe('AvatarStatusDot', () => {
       }
     });
 
+    it('uses each filled status plate matching on-fill ink role', () => {
+      const probe = stylex.create({
+        successInk: {color: colorVars['--color-on-success']},
+        errorInk: {color: colorVars['--color-on-error']},
+      });
+      const cases = [
+        ['success', probe.successInk],
+        ['error', probe.errorInk],
+      ] as const;
+
+      for (const [variant, ink] of cases) {
+        const inkClasses = (stylex.props(ink).className ?? '')
+          .split(' ')
+          .filter(cls => !cls.includes('__'));
+        expect(inkClasses.length).toBeGreaterThan(0);
+        const dot = renderDot({variant}, 48);
+        for (const cls of inkClasses) {
+          expect(dot.className).toContain(cls);
+        }
+      }
+    });
+
     it('lets a user icon inherit the dot ink instead of hard-coding surface', () => {
       // Surface ink on the surface-filled ring variant would be invisible.
       const probe = stylex.create({

package/src/Avatar/AvatarStatusDot.tsx

@@ -137,7 +137,7 @@ const styles = stylex.create({
   // `currentColor`, so the two can never drift out of contrast.
   success: {
     backgroundColor: colorVars['--color-success'],
-    color: colorVars['--color-background-surface'],
+    color: colorVars['--color-on-success'],
   },
   // The ring variant inverts: a hollow shape only reads as hollow if its
   // interior is not the variant colour, so the plate is surface and the
@@ -149,7 +149,7 @@ const styles = stylex.create({
   },
   error: {
     backgroundColor: colorVars['--color-error'],
-    color: colorVars['--color-background-surface'],
+    color: colorVars['--color-on-error'],
   },
   icon: {
     display: 'flex',

package/src/AvatarGroup/AvatarGroup.spec.md

@@ -0,0 +1,205 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:AvatarGroup
+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/AvatarGroup/AvatarGroup.test.tsx,
+    packages/core/src/AvatarGroup/AvatarGroupOverflow.test.tsx,
+    packages/core/src/Avatar/Avatar.test.tsx,
+    packages/core/src/theme/themingTargets.test.ts,
+    apps/storybook/stories/AvatarGroup.stories.tsx,
+    apps/storybook/stories/AvatarGroupOverflow.stories.tsx,
+  ]
+modules: []
+families: []
+design_specs: []
+architecture:
+  [
+    architecture:component-theming-surface,
+    architecture:internationalization,
+    architecture:public-component-api,
+  ]
+contributing: []
+system_specs: [spec:AST-009, spec:AST-038]
+---
+
+# AvatarGroup component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                       |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | A labelled group of caller-supplied Avatar children, optionally ending in one AvatarGroupOverflow, with a uniform `size` and `shape`.                          |
+| Behavior                | Members overlap by a quarter of the avatar size; interactive members share one tab stop with arrow-key roving and a translated keyboard hint.                  |
+| End-user impact         | Screen-reader users hear a named group; keyboard users Tab into the group once and move between interactive avatars with arrow keys.                           |
+| Builder impact          | None; the record describes shipped behavior.                                                                                                                   |
+| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. One implementation gap is listed under Current-state impact.                        |
+| Review checks           | Reject a member whose own size or shape wins inside the group, more than one tab stop over interactive members, or a keyboard hint with no interactive member. |
+| Governing rules         | `architecture:public-component-api/INV5,INV6,INV7,INV8`; `architecture:component-theming-surface/INV2,INV6`; `architecture:internationalization/INV1a`.        |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+AvatarGroup shows several people as one compact, overlapping row. It owns the
+group's name, the uniform size and shape it passes to its members, the overlap
+geometry, and keyboard movement between interactive members.
+
+## Compatibility and migration
+
+- Released default preserved: `yes`
+- Compatibility class: records shipped behavior; no public prop, default, DOM,
+  or styling output changes
+- Controlled/uncontrolled behavior: not applicable
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Current-state impact
+
+- **Stale hint and tab stop (FR5, AR2, AR3).** When a member becomes a link or
+  button, or turns static, through its own state while the group does not
+  render, the group keeps its previous hint and tab stop. New interactive
+  members get no hint and are separate Tab stops until focus enters the group;
+  a group left with no interactive members keeps a stale hint; and when the
+  member holding the tab stop turns static, the remaining links keep
+  `tabindex="-1"`, so Tab skips the group and keyboard users cannot reach them
+  until it renders again.
+
+## Ownership boundary
+
+**Owns**
+
+- The group root, its role and name, and its `avatar-group` target.
+- Size, shape, overlap, and numeric size supplied to members through context.
+- The start padding that keeps the first overlapped member inside the group.
+- Roving focus over members carrying the avatar item marker, and the keyboard
+  hint.
+
+**Does not own / non-goals**
+
+- Which avatars are visible and the hidden count — owned by the product
+  callsite, which slices its list.
+- Each member's rendering, name, tooltip, and in-group ring — owned by
+  `component:Avatar`.
+- The "+N" indicator — owned by `component:AvatarGroupOverflow`.
+
+## Public concepts
+
+| Concept  | Closed values or states         | Meaning                                             | Availability by variant/orientation/state | Default  | Owner                   | Stability | Invalid-value behavior           |
+| -------- | ------------------------------- | --------------------------------------------------- | ----------------------------------------- | -------- | ----------------------- | --------- | -------------------------------- |
+| Size     | Any `component:Avatar` size     | Applied to every member and the overflow indicator. | All groups                                | `md`     | `component:AvatarGroup` | Stable    | TypeScript rejects other values. |
+| Shape    | `circle`, `rounded`, `square`   | Applied to every member and the overflow indicator. | All groups                                | `circle` | `component:AvatarGroup` | Stable    | TypeScript rejects other values. |
+| Keyboard | static group; interactive group | Whether any member carries the avatar item marker.  | Read at each of the group's own renders   | static   | `component:AvatarGroup` | Stable    | —                                |
+
+## Behavioral and layout contract
+
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Basis                    |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| FR1 | The root is an inline-flex, vertically centered `div` with `role="group"`, named by the caller's `aria-label` or `aria-labelledby`, else the translated "Avatars". It carries the `avatar-group` target reflecting `size` and `shape`, and renders children in order.                                                                                                                                                                                                                                                             | Current source and tests |
+| FR2 | The group supplies its `size`, `shape`, numeric size, and an overlap of a quarter of the numeric size, rounded, to every Avatar and AvatarGroupOverflow below it in the same layer (`spec:AST-038` FR7, FR8; a member in a hover card, popover, or other layer keeps its own size and shape, though a marked member there stays in the FR4 roving set); a member's own size and shape never win, including when the group uses its defaults.                                                                                      | Current source and tests |
+| FR3 | Every member takes the negative overlap as its inline-start margin, including the first; the group pads its inline start by the same amount so the first member stays inside it, and an empty group has no start padding. The overlap holds when members are wrapped in a HoverCard or Tooltip.                                                                                                                                                                                                                                   | Current source and tests |
+| FR4 | Elements carrying `data-avatar-item` — link and button avatars and a clickable overflow indicator — form one horizontal roving set with a single tab stop: arrow keys move between them following the rendered direction and wrap at the ends, and Home and End jump to the first and last. Other focusable content in a member, such as a button in a status slot, is not in the set.                                                                                                                                            | Current source and tests |
+| FR5 | The hint and tab stop follow whether any member carries the item marker as read at the group's own last render: while one does, a visually hidden translated hint ("Use arrow keys to move between avatars") renders inside the group and is appended to `aria-describedby` after any caller value; a purely static group has no tab stop and no hint. Implementation gap: a member that gains or loses the marker through its own state, without the group rendering, leaves the hint and tab stop stale (Current-state impact). | Current source and tests |
+| FR6 | `ref` reaches the root. Supported DOM, ARIA, data, and event props reach the root; the component's role, name, description, and `data-testid` apply after them; caller `onKeyDown` and `onFocus` run before the roving handlers, and one that calls `preventDefault()` skips the roving handler for that event (`architecture:public-component-api` INV7); `xstyle`, `className`, and `style` merge in that order after component styles.                                                                                         | Current source and tests |
+
+### Allowed variation
+
+- **AV1 — Theme paint.** A theme may restyle `avatar-group` per `size` and
+  `shape` without changing membership, overlap ownership, or focus behavior.
+- **AV2 — Membership.** The number and kind of members vary per callsite.
+
+### Representative states
+
+| State                | Required invariant                                                         | Allowed variation |
+| -------------------- | -------------------------------------------------------------------------- | ----------------- |
+| Static group         | Named group; no tab stop; no hint.                                         | Members.          |
+| Interactive group    | One member has `tabIndex={0}`, the rest `-1`; arrows rove; hint described. | Members.          |
+| With overflow button | The overflow indicator is the last roving item.                            | Count.            |
+| Empty group          | Renders with no start padding.                                             | —                 |
+| Right-to-left        | Overlap and arrow movement follow the rendered direction.                  | —                 |
+
+### Transformation and precedence order
+
+- **ORD1 — Member size and shape.** Group value → member's own prop (ignored
+  inside a group).
+- **ORD2 — Description.** Caller `aria-describedby` → keyboard hint id.
+- **ORD3 — Key and focus handling.** Caller `onKeyDown` or `onFocus` → roving
+  handler; a caller handler that calls `preventDefault()` skips the roving
+  handler for that event.
+
+### Performance and resources
+
+- **PR1 — Member detection.** Detecting interactive members adds no observer or
+  listener; the group re-reads its members after each of its own renders, and a change in
+  whether any member is interactive re-renders the group before paint.
+
+## Accessibility contract
+
+- **AR1 — Named group.** The root is `role="group"` with a translated default
+  name the caller can replace.
+- **AR2 — One tab stop.** Interactive members share a single tab stop and are
+  reached with arrow keys, Home, and End, in visual order in both directions,
+  as read at the group's own last render (FR5 gap for member-local changes).
+- **AR3 — Keyboard hint.** The hint describes the group only while roving
+  applies, as read at the group's own last render (FR5 gap for member-local
+  changes).
+- **AR4 — Static members.** Static avatars are not roving items and have no tab
+  stop inside a group; `component:Avatar` records the effect on their tooltips.
+
+## Design relationships
+
+| Anatomy or state   | Design requirement                              | Representation authority | Hierarchy role | Component contract |
+| ------------------ | ----------------------------------------------- | ------------------------ | -------------- | ------------------ |
+| Avatar children    | Uniformly sized members overlapping in one row. | Current source and docs  | Prominent      | FR1–FR3            |
+| Overflow indicator | An optional "+N" member at the end of the row.  | Current source and docs  | Supporting     | FR2, FR4           |
+
+Theming: the root is the `avatar-group` target. Members keep their own targets;
+the overflow indicator's `avatar-group-overflow` target belongs to
+`component:AvatarGroupOverflow`. The consumer anatomy names no root part, so no
+anatomy-theming block is declared.
+
+## Family and system relationships
+
+- `component:Avatar` reads the group context and applies the ring, overlap, and
+  item marker on its own root.
+- `component:AvatarGroupOverflow` reads the same context and joins the roving
+  set when clickable.
+- `architecture:internationalization` owns the catalog behind the group name
+  and hint.
+
+## Verification map
+
+| Contract       | Verification                                                                                                                                     | Representative states                                             | Mutation or failure expectation                                                                                                                                                                                                                 | Audit section                |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
+| FR1, AR1       | `AvatarGroup.test.tsx` render, label, size-reflection, test-id, and empty-group tests                                                            | Default and custom `aria-label`; sizes; empty                     | A missing `group` role, default or custom name, `data-size` reflection, or child fails. Gap: no test asserts the inline-flex centering, `data-shape`, child order, a caller `aria-labelledby`, or a caller `role` being replaced.               | `audit:AvatarGroup/a11y`     |
+| FR2, ORD1      | `AvatarGroup.test.tsx` size-cascade and overlap suites; `Avatar.test.tsx` group shape tests; `AvatarGroupOverflow.test.tsx` size and shape tests | Group size and shape, defaults, outside a group; `md` overlap     | A member's own size or shape winning inside the group, or a wrong `md` overlap value, fails. Gap: no test asserts the overlap value for sizes other than `md`, or that a member in another layer keeps its own size and shape.                  | `audit:AvatarGroup/behavior` |
+| FR3            | `AvatarGroup.test.tsx` overlap suite                                                                                                             | Plain and wrapped members, overflow indicator, empty group        | A missing member margin, a missing start padding, or start padding on an empty group fails.                                                                                                                                                     | `audit:AvatarGroup/layout`   |
+| FR3 (layout)   | `AvatarGroup.stories.tsx` sizes; `AvatarGroupOverflow.stories.tsx` AllShapes                                                                     | Sizes and shapes, LTR and RTL                                     | Gap: no automated check; a clipped first member or an unmirrored overlap is visible only in the rendered fixtures.                                                                                                                              | `audit:AvatarGroup/layout`   |
+| FR4, AR2, AR4  | `AvatarGroup.test.tsx` roving-focus suite                                                                                                        | Interactive avatars, overflow button, status button, static group | More than one tab stop, lost ArrowRight/ArrowLeft movement, a missing overflow item, a status button in the set, or a tab stop on a static group fails. Gap: wrapping, Home and End, and right-to-left arrow direction have no automated check. | `audit:AvatarGroup/a11y`     |
+| FR5, AR3, ORD2 | `AvatarGroup.test.tsx` hint tests                                                                                                                | Interactive and static groups                                     | A missing hint on an interactive group, or a hint on a static one, fails. Gap: no test covers the hint's order after a caller `aria-describedby` or a member changing interactivity through its own state.                                      | `audit:AvatarGroup/a11y`     |
+| FR6, ORD3      | `AvatarGroup.test.tsx` test-id test                                                                                                              | Caller `data-testid`                                              | A lost test id fails. Gap: no test covers the ref, DOM passthrough, attribute order, caller handler order and cancellation, or the styling-input merge.                                                                                         | `audit:AvatarGroup/api`      |
+| PR1            | Source review                                                                                                                                    | Interactive and static groups                                     | Gap: no automated check fails if member detection adds an observer or listener.                                                                                                                                                                 | `audit:AvatarGroup/behavior` |
+| AR1, AR3       | Accessibility-tree evidence (`spec:AST-009` FR3)                                                                                                 | Static and interactive groups                                     | Gap: no accessibility-tree check proves the group role, name, or description; the unit tests query the DOM.                                                                                                                                     | `audit:AvatarGroup/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.