# 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`