@withmata/blueprints 0.3.1 → 0.3.3

package/.claude/skills/scaffold-tailwind/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: scaffold-tailwind
+description: Scaffold Tailwind v4 full design system into the current project
+---
+
+# Scaffold Tailwind v4 Blueprint
+
+Scaffold the `tailwind-v4` blueprint into the current project. This upgrades the foundation's minimal tailwind-config into a production-ready design system with animations, typography, sidebar tokens, and full shadcn/ui integration.
+
+## Step 1: Read the Blueprint
+
+Read the full BLUEPRINT.md and all template files from the tailwind blueprint:
+
+```
+~/.withmata/blueprints/blueprints/features/tailwind-v4/BLUEPRINT.md
+~/.withmata/blueprints/blueprints/features/tailwind-v4/files/**/*
+```
+
+If not found at these paths, run `npx @withmata/blueprints` to install.
+
+## Step 1.5: Read Project Context
+
+Check if `.project-context.md` exists in the target project root:
+
+- **If it exists**: read it to understand:
+  - npm scope (from Foundation)
+  - Whether `monorepo-turbo` foundation is installed
+  - What other blueprints are already installed
+  - Use this to determine if `config/tailwind-config/` exists
+
+- **If it does not exist**: proceed normally — explore the project manually
+
+## Step 2: Understand the Target Project
+
+### 2a. Detect Project Type
+
+Check `.project-context.md` for `project_type`. If not present, detect:
+
+- **Monorepo indicators**: `pnpm-workspace.yaml`, `turbo.json`, or `"workspaces"` in root `package.json`
+- **Single-repo indicators**: Single `package.json` at root, `src/` directory
+
+### 2b. Check Existing Tailwind Setup
+
+- Does `config/tailwind-config/` exist? (Foundation blueprint creates this)
+- Read existing `shared-styles.css` — is it the minimal version or already upgraded?
+- Read existing `package.json` — what deps are already present?
+- Check `tailwind-v4` in `.project-context.md` Installed Blueprints — already installed?
+
+## Step 3: Ask Clarifying Questions
+
+1. **Sidebar tokens** — "Include sidebar-specific color tokens for dashboard layouts? (Default: yes)"
+2. **Chart tokens** — "Include chart color tokens for data visualization? (Default: yes)"
+
+Skip questions if the user has indicated preferences or if the project type makes the answer obvious.
+
+## Step 4: Adapt and Scaffold
+
+### 4a. Monorepo — Upgrade Existing Config
+
+**If `config/tailwind-config/` exists (foundation was run):**
+
+1. **Replace `shared-styles.css`** — Copy the full version from this blueprint, replacing the foundation's minimal version entirely. The full version includes everything the minimal version had, plus:
+   - `@import "tw-animate-css"`
+   - `@import "shadcn/tailwind.css"`
+   - `@import "tailwind-scrollbar-hide/v4"`
+   - Sidebar tokens (`--color-sidebar-*`)
+   - Chart tokens (`--color-chart-*`)
+   - Extended radius tokens (`--radius-3xl`, `--radius-4xl`)
+   - Font mono token (`--font-mono`)
+
+2. **Merge `package.json` dependencies** — Add these to the existing `dependencies`:
+   - `@tailwindcss/typography`
+   - `shadcn`
+   - `tailwind-scrollbar-hide`
+   - `tw-animate-css`
+   Keep existing `devDependencies` unchanged.
+
+3. **Leave `postcss.config.mjs` unchanged** — it's already correct from foundation.
+
+**If `config/tailwind-config/` does NOT exist:**
+
+1. Create the `config/tailwind-config/` directory
+2. Copy `shared-styles.css` from template
+3. Copy `package.json` from template — replace `{{SCOPE}}`
+4. Create `postcss.config.mjs`:
+   ```javascript
+   export const postcssConfig = {
+     plugins: {
+       "@tailwindcss/postcss": {},
+     },
+   };
+   ```
+
+### 4b. Single-Repo
+
+1. Create `src/styles/shared-styles.css` from template
+2. Add all design system deps to root `package.json`
+3. Update `globals.css` or equivalent to import the shared styles:
+   ```css
+   @import "./src/styles/shared-styles.css";
+   ```
+
+### 4c. Install Dependencies
+
+Run `pnpm install` (or the project's package manager) to fetch new dependencies.
+
+## Step 5: Update Project Context
+
+Append an entry to `.project-context.md` under `## Installed Blueprints`:
+
+```yaml
+### tailwind-v4
+blueprint: tailwind-v4
+choices:
+  include_sidebar_tokens: <true|false>
+  include_chart_tokens: <true|false>
+  include_scrollbar_hide: <true|false>
+files_modified:
+  - config/tailwind-config/shared-styles.css
+  - config/tailwind-config/package.json
+packages_added:
+  - "@tailwindcss/typography"
+  - shadcn
+  - tailwind-scrollbar-hide
+  - tw-animate-css
+```
+
+### Create Maintenance Skill
+
+Create a project-level maintenance skill:
+
+**File:** `<project>/.claude/skills/tailwind-maintenance/SKILL.md`
+
+```yaml
+---
+name: tailwind-maintenance
+description: Maintenance rules for Tailwind v4 design system. Invoke when modifying theme tokens, colors, or adding new apps.
+user-invocable: false
+---
+
+### tailwind-v4 maintenance
+- After adding a new color: add CSS variable to both :root and .dark selectors in shared-styles.css, then map in @theme inline
+- After adding a new app: import the tailwind-config package in the app's globals.css
+- After upgrading Tailwind: check for @import, @theme, or @custom-variant breaking changes
+- Never use tailwind.config.js — all configuration is CSS-based in shared-styles.css
+- Colors use OKLCH color space — do not use hex or RGB
+```
+
+## Step 6: Output Summary
+
+### Packages Added
+
+```
+@tailwindcss/typography, shadcn, tailwind-scrollbar-hide, tw-animate-css
+```
+
+### Files Modified
+
+List every file created or modified with a one-line description.
+
+### What Changed from Foundation
+
+- `shared-styles.css` upgraded with animation imports, sidebar tokens, chart tokens, scrollbar utility
+- `package.json` now includes design system dependencies
+- Typography plugin available (add `@plugin "@tailwindcss/typography"` in app globals.css)
+
+### Next Steps
+
+- Add `@plugin "@tailwindcss/typography"` to your app's `globals.css` if you need prose styling
+- Customize the primary color hue in `:root` and `.dark` (currently indigo at hue 264)
+- Run `/scaffold-ui` to set up a shared component library that uses this design system
+
+## Important Notes
+
+- The full `shared-styles.css` is a complete replacement — it includes everything the foundation's minimal version had plus the new additions.
+- Never overwrite `postcss.config.mjs` — it's already correct from the foundation.
+- If the user has customized colors in the existing `shared-styles.css`, ask before replacing. Offer to merge their custom values into the new file.

package/.claude/skills/scaffold-ui/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: scaffold-ui
+description: Scaffold shared UI component library with shadcn/ui into the current project
+---
+
+# Scaffold UI Blueprint
+
+Scaffold the `ui-shared-components` blueprint into the current project. Read the full blueprint first, then adapt it to this project's stack.
+
+## Step 1: Read the Blueprint
+
+Read the full BLUEPRINT.md and all template files from the UI blueprint:
+
+```
+~/.withmata/blueprints/blueprints/features/ui-shared-components/BLUEPRINT.md
+~/.withmata/blueprints/blueprints/features/ui-shared-components/files/**/*
+```
+
+If not found at these paths, run `npx @withmata/blueprints` to install.
+
+## Step 1.5: Read Project Context
+
+Check if `.project-context.md` exists in the target project root:
+
+- **If it exists**: read it to understand:
+  - npm scope (from Foundation)
+  - Whether `tailwind-v4` is installed (required dependency)
+  - What other blueprints are installed
+  - Use this to pre-fill scope and adapt paths
+
+- **If it does not exist**: proceed normally — explore the project manually
+
+When project context provides clear answers, skip the corresponding questions in Step 3.
+
+## Step 2: Understand the Target Project
+
+### 2a. Detect Project Type
+
+Check `.project-context.md` for `project_type`. If not present, detect:
+
+- **Monorepo indicators**: `pnpm-workspace.yaml`, `turbo.json`, or `"workspaces"` in root `package.json`
+- **Single-repo indicators**: Single `package.json` at root, `src/` directory
+
+### 2b. Check Blueprint Dependencies
+
+**Required: `tailwind-v4`**
+
+Check if `tailwind-v4` is in `.project-context.md` Installed Blueprints, OR check if `config/tailwind-config/shared-styles.css` contains `@import "tw-animate-css"` (indicator of the full tailwind-v4 blueprint).
+
+If NOT installed: ask "UI components need the Tailwind design system. Run `/scaffold-tailwind` first? (Y/n)"
+- If yes: tell the user to run `/scaffold-tailwind` first, then come back
+- If no: proceed with basic Tailwind defaults and warn about missing design tokens
+
+### 2c. Explore Structure
+
+**If monorepo:**
+1. Does `packages/ui/` already exist? If so, what's in it?
+2. What npm scope is used?
+3. What is the shared TypeScript config package name?
+4. Where are the consuming apps? (`apps/web/`, `apps/*/`, etc.)
+5. What's in the consuming app's `globals.css`?
+
+**If single-repo:**
+1. Does `src/ui/` or `src/components/` exist?
+2. What framework is this? (Next.js?)
+3. What import convention is used? (`@/`, `#`, relative?)
+
+## Step 3: Ask Clarifying Questions
+
+1. **shadcn style** — "Which shadcn style do you prefer? (Default: new-york)" Only ask if the user hasn't specified.
+
+2. **Icon library** — "Which icon library? Lucide (default, shadcn default), Phosphor (richer set), or custom?"
+
+3. **Existing `packages/ui/`** — If it exists: "I found an existing `packages/ui/`. I'll merge the new files without overwriting existing ones."
+
+Skip questions where the answer is obvious.
+
+## Step 4: Adapt and Scaffold
+
+### 4a. Monorepo — Create UI Package
+
+1. Create `packages/ui/` directory (if it doesn't exist)
+2. Copy `package.json` — replace `{{SCOPE}}` with the project's npm scope
+3. Copy `tsconfig.json` — replace `{{SCOPE}}`
+4. Copy `components.json` — update style if user chose something other than `new-york`, update iconLibrary if user chose something other than `lucide`
+5. Create `styles/` directory and copy `globals.css` — replace `{{SCOPE}}`
+6. Create `utils/` directory, copy `cn.ts` and `cva.ts`
+7. Create empty directories: `components/ui/`, `icons/`, `icons/logos/`
+
+### 4b. Single-Repo — Create UI Directory
+
+1. Create `src/ui/` directory structure
+2. Copy utility files (`cn.ts`, `cva.ts`) to `src/ui/utils/`
+3. Copy `styles/globals.css` to `src/ui/styles/` — adjust import to direct path
+4. Copy `components.json` to project root — update aliases for single-repo paths
+5. Create empty directories: `src/ui/components/ui/`, `src/ui/icons/`
+6. Add UI deps to root `package.json`
+
+### 4c. Update Consuming App
+
+**For each Next.js app (monorepo):**
+
+Update `app/globals.css`. The final file should look like:
+
+```css
+@import "tailwindcss";
+@import "{{SCOPE}}/tailwind-config";
+@import "{{SCOPE}}/ui/styles";
+@plugin "@tailwindcss/typography";
+
+@source "../../../packages/ui";
+```
+
+Compute the `@source` relative path based on the consuming app's location relative to `packages/ui/`. For example:
+- `apps/web/` → `@source "../../../packages/ui"` (if workspace root is 3 levels up... actually the typical path is `../../packages/ui` since apps/web/ is 2 levels)
+- Verify the path resolves correctly
+
+**Important:** Don't overwrite the entire `globals.css` — merge the new imports. If the file already has `@import "tailwindcss"` and `@import "{{SCOPE}}/tailwind-config"`, add the new lines after them.
+
+### 4d. Dependency Installation
+
+Run `pnpm install` to wire workspace dependencies.
+
+## Step 5: Update Project Context
+
+Append an entry to `.project-context.md` under `## Installed Blueprints`:
+
+```yaml
+### ui-shared-components
+blueprint: ui-shared-components
+choices:
+  shadcn_style: <style>
+  icon_library: <library>
+  include_cva: true
+files_created:
+  - <list of all files created>
+globals_css_updated:
+  - <list of globals.css files modified>
+packages_added:
+  - <list of packages>
+```
+
+### Create Maintenance Skill
+
+Create a project-level maintenance skill:
+
+**File:** `<project>/.claude/skills/ui-maintenance/SKILL.md`
+
+```yaml
+---
+name: ui-maintenance
+description: Maintenance rules for shared UI component library. Invoke when adding components, icons, or modifying the UI package.
+user-invocable: false
+---
+
+### 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
+```
+
+## Step 6: Output Summary
+
+### Packages to Install
+
+```bash
+# Should be handled by pnpm install, but verify these are in packages/ui/package.json:
+# Dependencies: @radix-ui/react-slot, class-variance-authority, clsx, tailwind-merge, tw-animate-css, shadcn
+# DevDeps: @tailwindcss/postcss, tailwindcss, typescript, @types/react, @types/react-dom
+```
+
+### Files Created
+
+List every file created or modified with a one-line description.
+
+### How to Add Components
+
+```bash
+# From packages/ui/
+cd packages/ui
+pnpm dlx shadcn@latest add button
+pnpm dlx shadcn@latest add card
+pnpm dlx shadcn@latest add input
+```
+
+### How to Use in Apps
+
+```typescript
+import { Button } from "@scope/ui/components/ui/button";
+import { cn } from "@scope/ui/utils/cn";
+```
+
+### Next Steps
+
+- Add your first shadcn components with the commands above
+- Create brand icons in `packages/ui/icons/logos/`
+- Build custom components in `packages/ui/components/`
+
+## Important Notes
+
+- When adapting code, preserve the `// CONFIGURE:` comments so the user can find customization points later.
+- Never overwrite existing files without asking. If `packages/ui/` exists, merge new files.
+- The `@source` directive path must be correct relative to the consuming app — verify it resolves.
+- If `tailwind-v4` is not installed and the user proceeds anyway, the UI package will work but may have missing design tokens (no animations, no sidebar colors, etc.).