@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/Grid/Grid.spec.md

@@ -3,20 +3,21 @@ schema_version: 3
 template_version: 7
 kind: component
 id: component:Grid
-authority: draft
+authority: current
 archive_reason: null
 superseded_by: null
-approved_by: null
-approved_at: 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,
-    scripts/check-knowledge.mjs,
   ]
 modules: []
 families: [family:layout-primitives]
@@ -35,26 +36,26 @@ system_specs: []
 
 ## Contract at a glance
 
-| Area                    | Contract                                                                                                                                                                                                               |
-| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Public contract         | `Grid` owns fixed and intrinsic column-track construction; `GridSpan` changes one direct item's row or column participation. Both accept root `BaseProps`.                                                             |
-| 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          | Builders choose fixed numeric tracks or responsive object tracks explicitly. `'full'` spans all explicit columns, not implicit tracks created by an oversized numeric span.                                            |
-| Compatibility/readiness | This draft records released behavior. It changes no public API, default, target, or runtime behavior.                                                                                                                  |
-| Review checks           | Reject automatic reflow for numeric columns, equal-width promises that ignore minimum content, lost gap precedence, raw inline track templates, caller-overridable owned metadata, or `'full'` as all implicit tracks. |
-| Governing rules         | `family:layout-primitives/FR1–FR7`; `architecture:public-component-api/INV5–INV9`; `architecture:component-theming-surface/INV2–INV6`.                                                                                 |
+| 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. GridSpan optionally wraps one item to control its row or column participation. Neither component owns the content, a surface, or structural page semantics.
+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: observational only; runtime, DOM, styling, targets, and public API remain unchanged.
+- Compatibility class: records shipped behavior; no runtime, DOM, styling, target, or public API changes.
 - Controlled/uncontrolled behavior: not applicable.
 - Migration decision: none.
 
@@ -64,82 +65,83 @@ Consumer migration instructions belong in consumer docs and release notes.
 
 **Owns**
 
-- Grid's root container, current `grid` target, track construction, axis gaps, item alignment, and explicit box dimensions.
-- GridSpan's optional wrapper, current `grid-span` target, and one item's row/column participation.
-- Root prop and style composition on each owned element.
+- 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.
-- Implicit tracks created by CSS Grid when a numeric span exceeds the explicit grid.
+- 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`           | released  | 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`           | released  | 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`           | released  | 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` | released  | Type-constrained                                          |
-| item alignment       | `start`; `center`; `end`; `stretch`        | Sets `align-items` and `justify-items`.                                 | Every Grid                                | `stretch`                   | `component:Grid`           | released  | Type-constrained                                          |
-| box size             | number; CSS value string; absent           | Sizes the Grid box; numbers become pixels.                              | Every Grid                                | caller/container-determined | `family:layout-primitives` | released  | Browser validates strings                                 |
-| implicit row height  | number; absent                             | Sets pixel height for implicit rows used by row spans.                  | Every Grid                                | browser `auto`              | `component:Grid`           | released  | Browser validates the resulting CSS                       |
-| column participation | number; `full`; absent                     | Spans N columns or every explicit column.                               | GridSpan under a grid                     | intrinsic item placement    | `component:GridSpan`       | released  | Browser resolves numeric spans, including implicit tracks |
-| row participation    | number; absent                             | Spans N rows.                                                           | GridSpan under a grid                     | intrinsic item placement    | `component:GridSpan`       | released  | Browser validates the resulting CSS                       |
+| 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
 
-Draft requirements identify their basis so observed code is not mistaken for an intentional decision.
-
-| ID  | Candidate invariant                                                                                                                                                                                                                                                                                                    | Basis                                                       | Draft review state  |
-| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | ------------------- |
-| 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.                                                                                                                                                 | DEC-1; released docs, source, tests, and browser evidence   | settled observation |
-| 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 count and allows a lone track to shrink to the container.                                                                                                                     | Released docs, source, tests, and browser evidence          | settled observation |
-| FR3 | `rowGap` overrides `gap` only for rows, and `columnGap` overrides `gap` only for columns; the effective column gap participates in capped-track math.                                                                                                                                                                  | `family:layout-primitives/FR4`; source and tests            | settled observation |
-| FR4 | Grid's dynamic track template uses CSS-variable-backed StyleX so caller `xstyle` and class rules, including media rules, can replace it. Caller `style` wins other inline declarations, including `gridTemplateColumns`; explicit `width`, `height`, `maxWidth`, and `minHeight` props override matching `style` keys. | `architecture:public-component-api/INV5–INV8`; source/tests | settled observation |
-| FR5 | GridSpan changes only its wrapper's participation. `columns="full"` uses `1 / -1`, which covers explicit tracks; a wider numeric span may create implicit tracks that participate in later placement.                                                                                                                  | Released source, tests, and browser CSS Grid behavior       | settled observation |
-| FR6 | Root refs, DOM/data/ARIA/events, `xstyle`, class name, and inline style reach or compose on the owned root without replacing the canonical target or Grid's owned reflected metadata.                                                                                                                                  | `architecture:public-component-api/INV5–INV8`               | settled observation |
-| FR7 | Grid and GridSpan preserve caller DOM order and use the document's logical inline direction; neither creates a separate keyboard order.                                                                                                                                                                                | Platform layout behavior and browser evidence               | settled observation |
+| 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 component-owned targets and metadata.
+- **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.               |
-| numeric spanning item | The wrapper spans N rows/columns and may cause implicit tracks.          | Positive browser-valid span counts.                   |
-| full spanning item    | The wrapper covers the explicit grid from line 1 to -1.                  | Explicit count and caller content.                    |
+| 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 → zero gap for capped-track arithmetic.
-- **ORD3 — Root composition.** Neutral pass-throughs apply first; component-owned target/reflection and StyleX compose next; `xstyle`, class name, and caller inline style retain their documented styling precedence.
-- **ORD4 — Span.** `'full'` becomes `1 / -1`; a number becomes `span N`; absence leaves browser placement intrinsic.
+- **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 and GridSpan own no state, effect, observer, listener, timer, or JavaScript measurement loop; layout and reflow remain CSS-owned.
+- **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 and GridSpan render `<div>` elements without inventing grid, list, group, or landmark semantics; callers provide semantics when their composition needs them.
+- **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.
-- **AR3 — Content remains reachable.** GridSpan keeps a zero inline minimum so supported shrinkable descendants can remain inside their track; caller content that cannot shrink may still overflow under FR1.
 
 ## Design relationships
 
-No current component-local or shared design record prescribes a Grid-specific visual representation. Grid and GridSpan own geometry only; caller content owns visible surfaces and states.
+| 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
 
@@ -154,21 +156,21 @@ No current component-local or shared design record prescribes a Grid-specific vi
 
 ## Family and system relationships
 
-- `family:layout-primitives` owns shared spacing, sizing, alignment, and item-participation vocabulary; Grid owns the two-dimensional realization.
+- `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` owns the two exact target mappings and Grid's reflected visual axes.
+- `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–2 | `Grid.test.tsx` exact track tests and exact-head AuditMatrix story guards | fixed; fill; fit; capped wide/narrow; uniform/axis gap   | Track output, count, fill behavior, or gap precedence changes fail exact source or browser checks. | `audit:Grid/behavior`     |
-| FR4, FR6, ORD3  | root composition tests, BaseProps lint, theming target tests              | DOM/data/ARIA/events; class/style/xstyle; reflected axes | A caller input drops, owned metadata is replaced, or a raw inline track defeats media xstyle.      | `audit:Grid/api`          |
-| FR5, ORD4, AR3  | `Grid.test.tsx`, long-content play, and AuditMatrix full-span assertion   | numeric/full/row/combined spans; long shrinkable child   | Span CSS, explicit-grid coverage, target, or bounded shrink behavior changes.                      | `audit:GridSpan/behavior` |
-| FR7, AR1–AR2    | DOM tests and exact-head LTR/RTL AuditMatrix guards                       | plain roots; fixed tracks in LTR/RTL                     | A semantic role appears, DOM order changes, or logical order stops mirroring.                      | `audit:Grid/a11y-rtl`     |
-| Theming anatomy | knowledge validation and `themingTargets.test.ts`                         | Grid and GridSpan targets                                | A target loses its semantic owner or the anatomy map drifts.                                       | `audit:Grid/theming`      |
-| Documentation   | docs typecheck, prop literal/reference tests, and Storybook typecheck     | fixed/responsive columns; row height; spans              | Docs claim equal widths, automatic numeric reflow, whole implicit rows, or omit public behavior.   | `audit:Grid/docs`         |
+| 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
 
@@ -187,4 +189,5 @@ None.
 
 ## Content boundary
 
-This file records verified shipped behavior. It does not duplicate consumer prop tables or examples, prescribe caller content or visuals, approve a new API or target, or store audit scores and run evidence.
+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

@@ -0,0 +1,158 @@
+---
+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.