An open source design system that's fully customizable and agent ready
TypeScript
docs(spec): GridSpan and Heading verification maps name the checks that now cover them (#9349)
Cindy Zhang350ee2eb9156
diff --git a/docs/specs/components/Grid/GridSpan.spec.md b/docs/specs/components/Grid/GridSpan.spec.mdindex b457f55492..2e2be77a4e 100644--- a/docs/specs/components/Grid/GridSpan.spec.md+++ b/docs/specs/components/Grid/GridSpan.spec.md@@ -16,6 +16,9 @@ verified_by:packages/core/src/Grid/Grid.test.tsx,apps/storybook/stories/Grid.stories.tsx,packages/core/src/theme/themingTargets.test.ts,+ apps/storybook/stories/GridSpan.stories.tsx,+ packages/core/src/Grid/__tests__/GridSpanAudit.a11y.chromium.spec.ts,+ apps/storybook/rtl-audit/targets.json,]modules: []families: [family:layout-primitives]@@ -137,12 +140,12 @@ its own, so no anatomy-theming block is declared here.## Verification map-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |-| -------- | -------------------------------------------------------------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |-| FR1, FR2 | `Grid.test.tsx` GridSpan suite | Numeric, full, row, combined, none | A wrong inline `grid-column` or `grid-row`, or a span set when none is given, fails. Gap: the `grid-span` target, the one-track inner grid, the zero minimum width, and the full height have no unit check. | `audit:GridSpan/layout` |-| FR3 | `Grid.test.tsx` GridSpan ref and passthrough tests | Ref; extra props | A dropped ref or `aria-label` fails. Gap: the ref test accepts any element, and spans winning over caller `style` and the styling-input merge have no check. | `audit:GridSpan/api` |-| AR2 | `Grid.stories.tsx` long-content play and AuditMatrix full-span check | Long shrinkable child; full span | Content escaping its track or a full span missing explicit columns fails the play. | `audit:GridSpan/layout` |-| AR1, PR1 | `serverSafeComponents.test.ts`; source review | Every state | A client API added without a client directive fails `serverSafeComponents.test.ts`. Gap: a client API added together with a client directive passes, and no automated check fails if GridSpan adds a role. | `audit:GridSpan/behavior` |+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |+| FR1, FR2 | `Grid.test.tsx` GridSpan suite; `GridSpanAudit.a11y.chromium.spec.ts` on `GridSpan.stories.tsx`; the GridSpan order target in `rtl-audit/targets.json` | Numeric, full, row, combined, none; LTR and RTL | A wrong inline `grid-column` or `grid-row`, a span set when none is given, or a lost `grid-span` target fails the unit suite. A lost one-track inner grid or zero minimum width, or a span that does not cover two tracks and a gap, every explicit column, or two rows and a gap from the inline start, fails the browser spec; a row span that stops taking effect or mirroring fails the RTL order target. Gap: the full height has no check distinct from the grid's default stretch. | `audit:GridSpan/layout` |+| FR3 | `Grid.test.tsx` GridSpan ref, passthrough, style-precedence, and styling-input tests | Ref; extra props; caller style; `className` and `xstyle` | A ref that resolves to anything but the span element, a dropped `aria-label`, a caller `style` that replaces a span, a lost caller placement when no span is set, or a `className` or `xstyle` that is dropped or merges before the component styles fails. | `audit:GridSpan/api` |+| AR2 | `Grid.stories.tsx` long-content play and AuditMatrix full-span check; `GridSpanAudit.a11y.chromium.spec.ts` long-content case | Long shrinkable child; full span | Content escaping its track or a full span missing explicit columns fails the play; a span or truncating child escaping its 240px host fails the browser spec. | `audit:GridSpan/layout` |+| AR1, PR1 | `serverSafeComponents.test.ts`; `Grid.test.tsx` no-role test; `GridSpanAudit.a11y.chromium.spec.ts` | Every state | A client API added without a client directive fails `serverSafeComponents.test.ts`; a role, accessible name, or tab stop on the span fails the unit test and the browser spec. Gap: a client API added together with a client directive passes. | `audit:GridSpan/behavior` |## Decision logdiff --git a/docs/specs/components/Heading/Heading.spec.md b/docs/specs/components/Heading/Heading.spec.mdindex e449cce683..2c6844e6cf 100644--- a/docs/specs/components/Heading/Heading.spec.md+++ b/docs/specs/components/Heading/Heading.spec.md@@ -18,6 +18,7 @@ verified_by:packages/core/src/theme/themingTargets.test.ts,packages/core/src/theme/extensibleAxes.test.ts,apps/storybook/stories/Heading.stories.tsx,+ packages/core/src/Heading/__tests__/HeadingAudit.a11y.chromium.spec.ts,]modules: []families: []@@ -173,16 +174,16 @@ Tooltip.## Verification map-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |-| -------- | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |-| FR1, AR2 | `Heading.test.tsx` level and `accessibilityLevel` tests | Levels 1–6; differing override | A wrong element, or a missing `aria-level` for a differing override, fails. Gap: no test asserts that an equal `accessibilityLevel` adds no `aria-level`. | `audit:Heading/a11y` |-| FR2 | `Heading.test.tsx` target, type, theme-added type, weight, and omitted-type tests; `extensibleAxes.test.ts` | Display types, theme-added type, weight | A lost `heading` class or `data-level`, `data-color`, `data-type`, or `data-weight` reflection, a reflected omitted type, or a theme-added type losing its level baseline fails. Gap: the display scales, default weights, and weight precedence in paint have no automated check. | `audit:Heading/theming` |-| FR3 | Stable visual baseline `core-heading--level-1`; `Heading.stories.tsx` | Level 1 default | A changed level-1 scale, color, or display comes back changed for review. Gap: the prop tests assert presence only, so color paint, `display` precedence, `justify`, `textWrap`, cap-height trim, strikethrough, and the theme-added color baseline have no automated check. | `audit:Heading/behavior` |-| FR4, PR1 | `Heading.test.tsx` truncation-measurement tests; `useTruncation.test.tsx` | Tooltip on and off; content change | Measuring with the tooltip off, not measuring with it on, or a missed re-measure fails. Gap: the ellipsis and line clamp, the `wordBreak` defaults, and the tooltip's appearance and placement have no automated check. | `audit:Heading/behavior` |-| FR5 | `Heading.test.tsx` ref, `id`, and passthrough tests | Rerender; `id`; `data-testid` | A detached ref, a lost `id`, or a lost test id fails. Gap: no test covers a caller `aria-level` winning, the styling-input merge order, or the line clamp after `style`. | `audit:Heading/behavior` |-| AR1 | `Heading.test.tsx` display-type element tests | Levels with display and theme-added types | A visual type that changes the element fails. | `audit:Heading/a11y` |-| AR3 | Source review | Truncated heading | Gap: no Heading test asserts the absence of a native `title`. | `audit:Heading/a11y` |-| AR1, AR2 | Accessibility-tree evidence (`spec:AST-009` FR3) | Levels, override, display types | Gap: no accessibility-tree check proves the heading role and level; the unit tests query the DOM. | `audit:Heading/a11y` |+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------ |+| FR1, AR2 | `Heading.test.tsx` level and `accessibilityLevel` tests | Levels 1–6; differing and equal override | A wrong element, a missing `aria-level` for a differing override, or an `aria-level` added for an equal one fails. | `audit:Heading/a11y` |+| FR2 | `Heading.test.tsx` target, type, theme-added type, weight, and omitted-type tests; `extensibleAxes.test.ts`; `HeadingAudit.a11y.chromium.spec.ts` on the AuditMatrix story | Display types, theme-added type, weight | A lost `heading` class or `data-level`, `data-color`, `data-type`, or `data-weight` reflection, a reflected omitted type, or a theme-added type losing its level baseline fails. Display sizes out of order, or an explicit `bold` no heavier than the display default, fails the browser spec. Gap: the level scales and the level default weights have no paint check. | `audit:Heading/theming` |+| FR3 | Stable visual baseline `core-heading--level-1`; `Heading.stories.tsx`; `HeadingAudit.a11y.chromium.spec.ts` | Level 1 default; secondary color; `center` and `end` alignment | A changed level-1 scale, color, or display comes back changed for review; a `justify` that does not resolve to logical `center` or `end`, or heading text below its WCAG contrast threshold, fails the browser spec. Gap: `display` precedence, `textWrap`, cap-height trim, strikethrough, and the theme-added color baseline have no automated check. | `audit:Heading/behavior` |+| FR4, PR1 | `Heading.test.tsx` truncation-measurement tests; `useTruncation.test.tsx`; `HeadingAudit.a11y.chromium.spec.ts` | Tooltip on and off; content change; one and two lines | Measuring with the tooltip off, not measuring with it on, or a missed re-measure fails. A one-line heading without its ellipsis, a two-line clamp that does not hold two lines, or a clipped heading whose hover shows no full-text tooltip fails the browser spec. Gap: the `wordBreak` defaults and the tooltip placement have no automated check. | `audit:Heading/behavior` |+| FR5 | `Heading.test.tsx` ref, `id`, passthrough, `aria-level` precedence, styling-input, and line-clamp tests | Rerender; `id`; `data-testid`; caller `aria-level`; `className`, `xstyle`, and `style` | A detached ref, a lost `id` or test id, a derived `aria-level` that overrides the caller's, a `className` or `xstyle` that is dropped or merges before the component styles, or a caller `WebkitLineClamp` that replaces the clamp fails. | `audit:Heading/behavior` |+| AR1 | `Heading.test.tsx` display-type element tests | Levels with display and theme-added types | A visual type that changes the element fails. | `audit:Heading/a11y` |+| AR3 | `Heading.test.tsx` truncation title test; `HeadingAudit.a11y.chromium.spec.ts` | Truncated heading | A native `title` on a truncated heading fails both. | `audit:Heading/a11y` |+| AR1, AR2 | `HeadingAudit.a11y.chromium.spec.ts` reading Chromium's accessibility tree (`spec:AST-009` FR3) | Levels, equal and differing override, display types | A heading exposed with a role or level other than its element or `aria-level` requires fails the browser spec. | `audit:Heading/a11y` |## Decision log