An open source design system that's fully customizable and agent ready
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, apps/storybook/stories/GridSpan.stories.tsx, packages/core/src/Grid/tests/GridSpanAudit.a11y.chromium.spec.ts, apps/storybook/rtl-audit/targets.json, ] modules: [] families: [family:layout-primitives] 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 thegrid-spantarget thatcomponent:Gridpublishes 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:GridFR1.
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-primitivesFR6 names GridSpan the participation modifier for Grid; its behavior outside a Grid is this record's.component:Gridowns the tracks GridSpan spans.architecture:public-component-apiowns 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; GridSpanAudit.a11y.chromium.spec.ts on GridSpan.stories.tsx; the GridSpan order target in rtl-audit/targets.json |
Numeric, full, row, combined, none; LTR and RTL | A wrong inline grid-column or grid-row, a span set when none is given, or a lost grid-span target fails the unit suite. A lost one-track inner grid or zero minimum width, or a span that does not cover two tracks and a gap, every explicit column, or two rows and a gap from the inline start, fails the browser spec; a row span that stops taking effect or mirroring fails the RTL order target. Gap: the full height has no check distinct from the grid's default stretch. |
audit:GridSpan/layout |
| FR3 | Grid.test.tsx GridSpan ref, passthrough, style-precedence, and styling-input tests |
Ref; extra props; caller style; className and xstyle |
A ref that resolves to anything but the span element, a dropped aria-label, a caller style that replaces a span, a lost caller placement when no span is set, or a className or xstyle that is dropped or merges before the component styles fails. |
audit:GridSpan/api |
| AR2 | Grid.stories.tsx long-content play and AuditMatrix full-span check; GridSpanAudit.a11y.chromium.spec.ts long-content case |
Long shrinkable child; full span | Content escaping its track or a full span missing explicit columns fails the play; a span or truncating child escaping its 240px host fails the browser spec. | audit:GridSpan/layout |
| AR1, PR1 | serverSafeComponents.test.ts; Grid.test.tsx no-role test; GridSpanAudit.a11y.chromium.spec.ts |
Every state | A client API added without a client directive fails serverSafeComponents.test.ts; a role, accessible name, or tab stop on the span fails the unit test and the browser spec. Gap: a client API added together with a client directive passes. |
audit:GridSpan/behavior |
Decision log
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.