@atomixstudio/mcp 1.0.33 → 1.0.35

package/dist/index.js

@@ -1,8 +1,16 @@
 #!/usr/bin/env node
 import {
+  FIGMA_DESIGN_CATALOG,
+  FIGMA_DESIGN_SKILL_MD,
+  buildFigmaPayloadsFromDS,
+  buildResolvers,
+  formatCatalogForMCP,
+  getDesignMethodNames,
+  getQueryMethodNames,
   isAllowedMethod,
-  normalizeBridgeMethod
-} from "./chunk-CE6J5MJX.js";
+  normalizeBridgeMethod,
+  resolveStepParams
+} from "./chunk-426RNS3G.js";
 
 // src/index.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
@@ -17,8 +25,6 @@ import {
 } from "@modelcontextprotocol/sdk/types.js";
 
 // ../atomix-sync-core/dist/index.js
-import * as fs from "fs";
-import * as path from "path";
 import * as path3 from "path";
 function generateETag(meta) {
   const hash = `${meta.version}-${meta.updatedAt}`;
@@ -224,7 +230,7 @@ function detectGovernanceChangesByFoundation(cached, fresh) {
   return changes;
 }
 async function fetchDesignSystem(options) {
-  const { dsId: dsId2, apiKey: apiKey2, accessToken: accessToken2, apiBase: apiBase2 = "https://atomixstudio.eu", etag, forceRefresh = false } = options;
+  const { dsId: dsId2, apiKey: apiKey2, accessToken: accessToken2, apiBase: apiBase2 = "https://atomix.studio", etag, forceRefresh = false } = options;
   if (!dsId2) {
     throw new Error("Missing dsId. Usage: fetchDesignSystem({ dsId: '...' })");
   }
@@ -337,74 +343,6 @@ function diffTokens(oldContent, newCssVars, format, newDarkVars) {
   }
   return { added, modified, removed, addedDark, modifiedDark, removedDark };
 }
-async function syncRulesFiles(options) {
-  const { dsId: dsId2, apiKey: apiKey2, apiBase: apiBase2 = "https://atomixstudio.eu", rulesDir = process.cwd() } = options;
-  const rulesDirResolved = path.resolve(process.cwd(), rulesDir);
-  const toolsToSync = [
-    { tool: "cursor", filename: ".cursorrules" },
-    { tool: "windsurf", filename: ".windsurfrules" },
-    { tool: "cline", filename: ".clinerules" },
-    { tool: "continue", filename: ".continuerules" },
-    { tool: "copilot", filename: "copilot-instructions.md", dir: ".github" },
-    { tool: "generic", filename: "AI_GUIDELINES.md" }
-  ];
-  const existingTools = toolsToSync.filter((t) => {
-    const filePath = t.dir ? path.join(rulesDirResolved, t.dir, t.filename) : path.join(rulesDirResolved, t.filename);
-    return fs.existsSync(filePath);
-  });
-  const toolsToWrite = existingTools.length > 0 ? existingTools : [{ tool: "cursor", filename: ".cursorrules" }];
-  const results = [];
-  for (const { tool, filename, dir } of toolsToWrite) {
-    try {
-      const rulesUrl = `${apiBase2}/api/ds/${dsId2}/rules?format=${tool}`;
-      const headers = { "Content-Type": "application/json" };
-      if (apiKey2) headers["x-api-key"] = apiKey2;
-      const response = await fetch(rulesUrl, { headers });
-      if (!response.ok) {
-        results.push({
-          tool,
-          filename,
-          path: dir ? `${dir}/${filename}` : filename,
-          success: false,
-          error: `Failed to fetch ${tool} rules: ${response.status}`
-        });
-        continue;
-      }
-      const rulesData = await response.json();
-      if (!rulesData.content) {
-        results.push({
-          tool,
-          filename,
-          path: dir ? `${dir}/${filename}` : filename,
-          success: false,
-          error: `No content for ${tool} rules`
-        });
-        continue;
-      }
-      const targetDir = dir ? path.join(rulesDirResolved, dir) : rulesDirResolved;
-      if (!fs.existsSync(targetDir)) {
-        fs.mkdirSync(targetDir, { recursive: true });
-      }
-      const filePath = path.join(targetDir, filename);
-      fs.writeFileSync(filePath, rulesData.content);
-      results.push({
-        tool,
-        filename,
-        path: dir ? `${dir}/${filename}` : filename,
-        success: true
-      });
-    } catch (error) {
-      results.push({
-        tool,
-        filename,
-        path: dir ? `${dir}/${filename}` : filename,
-        success: false,
-        error: error instanceof Error ? error.message : String(error)
-      });
-    }
-  }
-  return results;
-}
 function generateCSSOutput(cssVariables, darkModeColors, deprecatedTokens = /* @__PURE__ */ new Map()) {
   const lines = [
     "/* Atomix Design System Tokens",
@@ -1163,9 +1101,7 @@ function formatSyncResponse(options) {
 `;
     });
     response += `
-These changes are reflected in your AI tool rules files (e.g., .cursorrules).
-`;
-    response += `Review the updated rules files to see the new guidance.
+These changes are reflected in the design system governance; run /--sync to update the skill and call getRules for the latest rules.
 `;
   }
   if (diff) {
@@ -1288,712 +1224,9 @@ function getTokenStats(data) {
   };
 }
 
-// ../figma-tools/dist/index.js
-var LEGACY_GROUP_PREFIX = {
-  background: "bg",
-  text: "text",
-  icon: "icon",
-  border: "border",
-  brand: "brand",
-  action: "action",
-  feedback: "feedback"
-};
-var RESERVED_COLOR_KEYS = /* @__PURE__ */ new Set(["customScales", "neutral"]);
-function getColorGroupOrder(storedColors) {
-  if (Array.isArray(storedColors._groupOrder) && storedColors._groupOrder.length > 0) {
-    return storedColors._groupOrder;
-  }
-  return Object.keys(storedColors).filter(
-    (k) => !k.startsWith("_") && !RESERVED_COLOR_KEYS.has(k) && typeof storedColors[k] === "object"
-  );
-}
-function getGroupPrefix(storedColors, groupName) {
-  const custom = storedColors._groupPrefix;
-  if (custom && typeof custom[groupName] === "string") return custom[groupName];
-  return LEGACY_GROUP_PREFIX[groupName] ?? groupName;
-}
-function refScaleToFigmaDisplayName(scaleFromRef) {
-  const s = scaleFromRef.trim();
-  if (!s) return s;
-  return s.charAt(0).toUpperCase() + s.slice(1);
-}
-function referenceToFigmaPrimitiveName(ref, primitiveNames) {
-  if (!ref || typeof ref !== "string") return null;
-  const r = ref.trim();
-  const scaleStep = /^([a-zA-Z]+)\.(\d+|[a-z]+)$/.exec(r);
-  if (scaleStep) {
-    const [, scale, step] = scaleStep;
-    const scaleDisplay = refScaleToFigmaDisplayName(scale);
-    const name = `${scaleDisplay} / ${step}`;
-    return primitiveNames.has(name) ? name : null;
-  }
-  const radixMatch = /^radix\.([a-zA-Z]+)\.(\d+)$/.exec(r);
-  if (radixMatch) {
-    const [, family, step] = radixMatch;
-    const scaleName = refScaleToFigmaDisplayName(family);
-    const name = `${scaleName} / ${step}`;
-    return primitiveNames.has(name) ? name : null;
-  }
-  const oneOffMatch = /^(?:new|oneOff)\.(.+)$/.exec(r);
-  if (oneOffMatch) {
-    const name = `One-off / ${oneOffMatch[1]}`;
-    return primitiveNames.has(name) ? name : null;
-  }
-  const whiteAlpha = /^whiteAlpha\.(.+)$/.exec(r);
-  if (whiteAlpha) {
-    const name = `WhiteAlpha / ${whiteAlpha[1]}`;
-    return primitiveNames.has(name) ? name : null;
-  }
-  const blackAlpha = /^blackAlpha\.(.+)$/.exec(r);
-  if (blackAlpha) {
-    const name = `BlackAlpha / ${blackAlpha[1]}`;
-    return primitiveNames.has(name) ? name : null;
-  }
-  return null;
-}
-function referenceToScaleName(ref) {
-  if (!ref || typeof ref !== "string") return null;
-  const r = ref.trim();
-  const scaleStep = /^([a-zA-Z]+)\.(\d+|[a-z]+)$/.exec(r);
-  if (scaleStep) return refScaleToFigmaDisplayName(scaleStep[1]);
-  const radixMatch = /^radix\.([a-zA-Z]+)\.(\d+)$/.exec(r);
-  if (radixMatch) return refScaleToFigmaDisplayName(radixMatch[1]);
-  return null;
-}
-function getReferencedScaleNames(storedColors) {
-  const names = /* @__PURE__ */ new Set();
-  const groupOrder = getColorGroupOrder(storedColors);
-  for (const groupName of groupOrder) {
-    const group = storedColors[groupName];
-    if (!group || typeof group !== "object") continue;
-    const keys = Object.keys(group).filter((k) => !k.startsWith("_") && k !== "governance");
-    for (const key of keys) {
-      const value = group[key];
-      if (value === void 0 || typeof value !== "object" || value === null) continue;
-      const theme = value;
-      const lightScale = theme.light?.reference ? referenceToScaleName(theme.light.reference) : null;
-      const darkScale = theme.dark?.reference ? referenceToScaleName(theme.dark.reference) : null;
-      if (lightScale) names.add(lightScale);
-      if (darkScale) names.add(darkScale);
-    }
-  }
-  return names;
-}
-function getFullScaleFromStored(storedColors, scaleName) {
-  const key = scaleName.toLowerCase();
-  if (key === "neutral" || key === "gray") {
-    const neutral = storedColors.neutral;
-    if (!neutral?.steps || typeof neutral.steps !== "object") return null;
-    const out = {};
-    for (const [step, stepValue] of Object.entries(neutral.steps)) {
-      const hex = stepValue?.hex;
-      if (typeof hex === "string" && /^#?[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$/i.test(hex)) {
-        out[step] = hex.startsWith("#") ? hex : `#${hex}`;
-      }
-    }
-    return Object.keys(out).length > 0 ? out : null;
-  }
-  const customScales = storedColors.customScales;
-  if (Array.isArray(customScales)) {
-    const keyNorm = key.replace(/\s+/g, "");
-    const scale = customScales.find(
-      (s) => s.name?.toLowerCase() === key || s.name?.toLowerCase().replace(/\s+/g, "") === keyNorm
-    );
-    if (scale?.steps && typeof scale.steps === "object") {
-      const out = {};
-      for (const [step, stepValue] of Object.entries(scale.steps)) {
-        const hex = stepValue?.hex;
-        if (typeof hex === "string" && /^#?[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$/i.test(hex)) {
-          out[step] = hex.startsWith("#") ? hex : `#${hex}`;
-        }
-      }
-      if (Object.keys(out).length > 0) return out;
-    }
-  }
-  return null;
-}
-function buildSemanticRefMap(storedColors, primitiveNames) {
-  const out = {};
-  const groupOrder = getColorGroupOrder(storedColors);
-  for (const groupName of groupOrder) {
-    const group = storedColors[groupName];
-    if (!group || typeof group !== "object") continue;
-    const prefix = getGroupPrefix(storedColors, groupName);
-    const rowOrder = Array.isArray(group._rowOrder) ? group._rowOrder : void 0;
-    const keys = Array.isArray(rowOrder) ? rowOrder : Object.keys(group).filter((k) => !k.startsWith("_") && k !== "governance");
-    const toKebab = prefix === "action" || prefix === "brand" || prefix === "feedback";
-    for (const key of keys) {
-      const value = group[key];
-      if (value === void 0 || typeof value !== "object" || value === null) continue;
-      const theme = value;
-      let cssKey = key === "app" ? "page" : key;
-      if (toKebab) {
-        cssKey = String(key).replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase();
-      }
-      const fullKey = `${prefix}-${cssKey}`;
-      const lightRef = theme.light?.reference ? referenceToFigmaPrimitiveName(theme.light.reference, primitiveNames) : null;
-      const darkRef = theme.dark?.reference ? referenceToFigmaPrimitiveName(theme.dark.reference, primitiveNames) : null;
-      if (lightRef || darkRef) {
-        out[fullKey] = {};
-        if (lightRef) out[fullKey].Light = lightRef;
-        if (darkRef) out[fullKey].Dark = darkRef;
-      }
-    }
-  }
-  return out;
-}
-function figmaColorNameWithGroup(key) {
-  if (key.includes("/")) {
-    const [group2, ...rest] = key.split("/");
-    const name2 = rest.join("/").trim();
-    if (!name2) return key;
-    const groupDisplay2 = group2.charAt(0).toUpperCase() + group2.slice(1).toLowerCase();
-    return `${groupDisplay2} / ${name2}`;
-  }
-  const firstDash = key.indexOf("-");
-  if (firstDash <= 0) return key;
-  const group = key.slice(0, firstDash);
-  const name = key.slice(firstDash + 1);
-  const groupDisplay = group.charAt(0).toUpperCase() + group.slice(1).toLowerCase();
-  return `${groupDisplay} / ${name}`;
-}
-var FIGMA_SHADOW_ORDER = {
-  none: 0,
-  xs: 1,
-  sm: 2,
-  md: 3,
-  lg: 4,
-  xl: 5,
-  "2xl": 6,
-  focus: 7
-};
-function tokenValueToNumber(s) {
-  if (typeof s !== "string" || !s.trim()) return 0;
-  const t = s.trim();
-  if (t.endsWith("rem")) {
-    const n2 = parseFloat(t.replace(/rem$/, ""));
-    return Number.isFinite(n2) ? Math.round(n2 * 16) : 0;
-  }
-  if (t.endsWith("px")) {
-    const n2 = parseFloat(t.replace(/px$/, ""));
-    return Number.isFinite(n2) ? Math.round(n2) : 0;
-  }
-  const n = parseFloat(t);
-  return Number.isFinite(n) ? n : 0;
-}
-function parseBoxShadowToFigmaEffect(shadowStr) {
-  const s = shadowStr.trim();
-  if (!s || s.toLowerCase() === "none") return null;
-  const parsePx = (x) => typeof x === "string" ? parseFloat(x.replace(/px$/i, "")) : NaN;
-  const colorMatch = s.match(/(rgba?\s*\([^)]+\)|#[0-9A-Fa-f]{3,8})\s*$/i);
-  const colorStr = colorMatch ? colorMatch[1].trim() : void 0;
-  const rest = (colorMatch ? s.slice(0, colorMatch.index) : s).trim();
-  const parts = rest ? rest.split(/\s+/) : [];
-  if (parts.length < 3) return null;
-  const offsetX = parsePx(parts[0]);
-  const offsetY = parsePx(parts[1]);
-  const blur = parsePx(parts[2]);
-  let spread = 0;
-  if (parts.length >= 4) spread = parsePx(parts[3]);
-  let r = 0, g = 0, b = 0, a = 0.1;
-  if (colorStr) {
-    const rgbaMatch = colorStr.match(/rgba?\s*\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*(?:,\s*([\d.]+)\s*)?\)/i);
-    if (rgbaMatch) {
-      r = Number(rgbaMatch[1]) / 255;
-      g = Number(rgbaMatch[2]) / 255;
-      b = Number(rgbaMatch[3]) / 255;
-      a = rgbaMatch[4] != null ? parseFloat(rgbaMatch[4]) : 1;
-    } else {
-      const hexMatch = colorStr.match(/^#?([0-9A-Fa-f]{6})([0-9A-Fa-f]{2})?$/);
-      if (hexMatch) {
-        r = parseInt(hexMatch[1].slice(0, 2), 16) / 255;
-        g = parseInt(hexMatch[1].slice(2, 4), 16) / 255;
-        b = parseInt(hexMatch[1].slice(4, 6), 16) / 255;
-        a = hexMatch[2] ? parseInt(hexMatch[2], 16) / 255 : 0.1;
-      }
-    }
-  }
-  if (!Number.isFinite(offsetX) || !Number.isFinite(offsetY) || !Number.isFinite(blur)) return null;
-  return {
-    type: "DROP_SHADOW",
-    offset: { x: offsetX, y: offsetY },
-    radius: Math.max(0, blur),
-    spread: Number.isFinite(spread) ? spread : 0,
-    color: { r, g, b, a },
-    visible: true,
-    blendMode: "NORMAL"
-  };
-}
-function parseBoxShadowToFigmaEffects(shadowStr) {
-  const s = (shadowStr || "").trim();
-  if (!s || s.toLowerCase() === "none") return [];
-  const out = [];
-  const segments = s.split(/\s*,\s*/);
-  for (const seg of segments) {
-    const effect = parseBoxShadowToFigmaEffect(seg.trim());
-    if (effect) out.push(effect);
-  }
-  return out;
-}
-function colorTo8DigitHex(color) {
-  if (!color || typeof color !== "string") return null;
-  const s = color.trim();
-  const rgbaMatch = s.match(/rgba?\s*\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*(?:,\s*([\d.]+)\s*)?\)/i);
-  if (rgbaMatch) {
-    const r = Math.max(0, Math.min(255, parseInt(rgbaMatch[1], 10)));
-    const g = Math.max(0, Math.min(255, parseInt(rgbaMatch[2], 10)));
-    const b = Math.max(0, Math.min(255, parseInt(rgbaMatch[3], 10)));
-    const a = rgbaMatch[4] != null ? Math.max(0, Math.min(1, parseFloat(rgbaMatch[4]))) : 1;
-    const aByte = Math.round(a * 255);
-    const hex = "#" + [r, g, b, aByte].map((n) => n.toString(16).padStart(2, "0")).join("").toUpperCase();
-    return hex;
-  }
-  const hexMatch = s.match(/^#?([0-9A-Fa-f]{6})([0-9A-Fa-f]{2})?$/i);
-  if (hexMatch) {
-    const rgb = hexMatch[1];
-    const aa = hexMatch[2] ?? "FF";
-    return `#${rgb}${aa}`.toUpperCase();
-  }
-  return null;
-}
-function typesetKeyToFontFamilyRole(key) {
-  const prefix = (key.split("-")[0] ?? key).toLowerCase();
-  if (prefix === "display" || prefix.startsWith("display")) return "display";
-  if (prefix === "heading" || prefix.startsWith("heading")) return "heading";
-  if (prefix === "mono" || prefix.startsWith("mono")) return "mono";
-  if (prefix.startsWith("body")) return "body";
-  return "body";
-}
-function buildFigmaPayloadsFromDS(data) {
-  const tokens = data.tokens;
-  const colors = tokens?.colors;
-  const typography = tokens?.typography;
-  const hexRe = /^#?[0-9A-Fa-f]{6}([0-9A-Fa-f]{2})?$/;
-  const modes = [];
-  if (colors?.modes) {
-    const light = colors.modes.light ?? {};
-    const dark = colors.modes.dark ?? {};
-    if (Object.keys(light).length > 0) modes.push("Light");
-    if (Object.keys(dark).length > 0 && !modes.includes("Dark")) modes.push("Dark");
-  }
-  if (modes.length === 0) modes.push("Light");
-  const primitiveModes = ["Value"];
-  const dsName = data.meta?.name;
-  const collectionPrefix = dsName ? `${dsName} ` : "";
-  const referencedScaleNames = data.storedColors ? getReferencedScaleNames(data.storedColors) : /* @__PURE__ */ new Set();
-  const primitiveVariables = [];
-  const primitiveNames = /* @__PURE__ */ new Set();
-  const oneOffHexToFigmaName = /* @__PURE__ */ new Map();
-  const alphaScales = colors?.alphaScales;
-  if (alphaScales?.whiteAlpha && typeof alphaScales.whiteAlpha === "object") {
-    for (const [step, value] of Object.entries(alphaScales.whiteAlpha)) {
-      if (typeof value !== "string") continue;
-      const hex = colorTo8DigitHex(value);
-      if (!hex || !hexRe.test(hex)) continue;
-      const figmaName = `WhiteAlpha / ${step}`;
-      if (primitiveNames.has(figmaName)) continue;
-      primitiveNames.add(figmaName);
-      const values = {};
-      for (const m of primitiveModes) values[m] = hex;
-      primitiveVariables.push({ name: figmaName, values });
-    }
-  }
-  if (alphaScales?.blackAlpha && typeof alphaScales.blackAlpha === "object") {
-    for (const [step, value] of Object.entries(alphaScales.blackAlpha)) {
-      if (typeof value !== "string") continue;
-      const hex = colorTo8DigitHex(value);
-      if (!hex || !hexRe.test(hex)) continue;
-      const figmaName = `BlackAlpha / ${step}`;
-      if (primitiveNames.has(figmaName)) continue;
-      primitiveNames.add(figmaName);
-      const values = {};
-      for (const m of primitiveModes) values[m] = hex;
-      primitiveVariables.push({ name: figmaName, values });
-    }
-  }
-  if (colors?.scales && typeof colors.scales === "object") {
-    for (const [scaleName, steps] of Object.entries(colors.scales)) {
-      if (!steps || typeof steps !== "object") continue;
-      let groupDisplay = scaleName.charAt(0).toUpperCase() + scaleName.slice(1);
-      if (scaleName.toLowerCase() === "neutral" && data.storedColors) {
-        const neutral = data.storedColors.neutral;
-        if (neutral?.baseHueFamily) {
-          groupDisplay = refScaleToFigmaDisplayName(neutral.baseHueFamily);
-        }
-      }
-      for (const [step, hexVal] of Object.entries(steps)) {
-        if (typeof hexVal !== "string") continue;
-        const hex = colorTo8DigitHex(hexVal) ?? (hexRe.test(hexVal) ? hexVal : null);
-        if (!hex || !hexRe.test(hex)) continue;
-        const figmaName = `${groupDisplay} / ${step}`;
-        if (primitiveNames.has(figmaName)) continue;
-        primitiveNames.add(figmaName);
-        const values = {};
-        for (const m of primitiveModes) values[m] = hex;
-        primitiveVariables.push({ name: figmaName, values });
-      }
-    }
-  }
-  const radixVariables = [];
-  const radixCollectionName = `${collectionPrefix}Colors Radix`;
-  for (const scaleName of referencedScaleNames) {
-    if (primitiveNames.has(`${scaleName} / 50`) || primitiveNames.has(`${scaleName} / 100`)) continue;
-    const fromStored = data.storedColors ? getFullScaleFromStored(data.storedColors, scaleName) : null;
-    const scaleData = fromStored ?? data.getRadixScale?.(scaleName) ?? null;
-    if (!scaleData) continue;
-    for (const [step, hexVal] of Object.entries(scaleData)) {
-      const figmaName = `${scaleName} / ${step}`;
-      if (primitiveNames.has(figmaName)) continue;
-      const hex = colorTo8DigitHex(hexVal) ?? (hexRe.test(hexVal) ? hexVal : null);
-      if (!hex || !hexRe.test(hex)) continue;
-      primitiveNames.add(figmaName);
-      const values = {};
-      for (const m of primitiveModes) values[m] = hex;
-      primitiveVariables.push({ name: figmaName, values });
-    }
-  }
-  if (colors?.oneOffs && Array.isArray(colors.oneOffs)) {
-    for (const oneOff of colors.oneOffs) {
-      if (!oneOff || typeof oneOff !== "object" || typeof oneOff.hex !== "string") continue;
-      const hex = colorTo8DigitHex(oneOff.hex) ?? (hexRe.test(oneOff.hex) ? oneOff.hex : null);
-      if (!hex || !hexRe.test(hex)) continue;
-      const name = typeof oneOff.name === "string" && oneOff.name ? oneOff.name : oneOff.id ?? "unnamed";
-      const figmaName = `One-off / ${name}`;
-      if (primitiveNames.has(figmaName)) continue;
-      primitiveNames.add(figmaName);
-      const values = {};
-      for (const m of primitiveModes) values[m] = hex;
-      primitiveVariables.push({ name: figmaName, values });
-      const normalizedHex = hex.replace(/^#/, "").toUpperCase();
-      const key8 = normalizedHex.length === 6 ? normalizedHex + "FF" : normalizedHex;
-      oneOffHexToFigmaName.set(key8, figmaName);
-    }
-  }
-  const semanticRefMap = data.storedColors && primitiveNames.size > 0 ? buildSemanticRefMap(data.storedColors, primitiveNames) : {};
-  const semanticVariables = [];
-  const semanticNames = /* @__PURE__ */ new Set();
-  const primitivesCollectionName = `${collectionPrefix}Colors Primitives`;
-  if (colors?.modes) {
-    const light = colors.modes.light ?? {};
-    const dark = colors.modes.dark ?? {};
-    const orderedKeys = [...Object.keys(light)];
-    for (const k of Object.keys(dark)) {
-      if (!orderedKeys.includes(k)) orderedKeys.push(k);
-    }
-    for (const key of orderedKeys) {
-      const lightVal = light[key];
-      const darkVal = dark[key];
-      const lightHex = typeof lightVal === "string" ? colorTo8DigitHex(lightVal) ?? (hexRe.test(lightVal) ? lightVal : null) : null;
-      if (lightHex && hexRe.test(lightHex)) {
-        const figmaName = figmaColorNameWithGroup(key);
-        if (semanticNames.has(figmaName)) continue;
-        semanticNames.add(figmaName);
-        const darkHex = typeof darkVal === "string" ? colorTo8DigitHex(darkVal) ?? (hexRe.test(darkVal) ? darkVal : null) : null;
-        const refs = semanticRefMap[key];
-        const values = {
-          ...modes.includes("Light") && { Light: lightHex },
-          ...modes.includes("Dark") && { Dark: darkHex && hexRe.test(darkHex) ? darkHex : lightHex }
-        };
-        const aliasByMode = {};
-        for (const m of modes) {
-          const aliasFromRef = m === "Light" ? refs?.Light : refs?.Dark;
-          if (aliasFromRef && primitiveNames.has(aliasFromRef)) {
-            aliasByMode[m] = aliasFromRef;
-            continue;
-          }
-          const hexForMode = m === "Light" ? lightHex : darkHex && hexRe.test(darkHex) ? darkHex : lightHex;
-          const norm = hexForMode.replace(/^#/, "").toUpperCase();
-          const key8 = norm.length === 6 ? norm + "FF" : norm;
-          const oneOffAlias = oneOffHexToFigmaName.get(key8);
-          if (oneOffAlias) {
-            aliasByMode[m] = oneOffAlias;
-          }
-        }
-        semanticVariables.push({
-          name: figmaName,
-          values,
-          ...Object.keys(aliasByMode).length > 0 ? { aliasByMode } : {}
-        });
-      }
-    }
-  }
-  if (colors?.static?.brand && typeof colors.static.brand === "object") {
-    for (const [key, hex] of Object.entries(colors.static.brand)) {
-      if (typeof hex !== "string" || !hexRe.test(hex)) continue;
-      const figmaName = figmaColorNameWithGroup(`brand/${key}`);
-      if (semanticNames.has(figmaName)) continue;
-      semanticNames.add(figmaName);
-      const values = {};
-      for (const m of modes) values[m] = hex;
-      semanticVariables.push({ name: figmaName, values });
-    }
-  }
-  const colorVariableCollections = [];
-  if (primitiveVariables.length > 0) {
-    colorVariableCollections.push({
-      collectionName: primitivesCollectionName,
-      modes: primitiveModes,
-      variables: primitiveVariables,
-      applyScopes: false
-    });
-  }
-  if (radixVariables.length > 0) {
-    colorVariableCollections.push({
-      collectionName: radixCollectionName,
-      modes,
-      variables: radixVariables,
-      applyScopes: false
-    });
-  }
-  if (semanticVariables.length > 0) {
-    const primitiveCollections = [];
-    if (primitiveVariables.length > 0) primitiveCollections.push(primitivesCollectionName);
-    if (radixVariables.length > 0) primitiveCollections.push(radixCollectionName);
-    colorVariableCollections.push({
-      collectionName: `${collectionPrefix}Colors Semantic`,
-      modes,
-      variables: semanticVariables,
-      applyScopes: true,
-      ...primitiveCollections.length > 1 ? { primitiveCollectionNames: primitiveCollections } : primitiveCollections.length === 1 ? { primitiveCollectionName: primitiveCollections[0] } : {}
-    });
-  }
-  const paintStyles = [];
-  const textStyles = [];
-  const sizeToPx = (val, basePx = 16) => {
-    if (typeof val === "number") return Math.round(val);
-    const s = String(val).trim();
-    const pxMatch = s.match(/^([\d.]+)\s*px$/i);
-    if (pxMatch) return Math.round(parseFloat(pxMatch[1]));
-    const remMatch = s.match(/^([\d.]+)\s*rem$/i);
-    if (remMatch) return Math.round(parseFloat(remMatch[1]) * basePx);
-    const n = parseFloat(s);
-    if (Number.isFinite(n)) return n <= 0 ? basePx : n < 50 ? Math.round(n * basePx) : Math.round(n);
-    return basePx;
-  };
-  const letterSpacingToPx = (val, fontSizePx) => {
-    if (val === void 0 || val === null) return void 0;
-    if (typeof val === "number") return Math.round(val);
-    const s = String(val).trim();
-    const pxMatch = s.match(/^([-\d.]+)\s*px$/i);
-    if (pxMatch) return Math.round(parseFloat(pxMatch[1]));
-    const emMatch = s.match(/^([-\d.]+)\s*em$/i);
-    if (emMatch) return Math.round(parseFloat(emMatch[1]) * fontSizePx);
-    const n = parseFloat(s);
-    return Number.isFinite(n) ? Math.round(n) : void 0;
-  };
-  const firstFont = (obj) => {
-    if (typeof obj === "string") {
-      const primary = obj.split(",")[0].trim().replace(/^['"]|['"]$/g, "");
-      return primary || "Inter";
-    }
-    if (obj && typeof obj === "object" && !Array.isArray(obj)) {
-      const v = obj.body ?? obj.heading ?? obj.display ?? Object.values(obj)[0];
-      return firstFont(v);
-    }
-    return "Inter";
-  };
-  const toFontFamilyString = (val) => {
-    if (typeof val === "string") {
-      const s = val.trim().replace(/^["']|["']$/g, "");
-      return s || "Inter";
-    }
-    return firstFont(val);
-  };
-  const fontFamilyMap = typography?.fontFamily ?? {};
-  const defaultFontFamily = typography ? firstFont(typography.fontFamily ?? "Inter") : "Inter";
-  const fontSizeMap = typography?.fontSize;
-  const fontWeightMap = typography?.fontWeight;
-  const lineHeightMap = typography?.lineHeight;
-  const letterSpacingMap = typography?.letterSpacing;
-  const textTransformMap = typography?.textTransform;
-  const textDecorationMap = typography?.textDecoration;
-  if (fontSizeMap && typeof fontSizeMap === "object" && Object.keys(fontSizeMap).length > 0) {
-    for (const [key, sizeVal] of Object.entries(fontSizeMap)) {
-      const fontSize = sizeToPx(sizeVal);
-      if (fontSize <= 0) continue;
-      const role = typesetKeyToFontFamilyRole(key);
-      const fontFamily = toFontFamilyString(
-        fontFamilyMap[role] ?? fontFamilyMap.body ?? fontFamilyMap.heading ?? fontFamilyMap.display ?? defaultFontFamily
-      );
-      const lh = lineHeightMap && typeof lineHeightMap === "object" ? lineHeightMap[key] : void 0;
-      const weight = fontWeightMap && typeof fontWeightMap === "object" ? fontWeightMap[key] : void 0;
-      const fontWeight = weight != null ? String(weight) : "400";
-      const letterSpacingPx = letterSpacingToPx(
-        letterSpacingMap && typeof letterSpacingMap === "object" ? letterSpacingMap[key] : void 0,
-        fontSize
-      );
-      const textTransform = textTransformMap && typeof textTransformMap === "object" ? textTransformMap[key] : void 0;
-      const textDecoration = textDecorationMap && typeof textDecorationMap === "object" ? textDecorationMap[key] : void 0;
-      const namePart = key.replace(/-/g, " / ");
-      const style = {
-        name: namePart.startsWith("Typography") ? namePart : `Typography / ${namePart}`,
-        fontFamily,
-        fontWeight,
-        fontSize,
-        lineHeightUnit: "PERCENT",
-        letterSpacingUnit: "PIXELS",
-        ...letterSpacingPx !== void 0 && letterSpacingPx !== 0 ? { letterSpacingValue: letterSpacingPx } : {}
-      };
-      if (lh != null && typeof lh === "number" && lh > 0) {
-        style.lineHeightValue = lh >= 10 ? Math.round(lh / fontSize * 100) : Math.round(lh * 100);
-      } else {
-        style.lineHeightValue = 150;
-      }
-      if (textTransform === "uppercase") style.textCase = "UPPER";
-      else if (textTransform === "lowercase") style.textCase = "LOWER";
-      else if (textTransform === "capitalize") style.textCase = "TITLE";
-      else style.textCase = "ORIGINAL";
-      if (textDecoration === "underline") style.textDecoration = "UNDERLINE";
-      else style.textDecoration = "NONE";
-      textStyles.push(style);
-    }
-  }
-  const textStylesMap = typography?.textStyles;
-  if (textStyles.length === 0 && textStylesMap && typeof textStylesMap === "object") {
-    for (const [styleName, style] of Object.entries(textStylesMap)) {
-      if (!style || typeof style !== "object") continue;
-      const fontSize = sizeToPx(style.fontSize ?? "1rem");
-      const lhStr = style.lineHeight;
-      const lineHeightUnitless = lhStr != null ? lhStr.endsWith("%") ? parseFloat(lhStr) / 100 : sizeToPx(lhStr) / fontSize : 1.5;
-      const payload = {
-        name: styleName.startsWith("Typography") ? styleName : `Typography / ${styleName.replace(/\//g, " / ")}`,
-        fontFamily: defaultFontFamily,
-        fontWeight: String(style.fontWeight ?? "400"),
-        fontSize,
-        lineHeightUnit: "PERCENT",
-        lineHeightValue: Math.round((Number.isFinite(lineHeightUnitless) ? lineHeightUnitless : 1.5) * 100),
-        letterSpacingUnit: "PIXELS",
-        textCase: "ORIGINAL",
-        textDecoration: "NONE"
-      };
-      textStyles.push(payload);
-    }
-  }
-  textStyles.sort((a, b) => {
-    if (a.fontSize !== b.fontSize) return a.fontSize - b.fontSize;
-    return (a.name || "").localeCompare(b.name || "");
-  });
-  const numberVariableCollections = [];
-  const spacing = tokens?.spacing;
-  if (spacing?.scale && typeof spacing.scale === "object") {
-    const vars = [];
-    for (const [key, val] of Object.entries(spacing.scale)) {
-      const n = tokenValueToNumber(val);
-      if (n >= 0) vars.push({ name: `Spacing / ${key}`, value: n });
-    }
-    vars.sort((a, b) => a.value - b.value);
-    if (vars.length > 0)
-      numberVariableCollections.push({
-        collectionName: `${collectionPrefix}Spacing`,
-        categoryKey: "Spacing",
-        variables: vars,
-        scopes: ["GAP"]
-      });
-  }
-  const radius = tokens?.radius;
-  if (radius?.scale && typeof radius.scale === "object") {
-    const vars = [];
-    for (const [key, val] of Object.entries(radius.scale)) {
-      const n = tokenValueToNumber(val);
-      if (n >= 0) vars.push({ name: `Radius / ${key}`, value: n });
-    }
-    vars.sort((a, b) => a.value - b.value);
-    if (vars.length > 0)
-      numberVariableCollections.push({
-        collectionName: `${collectionPrefix}Radius`,
-        categoryKey: "Radius",
-        variables: vars,
-        scopes: ["CORNER_RADIUS"]
-      });
-  }
-  const borders = tokens?.borders;
-  if (borders?.width && typeof borders.width === "object") {
-    const vars = [];
-    for (const [key, val] of Object.entries(borders.width)) {
-      const n = tokenValueToNumber(val);
-      if (n >= 0) vars.push({ name: `Borders / ${key}`, value: n });
-    }
-    vars.sort((a, b) => a.value - b.value);
-    if (vars.length > 0)
-      numberVariableCollections.push({
-        collectionName: `${collectionPrefix}Borders`,
-        categoryKey: "Borders",
-        variables: vars,
-        scopes: ["STROKE_FLOAT"]
-      });
-  }
-  const sizing = tokens?.sizing;
-  const sizingVariables = [];
-  if (sizing?.height && typeof sizing.height === "object") {
-    for (const [key, val] of Object.entries(sizing.height)) {
-      const n = tokenValueToNumber(val);
-      if (n >= 0) sizingVariables.push({ name: `Height / ${key}`, value: n });
-    }
-  }
-  if (sizing?.icon && typeof sizing.icon === "object") {
-    for (const [key, val] of Object.entries(sizing.icon)) {
-      const n = tokenValueToNumber(val);
-      if (n >= 0) sizingVariables.push({ name: `Icon / ${key}`, value: n });
-    }
-  }
-  sizingVariables.sort((a, b) => a.value - b.value);
-  if (sizingVariables.length > 0) {
-    numberVariableCollections.push({
-      collectionName: `${collectionPrefix}Sizing`,
-      categoryKey: "Sizing",
-      variables: sizingVariables,
-      scopes: ["WIDTH_HEIGHT"]
-    });
-  }
-  const layout = tokens?.layout;
-  if (layout?.breakpoint && typeof layout.breakpoint === "object") {
-    const vars = [];
-    for (const [key, val] of Object.entries(layout.breakpoint)) {
-      const n = tokenValueToNumber(val);
-      if (n >= 0) vars.push({ name: `Breakpoint / ${key}`, value: n });
-    }
-    vars.sort((a, b) => a.value - b.value);
-    if (vars.length > 0)
-      numberVariableCollections.push({
-        collectionName: `${collectionPrefix}Layout`,
-        categoryKey: "Layout",
-        variables: vars,
-        scopes: ["WIDTH_HEIGHT"]
-      });
-  }
-  const effectStyles = [];
-  const shadows = tokens?.shadows;
-  if (shadows?.elevation && typeof shadows.elevation === "object") {
-    for (const [key, val] of Object.entries(shadows.elevation)) {
-      if (typeof val !== "string") continue;
-      const effects = parseBoxShadowToFigmaEffects(val);
-      if (effects.length > 0) effectStyles.push({ name: `Shadow / ${key}`, effects });
-    }
-  }
-  if (shadows?.focus && typeof shadows.focus === "string") {
-    const effects = parseBoxShadowToFigmaEffects(shadows.focus);
-    if (effects.length > 0) effectStyles.push({ name: "Shadow / focus", effects });
-  }
-  effectStyles.sort((a, b) => {
-    const nameA = a.name.startsWith("Shadow / ") ? a.name.slice(9) : a.name;
-    const nameB = b.name.startsWith("Shadow / ") ? b.name.slice(9) : b.name;
-    const orderA = FIGMA_SHADOW_ORDER[nameA] ?? 100;
-    const orderB = FIGMA_SHADOW_ORDER[nameB] ?? 100;
-    if (orderA !== orderB) return orderA - orderB;
-    return nameA.localeCompare(nameB);
-  });
-  return {
-    colorVariableCollections,
-    paintStyles,
-    textStyles,
-    numberVariableCollections,
-    effectStyles
-  };
-}
-
 // src/index.ts
-import * as path2 from "path";
-import * as fs2 from "fs";
+import * as path from "path";
+import * as fs from "fs";
 import { execSync } from "child_process";
 import { platform } from "os";
 import WebSocket, { WebSocketServer } from "ws";
@@ -2152,13 +1385,13 @@ function sendBridgeRequest(method, params, timeoutMs = FIGMA_BRIDGE_TIMEOUT_MS)
     );
   }
   const id = `mcp-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
-  return new Promise((resolve4, reject) => {
+  return new Promise((resolve3, reject) => {
     const timeout = setTimeout(() => {
       if (pendingBridgeRequests.delete(id)) {
         reject(new Error("Figma bridge timeout. " + FIGMA_CONNECTION_INSTRUCTIONS.startBridge + " Then " + FIGMA_CONNECTION_INSTRUCTIONS.connect));
       }
     }, timeoutMs);
-    pendingBridgeRequests.set(id, { resolve: resolve4, reject, timeout });
+    pendingBridgeRequests.set(id, { resolve: resolve3, reject, timeout });
     try {
       ws.send(JSON.stringify({ id, method: normalized, params }));
     } catch (e) {
@@ -2194,10 +1427,25 @@ function parseArgs() {
 var cliArgs = parseArgs();
 var { dsId, apiKey, accessToken } = cliArgs;
 var apiBase = cliArgs.apiBase || "https://atomix.studio";
+var MCP_VERSION = "1.0.34";
 var cachedData = null;
 var cachedETag = null;
 var cachedMcpTier = null;
 var authFailedNoTools = false;
+var mcpUpdateNotice = null;
+var mcpLatestVersion = null;
+function isVersionNewer(latest, current) {
+  const toParts = (v) => v.split(".").map((n) => parseInt(n, 10) || 0);
+  const a = toParts(latest);
+  const b = toParts(current);
+  for (let i = 0; i < Math.max(a.length, b.length); i++) {
+    const x = a[i] ?? 0;
+    const y = b[i] ?? 0;
+    if (x > y) return true;
+    if (x < y) return false;
+  }
+  return false;
+}
 function hasValidAuthConfig() {
   return !!(dsId && accessToken);
 }
@@ -2218,10 +1466,10 @@ ${changes.summary}`);
   }
 }
 function validateTokenFileAfterWrite(outputPath, format, expectedMinVariables) {
-  if (!fs2.existsSync(outputPath)) {
+  if (!fs.existsSync(outputPath)) {
     return { path: outputPath, status: "FAIL", detail: "File not found after write." };
   }
-  const content = fs2.readFileSync(outputPath, "utf-8");
+  const content = fs.readFileSync(outputPath, "utf-8");
   if (!content || content.trim().length === 0) {
     return { path: outputPath, status: "FAIL", detail: "File is empty after write." };
   }
@@ -2243,7 +1491,7 @@ function validateTokenFileAfterWrite(outputPath, format, expectedMinVariables) {
 }
 function formatValidationBlock(entries) {
   if (entries.length === 0) return "";
-  const displayPath = (p) => p.startsWith("(") ? p : path2.relative(process.cwd(), p);
+  const displayPath = (p) => p.startsWith("(") ? p : path.relative(process.cwd(), p);
   const lines = [
     "",
     "\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501",
@@ -2273,11 +1521,19 @@ async function fetchDesignSystemForMCP(forceRefresh = false) {
   cachedData = result.data;
   cachedETag = result.etag;
   cachedMcpTier = result.data.meta.mcpTier ?? null;
+  const latest = result.data.meta.mcpLatestVersion;
+  if (latest && isVersionNewer(latest, MCP_VERSION)) {
+    mcpLatestVersion = latest;
+    mcpUpdateNotice = `**MCP update available:** A new Atomix MCP server (v${latest}) is available. You're on v${MCP_VERSION}. To use the new version in Cursor: 1) Quit Cursor completely and reopen, 2) Clear npx cache: \`rm -rf ~/.npm/_npx\` (macOS/Linux), 3) Ensure your MCP config uses \`@atomixstudio/mcp@latest\` or \`@atomixstudio/mcp@${latest}\`. To test a local build before publishing: point MCP to \`node /path/to/Atom/packages/mcp-user/dist/index.js\` with \`--ds-id\` and \`--atomix-token\`.`;
+  } else {
+    mcpUpdateNotice = null;
+    mcpLatestVersion = null;
+  }
   await updateChangeSummary(result.data);
   return result.data;
 }
 var TOKEN_CATEGORIES = ["colors", "typography", "spacing", "sizing", "shadows", "radius", "borders", "motion", "zIndex"];
-function typesetKeyToFontFamilyRole2(key) {
+function typesetKeyToFontFamilyRole(key) {
   const prefix = (key.split("-")[0] ?? key).toLowerCase();
   if (prefix === "display" || prefix.startsWith("display")) return "display";
   if (prefix === "heading" || prefix.startsWith("heading")) return "heading";
@@ -2297,7 +1553,7 @@ function buildTypesetsList(typography, cssPrefix = "atmx") {
   const p = cssPrefix ? `${cssPrefix}-` : "";
   const typesets = [];
   for (const key of Object.keys(fontSize)) {
-    const role = typesetKeyToFontFamilyRole2(key);
+    const role = typesetKeyToFontFamilyRole(key);
     const familyName = fontFamily[role] ?? fontFamily.body;
     const fontFamilyVarName = familyName ? `--${p}typography-font-family-${role}` : void 0;
     const fontFamilyVar = familyName ? `var(${fontFamilyVarName})` : "";
@@ -2323,7 +1579,7 @@ function buildTypesetsList(typography, cssPrefix = "atmx") {
 var server = new Server(
   {
     name: "atomix-mcp-user",
-    version: "1.0.30"
+    version: MCP_VERSION
   },
   {
     capabilities: {
@@ -2441,18 +1697,17 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       }
     },
     {
-      name: "getAIToolRules",
-      description: "Generate design system rules for AI coding tools (Cursor, Copilot, Windsurf, etc.).",
+      name: "getRules",
+      description: "Get design system governance rules. Optionally filter by topic (colors, typo, motion, icons, layout, visual). Call at session start or before writing visual code.",
       inputSchema: {
         type: "object",
         properties: {
-          tool: {
+          topic: {
             type: "string",
-            enum: ["cursor", "copilot", "windsurf", "cline", "continue", "zed", "generic", "all"],
-            description: "AI tool to generate rules for. Use 'all' to get rules for all tools."
+            enum: ["colors", "typo", "typography", "motion", "icons", "layout", "visual", "style"],
+            description: "Optional. Filter rules by topic: colors, typo/typography, motion, icons, layout, or visual/style (color, border, radius, shadows, icons). Omit for all rules."
           }
-        },
-        required: ["tool"]
+        }
       }
     },
     {
@@ -2487,10 +1742,14 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
     },
     {
       name: "syncAll",
-      description: "Sync tokens, AI rules, skills (.cursor/skills/atomix-ds/SKILL.md), and atomix-dependencies.json. Use dryRun: true first to report what would change without writing; then dryRun: false to apply. Response includes a VALIDATION section\u2014agent must check it to confirm success. Optional: output (default ./tokens.css), format (default css), skipTokens (if true, only skills and manifest), dryRun (if true, report only; no files written).",
+      description: "Sync tokens, AI rules, skills (.cursor/skills/atomix-ds/SKILL.md and figma-design-SKILL.md), and atomix-dependencies.json. All paths are resolved under workspaceRoot so files are written inside the project repo (committable). Use dryRun: true first to report what would change without writing; then dryRun: false to apply. Optional: workspaceRoot (project root; default: ATOMIX_PROJECT_ROOT env or process.cwd()), output (default ./tokens.css), format (default css), skipTokens, dryRun.",
       inputSchema: {
         type: "object",
         properties: {
+          workspaceRoot: {
+            type: "string",
+            description: "Absolute path to the project/repo root. Skills and manifest are written under this path so they can be committed. If omitted, uses ATOMIX_PROJECT_ROOT env var, then process.cwd()."
+          },
           output: {
             type: "string",
             description: "Token file path (e.g. ./tokens.css). Default: ./tokens.css. Ignored if skipTokens is true."
@@ -2531,6 +1790,15 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
         required: []
       }
     },
+    {
+      name: "getMcpVersion",
+      description: "Return the current Atomix MCP server version (e.g. 1.0.33) and, if known, the latest available from the API. Call this whenever the user asks about MCP version, Atomix MCP version, what version of the MCP server they are using, or whether an update is available. Prefer this over explaining the MCP protocol spec version.",
+      inputSchema: {
+        type: "object",
+        properties: {},
+        required: []
+      }
+    },
     {
       name: "syncToFigma",
       description: "Push the owner's design system to Figma: creates color variable collection (Light/Dark), color and paint styles, number variables (spacing, radius, borders, sizing, breakpoints), text styles, and shadow effect styles. Uses local WebSocket bridge and Atomix Figma plugin (no Figma REST API). No arguments. If the bridge is not running, the response includes agentInstruction to start it; only if that fails should the user start the bridge and connect the plugin. Call this when the user asks to 'sync to Figma' or 'push DS to Figma'.",
@@ -2541,6 +1809,43 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       }
     }
   ];
+  if (cachedMcpTier === "pro") {
+    toolsList.push({
+      name: "designInFigma",
+      description: "Design UI in the connected Figma file using the design system tokens. Call with action:'catalog' to discover available bridge methods, their parameters, and the file's variables/styles. Call with action:'query' to read from Figma: get_selection (current selection), get_node_info (nodeId), get_design_screenshot (frameId; returns PNG image for review). Call with action:'execute' and an array of steps to create the design on canvas. Requires the Atomix Figma plugin to be connected.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          action: {
+            type: "string",
+            enum: ["catalog", "query", "execute"],
+            description: "catalog = discover methods + file context; query = read selection/node/screenshot; execute = run design steps"
+          },
+          queryMethod: {
+            type: "string",
+            description: "Required when action is 'query'. One of: get_selection, get_node_info, get_document_info, get_design_screenshot, get_figma_variables_and_styles, list_local_components, get_component_catalog, get_variable_collection_modes, get_frame_variable_mode."
+          },
+          queryParams: {
+            type: "object",
+            description: "Optional params for query. get_node_info needs { nodeId }. get_design_screenshot needs { frameId } and optional { scale }."
+          },
+          steps: {
+            type: "array",
+            description: "Required when action is 'execute'. Array of { method, params } design commands.",
+            items: {
+              type: "object",
+              properties: {
+                method: { type: "string" },
+                params: { type: "object" }
+              },
+              required: ["method"]
+            }
+          }
+        },
+        required: ["action"]
+      }
+    });
+  }
   return { tools: toolsList };
 });
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -2554,18 +1859,31 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       isError: true
     };
   }
+  if (name === "getMcpVersion") {
+    const out = {
+      version: MCP_VERSION,
+      name: "atomix-mcp-user"
+    };
+    if (mcpLatestVersion) {
+      out.latestVersion = mcpLatestVersion;
+      out.updateAvailable = true;
+    }
+    return {
+      content: [{ type: "text", text: JSON.stringify(out, null, 2) }]
+    };
+  }
   try {
     const shouldForceRefresh = name === "syncAll";
     const data = await fetchDesignSystemForMCP(shouldForceRefresh);
-    async function performTokenSyncAndRules(designSystemData, tokenOutput, tokenFormat, dryRun) {
+    async function performTokenSyncAndRules(designSystemData, tokenOutput, tokenFormat, dryRun, projectRoot) {
       const output = tokenOutput;
       const format = tokenFormat;
-      const outputPath = path2.resolve(process.cwd(), output);
-      const fileExists = fs2.existsSync(outputPath);
+      const outputPath = path.resolve(projectRoot, output);
+      const fileExists = fs.existsSync(outputPath);
       const deprecatedTokens = /* @__PURE__ */ new Map();
       const existingTokens = /* @__PURE__ */ new Map();
       if (fileExists && ["css", "scss", "less"].includes(format)) {
-        const oldContent = fs2.readFileSync(outputPath, "utf-8");
+        const oldContent = fs.readFileSync(outputPath, "utf-8");
         const oldVarPattern = /(?:^|\n)\s*(?:\/\*[^*]*\*+(?:[^/*][^*]*\*+)*\/\s*)?(--[a-zA-Z0-9-]+):\s*([^;]+);/gm;
         let match;
         while ((match = oldVarPattern.exec(oldContent)) !== null) {
@@ -2615,7 +1933,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       let changes = [];
       let diff;
       if (fileExists && ["css", "scss", "less"].includes(format)) {
-        const oldContent = fs2.readFileSync(outputPath, "utf-8");
+        const oldContent = fs.readFileSync(outputPath, "utf-8");
         diff = diffTokens(oldContent, mergedCssVariables, format, darkModeColors?.dark);
         const lightChanges = diff.added.length + diff.modified.length;
         const darkChanges = diff.addedDark.length + diff.modifiedDark.length;
@@ -2670,7 +1988,7 @@ Version: ${designSystemData.meta.version}`,
           `  Tokens: ${tokenCount} (${deprecatedCount} deprecated preserved)`,
           changeLine,
           "",
-          "Rules: .cursorrules (or existing rules files in project)",
+          "Would write skills: .cursor/skills/atomix-ds/SKILL.md, .cursor/skills/atomix-ds/figma-design-SKILL.md",
           "",
           "Call syncAll again with dryRun: false to apply."
         ].filter(Boolean).join("\n");
@@ -2680,30 +1998,12 @@ Version: ${designSystemData.meta.version}`,
           validation: [{ path: "(dry run)", status: "OK", detail: "No files written." }]
         };
       }
-      const outputDir = path2.dirname(outputPath);
-      if (!fs2.existsSync(outputDir)) fs2.mkdirSync(outputDir, { recursive: true });
-      fs2.writeFileSync(outputPath, newContent);
+      const outputDir = path.dirname(outputPath);
+      if (!fs.existsSync(outputDir)) fs.mkdirSync(outputDir, { recursive: true });
+      fs.writeFileSync(outputPath, newContent);
       const validation = [];
       validation.push(validateTokenFileAfterWrite(outputPath, format, tokenCount));
-      let rulesResults = [];
-      try {
-        rulesResults = await syncRulesFiles({
-          dsId,
-          apiKey: apiKey ?? void 0,
-          apiBase: apiBase ?? void 0,
-          rulesDir: process.cwd()
-        });
-        for (const r of rulesResults) {
-          const fullPath = path2.resolve(process.cwd(), r.path);
-          validation.push({
-            path: fullPath,
-            status: r.success && fs2.existsSync(fullPath) ? "OK" : "FAIL",
-            detail: r.success ? "Written." : r.error || "Write failed."
-          });
-        }
-      } catch (error) {
-        console.error(`[syncAll] Failed to sync rules: ${error}`);
-      }
+      const rulesResults = [];
       const governanceChanges = cachedData ? detectGovernanceChangesByFoundation(cachedData, designSystemData) : [];
       const response = formatSyncResponse({
         data: designSystemData,
@@ -2721,31 +2021,32 @@ Version: ${designSystemData.meta.version}`,
         hasRefactorRecommendation: !!lastSyncAffectedTokens?.removed.length,
         deprecatedTokenCount: lastSyncAffectedTokens?.removed.length || 0
       });
-      return { responseText: response, rulesResults, validation };
+      const tokenSyncChangeSummary = fileExists && ["css", "scss", "less"].includes(format) ? { fileExisted: true, previousVarCount: existingTokens.size, currentVarCount: tokenCount } : { fileExisted: false, previousVarCount: void 0, currentVarCount: tokenCount };
+      return { responseText: response, rulesResults, validation, tokenSyncChangeSummary };
     }
     switch (name) {
       case "getToken": {
-        const path4 = args?.path;
-        const value = getTokenByPath(data.tokens, path4);
+        const path2 = args?.path;
+        const value = getTokenByPath(data.tokens, path2);
         if (value === void 0) {
           return {
             content: [{
               type: "text",
               text: JSON.stringify({
-                error: `Token not found: ${path4}`,
+                error: `Token not found: ${path2}`,
                 suggestion: "Use listTokens or searchTokens to find available tokens.",
                 availableCategories: TOKEN_CATEGORIES
               }, null, 2)
             }]
           };
         }
-        const cssVarKey = `--atmx-${path4.replace(/\./g, "-")}`;
+        const cssVarKey = `--atmx-${path2.replace(/\./g, "-")}`;
         const cssVar = data.cssVariables[cssVarKey];
         return {
           content: [{
             type: "text",
             text: JSON.stringify({
-              path: path4,
+              path: path2,
               value,
               cssVariable: cssVar || `var(${cssVarKey})`,
               usage: `style={{ property: "var(${cssVarKey})" }}`
@@ -2772,13 +2073,13 @@ Version: ${designSystemData.meta.version}`,
           };
         }
         const flat = flattenTokens(tokensToList);
-        const tokensWithCssVars = flat.map(({ path: path4, value }) => {
-          const fullPath = subcategory ? `${category}.${subcategory}.${path4}` : `${category}.${path4}`;
+        const tokensWithCssVars = flat.map(({ path: path2, value }) => {
+          const fullPath = subcategory ? `${category}.${subcategory}.${path2}` : `${category}.${path2}`;
           let cssVar;
           if (category === "colors" && subcategory === "static.brand") {
-            cssVar = data.cssVariables[`--atmx-color-brand-${path4}`];
+            cssVar = data.cssVariables[`--atmx-color-brand-${path2}`];
           } else if (category === "colors" && subcategory?.startsWith("modes.")) {
-            cssVar = data.cssVariables[`--atmx-color-${path4}`];
+            cssVar = data.cssVariables[`--atmx-color-${path2}`];
           } else {
             const cssVarKey = `--atmx-${fullPath.replace(/\./g, "-")}`;
             cssVar = data.cssVariables[cssVarKey];
@@ -2887,30 +2188,63 @@ Version: ${designSystemData.meta.version}`,
           }]
         };
       }
-      case "getAIToolRules": {
-        const tool = args?.tool;
-        const rulesUrl = `${apiBase}/api/ds/${dsId}/rules?format=${tool === "all" ? "all" : tool}`;
-        console.error(`[getAIToolRules] Fetching: ${rulesUrl}`);
+      case "getRules": {
+        const topicRaw = args?.topic;
+        const topic = topicRaw?.toLowerCase().trim();
+        const rulesUrl = `${apiBase}/api/ds/${dsId}/rules?format=json`;
+        console.error(`[getRules] Fetching: ${rulesUrl}${topic ? ` topic=${topic}` : ""}`);
         const headers = { "Content-Type": "application/json" };
         if (apiKey) headers["x-api-key"] = apiKey;
         try {
           const response = await fetch(rulesUrl, { headers });
-          console.error(`[getAIToolRules] Response status: ${response.status}`);
+          console.error(`[getRules] Response status: ${response.status}`);
           if (!response.ok) {
             const errorText = await response.text();
-            console.error(`[getAIToolRules] Error response: ${errorText}`);
+            console.error(`[getRules] Error response: ${errorText}`);
             throw new Error(`Failed to fetch rules: ${response.status} - ${errorText}`);
           }
-          const rules = await response.json();
-          console.error(`[getAIToolRules] Got ${rules.rules?.length || 0} rules`);
+          const payload = await response.json();
+          const categories = payload.categories ?? {};
+          const allRules = payload.rules ?? [];
+          if (!topic) {
+            return {
+              content: [{ type: "text", text: JSON.stringify({ rules: allRules, categories }, null, 2) }]
+            };
+          }
+          const topicToCategories = {
+            colors: ["general", "colors"],
+            typo: ["general", "typography"],
+            typography: ["general", "typography"],
+            motion: ["general", "motion"],
+            icons: ["general", "icons"],
+            layout: ["general", "spacing", "sizing", "layout"],
+            visual: ["general", "colors", "borders", "radius", "shadows", "icons"],
+            style: ["general", "colors", "borders", "radius", "shadows", "icons"]
+          };
+          const categoryKeys = topicToCategories[topic];
+          if (!categoryKeys) {
+            return {
+              content: [{ type: "text", text: JSON.stringify({ rules: allRules, categories }, null, 2) }]
+            };
+          }
+          const filteredCategories = {};
+          const filteredRules = [];
+          for (const key of categoryKeys) {
+            const list = categories[key];
+            if (list && list.length > 0) {
+              filteredCategories[key] = list;
+              filteredRules.push(...list);
+            }
+          }
+          console.error(`[getRules] Got ${filteredRules.length} rules for topic=${topic}`);
           return {
             content: [{
               type: "text",
-              text: JSON.stringify(rules, null, 2)
+              text: JSON.stringify({ rules: filteredRules, categories: filteredCategories }, null, 2)
             }]
           };
         } catch (fetchError) {
-          console.error(`[getAIToolRules] Fetch error:`, fetchError);
+          console.error(`[getRules] Fetch error:`, fetchError);
           throw fetchError;
         }
       }
@@ -2995,7 +2329,7 @@ Version: ${designSystemData.meta.version}`,
           copilot: `# Copilot Setup
 
 1. Create a Copilot instructions file in your project (e.g. \`.github/copilot-instructions.md\`)
-2. Use getAIToolRules({ tool: "copilot" }) to get the content
+2. Run /--sync to write the skill; call getRules() when you need governance rules
 3. Enable custom instructions in your editor (e.g. \`github.copilot.chat.codeGeneration.useInstructionFiles\`: true in settings)
 
 ## File Structure
@@ -3009,7 +2343,7 @@ Version: ${designSystemData.meta.version}`,
           windsurf: `# Windsurf Setup
 
 1. Create \`.windsurf/mcp.json\` in your project root
-2. Create \`.windsurfrules\` with rules from getAIToolRules
+2. Run /--sync to write the skill; call getRules() when you need governance rules
 3. Restart Windsurf Editor
 
 ## File Structure
@@ -3050,7 +2384,7 @@ Version: ${designSystemData.meta.version}`,
           zed: `# Zed Setup
 
 1. Create \`.zed/assistant/rules.md\` in your project
-2. Use getAIToolRules({ tool: "zed" }) for content
+2. Run /--sync to write the skill; call getRules() for governance rules
 
 ## File Structure
 
@@ -3078,9 +2412,8 @@ Version: ${designSystemData.meta.version}`,
 **Best Practice**: Keep \`tokens.css\` separate from your custom CSS. Use a separate file (e.g., \`custom.css\`) for custom styles.`,
           generic: `# Generic AI Tool Setup
 
-1. Create AI_GUIDELINES.md in your project root
-2. Use getAIToolRules({ tool: "generic" }) for content
-3. Reference in your prompts or context
+1. Run /--sync to write the skill (.cursor/skills/atomix-ds/SKILL.md)
+2. Call getRules() when you need governance rules; reference in your prompts or context
 
 ## File Structure
 
@@ -3115,16 +2448,18 @@ Version: ${designSystemData.meta.version}`,
         const dryRun = args?.dryRun === true;
         const output = args?.output || "./tokens.css";
         const format = args?.format || "css";
+        const projectRoot = path.resolve(
+          args?.workspaceRoot || process.env.ATOMIX_PROJECT_ROOT || process.cwd()
+        );
         const parts = [dryRun ? "[DRY RUN] syncAll report (no files written)." : "\u2713 syncAll complete."];
         let tokenResponseText = "";
         const allValidation = [];
+        let tokenSyncChangeSummary;
         if (!skipTokens) {
-          const result = await performTokenSyncAndRules(data, output, format, dryRun);
+          const result = await performTokenSyncAndRules(data, output, format, dryRun, projectRoot);
           tokenResponseText = result.responseText;
           allValidation.push(...result.validation);
-          if (!dryRun && result.rulesResults.length > 0) {
-            parts.push(`Rules: ${result.rulesResults.map((r) => r.path).join(", ")}`);
-          }
+          tokenSyncChangeSummary = result.tokenSyncChangeSummary;
           if (dryRun) {
             parts.push(`Would write tokens: ${output} (${format})`);
           } else {
@@ -3133,11 +2468,12 @@ Version: ${designSystemData.meta.version}`,
         }
         const dsVersion = String(data.meta.version ?? "1.0.0");
         const dsExportedAt = data.meta.exportedAt;
-        const skillsDir = path2.resolve(process.cwd(), ".cursor/skills/atomix-ds");
-        const skillPath1 = path2.join(skillsDir, "SKILL.md");
-        const manifestPath = path2.resolve(process.cwd(), "atomix-dependencies.json");
+        const skillsDir = path.resolve(projectRoot, ".cursor/skills/atomix-ds");
+        const manifestPath = path.resolve(projectRoot, "atomix-dependencies.json");
+        const dependencySkills = getSyncDependencySkills(data, dsVersion, dsExportedAt);
         if (dryRun) {
-          parts.push("Would write skills: .cursor/skills/atomix-ds/SKILL.md");
+          const skillList = dependencySkills.map((s) => s.path).join(", ");
+          parts.push(`Would write skills: ${skillList}`);
           parts.push("Would write manifest: atomix-dependencies.json");
           const reportText = [parts.join("\n"), tokenResponseText].filter(Boolean).join("\n\n---\n\n");
           return {
@@ -3146,11 +2482,19 @@ Version: ${designSystemData.meta.version}`,
 ${reportText}` }]
           };
         }
-        if (!fs2.existsSync(skillsDir)) fs2.mkdirSync(skillsDir, { recursive: true });
-        const genericWithVersion = injectSkillVersion(GENERIC_SKILL_MD, dsVersion, dsExportedAt);
-        fs2.writeFileSync(skillPath1, genericWithVersion);
-        allValidation.push({ path: skillPath1, status: fs2.existsSync(skillPath1) ? "OK" : "FAIL", detail: "Written." });
-        parts.push("Skills: .cursor/skills/atomix-ds/SKILL.md (synced at DS v" + dsVersion + ")");
+        if (!fs.existsSync(skillsDir)) fs.mkdirSync(skillsDir, { recursive: true });
+        const skillsWritten = [];
+        for (const sk of dependencySkills) {
+          const absPath = path.resolve(projectRoot, sk.path);
+          const existed = fs.existsSync(absPath);
+          const prevVersion = existed ? readSkillVersionFromFile(absPath) : null;
+          const fromLabel = existed ? prevVersion ? `DS v${prevVersion}` : "existing" : "missing";
+          fs.writeFileSync(absPath, sk.content);
+          allValidation.push({ path: absPath, status: fs.existsSync(absPath) ? "OK" : "FAIL", detail: "Written." });
+          skillsWritten.push({ path: sk.path, shortName: sk.shortName, from: fromLabel });
+        }
+        const skillShortNames = skillsWritten.map((s) => s.shortName).join(" + ");
+        parts.push(`Skills: ${skillShortNames} (DS v${dsVersion})`);
         const tokens = data.tokens;
         const typography = tokens?.typography;
         const fontFamily = typography?.fontFamily;
@@ -3169,6 +2513,10 @@ ${reportText}` }]
         };
         const lib = icons?.library || "lucide";
         const iconPkgs = ICON_PACKAGES[lib] || ICON_PACKAGES.lucide;
+        const skillsManifestEntry = { skill: ".cursor/skills/atomix-ds/SKILL.md", syncedAtVersion: String(data.meta.version ?? "1.0.0") };
+        if (dependencySkills.some((s) => s.shortName === "figma-design-SKILL.md")) {
+          skillsManifestEntry.figmaDesignSkill = ".cursor/skills/atomix-ds/figma-design-SKILL.md";
+        }
         const manifest = {
           designSystem: { name: data.meta.name, version: data.meta.version },
           tokenFile: skipTokens ? void 0 : output,
@@ -3179,23 +2527,67 @@ ${reportText}` }]
             strokeWidthValue: icons?.strokeWidth
           },
           fonts: { families: fontNames },
-          skills: {
-            skill: ".cursor/skills/atomix-ds/SKILL.md",
-            syncedAtVersion: data.meta.version ?? "1.0.0"
-          }
+          skills: skillsManifestEntry
         };
-        fs2.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
-        allValidation.push({ path: manifestPath, status: fs2.existsSync(manifestPath) ? "OK" : "FAIL", detail: "Written." });
+        const manifestExisted = fs.existsSync(manifestPath);
+        fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+        allValidation.push({ path: manifestPath, status: fs.existsSync(manifestPath) ? "OK" : "FAIL", detail: "Written." });
         parts.push("Manifest: atomix-dependencies.json (icons, fonts, skill paths)");
+        const changeRows = [];
+        if (!skipTokens && tokenSyncChangeSummary) {
+          const fromStr = tokenSyncChangeSummary.fileExisted && tokenSyncChangeSummary.previousVarCount != null ? `${tokenSyncChangeSummary.previousVarCount} tokens in ${output}` : "missing";
+          changeRows.push({
+            what: "Tokens",
+            from: fromStr,
+            to: `${tokenSyncChangeSummary.currentVarCount} tokens in ${output} (${format})`
+          });
+        }
+        const skillsFrom = skillsWritten.length ? skillsWritten.every((s) => s.from === "missing") ? "missing" : "updated" : "";
+        if (skillsWritten.length > 0) {
+          changeRows.push({
+            what: "Skills",
+            from: skillsFrom,
+            to: `${skillShortNames} (DS v${dsVersion})`
+          });
+        }
+        changeRows.push({
+          what: "Manifest",
+          from: manifestExisted ? "existing" : "missing",
+          to: "atomix-dependencies.json"
+        });
+        if (lastSyncAffectedTokens && (lastSyncAffectedTokens.modified.length > 0 || lastSyncAffectedTokens.added.length > 0 || lastSyncAffectedTokens.removed.length > 0)) {
+          const mod = lastSyncAffectedTokens.modified;
+          const add = lastSyncAffectedTokens.added;
+          const rem = lastSyncAffectedTokens.removed;
+          const tokenNames = [
+            ...mod.map((m) => m.token),
+            ...add,
+            ...rem.map((r) => r.token)
+          ];
+          const fromParts = [];
+          if (mod.length) fromParts.push(`${mod.length} modified`);
+          if (add.length) fromParts.push(`${add.length} added`);
+          if (rem.length) fromParts.push(`${rem.length} removed`);
+          const toDetail = tokenNames.length <= 8 ? tokenNames.join(", ") : `${tokenNames.length} tokens (${tokenNames.slice(0, 4).join(", ")}...)`;
+          changeRows.push({
+            what: "Token changes (this run)",
+            from: fromParts.join(", ") || "\u2014",
+            to: toDetail
+          });
+          if (mod.length > 0 && mod.length <= 15) {
+            mod.forEach((m) => {
+              changeRows.push({ what: `  ${m.token}`, from: m.oldValue, to: m.newValue });
+            });
+          }
+        }
+        const changesList = "Report the following changes to the user (From \u2192 To). Do not mention what did not change.\n\n**Changes applied**\n\n" + changeRows.map((r) => `\u2022 **${r.what}:** ${r.from} \u2192 ${r.to}`).join("\n");
         const summary = parts.join("\n");
         const validationBlock = formatValidationBlock(allValidation);
         const hasFailure = allValidation.some((e) => e.status === "FAIL");
         const resultLine = hasFailure ? "syncAllResult: FAIL \u2014 Check VALIDATION section below. Do not report success to the user.\n\n" : "syncAllResult: OK\n\n";
-        const fullText = resultLine + (tokenResponseText ? `${summary}
-
----
+        const fullText = resultLine + changesList + "\n\n" + (tokenResponseText ? `---
 
-${tokenResponseText}${validationBlock}` : `${summary}${validationBlock}`);
+${tokenResponseText}` : "") + validationBlock;
         return {
           content: [{ type: "text", text: fullText }]
         };
@@ -3233,10 +2625,17 @@ ${tokenResponseText}${validationBlock}` : `${summary}${validationBlock}`);
             families: fontNames,
             performanceHint: "Link fonts via URL (e.g. Google Fonts <link> or CSS @import); no need to download font files or add them to the repo. Prefer font-display: swap when possible. You must also build a complete typeset CSS: call listTypesets to get every typeset from the design system, then emit one CSS class per typeset (do not skip any). For each class set font-family, font-size, font-weight, line-height, letter-spacing; when the typeset has text-transform or text-decoration, set those too so the result is 1:1 with the DS. Use the CSS variable names returned by listTypesets. Do not create a file that only contains a font import."
           },
-          skill: {
-            path: ".cursor/skills/atomix-ds/SKILL.md",
-            content: GENERIC_SKILL_MD
-          },
+          skill: (() => {
+            const list = getSyncDependencySkills(data, String(data.meta.version ?? "1.0.0"), data.meta.exportedAt);
+            const generic = list.find((s) => s.shortName === "SKILL.md");
+            return generic ? { path: generic.path, content: GENERIC_SKILL_MD } : { path: ".cursor/skills/atomix-ds/SKILL.md", content: GENERIC_SKILL_MD };
+          })(),
+          ...getEffectiveTier() === "pro" ? {
+            skillFigmaDesign: {
+              path: ".cursor/skills/atomix-ds/figma-design-SKILL.md",
+              content: FIGMA_DESIGN_SKILL_MD
+            }
+          } : {},
           tokenFiles: {
             files: ["tokens.css", "tokens.json"],
             copyInstructions: "Call the syncAll MCP tool to create the token file, skills, and atomix-dependencies.json; do not only suggest the user run sync later."
@@ -3244,7 +2643,7 @@ ${tokenResponseText}${validationBlock}` : `${summary}${validationBlock}`);
           showcase: platform2 === "web" || !platform2 ? {
             path: "atomix-setup-showcase.html",
             template: SHOWCASE_HTML_TEMPLATE,
-            substitutionInstructions: 'Replace placeholders with values from the synced token file. MCP/sync/export use the --atmx- prefix. {{TOKENS_CSS_PATH}} = path to the synced token file (e.g. ./tokens.css, same as syncAll output). {{TYPESETS_LINK}} = if a typeset CSS file was created (e.g. typesets.css), the full tag e.g. <link rel="stylesheet" href="typesets.css">, otherwise empty string. {{DS_NAME}} = design system name. {{BRAND_PRIMARY_VAR}} = var(--atmx-color-brand-primary). {{BRAND_PRIMARY_FOREGROUND_VAR}} = var(--atmx-color-brand-primary-foreground). {{HEADING_FONT_VAR}} = var(--atmx-typography-font-family-heading) or var(--atmx-typography-font-family-display). {{FONT_FAMILY_VAR}} = var(--atmx-typography-font-family-body). {{LARGEST_DISPLAY_TYPESET_CLASS}} = largest display typeset class from listTypesets (display role, largest font size; e.g. typeset-display-2xl or typeset-display-bold), or empty string if no typeset file. {{BODY_TYPESET_CLASS}} = typeset class for body text from listTypesets (e.g. typeset-body-md), or empty string if no typeset file. {{FONT_LINK_TAG}} = Google Fonts <link> for the font, or empty string. Do not invent CSS variable names; use only vars that exist in the export.'
+            substitutionInstructions: 'The synced token file (from syncAll) always uses the --atmx- prefix for every CSS variable. Keep all var(--atmx-*) references in the template; do not remove or change the prefix. Replace placeholders with values from the synced token file. {{TOKENS_CSS_PATH}} = path to the synced token file (e.g. ./tokens.css). {{TYPESETS_LINK}} = if a typeset CSS file was created, the full <link rel=\\"stylesheet\\" href=\\"typesets.css\\"> tag, otherwise empty string. {{DS_NAME}} = design system name. {{HEADING_FONT_VAR}} = var(--atmx-typography-font-family-heading) or var(--atmx-typography-font-family-display). {{FONT_FAMILY_VAR}} = var(--atmx-typography-font-family-body). {{LARGEST_DISPLAY_TYPESET_CLASS}} = largest display typeset class from listTypesets (display role, largest font size; e.g. typeset-display-2xl), or empty string if no typeset file. {{LARGEST_BODY_TYPESET_CLASS}} = largest body typeset class from listTypesets (body role, largest font size; e.g. typeset-body-lg), or empty string if no typeset file. {{BODY_TYPESET_CLASS}} = default body typeset class from listTypesets (e.g. typeset-body-md), or empty string. {{FONT_LINK_TAG}} = Google Fonts <link> for the font, or empty string. {{BRAND_PRIMARY_VAR}} = var(--atmx-color-brand-primary). Icon on circle uses luminance of brand primary (script sets white or black); no semantic foreground var. {{BUTTON_PADDING_VAR}} = var(--atmx-spacing-scale-md) or closest spacing token for button padding. {{BUTTON_HEIGHT_VAR}} = var(--atmx-sizing-height-md) or closest height token. {{BUTTON_RADIUS_VAR}} = var(--atmx-radius-scale-md) or var(--atmx-radius-scale-lg). {{CIRCLE_PADDING_VAR}} = var(--atmx-spacing-scale-md) or var(--atmx-spacing-scale-sm) for icon circle padding. {{ICON_SIZE_VAR}} = var(--atmx-sizing-icon-md) or var(--atmx-sizing-icon-lg). {{CHECK_ICON_SVG}} = inline SVG for Check icon from the design system icon library (getDependencies.iconLibrary.package: lucide-react, @heroicons/react, or phosphor-react). Use 24x24 viewBox; stroke=\\"currentColor\\" for Lucide/Heroicons, fill=\\"currentColor\\" for Phosphor so the script can set icon color by luminance. If unavailable, use: <svg xmlns=\\"http://www.w3.org/2000/svg\\" viewBox=\\"0 0 24 24\\" fill=\\"none\\" stroke=\\"currentColor\\" stroke-width=\\"2\\" stroke-linecap=\\"round\\" stroke-linejoin=\\"round\\"><path d=\\"M20 6L9 17l-5-5\\"/></svg>. Do not invent CSS variable names; use only vars that exist in the export.'
           } : void 0,
           meta: {
             dsName: data.meta.name,
@@ -3461,13 +2860,282 @@ ${JSON.stringify(out, null, 2)}` : JSON.stringify(out, null, 2);
           ...out.error ? { isError: true } : {}
         };
       }
+      case "designInFigma": {
+        if (cachedMcpTier !== "pro") {
+          return {
+            content: [{ type: "text", text: JSON.stringify({ error: "designInFigma requires a Pro subscription. Upgrade at https://atomix.studio" }, null, 2) }],
+            isError: true
+          };
+        }
+        const action = args?.action;
+        if (action === "catalog") {
+          try {
+            const reachable = await isBridgeReachable();
+            let fileCtx;
+            if (reachable) {
+              try {
+                const raw = await sendBridgeRequest("get_figma_variables_and_styles", {});
+                fileCtx = raw;
+              } catch {
+              }
+            }
+            const localVars = [];
+            const libVars = [];
+            const textStyleNames = [];
+            const effectStyleNames = [];
+            if (fileCtx) {
+              for (const coll of fileCtx.variableCollections ?? []) {
+                for (const v of coll.variables) localVars.push(v.name);
+              }
+              for (const coll of fileCtx.variableCollectionsLibrary ?? []) {
+                for (const v of coll.variables) libVars.push(v.name);
+              }
+              for (const s of fileCtx.textStyles ?? []) textStyleNames.push(s.name);
+              for (const s of fileCtx.effectStyles ?? []) effectStyleNames.push(s.name);
+            }
+            const catalogPayload = formatCatalogForMCP(FIGMA_DESIGN_CATALOG, {
+              localVariables: localVars,
+              libraryVariables: libVars,
+              textStyles: textStyleNames,
+              effectStyles: effectStyleNames
+            });
+            let designAssets = void 0;
+            if (reachable) {
+              try {
+                const raw = await sendBridgeRequest("get_component_catalog", {});
+                if (raw && typeof raw === "object") {
+                  designAssets = raw;
+                }
+              } catch {
+              }
+            }
+            return {
+              content: [{
+                type: "text",
+                text: JSON.stringify({
+                  ...catalogPayload,
+                  pluginConnected: reachable,
+                  ...designAssets ? { designAssets } : {},
+                  ...reachable ? {
+                    queryMethods: getQueryMethodNames(),
+                    queryHint: "Use action:'query' with queryMethod (e.g. get_selection, get_node_info, get_design_screenshot) and optional queryParams to read selection, node details, or a frame screenshot for review."
+                  } : {},
+                  ...reachable ? {} : { hint: "Figma plugin not connected. Open Figma, run Atomix plugin, and tap Connect." }
+                }, null, 2)
+              }]
+            };
+          } catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            return { content: [{ type: "text", text: JSON.stringify({ error: msg }, null, 2) }], isError: true };
+          }
+        }
+        if (action === "query") {
+          const queryMethodRaw = args?.queryMethod;
+          const queryParams = args?.queryParams ?? {};
+          if (!queryMethodRaw || typeof queryMethodRaw !== "string") {
+            return {
+              content: [{ type: "text", text: JSON.stringify({ error: "query requires queryMethod (e.g. get_selection, get_node_info, get_design_screenshot)" }, null, 2) }],
+              isError: true
+            };
+          }
+          const queryMethod = queryMethodRaw.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
+          const allowedQueryMethods = new Set(getQueryMethodNames());
+          if (!allowedQueryMethods.has(queryMethod)) {
+            return {
+              content: [{ type: "text", text: JSON.stringify({ error: `Unknown query method "${queryMethod}". Allowed: ${[...allowedQueryMethods].join(", ")}` }, null, 2) }],
+              isError: true
+            };
+          }
+          try {
+            const reachable = await isBridgeReachable();
+            if (!reachable) {
+              return {
+                content: [{
+                  type: "text",
+                  text: JSON.stringify({
+                    error: "Figma plugin not connected.",
+                    bridgeNotRunning: true,
+                    agentInstruction: "Run the Atomix plugin in Figma and tap Connect, then call designInFigma with action:'query' again."
+                  }, null, 2)
+                }],
+                isError: true
+              };
+            }
+            const result = await sendBridgeRequest(queryMethod, queryParams);
+            const content = [];
+            const summary = { method: queryMethod, success: true };
+            if (result && typeof result === "object" && "imageBase64" in result && typeof result.imageBase64 === "string") {
+              summary.screenshot = "included below (base64 PNG)";
+              summary.format = result.format ?? "PNG";
+              summary.scale = result.scale;
+              content.push({ type: "text", text: JSON.stringify(summary, null, 2) });
+              content.push({
+                type: "image",
+                data: result.imageBase64,
+                mimeType: "image/png"
+              });
+            } else {
+              summary.result = result;
+              content.push({ type: "text", text: JSON.stringify(summary, null, 2) });
+            }
+            return { content };
+          } catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            return { content: [{ type: "text", text: JSON.stringify({ method: queryMethod, success: false, error: msg }, null, 2) }], isError: true };
+          }
+        }
+        if (action === "execute") {
+          const rawSteps = args?.steps;
+          if (!rawSteps || !Array.isArray(rawSteps) || rawSteps.length === 0) {
+            return {
+              content: [{ type: "text", text: JSON.stringify({ error: "steps array is required for action:'execute'" }, null, 2) }],
+              isError: true
+            };
+          }
+          try {
+            const reachable = await isBridgeReachable();
+            if (!reachable) {
+              return {
+                content: [{
+                  type: "text",
+                  text: JSON.stringify({
+                    error: "Figma plugin not connected.",
+                    bridgeNotRunning: true,
+                    agentInstruction: "Run the Atomix plugin in Figma and tap Connect, then call designInFigma again."
+                  }, null, 2)
+                }],
+                isError: true
+              };
+            }
+            const designMethods = /* @__PURE__ */ new Set([
+              ...getDesignMethodNames(),
+              "list_local_components",
+              "get_component_catalog",
+              "get_design_screenshot",
+              "get_variable_collection_modes",
+              "get_frame_variable_mode"
+            ]);
+            const warnings = [];
+            let fileCtx;
+            try {
+              const raw = await sendBridgeRequest("get_figma_variables_and_styles", {});
+              fileCtx = raw;
+            } catch {
+            }
+            const resolvers = fileCtx ? buildResolvers(fileCtx) : null;
+            const isFigmaNodeId = (s) => /^\d+:\d+$/.test(s);
+            let rootFrameId = null;
+            let lastCreatedFrameNodeId = null;
+            const namedNodeIds = /* @__PURE__ */ new Map();
+            const results = [];
+            for (let i = 0; i < rawSteps.length; i++) {
+              const step = rawSteps[i];
+              const method = (step.method ?? "").replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
+              if (!designMethods.has(method)) {
+                warnings.push({ step: i, method, issue: `Unknown method "${method}" \u2014 skipped` });
+                continue;
+              }
+              let params = { ...step.params ?? {} };
+              if (resolvers) {
+                params = resolveStepParams(params, resolvers);
+              }
+              if (rootFrameId) {
+                const parentId = params.parentId;
+                const frameId = params.frameId;
+                if (typeof parentId === "string" && !isFigmaNodeId(parentId)) {
+                  params.parentId = namedNodeIds.get(parentId) ?? rootFrameId;
+                }
+                if (typeof frameId === "string" && !isFigmaNodeId(frameId)) {
+                  params.frameId = namedNodeIds.get(frameId) ?? rootFrameId;
+                }
+                if (method === "finalize_design_frame" && !params.frameId) {
+                  params.frameId = rootFrameId;
+                }
+                const needsParent = method.startsWith("design_create_") || method === "design_create_component";
+                if (needsParent && !params.parentId) {
+                  params.parentId = rootFrameId;
+                }
+              }
+              const nodeId = params.nodeId;
+              if (typeof nodeId === "string" && nodeId && !isFigmaNodeId(nodeId)) {
+                const resolved = namedNodeIds.get(nodeId) ?? lastCreatedFrameNodeId ?? rootFrameId;
+                params.nodeId = resolved ?? nodeId;
+              }
+              const needsNode = [
+                "design_set_auto_layout",
+                "design_set_layout_sizing",
+                "design_set_effects",
+                "design_set_strokes",
+                "design_resize_node",
+                "design_set_resize_constraints",
+                "design_set_layout_constraints",
+                "design_set_node_position",
+                "design_set_text_properties"
+              ].includes(method);
+              if (needsNode && !params.nodeId) {
+                params.nodeId = lastCreatedFrameNodeId ?? rootFrameId;
+              }
+              const childId = params.childId;
+              if (typeof childId === "string" && childId && !isFigmaNodeId(childId)) {
+                params.childId = namedNodeIds.get(childId) ?? childId;
+              }
+              try {
+                const response = await sendBridgeRequest(method, params);
+                const res = response;
+                if (method === "create_design_placeholder" && typeof res?.frameId === "string") {
+                  rootFrameId = res.frameId;
+                }
+                const isCreateMethod = method.startsWith("design_create_") || method === "design_convert_to_component" || method === "design_combine_as_variants" || method === "design_create_frame_from_preset" || method === "design_group_nodes";
+                if (isCreateMethod && typeof res?.nodeId === "string") {
+                  const createdNodeId = res.nodeId;
+                  if (method === "design_create_frame" || method === "design_create_frame_from_preset") {
+                    lastCreatedFrameNodeId = createdNodeId;
+                    if (!rootFrameId && res?.isRoot === true) {
+                      rootFrameId = createdNodeId;
+                    }
+                  }
+                  const stepName = step.params?.name ?? "";
+                  if (stepName) namedNodeIds.set(stepName, createdNodeId);
+                }
+                results.push({ step: i, method, result: response });
+              } catch (e) {
+                const errMsg = e instanceof Error ? e.message : String(e);
+                results.push({ step: i, method, error: errMsg });
+                if (!rootFrameId && (method === "design_create_frame" || method === "create_design_placeholder")) break;
+              }
+            }
+            const errorCount = results.filter((r) => r.error).length;
+            const success = errorCount === 0;
+            return {
+              content: [{
+                type: "text",
+                text: JSON.stringify({
+                  success,
+                  stepsExecuted: results.length,
+                  errors: errorCount,
+                  warnings,
+                  results
+                }, null, 2)
+              }],
+              ...errorCount > 0 ? { isError: true } : {}
+            };
+          } catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            return { content: [{ type: "text", text: JSON.stringify({ error: msg }, null, 2) }], isError: true };
+          }
+        }
+        return {
+          content: [{ type: "text", text: JSON.stringify({ error: "action must be 'catalog', 'query', or 'execute'" }, null, 2) }],
+          isError: true
+        };
+      }
       default:
         return {
           content: [{
             type: "text",
             text: JSON.stringify({
               error: `Unknown tool: ${name}`,
-              availableTools: ["getToken", "listTokens", "listTypesets", "searchTokens", "validateUsage", "getAIToolRules", "exportMCPConfig", "getSetupInstructions", "syncAll", "getDependencies", "syncToFigma"]
+              availableTools: ["getToken", "listTokens", "listTypesets", "searchTokens", "validateUsage", "getRules", "exportMCPConfig", "getSetupInstructions", "syncAll", "getDependencies", "getMcpVersion", "syncToFigma", "designInFigma"]
             }, null, 2)
           }]
         };
@@ -3509,6 +3177,43 @@ ${JSON.stringify(out, null, 2)}` : JSON.stringify(out, null, 2);
     };
   }
 });
+function getEffectiveTier() {
+  return cachedMcpTier;
+}
+function getSyncDependencySkills(data, dsVersion, dsExportedAt) {
+  const tier = getEffectiveTier();
+  const skills = [];
+  const genericWithVersion = injectSkillVersion(GENERIC_SKILL_MD, dsVersion, dsExportedAt);
+  skills.push({
+    path: ".cursor/skills/atomix-ds/SKILL.md",
+    content: genericWithVersion,
+    shortName: "SKILL.md"
+  });
+  if (tier === "pro") {
+    const figmaSkillWithFrontmatter = `---
+name: atomix-figma-design
+description: Figma design skill \u2014 create high-quality, token-bound designs in Figma from any reference (screenshots, images, code snippets, URLs). Covers mobile, web, token application, and component/variant creation. Use with syncToFigma and designInFigma MCP tools when the Atomix plugin is connected.
+---
+${FIGMA_DESIGN_SKILL_MD}`;
+    const figmaSkillWithVersion = injectSkillVersion(figmaSkillWithFrontmatter, dsVersion, dsExportedAt);
+    skills.push({
+      path: ".cursor/skills/atomix-ds/figma-design-SKILL.md",
+      content: figmaSkillWithVersion,
+      shortName: "figma-design-SKILL.md"
+    });
+  }
+  return skills;
+}
+function readSkillVersionFromFile(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  try {
+    const raw = fs.readFileSync(filePath, "utf-8");
+    const match = raw.match(/atomixDsVersion:\s*["']([^"']+)["']/);
+    return match ? match[1] : null;
+  } catch {
+    return null;
+  }
+}
 function injectSkillVersion(content, version, exportedAt) {
   const endOfFrontmatter = content.indexOf("\n---\n", 3);
   if (endOfFrontmatter === -1) return content;
@@ -3521,51 +3226,124 @@ atomixDsExportedAt: "${exportedAt ?? ""}"
 }
 var GENERIC_SKILL_MD = `---
 name: atomix-ds
-description: Use the Atomix design system for UI, tokens, and styles. Fetch rules and tokens via MCP tools; never hardcode design values.
+description: Use the project's design system tokens semantically when building or editing any UI. Covers everyday tasks \u2014 creating components, building pages, styling forms, theming, dark mode, responsive layouts, adding icons, choosing colors, setting type, adjusting spacing, and applying motion. Works with any platform or framework (web, React Native, iOS, Android, Flutter, etc.). Fetch token values and governance rules via MCP tools (getToken, listTokens, searchTokens, getRules, validateUsage). Tokens include colors, typography, spacing, sizing, radius, shadows, borders, motion, z-index, and icons. Never hardcode visual values \u2014 always resolve from the design system first.
 ---
 
 # Atomix Design System
 
-Use this skill when editing UI, design system files, or when the user asks to follow the project's design system. Your job is to **get the relevant data from the design system via MCP** and apply it\u2014not to guess or invent values.
+**Prerequisite:** Load rules first before anything else \u2014 call getRules() at the start of the session or before writing any visual code.
 
-## Goal
-
-Complete the user's task using the design system as the single source of truth. Every color, spacing, typography, radius, shadow, or sizing value must come from the MCP tools (tokens or governance rules). Do not hardcode hex codes, pixel values, or font names.
+This project uses a design system with semantic tokens. **Before writing any visual code**, fetch the relevant tokens and governance rules from the MCP tools below. The design system is the single source of truth \u2014 do not guess, invent, or hardcode visual values.
 
 ## When to use
 
-- Building or editing UI components, pages, or styles
-- Working in design system or token files (e.g. \`tokens.css\`, theme files)
-- User asks to "follow the design system", "use tokens", or "match the DS"
-- Validating or refactoring existing code, UI or visual design for token compliance
+Use this skill for everyday design and frontend tasks:
+
+**Building UI**
+- Creating a component (button, card, input, modal, nav, sidebar, table, list, badge, tooltip\u2026)
+- Laying out a page, screen, or view
+- Building a form, dialog, popover, or overlay
+- Adding a header, footer, hero section, or onboarding flow
+
+**Styling & theming**
+- Choosing colors for backgrounds, text, borders, icons, or interactive states
+- Setting typography \u2014 font family, size, weight, line height, letter spacing
+- Adjusting spacing, padding, margins, or gaps between elements
+- Applying border radius, shadows, or elevation to surfaces
+- Adding hover, focus, active, disabled, or loading states
+- Setting up dark mode, light mode, or theme switching
+- Configuring responsive or adaptive layouts
+
+**Working with assets**
+- Rendering icons (sizing and stroke width are defined by the design system)
+- Implementing designs from Figma, mockups, screenshots, or design specs
+- Translating a design handoff into code
+
+**Maintenance**
+- Refactoring hardcoded values to use tokens
+- Auditing code for design system compliance
+- Updating styles after a design system version change
+
+If the task has no visual output (pure logic, data, APIs, DevOps), this skill is not needed.
+
+## Semantic token usage
+
+Tokens have two layers \u2014 **primitives** (raw scales) and **semantic** (purpose-driven). Always prefer semantic tokens because they adapt to themes and modes automatically.
+
+| Intent | Use semantic token | Avoid raw primitive |
+|--------|-------------------|---------------------|
+| Page background | \`bg-page\` | \`neutral.50\` |
+| Card surface | \`bg-surface\` | \`white\` |
+| Primary text | \`text-primary\` | \`neutral.900\` |
+| Muted text | \`text-muted\` | \`neutral.500\` |
+| Default border | \`border-default\` | \`neutral.200\` |
+| Brand action | \`brand.primary\` | \`green.600\` |
+| Error state | \`status.error\` | \`red.500\` |
+
+Call \`getRules\` for the full mapping of semantic tokens to primitives in each theme.
+
+When a semantic token doesn't exist for your use case, use the closest primitive from \`listTokens\` \u2014 but document why so the team can promote it to a semantic token later.
+
+## How to fetch design system data
+
+### 1. Governance rules \u2014 always fetch first
 
-## How to get design system data
+\`getRules()\` \u2014 optionally with a topic: \`colors\`, \`typo\`, \`motion\`, \`icons\`, \`layout\`, or \`visual\` (color, border, radius, shadows, icons). Returns how tokens should be applied \u2014 naming conventions, variable format, and semantic mappings.
 
-**1. Governance rules (how to use tokens in code)**  
-Call **getAIToolRules** with the tool id for your current environment: \`cursor\`, \`windsurf\`, \`copilot\`, \`cline\`, \`continue\`, \`zed\`, or \`generic\`.  
-Example: \`getAIToolRules({ tool: "cursor" })\`.  
-Alternatively use the **/--rules** prompt or the resource \`atomix://rules/<tool>\`.
+### 2. Token values \u2014 by task
 
-**2. Token values (what to use in code)**  
-- **getToken(path)** \u2014 One token by path (e.g. \`colors.brand.primary\`, \`typography.fontSize.lg\`, \`sizing.icon.sm\`, \`icons.strokeWidth\`). Icon stroke width is at \`icons.strokeWidth\` when the design system defines it.
-- **listTokens(category)** \u2014 All tokens in a category: \`colors\`, \`typography\`, \`spacing\`, \`sizing\`, \`shadows\`, \`radius\`, \`borders\`, \`motion\`, \`zIndex\`. For icon config (e.g. stroke width), use \`getToken("icons.strokeWidth")\` since \`icons\` is not a list category.
-- **searchTokens(query)** \u2014 Find tokens by name or value.
+| I need\u2026 | MCP call |
+|---------|----------|
+| A specific token | \`getToken("colors.brand.primary")\` or \`getToken("spacing.scale.md")\` |
+| All tokens in a category | \`listTokens("colors")\` \u2014 categories: \`colors\`, \`typography\`, \`spacing\`, \`sizing\`, \`shadows\`, \`radius\`, \`borders\`, \`motion\`, \`zIndex\` |
+| Search by name or value | \`searchTokens("primary")\` or \`searchTokens("bold")\` |
+| Icon size or stroke | \`getToken("sizing.icon.sm")\` for dimensions, \`getToken("icons.strokeWidth")\` for stroke |
+| Typeset classes | \`listTypesets()\` \u2014 emit one class per typeset; include text-transform and text-decoration for 1:1 match |
 
-**3. Validation**  
-- **validateUsage(value, context)** \u2014 Check if a CSS/value should use a token instead (e.g. \`validateUsage("#007061", "color")\`).
+### 3. Validation
 
-**4. Syncing tokens to a file**  
-- **syncAll({ output?, format?, skipTokens? })** \u2014 Syncs tokens to a file, AI rules, skills (.cursor/skills/atomix-ds/*), and atomix-dependencies.json. Default output \`./tokens.css\`, format \`css\`. Use \`skipTokens: true\` to only write skills and manifest.
+\`validateUsage("#007061", "color")\` \u2014 checks if a raw value should be a token. Run this on any value you suspect is hardcoded.
 
-Use the returned rules and token paths/values when generating or editing code. Prefer CSS variables (e.g. \`var(--atmx-*)\`) or the exact token references from the tools.
+### 4. Syncing tokens to a file
+
+\`syncAll({ output?, format?, skipTokens? })\` \u2014 writes tokens to a file (default \`./tokens.css\`), skills (.cursor/skills/atomix-ds/SKILL.md and figma-design-SKILL.md), and manifest. Use \`skipTokens: true\` to only write skills and manifest.
+
+## Workflow
+
+1. **Fetch rules** \u2014 call \`getRules\` once per session (or with a topic when working on a specific area).
+2. **Fetch tokens** \u2014 call \`getToken\`, \`listTokens\`, or \`searchTokens\` for the values you need.
+3. **Apply semantically** \u2014 use token references or CSS variables (\`var(--atmx-*)\`) depending on your platform. Choose the semantic token that matches the *purpose*, not just the visual appearance.
+4. **Self-check** \u2014 scan your output for hardcoded hex codes, pixel values, rem/em literals, duration strings, or font names. If found, replace with the matching token.
+
+## Common mistakes
+
+Do not hardcode visual values. Always resolve from the design system:
+
+- A hex color (\`#007061\`, \`#333\`) \u2192 call \`getToken\` or \`searchTokens\` for the matching color token
+- A pixel/rem value (\`16px\`, \`1.5rem\`) \u2192 use the spacing, sizing, or radius token
+- A font name (\`"Inter"\`, \`"SF Pro"\`) \u2192 use the typography font-family token
+- A duration (\`200ms\`, \`0.3s\`) \u2192 use the motion duration token
+- A numeric weight (\`600\`, \`700\`) \u2192 use the typography font-weight token
+- A shadow string (\`0 4px 6px rgba(\u2026)\`) \u2192 use the shadow elevation token
+
+If no token matches, call \`searchTokens\` to find the closest option. Never invent a token path.
 
 ## Best practices
 
-- **Fetch first:** Before writing UI or styles, call getAIToolRules and/or getToken/listTokens so you know the exact tokens and conventions.
-- **Icons:** Apply the design system's icon tokens when rendering icons: sizing via \`getToken("sizing.icon.sm")\` or \`listTokens("sizing")\`, and stroke width via \`getToken("icons.strokeWidth")\` when the DS defines it; do not use hardcoded sizes or stroke widths.
-- **Typography:** Use typography tokens from the DS for any text. When creating global typeset CSS, call **listTypesets** and emit one CSS class per typeset (do not skip any); include text-transform and text-decoration when present for 1:1 match.
-- **No guessing:** If a value is not in the rules or token list, use searchTokens or listTokens to find the closest match rather than inventing a value.
-- **Version check:** If this skill file has frontmatter \`atomixDsVersion\`, compare it to the design system version from **getDependencies** (\`meta.designSystemVersion\`). If the design system is newer, suggest the user run **syncAll** to update skills and tokens.
+- **Fetch first:** Always call getRules and/or listTokens before writing any styles, regardless of platform or framework.
+- **Semantic over primitive:** Prefer tokens that describe purpose (\`text-primary\`, \`bg-surface\`) over tokens that describe appearance (\`neutral.900\`, \`white\`).
+- **Icons:** Size via \`getToken("sizing.icon.sm")\`; stroke width via \`getToken("icons.strokeWidth")\` when the DS defines it.
+- **Typography:** Use **typeset classes** (e.g. from \`typesets.css\` or \`listTypesets()\` output \u2014 \`typeset-heading-h1\`, \`typeset-body-md-regular\`, etc.) for all text; do not re-declare font-family, font-size, font-weight, line-height, or letter-spacing in component CSS, which duplicates the design system. For global typeset output, call **listTypesets** and emit every entry; include text-transform and text-decoration for 1:1 match.
+- **No guessing:** If a value is not in the rules or token list, call searchTokens or listTokens to find the closest match.
+- **Platform agnostic:** Token values work across CSS, Tailwind, React Native, SwiftUI, Compose, Flutter, and any style system. Use the output format appropriate to your platform.
+- **Version check:** If this file has frontmatter \`atomixDsVersion\`, compare to the version from **getDependencies** (\`meta.designSystemVersion\`). If the DS is newer, suggest running **syncAll** to update.
+
+## Strict mode and patterns
+
+- **Strict mode:** NO arbitrary values (e.g. \`bg-[#ff0000]\` forbidden). NO hardcoded colors \u2014 use CSS variables and semantic tokens only. NO hardcoded pixel values \u2014 use spacing/sizing tokens only. NO hardcoded typography \u2014 use typography typeset tokens only. Token vocabulary only \u2014 if a value is not in the design system, do not use it.
+- **CSS variables:** All tokens follow \`--atmx-{category}-{subcategory}-{token}\`. Correct: \`backgroundColor: "var(--atmx-color-bg-surface)"\`, \`borderRadius: "var(--atmx-radius-scale-md)"\`. Wrong: hex, raw px.
+- **Dark mode:** Colors switch in dark mode when using CSS variables; \`.dark\` on root toggles color variables.
+- **Button pattern:** Height and padding use sizing/spacing tokens; typography from typeset tokens; radius and border from tokens; transition from motion tokens; primary/secondary/ghost use action color tokens (e.g. \`--atmx-color-action-primary\`, \`--atmx-color-action-on-primary\`).
 `;
 var SHOWCASE_HTML_TEMPLATE = `<!DOCTYPE html>
 <html lang="en">
@@ -3581,52 +3359,153 @@ var SHOWCASE_HTML_TEMPLATE = `<!DOCTYPE html>
     body {
       margin: 0;
       font-family: {{FONT_FAMILY_VAR}}, system-ui, sans-serif;
-      background: {{BRAND_PRIMARY_VAR}};
-      color: {{BRAND_PRIMARY_FOREGROUND_VAR}};
+      background: var(--atmx-color-bg-page);
+      color: var(--atmx-color-text-primary);
       min-height: 100vh;
-      padding: 2rem;
+      padding: var(--atmx-spacing-scale-2xl);
       display: flex;
       justify-content: center;
       align-items: center;
     }
     .wrap { width: 375px; max-width: 100%; }
-    .icon { width: 2rem; height: 2rem; margin: 0 0 1rem; }
+    .top-row {
+      display: flex;
+      justify-content: space-between;
+      align-items: flex-start;
+      margin-bottom: var(--atmx-spacing-scale-lg);
+    }
+    .top-row .mode-toggle { margin-bottom: 0; }
+    .icon-circle {
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      width: calc({{ICON_SIZE_VAR}} + 2 * {{CIRCLE_PADDING_VAR}});
+      height: calc({{ICON_SIZE_VAR}} + 2 * {{CIRCLE_PADDING_VAR}});
+      padding: {{CIRCLE_PADDING_VAR}};
+      background: {{BRAND_PRIMARY_VAR}};
+      border-radius: 50%;
+    }
+    .icon-circle.light-icon { color: #fff; }
+    .icon-circle.dark-icon { color: #000; }
+    .icon-circle svg {
+      width: {{ICON_SIZE_VAR}};
+      height: {{ICON_SIZE_VAR}};
+      flex-shrink: 0;
+    }
+    .mode-toggle {
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      padding: {{BUTTON_PADDING_VAR}};
+      height: {{BUTTON_HEIGHT_VAR}};
+      border-radius: {{BUTTON_RADIUS_VAR}};
+      background: var(--atmx-color-bg-surface);
+      color: var(--atmx-color-text-primary);
+      border: 1px solid var(--atmx-color-border-default);
+      font-family: inherit;
+      font-size: inherit;
+      font-weight: inherit;
+      cursor: pointer;
+      margin-bottom: var(--atmx-spacing-scale-xl);
+    }
+    .mode-toggle:hover {
+      background: var(--atmx-color-bg-muted);
+    }
     h1 {
       font-family: {{HEADING_FONT_VAR}}, {{FONT_FAMILY_VAR}}, system-ui, sans-serif;
-      font-size: clamp(3rem, 4vw, 5rem);
-      font-weight: 700;
-      margin: 0 0 0.75rem;
+      margin: 0 0 var(--atmx-spacing-scale-md);
       line-height: 1.2;
     }
-    .lead { margin: 0 0 1.5rem; font-size: 1rem; line-height: 1.5; opacity: 0.95; }
-    .now { margin: 1.5rem 0 0; font-size: 0.875rem; line-height: 1.6; opacity: 0.95; text-align: left; }
-    .now strong { display: block; margin-bottom: 0.5rem; }
-    .now ul { margin: 0; padding-left: 1.25rem; }
-    .tips { margin-top: 1.5rem; font-size: 0.875rem; line-height: 1.6; opacity: 0.9; }
+    .lead {
+      margin: 0 0 var(--atmx-spacing-scale-xl);
+      opacity: 0.95;
+    }
+    .now { margin: var(--atmx-spacing-scale-xl) 0 0; opacity: 0.95; text-align: left; }
+    .now strong { display: block; margin-bottom: var(--atmx-spacing-scale-sm); }
+    .now ul { margin: 0; padding-left: var(--atmx-spacing-scale-xl); }
+    .tips { margin-top: var(--atmx-spacing-scale-xl); opacity: 0.9; }
     .tips a { color: inherit; text-decoration: underline; }
+    code {
+      font-family: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace;
+      font-size: 0.8125rem;
+      padding: 0.125rem 0.375rem;
+      border-radius: 0.25rem;
+      background: var(--atmx-color-bg-muted);
+    }
   </style>
 </head>
 <body class="{{BODY_TYPESET_CLASS}}">
   <div class="wrap">
-    <div class="icon" aria-hidden="true">
-      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" width="44" height="44"><path d="M20 6L9 17l-5-5"/></svg>
+    <div class="top-row">
+      <div class="icon-circle" aria-hidden="true">
+        {{CHECK_ICON_SVG}}
+      </div>
+      <button type="button" class="mode-toggle" id="mode-toggle" aria-label="Toggle light or dark mode">Dark</button>
     </div>
     <h1 class="{{LARGEST_DISPLAY_TYPESET_CLASS}}">You're all set with {{DS_NAME}}</h1>
-    <p class="lead">This page uses your design system: brand primary as background, headline and body typesets, and an icon.</p>
-    <div class="now">
+    <p class="lead {{LARGEST_BODY_TYPESET_CLASS}}">This page uses your design system: semantic colors (mode-aware), headline and body typesets, and an icon.</p>
+    <div class="now {{LARGEST_BODY_TYPESET_CLASS}}">
       <strong>What you can do now:</strong>
       <ul>
         <li>Ask your agent to build your designs using the design system tokens</li>
         <li>Build components and pages that use <code>var(--atmx-*)</code> for colors, spacing, and typography</li>
-        <li>Run <code>/--rules</code> to load governance rules; run <code>/--sync</code> and <code>/--refactor</code> after you change tokens in Atomix Studio</li>
+        <li>Run <code>/--rules</code> to load governance rules (or call getRules); run <code>/--sync</code> and <code>/--refactor</code> after you change tokens in Atomix Studio</li>
       </ul>
     </div>
-    <p class="tips">Keep the source of truth at <a href="https://atomix.studio" target="_blank" rel="noopener">atomix.studio</a> \u2014 avoid editing token values in this repo.</p>
+    <p class="tips {{LARGEST_BODY_TYPESET_CLASS}}">Keep the source of truth at <a href="https://atomix.studio" target="_blank" rel="noopener">atomix.studio</a> \u2014 avoid editing token values in this repo.</p>
   </div>
+  <script>
+    (function() {
+      var root = document.documentElement;
+      var btn = document.getElementById('mode-toggle');
+      var circle = document.querySelector('.icon-circle');
+      function hexToRgb(hex) {
+        var m = hex.slice(1).match(/.{2}/g);
+        return m ? m.map(function(x) { return parseInt(x, 16) / 255; }) : [0, 0, 0];
+      }
+      function relativeLuminance(r, g, b) {
+        var srgb = function(x) { return x <= 0.03928 ? x / 12.92 : Math.pow((x + 0.055) / 1.055, 2.4); };
+        return 0.2126 * srgb(r) + 0.7152 * srgb(g) + 0.0722 * srgb(b);
+      }
+      function setIconContrast() {
+        if (!circle) return;
+        var bg = getComputedStyle(circle).backgroundColor;
+        var r = 0, g = 0, b = 0;
+        var rgbMatch = bg.match(/rgb\\(?\\s*(\\d+)\\s*,\\s*(\\d+)\\s*,\\s*(\\d+)\\s*\\)?/);
+        if (rgbMatch) {
+          r = parseInt(rgbMatch[1], 10) / 255;
+          g = parseInt(rgbMatch[2], 10) / 255;
+          b = parseInt(rgbMatch[3], 10) / 255;
+        } else if (bg.indexOf('#') === 0) {
+          var parts = hexToRgb(bg);
+          r = parts[0]; g = parts[1]; b = parts[2];
+        } else return;
+        var L = relativeLuminance(r, g, b);
+        circle.classList.remove('light-icon', 'dark-icon');
+        circle.classList.add(L > 0.179 ? 'dark-icon' : 'light-icon');
+      }
+      function updateLabel() {
+        var isDark = root.classList.contains('dark');
+        btn.textContent = isDark ? 'Light' : 'Dark';
+        btn.setAttribute('aria-label', isDark ? 'Switch to light mode' : 'Switch to dark mode');
+      }
+      btn.addEventListener('click', function() {
+        root.classList.toggle('dark');
+        root.setAttribute('data-theme', root.classList.contains('dark') ? 'dark' : 'light');
+        updateLabel();
+        setIconContrast();
+      });
+      if (root.classList.contains('dark') || root.getAttribute('data-theme') === 'dark') {
+        root.classList.add('dark');
+        root.setAttribute('data-theme', 'dark');
+      }
+      updateLabel();
+      setIconContrast();
+    })();
+  </script>
 </body>
 </html>
 `;
-var AI_TOOLS = ["cursor", "copilot", "windsurf", "cline", "continue", "zed", "generic"];
 server.setRequestHandler(ListResourcesRequestSchema, async () => {
   if (!hasValidAuthConfig() || authFailedNoTools) {
     throw new Error(AUTH_REQUIRED_MESSAGE);
@@ -3681,26 +3560,44 @@ Get your DS ID and token from the Export modal or Settings \u2192 Regenerate Ato
       }]
     };
   }
-  const rulesMatch = uri.match(/^atomix:\/\/rules\/(.+)$/);
+  const rulesMatch = uri.match(/^atomix:\/\/rules(?:\/(.+))?$/);
   if (rulesMatch) {
-    const tool = rulesMatch[1];
-    if (!AI_TOOLS.includes(tool)) {
-      throw new Error(`Unknown tool: ${tool}. Available: ${AI_TOOLS.join(", ")}`);
-    }
-    const rulesUrl = `${apiBase}/api/ds/${dsId}/rules?format=${tool}`;
+    const topicRaw = rulesMatch[1]?.toLowerCase().trim();
+    const rulesUrl = `${apiBase}/api/ds/${dsId}/rules?format=json`;
     const headers = { "Content-Type": "application/json" };
     if (apiKey) headers["x-api-key"] = apiKey;
     const response = await fetch(rulesUrl, { headers });
-    if (!response.ok) {
-      throw new Error(`Failed to fetch rules: ${response.status}`);
+    if (!response.ok) throw new Error(`Failed to fetch rules: ${response.status}`);
+    const payload = await response.json();
+    const categories = payload.categories ?? {};
+    const allRules = payload.rules ?? [];
+    const topicToCategories = {
+      colors: ["general", "colors"],
+      typo: ["general", "typography"],
+      typography: ["general", "typography"],
+      motion: ["general", "motion"],
+      icons: ["general", "icons"],
+      layout: ["general", "spacing", "sizing", "layout"],
+      visual: ["general", "colors", "borders", "radius", "shadows", "icons"],
+      style: ["general", "colors", "borders", "radius", "shadows", "icons"]
+    };
+    if (!topicRaw || !topicToCategories[topicRaw]) {
+      return {
+        contents: [{ uri, mimeType: "application/json", text: JSON.stringify({ rules: allRules, categories }, null, 2) }]
+      };
+    }
+    const categoryKeys = topicToCategories[topicRaw];
+    const filteredCategories = {};
+    const filteredRules = [];
+    for (const key of categoryKeys) {
+      const list = categories[key];
+      if (list?.length) {
+        filteredCategories[key] = list;
+        filteredRules.push(...list);
+      }
     }
-    const rulesData = await response.json();
     return {
-      contents: [{
-        uri,
-        mimeType: "text/markdown",
-        text: rulesData.content || JSON.stringify(rulesData, null, 2)
-      }]
+      contents: [{ uri, mimeType: "application/json", text: JSON.stringify({ rules: filteredRules, categories: filteredCategories }, null, 2) }]
     };
   }
   throw new Error(`Unknown resource: ${uri}`);
@@ -3723,11 +3620,14 @@ server.setRequestHandler(ListPromptsRequestSchema, async () => {
   const prompts = [
     { name: "--hello", description: "Get started with this design system - overview, tokens, and tools. Run this first!" },
     { name: "--get-started", description: "Get started with design system in project. Three phases: scan, report and ask, then create only after you approve." },
-    { name: "--rules", description: "Get the design system governance rules for your AI coding tool (default: cursor)." },
+    { name: "--rules", description: "Get design system governance rules (optionally by topic: colors, typo, motion, icons, layout, visual)." },
     { name: "--sync", description: "Sync tokens, AI rules, skills files, and dependencies manifest (icons, fonts). Use /--refactor to migrate deprecated tokens." },
     { name: "--refactor", description: "Migrate deprecated tokens in codebase. Run after /--sync." },
     { name: "--sync-to-figma", description: "Push this design system to Figma (variables, color + typography styles). Uses local bridge + plugin; no Figma token." }
   ];
+  if (cachedMcpTier === "pro") {
+    prompts.push({ name: "--design-in-figma", description: "Load Figma design skill and use designInFigma tool to design UI in the connected Figma file. Pro only." });
+  }
   return { prompts };
 });
 server.setRequestHandler(GetPromptRequestSchema, async (request) => {
@@ -3744,8 +3644,18 @@ server.setRequestHandler(GetPromptRequestSchema, async (request) => {
       }]
     };
   }
-  const canonicalName = name === "--hello" ? "hello" : name === "--get-started" ? "atomix-setup" : name === "--rules" ? "design-system-rules" : name === "--sync" ? "sync" : name === "--refactor" ? "refactor" : name === "--sync-to-figma" || name === "syncToFigma" ? "sync-to-figma" : name;
-  const shouldForceRefresh = canonicalName === "sync" || canonicalName === "refactor";
+  const canonicalName = name === "--hello" ? "hello" : name === "--get-started" ? "atomix-setup" : name === "--rules" ? "design-system-rules" : name === "--sync" ? "sync" : name === "--refactor" ? "refactor" : name === "--sync-to-figma" || name === "syncToFigma" ? "sync-to-figma" : name === "--design-in-figma" || name === "designInFigma" ? "design-in-figma" : name;
+  const shouldForceRefresh = [
+    "hello",
+    "atomix-setup",
+    // --get-started
+    "design-system-rules",
+    // --rules
+    "sync",
+    "refactor",
+    "sync-to-figma",
+    "design-in-figma"
+  ].includes(canonicalName);
   let data = null;
   let stats = null;
   try {
@@ -3848,6 +3758,20 @@ Both are required. Configure the MCP server in your AI tool's MCP settings, then
     lines.push(instructions);
     return lines.join("\n");
   };
+  function withMcpNotice(res) {
+    if (!mcpUpdateNotice || res.messages.length === 0) return res;
+    const first = res.messages[0];
+    if (first?.content?.type === "text" && typeof first.content.text === "string") {
+      return {
+        ...res,
+        messages: [
+          { ...first, content: { ...first.content, text: first.content.text + "\n\n---\n\n" + mcpUpdateNotice } },
+          ...res.messages.slice(1)
+        ]
+      };
+    }
+    return res;
+  }
   switch (canonicalName) {
     case "hello": {
       const welcome = generateWelcomeMessage(data, stats);
@@ -3860,7 +3784,7 @@ Do not add any introduction or commentary before the ASCII art. The ASCII art mu
 
 ---
 ${welcome}`;
-      return {
+      return withMcpNotice({
         description: `Hello \u2014 ${data.meta.name} Design System`,
         messages: [
           {
@@ -3871,41 +3795,55 @@ ${welcome}`;
             }
           }
         ]
-      };
+      });
     }
     case "design-system-rules": {
-      const tool = args?.tool || "cursor";
-      const rulesUrl = `${apiBase}/api/ds/${dsId}/rules?format=${tool}`;
+      const topic = args?.topic?.toLowerCase().trim();
+      const rulesUrl = `${apiBase}/api/ds/${dsId}/rules?format=json`;
       const headers = { "Content-Type": "application/json" };
       if (apiKey) headers["x-api-key"] = apiKey;
       const response = await fetch(rulesUrl, { headers });
-      if (!response.ok) {
-        throw new Error(`Failed to fetch rules: ${response.status}`);
+      if (!response.ok) throw new Error(`Failed to fetch rules: ${response.status}`);
+      const payload = await response.json();
+      const categories = payload.categories ?? {};
+      const allRules = payload.rules ?? [];
+      const topicToCategories = {
+        colors: ["general", "colors"],
+        typo: ["general", "typography"],
+        typography: ["general", "typography"],
+        motion: ["general", "motion"],
+        icons: ["general", "icons"],
+        layout: ["general", "spacing", "sizing", "layout"],
+        visual: ["general", "colors", "borders", "radius", "shadows", "icons"],
+        style: ["general", "colors", "borders", "radius", "shadows", "icons"]
+      };
+      let rulesText;
+      if (topic && topicToCategories[topic]) {
+        const categoryKeys = topicToCategories[topic];
+        const filteredCategories = {};
+        const filteredRules = [];
+        for (const key of categoryKeys) {
+          const list = categories[key];
+          if (list?.length) {
+            filteredCategories[key] = list;
+            filteredRules.push(...list);
+          }
+        }
+        rulesText = JSON.stringify({ rules: filteredRules, categories: filteredCategories }, null, 2);
+      } else {
+        rulesText = JSON.stringify({ rules: allRules, categories }, null, 2);
       }
-      const rulesData = await response.json();
-      return {
-        description: `Design system rules for ${tool}`,
+      return withMcpNotice({
+        description: topic ? `Design system rules (topic: ${topic})` : "Design system rules",
         messages: [
-          {
-            role: "user",
-            content: {
-              type: "text",
-              text: `Show me the design system rules for ${tool}.`
-            }
-          },
-          {
-            role: "assistant",
-            content: {
-              type: "text",
-              text: rulesData.content || JSON.stringify(rulesData, null, 2)
-            }
-          }
+          { role: "user", content: { type: "text", text: topic ? `Show me the design system rules for topic: ${topic}.` : "Show me the design system rules." } },
+          { role: "assistant", content: { type: "text", text: rulesText } }
         ]
-      };
+      });
     }
     case "spacing": {
       const instructions = `List all spacing tokens in a table format. Use the listTokens tool with category "spacing" and subcategory "scale". Format the response as a markdown table with columns: Token Name | Value | CSS Variable. The Token Name should be in short format (e.g., "spacing.xs" instead of "spacing.scale.xs").`;
-      const response = {
+      return withMcpNotice({
         description: "List all spacing tokens",
         messages: [
           {
@@ -3916,12 +3854,11 @@ ${welcome}`;
             }
           }
         ]
-      };
-      return response;
+      });
     }
     case "radius": {
       const instructions = `List all border radius tokens in a table format. Use the listTokens tool with category "radius" and subcategory "scale". Format the response as a markdown table with columns: Token Name | Value | CSS Variable. The Token Name should be in short format (e.g., "radius.sm" instead of "radius.scale.sm").`;
-      return {
+      return withMcpNotice({
         description: "List all border radius tokens",
         messages: [
           {
@@ -3932,7 +3869,7 @@ ${welcome}`;
             }
           }
         ]
-      };
+      });
     }
     case "color": {
       const instructions = `List all color tokens in a table format showing both light and dark mode values. 
@@ -3949,7 +3886,7 @@ For semantic colors (from modes.light/modes.dark), match tokens by name and show
 The Token Name should be in short format:
 - Brand colors: "colors.brand.primary" (not "colors.static.brand.primary")
 - Semantic colors: "colors.bgSurface" (not "colors.modes.light.bgSurface")`;
-      return {
+      return withMcpNotice({
         description: "List all color tokens with light/dark mode",
         messages: [
           {
@@ -3960,11 +3897,11 @@ The Token Name should be in short format:
             }
           }
         ]
-      };
+      });
     }
     case "typography": {
       const instructions = `List all typography tokens in a table format. Use the listTokens tool with category "typography" (no subcategory needed). Format the response as a markdown table with columns: Token Name | Value | CSS Variable. Group tokens by type (fontSize, fontWeight, lineHeight, etc.) with section headers.`;
-      return {
+      return withMcpNotice({
         description: "List all typography tokens",
         messages: [
           {
@@ -3975,11 +3912,11 @@ The Token Name should be in short format:
             }
           }
         ]
-      };
+      });
     }
     case "shadow": {
       const instructions = `List all shadow/elevation tokens in a table format. Use the listTokens tool with category "shadows" and subcategory "elevation". Format the response as a markdown table with columns: Token Name | Value | CSS Variable. The Token Name should be in short format (e.g., "shadows.elevation.md" is fine as-is).`;
-      return {
+      return withMcpNotice({
         description: "List all shadow/elevation tokens",
         messages: [
           {
@@ -3990,11 +3927,11 @@ The Token Name should be in short format:
             }
           }
         ]
-      };
+      });
     }
     case "border": {
       const instructions = `List all border width tokens in a table format. Use the listTokens tool with category "borders" and subcategory "width". Format the response as a markdown table with columns: Token Name | Value | CSS Variable. The Token Name should be in short format (e.g., "borders.width.sm" is fine as-is).`;
-      return {
+      return withMcpNotice({
         description: "List all border width tokens",
         messages: [
           {
@@ -4005,7 +3942,7 @@ The Token Name should be in short format:
             }
           }
         ]
-      };
+      });
     }
     case "sizing": {
       const instructions = `List all sizing tokens in a table format. Call listTokens twice:
@@ -4013,7 +3950,7 @@ The Token Name should be in short format:
 2. category "sizing" and subcategory "icon" for icon sizes
 
 Format the response as a markdown table with columns: Token Name | Value | CSS Variable. Group by type (height vs icon) with section headers.`;
-      return {
+      return withMcpNotice({
         description: "List all sizing tokens",
         messages: [
           {
@@ -4024,7 +3961,7 @@ Format the response as a markdown table with columns: Token Name | Value | CSS V
             }
           }
         ]
-      };
+      });
     }
     case "motion": {
       const instructions = `List all motion tokens in a table format. Call listTokens twice:
@@ -4032,7 +3969,7 @@ Format the response as a markdown table with columns: Token Name | Value | CSS V
 2. category "motion" and subcategory "easing" for easing tokens
 
 Format the response as a markdown table with columns: Token Name | Value | CSS Variable. Group by type (duration vs easing) with section headers.`;
-      return {
+      return withMcpNotice({
         description: "List all motion tokens",
         messages: [
           {
@@ -4043,26 +3980,28 @@ Format the response as a markdown table with columns: Token Name | Value | CSS V
             }
           }
         ]
-      };
+      });
     }
     case "sync": {
       const output = args?.output || "./tokens.css";
       const format = args?.format || "css";
-      return {
+      const workspaceRoot = args?.workspaceRoot;
+      const rootHint = workspaceRoot ? ` Use workspaceRoot: "${workspaceRoot}" so files are written inside the repo.` : " If the project root is known, pass workspaceRoot with its absolute path so skills and manifest are written inside the repo (committable).";
+      return withMcpNotice({
         description: "Sync tokens, rules, skills, and dependencies manifest",
         messages: [
           {
             role: "user",
             content: {
               type: "text",
-              text: `Call the syncAll tool now. Use output="${output}" and format="${format}". This syncs tokens, AI rules, skills (.cursor/skills/atomix-ds/*), and atomix-dependencies.json. Execute immediately - do not search or ask questions.`
+              text: `Call the syncAll tool now. Use output="${output}" and format="${format}".${rootHint} This syncs tokens, AI rules, skills (.cursor/skills/atomix-ds/*), and atomix-dependencies.json. Execute immediately - do not search or ask questions.`
             }
           }
         ]
-      };
+      });
     }
     case "sync-to-figma": {
-      return {
+      return withMcpNotice({
         description: "Push design system to Figma via MCP tool",
         messages: [
           {
@@ -4073,34 +4012,108 @@ Format the response as a markdown table with columns: Token Name | Value | CSS V
             }
           }
         ]
-      };
+      });
+    }
+    case "design-in-figma": {
+      if (getEffectiveTier() !== "pro") {
+        return withMcpNotice({
+          description: "Design in Figma (Pro required)",
+          messages: [
+            {
+              role: "user",
+              content: {
+                type: "text",
+                text: "designInFigma requires a Pro subscription. Upgrade at https://atomix.studio to use Design in Figma."
+              }
+            }
+          ]
+        });
+      }
+      if (!data) {
+        return withMcpNotice({
+          description: "Design in Figma",
+          messages: [
+            {
+              role: "user",
+              content: {
+                type: "text",
+                text: "Failed to fetch design system. Check your --ds-id and --atomix-token configuration, then try /--design-in-figma again."
+              }
+            }
+          ]
+        });
+      }
+      const figmaSkillPath = path.resolve(process.cwd(), ".cursor/skills/atomix-ds/figma-design-SKILL.md");
+      const skillExists = fs.existsSync(figmaSkillPath);
+      const currentVersion = String(data.meta.version ?? "1.0.0");
+      const fileVersion = skillExists ? readSkillVersionFromFile(figmaSkillPath) : null;
+      const isOutdated = !skillExists || fileVersion === null || fileVersion !== currentVersion;
+      if (isOutdated) {
+        return withMcpNotice({
+          description: "Figma design skill missing or outdated",
+          messages: [
+            {
+              role: "user",
+              content: {
+                type: "text",
+                text: skillExists ? `The Figma design skill at \`.cursor/skills/atomix-ds/figma-design-SKILL.md\` is outdated (design system version ${currentVersion}). Run **/--sync** to update the skill and other design system files, then run **/--design-in-figma** again.` : `The Figma design skill is missing. Run **/--sync** to write \`.cursor/skills/atomix-ds/figma-design-SKILL.md\` (and other design system files), then run **/--design-in-figma** again.`
+              }
+            }
+          ]
+        });
+      }
+      return withMcpNotice({
+        description: "Load Figma design skill and use designInFigma tool",
+        messages: [
+          {
+            role: "user",
+            content: {
+              type: "text",
+              text: `You are using **/--design-in-figma**: load the Figma design skill below and use the **designInFigma** MCP tool to design UI in the connected Figma file.
+
+**Instructions:**
+1. Treat the following as the Figma design skill (advisory and generative UI on the Figma canvas). Follow it when creating or editing designs.
+2. Call **designInFigma** with \`action: "catalog"\` first to discover available bridge methods, file variables/styles, and query/execute capabilities.
+3. Use \`action: "query"\` to read from Figma (e.g. get_selection, get_node_info, get_design_screenshot).
+4. Use \`action: "execute"\` with an array of steps to create or modify the design on the canvas.
+5. If the response includes \`bridgeNotRunning\` or \`pluginConnected: false\`, tell the user to run the Atomix plugin in Figma and tap Connect, then try again.
+
+---
+
+## Figma design skill
+
+${FIGMA_DESIGN_SKILL_MD}`
+            }
+          }
+        ]
+      });
     }
     case "refactor": {
       const refactorOutput = args?.output || "./tokens.css";
       const refactorFormat = args?.format || "css";
-      const refactorOutputPath = path2.resolve(process.cwd(), refactorOutput);
-      const refactorFileExists = fs2.existsSync(refactorOutputPath);
+      const refactorOutputPath = path.resolve(process.cwd(), refactorOutput);
+      const refactorFileExists = fs.existsSync(refactorOutputPath);
       if (!data) {
-        return {
+        return withMcpNotice({
           description: "Refactor codebase for deprecated tokens",
           messages: [{
             role: "user",
             content: { type: "text", text: `Failed to fetch design system from DB. Check your --ds-id and --atomix-token configuration.` }
           }]
-        };
+        });
       }
       if (!refactorFileExists) {
-        return {
+        return withMcpNotice({
           description: "Refactor codebase for deprecated tokens",
           messages: [{
             role: "user",
             content: { type: "text", text: `No token file found at \`${refactorOutput}\`. Please run \`/--sync\` first to create your token file, then run \`/--refactor\` to scan your codebase for deprecated token usage.` }
           }]
-        };
+        });
       }
       const deprecatedTokens = /* @__PURE__ */ new Map();
       if (["css", "scss", "less"].includes(refactorFormat)) {
-        const oldContent = fs2.readFileSync(refactorOutputPath, "utf-8");
+        const oldContent = fs.readFileSync(refactorOutputPath, "utf-8");
         const oldVarPattern = /(?:^|\n)\s*(?:\/\*[^*]*\*+(?:[^/*][^*]*\*+)*\/\s*)?(--[a-zA-Z0-9-]+):\s*([^;]+);/gm;
         let match;
         while ((match = oldVarPattern.exec(oldContent)) !== null) {
@@ -4112,7 +4125,7 @@ Format the response as a markdown table with columns: Token Name | Value | CSS V
       const dsVersion = data.meta.version ?? "?";
       const dsExportedAt = data.meta.exportedAt ? new Date(data.meta.exportedAt).toLocaleString() : "N/A";
       if (deprecatedTokens.size === 0) {
-        return {
+        return withMcpNotice({
           description: "Refactor codebase for deprecated tokens",
           messages: [{
             role: "user",
@@ -4120,7 +4133,7 @@ Format the response as a markdown table with columns: Token Name | Value | CSS V
 
 Your token file \`${refactorOutput}\` is aligned with the design system (v${dsVersion}, exported ${dsExportedAt}). No tokens need migration.` }
           }]
-        };
+        });
       }
       const format = refactorFormat;
       const isNativeFormat = ["swift", "kotlin", "dart"].includes(format);
@@ -4221,8 +4234,8 @@ Use \`/color\`, \`/spacing\`, \`/radius\`, \`/typography\`, \`/shadow\`, \`/bord
 
 - Resolve platform/stack: infer from the project (e.g. package.json, build.gradle, Xcode) or ask once: "Which platform? (e.g. web, Android, iOS)" and if relevant "Which stack? (e.g. React, Vue, Next, Swift, Kotlin)." Do not assume a default.
 - Call **getDependencies** with \`platform\` and optional \`stack\`. If it fails, tell the user the design system could not be reached and stop.
-- Scan the repo for: .cursor/skills/atomix-ds/SKILL.md, a tokens file (e.g. tokens.css or src/tokens.css), icon package from getDependencies, font links. **Web:** note any existing CSS (globals.css, main.css, Tailwind, etc.). **Native:** note any theme/style files (SwiftUI, Android themes, Compose).
-- Build two lists: **Suggested** (from getDependencies minus what exists) and **Already present**. Include: icon package, font links, skill (.cursor/skills/atomix-ds/SKILL.md), token files; for web, also include the **showcase page** (atomix-setup-showcase.html) if getDependencies returned a \`showcase\` object.
+- Scan the repo for: .cursor/skills/atomix-ds/SKILL.md, .cursor/skills/atomix-ds/figma-design-SKILL.md, a tokens file (e.g. tokens.css or src/tokens.css), icon package from getDependencies, font links. **Web:** note any existing CSS (globals.css, main.css, Tailwind, etc.). **Native:** note any theme/style files (SwiftUI, Android themes, Compose).
+- Build two lists: **Suggested** (from getDependencies minus what exists) and **Already present**. Include: icon package, font links, skills (SKILL.md and figma-design-SKILL.md), token files; for web, also include the **showcase page** (atomix-setup-showcase.html) if getDependencies returned a \`showcase\` object.
 - Do not write, create, or add anything in Phase 1.
 
 ## Phase 2 \u2013 Report and ask
@@ -4235,18 +4248,18 @@ Use \`/color\`, \`/spacing\`, \`/radius\`, \`/typography\`, \`/shadow\`, \`/bord
 
 - Run only when the user has said yes (all or specific items).
 - For each approved item:
-  - **Skill:** Write the skill content from getDependencies \`skill.content\` to \`skill.path\` (.cursor/skills/atomix-ds/SKILL.md).
-  - **Token file:** Call **syncAll** with \`output\` set to the path (e.g. "./src/tokens.css" or "./tokens.css"). syncAll also writes skills and atomix-dependencies.json. You must call syncAll; do not only suggest the user run it later.
+  - **Skills:** Prefer calling **syncAll** (it writes both skills into the repo). If writing manually, write getDependencies \`skill.content\` to \`skill.path\` and \`skillFigmaDesign.content\` to \`skillFigmaDesign.path\` under the project root.
+  - **Token file and skills in repo:** Call **syncAll** with \`output\` set to the path (e.g. "./src/tokens.css" or "./tokens.css") and **workspaceRoot** set to the absolute path of the current project/workspace root. This ensures .cursor/skills/atomix-ds/SKILL.md, .cursor/skills/atomix-ds/figma-design-SKILL.md, and atomix-dependencies.json are written inside the repo so they can be committed. You must call syncAll; do not only suggest the user run it later.
   - **Icon package:** Install per getDependencies. When rendering icons, apply the design system's icon tokens: use getToken(\`sizing.icon.*\`) or listTokens(\`sizing\`) for size, and getToken(\`icons.strokeWidth\`) for stroke width when the DS defines it; do not use hardcoded sizes or stroke widths.
   - **Fonts and typeset:** Add font links (e.g. \`<link>\` or \`@import\` from Google Fonts). Then build a **complete typeset CSS**: call **listTypesets** to get every typeset from the owner's design system (do not skip any). Emit **one CSS rule per typeset** using the \`cssClass\` and the \`fontFamilyVar\`, \`fontSizeVar\`, \`fontWeightVar\`, \`lineHeightVar\` (and \`letterSpacingVar\`, \`textTransformVar\`, \`textDecorationVar\` when present) returned by listTypesets. Include text-transform and text-decoration when the typeset has them so the result is **1:1** with the design system. The typeset file must define the full type scale\u2014not only a font import. Do not create a CSS file that contains only a font import.
-  - **Showcase page (web only):** If platform is web and getDependencies returned a \`showcase\` object, create the file at \`showcase.path\` using \`showcase.template\`. Replace every placeholder per \`showcase.substitutionInstructions\`: TOKENS_CSS_PATH, TYPESETS_LINK (if you created a typeset CSS file, use the full \`<link rel="stylesheet" href="\u2026">\` tag; otherwise empty string), DS_NAME, BRAND_PRIMARY_VAR (page background), BRAND_PRIMARY_FOREGROUND_VAR (text on brand), HEADING_FONT_VAR (h1 fallback), FONT_FAMILY_VAR (body fallback), LARGEST_DISPLAY_TYPESET_CLASS (largest display typeset from listTypesets) and BODY_TYPESET_CLASS (e.g. typeset-body-md; leave empty if no typeset file), FONT_LINK_TAG. Use only CSS variable names that exist in the synced token file. Do not change the HTML structure. After creating the file, launch it in the default browser (e.g. \`open atomix-setup-showcase.html\` on macOS, \`xdg-open atomix-setup-showcase.html\` on Linux, or the equivalent on Windows).
+  - **Showcase page (web only):** If platform is web and getDependencies returned a \`showcase\` object, create the file at \`showcase.path\` using \`showcase.template\`. Replace every placeholder per \`showcase.substitutionInstructions\`: TOKENS_CSS_PATH, TYPESETS_LINK, DS_NAME, HEADING_FONT_VAR, FONT_FAMILY_VAR, LARGEST_DISPLAY_TYPESET_CLASS, LARGEST_BODY_TYPESET_CLASS, BODY_TYPESET_CLASS, FONT_LINK_TAG, BRAND_PRIMARY_VAR, BUTTON_PADDING_VAR, BUTTON_HEIGHT_VAR, BUTTON_RADIUS_VAR, CIRCLE_PADDING_VAR, ICON_SIZE_VAR, CHECK_ICON_SVG (inline SVG from the design system icon library). The page uses semantic colors (mode-aware) and a Dark/Light toggle. Use only CSS variable names that exist in the synced token file. Do not change the HTML structure. After creating the file, launch it in the default browser (e.g. \`open atomix-setup-showcase.html\` on macOS, \`xdg-open atomix-setup-showcase.html\` on Linux, or the equivalent on Windows).
 - Report only what you actually created or updated. Do not claim the token file was added if you did not call syncAll.
 - **After reporting \u2013 styles/theme:**
   - **Web:** If the project already has at least one CSS file: recommend how to integrate Atomix (e.g. import the synced tokens file, use \`var(--atmx-*)\`). Do not suggest a new global CSS. Only if there is **no** CSS file at all, ask once: "There are no CSS files yet. Do you want me to build a global typeset from the design system?" If yes, create a CSS file that includes: (1) font \`@import\` or document that a font link is needed, and (2) **typeset rules**\u2014call **listTypesets** and emit **one CSS class per typeset** (do not skip any). For each class set font-family, font-size, font-weight, line-height, letter-spacing; when the typeset has text-transform or text-decoration, set those too for a 1:1 match. Use the CSS variable names returned by listTypesets. The output must not be only a font import; it must define every typeset with every style detail from the design system.
   - **iOS/Android:** If the project already has theme/style files: recommend how to integrate Atomix tokens. Do not suggest a new global theme. Only if there is **no** theme/style at all, ask once: "There's no theme/style setup yet. Do you want a minimal token-based theme?" and add only if the user says yes.
 
 Create your todo list first, then Phase 1 (resolve platform/stack, call getDependencies, scan, build lists), then Phase 2 (report and ask). Do not perform Phase 3 until the user replies.`;
-      return {
+      return withMcpNotice({
         description: "Get started with design system in project (/--get-started). Create todo list; Phase 1 scan, Phase 2 report and ask, Phase 3 create only after user approval.",
         messages: [
           {
@@ -4257,7 +4270,7 @@ Create your todo list first, then Phase 1 (resolve platform/stack, call getDepen
             }
           }
         ]
-      };
+      });
     }
     default:
       throw new Error(`Unknown prompt: ${name}`);
@@ -4322,6 +4335,7 @@ ${tokenSummary}
 | **/--rules** | Governance rules for your AI tool (e.g. Cursor, Copilot, Windsurf). |
 | **/--sync** | Sync tokens, rules, skills, and dependencies manifest (icons, fonts). Safe: adds new, updates existing, marks deprecated. |
 | **/--sync-to-figma** | Push design system to Figma (variables, paint/text/effect styles). Uses built-in bridge + Atomix plugin; connect plugin in Figma then run. Available on all tiers. |
+| **/--design-in-figma** | Design in Figma: loads Figma design skill and use designInFigma tool (catalog, query, execute). Pro only. |
 | **/--refactor** | Migrate deprecated tokens in codebase. Run after /--sync. |
 
 **Suggested next step:** Run **/--get-started** to set up global styles, icons, fonts, and token files; the AI will list options and ask before adding anything.