Skip to content

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

TypeScript

docs(specs): Icon and IconButton verification maps name their current tests and receipts (#9780)

Cindy Zhangcf8e4e04a917
diff --git a/docs/specs/components/Icon/Icon.spec.md b/docs/specs/components/Icon/Icon.spec.md
index 83d20a6c0b..02a635351d 100644
--- a/docs/specs/components/Icon/Icon.spec.md
+++ b/docs/specs/components/Icon/Icon.spec.md
@@ -13,6 +13,7 @@ review_triggers: [public-api, behavior, theming, accessibility]
verified_by:
[
packages/core/src/Icon/Icon.test.tsx,
+ packages/core/src/Icon/__tests__/IconAudit.a11y.chromium.spec.ts,
packages/core/src/IconButton/IconButton.test.tsx,
scripts/check-knowledge.mjs,
]
@@ -190,17 +191,15 @@ not promise a `span`, `svg`, or other element type.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| ------------------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
-| FR1, FR3, FR5 | `Icon.test.tsx` sizing suites and `IconButton.test.tsx` contextual-size suites | standalone default; Button sizes; explicit override; both modes | Breaking source rendering, standalone fallback, contextual mapping, explicit precedence, or cross-mode sizing fails assertions. | `audit:Icon/behavior` |
-| FR2, FR4 | `Icon.test.tsx` target/styling suites plus source inspection | Both source modes; size and color variants | Removing the target or breaking override composition fails existing assertions; `data-color` reflection currently lacks focused assertions. | `audit:Icon/theming` |
-| AR1, AR2, AR3 | `Icon.test.tsx` accessible-name suites | Decorative, labelled, explicit ARIA override | Changing default or labelled semantics fails accessibility assertions. | `audit:Icon/accessibility` |
-| FR6 | `Icon.test.tsx` variant suites (pending) | listed, unlisted, and omitted variant; no active list; inherited entry under a replaced list; supplied component | An unlisted variant, or one the entry's defining theme does not list, reaches an entry, or `variant` reaches a supplied component or the DOM. | `audit:Icon/behavior` |
-| FR7 | Theme styling tests for each size (pending) | each size with and without theme styles | A themed size does not change the glyph dimension, or an unstyled size changes. | `audit:Icon/theming` |
-| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical consumer anatomy and current target | Missing, extra, prefixed, or stale mappings fail repository validation. | `audit:Icon/theming` |
-
-Focused coverage for `data-color` on both glyph source modes is a checkable test
-gap; source inspection is the current evidence for that part of FR2.
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ------------------- | --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------- |
+| FR1, FR3, FR5 | `Icon.test.tsx` sizing suites and `IconButton.test.tsx` contextual-size suites | standalone default; Button sizes; explicit override; both modes | Breaking source rendering, standalone fallback, contextual mapping, explicit precedence, or cross-mode sizing fails assertions. | `audit:Icon/behavior` |
+| FR2, FR4 | `Icon.test.tsx` theming-target reflection and styling-prop suites | both source modes; every color and size; omitted color; `className`, `style`, and `xstyle` | Removing the target, dropping `data-color` or `data-size` in either mode, or breaking override composition fails assertions. | `audit:Icon/theming` |
+| FR2, FR3 (rendered) | `IconAudit.a11y.chromium.spec.ts` sensor receipts | semantic key and icon component; every size and color; Neutral and Butter in light and dark; right-to-left; 320px | A glyph without its target data, a color that does not paint its token, sizes that do not step 12, 16, 20, and 24px at the Neutral theme, registry artwork that does not fill its box, or a transformed glyph fails a receipt. | `audit:Icon/theming` |
+| AR1, AR2, AR3 | `Icon.test.tsx` accessible-name suites and the `IconAudit.a11y.chromium.spec.ts` accessible-name receipts | decorative, labelled, explicit ARIA override; labelled icon component that writes its own `aria-hidden` | Changing default or labelled semantics, or leaving a component's own `aria-hidden` on a labelled glyph, fails accessibility assertions. | `audit:Icon/accessibility` |
+| FR6 | `Icon.test.tsx` variant suite | listed, unlisted, and omitted variant; no active list; inherited entry under a replaced list; supplied component | An unlisted variant, or one the entry's defining theme does not list, reaches an entry, or `variant` reaches a supplied component or the DOM. | `audit:Icon/behavior` |
+| FR7 | `Icon.test.tsx` theme size dimension suite | each size with and without theme styles, both source modes | A themed size does not change the glyph dimension, or an unstyled size changes. | `audit:Icon/theming` |
+| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical consumer anatomy and current target | Missing, extra, prefixed, or stale mappings fail repository validation. | `audit:Icon/theming` |
## Decision log
diff --git a/docs/specs/components/IconButton/IconButton.spec.md b/docs/specs/components/IconButton/IconButton.spec.md
index 22fe92d5bd..76d602b540 100644
--- a/docs/specs/components/IconButton/IconButton.spec.md
+++ b/docs/specs/components/IconButton/IconButton.spec.md
@@ -13,6 +13,7 @@ review_triggers: [public-api, behavior, layout, accessibility]
verified_by:
[
packages/core/src/IconButton/IconButton.test.tsx,
+ packages/core/src/IconButton/__tests__/IconButtonAudit.a11y.chromium.spec.ts,
packages/core/src/Button/__tests__/Button.a11y.test.tsx,
packages/core/src/Button/__tests__/Button.a11y.chromium.spec.ts,
]
@@ -152,17 +153,18 @@ it renders Button's `button` target.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
-| FR1, FR2 | `IconButton.test.tsx` label, visible-text, ref, and displayName cases | At rest | Visible label text, a lost `aria-label`, or a dropped ref fails. | `audit:IconButton/anatomy` |
-| FR3 | `IconButton.test.tsx` icon size cases | `sm`, `md`, `lg`; explicit Icon size | A wrong default Icon size or an overridden explicit size fails. | `audit:IconButton/layout` |
-| FR3 (square) | Evidence gap: no IconButton test asserts the default square shape or zero padding | `sm`, `md`, `lg` | — | `audit:IconButton/layout` |
-| FR4 | `IconButton.test.tsx` click, disabled, loading, and elevation cases | Click; disabled; loading; `none` and `med` elevation | A click that does not reach `onClick`, a disabled click that does, a busy IconButton without `aria-disabled`, or identical classes for two elevations fails. | `audit:IconButton/behavior` |
-| FR4 (variant, size) | Evidence gap: the variant and size cases assert only that a button renders | `destructive`; `sm` | — | `audit:IconButton/behavior` |
-| FR4 (reduced motion) | Evidence gap: no test presses or loads an IconButton under `prefers-reduced-motion: reduce`; the shipped scale and Spinner fade fail this clause | Mouse and touch press; pending `clickAction` or interruptible loading with a fine pointer | A computed transform other than `none` or `scale(1)` during the press, or a Spinner opacity below 1 after loading starts. | `audit:IconButton/behavior` |
-| AR1, AR4 | `Button.a11y.test.tsx` and `Button.a11y.chromium.spec.ts` IconButton states | IconButton at rest, disabled, loading | A missing name or a wrong focusable, operable, or unavailable state fails. The shared disabled state expects native `disabled`, matching the `component:Button` FR10 gap. | `audit:IconButton/accessibility` |
-| AR2, AR3 | Evidence gap: no IconButton test asserts the tooltip hint or the 28 by 28 target | — | — | `audit:IconButton/accessibility` |
-| ORD1, PR1 | Evidence gap: no test passes a caller `isIconOnly` or asserts that IconButton adds no work | — | — | `audit:IconButton/behavior` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- |
+| FR1, FR2 | `IconButton.test.tsx` label, visible-text, ref, and displayName cases | At rest | Visible label text, a lost `aria-label`, or a dropped ref fails. | `audit:IconButton/anatomy` |
+| FR3 | `IconButton.test.tsx` icon size cases | `sm`, `md`, `lg`; explicit Icon size | A wrong default Icon size or an overridden explicit size fails. | `audit:IconButton/layout` |
+| FR3 (square) | `IconButtonAudit.a11y.chromium.spec.ts` sensor receipts | `sm`, `md`, `lg` in Neutral and Butter, light and dark | A box that is not square, padding at the Neutral theme, an icon off center, or an icon other than 16px (`sm`, `md`) or 20px (`lg`) at the Neutral theme fails a receipt. | `audit:IconButton/layout` |
+| FR4 | `IconButton.test.tsx` click, disabled, loading, and elevation cases | Click; disabled; loading; `none` and `med` elevation | A click that does not reach `onClick`, a disabled click that does, a busy IconButton without `aria-disabled`, or identical classes for two elevations fails. | `audit:IconButton/behavior` |
+| FR4 (variant, size) | `IconButton.test.tsx` variant and size reflection cases | every variant; every size | A dropped or wrong `data-variant` or `data-size` fails. | `audit:IconButton/behavior` |
+| FR4 (reduced motion) | Evidence gap: no test asserts the press or loading result under `prefers-reduced-motion: reduce`. The pressed `IconButtonAudit.a11y.chromium.spec.ts` receipt records the shipped 0.98 press scale with reduced motion on, which fails this clause, as the shipped Spinner fade does | Mouse and touch press; pending `clickAction` or interruptible loading with a fine pointer | A computed transform other than `none` or `scale(1)` during the press, or a Spinner opacity below 1 after loading starts. | `audit:IconButton/behavior` |
+| AR1, AR4 | `Button.a11y.test.tsx` and `Button.a11y.chromium.spec.ts` IconButton states | IconButton at rest, disabled, loading | A missing name or a wrong focusable, operable, or unavailable state fails. The shared disabled state expects native `disabled`, matching the `component:Button` FR10 gap. | `audit:IconButton/accessibility` |
+| AR2, AR3 | `IconButton.test.tsx` tooltip-description case and `IconButtonAudit.a11y.chromium.spec.ts` sensor receipts | tooltip on keyboard focus; `sm` at the Neutral theme | A tooltip that does not show on focus or describe the button, or an `sm` target under 28 by 28 CSS pixels at the default aspect, fails. | `audit:IconButton/accessibility` |
+| ORD1 | `IconButton.test.tsx` caller `isIconOnly` case | caller `isIconOnly={false}` | Visible label text or a lost `aria-label` fails. | `audit:IconButton/behavior` |
+| PR1 | Evidence gap: no test asserts that IconButton adds no work | — | — | `audit:IconButton/behavior` |
## Current-state impact