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.mdindex 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 logdiff --git a/docs/specs/components/IconButton/IconButton.spec.md b/docs/specs/components/IconButton/IconButton.spec.mdindex 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