@atomixstudio/mcp 1.0.26 → 1.0.28

package/README.md

@@ -2,7 +2,7 @@
 
 MCP (Model Context Protocol) server and CLI for Atomix Design System. Query and sync design tokens from AI coding tools (Cursor, Claude Desktop, Windsurf, etc.) or from the command line.
 
-**Version:** 1.0.25 — Pro Figma skill gated by `pro_figma_export`; design-in-Figma skill file renamed to `FIGMA-SKILL.md`; get-started and syncAll only add/write FIGMA-SKILL when the design system has Pro Figma access.
+**Version:** 1.0.28 — Sync to Figma: removes variables/styles not in payload (same collections only); color scopes (Bg = frame fill only, Action/Feedback = all fill); update-or-create for paint/text/effect styles to avoid duplicates; change summary in sync response; instructions AI-tool agnostic.
 
 ## Getting Your Credentials
 
@@ -100,7 +100,7 @@ Run these prompts from your AI tool (e.g. **/--hello**, **/--get-started**):
 
 | Prompt | Description |
 |--------|-------------|
-| **/--hello** | Get started — overview, tokens, and tools. Run this first. |
+| **/--hello** | Get started — overview, tokens, essential commands (including **/--sync-to-figma**). Run this first. |
 | **/--get-started** | Get started with design system in project. Three phases; creates files only after you approve. |
 | **/--rules** | Governance rules for your AI tool (Cursor, Copilot, Windsurf, etc.). |
 | **/--sync** | Sync tokens, AI rules, skills files, and dependencies manifest (icons, fonts). Use **/--refactor** to migrate deprecated tokens. |

package/dist/index.js

@@ -1300,8 +1300,8 @@ var FIGMA_BRIDGE_TIMEOUT_MS = 15e3;
 var FIGMA_BRIDGE_TOKEN = process.env.FIGMA_BRIDGE_TOKEN || null;
 var FIGMA_CONNECTION_INSTRUCTIONS = {
   installAndRun: "In Figma: Open Plugins and run the Atomix plugin (Atomix Token Extractor). If it's not installed yet, install it from the Figma Community or your team's plugin library, then run it.",
-  connect: 'In the plugin UI, tap **Connect to Cursor** and wait until the status shows "Connected".',
-  startBridge: "The Figma bridge runs with this MCP server. Ensure Cursor has started this MCP server (e.g. in Cursor settings), then in Figma run the Atomix plugin and click Connect to Cursor."
+  connect: 'In the plugin UI, tap **Connect** and wait until the status shows "Connected".',
+  startBridge: "The Figma bridge runs with this MCP server. Ensure your AI environment has this MCP server running (e.g. in MCP settings), then in Figma run the Atomix plugin and tap Connect."
 };
 var bridgeWss = null;
 var pluginWs = null;
@@ -1445,7 +1445,7 @@ function sendBridgeRequest(method, params, timeoutMs = FIGMA_BRIDGE_TIMEOUT_MS)
   const ws = pluginWs;
   if (!ws || ws.readyState !== WebSocket.OPEN) {
     return Promise.reject(
-      new Error("Figma plugin not connected. Open Figma, run Atomix plugin, and click Connect to Cursor.")
+      new Error("Figma plugin not connected. Open Figma, run Atomix plugin, and tap Connect.")
     );
   }
   const id = `mcp-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
@@ -1607,7 +1607,8 @@ function buildFigmaPayloadsFromDS(data) {
   }
   if (variables.length === 0 && modes.length === 0) modes.push("Light");
   const dsName = data.meta?.name;
-  const collectionName = dsName ? `${dsName} Foundations` : "Foundations";
+  const collectionPrefix = dsName ? `${dsName} ` : "";
+  const colorCollectionName = `${collectionPrefix}Colors`;
   const textStyles = [];
   const sizeToPx = (val, basePx = 16) => {
     if (typeof val === "number") return Math.round(val);
@@ -1642,7 +1643,15 @@ function buildFigmaPayloadsFromDS(data) {
     }
     return "Inter";
   };
-  const fontFamily = typography ? firstFont(typography.fontFamily ?? "Inter") : "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;
@@ -1653,6 +1662,10 @@ function buildFigmaPayloadsFromDS(data) {
     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";
@@ -1695,7 +1708,7 @@ function buildFigmaPayloadsFromDS(data) {
       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,
+        fontFamily: defaultFontFamily,
         fontWeight: String(style.fontWeight ?? "400"),
         fontSize,
         lineHeightUnit: "PERCENT",
@@ -1717,59 +1730,58 @@ function buildFigmaPayloadsFromDS(data) {
     const variables2 = [];
     for (const [key, val] of Object.entries(spacing.scale)) {
       const n = tokenValueToNumber(val);
-      if (n >= 0) variables2.push({ name: key, value: n });
+      if (n >= 0) variables2.push({ name: `Spacing / ${key}`, value: n });
     }
     variables2.sort((a, b) => a.value - b.value);
-    if (variables2.length > 0) numberVariableCollections.push({ collectionName, categoryKey: "Spacing", variables: variables2, scopes: ["GAP"] });
+    if (variables2.length > 0) numberVariableCollections.push({ collectionName: `${collectionPrefix}Spacing`, categoryKey: "Spacing", variables: variables2, scopes: ["GAP"] });
   }
   const radius = tokens?.radius;
   if (radius?.scale && typeof radius.scale === "object") {
     const variables2 = [];
     for (const [key, val] of Object.entries(radius.scale)) {
       const n = tokenValueToNumber(val);
-      if (n >= 0) variables2.push({ name: key, value: n });
+      if (n >= 0) variables2.push({ name: `Radius / ${key}`, value: n });
     }
     variables2.sort((a, b) => a.value - b.value);
-    if (variables2.length > 0) numberVariableCollections.push({ collectionName, categoryKey: "Radius", variables: variables2, scopes: ["CORNER_RADIUS"] });
+    if (variables2.length > 0) numberVariableCollections.push({ collectionName: `${collectionPrefix}Radius`, categoryKey: "Radius", variables: variables2, scopes: ["CORNER_RADIUS"] });
   }
   const borders = tokens?.borders;
   if (borders?.width && typeof borders.width === "object") {
     const variables2 = [];
     for (const [key, val] of Object.entries(borders.width)) {
       const n = tokenValueToNumber(val);
-      if (n >= 0) variables2.push({ name: key, value: n });
+      if (n >= 0) variables2.push({ name: `Borders / ${key}`, value: n });
     }
     variables2.sort((a, b) => a.value - b.value);
-    if (variables2.length > 0) numberVariableCollections.push({ collectionName, categoryKey: "Borders", variables: variables2, scopes: ["STROKE_FLOAT"] });
+    if (variables2.length > 0) numberVariableCollections.push({ collectionName: `${collectionPrefix}Borders`, categoryKey: "Borders", variables: variables2, scopes: ["STROKE_FLOAT"] });
   }
   const sizing = tokens?.sizing;
+  const sizingVariables = [];
   if (sizing?.height && typeof sizing.height === "object") {
-    const variables2 = [];
     for (const [key, val] of Object.entries(sizing.height)) {
       const n = tokenValueToNumber(val);
-      if (n >= 0) variables2.push({ name: key, value: n });
+      if (n >= 0) sizingVariables.push({ name: `Height / ${key}`, value: n });
     }
-    variables2.sort((a, b) => a.value - b.value);
-    if (variables2.length > 0) numberVariableCollections.push({ collectionName, categoryKey: "Height", variables: variables2, scopes: ["WIDTH_HEIGHT"] });
   }
   if (sizing?.icon && typeof sizing.icon === "object") {
-    const variables2 = [];
     for (const [key, val] of Object.entries(sizing.icon)) {
       const n = tokenValueToNumber(val);
-      if (n >= 0) variables2.push({ name: key, value: n });
+      if (n >= 0) sizingVariables.push({ name: `Icon / ${key}`, value: n });
     }
-    variables2.sort((a, b) => a.value - b.value);
-    if (variables2.length > 0) numberVariableCollections.push({ collectionName, categoryKey: "Icon", variables: variables2, scopes: ["WIDTH_HEIGHT"] });
+  }
+  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 variables2 = [];
     for (const [key, val] of Object.entries(layout.breakpoint)) {
       const n = tokenValueToNumber(val);
-      if (n >= 0) variables2.push({ name: key, value: n });
+      if (n >= 0) variables2.push({ name: `Breakpoint / ${key}`, value: n });
     }
     variables2.sort((a, b) => a.value - b.value);
-    if (variables2.length > 0) numberVariableCollections.push({ collectionName, categoryKey: "Breakpoint", variables: variables2, scopes: ["WIDTH_HEIGHT"] });
+    if (variables2.length > 0) numberVariableCollections.push({ collectionName: `${collectionPrefix}Layout`, categoryKey: "Layout", variables: variables2, scopes: ["WIDTH_HEIGHT"] });
   }
   const effectStyles = [];
   const shadows = tokens?.shadows;
@@ -1800,7 +1812,7 @@ function buildFigmaPayloadsFromDS(data) {
     return nameA.localeCompare(nameB);
   });
   return {
-    colorVariables: { collectionName, modes, variables },
+    colorVariables: { collectionName: colorCollectionName, modes, variables },
     paintStyles,
     textStyles,
     numberVariableCollections,
@@ -1810,7 +1822,7 @@ function buildFigmaPayloadsFromDS(data) {
 function getExpectedFigmaNamesFromDS(data) {
   const payloads = buildFigmaPayloadsFromDS(data);
   const numberVariableNames = payloads.numberVariableCollections.flatMap(
-    (c) => c.variables.map((v) => `${c.categoryKey} / ${v.name}`)
+    (c) => c.variables.map((v) => v.name)
   );
   return {
     colorVariableNames: payloads.colorVariables.variables.map((v) => v.name),
@@ -1853,7 +1865,7 @@ var authFailedNoTools = false;
 function hasValidAuthConfig() {
   return !!(dsId && accessToken);
 }
-var AUTH_REQUIRED_MESSAGE = "Atomix MCP requires authentication. Add both --ds-id and --atomix-token to your MCP config (Settings \u2192 MCP), then restart Cursor. Get your token from Atomix Studio: Export modal or Settings \u2192 Regenerate Atomix access token.";
+var AUTH_REQUIRED_MESSAGE = "Atomix MCP requires authentication. Add both --ds-id and --atomix-token to your MCP config (Settings \u2192 MCP), then restart your AI tool. Get your token from Atomix Studio: Export modal or Settings \u2192 Regenerate Atomix access token.";
 var lastChangeSummary = null;
 var FIGMA_SYNC_TOOL_NAME = "syncToFigma";
 var FIGMA_DESIGN_TOOL_NAMES = /* @__PURE__ */ new Set([
@@ -1941,10 +1953,10 @@ async function fetchDesignSystemForMCP(forceRefresh = false) {
 }
 var TOKEN_CATEGORIES = ["colors", "typography", "spacing", "sizing", "shadows", "radius", "borders", "motion", "zIndex"];
 function typesetKeyToFontFamilyRole(key) {
-  const prefix = key.split("-")[0] ?? "";
-  if (prefix === "display") return "display";
-  if (prefix === "heading") return "heading";
-  if (prefix === "mono") return "mono";
+  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";
 }
@@ -1962,12 +1974,15 @@ function buildTypesetsList(typography, cssPrefix = "atmx") {
   for (const key of Object.keys(fontSize)) {
     const role = typesetKeyToFontFamilyRole(key);
     const familyName = fontFamily[role] ?? fontFamily.body;
-    const fontFamilyVar = familyName ? `var(--${p}typography-font-family-${role})` : "";
+    const fontFamilyVarName = familyName ? `--${p}typography-font-family-${role}` : void 0;
+    const fontFamilyVar = familyName ? `var(${fontFamilyVarName})` : "";
     const keyKebab = key.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase();
     typesets.push({
       key,
       cssClass: `.typeset-${keyKebab}`,
       fontFamilyVar: fontFamilyVar || "inherit",
+      fontFamilyVarName,
+      fontFamilyValue: familyName,
       fontSizeVar: `var(--${p}typography-${key}-size)`,
       fontWeightVar: `var(--${p}typography-${key}-weight)`,
       lineHeightVar: `var(--${p}typography-${key}-line-height)`,
@@ -1983,7 +1998,7 @@ function buildTypesetsList(typography, cssPrefix = "atmx") {
 var server = new Server(
   {
     name: "atomix-mcp-user",
-    version: "1.0.25"
+    version: "1.0.27"
   },
   {
     capabilities: {
@@ -2014,7 +2029,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       authFailedNoTools = true;
       console.error(
         "[Atomix MCP] Design system not loaded: ds-id or token invalid or API error. No tools will be shown.",
-        msg.includes("401") ? " Token invalid or expired. Regenerate in Atomix Studio (Settings \u2192 Regenerate Atomix access token), update your MCP config, then restart Cursor." : msg.includes("403") ? " You do not have access to this design system (owner or invited guest)." : msg.includes("404") ? " Design system not found (invalid ds-id)." : msg
+        msg.includes("401") ? " Token invalid or expired. Regenerate in Atomix Studio (Settings \u2192 Regenerate Atomix access token), update your MCP config, then restart your AI tool." : msg.includes("403") ? " You do not have access to this design system (owner or invited guest)." : msg.includes("404") ? " Design system not found (invalid ds-id)." : msg
       );
     }
   }
@@ -2362,7 +2377,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     return {
       content: [{
         type: "text",
-        text: "MCP access requires valid --ds-id and --atomix-token. Add both to your MCP config and restart Cursor. No tools are available until then."
+        text: "MCP access requires valid --ds-id and --atomix-token. Add both to your MCP config and restart your AI tool. No tools are available until then."
       }],
       isError: true
     };
@@ -2652,7 +2667,7 @@ Version: ${designSystemData.meta.version}`,
             text: JSON.stringify({
               count: typesets.length,
               typesets,
-              instruction: "Emit one CSS rule per typeset using the cssClass and the listed var() properties. Include font-family, font-size, font-weight, line-height; add letter-spacing when present; add text-transform and text-decoration when hasTextTransform/hasTextDecoration are true so the result is 1:1 with the design system.",
+              instruction: "Emit one CSS rule per typeset using the cssClass and the listed var() properties. Include font-family, font-size, font-weight, line-height; add letter-spacing when present; add text-transform and text-decoration when hasTextTransform/hasTextDecoration are true so the result is 1:1 with the design system. The synced token file quotes font names that contain spaces; no override is needed in the typeset file. For native (iOS/Android) projects, font names with spaces must be quoted or use the platform's canonical font name in theme or resource files.",
               ...underlineThickness != null && underlineOffset != null && {
                 underlineVars: {
                   thickness: `var(--${cssPrefix}-typography-underline-thickness)`,
@@ -2799,11 +2814,11 @@ Version: ${designSystemData.meta.version}`,
       case "getSetupInstructions": {
         const tool = args?.tool;
         const instructions = {
-          cursor: `# Cursor MCP Setup
+          cursor: `# MCP Setup
 
-1. Create \`.cursor/mcp.json\` in your project root
+1. Create your MCP config file in the project (e.g. \`.cursor/mcp.json\` for Cursor)
 2. Add the MCP configuration (use exportMCPConfig to get it)
-3. Restart Cursor IDE
+3. Restart your IDE
 4. Verify by asking: "What design tokens are available?"
 
 ## File Structure
@@ -3083,7 +3098,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). {{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). {{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: '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.'
           } : void 0,
           meta: {
             dsName: data.meta.name,
@@ -3103,7 +3118,7 @@ ${tokenResponseText}${validationBlock}` : `${summary}${validationBlock}`);
       case "syncToFigma": {
         const payloads = buildFigmaPayloadsFromDS(data);
         const out = {};
-        const agentStartBridge = `The Figma bridge runs with this MCP server. Ensure Cursor has this MCP configured and running, then in Figma run the Atomix plugin and click Connect to Cursor. Then call **syncToFigma** again.`;
+        const agentStartBridge = `The Figma bridge runs with this MCP server. Ensure your AI environment has this MCP server configured and running, then in Figma run the Atomix plugin and tap Connect. Then call **syncToFigma** again.`;
         const userSteps = [
           FIGMA_CONNECTION_INSTRUCTIONS.startBridge,
           FIGMA_CONNECTION_INSTRUCTIONS.installAndRun,
@@ -3133,21 +3148,25 @@ ${tokenResponseText}${validationBlock}` : `${summary}${validationBlock}`);
             out.colorVariables = await sendBridgeRequest("create_color_variables", {
               collectionName: payloads.colorVariables.collectionName,
               modes: payloads.colorVariables.modes,
-              variables: payloads.colorVariables.variables
+              variables: payloads.colorVariables.variables,
+              removeVariablesNotInPayload: true
             });
           }
           if (payloads.paintStyles.length > 0) {
-            out.paintStyles = await sendBridgeRequest("create_paint_styles", { styles: payloads.paintStyles });
+            out.paintStyles = await sendBridgeRequest("create_paint_styles", {
+              styles: payloads.paintStyles,
+              removePaintStylesNotInPayload: true
+            });
           }
           if (payloads.numberVariableCollections.length > 0) {
             const numberResults = [];
             try {
-              const foundationsName = payloads.colorVariables.collectionName;
               for (const coll of payloads.numberVariableCollections) {
                 const result = await sendBridgeRequest("create_number_variables", {
-                  collectionName: foundationsName,
-                  variables: coll.variables.map((v) => ({ name: `${coll.categoryKey} / ${v.name}`, value: v.value })),
-                  scopes: coll.scopes
+                  collectionName: coll.collectionName,
+                  variables: coll.variables.map((v) => ({ name: v.name, value: v.value })),
+                  scopes: coll.scopes,
+                  removeVariablesNotInPayload: true
                 });
                 numberResults.push({ categoryKey: coll.categoryKey, result });
               }
@@ -3161,10 +3180,16 @@ ${tokenResponseText}${validationBlock}` : `${summary}${validationBlock}`);
             }
           }
           if (payloads.textStyles.length > 0) {
-            out.textStyles = await sendBridgeRequest("create_text_styles", { styles: payloads.textStyles });
+            out.textStyles = await sendBridgeRequest("create_text_styles", {
+              styles: payloads.textStyles,
+              removeTextStylesNotInPayload: true
+            });
           }
           if (payloads.effectStyles.length > 0) {
-            out.effectStyles = await sendBridgeRequest("create_effect_styles", { styles: payloads.effectStyles });
+            out.effectStyles = await sendBridgeRequest("create_effect_styles", {
+              styles: payloads.effectStyles,
+              removeShadowStylesNotInPayload: true
+            });
           }
           out.figmaPayload = {
             collectionName: payloads.colorVariables.collectionName,
@@ -3204,11 +3229,76 @@ ${tokenResponseText}${validationBlock}` : `${summary}${validationBlock}`);
         if (out.numberVariablesHint) {
           out.summary = [out.summary, out.numberVariablesHint].filter(Boolean).join(" ");
         }
+        const summaryParts = [];
+        const colorResult = out.colorVariables;
+        if (colorResult && (colorResult.variableNames?.length || (colorResult.removed ?? 0) > 0)) {
+          const parts = [];
+          if (colorResult.variableNames?.length) parts.push(`${colorResult.variableNames.length} synced`);
+          if ((colorResult.removed ?? 0) > 0) parts.push(`${colorResult.removed} removed`);
+          summaryParts.push(`Colors: ${parts.join(", ")}.`);
+        }
+        const paintResult = out.paintStyles;
+        if (paintResult) {
+          const c = paintResult.created ?? 0;
+          const u = paintResult.updated ?? 0;
+          const r = paintResult.removed ?? 0;
+          if (c + u + r > 0) {
+            const parts = [];
+            if (c > 0) parts.push(`${c} created`);
+            if (u > 0) parts.push(`${u} updated`);
+            if (r > 0) parts.push(`${r} removed`);
+            summaryParts.push(`Paint styles: ${parts.join(", ")}.`);
+          }
+        }
+        const effectResult = out.effectStyles;
+        if (effectResult) {
+          const c = effectResult.created ?? 0;
+          const u = effectResult.updated ?? 0;
+          const r = effectResult.removed ?? 0;
+          if (c + u + r > 0) {
+            const parts = [];
+            if (c > 0) parts.push(`${c} created`);
+            if (u > 0) parts.push(`${u} updated`);
+            if (r > 0) parts.push(`${r} removed`);
+            summaryParts.push(`Effect styles (shadows): ${parts.join(", ")}.`);
+            if (effectResult.removedNames?.length) {
+              summaryParts.push(`Removed: ${effectResult.removedNames.join(", ")}.`);
+            }
+          }
+        }
+        const numResult = out.numberVariables;
+        if (Array.isArray(numResult)) {
+          const total = numResult.reduce((acc, r) => acc + (r.result?.variableNames?.length ?? 0), 0);
+          const totalRemoved = numResult.reduce((acc, r) => acc + (r.result?.removed ?? 0), 0);
+          if (total > 0 || totalRemoved > 0) {
+            const parts = [];
+            if (total > 0) parts.push(`${total} synced`);
+            if (totalRemoved > 0) parts.push(`${totalRemoved} removed`);
+            summaryParts.push(`Number variables: ${parts.join(", ")}.`);
+          }
+        }
+        const textStylesWithRemoved = out.textStyles;
+        if (textStylesWithRemoved && (textStylesWithRemoved.created ?? 0) + (textStylesWithRemoved.updated ?? 0) + (textStylesWithRemoved.removed ?? 0) > 0) {
+          const c = textStylesWithRemoved.created ?? 0;
+          const u = textStylesWithRemoved.updated ?? 0;
+          const r = textStylesWithRemoved.removed ?? 0;
+          const parts = [];
+          if (c > 0) parts.push(`${c} created`);
+          if (u > 0) parts.push(`${u} updated`);
+          if (r > 0) parts.push(`${r} removed`);
+          summaryParts.push(`Text styles: ${parts.join(", ")}.`);
+        }
+        if (summaryParts.length > 0 && !out.error) {
+          out.summary = [out.summary, summaryParts.join(" ")].filter(Boolean).join(" ");
+        }
         out.motionEasingNote = "Motion easing tokens are not synced as Figma styles; Figma has no reusable easing style. Easing is only used in prototype transitions (e.g. smart animate). Duration/easing remain available as number variables (duration) or in export JSON.";
+        const responseText = out.summary ? `${out.summary}
+
+${JSON.stringify(out, null, 2)}` : JSON.stringify(out, null, 2);
         return {
           content: [{
             type: "text",
-            text: JSON.stringify(out, null, 2)
+            text: responseText
           }],
           ...out.error ? { isError: true } : {}
         };
@@ -3223,7 +3313,7 @@ ${tokenResponseText}${validationBlock}` : `${summary}${validationBlock}`);
                 text: JSON.stringify({
                   error: "Figma bridge not reachable.",
                   bridgeNotRunning: true,
-                  agentInstruction: "The Figma bridge runs with this MCP server. Ensure Cursor has this MCP running, then in Figma run the Atomix plugin and click Connect to Cursor. Then call getFigmaVariablesAndStyles again."
+                  agentInstruction: "The Figma bridge runs with this MCP server. Ensure your AI environment has this MCP server running, then in Figma run the Atomix plugin and tap Connect. Then call getFigmaVariablesAndStyles again."
                 }, null, 2)
               }],
               isError: true
@@ -3253,7 +3343,7 @@ ${tokenResponseText}${validationBlock}` : `${summary}${validationBlock}`);
                 type: "text",
                 text: JSON.stringify({
                   error: "Figma bridge not reachable.",
-                  hint: "The bridge runs with this MCP server. Ensure Cursor has this MCP running, then run the Atomix plugin and click Connect to Cursor."
+                  hint: "The bridge runs with this MCP server. Ensure your AI environment has this MCP server running, then run the Atomix plugin and tap Connect."
                 }, null, 2)
               }],
               isError: true
@@ -3371,7 +3461,7 @@ ${tokenResponseText}${validationBlock}` : `${summary}${validationBlock}`);
                 type: "text",
                 text: JSON.stringify({
                   error: "Figma bridge not reachable.",
-                  hint: "Run the Atomix plugin in Figma and click Connect to Cursor, then retry."
+                  hint: "Run the Atomix plugin in Figma and tap Connect, then retry."
                 }, null, 2)
               }],
               isError: true
@@ -3412,7 +3502,7 @@ ${tokenResponseText}${validationBlock}` : `${summary}${validationBlock}`);
                 type: "text",
                 text: JSON.stringify({
                   error: "Figma bridge not reachable.",
-                  hint: "Run the Atomix plugin in Figma and click Connect to Cursor, then retry."
+                  hint: "Run the Atomix plugin in Figma and tap Connect, then retry."
                 }, null, 2)
               }],
               isError: true
@@ -3445,7 +3535,7 @@ ${tokenResponseText}${validationBlock}` : `${summary}${validationBlock}`);
                 type: "text",
                 text: JSON.stringify({
                   error: "Figma bridge not reachable.",
-                  hint: "Run the Atomix plugin in Figma and click Connect to Cursor, then retry."
+                  hint: "Run the Atomix plugin in Figma and tap Connect, then retry."
                 }, null, 2)
               }],
               isError: true
@@ -3625,6 +3715,7 @@ var SHOWCASE_HTML_TEMPLATE = `<!DOCTYPE html>
   <title>Setup complete \u2014 {{DS_NAME}}</title>
   {{FONT_LINK_TAG}}
   <link rel="stylesheet" href="{{TOKENS_CSS_PATH}}">
+  {{TYPESETS_LINK}}
   <style>
     * { box-sizing: border-box; }
     body {
@@ -3635,9 +3726,11 @@ var SHOWCASE_HTML_TEMPLATE = `<!DOCTYPE html>
       min-height: 100vh;
       padding: 2rem;
       display: flex;
+      justify-content: center;
+      align-items: center;
     }
     .wrap { width: 375px; max-width: 100%; }
-    .icon { width: 2rem; height: 2rem; margin: 0 auto 1rem; }
+    .icon { width: 2rem; height: 2rem; margin: 0 0 1rem; }
     h1 {
       font-family: {{HEADING_FONT_VAR}}, {{FONT_FAMILY_VAR}}, system-ui, sans-serif;
       font-size: clamp(3rem, 4vw, 5rem);
@@ -3653,12 +3746,12 @@ var SHOWCASE_HTML_TEMPLATE = `<!DOCTYPE html>
     .tips a { color: inherit; text-decoration: underline; }
   </style>
 </head>
-<body>
+<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>
-    <h1>You're all set with {{DS_NAME}}</h1>
+    <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">
       <strong>What you can do now:</strong>
@@ -3714,7 +3807,7 @@ Get your DS ID and token from the Export modal or Settings \u2192 Regenerate Ato
     };
   }
   if (!hasValidAuthConfig() || authFailedNoTools) {
-    throw new Error("MCP access requires valid --ds-id and --atomix-token. Add both to your MCP config and restart Cursor. See atomix://setup for instructions.");
+    throw new Error("MCP access requires valid --ds-id and --atomix-token. Add both to your MCP config and restart your AI tool. See atomix://setup for instructions.");
   }
   const data = await fetchDesignSystemForMCP();
   const stats = getTokenStats(data);
@@ -3789,7 +3882,7 @@ server.setRequestHandler(GetPromptRequestSchema, async (request) => {
         role: "user",
         content: {
           type: "text",
-          text: "MCP access requires valid --ds-id and --atomix-token. Add both to your MCP config and restart Cursor. No tools or prompts are available until then."
+          text: "MCP access requires valid --ds-id and --atomix-token. Add both to your MCP config and restart your AI tool. No tools or prompts are available until then."
         }
       }]
     };
@@ -3815,7 +3908,7 @@ server.setRequestHandler(GetPromptRequestSchema, async (request) => {
 - \`--ds-id\`: Your design system ID (get it from https://atomixstudio.eu/ds/[your-ds-id])
 - \`--atomix-token\`: Your access token (get it from the Export modal or Settings \u2192 Regenerate Atomix access token)
 
-Both are required. Configure the MCP server in your Cursor settings, then restart Cursor.`
+Both are required. Configure the MCP server in your AI tool's MCP settings, then restart your AI tool.`
             }
           }
         ]
@@ -4133,7 +4226,7 @@ Format the response as a markdown table with columns: Token Name | Value | CSS V
             role: "user",
             content: {
               type: "text",
-              text: `Call the MCP tool **syncToFigma** now (no arguments). It pushes the design system into the open Figma file via the built-in bridge and Atomix plugin. Do not use the Figma REST API or external scripts. If the response includes \`bridgeNotRunning\` and \`agentInstruction\`, ensure Cursor has this MCP server running, then in Figma run the Atomix plugin and click Connect to Cursor, then call syncToFigma again. Only if that fails, tell the user: (1) Ensure Cursor has this MCP configured and running. (2) In Figma, open and run the Atomix plugin, then tap **Connect to Cursor**. (3) Run Sync to Figma again.`
+              text: `Call the MCP tool **syncToFigma** now (no arguments). It pushes the design system into the open Figma file via the built-in bridge and Atomix plugin. Do not use the Figma REST API or external scripts. If the response includes \`bridgeNotRunning\` and \`agentInstruction\`, ensure your AI environment has this MCP server running, then in Figma run the Atomix plugin and tap Connect, then call syncToFigma again. Only if that fails, tell the user: (1) Ensure this MCP server is configured and running in your AI tool. (2) In Figma, open and run the Atomix plugin, then tap **Connect**. (3) Run Sync to Figma again. After a successful sync, report the **summary** from the response (what was created, updated, or removed)\u2014do not say "we added the whole design system" when only some items changed.`
             }
           }
         ]
@@ -4149,7 +4242,7 @@ Format the response as a markdown table with columns: Token Name | Value | CSS V
               type: "text",
               text: `You must **design in Figma** by calling a **sequence of MCP tools**\u2014do not generate or run any JavaScript code. Follow the design-in-Figma skill if present; otherwise follow this **three-pass flow**.
 
-Prerequisites: Figma bridge runs inside this MCP server. In Figma, run the Atomix plugin and click "Connect to Cursor"; leave the plugin open.
+Prerequisites: Figma bridge runs inside this MCP server. In Figma, run the Atomix plugin and tap Connect; leave the plugin open.
 
 **Setup (once):** syncToFigma \u2192 createDesignPlaceholder (save \`frameId\`) \u2192 getAIToolRules + listTokens \u2192 resolveFigmaIdsForTokens. Use the returned \`resolved\` map and \`frameId\` for all passes.
 
@@ -4162,7 +4255,7 @@ Apply the owner's design system: set all fills and text styles using only ids fr
 **Pass 3 \u2014 Confirm no hardcoded values**  
 Audit: ensure no raw px, hex, or font values remain; every fill and text style must use an id from \`resolved\`. Call **getDesignScreenshot** once more. If everything is correct: call **finalizeDesignFrame** with \`frameId\`, \`name\` = a short description of the design + " \u2705", and \`fillVariableId\` (or \`fillPaintStyleId\`) from resolved for the surface/background so the placeholder gray is removed. Then **summarise** what was built and any fixes made across the three passes.
 
-If the bridge is not reachable: tell the user to run the Atomix plugin in Figma and click Connect to Cursor, then retry.`
+If the bridge is not reachable: tell the user to run the Atomix plugin in Figma and tap Connect, then retry.`
             }
           }
         ]
@@ -4311,7 +4404,7 @@ Use \`/color\`, \`/spacing\`, \`/radius\`, \`/typography\`, \`/shadow\`, \`/bord
   - **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.
   - **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, DS_NAME, BRAND_PRIMARY_VAR (page background), BRAND_PRIMARY_FOREGROUND_VAR (text on brand), HEADING_FONT_VAR (h1), FONT_FAMILY_VAR (body), 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 (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).
 - 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.
@@ -4391,8 +4484,9 @@ ${tokenSummary}
 |---------|----------------|
 | **/--hello** | Get started - overview, tokens, and tools. Run this first! |
 | **/--get-started** | Get started with design system in project. Three phases; creates files only after you approve. |
-| **/--rules** | Governance rules for your AI tool (Cursor, Copilot, Windsurf, etc.). |
+| **/--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. |
 | **/--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.
@@ -4423,7 +4517,7 @@ async function startServer() {
   console.error(`Atomix MCP Server started for design system: ${dsId}`);
   console.error(`Atomix MCP API base: ${apiBase}`);
   console.error(
-    "If you switched MCP config (e.g. free vs pro DS), restart Cursor so this process uses the new --ds-id and --atomix-token."
+    "If you switched MCP config (e.g. free vs pro DS), restart your AI tool so this process uses the new --ds-id and --atomix-token."
   );
 }
 function onShutdown() {
@@ -4431,6 +4525,8 @@ function onShutdown() {
 }
 process.on("SIGINT", onShutdown);
 process.on("SIGTERM", onShutdown);
+process.stdin.on("end", onShutdown);
+process.stdin.on("close", onShutdown);
 async function main() {
   await startServer();
 }