rafters 0.0.28 → 0.0.29

package/dist/index.js

@@ -53297,6 +53297,21 @@ Color.extend(interpolation);
 Color.extend(contrastMethods);
 
 // ../color-utils/src/conversion.ts
+function hexToOKLCH(hex3) {
+  try {
+    const color = new Color(hex3);
+    const oklch2 = color.to("oklch");
+    return {
+      l: oklch2.coords[0] ?? 0,
+      c: oklch2.coords[1] ?? 0,
+      h: oklch2.coords[2] ?? 0,
+      // Handle undefined hue for achromatic colors
+      alpha: oklch2.alpha ?? 1
+    };
+  } catch (_error) {
+    throw new Error(`Invalid hex color: ${hex3}`);
+  }
+}
 function roundOKLCH(oklch2) {
   return {
     l: Math.round(oklch2.l * 1e3) / 1e3,
@@ -59683,10 +59698,13 @@ When onboarding an existing project, do NOT skip the learning step.
 1. Call rafters_vocabulary and explore token shapes first. Understand namespaces, dependency graph, the two primitives.
 2. Call rafters_onboard analyze to see what existing design decisions are in the CSS.
 3. Do NOT automatically map colors. Ask the designer about each ambiguous decision.
-4. Every token mutation needs a reason that captures design INTENT, not just origin.
+4. CHALLENGE SEMANTIC ASSIGNMENTS. Do not accept "this is primary" without asking why. "What makes this the primary identity color? Where is it used? What role does it play?" The designer must justify every family assignment.
+5. Every token mutation needs a reason that captures design INTENT, not just origin.
    Bad: "imported from globals.css"
    Good: "Brand blue from --brand-primary, primary identity color used on nav and CTAs per designer"
-5. Call rafters_onboard map to execute the migration once the designer confirms.
+6. The 11 semantic families (primary, secondary, tertiary, accent, neutral, success, warning, destructive, info, highlight, muted) MUST all be mapped. Extra colors are custom families in the color namespace.
+7. If analyze detects color scale patterns (e.g., --color-blaze-50 through --color-blaze-950), map the family using its base color. Do NOT create 11 individual tokens.
+8. Call rafters_onboard map to execute the migration once the designer confirms. Colors are automatically enriched with full OKLCH scales, harmonies, accessibility data, and API intelligence.
 
 When in doubt: less code, not more. Rafters has already made the design decision.`;
 var CONSUMER_QUICKSTART = {
@@ -60107,14 +60125,18 @@ var TOOL_DEFINITIONS = [
   },
   {
     name: "rafters_onboard",
-    description: 'Analyze an existing project for design decisions (CSS custom properties, @theme blocks, shadcn colors) and map them into Rafters tokens. Use "analyze" to surface raw findings. Use "map" to execute token writes from a mapping plan. The agent interprets the findings, asks the designer about ambiguous decisions, then maps with intent.',
+    description: 'Analyze an existing project for design decisions and map them into Rafters tokens. Use "analyze" to surface raw findings. Use "map" to execute -- but map REQUIRES the designer to confirm every mapping first. The tool will reject unconfirmed mappings and instruct you to ask the designer. This is an intentional system, not an automatic one.',
     inputSchema: {
       type: "object",
       properties: {
         action: {
           type: "string",
-          enum: ["analyze", "map"],
-          description: "analyze: scan project CSS and return structured findings. map: execute a mapping plan (array of source->target->reason)."
+          enum: ["analyze", "map", "status"],
+          description: "analyze: scan CSS and return findings + family checklist. status: show which of the 11 families have designer decisions vs defaults. map: execute confirmed mappings (requires confirmed: true after designer review)."
+        },
+        confirmed: {
+          type: "boolean",
+          description: "Set to true ONLY after the designer has reviewed and approved every mapping. The reasons must come from the designer, not from you."
         },
         mappings: {
           type: "array",
@@ -60135,7 +60157,7 @@ var TOOL_DEFINITIONS = [
               },
               reason: {
                 type: "string",
-                description: "Why this mapping makes sense (design intent)"
+                description: "The designer explains why this mapping makes sense. This must come from the human, not from you. Ask them."
               },
               namespace: {
                 type: "string",
@@ -60977,6 +60999,23 @@ var RaftersToolHandler = class _RaftersToolHandler {
       "app/globals.css"
     ]
   };
+  /**
+   * The 11 semantic color families every design system needs.
+   * Defaults are not wrong. Unexamined defaults are wrong.
+   */
+  static SEMANTIC_FAMILIES = [
+    "primary",
+    "secondary",
+    "tertiary",
+    "accent",
+    "neutral",
+    "success",
+    "warning",
+    "destructive",
+    "info",
+    "highlight",
+    "muted"
+  ];
   /**
    * Handle rafters_onboard tool calls
    */
@@ -60985,8 +61024,32 @@ var RaftersToolHandler = class _RaftersToolHandler {
     switch (action) {
       case "analyze":
         return this.analyzeProject();
-      case "map":
+      case "status":
+        return this.getOnboardStatus();
+      case "map": {
+        const confirmed = args.confirmed;
+        if (!confirmed) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify({
+                  error: "Human confirmation required.",
+                  action: "STOP. Do not call this tool again until the designer has reviewed and approved every mapping.",
+                  instructions: [
+                    "Show each proposed mapping to the designer: source -> target, value, and your proposed reason.",
+                    'Ask the designer: "Is this the right semantic role? Why did you choose this color for this purpose?"',
+                    "The designer must provide or approve the reason. Do not write reasons yourself.",
+                    "Once the designer has confirmed all mappings, call rafters_onboard map again with confirmed: true."
+                  ]
+                })
+              }
+            ],
+            isError: true
+          };
+        }
         return this.mapTokens(args.mappings);
+      }
       default:
         return {
           content: [
@@ -61055,17 +61118,61 @@ var RaftersToolHandler = class _RaftersToolHandler {
       } catch {
       }
       let existingTokenCount = 0;
+      const familyStatus = {};
       if (this.adapter) {
         const tokens = await this.adapter.load();
         existingTokenCount = tokens.length;
+        for (const family of _RaftersToolHandler.SEMANTIC_FAMILIES) {
+          const token = tokens.find((t2) => t2.name === family);
+          if (!token) {
+            familyStatus[family] = { status: "unmapped" };
+          } else if (token.userOverride?.reason) {
+            familyStatus[family] = { status: "designer", reason: token.userOverride.reason };
+          } else {
+            familyStatus[family] = { status: "default" };
+          }
+        }
+      }
+      const detectedFamilies = [];
+      const allProps = cssFindings.flatMap((f) => f.customProperties);
+      const familyMap = /* @__PURE__ */ new Map();
+      for (const prop of allProps) {
+        const scaleMatch = prop.name.match(
+          /^--(color-)?(.+?)-(50|100|200|300|400|500|600|700|800|900|950)$/
+        );
+        if (scaleMatch?.[2] && scaleMatch[3]) {
+          const family = scaleMatch[2];
+          if (!familyMap.has(family)) familyMap.set(family, []);
+          familyMap.get(family)?.push({ position: scaleMatch[3], value: prop.value });
+        }
+      }
+      for (const [family, positions] of familyMap) {
+        if (positions.length >= 3) {
+          const base = positions.find((p2) => p2.position === "500") ?? positions.find((p2) => p2.position === "600") ?? positions[0];
+          if (base) {
+            detectedFamilies.push({
+              family,
+              positions: positions.map((p2) => p2.position),
+              baseValue: base.value,
+              source: `--color-${family}-*`
+            });
+          }
+        }
       }
+      const designerCount = Object.values(familyStatus).filter(
+        (s) => s.status === "designer"
+      ).length;
+      const totalFamilies = _RaftersToolHandler.SEMANTIC_FAMILIES.length;
       const result = {
         framework,
         cssFiles: cssFindings,
+        colorFamilies: detectedFamilies.length > 0 ? detectedFamilies : void 0,
+        familyStatus,
+        familyCoverage: `${designerCount}/${totalFamilies} semantic families have designer decisions`,
         shadcn,
         designDependencies: designDeps,
         existingTokenCount,
-        guidance: 'Review the custom properties above. Map each to a rafters token using rafters_onboard with action: "map". For ambiguous decisions, ask the designer.'
+        guidance: detectedFamilies.length > 0 ? `Found ${detectedFamilies.length} color scale pattern(s): ${detectedFamilies.map((f) => f.family).join(", ")}. Map each family using its base color (position 500/600), not individual scale positions. buildColorValue() will regenerate the full 11-step scale.` : 'Review the custom properties above. Map each to a rafters token using rafters_onboard with action: "map". For ambiguous decisions, ask the designer.'
       };
       return {
         content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
@@ -61074,6 +61181,63 @@ var RaftersToolHandler = class _RaftersToolHandler {
       return this.handleError("analyzeProject", error48);
     }
   }
+  /**
+   * Check onboarding completeness -- which families have designer decisions
+   */
+  async getOnboardStatus() {
+    if (!this.adapter || !this.projectRoot) {
+      return { content: [{ type: "text", text: NO_PROJECT_ERROR }], isError: true };
+    }
+    try {
+      const tokens = await this.adapter.load();
+      const mapped = [];
+      const defaultsRemaining = [];
+      const unmapped = [];
+      for (const family of _RaftersToolHandler.SEMANTIC_FAMILIES) {
+        const token = tokens.find((t2) => t2.name === family);
+        if (!token) {
+          unmapped.push(family);
+        } else if (token.userOverride?.reason) {
+          mapped.push(family);
+        } else {
+          defaultsRemaining.push(family);
+        }
+      }
+      const semanticSet = new Set(_RaftersToolHandler.SEMANTIC_FAMILIES);
+      const customFamilies = tokens.filter(
+        (t2) => t2.namespace === "color" && !semanticSet.has(t2.name) && t2.userOverride?.reason && !t2.name.includes("-")
+      ).map((t2) => t2.name);
+      const complete = defaultsRemaining.length === 0 && unmapped.length === 0;
+      const coverage = `${mapped.length}/${_RaftersToolHandler.SEMANTIC_FAMILIES.length}`;
+      let guidance;
+      if (complete) {
+        guidance = "All semantic families have designer decisions. Onboarding is complete.";
+      } else if (defaultsRemaining.length > 0) {
+        guidance = `${defaultsRemaining.length} families still use generated defaults: ${defaultsRemaining.join(", ")}. Ask the designer: do these defaults work, or should we choose specific colors? If the defaults are intentional, confirm them with a reason.`;
+      } else {
+        guidance = `${unmapped.length} families are unmapped: ${unmapped.join(", ")}. These need designer decisions.`;
+      }
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                complete,
+                coverage,
+                families: { mapped, defaultsRemaining, unmapped, customFamilies },
+                guidance
+              },
+              null,
+              2
+            )
+          }
+        ]
+      };
+    } catch (error48) {
+      return this.handleError("getOnboardStatus", error48);
+    }
+  }
   /**
    * Parse CSS content into structured findings
    */
@@ -61088,6 +61252,7 @@ var RaftersToolHandler = class _RaftersToolHandler {
     const themeMatches = content.matchAll(/@theme\s*\{([^}]+)\}/g);
     for (const match2 of themeMatches) {
       if (match2[0]) themeBlocks.push(match2[0].trim());
+      if (match2[1]) this.extractCustomProperties(match2[1], "@theme", customProperties);
     }
     const rootMatch = content.match(/:root\s*\{([^}]+)\}/);
     if (rootMatch?.[1]) {
@@ -61117,7 +61282,51 @@ var RaftersToolHandler = class _RaftersToolHandler {
     }
   }
   /**
-   * Execute a mapping plan -- calls writeToken for each mapping
+   * Detect if a string value is a CSS color (not a size, calc, or var reference)
+   */
+  static isColorValue(value2) {
+    const v = value2.trim().toLowerCase();
+    if (/^\d/.test(v) || v.startsWith("var(") || v.startsWith("calc(")) return false;
+    if (/\d+(rem|px|em|%|vw|vh|dvh|svh|ch|ex)$/.test(v)) return false;
+    return v.startsWith("#") || v.startsWith("rgb") || v.startsWith("hsl") || v.startsWith("oklch") || v.startsWith("oklab") || v.startsWith("lch") || v.startsWith("lab") || v.startsWith("color(") || v.startsWith("hwb");
+  }
+  /**
+   * Parse any CSS color to OKLCH. hexToOKLCH uses colorjs.io internally
+   * which accepts all CSS color formats, not just hex.
+   */
+  static parseToOKLCH(value2) {
+    try {
+      return hexToOKLCH(value2.trim());
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Fire api.rafters.studio enrichment for a color (non-blocking)
+   */
+  static fireEnrichment(oklch2) {
+    const l = oklch2.l.toFixed(3);
+    const c4 = oklch2.c.toFixed(3);
+    const h = Math.round(oklch2.h);
+    return fetch(`https://api.rafters.studio/color/${l}-${c4}-${h}?sync=true`).then((r) => r.ok ? r.json() : null).catch(() => null);
+  }
+  /**
+   * Build enriched ColorValue: local math + API intelligence
+   */
+  static async buildEnrichedColor(oklch2, tokenName) {
+    const enrichmentPromise = _RaftersToolHandler.fireEnrichment(oklch2);
+    const colorValue = buildColorValue(oklch2, { token: tokenName });
+    const enrichment = await enrichmentPromise;
+    if (enrichment && typeof enrichment === "object" && "color" in enrichment) {
+      const apiColor = enrichment.color;
+      if (apiColor?.intelligence) {
+        colorValue.intelligence = apiColor.intelligence;
+      }
+    }
+    return colorValue;
+  }
+  /**
+   * Execute a mapping plan -- enriches colors, writes tokens
    */
   async mapTokens(mappings) {
     if (!mappings || mappings.length === 0) {
@@ -61154,6 +61363,15 @@ var RaftersToolHandler = class _RaftersToolHandler {
           });
           continue;
         }
+        let tokenValue = value2;
+        let enriched = false;
+        if (_RaftersToolHandler.isColorValue(value2)) {
+          const oklch2 = _RaftersToolHandler.parseToOKLCH(value2);
+          if (oklch2) {
+            tokenValue = await _RaftersToolHandler.buildEnrichedColor(oklch2, target);
+            enriched = true;
+          }
+        }
         const exists = registry2.has(target);
         if (exists) {
           const existing = registry2.get(target);
@@ -61163,17 +61381,17 @@ var RaftersToolHandler = class _RaftersToolHandler {
               previousValue: typeof previousValue === "string" ? previousValue : JSON.stringify(previousValue),
               reason: `Onboarded from ${source}: ${reason}`
             };
-            await registry2.set(target, value2);
-            results.push({ source, target, action: "set", ok: true });
+            await registry2.set(target, tokenValue);
+            results.push({ source, target, action: "set", ok: true, enriched });
           }
         } else {
-          const ns = namespace ?? "color";
+          const ns = namespace ?? (enriched ? "color" : "custom");
           const cat = category ?? ns;
           const newToken = {
             name: target,
             namespace: ns,
             category: cat,
-            value: value2,
+            value: tokenValue,
             containerQueryAware: true,
             userOverride: {
               previousValue: "",
@@ -61181,13 +61399,14 @@ var RaftersToolHandler = class _RaftersToolHandler {
             }
           };
           registry2.add(newToken);
-          results.push({ source, target, action: "create", ok: true });
+          results.push({ source, target, action: "create", ok: true, enriched });
         }
       }
       await this.adapter.save(registry2.list());
       await this.regenerateOutputs(registry2);
       const setCount = results.filter((r) => r.action === "set" && r.ok).length;
       const createCount = results.filter((r) => r.action === "create" && r.ok).length;
+      const enrichedCount = results.filter((r) => r.enriched).length;
       const failCount = results.filter((r) => !r.ok).length;
       return {
         content: [
@@ -61196,7 +61415,12 @@ var RaftersToolHandler = class _RaftersToolHandler {
             text: JSON.stringify(
               {
                 ok: true,
-                summary: { set: setCount, created: createCount, failed: failCount },
+                summary: {
+                  set: setCount,
+                  created: createCount,
+                  enriched: enrichedCount,
+                  failed: failCount
+                },
                 results
               },
               null,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rafters",
-  "version": "0.0.28",
+  "version": "0.0.29",
   "description": "CLI for Rafters design system - scaffold tokens and add components",
   "license": "MIT",
   "type": "module",
@@ -40,6 +40,7 @@
   },
   "devDependencies": {
     "@playwright/test": "catalog:",
+    "@rafters/color-utils": "workspace:*",
     "@rafters/design-tokens": "workspace:*",
     "@rafters/shared": "workspace:*",
     "@rafters/studio": "workspace:*",