@astryxdesign/core 0.7.6-canary.fdabeba → 0.7.6

package/src/Grid/Grid.spec.md

@@ -1,193 +0,0 @@
----
-schema_version: 3
-template_version: 7
-kind: component
-id: component:Grid
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-10-28
-owners: [cixzhang]
-review_triggers: [public-api, behavior, layout, theming, accessibility]
-verified_by:
-  [
-    scripts/check-knowledge.mjs,
-    packages/core/src/serverSafeComponents.test.ts,
-    packages/core/src/Grid/Grid.test.tsx,
-    apps/storybook/stories/Grid.stories.tsx,
-    .github/scripts/story-play-guard.js,
-    packages/core/src/theme/themingTargets.test.ts,
-  ]
-modules: []
-families: [family:layout-primitives]
-design_specs: []
-architecture:
-  [
-    architecture:component-theming-surface,
-    architecture:public-component-api,
-    architecture:component-test-sufficiency,
-  ]
-contributing: []
-system_specs: []
----
-
-# Grid component contract
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                                                              |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | Grid arranges children in two-dimensional tracks with `columns` (a fixed count or a responsive object), gaps, item alignment, `rowHeight`, and box sizing.                            |
-| Behavior                | A positive number creates exactly N `1fr` tracks without reflow; an object creates fill/fit tracks from a pixel minimum and optional count cap; axis gaps override uniform gap.       |
-| End-user impact         | Content keeps DOM order and logical direction while responsive object-form grids reduce their count to fit. Fixed tracks may narrow or overflow when their content cannot shrink.     |
-| Builder impact          | None; the record describes shipped behavior. Builders choose fixed numeric tracks or responsive object tracks explicitly.                                                             |
-| Compatibility/readiness | Released behavior recorded as current; no API, default, target, or runtime changes.                                                                                                   |
-| Review checks           | Reject automatic reflow for numeric columns, equal-width promises that ignore minimum content, lost gap precedence, raw inline track templates, or caller-overridable owned metadata. |
-| Governing rules         | `family:layout-primitives/FR1–FR7`; `architecture:public-component-api/INV5–INV9`; `architecture:component-theming-surface/INV2–INV6`.                                                |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-Grid arranges caller-supplied items in two-dimensional tracks. It owns track construction, gaps, item alignment, and its box size; it owns no content, surface, or structural page semantics.
-
-## Compatibility and migration
-
-- Released default preserved: yes; omitted, zero, or negative numeric `columns` resolves to one track.
-- Compatibility class: records shipped behavior; no runtime, DOM, styling, target, or public API changes.
-- Controlled/uncontrolled behavior: not applicable.
-- Migration decision: none.
-
-Consumer migration instructions belong in consumer docs and release notes.
-
-## Ownership boundary
-
-**Owns**
-
-- Grid's root container, `grid` target, track construction, axis gaps, item alignment, and explicit box dimensions.
-- The `grid-span` target that GridSpan's wrapper carries, which `Grid.doc.mjs` declares and the anatomy map below lists.
-- Root prop and style composition on the Grid root.
-
-**Does not own / non-goals**
-
-- Caller content, item semantics, surfaces, or interaction — owned by the product callsite or rendered child component.
-- A shared breakpoint or automatic reflow for numeric columns — responsiveness is selected by Grid's object form.
-- The GridSpan wrapper's behavior and one item's row and column participation —
-  owned by `component:GridSpan`, which has its own consumer doc and record.
-
-## Public concepts
-
-| Concept              | Closed values or states                    | Meaning                                                                 | Availability by variant/orientation/state | Default                     | Owner                      | Stability | Invalid-value behavior                       |
-| -------------------- | ------------------------------------------ | ----------------------------------------------------------------------- | ----------------------------------------- | --------------------------- | -------------------------- | --------- | -------------------------------------------- |
-| column shape         | fixed number; responsive object; omitted   | Selects fixed `1fr` tracks or intrinsic fill/fit tracks.                | Every Grid                                | one track                   | `component:Grid`           | Stable    | zero/negative number falls back to one track |
-| responsive repeat    | `fill`; `fit`                              | Keeps empty tracks or collapses them so present items stretch.          | Object-form columns                       | `fill`                      | `component:Grid`           | Stable    | Type-constrained                             |
-| responsive count cap | absent; positive `max`; non-positive `max` | Caps the number of intrinsic tracks while allowing present tracks fill. | Object-form columns                       | absent                      | `component:Grid`           | Stable    | non-positive behaves as uncapped             |
-| spacing              | shared `SpacingStep` values                | Separates rows/columns; axis values override uniform gap.               | Every Grid                                | browser grid gap default    | `family:layout-primitives` | Stable    | Type-constrained                             |
-| item alignment       | `start`; `center`; `end`; `stretch`        | Sets `align-items` and `justify-items`.                                 | Every Grid                                | browser `normal`            | `component:Grid`           | Stable    | Type-constrained                             |
-| box size             | number; CSS value string; absent           | Sizes the Grid box; numbers become pixels.                              | Every Grid                                | caller/container-determined | `family:layout-primitives` | Stable    | Browser validates strings                    |
-| implicit row height  | number; absent                             | Sets pixel height for implicit rows used by row spans.                  | Every Grid                                | browser `auto`              | `component:Grid`           | Stable    | Browser validates the resulting CSS          |
-
-## Behavioral and layout contract
-
-| ID  | Invariant                                                                                                                                                                                                                                                                    | Basis                                                           |
-| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
-| FR1 | A positive numeric `columns={N}` creates exactly N `1fr` tracks at every width and never reflows; minimum content may widen one track and overflow a narrow container. Omitted, zero, or negative `columns` gives one `1fr` track.                                           | DEC-1; released docs, source, and tests                         |
-| FR2 | Object-form columns use auto-fill by default or auto-fit for `repeat: 'fit'`; `minWidth` is the track floor, while a positive `max` caps the count and lets a lone track shrink to the container.                                                                            | Released docs, source, and tests                                |
-| FR3 | `rowGap` overrides `gap` only for rows, and `columnGap` overrides `gap` only for columns; the effective column gap participates in capped-track math. `rowHeight` sets the implicit row height in pixels.                                                                    | `family:layout-primitives/FR4`; source and tests                |
-| FR4 | The track template is a class-level declaration, so caller `xstyle` and class rules, including media rules, can replace it. Caller `style` wins other inline declarations, and explicit `width`, `height`, `maxWidth`, and `minHeight` props override matching `style` keys. | `architecture:public-component-api/INV5–INV8`; source and tests |
-| FR5 | `align` and `justify` set `align-items` and `justify-items` to `start`, `center`, `end`, or `stretch`; unset leaves the browser default (`normal`, which stretches items without a natural size or aspect ratio).                                                            | Source and tests                                                |
-| FR6 | `ref`, DOM, data, ARIA, and event props, `xstyle`, class name, and inline style reach or compose on the root without replacing the `grid` target or its reflected `columns` (numeric form only), `gap`, `align`, and `justify`.                                              | `architecture:public-component-api/INV5–INV8`; source and tests |
-| FR7 | Grid preserves caller DOM order and uses the document's logical inline direction; it creates no separate keyboard order.                                                                                                                                                     | Platform layout behavior                                        |
-
-### Allowed variation
-
-- **AV1 — Caller content.** Any caller-owned element may participate directly or inside GridSpan; Grid does not inspect or rewrite it.
-- **AV2 — Track count.** Container width, minimum content, gaps, and object-form options may change the rendered responsive count within FR1–FR3.
-- **AV3 — Root styling.** Caller styles may replace track templates or box presentation while preserving the component-owned target and metadata.
-
-### Representative states
-
-| State              | Required invariant                                                       | Allowed variation                                     |
-| ------------------ | ------------------------------------------------------------------------ | ----------------------------------------------------- |
-| fixed Grid         | Exactly N explicit `1fr` tracks; no component-owned reflow.              | N, content minimums, gaps, and caller styling.        |
-| responsive fill    | Empty tracks remain allocated while count responds to available width.   | Minimum width, cap, content count, and effective gap. |
-| responsive fit     | Empty tracks collapse and present items stretch.                         | Minimum width, cap, content count, and effective gap. |
-| capped narrow Grid | Count drops and one present track can fill a container below `minWidth`. | Container width and caller content.                   |
-| direct item        | Caller content participates without a Grid-owned wrapper.                | Any caller-owned element and semantics.               |
-
-### Transformation and precedence order
-
-- **ORD1 — Track shape.** Responsive object with positive `max` → capped fill/fit template; responsive object without positive `max` → uncapped fill/fit template; positive number → fixed `repeat(N, 1fr)`; otherwise → one `1fr` track.
-- **ORD2 — Gap.** Axis gap → uniform gap → no gap term in capped-track arithmetic.
-- **ORD3 — Root composition.** Caller props apply first; the component-owned target, reflection, and StyleX compose next; `xstyle`, class name, and caller inline style keep their styling precedence; sizing props win over matching inline keys.
-
-### Performance and resources
-
-- **PR1 — CSS-owned layout.** Grid owns no state, effect, observer, listener, timer, or JavaScript measurement; layout and reflow are CSS-owned.
-
-## Accessibility contract
-
-- **AR1 — Layout remains nonsemantic.** Grid renders a `<div>` without grid, list, group, or landmark semantics of its own; callers provide semantics when their composition needs them.
-- **AR2 — Order remains perceivable.** DOM order remains the reading and keyboard order in LTR and RTL; visual tracks do not create a second sequence.
-
-## Design relationships
-
-| Anatomy or state | Design requirement                                      | Representation authority | Hierarchy role | Component contract |
-| ---------------- | ------------------------------------------------------- | ------------------------ | -------------- | ------------------ |
-| Grid container   | Two-dimensional tracks for caller items; geometry only. | Current source and docs  | Supporting     | FR1–FR6            |
-| Spanning item    | An optional wrapper documented beside Grid.             | `component:GridSpan`     | Supporting     | —                  |
-
-Theming: the root is the `grid` target, reflecting `align`, numeric `columns`,
-`gap`, and `justify`. `Grid.doc.mjs` documents the Spanning item part and its
-`grid-span` target, so the map below lists both; `component:GridSpan` owns the
-wrapper's behavior.
-
-### Theming anatomy
-
-<!-- anatomy-theming:v1 -->
-
-```json
-{
-  "Grid container": {"target": "grid"},
-  "Spanning item": {"target": "grid-span"}
-}
-```
-
-## Family and system relationships
-
-- `family:layout-primitives` owns shared spacing, sizing, alignment, and item-participation vocabulary; Grid owns the two-dimensional realization, and `component:GridSpan` the participation modifier.
-- `architecture:public-component-api` owns root prop, styling, event, ref, and released-type composition.
-- `architecture:component-theming-surface` sets the rules the `grid` target and its reflected axes follow.
-- `architecture:component-test-sufficiency` owns bounded, mutation-sensitive evidence selection.
-
-## Verification map
-
-| Contract            | Verification                                                                                                      | Representative states                                                         | Mutation or failure expectation                                                                                                                                                                                                                                                                                         | Audit section         |
-| ------------------- | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
-| FR1–FR3, ORD1, ORD2 | `Grid.test.tsx` track-template, row-height, and capped-gap tests; `Grid.stories.tsx` AuditMatrix play guard       | Fixed; zero and negative; fill; fit; capped with and without gaps; row height | A changed track template (count, fill or fit, floor, cap, or the gap in the cap) or row height fails exact assertions; a grid that overflows its host fails the play guard. Gap: the gap and axis-gap tests assert only that the grid renders, so `rowGap` and `columnGap` overriding `gap` on their axis has no check. | `audit:Grid/behavior` |
-| FR4, FR6, ORD3      | `Grid.test.tsx` raw-inline-template, sizing, ref, passthrough, and owned-metadata tests; `themingTargets.test.ts` | DOM, data, ARIA, events; class, style, xstyle; reflected axes                 | A dropped `aria-label`, replaced owned metadata, a raw inline track, or a wrong width or height fails. Gap: the ref test accepts any element, and the `xstyle`, `className`, `style` merge order and size props winning over `style` have no check.                                                                     | `audit:Grid/api`      |
-| FR5                 | `Grid.test.tsx` alignment and owned-metadata tests                                                                | `align` and `justify`                                                         | A lost `data-align` or `data-justify` reflection fails. Gap: the alignment test asserts only that the grid renders, so the `align-items` and `justify-items` values have no check.                                                                                                                                      | `audit:Grid/behavior` |
-| FR7, AR1, AR2       | `Grid.stories.tsx` AuditMatrix play guard in LTR and RTL                                                          | Fixed tracks in both directions                                               | Items that do not run start to end in the document direction fail the play guard. Gap: no automated check asserts that Grid adds no role or keeps DOM order.                                                                                                                                                            | `audit:Grid/a11y-rtl` |
-| PR1                 | `serverSafeComponents.test.ts`; source review                                                                     | Every state                                                                   | A client API (state, an effect) 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 Grid adds layout measurement.                                                                                   | `audit:Grid/behavior` |
-| Theming anatomy map | `scripts/check-knowledge.mjs`                                                                                     | Consumer anatomy and current targets                                          | Missing, extra, or stale mappings fail repository validation.                                                                                                                                                                                                                                                           | `audit:Grid/theming`  |
-
-## Decision log
-
-### DEC-1 — Numeric `columns` stays fixed; reflow uses the existing object form
-
-**Reference:** `component:Grid/DEC-1`
-**Decider:** `cixzhang`, `2026-10-11`
-
-`columns={N}` means exactly N `1fr` tracks at every width, and a grid that reflows on small screens uses `{minWidth, max?, repeat?}`. The number is the fixed contract; the object form is the responsive contract.
-
-Rejected: redefining the number as "at most N" would break released numeric grids; a `{count, isFixed}` shape would duplicate the number and the `max` cap.
-
-## Open questions
-
-None.
-
-## Content boundary
-
-This file does not duplicate consumer prop tables/examples, current audit
-results, implementation steps, or family/system rules. It links to their owners.

package/src/Grid/GridSpan.spec.md

@@ -1,158 +0,0 @@
----
-schema_version: 3
-template_version: 7
-kind: component
-id: component:GridSpan
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-10-28
-owners: [cixzhang]
-review_triggers: [public-api, layout, theming, accessibility]
-verified_by:
-  [
-    packages/core/src/serverSafeComponents.test.ts,
-    packages/core/src/Grid/Grid.test.tsx,
-    apps/storybook/stories/Grid.stories.tsx,
-    packages/core/src/theme/themingTargets.test.ts,
-  ]
-modules: []
-families: [family:layout-primitives]
-design_specs: []
-architecture:
-  [architecture:component-theming-surface, architecture:public-component-api]
-contributing: []
-system_specs: []
----
-
-# GridSpan component contract
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                               |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Public contract         | An optional wrapper for one Grid item with `columns` (a count or `'full'`) and `rows`.                                                                 |
-| Behavior                | A count spans that many tracks; `'full'` spans every explicit column; the wrapper keeps a zero minimum width so shrinkable content stays in its track. |
-| End-user impact         | Readers see featured or tall items occupy several tracks without breaking the grid's order.                                                            |
-| Builder impact          | None; the record describes shipped behavior.                                                                                                           |
-| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes.                                                                             |
-| Review checks           | Reject `'full'` described as covering implicit tracks, a lost zero minimum width, or a wrapper that adds semantics.                                    |
-| Governing rules         | `family:layout-primitives/FR6`; `architecture:public-component-api/INV5,INV6,INV8`; `architecture:component-theming-surface/INV2`.                     |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-GridSpan changes how one item participates in a Grid: how many columns or rows
-it covers. It owns that wrapper and nothing about the content inside it.
-
-## Compatibility and migration
-
-- Released default preserved: `yes`
-- Compatibility class: records shipped behavior; no public prop, default, DOM,
-  or styling output changes
-- Controlled/uncontrolled behavior: not applicable
-- Migration decision: none
-
-Consumer migration instructions belong in consumer docs and release notes.
-
-## Ownership boundary
-
-**Owns**
-
-- The wrapper `div`, which carries the `grid-span` target that
-  `component:Grid` publishes and maps, and its column and row spans.
-- The wrapper's single-track inner grid and zero minimum width.
-
-**Does not own / non-goals**
-
-- Track construction, gaps, and alignment — owned by `component:Grid`.
-- Implicit tracks the browser creates when a numeric span exceeds the explicit
-  grid.
-- Caller content and its semantics.
-
-## Public concepts
-
-| Concept | Closed values or states        | Meaning                                    | Availability by variant/orientation/state | Default             | Owner                | Stability | Invalid-value behavior                                         |
-| ------- | ------------------------------ | ------------------------------------------ | ----------------------------------------- | ------------------- | -------------------- | --------- | -------------------------------------------------------------- |
-| Columns | positive number; `full`; unset | Spans N columns, or every explicit column. | Inside a Grid                             | intrinsic placement | `component:GridSpan` | Stable    | The browser resolves numeric spans, including implicit tracks. |
-| Rows    | positive number; unset         | Spans N rows.                              | Inside a Grid                             | intrinsic placement | `component:GridSpan` | Stable    | The browser validates the resulting CSS.                       |
-
-## Behavioral and layout contract
-
-| ID  | Invariant                                                                                                                                                                                                        | Basis                    |
-| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
-| FR1 | GridSpan renders one `div` carrying the `grid-span` target, displayed as a grid with one `minmax(0, 1fr)` column, zero minimum width, and full height, holding its children.                                     | Current source and tests |
-| FR2 | `columns={N}` sets `grid-column: span N`; `columns="full"` sets `grid-column: 1 / -1`, covering the explicit columns only; `rows={N}` sets `grid-row: span N`. Unset spans leave browser placement intrinsic.    | Current source and tests |
-| FR3 | The span declarations are inline styles applied after the caller's `style`. `ref` reaches the `div`; supported DOM, ARIA, data, and event props reach it; `xstyle` and `className` merge after component styles. | Current source and tests |
-
-### Allowed variation
-
-- **AV1 — Caller content.** Any content may fill the wrapper.
-
-### Representative states
-
-| State        | Required invariant                            | Allowed variation |
-| ------------ | --------------------------------------------- | ----------------- |
-| Numeric span | Spans N tracks; may create implicit tracks.   | N.                |
-| Full span    | Covers explicit columns from line 1 to -1.    | Column count.     |
-| Row span     | Spans N rows, often with Grid's `rowHeight`.  | N.                |
-| Long content | Shrinkable descendants stay inside the track. | Content.          |
-
-### Transformation and precedence order
-
-- **ORD1 — Span.** `'full'` → `1 / -1`; a number → `span N`; unset → intrinsic.
-- **ORD2 — Inline style.** Caller `style` → span declarations.
-
-### Performance and resources
-
-- **PR1 — Static render.** GridSpan holds no state and uses no hooks.
-
-## Accessibility contract
-
-- **AR1 — Nonsemantic wrapper.** GridSpan adds no role, name, or tab stop of
-  its own and keeps DOM order.
-- **AR2 — Content stays reachable.** The zero minimum width lets shrinkable
-  descendants stay inside their track; content that cannot shrink may still
-  overflow under `component:Grid` FR1.
-
-## Design relationships
-
-| Anatomy or state | Design requirement                               | Representation authority | Hierarchy role | Component contract |
-| ---------------- | ------------------------------------------------ | ------------------------ | -------------- | ------------------ |
-| Spanning item    | One item covering several tracks; geometry only. | Current source and docs  | Supporting     | FR1, FR2, AR2      |
-
-Theming: the wrapper carries the `grid-span` target, which `Grid.doc.mjs`
-declares and `component:Grid` maps. `GridSpan.doc.mjs` declares no anatomy of
-its own, so no anatomy-theming block is declared here.
-
-## Family and system relationships
-
-- `family:layout-primitives` FR6 names GridSpan the participation modifier for
-  Grid; its behavior outside a Grid is this record's.
-- `component:Grid` owns the tracks GridSpan spans.
-- `architecture:public-component-api` owns ref, passthrough, and styling-input
-  rules; FR3 applies them.
-
-## 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` |
-
-## Decision log
-
-None recorded. The record describes shipped behavior.
-
-## Open questions
-
-None.
-
-## Content boundary
-
-This file does not duplicate consumer prop tables/examples, current audit
-results, implementation steps, or family/system rules. It links to their owners.

package/src/Heading/Heading.spec.md

@@ -1,198 +0,0 @@
----
-schema_version: 3
-template_version: 7
-kind: component
-id: component:Heading
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-10-27
-owners: [cixzhang]
-review_triggers: [public-api, behavior, layout, theming, accessibility]
-verified_by:
-  [
-    .github/visual-baseline/manifest.json,
-    packages/core/src/Heading/Heading.test.tsx,
-    packages/core/src/Text/useTruncation.test.tsx,
-    packages/core/src/theme/themingTargets.test.ts,
-    packages/core/src/theme/extensibleAxes.test.ts,
-    apps/storybook/stories/Heading.stories.tsx,
-  ]
-modules: []
-families: []
-design_specs: []
-architecture:
-  [architecture:component-theming-surface, architecture:public-component-api]
-contributing: []
-system_specs: [spec:AST-009, spec:AST-024]
----
-
-# Heading component contract
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                                                                   |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Public contract         | A semantic heading with a required `level`, an optional theme-extensible visual `type`, `weight`, `accessibilityLevel`, and the shared text controls documented in `Heading.doc.mjs`.      |
-| Behavior                | `level` picks `h1`–`h6` and the default visual scale; `type` and `weight` change only appearance; `accessibilityLevel` sets `aria-level` when it differs.                                  |
-| End-user impact         | Screen-reader users navigate a document outline that matches the page's sections, whatever size each heading is drawn at.                                                                  |
-| Builder impact          | None; the record describes shipped behavior.                                                                                                                                               |
-| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. One implementation gap is listed under Current-state impact.                                                    |
-| Review checks           | Reject a visual `type` or `weight` that changes the element or level, a heading that renders without a level baseline, or a duplicate native tooltip for truncation.                       |
-| Governing rules         | `spec:AST-024` (custom visual types, weight precedence, unchanged accessibility); `architecture:component-theming-surface/INV6,INV14`; `architecture:public-component-api/INV5,INV6,INV8`. |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-Heading marks a section or page title with native heading semantics and themed
-type. It keeps the document outline (`level`, `accessibilityLevel`) separate
-from appearance (`type`, `weight`). Its consumer documentation lives in
-`Text/Heading.doc.mjs`, as a member of the Text documentation; this record is
-Heading's own contract.
-
-## Compatibility and migration
-
-- Released default preserved: `yes`
-- Compatibility class: records shipped behavior; no public prop, default, DOM,
-  or styling output changes
-- Controlled/uncontrolled behavior: not applicable
-- Migration decision: none
-
-Consumer migration instructions belong in consumer docs and release notes.
-
-## Current-state impact
-
-- **Truncation tooltip not reachable by keyboard (FR4).** A truncated Heading
-  is not focusable, so Tooltip attaches no focus trigger and sighted keyboard
-  users cannot reveal the clipped text, where WCAG 2.2 2.1.1 expects
-  functionality to be keyboard operable. The full text stays in the DOM for
-  assistive technology.
-
-## Ownership boundary
-
-**Owns**
-
-- The `h1`–`h6` element, its `heading` theming target, and `aria-level`.
-- Level-based and built-in display-type sizing, weight defaults, color, and the
-  shared text layout controls on the heading element.
-- Measuring truncation and deciding when to compose the truncation Tooltip.
-
-**Does not own / non-goals**
-
-- Theme enrollment and generated declarations for custom visual types — owned
-  by `spec:AST-024` and the theme build.
-- Non-heading text — owned by `component:Text`.
-- The truncation tooltip surface, layer, and `tooltip` target — owned by
-  Tooltip.
-- Heading content — owned by the caller.
-
-## Public concepts
-
-| Concept             | Closed values or states                                             | Meaning                                                       | Availability by variant/orientation/state | Default               | Owner               | Stability | Invalid-value behavior                                                                             |
-| ------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------- | ----------------------------------------- | --------------------- | ------------------- | --------- | -------------------------------------------------------------------------------------------------- |
-| Level               | 1–6                                                                 | Selects `h1`–`h6` and the level's visual scale.               | Always                                    | Required              | `component:Heading` | Stable    | TypeScript rejects other values.                                                                   |
-| Visual type         | `display-1`, `display-2`, `display-3`; theme additions              | Replaces the level's visual scale without changing semantics. | Always                                    | unset                 | `component:Heading` | Stable    | A theme-added value is reflected on `heading` and keeps the level's baseline (`spec:AST-024` FR4). |
-| Weight              | `normal`, `medium`, `semibold`, `bold`                              | Overrides the type or level default weight.                   | Always                                    | type or level default | `component:Heading` | Stable    | TypeScript rejects other values.                                                                   |
-| Accessibility level | 1–6                                                                 | The outline level exposed to assistive technology.            | Always                                    | `level`               | `component:Heading` | Stable    | TypeScript rejects other values.                                                                   |
-| Truncation          | `maxLines` 0 (none), 1, or more; tooltip on, off, or at a placement | Clamps lines and offers the full text in a Tooltip.           | Always                                    | 0; tooltip on         | `component:Heading` | Stable    | —                                                                                                  |
-
-## Behavioral and layout contract
-
-| ID  | Invariant                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Basis                    |
-| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
-| FR1 | `level` renders `h1`–`h6`. `accessibilityLevel` adds `aria-level` only when it differs from `level`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Current source and tests |
-| FR2 | The heading carries the `heading` target reflecting `level`, `color`, and any supplied `type` and `weight`. A built-in `type` applies its display scale and default weight; otherwise the level's scale applies. A theme-added `type` keeps the level's scale as its baseline. An explicit `weight` wins over the type and level defaults.                                                                                                                                                                                                                                                                                                                                                                                                  | Current source and tests |
-| FR3 | `color` defaults to `primary`; a theme-added color keeps the primary baseline until a theme paints it. `hasCapsize` renders `block` and trims to cap height; otherwise `maxLines` above 1 renders the line-clamp box, `maxLines={1}` renders `block`, and otherwise `display` (default `block`) applies. `justify` uses logical values; `start`, the default, sets no alignment, so the element follows its container's. `textWrap` and `hasStrikethrough` apply their text treatments.                                                                                                                                                                                                                                                     | Current source and tests |
-| FR4 | `maxLines={1}` clips one line with an ellipsis; a larger value clamps to that many lines unless `hasCapsize` is set, whose `block` display removes the clamp. With truncation, `wordBreak` defaults to `break-all` for one line and `break-word` otherwise. When the text is measured as truncated and `hasTruncateTooltip` is not `false`, a lazily loaded Tooltip anchored to the heading shows the full text at the given placement (default `above`); no native `title` is added. `hasTruncateTooltip={false}` takes no measurement. A truncation tooltip can be opened from the keyboard (WCAG 2.2 2.1.1). Implementation gap: the tooltip opens on hover and touch only, because the heading is not focusable (Current-state impact). | Current source and tests |
-| FR5 | `ref` reaches the heading element. Supported DOM, ARIA, data, and event props reach it after the derived `aria-level`, so a caller `aria-level` wins; `xstyle`, `className`, and `style` merge in that order after component styles, with the line clamp applied after `style`.                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Current source and tests |
-
-### Allowed variation
-
-- **AV1 — Theme paint.** A theme may restyle `heading` per `level`, `color`,
-  `type`, and `weight` without changing the element or level.
-- **AV2 — Visual reuse.** Any level may use any visual type.
-
-### Representative states
-
-| State                   | Required invariant                                             | Allowed variation |
-| ----------------------- | -------------------------------------------------------------- | ----------------- |
-| Level only              | `h{level}` at the level's scale.                               | Level.            |
-| Display type            | Same element; display scale and weight; `data-type` reflected. | Type.             |
-| Theme-added type        | Same element; level baseline; `data-type` reflected.           | Theme paint.      |
-| Accessibility override  | `aria-level` differs from the element's level.                 | —                 |
-| Truncated with tooltip  | Clamped heading anchors one Tooltip with the full text.        | Placement.        |
-| Truncation, tooltip off | Clamped heading; no measurement; no Tooltip.                   | —                 |
-
-### Transformation and precedence order
-
-- **ORD1 — Weight.** Explicit `weight` → built-in type default → level default
-  (`spec:AST-024` FR8).
-- **ORD2 — Scale.** Built-in `type` → level scale (also the baseline for a
-  theme-added type).
-- **ORD3 — Display.** `hasCapsize` (`block`) → `maxLines` above 1 (line-clamp
-  box) → `maxLines={1}` (`block`) → `display` prop.
-
-### Performance and resources
-
-- **PR1 — Measured only when needed.** Truncation is measured only when
-  `maxLines` is positive and the tooltip is enabled; re-measuring follows size
-  and content changes without a per-heading observer; the Tooltip module loads
-  only when the text is truncated.
-
-## Accessibility contract
-
-- **AR1 — Native heading.** The element is a native `h1`–`h6`; a visual type or
-  weight never changes the role, level, or name (`spec:AST-024` FR15).
-- **AR2 — Outline override.** `accessibilityLevel` exposes a different outline
-  level through `aria-level` without changing the element.
-- **AR3 — Truncated text.** The full text stays in the heading's DOM; the
-  truncation Tooltip is the only tooltip, and any description it adds is
-  Tooltip's.
-
-## Design relationships
-
-| Anatomy or state   | Design requirement                                      | Representation authority | Hierarchy role | Component contract |
-| ------------------ | ------------------------------------------------------- | ------------------------ | -------------- | ------------------ |
-| Heading            | A section or page title at the level's or type's scale. | Current source and docs  | Prominent      | FR1–FR3, AR1, AR2  |
-| Truncation tooltip | The full text when the heading is clamped.              | Tooltip                  | Supporting     | FR4, AR3           |
-
-Theming: the heading element is the single `heading` target. Its consumer
-documentation is a member of `Text/Heading.doc.mjs` and lists no anatomy, so no
-anatomy-theming block is declared; the truncation tooltip's target belongs to
-Tooltip.
-
-## Family and system relationships
-
-- `spec:AST-024` owns custom visual types, weight precedence, and the rule that
-  visual changes leave accessibility unchanged; FR2, ORD1, and AR1 apply it.
-- `component:Text` shares Heading's type styles and truncation mechanism.
-- `architecture:component-theming-surface` sets the rules the `heading` target
-  follows (INV6) and qualifies `type` as a theme-extensible axis (INV14).
-
-## 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`     |
-
-## Decision log
-
-None recorded. The record describes shipped behavior.
-
-## Open questions
-
-None.
-
-## Content boundary
-
-This file does not duplicate consumer prop tables/examples, current audit
-results, implementation steps, or family/system rules. It links to their owners.