rafters 0.0.37 → 0.0.39

package/dist/index.js

@@ -46768,6 +46768,13 @@ var DEFAULT_SEMANTIC_COLOR_MAPPINGS = {
 };
 
 // ../design-tokens/src/exporters/tailwind.ts
+var SHADOW_PART_SUFFIX = /-(offset-x|offset-y|blur|spread|color)$/;
+function isShadowDecomposedPart(name2) {
+  return SHADOW_PART_SUFFIX.test(name2);
+}
+function isMediaQueryToken(token) {
+  return typeof token.value === "string" && token.value.startsWith("(");
+}
 function colorRefToString(ref) {
   return `${ref.family}-${ref.position}`;
 }
@@ -46965,8 +46972,12 @@ function generateThemeBlock(groups) {
     for (const token of groups.shadow) {
       const value2 = tokenValueToCSS(token);
       if (value2 === null) continue;
-      const key = token.name.replace(/^shadow-/, "");
-      lines.push(`  --shadow-${key}: ${value2};`);
+      if (isShadowDecomposedPart(token.name)) {
+        lines.push(`  --rafters-${token.name}: ${value2};`);
+      } else {
+        const key = token.name.replace(/^shadow-/, "");
+        lines.push(`  --shadow-${key}: ${value2};`);
+      }
     }
     lines.push("");
   }
@@ -47010,6 +47021,7 @@ function generateThemeBlock(groups) {
     for (const token of groups.breakpoint) {
       const value2 = tokenValueToCSS(token);
       if (value2 === null) continue;
+      if (isMediaQueryToken(token)) continue;
       lines.push(`  --${token.name}: ${value2};`);
     }
     lines.push("");
@@ -47218,7 +47230,7 @@ function generateVarsRootBlock(groups) {
     for (const token of groups.shadow) {
       const value2 = tokenValueToCSS(token);
       if (value2 === null) continue;
-      lines.push(`  --rafters-shadow-${token.name}: ${value2};`);
+      lines.push(`  --rafters-${token.name}: ${value2};`);
     }
     lines.push("");
   }
@@ -47260,6 +47272,7 @@ function generateVarsRootBlock(groups) {
     for (const token of groups.breakpoint) {
       const value2 = tokenValueToCSS(token);
       if (value2 === null) continue;
+      if (isMediaQueryToken(token)) continue;
       lines.push(`  --rafters-${token.name}: ${value2};`);
     }
     lines.push("");
@@ -57673,6 +57686,13 @@ function generateMotionTokens(config3, durationDefs, easingDefs, delayDefs) {
 }
 
 // ../design-tokens/src/generators/radius.ts
+var CORNERS = ["tl", "tr", "bl", "br"];
+var CORNER_NAMES = {
+  tl: "top-left",
+  tr: "top-right",
+  bl: "bottom-left",
+  br: "bottom-right"
+};
 function generateRadiusTokens(config3, radiusDefs) {
   const tokens = [];
   const timestamp = (/* @__PURE__ */ new Date()).toISOString();
@@ -57695,6 +57715,20 @@ function generateRadiusTokens(config3, radiusDefs) {
       never: ["Change without understanding scale impact"]
     }
   });
+  for (const corner of CORNERS) {
+    tokens.push({
+      name: `radius-${corner}`,
+      value: "var(--rafters-radius-base)",
+      category: "radius",
+      namespace: "radius",
+      semanticMeaning: `Base ${CORNER_NAMES[corner]} radius - override to affect all scales for this corner`,
+      usageContext: ["designer-override"],
+      dependsOn: ["radius-base"],
+      description: `${CORNER_NAMES[corner]} radius. Defaults to radius-base. Set to 0 for a sharp corner on every component.`,
+      generatedAt: timestamp,
+      containerQueryAware: false
+    });
+  }
   for (const scale3 of RADIUS_SCALE) {
     const def = radiusDefs[scale3];
     if (!def) continue;
@@ -57715,8 +57749,9 @@ function generateRadiusTokens(config3, radiusDefs) {
       value2 = `calc(var(--rafters-radius-base) * ${multiplier})`;
       mathRelationship = `base \xD7 ${progression.ratio}^${def.step} (\xD7${multiplier})`;
     }
+    const scaleName = scale3 === "DEFAULT" ? "radius" : `radius-${scale3}`;
     tokens.push({
-      name: scale3 === "DEFAULT" ? "radius" : `radius-${scale3}`,
+      name: scaleName,
       value: value2,
       category: "radius",
       namespace: "radius",
@@ -57730,6 +57765,25 @@ function generateRadiusTokens(config3, radiusDefs) {
       generatedAt: timestamp,
       containerQueryAware: false
     });
+    if (def.step !== "none" && def.step !== "full" && scale3 !== "DEFAULT") {
+      const cornerMultiplier = def.step === 0 ? null : Math.round(progression.ratio ** def.step * 1e3) / 1e3;
+      for (const corner of CORNERS) {
+        const cornerValue = cornerMultiplier === null ? `var(--rafters-radius-${corner})` : `calc(var(--rafters-radius-${corner}) * ${cornerMultiplier})`;
+        tokens.push({
+          name: `radius-${scale3}-${corner}`,
+          value: cornerValue,
+          category: "radius",
+          namespace: "radius",
+          semanticMeaning: `${CORNER_NAMES[corner]} radius at ${scale3} scale`,
+          usageContext: def.contexts,
+          scalePosition: scaleIndex,
+          dependsOn: [`radius-${corner}`],
+          description: `${CORNER_NAMES[corner]} radius ${scale3}: derives from radius-${corner} base`,
+          generatedAt: timestamp,
+          containerQueryAware: false
+        });
+      }
+    }
   }
   return {
     namespace: "radius",
@@ -57786,26 +57840,29 @@ function pxToRem2(px) {
   const rem = Math.round(px / 16 * 1e3) / 1e3;
   return `${rem}rem`;
 }
-function generateShadowValue(def, baseSpacing) {
-  if (def.opacity === 0) {
-    return "none";
-  }
-  const shadows = [];
-  const yOffsetPx = Math.round(def.yOffset * baseSpacing * 100) / 100;
-  const blurPx = Math.round(def.blur * baseSpacing * 100) / 100;
-  const spreadPx = Math.round(def.spread * baseSpacing * 100) / 100;
-  shadows.push(
-    `0 ${pxToRem2(yOffsetPx)} ${pxToRem2(blurPx)} ${pxToRem2(spreadPx)} rgb(0 0 0 / ${def.opacity})`
-  );
-  if (def.innerShadow) {
-    const innerYPx = Math.round(def.innerShadow.yOffset * baseSpacing * 100) / 100;
-    const innerBlurPx = Math.round(def.innerShadow.blur * baseSpacing * 100) / 100;
-    const innerSpreadPx = Math.round(def.innerShadow.spread * baseSpacing * 100) / 100;
-    shadows.push(
-      `0 ${pxToRem2(innerYPx)} ${pxToRem2(innerBlurPx)} ${pxToRem2(innerSpreadPx)} rgb(0 0 0 / ${def.innerShadow.opacity})`
-    );
-  }
-  return shadows.join(", ");
+var SHADOW_PARTS = ["offset-x", "offset-y", "blur", "spread", "color"];
+function scalePx(multiplier, baseSpacing) {
+  return Math.round(multiplier * baseSpacing * 100) / 100;
+}
+function resolveShadowParts(def, baseSpacing) {
+  return {
+    // Shadows are vertical-only by design (material elevation model)
+    "offset-x": "0rem",
+    "offset-y": pxToRem2(scalePx(def.yOffset, baseSpacing)),
+    blur: pxToRem2(scalePx(def.blur, baseSpacing)),
+    spread: pxToRem2(scalePx(def.spread, baseSpacing)),
+    color: `rgb(0 0 0 / ${def.opacity})`
+  };
+}
+function generateInnerShadowValue(inner, baseSpacing) {
+  const y = pxToRem2(scalePx(inner.yOffset, baseSpacing));
+  const blur = pxToRem2(scalePx(inner.blur, baseSpacing));
+  const spread = pxToRem2(scalePx(inner.spread, baseSpacing));
+  return `0 ${y} ${blur} ${spread} rgb(0 0 0 / ${inner.opacity})`;
+}
+function buildCompositeFromVars(prefix, innerValue) {
+  const primary = SHADOW_PARTS.map((part) => `var(--rafters-${prefix}-${part})`).join(" ");
+  return innerValue ? `${primary}, ${innerValue}` : primary;
 }
 function generateShadowTokens(config3, shadowDefs) {
   const tokens = [];
@@ -57830,23 +57887,65 @@ function generateShadowTokens(config3, shadowDefs) {
     const def = shadowDefs[scale3];
     if (!def) continue;
     const scaleIndex = SHADOW_SCALE.indexOf(scale3);
-    const value2 = generateShadowValue(def, baseSpacingUnit);
+    const scaleName = scale3 === "DEFAULT" ? "shadow" : `shadow-${scale3}`;
+    if (def.opacity === 0) {
+      tokens.push({
+        name: scaleName,
+        value: "none",
+        category: "shadow",
+        namespace: "shadow",
+        semanticMeaning: def.meaning,
+        usageContext: def.contexts,
+        scalePosition: scaleIndex,
+        progressionSystem: progressionRatio,
+        dependsOn: [],
+        description: `Shadow ${scale3}: ${def.meaning}`,
+        generatedAt: timestamp,
+        containerQueryAware: false,
+        usagePatterns: {
+          do: ["Use for flat elements", "Use for disabled states"],
+          never: ["Use on interactive elements that need depth feedback"]
+        }
+      });
+      continue;
+    }
+    const parts = resolveShadowParts(def, baseSpacingUnit);
+    const partDeps = [];
+    for (const part of SHADOW_PARTS) {
+      const partName = `${scaleName}-${part}`;
+      partDeps.push(partName);
+      tokens.push({
+        name: partName,
+        value: parts[part],
+        category: "shadow",
+        namespace: "shadow",
+        semanticMeaning: `${part} component of ${scale3} shadow`,
+        usageContext: ["designer-override"],
+        scalePosition: scaleIndex,
+        dependsOn: ["shadow-base-unit"],
+        description: `Shadow ${scale3} ${part}: ${parts[part]}. Override to customize this shadow layer.`,
+        generatedAt: timestamp,
+        containerQueryAware: false
+      });
+    }
+    const innerValue = def.innerShadow && def.innerShadow.opacity > 0 ? generateInnerShadowValue(def.innerShadow, baseSpacingUnit) : null;
+    const compositeValue = buildCompositeFromVars(scaleName, innerValue);
     tokens.push({
-      name: scale3 === "DEFAULT" ? "shadow" : `shadow-${scale3}`,
-      value: value2,
+      name: scaleName,
+      value: compositeValue,
       category: "shadow",
       namespace: "shadow",
       semanticMeaning: def.meaning,
       usageContext: def.contexts,
       scalePosition: scaleIndex,
       progressionSystem: progressionRatio,
-      dependsOn: scale3 === "none" ? [] : ["shadow-base-unit"],
-      description: `Shadow ${scale3}: ${def.meaning}. Y: ${def.yOffset}\xD7base, Blur: ${def.blur}\xD7base`,
+      dependsOn: partDeps,
+      description: `Shadow ${scale3}: ${def.meaning}. Composed from var() refs to ${scaleName}-* tokens.`,
       generatedAt: timestamp,
       containerQueryAware: false,
       usagePatterns: {
-        do: scale3 === "none" ? ["Use for flat elements", "Use for disabled states"] : scaleIndex <= 2 ? ["Use for subtle depth", "Use for cards at rest"] : scaleIndex <= 4 ? ["Use for hovering elements", "Use for focus states"] : ["Use for floating elements", "Use for modals"],
-        never: scale3 === "none" ? ["Use on interactive elements that need depth feedback"] : ["Use shadows that don't match element's semantic depth"]
+        do: scaleIndex <= 2 ? ["Use for subtle depth", "Use for cards at rest"] : scaleIndex <= 4 ? ["Use for hovering elements", "Use for focus states"] : ["Use for floating elements", "Use for modals"],
+        never: ["Use shadows that don't match element's semantic depth"]
       }
     });
   }
@@ -57857,27 +57956,33 @@ function generateShadowTokens(config3, shadowDefs) {
       {
         name: "shadow-primary",
         desc: "Primary colored shadow for emphasis",
-        color: "var(--primary)"
+        color: "var(--primary)",
+        colorToken: "primary"
       },
       {
         name: "shadow-destructive",
         desc: "Destructive colored shadow for warnings",
-        color: "var(--destructive)"
+        color: "var(--destructive)",
+        colorToken: "destructive"
       }
     ];
-    for (const { name: name2, desc, color } of coloredShadows) {
-      const yOffsetPx = Math.round(baseDef.yOffset * baseSpacingUnit * 100) / 100;
-      const blurPx = Math.round(baseDef.blur * baseSpacingUnit * 100) / 100;
-      const spreadPx = Math.round(baseDef.spread * baseSpacingUnit * 100) / 100;
+    for (const { name: name2, desc, color, colorToken } of coloredShadows) {
+      const value2 = `var(--rafters-shadow-offset-x) var(--rafters-shadow-offset-y) var(--rafters-shadow-blur) var(--rafters-shadow-spread) color-mix(in oklch, ${color} ${coloredOpacity * 100}%, transparent)`;
       tokens.push({
         name: name2,
-        value: `0 ${pxToRem2(yOffsetPx)} ${pxToRem2(blurPx)} ${pxToRem2(spreadPx)} color-mix(in oklch, ${color} ${coloredOpacity * 100}%, transparent)`,
+        value: value2,
         category: "shadow",
         namespace: "shadow",
         semanticMeaning: desc,
         usageContext: ["branded-elements", "emphasis"],
-        dependsOn: ["shadow", color.replace("var(--", "").replace(")", "")],
-        description: `${desc}. Uses color-mix for proper OKLCH blending.`,
+        dependsOn: [
+          "shadow-offset-x",
+          "shadow-offset-y",
+          "shadow-blur",
+          "shadow-spread",
+          colorToken
+        ],
+        description: `${desc}. Reuses DEFAULT shadow geometry, swaps color via color-mix.`,
         generatedAt: timestamp,
         containerQueryAware: false
       });
@@ -59853,6 +59958,7 @@ When onboarding an existing project, do NOT skip the learning step.
 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.
+9. AFTER mapping color families, check if semantic surface tokens (background, foreground, card, popover, etc.) need remapping. By default they reference "neutral" family. For dark-themed sites or custom palettes, remap them using the "light" and "dark" fields in the mapping: { source: "--bg", target: "background", light: "neutral-50", dark: "custom-dark-950", reason: "..." }. The light/dark values are "family-position" references to existing color tokens. Map color families FIRST, then remap semantic tokens that reference them.
 
 When in doubt: less code, not more. Rafters has already made the design decision.`;
 var CONSUMER_QUICKSTART = {
@@ -60246,6 +60352,10 @@ var TOOL_DEFINITIONS = [
         category: {
           type: "string",
           description: 'Token category (required for create). E.g., "color", "spacing", "font".'
+        },
+        dark: {
+          type: "string",
+          description: 'Dark mode color reference as "family-position" (e.g., "neutral-950"). For semantic tokens, sets dependsOn[1] so the CSS dark mode layer uses this reference instead of the light value.'
         }
       },
       required: ["name"]
@@ -60273,7 +60383,7 @@ var TOOL_DEFINITIONS = [
   },
   {
     name: "rafters_onboard",
-    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.',
+    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. Supports two mapping types: (1) color family mapping with "value" field (enriches CSS color into full ColorValue), (2) semantic remapping with "light"/"dark" fields (remaps which color family+position a semantic token like "background" or "card" references for light/dark mode). Map color families first, then remap semantic surface tokens.',
     inputSchema: {
       type: "object",
       properties: {
@@ -60301,7 +60411,15 @@ var TOOL_DEFINITIONS = [
               },
               value: {
                 type: "string",
-                description: "The value to set (from the original CSS)"
+                description: "The CSS color value to set (from the original CSS). Required for color family mappings. Omit for semantic remappings that use light/dark instead."
+              },
+              light: {
+                type: "string",
+                description: 'Light mode color reference as "family-position" (e.g., "neutral-50"). Used for semantic token remapping -- tells the token which color family+position to use in light mode.'
+              },
+              dark: {
+                type: "string",
+                description: 'Dark mode color reference as "family-position" (e.g., "neutral-950"). Used for semantic token remapping -- tells the token which color family+position to use in dark mode.'
               },
               reason: {
                 type: "string",
@@ -60316,7 +60434,7 @@ var TOOL_DEFINITIONS = [
                 description: "Category for new tokens (required if token does not exist)"
               }
             },
-            required: ["source", "target", "value", "reason"]
+            required: ["source", "target", "reason"]
           },
           description: "Array of mappings to execute (required for map action)"
         }
@@ -60936,6 +61054,19 @@ var RaftersToolHandler = class _RaftersToolHandler {
     }
   }
   // ==================== Token Write Operations ====================
+  static VALID_SCALE_POSITIONS = /^(50|100|200|300|400|500|600|700|800|900|950)$/;
+  /**
+   * Parse "family-position" string (e.g., "neutral-950") into { family, position }.
+   * Returns null if the string is not a valid color reference.
+   */
+  static parseColorRef(ref) {
+    const lastDash = ref.lastIndexOf("-");
+    if (lastDash <= 0) return null;
+    const position = ref.slice(lastDash + 1);
+    const family = ref.slice(0, lastDash);
+    if (!_RaftersToolHandler.VALID_SCALE_POSITIONS.test(position)) return null;
+    return { family, position };
+  }
   /**
    * Handle set, create, and reset actions for rafters_token.
    * Loads the full registry, mutates, cascades, persists, and regenerates outputs.
@@ -60944,6 +61075,7 @@ var RaftersToolHandler = class _RaftersToolHandler {
     const name2 = args.name;
     const reason = args.reason;
     const value2 = args.value;
+    const dark = args.dark;
     if (!reason) {
       return {
         content: [
@@ -60989,14 +61121,64 @@ var RaftersToolHandler = class _RaftersToolHandler {
               isError: true
             };
           }
+          if (dark) {
+            if (existing.namespace !== "semantic") {
+              return {
+                content: [
+                  {
+                    type: "text",
+                    text: JSON.stringify({
+                      error: `The "dark" parameter only applies to semantic color tokens. Token "${name2}" is in the "${existing.namespace}" namespace.`
+                    })
+                  }
+                ],
+                isError: true
+              };
+            }
+            if (!_RaftersToolHandler.parseColorRef(dark)) {
+              return {
+                content: [
+                  {
+                    type: "text",
+                    text: JSON.stringify({
+                      error: `Invalid dark reference "${dark}". Use format "family-position" (e.g., "neutral-950"). Valid positions: 50, 100-900 by 100, 950.`
+                    })
+                  }
+                ],
+                isError: true
+              };
+            }
+          }
           const previousValue = existing.value;
           existing.userOverride = {
             previousValue: typeof previousValue === "string" ? previousValue : JSON.stringify(previousValue),
             reason
           };
-          await registry2.set(name2, value2);
+          const parsed = existing.namespace === "semantic" && typeof value2 === "string" ? _RaftersToolHandler.parseColorRef(value2) : null;
+          if (existing.namespace === "semantic" && typeof value2 === "string" && !parsed) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify({
+                    error: `Semantic token "${name2}" requires a color reference in "family-position" format (e.g., "neutral-50"), not "${value2}". Use rafters_vocabulary to find available color families.`
+                  })
+                }
+              ],
+              isError: true
+            };
+          }
+          if (parsed) {
+            existing.value = parsed;
+            const lightRefStr = `${parsed.family}-${parsed.position}`;
+            const darkRef = dark ?? existing.dependsOn?.[1] ?? lightRefStr;
+            existing.dependsOn = [lightRefStr, darkRef];
+          } else {
+            existing.value = value2;
+          }
+          await registry2.setToken(existing);
           const affected = this.getAffectedTokens(registry2, name2);
-          await this.regenerateOutputs(registry2);
+          const outputFiles = await this.regenerateOutputs(registry2);
           return {
             content: [
               {
@@ -61006,7 +61188,13 @@ var RaftersToolHandler = class _RaftersToolHandler {
                   action: "set",
                   name: name2,
                   reason,
-                  cascaded: affected
+                  persisted: {
+                    value: existing.value,
+                    dependsOn: existing.dependsOn,
+                    namespace: existing.namespace
+                  },
+                  cascaded: affected,
+                  outputFiles
                 })
               }
             ]
@@ -61063,7 +61251,7 @@ var RaftersToolHandler = class _RaftersToolHandler {
           };
           registry2.add(newToken);
           await this.adapter.save(registry2.list());
-          await this.regenerateOutputs(registry2);
+          const outputFiles = await this.regenerateOutputs(registry2);
           return {
             content: [
               {
@@ -61073,7 +61261,13 @@ var RaftersToolHandler = class _RaftersToolHandler {
                   action: "create",
                   name: name2,
                   namespace,
-                  reason
+                  reason,
+                  persisted: {
+                    value: newToken.value,
+                    dependsOn: newToken.dependsOn,
+                    namespace: newToken.namespace
+                  },
+                  outputFiles
                 })
               }
             ]
@@ -61090,8 +61284,9 @@ var RaftersToolHandler = class _RaftersToolHandler {
             };
           }
           await registry2.set(name2, COMPUTED);
+          const resolved = registry2.get(name2);
           const affected = this.getAffectedTokens(registry2, name2);
-          await this.regenerateOutputs(registry2);
+          const outputFiles = await this.regenerateOutputs(registry2);
           return {
             content: [
               {
@@ -61101,7 +61296,13 @@ var RaftersToolHandler = class _RaftersToolHandler {
                   action: "reset",
                   name: name2,
                   reason,
-                  cascaded: affected
+                  persisted: {
+                    value: resolved?.value,
+                    dependsOn: resolved?.dependsOn,
+                    namespace: resolved?.namespace
+                  },
+                  cascaded: affected,
+                  outputFiles
                 })
               }
             ]
@@ -61137,10 +61338,11 @@ var RaftersToolHandler = class _RaftersToolHandler {
     return affected;
   }
   /**
-   * Regenerate output files (CSS, TS, DTCG) from registry state
+   * Regenerate output files (CSS, TS, DTCG) from registry state.
+   * Returns list of files written so callers can report what changed.
    */
   async regenerateOutputs(registry2) {
-    if (!this.projectRoot) return;
+    if (!this.projectRoot) return [];
     const paths = getRaftersPaths(this.projectRoot);
     const config3 = await this.loadConfig();
     const exports = config3?.exports ?? {
@@ -61150,20 +61352,28 @@ var RaftersToolHandler = class _RaftersToolHandler {
       compiled: false
     };
     const shadcn = config3?.shadcn ?? false;
+    const written = [];
     await mkdir4(paths.output, { recursive: true });
     if (exports.tailwind) {
       const darkMode = config3?.darkMode ?? "class";
       const css3 = registryToTailwind(registry2, { includeImport: !shadcn, darkMode });
-      await writeFile4(join10(paths.output, "rafters.css"), css3);
+      const cssPath = join10(paths.output, "rafters.css");
+      await writeFile4(cssPath, css3);
+      written.push(relative2(this.projectRoot, cssPath));
     }
     if (exports.typescript) {
       const ts = registryToTypeScript(registry2, { includeJSDoc: true });
-      await writeFile4(join10(paths.output, "rafters.ts"), ts);
+      const tsPath = join10(paths.output, "rafters.ts");
+      await writeFile4(tsPath, ts);
+      written.push(relative2(this.projectRoot, tsPath));
     }
     if (exports.dtcg) {
       const json3 = toDTCG(registry2.list());
-      await writeFile4(join10(paths.output, "rafters.json"), JSON.stringify(json3, null, 2));
+      const jsonPath = join10(paths.output, "rafters.json");
+      await writeFile4(jsonPath, JSON.stringify(json3, null, 2));
+      written.push(relative2(this.projectRoot, jsonPath));
     }
+    return written;
   }
   // ==================== Tool 6: Onboard ====================
   /**
@@ -61349,6 +61559,20 @@ var RaftersToolHandler = class _RaftersToolHandler {
         (s) => s.status === "designer"
       ).length;
       const totalFamilies = _RaftersToolHandler.SEMANTIC_FAMILIES.length;
+      const hasDarkMode = cssFindings.some(
+        (f) => f.customProperties.some(
+          (p2) => p2.context === ".dark" || p2.context === "prefers-color-scheme: dark"
+        )
+      );
+      let guidance;
+      if (detectedFamilies.length > 0) {
+        guidance = `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.`;
+      } else {
+        guidance = 'Review the custom properties above. Map each to a rafters token using rafters_onboard with action: "map". For ambiguous decisions, ask the designer.';
+      }
+      if (hasDarkMode) {
+        guidance += ' DARK MODE DETECTED: After mapping color families, remap semantic surface tokens (background, foreground, card, popover, etc.) to point at the correct family+position for dark mode. Use the "light" and "dark" fields in the mapping instead of "value". Default semantic tokens reference "neutral" family -- if the project uses a different dark palette, these must be remapped.';
+      }
       const result = {
         framework,
         cssFiles: cssFindings,
@@ -61358,7 +61582,8 @@ var RaftersToolHandler = class _RaftersToolHandler {
         shadcn,
         designDependencies: designDeps,
         existingTokenCount,
-        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.'
+        hasDarkMode,
+        guidance
       };
       return {
         content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
@@ -61537,15 +61762,133 @@ var RaftersToolHandler = class _RaftersToolHandler {
       const registry2 = new TokenRegistry(allTokens);
       registry2.setAdapter(this.adapter);
       const results = [];
+      const parseRef = _RaftersToolHandler.parseColorRef;
       for (const mapping of mappings) {
         const { source, target, value: value2, reason, namespace, category } = mapping;
-        if (!source || !target || !value2 || !reason) {
+        const lightRef = mapping.light;
+        const darkRef = mapping.dark;
+        if (!source || !target || !reason) {
           results.push({
             source: source ?? "?",
             target: target ?? "?",
             action: "skipped",
             ok: false,
-            error: "Missing required fields: source, target, value, reason"
+            error: "Missing required fields: source, target, reason"
+          });
+          continue;
+        }
+        if (lightRef || darkRef) {
+          const existing = registry2.get(target);
+          if (!existing) {
+            results.push({
+              source,
+              target,
+              action: "skipped",
+              ok: false,
+              error: `Semantic token "${target}" not found. Only existing semantic tokens can be remapped.`
+            });
+            continue;
+          }
+          const currentValue = existing.value;
+          const currentLight = typeof currentValue === "object" && currentValue !== null && "family" in currentValue ? currentValue : null;
+          const newLight = lightRef ? parseRef(lightRef) : currentLight;
+          if (lightRef && !newLight) {
+            results.push({
+              source,
+              target,
+              action: "skipped",
+              ok: false,
+              error: `Invalid light reference "${lightRef}". Use format "family-position" (e.g., "neutral-50"). Valid positions: 50, 100-900 by 100, 950.`
+            });
+            continue;
+          }
+          if (!lightRef && !currentLight) {
+            results.push({
+              source,
+              target,
+              action: "skipped",
+              ok: false,
+              error: `Token "${target}" has no existing ColorReference value. You must supply an explicit "light" field to remap it.`
+            });
+            continue;
+          }
+          const darkFallbackRef = existing.dependsOn?.[1];
+          const newDark = darkRef ? parseRef(darkRef) : darkFallbackRef ? parseRef(darkFallbackRef) : newLight;
+          if (darkRef && !newDark) {
+            results.push({
+              source,
+              target,
+              action: "skipped",
+              ok: false,
+              error: `Invalid dark reference "${darkRef}". Use format "family-position" (e.g., "neutral-950"). Valid positions: 50, 100-900 by 100, 950.`
+            });
+            continue;
+          }
+          if (!darkRef && darkFallbackRef && !newDark) {
+            results.push({
+              source,
+              target,
+              action: "skipped",
+              ok: false,
+              error: `Could not infer dark reference from existing dependsOn value "${darkFallbackRef}". Supply an explicit "dark" field.`
+            });
+            continue;
+          }
+          if (!newLight || !newDark) {
+            results.push({
+              source,
+              target,
+              action: "skipped",
+              ok: false,
+              error: `Could not resolve light/dark references for "${target}". Supply explicit "light" and "dark" fields.`
+            });
+            continue;
+          }
+          const lightTokenName = `${newLight.family}-${newLight.position}`;
+          const darkTokenName = `${newDark.family}-${newDark.position}`;
+          const missingRefs = [];
+          if (!registry2.has(lightTokenName)) missingRefs.push(lightTokenName);
+          if (!registry2.has(darkTokenName)) missingRefs.push(darkTokenName);
+          if (missingRefs.length > 0) {
+            results.push({
+              source,
+              target,
+              action: "skipped",
+              ok: false,
+              error: `Referenced color tokens not found: ${missingRefs.join(", ")}. Map the color family first, then remap the semantic token.`
+            });
+            continue;
+          }
+          const previousValue = typeof existing.value === "string" ? existing.value : JSON.stringify(existing.value);
+          existing.userOverride = {
+            previousValue,
+            reason: `Remapped from ${source}: ${reason}`
+          };
+          const newColorRef = { family: newLight.family, position: newLight.position };
+          await registry2.setToken({
+            ...existing,
+            value: newColorRef,
+            dependsOn: [lightTokenName, darkTokenName]
+          });
+          results.push({
+            source,
+            target,
+            action: "remap",
+            ok: true,
+            persisted: {
+              value: newColorRef,
+              dependsOn: [lightTokenName, darkTokenName]
+            }
+          });
+          continue;
+        }
+        if (!value2) {
+          results.push({
+            source,
+            target,
+            action: "skipped",
+            ok: false,
+            error: 'Missing "value" for color family mapping. Provide a CSS color value, or use "light"/"dark" for semantic remapping.'
           });
           continue;
         }
@@ -61569,6 +61912,14 @@ var RaftersToolHandler = class _RaftersToolHandler {
             };
             await registry2.set(target, tokenValue);
             results.push({ source, target, action: "set", ok: true, enriched });
+          } else {
+            results.push({
+              source,
+              target,
+              action: "skipped",
+              ok: false,
+              error: `Token "${target}" exists in registry index but could not be retrieved.`
+            });
           }
         } else {
           const ns = namespace ?? (enriched ? "color" : "custom");
@@ -61589,9 +61940,10 @@ var RaftersToolHandler = class _RaftersToolHandler {
         }
       }
       await this.adapter.save(registry2.list());
-      await this.regenerateOutputs(registry2);
+      const outputFiles = 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 remapCount = results.filter((r) => r.action === "remap" && r.ok).length;
       const enrichedCount = results.filter((r) => r.enriched).length;
       const failCount = results.filter((r) => !r.ok).length;
       return {
@@ -61604,10 +61956,12 @@ var RaftersToolHandler = class _RaftersToolHandler {
                 summary: {
                   set: setCount,
                   created: createCount,
+                  remapped: remapCount,
                   enriched: enrichedCount,
                   failed: failCount
                 },
-                results
+                results,
+                outputFiles
               },
               null,
               2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rafters",
-  "version": "0.0.37",
+  "version": "0.0.39",
   "description": "CLI for Rafters design system - scaffold tokens and add components",
   "license": "MIT",
   "type": "module",