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.mdindex 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 areseparate 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 auditdiff --git a/docs/specs/components/Kbd/Kbd.spec.md b/docs/specs/components/Kbd/Kbd.spec.mdindex 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 logdiff --git a/docs/specs/components/Layer/LayerProvider.spec.md b/docs/specs/components/Layer/LayerProvider.spec.mdindex 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