Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs(records): Kbd, LayerProvider and theming-surface verification follow-ups (#10299)

Cindy Zhangc3cef9f678cc
diff --git a/docs/architecture/component-theming-surface.md b/docs/architecture/component-theming-surface.md
index 8d337084e3..83deab857e 100644
--- a/docs/architecture/component-theming-surface.md
+++ b/docs/architecture/component-theming-surface.md
@@ -438,18 +438,18 @@ how themes become output, or the design rationale for a component's appearance.
## Verification
-| Invariant | Evidence | Failure signal |
-| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| INV1 | Cross-package target/documentation inventory | An exported target in a participating package is invisible to metadata or CLI validation |
-| INV2, INV3 | Bidirectional anatomy-disposition/target check | A current target has no semantic part owner, anatomy mechanically creates targets, or `none` silently becomes future policy; or separate desktop and touch rows are mounted at once outside the transient switch copy |
-| INV4, INV5 | Component review plus rendered DOM inspection | Public target lands on non-painting plumbing or aliases a child primitive without distinct semantics |
-| INV6 | `themingTargets.test.ts` and `extensibleAxes.test.ts` | State/variant is invisible to the owner target or becomes an unnecessary parallel target |
-| INV7, INV8 | Existing property fixtures (partial; gaps below) | A declared property is missing evidence, or an unlisted counterpart is treated as implied |
-| INV9 | API docs and compatibility review | Generic property acceptance is presented as a supported compatibility promise |
-| INV10, INV11 | Existing registry/public-var/runtime tests (partial; gaps below) | A public semantic var bypasses admission, or a consumer must write a private var to reach promised behavior |
-| INV12, INV13 | Canonical-only runtime emission and discovery, removed-alias rejection, complete codemod mapping/tests, canonical maintained-theme/template inventory, and family-owner fixtures | A removed alias is emitted or discovered, the migration mapping is incomplete, canonical targets change, removed compatibility metadata survives, or ownership stays implicit |
-| INV14 | Component contract, owner review, focused no-match fallback test, and structural `extensibleAxes.test.ts` coverage with its explicit artwork-axis exemption list | An ineligible axis opens, a missing rule changes behavior unpredictably, the map/reflection/docs wiring drifts, or an artwork axis gains reflection or loses its exemption |
-| INV15 | Shared root/adaptation component-validation fixtures covering finite, open, enrolled, and unresolved domains | Root and adaptation disagree, a valid open value requires a root style, a rule conditionally enrolls a custom value, or unresolved behavior becomes adaptation-specific |
+| Invariant | Evidence | Failure signal |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| INV1 | Cross-package target/documentation inventory | An exported target in a participating package is invisible to metadata or CLI validation |
+| INV2, INV3 | Bidirectional anatomy-disposition/target check | A current target has no semantic part owner, anatomy mechanically creates targets, or `none` silently becomes future policy; or separate desktop and touch rows are mounted at once outside the transient switch copy |
+| INV4, INV5 | Component review plus rendered DOM inspection | Public target lands on non-painting plumbing or aliases a child primitive without distinct semantics |
+| INV6 | `themingTargets.test.ts` and `extensibleAxes.test.ts`; the visual gate's probe theme gives each declared target, each declared state, and each enumerated value of a reflected prop its own probe colours, so a capture shows which entry last painted each element; entries on one target set the same four colour properties, so a capture proves the winning entry reached the element, not every entry beneath it; props it cannot enumerate are reported unprobed (`.github/scripts/visual-gate/generate-probe-theme.mjs`) | State/variant is invisible to the owner target or becomes an unnecessary parallel target |
+| INV7, INV8 | Existing property fixtures (partial; gaps below) | A declared property is missing evidence, or an unlisted counterpart is treated as implied |
+| INV9 | API docs and compatibility review | Generic property acceptance is presented as a supported compatibility promise |
+| INV10, INV11 | Existing registry/public-var/runtime tests (partial; gaps below) | A public semantic var bypasses admission, or a consumer must write a private var to reach promised behavior |
+| INV12, INV13 | Canonical-only runtime emission and discovery, removed-alias rejection, complete codemod mapping/tests, canonical maintained-theme/template inventory, and family-owner fixtures | A removed alias is emitted or discovered, the migration mapping is incomplete, canonical targets change, removed compatibility metadata survives, or ownership stays implicit |
+| INV14 | Component contract, owner review, focused no-match fallback test, and structural `extensibleAxes.test.ts` coverage with its explicit artwork-axis exemption list | An ineligible axis opens, a missing rule changes behavior unpredictably, the map/reflection/docs wiring drifts, or an artwork axis gains reflection or loses its exemption |
+| INV15 | Shared root/adaptation component-validation fixtures covering finite, open, enrolled, and unresolved domains | Root and adaptation disagree, a valid open value requires a root style, a rule conditionally enrolls a custom value, or unresolved behavior becomes adaptation-specific |
Known conformance and verification gaps:
@@ -483,6 +483,16 @@ Known conformance and verification gaps:
- Runtime/build private-variable rejection and media-surface derived expansion are
separate compiler conformance gaps owned and specified by
`architecture:theme-compilation`.
+- The probe theme covers Core targets only (e.g. `rich-text-editor` has no
+ probe entry). It resolves a reflected prop's values only from the top-level
+ `props` of the doc named by the target's component, so a prop documented
+ elsewhere, such as on another doc or under a subcomponent, goes unprobed;
+ that accounts for 76 of the 83 props the generator reports as skipped (e.g.
+ `button-group.size`, `avatar-status-dot.variant`). The other 7 have a type
+ with no enumerable string values, such as a numeric `gap` scale or
+ `string | CodeLanguage`. Each entry also sets the same four colour
+ properties, so an entry applied later on the same element covers an earlier
+ one's paint (on Button, `elevation` covers base, `size` and `variant`).
### Migration work from the 2026-08-30 audit
diff --git a/docs/specs/components/Kbd/Kbd.spec.md b/docs/specs/components/Kbd/Kbd.spec.md
index 0964c7602d..484074f3bb 100644
--- a/docs/specs/components/Kbd/Kbd.spec.md
+++ b/docs/specs/components/Kbd/Kbd.spec.md
@@ -34,7 +34,7 @@ system_specs: [spec:AST-102]
| Behavior | Kbd splits `keys` on `+`, draws one hidden key badge per key with platform-aware glyphs, and names the whole shortcut once with spoken key names. |
| End-user impact | Sighted people see familiar key glyphs; screen-reader users hear the shortcut as words. Those words are English in every locale. |
| Builder impact | None. |
-| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. Badges hold a fixed height; listed under Current-state impact. |
+| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. The `kbd` target sits on the non-painting shortcut group; listed under Current-state impact. |
| Review checks | Reject a badge that is exposed to assistive technology, a caller `role` or `aria-label` that replaces the computed one, duplicate React keys for repeated keys, or `mod` that ignores the platform. |
| Governing rules | `architecture:component-theming-surface`; `architecture:internationalization` INV1, INV1a; `architecture:public-component-api` INV5; `spec:AST-102` FR4. |
@@ -85,7 +85,7 @@ Consumer migration instructions belong in consumer docs and release notes.
| ID | Invariant | Basis |
| --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
-| FR1 | The current render contains one shortcut group and one painted key badge for every parsed key segment. `keys` splits on `+`; each segment is trimmed and lowercased, `esc` reads as `escape` and `return` as `enter`, and a repeated key gets its own badge. Each badge is at least the `--spacing-5` size and MUST grow with a set text size so its glyph never clips (`spec:AST-102` FR4). Implementation gap: the badge height is fixed at `--spacing-5`. | Current source, docs, and tests; `spec:AST-102` FR4 |
+| FR1 | The current render contains one shortcut group and one painted key badge for every parsed key segment. `keys` splits on `+`; each segment is trimmed and lowercased, `esc` reads as `escape` and `return` as `enter`, and a repeated key gets its own badge. Each badge is at least the `--spacing-5` size and MUST grow with a set text size so its glyph never clips (`spec:AST-102` FR4). | Current source, docs, and tests; `spec:AST-102` FR4 |
| FR2 | The shortcut group carries the current `kbd` target; individual key badges currently carry no public target (OQ1). | Current source, docs, and tests |
| FR3 | Each badge shows a glyph: `mod` is ⌘ on Apple platforms and the catalog's short Control text ("Ctrl" in English) elsewhere and before hydration; `escape` shows the catalog's short Escape text ("Esc"); `ctrl`, `alt`, `shift`, `enter`, `backspace`, `tab`, and the arrows show their symbols; `plus` shows "+"; any other key shows uppercased. | `architecture:internationalization` INV1a; current source and tests |
| FR4 | The group has `role="img"` and an `aria-label` built from each key's spoken name, taken from the Astryx catalog (`mod` is "Command" on Apple platforms and "Control" elsewhere and before hydration; an unknown key is spoken uppercased), joined pairwise through the catalog's shortcut message (" + " in English, for example "Command + K"); every badge is `aria-hidden`. A caller's `role` and `aria-label` never replace the computed ones; other caller ARIA props, such as `aria-labelledby` and `aria-hidden`, still reach the group. | `architecture:internationalization` INV1, INV1a; current source and tests |
@@ -159,7 +159,7 @@ target.
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
-| FR1 | `Kbd.test.tsx` single-key, multi-key, whitespace, alias, and repeated-key cases | Single and multiple keys; spaced and mixed-case input; repeated aliases | A missing or extra badge, an untrimmed or wrongly cased key, or a lost alias fails. Evidence gap: no test asserts badge height or text growth. | `audit:Kbd/anatomy` |
+| FR1 | `Kbd.test.tsx` single-key, multi-key, whitespace, alias, and repeated-key cases | Single and multiple keys; spaced and mixed-case input; repeated aliases | A missing or extra badge, an untrimmed or wrongly cased key, or a lost alias fails. `KbdAudit.a11y.chromium.spec.ts` larger-text cases measure each badge growing past `--spacing-5` with a set text size. | `audit:Kbd/anatomy` |
| FR2 | `Kbd.test.tsx` theme-class case | Root target and child badges | A missing root `kbd` target fails. Evidence gap: no test asserts that badges carry no target. | `audit:Kbd/theming` |
| FR3, FR4 | `Kbd.test.tsx` glyph, platform, accessible-name, override, and localization cases ("localizes visible key text and the spoken shortcut combination") | Mac and non-Mac; special and unknown keys | A wrong glyph for `mod`, `ctrl`, `alt`, `shift`, `enter`, `escape`, `plus`, or an unknown key, an exposed badge, a caller `role` or `aria-label` that replaces the computed one, or text that skips the catalog fails. Evidence gap: no test asserts the `backspace`, `tab`, or arrow glyphs, or the "Ctrl" text and "Control" name before hydration. | `audit:Kbd/accessibility` |
| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and targets | Missing, extra, prefixed, stale, or alias-backed mappings fail repository validation. | `audit:Kbd/theming` |
@@ -167,8 +167,7 @@ target.
## Current-state impact
-- **Fixed badge height (FR1).** Badges hold a fixed height instead of growing
- with a set text size, against `spec:AST-102` FR4.
+- **Target on a non-painting group (FR2).** The `kbd` target sits on the shortcut group, which paints nothing of its own, against `architecture:component-theming-surface` INV4; the key badges paint. It stays as shipped under `architecture:public-component-api` INV21a until OQ1 is decided.
## Decision log
diff --git a/docs/specs/components/Layer/LayerProvider.spec.md b/docs/specs/components/Layer/LayerProvider.spec.md
index dfad6c901b..f3b269d45b 100644
--- a/docs/specs/components/Layer/LayerProvider.spec.md
+++ b/docs/specs/components/Layer/LayerProvider.spec.md
@@ -128,15 +128,13 @@ No component-local concept beyond the consumer props.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| -------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------ |
-| FR1–FR3 | `LayerProvider.test.tsx`; for FR1 also `toastHost.test.tsx` and `toastHost.lateRegistration.test.tsx` | Default, declared inset, nested, toast inset, no Toast import | A default-provider difference, an inset that does not reach its layers, or a viewport with no Toast import fails. | `audit:LayerProvider/behavior` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------ |
+| FR1–FR3 | `LayerProvider.test.tsx`; for FR1 also `toastHost.test.tsx` and `toastHost.lateRegistration.test.tsx`; `LayerProvider.test.tsx` toast-configuration suite for `toast.maxVisible` and for a nested provider without `inset` (one viewport, outer configuration kept, no added element) | Default, declared inset, nested, toast inset, no Toast import | A default-provider difference, an inset that does not reach its layers, or a viewport with no Toast import fails. | `audit:LayerProvider/behavior` |
Read from source, with no focused test yet:
-- FR1: `toast.position` and `toast.maxVisible` reaching the viewport.
-- FR2: a nested provider without `inset` mounting no second viewport and
- rendering its children unchanged, and the outer `toast` configuration being kept.
+- FR1: `toast.position` reaching the viewport.
## Decision log