inkbridge 0.1.0-beta.4 → 0.1.0-beta.6

package/README.md

@@ -1,3 +1,5 @@
+<img src="https://raw.githubusercontent.com/inkn9ne/inkbridge/main/public/inkbridge-logo.png" alt="Inkbridge" width="80" />
+
 # Inkbridge
 
 Generates native Figma frames from your Tailwind React components and syncs design tokens back to your codebase via GitHub PRs.
@@ -63,7 +65,7 @@ The plugin auto-discovers your server on ports `4000`, `3000`, and `5173`.
 1. Start dev server: `pnpm figma:dev`
 2. Open any Figma file
 3. **Plugins → Development → Inkbridge → Generate Design System Page**
-4. The plugin scans your Storybook stories and builds a "Design System" page
+4. The plugin scans your Storybook stories and builds a "Design System" page with token tables, themed columns, grouped component sections, and responsive/state preview blocks where relevant
 
 Component data is always scanned live on every run — never stale. Re-run at any time to pick up changes.
 

package/code.js

@@ -26,7 +26,7 @@
     repo: "",
     baseBranch: "main",
     tokenPath: "design-tokens/tokens.dtcg.json",
-    tokenSourceMode: "auto",
+    tokenSourceMode: "css",
     cssTokenPath: "",
     syncDtcgOnPush: false,
     allowNewTokensFromFigma: false,
@@ -44,8 +44,8 @@
     return tokenPath;
   }
   function normalizeTokenSourceMode(mode) {
-    if (mode === "css" || mode === "dtcg" || mode === "auto") return mode;
-    return "auto";
+    if (mode === "dtcg") return "dtcg";
+    return "css";
   }
   function normalizeCssTokenPath(cssTokenPath) {
     if (typeof cssTokenPath !== "string") return "";
@@ -1210,11 +1210,36 @@
   function hasKeys(group) {
     return !!group && Object.keys(group).length > 0;
   }
+  function enrichFontValue(value) {
+    const parts = value.split(",");
+    let hasLiteral = false;
+    let insertAfterIdx = -1;
+    for (let i = 0; i < parts.length; i++) {
+      const trimmed = parts[i].trim();
+      if (/^var\(/.test(trimmed)) {
+        if (insertAfterIdx === -1) insertAfterIdx = i;
+        continue;
+      }
+      const lower = trimmed.toLowerCase().replace(/^["']|["']$/g, "");
+      if (SYSTEM_FONT_KEYWORDS.has(lower)) continue;
+      if (trimmed.replace(/^["']|["']$/g, "").trim()) {
+        hasLiteral = true;
+        break;
+      }
+    }
+    if (hasLiteral || insertAfterIdx === -1) return value;
+    const varMatch = parts[insertAfterIdx].trim().match(/^var\(--font-([a-z0-9-]+)\)/i);
+    if (!varMatch) return value;
+    const literal = varMatch[1].split("-").map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+    const result = [...parts];
+    result.splice(insertAfterIdx + 1, 0, ` "${literal}"`);
+    return result.join(",");
+  }
   function buildTokenPatchFromScanned(map) {
     const patch = {};
     const primary = {};
     if (hasKeys(map.colors)) primary.color = __spreadValues({}, map.colors);
-    if (hasKeys(map.fonts)) primary.font = __spreadValues({}, map.fonts);
+    if (hasKeys(map.fonts)) primary.font = Object.fromEntries(Object.entries(map.fonts).map(([k, v]) => [k, enrichFontValue(String(v))]));
     if (hasKeys(map.radius)) primary.radius = mapDimensionGroup(map.radius);
     if (hasKeys(map.spacing)) primary.spacing = mapDimensionGroup(map.spacing);
     if (hasKeys(map.fontSize)) primary.fontSize = mapDimensionGroup(map.fontSize);
@@ -1225,7 +1250,7 @@
       if (!scanned) continue;
       const themedPatch = {};
       if (hasKeys(scanned.colors)) themedPatch.color = __spreadValues({}, scanned.colors);
-      if (hasKeys(scanned.fonts)) themedPatch.font = __spreadValues({}, scanned.fonts);
+      if (hasKeys(scanned.fonts)) themedPatch.font = Object.fromEntries(Object.entries(scanned.fonts).map(([k, v]) => [k, enrichFontValue(v)]));
       if (hasKeys(scanned.radius)) themedPatch.radius = mapDimensionGroup(scanned.radius);
       if (hasKeys(scanned.spacing)) themedPatch.spacing = mapDimensionGroup(scanned.spacing);
       if (hasKeys(scanned.fontSize)) themedPatch.fontSize = mapDimensionGroup(scanned.fontSize);
@@ -1301,6 +1326,54 @@
       );
     });
   }
+  var SYSTEM_FONT_KEYWORDS = /* @__PURE__ */ new Set([
+    // Generic families & system keywords
+    "ui-sans-serif",
+    "ui-serif",
+    "ui-monospace",
+    "system-ui",
+    "sans-serif",
+    "serif",
+    "monospace",
+    "-apple-system",
+    "inherit",
+    "initial",
+    // Common web-safe fonts that appear as fallbacks, not as the intended design font
+    "arial",
+    "helvetica",
+    "georgia",
+    "verdana",
+    "tahoma",
+    "trebuchet ms",
+    "times new roman",
+    "courier new",
+    "courier",
+    "palatino",
+    "garamond",
+    "bookman",
+    "comic sans ms",
+    "impact",
+    "lucida sans unicode"
+  ]);
+  function extractFontName(raw) {
+    const parts = String(raw || "").split(",");
+    let varFallback = null;
+    for (const part of parts) {
+      const trimmed = part.trim();
+      const varMatch = trimmed.match(/^var\(--font-([a-z0-9-]+)\)/i);
+      if (varMatch) {
+        if (!varFallback) {
+          varFallback = varMatch[1].split("-").map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+        }
+        continue;
+      }
+      const lower = trimmed.toLowerCase().replace(/^["']|["']$/g, "");
+      if (SYSTEM_FONT_KEYWORDS.has(lower)) continue;
+      const name = trimmed.replace(/^["']|["']$/g, "");
+      if (name) return name;
+    }
+    return varFallback;
+  }
   function getThemeFontFamily(tokens, theme, role = "sans") {
     const block = tokens[theme];
     if (block && "font" in block) {
@@ -1308,8 +1381,8 @@
       if (font) {
         const raw = font[role] || (role !== "sans" ? font.sans : null) || Object.values(font)[0];
         if (raw) {
-          const first = String(raw).split(",")[0].trim().replace(/^["']|["']$/g, "");
-          if (first) return first;
+          const name = extractFontName(raw);
+          if (name) return name;
         }
       }
     }
@@ -1623,7 +1696,7 @@
   function normalizeTokenMap(raw) {
     if (!raw || !isPlainObject3(raw)) return void 0;
     const mode = raw.mode === "css" || raw.mode === "dtcg" || raw.mode === "embedded" ? raw.mode : "embedded";
-    const requestedMode = raw.requestedMode === "css" || raw.requestedMode === "dtcg" || raw.requestedMode === "auto" ? raw.requestedMode : void 0;
+    const requestedMode = raw.requestedMode === "css" || raw.requestedMode === "dtcg" ? raw.requestedMode : void 0;
     const out = createEmptyScannedTokenMap(
       mode,
       typeof raw.source === "string" && raw.source ? raw.source : "embedded:tokens.ts",
@@ -1730,7 +1803,7 @@
         const baseUrl = "http://localhost:" + port + "/" + path;
         const query = [];
         const requestedMode = config == null ? void 0 : config.tokenSourceMode;
-        if (requestedMode === "auto" || requestedMode === "css" || requestedMode === "dtcg") {
+        if (requestedMode === "css" || requestedMode === "dtcg") {
           query.push("tokenSourceMode=" + encodeURIComponent(requestedMode));
         }
         const cssTokenPath = ((config == null ? void 0 : config.cssTokenPath) || "").trim();
@@ -4329,7 +4402,7 @@
     const modeRaw = raw && typeof raw === "object" ? raw.mode : null;
     const mode = modeRaw === "css" || modeRaw === "dtcg" || modeRaw === "embedded" ? modeRaw : "embedded";
     const requestedRaw = raw && typeof raw === "object" ? raw.requestedMode : null;
-    const requestedMode = requestedRaw === "auto" || requestedRaw === "css" || requestedRaw === "dtcg" ? requestedRaw : void 0;
+    const requestedMode = requestedRaw === "css" || requestedRaw === "dtcg" ? requestedRaw : void 0;
     return { source, mode, requestedMode };
   }
   async function loadTokenSourceInfo() {
@@ -4750,8 +4823,8 @@
     return true;
   }
   function resolveConfiguredMode(mode) {
-    if (mode === "css" || mode === "dtcg" || mode === "auto") return mode;
-    return "auto";
+    if (mode === "dtcg") return "dtcg";
+    return "css";
   }
   async function buildTokenCommitPlan(token) {
     const tokensBeforeVariablePatch = JSON.parse(JSON.stringify(TOKENS));
@@ -4765,7 +4838,7 @@
     const configuredMode = resolveConfiguredMode(GITHUB_CONFIG.tokenSourceMode);
     const dtcgPath = normalizePath(GITHUB_CONFIG.tokenPath, DEFAULT_DTCG_PATH);
     const dtcgExisting = await fetchFileContent(token, dtcgPath, GITHUB_CONFIG.baseBranch);
-    const preferDtcg = configuredMode === "dtcg" || configuredMode === "auto" && sourceInfo.mode === "dtcg";
+    const preferDtcg = configuredMode === "dtcg" || configuredMode === "css" && sourceInfo.mode === "dtcg";
     if (preferDtcg) {
       const dtcg = tokensToDTCG(workingTokens);
       const dtcgContent = JSON.stringify(dtcg, null, 2) + "\n";
@@ -7212,6 +7285,62 @@
 
   // src/story-builder.ts
   var THEME_CONTEXT_CACHE = {};
+  var BOARD_LAYOUT = {
+    boardGap: 96,
+    sectionPaddingX: 64,
+    sectionPaddingY: 64,
+    columnsGap: 320,
+    columnGap: 144,
+    columnPaddingX: 0,
+    columnPaddingY: 160,
+    sectionGroupGap: 176,
+    sectionTitleGap: 48,
+    componentBlockGap: 128,
+    componentTitleGap: 48,
+    storyGap: 32,
+    showcaseGap: 128,
+    stateMatrixGap: 40,
+    stateMatrixAxisGap: 64,
+    responsiveBlockGap: 32,
+    responsiveColumnGap: 64,
+    responsiveLabelGap: 20
+  };
+  var COMPONENT_SECTION_ORDER = [
+    {
+      key: "actions-forms",
+      title: "Actions & Forms",
+      description: "Buttons, fields, feedback, and overlay primitives."
+    },
+    {
+      key: "content-data",
+      title: "Content & Data",
+      description: "Cards, tables, media, and information-heavy components."
+    },
+    {
+      key: "navigation-shell",
+      title: "Navigation & Shell",
+      description: "Headers, footers, and navigation patterns."
+    },
+    {
+      key: "marketing-sections",
+      title: "Marketing Sections",
+      description: "Landing-page compositions and promotional blocks."
+    },
+    {
+      key: "pricing",
+      title: "Pricing",
+      description: "Pricing components and plan comparisons."
+    },
+    {
+      key: "other",
+      title: "Additional Components",
+      description: "Everything else that does not fit the main groups."
+    }
+  ];
+  var COMPONENT_SECTION_BY_KEY = COMPONENT_SECTION_ORDER.reduce(function(map, section) {
+    map[section.key] = section;
+    return map;
+  }, {});
   function getThemeContext(theme) {
     if (THEME_CONTEXT_CACHE[theme]) return THEME_CONTEXT_CACHE[theme];
     const colorGroup = getThemeColors(TOKENS, theme);
@@ -7224,6 +7353,100 @@
     THEME_CONTEXT_CACHE[theme] = ctx;
     return ctx;
   }
+  function isTextNode(node) {
+    return !!node && node.type === "TEXT";
+  }
+  function removeDirectTextChildren(parent, names) {
+    if (!parent || !Array.isArray(parent.children)) return;
+    const stale = parent.children.filter(function(child) {
+      if (!isTextNode(child)) return false;
+      if (!names || names.length === 0) return true;
+      return names.indexOf(child.name) !== -1 || names.indexOf(child.characters) !== -1;
+    });
+    for (let i = 0; i < stale.length; i++) {
+      stale[i].remove();
+    }
+  }
+  function ensureHeaderBlock(parent, frameName, title, description, opts) {
+    let frame = findChildByName(parent, frameName);
+    if (!frame) {
+      frame = figma.createFrame();
+      frame.name = frameName;
+    }
+    frame.layoutMode = "VERTICAL";
+    frame.primaryAxisSizingMode = "AUTO";
+    frame.counterAxisSizingMode = "AUTO";
+    frame.counterAxisAlignItems = "MIN";
+    frame.itemSpacing = description ? 10 : 0;
+    frame.fills = [];
+    const titleNode = createTextNode(title, {
+      fontSize: opts && opts.titleSize ? opts.titleSize : 20,
+      lineHeight: opts && opts.titleLineHeight ? opts.titleLineHeight : void 0,
+      bold: true
+    });
+    titleNode.name = "Title";
+    frame.children.slice().forEach(function(child) {
+      child.remove();
+    });
+    frame.appendChild(titleNode);
+    if (description) {
+      const descriptionNode = createTextNode(description, {
+        fontSize: opts && opts.descriptionSize ? opts.descriptionSize : 14,
+        lineHeight: 20,
+        opacity: 0.62
+      });
+      descriptionNode.name = "Description";
+      frame.appendChild(descriptionNode);
+    }
+    return frame;
+  }
+  function getComponentSectionName(section) {
+    return "Section / " + section.title;
+  }
+  function inferComponentSection(def) {
+    const name = String(def && def.name ? def.name : "").toLowerCase();
+    const filePath = String(def && def.filePath ? def.filePath : "").toLowerCase();
+    if (filePath.includes("/feature/marketing/") || ["comparison-table", "compatibility-bar", "cta", "faq-section", "features", "hero-section", "how-it-works"].includes(name)) {
+      return COMPONENT_SECTION_BY_KEY["marketing-sections"];
+    }
+    if (filePath.includes("/feature/pricing/") || name === "plan-card") {
+      return COMPONENT_SECTION_BY_KEY.pricing;
+    }
+    if (["navbar", "footer", "hero", "mobile-nav-closed", "mobile-nav-open"].includes(name)) {
+      return COMPONENT_SECTION_BY_KEY["navigation-shell"];
+    }
+    if (["button", "badge", "alert", "input", "select", "dialog", "dropdown-menu", "sheet"].includes(name) || filePath.includes("/components/ui/") && ["button", "badge", "alert", "input", "select", "dialog", "dropdown-menu", "sheet"].some(function(token) {
+      return name === token;
+    })) {
+      return COMPONENT_SECTION_BY_KEY["actions-forms"];
+    }
+    if (["card", "table", "separator", "media-card", "skeleton", "text-truncation"].includes(name) || filePath.includes("/components/")) {
+      return COMPONENT_SECTION_BY_KEY["content-data"];
+    }
+    return COMPONENT_SECTION_BY_KEY.other;
+  }
+  function groupComponentDefs(defs) {
+    const grouped = {};
+    for (let i = 0; i < defs.length; i++) {
+      const def = defs[i];
+      const section = inferComponentSection(def);
+      if (!grouped[section.key]) grouped[section.key] = [];
+      grouped[section.key].push(def);
+    }
+    const out = [];
+    for (let i = 0; i < COMPONENT_SECTION_ORDER.length; i++) {
+      const section = COMPONENT_SECTION_ORDER[i];
+      const entries = grouped[section.key];
+      if (!entries || entries.length === 0) continue;
+      out.push({
+        section,
+        defs: entries.sort(function(a, b) {
+          return a.name.localeCompare(b.name);
+        })
+      });
+    }
+    return out;
+  }
   function applyStyleToFrame(frame, style, theme) {
     if (!style) return;
     if (style.bg) {
@@ -7641,7 +7864,7 @@
     const block = figma.createFrame();
     block.name = "States";
     block.layoutMode = "VERTICAL";
-    block.itemSpacing = 16;
+    block.itemSpacing = BOARD_LAYOUT.stateMatrixGap;
     block.primaryAxisSizingMode = "AUTO";
     block.counterAxisSizingMode = "AUTO";
     block.fills = [];
@@ -7736,7 +7959,7 @@
     const axesRow = figma.createFrame();
     axesRow.name = "State Axes";
     axesRow.layoutMode = "HORIZONTAL";
-    axesRow.itemSpacing = 28;
+    axesRow.itemSpacing = BOARD_LAYOUT.stateMatrixAxisGap;
     axesRow.primaryAxisSizingMode = "AUTO";
     axesRow.counterAxisSizingMode = "AUTO";
     axesRow.fills = [];
@@ -7747,7 +7970,7 @@
     const table = figma.createFrame();
     table.name = "State Table";
     table.layoutMode = "VERTICAL";
-    table.itemSpacing = 12;
+    table.itemSpacing = BOARD_LAYOUT.stateMatrixGap;
     table.primaryAxisSizingMode = "AUTO";
     table.counterAxisSizingMode = "AUTO";
     table.fills = [];
@@ -7755,7 +7978,7 @@
     const tableHeader = figma.createFrame();
     tableHeader.name = "State Table Header";
     tableHeader.layoutMode = "HORIZONTAL";
-    tableHeader.itemSpacing = 28;
+    tableHeader.itemSpacing = BOARD_LAYOUT.stateMatrixAxisGap;
     tableHeader.primaryAxisSizingMode = "AUTO";
     tableHeader.counterAxisSizingMode = "AUTO";
     tableHeader.fills = [];
@@ -7779,7 +8002,7 @@
       const row = figma.createFrame();
       row.name = "State Row/" + stateNames[si];
       row.layoutMode = "HORIZONTAL";
-      row.itemSpacing = 28;
+      row.itemSpacing = BOARD_LAYOUT.stateMatrixAxisGap;
       row.primaryAxisSizingMode = "AUTO";
       row.counterAxisSizingMode = "AUTO";
       row.counterAxisAlignItems = "CENTER";
@@ -7866,7 +8089,7 @@
     const block = figma.createFrame();
     block.name = "Responsive";
     block.layoutMode = "VERTICAL";
-    block.itemSpacing = 8;
+    block.itemSpacing = BOARD_LAYOUT.responsiveBlockGap;
     block.primaryAxisSizingMode = "AUTO";
     block.counterAxisSizingMode = "AUTO";
     block.fills = [];
@@ -7875,7 +8098,7 @@
     const row = figma.createFrame();
     row.name = "Responsive Strip";
     row.layoutMode = "HORIZONTAL";
-    row.itemSpacing = 16;
+    row.itemSpacing = BOARD_LAYOUT.responsiveColumnGap;
     row.primaryAxisSizingMode = "AUTO";
     row.counterAxisSizingMode = "AUTO";
     row.fills = [];
@@ -7887,7 +8110,7 @@
       const col = figma.createFrame();
       col.name = getBreakpointLabel(bp.name, bp.minWidth);
       col.layoutMode = "VERTICAL";
-      col.itemSpacing = 6;
+      col.itemSpacing = BOARD_LAYOUT.responsiveLabelGap;
       col.primaryAxisSizingMode = "AUTO";
       col.counterAxisSizingMode = "AUTO";
       col.fills = [];
@@ -8286,24 +8509,40 @@
     debug("createUIComponents start", { opts: options });
     const sectionTitle = options.sectionTitle || "UI Components";
     const tokenHash = typeof options.tokenHash === "string" ? options.tokenHash : "";
+    const showSectionHeader = options.showSectionHeader !== false;
+    const sectionPaddingX = typeof options.sectionPaddingX === "number" ? options.sectionPaddingX : showSectionHeader ? BOARD_LAYOUT.sectionPaddingX : 0;
+    const sectionPaddingY = typeof options.sectionPaddingY === "number" ? options.sectionPaddingY : showSectionHeader ? BOARD_LAYOUT.sectionPaddingY : 0;
     let section = findChildByName(parent, sectionTitle);
     if (!section) {
       section = figma.createFrame();
       section.name = sectionTitle;
-      section.layoutMode = "VERTICAL";
-      section.itemSpacing = 32;
-      section.primaryAxisSizingMode = "AUTO";
-      section.counterAxisSizingMode = "AUTO";
-      section.paddingLeft = section.paddingRight = 24;
-      section.paddingTop = section.paddingBottom = 24;
-      section.fills = [];
-      ctx.applyClipBehavior(section, []);
       const offsetY = typeof options.yOffset === "number" ? options.yOffset : 0;
       const offsetX = typeof options.xOffset === "number" ? options.xOffset : 0;
       section.x = offsetX;
       section.y = offsetY;
       parent.appendChild(section);
-      section.appendChild(createTextNode(sectionTitle, { fontSize: 28, bold: true }));
+    }
+    section.layoutMode = "VERTICAL";
+    section.itemSpacing = showSectionHeader ? BOARD_LAYOUT.boardGap : 0;
+    section.primaryAxisSizingMode = "AUTO";
+    section.counterAxisSizingMode = "AUTO";
+    section.paddingLeft = section.paddingRight = sectionPaddingX;
+    section.paddingTop = section.paddingBottom = sectionPaddingY;
+    section.counterAxisAlignItems = "MIN";
+    section.fills = [];
+    ctx.applyClipBehavior(section, []);
+    removeDirectTextChildren(section);
+    const existingSectionHeader = findChildByName(section, "Section Header");
+    if (showSectionHeader) {
+      const sectionHeader = ensureHeaderBlock(section, "Section Header", sectionTitle, null, {
+        titleSize: 32,
+        titleLineHeight: 38
+      });
+      if (findChildIndexByName(section, "Section Header") !== 0) {
+        section.insertChild(0, sectionHeader);
+      }
+    } else if (existingSectionHeader) {
+      existingSectionHeader.remove();
     }
     function formatThemeLabel(theme) {
       if (!theme) return "Theme";
@@ -8316,25 +8555,26 @@
       const block = figma.createFrame();
       block.name = def.name;
       block.layoutMode = "VERTICAL";
-      block.itemSpacing = 12;
+      block.itemSpacing = BOARD_LAYOUT.componentTitleGap;
       block.primaryAxisSizingMode = "AUTO";
       block.counterAxisSizingMode = "AUTO";
+      block.counterAxisAlignItems = "MIN";
       block.fills = [];
       ctx.applyClipBehavior(block, []);
-      block.appendChild(createTextNode(def.name, { fontSize: 16, bold: true }));
+      block.appendChild(createTextNode(def.name, { fontSize: 16, lineHeight: 22, bold: true }));
       const storyList = def.stories || [];
       for (let storyIndex = 0; storyIndex < storyList.length; storyIndex++) {
         const story = storyList[storyIndex];
         const storyWrap = figma.createFrame();
         storyWrap.name = story.name;
         storyWrap.layoutMode = "VERTICAL";
-        storyWrap.itemSpacing = 8;
+        storyWrap.itemSpacing = BOARD_LAYOUT.storyGap;
         storyWrap.primaryAxisSizingMode = "AUTO";
         storyWrap.counterAxisSizingMode = "AUTO";
         storyWrap.counterAxisAlignItems = "MIN";
         storyWrap.fills = [];
         ctx.applyClipBehavior(storyWrap, []);
-        storyWrap.appendChild(createTextNode(story.name, { fontSize: 12, opacity: 0.6, textAlignHorizontal: "LEFT" }));
+        storyWrap.appendChild(createTextNode(story.name, { fontSize: 14, lineHeight: 20, opacity: 0.6, textAlignHorizontal: "LEFT" }));
         const layout = figma.createFrame();
         layout.name = "Story Layout";
         layout.primaryAxisSizingMode = "AUTO";
@@ -8397,7 +8637,7 @@
           layout.counterAxisSizingMode = "AUTO";
         }
         let added = 0;
-        if ((def.type === "compound" || def.type === "simple") && story.jsxTree) {
+        if ((def.type === "compound" || def.type === "simple" || def.type === "cva") && story.jsxTree) {
           let rendered = false;
           const allowAbsolute = ctx.hasExplicitHeight(layoutClasses);
           const rootNode = story.jsxTree;
@@ -8537,13 +8777,26 @@
       if (!colFrame) {
         colFrame = figma.createFrame();
         colFrame.name = label + " Column";
-        colFrame.layoutMode = "VERTICAL";
-        colFrame.itemSpacing = 24;
-        colFrame.primaryAxisSizingMode = "AUTO";
-        colFrame.counterAxisSizingMode = "AUTO";
-        colFrame.fills = [];
-        ctx.applyClipBehavior(colFrame, []);
-        colFrame.appendChild(createTextNode(label + " Theme", { fontSize: 18, bold: true }));
+      }
+      colFrame.layoutMode = "VERTICAL";
+      colFrame.itemSpacing = BOARD_LAYOUT.columnGap;
+      colFrame.primaryAxisSizingMode = "AUTO";
+      colFrame.counterAxisSizingMode = "AUTO";
+      colFrame.counterAxisAlignItems = "MIN";
+      colFrame.paddingLeft = colFrame.paddingRight = BOARD_LAYOUT.columnPaddingX;
+      colFrame.paddingTop = colFrame.paddingBottom = BOARD_LAYOUT.columnPaddingY;
+      colFrame.fills = [];
+      ctx.applyClipBehavior(colFrame, []);
+      removeDirectTextChildren(colFrame);
+      const themeHeader = ensureHeaderBlock(
+        colFrame,
+        "Theme Header",
+        label + " Theme",
+        "Generated component board with grouped stories and larger comparison spacing.",
+        { titleSize: 32, titleLineHeight: 38, descriptionSize: 14 }
+      );
+      if (findChildIndexByName(colFrame, "Theme Header") !== 0) {
+        colFrame.insertChild(0, themeHeader);
       }
       const pack = getActivePack();
       const packStories = pack && pack.stories ? pack.stories : [];
@@ -8554,52 +8807,63 @@
         return tags.indexOf(storyTagFilter) !== -1;
       });
       const packStoriesHash = hashString(JSON.stringify(filteredStories) + theme);
-      let packStoriesFrame = findChildByName(colFrame, "Pack Stories");
+      let packStoriesFrame = findChildByName(colFrame, "Showcase Stories");
       if (!packStoriesFrame || getFrameHash(packStoriesFrame) !== packStoriesHash) {
         if (packStoriesFrame) packStoriesFrame.remove();
+        const stalePackFrame = findChildByName(colFrame, "Pack Stories");
+        if (stalePackFrame) stalePackFrame.remove();
         if (filteredStories.length > 0) {
           packStoriesFrame = figma.createFrame();
-          packStoriesFrame.name = "Pack Stories";
+          packStoriesFrame.name = "Showcase Stories";
           packStoriesFrame.layoutMode = "VERTICAL";
-          packStoriesFrame.itemSpacing = 12;
+          packStoriesFrame.itemSpacing = BOARD_LAYOUT.showcaseGap;
           packStoriesFrame.primaryAxisSizingMode = "AUTO";
           packStoriesFrame.counterAxisSizingMode = "AUTO";
+          packStoriesFrame.counterAxisAlignItems = "MIN";
           packStoriesFrame.fills = [];
           ctx.applyClipBehavior(packStoriesFrame, []);
+          packStoriesFrame.appendChild(ensureHeaderBlock(
+            packStoriesFrame,
+            "Section Header",
+            "Showcase Stories",
+            "Larger composite stories rendered before the component catalog.",
+            { titleSize: 20, titleLineHeight: 26, descriptionSize: 14 }
+          ));
           for (let si = 0; si < filteredStories.length; si++) {
             const story = filteredStories[si];
             const storyBlock = figma.createFrame();
             storyBlock.name = story.name || "Story";
             storyBlock.layoutMode = "VERTICAL";
-            storyBlock.itemSpacing = 12;
+            storyBlock.itemSpacing = BOARD_LAYOUT.componentTitleGap;
             storyBlock.primaryAxisSizingMode = "AUTO";
             storyBlock.counterAxisSizingMode = "AUTO";
+            storyBlock.counterAxisAlignItems = "MIN";
             storyBlock.fills = [];
             ctx.applyClipBehavior(storyBlock, []);
-            storyBlock.appendChild(createTextNode(story.name || "Story", { fontSize: 16, bold: true }));
+            storyBlock.appendChild(createTextNode(story.name || "Story", { fontSize: 16, lineHeight: 22, bold: true }));
             storyBlock.appendChild(renderStandaloneStory(story, theme, ctx));
             packStoriesFrame.appendChild(storyBlock);
           }
-          const headerExists = colFrame.children && colFrame.children.length > 0;
-          if (headerExists) {
-            colFrame.insertChild(1, packStoriesFrame);
-          } else {
-            colFrame.appendChild(packStoriesFrame);
-          }
+          colFrame.appendChild(packStoriesFrame);
           setFrameHash(packStoriesFrame, packStoriesHash);
         }
       }
+      packStoriesFrame = findChildByName(colFrame, "Showcase Stories");
+      if (packStoriesFrame && findChildIndexByName(colFrame, "Showcase Stories") !== 1) {
+        colFrame.insertChild(1, packStoriesFrame);
+      }
       let componentList = findChildByName(colFrame, "Component Blocks");
       if (!componentList) {
         componentList = figma.createFrame();
         componentList.name = "Component Blocks";
         componentList.layoutMode = "VERTICAL";
-        componentList.primaryAxisSizingMode = "AUTO";
-        componentList.counterAxisSizingMode = "AUTO";
-        componentList.itemSpacing = colFrame.itemSpacing * 6;
-        componentList.fills = [];
-        ctx.applyClipBehavior(componentList, []);
       }
+      componentList.primaryAxisSizingMode = "AUTO";
+      componentList.counterAxisSizingMode = "AUTO";
+      componentList.counterAxisAlignItems = "MIN";
+      componentList.itemSpacing = BOARD_LAYOUT.sectionGroupGap;
+      componentList.fills = [];
+      ctx.applyClipBehavior(componentList, []);
       const defsRaw = COMPONENT_DEFS && COMPONENT_DEFS.components ? COMPONENT_DEFS.components : [];
       const onlyComponents = options.onlyComponents;
       const excludeComponents = options.excludeComponents;
@@ -8611,57 +8875,122 @@
       }).sort(function(a, b) {
         return a.name.localeCompare(b.name);
       });
-      const expectedNames = {};
-      for (let di = 0; di < defs.length; di++) {
-        expectedNames[defs[di].name] = true;
-      }
-      const existingBlocks = componentList.children ? Array.from(componentList.children) : [];
-      for (let ei = 0; ei < existingBlocks.length; ei++) {
-        const existingBlock = existingBlocks[ei];
-        if (!expectedNames[existingBlock.name]) {
-          existingBlock.remove();
-          debug("Removed stale component block", { name: existingBlock.name });
-        }
-      }
-      for (let di = 0; di < defs.length; di++) {
-        const def = defs[di];
-        const blockHash = hashDef(def) + ":" + tokenHash;
-        const existingBlock = findChildByName(componentList, def.name);
-        if (existingBlock && getFrameHash(existingBlock) === blockHash) {
-          debug("Component block unchanged \u2014 skipped", { name: def.name });
-          continue;
+      const groupedDefs = groupComponentDefs(defs);
+      const expectedSectionNames = {};
+      for (let gi = 0; gi < groupedDefs.length; gi++) {
+        expectedSectionNames[getComponentSectionName(groupedDefs[gi].section)] = true;
+      }
+      const existingGroups = componentList.children ? Array.from(componentList.children) : [];
+      for (let gi = 0; gi < existingGroups.length; gi++) {
+        const existingGroup = existingGroups[gi];
+        if (!expectedSectionNames[existingGroup.name]) {
+          existingGroup.remove();
+        }
+      }
+      for (let gi = 0; gi < groupedDefs.length; gi++) {
+        const group = groupedDefs[gi];
+        const sectionName = getComponentSectionName(group.section);
+        let sectionFrame = findChildByName(componentList, sectionName);
+        if (!sectionFrame) {
+          sectionFrame = figma.createFrame();
+          sectionFrame.name = sectionName;
+        }
+        sectionFrame.layoutMode = "VERTICAL";
+        sectionFrame.primaryAxisSizingMode = "AUTO";
+        sectionFrame.counterAxisSizingMode = "AUTO";
+        sectionFrame.counterAxisAlignItems = "MIN";
+        sectionFrame.itemSpacing = BOARD_LAYOUT.sectionTitleGap;
+        sectionFrame.fills = [];
+        ctx.applyClipBehavior(sectionFrame, []);
+        const groupHeader = ensureHeaderBlock(
+          sectionFrame,
+          "Section Header",
+          group.section.title,
+          group.section.description,
+          { titleSize: 20, titleLineHeight: 26, descriptionSize: 14 }
+        );
+        if (findChildIndexByName(sectionFrame, "Section Header") !== 0) {
+          sectionFrame.insertChild(0, groupHeader);
+        }
+        let groupBlocks = findChildByName(sectionFrame, "Blocks");
+        if (!groupBlocks) {
+          groupBlocks = figma.createFrame();
+          groupBlocks.name = "Blocks";
+          sectionFrame.appendChild(groupBlocks);
+        }
+        groupBlocks.layoutMode = "VERTICAL";
+        groupBlocks.primaryAxisSizingMode = "AUTO";
+        groupBlocks.counterAxisSizingMode = "AUTO";
+        groupBlocks.counterAxisAlignItems = "MIN";
+        groupBlocks.itemSpacing = BOARD_LAYOUT.componentBlockGap;
+        groupBlocks.fills = [];
+        ctx.applyClipBehavior(groupBlocks, []);
+        const expectedNames = {};
+        for (let di = 0; di < group.defs.length; di++) {
+          expectedNames[group.defs[di].name] = true;
+        }
+        const existingBlocks = groupBlocks.children ? Array.from(groupBlocks.children) : [];
+        for (let ei = 0; ei < existingBlocks.length; ei++) {
+          const existingBlock = existingBlocks[ei];
+          if (!expectedNames[existingBlock.name]) {
+            existingBlock.remove();
+            debug("Removed stale component block", { name: existingBlock.name });
+          }
         }
-        let insertIndex = -1;
-        if (existingBlock) {
-          insertIndex = findChildIndexByName(componentList, def.name);
-          existingBlock.remove();
-          debug("Component block changed \u2014 rebuilding", { name: def.name });
+        for (let di = 0; di < group.defs.length; di++) {
+          const def = group.defs[di];
+          const blockHash = hashDef(def) + ":" + tokenHash;
+          const existingBlock = findChildByName(groupBlocks, def.name);
+          if (existingBlock && getFrameHash(existingBlock) === blockHash) {
+            const currentIndex = findChildIndexByName(groupBlocks, def.name);
+            if (currentIndex !== di) {
+              groupBlocks.insertChild(di, existingBlock);
+            }
+            debug("Component block unchanged \u2014 skipped", { name: def.name });
+            continue;
+          }
+          let insertIndex = di;
+          if (existingBlock) {
+            existingBlock.remove();
+            debug("Component block changed \u2014 rebuilding", { name: def.name });
+          }
+          const newBlock = buildComponentBlock(def, theme, colFrame);
+          setFrameHash(newBlock, blockHash);
+          if (insertIndex >= 0 && insertIndex < groupBlocks.children.length) {
+            groupBlocks.insertChild(insertIndex, newBlock);
+          } else {
+            groupBlocks.appendChild(newBlock);
+          }
         }
-        const newBlock = buildComponentBlock(def, theme, colFrame);
-        setFrameHash(newBlock, blockHash);
-        if (insertIndex >= 0 && insertIndex < componentList.children.length) {
-          componentList.insertChild(insertIndex, newBlock);
-        } else {
-          componentList.appendChild(newBlock);
+        const currentSectionIndex = findChildIndexByName(componentList, sectionName);
+        if (currentSectionIndex !== gi) {
+          componentList.insertChild(gi, sectionFrame);
         }
       }
       if (componentList.children.length > 0 && !findChildByName(colFrame, "Component Blocks")) {
         colFrame.appendChild(componentList);
       }
+      if (findChildByName(colFrame, "Component Blocks")) {
+        const componentListIndex = packStoriesFrame ? 2 : 1;
+        if (findChildIndexByName(colFrame, "Component Blocks") !== componentListIndex) {
+          colFrame.insertChild(componentListIndex, componentList);
+        }
+      }
       return colFrame;
     }
     let columns = findChildByName(section, "Columns");
     if (!columns) {
       columns = figma.createFrame();
       columns.name = "Columns";
-      columns.layoutMode = "HORIZONTAL";
-      columns.itemSpacing = 32;
-      columns.primaryAxisSizingMode = "AUTO";
-      columns.counterAxisSizingMode = "AUTO";
-      columns.fills = [];
-      ctx.applyClipBehavior(columns, []);
       section.appendChild(columns);
     }
+    columns.layoutMode = "HORIZONTAL";
+    columns.itemSpacing = BOARD_LAYOUT.columnsGap;
+    columns.primaryAxisSizingMode = "AUTO";
+    columns.counterAxisSizingMode = "AUTO";
+    columns.counterAxisAlignItems = "MIN";
+    columns.fills = [];
+    ctx.applyClipBehavior(columns, []);
     const requestedThemes = Array.isArray(options.themeNames) ? options.themeNames.filter(function(theme, index, list) {
       return typeof theme === "string" && theme.trim().length > 0 && list.indexOf(theme) === index;
     }) : [];
@@ -8673,16 +9002,17 @@
     if (multiMode) {
       const activeTheme = requestedThemes[0] || "primary";
       const singleCol = addColumn("Theme", activeTheme);
-      if (!findChildByName(columns, "Theme Column")) {
-        columns.appendChild(singleCol);
+      if (findChildIndexByName(columns, "Theme Column") !== 0) {
+        columns.insertChild(0, singleCol);
       }
       setThemeMode(singleCol, activeTheme);
     } else {
       for (let ti = 0; ti < requestedThemes.length; ti++) {
         const themeName = requestedThemes[ti];
         const themeCol = addColumn(formatThemeLabel(themeName), themeName);
-        if (!findChildByName(columns, formatThemeLabel(themeName) + " Column")) {
-          columns.appendChild(themeCol);
+        const columnName = formatThemeLabel(themeName) + " Column";
+        if (findChildIndexByName(columns, columnName) !== ti) {
+          columns.insertChild(ti, themeCol);
         }
         setThemeMode(themeCol, themeName);
       }
@@ -10235,6 +10565,7 @@
   function normalizeComponentDef(raw) {
     if (!raw || !raw.analysis) return raw;
     return __spreadProps(__spreadValues({}, raw.analysis), {
+      filePath: raw.analysis.filePath || raw.filePath,
       stories: Array.isArray(raw.analysis.stories) ? raw.analysis.stories : Array.isArray(raw.stories) ? raw.stories : [],
       hasStory: typeof raw.analysis.hasStory === "boolean" ? raw.analysis.hasStory : !!raw.hasStory,
       layout: raw.layout,
@@ -11342,6 +11673,16 @@
 
   // src/design-system.ts
   var EFFECTS_COMPONENTS = ["Gradient-showcase"];
+  function removeStalePageLabels(page, labels) {
+    if (!page || !Array.isArray(page.children)) return;
+    const targets = new Set(labels);
+    const staleNodes = page.children.filter(function(node) {
+      return node && node.type === "TEXT" && typeof node.characters === "string" && targets.has(node.characters);
+    });
+    for (let i = 0; i < staleNodes.length; i++) {
+      staleNodes[i].remove();
+    }
+  }
   function buildDesignSystemSinglePage() {
     let ds = figma.root.children.find((p) => p.name === "Design System");
     if (!ds) {
@@ -11349,6 +11690,7 @@
       ds.name = "Design System";
     }
     figma.currentPage = ds;
+    removeStalePageLabels(ds, ["Design Tokens", "UI Components", "Effects"]);
     const themeNames = getThemeNames(TOKENS);
     const tokenHash = hashString(JSON.stringify(TOKENS));
     let tokensRow = findChildByName(ds, "Design Tokens");
@@ -11384,7 +11726,8 @@
       yOffset: defaultUiY,
       xOffset: 48,
       excludeComponents: EFFECTS_COMPONENTS,
-      tokenHash
+      tokenHash,
+      showSectionHeader: false
     });
     const uiSection = findChildByName(ds, "UI Components");
     const defaultEffectsY = uiSection ? uiSection.y + uiSection.height + 80 : defaultUiY + 800;
@@ -11394,7 +11737,8 @@
       xOffset: 48,
       sectionTitle: "Effects",
       onlyComponents: EFFECTS_COMPONENTS,
-      tokenHash
+      tokenHash,
+      showSectionHeader: false
     });
   }
 
@@ -11416,7 +11760,7 @@
   }
   function coerceTokenSourceInfo(raw) {
     const mode = raw && (raw.mode === "css" || raw.mode === "dtcg" || raw.mode === "embedded") ? raw.mode : "embedded";
-    const requestedMode = raw && (raw.requestedMode === "auto" || raw.requestedMode === "css" || raw.requestedMode === "dtcg") ? raw.requestedMode : void 0;
+    const requestedMode = raw && (raw.requestedMode === "css" || raw.requestedMode === "dtcg") ? raw.requestedMode : void 0;
     const source = raw && typeof raw.source === "string" && raw.source.trim() ? raw.source.trim() : "embedded:tokens.ts";
     return { source, mode, requestedMode };
   }
@@ -11757,7 +12101,7 @@
           repo: msg.repo || "",
           baseBranch: msg.baseBranch || "main",
           tokenPath: msg.tokenPath || "design-tokens/tokens.dtcg.json",
-          tokenSourceMode: msg.tokenSourceMode || "auto",
+          tokenSourceMode: msg.tokenSourceMode || "css",
           cssTokenPath: msg.cssTokenPath || "",
           syncDtcgOnPush: msg.syncDtcgOnPush === true,
           allowNewTokensFromFigma: msg.allowNewTokensFromFigma === true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "inkbridge",
-  "version": "0.1.0-beta.4",
+  "version": "0.1.0-beta.6",
   "description": "Figma plugin that generates a pixel-accurate design system from your Tailwind React components.",
   "type": "module",
   "bin": {
@@ -42,10 +42,5 @@
     "storybook"
   ],
   "license": "MIT",
-  "homepage": "https://inkbridge.io",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/inkn9ne/inkbridge.git",
-    "directory": "tools/figma-plugin-tailwind-tokens"
-  }
+  "homepage": "https://inkbridge.ink"
 }

package/scanner/component-scanner.ts

@@ -2457,10 +2457,105 @@ export class ComponentScanner {
         }
         return parts.join(' ').trim();
       }
+      // Try to resolve as a CVA variant function call (e.g., alertVariants({ variant }))
+      const cvaResult = this.resolveCvaFunctionCall(expr, propsContext);
+      if (cvaResult !== null) return cvaResult;
     }
     return '';
   }
 
+  /**
+   * Resolve a CVA variant function call like `alertVariants({ variant })` to its
+   * combined class string. Looks up the function definition in the same source file,
+   * then merges base classes with the appropriate variant classes.
+   */
+  private resolveCvaFunctionCall(callExpr: Node, propsContext: Map<string, any>): string | null {
+    if (!Node.isCallExpression(callExpr)) return null;
+    const funcName = callExpr.getExpression().getText();
+    const sourceFile = callExpr.getSourceFile();
+
+    // Find `const funcName = cva(...)` in the source file
+    for (const varStmt of sourceFile.getVariableStatements()) {
+      for (const decl of varStmt.getDeclarationList().getDeclarations()) {
+        if (decl.getName() !== funcName) continue;
+        const init = decl.getInitializer();
+        if (!init || !Node.isCallExpression(init)) continue;
+        if (init.getExpression().getText() !== 'cva') continue;
+
+        const cvaArgs = init.getArguments();
+        if (cvaArgs.length === 0) return '';
+
+        const baseClasses = this.extractStringValue(cvaArgs[0]);
+        const classes: string[] = baseClasses ? [baseClasses] : [];
+
+        if (cvaArgs.length >= 2 && Node.isObjectLiteralExpression(cvaArgs[1])) {
+          const configObj = cvaArgs[1];
+
+          // Parse the call argument object e.g. { variant } or { variant: "destructive" }
+          const callArgs = callExpr.getArguments();
+          const requestedVariants: Record<string, string> = {};
+          if (callArgs.length > 0 && Node.isObjectLiteralExpression(callArgs[0])) {
+            for (const prop of callArgs[0].getProperties()) {
+              if (Node.isPropertyAssignment(prop)) {
+                const key = prop.getName();
+                const valInit = prop.getInitializer();
+                if (!valInit) continue;
+                const resolved = this.resolveExpressionValue(valInit, propsContext);
+                if (typeof resolved === 'string') requestedVariants[key] = resolved;
+                else if (Node.isStringLiteral(valInit)) requestedVariants[key] = valInit.getLiteralValue();
+              } else if (Node.isShorthandPropertyAssignment(prop)) {
+                // { variant } shorthand — look up value from propsContext
+                const key = prop.getName();
+                const resolved = propsContext.get(key);
+                if (typeof resolved === 'string') requestedVariants[key] = resolved;
+              }
+            }
+          }
+
+          // Extract defaultVariants
+          const defaultVariants: Record<string, string> = {};
+          const defaultVariantsProp = configObj.getProperty('defaultVariants');
+          if (defaultVariantsProp && Node.isPropertyAssignment(defaultVariantsProp)) {
+            const defaultObj = defaultVariantsProp.getInitializer();
+            if (defaultObj && Node.isObjectLiteralExpression(defaultObj)) {
+              for (const prop of defaultObj.getProperties()) {
+                if (!Node.isPropertyAssignment(prop)) continue;
+                const val = this.extractStringValue(prop.getInitializer()!);
+                defaultVariants[prop.getName()] = val.replace(/['"]/g, '');
+              }
+            }
+          }
+
+          // Look up each variant and add its classes
+          const variantsProp = configObj.getProperty('variants');
+          if (variantsProp && Node.isPropertyAssignment(variantsProp)) {
+            const variantsObj = variantsProp.getInitializer();
+            if (variantsObj && Node.isObjectLiteralExpression(variantsObj)) {
+              for (const variantProp of variantsObj.getProperties()) {
+                if (!Node.isPropertyAssignment(variantProp)) continue;
+                const variantName = variantProp.getName();
+                const selectedValue = requestedVariants[variantName] ?? defaultVariants[variantName];
+                if (!selectedValue) continue;
+
+                const variantValuesObj = variantProp.getInitializer();
+                if (!variantValuesObj || !Node.isObjectLiteralExpression(variantValuesObj)) continue;
+
+                const matchedProp = variantValuesObj.getProperty(selectedValue);
+                if (matchedProp && Node.isPropertyAssignment(matchedProp)) {
+                  const variantClassStr = this.extractStringValue(matchedProp.getInitializer()!);
+                  if (variantClassStr) classes.push(variantClassStr);
+                }
+              }
+            }
+          }
+        }
+
+        return classes.filter(Boolean).join(' ').trim();
+      }
+    }
+    return null;
+  }
+
   /**
    * Extract props from a JSX node (opening element or self-closing element).
    * Uses getDescendantsOfKind to safely get only JsxAttribute nodes,

package/scanner/css-token-reader.ts

@@ -9,10 +9,10 @@ import {
 } from '../src/token-source';
 
 const CSS_DISCOVERY_PATHS = [
-  'src/app/tokens.css',
   'src/app/globals.css',
   'app/globals.css',
   'styles/globals.css',
+  'src/app/tokens.css',
 ];
 
 const DEFAULT_DTCG_PATH = 'design-tokens/tokens.dtcg.json';
@@ -84,6 +84,10 @@ function resolveImportedCssPath(baseFilePath: string, params: string): string |
 }
 
 function cssHasTokenDeclarations(cssText: string): boolean {
+  // Only count declarations inside :root {} or .[theme] {} rules — the same
+  // selectors that patchCssVariables targets. We intentionally skip @theme
+  // at-rules (Tailwind v4 utility mappings) because those contain var()
+  // references, not source values, and the patcher cannot update them.
   try {
     const root = postcss.parse(cssText);
     let found = false;
@@ -91,16 +95,9 @@ function cssHasTokenDeclarations(cssText: string): boolean {
       if (found) return;
       if (!decl.prop || !decl.prop.startsWith('--')) return;
       const parent = decl.parent;
-      if (!parent) return;
-      if (parent.type === 'atrule') {
-        const at = parent as AtRule;
-        if ((at.name || '').toLowerCase() === 'theme') found = true;
-        return;
-      }
-      if (parent.type === 'rule') {
-        const selector = (parent as Rule).selector || '';
-        if (parseThemeSelectors(selector).length > 0) found = true;
-      }
+      if (!parent || parent.type !== 'rule') return;
+      const selector = (parent as Rule).selector || '';
+      if (parseThemeSelectors(selector).length > 0) found = true;
     });
     return found;
   } catch {
@@ -108,7 +105,7 @@ function cssHasTokenDeclarations(cssText: string): boolean {
   }
 }
 
-function resolveCssTokenPathFromImports(filePath: string, visited: Set<string> = new Set()): string {
+export function resolveCssTokenPathFromImports(filePath: string, visited: Set<string> = new Set()): string {
   const absolute = path.resolve(filePath);
   if (visited.has(absolute)) return absolute;
   visited.add(absolute);
@@ -179,12 +176,11 @@ function readCssWithImports(filePath: string, visited: Set<string> = new Set()):
 
 export function discoverCssTokenPath(projectRoot: string, explicitPath?: string): string | null {
   if (explicitPath && explicitPath.trim()) {
-    const explicit = discoverFilePath(projectRoot, explicitPath.trim());
-    return explicit ? resolveCssTokenPathFromImports(explicit) : null;
+    return discoverFilePath(projectRoot, explicitPath.trim());
   }
   for (const rel of CSS_DISCOVERY_PATHS) {
     const found = discoverFilePath(projectRoot, rel);
-    if (found) return resolveCssTokenPathFromImports(found);
+    if (found) return found;
   }
   return null;
 }
@@ -384,7 +380,7 @@ function walkCssNodes(map: ScannedTokenMap, container: postcss.Container): void
   }
 }
 
-export function parseCssTokenMap(cssText: string, source: string, requestedMode: TokenSourceMode = 'auto'): ScannedTokenMap {
+export function parseCssTokenMap(cssText: string, source: string, requestedMode: TokenSourceMode = 'css'): ScannedTokenMap {
   const map = createEmptyScannedTokenMap('css', source, requestedMode);
   const root = postcss.parse(cssText);
   walkCssNodes(map, root);
@@ -425,7 +421,7 @@ function applyDtcgDimensionGroup(
 function parseDtcgTokenMap(
   dtcgJson: unknown,
   source: string,
-  requestedMode: TokenSourceMode = 'auto'
+  requestedMode: TokenSourceMode = 'dtcg'
 ): ScannedTokenMap {
   const map = createEmptyScannedTokenMap('dtcg', source, requestedMode);
   if (!isPlainObject(dtcgJson)) return map;
@@ -453,16 +449,10 @@ function parseDtcgTokenMap(
 
 export function readTokenSourceMap(options: ReadTokenSourceOptions): ScannedTokenMap {
   const projectRoot = path.resolve(options.projectRoot);
-  const requestedMode = options.tokenSourceMode || 'auto';
+  const requestedMode: TokenSourceMode = options.tokenSourceMode === 'dtcg' ? 'dtcg' : 'css';
   const cssPath = discoverCssTokenPath(projectRoot, options.cssTokenPath);
   const dtcgPath = discoverDtcgTokenPath(projectRoot, options.dtcgTokenPath);
 
-  if (requestedMode === 'css') {
-    if (!cssPath) return createEmptyScannedTokenMap('embedded', 'embedded:tokens.ts', requestedMode);
-    const cssText = readCssWithImports(cssPath);
-    return parseCssTokenMap(cssText, toDisplayPath(projectRoot, cssPath), requestedMode);
-  }
-
   if (requestedMode === 'dtcg') {
     if (!dtcgPath) return createEmptyScannedTokenMap('embedded', 'embedded:tokens.ts', requestedMode);
     const dtcgText = fs.readFileSync(dtcgPath, 'utf-8');
@@ -470,10 +460,14 @@ export function readTokenSourceMap(options: ReadTokenSourceOptions): ScannedToke
     return parseDtcgTokenMap(dtcgJson, toDisplayPath(projectRoot, dtcgPath), requestedMode);
   }
 
-  // auto mode: CSS always wins when present.
+  // css mode: CSS preferred; fall back to DTCG if no CSS file found, then embedded.
   if (cssPath) {
     const cssText = readCssWithImports(cssPath);
-    return parseCssTokenMap(cssText, toDisplayPath(projectRoot, cssPath), requestedMode);
+    // Use the file that actually contains the declarations as source so the
+    // write-back path (PR/patch) targets the right file even when globals.css
+    // delegates token definitions to an imported file like tokens.css.
+    const writeTarget = resolveCssTokenPathFromImports(cssPath);
+    return parseCssTokenMap(cssText, toDisplayPath(projectRoot, writeTarget), requestedMode);
   }
   if (dtcgPath) {
     const dtcgText = fs.readFileSync(dtcgPath, 'utf-8');

package/src/token-source.ts

@@ -1,4 +1,4 @@
-export type TokenSourceMode = 'auto' | 'css' | 'dtcg';
+export type TokenSourceMode = 'css' | 'dtcg';
 export type ResolvedTokenSourceMode = 'css' | 'dtcg' | 'embedded';
 
 export interface ScannedThemeTokens {

package/ui.html

@@ -205,7 +205,7 @@
     </div>
     <div id="tokenSourceInfoPush" class="repo-display" style="display:none;padding:6px 8px;">
       Last scan source: <strong id="tokenSourceLabelPush"></strong><br>
-      Configured mode: <strong id="configuredTokenSourceModePush">auto</strong>
+      Configured mode: <strong id="configuredTokenSourceModePush">css</strong>
     </div>
 
     <div class="field">
@@ -250,7 +250,7 @@
 
     <div id="tokenSourceInfoSettings" class="repo-display" style="display:none;padding:6px 8px;">
       Last scan source: <strong id="tokenSourceLabelSettings"></strong><br>
-      Configured mode: <strong id="configuredTokenSourceModeSettings">auto</strong>
+      Configured mode: <strong id="configuredTokenSourceModeSettings">css</strong>
     </div>
 
     <div class="field">
@@ -271,11 +271,10 @@
     <div class="field">
       <label>Token Source Mode</label>
       <select id="settingsTokenSourceMode">
-        <option value="auto">auto (prefer CSS)</option>
-        <option value="css">css (force CSS only)</option>
-        <option value="dtcg">dtcg (force DTCG only)</option>
+        <option value="css">css (auto-discover CSS, fallback to DTCG)</option>
+        <option value="dtcg">dtcg (force DTCG file only)</option>
       </select>
-      <p class="hint">`auto` prefers CSS and falls back to DTCG, then embedded tokens.</p>
+      <p class="hint">CSS mode auto-discovers your globals.css and falls back to DTCG if not found. Use DTCG to force the legacy token file.</p>
     </div>
 
     <div class="field" id="tokenPathField">
@@ -291,25 +290,25 @@
     </div>
 
     <div class="field" id="syncDtcgOnPushField">
-      <label style="display:flex;align-items:center;gap:8px;">
-        <input type="checkbox" id="settingsSyncDtcgOnPush">
-        Also update DTCG on Push to Code
-      </label>
+      <div style="display:flex;align-items:center;gap:8px;">
+        <input type="checkbox" id="settingsSyncDtcgOnPush" style="width:auto;flex-shrink:0;">
+        <label for="settingsSyncDtcgOnPush" style="display:inline;margin:0;cursor:pointer;">Also update DTCG on Push to Code</label>
+      </div>
       <p class="hint">When enabled, the plugin also commits <code>tokens.dtcg.json</code> as a generated artifact.</p>
     </div>
 
     <div class="field">
-      <label style="display:flex;align-items:center;gap:8px;">
-        <input type="checkbox" id="settingsAllowNewTokensFromFigma">
-        Allow New Tokens from Figma
-      </label>
+      <div style="display:flex;align-items:center;gap:8px;">
+        <input type="checkbox" id="settingsAllowNewTokensFromFigma" style="width:auto;flex-shrink:0;">
+        <label for="settingsAllowNewTokensFromFigma" style="display:inline;margin:0;cursor:pointer;">Allow New Tokens from Figma</label>
+      </div>
       <p class="hint">Disabled by default. When enabled, new token keys can be added to code on push.</p>
     </div>
 
-    <div class="field">
+    <div class="field" id="newTokenPrefixesField" style="display:none;">
       <label>New Token Prefixes (optional)</label>
       <input type="text" id="settingsNewTokenPrefixes" placeholder="chart-, brand-">
-      <p class="hint">Comma-separated. If empty, all new keys are allowed. If set, only matching prefixes are allowed.</p>
+      <p class="hint">Comma-separated. Only tokens with these prefixes can be added. Leave empty to allow all new tokens.</p>
     </div>
 
     <div class="divider"></div>
@@ -410,7 +409,7 @@
     </div>
     <div id="tokenSourceInfoSync" class="repo-display" style="display:none;padding:6px 8px;">
       Last scan source: <strong id="tokenSourceLabelSync"></strong><br>
-      Configured mode: <strong id="configuredTokenSourceModeSync">auto</strong>
+      Configured mode: <strong id="configuredTokenSourceModeSync">css</strong>
     </div>
 
     <p style="font-size: 11px; color: #666; margin-bottom: 12px;">
@@ -531,6 +530,7 @@
     var syncDtcgOnPushField = document.getElementById('syncDtcgOnPushField');
     var settingsAllowNewTokensFromFigma = document.getElementById('settingsAllowNewTokensFromFigma');
     var settingsNewTokenPrefixes = document.getElementById('settingsNewTokenPrefixes');
+    var newTokenPrefixesField = document.getElementById('newTokenPrefixesField');
     var settingsToken = document.getElementById('settingsToken');
     var settingsProjectName = document.getElementById('settingsProjectName');
     var settingsLicenseKey = document.getElementById('settingsLicenseKey');
@@ -538,7 +538,7 @@
     // Current detected changes
     var detectedChanges = { tokens: true, components: [] };
     var lastTokenSourceInfo = null;
-    var configuredTokenSourceMode = 'auto';
+    var configuredTokenSourceMode = 'css';
 
     function resizeToContent() {
       // Wait for layout to settle before measuring
@@ -580,25 +580,20 @@
     }
 
     function normalizeConfiguredMode(mode) {
-      if (mode === 'css' || mode === 'dtcg' || mode === 'auto') return mode;
-      return 'auto';
+      if (mode === 'dtcg') return 'dtcg';
+      return 'css';
     }
 
     function applyTokenSourceModeVisibility(mode) {
       var normalized = normalizeConfiguredMode(mode);
-      if (normalized === 'css') {
-        tokenPathField.style.display = 'none';
-        cssTokenPathField.style.display = 'block';
-        syncDtcgOnPushField.style.display = 'block';
-        return;
-      }
       if (normalized === 'dtcg') {
         tokenPathField.style.display = 'block';
         cssTokenPathField.style.display = 'none';
         syncDtcgOnPushField.style.display = 'none';
         return;
       }
-      tokenPathField.style.display = 'block';
+      // css mode
+      tokenPathField.style.display = 'none';
       cssTokenPathField.style.display = 'block';
       syncDtcgOnPushField.style.display = 'block';
     }
@@ -980,7 +975,8 @@
         settingsCssTokenPath.value = config.cssTokenPath || '';
         settingsSyncDtcgOnPush.checked = config.syncDtcgOnPush === true;
         settingsAllowNewTokensFromFigma.checked = config.allowNewTokensFromFigma === true;
-        settingsNewTokenPrefixes.value = Array.isArray(config.newTokenPrefixes) ? config.newTokenPrefixes.join(', ') : '';
+        settingsNewTokenPrefixes.value = Array.isArray(config.newTokenPrefixes) ? config.newTokenPrefixes.join(', ') : (typeof config.newTokenPrefixes === 'string' ? config.newTokenPrefixes : '');
+        newTokenPrefixesField.style.display = config.allowNewTokensFromFigma === true ? 'block' : 'none';
         settingsProjectName.value = config.projectName || '';
         configuredTokenSourceMode = tokenSourceMode;
         applyTokenSourceModeVisibility(tokenSourceMode);
@@ -1197,7 +1193,7 @@
           repo: repo,
           baseBranch: settingsBranch.value.trim() || 'main',
           tokenPath: settingsTokenPath.value.trim() || 'design-tokens/tokens.dtcg.json',
-          tokenSourceMode: settingsTokenSourceMode.value || 'auto',
+          tokenSourceMode: settingsTokenSourceMode.value || 'css',
           cssTokenPath: settingsCssTokenPath.value.trim(),
           syncDtcgOnPush: settingsSyncDtcgOnPush.checked === true,
           allowNewTokensFromFigma: settingsAllowNewTokensFromFigma.checked === true,
@@ -1217,6 +1213,10 @@
       applyTokenSourceModeVisibility(configuredTokenSourceMode);
       setTokenSourceInfo(lastTokenSourceInfo);
     };
+
+    settingsAllowNewTokensFromFigma.onchange = function() {
+      newTokenPrefixesField.style.display = settingsAllowNewTokensFromFigma.checked ? 'block' : 'none';
+    };
   </script>
 </body>
 </html>