69 lines
3.1 KiB
Markdown
69 lines
3.1 KiB
Markdown
# 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
|