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, FrameRegion/FrameRegionRow for composed edge geometry, and the public FrameBoundary primitive for structural boundaries. It does not know website routes or domain state. Load its explicit styles.css export after Theme and before styles of composed families. 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 reuse Theme's public paletteClass contract for background, foreground, muted text, borders, controls, and focus colors. Theme owns both palette values and their scoped semantic mapping; Grid owns region geometry. Nested non-neutral tones establish their own palette; tone="neutral" continues to inherit its surroundings. Use paletteClass("neutral") from @gridui/theme on a native content surface for an explicit reset to registered application neutral colors without adding a section or boundary.

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:

--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. For wrapping lists with a container-driven track count, use columns="auto" with minItemWidth and optional responsive gap. The minimum is capped to available space. Grid asChild and GridItem asChild preserve native ul/ol/li hosts without wrapper elements. Adaptive mode excludes frames and fillLastRow; root asChild also excludes fillLastRow, preserving the fixed planner's direct-item contract. Hover/focus outlines paint above neighboring seams and page lines. Table cell lines belong to Table; functional control borders belong to their Core families.

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.

Every public component owns a matching directory, such as src/grid/, src/grid-item/, src/split/, and src/frame-section/. Private parts, styles, and helpers stay beside their owner. src/shared/ contains only collaborators used by multiple components: track planning, inherited frame geometry, region tones, and shared boundary/chrome rules. Responsive spacing comes from Style-utils.

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 source conventions. 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.

DashboardFrame supplies full-height workspace gutters and structural edges without creating a main landmark. See dashboard frames.