@withmata/blueprints 0.3.1 → 0.3.2

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

@@ -6,30 +6,367 @@ Feature
 
 ## Status
 
-Planned.
+Complete.
 
 ## Problem
 
-Sharing UI components across multiple apps in a Turborepo monorepo requires careful package structure, export patterns, and styling integration. Without a standard setup, teams duplicate components, diverge on patterns, and fight build tooling issues.
-
-## Intended Scope
-
-- `packages/ui/` workspace package with shadcn/ui setup
-- Component export pattern via barrel `index.ts`
-- Consuming shared components from `apps/web/` and other apps
-- Integration with the shared Tailwind config from `config/tailwind-config/`
-- Component generation workflow (shadcn CLI adapted for monorepo)
-- Storybook setup (optional)
+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.
 
 ## Blueprint Dependencies
 
 | Blueprint | Type | Why |
 |-----------|------|-----|
-| `features/tailwind-v4` | required | UI components depend on design tokens and theme setup from the Tailwind blueprint. Without it, components lack consistent styling. |
-| `foundation/monorepo-turbo` | recommended | Provides workspace structure, TypeScript config, and package conventions. Without it, the shared UI package is created as a local directory. |
+| `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. |
 
 ### 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.
+
+---
+
+## Architecture
+
+### 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.
+
+Components use shadcn/ui conventions: Radix UI primitives for accessibility, `class-variance-authority` for variant management, and the `cn()` utility for class merging.
+
+### Key Decisions
+
+- **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.
+
+- **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`.
+
+- **CVA for variants** (recommended) — `class-variance-authority` for defining component variants (size, color, style). Re-exported from `utils/cva.ts` for consistency.
+
+- **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.
+
+- **Styles exported as CSS** (required) — The UI package exports its `styles/globals.css` which imports the tailwind-config. Consuming apps import this via `@import "{{SCOPE}}/ui/styles"` in their own `globals.css`.
+
+---
+
+## Hard Requirements vs Recommended Defaults
+
+**Hard requirements:**
+- Path-based exports (no barrel re-exports for components)
+- shadcn/ui CLI compatibility (`components.json`)
+- `cn()` utility using clsx + tailwind-merge
+- TypeScript source exports (no build step)
+- Styles import chain through tailwind-config
+
+**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 |
+
+---
+
+## Dependencies
+
+### npm packages
+
+**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 |
+
+**packages/ui (dev):**
+| Package | Version | Purpose |
+|---|---|---|
+| `{{SCOPE}}/typescript-config` | `workspace:*` | Shared TypeScript config |
+| `@tailwindcss/postcss` | ^4 | PostCSS plugin |
+| `tailwindcss` | ^4 | Tailwind CSS |
+| `typescript` | ^5.9 | TypeScript compiler |
+| `@types/react` | ^19 | React type definitions |
+| `@types/react-dom` | ^19 | React DOM type definitions |
+
+---
+
+## Monorepo Wiring
+
+### UI Package (`packages/ui/`)
+
+**`package.json` exports:**
+```json
+{
+  "exports": {
+    "./components/*": "./components/*.tsx",
+    "./components/ui/*": "./components/ui/*.tsx",
+    "./utils/*": "./utils/*.ts",
+    "./styles": "./styles/globals.css",
+    "./icons/*": "./icons/*.tsx",
+    "./icons/logos/*": "./icons/logos/*.tsx"
+  },
+  "imports": {
+    "#components/*": "./components/*.tsx",
+    "#components/ui/*": "./components/ui/*.tsx",
+    "#utils/*": "./utils/*.ts",
+    "#hooks/*": "./hooks/*.ts",
+    "#types/*": "./types/*.ts"
+  }
+}
+```
+
+**File structure:**
+```
+packages/ui/
+├── components/
+│   └── ui/                    # shadcn-generated components go here
+├── icons/
+│   └── logos/                 # Brand logos (SVG as React components)
+├── styles/
+│   └── globals.css            # Imports tailwind-config
+├── utils/
+│   ├── cn.ts                  # Class merging utility
+│   └── cva.ts                 # CVA re-export
+├── components.json            # shadcn CLI config
+├── package.json               # Exports, imports, deps
+└── tsconfig.json              # Extends shared react-library config
+```
+
+### Consuming App (`apps/web/`)
+
+**`app/globals.css` (updated):**
+```css
+@import "tailwindcss";
+@import "{{SCOPE}}/tailwind-config";
+@import "{{SCOPE}}/ui/styles";
+@plugin "@tailwindcss/typography";
+
+@source "../../../packages/ui";
+```
+
+The `@source` directive tells Tailwind to scan the UI package for classes. The relative path must point from the consuming app to `packages/ui/`.
+
+**Usage in components:**
+```typescript
+import { Button } from "{{SCOPE}}/ui/components/ui/button";
+import { cn } from "{{SCOPE}}/ui/utils/cn";
+import { Logo } from "{{SCOPE}}/ui/icons/logos/Logo";
+```
+
+---
+
+## Single-Repo Adaptation
+
+For standalone applications without a monorepo, UI components live alongside the app code.
+
+### Path Mapping
+
+| Aspect | Monorepo | Single-Repo |
+|--------|----------|-------------|
+| UI code location | `packages/ui/` (workspace package) | `src/ui/` or `src/components/` |
+| 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 |
+
+### What Stays the Same
+
+- Path-based exports pattern (via `package.json` exports or TypeScript paths)
+- `cn()` utility and CVA pattern
+- `components.json` for shadcn CLI
+- Component file organization (`components/ui/`, `icons/`, `utils/`)
+
+---
+
+## File Manifest
+
+| 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` |
+| `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`) |
+
+---
+
+## Integration Steps
+
+### 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`
+
+### Phase 2: Utilities and Styles
+
+5. Create `utils/` directory
+6. Copy `cn.ts`
+7. Copy `cva.ts`
+8. Create `styles/` directory
+9. Copy `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
+
+### Phase 4: Consuming App Integration
+
+13. 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/*`
+
+### Phase 5: Dependency Installation
+
+15. Run `pnpm install` to wire workspace dependencies
+16. Verify no peer dependency warnings
+
+### Phase 6: 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
+
+---
+
+## Adding Components
+
+After initial scaffolding, add shadcn/ui components:
+
+```bash
+# From packages/ui/
+pnpm dlx shadcn@latest add button
+pnpm dlx shadcn@latest add card
+pnpm dlx shadcn@latest add input
+```
+
+Components are generated in `components/ui/` and immediately available to consuming apps via path-based exports.
+
+### Custom Components
+
+For non-shadcn components, create files in `components/`:
+
+```typescript
+// packages/ui/components/feature-card.tsx
+import { cn } from "#utils/cn";
+
+interface FeatureCardProps {
+  title: string;
+  className?: string;
+  children: React.ReactNode;
+}
+
+export function FeatureCard({ title, className, children }: FeatureCardProps) {
+  return (
+    <div className={cn("rounded-lg border p-6", className)}>
+      <h3 className="text-lg font-semibold">{title}</h3>
+      {children}
+    </div>
+  );
+}
+```
+
+Import in consuming apps: `import { FeatureCard } from "@scope/ui/components/feature-card";`
+
+---
+
+## 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 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 |
+
+### Condensed Rules for project rules file
+
+```markdown
+### ui-shared-components maintenance
+- Add shadcn components via `pnpm dlx shadcn@latest add <name>` from packages/ui/
+- Use cn() for all className composition — never concatenate class strings manually
+- 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
+- After adding a new consuming app: add @import and @source directive to the app's globals.css
+```
+
+---
+
+## 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
+
+## 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
+
+## Project Context Output
+
+Appends to `.project-context.md` under `## Installed Blueprints`:
+
+```yaml
+### ui-shared-components
+blueprint: ui-shared-components
+choices:
+  shadcn_style: new-york
+  icon_library: lucide
+  include_cva: true
+files_created:
+  - packages/ui/package.json
+  - packages/ui/tsconfig.json
+  - packages/ui/components.json
+  - packages/ui/styles/globals.css
+  - packages/ui/utils/cn.ts
+  - packages/ui/utils/cva.ts
+globals_css_updated:
+  - apps/web/app/globals.css
+packages_added:
+  - "@radix-ui/react-slot"
+  - class-variance-authority
+  - clsx
+  - tailwind-merge
+  - tw-animate-css
+  - shadcn
+```
+
+---
+
+## References
+
+- **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

package/blueprints/features/ui-shared-components/files/ui/components.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": true,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "styles/globals.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "iconLibrary": "lucide",
+  "aliases": {
+    "components": "#components",
+    "utils": "#utils",
+    "ui": "#components/ui",
+    "lib": "#utils",
+    "hooks": "#hooks"
+  }
+}

package/blueprints/features/ui-shared-components/files/ui/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "{{SCOPE}}/ui",
+  "version": "0.0.0",
+  "private": true,
+  "scripts": {
+    "ui:add": "pnpm dlx shadcn@latest add"
+  },
+  "imports": {
+    "#components/*": "./components/*.tsx",
+    "#components/ui/*": "./components/ui/*.tsx",
+    "#utils/*": "./utils/*.ts",
+    "#hooks/*": "./hooks/*.ts",
+    "#types/*": "./types/*.ts"
+  },
+  "exports": {
+    "./components/*": "./components/*.tsx",
+    "./components/ui/*": "./components/ui/*.tsx",
+    "./utils/*": "./utils/*.ts",
+    "./styles": "./styles/globals.css",
+    "./icons/*": "./icons/*.tsx",
+    "./icons/logos/*": "./icons/logos/*.tsx"
+  },
+  "dependencies": {
+    "{{SCOPE}}/tailwind-config": "workspace:*",
+    "@radix-ui/react-slot": "^1.2",
+    "class-variance-authority": "^0.7",
+    "clsx": "^2.1",
+    "react": "^19",
+    "react-dom": "^19",
+    "shadcn": "^3",
+    "tailwind-merge": "^3",
+    "tw-animate-css": "^1"
+  },
+  "devDependencies": {
+    "{{SCOPE}}/typescript-config": "workspace:*",
+    "@tailwindcss/postcss": "^4",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "tailwindcss": "^4",
+    "typescript": "^5.9"
+  }
+}

package/blueprints/features/ui-shared-components/files/ui/styles/globals.css

@@ -0,0 +1,2 @@
+@import "tailwindcss";
+@import "{{SCOPE}}/tailwind-config";

package/blueprints/features/ui-shared-components/files/ui/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "{{SCOPE}}/typescript-config/react-library.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "."
+  },
+  "include": ["."],
+  "exclude": ["node_modules", "dist"]
+}

package/blueprints/features/ui-shared-components/files/ui/utils/cn.ts

@@ -0,0 +1,6 @@
+import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

package/blueprints/features/ui-shared-components/files/ui/utils/cva.ts

@@ -0,0 +1,4 @@
+import { cva } from "class-variance-authority";
+
+export { cva };
+export type { VariantProps } from "class-variance-authority";

package/dist/index.js

@@ -6,7 +6,7 @@ import pc3 from "picocolors";
 
 // src/constants.ts
 var API_URL = process.env["WITHMATA_API_URL"] || "https://blueprints.withmata.dev";
-var VERSION = "0.3.1";
+var VERSION = "0.3.2";
 
 // src/steps/auth.ts
 import { log } from "@clack/prompts";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withmata/blueprints",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Set up AI-powered project blueprints for Claude Code, OpenCode, and Cursor",
   "type": "module",
   "bin": {