rafters 0.0.55 → 0.0.56

package/README.md

@@ -1,6 +1,8 @@
 # rafters
 
-Design Intelligence CLI. Scaffold tokens, add components, and serve an MCP server so AI agents build UIs with designer-level judgment instead of guessing.
+Design Intelligence CLI. Encodes a designer's judgment into queryable data so AI agents read decisions instead of guessing at colors, spacing, hierarchy.
+
+→ [rafters.studio](https://rafters.studio)
 
 ## Quick Start
 
@@ -8,24 +10,31 @@ Design Intelligence CLI. Scaffold tokens, add components, and serve an MCP serve
 pnpm dlx rafters init
 ```
 
-This detects your framework, scaffolds `.rafters/` with a complete token system, and generates output files.
+`init` detects your framework, reads your existing CSS (shadcn or Tailwind v4 `@theme` blocks), and produces a complete token system that imports your brand decisions and derives the rest mathematically.
+
+## What `init` does
 
-## Commands
+On the first run against an existing project, `init` runs an import flow that lifts brand decisions out of your CSS into the token system. Every step emits a discrete event you can read with `--agent`:
 
-### `rafters init`
+- **Pre-generation base detection** — reads `--spacing` / `--spacing-base`, `--radius` / `--radius-base`, `--text-base` / `--font-size-base`, `--ring-width` / `--focus-ring-width` and threads them into the token generator BEFORE construction. The cascade flows correctly from the first generation; derived namespaces (spacing scale, shadow numerics, radius scale, focus tokens) all match the imported base.
+- **Color import** — walks `:root` semantic declarations (`--primary`, `--background`, etc.) AND `@theme { ... }` multi-palette blocks (Tailwind v4 brand palette convention). Detects ramps (palette-0 through palette-950), runs a designer-driven role-walk in interactive mode or auto-assigns in `--agent` mode.
+- **Font role-walk** — detects every font family loaded by the source (`@import url(google fonts)`, `@font-face`, named `--font-*` declarations) and assigns each to a typography role (`font-heading`, `font-body`, `font-code`). Custom fonts that don't fit a canonical role become their own tokens (`font-aurabesh`, `font-mydisplay`, etc.) so consumers can reference them via Tailwind utilities.
+- **Motion is intentionally untouched** — rafters' motion system is research-backed (perceptual response curves, cognitive thresholds, reduced-motion accommodations); arbitrary `--duration-base` declarations in source are NOT auto-applied. Use `rafters set motion-duration-base ...` if you specifically need to override.
 
-Initialize a project with design tokens.
+### Modes
 
 ```bash
-pnpm dlx rafters init              # Interactive setup
-pnpm dlx rafters init --rebuild    # Regenerate output files from existing tokens
-pnpm dlx rafters init --reset      # Re-run generators fresh, replacing persisted tokens
-pnpm dlx rafters init --agent      # JSON output for CI/machine consumption
+pnpm dlx rafters init              # Interactive prompts for role assignments
+pnpm dlx rafters init --agent      # Non-interactive; auto-assigns; emits JSON events
+pnpm dlx rafters init --rebuild    # Regenerate output files from existing .rafters/tokens
+pnpm dlx rafters init --reset      # Re-run generators from defaults, replacing tokens
 ```
 
-**Detected frameworks:** Next.js, Vite, Remix, React Router, Astro
+### Detected frameworks
+
+Next.js, Vite, Remix, React Router, Astro, Web Components, vanilla.
 
-**Export formats** (configured during init):
+### Export formats
 
 | Format | File | Default | Description |
 |--------|------|---------|-------------|
@@ -34,19 +43,29 @@ pnpm dlx rafters init --agent      # JSON output for CI/machine consumption
 | DTCG JSON | `rafters.json` | No | W3C Design Tokens standard format |
 | Standalone CSS | `rafters.standalone.css` | No | Pre-built, no Tailwind required |
 
-Automatically detects and migrates existing shadcn/ui color values. Requires Tailwind v4.
+Requires Tailwind v4. Tailwind v3 projects are rejected.
+
+## Other commands
 
 ### `rafters add [components...]`
 
-Add components from the Rafters registry to your project.
+Add components from the rafters registry to your project.
 
 ```bash
 pnpm dlx rafters add button dialog    # Add specific components
-pnpm dlx rafters add --list           # List all available components
+pnpm dlx rafters add --list           # List available components
 pnpm dlx rafters add --overwrite      # Replace existing files
 ```
 
-Components include embedded design intelligence: cognitive load ratings (1-7), accessibility requirements, do/never guidance, and trust-building patterns. Dependencies are resolved automatically.
+Each component carries embedded design intelligence (cognitive load, accessibility, do/never guidance, variant patterns). Dependencies resolve automatically.
+
+### `rafters set <name> <value>`
+
+Override a token value with a recorded reason. The previous value and the why-gate land as `userOverride` metadata so future agents can read your intent.
+
+```bash
+pnpm dlx rafters set spacing-base 0.5rem --reason "denser layout for data-heavy UI"
+```
 
 ### `rafters mcp`
 
@@ -58,89 +77,98 @@ pnpm dlx rafters mcp
 
 ### `rafters studio`
 
-Launch Studio for visual token editing. Spawns a local Vite dev server from the `@rafters/studio` package.
+Launch Studio for visual token editing.
 
 ```bash
 pnpm dlx rafters studio
 ```
 
-## MCP Tools
+## MCP tools
 
-Four tools give AI agents complete design system access:
+Four tools for agent ASSEMBLY (not design). Token design lives in Studio; import lives in `rafters init`. Agents read pre-made decisions; they do not author them.
 
 ### `rafters_composite`
 
-Query composites by ID, search term, or category. Returns designer intent (solves, appliesWhen, do/never), I/O rules for chaining, and block structure.
+Query composites by ID, search term, or category. Returns designer intent (solves, appliesWhen, do/never), I/O rules, and block structure.
 
 ```json
-{ "id": "heading" }           // Get specific composite
-{ "query": "form" }           // Fuzzy search
-{ "category": "typography" }  // Filter by category
+{ "id": "login-form" }        // Get a specific composite
+{ "query": "form" }           // Fuzzy search across composites
+{ "category": "typography" }  // Filter
 ```
 
 ### `rafters_pattern`
 
-Design pattern guidance by querying composites. Search by what the pattern solves or use fuzzy search.
+Design pattern guidance by querying composites. Search by what the page or section SOLVES.
 
 ```json
-{ "solves": "hierarchy" }      // Find patterns for document hierarchy
-{ "solves": "authentication" } // Find patterns for auth flows
-{ "query": "form" }            // Fuzzy search across composites
+{ "solves": "authentication" }
+{ "solves": "data entry" }
+{ "query": "navigation" }
 ```
 
-Returns composites with usagePatterns (do/never rules), cognitive load, and designer intent.
+Returns composites with usagePatterns (do/never), cognitive load, and intent.
 
 ### `rafters_rule`
 
-Query validation rules or create new ones. Rules are named validation patterns that composites can apply.
+Query validation rules or create new ones. Rules are named patterns composites apply to inputs.
 
 ```json
 {}                    // List all rules
-{ "name": "email" }   // Get specific rule
-{ "query": "pass" }   // Search rules
+{ "name": "email" }   // Get a specific rule
 ```
 
-**Built-in rules:** `required`, `email`, `password`, `url`, `credentials`
+Built-in: `required`, `email`, `password`, `url`, `credentials`.
 
 ### `rafters_component`
 
-Full intelligence for a specific component. Cognitive load rating, attention economics, accessibility requirements, trust-building patterns, variants, sizes, and primitives.
+Full intelligence for a specific component: cognitive load, accessibility level, variants, sizes, do/never.
 
 ```json
 { "name": "button" }
 ```
 
-## How It Works
-
-Rafters is a Design Intelligence Protocol. AI agents don't have taste -- they guess at colors, spacing, hierarchy. Rafters encodes a designer's judgment into queryable data so AI reads decisions instead of guessing.
+## Architecture
 
 Three layers:
 
-- **What** (Components) -- 55 React components with embedded intelligence metadata
-- **Where** (Tokens) -- 240+ tokens with dependency graph and human override tracking
-- **Why** (Decisions) -- Do/never patterns, cognitive load scores, trust patterns, accessibility requirements
+- **What (Components)** — React components with embedded intelligence metadata
+- **Where (Tokens)** — token dependency graph with human override tracking
+- **Why (Decisions)** — composite manifests, do/never patterns, cognitive load scores, trust-building patterns
+
+The token system uses OKLCH color space, modular scales based on musical ratios, and a dependency engine that derives related values from primitive bases. Override a base — `spacing-base`, `radius-base`, `font-size-base` — and dependents recompute. Override a leaf (`primary` color, `spacing-4`) and the override anchors the subtree against future upstream changes.
 
-The token system uses OKLCH color space, modular scales based on musical ratios, and a dependency engine that automatically derives related values. When a designer overrides a computed value, the system records the reason so AI agents respect the intent.
+When a designer overrides a computed value, the system records the reason. Agents read the why before they read the what.
 
-## Project Structure
+## Project structure
 
 ```
 .rafters/
   config.rafters.json         # Framework paths and export settings
   tokens/
-    color.rafters.json        # Color tokens with OKLCH values
-    spacing.rafters.json      # Spacing scale
-    typography.rafters.json   # Type scale
+    color.rafters.json
+    spacing.rafters.json
+    typography.rafters.json
+    radius.rafters.json
+    shadow.rafters.json
+    focus.rafters.json
+    motion.rafters.json
+    depth.rafters.json
+    elevation.rafters.json
+    breakpoint.rafters.json
+    semantic.rafters.json
+    fill.rafters.json
+    typography-composite.rafters.json
   output/
-    rafters.css               # Tailwind CSS export
+    rafters.css               # Tailwind v4 CSS variables
     rafters.ts                # TypeScript constants
 ```
 
 ## Requirements
 
-- Node.js >= 24.12.0
+- Node.js ≥ 24.12.0
 - Tailwind CSS v4
-- React >= 19.0.0
+- React ≥ 19.0.0 (when using React components)
 
 ## License
 

package/dist/index.js

@@ -28494,6 +28494,7 @@ function firstFamilyFromStack(value) {
   for (const raw of parts) {
     const stripped = stripQuotes(raw.trim());
     if (stripped === "" || GENERIC_KEYWORDS.has(stripped.toLowerCase())) continue;
+    if (stripped.startsWith("var(") || stripped.includes("var(--")) continue;
     return stripped;
   }
   return null;
@@ -29084,6 +29085,20 @@ ${cssContent}`;
 function isInteractive() {
   return Boolean(process.stdin.isTTY && process.stdout.isTTY);
 }
+function resolveSourceCssPath(cwd, framework, detectedFramework, projectCssPath, shadcnCssPath, emit) {
+  if (shadcnCssPath) {
+    if (existsSync3(join7(cwd, shadcnCssPath))) return shadcnCssPath;
+    const fallback = framework === detectedFramework ? projectCssPath : findCssPath(cwd, framework);
+    emit({
+      event: "init:shadcn_css_missing",
+      configuredPath: shadcnCssPath,
+      fallbackPath: fallback,
+      message: "components.json points at a CSS file that does not exist. Falling back to the framework canonical location."
+    });
+    return fallback;
+  }
+  return framework === detectedFramework ? projectCssPath : findCssPath(cwd, framework);
+}
 function slugifyFontName(name) {
   return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 }
@@ -29415,7 +29430,14 @@ async function init(options) {
     log({ event: "init:exports_selected", exports });
   }
   const baseConfig = {};
-  const sourceCssPathForBase = !shadcn && exports.tailwind ? framework === detectedFramework ? project.cssPath : findCssPath(cwd, framework) : shadcn?.tailwind?.css ?? null;
+  const sourceCssPathForBase = resolveSourceCssPath(
+    cwd,
+    framework,
+    detectedFramework,
+    project.cssPath,
+    shadcn?.tailwind?.css,
+    log
+  );
   if (sourceCssPathForBase !== null) {
     try {
       const cssForBase = await readFile4(join7(cwd, sourceCssPathForBase), "utf-8");
@@ -29478,8 +29500,15 @@ async function init(options) {
   });
   const outputs = await generateOutputs(cwd, paths, registry2, exports, shadcn);
   let detectedCssPath = null;
+  detectedCssPath = resolveSourceCssPath(
+    cwd,
+    framework,
+    detectedFramework,
+    project.cssPath,
+    shadcn?.tailwind?.css,
+    log
+  );
   if (!shadcn && exports.tailwind) {
-    detectedCssPath = framework === detectedFramework ? project.cssPath : findCssPath(cwd, framework);
     if (detectedCssPath) {
       await updateMainCss(cwd, detectedCssPath, ".rafters/output/rafters.css");
     } else {
@@ -29489,8 +29518,6 @@ async function init(options) {
         searchedLocations: FRAMEWORK_SPECS[framework].cssLocations
       });
     }
-  } else if (shadcn?.tailwind?.css) {
-    detectedCssPath = shadcn.tailwind.css;
   }
   let componentTarget = frameworkToTarget(framework);
   if (framework === "astro" && astroHasReact && isInteractive() && !isAgentMode2) {

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "rafters",
-  "version": "0.0.55",
-  "description": "CLI for Rafters design system - scaffold tokens and add components",
+  "version": "0.0.56",
+  "description": "Design Intelligence CLI. Scaffold tokens, import existing shadcn/Tailwind v4 sources, add components, and serve an MCP server so AI agents read decisions instead of guessing.",
+  "homepage": "https://rafters.studio",
   "license": "MIT",
   "type": "module",
   "bin": {