@withmata/blueprints 0.2.0 → 0.3.2

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

@@ -6,24 +6,274 @@ Feature
 
 ## Status
 
-Planned.
+Complete.
 
 ## Problem
 
-The foundation blueprint creates a minimal `config/tailwind-config/` package with basic theme tokens. Production apps need a complete design system: extended color palettes, dark mode strategy, animation utilities, typography scale, font loading, and component-friendly CSS custom properties. This blueprint extends the foundation's base into a full design system.
+The foundation blueprint creates a minimal `config/tailwind-config/` package with basic theme tokens — enough to get started but not enough for production apps. A complete design system needs: animation utilities, typography plugin, sidebar tokens for dashboard layouts, chart tokens for data visualization, scrollbar utilities, and the full shadcn/ui CSS integration. Setting up these imports and tokens correctly with Tailwind v4's CSS-based configuration is non-obvious and error-prone.
 
-## Intended Scope
-
-- Extended CSS custom properties and design tokens in `config/tailwind-config/`
-- Dark mode setup (class-based or media-query)
-- Animation utilities and keyframes
-- Typography scale and font loading (local + variable fonts)
-- Color palette generation using OKLCH color space
-- shadcn/ui-compatible token structure
-- Documentation of available tokens and usage patterns
+This blueprint upgrades the foundation's minimal tailwind-config into a production-ready design system.
 
 ## Blueprint Dependencies
 
 | Blueprint | Type | Why |
 |-----------|------|-----|
-| `foundation/monorepo-turbo` | recommended | Provides the base `config/tailwind-config/` package with minimal theme tokens. Without it, this blueprint creates the config structure from scratch. Works in both monorepo and single-repo projects. |
+| `foundation/monorepo-turbo` | recommended | Provides the base `config/tailwind-config/` package with minimal theme tokens. Without it, this blueprint creates the config structure from scratch. |
+
+---
+
+## Architecture
+
+### Core Pattern
+
+Tailwind v4 uses **CSS-based configuration** instead of JavaScript config files. All theme tokens, custom variants, and plugin imports are defined in `shared-styles.css` — a single CSS file that serves as the design system source of truth. This file is exported from the `config/tailwind-config/` workspace package and imported by every app and package that uses Tailwind.
+
+### Key Decisions
+
+- **CSS-based configuration only** (required) — Tailwind v4 uses `@theme inline`, `@custom-variant`, and `@import` directives in CSS. No `tailwind.config.js`. This is the Tailwind v4 way and enables better tree-shaking and faster builds.
+
+- **OKLCH color space** (required) — All color tokens use the `oklch()` color function for perceptually uniform colors. This produces better gradients, more accessible contrast ratios, and a wider gamut than hex/RGB. Colors are defined as CSS custom properties in `:root` and `.dark` selectors.
+
+- **Class-based dark mode** (required) — Uses `@custom-variant dark (&:is(.dark *))` for class-based dark mode toggling. This integrates with Next.js theme providers and gives JavaScript control over the theme (vs. media-query which follows OS preference only).
+
+- **shadcn/ui CSS integration** (required) — Imports `shadcn/tailwind.css` which provides the CSS variable structure that shadcn components expect. This is required for any project using shadcn/ui components.
+
+- **Animation utilities** (required) — Imports `tw-animate-css` for common animation classes (fade-in, slide-in, etc.) used by shadcn components and dialog/popover transitions.
+
+- **Scrollbar hiding** (recommended) — Imports `tailwind-scrollbar-hide/v4` for utility classes that hide scrollbars while maintaining scroll functionality. Useful for custom scroll areas and overflow containers.
+
+- **Typography plugin** (recommended) — `@tailwindcss/typography` is included as a dependency but imported by consuming apps (via `@plugin`) rather than the config. This allows per-app control over prose styling.
+
+- **Sidebar tokens** (recommended) — CSS variables for sidebar-specific colors (`--sidebar`, `--sidebar-primary`, `--sidebar-accent`, etc.) for dashboard layouts. These tokens integrate with shadcn's sidebar component.
+
+- **Chart tokens** (recommended) — CSS variables for data visualization (`--chart-1` through `--chart-5`) with OKLCH values that work well together in both light and dark modes.
+
+- **Extended radius scale** (recommended) — Adds `--radius-3xl` and `--radius-4xl` beyond the foundation's base radius tokens, useful for larger cards and containers.
+
+---
+
+## Hard Requirements vs Recommended Defaults
+
+**Hard requirements:**
+- Tailwind CSS v4
+- CSS-based configuration (`shared-styles.css`)
+- OKLCH color space for all color tokens
+- Class-based dark mode
+- shadcn/ui CSS variable structure
+
+**Recommended defaults — ask during scaffolding:**
+
+| Choice | Recommended | Alternatives |
+|---|---|---|
+| Include sidebar tokens | Yes | No (if not building dashboards) |
+| Include chart tokens | Yes | No (if not doing data visualization) |
+| Include scrollbar-hide | Yes | No |
+| Primary color hue | 264 (indigo/violet) | Any OKLCH hue value |
+
+---
+
+## Dependencies
+
+### npm packages
+
+**config/tailwind-config:**
+| Package | Version | Purpose |
+|---|---|---|
+| `@tailwindcss/typography` | ^0.5 | Prose styling for rich text content |
+| `shadcn` | ^3 | shadcn/ui CSS integration and component CLI |
+| `tailwind-scrollbar-hide` | ^4 | Utility classes for hiding scrollbars |
+| `tw-animate-css` | ^1 | Animation utility classes for transitions |
+
+**config/tailwind-config (dev):**
+| Package | Version | Purpose |
+|---|---|---|
+| `@tailwindcss/postcss` | ^4 | PostCSS plugin for Tailwind v4 |
+| `tailwindcss` | ^4 | Tailwind CSS v4 core |
+
+---
+
+## Monorepo Wiring
+
+### Tailwind Config Package (`config/tailwind-config/`)
+
+**`package.json` exports:**
+```json
+{
+  "exports": {
+    ".": "./shared-styles.css",
+    "./postcss": "./postcss.config.mjs"
+  }
+}
+```
+
+**File structure:**
+```
+config/tailwind-config/
+├── package.json               # Package config with exports and deps
+├── shared-styles.css          # Full design system (tokens, colors, dark mode)
+└── postcss.config.mjs         # PostCSS config with @tailwindcss/postcss
+```
+
+### Consuming Apps
+
+Apps import the tailwind config in their `globals.css`:
+
+```css
+@import "tailwindcss";
+@import "{{SCOPE}}/tailwind-config";
+```
+
+Typography plugin is added per-app:
+```css
+@plugin "@tailwindcss/typography";
+```
+
+---
+
+## Single-Repo Adaptation
+
+For standalone applications without a monorepo, the tailwind config lives directly in the project.
+
+### Path Mapping
+
+| Aspect | Monorepo | Single-Repo |
+|--------|----------|-------------|
+| Config location | `config/tailwind-config/` (workspace package) | `src/styles/` or project root |
+| Import in globals.css | `@import "{{SCOPE}}/tailwind-config"` | `@import "./src/styles/shared-styles.css"` or inline |
+| Package dependencies | In `config/tailwind-config/package.json` | In root `package.json` |
+| PostCSS config | Exported from config package | At project root |
+
+### Single-Repo File Structure
+
+```
+<project-root>/
+├── src/styles/
+│   └── shared-styles.css      # Full design system
+├── postcss.config.mjs         # PostCSS config
+├── app/globals.css            # Imports shared-styles.css directly
+└── package.json               # All deps at root
+```
+
+### What Stays the Same
+
+- CSS-based configuration pattern
+- All theme tokens, color values, dark mode setup
+- `@import` chain and plugin usage
+- OKLCH color space
+- shadcn/ui compatibility
+
+---
+
+## File Manifest
+
+| File | Purpose | Monorepo Target | Single-Repo Target |
+|---|---|---|---|
+| `files/tailwind-config/shared-styles.css` | Full design system: tokens, colors, dark mode, animations | `config/tailwind-config/shared-styles.css` | `src/styles/shared-styles.css` |
+| `files/tailwind-config/package.json` | Package config with all design system deps | `config/tailwind-config/package.json` | N/A (deps go in root `package.json`) |
+
+---
+
+## Integration Steps
+
+### Phase 1: Upgrade Tailwind Config
+
+**If foundation's `config/tailwind-config/` exists:**
+
+1. Replace `shared-styles.css` with the full version from this blueprint
+2. Merge dependencies into the existing `package.json`:
+   - Add `@tailwindcss/typography`, `shadcn`, `tailwind-scrollbar-hide`, `tw-animate-css` to `dependencies`
+   - Keep existing `devDependencies` (`@tailwindcss/postcss`, `tailwindcss`)
+3. Keep existing `postcss.config.mjs` (unchanged)
+
+**If no existing config:**
+
+1. Create `config/tailwind-config/` directory
+2. Copy `shared-styles.css` — replace `{{SCOPE}}` placeholders
+3. Copy `package.json` — replace `{{SCOPE}}`
+4. Create `postcss.config.mjs` (same as foundation's version)
+
+### Phase 2: Dependency Installation
+
+5. Run `pnpm 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
+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
+
+---
+
+## Maintenance Hooks
+
+### Design System Hooks
+
+| When you... | Then do... | Why |
+|---|---|---|
+| Add a new color token | Add CSS variable to both `:root` and `.dark`, then map it in `@theme inline` | Missing from either = broken in one mode |
+| Add a sidebar component | Verify sidebar tokens exist in `shared-styles.css` | Sidebar components reference `--sidebar-*` variables |
+| Upgrade Tailwind CSS | Check for breaking changes in `@import` syntax or `@theme` directives | v4 API is still evolving |
+| Add a new app to the monorepo | Import `{{SCOPE}}/tailwind-config` in the new app's `globals.css` | New apps don't automatically get the design system |
+
+### Condensed Rules for project rules file
+
+```markdown
+### 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
+```
+
+---
+
+## What's Configurable
+
+- Primary color hue (OKLCH hue value)
+- Whether to include sidebar tokens
+- Whether to include chart tokens
+- Whether to include scrollbar-hide
+- Additional custom tokens can be added to `@theme inline`
+
+## What's Opinionated
+
+- **Tailwind CSS v4** — CSS-based config, not JavaScript
+- **OKLCH color space** — no hex or RGB color values
+- **Class-based dark mode** — not media-query based
+- **shadcn/ui CSS structure** — CSS variables follow shadcn conventions
+- **`shared-styles.css` as single source** — one file for the entire design system, not split across multiple files
+
+## Project Context Output
+
+Appends to `.project-context.md` under `## Installed Blueprints`:
+
+```yaml
+### tailwind-v4
+blueprint: tailwind-v4
+choices:
+  include_sidebar_tokens: true
+  include_chart_tokens: true
+  include_scrollbar_hide: true
+  primary_hue: 264
+files_modified:
+  - config/tailwind-config/shared-styles.css
+  - config/tailwind-config/package.json
+packages_added:
+  - "@tailwindcss/typography"
+  - shadcn
+  - tailwind-scrollbar-hide
+  - tw-animate-css
+```
+
+---
+
+## References
+
+- **Tailwind CSS v4 Docs:** https://tailwindcss.com/docs
+- **Tailwind v4 CSS Config:** https://tailwindcss.com/docs/theme
+- **OKLCH Color Space:** https://oklch.com/
+- **shadcn/ui Theming:** https://ui.shadcn.com/docs/theming
+- **tw-animate-css:** https://github.com/Wombosvideo/tw-animate-css
+- **tailwind-scrollbar-hide:** https://github.com/reslear/tailwind-scrollbar-hide

package/blueprints/features/tailwind-v4/files/tailwind-config/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "{{SCOPE}}/tailwind-config",
+  "version": "0.0.0",
+  "type": "module",
+  "private": true,
+  "exports": {
+    ".": "./shared-styles.css",
+    "./postcss": "./postcss.config.mjs"
+  },
+  "dependencies": {
+    "@tailwindcss/typography": "^0.5",
+    "shadcn": "^3",
+    "tailwind-scrollbar-hide": "^4",
+    "tw-animate-css": "^1"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4",
+    "tailwindcss": "^4"
+  }
+}

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

@@ -0,0 +1,131 @@
+@import "tailwindcss";
+@import "tw-animate-css";
+@import "shadcn/tailwind.css";
+@import "tailwind-scrollbar-hide/v4";
+
+@custom-variant dark (&:is(.dark *));
+
+/* ==========================================================================
+   Theme tokens — OKLCH color space, shadcn/ui compatible
+   ========================================================================== */
+
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --font-sans: var(--font-sans);
+  --font-mono: var(--font-geist-mono);
+  --color-sidebar-ring: var(--sidebar-ring);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-primary: var(--sidebar-primary);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-sidebar: var(--sidebar);
+  --color-chart-5: var(--chart-5);
+  --color-chart-4: var(--chart-4);
+  --color-chart-3: var(--chart-3);
+  --color-chart-2: var(--chart-2);
+  --color-chart-1: var(--chart-1);
+  --color-ring: var(--ring);
+  --color-input: var(--input);
+  --color-border: var(--border);
+  --color-destructive: var(--destructive);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-accent: var(--accent);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-muted: var(--muted);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-secondary: var(--secondary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-primary: var(--primary);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-popover: var(--popover);
+  --color-card-foreground: var(--card-foreground);
+  --color-card: var(--card);
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+  --radius-2xl: calc(var(--radius) + 8px);
+  --radius-3xl: calc(var(--radius) + 12px);
+  --radius-4xl: calc(var(--radius) + 16px);
+}
+
+:root {
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.145 0 0);
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0.145 0 0);
+  --popover: oklch(1 0 0);
+  --popover-foreground: oklch(0.145 0 0);
+  --primary: oklch(0.488 0.243 264.376);
+  --primary-foreground: oklch(0.97 0.014 254.604);
+  --secondary: oklch(0.967 0.001 286.375);
+  --secondary-foreground: oklch(0.21 0.006 285.885);
+  --muted: oklch(0.97 0 0);
+  --muted-foreground: oklch(0.556 0 0);
+  --accent: oklch(0.97 0 0);
+  --accent-foreground: oklch(0.205 0 0);
+  --destructive: oklch(0.58 0.22 27);
+  --border: oklch(0.922 0 0);
+  --input: oklch(0.922 0 0);
+  --ring: oklch(0.708 0 0);
+  --chart-1: oklch(0.809 0.105 251.813);
+  --chart-2: oklch(0.623 0.214 259.815);
+  --chart-3: oklch(0.546 0.245 262.881);
+  --chart-4: oklch(0.488 0.243 264.376);
+  --chart-5: oklch(0.424 0.199 265.638);
+  --radius: 0.625rem;
+  --sidebar: oklch(0.985 0 0);
+  --sidebar-foreground: oklch(0.145 0 0);
+  --sidebar-primary: oklch(0.546 0.245 262.881);
+  --sidebar-primary-foreground: oklch(0.97 0.014 254.604);
+  --sidebar-accent: oklch(0.97 0 0);
+  --sidebar-accent-foreground: oklch(0.205 0 0);
+  --sidebar-border: oklch(0.922 0 0);
+  --sidebar-ring: oklch(0.708 0 0);
+}
+
+.dark {
+  --background: oklch(0.145 0 0);
+  --foreground: oklch(0.985 0 0);
+  --card: oklch(0.205 0 0);
+  --card-foreground: oklch(0.985 0 0);
+  --popover: oklch(0.205 0 0);
+  --popover-foreground: oklch(0.985 0 0);
+  --primary: oklch(0.42 0.18 266);
+  --primary-foreground: oklch(0.97 0.014 254.604);
+  --secondary: oklch(0.274 0.006 286.033);
+  --secondary-foreground: oklch(0.985 0 0);
+  --muted: oklch(0.269 0 0);
+  --muted-foreground: oklch(0.708 0 0);
+  --accent: oklch(0.371 0 0);
+  --accent-foreground: oklch(0.985 0 0);
+  --destructive: oklch(0.704 0.191 22.216);
+  --border: oklch(1 0 0 / 10%);
+  --input: oklch(1 0 0 / 15%);
+  --ring: oklch(0.556 0 0);
+  --chart-1: oklch(0.809 0.105 251.813);
+  --chart-2: oklch(0.623 0.214 259.815);
+  --chart-3: oklch(0.546 0.245 262.881);
+  --chart-4: oklch(0.488 0.243 264.376);
+  --chart-5: oklch(0.424 0.199 265.638);
+  --sidebar: oklch(0.205 0 0);
+  --sidebar-foreground: oklch(0.985 0 0);
+  --sidebar-primary: oklch(0.623 0.214 259.815);
+  --sidebar-primary-foreground: oklch(0.97 0.014 254.604);
+  --sidebar-accent: oklch(0.269 0 0);
+  --sidebar-accent-foreground: oklch(0.985 0 0);
+  --sidebar-border: oklch(1 0 0 / 10%);
+  --sidebar-ring: oklch(0.556 0 0);
+}
+
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+  }
+  body {
+    @apply bg-background text-foreground;
+  }
+}