@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/Badge/Badge.spec.md

@@ -0,0 +1,207 @@
+---
+schema_version: 3
+template_version: 7
+kind: component
+id: component:Badge
+authority: current
+archive_reason: null
+superseded_by: null
+approved_by: cixzhang
+approved_at: 2026-10-24
+owners: [cixzhang]
+review_triggers: [public-api, behavior, layout, theming, accessibility]
+verified_by:
+  [
+    packages/core/src/Badge/Badge.test.tsx,
+    packages/core/src/serverSafeComponents.test.ts,
+    packages/core/src/theme/themingTargets.test.ts,
+    packages/core/src/theme/extensibleAxes.test.ts,
+    apps/storybook/stories/Badge.stories.tsx,
+  ]
+modules: []
+families: []
+design_specs: []
+architecture:
+  [architecture:component-theming-surface, architecture:public-component-api]
+contributing: []
+system_specs: []
+---
+
+# Badge component contract
+
+## Contract at a glance
+
+| Area                    | Contract                                                                                                                                                                                          |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract         | A read-only, one-line label with a required `label`, an optional leading `icon`, and a theme-extensible `variant` (default `neutral`).                                                            |
+| Behavior                | The badge never wraps; a label wider than the available space is cut with an ellipsis inside the badge, and a string or number label is also carried in the root's `title`.                       |
+| End-user impact         | Readers see a compact status or category label that stays inside its container; assistive technology reads the full label text.                                                                   |
+| 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 badge that wraps or escapes its container, a `title` derived from a rich label, a badge that adds its own role, tab stop, or live region, or a variant that is not reflected on `badge`. |
+| Governing rules         | `architecture:public-component-api/INV5,INV6,INV8`; `architecture:component-theming-surface/INV2,INV6,INV14`.                                                                                     |
+
+This table is a review projection; the body below is authoritative.
+
+## Intent
+
+Badge marks one status or category with a short, non-interactive label. It owns
+the label's one-line geometry, its overflow treatment, and the closed set of
+built-in tones that a theme can extend.
+
+## 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; Badge holds no state
+- Migration decision: none
+
+Consumer migration instructions belong in consumer docs and release notes.
+
+## Current-state impact
+
+- **Clipped label tail is pointer-only (AR4).** Keyboard and touch users cannot
+  reveal the clipped tail of a long label; only a pointer hover on the native
+  `title` shows it. Assistive technology still receives the full text from the
+  DOM.
+
+## Ownership boundary
+
+**Owns**
+
+- The badge root, its optional leading Icon slot, and the Label container.
+- One-line geometry, inline padding, radius, typography, and the ellipsis
+  overflow treatment.
+- The built-in `variant` tones and the reflection of `variant` on the `badge`
+  theming target.
+- Deriving the root `title` from a string or number label.
+
+**Does not own / non-goals**
+
+- Which status or category a product shows, its wording, and whether a badge is
+  appropriate — owned by the product callsite and consumer guidance in
+  `Badge.doc.mjs`.
+- The supplied icon's artwork, size, and accessibility exposure — owned by the
+  supplied node (`component:Icon` when an Icon is passed).
+- Tag-like and dot-only status presentations — owned by
+  `component:Token` and `component:StatusDot`.
+- Contrast of the color tokens each tone uses — owned by the active theme.
+
+## Public concepts
+
+| Concept          | Closed values or states                                                                                                                                          | Meaning                                               | Availability by variant/orientation/state | Default   | Owner             | Stability | Invalid-value behavior                                                                                                             |
+| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | ----------------------------------------- | --------- | ----------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| Tone (`variant`) | Semantic: `neutral`, `info`, `success`, `warning`, `error`; color: `blue`, `cyan`, `green`, `orange`, `pink`, `purple`, `red`, `teal`, `yellow`; theme additions | Selects the badge fill and text color.                | All badges                                | `neutral` | `component:Badge` | Stable    | A theme-added value is reflected on `badge` and receives no component fill or color (FR6); TypeScript rejects unregistered values. |
+| Label            | string, number, or rich node                                                                                                                                     | The visible badge content.                            | Always rendered; required                 | Required  | `component:Badge` | Stable    | An empty string renders an empty label and no `title`.                                                                             |
+| Icon             | present; absent                                                                                                                                                  | Optional caller-supplied node shown before the label. | All badges                                | absent    | `component:Badge` | Stable    | Absent renders no icon and no placeholder.                                                                                         |
+
+## Behavioral and layout contract
+
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                        | Basis                                   |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
+| FR1 | Badge renders one inline-flex `span` root, centered on both axes, with block size `--spacing-5` (at least that size once it grows with a set text size under `spec:AST-102` FR4; today's fixed size is a gap), no block padding, inline padding `--spacing-2`, `--radius-full` corners, inherited font family, `--text-supporting-size` and `--text-supporting-leading` type, and `--font-weight-medium` weight. | Current source                          |
+| FR2 | When `icon` is supplied it renders directly inside the root, before the Label container, separated by `--spacing-1`; the label always renders inside its own Label container.                                                                                                                                                                                                                                    | Current source and tests                |
+| FR3 | The badge is one line and never wraps. The root is capped at the inline size of its container and may shrink below its content size; a label that does not fit is clipped with a trailing ellipsis inside the Label container and does not escape the badge.                                                                                                                                                     | Current source and consumer docs        |
+| FR4 | A non-empty string label or any number label sets the root `title` to the label text, whether or not the label is clipped. A rich-node or empty-string label sets no `title`.                                                                                                                                                                                                                                    | Current source and tests                |
+| FR5 | `variant` defaults to `neutral`. `neutral` paints `--color-neutral` with primary text; `info`, `success`, `warning`, and `error` paint their strong status fills (`--color-<status>`) with their matching `--color-on-<status>` text and keep a `CanvasText` outline in forced colors; each color variant paints its tinted background with its matching colored text.                                           | Current source and consumer docs        |
+| FR6 | The `badge` target carries the resolved `variant` for every value, including a value a theme adds through `BadgeVariantMap`. A theme-added value receives no component fill or text color, so it renders the FR1 geometry over a transparent background in the inherited text color until a theme paints it.                                                                                                     | Current source and extensible-axis test |
+| FR7 | `ref` reaches the root `span`. Supported DOM, ARIA, data, and event props reach the root; `xstyle`, `className`, and `style` merge in that order after the component styles.                                                                                                                                                                                                                                     | Current source and tests                |
+| FR8 | Badge uses no hooks, measurement, or client-only API, so it renders identically on the server and the client.                                                                                                                                                                                                                                                                                                    | Current source and server-safety test   |
+
+### Allowed variation
+
+- **AV1 — Theme paint.** A theme may change any visual property of `badge`,
+  including per-`variant` fill, text color, height, and radius, without changing
+  anatomy, the one-line rule, or the `title` rule.
+- **AV2 — Label content.** Label length and content may vary; clipping position
+  depends on the available inline size.
+
+### Representative states
+
+| State               | Required invariant                                                        | Allowed variation                |
+| ------------------- | ------------------------------------------------------------------------- | -------------------------------- |
+| Default             | Neutral tone, one line, `title` equal to the string label.                | Label text.                      |
+| With icon           | Icon renders before the Label container on the inline-start side.         | Icon artwork and size.           |
+| Count               | A number label renders as text and sets `title` to its string form.       | Tone.                            |
+| Long label, narrow  | The badge stays within its container and the label ends in an ellipsis.   | Clip position.                   |
+| Rich label          | The node renders inside the Label container and no `title` is set.        | Node content.                    |
+| Theme-added variant | `data-variant` names the added value; no component fill or color applies. | Theme paint for the added value. |
+
+### Transformation and precedence order
+
+- **ORD1 — Root attributes.** Component class and `data-variant` → component
+  styles → `xstyle` → `className` → `style` → derived `title` → remaining
+  caller props.
+- **ORD2 — Content order.** Icon, then Label container, in logical inline
+  order.
+
+### Performance and resources
+
+- **PR1 — Static render.** Badge registers no listener, observer, timer, or
+  effect and performs no layout measurement.
+
+## Accessibility contract
+
+- **AR1 — Static text.** Badge adds no role, tab stop, or live region of its
+  own and exposes its label as ordinary text in reading order, so a changed
+  label is not announced. A caller `role` or `tabIndex` passes through (FR7).
+- **AR2 — Meaning in text.** Badge renders `label` as text, and tone color
+  supplements that text. An empty label renders a color-only badge with nothing
+  in the accessibility tree; supplying a meaningful label is the callsite's
+  responsibility.
+- **AR3 — Icon exposure is delegated.** Badge adds no name, role, or
+  `aria-hidden` to the supplied icon; its exposure is the supplied node's own
+  (an Icon without a label is decorative under `component:Icon`).
+- **AR4 — Full text stays in the DOM.** Clipping is visual only: the complete
+  label remains in the accessibility tree, and the FR4 `title` exposes it to
+  pointer hover. Implementation gap: keyboard and touch users have no way to
+  reveal a clipped tail.
+
+## Design relationships
+
+| Anatomy or state | Design requirement                                             | Representation authority | Hierarchy role | Component contract |
+| ---------------- | -------------------------------------------------------------- | ------------------------ | -------------- | ------------------ |
+| Badge root       | A compact one-line pill whose tone signals status or category. | Current source           | Supporting     | FR1, FR3, FR5, FR6 |
+| Icon             | An optional leading glyph that helps identify the badge type.  | Current source and docs  | Supporting     | FR2, AR3           |
+| Label            | The text or number that carries the badge's meaning.           | Current source and docs  | Prominent      | FR3, FR4, AR2, AR4 |
+
+Theming: the root is the single `badge` target and reflects `variant`. The Label
+container and the Icon slot add no targets: the label inherits `badge`, and a
+supplied icon keeps its own styling and inherits the badge text color.
+
+## Family and system relationships
+
+- `architecture:public-component-api` owns ref, passthrough, and styling-input
+  rules; FR7 applies them to the root `span`.
+- `architecture:component-theming-surface` owns target qualification, state
+  reflection, and extensible-axis rules; FR6 records Badge's extensible
+  `variant` axis and its unthemed fallback.
+
+## Verification map
+
+| Contract | Verification                                                                                  | Representative states                                  | Mutation or failure expectation                                                                                                                                                                             | Audit section          |
+| -------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
+| FR2, FR7 | `Badge.test.tsx`                                                                              | Icon, ref, passthrough                                 | Dropping the icon, the ref, or a passthrough prop fails DOM assertions. Gap: the icon-before-label order is untested.                                                                                       | `audit:Badge/behavior` |
+| AR1–AR3  | Source review                                                                                 | Default, with icon                                     | Gap: no automated check fails if Badge adds its own role, tab stop, live region, or icon semantics.                                                                                                         | `audit:Badge/a11y`     |
+| FR5      | `Badge.test.tsx` `data-variant` assertions; `Badge.stories.tsx` variant fixtures in a browser | `success` and `purple` reflection; every tone rendered | A lost `data-variant` for those tones fails. Gap: no automated check covers the `neutral` default's reflection or any tone's paint; a paint change is visible only in the rendered fixtures.                | `audit:Badge/theming`  |
+| FR4, AR4 | `Badge.test.tsx` full-label suite                                                             | String, number, rich, and empty labels                 | Setting `title` from a rich or empty label, or dropping it for a string or number, fails. Gap: no check asserts that a clipped label stays whole in the accessibility tree.                                 | `audit:Badge/a11y`     |
+| FR1, FR3 | `Badge.stories.tsx` long-label fixture in a browser                                           | Long labels in tight space                             | A label that wraps or escapes the badge is visible in the rendered fixture.                                                                                                                                 | `audit:Badge/layout`   |
+| FR6      | `extensibleAxes.test.ts`, `themingTargets.test.ts`                                            | `BadgeVariantMap`, `badge` target                      | Removing `variant` from the target reflection or the doc's `visualProps` fails the structural checks. Gap: no test renders a theme-added value, so the unthemed fallback is verified by source review only. | `audit:Badge/theming`  |
+| FR8, PR1 | `serverSafeComponents.test.ts`                                                                | Import graph                                           | Adding a hook or a client-only import to Badge fails the server-safety invariant.                                                                                                                           | `audit:Badge/behavior` |
+
+## Decision log
+
+None recorded. The record describes shipped behavior.
+
+## Open questions
+
+- **OQ1 — How should the full text of a clipped label reach keyboard and touch
+  users?** (`human-design`) Options include a measured tooltip shown only when
+  the label is clipped, which makes Badge a client component and focusable
+  while clipped, or leaving recovery to the callsite.
+
+## Content boundary
+
+This file does not duplicate consumer prop tables/examples, current audit
+results, implementation steps, or family/system rules. It links to their owners.

package/src/Badge/Badge.test.tsx

@@ -3,6 +3,7 @@
 import {describe, it, expect} from 'vitest';
 import {render, screen} from '@testing-library/react';
 import {Badge} from './Badge';
+import {getForcedColorsRules} from '../__tests__/forcedColors';
 
 describe('Badge', () => {
   it('renders with default variant', () => {
@@ -110,3 +111,15 @@ describe('Badge', () => {
     expect(root).toHaveAttribute('data-variant', 'success');
   });
 });
+
+// jsdom cannot emulate forced colors, so this asserts the compiled rule the
+// status fill relies on (architecture:theme-tokens INV11): the fill becomes
+// Canvas, and a CanvasText boundary keeps its shape.
+describe('Badge forced colors', () => {
+  it('keeps a visible boundary on the status fill', () => {
+    render(<Badge variant="error" label="Failed" />);
+    const css = getForcedColorsRules();
+    expect(css).toContain('outline-style: solid;');
+    expect(css).toContain('outline-color: canvastext;');
+  });
+});

package/src/Badge/Badge.tsx

@@ -78,20 +78,56 @@ const variants = stylex.create({
     color: colorVars['--color-text-primary'],
   },
   info: {
-    backgroundColor: colorVars['--color-accent'],
-    color: colorVars['--color-on-accent'],
+    backgroundColor: colorVars['--color-info'],
+    color: colorVars['--color-on-info'],
+    // Forced colors replace status fills with Canvas; this boundary keeps the
+    // fill's shape visible (architecture:theme-tokens INV11).
+    outlineWidth: {default: null, '@media (forced-colors: active)': '1px'},
+    outlineStyle: {default: null, '@media (forced-colors: active)': 'solid'},
+    outlineColor: {
+      default: null,
+      '@media (forced-colors: active)': 'CanvasText',
+    },
+    outlineOffset: {default: null, '@media (forced-colors: active)': '-1px'},
   },
   success: {
     backgroundColor: colorVars['--color-success'],
     color: colorVars['--color-on-success'],
+    // Forced colors replace status fills with Canvas; this boundary keeps the
+    // fill's shape visible (architecture:theme-tokens INV11).
+    outlineWidth: {default: null, '@media (forced-colors: active)': '1px'},
+    outlineStyle: {default: null, '@media (forced-colors: active)': 'solid'},
+    outlineColor: {
+      default: null,
+      '@media (forced-colors: active)': 'CanvasText',
+    },
+    outlineOffset: {default: null, '@media (forced-colors: active)': '-1px'},
   },
   warning: {
     backgroundColor: colorVars['--color-warning'],
     color: colorVars['--color-on-warning'],
+    // Forced colors replace status fills with Canvas; this boundary keeps the
+    // fill's shape visible (architecture:theme-tokens INV11).
+    outlineWidth: {default: null, '@media (forced-colors: active)': '1px'},
+    outlineStyle: {default: null, '@media (forced-colors: active)': 'solid'},
+    outlineColor: {
+      default: null,
+      '@media (forced-colors: active)': 'CanvasText',
+    },
+    outlineOffset: {default: null, '@media (forced-colors: active)': '-1px'},
   },
   error: {
     backgroundColor: colorVars['--color-error'],
     color: colorVars['--color-on-error'],
+    // Forced colors replace status fills with Canvas; this boundary keeps the
+    // fill's shape visible (architecture:theme-tokens INV11).
+    outlineWidth: {default: null, '@media (forced-colors: active)': '1px'},
+    outlineStyle: {default: null, '@media (forced-colors: active)': 'solid'},
+    outlineColor: {
+      default: null,
+      '@media (forced-colors: active)': 'CanvasText',
+    },
+    outlineOffset: {default: null, '@media (forced-colors: active)': '-1px'},
   },
   // Non-semantic color variants — tinted backgrounds with colored text
   blue: {

package/src/Banner/Banner.spec.md

@@ -40,7 +40,7 @@ separately targetable surface. The status and content targets remain unchanged.
 ## Compatibility and migration
 
 - Released default preserved: `no` — Banner no longer derives a live-region role from visual status
-- Compatibility class: breaking accessibility-semantic correction; visual output, DOM structure, props, theming targets, and interaction behavior are unchanged
+- Compatibility class: breaking accessibility-semantic correction for the live-region change (DEP-0007), whose visual output, DOM structure, props, theming targets, and interaction behavior are unchanged. FR9 is a visual change: the Info status surface fills with `--color-info-muted` and built-in content takes the on-muted roles; props, DOM structure, and theming targets stay the same
 - Controlled/uncontrolled behavior: unchanged
 - Migration decision: announce async outcomes in their transition handler with `useAnnounce`; add an explicit `role="status"` only for a persistent semantic mirror, and reserve `role="alert"` for genuinely urgent interruption. Inside a mounted live container, `spec:AST-086` FR4 applies instead.
 
@@ -84,10 +84,16 @@ Consumer migration instructions belong in consumer docs and release notes.
 - The optional content surface below it.
 - The Banner frame that groups both surfaces and carries the current whole-banner
   elevation and elevated-card silhouette.
+- The semantic foreground context for Banner-authored title, description, icon,
+  collapse, and dismiss content on the status surface.
+  Built-in controls receive that context on their Button element only, so their
+  tooltip remains an ordinary Button surface.
 
 **Does not own / non-goals**
 
-- Painting for action and dismiss controls — delegated to `component:Button`.
+- Button geometry, interaction layers, tooltip painting, or consumer-supplied
+  `endContent` — delegated to `component:Button`. An action row of two or more
+  actions follows `family:action-groups`.
 - A new theme property, prop, variant, or DOM element.
 
 ## Public concepts
@@ -105,16 +111,17 @@ prop vocabulary or extensibility rule changes.
 The requirements below describe the current implementation and its additive
 frame target contract.
 
-| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Basis                                                  | Contract state           |
-| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ------------------------ |
-| FR1 | The current render places `banner` on the colored status surface, which is Banner's primary painted surface and reflects `container` and `status`.                                                                                                                                                                                                                                                                                                                            | Current source, public docs, and tests                 | Current behavior         |
-| FR2 | The Banner frame receives the public ref, role, supported DOM props, `xstyle`, `className`, and `style`; it also paints the selected `boxShadow`.                                                                                                                                                                                                                                                                                                                             | Current source and tests                               | Current behavior         |
-| FR3 | An elevated `card` frame also paints the whole-banner radius. A `section` frame remains square. A non-elevated frame does not receive the frame-radius style.                                                                                                                                                                                                                                                                                                                 | Current source and elevation tests                     | Current behavior         |
-| FR4 | Card shape is split across surface owners: the status surface owns all corners without visible content or the top corners with visible content; the content surface owns the bottom corners.                                                                                                                                                                                                                                                                                  | Current source                                         | Current behavior         |
-| FR5 | Theme-authored `borderRadius` on `banner` currently writes the private `--_banner-radius` variable on the Status surface only. CSS inheritance does not carry that value upward to the frame or sideways to the Content surface, so both keep their fallback radius.                                                                                                                                                                                                          | Current compiler output and CSS inheritance            | Current reachability gap |
-| FR6 | The Banner frame exposes `banner-frame` and reflects `container` and `elevation`. The existing `banner` target remains on the Status surface rather than moving to the outermost DOM element.                                                                                                                                                                                                                                                                                 | Owner decision; current source and tests               | Current behavior         |
-| FR7 | `banner-frame` is additive. The existing `banner`, `banner-icon`, `banner-description`, and `banner-content` targets and their current axes remain unchanged.                                                                                                                                                                                                                                                                                                                 | Current target inventory; compatibility policy         | Current behavior         |
-| FR8 | `status` controls visual meaning only and MUST NOT derive `role`, `aria-live`, or an announcement. Standard DOM props MAY provide an explicit persistent role, except on a Banner added inside a mounted live container (`spec:AST-086` FR4). Async outcomes MUST announce from the transition handler through `useAnnounce`, except inside a mounted live container, where `spec:AST-086` FR4 applies; `role="alert"` is reserved for genuinely urgent interruptive content. | Accessibility Checklist §Announcements; owner decision | Current behavior         |
+| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Basis                                                    | Contract state           |
+| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | ------------------------ |
+| FR1 | The current render places `banner` on the colored status surface, which is Banner's primary painted surface and reflects `container` and `status`.                                                                                                                                                                                                                                                                                                                                                   | Current source, public docs, and tests                   | Current behavior         |
+| FR2 | The Banner frame receives the public ref, role, supported DOM props, `xstyle`, `className`, and `style`; it also paints the selected `boxShadow`.                                                                                                                                                                                                                                                                                                                                                    | Current source and tests                                 | Current behavior         |
+| FR3 | An elevated `card` frame also paints the whole-banner radius. A `section` frame remains square. A non-elevated frame does not receive the frame-radius style.                                                                                                                                                                                                                                                                                                                                        | Current source and elevation tests                       | Current behavior         |
+| FR4 | Card shape is split across surface owners: the status surface owns all corners without visible content or the top corners with visible content; the content surface owns the bottom corners.                                                                                                                                                                                                                                                                                                         | Current source                                           | Current behavior         |
+| FR5 | Theme-authored `borderRadius` on `banner` currently writes the private `--_banner-radius` variable on the Status surface only. CSS inheritance does not carry that value upward to the frame or sideways to the Content surface, so both keep their fallback radius.                                                                                                                                                                                                                                 | Current compiler output and CSS inheritance              | Current reachability gap |
+| FR6 | The Banner frame exposes `banner-frame` and reflects `container` and `elevation`. The existing `banner` target remains on the Status surface rather than moving to the outermost DOM element.                                                                                                                                                                                                                                                                                                        | Owner decision; current source and tests                 | Current behavior         |
+| FR7 | `banner-frame` is additive. The existing `banner`, `banner-icon`, `banner-description`, and `banner-content` targets and their current axes remain unchanged.                                                                                                                                                                                                                                                                                                                                        | Current target inventory; compatibility policy           | Current behavior         |
+| FR8 | `status` controls visual meaning only and MUST NOT derive `role`, `aria-live`, or an announcement. Standard DOM props MAY provide an explicit persistent role, except on a Banner added inside a mounted live container (`spec:AST-086` FR4). Async outcomes MUST announce from the transition handler through `useAnnounce`, except inside a mounted live container, where `spec:AST-086` FR4 applies; `role="alert"` is reserved for genuinely urgent interruptive content.                        | Accessibility Checklist §Announcements; owner decision   | Current behavior         |
+| FR9 | The status surface fills with the matching `--color-<status>-muted` role (`--color-info-muted` for Info) and paints its built-in title, description, icon, collapse, and dismiss content with the matching `--color-on-<status>-muted` role. Banner supplies that semantic foreground context to each built-in Button element without changing Button-owned geometry or interaction layers; a sibling tooltip keeps Button's ordinary theme color. Consumer-provided `endContent` remains untouched. | Status-role architecture; Banner and Button source/tests | Current behavior         |
 
 ### Allowed variation
 
@@ -147,7 +154,8 @@ frame target contract.
 ### Performance and resources
 
 This contract introduces no new measurement, observer, listener, render pass, or
-runtime work.
+runtime work beyond the press tracking `family:action-groups` FR5 gives an
+action row of two or more actions.
 
 ## Accessibility contract
 
@@ -169,12 +177,12 @@ unchanged.
 
 ## Design relationships
 
-| Anatomy or state        | Design requirement                                                                                 | Representation authority       | Hierarchy role | Component contract |
-| ----------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------ | -------------- | ------------------ |
-| Banner frame            | Groups the status and optional content surfaces and carries their shared silhouette and elevation. | Current source and public docs | Supporting     | FR2, FR3, FR4      |
-| Status surface          | Acts as Banner's primary painted surface, carrying the status fill, message, and controls.         | Current source and public docs | Prominent      | FR1                |
-| Content surface         | Carries optional supporting detail below the status surface.                                       | Current source and public docs | Supporting     | FR4, FR7           |
-| Action/dismiss controls | Keep their own Button painting and target ownership.                                               | Current composition            | Supporting     | FR7                |
+| Anatomy or state        | Design requirement                                                                                                                                                                                  | Representation authority                      | Hierarchy role | Component contract |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | -------------- | ------------------ |
+| Banner frame            | Groups the status and optional content surfaces and carries their shared silhouette and elevation.                                                                                                  | Current source and public docs                | Supporting     | FR2, FR3, FR4      |
+| Status surface          | Acts as Banner's primary painted surface, carrying the status fill, message, and controls.                                                                                                          | Current source and public docs                | Prominent      | FR1                |
+| Content surface         | Carries optional supporting detail below the status surface.                                                                                                                                        | Current source and public docs                | Supporting     | FR4, FR7           |
+| Action/dismiss controls | Built-in control content receives the Status surface's on-muted foreground on the Button element; interaction layers and tooltips remain Button-owned. Consumer-supplied `endContent` is unchanged. | Banner status context plus `component:Button` | Supporting     | FR7, FR9           |
 
 The Banner frame is stable anatomy and owns the additive `banner-frame` target.
 The Status surface remains Banner's primary painted surface and keeps the
@@ -203,7 +211,11 @@ unqualified `banner` target.
 
 This map records runtime reachability. `banner` belongs to the primary Status
 surface rather than the outermost DOM element, while `banner-frame` belongs to
-the visible frame that owns whole-banner elevation and silhouette.
+the visible frame that owns whole-banner elevation and silhouette. Delegation to
+Button preserves each built-in control's anatomy and interaction ownership.
+Banner supplies only the status-surface foreground
+context on the Button element, and it does not restyle a consumer-provided
+`endContent` child.
 
 ## Family and system relationships
 
@@ -216,14 +228,15 @@ the visible frame that owns whole-banner elevation and silhouette.
 
 ## Verification map
 
-| Contract            | Verification                                                   | Representative states                                               | Mutation or failure expectation                                                                                                         | Audit section           |
-| ------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
-| FR1, FR7            | `Banner.test.tsx` and `themingTargets.test.ts`                 | Status surface, content surface, current target axes                | Moving, removing, or changing an existing target breaks current assertions.                                                             | `audit:Banner/theming`  |
-| FR2, FR3, FR4       | `Banner.test.tsx` plus current source inspection               | Flat/elevated card and elevated section                             | Frame, status surface, content surface, shadow, or radius ownership changes from the recorded state.                                    | `audit:Banner/surfaces` |
-| FR5                 | Compiler output plus browser/computed-style evidence           | Card with and without content; elevated card                        | `banner.borderRadius` unexpectedly reaches the frame/content, or docs claim that the current route already does.                        | `audit:Banner/radius`   |
-| FR6, FR7            | Implementation PR target, compiler, probe, and component tests | Card/section across none, low, med, and high elevation              | `banner-frame` is absent, uses another name, misses an axis, or moves the existing `banner` target.                                     | `audit:Banner/theming`  |
-| FR8                 | `Banner.test.tsx`, consumer docs, Accessibility Checklist A6   | Default info/success/warning/error; explicit status and alert roles | A visual status creates a live region, an explicit role is dropped, or docs tell builders to announce by conditionally mounting Banner. | `audit:Banner/a11y`     |
-| Theming anatomy map | `scripts/check-knowledge.mjs`                                  | Eight anatomy entries and five current targets                      | Missing, extra, prefixed, stale, or unclaimed current mappings fail validation.                                                         | `audit:Banner/theming`  |
+| Contract            | Verification                                                            | Representative states                                               | Mutation or failure expectation                                                                                                                  | Audit section           |
+| ------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------- |
+| FR1, FR7            | `Banner.test.tsx` and `themingTargets.test.ts`                          | Status surface, content surface, current target axes                | Moving, removing, or changing an existing target breaks current assertions.                                                                      | `audit:Banner/theming`  |
+| FR2, FR3, FR4       | `Banner.test.tsx` plus current source inspection                        | Flat/elevated card and elevated section                             | Frame, status surface, content surface, shadow, or radius ownership changes from the recorded state.                                             | `audit:Banner/surfaces` |
+| FR5                 | Compiler output plus browser/computed-style evidence                    | Card with and without content; elevated card                        | `banner.borderRadius` unexpectedly reaches the frame/content, or docs claim that the current route already does.                                 | `audit:Banner/radius`   |
+| FR6, FR7            | Implementation PR target, compiler, probe, and component tests          | Card/section across none, low, med, and high elevation              | `banner-frame` is absent, uses another name, misses an axis, or moves the existing `banner` target.                                              | `audit:Banner/theming`  |
+| FR8                 | `Banner.test.tsx`, consumer docs, Accessibility Checklist A6            | Default info/success/warning/error; explicit status and alert roles | A visual status creates a live region, an explicit role is dropped, or docs tell builders to announce by conditionally mounting Banner.          | `audit:Banner/a11y`     |
+| FR9                 | `Banner.test.tsx` plus Button tooltip and custom-end-content assertions | Four statuses; built-in collapse/dismiss; tooltip; consumer action  | Built-in content loses the matching on-muted role, a tooltip is repainted, Button interaction ownership changes, or consumer content is mutated. | `audit:Banner/theming`  |
+| Theming anatomy map | `scripts/check-knowledge.mjs`                                           | Eight anatomy entries and five current targets                      | Missing, extra, prefixed, stale, or unclaimed current mappings fail validation.                                                                  | `audit:Banner/theming`  |
 
 ## Decision log
 

package/src/Banner/Banner.test.tsx

@@ -4,9 +4,10 @@
  * @file Banner.test.tsx
  * @input Uses vitest, @testing-library/react, Banner component
  * @output Unit tests for Banner component behavior, including default and
- *   explicit live-region roles, the 'banner-frame' theme target on the outer
- *   elevation/radius painter, and the 'banner-icon' theme target on the status
- *   icon glyph (#4166)
+ *   explicit live-region roles, augmented-status color fallback, scoped status
+ *   foregrounds that do not recolor consumer content or tooltips, the
+ *   'banner-frame' theme target on the outer elevation/radius painter, and the
+ *   'banner-icon' theme target on the status icon glyph (#4166)
  * @position Testing; validates Banner.tsx implementation
  *
  * SYNC: When modified, update this header
@@ -15,10 +16,11 @@
 import {describe, it, expect, vi, afterEach} from 'vitest';
 import {render, screen} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
-import {Banner} from './Banner';
+import {Banner, type BannerStatus} from './Banner';
 import {defineTheme, generateThemeCSS} from '../theme';
 import {registerIcons, resetIcons} from '../Icon';
 import {InternationalizationProvider} from '../i18n';
+import {getForcedColorsRules} from '../__tests__/forcedColors';
 
 describe('Banner', () => {
   afterEach(() => {
@@ -101,6 +103,71 @@ describe('Banner', () => {
     expect(screen.queryByText('This is a description')).not.toBeInTheDocument();
   });
 
+  it('keeps base title and description colors for an augmented status', () => {
+    const augmentedStatus = 'neutral' as unknown as BannerStatus;
+    const {rerender} = render(
+      <Banner
+        status={augmentedStatus}
+        title="Neutral title"
+        description="Neutral description"
+      />,
+    );
+
+    const customTitleClass = screen.getByText('Neutral title').className;
+    const customDescriptionClass = screen.getByText(
+      'Neutral description',
+    ).className;
+
+    rerender(
+      <Banner
+        status="info"
+        title="Info title"
+        description="Info description"
+      />,
+    );
+
+    expect(screen.getByText('Info title').className).not.toBe(customTitleClass);
+    expect(screen.getByText('Info description').className).not.toBe(
+      customDescriptionClass,
+    );
+  });
+
+  it.each([
+    ['info', 'var(--color-on-info-muted)'],
+    ['success', 'var(--color-on-success-muted)'],
+    ['warning', 'var(--color-on-warning-muted)'],
+    ['error', 'var(--color-on-error-muted)'],
+  ] as const)(
+    'routes %s built-in controls to the matching on-muted role without recoloring tooltips',
+    (status, expectedRole) => {
+      render(
+        <Banner
+          status={status}
+          title={`${status} banner`}
+          collapsible={{defaultIsOpen: true}}
+          isDismissable>
+          <div>Details</div>
+        </Banner>,
+      );
+
+      for (const button of [
+        screen.getByRole('button', {name: 'Collapse'}),
+        screen.getByRole('button', {name: `Dismiss ${status} banner`}),
+      ]) {
+        expect(
+          getComputedStyle(button).getPropertyValue('--color-text-primary'),
+        ).toBe(expectedRole);
+        const tooltip = document.getElementById(
+          button.getAttribute('aria-describedby')!,
+        );
+        expect(tooltip).not.toBeNull();
+        expect(
+          getComputedStyle(tooltip!).getPropertyValue('--color-text-primary'),
+        ).not.toBe(expectedRole);
+      }
+    },
+  );
+
   it('renders dismiss button when isDismissable', () => {
     render(<Banner status="info" title="Dismissable" isDismissable />);
     expect(
@@ -162,19 +229,42 @@ describe('Banner', () => {
     expect(screen.queryByRole('button', {name: /^Dismiss/})).toBeNull();
   });
 
-  it('renders endContent', () => {
+  it('leaves consumer endContent outside the built-in status foreground', () => {
     render(
-      <Banner
-        status="info"
-        title="With Action"
-        endContent={
-          <button type="button" data-testid="end-btn">
-            Action
-          </button>
-        }
-      />,
+      <>
+        <style>{'dialog { color: inherit; }'}</style>
+        <Banner
+          status="warning"
+          title="Warning action"
+          endContent={
+            <dialog open data-testid="warning-dialog">
+              Consumer dialog
+            </dialog>
+          }
+        />
+        <Banner
+          status="error"
+          title="Error action"
+          endContent={
+            <dialog open data-testid="error-dialog">
+              Consumer dialog
+            </dialog>
+          }
+        />
+      </>,
+    );
+
+    const warningTitle = screen.getByText('Warning action');
+    const errorTitle = screen.getByText('Error action');
+    const warningDialog = screen.getByTestId('warning-dialog');
+    const errorDialog = screen.getByTestId('error-dialog');
+
+    expect(getComputedStyle(warningTitle).color).not.toBe(
+      getComputedStyle(errorTitle).color,
+    );
+    expect(getComputedStyle(warningDialog).color).toBe(
+      getComputedStyle(errorDialog).color,
     );
-    expect(screen.getByTestId('end-btn')).toBeInTheDocument();
   });
 
   it('renders card container by default', () => {
@@ -462,7 +552,7 @@ describe('Banner', () => {
     const target = container.querySelector(
       '.astryx-banner-icon[data-status="info"]',
     );
-    expect(target).toHaveAttribute('data-color', 'accent');
+    expect(target).toHaveAttribute('data-color', 'inherit');
   });
 
   it("keeps the 'banner-icon' target on the wrapper for a custom icon node", () => {
@@ -775,3 +865,15 @@ describe('Banner', () => {
     });
   });
 });
+
+// jsdom cannot emulate forced colors, so this asserts the compiled rule the
+// status fill relies on (architecture:theme-tokens INV11): the fill becomes
+// Canvas, and a CanvasText boundary keeps its shape.
+describe('Banner forced colors', () => {
+  it('keeps a visible boundary on the status fill', () => {
+    render(<Banner status="error" title="Upload failed" />);
+    const css = getForcedColorsRules();
+    expect(css).toContain('outline-style: solid;');
+    expect(css).toContain('outline-color: canvastext;');
+  });
+});