rafters 0.0.36 → 0.0.38

package/dist/index.js

@@ -12829,6 +12829,7 @@ function frameworkToTarget(framework) {
   if (framework === "astro") return "astro";
   return "react";
 }
+var COMPONENT_EXTENSIONS = [".tsx", ".astro", ".vue", ".svelte"];
 function targetToExtension(target) {
   const map2 = {
     react: ".tsx",
@@ -12838,6 +12839,11 @@ function targetToExtension(target) {
   };
   return map2[target];
 }
+function resolveComponentTarget(config3) {
+  if (config3?.componentTarget) return config3.componentTarget;
+  if (config3?.framework) return frameworkToTarget(config3.framework);
+  return "react";
+}
 async function hasAstroReact(cwd) {
   try {
     const content = await readFile(join(cwd, "package.json"), "utf-8");
@@ -13350,9 +13356,7 @@ function getInstalledNames(config3) {
   return [...names2].sort();
 }
 function getComponentTarget(config3) {
-  if (config3?.componentTarget) return config3.componentTarget;
-  if (config3?.framework) return frameworkToTarget(config3.framework);
-  return "react";
+  return resolveComponentTarget(config3);
 }
 var SHARED_EXTENSIONS = /* @__PURE__ */ new Set([".classes.ts", ".types.ts", ".constants.ts"]);
 function isSharedFile(path2) {
@@ -46764,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}`;
 }
@@ -46961,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("");
   }
@@ -47006,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("");
@@ -47214,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("");
   }
@@ -47256,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("");
@@ -57669,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();
@@ -57691,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;
@@ -57711,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",
@@ -57726,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",
@@ -57782,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 = [];
@@ -57826,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"]
       }
     });
   }
@@ -57853,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
       });
@@ -59849,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 = {
@@ -60269,7 +60379,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: {
@@ -60297,7 +60407,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",
@@ -60312,7 +60430,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)"
         }
@@ -60601,12 +60719,32 @@ var RaftersToolHandler = class _RaftersToolHandler {
     return join10(this.projectRoot, "packages/ui/src/components/ui");
   }
   /**
-   * Load component metadata from source file
+   * Find the actual component file on disk for a given name.
+   * Checks the config's componentTarget extension first, then falls back
+   * to all known extensions so Astro projects with React islands also work.
+   */
+  async resolveComponentFile(componentsPath, name2) {
+    const config3 = await this.loadConfig();
+    const preferredExt = targetToExtension(resolveComponentTarget(config3));
+    const preferred = join10(componentsPath, `${name2}${preferredExt}`);
+    if (existsSync4(preferred)) return preferred;
+    for (const ext2 of COMPONENT_EXTENSIONS) {
+      if (ext2 === preferredExt) continue;
+      const candidate = join10(componentsPath, `${name2}${ext2}`);
+      if (existsSync4(candidate)) return candidate;
+    }
+    return null;
+  }
+  /**
+   * Load component metadata from source file.
+   * Resolves the actual file extension from the config's componentTarget
+   * and merges variant/size data from .classes.ts companions when present.
    */
   async loadComponentMetadata(name2) {
     const componentsPath = await this.getComponentsPath();
     if (!componentsPath) return null;
-    const filePath = join10(componentsPath, `${name2}.tsx`);
+    const filePath = await this.resolveComponentFile(componentsPath, name2);
+    if (!filePath) return null;
     try {
       const source = await readFile6(filePath, "utf-8");
       const intelligence = parseJSDocIntelligence(source);
@@ -60616,16 +60754,28 @@ var RaftersToolHandler = class _RaftersToolHandler {
         jsDocDeps = extractJSDocDependencies(source);
       } catch {
       }
+      let variants = extractVariants(source);
+      let sizes = extractSizes(source);
+      try {
+        const classesSource = await readFile6(join10(componentsPath, `${name2}.classes.ts`), "utf-8");
+        if (!variants || variants.length === 0) {
+          variants = extractVariants(classesSource);
+        }
+        if (!sizes || sizes.length === 0) {
+          sizes = extractSizes(classesSource);
+        }
+      } catch {
+      }
       const metadata = {
         name: name2,
         displayName: toDisplayName(name2),
         category: this.inferCategory(name2),
-        variants: extractVariants(source),
-        sizes: extractSizes(source),
+        variants,
+        sizes,
         dependencies: extractDependencies(source),
         primitives: extractPrimitiveDependencies(source),
         // projectRoot is guaranteed non-null here: handleToolCall guards it
-        filePath: relative2(this.projectRoot, join10(componentsPath, `${name2}.tsx`))
+        filePath: relative2(this.projectRoot, filePath)
       };
       if (hasAnyDeps(jsDocDeps)) {
         metadata.jsDocDependencies = jsDocDeps;
@@ -60722,7 +60872,12 @@ var RaftersToolHandler = class _RaftersToolHandler {
         if (componentsPath) {
           try {
             const files = await readdir3(componentsPath);
-            available = files.filter((f) => f.endsWith(".tsx")).map((f) => basename(f, ".tsx")).filter((n2) => n2.includes(name2) || name2.includes(n2)).slice(0, 5);
+            available = files.filter(
+              (f) => COMPONENT_EXTENSIONS.some((ext2) => f.endsWith(ext2)) && !f.includes(".classes.")
+            ).map((f) => {
+              const ext2 = COMPONENT_EXTENSIONS.find((e) => f.endsWith(e));
+              return ext2 ? basename(f, ext2) : basename(f);
+            }).filter((n2) => n2.includes(name2) || name2.includes(n2)).slice(0, 5);
           } catch {
           }
         }
@@ -61308,6 +61463,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,
@@ -61317,7 +61486,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) }]
@@ -61496,15 +61666,145 @@ var RaftersToolHandler = class _RaftersToolHandler {
       const registry2 = new TokenRegistry(allTokens);
       registry2.setAdapter(this.adapter);
       const results = [];
+      const parseRef = (ref) => {
+        const lastDash = ref.lastIndexOf("-");
+        if (lastDash <= 0) return null;
+        const position = ref.slice(lastDash + 1);
+        const family = ref.slice(0, lastDash);
+        if (!/^(50|100|200|300|400|500|600|700|800|900|950)$/.test(position)) return null;
+        return { family, position };
+      };
       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.set(target, newColorRef);
+          const updated = registry2.get(target);
+          if (updated) {
+            updated.dependsOn = [lightTokenName, darkTokenName];
+          } else {
+            results.push({
+              source,
+              target,
+              action: "skipped",
+              ok: false,
+              error: `Token "${target}" was set but could not be retrieved from registry to update dependencies.`
+            });
+            continue;
+          }
+          results.push({
+            source,
+            target,
+            action: "remap",
+            ok: true
+          });
+          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;
         }
@@ -61528,6 +61828,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");
@@ -61551,6 +61859,7 @@ var RaftersToolHandler = class _RaftersToolHandler {
       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 {
@@ -61563,6 +61872,7 @@ var RaftersToolHandler = class _RaftersToolHandler {
                 summary: {
                   set: setCount,
                   created: createCount,
+                  remapped: remapCount,
                   enriched: enrichedCount,
                   failed: failCount
                 },

package/package.json

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