@agent-native/core 0.153.9 → 0.154.0

package/corpus/templates/design/.agents/skills/design-generation/SKILL.md

@@ -35,6 +35,53 @@ them:
 
 Jumping straight to code is how you get slop. Let the phases (below) do the work.
 
+## First decide the mode: reproduce or explore
+
+The workflow above assumes an under-specified prompt. When the user has already
+specified the design, that same workflow is the failure — exploration reads to
+them as "the agent ignored everything I gave it".
+
+Before Phase 1, check for **specification signals**:
+
+- an attached screenshot, mockup, or photo of a UI,
+- a linked design system / Brand Kit,
+- a written outline naming concrete screens, sections, components, or copy,
+- a named existing product/page to match, or pasted markup or tokens.
+
+**Any one of these puts you in reproduce mode.** In reproduce mode:
+
+- Do **not** call `present-design-variants`. Three divergent directions when the
+  user handed you one is not exploration, it is discarding their work. Produce
+  the one thing they specified.
+- Do **not** call `show-design-questions` about anything the supplied material
+  already answers. Ask only about a genuine gap, and prefer stating an
+  assumption over asking.
+- Every "Do" in the aesthetic quality bar below is **off** wherever it would
+  contradict the supplied material. Those rules break ties in the absence of a
+  spec; they never outvote one.
+- Reproduce first, improve second. Match the structure, then raise quality
+  *within* it, and say what you changed and why.
+
+Mixed input is normal: reproduce what was given, use the quality bar only for
+the parts genuinely left open. When a supplied reference and the linked design
+system disagree, follow the design system for tokens (color, type, spacing,
+radius) and the reference for layout and composition, then say you did.
+
+### A reference screenshot is a specification, not a mood board
+
+When the user attaches an image of a UI, read it as a layout spec and
+reproduce it: the same regions in the same positions, the same navigation
+pattern, the same information hierarchy and density, the same component
+grammar (tabs vs. pills, cards vs. rows, sidebar vs. topbar), the same
+approximate proportions. Name what you see before you build, so the user can
+correct a misread early. Deviate only where the image is genuinely unreadable
+or an explicit instruction overrides it — and say which, rather than
+silently substituting your own composition.
+
+An attached image is only guaranteed to be visible on the turn it arrived.
+If a screenshot was described earlier in the thread but you cannot see one now,
+say so and ask for a re-attach — never quietly design from the text alone.
+
 ## Authority and direction record
 
 Before generating, make a compact direction record: the job this surface must
@@ -69,13 +116,21 @@ change the design. Never smooth an evidence gap into confident copy.
 
 ## Aesthetic quality bar — beat distributional convergence
 
-The rules in this section are fallback quality heuristics. They do not
-override an active Agent-Native design system or an explicit brand constraint.
+The rules in this section are fallback quality heuristics for prompts that
+leave the look open. They do not override an active Agent-Native design system,
+a supplied reference, or an explicit brand constraint. **A banned item stops
+being banned the moment the user's own material specifies it** — if their Brand
+Kit's body font is Inter, the design ships Inter; if their screenshot is a
+centered hero with three icon cards, the design ships that. Substituting a
+"better" choice for a specified one is the single most-reported failure of this
+app. When you follow a specified value that appears on a "don't" list below,
+just follow it — no apology, no note, no compensating flourish elsewhere.
 
 You sample toward the "on-distribution" center by default; refuse it. **Every
 "don't" here carries a "do"** — a banned default plus where to go instead —
 because banning Inter alone just makes you reach for Roboto next. Use a banned
-item only if the user explicitly asks.
+item only if the user explicitly asks, or their design system or reference
+already uses it.
 
 - **Fonts.** Don't: Inter, Roboto, Arial, Open Sans, system-ui. Do: a distinctive
   Google Font pairing matched to the chosen aesthetic (see the table) — editorial
@@ -97,7 +152,10 @@ item only if the user explicitly asks.
 
 **Second-order convergence is real.** Even your "creative" picks converge (Space
 Grotesk everywhere; teal accent + blinking dot + left accent bars). Vary
-deliberately across generations so two designs never share a fingerprint.
+deliberately across generations so two designs never share a fingerprint —
+but only across designs *you* had to invent. A token the user's own system
+specifies is theirs, not your fingerprint: consistency with their brand is the
+goal, and varying away from it to avoid repeating yourself is a bug.
 
 **Principles to quote back while building:** color creates hierarchy, not
 decoration · density over decoration · earn every animation · commit to one point
@@ -293,9 +351,15 @@ The WIDEST requested device is the base/primary frame; narrower devices become b
 
 ### Phase 2 — Generate side-by-side variations (2-5, three by default)
 
-For new designs, default to **three** variations (`present-design-variants`
-accepts 2-5; three is the sweet spot). Call `present-design-variants` for both
-first-party and external MCP-host flows. It saves each candidate as a normal
+Skip this phase entirely in reproduce mode (see "First decide the mode" above) —
+a screenshot, a written outline, or a linked design system means the direction
+is already chosen, and offering three alternatives to it is the behavior users
+report as "the agent ignored my design".
+
+For new designs whose direction is genuinely open, default to **three**
+variations (`present-design-variants` accepts 2-5; three is the sweet spot).
+Call `present-design-variants` for both first-party and external MCP-host
+flows. It saves each candidate as a normal
 overview-board screen, then renders an inline chat choice with one button per
 screen name.
 
@@ -389,6 +453,14 @@ structural issues, token drift), fix them directly with `edit-design`. **A
 design with audit errors is not ready** — don't report a design as done while
 `run-design-audit` still returns unresolved errors.
 
+A `design-system-drift` finding means the screen uses none of the linked
+system's fonts, colors, or token names. That is a generation bug, not a style
+disagreement: the user linked that system precisely so the output would use it.
+Call `get-design-system` for the linked id, apply the real values through
+`edit-design`, and re-audit — never resolve it by explaining the deviation or
+by unlinking the system. It is the one check that can catch a design that
+looks fine and is still not the user's.
+
 After the audit is clean, call `take-design-screenshot` on each changed screen
 (default: 1280px desktop + 375px mobile). Fix everything its `diagnostics`
 report flags — real computed contrast ratios, horizontal/container overflow,

package/corpus/templates/design/.agents/skills/design-systems/SKILL.md

@@ -201,10 +201,22 @@ it reports an explicit static SSRF-safe fallback when no browser is available.
 ### Source: GitHub Repository
 
 ```bash
-pnpm action index-design-system-with-builder --githubRepoUrl "https://github.com/acme/ui"
+pnpm action index-design-system-with-builder --githubSources '[{"repoUrl":"https://github.com/acme/ui","ref":"main","include":["src/styles","design.md"]}]'
 ```
 
-Starts Builder design-system indexing for the repository. Builder is the source of truth for the indexed brand kit, generated docs, and usage guidance. If Builder is not connected, stop and ask the user to connect Builder.
+Starts one Builder design-system job with one or more GitHub sources. Each
+source can pin a branch, tag, or commit and include repository-relative files or
+folders. Unscoped public repositories stay native Builder sources so large
+codebases are not truncated; private repos and scoped refs stay server-side and
+use the saved `GITHUB_TOKEN` without exposing it to the browser or Builder.
+Builder is the source of truth for the indexed brand kit, generated docs, and
+usage guidance. If Builder is not connected, stop and ask the user to connect
+Builder.
+
+The legacy `githubRepoUrl` argument remains compatible for one unscoped repo.
+For a saved GitHub-backed system, use `sync-design-system-with-builder --id
+<localDesignSystemId>` to replay the stored repository/ref/scope after upstream
+changes. Do not create a second local copy.
 
 ### Source: Local Code Files
 

package/corpus/templates/design/.agents/skills/visual-edit/SKILL.md

@@ -51,8 +51,8 @@ Prefer the MCP App surface for a connected Design plugin, then the host's
 browser/preview tool as the universal fallback. Keep the canvas beside chat
 when the host supports rearrangeable panes.
 
-Inside Design, use **Show/Hide UI** from the `Cmd+K` menu or press Figma's
-`Shift+\` shortcut to toggle all editing chrome so only the canvas remains.
+Inside Design, use **Show/Hide UI** from the `Cmd K` menu or press Figma's
+`Shift \` shortcut to toggle all editing chrome so only the canvas remains.
 The same action is available from Design's empty-canvas context menu.
 
 ## Core Model

package/corpus/templates/design/.generated/bridge/editor-chrome.generated.ts

@@ -134,23 +134,46 @@ export const editorChromeBridgeScript: string = `"use strict";
     const fromSouth = input.handle === "sw" || input.handle === "s" || input.handle === "se";
     const resizesHorizontally = fromWest || fromEast;
     const resizesVertically = fromNorth || fromSouth;
-    let width = start.width + (fromWest ? -input.delta.x : fromEast ? input.delta.x : 0);
-    let height = start.height + (fromNorth ? -input.delta.y : fromSouth ? input.delta.y : 0);
+    const resizeFromCenter = Boolean(input.altKey);
+    let width = start.width + (fromWest ? -input.delta.x : fromEast ? input.delta.x : 0) * (resizeFromCenter ? 2 : 1);
+    let height = start.height + (fromNorth ? -input.delta.y : fromSouth ? input.delta.y : 0) * (resizeFromCenter ? 2 : 1);
     const minWidth = input.minWidth ?? DEFAULT_CANVAS_MIN_SIZE;
     const minHeight = input.minHeight ?? DEFAULT_CANVAS_MIN_SIZE;
-    if (input.preserveAspectRatio && resizesHorizontally && resizesVertically && start.width > 0 && start.height > 0) {
-      const horizontalScale = width / start.width;
-      const verticalScale = height / start.height;
-      const scale = Math.abs(horizontalScale - 1) >= Math.abs(verticalScale - 1) ? horizontalScale : verticalScale;
-      const minScale = Math.max(minWidth / start.width, minHeight / start.height);
-      width = start.width * Math.max(minScale, scale);
-      height = start.height * Math.max(minScale, scale);
+    const preserveAspectRatio = Boolean(input.preserveAspectRatio) && start.width > 0 && start.height > 0;
+    const widthChange = Math.abs(width - start.width);
+    const heightChange = Math.abs(height - start.height);
+    const derivesHeight = preserveAspectRatio && resizesHorizontally && !resizesVertically;
+    const derivesWidth = preserveAspectRatio && resizesVertically && !resizesHorizontally;
+    if (derivesHeight) {
+      height = width / (start.width / start.height);
+    } else if (derivesWidth) {
+      width = height * (start.width / start.height);
+    } else if (preserveAspectRatio && resizesHorizontally && resizesVertically) {
+      if (widthChange >= heightChange) {
+        height = width / (start.width / start.height);
+      } else {
+        width = height * (start.width / start.height);
+      }
     }
+    const widthBelowMinimum = width < minWidth;
+    const heightBelowMinimum = height < minHeight;
     width = Math.max(minWidth, width);
     height = Math.max(minHeight, height);
+    if (preserveAspectRatio) {
+      if (widthBelowMinimum && !heightBelowMinimum) {
+        height = Math.max(minHeight, width / (start.width / start.height));
+      } else if (heightBelowMinimum && !widthBelowMinimum) {
+        width = Math.max(minWidth, height * (start.width / start.height));
+      } else if (widthBelowMinimum && heightBelowMinimum) {
+        width = Math.max(minWidth, minHeight * (start.width / start.height));
+        height = width / (start.width / start.height);
+      }
+    }
+    const centerDerivedHeight = derivesHeight && !resizeFromCenter;
+    const centerDerivedWidth = derivesWidth && !resizeFromCenter;
     return {
-      x: fromWest ? start.x + start.width - width : start.x,
-      y: fromNorth ? start.y + start.height - height : start.y,
+      x: resizeFromCenter || centerDerivedWidth ? start.x + (start.width - width) / 2 : fromWest ? start.x + start.width - width : start.x,
+      y: resizeFromCenter || centerDerivedHeight ? start.y + (start.height - height) / 2 : fromNorth ? start.y + start.height - height : start.y,
       width,
       height
     };
@@ -311,6 +334,7 @@ export const editorChromeBridgeScript: string = `"use strict";
         rect: core.resize(gestureStart.rect, {
           handle: gestureStart.handle,
           delta: convertedDelta,
+          altKey: pointer.altKey,
           preserveAspectRatio: Boolean(pointer.shiftKey)
         })
       };

package/corpus/templates/design/actions/get-design-system.ts

@@ -13,6 +13,15 @@ const MAX_JSON_CONTEXT_CHARS = 2_500;
 const MAX_BUILDER_DOCS = 8;
 const MAX_BUILDER_DOC_CHARS = 1_200;
 const MAX_TOKEN_VALUES = 48;
+// Per-section budgets for a locally-stored kit. These exist because one shared
+// JSON dump starves whatever `JSON.stringify` happens to order last — which was
+// `notes` and `customCSS`, the only carriers of component, shadow, and motion
+// detail a rich import produces. Sectioning them means a 500-token kit loses
+// tail tokens instead of losing its entire component vocabulary.
+const MAX_NAMED_TOKENS = 220;
+const MAX_CUSTOM_CSS_CHARS = 3_000;
+const MAX_NOTES_CHARS = 3_000;
+const MAX_CORE_TOKEN_JSON_CHARS = 2_000;
 
 interface BuilderGenerationContext {
   builderDesignSystemId: string;
@@ -50,6 +59,42 @@ function formatJson(value: unknown, maxChars = MAX_JSON_CONTEXT_CHARS): string {
   return truncate(JSON.stringify(value, null, 2), maxChars);
 }
 
+/**
+ * The source system's own token names. A kit that renders as seven color roles
+ * reads as "a few colors" no matter how much was imported — these names are the
+ * difference between the user's design system and a palette that resembles it.
+ */
+function formatNamedTokens(tokens: unknown): string[] {
+  if (!Array.isArray(tokens)) return [];
+  const usable = tokens.filter(
+    (token): token is Record<string, string> =>
+      Boolean(token) &&
+      typeof token === "object" &&
+      typeof (token as { name?: unknown }).name === "string" &&
+      typeof (token as { value?: unknown }).value === "string",
+  );
+  if (usable.length === 0) return [];
+  const shown = usable.slice(0, MAX_NAMED_TOKENS);
+  const lines = [
+    `Named tokens from the source system (${usable.length} total).`,
+    "These are the design team's own names. Use them verbatim as CSS custom " +
+      "properties instead of inventing generic ones:",
+    ...shown.map((token) => {
+      const cssVar = token.cssVar ? ` (${token.cssVar})` : "";
+      const group = token.group ? ` [${token.group}]` : "";
+      const type = token.type ? ` {${token.type}}` : "";
+      return `- ${token.name}${cssVar}: ${token.value}${type}${group}`;
+    }),
+  ];
+  if (shown.length < usable.length) {
+    lines.push(
+      `- [${usable.length - shown.length} further tokens stored but not listed here; ` +
+        "they exist in the kit — do not treat this list as the complete system]",
+    );
+  }
+  return lines;
+}
+
 function formatTokenValues(tokenValues: Record<string, string>): string[] {
   const entries = Object.entries(tokenValues)
     .filter(([, value]) => typeof value === "string" && value.trim())
@@ -135,10 +180,65 @@ function buildDesignSystemAgentContext({
         );
       }
     }
-  } else {
-    const parsedData = parseJson(data);
+  }
+
+  // Builder hydration can succeed as a request and still carry nothing usable
+  // (a failed/incomplete index returns zero docs and zero token values). The
+  // stored local kit is then the only real content there is, so emit it rather
+  // than presenting placeholder proxy values as if they were the user's brand.
+  const builderUsable = Boolean(
+    builder &&
+    (builder.docCount > 0 || Object.keys(builder.tokenValues).length > 0),
+  );
+  if (builder && !builderUsable) {
+    lines.push(
+      "",
+      "- Builder returned no usable docs or token values for this system. " +
+        "Anything below comes from the locally stored kit; if that is also " +
+        "thin, say so and ask the user to finish indexing rather than " +
+        "filling the gap with a generic style.",
+    );
+  }
+
+  if (!builder || !builderUsable) {
+    const parsedData = parseJson(data) as Record<string, unknown> | null;
     if (parsedData) {
-      lines.push("", "Local design-system tokens:", formatJson(parsedData));
+      const { tokens, customCSS, notes, ...coreTokens } = parsedData as {
+        tokens?: unknown;
+        customCSS?: unknown;
+        notes?: unknown;
+      } & Record<string, unknown>;
+
+      if (Object.keys(coreTokens).length > 0) {
+        lines.push(
+          "",
+          "Core design-system tokens:",
+          formatJson(coreTokens, MAX_CORE_TOKEN_JSON_CHARS),
+        );
+      }
+
+      const namedTokens = formatNamedTokens(tokens);
+      if (namedTokens.length > 0) {
+        lines.push("", ...namedTokens);
+      }
+
+      if (typeof customCSS === "string" && customCSS.trim()) {
+        lines.push(
+          "",
+          "Design-system CSS to place in the generated document's `:root` " +
+            "(use these declarations directly; do not re-derive them):",
+          truncate(customCSS.trim(), MAX_CUSTOM_CSS_CHARS),
+        );
+      }
+
+      if (typeof notes === "string" && notes.trim()) {
+        lines.push(
+          "",
+          "Design-system notes — component, elevation, motion, and usage " +
+            "detail captured at import. Follow these as rules, not trivia:",
+          truncate(notes.trim(), MAX_NOTES_CHARS),
+        );
+      }
     }
   }
 

package/corpus/templates/design/actions/import-design-tokens.ts

@@ -1,4 +1,5 @@
 import { defineAction } from "@agent-native/core";
+import type { BrandKitTokenType } from "@agent-native/core/brand-kit";
 import { buildDeepLink } from "@agent-native/core/server";
 import {
   CODE_MAX_FILES,
@@ -28,13 +29,10 @@ import {
   resolveTweaksToCssVars,
 } from "../shared/resolve-tweaks.js";
 
-type ImportedTokenType =
-  | "color"
-  | "typography"
-  | "spacing"
-  | "radius"
-  | "shadow"
-  | "other";
+// Aliased, not re-declared: this was a hand-copy of BrandKitTokenType that
+// drifted, so tokens classified here could name a category the stored kit had
+// no word for.
+type ImportedTokenType = BrandKitTokenType;
 
 interface ImportedDesignToken {
   name: string;
@@ -116,6 +114,23 @@ function designDeepLink(designId: string): string {
   });
 }
 
+/** `120ms`, `0.2s`, `cubic-bezier(...)`, `ease-in-out`, `steps(4, end)`. */
+function isMotionValue(value: string): boolean {
+  const v = value.trim().toLowerCase();
+  return (
+    /^-?\d*\.?\d+m?s$/.test(v) ||
+    /^(cubic-bezier|steps|linear)\s*\(/.test(v) ||
+    /^(linear|ease|ease-in|ease-out|ease-in-out|step-start|step-end)$/.test(v)
+  );
+}
+
+/** An offset/blur triple in px/rem/em with any color notation, or `none`. */
+function isShadowValue(value: string): boolean {
+  const v = value.trim().toLowerCase();
+  if (v === "none") return true;
+  return /\d/.test(v) && /(px|rem|em)\b/.test(v);
+}
+
 function classifyVar(name: string, value: string): ImportedTokenType {
   const n = name.toLowerCase();
   if (isColorValue(value)) return "color";
@@ -124,7 +139,10 @@ function classifyVar(name: string, value: string): ImportedTokenType {
     return "typography";
   }
   if (/spacing|gap|padding|margin|space/i.test(n)) return "spacing";
-  if (/shadow|blur|drop/i.test(n)) return "shadow";
+  if (/shadow|blur|drop|elevation/i.test(n)) return "shadow";
+  if (/duration|easing|ease|transition|animation|motion|delay/i.test(n)) {
+    return "motion";
+  }
   if (
     /color|bg|background|text|border|accent|primary|secondary|surface|muted|foreground|fill|stroke/i.test(
       n,
@@ -272,6 +290,17 @@ function parseNamedLines(
         cssVar = tokenVar("spacing", label);
       } else if (/font|typeface|typography/.test(lower)) {
         cssVar = tokenVar("font", label);
+      } else if (/shadow|elevation/.test(lower) && isShadowValue(value)) {
+        cssVar = tokenVar("shadow", label);
+      } else if (
+        /duration|easing|ease|transition|animation|motion|delay/.test(lower) &&
+        isMotionValue(value)
+      ) {
+        // Motion is part of the brand. Dropping these here is why an imported
+        // system arrives with colors and type but nothing that moves. The
+        // value guard keeps prose out: this runs over free-text design.md
+        // lines, where "Release notes: v2" matches the label pattern.
+        cssVar = tokenVar("motion", label);
       }
 
       if (!cssVar) continue;

package/corpus/templates/design/actions/import-github.ts

@@ -1,60 +1,18 @@
 import { defineAction } from "@agent-native/core";
-import { resolveSecret } from "@agent-native/core/server";
+import { collectBuilderDesignSystemGitHubFiles } from "@agent-native/core/server";
 import {
-  validateUrl,
-  parseOwnerRepo,
-  fetchGitHubJson,
-  fetchGitHubJsonResult,
-  fetchGitHubRaw,
   parseTailwindConfig,
   parseCss,
   detectStylingFramework,
-  MAX_FILES,
-  MAX_FILE_SIZE,
-  ROOT_PATTERNS,
-  SECONDARY_PATHS,
   COLOR_VAR_PATTERN,
 } from "@agent-native/core/server/design-token-utils";
 import { z } from "zod";
 
-function githubAccessError(
-  owner: string,
-  repo: string,
-  status: number,
-  hasToken: boolean,
-  message?: string,
-): Error {
-  const repoLabel = `${owner}/${repo}`;
-  const suffix = message ? ` GitHub said: ${message}` : "";
-
-  if (!hasToken && (status === 401 || status === 403 || status === 404)) {
-    return new Error(
-      `Could not access ${repoLabel}. Public repositories work without setup; private repositories require a fine-grained GitHub personal access token saved as GITHUB_TOKEN in Settings > Secrets. Limit the token to this repository and grant Repository permissions > Contents: Read-only.${suffix}`,
-    );
-  }
-
-  if (hasToken && (status === 401 || status === 403 || status === 404)) {
-    return new Error(
-      `Could not access ${repoLabel} with the saved GITHUB_TOKEN. Check that the token is not expired, the repository is selected for the token, organization SSO/approval is complete, and Repository permissions > Contents is set to Read-only.${suffix}`,
-    );
-  }
-
-  if (status === 429) {
-    return new Error(
-      `GitHub rate-limited requests for ${repoLabel}. Save a GITHUB_TOKEN in Settings > Secrets or try again after the rate limit resets.${suffix}`,
-    );
-  }
-
-  return new Error(
-    `Could not list repository contents for ${repoLabel} (GitHub returned ${status || "an error"}).${suffix}`,
-  );
-}
-
 export default defineAction({
   description:
     "Import design tokens from a GitHub repository. " +
     "Reads Tailwind configs, CSS files, theme/token files, and package.json " +
-    "to extract colors, fonts, spacing, and CSS custom properties. " +
+    "to extract colors, fonts, spacing, and CSS custom properties. Supports a pinned ref and file/folder scope. " +
     "Private repositories require a saved GITHUB_TOKEN secret; never ask users to paste a token into chat.",
   schema: z.object({
     repoUrl: z
@@ -62,103 +20,36 @@ export default defineAction({
       .describe(
         'GitHub repository URL (e.g. "https://github.com/org/repo" or "org/repo")',
       ),
+    ref: z
+      .string()
+      .trim()
+      .min(1)
+      .optional()
+      .describe("Optional branch, tag, or commit"),
+    include: z
+      .array(z.string().trim().min(1))
+      .optional()
+      .describe("Optional repository-relative files or folders to include"),
+    exclude: z
+      .array(z.string().trim().min(1))
+      .optional()
+      .describe("Optional repository-relative files or folders to exclude"),
   }),
   readOnly: true,
   http: { method: "GET" },
-  run: async ({ repoUrl }) => {
-    const { owner, repo } = parseOwnerRepo(repoUrl.trim());
-    const githubToken = await resolveSecret("GITHUB_TOKEN");
-    const githubOptions = { token: githubToken };
-
-    validateUrl(`https://api.github.com/repos/${owner}/${repo}`);
-
-    const rawFiles: Record<string, string> = {};
-    let fetchedCount = 0;
-
-    async function collectFile(path: string): Promise<void> {
-      if (fetchedCount >= MAX_FILES) return;
-      const content = await fetchGitHubRaw(owner, repo, path, githubOptions);
-      if (content) {
-        rawFiles[path] = content;
-        fetchedCount++;
-      }
-    }
-
-    // 1. List repository root
-    const rootResult = await fetchGitHubJsonResult<
-      Array<{
-        name: string;
-        type: string;
-        size?: number;
-      }>
-    >(owner, repo, "", githubOptions);
-    const rootListing = rootResult.data;
-
-    if (!rootResult.ok || !Array.isArray(rootListing)) {
-      throw githubAccessError(
-        owner,
-        repo,
-        rootResult.status,
-        !!githubToken,
-        rootResult.message,
-      );
-    }
-
-    // 2. Fetch root-level files matching patterns
-    const rootFilePromises: Promise<void>[] = [];
-    for (const entry of rootListing) {
-      if (entry.type !== "file") continue;
-      if (entry.size && entry.size > MAX_FILE_SIZE) continue;
-      const matches = ROOT_PATTERNS.some((p) => p.test(entry.name));
-      if (matches && fetchedCount < MAX_FILES) {
-        rootFilePromises.push(collectFile(entry.name));
-      }
-    }
-    await Promise.all(rootFilePromises);
-
-    // 3. Fetch secondary paths (files and directories)
-    const secondaryPromises: Promise<void>[] = [];
-    for (const path of SECONDARY_PATHS) {
-      if (fetchedCount >= MAX_FILES) break;
-
-      if (/\.\w+$/.test(path)) {
-        secondaryPromises.push(collectFile(path));
-      } else {
-        secondaryPromises.push(
-          (async () => {
-            const listing = (await fetchGitHubJson(
-              owner,
-              repo,
-              path,
-              githubOptions,
-            )) as Array<{
-              name: string;
-              type: string;
-              path: string;
-              size?: number;
-            }> | null;
-            if (!listing || !Array.isArray(listing)) return;
-            const innerPromises: Promise<void>[] = [];
-            for (const entry of listing) {
-              if (fetchedCount >= MAX_FILES) break;
-              if (entry.type !== "file") continue;
-              if (entry.size && entry.size > MAX_FILE_SIZE) continue;
-              if (
-                /\.(css|scss|less)$/.test(entry.name) ||
-                /theme/i.test(entry.name) ||
-                /tokens?/i.test(entry.name)
-              ) {
-                innerPromises.push(collectFile(entry.path));
-              }
-            }
-            await Promise.all(innerPromises);
-          })(),
-        );
-      }
-    }
-    await Promise.all(secondaryPromises);
+  run: async ({ repoUrl, ref, include, exclude }) => {
+    const collection = await collectBuilderDesignSystemGitHubFiles({
+      repoUrl: repoUrl.trim(),
+      ...(ref ? { ref } : {}),
+      ...(include ? { include } : {}),
+      ...(exclude ? { exclude } : {}),
+    });
+    const { source } = collection;
+    const rawFiles = Object.fromEntries(
+      collection.files.map(({ path, content }) => [path, content]),
+    );
 
-    // 4. Parse collected files
+    // Parse collected files
     let colors: Record<string, unknown> = {};
     let fonts: string[] = [];
     let spacing: Record<string, string> = {};
@@ -210,7 +101,10 @@ export default defineAction({
 
     return {
       source: "github" as const,
-      repoUrl: `https://github.com/${owner}/${repo}`,
+      repoUrl: source.repoUrl,
+      ...(source.ref ? { ref: source.ref } : {}),
+      ...(source.include?.length ? { include: source.include } : {}),
+      ...(source.exclude?.length ? { exclude: source.exclude } : {}),
       colors: Object.keys(colors).length > 0 ? colors : undefined,
       fonts: fonts.length > 0 ? fonts : undefined,
       spacing: Object.keys(spacing).length > 0 ? spacing : undefined,