rafters 0.0.63 → 0.0.65

package/dist/index.js

@@ -18394,94 +18394,6 @@ function generateHarmony(baseColor) {
     monochromatic
   };
 }
-function generateSemanticColorSuggestions(baseColor) {
-  const danger = [
-    roundOKLCH({
-      l: Math.max(0.55, Math.min(0.7, baseColor.l + 0.1)),
-      c: Math.min(0.25, baseColor.c * 1.2),
-      h: 15,
-      alpha: 1
-    }),
-    roundOKLCH({
-      l: Math.max(0.6, Math.min(0.75, baseColor.l + 0.15)),
-      c: Math.min(0.22, baseColor.c * 1.1),
-      h: 25,
-      alpha: 1
-    }),
-    roundOKLCH({
-      l: Math.max(0.5, Math.min(0.65, baseColor.l + 0.05)),
-      c: Math.min(0.23, baseColor.c * 1.15),
-      h: 5,
-      alpha: 1
-    })
-  ];
-  const success2 = [
-    roundOKLCH({
-      l: Math.max(0.6, Math.min(0.75, baseColor.l + 0.15)),
-      c: Math.min(0.2, baseColor.c * 0.9),
-      h: 135,
-      alpha: 1
-    }),
-    roundOKLCH({
-      l: Math.max(0.55, Math.min(0.7, baseColor.l + 0.1)),
-      c: Math.min(0.22, baseColor.c * 1),
-      h: 145,
-      alpha: 1
-    }),
-    roundOKLCH({
-      l: Math.max(0.65, Math.min(0.8, baseColor.l + 0.2)),
-      c: Math.min(0.24, baseColor.c * 1.1),
-      h: 125,
-      alpha: 1
-    })
-  ];
-  const warning = [
-    roundOKLCH({
-      l: Math.max(0.7, Math.min(0.8, baseColor.l + 0.15)),
-      c: Math.min(0.2, baseColor.c * 0.95),
-      h: 45,
-      alpha: 1
-    }),
-    roundOKLCH({
-      l: Math.max(0.75, Math.min(0.85, baseColor.l + 0.2)),
-      c: Math.min(0.18, baseColor.c * 0.9),
-      h: 55,
-      alpha: 1
-    }),
-    roundOKLCH({
-      l: Math.max(0.72, Math.min(0.82, baseColor.l + 0.17)),
-      c: Math.min(0.19, baseColor.c * 0.92),
-      h: 35,
-      alpha: 1
-    })
-  ];
-  const info = [
-    roundOKLCH({
-      l: Math.max(0.6, Math.min(0.75, baseColor.l + 0.1)),
-      c: Math.min(0.2, baseColor.c * 0.9),
-      h: 220,
-      alpha: 1
-    }),
-    roundOKLCH({
-      l: Math.max(0.55, Math.min(0.7, baseColor.l + 0.05)),
-      c: Math.min(0.22, baseColor.c * 1),
-      h: 230,
-      alpha: 1
-    }),
-    roundOKLCH({
-      l: Math.max(0.5, Math.min(0.65, baseColor.l)),
-      c: Math.min(0.25, baseColor.c * 1.1),
-      h: 240,
-      alpha: 1
-    })
-  ];
-  return {
-    danger: danger.map(clampColor),
-    success: success2.map(clampColor),
-    warning: warning.map(clampColor),
-    info: info.map(clampColor)
-  };
-}
 function validateScaleGeneration(baseColor) {
   const l = baseColor.l;
   if (l > 0.85) {
@@ -21213,44 +21125,255 @@ var POSITION_TO_INDEX = SCALE_POSITIONS.reduce(
   },
   {}
 );
-var MIN_WCAG_PAIR_DISTANCE = 3;
-function findBestWcagPair(sourceIndex, pairs, wantHigher) {
-  let best;
-  let bestDistance = -1;
+
+// ../color-utils/src/semantic.ts
+var SemanticSelectionError = class extends Error {
+  constructor(familyName, message) {
+    super(`semantic selection: family "${familyName}" ${message}`);
+    this.familyName = familyName;
+    this.name = "SemanticSelectionError";
+  }
+};
+var STATE_USES = ["hover", "active", "focus", "disabled"];
+var STATE_RANK_STEP = {
+  hover: (rank) => rank + 1,
+  active: (rank) => rank + 2,
+  focus: (rank) => rank + 1,
+  disabled: (_rank, ladder) => closestRankTo(ladder, 5)
+};
+function partnerForBase(pairs, base) {
+  if (!pairs) return void 0;
+  for (const [p1, p2] of pairs) {
+    if (p1 === base) return p2;
+    if (p2 === base) return p1;
+  }
+  return void 0;
+}
+function nearestPartner(pairs, base) {
+  if (!pairs || pairs.length === 0) return void 0;
+  const anchors = /* @__PURE__ */ new Set();
   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) {
+    for (const position of pair) anchors.add(position);
+  }
+  let nearest = -1;
+  let bestDistance = Number.POSITIVE_INFINITY;
+  for (const anchor of anchors) {
+    const distance2 = Math.abs(anchor - base);
+    if (distance2 < bestDistance) {
       bestDistance = distance2;
-      best = partner;
+      nearest = anchor;
     }
   }
-  return best;
+  return nearest === -1 ? void 0 : partnerForBase(pairs, nearest);
 }
-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.`
-    );
+function collectLadder(pairs) {
+  const positions = /* @__PURE__ */ new Set();
+  for (const pair of pairs) {
+    for (const position of pair) positions.add(position);
+  }
+  return Array.from(positions).sort((a2, b2) => a2 - b2);
+}
+function closestRankTo(ladder, target) {
+  let bestRank = 0;
+  let bestDistance = Number.POSITIVE_INFINITY;
+  for (let rank = 0; rank < ladder.length; rank++) {
+    const position = ladder[rank];
+    if (position === void 0) continue;
+    const distance2 = Math.abs(position - target);
+    if (distance2 < bestDistance) {
+      bestDistance = distance2;
+      bestRank = rank;
+    }
+  }
+  return bestRank;
+}
+function requirePosition(index, familyName) {
+  const position = SCALE_POSITIONS[index];
+  if (!position) {
+    throw new SemanticSelectionError(familyName, `produced invalid scale index ${index}`);
+  }
+  return position;
+}
+function requireIndex(position, familyName) {
+  const index = POSITION_TO_INDEX[position];
+  if (index === void 0) {
+    throw new SemanticSelectionError(familyName, `has no scale position "${position}"`);
+  }
+  return index;
+}
+var STATUS_ROLE_ANCHORS = {
+  // band is the recognizability range a variant may never leave;
+  // [min > max] means the band wraps through 0 (destructive: 330..360..30).
+  destructive: { hue: 25, l: 0.55, cCap: 0.2, cScale: 1, band: [330, 30] },
+  success: { hue: 145, l: 0.55, cCap: 0.18, cScale: 0.9, band: [120, 160] },
+  warning: { hue: 85, l: 0.75, cCap: 0.18, cScale: 0.9, band: [60, 110] },
+  info: { hue: 230, l: 0.58, cCap: 0.15, cScale: 0.85, band: [200, 250] }
+};
+function statusAnchor(role, seed) {
+  const spec = STATUS_ROLE_ANCHORS[role];
+  return roundOKLCH({
+    l: spec.l,
+    c: Math.min(spec.cCap, seed.c * spec.cScale),
+    h: spec.hue,
+    alpha: seed.alpha ?? 1
+  });
+}
+function clampHueToBand(hue, band) {
+  const h = (hue % 360 + 360) % 360;
+  const [min, max2] = band;
+  if (min <= max2) return Math.max(min, Math.min(max2, h));
+  if (h >= min || h <= max2) return h;
+  const toMin = Math.abs(h - min);
+  const toMax = Math.abs(h - max2);
+  return toMin < toMax ? min : max2;
+}
+var VARIANT_OFFSETS = [
+  { dh: 0, dl: 0 },
+  { dh: 10, dl: 0.05 },
+  { dh: -10, dl: -0.05 }
+];
+function generateSemanticColorSuggestions(baseColor) {
+  const roles = {};
+  for (const role of Object.keys(STATUS_ROLE_ANCHORS)) {
+    const anchor = statusAnchor(role, baseColor);
+    const { band } = STATUS_ROLE_ANCHORS[role];
+    roles[role] = VARIANT_OFFSETS.map(({ dh, dl }) => {
+      const raw = roundOKLCH({
+        l: Math.max(0, Math.min(1, anchor.l + dl)),
+        c: anchor.c,
+        h: clampHueToBand(anchor.h + dh, band),
+        alpha: anchor.alpha ?? 1
+      });
+      return roundOKLCH(toNearestGamut(raw).color);
+    });
+  }
+  return { ...roles, danger: roles.destructive };
+}
+function semanticFor(family, options) {
+  const familyName = options?.name ?? family.name;
+  const refs = family;
+  const aaaPairs = family.accessibility?.wcagAAA?.normal;
+  const aaPairs = family.accessibility?.wcagAA?.normal;
+  function foregroundPair(from, level) {
+    const auto = refs.foregroundReferences?.auto;
+    if (auto) {
+      return {
+        from: { family: familyName, position: from },
+        to: { family: auto.family, position: auto.position },
+        standard: level,
+        tier: "reference"
+      };
+    }
+    const base = requireIndex(from, familyName);
+    const exactAAA = partnerForBase(aaaPairs, base);
+    const aaa = exactAAA ?? nearestPartner(aaaPairs, base);
+    const exactAA = partnerForBase(aaPairs, base);
+    const aa = exactAA ?? nearestPartner(aaPairs, base);
+    const partner = level === "AAA" ? aaa ?? aa : aa;
+    if (partner === void 0) {
+      throw new SemanticSelectionError(
+        familyName,
+        `has no WCAG pair partner for position ${from} (accessibility metadata required)`
+      );
+    }
+    const fromAAA = level === "AAA" && aaa !== void 0;
+    return {
+      from: { family: familyName, position: from },
+      to: { family: familyName, position: requirePosition(partner, familyName) },
+      standard: fromAAA ? "AAA" : "AA",
+      tier: (fromAAA ? exactAAA : exactAA) !== void 0 ? "pair-exact" : "pair-nearest"
+    };
+  }
+  function statePair(use, from) {
+    const precomputed = refs.stateReferences?.[use];
+    if (precomputed) {
+      return {
+        from: { family: familyName, position: from },
+        to: { family: precomputed.family, position: String(precomputed.position) },
+        standard: "AAA",
+        tier: "reference"
+      };
+    }
+    if (!aaaPairs || aaaPairs.length === 0) {
+      throw new SemanticSelectionError(
+        familyName,
+        "has no accessibility.wcagAAA.normal ladder (color generator must emit accessibility metadata)"
+      );
+    }
+    const base = requireIndex(from, familyName);
+    const ladder = collectLadder(aaaPairs);
+    const baseRank = closestRankTo(ladder, base);
+    const targetRank = STATE_RANK_STEP[use](baseRank, ladder);
+    const clampedRank = Math.max(0, Math.min(ladder.length - 1, targetRank));
+    const targetIndex = ladder[clampedRank];
+    if (targetIndex === void 0) {
+      throw new SemanticSelectionError(familyName, `ladder lookup failed at rank ${clampedRank}`);
+    }
+    return {
+      from: { family: familyName, position: from },
+      to: { family: familyName, position: requirePosition(targetIndex, familyName) },
+      standard: "AAA",
+      tier: "ladder"
+    };
   }
-  const wantHigher = lightIndex <= 5;
-  for (const pairs of [aaaPairs, aaPairs]) {
-    const match = findBestWcagPair(lightIndex, pairs, wantHigher);
-    if (match !== void 0 && Math.abs(match - lightIndex) >= MIN_WCAG_PAIR_DISTANCE) {
-      return match;
+  function invert(pair) {
+    if (pair.to.family !== familyName && pair.tier !== "reference") {
+      throw new SemanticSelectionError(
+        familyName,
+        `cannot invert a pair whose legs belong to "${pair.from.family}"/"${pair.to.family}"`
+      );
     }
+    const fromTarget = 10 - requireIndex(pair.from.position, familyName);
+    const toIndex = POSITION_TO_INDEX[pair.to.position];
+    const toTarget = toIndex === void 0 ? void 0 : 10 - toIndex;
+    for (const [pairs, standard] of [
+      [aaaPairs, "AAA"],
+      [aaPairs, "AA"]
+    ]) {
+      if (!pairs || pairs.length === 0) continue;
+      let best = null;
+      for (const [p1, p2] of pairs) {
+        if (p1 === void 0 || p2 === void 0) continue;
+        for (const [a2, b2] of [
+          [p1, p2],
+          [p2, p1]
+        ]) {
+          const fromDist = Math.abs(a2 - fromTarget);
+          const toDist = toTarget === void 0 ? 0 : Math.abs(b2 - toTarget);
+          const better = best === null || fromDist < best.fromDist || fromDist === best.fromDist && toDist < best.toDist || fromDist === best.fromDist && toDist === best.toDist && a2 < best.from;
+          if (better) best = { from: a2, to: b2, fromDist, toDist };
+        }
+      }
+      if (best) {
+        return {
+          from: { family: familyName, position: requirePosition(best.from, familyName) },
+          to: { family: familyName, position: requirePosition(best.to, familyName) },
+          standard,
+          tier: best.fromDist === 0 && best.toDist === 0 ? "pair-exact" : "pair-nearest"
+        };
+      }
+    }
+    const toFallback = toTarget === void 0 ? fromTarget : toTarget;
+    return {
+      from: { family: familyName, position: requirePosition(fromTarget, familyName) },
+      to: { family: familyName, position: requirePosition(toFallback, familyName) },
+      standard: "none",
+      tier: "inversion"
+    };
   }
-  return Math.max(0, Math.min(10, 10 - lightIndex));
+  return {
+    pair(request) {
+      const level = request.level ?? "AAA";
+      if (request.use === "foreground") return foregroundPair(request.from, level);
+      return statePair(request.use, request.from);
+    },
+    states(from) {
+      const out = {};
+      for (const use of STATE_USES) out[use] = statePair(use, from);
+      return out;
+    },
+    invert
+  };
 }
 
 // ../color-utils/src/builder.ts
@@ -21603,12 +21726,22 @@ var PerceptualWeightSchema = external_exports.object({
   density: external_exports.enum(["light", "medium", "heavy"]),
   balancingRecommendation: external_exports.string()
 });
-var SemanticColorSuggestionsSchema = external_exports.object({
-  danger: external_exports.array(OKLCHSchema),
-  success: external_exports.array(OKLCHSchema),
-  warning: external_exports.array(OKLCHSchema),
-  info: external_exports.array(OKLCHSchema)
-});
+var SemanticColorSuggestionsSchema = external_exports.preprocess(
+  (raw) => {
+    if (raw && typeof raw === "object" && !("destructive" in raw) && "danger" in raw) {
+      return { ...raw, destructive: raw.danger };
+    }
+    return raw;
+  },
+  external_exports.object({
+    destructive: external_exports.array(OKLCHSchema),
+    success: external_exports.array(OKLCHSchema),
+    warning: external_exports.array(OKLCHSchema),
+    info: external_exports.array(OKLCHSchema),
+    /** @deprecated mirror of `destructive`; dies when apps/api leaves the repo */
+    danger: external_exports.array(OKLCHSchema).optional()
+  })
+);
 var ColorValueSchema = external_exports.object({
   name: external_exports.string(),
   // the fancy name from color-utils, IE ocean-blue
@@ -24290,16 +24423,16 @@ var DEFAULT_SEMANTIC_COLOR_MAPPINGS = {
   // CORE SURFACE TOKENS (shadcn compatible)
   // ============================================================================
   background: {
-    light: { family: "zinc", position: "50" },
-    dark: { family: "zinc", position: "950" },
+    light: { family: "neutral", position: "50" },
+    dark: { family: "neutral", position: "950" },
     meaning: "Primary page background color",
     contexts: ["page-bg", "app-background"],
     do: ["Use for main page background"],
     never: ["Use for interactive elements"]
   },
   foreground: {
-    light: { family: "zinc", position: "950" },
-    dark: { family: "zinc", position: "50" },
+    light: { family: "neutral", position: "950" },
+    dark: { family: "neutral", position: "50" },
     meaning: "Primary text color",
     contexts: ["body-text", "headings", "primary-content"],
     do: ["Use for main text content", "Use for headings"],
@@ -24307,32 +24440,32 @@ var DEFAULT_SEMANTIC_COLOR_MAPPINGS = {
   },
   // Card surfaces
   card: {
-    light: { family: "zinc", position: "50" },
-    dark: { family: "zinc", position: "950" },
+    light: { family: "neutral", position: "50" },
+    dark: { family: "neutral", position: "950" },
     meaning: "Card and contained surface background",
     contexts: ["cards", "modals", "dialogs", "panels"],
     do: ["Use for elevated surfaces"],
     never: ["Use for page-level backgrounds"]
   },
   "card-foreground": {
-    light: { family: "zinc", position: "950" },
-    dark: { family: "zinc", position: "50" },
+    light: { family: "neutral", position: "950" },
+    dark: { family: "neutral", position: "50" },
     meaning: "Text on card surfaces",
     contexts: ["card-text", "modal-text"],
     do: ["Use for text within cards"],
     never: ["Use without card background"]
   },
   "card-hover": {
-    light: { family: "zinc", position: "100" },
-    dark: { family: "zinc", position: "900" },
+    light: { family: "neutral", position: "100" },
+    dark: { family: "neutral", position: "900" },
     meaning: "Card hover state background",
     contexts: ["card-hover"],
     do: ["Use for card hover states"],
     never: ["Use as default card background"]
   },
   "card-border": {
-    light: { family: "zinc", position: "200" },
-    dark: { family: "zinc", position: "800" },
+    light: { family: "neutral", position: "200" },
+    dark: { family: "neutral", position: "800" },
     meaning: "Card border color",
     contexts: ["card-borders"],
     do: ["Use for card borders"],
@@ -24340,24 +24473,24 @@ var DEFAULT_SEMANTIC_COLOR_MAPPINGS = {
   },
   // Popover surfaces
   popover: {
-    light: { family: "zinc", position: "50" },
-    dark: { family: "zinc", position: "950" },
+    light: { family: "neutral", position: "50" },
+    dark: { family: "neutral", position: "950" },
     meaning: "Popover and dropdown background",
     contexts: ["dropdowns", "tooltips", "menus"],
     do: ["Use for floating elements"],
     never: ["Use for static content"]
   },
   "popover-foreground": {
-    light: { family: "zinc", position: "950" },
-    dark: { family: "zinc", position: "50" },
+    light: { family: "neutral", position: "950" },
+    dark: { family: "neutral", position: "50" },
     meaning: "Text in popovers",
     contexts: ["dropdown-text", "menu-text"],
     do: ["Use for popover content"],
     never: ["Use outside floating elements"]
   },
   "popover-border": {
-    light: { family: "zinc", position: "200" },
-    dark: { family: "zinc", position: "800" },
+    light: { family: "neutral", position: "200" },
+    dark: { family: "neutral", position: "800" },
     meaning: "Popover border color",
     contexts: ["popover-borders"],
     do: ["Use for popover borders"],
@@ -24365,40 +24498,40 @@ var DEFAULT_SEMANTIC_COLOR_MAPPINGS = {
   },
   // Generic surface
   surface: {
-    light: { family: "zinc", position: "50" },
-    dark: { family: "zinc", position: "900" },
+    light: { family: "neutral", position: "50" },
+    dark: { family: "neutral", position: "900" },
     meaning: "Elevated surface background",
     contexts: ["elevated-elements"],
     do: ["Use for elevated surfaces"],
     never: ["Use for page background"]
   },
   "surface-foreground": {
-    light: { family: "zinc", position: "950" },
-    dark: { family: "zinc", position: "50" },
+    light: { family: "neutral", position: "950" },
+    dark: { family: "neutral", position: "50" },
     meaning: "Text on surface backgrounds",
     contexts: ["surface-text"],
     do: ["Use for text on surfaces"],
     never: ["Use without surface background"]
   },
   "surface-hover": {
-    light: { family: "zinc", position: "100" },
-    dark: { family: "zinc", position: "800" },
+    light: { family: "neutral", position: "100" },
+    dark: { family: "neutral", position: "800" },
     meaning: "Surface hover state",
     contexts: ["surface-hover"],
     do: ["Use for surface hover states"],
     never: ["Use as default surface"]
   },
   "surface-active": {
-    light: { family: "zinc", position: "200" },
-    dark: { family: "zinc", position: "700" },
+    light: { family: "neutral", position: "200" },
+    dark: { family: "neutral", position: "700" },
     meaning: "Surface active/pressed state",
     contexts: ["surface-active"],
     do: ["Use for active surface states"],
     never: ["Use for hover states"]
   },
   "surface-border": {
-    light: { family: "zinc", position: "200" },
-    dark: { family: "zinc", position: "800" },
+    light: { family: "neutral", position: "200" },
+    dark: { family: "neutral", position: "800" },
     meaning: "Surface border color",
     contexts: ["surface-borders"],
     do: ["Use for surface borders"],
@@ -24408,8 +24541,8 @@ var DEFAULT_SEMANTIC_COLOR_MAPPINGS = {
   // PRIMARY - Main brand/action color (shadcn compatible + extended)
   // ============================================================================
   primary: {
-    light: { family: "zinc", position: "900" },
-    dark: { family: "zinc", position: "50" },
+    light: { family: "neutral", position: "900" },
+    dark: { family: "neutral", position: "50" },
     meaning: "Primary interactive elements - buttons, links, focus states",
     contexts: ["primary-buttons", "links", "active-states"],
     do: ["Use for main CTA buttons", "Use for primary links"],
@@ -24418,80 +24551,80 @@ var DEFAULT_SEMANTIC_COLOR_MAPPINGS = {
     consequence: "reversible"
   },
   "primary-foreground": {
-    light: { family: "zinc", position: "50" },
-    dark: { family: "zinc", position: "900" },
+    light: { family: "neutral", position: "50" },
+    dark: { family: "neutral", position: "900" },
     meaning: "Text on primary color backgrounds",
     contexts: ["button-text", "primary-action-text"],
     do: ["Use for text on primary buttons"],
     never: ["Use without primary background"]
   },
   "primary-hover": {
-    light: { family: "zinc", position: "800" },
-    dark: { family: "zinc", position: "200" },
+    light: { family: "neutral", position: "800" },
+    dark: { family: "neutral", position: "200" },
     meaning: "Primary hover state",
     contexts: ["primary-hover"],
     do: ["Use for primary button hover"],
     never: ["Use as default primary"]
   },
   "primary-hover-foreground": {
-    light: { family: "zinc", position: "50" },
-    dark: { family: "zinc", position: "900" },
+    light: { family: "neutral", position: "50" },
+    dark: { family: "neutral", position: "900" },
     meaning: "Text on primary hover",
     contexts: ["primary-hover-text"],
     do: ["Use for text on primary hover"],
     never: ["Use without primary-hover background"]
   },
   "primary-active": {
-    light: { family: "zinc", position: "700" },
-    dark: { family: "zinc", position: "300" },
+    light: { family: "neutral", position: "700" },
+    dark: { family: "neutral", position: "300" },
     meaning: "Primary active/pressed state",
     contexts: ["primary-active"],
     do: ["Use for primary button active state"],
     never: ["Use for hover states"]
   },
   "primary-active-foreground": {
-    light: { family: "zinc", position: "50" },
-    dark: { family: "zinc", position: "900" },
+    light: { family: "neutral", position: "50" },
+    dark: { family: "neutral", position: "900" },
     meaning: "Text on primary active",
     contexts: ["primary-active-text"],
     do: ["Use for text on primary active"],
     never: ["Use without primary-active background"]
   },
   "primary-focus": {
-    light: { family: "zinc", position: "900" },
-    dark: { family: "zinc", position: "50" },
+    light: { family: "neutral", position: "900" },
+    dark: { family: "neutral", position: "50" },
     meaning: "Primary focus state",
     contexts: ["primary-focus"],
     do: ["Use for primary focus states"],
     never: ["Use for non-focused elements"]
   },
   "primary-border": {
-    light: { family: "zinc", position: "900" },
-    dark: { family: "zinc", position: "50" },
+    light: { family: "neutral", position: "900" },
+    dark: { family: "neutral", position: "50" },
     meaning: "Primary border color",
     contexts: ["primary-borders"],
     do: ["Use for primary element borders"],
     never: ["Use for neutral borders"]
   },
   "primary-ring": {
-    light: { family: "zinc", position: "900" },
-    dark: { family: "zinc", position: "50" },
+    light: { family: "neutral", position: "900" },
+    dark: { family: "neutral", position: "50" },
     meaning: "Primary focus ring color",
     contexts: ["primary-focus-ring"],
     do: ["Use for primary element focus rings"],
     never: ["Use for decorative rings"]
   },
   "primary-subtle": {
-    light: { family: "zinc", position: "100" },
-    dark: { family: "zinc", position: "900" },
+    light: { family: "neutral", position: "100" },
+    dark: { family: "neutral", position: "900" },
     meaning: "Subtle primary background for badges/alerts",
     contexts: ["primary-badges", "primary-alerts"],
     do: ["Use for subtle primary backgrounds"],
     never: ["Use for primary buttons"]
   },
   "primary-subtle-foreground": {
-    light: { family: "zinc", position: "900" },
-    dark: { family: "zinc", position: "100" },
+    light: { family: "neutral", position: "900" },
+    dark: { family: "neutral", position: "100" },
     meaning: "Text on subtle primary backgrounds",
     contexts: ["primary-subtle-text"],
     do: ["Use for text on subtle primary"],
@@ -24501,8 +24634,8 @@ var DEFAULT_SEMANTIC_COLOR_MAPPINGS = {
   // SECONDARY - Alternative action color (shadcn compatible + extended)
   // ============================================================================
   secondary: {
-    light: { family: "zinc", position: "100" },
-    dark: { family: "zinc", position: "800" },
+    light: { family: "neutral", position: "100" },
+    dark: { family: "neutral", position: "800" },
     meaning: "Secondary interactive elements - less prominent actions",
     contexts: ["secondary-buttons", "alternative-actions"],
     do: ["Use for secondary actions", "Use when primary is too strong"],
@@ -24511,64 +24644,64 @@ var DEFAULT_SEMANTIC_COLOR_MAPPINGS = {
     consequence: "reversible"
   },
   "secondary-foreground": {
-    light: { family: "zinc", position: "900" },
-    dark: { family: "zinc", position: "50" },
+    light: { family: "neutral", position: "900" },
+    dark: { family: "neutral", position: "50" },
     meaning: "Text on secondary color backgrounds",
     contexts: ["secondary-button-text"],
     do: ["Use for text on secondary buttons"],
     never: ["Use without secondary background"]
   },
   "secondary-hover": {
-    light: { family: "zinc", position: "200" },
-    dark: { family: "zinc", position: "700" },
+    light: { family: "neutral", position: "200" },
+    dark: { family: "neutral", position: "700" },
     meaning: "Secondary hover state",
     contexts: ["secondary-hover"],
     do: ["Use for secondary hover"],
     never: ["Use as default secondary"]
   },
   "secondary-hover-foreground": {
-    light: { family: "zinc", position: "900" },
-    dark: { family: "zinc", position: "50" },
+    light: { family: "neutral", position: "900" },
+    dark: { family: "neutral", position: "50" },
     meaning: "Text on secondary hover",
     contexts: ["secondary-hover-text"],
     do: ["Use for text on secondary hover"],
     never: ["Use without secondary-hover background"]
   },
   "secondary-active": {
-    light: { family: "zinc", position: "300" },
-    dark: { family: "zinc", position: "600" },
+    light: { family: "neutral", position: "300" },
+    dark: { family: "neutral", position: "600" },
     meaning: "Secondary active/pressed state",
     contexts: ["secondary-active"],
     do: ["Use for secondary active state"],
     never: ["Use for hover states"]
   },
   "secondary-active-foreground": {
-    light: { family: "zinc", position: "900" },
-    dark: { family: "zinc", position: "50" },
+    light: { family: "neutral", position: "900" },
+    dark: { family: "neutral", position: "50" },
     meaning: "Text on secondary active",
     contexts: ["secondary-active-text"],
     do: ["Use for text on secondary active"],
     never: ["Use without secondary-active background"]
   },
   "secondary-focus": {
-    light: { family: "zinc", position: "100" },
-    dark: { family: "zinc", position: "800" },
+    light: { family: "neutral", position: "100" },
+    dark: { family: "neutral", position: "800" },
     meaning: "Secondary focus state",
     contexts: ["secondary-focus"],
     do: ["Use for secondary focus states"],
     never: ["Use for non-focused elements"]
   },
   "secondary-border": {
-    light: { family: "zinc", position: "300" },
-    dark: { family: "zinc", position: "700" },
+    light: { family: "neutral", position: "300" },
+    dark: { family: "neutral", position: "700" },
     meaning: "Secondary border color",
     contexts: ["secondary-borders"],
     do: ["Use for secondary element borders"],
     never: ["Use for primary borders"]
   },
   "secondary-ring": {
-    light: { family: "zinc", position: "400" },
-    dark: { family: "zinc", position: "500" },
+    light: { family: "neutral", position: "400" },
+    dark: { family: "neutral", position: "500" },
     meaning: "Secondary focus ring color",
     contexts: ["secondary-focus-ring"],
     do: ["Use for secondary element focus rings"],
@@ -24578,48 +24711,48 @@ var DEFAULT_SEMANTIC_COLOR_MAPPINGS = {
   // MUTED - Subdued elements (shadcn compatible + extended)
   // ============================================================================
   muted: {
-    light: { family: "zinc", position: "100" },
-    dark: { family: "zinc", position: "800" },
+    light: { family: "neutral", position: "100" },
+    dark: { family: "neutral", position: "800" },
     meaning: "Muted backgrounds for subtle emphasis",
     contexts: ["subtle-backgrounds", "inactive-tabs", "disabled-areas"],
     do: ["Use for subtle background differentiation"],
     never: ["Use for interactive elements needing visibility"]
   },
   "muted-foreground": {
-    light: { family: "zinc", position: "500" },
-    dark: { family: "zinc", position: "400" },
+    light: { family: "neutral", position: "500" },
+    dark: { family: "neutral", position: "400" },
     meaning: "Muted text for secondary information",
     contexts: ["helper-text", "placeholders", "metadata"],
     do: ["Use for secondary text", "Use for placeholders"],
     never: ["Use for primary content", "Use for important information"]
   },
   "muted-hover": {
-    light: { family: "zinc", position: "200" },
-    dark: { family: "zinc", position: "700" },
+    light: { family: "neutral", position: "200" },
+    dark: { family: "neutral", position: "700" },
     meaning: "Muted hover state",
     contexts: ["muted-hover"],
     do: ["Use for muted hover states"],
     never: ["Use as default muted"]
   },
   "muted-hover-foreground": {
-    light: { family: "zinc", position: "600" },
-    dark: { family: "zinc", position: "300" },
+    light: { family: "neutral", position: "600" },
+    dark: { family: "neutral", position: "300" },
     meaning: "Text on muted hover",
     contexts: ["muted-hover-text"],
     do: ["Use for text on muted hover"],
     never: ["Use without muted-hover background"]
   },
   "muted-active": {
-    light: { family: "zinc", position: "300" },
-    dark: { family: "zinc", position: "600" },
+    light: { family: "neutral", position: "300" },
+    dark: { family: "neutral", position: "600" },
     meaning: "Muted active state",
     contexts: ["muted-active"],
     do: ["Use for muted active states"],
     never: ["Use for hover states"]
   },
   "muted-border": {
-    light: { family: "zinc", position: "200" },
-    dark: { family: "zinc", position: "700" },
+    light: { family: "neutral", position: "200" },
+    dark: { family: "neutral", position: "700" },
     meaning: "Muted border color",
     contexts: ["muted-borders"],
     do: ["Use for muted element borders"],
@@ -24629,64 +24762,64 @@ var DEFAULT_SEMANTIC_COLOR_MAPPINGS = {
   // ACCENT - Highlight/emphasis color (shadcn compatible + extended)
   // ============================================================================
   accent: {
-    light: { family: "zinc", position: "100" },
-    dark: { family: "zinc", position: "800" },
+    light: { family: "neutral", position: "100" },
+    dark: { family: "neutral", position: "800" },
     meaning: "Accent for hover states and highlights",
     contexts: ["hover-states", "selected-items", "focus-backgrounds"],
     do: ["Use for hover backgrounds", "Use for selected states"],
     never: ["Use for primary actions"]
   },
   "accent-foreground": {
-    light: { family: "zinc", position: "900" },
-    dark: { family: "zinc", position: "50" },
+    light: { family: "neutral", position: "900" },
+    dark: { family: "neutral", position: "50" },
     meaning: "Text on accent backgrounds",
     contexts: ["hover-text", "selected-text"],
     do: ["Use for text on accent backgrounds"],
     never: ["Use without accent background"]
   },
   "accent-hover": {
-    light: { family: "zinc", position: "200" },
-    dark: { family: "zinc", position: "700" },
+    light: { family: "neutral", position: "200" },
+    dark: { family: "neutral", position: "700" },
     meaning: "Accent hover state",
     contexts: ["accent-hover"],
     do: ["Use for accent hover states"],
     never: ["Use as default accent"]
   },
   "accent-hover-foreground": {
-    light: { family: "zinc", position: "900" },
-    dark: { family: "zinc", position: "50" },
+    light: { family: "neutral", position: "900" },
+    dark: { family: "neutral", position: "50" },
     meaning: "Text on accent hover",
     contexts: ["accent-hover-text"],
     do: ["Use for text on accent hover"],
     never: ["Use without accent-hover background"]
   },
   "accent-active": {
-    light: { family: "zinc", position: "300" },
-    dark: { family: "zinc", position: "600" },
+    light: { family: "neutral", position: "300" },
+    dark: { family: "neutral", position: "600" },
     meaning: "Accent active state",
     contexts: ["accent-active"],
     do: ["Use for accent active states"],
     never: ["Use for hover states"]
   },
   "accent-active-foreground": {
-    light: { family: "zinc", position: "900" },
-    dark: { family: "zinc", position: "50" },
+    light: { family: "neutral", position: "900" },
+    dark: { family: "neutral", position: "50" },
     meaning: "Text on accent active",
     contexts: ["accent-active-text"],
     do: ["Use for text on accent active"],
     never: ["Use without accent-active background"]
   },
   "accent-border": {
-    light: { family: "zinc", position: "300" },
-    dark: { family: "zinc", position: "700" },
+    light: { family: "neutral", position: "300" },
+    dark: { family: "neutral", position: "700" },
     meaning: "Accent border color",
     contexts: ["accent-borders"],
     do: ["Use for accent element borders"],
     never: ["Use for neutral borders"]
   },
   "accent-ring": {
-    light: { family: "zinc", position: "400" },
-    dark: { family: "zinc", position: "500" },
+    light: { family: "neutral", position: "400" },
+    dark: { family: "neutral", position: "500" },
     meaning: "Accent focus ring color",
     contexts: ["accent-focus-ring"],
     do: ["Use for accent element focus rings"],
@@ -24707,8 +24840,8 @@ var DEFAULT_SEMANTIC_COLOR_MAPPINGS = {
     consequence: "destructive"
   },
   "destructive-foreground": {
-    light: { family: "zinc", position: "50" },
-    dark: { family: "zinc", position: "50" },
+    light: { family: "neutral", position: "50" },
+    dark: { family: "neutral", position: "50" },
     meaning: "Text on destructive backgrounds",
     contexts: ["delete-button-text", "error-message-text"],
     do: ["Use for text on destructive buttons"],
@@ -24723,8 +24856,8 @@ var DEFAULT_SEMANTIC_COLOR_MAPPINGS = {
     never: ["Use as default destructive"]
   },
   "destructive-hover-foreground": {
-    light: { family: "zinc", position: "50" },
-    dark: { family: "zinc", position: "950" },
+    light: { family: "neutral", position: "50" },
+    dark: { family: "neutral", position: "950" },
     meaning: "Text on destructive hover",
     contexts: ["destructive-hover-text"],
     do: ["Use for text on destructive hover"],
@@ -24739,8 +24872,8 @@ var DEFAULT_SEMANTIC_COLOR_MAPPINGS = {
     never: ["Use for hover states"]
   },
   "destructive-active-foreground": {
-    light: { family: "zinc", position: "50" },
-    dark: { family: "zinc", position: "950" },
+    light: { family: "neutral", position: "50" },
+    dark: { family: "neutral", position: "950" },
     meaning: "Text on destructive active",
     contexts: ["destructive-active-text"],
     do: ["Use for text on destructive active"],
@@ -24801,8 +24934,8 @@ var DEFAULT_SEMANTIC_COLOR_MAPPINGS = {
     consequence: "reversible"
   },
   "success-foreground": {
-    light: { family: "zinc", position: "50" },
-    dark: { family: "zinc", position: "950" },
+    light: { family: "neutral", position: "50" },
+    dark: { family: "neutral", position: "950" },
     meaning: "Text on success backgrounds",
     contexts: ["success-message-text"],
     do: ["Use for text on success backgrounds"],
@@ -24817,8 +24950,8 @@ var DEFAULT_SEMANTIC_COLOR_MAPPINGS = {
     never: ["Use as default success"]
   },
   "success-hover-foreground": {
-    light: { family: "zinc", position: "50" },
-    dark: { family: "zinc", position: "950" },
+    light: { family: "neutral", position: "50" },
+    dark: { family: "neutral", position: "950" },
     meaning: "Text on success hover",
     contexts: ["success-hover-text"],
     do: ["Use for text on success hover"],
@@ -24833,8 +24966,8 @@ var DEFAULT_SEMANTIC_COLOR_MAPPINGS = {
     never: ["Use for hover states"]
   },
   "success-active-foreground": {
-    light: { family: "zinc", position: "50" },
-    dark: { family: "zinc", position: "950" },
+    light: { family: "neutral", position: "50" },
+    dark: { family: "neutral", position: "950" },
     meaning: "Text on success active",
     contexts: ["success-active-text"],
     do: ["Use for text on success active"],
@@ -24895,8 +25028,8 @@ var DEFAULT_SEMANTIC_COLOR_MAPPINGS = {
     consequence: "significant"
   },
   "warning-foreground": {
-    light: { family: "zinc", position: "950" },
-    dark: { family: "zinc", position: "950" },
+    light: { family: "neutral", position: "950" },
+    dark: { family: "neutral", position: "950" },
     meaning: "Text on warning backgrounds",
     contexts: ["warning-message-text"],
     do: ["Use for text on warning backgrounds"],
@@ -24911,8 +25044,8 @@ var DEFAULT_SEMANTIC_COLOR_MAPPINGS = {
     never: ["Use as default warning"]
   },
   "warning-hover-foreground": {
-    light: { family: "zinc", position: "950" },
-    dark: { family: "zinc", position: "950" },
+    light: { family: "neutral", position: "950" },
+    dark: { family: "neutral", position: "950" },
     meaning: "Text on warning hover",
     contexts: ["warning-hover-text"],
     do: ["Use for text on warning hover"],
@@ -24927,8 +25060,8 @@ var DEFAULT_SEMANTIC_COLOR_MAPPINGS = {
     never: ["Use for hover states"]
   },
   "warning-active-foreground": {
-    light: { family: "zinc", position: "50" },
-    dark: { family: "zinc", position: "950" },
+    light: { family: "neutral", position: "50" },
+    dark: { family: "neutral", position: "950" },
     meaning: "Text on warning active",
     contexts: ["warning-active-text"],
     do: ["Use for text on warning active"],
@@ -24989,8 +25122,8 @@ var DEFAULT_SEMANTIC_COLOR_MAPPINGS = {
     consequence: "reversible"
   },
   "info-foreground": {
-    light: { family: "zinc", position: "50" },
-    dark: { family: "zinc", position: "50" },
+    light: { family: "neutral", position: "50" },
+    dark: { family: "neutral", position: "50" },
     meaning: "Text on info backgrounds",
     contexts: ["info-message-text"],
     do: ["Use for text on info backgrounds"],
@@ -25005,8 +25138,8 @@ var DEFAULT_SEMANTIC_COLOR_MAPPINGS = {
     never: ["Use as default info"]
   },
   "info-hover-foreground": {
-    light: { family: "zinc", position: "50" },
-    dark: { family: "zinc", position: "950" },
+    light: { family: "neutral", position: "50" },
+    dark: { family: "neutral", position: "950" },
     meaning: "Text on info hover",
     contexts: ["info-hover-text"],
     do: ["Use for text on info hover"],
@@ -25021,8 +25154,8 @@ var DEFAULT_SEMANTIC_COLOR_MAPPINGS = {
     never: ["Use for hover states"]
   },
   "info-active-foreground": {
-    light: { family: "zinc", position: "50" },
-    dark: { family: "zinc", position: "950" },
+    light: { family: "neutral", position: "50" },
+    dark: { family: "neutral", position: "950" },
     meaning: "Text on info active",
     contexts: ["info-active-text"],
     do: ["Use for text on info active"],
@@ -25082,8 +25215,8 @@ var DEFAULT_SEMANTIC_COLOR_MAPPINGS = {
     consequence: "significant"
   },
   "alert-foreground": {
-    light: { family: "zinc", position: "50" },
-    dark: { family: "zinc", position: "50" },
+    light: { family: "neutral", position: "50" },
+    dark: { family: "neutral", position: "50" },
     meaning: "Text on alert backgrounds",
     contexts: ["alert-text"],
     do: ["Use for text on alert backgrounds"],
@@ -25098,8 +25231,8 @@ var DEFAULT_SEMANTIC_COLOR_MAPPINGS = {
     never: ["Use as default alert"]
   },
   "alert-hover-foreground": {
-    light: { family: "zinc", position: "50" },
-    dark: { family: "zinc", position: "950" },
+    light: { family: "neutral", position: "50" },
+    dark: { family: "neutral", position: "950" },
     meaning: "Text on alert hover",
     contexts: ["alert-hover-text"],
     do: ["Use for text on alert hover"],
@@ -25114,8 +25247,8 @@ var DEFAULT_SEMANTIC_COLOR_MAPPINGS = {
     never: ["Use for hover states"]
   },
   "alert-active-foreground": {
-    light: { family: "zinc", position: "50" },
-    dark: { family: "zinc", position: "950" },
+    light: { family: "neutral", position: "50" },
+    dark: { family: "neutral", position: "950" },
     meaning: "Text on alert active",
     contexts: ["alert-active-text"],
     do: ["Use for text on alert active"],
@@ -25208,32 +25341,32 @@ var DEFAULT_SEMANTIC_COLOR_MAPPINGS = {
   // BORDER TOKENS (shadcn compatible + extended)
   // ============================================================================
   border: {
-    light: { family: "zinc", position: "200" },
-    dark: { family: "zinc", position: "800" },
+    light: { family: "neutral", position: "200" },
+    dark: { family: "neutral", position: "800" },
     meaning: "Default border color",
     contexts: ["dividers", "separators", "input-borders"],
     do: ["Use for subtle borders", "Use for dividers"],
     never: ["Use for emphasized borders"]
   },
   "border-hover": {
-    light: { family: "zinc", position: "300" },
-    dark: { family: "zinc", position: "700" },
+    light: { family: "neutral", position: "300" },
+    dark: { family: "neutral", position: "700" },
     meaning: "Border hover state",
     contexts: ["border-hover"],
     do: ["Use for border hover states"],
     never: ["Use as default border"]
   },
   "border-focus": {
-    light: { family: "zinc", position: "400" },
-    dark: { family: "zinc", position: "600" },
+    light: { family: "neutral", position: "400" },
+    dark: { family: "neutral", position: "600" },
     meaning: "Border focus state",
     contexts: ["border-focus"],
     do: ["Use for focused element borders"],
     never: ["Use for non-focused elements"]
   },
   "border-active": {
-    light: { family: "zinc", position: "500" },
-    dark: { family: "zinc", position: "500" },
+    light: { family: "neutral", position: "500" },
+    dark: { family: "neutral", position: "500" },
     meaning: "Border active state",
     contexts: ["border-active"],
     do: ["Use for active element borders"],
@@ -25243,56 +25376,56 @@ var DEFAULT_SEMANTIC_COLOR_MAPPINGS = {
   // INPUT TOKENS (shadcn compatible + extended for form states)
   // ============================================================================
   input: {
-    light: { family: "zinc", position: "200" },
-    dark: { family: "zinc", position: "800" },
+    light: { family: "neutral", position: "200" },
+    dark: { family: "neutral", position: "800" },
     meaning: "Input field border color",
     contexts: ["form-inputs", "text-fields", "selects"],
     do: ["Use for form field borders"],
     never: ["Use for buttons"]
   },
   "input-foreground": {
-    light: { family: "zinc", position: "950" },
-    dark: { family: "zinc", position: "50" },
+    light: { family: "neutral", position: "950" },
+    dark: { family: "neutral", position: "50" },
     meaning: "Input text color",
     contexts: ["input-text"],
     do: ["Use for input text"],
     never: ["Use for placeholders"]
   },
   "input-hover": {
-    light: { family: "zinc", position: "300" },
-    dark: { family: "zinc", position: "700" },
+    light: { family: "neutral", position: "300" },
+    dark: { family: "neutral", position: "700" },
     meaning: "Input hover state",
     contexts: ["input-hover"],
     do: ["Use for input hover states"],
     never: ["Use as default input"]
   },
   "input-focus": {
-    light: { family: "zinc", position: "400" },
-    dark: { family: "zinc", position: "600" },
+    light: { family: "neutral", position: "400" },
+    dark: { family: "neutral", position: "600" },
     meaning: "Input focus state",
     contexts: ["input-focus"],
     do: ["Use for input focus states"],
     never: ["Use for non-focused inputs"]
   },
   "input-disabled": {
-    light: { family: "zinc", position: "100" },
-    dark: { family: "zinc", position: "900" },
+    light: { family: "neutral", position: "100" },
+    dark: { family: "neutral", position: "900" },
     meaning: "Disabled input background",
     contexts: ["disabled-inputs"],
     do: ["Use for disabled input backgrounds"],
     never: ["Use for enabled inputs"]
   },
   "input-disabled-foreground": {
-    light: { family: "zinc", position: "400" },
-    dark: { family: "zinc", position: "600" },
+    light: { family: "neutral", position: "400" },
+    dark: { family: "neutral", position: "600" },
     meaning: "Disabled input text color",
     contexts: ["disabled-input-text"],
     do: ["Use for disabled input text"],
     never: ["Use for enabled input text"]
   },
   "input-placeholder": {
-    light: { family: "zinc", position: "500" },
-    dark: { family: "zinc", position: "400" },
+    light: { family: "neutral", position: "500" },
+    dark: { family: "neutral", position: "400" },
     meaning: "Placeholder text color",
     contexts: ["placeholders"],
     do: ["Use for placeholder text"],
@@ -25334,24 +25467,24 @@ var DEFAULT_SEMANTIC_COLOR_MAPPINGS = {
   // RING/FOCUS TOKENS (shadcn compatible + extended for a11y)
   // ============================================================================
   ring: {
-    light: { family: "zinc", position: "950" },
-    dark: { family: "zinc", position: "300" },
+    light: { family: "neutral", position: "950" },
+    dark: { family: "neutral", position: "300" },
     meaning: "Focus ring color",
     contexts: ["focus-states", "keyboard-navigation"],
     do: ["Use for focus indicators", "Ensure high contrast"],
     never: ["Use for decorative elements"]
   },
   "ring-offset": {
-    light: { family: "zinc", position: "50" },
-    dark: { family: "zinc", position: "950" },
+    light: { family: "neutral", position: "50" },
+    dark: { family: "neutral", position: "950" },
     meaning: "Focus ring offset color",
     contexts: ["focus-ring-offset"],
     do: ["Use for focus ring offset"],
     never: ["Use as primary color"]
   },
   "ring-primary": {
-    light: { family: "zinc", position: "900" },
-    dark: { family: "zinc", position: "50" },
+    light: { family: "neutral", position: "900" },
+    dark: { family: "neutral", position: "50" },
     meaning: "Primary focus ring",
     contexts: ["primary-focus-ring"],
     do: ["Use for primary element focus rings"],
@@ -25444,8 +25577,8 @@ var DEFAULT_SEMANTIC_COLOR_MAPPINGS = {
     never: ["Use for other highlights"]
   },
   "selection-foreground": {
-    light: { family: "zinc", position: "950" },
-    dark: { family: "zinc", position: "50" },
+    light: { family: "neutral", position: "950" },
+    dark: { family: "neutral", position: "50" },
     meaning: "Text selection foreground",
     contexts: ["text-selection-foreground"],
     do: ["Use for ::selection text color"],
@@ -25455,168 +25588,168 @@ var DEFAULT_SEMANTIC_COLOR_MAPPINGS = {
   // SIDEBAR TOKENS (shadcn compatible + extended)
   // ============================================================================
   sidebar: {
-    light: { family: "zinc", position: "50" },
-    dark: { family: "zinc", position: "950" },
+    light: { family: "neutral", position: "50" },
+    dark: { family: "neutral", position: "950" },
     meaning: "Sidebar background",
     contexts: ["navigation-sidebar", "side-panels"],
     do: ["Use for sidebar backgrounds"],
     never: ["Use for main content areas"]
   },
   "sidebar-foreground": {
-    light: { family: "zinc", position: "950" },
-    dark: { family: "zinc", position: "50" },
+    light: { family: "neutral", position: "950" },
+    dark: { family: "neutral", position: "50" },
     meaning: "Sidebar text color",
     contexts: ["sidebar-text", "nav-items"],
     do: ["Use for sidebar content"],
     never: ["Use outside sidebar context"]
   },
   "sidebar-muted": {
-    light: { family: "zinc", position: "500" },
-    dark: { family: "zinc", position: "400" },
+    light: { family: "neutral", position: "500" },
+    dark: { family: "neutral", position: "400" },
     meaning: "Sidebar muted text",
     contexts: ["sidebar-secondary-text"],
     do: ["Use for secondary sidebar text"],
     never: ["Use for primary sidebar text"]
   },
   "sidebar-primary": {
-    light: { family: "zinc", position: "900" },
-    dark: { family: "zinc", position: "50" },
+    light: { family: "neutral", position: "900" },
+    dark: { family: "neutral", position: "50" },
     meaning: "Sidebar primary accent",
     contexts: ["active-nav-item", "selected-sidebar-item"],
     do: ["Use for active sidebar items"],
     never: ["Use for inactive items"]
   },
   "sidebar-primary-foreground": {
-    light: { family: "zinc", position: "50" },
-    dark: { family: "zinc", position: "900" },
+    light: { family: "neutral", position: "50" },
+    dark: { family: "neutral", position: "900" },
     meaning: "Text on sidebar primary",
     contexts: ["active-nav-text"],
     do: ["Use for active nav item text"],
     never: ["Use without sidebar-primary background"]
   },
   "sidebar-primary-hover": {
-    light: { family: "zinc", position: "800" },
-    dark: { family: "zinc", position: "200" },
+    light: { family: "neutral", position: "800" },
+    dark: { family: "neutral", position: "200" },
     meaning: "Sidebar primary hover",
     contexts: ["sidebar-primary-hover"],
     do: ["Use for sidebar primary hover"],
     never: ["Use as default sidebar primary"]
   },
   "sidebar-primary-active": {
-    light: { family: "zinc", position: "700" },
-    dark: { family: "zinc", position: "300" },
+    light: { family: "neutral", position: "700" },
+    dark: { family: "neutral", position: "300" },
     meaning: "Sidebar primary active",
     contexts: ["sidebar-primary-active"],
     do: ["Use for sidebar primary active state"],
     never: ["Use for hover states"]
   },
   "sidebar-accent": {
-    light: { family: "zinc", position: "100" },
-    dark: { family: "zinc", position: "800" },
+    light: { family: "neutral", position: "100" },
+    dark: { family: "neutral", position: "800" },
     meaning: "Sidebar hover/accent state",
     contexts: ["sidebar-hover", "sidebar-selected"],
     do: ["Use for sidebar hover states"],
     never: ["Use for active state"]
   },
   "sidebar-accent-foreground": {
-    light: { family: "zinc", position: "900" },
-    dark: { family: "zinc", position: "50" },
+    light: { family: "neutral", position: "900" },
+    dark: { family: "neutral", position: "50" },
     meaning: "Text on sidebar accent",
     contexts: ["sidebar-hover-text"],
     do: ["Use for hovered sidebar text"],
     never: ["Use without sidebar-accent background"]
   },
   "sidebar-accent-hover": {
-    light: { family: "zinc", position: "200" },
-    dark: { family: "zinc", position: "700" },
+    light: { family: "neutral", position: "200" },
+    dark: { family: "neutral", position: "700" },
     meaning: "Sidebar accent hover",
     contexts: ["sidebar-accent-hover"],
     do: ["Use for sidebar accent hover"],
     never: ["Use as default sidebar accent"]
   },
   "sidebar-accent-active": {
-    light: { family: "zinc", position: "300" },
-    dark: { family: "zinc", position: "600" },
+    light: { family: "neutral", position: "300" },
+    dark: { family: "neutral", position: "600" },
     meaning: "Sidebar accent active",
     contexts: ["sidebar-accent-active"],
     do: ["Use for sidebar accent active state"],
     never: ["Use for hover states"]
   },
   "sidebar-item": {
-    light: { family: "zinc", position: "50" },
-    dark: { family: "zinc", position: "950" },
+    light: { family: "neutral", position: "50" },
+    dark: { family: "neutral", position: "950" },
     meaning: "Sidebar item background",
     contexts: ["sidebar-items"],
     do: ["Use for sidebar item backgrounds"],
     never: ["Use for active items"]
   },
   "sidebar-item-foreground": {
-    light: { family: "zinc", position: "700" },
-    dark: { family: "zinc", position: "300" },
+    light: { family: "neutral", position: "700" },
+    dark: { family: "neutral", position: "300" },
     meaning: "Sidebar item text",
     contexts: ["sidebar-item-text"],
     do: ["Use for sidebar item text"],
     never: ["Use for active item text"]
   },
   "sidebar-item-hover": {
-    light: { family: "zinc", position: "100" },
-    dark: { family: "zinc", position: "900" },
+    light: { family: "neutral", position: "100" },
+    dark: { family: "neutral", position: "900" },
     meaning: "Sidebar item hover",
     contexts: ["sidebar-item-hover"],
     do: ["Use for sidebar item hover"],
     never: ["Use as default item background"]
   },
   "sidebar-item-hover-foreground": {
-    light: { family: "zinc", position: "900" },
-    dark: { family: "zinc", position: "50" },
+    light: { family: "neutral", position: "900" },
+    dark: { family: "neutral", position: "50" },
     meaning: "Sidebar item hover text",
     contexts: ["sidebar-item-hover-text"],
     do: ["Use for sidebar item hover text"],
     never: ["Use without hover background"]
   },
   "sidebar-item-active": {
-    light: { family: "zinc", position: "200" },
-    dark: { family: "zinc", position: "800" },
+    light: { family: "neutral", position: "200" },
+    dark: { family: "neutral", position: "800" },
     meaning: "Sidebar item active",
     contexts: ["sidebar-item-active"],
     do: ["Use for sidebar item active state"],
     never: ["Use for hover states"]
   },
   "sidebar-item-active-foreground": {
-    light: { family: "zinc", position: "950" },
-    dark: { family: "zinc", position: "50" },
+    light: { family: "neutral", position: "950" },
+    dark: { family: "neutral", position: "50" },
     meaning: "Sidebar item active text",
     contexts: ["sidebar-item-active-text"],
     do: ["Use for sidebar item active text"],
     never: ["Use without active background"]
   },
   "sidebar-item-selected": {
-    light: { family: "zinc", position: "100" },
-    dark: { family: "zinc", position: "800" },
+    light: { family: "neutral", position: "100" },
+    dark: { family: "neutral", position: "800" },
     meaning: "Sidebar selected item",
     contexts: ["sidebar-selected-item"],
     do: ["Use for selected sidebar items"],
     never: ["Use for unselected items"]
   },
   "sidebar-item-selected-foreground": {
-    light: { family: "zinc", position: "950" },
-    dark: { family: "zinc", position: "50" },
+    light: { family: "neutral", position: "950" },
+    dark: { family: "neutral", position: "50" },
     meaning: "Sidebar selected item text",
     contexts: ["sidebar-selected-item-text"],
     do: ["Use for selected item text"],
     never: ["Use without selected background"]
   },
   "sidebar-border": {
-    light: { family: "zinc", position: "200" },
-    dark: { family: "zinc", position: "800" },
+    light: { family: "neutral", position: "200" },
+    dark: { family: "neutral", position: "800" },
     meaning: "Sidebar border/divider color",
     contexts: ["sidebar-dividers", "nav-section-borders"],
     do: ["Use for sidebar dividers"],
     never: ["Use for main content borders"]
   },
   "sidebar-ring": {
-    light: { family: "zinc", position: "950" },
-    dark: { family: "zinc", position: "300" },
+    light: { family: "neutral", position: "950" },
+    dark: { family: "neutral", position: "300" },
     meaning: "Sidebar focus ring",
     contexts: ["sidebar-focus-states"],
     do: ["Use for sidebar focus indicators"],
@@ -25626,80 +25759,80 @@ var DEFAULT_SEMANTIC_COLOR_MAPPINGS = {
   // NAVIGATION TOKENS
   // ============================================================================
   nav: {
-    light: { family: "zinc", position: "50" },
-    dark: { family: "zinc", position: "950" },
+    light: { family: "neutral", position: "50" },
+    dark: { family: "neutral", position: "950" },
     meaning: "Navigation background",
     contexts: ["navbars", "breadcrumbs", "tabs"],
     do: ["Use for navigation backgrounds"],
     never: ["Use for content areas"]
   },
   "nav-foreground": {
-    light: { family: "zinc", position: "700" },
-    dark: { family: "zinc", position: "300" },
+    light: { family: "neutral", position: "700" },
+    dark: { family: "neutral", position: "300" },
     meaning: "Navigation text",
     contexts: ["nav-links", "nav-items"],
     do: ["Use for navigation text"],
     never: ["Use for active nav text"]
   },
   "nav-hover": {
-    light: { family: "zinc", position: "100" },
-    dark: { family: "zinc", position: "900" },
+    light: { family: "neutral", position: "100" },
+    dark: { family: "neutral", position: "900" },
     meaning: "Navigation hover",
     contexts: ["nav-hover"],
     do: ["Use for nav hover states"],
     never: ["Use as default nav background"]
   },
   "nav-hover-foreground": {
-    light: { family: "zinc", position: "900" },
-    dark: { family: "zinc", position: "50" },
+    light: { family: "neutral", position: "900" },
+    dark: { family: "neutral", position: "50" },
     meaning: "Navigation hover text",
     contexts: ["nav-hover-text"],
     do: ["Use for nav hover text"],
     never: ["Use without hover background"]
   },
   "nav-active": {
-    light: { family: "zinc", position: "200" },
-    dark: { family: "zinc", position: "800" },
+    light: { family: "neutral", position: "200" },
+    dark: { family: "neutral", position: "800" },
     meaning: "Navigation active",
     contexts: ["nav-active"],
     do: ["Use for nav active states"],
     never: ["Use for hover states"]
   },
   "nav-active-foreground": {
-    light: { family: "zinc", position: "950" },
-    dark: { family: "zinc", position: "50" },
+    light: { family: "neutral", position: "950" },
+    dark: { family: "neutral", position: "50" },
     meaning: "Navigation active text",
     contexts: ["nav-active-text"],
     do: ["Use for nav active text"],
     never: ["Use without active background"]
   },
   "nav-selected": {
-    light: { family: "zinc", position: "900" },
-    dark: { family: "zinc", position: "50" },
+    light: { family: "neutral", position: "900" },
+    dark: { family: "neutral", position: "50" },
     meaning: "Navigation selected",
     contexts: ["nav-selected"],
     do: ["Use for selected nav items"],
     never: ["Use for unselected items"]
   },
   "nav-selected-foreground": {
-    light: { family: "zinc", position: "50" },
-    dark: { family: "zinc", position: "900" },
+    light: { family: "neutral", position: "50" },
+    dark: { family: "neutral", position: "900" },
     meaning: "Navigation selected text",
     contexts: ["nav-selected-text"],
     do: ["Use for selected nav text"],
     never: ["Use without selected background"]
   },
   "nav-disabled": {
-    light: { family: "zinc", position: "200" },
-    dark: { family: "zinc", position: "800" },
+    light: { family: "neutral", position: "200" },
+    dark: { family: "neutral", position: "800" },
     meaning: "Navigation disabled",
     contexts: ["nav-disabled"],
     do: ["Use for disabled nav items"],
     never: ["Use for enabled items"]
   },
   "nav-disabled-foreground": {
-    light: { family: "zinc", position: "400" },
-    dark: { family: "zinc", position: "600" },
+    light: { family: "neutral", position: "400" },
+    dark: { family: "neutral", position: "600" },
     meaning: "Navigation disabled text",
     contexts: ["nav-disabled-text"],
     do: ["Use for disabled nav text"],
@@ -25709,64 +25842,64 @@ var DEFAULT_SEMANTIC_COLOR_MAPPINGS = {
   // TABLE TOKENS
   // ============================================================================
   table: {
-    light: { family: "zinc", position: "50" },
-    dark: { family: "zinc", position: "950" },
+    light: { family: "neutral", position: "50" },
+    dark: { family: "neutral", position: "950" },
     meaning: "Table background",
     contexts: ["data-tables"],
     do: ["Use for table backgrounds"],
     never: ["Use for content areas"]
   },
   "table-foreground": {
-    light: { family: "zinc", position: "950" },
-    dark: { family: "zinc", position: "50" },
+    light: { family: "neutral", position: "950" },
+    dark: { family: "neutral", position: "50" },
     meaning: "Table text",
     contexts: ["table-text"],
     do: ["Use for table text"],
     never: ["Use without table background"]
   },
   "table-header": {
-    light: { family: "zinc", position: "100" },
-    dark: { family: "zinc", position: "900" },
+    light: { family: "neutral", position: "100" },
+    dark: { family: "neutral", position: "900" },
     meaning: "Table header background",
     contexts: ["table-headers"],
     do: ["Use for table header backgrounds"],
     never: ["Use for table body"]
   },
   "table-header-foreground": {
-    light: { family: "zinc", position: "950" },
-    dark: { family: "zinc", position: "50" },
+    light: { family: "neutral", position: "950" },
+    dark: { family: "neutral", position: "50" },
     meaning: "Table header text",
     contexts: ["table-header-text"],
     do: ["Use for table header text"],
     never: ["Use for body text"]
   },
   "table-row-hover": {
-    light: { family: "zinc", position: "50" },
-    dark: { family: "zinc", position: "900" },
+    light: { family: "neutral", position: "50" },
+    dark: { family: "neutral", position: "900" },
     meaning: "Table row hover",
     contexts: ["table-row-hover"],
     do: ["Use for table row hover"],
     never: ["Use as default row background"]
   },
   "table-row-selected": {
-    light: { family: "zinc", position: "100" },
-    dark: { family: "zinc", position: "800" },
+    light: { family: "neutral", position: "100" },
+    dark: { family: "neutral", position: "800" },
     meaning: "Table row selected",
     contexts: ["table-row-selected"],
     do: ["Use for selected table rows"],
     never: ["Use for unselected rows"]
   },
   "table-row-selected-foreground": {
-    light: { family: "zinc", position: "950" },
-    dark: { family: "zinc", position: "50" },
+    light: { family: "neutral", position: "950" },
+    dark: { family: "neutral", position: "50" },
     meaning: "Table row selected text",
     contexts: ["table-row-selected-text"],
     do: ["Use for selected row text"],
     never: ["Use without selected background"]
   },
   "table-border": {
-    light: { family: "zinc", position: "200" },
-    dark: { family: "zinc", position: "800" },
+    light: { family: "neutral", position: "200" },
+    dark: { family: "neutral", position: "800" },
     meaning: "Table border",
     contexts: ["table-borders"],
     do: ["Use for table borders"],
@@ -25776,16 +25909,16 @@ var DEFAULT_SEMANTIC_COLOR_MAPPINGS = {
   // TOOLTIP TOKENS
   // ============================================================================
   tooltip: {
-    light: { family: "zinc", position: "900" },
-    dark: { family: "zinc", position: "50" },
+    light: { family: "neutral", position: "900" },
+    dark: { family: "neutral", position: "50" },
     meaning: "Tooltip background",
     contexts: ["tooltips"],
     do: ["Use for tooltip backgrounds"],
     never: ["Use for content areas"]
   },
   "tooltip-foreground": {
-    light: { family: "zinc", position: "50" },
-    dark: { family: "zinc", position: "900" },
+    light: { family: "neutral", position: "50" },
+    dark: { family: "neutral", position: "900" },
     meaning: "Tooltip text",
     contexts: ["tooltip-text"],
     do: ["Use for tooltip text"],
@@ -25795,16 +25928,16 @@ var DEFAULT_SEMANTIC_COLOR_MAPPINGS = {
   // OVERLAY TOKENS
   // ============================================================================
   overlay: {
-    light: { family: "zinc", position: "950" },
-    dark: { family: "zinc", position: "950" },
+    light: { family: "neutral", position: "950" },
+    dark: { family: "neutral", position: "950" },
     meaning: "Overlay background",
     contexts: ["modals", "dialogs", "sheets"],
     do: ["Use for modal backdrops"],
     never: ["Use for content backgrounds"]
   },
   "overlay-foreground": {
-    light: { family: "zinc", position: "50" },
-    dark: { family: "zinc", position: "50" },
+    light: { family: "neutral", position: "50" },
+    dark: { family: "neutral", position: "50" },
     meaning: "Overlay text",
     contexts: ["overlay-text"],
     do: ["Use for text on overlays"],
@@ -25814,16 +25947,16 @@ var DEFAULT_SEMANTIC_COLOR_MAPPINGS = {
   // SKELETON/LOADING TOKENS
   // ============================================================================
   skeleton: {
-    light: { family: "zinc", position: "200" },
-    dark: { family: "zinc", position: "800" },
+    light: { family: "neutral", position: "200" },
+    dark: { family: "neutral", position: "800" },
     meaning: "Skeleton loader background",
     contexts: ["loading-states", "skeletons"],
     do: ["Use for skeleton backgrounds"],
     never: ["Use for content backgrounds"]
   },
   "skeleton-highlight": {
-    light: { family: "zinc", position: "300" },
-    dark: { family: "zinc", position: "700" },
+    light: { family: "neutral", position: "300" },
+    dark: { family: "neutral", position: "700" },
     meaning: "Skeleton loader highlight",
     contexts: ["skeleton-animation"],
     do: ["Use for skeleton animation highlight"],
@@ -25876,24 +26009,24 @@ var DEFAULT_SEMANTIC_COLOR_MAPPINGS = {
   // SCROLLBAR TOKENS
   // ============================================================================
   scrollbar: {
-    light: { family: "zinc", position: "300" },
-    dark: { family: "zinc", position: "700" },
+    light: { family: "neutral", position: "300" },
+    dark: { family: "neutral", position: "700" },
     meaning: "Scrollbar thumb color",
     contexts: ["scrollbars"],
     do: ["Use for scrollbar thumbs"],
     never: ["Use for content elements"]
   },
   "scrollbar-hover": {
-    light: { family: "zinc", position: "400" },
-    dark: { family: "zinc", position: "600" },
+    light: { family: "neutral", position: "400" },
+    dark: { family: "neutral", position: "600" },
     meaning: "Scrollbar thumb hover",
     contexts: ["scrollbar-hover"],
     do: ["Use for scrollbar thumb hover"],
     never: ["Use as default scrollbar color"]
   },
   "scrollbar-track": {
-    light: { family: "zinc", position: "100" },
-    dark: { family: "zinc", position: "900" },
+    light: { family: "neutral", position: "100" },
+    dark: { family: "neutral", position: "900" },
     meaning: "Scrollbar track background",
     contexts: ["scrollbar-tracks"],
     do: ["Use for scrollbar track backgrounds"],
@@ -25903,24 +26036,24 @@ var DEFAULT_SEMANTIC_COLOR_MAPPINGS = {
   // CODE/SYNTAX TOKENS
   // ============================================================================
   code: {
-    light: { family: "zinc", position: "100" },
-    dark: { family: "zinc", position: "900" },
+    light: { family: "neutral", position: "100" },
+    dark: { family: "neutral", position: "900" },
     meaning: "Code block background",
     contexts: ["code-blocks", "inline-code"],
     do: ["Use for code backgrounds"],
     never: ["Use for regular text"]
   },
   "code-foreground": {
-    light: { family: "zinc", position: "900" },
-    dark: { family: "zinc", position: "100" },
+    light: { family: "neutral", position: "900" },
+    dark: { family: "neutral", position: "100" },
     meaning: "Code text color",
     contexts: ["code-text"],
     do: ["Use for code text"],
     never: ["Use without code background"]
   },
   "code-border": {
-    light: { family: "zinc", position: "200" },
-    dark: { family: "zinc", position: "800" },
+    light: { family: "neutral", position: "200" },
+    dark: { family: "neutral", position: "800" },
     meaning: "Code block border",
     contexts: ["code-borders"],
     do: ["Use for code block borders"],
@@ -25930,24 +26063,24 @@ var DEFAULT_SEMANTIC_COLOR_MAPPINGS = {
   // BADGE TOKENS
   // ============================================================================
   badge: {
-    light: { family: "zinc", position: "100" },
-    dark: { family: "zinc", position: "800" },
+    light: { family: "neutral", position: "100" },
+    dark: { family: "neutral", position: "800" },
     meaning: "Badge background",
     contexts: ["badges", "labels"],
     do: ["Use for badge backgrounds"],
     never: ["Use for buttons"]
   },
   "badge-foreground": {
-    light: { family: "zinc", position: "900" },
-    dark: { family: "zinc", position: "100" },
+    light: { family: "neutral", position: "900" },
+    dark: { family: "neutral", position: "100" },
     meaning: "Badge text color",
     contexts: ["badge-text"],
     do: ["Use for badge text"],
     never: ["Use without badge background"]
   },
   "badge-border": {
-    light: { family: "zinc", position: "200" },
-    dark: { family: "zinc", position: "700" },
+    light: { family: "neutral", position: "200" },
+    dark: { family: "neutral", position: "700" },
     meaning: "Badge border",
     contexts: ["badge-borders"],
     do: ["Use for badge borders"],
@@ -25957,16 +26090,16 @@ var DEFAULT_SEMANTIC_COLOR_MAPPINGS = {
   // AVATAR TOKENS
   // ============================================================================
   avatar: {
-    light: { family: "zinc", position: "200" },
-    dark: { family: "zinc", position: "800" },
+    light: { family: "neutral", position: "200" },
+    dark: { family: "neutral", position: "800" },
     meaning: "Avatar fallback background",
     contexts: ["avatars", "fallback-images"],
     do: ["Use for avatar fallback backgrounds"],
     never: ["Use for content backgrounds"]
   },
   "avatar-foreground": {
-    light: { family: "zinc", position: "600" },
-    dark: { family: "zinc", position: "400" },
+    light: { family: "neutral", position: "600" },
+    dark: { family: "neutral", position: "400" },
     meaning: "Avatar fallback text/icon color",
     contexts: ["avatar-initials", "avatar-icons"],
     do: ["Use for avatar initials or icons"],
@@ -27376,12 +27509,12 @@ function derivationParent(derivation, suffix = "") {
       return `${derivation.against}${suffix}`;
   }
 }
-function deriveDarkBinding(derivation) {
+function deriveDarkBinding(derivation, parentName) {
   switch (derivation.kind) {
     case "scale":
       return {
         plugin: "invert",
-        input: { familyName: derivation.family, basePosition: derivation.scalePosition }
+        input: { fromToken: parentName }
       };
     case "state":
       return {
@@ -27406,7 +27539,7 @@ function generateSemanticTokens(_config) {
     const binding = derivationToBinding(derivation);
     const parent = derivationParent(derivation);
     const darkName = `${name}--dark`;
-    const darkBinding = deriveDarkBinding(derivation);
+    const darkBinding = deriveDarkBinding(derivation, name);
     const darkParent = derivationParent(derivation, "--dark");
     const dependsOn = [parent, darkName];
     tokens.push({
@@ -28881,6 +29014,33 @@ function readEnvelopes(dir) {
 }
 
 // ../design-tokens/src/plugin.ts
+function resolveFamily(familyName, get3) {
+  let resolved = get3(familyName);
+  let name = familyName;
+  if (resolved && typeof resolved === "object" && "family" in resolved && "position" in resolved) {
+    name = resolved.family;
+    resolved = get3(name);
+  }
+  if (!resolved || typeof resolved !== "object" || !("scale" in resolved)) return null;
+  return { family: resolved, familyName: name };
+}
+function resolveParent(tokenName, get3) {
+  const raw = get3(tokenName);
+  if (!raw || typeof raw !== "object" || !("family" in raw) || !("position" in raw)) return null;
+  const ref = raw;
+  const positionIndex = POSITION_TO_INDEX[ref.position];
+  if (positionIndex === void 0) return null;
+  const result = resolveFamily(ref.family, get3);
+  if (!result) return null;
+  return { ref, positionIndex, ...result };
+}
+function requireSemanticParent(tokenName, get3, pluginName) {
+  const resolved = resolveParent(tokenName, get3);
+  if (!resolved) {
+    throw new Error(`${pluginName} plugin: "${tokenName}" could not resolve`);
+  }
+  return { sem: semanticFor(resolved.family, { name: resolved.familyName }), resolved };
+}
 function definePlugin(spec) {
   return {
     name: spec.name,
@@ -28933,132 +29093,32 @@ var ContrastInputSchema = external_exports.object({
   against: external_exports.string(),
   level: external_exports.enum(["AA", "AAA"]).default("AAA")
 });
-function partnerForBase(pairs, basePosition) {
-  if (!pairs) return void 0;
-  for (const [p1, p2] of pairs) {
-    if (p1 === basePosition) return p2;
-    if (p2 === basePosition) return p1;
-  }
-  return void 0;
-}
-function nearestPartner(pairs, basePosition) {
-  if (!pairs || pairs.length === 0) return void 0;
-  const anchors = /* @__PURE__ */ new Set();
-  for (const pair of pairs) {
-    for (const position of pair) anchors.add(position);
-  }
-  if (anchors.size === 0) return void 0;
-  let nearest = -1;
-  let bestDistance = Number.POSITIVE_INFINITY;
-  for (const anchor of anchors) {
-    const distance2 = Math.abs(anchor - basePosition);
-    if (distance2 < bestDistance) {
-      bestDistance = distance2;
-      nearest = anchor;
-    }
-  }
-  if (nearest === -1) return void 0;
-  return partnerForBase(pairs, nearest);
-}
-function requireScalePosition(index, label) {
-  const position = SCALE_POSITIONS[index];
-  if (!position) {
-    throw new Error(`contrast plugin: invalid scale index ${index} (${label})`);
-  }
-  return position;
-}
-function isPositionString(value) {
-  return typeof value === "string";
-}
-function resolveBasePosition(position) {
-  const map2 = {
-    "50": 0,
-    "100": 1,
-    "200": 2,
-    "300": 3,
-    "400": 4,
-    "500": 5,
-    "600": 6,
-    "700": 7,
-    "800": 8,
-    "900": 9,
-    "950": 10
-  };
-  const index = map2[position];
-  if (index === void 0) {
-    throw new Error(`contrast plugin: unknown scale position "${position}"`);
-  }
-  return index;
-}
 var contrastPlugin = definePlugin({
   name: "contrast",
   inputSchema: ContrastInputSchema,
   outputSchema: ColorReferenceSchema,
   dependsOn: (input2) => [input2.against],
   transform: (input2, get3) => {
-    const parent = get3(input2.against);
-    if (!parent || typeof parent !== "object" || !("family" in parent) || !("position" in parent)) {
-      throw new Error(
-        `contrast plugin: parent token "${input2.against}" did not resolve to a ColorReference`
-      );
-    }
-    const parentRef = parent;
-    if (!isPositionString(parentRef.position)) {
-      throw new Error(
-        `contrast plugin: parent token "${input2.against}" position is not a scale string`
-      );
-    }
-    const basePosition = resolveBasePosition(parentRef.position);
-    const family = get3(parentRef.family);
-    if (!family) {
-      throw new Error(
-        `contrast plugin: family "${parentRef.family}" (from "${input2.against}") not in registry`
-      );
-    }
-    if (family.foregroundReferences?.auto) {
-      const ref = family.foregroundReferences.auto;
-      return { family: ref.family, position: ref.position };
-    }
-    if (family.accessibility) {
-      const aaaPartner = partnerForBase(family.accessibility.wcagAAA?.normal, basePosition) ?? nearestPartner(family.accessibility.wcagAAA?.normal, basePosition);
-      const aaPartner = partnerForBase(family.accessibility.wcagAA?.normal, basePosition) ?? nearestPartner(family.accessibility.wcagAA?.normal, basePosition);
-      const partner = input2.level === "AAA" ? aaaPartner ?? aaPartner : aaPartner;
-      if (partner !== void 0) {
-        return {
-          family: parentRef.family,
-          position: requireScalePosition(partner, `${parentRef.family} pair`)
-        };
-      }
-    }
-    throw new Error(
-      `contrast plugin: family "${parentRef.family}" has no foregroundReferences and no accessibility WCAG pair partner for position ${parentRef.position} (against ${input2.against})`
-    );
+    const { sem, resolved } = requireSemanticParent(input2.against, get3, "contrast");
+    const pair = sem.pair({ use: "foreground", from: resolved.ref.position, level: input2.level });
+    return { family: pair.to.family, position: pair.to.position };
   }
 });
 
 // ../design-tokens/src/plugins/invert.ts
 var InvertInputSchema = external_exports.object({
-  familyName: external_exports.string(),
-  basePosition: external_exports.number().int().min(0).max(10)
+  fromToken: external_exports.string()
 });
 var invertPlugin = definePlugin({
   name: "invert",
   inputSchema: InvertInputSchema,
   outputSchema: ColorReferenceSchema,
-  dependsOn: (input2) => [input2.familyName],
+  dependsOn: (input2) => [input2.fromToken],
   transform: (input2, get3) => {
-    const family = get3(input2.familyName);
-    if (!family) {
-      throw new Error(`invert plugin: family "${input2.familyName}" not found in registry`);
-    }
-    const darkIndex = findDarkCounterpartIndex(input2.basePosition, family);
-    const darkPosition = SCALE_POSITIONS[darkIndex];
-    if (!darkPosition) {
-      throw new Error(
-        `invert plugin: invalid dark index ${darkIndex} for base position ${input2.basePosition}`
-      );
-    }
-    return { family: input2.familyName, position: darkPosition };
+    const { sem, resolved } = requireSemanticParent(input2.fromToken, get3, "invert");
+    const lightPair = sem.pair({ use: "foreground", from: resolved.ref.position });
+    const darkPair = sem.invert(lightPair);
+    return { family: resolved.familyName, position: darkPair.from.position };
   }
 });
 
@@ -29073,15 +29133,15 @@ var scalePlugin = definePlugin({
   outputSchema: ColorReferenceSchema,
   dependsOn: (input2) => [input2.familyName],
   transform: (input2, get3) => {
-    const family = get3(input2.familyName);
-    if (!family) {
+    const result = resolveFamily(input2.familyName, get3);
+    if (!result) {
       throw new Error(`scale plugin: family "${input2.familyName}" not found in registry`);
     }
     const position = SCALE_POSITIONS[input2.scalePosition];
     if (position === void 0) {
       throw new Error(`scale plugin: invalid position index ${input2.scalePosition}`);
     }
-    return { family: input2.familyName, position };
+    return { family: result.familyName, position };
   }
 });
 
@@ -29091,115 +29151,15 @@ var StateInputSchema = external_exports.object({
   from: external_exports.string(),
   stateType: StateTypeSchema
 });
-var POSITION_TO_INDEX3 = {
-  "50": 0,
-  "100": 1,
-  "200": 2,
-  "300": 3,
-  "400": 4,
-  "500": 5,
-  "600": 6,
-  "700": 7,
-  "800": 8,
-  "900": 9,
-  "950": 10
-};
-var STEP_BY_STATE = {
-  hover: (rank) => rank + 1,
-  active: (rank) => rank + 2,
-  focus: (rank) => rank + 1,
-  disabled: (_rank, ladder) => closestRankToMidpoint(ladder)
-};
-function closestRankToMidpoint(ladder) {
-  let bestRank = 0;
-  let bestDistance = Number.POSITIVE_INFINITY;
-  for (let r = 0; r < ladder.length; r++) {
-    const position = ladder[r];
-    if (position === void 0) continue;
-    const distance2 = Math.abs(position - 5);
-    if (distance2 < bestDistance) {
-      bestDistance = distance2;
-      bestRank = r;
-    }
-  }
-  return bestRank;
-}
-function nearestRankOnLadder(ladder, position) {
-  let bestRank = 0;
-  let bestDistance = Number.POSITIVE_INFINITY;
-  for (let r = 0; r < ladder.length; r++) {
-    const candidate = ladder[r];
-    if (candidate === void 0) continue;
-    const distance2 = Math.abs(candidate - position);
-    if (distance2 < bestDistance) {
-      bestDistance = distance2;
-      bestRank = r;
-    }
-  }
-  return bestRank;
-}
-function collectLadder(pairs) {
-  const positions = /* @__PURE__ */ new Set();
-  for (const pair of pairs) {
-    for (const position of pair) positions.add(position);
-  }
-  return Array.from(positions).sort((a2, b2) => a2 - b2);
-}
 var statePlugin = definePlugin({
   name: "state",
   inputSchema: StateInputSchema,
   outputSchema: ColorReferenceSchema,
   dependsOn: (input2) => [input2.from],
   transform: (input2, get3) => {
-    const parent = get3(input2.from);
-    if (!parent || typeof parent !== "object" || !("family" in parent) || !("position" in parent)) {
-      throw new Error(
-        `state plugin: parent token "${input2.from}" did not resolve to a ColorReference`
-      );
-    }
-    const parentRef = parent;
-    if (typeof parentRef.position !== "string") {
-      throw new Error(`state plugin: parent token "${input2.from}" position is not a scale string`);
-    }
-    const basePosition = POSITION_TO_INDEX3[parentRef.position];
-    if (basePosition === void 0) {
-      throw new Error(
-        `state plugin: parent token "${input2.from}" position "${parentRef.position}" is not a known scale step`
-      );
-    }
-    const family = get3(parentRef.family);
-    if (!family) {
-      throw new Error(
-        `state plugin: family "${parentRef.family}" (from "${input2.from}") not in registry`
-      );
-    }
-    const precomputed = family.stateReferences?.[input2.stateType];
-    if (precomputed) {
-      return { family: precomputed.family, position: String(precomputed.position) };
-    }
-    const pairs = family.accessibility?.wcagAAA?.normal;
-    if (!pairs || pairs.length === 0) {
-      throw new Error(
-        `state plugin: family "${parentRef.family}" has no accessibility.wcagAAA.normal ladder (color generator must emit accessibility metadata)`
-      );
-    }
-    const ladder = collectLadder(pairs);
-    const baseRank = nearestRankOnLadder(ladder, basePosition);
-    const targetRank = STEP_BY_STATE[input2.stateType](baseRank, ladder);
-    const clampedRank = Math.max(0, Math.min(ladder.length - 1, targetRank));
-    const targetIndex = ladder[clampedRank];
-    if (targetIndex === void 0) {
-      throw new Error(
-        `state plugin: ladder lookup failed for rank ${clampedRank} on family "${parentRef.family}"`
-      );
-    }
-    const position = SCALE_POSITIONS[targetIndex];
-    if (!position) {
-      throw new Error(
-        `state plugin: invalid scale index ${targetIndex} for family "${parentRef.family}"`
-      );
-    }
-    return { family: parentRef.family, position };
+    const { sem, resolved } = requireSemanticParent(input2.from, get3, "state");
+    const pair = sem.pair({ use: input2.stateType, from: resolved.ref.position });
+    return { family: pair.to.family, position: pair.to.position };
   }
 });
 
@@ -29210,6 +29170,15 @@ async function backupCss(cssPath) {
   await copyFile(cssPath, backupPath);
   return backupPath;
 }
+async function stripImportedDeclarations(cwd, cssPath, importedNames) {
+  if (importedNames.length === 0) return;
+  const fullPath = join7(cwd, cssPath);
+  const content = await readFile4(fullPath, "utf-8");
+  const pattern = new RegExp(importedNames.map((n2) => `^\\s*--${n2}[^;]*;\\s*$`).join("|"), "gm");
+  const cleaned = content.replace(pattern, "");
+  const collapsed = cleaned.replace(/\n{3,}/g, "\n\n");
+  await writeFile2(fullPath, collapsed);
+}
 async function updateMainCss(cwd, cssPath, themePath) {
   const fullCssPath = join7(cwd, cssPath);
   const cssContent = await readFile4(fullCssPath, "utf-8");
@@ -29771,6 +29740,11 @@ async function init(options) {
           }
           saveRegistryToDir(paths.tokens, registry2);
           await generateOutputs(cwd, paths, registry2, exports, shadcn);
+          const importedNames = [
+            ...toImportColors.map((c4) => c4.name),
+            ...toImportNonColors.map((d2) => d2.name)
+          ];
+          await stripImportedDeclarations(cwd, detectedCssPath, importedNames);
           log({
             event: "init:import_applied",
             count: toImportColors.length + toImportNonColors.length - skipped.length,
@@ -29854,6 +29828,10 @@ async function init(options) {
             }
             saveRegistryToDir(paths.tokens, registry2);
             await generateOutputs(cwd, paths, registry2, exports, shadcn);
+            const themeImportedNames = families.flatMap(
+              (f) => SCALE_POSITIONS.map((p2) => `color-${f.name}-${p2}`).concat([`color-${f.name}`])
+            );
+            await stripImportedDeclarations(cwd, detectedCssPath, themeImportedNames);
             log({
               event: "init:import_palettes_applied",
               cssPath: detectedCssPath,