Grid foundation

See the usage handbook and Grid contract for practical usage.

@gridui/grid owns Container, Grid, GridItem, Split, Stack, Row, PageFrame, FrameSections, FrameSection, frame chrome, rails, textures, and structural boundaries. It does not know website routes or domain state. Load its explicit styles.css export after theme styles and before Layout. Theme supplies token values; @gridui/style-utils/responsive supplies the React-free spacing and breakpoint-value calculations.

Use Grid for two-dimensional tracks and Split for a linear, non-wrapping sequence of regions. Split's direction and seam accept scalar or responsive values; it owns only the seam between direct child regions. Put functional controls and tables inside those regions so their own borders remain intact. See linear regions for the full contract.

FrameSection and FrameFooter accept tone="neutral" | "brand" | "warning" | "danger". Non-neutral tones scope background, foreground, muted text, borders, controls, and focus colors to that region. Theme owns the paired light/dark tokens; Grid owns their inherited application. Nested non-neutral tones establish their own palette; neutral inherits its surroundings.

FrameSection owns its leading separator and inline frame edges. Use boundary="none" and edges="none" when an enclosing region owns them. Both FrameSection and FrameFooter accept these leading boundary styles:

| boundary | Appearance | | --- | --- | | line (default) | One thin rule | | band | Theme-tinted 12px band with top and bottom rules | | stripe | The same band geometry with continuous 135-degree brand-colored stripes | | space | Transparent 40px spacing with no rules or fill | | none | No boundary element or extra spacing |

--gridui-band-size owns band and stripe height; --gridui-boundary-space-size owns whitespace height. Stripe and space default to no edge decoration. Band still defaults to nodes. Set decoration explicitly to choose an edge treatment.

<FrameSection boundary="stripe">Next chapter</FrameSection>
<FrameSection boundary="space">Related reading</FrameSection>

At a section seam, a non-neutral tone takes precedence over neutral; between two non-neutral tones, the lower section supplies the color. The lower section still draws the only separator. This works across React section groups without changing either region's content palette. Astro host elements require an application-owned adapter. The page filler uses the final section's tone for its leading line. Grid frame="cells" owns outer and cell edges; frame="internal" owns seams inside an existing frame. Use fillLastRow with direct GridItem children to fill incomplete rows at every breakpoint. Explicit gaps are disallowed in framed grids. Hover/focus outlines paint above neighboring seams and page lines. Table cell lines remain Data-owned and control borders remain Controls-owned.

See the Grid contract for geometry and API.

Source organization

The package root src/index.ts declares the public API, and src/styles.css imports component styles. Neither entry point contains component implementation.

• primitives/ groups Container, Grid/GridItem with track planning, Split, Stack, and Row with their own styles. responsive.ts retains only column, track, and span geometry; shared responsive spacing comes from Style-utils. geometry.css owns the shared Container/frame-rail tracks.
• frame/ groups page hosts, chrome, rails, boundaries, decorations, and textures with their CSS and variants. section.tsx composes those groups. Only shared content styles and tone variants remain in frame/style.ts; tone.css owns inherited region colors. Primitives never import Frame.

Cross-package browser fixtures live in root scripts/development/preview/fixtures and use public exports. Browser specifications live separately in scripts/testing/browser/specs.

Unit tests mirror these owners under test/unit/primitives/ and test/unit/frame/. Tests can combine public primitives to protect their collaboration. Keep ordinary presentation in the owner's CVA style.ts. Retain track resolution, seams, and decorative geometry in colocated CSS imported by the root stylesheet. See the shared style organization contract. Consumers use the package root and explicit stylesheet export; internal file paths are private.

See quarterly release history for prepared release notes and consumption records.