canvas-ui-sdk 0.3.13 → 0.3.14

package/README.md

@@ -1,6 +1,6 @@
 # Canvas UI SDK
 
-A comprehensive UI component library with design tokens for building beautiful interfaces.
+A themeable React component library with a shadcn-style CLI for copying components into consumer projects, a visual theme editor, and an MCP server for Claude Code.
 
 ## Installation
 
@@ -8,57 +8,34 @@ A comprehensive UI component library with design tokens for building beautiful i
 npm install canvas-ui-sdk
 ```
 
-## Usage
+## CLI
 
-```tsx
-import { Button, DashboardShell, DataTable } from 'canvas-ui-sdk';
-
-export default function MyPage() {
-  return (
-    <DashboardShell>
-      <Button variant="primary">Click me</Button>
-      <DataTable data={myData} columns={myColumns} />
-    </DashboardShell>
-  );
-}
-```
+Components are copied as editable source files into your project. Dependencies are auto-resolved and npm packages auto-installed.
 
-## CSS Variables
+```bash
+# See all 140+ available components
+npx canvas-ui list
 
-This SDK uses CSS custom properties (variables) for theming. Define these in your project's `globals.css`:
+# Copy components into your project
+npx canvas-ui add <component-name>
 
-```css
-:root {
-  /* Colors */
-  --canvas-primary: #2563eb;
-  --canvas-secondary: #64748b;
-  --canvas-background: #ffffff;
-  --canvas-foreground: #0f172a;
-  --canvas-border: #e2e8f0;
-  
-  /* Typography */
-  --typo-font-primary: 'Inter', sans-serif;
-  --typo-base-size: 16px;
-  
-  /* Spacing */
-  --spacing-xs: 4px;
-  --spacing-sm: 8px;
-  --spacing-md: 16px;
-  --spacing-lg: 24px;
-  --spacing-xl: 32px;
-  
-  /* Border Radius */
-  --radius-sm: 4px;
-  --radius-md: 8px;
-  --radius-lg: 12px;
-}
+# Examples:
+npx canvas-ui add button                 # Copies button + utils
+npx canvas-ui add dashboard-shell        # Copies shell + sidebar + header + 15 deps
+npx canvas-ui add standard-data-table    # Copies table + pagination + deps
 ```
 
-See `styles/tokens.reference.css` for a complete list of available CSS variables.
+Then import from local paths:
 
-## Tailwind v4
+```tsx
+import { DashboardShell } from "@/components/layout/dashboard-shell";
+import { StandardDataTable } from "@/components/blocks/data-tables/standard-data-table";
+import { Button } from "@/components/ui/button";
+```
 
-If you're using Tailwind CSS v4, add these imports to your CSS file:
+## CSS Setup
+
+Add these imports to your `globals.css` (Tailwind v4):
 
 ```css
 @import "tailwindcss";
@@ -67,43 +44,53 @@ If you're using Tailwind CSS v4, add these imports to your CSS file:
 @source "../../node_modules/canvas-ui-sdk/dist";
 ```
 
-- `canvas-ui-sdk/tailwind` maps the SDK's design tokens to Tailwind's semantic color names (`bg-muted`, `text-primary`, etc.)
+- `canvas-ui-sdk/tailwind` maps design tokens to Tailwind's semantic color names (`bg-muted`, `text-primary`, etc.)
+- `canvas-ui-sdk/styles` loads the design system's CSS variables (colors, typography, spacing, etc.)
 - `@source` tells Tailwind to scan the SDK's compiled output for utility classes — adjust the relative path based on your `globals.css` location
 
+## CSS Variables
+
+Override design tokens in your `globals.css`:
+
+```css
+:root {
+  --canvas-primary: #16a34a;
+  --canvas-primary-dark: #15803d;
+  --canvas-primary-foreground: #ffffff;
+}
+```
+
+See `styles/tokens.reference.css` for the full list of available CSS variables.
+
+## MCP Server (Claude Code)
+
+Connect the MCP server so Claude Code can discover all components, templates, and design tokens:
+
+```bash
+claude mcp add canvas-ui-sdk node node_modules/canvas-ui-sdk/mcp/dist/index.js
+```
+
+## Live Theme Editor
+
+The `<ThemeDrawer>` component provides a visual editor for customizing colors, typography, button sizes, input styles, and branding in real-time. When you're happy with your theme, bake it into source code with `prompts/bake-theme.md`.
+
 ## Components
 
-### UI Components
-- Button, Input, Select, Checkbox, Switch
-- Dialog, Popover, Dropdown
-- Avatar, Badge, Card
-- And more...
+### UI Primitives
+Button, Input, Select, Checkbox, Switch, Dialog, Popover, Dropdown, Avatar, Tabs, Tooltip, and more.
 
 ### Blocks
-- DataTable, ChatBubble, ProfileCard
-- Marketing sections (Hero, Testimonials, CTA)
-- Pricing components
-- Graph and metric tiles
-
-### Layouts
-- DashboardShell
-- IconSidebarShell
-- DoubleSidebarShell
-- StandardPageShell
-- AccountSettingsShell
-- MultistepShell
-- MobileMenuShell
+Data tables, social feeds, charts, metric tiles, chat widgets, forms, calendars, and more.
+
+### Layout Shells
+DashboardShell, IconSidebarShell, DoubleSidebarShell, StandardPageShell, AccountSettingsShell, MultistepShell, MobileMenuShell.
 
 ## Development
 
 ```bash
-# Install dependencies
-npm install
-
-# Build the package
-npm run build
-
-# Watch mode for development
-npm run dev
+npm install    # Install dependencies
+npm run build  # Build dist + registry + CLI
+npm run dev    # Watch mode
 ```
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "canvas-ui-sdk",
-  "version": "0.3.13",
+  "version": "0.3.14",
   "type": "module",
   "description": "A comprehensive UI component library with design tokens for building beautiful interfaces",
   "bin": {
@@ -30,7 +30,8 @@
     "dist",
     "styles",
     "registry",
-    "mcp/dist"
+    "mcp/dist",
+    "prompts"
   ],
   "scripts": {
     "build": "tsup && node -e \"const fs = require('fs'); for (const f of ['dist/index.js','dist/charts.js']) { const c = fs.readFileSync(f,'utf8'); fs.writeFileSync(f, '\\\"use client\\\";\\n' + c); }\" && npm run cli:build",

package/prompts/CLAUDE.md

@@ -0,0 +1,85 @@
+# Canvas Consumer App
+
+This is a Next.js app that uses the Canvas UI SDK component library.
+
+## Adding Components
+
+This project uses a **shadcn-style CLI** to copy component source files from `canvas-ui-sdk` into the project for full customization.
+
+### Available commands
+
+```bash
+# See all available components (145 total: layouts, blocks, UI primitives, hooks)
+npx canvas-ui list
+
+# Copy components into the project (auto-resolves dependencies)
+npx canvas-ui add <component-name> [component-name...]
+
+# Examples:
+npx canvas-ui add button                 # Copies button + utils
+npx canvas-ui add dashboard-shell        # Copies shell + sidebar + header + 15 deps
+npx canvas-ui add standard-data-table    # Copies table + pagination + deps
+```
+
+### How it works
+
+- Components are copied as **editable source files** into `src/components/`
+- UI primitives go to `src/components/ui/`
+- Layout shells go to `src/components/layout/`
+- Block components go to `src/components/blocks/<category>/`
+- Hooks go to `src/hooks/`
+- Utilities go to `src/lib/`
+- Import paths use `@/` aliases (e.g. `@/components/ui/button`, `@/lib/utils`)
+- npm dependencies (like `@radix-ui/*`, `class-variance-authority`) are auto-installed
+
+### When building a page
+
+1. Decide which layout shell fits (run `npx canvas-ui list` to see options)
+2. Add the layout: `npx canvas-ui add <shell-name>`
+3. Add any blocks needed: `npx canvas-ui add <block-name> [block-name...]`
+4. Import components from their local paths (e.g. `import { Button } from "@/components/ui/button"`)
+5. Customize the copied source files as needed
+
+### What stays in the npm package (do NOT copy these)
+
+- Design tokens / CSS variables (`canvas-ui-sdk/styles`)
+- Tailwind theme mappings (`canvas-ui-sdk/tailwind`)
+- Theme context and providers (`canvas-ui-sdk`)
+
+These are imported directly from the npm package, not copied.
+
+## Design Tokens
+
+When creating or modifying components, always use the canvas design token CSS variables. Never use raw Tailwind color classes (`bg-white`, `text-gray-500`, `border-gray-200`) or hardcoded pixel values for font sizes. Use the token system instead:
+
+- **Colors**: `var(--canvas-background)`, `var(--canvas-text)`, `var(--canvas-primary)`, `var(--canvas-border)`, etc.
+- **Typography**: `var(--typo-body-s-size)`, `var(--typo-body-m-size)`, `var(--typo-h4-size)`, `var(--typo-global-font)`, etc.
+- **Spacing**: `var(--spacing-sm)`, `var(--spacing-md)`, `var(--spacing-lg)`, etc.
+- **Radii**: `var(--radius-xs)`, `var(--radius-sm)`, `var(--radius-md)`, etc.
+- **Inputs**: `var(--canvas-border-input)`, `var(--input-standard-height)`, `var(--input-standard-radius)`, etc.
+- **Buttons**: `var(--btn-primary-bg)`, `var(--btn-standard-height)`, etc.
+
+Reference the SDK's `styles/tokens.reference.css` for the full list of available tokens.
+
+## CSS Setup
+
+The app's `src/app/globals.css` imports:
+```css
+@import "tailwindcss";
+@import "canvas-ui-sdk/tailwind";
+@import "canvas-ui-sdk/styles";
+@source "../../node_modules/canvas-ui-sdk/dist";
+```
+
+## Project Structure
+
+```
+src/
+  app/           # Next.js app router pages
+  components/    # Copied Canvas UI components (editable)
+    ui/          # Primitives (button, input, dialog, etc.)
+    layout/      # Layout shells (dashboard-shell, sidebar, etc.)
+    blocks/      # Feature blocks (data-tables, forms, cards, etc.)
+  hooks/         # Copied hooks
+  lib/           # Utilities (utils.ts with cn() helper)
+```

package/prompts/bake-theme.md

@@ -0,0 +1,194 @@
+# Bake Theme Into Source Code
+
+## What this does
+
+Reads the saved theme from `.data/theme.json` and applies it as source-code defaults
+so the app loads with the correct styling on first paint — no flash of unstyled content.
+
+After baking, `.data/theme.json` is deleted and the ThemeDrawer starts fresh.
+
+---
+
+## Steps
+
+### 1. Read the saved theme
+
+Read `.data/theme.json`. It has this shape:
+
+```json
+{
+  "overrides": { "--canvas-primary": "#ee4c11", "--typo-global-font": "Lato", ... },
+  "branding":  { "iconShape": "rounded", "iconName": "WifiHigh", ... },
+  "images":    { "logoLight": "", "logoDark": "", ... },
+  "customButtonStyles": []
+}
+```
+
+If the file doesn't exist or is empty, stop — there's nothing to bake.
+
+### 2. Update `src/app/globals.css`
+
+For each entry in `overrides`, add or update the CSS variable in the correct block:
+
+| Variable pattern | Block | Notes |
+|-----------------|-------|-------|
+| `--canvas-*` (colors) | `:root { }` | e.g. `--canvas-primary: #ee4c11;` |
+| `--typo-*-size`, `--typo-*-weight`, `--typo-*-spacing`, `--typo-*-height` | `body { }` | e.g. `--typo-menu-label-size: 40;` |
+| `--typo-global-font` | `body { }` | Set as: `--typo-global-font: var(--font-FONTNAME), "FontName", sans-serif;` where FONTNAME is the lowercased, hyphenated font name. Also update the existing `--typo-global-font` line if present. |
+| `--typo-*-font` (per-component) | `body { }` | Only if the value is a real font name (not empty). Set as: `--typo-COMPONENT-font: "FontName", sans-serif;`. Remove the corresponding `--typo-*-font: initial;` line from `:root` if present. |
+| `--btn-*` (button styles) | `body { }` | e.g. `--btn-border-radius: 8;` |
+
+**Important:** Keep any existing variables that aren't in the overrides. Only add/update the ones from the saved theme.
+
+### 3. Add Google Font imports in `src/app/layout.tsx`
+
+For each unique font name found in the overrides (values of `--typo-*-font` variables):
+
+1. Add an import from `next/font/google` at the top of the file:
+   ```typescript
+   import { ExistingFont, NewFont } from "next/font/google";
+   ```
+
+2. Create the font instance:
+   ```typescript
+   const newFont = NewFont({
+     variable: "--font-new-font",
+     subsets: ["latin"],
+     weight: ["400", "500", "600", "700"],
+   });
+   ```
+
+3. Add the font's variable class to the `<body>` className:
+   ```typescript
+   <body className={`${existingFont.variable} ${newFont.variable} antialiased`}>
+   ```
+
+**Variable naming convention:** The CSS variable name is `--font-` followed by the font name in lowercase with spaces replaced by hyphens. For example, "Open Sans" becomes `--font-open-sans`.
+
+**Keep existing fonts.** Don't remove Inter, Geist, or Geist_Mono — they're still needed.
+
+### 4. Update `src/lib/theme-config.ts`
+
+Write the `branding` and `images` objects from the saved theme into this file:
+
+```typescript
+import type { BrandingState, ImageKey } from "canvas-ui-sdk";
+
+export const savedBranding: BrandingState = {
+  // paste values from theme.json branding
+};
+
+export const savedImages: Record<ImageKey, string> = {
+  // paste values from theme.json images
+};
+```
+
+### 5. Delete the saved theme file
+
+Remove `.data/theme.json` — the overrides are now baked into the source code.
+
+```bash
+rm .data/theme.json
+```
+
+### 6. Verify
+
+Run `npm run dev` and confirm:
+- The page loads with the correct colors, fonts, and branding on first paint
+- No flash of default styles
+- The theme drawer opens with no unsaved changes
+
+---
+
+## Example
+
+Given this `.data/theme.json`:
+
+```json
+{
+  "overrides": {
+    "--canvas-primary": "#ee4c11",
+    "--canvas-primary-dark": "#772609",
+    "--typo-global-font": "Lato",
+    "--typo-menu-label-font": "Open Sans",
+    "--typo-menu-label-size": "40",
+    "--typo-menu-label-weight": "700"
+  },
+  "branding": {
+    "iconShape": "rounded",
+    "iconName": "WifiHigh",
+    "bgColor": "var(--canvas-primary)",
+    "iconColor": "var(--canvas-primary-foreground)",
+    "wordmark": "ohhh"
+  },
+  "images": {
+    "logoLight": "",
+    "logoDark": "",
+    "faviconLight": "",
+    "faviconDark": ""
+  },
+  "customButtonStyles": []
+}
+```
+
+**globals.css** `:root` block gets:
+```css
+:root {
+  --canvas-primary: #ee4c11;
+  --canvas-primary-dark: #772609;
+  /* ... keep other existing variables ... */
+
+  /* Remove --typo-menu-label-font: initial; since it now has a real value */
+}
+```
+
+**globals.css** `body` block gets:
+```css
+body {
+  --typo-global-font: var(--font-lato), "Lato", sans-serif;
+  --typo-menu-label-font: "Open Sans", sans-serif;
+  --typo-menu-label-size: 40;
+  --typo-menu-label-weight: 700;
+  /* ... keep existing body styles ... */
+}
+```
+
+**layout.tsx** gets new font imports:
+```typescript
+import { Inter, Geist, Geist_Mono, Lato, Open_Sans } from "next/font/google";
+
+const lato = Lato({
+  variable: "--font-lato",
+  subsets: ["latin"],
+  weight: ["400", "700"],
+});
+
+const openSans = Open_Sans({
+  variable: "--font-open-sans",
+  subsets: ["latin"],
+  weight: ["400", "500", "600", "700"],
+});
+
+// In the body className:
+<body className={`${inter.variable} ${geistSans.variable} ${geistMono.variable} ${lato.variable} ${openSans.variable} antialiased`}>
+```
+
+**theme-config.ts** gets:
+```typescript
+import type { BrandingState, ImageKey } from "canvas-ui-sdk";
+
+export const savedBranding: BrandingState = {
+  iconShape: "rounded",
+  iconName: "WifiHigh",
+  bgColor: "var(--canvas-primary)",
+  iconColor: "var(--canvas-primary-foreground)",
+  wordmark: "ohhh",
+};
+
+export const savedImages: Record<ImageKey, string> = {
+  logoLight: "",
+  logoDark: "",
+  faviconLight: "",
+  faviconDark: "",
+};
+```