Skip to content

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.md
index 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 log
diff --git a/docs/specs/components/Heading/Heading.spec.md b/docs/specs/components/Heading/Heading.spec.md
index 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