An open source design system that's fully customizable and agent ready
TypeScript
docs(spec): Grid records its shipped contract as current (#8800)
Cindy Zhang2b0f9a19f77f
diff --git a/docs/families/layout-primitives.md b/docs/families/layout-primitives.mdindex bdb62dd77c..d661f32d2f 100644--- a/docs/families/layout-primitives.md+++ b/docs/families/layout-primitives.md@@ -154,15 +154,15 @@ component does not join merely because its source uses flexbox or grid.## Representative matrix-| Member and state | Shared invariant | Deliberate variation |-| ------------------------------ | ------------------------------------------------------------------- | ----------------------------------------------------------------- |-| Stack / vertical or horizontal | Shared spacing and sizing values; direction resolves alignment axes | May wrap, scroll, or render a chosen element |-| HStack or VStack | Same Stack contract with a fixed direction | Narrower alignment types match the fixed axes |-| StackItem / `size="fill"` | One child may consume remaining Stack space | `isScrollable` pairs overflow with StackItem's flex minimum reset |-| Grid / fixed columns | Shared size and gap values | Explicit equal-width track count (`columns={N}`); never reflows |-| Grid / intrinsic columns | Shared size and gap values | `{minWidth, max?, repeat?}` constructs fluid tracks that reflow |-| GridSpan / columns or rows | Modifier participates in Grid | Spans tracks rather than controlling parent geometry |-| Center / one or both axes | Shared size and padding values | Needs available size on an axis before centering is observable |+| Member and state | Shared invariant | Deliberate variation |+| ------------------------------ | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |+| Stack / vertical or horizontal | Shared spacing and sizing values; direction resolves alignment axes | May wrap, scroll, or render a chosen element |+| HStack or VStack | Same Stack contract with a fixed direction | Narrower alignment types match the fixed axes |+| StackItem / `size="fill"` | One child may consume remaining Stack space | `isScrollable` pairs overflow with StackItem's flex minimum reset |+| Grid / fixed columns | Shared size and gap values | Explicit count of `1fr` tracks (`columns={N}`); never reflows; minimum content may widen a track |+| Grid / intrinsic columns | Shared size and gap values | `{minWidth, max?, repeat?}` constructs fluid tracks that reflow |+| GridSpan / columns or rows | Modifier participates in Grid | Spans tracks rather than controlling parent geometry |+| Center / one or both axes | Shared size and padding values | Needs available size on an axis before centering is observable |## Adoption and exceptionsdiff --git a/packages/core/src/Grid/Grid.spec.md b/packages/core/src/Grid/Grid.spec.mdindex 9136dcc210..84f51f0fbf 100644--- a/packages/core/src/Grid/Grid.spec.md+++ b/packages/core/src/Grid/Grid.spec.md@@ -3,20 +3,21 @@ schema_version: 3template_version: 7kind: componentid: component:Grid-authority: draft+authority: currentarchive_reason: nullsuperseded_by: null-approved_by: null-approved_at: null+approved_by: cixzhang+approved_at: 2026-10-28owners: [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.diff --git a/packages/core/src/Grid/GridSpan.spec.md b/packages/core/src/Grid/GridSpan.spec.mdnew file mode 100644index 0000000000..b457f55492--- /dev/null+++ b/packages/core/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.