rafters 0.0.55 → 0.0.57

package/README.md

@@ -1,6 +1,12 @@
 # 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)
+
+**60+ components across React, Astro, and Web Components.** Triple-target parity from one design system — the same Button, Card, Dialog, Combobox, Editor, etc. as a React component, an Astro component, AND a Web Component element class. Component code is installed into your project via `rafters add` (shadcn-style copy), not imported as a dependency, so you own and can fork what ships.
+
+**Composite manifests sit above components.** A composite is a designer-authored JSON manifest that bundles components into reusable patterns (login-form, copy-button, heading, paragraph) with designer intent baked in: `solves`, `appliesWhen`, do/never rules, cognitive load rating, I/O contracts, and a typed block tree. Agents query the composite registry via MCP and assemble pre-made decisions instead of inventing new ones.
 
 ## Quick Start
 
@@ -8,24 +14,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.
 
-## Commands
+## What `init` does
 
-### `rafters init`
+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`:
 
-Initialize a project with design tokens.
+- **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.
+
+### 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 +47,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 +81,97 @@ 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:
+Four layers, stacked:
 
-- **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
+- **Tokens** — primitive design values (color OKLCH, spacing scale, radius, typography, motion, focus, shadow, depth, elevation, breakpoints). 13 namespaces; dependency graph with human override tracking. Override a base (`spacing-base`, `radius-base`, `font-size-base`) and dependents recompute. Override a leaf and the override anchors the subtree.
+- **Primitives** — 62 framework-agnostic building blocks (clipboard, focus-trap, portal, roving-focus, selection, serializer, slot, token-sheet, typeahead, etc.). Headless behaviors components compose against.
+- **Components** — 60+ React + 71 Astro + 32 Web Component element classes. Triple-target parity. Each component carries embedded intelligence metadata: cognitive load rating, accessibility level, do/never, variant semantics, attention economics. Installed into your project via `rafters add` — you own the code.
+- **Composites** — designer-authored JSON manifests that bundle components into reusable patterns (login-form, copy-button, heading, paragraph, etc.). Each manifest carries `solves`, `appliesWhen`, `usagePatterns` (do/never), `cognitiveLoad`, I/O contracts, and a typed block tree. The composite owns the variant/size decisions — agents render blocks verbatim instead of choosing aesthetics.
 
-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

@@ -29084,6 +29084,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 +29429,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 +29499,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 +29517,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.57",
+  "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": {