@withmata/blueprints 0.3.4 → 0.4.0

package/blueprints/features/auth-better-auth/BLUEPRINT.md

@@ -17,7 +17,7 @@ Complete.
 | Blueprint | Type | Why |
 |-----------|------|-----|
 | `features/db-drizzle-postgres` | required | Auth creates schema files inside the database layer following the schema-group pattern (per-group drizzle.config.ts, barrel exports, explicit schema lists). Without it, auth must create a minimal db structure that lacks the full patterns. |
-| `foundation/monorepo-turbo` | recommended | Provides monorepo workspace structure (packages/, apis/, turbo tasks, pnpm workspaces). Works without it — adapts to single-repo projects automatically. |
+| `foundation/monorepo-turbo` | recommended | Provides monorepo workspace structure (packages/, apis/, turbo tasks, bun workspaces). Works without it — adapts to single-repo projects automatically. |
 
 ### If `db-drizzle-postgres` is not installed
 
@@ -210,7 +210,7 @@ In production, this proxies `/api/*` through the frontend domain so cookies work
   "scripts": {
     "auth:generate": "turbo run auth:generate --filter={{SCOPE}}/server --no-cache",
     "auth:migrate": "turbo run auth:migrate --filter={{SCOPE}}/db --no-cache",
-    "auth:setup": "pnpm run auth:generate && pnpm run auth:migrate"
+    "auth:setup": "bun run auth:generate && bun run auth:migrate"
   }
 }
 ```
@@ -226,15 +226,13 @@ In production, this proxies `/api/*` through the frontend domain so cookies work
 }
 ```
 
-### `pnpm-workspace.yaml`
+### Workspace Configuration
 
-Ensure `apis/*` is included (for standalone server mode):
-```yaml
-packages:
-  - "apps/*"
-  - "apis/*"
-  - "packages/*"
-  - "config/*"
+Ensure `apis/*` is included in the workspace configuration (for standalone server mode). In the root `package.json`:
+```json
+{
+  "workspaces": ["apps/*", "apis/*", "packages/*", "config/*"]
+}
 ```
 
 ---
@@ -276,7 +274,7 @@ Single-repo projects typically use **Next.js API routes** directly instead of a
   "scripts": {
     "auth:generate": "npx @better-auth/cli@latest generate --config ./src/lib/auth/index.ts --output ./src/db/auth/schema.ts --yes",
     "auth:migrate": "drizzle-kit generate --config ./drizzle/auth/drizzle.config.ts && drizzle-kit migrate --config ./drizzle/auth/drizzle.config.ts",
-    "auth:setup": "pnpm auth:generate && pnpm auth:migrate"
+    "auth:setup": "bun auth:generate && bun auth:migrate"
   }
 }
 ```
@@ -719,26 +717,26 @@ Rules that should be added to the target project's CLAUDE.md during scaffolding.
 
 | When you... | Then run... | Why |
 |---|---|---|
-| Modify the Better Auth server config (`auth.ts`) — plugins, providers, fields, session settings | `pnpm auth:generate` then `pnpm auth:migrate` | Config changes can alter the database schema |
-| Add or remove a social provider | `pnpm auth:generate` | Provider changes affect the account schema |
-| Change organization plugin settings (roles, limits, membership config) | `pnpm auth:generate` then `pnpm auth:migrate` | Org config changes affect member/invitation tables |
-| Edit `auth-schema.ts` manually | `pnpm auth:migrate` | Manual schema edits need migrations applied |
-| Update the `better-auth` package version | `pnpm auth:generate` then check for schema diff, migrate if needed | New versions may include schema changes |
+| Modify the Better Auth server config (`auth.ts`) — plugins, providers, fields, session settings | `bun auth:generate` then `bun auth:migrate` | Config changes can alter the database schema |
+| Add or remove a social provider | `bun auth:generate` | Provider changes affect the account schema |
+| Change organization plugin settings (roles, limits, membership config) | `bun auth:generate` then `bun auth:migrate` | Org config changes affect member/invitation tables |
+| Edit `auth-schema.ts` manually | `bun auth:migrate` | Manual schema edits need migrations applied |
+| Update the `better-auth` package version | `bun auth:generate` then check for schema diff, migrate if needed | New versions may include schema changes |
 
 ### Environment Hooks
 
 | When you... | Then run... | Why |
 |---|---|---|
-| Add a new env var to server `env.ts` | Add it to all relevant `.env` files and verify with `pnpm dev` | Missing env vars crash at startup due to t3-env validation |
+| Add a new env var to server `env.ts` | Add it to all relevant `.env` files and verify with `bun dev` | Missing env vars crash at startup due to t3-env validation |
 | Add a new `NEXT_PUBLIC_` env var | Add to `apps/web/.env.local` and restart dev server | Next.js requires restart to pick up new env vars |
 | Change `BETTER_AUTH_URL` or `FRONTEND_DOMAIN` | Update CORS config and verify OAuth callback URLs still work | Mismatched URLs break OAuth flows and cookie sharing |
 
 ### Validation Checks
 
 After any auth-related changes, verify:
-- Dev server starts without errors: `pnpm dev`
+- Dev server starts without errors: `bun dev`
 - Auth API responds: visit `{BETTER_AUTH_URL}/api/auth/ok`
-- If schema changed: `pnpm drizzle:studio:auth` shows expected tables
+- If schema changed: `bun drizzle:studio:auth` shows expected tables
 - If middleware changed: unauthenticated requests to protected routes redirect to `/auth`
 - If org plugin changed: verify org creation and member invitation flows
 
@@ -747,9 +745,9 @@ After any auth-related changes, verify:
 This is the version that gets injected into the target project's CLAUDE.md during scaffolding:
 ```markdown
 ### auth-better-auth maintenance
-- After modifying Better Auth server config, plugins, or providers: run `pnpm auth:generate && pnpm auth:migrate`
-- After updating `better-auth` package: run `pnpm auth:generate`, check for schema changes, migrate if needed
-- After adding/changing env vars: update all `.env` files and verify `pnpm dev` starts clean
+- After modifying Better Auth server config, plugins, or providers: run `bun auth:generate && bun auth:migrate`
+- After updating `better-auth` package: run `bun auth:generate`, check for schema changes, migrate if needed
+- After adding/changing env vars: update all `.env` files and verify `bun dev` starts clean
 - After changing `BETTER_AUTH_URL` or `FRONTEND_DOMAIN`: verify CORS config and OAuth callback URLs
 - After any auth changes: verify `{BETTER_AUTH_URL}/api/auth/ok` responds
 - Never edit the auto-generated auth schema directly — modify the Better Auth config and regenerate

package/blueprints/features/db-drizzle-postgres/BLUEPRINT.md

@@ -443,8 +443,8 @@ uniqueIndex("entity_slug_unique").on(table.slug),
 
 14. Add `{{GROUP}}:generate`, `{{GROUP}}:migrate` tasks to `turbo.json` (both `cache: false`)
 15. Add `db:generate`, `db:migrate`, `db:studio`, `db:seed` scripts to root `package.json` (Turbo wrappers)
-16. Verify `packages/db` is covered by `pnpm-workspace.yaml` (should be via `packages/*`)
-17. Run `pnpm install` to wire workspace dependencies
+16. Verify `packages/db` is covered by the workspace configuration in root `package.json` (should be via `packages/*`)
+17. Run `bun install` to wire workspace dependencies
 
 ### Phase 5-alt: Project Integration (single-repo)
 
@@ -457,10 +457,10 @@ uniqueIndex("entity_slug_unique").on(table.slug),
 ### Phase 6: Verification
 
 18. Set `{{GROUP_UPPER}}_DATABASE_URL` in `packages/db/.env`
-19. Run `pnpm db:generate` — should produce initial migration SQL
-20. Run `pnpm db:migrate` — should apply migration to database
-21. Run `pnpm db:studio` — should open Drizzle Studio
-22. Run `pnpm db:seed` — should insert sample data (if seed included)
+19. Run `bun db:generate` — should produce initial migration SQL
+20. Run `bun db:migrate` — should apply migration to database
+21. Run `bun db:studio` — should open Drizzle Studio
+22. Run `bun db:seed` — should insert sample data (if seed included)
 
 ---
 
@@ -471,8 +471,8 @@ After initial scaffolding, add new domain entities with this checklist:
 1. Create `src/{{GROUP}}/new-entity.ts` (copy the example entity pattern)
 2. Add `export * from "./new-entity.js";` to `src/{{GROUP}}/index.ts`
 3. Add `"./src/{{GROUP}}/new-entity.ts"` to `drizzle/{{GROUP}}/drizzle.config.ts` schema array
-4. Run `pnpm {{GROUP}}:generate` to create the migration
-5. Run `pnpm {{GROUP}}:migrate` to apply it
+4. Run `bun {{GROUP}}:generate` to create the migration
+5. Run `bun {{GROUP}}:migrate` to apply it
 
 ## Adding a New Schema Group
 
@@ -501,23 +501,23 @@ To add a second group (e.g., `"pipeline"`) for a separate database or logical do
 | When you... | Then run... | Why |
 |---|---|---|
 | Add a new entity file | Add to `drizzle.config.ts` schema array AND `index.ts` barrel | Missing entries = invisible to migrations and consumers |
-| Modify any schema file | `pnpm {{GROUP}}:generate` then `pnpm {{GROUP}}:migrate` | Schema changes need migrations generated and applied |
+| Modify any schema file | `bun {{GROUP}}:generate` then `bun {{GROUP}}:migrate` | Schema changes need migrations generated and applied |
 | Add a new schema group | Follow "Adding a New Schema Group" checklist | Multiple configs + exports + scripts needed |
-| Update drizzle-orm or drizzle-kit | `pnpm {{GROUP}}:generate` and check for unexpected diffs | New versions may change migration format |
+| Update drizzle-orm or drizzle-kit | `bun {{GROUP}}:generate` and check for unexpected diffs | New versions may change migration format |
 
 ### Environment Hooks
 
 | When you... | Then do... | Why |
 |---|---|---|
 | Add a new `DATABASE_URL` | Add to `.env`, `.env.example`, and consuming app env validation | Missing URL = crash at startup |
-| Change `DATABASE_URL` | Verify connection with `pnpm drizzle:studio:{{GROUP}}` | Wrong URL = silent connection failures |
+| Change `DATABASE_URL` | Verify connection with `bun drizzle:studio:{{GROUP}}` | Wrong URL = silent connection failures |
 
 ### Condensed Rules for CLAUDE.md
 
 ```markdown
 ### db-drizzle-postgres maintenance
 - After creating a new schema file: add it to `drizzle/<group>/drizzle.config.ts` schema array AND the group's `index.ts` barrel export
-- After any schema change: run `pnpm <group>:generate && pnpm <group>:migrate`
+- After any schema change: run `bun <group>:generate && bun <group>:migrate`
 - After adding a new schema group: create drizzle config, add package.json export, add scripts (see BLUEPRINT.md "Adding a New Schema Group")
 - After updating drizzle-orm/drizzle-kit: run generate and check migration diff for unexpected changes
 - Never use glob patterns in drizzle.config.ts schema — always list files explicitly, excluding index.ts

package/blueprints/features/db-drizzle-postgres/files/db/src/example-entity.ts

@@ -8,7 +8,7 @@
 //   3. Export $inferSelect / $inferInsert types
 //   4. Add the file path to drizzle/{{GROUP}}/drizzle.config.ts schema array
 //   5. Add the re-export to this group's index.ts
-//   6. Run `pnpm {{GROUP}}:generate` then `pnpm {{GROUP}}:migrate`
+//   6. Run `bun {{GROUP}}:generate` then `bun {{GROUP}}:migrate`
 // =============================================================================
 
 import {

package/blueprints/features/db-drizzle-postgres/files/db/src/scripts/seed.ts

@@ -3,7 +3,7 @@
 // =============================================================================
 // Populates the {{GROUP}} database with sample data for development.
 //
-// Usage: pnpm seed
+// Usage: bun seed
 // (runs via tsx, configured in packages/db/package.json)
 //
 // CONFIGURE: Replace the example inserts with your actual domain entities.

package/blueprints/features/env-t3/BLUEPRINT.md

@@ -243,7 +243,7 @@ All core patterns are project-type-agnostic:
 
 ### Phase 4: Verification
 
-15. Run `pnpm dev` (or equivalent) — env validation should run without errors
+15. Run `bun dev` (or equivalent) — env validation should run without errors
 16. Try removing a required variable from `.env.local` — build should fail with a clear error message
 
 ---

package/blueprints/features/tailwind-v4/BLUEPRINT.md

@@ -175,6 +175,10 @@ For standalone applications without a monorepo, the tailwind config lives direct
 
 ## Integration Steps
 
+### Design System Integration
+
+If a custom design system exists at `docs/design/shared-styles.css` (created by `/design-system`), the scaffold process uses it instead of the generic template below. This means the colors, typography, shadows, and animations in the installed `shared-styles.css` will reflect your product's visual identity rather than the default shadcn palette.
+
 ### Phase 1: Upgrade Tailwind Config
 
 **If foundation's `config/tailwind-config/` exists:**
@@ -194,12 +198,12 @@ For standalone applications without a monorepo, the tailwind config lives direct
 
 ### Phase 2: Dependency Installation
 
-5. Run `pnpm install` to fetch new dependencies
+5. Run `bun install` to fetch new dependencies
 6. Verify no peer dependency warnings
 
 ### Phase 3: Verification
 
-7. Run `pnpm dev` — the app should start without CSS errors
+7. Run `bun dev` — the app should start without CSS errors
 8. Verify dark mode works: add `class="dark"` to `<html>` and confirm colors change
 9. Verify animation classes work: try `animate-fade-in` on an element
 
@@ -236,6 +240,9 @@ For standalone applications without a monorepo, the tailwind config lives direct
 - Whether to include chart tokens
 - Whether to include scrollbar-hide
 - Additional custom tokens can be added to `@theme inline`
+- Shadow scale values (ambient/diffused, sharp/dramatic, or brand-tinted styles in the `@theme {}` block)
+- Custom easing curves (`--ease-smooth`, `--ease-spring`, etc.) for animation personality
+- Animation definitions and `@keyframes` — all defined in `@theme {}` alongside shadows and easing
 
 ## What's Opinionated
 

package/blueprints/features/tailwind-v4/files/tailwind-config/shared-styles.css

@@ -13,7 +13,7 @@
   --color-background: var(--background);
   --color-foreground: var(--foreground);
   --font-sans: var(--font-sans);
-  --font-mono: var(--font-geist-mono);
+  --font-mono: var(--font-mono);
   --color-sidebar-ring: var(--sidebar-ring);
   --color-sidebar-border: var(--sidebar-border);
   --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
@@ -52,6 +52,75 @@
   --radius-4xl: calc(var(--radius) + 16px);
 }
 
+/* ==========================================================================
+   Extended theme — shadows, easing, animations
+   ========================================================================== */
+
+@theme {
+  /* Shadow scale — ambient style, neutral black */
+  --shadow-2xs: 0 1px rgb(0 0 0 / 0.03);
+  --shadow-xs: 0 1px 2px 0 rgb(0 0 0 / 0.04);
+  --shadow-sm: 0 1px 3px 0 rgb(0 0 0 / 0.06), 0 1px 2px -1px rgb(0 0 0 / 0.06);
+  --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.07), 0 2px 4px -2px rgb(0 0 0 / 0.05);
+  --shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.07), 0 4px 6px -4px rgb(0 0 0 / 0.05);
+  --shadow-xl: 0 20px 25px -5px rgb(0 0 0 / 0.07), 0 8px 10px -6px rgb(0 0 0 / 0.05);
+  --shadow-2xl: 0 25px 50px -12px rgb(0 0 0 / 0.15);
+
+  /* Easing curves */
+  --ease-in: cubic-bezier(0.4, 0, 1, 1);
+  --ease-out: cubic-bezier(0, 0, 0.2, 1);
+  --ease-in-out: cubic-bezier(0.4, 0, 0.2, 1);
+  --ease-spring: cubic-bezier(0.34, 1.56, 0.64, 1);
+  --ease-smooth: cubic-bezier(0.25, 0.1, 0.25, 1);
+
+  /* Custom animations */
+  --animate-fade-in: fade-in 0.15s var(--ease-out);
+  --animate-fade-out: fade-out 0.1s var(--ease-in);
+  --animate-slide-up: slide-up 0.2s var(--ease-out);
+  --animate-slide-down: slide-down 0.2s var(--ease-out);
+  --animate-slide-in-from-left: slide-in-from-left 0.2s var(--ease-out);
+  --animate-slide-in-from-right: slide-in-from-right 0.2s var(--ease-out);
+  --animate-scale-in: scale-in 0.15s var(--ease-out);
+  --animate-scale-out: scale-out 0.1s var(--ease-in);
+
+  @keyframes fade-in {
+    from { opacity: 0; }
+    to { opacity: 1; }
+  }
+  @keyframes fade-out {
+    from { opacity: 1; }
+    to { opacity: 0; }
+  }
+  @keyframes slide-up {
+    from { transform: translateY(8px); opacity: 0; }
+    to { transform: translateY(0); opacity: 1; }
+  }
+  @keyframes slide-down {
+    from { transform: translateY(-8px); opacity: 0; }
+    to { transform: translateY(0); opacity: 1; }
+  }
+  @keyframes slide-in-from-left {
+    from { transform: translateX(-100%); }
+    to { transform: translateX(0); }
+  }
+  @keyframes slide-in-from-right {
+    from { transform: translateX(100%); }
+    to { transform: translateX(0); }
+  }
+  @keyframes scale-in {
+    from { transform: scale(0.95); opacity: 0; }
+    to { transform: scale(1); opacity: 1; }
+  }
+  @keyframes scale-out {
+    from { transform: scale(1); opacity: 1; }
+    to { transform: scale(0.95); opacity: 0; }
+  }
+}
+
+/* ==========================================================================
+   Color tokens — light mode
+   ========================================================================== */
+
 :root {
   --background: oklch(1 0 0);
   --foreground: oklch(0.145 0 0);
@@ -85,8 +154,14 @@
   --sidebar-accent-foreground: oklch(0.205 0 0);
   --sidebar-border: oklch(0.922 0 0);
   --sidebar-ring: oklch(0.708 0 0);
+  --font-sans: ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
+  --font-mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace;
 }
 
+/* ==========================================================================
+   Color tokens — dark mode
+   ========================================================================== */
+
 .dark {
   --background: oklch(0.145 0 0);
   --foreground: oklch(0.985 0 0);
@@ -121,6 +196,10 @@
   --sidebar-ring: oklch(0.556 0 0);
 }
 
+/* ==========================================================================
+   Base layer defaults
+   ========================================================================== */
+
 @layer base {
   * {
     @apply border-border outline-ring/50;