# Layout Patterns Layer

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

## Goal

Add a dedicated `patterns` layer inside `@ai-ui/ui` for reusable page and shell structures that
sit above base components: `SidebarNav`, `PageHeader`, `AppShell`, and `PageFooter`.

## Scope

- In scope:
  - create `packages/ui/src/patterns/`
  - implement `SidebarNav`, `PageHeader`, `AppShell`, and `PageFooter`
  - export the new patterns from `@ai-ui/ui`
  - add Storybook docs under `Patterns/*`
  - refactor the revenue dashboard scene to consume the new patterns where they fit
  - add focused tests for the public slot and state contract
- Out of scope:
  - splitting a second npm package for patterns
  - adding router-aware or data-source-aware app shells
  - replacing every existing layout composition across the repo in one slice

## Constraints

- Keep `components` as the lower layer and allow `patterns` to depend on `components`, not the reverse.
- Follow `DESIGN.md` and reuse the existing token and motion system instead of inventing a separate layout skin.
- Keep APIs compound and slot-oriented so different pages can restyle the same patterns.
- Use Storybook titles under `Patterns/*` so the review surface reflects the new layer clearly.

## Affected Surfaces

- `packages/ui/src/patterns`
- `packages/ui/src/index.ts`
- `apps/docs/src/patterns`
- `apps/docs/src/revenue-dashboard.stories.tsx`
- `docs/exec-plans`

## Plan

1. Create the new `patterns` directory and implement the four shared layout patterns with stable
   slots and restrained variant surfaces.
2. Export the patterns from `@ai-ui/ui` without moving the existing base components.
3. Add docs stories under `Patterns/*` that explain when to use each pattern.
4. Refactor the revenue dashboard scene to consume `SidebarNav`, `PageHeader`, and `AppShell`, and
   use `PageFooter` where it adds real value.
5. Add focused tests and run the narrowest useful validation suites.

## Validation

- `pnpm --filter @ai-ui/ui test -- sidebar-nav page-header page-footer app-shell`
- `pnpm --filter @ai-ui/ui typecheck`
- `pnpm build:docs`

## Orchestration Task Sketch

- `T1`: implement the new `patterns` layer and exports
- `T2 -> T1`: add docs stories for the four patterns
- `T3 -> T2`: refactor the revenue dashboard consumer and run focused validation

## Status Log

- `2026-03-25 16:48` started the patterns-layer slice after confirming the repo has component-internal headers and footers but no dedicated page-shell layer for shared layout structures
- `2026-03-25 17:06` implemented the new `packages/ui/src/patterns/` layer with `SidebarNav`, `PageHeader`, `PageFooter`, and `AppShell`, then exported the new public surface from `@ai-ui/ui`
- `2026-03-25 17:10` added Storybook docs under `Patterns/*` and refactored the revenue dashboard scene to consume the new shell and page patterns
- `2026-03-25 17:12` validated exact new pattern tests, workspace typecheck, and Storybook production build; the broader `pnpm --filter @ai-ui/ui test -- ...` entrypoint still pulls in unrelated in-flight `combobox` and `command` failures from concurrent work