rafters 0.0.46 → 0.0.47

package/dist/index.js

@@ -13718,6 +13718,245 @@ import { createRequire } from "module";
 import { join as join9, relative } from "path";
 import { checkbox, confirm, select } from "@inquirer/prompts";
 
+// ../design-tokens/src/scale-positions.ts
+var INDEX_TO_POSITION = [
+  "50",
+  "100",
+  "200",
+  "300",
+  "400",
+  "500",
+  "600",
+  "700",
+  "800",
+  "900",
+  "950"
+];
+var POSITION_TO_INDEX = {
+  "50": 0,
+  "100": 1,
+  "200": 2,
+  "300": 3,
+  "400": 4,
+  "500": 5,
+  "600": 6,
+  "700": 7,
+  "800": 8,
+  "900": 9,
+  "950": 10
+};
+var SCALE_POSITION_MAP = {
+  50: 0,
+  100: 1,
+  200: 2,
+  300: 3,
+  400: 4,
+  500: 5,
+  600: 6,
+  700: 7,
+  800: 8,
+  900: 9,
+  950: 10
+};
+var SCALE_POSITION_MAP_REVERSE = {};
+for (const [pos, idx] of Object.entries(SCALE_POSITION_MAP)) {
+  if (SCALE_POSITION_MAP_REVERSE[idx] !== void 0) {
+    throw new Error(
+      `Duplicate index ${idx} in SCALE_POSITION_MAP: "${SCALE_POSITION_MAP_REVERSE[idx]}" and "${pos}"`
+    );
+  }
+  SCALE_POSITION_MAP_REVERSE[idx] = pos;
+}
+var VALID_SCALE_POSITIONS = Object.keys(SCALE_POSITION_MAP).map(Number);
+var MIN_WCAG_PAIR_DISTANCE = 3;
+function findBestWcagPair(sourceIndex, pairs, wantHigher) {
+  let best;
+  let bestDistance = -1;
+  for (const pair of pairs) {
+    if (!pair || pair.length < 2) continue;
+    const [a2, b2] = pair;
+    if (a2 === void 0 || b2 === void 0) continue;
+    let partner;
+    if (a2 === sourceIndex) partner = b2;
+    else if (b2 === sourceIndex) partner = a2;
+    else continue;
+    if (wantHigher && partner <= sourceIndex) continue;
+    if (!wantHigher && partner >= sourceIndex) continue;
+    const distance2 = Math.abs(partner - sourceIndex);
+    if (distance2 > bestDistance) {
+      bestDistance = distance2;
+      best = partner;
+    }
+  }
+  return best;
+}
+function findDarkCounterpartIndex(lightIndex, colorValue) {
+  const aaaPairs = colorValue.accessibility?.wcagAAA?.normal ?? [];
+  const aaPairs = colorValue.accessibility?.wcagAA?.normal ?? [];
+  if (aaaPairs.length === 0 && aaPairs.length === 0) {
+    throw new Error(
+      `No WCAG accessibility data available for dark mode counterpart of index ${lightIndex}. ColorValue must include accessibility.wcagAAA or wcagAA pair matrices.`
+    );
+  }
+  const wantHigher = lightIndex <= 5;
+  for (const pairs of [aaaPairs, aaPairs]) {
+    const match2 = findBestWcagPair(lightIndex, pairs, wantHigher);
+    if (match2 !== void 0 && Math.abs(match2 - lightIndex) >= MIN_WCAG_PAIR_DISTANCE) {
+      return match2;
+    }
+  }
+  console.warn(
+    `[design-tokens] No WCAG pair with sufficient distance (>=${MIN_WCAG_PAIR_DISTANCE}) found for index ${lightIndex}. Falling back to mathematical inversion.`
+  );
+  return Math.max(0, Math.min(10, 10 - lightIndex));
+}
+
+// ../design-tokens/src/plugins/contrast.ts
+function contrast(registry2, tokenName, dependencies) {
+  if (dependencies.length === 0) {
+    throw new Error(`No dependencies found for contrast rule on token: ${tokenName}`);
+  }
+  const familyTokenName = dependencies[0];
+  if (!familyTokenName) {
+    throw new Error(`No dependency token name for contrast rule on token: ${tokenName}`);
+  }
+  const familyToken = registry2.get(familyTokenName);
+  if (!familyToken || typeof familyToken.value !== "object") {
+    throw new Error(`ColorValue family token ${familyTokenName} not found for contrast rule`);
+  }
+  const colorValue = familyToken.value;
+  if (colorValue.foregroundReferences?.auto) {
+    const reference = colorValue.foregroundReferences.auto;
+    return {
+      family: reference.family,
+      position: reference.position
+    };
+  }
+  const baseTokenMatch = tokenName.match(/^(.+)-(?:foreground|text|contrast)$/);
+  let basePosition = 5;
+  if (baseTokenMatch?.[1]) {
+    const baseTokenName = baseTokenMatch[1];
+    const baseToken = registry2.get(baseTokenName);
+    if (baseToken && typeof baseToken.value === "object") {
+      const baseRef = baseToken.value;
+      if (baseRef.position) {
+        basePosition = typeof baseRef.position === "string" ? Math.floor(parseInt(baseRef.position, 10) / 100) : Math.floor(baseRef.position / 100);
+      }
+    }
+  }
+  if (colorValue.accessibility) {
+    const accessibility = colorValue.accessibility;
+    const wcagAAA = accessibility.wcagAAA?.normal || [];
+    const wcagAA = accessibility.wcagAA?.normal || [];
+    let contrastPosition;
+    for (const [pos1, pos2] of wcagAAA) {
+      if (pos1 === basePosition) {
+        contrastPosition = pos2;
+        break;
+      }
+      if (pos2 === basePosition) {
+        contrastPosition = pos1;
+        break;
+      }
+    }
+    if (contrastPosition === void 0) {
+      for (const [pos1, pos2] of wcagAA) {
+        if (pos1 === basePosition) {
+          contrastPosition = pos2;
+          break;
+        }
+        if (pos2 === basePosition) {
+          contrastPosition = pos1;
+          break;
+        }
+      }
+    }
+    if (contrastPosition !== void 0) {
+      return {
+        family: familyTokenName,
+        position: INDEX_TO_POSITION[contrastPosition] ?? "500"
+      };
+    }
+  }
+  const neutralFamilies = ["neutral-grayscale", "neutral", "gray", "grey"];
+  for (const neutralFamily of neutralFamilies) {
+    const neutralToken = registry2.get(neutralFamily);
+    if (neutralToken && typeof neutralToken.value === "object") {
+      const neutralValue = neutralToken.value;
+      if (neutralValue.accessibility) {
+        const neutralAccessibility = neutralValue.accessibility;
+        if (neutralAccessibility.onWhite?.aaa && neutralAccessibility.onWhite.aaa.length > 0) {
+          const bestPosition = neutralAccessibility.onWhite.aaa[0];
+          if (bestPosition !== void 0) {
+            return {
+              family: neutralFamily,
+              position: INDEX_TO_POSITION[bestPosition] ?? "500"
+            };
+          }
+        }
+        if (neutralAccessibility.onWhite?.aa && neutralAccessibility.onWhite.aa.length > 0) {
+          const bestPosition = neutralAccessibility.onWhite.aa[0];
+          if (bestPosition !== void 0) {
+            return {
+              family: neutralFamily,
+              position: INDEX_TO_POSITION[bestPosition] ?? "500"
+            };
+          }
+        }
+      }
+      return {
+        family: neutralFamily,
+        position: basePosition <= 5 ? "900" : "100"
+        // Dark text for light backgrounds, light text for dark
+      };
+    }
+  }
+  return {
+    family: familyTokenName ?? "neutral",
+    position: basePosition <= 5 ? "900" : "100"
+  };
+}
+
+// ../design-tokens/src/plugins/invert.ts
+function invert(registry2, tokenName, dependencies) {
+  if (dependencies.length === 0) {
+    throw new Error(`No dependencies found for invert rule on token: ${tokenName}`);
+  }
+  const familyTokenName = dependencies[0];
+  if (!familyTokenName) {
+    throw new Error(`No dependency token name for invert rule on token: ${tokenName}`);
+  }
+  const familyToken = registry2.get(familyTokenName);
+  if (!familyToken || typeof familyToken.value !== "object") {
+    throw new Error(`ColorValue family token ${familyTokenName} not found for invert rule`);
+  }
+  const colorValue = familyToken.value;
+  const lightIndex = extractLightIndex(tokenName, dependencies);
+  const darkIndex = findDarkCounterpartIndex(lightIndex, colorValue);
+  const darkPosition = INDEX_TO_POSITION[darkIndex];
+  if (!darkPosition) {
+    throw new Error(`Invalid dark index ${darkIndex} for token: ${tokenName}`);
+  }
+  return { family: familyTokenName, position: darkPosition };
+}
+function extractLightIndex(tokenName, dependencies) {
+  if (dependencies.length > 1 && dependencies[1]) {
+    const posMatch = dependencies[1].match(/-(\d+)$/);
+    if (posMatch?.[1]) {
+      const idx = POSITION_TO_INDEX[posMatch[1]];
+      if (idx !== void 0) return idx;
+    }
+  }
+  const nameMatch = tokenName.match(/-(\d+)$/);
+  if (nameMatch?.[1]) {
+    const idx = POSITION_TO_INDEX[nameMatch[1]];
+    if (idx !== void 0) return idx;
+  }
+  throw new Error(
+    `Cannot determine light mode scale position for invert rule on token: ${tokenName}. Neither dependency[1] (${dependencies[1] ?? "none"}) nor token name suffix contain a valid position.`
+  );
+}
+
 // ../design-tokens/src/plugins/scale.ts
 function scale(registry2, tokenName, dependencies) {
   const match2 = tokenName.match(/(\d+)$/);
@@ -13742,21 +13981,58 @@ function scale(registry2, tokenName, dependencies) {
   };
 }
 
-// ../design-tokens/src/generation-rules.ts
-var SCALE_POSITION_MAP = {
-  50: 0,
-  100: 1,
-  200: 2,
-  300: 3,
-  400: 4,
-  500: 5,
-  600: 6,
-  700: 7,
-  800: 8,
-  900: 9,
-  950: 10
+// ../design-tokens/src/plugins/state.ts
+var STATE_OFFSETS = {
+  hover: 1,
+  active: 2,
+  focus: 1,
+  disabled: -2
 };
-var VALID_SCALE_POSITIONS = Object.keys(SCALE_POSITION_MAP).map(Number);
+function state(registry2, tokenName, dependencies) {
+  const stateMatch = tokenName.match(/(hover|active|focus|disabled)$/);
+  if (!stateMatch) {
+    throw new Error(`Cannot extract state from token name: ${tokenName}`);
+  }
+  const stateName = stateMatch[1];
+  if (dependencies.length === 0) {
+    throw new Error(`No dependencies found for state rule on token: ${tokenName}`);
+  }
+  const familyTokenName = dependencies[0];
+  if (!familyTokenName) {
+    throw new Error(`No dependency token name for state rule on token: ${tokenName}`);
+  }
+  const familyToken = registry2.get(familyTokenName);
+  if (!familyToken || typeof familyToken.value !== "object") {
+    throw new Error(`ColorValue family token ${familyTokenName} not found for state rule`);
+  }
+  const colorValue = familyToken.value;
+  if (colorValue.stateReferences?.[stateName]) {
+    const reference = colorValue.stateReferences[stateName];
+    return { family: reference.family, position: String(reference.position) };
+  }
+  const baseTokenName = tokenName.replace(/-(hover|active|focus|disabled)$/, "");
+  const baseToken = registry2.get(baseTokenName);
+  let baseIndex = 5;
+  if (baseToken && typeof baseToken.value === "object" && "position" in baseToken.value) {
+    const baseRef = baseToken.value;
+    if (baseRef.position) {
+      const idx = POSITION_TO_INDEX[baseRef.position];
+      if (idx !== void 0) baseIndex = idx;
+    }
+  }
+  const offset = STATE_OFFSETS[stateName] ?? 0;
+  const adjustedIndex = Math.max(0, Math.min(10, baseIndex + offset));
+  const position = INDEX_TO_POSITION[adjustedIndex] ?? "500";
+  return { family: familyTokenName, position };
+}
+
+// ../design-tokens/src/generation-rules.ts
+function cssResult(value2) {
+  return { kind: "css", value: value2 };
+}
+function refResult(family, position) {
+  return { kind: "ref", ref: { family, position } };
+}
 var GenerationRuleParser = class {
   /**
    * Parse a generation rule string into a structured rule object
@@ -13920,7 +14196,9 @@ var GenerationRuleExecutor = class {
     this.registry = registry2;
   }
   /**
-   * Execute a parsed rule and return the computed value
+   * Execute a parsed rule and return the computed value.
+   * Returns a string for CSS-value rules (calc, scale, scale-position)
+   * or a ColorReference for semantic rules (state, contrast, invert).
    */
   execute(rule, tokenName) {
     switch (rule.type) {
@@ -13931,11 +14209,11 @@ var GenerationRuleExecutor = class {
       case "scale-position":
         return this.executeScalePositionRule(rule, tokenName);
       case "state":
-        return this.executeStateRule(rule);
+        return this.executeStateRule(rule, tokenName);
       case "contrast":
-        return this.executeContrastRule(rule);
+        return this.executeContrastRule(rule, tokenName);
       case "invert":
-        return this.executeInvertRule(rule);
+        return this.executeInvertRule(rule, tokenName);
       default:
         throw new Error(`Unknown rule type: ${rule.type}`);
     }
@@ -13955,7 +14233,7 @@ var GenerationRuleExecutor = class {
         expression = expression.replace(new RegExp(`\\{${tokenName}\\}`, "g"), tokenValue);
       }
     }
-    return `calc(${expression})`;
+    return cssResult(`calc(${expression})`);
   }
   executeScaleRule(rule) {
     if (!rule.baseToken) {
@@ -13971,18 +14249,37 @@ var GenerationRuleExecutor = class {
     if (numericMatch?.[1]) {
       const value2 = parseFloat(numericMatch[1]);
       const unit = numericMatch[2] || "";
-      return `${value2 * ratio}${unit}`;
+      return cssResult(`${value2 * ratio}${unit}`);
     }
-    return `calc(${baseValue} * ${ratio})`;
+    return cssResult(`calc(${baseValue} * ${ratio})`);
   }
   /**
-   * Execute a scale-position rule to extract a value from a ColorValue's scale array.
-   * Delegates to the scale plugin for lazy reference, then resolves to CSS.
+   * Execute a scale-position rule.
+   *
+   * For position tokens (e.g., primary-600): extracts from ColorValue scale, returns CSS string.
+   * For semantic tokens (e.g., background): returns a ColorReference to family + position.
+   *
+   * Detection: if the token's current value is a ColorReference, return a ColorReference.
+   * Otherwise, resolve to CSS string via the scale plugin.
    */
-  executeScalePositionRule(_rule, tokenName) {
+  executeScalePositionRule(rule, tokenName) {
+    const existingToken = this.registry.get(tokenName);
+    const existingValue = existingToken?.value;
+    if (existingValue && typeof existingValue === "object" && "family" in existingValue) {
+      const dependencies2 = this.registry.getDependencies(tokenName);
+      const familyName = dependencies2[0];
+      if (!familyName) {
+        throw new Error(`No family dependency for semantic scale rule on token: ${tokenName}`);
+      }
+      const position = rule.scalePosition !== void 0 ? SCALE_POSITION_MAP_REVERSE[rule.scalePosition] : existingValue.position;
+      if (!position) {
+        throw new Error(`Cannot resolve scale position for token: ${tokenName}`);
+      }
+      return refResult(familyName, String(position));
+    }
     const dependencies = this.registry.getDependencies(tokenName);
     const reference = scale(this.registry, tokenName, dependencies);
-    return this.resolveColorReference(reference);
+    return cssResult(this.resolveColorReference(reference));
   }
   /**
    * Resolve a color reference {family, position} to a CSS value.
@@ -14026,49 +14323,20 @@ var GenerationRuleExecutor = class {
     }
     return `oklch(${l} ${c4} ${h})`;
   }
-  executeStateRule(rule) {
-    if (!rule.baseToken) {
-      throw new Error("State rule missing base token");
-    }
-    const baseToken = this.registry.get(rule.baseToken);
-    if (!baseToken) {
-      throw new Error(`Base token not found: ${rule.baseToken}`);
-    }
-    const baseValue = String(baseToken.value);
-    const stateType = rule.stateType || "hover";
-    switch (stateType) {
-      case "hover":
-        return `${baseValue}:hover`;
-      case "focus":
-        return `${baseValue}:focus`;
-      case "active":
-        return `${baseValue}:active`;
-      default:
-        return `${baseValue}:${stateType}`;
-    }
+  executeStateRule(_rule, tokenName) {
+    const dependencies = this.registry.getDependencies(tokenName);
+    const ref = state(this.registry, tokenName, dependencies);
+    return refResult(ref.family, ref.position);
   }
-  executeContrastRule(rule) {
-    if (!rule.baseToken) {
-      throw new Error("Contrast rule missing base token");
-    }
-    const baseToken = this.registry.get(rule.baseToken);
-    if (!baseToken) {
-      throw new Error(`Base token not found: ${rule.baseToken}`);
-    }
-    const baseValue = String(baseToken.value);
-    const contrast2 = rule.contrast || "high";
-    return `contrast(${baseValue}, ${contrast2})`;
+  executeContrastRule(_rule, tokenName) {
+    const dependencies = this.registry.getDependencies(tokenName);
+    const ref = contrast(this.registry, tokenName, dependencies);
+    return refResult(ref.family, ref.position);
   }
-  executeInvertRule(rule) {
-    if (!rule.baseToken) {
-      throw new Error("Invert rule missing base token");
-    }
-    const baseToken = this.registry.get(rule.baseToken);
-    if (!baseToken) {
-      throw new Error(`Base token not found: ${rule.baseToken}`);
-    }
-    const baseValue = String(baseToken.value);
-    return `invert(${baseValue})`;
+  executeInvertRule(_rule, tokenName) {
+    const dependencies = this.registry.getDependencies(tokenName);
+    const ref = invert(this.registry, tokenName, dependencies);
+    return refResult(ref.family, ref.position);
   }
 };
 
@@ -22707,10 +22975,10 @@ var require_events = __commonJS({
       }
     }
     function _onceWrap(target, type2, listener) {
-      var state = { fired: false, wrapFn: void 0, target, type: type2, listener };
-      var wrapped = onceWrapper.bind(state);
+      var state2 = { fired: false, wrapFn: void 0, target, type: type2, listener };
+      var wrapped = onceWrapper.bind(state2);
       wrapped.listener = listener;
-      state.wrapFn = wrapped;
+      state2.wrapFn = wrapped;
       return wrapped;
     }
     EventEmitter2.prototype.once = function once2(type2, listener) {
@@ -24359,20 +24627,20 @@ function __importStar(mod) {
 function __importDefault(mod) {
   return mod && mod.__esModule ? mod : { default: mod };
 }
-function __classPrivateFieldGet(receiver, state, kind, f) {
+function __classPrivateFieldGet(receiver, state2, kind, f) {
   if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
-  if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
-  return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+  if (typeof state2 === "function" ? receiver !== state2 || !f : !state2.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+  return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state2.get(receiver);
 }
-function __classPrivateFieldSet(receiver, state, value2, kind, f) {
+function __classPrivateFieldSet(receiver, state2, value2, kind, f) {
   if (kind === "m") throw new TypeError("Private method is not writable");
   if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
-  if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
-  return kind === "a" ? f.call(receiver, value2) : f ? f.value = value2 : state.set(receiver, value2), value2;
+  if (typeof state2 === "function" ? receiver !== state2 || !f : !state2.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+  return kind === "a" ? f.call(receiver, value2) : f ? f.value = value2 : state2.set(receiver, value2), value2;
 }
-function __classPrivateFieldIn(state, receiver) {
+function __classPrivateFieldIn(state2, receiver) {
   if (receiver === null || typeof receiver !== "object" && typeof receiver !== "function") throw new TypeError("Cannot use 'in' operator on non-object");
-  return typeof state === "function" ? receiver === state : state.has(receiver);
+  return typeof state2 === "function" ? receiver === state2 : state2.has(receiver);
 }
 function __addDisposableResource(env, value2, async) {
   if (value2 !== null && value2 !== void 0) {
@@ -44806,6 +45074,58 @@ var DEFAULT_SHADOW_DEFINITIONS = {
     contexts: ["critical-modals", "overlays", "drawer-panels"]
   }
 };
+var DEFAULT_FILL_DEFINITIONS = {
+  surface: {
+    color: "neutral-900",
+    foreground: "neutral-100",
+    meaning: "Primary content surface",
+    contexts: ["surface"]
+  },
+  panel: {
+    color: "neutral-800",
+    opacity: 0.95,
+    foreground: "neutral-100",
+    meaning: "Elevated panel",
+    contexts: ["surface"]
+  },
+  overlay: {
+    color: "neutral-950",
+    opacity: 0.8,
+    backdropBlur: "sm",
+    foreground: "neutral-50",
+    meaning: "Modal backdrop",
+    contexts: ["surface"]
+  },
+  glass: {
+    color: "neutral-900",
+    opacity: 0.6,
+    backdropBlur: "md",
+    foreground: "neutral-100",
+    meaning: "Glass morphism",
+    contexts: ["surface"]
+  },
+  primary: {
+    color: "primary",
+    foreground: "primary-foreground",
+    meaning: "Primary brand surface",
+    contexts: ["surface", "text"]
+  },
+  muted: {
+    color: "muted",
+    foreground: "muted-foreground",
+    meaning: "Subdued surface for secondary content",
+    contexts: ["surface"]
+  },
+  hero: {
+    gradient: {
+      direction: "to-b",
+      stops: [{ color: "primary" }, { color: "primary", opacity: 0 }]
+    },
+    foreground: "primary-foreground",
+    meaning: "Hero fade gradient",
+    contexts: ["surface", "text"]
+  }
+};
 var DEFAULT_ELEVATION_DEFINITIONS = {
   surface: {
     depth: "depth-base",
@@ -47062,6 +47382,7 @@ function groupTokens(tokens) {
     elevation: [],
     focus: [],
     "typography-composite": [],
+    fill: [],
     other: []
   };
   for (const token of tokens) {
@@ -47102,6 +47423,9 @@ function groupTokens(tokens) {
       case "typography-composite":
         groups["typography-composite"].push(token);
         break;
+      case "fill":
+        groups.fill.push(token);
+        break;
       default:
         groups.other.push(token);
     }
@@ -47270,6 +47594,13 @@ function generateThemeBlock(groups) {
     }
     lines.push("");
   }
+  if (groups.fill.length > 0) {
+    for (const token of groups.fill) {
+      const value2 = typeof token.value === "string" ? token.value : JSON.stringify(token.value);
+      lines.push(`  --${token.name}: ${value2};`);
+    }
+    lines.push("");
+  }
   if (groups.other.length > 0) {
     for (const token of groups.other) {
       const value2 = tokenValueToCSS(token);
@@ -47620,6 +47951,13 @@ function generateVarsRootBlock(groups) {
     }
     lines.push("");
   }
+  if (groups.fill.length > 0) {
+    for (const token of groups.fill) {
+      const value2 = typeof token.value === "string" ? token.value : JSON.stringify(token.value);
+      lines.push(`  --rafters-${token.name}: ${value2};`);
+    }
+    lines.push("");
+  }
   if (groups.other.length > 0) {
     for (const token of groups.other) {
       const value2 = tokenValueToCSS(token);
@@ -49318,24 +49656,60 @@ var TokenRegistry = class {
     }
     try {
       const parsedRule = this.ruleParser.parse(rule);
-      const newComputedValue = this.ruleExecutor.execute(parsedRule, tokenName);
+      const ruleResult = this.ruleExecutor.execute(parsedRule, tokenName);
       this.markDirty(existingToken.namespace);
+      let updatedDependsOn = existingToken.dependsOn;
+      let newValue;
+      switch (ruleResult.kind) {
+        case "ref": {
+          newValue = ruleResult.ref;
+          const darkTokenName = this.findDarkCounterpart(ruleResult.ref, existingToken.dependsOn);
+          updatedDependsOn = [ruleResult.ref.family, darkTokenName];
+          break;
+        }
+        case "css":
+          newValue = ruleResult.value;
+          break;
+      }
       if (existingToken.userOverride) {
         this.tokens.set(tokenName, {
           ...existingToken,
-          computedValue: newComputedValue
-          // value stays as-is (the human's choice)
+          computedValue: newValue,
+          dependsOn: updatedDependsOn
         });
       } else {
         this.tokens.set(tokenName, {
           ...existingToken,
-          value: newComputedValue,
-          computedValue: newComputedValue
+          value: newValue,
+          computedValue: newValue,
+          dependsOn: updatedDependsOn
         });
       }
     } catch (error48) {
-      throw new Error(`Failed to regenerate token ${tokenName}: ${error48}`);
+      throw new Error(`Failed to regenerate token ${tokenName}: ${error48}`, { cause: error48 });
+    }
+  }
+  /**
+   * Find the dark mode counterpart for a light mode ColorReference.
+   * Uses the WCAG accessibility matrix from the color family's ColorValue.
+   * Falls back to mathematical inversion if no WCAG data available.
+   */
+  findDarkCounterpart(lightRef, _existingDependsOn) {
+    const lightIdx = POSITION_TO_INDEX[lightRef.position];
+    if (lightIdx === void 0) {
+      throw new Error(
+        `Invalid position "${lightRef.position}" in ColorReference for family "${lightRef.family}". Expected one of: ${Object.keys(POSITION_TO_INDEX).join(", ")}`
+      );
     }
+    const familyToken = this.tokens.get(lightRef.family);
+    if (!familyToken || typeof familyToken.value !== "object" || !("scale" in familyToken.value)) {
+      const fallbackIdx = Math.max(0, Math.min(10, 10 - lightIdx));
+      return `${lightRef.family}-${INDEX_TO_POSITION[fallbackIdx] ?? "500"}`;
+    }
+    const colorValue = familyToken.value;
+    const darkIdx = findDarkCounterpartIndex(lightIdx, colorValue);
+    const darkPos = INDEX_TO_POSITION[darkIdx] ?? "500";
+    return `${lightRef.family}-${darkPos}`;
   }
   /**
    * Add multiple dependencies efficiently using bulk operations
@@ -52546,8 +52920,8 @@ function contrastDeltaPhi(color1, color2) {
   let Lstr1 = get(color1, [lab_d65, "l"]);
   let Lstr2 = get(color2, [lab_d65, "l"]);
   let deltaPhiStar = Math.abs(Math.pow(Lstr1, phi) - Math.pow(Lstr2, phi));
-  let contrast2 = Math.pow(deltaPhiStar, 1 / phi) * Math.SQRT2 - 40;
-  return contrast2 < 7.5 ? 0 : contrast2;
+  let contrast3 = Math.pow(deltaPhiStar, 1 / phi) * Math.SQRT2 - 40;
+  return contrast3 < 7.5 ? 0 : contrast3;
 }
 var contrastMethods = /* @__PURE__ */ Object.freeze({
   __proto__: null,
@@ -52558,7 +52932,7 @@ var contrastMethods = /* @__PURE__ */ Object.freeze({
   contrastWCAG21,
   contrastWeber
 });
-function contrast(background, foreground, o = {}) {
+function contrast2(background, foreground, o = {}) {
   if (isString(o)) {
     o = { algorithm: o };
   }
@@ -53870,7 +54244,7 @@ Color.extend(deltaEMethods);
 Color.extend({ deltaE });
 Object.assign(Color, { deltaEMethods });
 Color.extend(variations);
-Color.extend({ contrast });
+Color.extend({ contrast: contrast2 });
 Color.extend(chromaticity);
 Color.extend(luminance);
 Color.extend(interpolation);
@@ -53944,12 +54318,12 @@ function calculateAPCAContrast(foreground, background) {
   return typeof result === "number" ? result : 0;
 }
 function meetsWCAGStandard(foreground, background, level, textSize) {
-  const contrast2 = calculateWCAGContrast(foreground, background);
+  const contrast3 = calculateWCAGContrast(foreground, background);
   const thresholds = {
     AA: { normal: 4.5, large: 3 },
     AAA: { normal: 7, large: 4.5 }
   };
-  return contrast2 >= thresholds[level][textSize];
+  return contrast3 >= thresholds[level][textSize];
 }
 function generateAccessibilityMetadata(scale3) {
   if (!scale3 || scale3.length === 0) {
@@ -57342,6 +57716,102 @@ function generateElevationTokens(_config, elevationDefs) {
   };
 }
 
+// ../design-tokens/src/generators/fill.ts
+function validateFillDef(name2, def) {
+  if (!def.color && !def.gradient) {
+    return `Fill "${name2}" must have either a color or gradient field`;
+  }
+  if (def.gradient) {
+    if (!def.gradient.stops || def.gradient.stops.length < 2) {
+      return `Fill "${name2}" gradient must have at least 2 stops`;
+    }
+  }
+  if (def.opacity !== void 0 && (def.opacity < 0 || def.opacity > 1)) {
+    return `Fill "${name2}" opacity must be between 0 and 1`;
+  }
+  const validBlurSizes = ["sm", "md", "lg", "xl", "2xl", "3xl"];
+  if (def.backdropBlur && !validBlurSizes.includes(def.backdropBlur)) {
+    return `Fill "${name2}" backdropBlur must be one of: ${validBlurSizes.join(", ")}`;
+  }
+  return null;
+}
+function serializeFillValue(def) {
+  const parts = {};
+  if (def.color) parts.color = def.color;
+  if (def.opacity !== void 0) parts.opacity = def.opacity;
+  if (def.foreground) parts.foreground = def.foreground;
+  if (def.backdropBlur) parts.backdropBlur = def.backdropBlur;
+  if (def.gradient) parts.gradient = def.gradient;
+  return JSON.stringify(parts);
+}
+function generateFillTokens(_config, fillDefinitions) {
+  const tokens = [];
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+  const fillNames = Object.keys(fillDefinitions);
+  for (const [name2, def] of Object.entries(fillDefinitions)) {
+    const error48 = validateFillDef(name2, def);
+    if (error48) {
+      throw new Error(error48);
+    }
+    const dependsOn = [];
+    if (def.color) {
+      dependsOn.push(def.color);
+    }
+    if (def.foreground) {
+      dependsOn.push(def.foreground);
+    }
+    if (def.gradient) {
+      for (const stop of def.gradient.stops) {
+        dependsOn.push(stop.color);
+      }
+    }
+    tokens.push({
+      name: `fill-${name2}`,
+      value: serializeFillValue(def),
+      category: "fill",
+      namespace: "fill",
+      semanticMeaning: def.meaning,
+      usageContext: def.contexts,
+      dependsOn: dependsOn.length > 0 ? dependsOn : void 0,
+      description: buildDescription(name2, def),
+      generatedAt: timestamp,
+      containerQueryAware: true,
+      scalePosition: fillNames.indexOf(name2),
+      usagePatterns: {
+        do: [
+          `Use fill="${name2}" on surface components (Container, Card) for ${def.meaning.toLowerCase()}`,
+          ...def.gradient ? [`Use color="${name2}" on Typography for gradient text effect`] : []
+        ],
+        never: [
+          "Do not use raw bg-* classes when a fill token exists for the purpose",
+          "Do not hardcode opacity values -- use the fill token instead"
+        ]
+      }
+    });
+  }
+  return {
+    namespace: "fill",
+    tokens
+  };
+}
+function buildDescription(name2, def) {
+  const parts = [`Fill token "${name2}"`];
+  if (def.color && def.opacity !== void 0 && def.opacity < 1) {
+    parts.push(`-- ${def.color} at ${Math.round(def.opacity * 100)}% opacity`);
+  } else if (def.color) {
+    parts.push(`-- solid ${def.color}`);
+  }
+  if (def.backdropBlur) {
+    parts.push(`with backdrop-blur-${def.backdropBlur}`);
+  }
+  if (def.gradient) {
+    const stops = def.gradient.stops.map((s) => s.color).join(" to ");
+    parts.push(`-- gradient ${def.gradient.direction}: ${stops}`);
+  }
+  parts.push(`(${def.meaning})`);
+  return parts.join(" ");
+}
+
 // ../design-tokens/src/generators/focus.ts
 function pxToRem(px) {
   const rem = Math.round(px / 16 * 1e3) / 1e3;
@@ -58307,20 +58777,41 @@ function toColorRef(mapping) {
 function toDarkColorRef(mapping) {
   return { family: mapping.dark.family, position: mapping.dark.position };
 }
+function deriveGenerationRule(name2, lightRef) {
+  if (name2.endsWith("-foreground") || name2.endsWith("-text") || name2.endsWith("-contrast")) {
+    return "contrast:auto";
+  }
+  if (name2.endsWith("-hover") && !name2.endsWith("-hover-foreground")) {
+    return "state:hover";
+  }
+  if (name2.endsWith("-active") && !name2.endsWith("-active-foreground")) {
+    return "state:active";
+  }
+  if (name2.endsWith("-focus") && !name2.endsWith("-focus-foreground")) {
+    return "state:focus";
+  }
+  if (name2.endsWith("-disabled") && !name2.endsWith("-disabled-foreground")) {
+    return "state:disabled";
+  }
+  return `scale:${lightRef.position}`;
+}
 function generateSemanticTokens(_config) {
   const tokens = [];
   const timestamp = (/* @__PURE__ */ new Date()).toISOString();
   for (const [name2, mapping] of Object.entries(DEFAULT_SEMANTIC_COLOR_MAPPINGS)) {
     const lightRef = toColorRef(mapping);
     const darkRef = toDarkColorRef(mapping);
-    const dependsOn = [`${lightRef.family}-${lightRef.position}`];
-    if (darkRef.family !== lightRef.family || darkRef.position !== lightRef.position) {
-      dependsOn.push(`${darkRef.family}-${darkRef.position}`);
+    const familyDep = lightRef.family;
+    const darkTokenName = `${darkRef.family}-${darkRef.position}`;
+    const dependsOn = [familyDep];
+    if (darkTokenName !== familyDep) {
+      dependsOn.push(darkTokenName);
     }
+    const generationRule = deriveGenerationRule(name2, lightRef);
     tokens.push({
       name: name2,
       value: lightRef,
-      // Light mode is default value; dark mode lookup via DEFAULT_SEMANTIC_COLOR_MAPPINGS
+      // Light mode is default value; dark mode lookup via dependsOn[1]
       category: "color",
       namespace: "semantic",
       semanticMeaning: mapping.meaning,
@@ -58328,6 +58819,7 @@ function generateSemanticTokens(_config) {
       trustLevel: mapping.trustLevel,
       consequence: mapping.consequence,
       dependsOn,
+      generationRule,
       description: `${mapping.meaning}. Light: ${lightRef.family}-${lightRef.position}, Dark: ${darkRef.family}-${darkRef.position}.`,
       generatedAt: timestamp,
       containerQueryAware: true,
@@ -58676,6 +59168,21 @@ function generateTypographyTokens(config3, typographyScale, fontWeights) {
       never: ["Use for body text", "Use for UI elements"]
     }
   });
+  tokens.push({
+    name: "font-serif",
+    value: 'Georgia, "Times New Roman", Times, serif',
+    category: "typography",
+    namespace: "typography",
+    semanticMeaning: "Serif font family for editorial and long-form content",
+    usageContext: ["editorial", "long-form", "articles", "blockquotes"],
+    description: "Serif font family. System serif stack by default. Override in global.css @theme with your imported serif font.",
+    generatedAt: timestamp,
+    containerQueryAware: false,
+    usagePatterns: {
+      do: ["Override in global.css @theme to match imported serif font"],
+      never: ["Use without importing an actual serif font for production"]
+    }
+  });
   tokens.push({
     name: "font-heading",
     value: `var(--font-sans)`,
@@ -58962,6 +59469,11 @@ function createGeneratorDefs(colorPaletteBases) {
         DEFAULT_DELAY_DEFINITIONS
       )
     },
+    // Fill tokens (depend on color/semantic)
+    {
+      name: "fill",
+      generate: (_config) => generateFillTokens(_config, DEFAULT_FILL_DEFINITIONS)
+    },
     // Composite tokens (depend on multiple)
     {
       name: "elevation",
@@ -62622,100 +63134,133 @@ var RaftersToolHandler = class _RaftersToolHandler {
           });
           continue;
         }
-        let tokenValue = value2;
+        let colorValue = null;
         let enriched = false;
         if (_RaftersToolHandler.isColorValue(value2)) {
           const oklch2 = _RaftersToolHandler.parseToOKLCH(value2);
           if (oklch2) {
-            tokenValue = await _RaftersToolHandler.buildEnrichedColor(oklch2, target);
+            colorValue = await _RaftersToolHandler.buildEnrichedColor(oklch2, target);
             enriched = true;
           }
         }
-        const SCALE_POSITIONS2 = [
-          "50",
-          "100",
-          "200",
-          "300",
-          "400",
-          "500",
-          "600",
-          "700",
-          "800",
-          "900",
-          "950"
-        ];
-        if (enriched && tokenValue && typeof tokenValue === "object" && "scale" in tokenValue) {
-          const cv = tokenValue;
-          for (let i = 0; i < cv.scale.length && i < SCALE_POSITIONS2.length; i++) {
+        if (enriched && colorValue) {
+          const isSemantic = _RaftersToolHandler.SEMANTIC_FAMILY_SET.has(target);
+          const familyName = isSemantic ? colorValue.name : target;
+          if (registry2.has(familyName)) {
+            const existingFamily = registry2.get(familyName);
+            if (existingFamily && existingFamily.namespace === "semantic") {
+              registry2.add({
+                name: familyName,
+                value: colorValue,
+                category: "color",
+                namespace: "color",
+                semanticMeaning: `Color family for ${target}`,
+                description: `Enriched color family "${familyName}" mapped to semantic role "${target}"`,
+                containerQueryAware: true
+              });
+            } else {
+              await registry2.set(familyName, colorValue);
+            }
+          } else {
+            registry2.add({
+              name: familyName,
+              value: colorValue,
+              category: "color",
+              namespace: "color",
+              semanticMeaning: `Color family for ${target}`,
+              description: `Enriched color family "${familyName}" mapped to semantic role "${target}"`,
+              containerQueryAware: true,
+              userOverride: isSemantic ? void 0 : {
+                previousValue: "",
+                reason: `Onboarded from ${source}: ${reason}`
+              }
+            });
+          }
+          const SCALE_POSITIONS2 = [
+            "50",
+            "100",
+            "200",
+            "300",
+            "400",
+            "500",
+            "600",
+            "700",
+            "800",
+            "900",
+            "950"
+          ];
+          for (let i = 0; i < colorValue.scale.length && i < SCALE_POSITIONS2.length; i++) {
             const pos = SCALE_POSITIONS2[i];
-            const oklchValue = cv.scale[i];
+            const oklchValue = colorValue.scale[i];
             if (!oklchValue) continue;
-            const posName = `${target}-${pos}`;
+            const posName = `${familyName}-${pos}`;
             const cssValue = oklchToCSS(oklchValue);
-            const posToken = {
-              name: posName,
-              value: cssValue,
-              category: "color",
-              namespace: "color",
-              scalePosition: i,
-              description: `${target} color at ${pos} position`,
-              containerQueryAware: true
-            };
             if (registry2.has(posName)) {
               await registry2.set(posName, cssValue);
             } else {
-              registry2.add(posToken);
+              registry2.add({
+                name: posName,
+                value: cssValue,
+                category: "color",
+                namespace: "color",
+                scalePosition: i,
+                description: `${familyName} color at ${pos} position`,
+                containerQueryAware: true
+              });
             }
           }
-        }
-        const exists = registry2.has(target);
-        if (exists) {
-          const existing = registry2.get(target);
-          if (existing) {
-            const previousValue = existing.value;
-            existing.userOverride = {
-              previousValue: typeof previousValue === "string" ? previousValue : JSON.stringify(previousValue),
-              reason: `Onboarded from ${source}: ${reason}`
-            };
-            await registry2.set(target, tokenValue);
+          if (isSemantic) {
+            const existing = registry2.get(target);
+            if (existing) {
+              const previousValue = existing.value;
+              existing.userOverride = {
+                previousValue: typeof previousValue === "string" ? previousValue : JSON.stringify(previousValue),
+                reason: `Onboarded from ${source}: ${reason}`
+              };
+              const defaultMapping = DEFAULT_SEMANTIC_COLOR_MAPPINGS[target];
+              const lightPos = defaultMapping?.light.position ?? "900";
+              await registry2.setToken({
+                ...existing,
+                value: { family: familyName, position: lightPos },
+                dependsOn: [familyName, `${familyName}-${defaultMapping?.dark.position ?? "50"}`]
+              });
+            }
             results.push({ source, target, action: "set", ok: true, enriched });
+            allCascadeTokens.push(
+              ...this.cascadeSemanticFamily(registry2, target, familyName, results)
+            );
           } else {
-            results.push({
-              source,
-              target,
-              action: "skipped",
-              ok: false,
-              error: `Token "${target}" exists in registry index but could not be retrieved.`
-            });
+            results.push({ source, target, action: "create", ok: true, enriched });
           }
         } else {
-          const ns = namespace ?? (enriched ? "color" : "custom");
-          const cat = category ?? ns;
-          const newToken = {
-            name: target,
-            namespace: ns,
-            category: cat,
-            value: tokenValue,
-            containerQueryAware: true,
-            userOverride: {
-              previousValue: "",
-              reason: `Onboarded from ${source}: ${reason}`
+          const tokenValue = value2;
+          const exists = registry2.has(target);
+          if (exists) {
+            const existing = registry2.get(target);
+            if (existing) {
+              const previousValue = existing.value;
+              existing.userOverride = {
+                previousValue: typeof previousValue === "string" ? previousValue : JSON.stringify(previousValue),
+                reason: `Onboarded from ${source}: ${reason}`
+              };
+              await registry2.set(target, tokenValue);
+              results.push({ source, target, action: "set", ok: true, enriched });
             }
-          };
-          registry2.add(newToken);
-          results.push({ source, target, action: "create", ok: true, enriched });
-        }
-        if (_RaftersToolHandler.SEMANTIC_FAMILY_SET.has(target)) {
-          if (!enriched) {
-            results.push({
-              source,
-              target,
-              action: "skipped",
-              ok: false,
-              error: `Cascade skipped for "${target}": value was not enriched. Provide a CSS color value so the color family can be created with accessibility data.`
-            });
           } else {
-            allCascadeTokens.push(...this.cascadeSemanticFamily(registry2, target, target, results));
+            const ns = namespace ?? "custom";
+            const cat = category ?? ns;
+            registry2.add({
+              name: target,
+              namespace: ns,
+              category: cat,
+              value: tokenValue,
+              containerQueryAware: true,
+              userOverride: {
+                previousValue: "",
+                reason: `Onboarded from ${source}: ${reason}`
+              }
+            });
+            results.push({ source, target, action: "create", ok: true, enriched });
           }
         }
       }

package/package.json

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