cadence-ui/docs/exec-plans/2026-03-25-grid-primitives.md

Grid Primitives

• Status: completed
• Owner: codex
• Date: 2026-03-25

Goal

Add Cadence UI source-owned Row / Col grid primitives so product and docs surfaces can build responsive split layouts and dashboard sections without repeating ad hoc width math, alignment fixes, or one-off grid-cols-* strings.

Scope

• In scope:
  • add public Row and Col primitives to packages/ui
  • support a 12-column responsive layout model with tokenized gaps
  • support base plus breakpoint-specific span and offset placement on Col
  • expose stable slot and data-* hooks
  • document the primitives in Storybook
  • add unit coverage for the main layout contract
• Out of scope:
  • nested layout orchestration helpers such as SplitPanel or dialog-specific shells
  • CSS container-query driven layout APIs
  • ordering, push/pull, or visual reordering props that can drift from DOM order
  • replacing every existing docs layout in this pass

Constraints

• Keep the API small and familiar to teams coming from Ant Design / Element style Row / Col.
• Stay token-first for spacing instead of baking new hardcoded per-story gutters.
• Preserve DOM order as the semantic order; layout props should not encourage accessibility drift.
• Avoid introducing an external layout framework or dependency for this capability.

Affected Surfaces

• packages/ui/src/components
• packages/ui/src/index.ts
• packages/ui/src/lib/contracts.ts
• packages/ui/src/skins.css
• apps/docs/src/components
• docs/exec-plans
• registry/index.json

Plan

1. Add the execution plan and define a minimal Cadence UI grid contract.
2. Implement Row and Col with a 12-column base, tokenized gap sizes, and responsive span / offset placement.
3. Export the primitives on the public surface and document them in Storybook with usage, anatomy, and accessibility guidance.
4. Add focused unit coverage, run narrow validation, then rebuild registry metadata for the new public entrypoint.

Validation

• pnpm --filter @ai-ui/ui test -- grid
• pnpm build:docs
• pnpm registry:build

Orchestration Task Sketch

• T1: implement the grid primitives, skins, and public exports
• T2 -> T1: add Storybook docs, tests, and rebuild registry metadata

Status Log

• 2026-03-25 16:18 started after confirming the repo has many direct grid utility usages but no reusable source-owned layout primitive for responsive row/column composition
• 2026-03-25 18:54 implemented public Row / Col primitives, exported them from @ai-ui/ui, added Storybook coverage, and registered the new source-owned grid entrypoint
• 2026-03-25 18:56 validated with pnpm --filter @ai-ui/ui test -- grid, pnpm --filter @ai-ui/ui build, pnpm build:docs, and pnpm registry:build