cadence-ui/docs/exec-plans/2026-03-25-layout-patterns-layer.md

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