@withmata/blueprints 0.3.4 → 0.4.0

package/blueprints/features/ui-shared-components/BLUEPRINT.md

@@ -1,29 +1,27 @@
-# UI Shared Components Blueprint — shadcn/ui + Monorepo
+# UI Shared Components Blueprint — Base UI + shadcn/ui Component Library
 
 ## Tier
 
 Feature
 
-## Status
+## Problem
 
-Complete.
+Building a UI component library for a TypeScript project requires solving several hard problems at once: accessible headless primitives, a variant system that scales, styling that works across package boundaries, and a component authoring pattern that balances consistency with flexibility. Teams either adopt a full component library and fight its opinions, or build from scratch and lose months on accessibility and API design. This blueprint provides 31 production-ready components built on Base UI headless primitives, a compound component architecture with `data-slot` CSS targeting, CVA-driven variant systems, and full shadcn CLI compatibility for adding more components — all exported as TypeScript source with no build step.
 
-## Problem
+## Status
 
-Sharing UI components across multiple apps in a monorepo requires careful package structure, export patterns, and styling integration. Without a standard setup, teams duplicate components, fight build tooling issues, and waste time wiring shadcn/ui to work in a workspace package. This blueprint creates a `packages/ui/` package with path-based exports, shadcn CLI compatibility, and proper Tailwind style integration.
+Complete.
 
 ## Blueprint Dependencies
 
 | Blueprint | Type | Why |
 |-----------|------|-----|
-| `features/tailwind-v4` | required | UI components depend on design tokens and theme setup. Without it, components lack consistent styling. |
-| `foundation/monorepo-turbo` | recommended | Provides workspace structure, TypeScript config, and package conventions. Without it, the UI package is created as a local directory. |
+| `features/tailwind-v4` | required | Components depend on design tokens, theme variables, and animation classes from the Tailwind design system. Without it, component styles break or fall back to browser defaults. |
+| `foundation/monorepo-turbo` | recommended | Provides workspace structure, TypeScript config, and package conventions. Without it, components are created as a local directory with direct imports instead of workspace packages. |
 
 ### If `tailwind-v4` is not installed
 
-The scaffold command should ask: "UI components need the Tailwind design system. Install tailwind-v4 first? (Y/n)"
-
-If declined, scaffold with basic Tailwind defaults and warn about missing design tokens.
+The scaffold command automatically installs the Tailwind design system as a prerequisite — no user prompt needed. The design system (tokens, animations, typography) is a hard requirement for component styling. The scaffold skill runs the tailwind-v4 blueprint inline before proceeding with UI scaffolding.
 
 ---
 
@@ -31,23 +29,37 @@ If declined, scaffold with basic Tailwind defaults and warn about missing design
 
 ### Core Pattern
 
-The UI package is a workspace package (`packages/ui/`) that exports components, utilities, styles, and icons via **path-based exports** in `package.json`. Consuming apps import directly from specific paths (`@scope/ui/components/ui/button`) rather than through barrel re-exports. This enables better tree-shaking and clearer dependency graphs.
+The UI package is a workspace package (`packages/ui/`) that exports 31 base components, utilities, styles, and icons via **path-based exports** in `package.json`. Components are built on **Base UI** (`@base-ui/react`) headless primitives with **CVA** for variant management and the **compound component pattern** for complex UI elements. Every component and sub-component receives a `data-slot` attribute for CSS targeting. Consuming apps import directly from specific paths (`@scope/ui/components/ui/button`) rather than through barrel re-exports.
 
-Components use shadcn/ui conventions: Radix UI primitives for accessibility, `class-variance-authority` for variant management, and the `cn()` utility for class merging.
+The library ships with a custom **`base-maia` shadcn style** so that `shadcn add` generates Base UI components (not Radix) that are compatible with the existing library.
 
 ### Key Decisions
 
+- **Base UI as primary headless library** (required) — Base UI (`@base-ui/react`) is built by the same team that created Radix, with a modernized API. It uses `data-*` attributes for state instead of Radix's `data-[state=*]` convention, which produces cleaner CSS selectors. It provides first-class render props for polymorphism instead of the `asChild` pattern. Every new component in this blueprint uses Base UI primitives.
+
+- **Legacy Radix for popover and collapsible** (current state) — `collapsible.tsx` and `popover.tsx` still use Radix primitives because Base UI equivalents are not yet available or stable. These components work correctly alongside Base UI components. They can be migrated to Base UI when those primitives ship.
+
+- **`data-slot` attribute convention** (required) — Every component root and sub-component element gets `data-slot="component-name"`. This enables CSS targeting via `[data-slot=button]` selectors, which are more stable than class-based selectors that break when Tailwind classes change. It also enables parent components to style children without prop drilling.
+
+- **Compound component pattern** (required) — Complex components export multiple named parts that consumers compose freely. For example, `Card` exports `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardAction`, `CardContent`, and `CardFooter`. This gives consumers full control over layout and ordering while keeping each part's styling encapsulated.
+
+- **Phosphor Icons** (recommended) — Richer icon set than Lucide with six weights per icon (regular, bold, duotone, fill, light, thin). Tree-shakeable via deep imports (`@phosphor-icons/react/ArrowRight`). Consistent API across all icons. Can be swapped to Lucide or any other library.
+
 - **Path-based exports** (required) — Instead of `import { Button } from "@scope/ui"`, use `import { Button } from "@scope/ui/components/ui/button"`. This avoids barrel export issues, enables per-component tree-shaking, and makes dependencies explicit. Package.json uses wildcard exports (`"./components/*": "./components/*.tsx"`).
 
 - **Subpath imports with `#` prefix** (required) — Internal imports within the UI package use Node.js subpath imports (`#components/ui/button`). This provides clean paths without TypeScript path aliases and works natively with Node.js module resolution.
 
-- **shadcn CLI compatibility** (required) — The `components.json` file configures shadcn to generate components in the correct locations within the UI package. Run `pnpm dlx shadcn@latest add <component>` from `packages/ui/` to add new components.
+- **Blueprint-owned vs user-owned components** (required) — The 31 template components shipped with this blueprint are blueprint-owned. They can be updated during `/scaffold-ui` upgrade mode. Components added via `shadcn add` are user-owned and never touched by upgrades. This separation allows the library to evolve without overwriting user customizations.
+
+- **`base-maia` shadcn style** (recommended) — A custom shadcn style that generates Base UI components instead of Radix. Required for `shadcn add` to produce components compatible with the existing library. Configured in `components.json`. Can be changed to `new-york` or `default` if Radix compatibility is preferred.
 
 - **No build step** (required) — The UI package exports TypeScript source directly (`.tsx` files). Consuming Next.js apps transpile via their own bundler. This eliminates a build step and enables hot module replacement for components during development.
 
-- **`cn()` utility** (required) — Combines `clsx` for conditional classes and `tailwind-merge` for deduplication. Every component should use `cn()` for className composition. Located at `utils/cn.ts`.
+- **`cn()` utility** (required) — Combines `clsx` for conditional classes and `tailwind-merge` for deduplication. Every component uses `cn()` for className composition. Located at `utils/cn.ts`.
+
+- **CVA for variants** (required) — `class-variance-authority` for defining component variants. Re-exported from `utils/cva.ts` for consistency. Button alone has 6 variants x 8 sizes. Badge has 6 variants. Sidebar has multiple CVA-driven sub-component styles.
 
-- **CVA for variants** (recommended) — `class-variance-authority` for defining component variants (size, color, style). Re-exported from `utils/cva.ts` for consistency.
+- **Form system** (recommended) — `Field` (compound form field layout), `FormField` (higher-order field with hint popover system using IntersectionObserver for scroll detection and auto-show on focus), `TagInput` (controlled tag input with chips, max items, duplicate detection), and `PillSelect` (generic single-select pill buttons with search, collapse/expand, deselect) form a cohesive form building system.
 
 - **Separate `icons/` directory** (recommended) — SVG icons and brand logos in their own directory with path-based exports (`@scope/ui/icons/Logo`). Keeps component imports clean.
 
@@ -58,19 +70,91 @@ Components use shadcn/ui conventions: Radix UI primitives for accessibility, `cl
 ## Hard Requirements vs Recommended Defaults
 
 **Hard requirements:**
+- Base UI as the headless primitive layer
+- `data-slot` attribute on every component and sub-component
+- Compound component pattern for complex components
 - Path-based exports (no barrel re-exports for components)
 - shadcn/ui CLI compatibility (`components.json`)
 - `cn()` utility using clsx + tailwind-merge
+- CVA for variant management
 - TypeScript source exports (no build step)
 - Styles import chain through tailwind-config
+- `#` subpath imports for internal references
 
 **Recommended defaults — ask during scaffolding:**
 
 | Choice | Recommended | Alternatives |
 |---|---|---|
-| shadcn style | `"new-york"` | `"default"` or any shadcn style |
-| Icon library | `"lucide"` | `"phosphor"`, `"radix"`, or custom |
-| Include CVA utility | Yes | No |
+| shadcn style | `"base-maia"` | `"new-york"`, `"default"`, or any shadcn style |
+| Icon library | `"phosphor"` | `"lucide"`, `"radix"`, or custom |
+| Include base components | Yes (all 31) | No (skeleton only — empty `components/ui/`) |
+| Include form system | Yes | No (skip `form-field`, `field`, `tag-input`, `pill-select`) |
+| Which consuming apps get globals.css update | Ask during scaffolding | — |
+
+---
+
+## Components
+
+### Primitives (no internal UI deps)
+
+| Component | File | Headless Primitive | Notes |
+|---|---|---|---|
+| Button | `button.tsx` | Base UI `ButtonPrimitive` | 6 variants (default, destructive, outline, secondary, ghost, link) x 8 sizes. CVA-driven. |
+| Input | `input.tsx` | Base UI `InputPrimitive` | Standard text input with `data-slot="input"`. |
+| Label | `label.tsx` | Native `<label>` | Styled label with `data-slot="label"`. |
+| Textarea | `textarea.tsx` | Native `<textarea>` | Auto-styled textarea with `data-slot="textarea"`. |
+| Badge | `badge.tsx` | Base UI `useRender` | 6 variants. Polymorphic via render prop — can render as links, buttons, etc. |
+| Separator | `separator.tsx` | Base UI `SeparatorPrimitive` | Horizontal/vertical with `data-slot="separator"`. |
+
+### Compound Components
+
+| Component | File | Headless Primitive | Exports |
+|---|---|---|---|
+| Card | `card.tsx` | None (semantic HTML) | 7 parts: Card, CardHeader, CardTitle, CardDescription, CardAction, CardContent, CardFooter |
+| Alert Dialog | `alert-dialog.tsx` | Base UI `AlertDialogPrimitive` | 12 parts including AlertDialogMedia for icons/illustrations |
+| Select | `select.tsx` | Base UI `SelectPrimitive` | 10 parts with Portal/Positioner, scroll buttons |
+| Combobox | `combobox.tsx` | Base UI `ComboboxPrimitive` | 16 exports with chips support, InputGroup integration |
+| Dropdown Menu | `dropdown-menu.tsx` | Base UI `MenuPrimitive` | 15 exports with sub-menus, checkbox items, radio items |
+| Sidebar | `sidebar.tsx` | Context-based | 14 exports with cookie persistence, CVA variants for width/behavior |
+| Field | `field.tsx` | None (compound layout) | 10 parts: Field, FieldGroup, FieldSet, FieldLabel, FieldDescription, FieldError, FieldSeparator, FieldContent, FieldTitle, FieldLegend |
+| Input Group | `input-group.tsx` | None (compound layout) | 6 parts: InputGroup, InputGroupAddon, InputGroupButton, InputGroupText, InputGroupInput, InputGroupTextarea |
+
+### Navigation/Utility
+
+| Component | File | Headless Primitive | Notes |
+|---|---|---|---|
+| Breadcrumb | `breadcrumb.tsx` | Base UI `useRender` | 7 exports. Polymorphic links via render prop. |
+| Collapsible | `collapsible.tsx` | Radix `CollapsiblePrimitive` | Legacy Radix — awaiting Base UI port. |
+| Popover | `popover.tsx` | Radix `PopoverPrimitive` | Legacy Radix — forwardRef pattern. Awaiting Base UI port. |
+
+### Composed Form Widgets
+
+| Component | File | Deps | Notes |
+|---|---|---|---|
+| Form Field | `form-field.tsx` | Field, Popover | Higher-order FormField with hint popover system. `FieldHint` interface, IntersectionObserver for scroll detection, auto-show hints on focus. |
+| Tag Input | `tag-input.tsx` | Button | Controlled tag input with chips, max items, duplicate detection, counter display. |
+| Pill Select | `pill-select.tsx` | Button, Input | Generic single-select pill buttons with search, collapse/expand, deselect support. |
+| Card Select | `card-select.tsx` | Badge | Grid of selectable option cards with label + description. Configurable columns (2/3/4), disabled state with badge label. |
+| Entity Select | `entity-select.tsx` | Combobox | Generic type-safe combobox with render props for options/selected state, "Create new" action, loading/empty states. |
+| Selected Entity Card | `selected-entity-card.tsx` | Button | Compact card showing a selected entity with remove button and optional edit action. Companion to EntitySelect. |
+
+### Data Display
+
+| Component | File | Deps | Notes |
+|---|---|---|---|
+| Pagination | `pagination.tsx` | Button | Offset-based prev/next pagination with "Showing X-Y of Z" display. Auto-hides when total ≤ limit. |
+| Empty State | `empty-state.tsx` | Button | Centered layout with icon circle, heading, description, and optional CTA button. For empty lists/tables. |
+| Avatar | `avatar.tsx` | None | Image with initials fallback, error handling. CVA-driven size variants (xs/sm/default/lg/xl). |
+
+### App Shell & Layout
+
+| Component | File | Deps | Notes |
+|---|---|---|---|
+| User Menu | `user-menu.tsx` | Sidebar, DropdownMenu, Avatar | Sidebar footer user menu with avatar, name/email, dropdown actions (profile, settings, sign out). Adapts to collapsed sidebar state. |
+| Org Switcher | `org-switcher.tsx` | DropdownMenu, Button | Organization switcher dropdown with current org display, switch list with check indicator, and "Create Organization" action with PlusIcon. |
+| Page Header | `page-header.tsx` | Button | Page title + description + action button (defaults to PlusIcon). Standard header for list/entity pages. |
+| Status Filter | `status-filter.tsx` | Button | Pill-style filter tabs toggling active variant. Supports optional count display. Generic for any status enum. |
+| Search Input | `search-input.tsx` | Input | Debounced search input with MagnifyingGlass icon. Configurable delay (default 300ms). |
 
 ---
 
@@ -81,19 +165,23 @@ Components use shadcn/ui conventions: Radix UI primitives for accessibility, `cl
 **packages/ui:**
 | Package | Version | Purpose |
 |---|---|---|
-| `{{SCOPE}}/tailwind-config` | `workspace:*` | Shared design tokens |
-| `@radix-ui/react-slot` | ^1.2 | Polymorphic component support (asChild pattern) |
-| `class-variance-authority` | ^0.7 | Component variant management |
-| `clsx` | ^2.1 | Conditional className utility |
-| `tailwind-merge` | ^3 | Smart Tailwind class deduplication |
-| `tw-animate-css` | ^1 | Animation classes |
-| `react` | ^19 | React |
-| `react-dom` | ^19 | React DOM |
-| `shadcn` | ^3 | Component generation CLI |
+| `@base-ui/react` | ^1.0.0 | Headless UI primitives (Button, Input, Select, Combobox, Menu, AlertDialog, Separator, Badge) |
+| `@phosphor-icons/react` | ^2.1.10 | Icon library with 6 weights per icon |
+| `@radix-ui/react-collapsible` | ^1.1.12 | Collapsible primitive (legacy, pending Base UI port) |
+| `@radix-ui/react-popover` | ^1.1.15 | Popover primitive (legacy, pending Base UI port) |
+| `@radix-ui/react-slot` | ^1.2.4 | Polymorphic component support (used by some composed components) |
+| `class-variance-authority` | ^0.7.1 | Component variant management |
+| `clsx` | ^2.1.1 | Conditional className utility |
+| `tailwind-merge` | ^3.4.0 | Smart Tailwind class deduplication |
+| `tw-animate-css` | ^1.4.0 | Animation classes for transitions |
+| `shadcn` | ^3.6.2 | Component generation CLI |
+| `react` | ^19.1.0 | React |
+| `react-dom` | ^19.1.0 | React DOM |
 
 **packages/ui (dev):**
 | Package | Version | Purpose |
 |---|---|---|
+| `{{SCOPE}}/tailwind-config` | `workspace:*` | Shared design tokens |
 | `{{SCOPE}}/typescript-config` | `workspace:*` | Shared TypeScript config |
 | `@tailwindcss/postcss` | ^4 | PostCSS plugin |
 | `tailwindcss` | ^4 | Tailwind CSS |
@@ -132,7 +220,27 @@ Components use shadcn/ui conventions: Radix UI primitives for accessibility, `cl
 ```
 packages/ui/
 ├── components/
-│   └── ui/                    # shadcn-generated components go here
+│   └── ui/                    # 31 base components (blueprint-owned)
+│       ├── button.tsx
+│       ├── input.tsx
+│       ├── label.tsx
+│       ├── textarea.tsx
+│       ├── badge.tsx
+│       ├── separator.tsx
+│       ├── card.tsx
+│       ├── alert-dialog.tsx
+│       ├── select.tsx
+│       ├── combobox.tsx
+│       ├── dropdown-menu.tsx
+│       ├── sidebar.tsx
+│       ├── field.tsx
+│       ├── input-group.tsx
+│       ├── breadcrumb.tsx
+│       ├── collapsible.tsx
+│       ├── popover.tsx
+│       ├── form-field.tsx
+│       ├── tag-input.tsx
+│       └── pill-select.tsx
 ├── icons/
 │   └── logos/                 # Brand logos (SVG as React components)
 ├── styles/
@@ -140,7 +248,7 @@ packages/ui/
 ├── utils/
 │   ├── cn.ts                  # Class merging utility
 │   └── cva.ts                 # CVA re-export
-├── components.json            # shadcn CLI config
+├── components.json            # shadcn CLI config (base-maia style)
 ├── package.json               # Exports, imports, deps
 └── tsconfig.json              # Extends shared react-library config
 ```
@@ -162,8 +270,9 @@ The `@source` directive tells Tailwind to scan the UI package for classes. The r
 **Usage in components:**
 ```typescript
 import { Button } from "{{SCOPE}}/ui/components/ui/button";
+import { Card, CardHeader, CardTitle, CardContent } from "{{SCOPE}}/ui/components/ui/card";
 import { cn } from "{{SCOPE}}/ui/utils/cn";
-import { Logo } from "{{SCOPE}}/ui/icons/logos/Logo";
+import { ArrowRight } from "@phosphor-icons/react/ArrowRight";
 ```
 
 ---
@@ -176,20 +285,26 @@ For standalone applications without a monorepo, UI components live alongside the
 
 | Aspect | Monorepo | Single-Repo |
 |--------|----------|-------------|
-| UI code location | `packages/ui/` (workspace package) | `src/ui/` or `src/components/` |
+| UI code location | `packages/ui/` (workspace package) | `src/ui/` |
+| Component location | `packages/ui/components/ui/` | `src/ui/components/ui/` |
 | Import pattern | `import { x } from "@scope/ui/components/ui/button"` | `import { x } from "@/ui/components/ui/button"` |
 | Package dependencies | `workspace:*` protocol | Direct — packages at root `package.json` |
 | TypeScript config | Extends `@scope/typescript-config/react-library.json` | Inherits from root `tsconfig.json` |
 | Styles import | `@import "{{SCOPE}}/ui/styles"` in consuming app | Not needed (same bundle) |
 | `@source` directive | Required (cross-package scanning) | Not needed (same project) |
 | shadcn CLI | Run from `packages/ui/` | Run from project root |
+| `package.json` / `tsconfig.json` | `packages/ui/package.json` + `packages/ui/tsconfig.json` | N/A (use root configs) |
 
 ### What Stays the Same
 
+- Base UI headless primitives and `data-slot` convention
+- Compound component pattern and component API shapes
 - Path-based exports pattern (via `package.json` exports or TypeScript paths)
-- `cn()` utility and CVA pattern
-- `components.json` for shadcn CLI
+- `cn()` utility and CVA patterns
+- `components.json` for shadcn CLI (base-maia style)
 - Component file organization (`components/ui/`, `icons/`, `utils/`)
+- All 31 base components — identical source files
+- Phosphor Icons integration
 
 ---
 
@@ -197,12 +312,48 @@ For standalone applications without a monorepo, UI components live alongside the
 
 | File | Purpose | Monorepo Target | Single-Repo Target |
 |---|---|---|---|
-| `files/ui/styles/globals.css` | UI package styles (imports tailwind-config) | `packages/ui/styles/globals.css` | `src/ui/styles/globals.css` |
+| **Config/Utilities** | | | |
+| `files/ui/package.json` | Package config with exports, imports, deps, Base UI + Radix + Phosphor dependencies | `packages/ui/package.json` | N/A (merge deps into root `package.json`) |
+| `files/ui/tsconfig.json` | TypeScript config extending shared react-library base | `packages/ui/tsconfig.json` | N/A (use root `tsconfig.json`) |
+| `files/ui/components.json` | shadcn CLI configuration with `base-maia` style | `packages/ui/components.json` | `components.json` (project root) |
+| `files/ui/styles/globals.css` | UI package styles (imports tailwind-config, animation classes) | `packages/ui/styles/globals.css` | `src/ui/styles/globals.css` |
 | `files/ui/utils/cn.ts` | Class merging utility (clsx + tailwind-merge) | `packages/ui/utils/cn.ts` | `src/ui/utils/cn.ts` |
 | `files/ui/utils/cva.ts` | CVA re-export for component variants | `packages/ui/utils/cva.ts` | `src/ui/utils/cva.ts` |
-| `files/ui/components.json` | shadcn CLI configuration | `packages/ui/components.json` | `components.json` (project root) |
-| `files/ui/package.json` | Package config with exports, imports, deps | `packages/ui/package.json` | N/A (use root `package.json`) |
-| `files/ui/tsconfig.json` | TypeScript config extending shared base | `packages/ui/tsconfig.json` | N/A (use root `tsconfig.json`) |
+| **Primitive Components** | | | |
+| `files/ui/components/ui/button.tsx` | Button with Base UI primitive, 6 variants x 8 sizes, CVA | `packages/ui/components/ui/button.tsx` | `src/ui/components/ui/button.tsx` |
+| `files/ui/components/ui/input.tsx` | Text input with Base UI InputPrimitive | `packages/ui/components/ui/input.tsx` | `src/ui/components/ui/input.tsx` |
+| `files/ui/components/ui/label.tsx` | Form label with data-slot targeting | `packages/ui/components/ui/label.tsx` | `src/ui/components/ui/label.tsx` |
+| `files/ui/components/ui/textarea.tsx` | Textarea with data-slot targeting | `packages/ui/components/ui/textarea.tsx` | `src/ui/components/ui/textarea.tsx` |
+| `files/ui/components/ui/badge.tsx` | Badge with Base UI useRender, 6 variants, polymorphic render prop | `packages/ui/components/ui/badge.tsx` | `src/ui/components/ui/badge.tsx` |
+| `files/ui/components/ui/separator.tsx` | Separator with Base UI SeparatorPrimitive | `packages/ui/components/ui/separator.tsx` | `src/ui/components/ui/separator.tsx` |
+| **Compound Components** | | | |
+| `files/ui/components/ui/card.tsx` | Card with 7 compound parts (Header, Title, Description, Action, Content, Footer) | `packages/ui/components/ui/card.tsx` | `src/ui/components/ui/card.tsx` |
+| `files/ui/components/ui/alert-dialog.tsx` | Alert dialog with Base UI AlertDialogPrimitive, 12 parts including AlertDialogMedia | `packages/ui/components/ui/alert-dialog.tsx` | `src/ui/components/ui/alert-dialog.tsx` |
+| `files/ui/components/ui/select.tsx` | Select with Base UI SelectPrimitive, Portal/Positioner, scroll buttons, 10 parts | `packages/ui/components/ui/select.tsx` | `src/ui/components/ui/select.tsx` |
+| `files/ui/components/ui/combobox.tsx` | Combobox with Base UI ComboboxPrimitive, chips support, InputGroup integration, 16 exports | `packages/ui/components/ui/combobox.tsx` | `src/ui/components/ui/combobox.tsx` |
+| `files/ui/components/ui/dropdown-menu.tsx` | Dropdown menu with Base UI MenuPrimitive, sub-menus, checkbox/radio items, 15 exports | `packages/ui/components/ui/dropdown-menu.tsx` | `src/ui/components/ui/dropdown-menu.tsx` |
+| `files/ui/components/ui/sidebar.tsx` | Sidebar with context-based state, cookie persistence, CVA variants, 14 exports | `packages/ui/components/ui/sidebar.tsx` | `src/ui/components/ui/sidebar.tsx` |
+| `files/ui/components/ui/field.tsx` | Field compound layout with 10 parts (Field, FieldGroup, FieldSet, FieldLabel, etc.) | `packages/ui/components/ui/field.tsx` | `src/ui/components/ui/field.tsx` |
+| `files/ui/components/ui/input-group.tsx` | Input group compound with 6 parts (Addon, Button, Text, Input, Textarea) | `packages/ui/components/ui/input-group.tsx` | `src/ui/components/ui/input-group.tsx` |
+| **Navigation/Utility** | | | |
+| `files/ui/components/ui/breadcrumb.tsx` | Breadcrumb with Base UI useRender for polymorphic links, 7 exports | `packages/ui/components/ui/breadcrumb.tsx` | `src/ui/components/ui/breadcrumb.tsx` |
+| `files/ui/components/ui/collapsible.tsx` | Collapsible with Radix CollapsiblePrimitive (legacy) | `packages/ui/components/ui/collapsible.tsx` | `src/ui/components/ui/collapsible.tsx` |
+| `files/ui/components/ui/popover.tsx` | Popover with Radix PopoverPrimitive, forwardRef pattern (legacy) | `packages/ui/components/ui/popover.tsx` | `src/ui/components/ui/popover.tsx` |
+| **Composed Form Widgets** | | | |
+| `files/ui/components/ui/form-field.tsx` | Higher-order FormField with hint popover system (FieldHint interface, IntersectionObserver scroll detection, auto-show on focus) | `packages/ui/components/ui/form-field.tsx` | `src/ui/components/ui/form-field.tsx` |
+| `files/ui/components/ui/tag-input.tsx` | Controlled tag input with chips, max items, duplicate detection, counter | `packages/ui/components/ui/tag-input.tsx` | `src/ui/components/ui/tag-input.tsx` |
+| `files/ui/components/ui/pill-select.tsx` | Generic single-select pill buttons with search, collapse/expand, deselect | `packages/ui/components/ui/pill-select.tsx` | `src/ui/components/ui/pill-select.tsx` |
+| `files/ui/components/ui/card-select.tsx` | Grid of selectable option cards with label, description, disabled state | `packages/ui/components/ui/card-select.tsx` | `src/ui/components/ui/card-select.tsx` |
+| `files/ui/components/ui/entity-select.tsx` | Generic combobox with render props, "Create new" action, loading/empty states | `packages/ui/components/ui/entity-select.tsx` | `src/ui/components/ui/entity-select.tsx` |
+| `files/ui/components/ui/selected-entity-card.tsx` | Compact selected entity display with remove/edit actions | `packages/ui/components/ui/selected-entity-card.tsx` | `src/ui/components/ui/selected-entity-card.tsx` |
+| `files/ui/components/ui/pagination.tsx` | Offset-based prev/next pagination with count display | `packages/ui/components/ui/pagination.tsx` | `src/ui/components/ui/pagination.tsx` |
+| `files/ui/components/ui/empty-state.tsx` | Centered empty state with icon, heading, description, CTA | `packages/ui/components/ui/empty-state.tsx` | `src/ui/components/ui/empty-state.tsx` |
+| `files/ui/components/ui/avatar.tsx` | Image avatar with initials fallback and size variants | `packages/ui/components/ui/avatar.tsx` | `src/ui/components/ui/avatar.tsx` |
+| `files/ui/components/ui/user-menu.tsx` | Sidebar footer user menu with avatar, dropdown actions, collapsed state | `packages/ui/components/ui/user-menu.tsx` | `src/ui/components/ui/user-menu.tsx` |
+| `files/ui/components/ui/org-switcher.tsx` | Organization switcher dropdown with switch list and create action | `packages/ui/components/ui/org-switcher.tsx` | `src/ui/components/ui/org-switcher.tsx` |
+| `files/ui/components/ui/page-header.tsx` | Page title + description + action button with PlusIcon default | `packages/ui/components/ui/page-header.tsx` | `src/ui/components/ui/page-header.tsx` |
+| `files/ui/components/ui/status-filter.tsx` | Pill-style status filter tabs with count display | `packages/ui/components/ui/status-filter.tsx` | `src/ui/components/ui/status-filter.tsx` |
+| `files/ui/components/ui/search-input.tsx` | Debounced search input with magnifying glass icon | `packages/ui/components/ui/search-input.tsx` | `src/ui/components/ui/search-input.tsx` |
 
 ---
 
@@ -211,57 +362,73 @@ For standalone applications without a monorepo, UI components live alongside the
 ### Phase 1: Package Setup
 
 1. Create `packages/ui/` directory
-2. Copy `package.json` — replace `{{SCOPE}}`
-3. Copy `tsconfig.json` — replace `{{SCOPE}}`
-4. Copy `components.json`
+2. Copy `files/ui/package.json` — replace `{{SCOPE}}` with project scope
+3. Copy `files/ui/tsconfig.json` — replace `{{SCOPE}}`
+4. Copy `files/ui/components.json`
 
 ### Phase 2: Utilities and Styles
 
 5. Create `utils/` directory
-6. Copy `cn.ts`
-7. Copy `cva.ts`
+6. Copy `files/ui/utils/cn.ts`
+7. Copy `files/ui/utils/cva.ts`
 8. Create `styles/` directory
-9. Copy `globals.css` — replace `{{SCOPE}}`
+9. Copy `files/ui/styles/globals.css` — replace `{{SCOPE}}`
 
 ### Phase 3: Directory Structure
 
-10. Create `components/ui/` directory (empty — shadcn will populate it)
-11. Create `icons/` directory (empty — user adds brand assets)
-12. Create `icons/logos/` directory
+10. Create `components/ui/` directory
+11. Create `icons/` directory (empty — user adds custom icons)
+12. Create `icons/logos/` directory (empty — user adds brand assets)
+
+### Phase 4: Base Components
 
-### Phase 4: Consuming App Integration
+13. Copy all 31 component files from `files/ui/components/ui/` to `packages/ui/components/ui/`:
+    - Primitives: `button.tsx`, `input.tsx`, `label.tsx`, `textarea.tsx`, `badge.tsx`, `separator.tsx`
+    - Compound: `card.tsx`, `alert-dialog.tsx`, `select.tsx`, `combobox.tsx`, `dropdown-menu.tsx`, `sidebar.tsx`, `field.tsx`, `input-group.tsx`
+    - Navigation: `breadcrumb.tsx`, `collapsible.tsx`, `popover.tsx`
+    - Form widgets: `form-field.tsx`, `tag-input.tsx`, `pill-select.tsx`, `card-select.tsx`, `entity-select.tsx`, `selected-entity-card.tsx`
+    - Data display: `pagination.tsx`, `empty-state.tsx`, `avatar.tsx`
+    - App shell: `user-menu.tsx`, `org-switcher.tsx`, `page-header.tsx`, `status-filter.tsx`, `search-input.tsx`
 
-13. Update `apps/web/app/globals.css`:
+### Phase 5: Consuming App Integration
+
+14. Update `apps/web/app/globals.css`:
     - Add `@import "{{SCOPE}}/ui/styles";` after the tailwind-config import
     - Add `@plugin "@tailwindcss/typography";`
     - Add `@source "../../../packages/ui";` (compute relative path based on app location)
-14. Verify `pnpm-workspace.yaml` includes `packages/*`
+15. Verify the workspace configuration in root `package.json` includes `packages/*`
 
-### Phase 5: Dependency Installation
+### Phase 6: Dependency Installation
 
-15. Run `pnpm install` to wire workspace dependencies
-16. Verify no peer dependency warnings
+16. Run `bun install` to wire workspace dependencies and install Base UI, Phosphor, Radix legacy, CVA, and other packages
+17. Verify no peer dependency warnings
 
-### Phase 6: Verification
+### Phase 7: Verification
 
-17. Run `pnpm dev` — no CSS/import errors
-18. Try adding a shadcn component: `cd packages/ui && pnpm dlx shadcn@latest add button`
-19. Import and use the button in `apps/web/` — verify it renders with correct styles
+18. Run `bun dev` — no CSS/import errors
+19. Import a component in `apps/web/` and verify it renders with correct styles:
+    ```typescript
+    import { Button } from "@scope/ui/components/ui/button";
+    ```
+20. Verify `data-slot` attributes appear in rendered HTML via browser dev tools
+21. Try adding a shadcn component: `cd packages/ui && bunx shadcn@latest add tooltip` — verify it uses `base-maia` style and produces Base UI output
 
 ---
 
 ## Adding Components
 
-After initial scaffolding, add shadcn/ui components:
+### Via shadcn CLI (user-owned)
+
+After initial scaffolding, add more shadcn/ui components. The `base-maia` style ensures generated components use Base UI primitives and follow the `data-slot` convention:
 
 ```bash
 # From packages/ui/
-pnpm dlx shadcn@latest add button
-pnpm dlx shadcn@latest add card
-pnpm dlx shadcn@latest add input
+bunx shadcn@latest add tooltip
+bunx shadcn@latest add tabs
+bunx shadcn@latest add dialog
 ```
 
-Components are generated in `components/ui/` and immediately available to consuming apps via path-based exports.
+Components generated via `shadcn add` are **user-owned** — the blueprint never modifies them during upgrades.
 
 ### Custom Components
 
@@ -279,7 +446,7 @@ interface FeatureCardProps {
 
 export function FeatureCard({ title, className, children }: FeatureCardProps) {
   return (
-    <div className={cn("rounded-lg border p-6", className)}>
+    <div data-slot="feature-card" className={cn("rounded-lg border p-6", className)}>
       <h3 className="text-lg font-semibold">{title}</h3>
       {children}
     </div>
@@ -291,26 +458,160 @@ Import in consuming apps: `import { FeatureCard } from "@scope/ui/components/fea
 
 ---
 
+## Usage Patterns
+
+These patterns document **how to compose** the base components into real application features. They are conventions extracted from production usage — not additional components, but recipes for building with the component library.
+
+### Icon Conventions
+
+- **Create/add actions**: Always use `PlusIcon` before the label: `<Button><PlusIcon className="size-4" />New Item</Button>`
+- **Navigation arrows**: `CaretLeftIcon` / `CaretRightIcon` for pagination, `CaretUpDownIcon` for dropdown triggers
+- **Menu triggers**: `DotsThreeIcon weight="bold"` for action menus on cards/rows
+- **Import style**: Prefer deep imports for tree-shaking: `import { PlusIcon } from "@phosphor-icons/react/Plus"`
+- **Default icon size**: `size-4` (16px) inside buttons and menu items, `size-3.5` for inline indicators
+
+### Form Integration with React Hook Form + Zod
+
+The recommended form stack is **react-hook-form** + **@hookform/resolvers** + **zod** + **FormField**:
+
+```tsx
+import { useForm, Controller } from "react-hook-form";
+import { zodResolver } from "@hookform/resolvers/zod";
+
+const { register, control, handleSubmit, formState: { errors } } = useForm({
+  resolver: zodResolver(schema),
+  defaultValues: { ... },
+});
+```
+
+**Field connection patterns:**
+- **Simple inputs** — use `register()` directly: `<Input {...register("name")} />`
+- **Custom/controlled fields** — use `Controller`: `<Controller name="field" control={control} render={({ field }) => <CardSelect value={field.value} onChange={field.onChange} />} />`
+- **FormField wrapper** — wraps every field with label, error, description, and optional hint system
+
+**Hint system wiring:**
+```tsx
+const [showHints, setShowHints] = useState(true);
+const [activeHintField, setActiveHintField] = useState<string | null>(null);
+
+<FormField
+  label="Name" name="name" required error={errors.name?.message}
+  hint={{ directive: "Be specific", example: "Enterprise SaaS for HR teams" }}
+  showHints={showHints} isHintOpen={activeHintField === "name"}
+  onHintOpen={(name) => setActiveHintField(name)}
+  onHintClose={() => setActiveHintField(null)}
+  onToggleHints={() => setShowHints(prev => !prev)}
+>
+  <Input {...register("name")} />
+</FormField>
+```
+
+### Dialog Form Pattern
+
+Dialogs that contain forms follow a consistent structure:
+
+**Confirmation dialogs** (archive, delete, restore):
+- `AlertDialog` + `AlertDialogContent size="sm"`
+- `AlertDialogHeader` with `AlertDialogMedia` (icon in circle) + title + description
+- `AlertDialogFooter` with Cancel + destructive/confirm Button
+- Async action with loading state on the confirm button
+
+**Multi-step form dialogs** (create entity):
+1. **Choice step**: Two-column grid of outline buttons choosing creation method (manual vs AI). `AlertDialogContent` at `max-w-lg`.
+2. **Form step**: Animated width transition to `max-w-[38rem]`. Scrollable form body with sticky footer. Close button positioned `absolute top-0 right-0`.
+3. On close: reset form, reset mutation state, then `setTimeout(() => setStep("choice"), 500)` for smooth animation.
+
+**Single-step form dialogs**: Skip the choice step, go directly to the form. Same scrollable body + sticky footer pattern.
+
+### List Page Composition
+
+Every entity list page follows this structure:
+
+```
+PageHeader (title + description + "New X" button)
+  ↓
+StatusFilter (active/archived tabs, or full status set)
+  ↓
+SearchInput + sort Select (optional, for complex lists)
+  ↓
+Content area:
+  - Loading: skeleton grid/table with animate-pulse
+  - Empty: EmptyState component
+  - Data: grid of EntityCards or DataTable + Pagination
+  ↓
+Inline dialogs (create, edit, archive, restore)
+```
+
+**Skeleton loading pattern:**
+```tsx
+{isLoading && (
+  <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
+    {[...Array(6)].map((_, i) => (
+      <Card key={i} className="animate-pulse">
+        <CardHeader><div className="h-5 bg-muted rounded w-3/4" /></CardHeader>
+        <CardContent><div className="h-4 bg-muted rounded w-1/2" /></CardContent>
+      </Card>
+    ))}
+  </div>
+)}
+```
+
+### Sidebar App Shell
+
+The recommended app shell layout:
+
+```
+SidebarProvider
+  ├── Header (sticky top-0, contains OrgSwitcher + Separator + Breadcrumbs)
+  ├── Sidebar collapsible="icon"
+  │   ├── SidebarContent → Navigation (SidebarMenu with SidebarMenuButton)
+  │   ├── SidebarFooter → UserMenu
+  │   └── SidebarRail (edge toggle)
+  └── SidebarInset → main content area
+```
+
+- Header height set via `--header-height` CSS variable
+- Sidebar adapts to collapsed state — UserMenu shows only avatar, navigation shows only icons
+- OrgSwitcher lives in the header, not the sidebar — stays visible when sidebar collapses
+
+### Entity Management Pattern
+
+For CRUD entity pages (audiences, brand voices, CTAs), the pattern is:
+
+1. **List page**: `PageHeader` + `StatusFilter` + grid of entity `Card` components with action `DropdownMenu`
+2. **Entity cards**: `Card` + `CardHeader` (name + action menu) + `CardContent` (badges/metadata) + `CardFooter` (timestamp)
+3. **Action menus**: `DropdownMenu` triggered by 3-dot icon button. Edit + Archive (active) or Restore (archived) items. Destructive separator before archive/delete.
+4. **Inline dialogs**: All create/edit/archive/restore dialogs render at the page level, controlled by state. On success, invalidate SWR cache.
+5. **Entity selection in forms**: `EntitySelect` with render props for custom option/selected display. "Create new" action opens an inline dialog, auto-selects the created entity via `setValue()`.
+
+---
+
 ## Maintenance Hooks
 
 ### Component & Style Hooks
 
 | When you... | Then do... | Why |
 |---|---|---|
-| Add a shadcn component | Run `pnpm dlx shadcn@latest add <name>` from `packages/ui/` | Generates in the correct location with proper aliases |
+| Add a shadcn component | Run `bunx shadcn@latest add <name>` from `packages/ui/` | Uses `base-maia` style to generate Base UI components in the correct location |
+| Create a custom component | Add `data-slot="component-name"` to the root element | Maintains the CSS targeting convention across all components |
 | Add a new app that uses UI | Add `@import "{{SCOPE}}/ui/styles"` and `@source` directive to the app's `globals.css` | New apps don't automatically see UI package classes |
 | Add a new export directory | Add it to both `exports` and `imports` in `packages/ui/package.json` | Missing exports = import errors in consuming apps |
 | Modify component variants | Update CVA definitions and ensure `cn()` is used for className composition | Inconsistent class merging = broken styles |
 | Add an icon | Place in `icons/` or `icons/logos/` — export is automatic via wildcard | Follows the path-based export convention |
+| Upgrade base components | Run `/scaffold-ui` in upgrade mode | Updates blueprint-owned components without touching user-owned ones |
 
-### Condensed Rules for project rules file
+### Condensed Rules for project maintenance skill
 
 ```markdown
 ### ui-shared-components maintenance
-- Add shadcn components via `pnpm dlx shadcn@latest add <name>` from packages/ui/
+- Add shadcn components via `bunx shadcn@latest add <name>` from packages/ui/ (uses base-maia style)
 - Use cn() for all className composition — never concatenate class strings manually
+- Use data-slot attribute on every component root element and sub-components
+- Import Phosphor icons from @phosphor-icons/react or @phosphor-icons/react/<IconName>
+- Base UI primitives: import from @base-ui/react/<primitive-name>
 - Internal imports use #prefix (#components/ui/button); cross-package imports use @scope/ui/components/ui/button
-- After adding a new export directory: add to both exports and imports in packages/ui/package.json
+- Base components in components/ui/ are blueprint-owned — update via /scaffold-ui upgrade mode
+- After adding new export directory: add to both exports and imports in packages/ui/package.json
 - After adding a new consuming app: add @import and @source directive to the app's globals.css
 ```
 
@@ -318,18 +619,23 @@ Import in consuming apps: `import { FeatureCard } from "@scope/ui/components/fea
 
 ## What's Configurable
 
-- shadcn style (`new-york`, `default`, or custom)
-- Icon library (`lucide`, `phosphor`, `radix`)
-- Which consuming apps get the globals.css update
-- Additional export directories
+- **shadcn style** — `base-maia` (default), `new-york`, `default`, or any shadcn style
+- **Icon library** — Phosphor (default), Lucide, Radix, or custom
+- **Include base components** — Yes (default, all 31 components), No (skeleton only with empty `components/ui/`)
+- **Include form system** — Yes (default), No (skip `form-field`, `field`, `tag-input`, `pill-select`)
+- **Which consuming apps get globals.css update** — Ask during scaffolding
 
 ## What's Opinionated
 
-- **Path-based exports** — no barrel re-exports for components
-- **No build step** — exports TypeScript source, consuming apps transpile
-- **shadcn/ui conventions** — `components.json`, `cn()`, CVA variants
-- **`#` subpath imports** — internal package imports use Node.js subpath imports
-- **Flat component structure** — `components/ui/` for shadcn, `components/` for custom, `icons/` for assets
+- **Base UI as headless layer** — Modern API, `data-*` state attributes, render props for polymorphism
+- **`data-slot` attribute convention** — Stable CSS targeting that survives class changes
+- **Compound component pattern** — Named parts over monolithic prop APIs
+- **Phosphor Icons** — Six weights, tree-shakeable, consistent API
+- **Path-based exports** — No barrel re-exports for components
+- **No build step** — Exports TypeScript source, consuming apps transpile
+- **`#` prefix subpath imports** — Node.js native, no path alias configuration
+- **Flat component structure** — `components/ui/` for all components, no nested directories
+- **CVA for all variant systems** — Consistent variant definition pattern across components
 
 ## Project Context Output
 
@@ -340,9 +646,11 @@ Appends to `.project-context.md` under `## Installed Blueprints`:
 blueprint: ui-shared-components
 installed_at: <date>
 choices:
-  shadcn_style: new-york
-  icon_library: lucide
+  shadcn_style: base-maia
+  icon_library: phosphor
   include_cva: true
+  include_base_components: true
+  include_form_system: true
 files_created:
   - packages/ui/package.json
   - packages/ui/tsconfig.json
@@ -350,9 +658,33 @@ files_created:
   - packages/ui/styles/globals.css
   - packages/ui/utils/cn.ts
   - packages/ui/utils/cva.ts
+  - packages/ui/components/ui/button.tsx
+  - packages/ui/components/ui/input.tsx
+  - packages/ui/components/ui/label.tsx
+  - packages/ui/components/ui/textarea.tsx
+  - packages/ui/components/ui/card.tsx
+  - packages/ui/components/ui/badge.tsx
+  - packages/ui/components/ui/separator.tsx
+  - packages/ui/components/ui/alert-dialog.tsx
+  - packages/ui/components/ui/select.tsx
+  - packages/ui/components/ui/combobox.tsx
+  - packages/ui/components/ui/dropdown-menu.tsx
+  - packages/ui/components/ui/breadcrumb.tsx
+  - packages/ui/components/ui/collapsible.tsx
+  - packages/ui/components/ui/popover.tsx
+  - packages/ui/components/ui/sidebar.tsx
+  - packages/ui/components/ui/field.tsx
+  - packages/ui/components/ui/form-field.tsx
+  - packages/ui/components/ui/input-group.tsx
+  - packages/ui/components/ui/tag-input.tsx
+  - packages/ui/components/ui/pill-select.tsx
 globals_css_updated:
   - apps/web/app/globals.css
 packages_added:
+  - "@base-ui/react"
+  - "@phosphor-icons/react"
+  - "@radix-ui/react-collapsible"
+  - "@radix-ui/react-popover"
   - "@radix-ui/react-slot"
   - class-variance-authority
   - clsx
@@ -365,9 +697,10 @@ packages_added:
 
 ## References
 
+- **Base UI:** https://base-ui.com
+- **Phosphor Icons:** https://phosphoricons.com
 - **shadcn/ui Docs:** https://ui.shadcn.com/docs
 - **shadcn/ui Monorepo Guide:** https://ui.shadcn.com/docs/monorepo
 - **Tailwind CSS v4:** https://tailwindcss.com/docs
 - **Class Variance Authority:** https://cva.style/docs
 - **Node.js Subpath Imports:** https://nodejs.org/api/packages.html#subpath-imports
-- **Radix UI Primitives:** https://www.radix-ui.com/primitives