@atomixstudio/mcp 1.0.26 → 1.0.27

package/README.md

@@ -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

@@ -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),
@@ -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.26"
   },
   {
     capabilities: {
@@ -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)`,
@@ -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,
@@ -3142,11 +3157,10 @@ ${tokenResponseText}${validationBlock}` : `${summary}${validationBlock}`);
           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 })),
+                  collectionName: coll.collectionName,
+                  variables: coll.variables.map((v) => ({ name: v.name, value: v.value })),
                   scopes: coll.scopes
                 });
                 numberResults.push({ categoryKey: coll.categoryKey, result });
@@ -3625,6 +3639,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 +3650,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 +3670,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>
@@ -4311,7 +4328,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.
@@ -4431,6 +4448,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();
 }