@agent-native/core 0.153.10 → 0.154.0

package/corpus/templates/design/app/components/design/inspector/ImageFillControls.tsx

@@ -71,7 +71,10 @@ function readFileAsDataUrl(file: File): Promise<string> {
   });
 }
 
-const CHECKER_A = "#d4d4d4";
+// guard:allow-raw-color — fixed light checkerboard tile keeps transparency visible.
+const CHECKER_A = "#e5e5e5";
+// guard:allow-raw-color — fixed light checkerboard tile keeps transparency visible.
+const CHECKER_B = "#f5f5f5";
 const CHECKERBOARD_IMAGE = `linear-gradient(45deg, ${CHECKER_A} 25%, transparent 25%), linear-gradient(-45deg, ${CHECKER_A} 25%, transparent 25%), linear-gradient(45deg, transparent 75%, ${CHECKER_A} 75%), linear-gradient(-45deg, transparent 75%, ${CHECKER_A} 75%)`;
 const FIT_MARKER_RE =
   /\/\*\s*agent-native-image-fit:(fill|fit|crop|tile)\s*\*\//i;
@@ -345,6 +348,7 @@ export function ImageFillControls({
           backgroundImage: value.url
             ? `url("${escapeForQuotedUrl(value.url.trim())}")`
             : CHECKERBOARD_IMAGE,
+          backgroundColor: value.url ? undefined : CHECKER_B,
           backgroundSize: value.url
             ? value.fit === "fit"
               ? "contain"

package/corpus/templates/design/app/hooks/use-question-flow.ts

@@ -7,6 +7,7 @@ import { type PromptComposerSubmitOptions } from "@agent-native/core/client/comp
 import { useCallback } from "react";
 
 import { sendToDesignAgentChat } from "@/lib/agent-chat";
+import { loadDesignSystemGenerationContext } from "@/pages/design-editor/generation-prompt-directives";
 
 export interface QuestionFlowModelSelection {
   model?: string;
@@ -14,6 +15,23 @@ export interface QuestionFlowModelSelection {
   effort?: PromptComposerSubmitOptions["effort"];
 }
 
+/**
+ * What the user actually supplied at kickoff. The intake turn is forced to emit
+ * only a questionnaire and then stop, so THIS continuation is the turn that
+ * writes HTML — and a fresh thread inherits nothing. Re-sending the brief here
+ * is the only thing that puts the user's own prompt, reference screenshots, and
+ * design system in front of the model at the moment it generates.
+ */
+export interface QuestionFlowGenerationBrief {
+  /** The user's original words, replayed verbatim — never a paraphrase. */
+  prompt?: string;
+  designSystemId?: string | null;
+  /** Data URLs; re-attached so the reference screenshot survives the hop. */
+  images?: string[];
+  /** Extracted text from uploaded files (specs, outlines, token dumps). */
+  uploadedFileContext?: string;
+}
+
 interface UseQuestionFlowOptions {
   enabled?: boolean;
   continuationTabId?: string | null;
@@ -25,12 +43,49 @@ interface UseQuestionFlowOptions {
    * filled after render, so a snapshot taken here would be the pre-kickoff one.
    */
   getModelSelection?: () => QuestionFlowModelSelection | null | undefined;
+  /** Read at send time, for the same reason as `getModelSelection`. */
+  getGenerationBrief?: () => QuestionFlowGenerationBrief | null | undefined;
 }
 
 function designQuestionsStateKey(designId: string | undefined): string {
   return designId ? `show-questions:${designId}` : "show-questions";
 }
 
+/**
+ * Render the kickoff brief as prompt context for the continuation turn.
+ * Exported and pure so the carry-through is testable without a DOM — this is
+ * the whole fix for "the agent ignored my design system / screenshot / brief".
+ */
+export function buildGenerationBriefContext(
+  brief: QuestionFlowGenerationBrief | null | undefined,
+  designSystemContext: string,
+): string {
+  return [
+    brief?.prompt?.trim()
+      ? [
+          "## The user's original request (verbatim)",
+          "This is the spec for what to build. The answers below refine it;",
+          "they do not replace it. Do not restate it as a looser paraphrase.",
+          "",
+          brief.prompt.trim(),
+        ].join("\n")
+      : "",
+    brief?.images?.length
+      ? [
+          `## ${brief.images.length} reference image(s) re-attached to this message`,
+          "Treat an attached UI screenshot as a layout specification to",
+          "reproduce — its structure, hierarchy, density, and component",
+          "grammar — not as loose inspiration. Match it unless an answer",
+          "below explicitly overrides a part of it.",
+        ].join("\n")
+      : "",
+    brief?.uploadedFileContext?.trim() ?? "",
+    designSystemContext,
+  ]
+    .filter(Boolean)
+    .join("\n\n");
+}
+
 const RESPONSIVE_GENERATION_REQUIREMENTS =
   'Responsive behavior is mandatory for every web design. Read the form-factor answer above: for Desktop or Both/responsive, call generate-design with `primaryViewport: "desktop"` and a 1440x1024 canvas frame; use `primaryViewport: "mobile"` only for an explicitly mobile-primary choice. Use mobile-first responsive CSS, then take desktop and mobile screenshots and fix any overflow before reporting the design complete.';
 
@@ -47,6 +102,7 @@ export function useQuestionFlow(
     continuationTabId,
     onContinue,
     getModelSelection,
+    getGenerationBrief,
   }: UseQuestionFlowOptions = {},
 ) {
   const stateKey = designQuestionsStateKey(designId);
@@ -79,9 +135,21 @@ export function useQuestionFlow(
   });
 
   const sendContinuation = useCallback(
-    (message: string, context?: string) => {
+    async (message: string, context?: string) => {
       const selection = getModelSelection?.() ?? {};
       const { model, engine, effort } = selection;
+      const brief = getGenerationBrief?.() ?? null;
+      // Re-hydrated rather than snapshotted at kickoff: the user can link or
+      // change the design system while the questionnaire is open. This never
+      // throws — a load failure returns instruction text telling the agent to
+      // stop rather than improvise a generic style.
+      const designSystemContext = brief?.designSystemId
+        ? await loadDesignSystemGenerationContext(brief.designSystemId)
+        : "";
+      const briefContext = buildGenerationBriefContext(
+        brief,
+        designSystemContext,
+      );
       // Always request `newTab` (mirroring useAgentGenerating.submit's
       // default). Without it, when there is no continuationTabId yet the
       // message goes to whatever tab is currently active, but the id we
@@ -96,9 +164,10 @@ export function useQuestionFlow(
       // real destination thread.
       const tabId = sendToDesignAgentChat({
         message,
-        context,
+        context: [briefContext, context].filter(Boolean).join("\n\n"),
         submit: true,
         newTab: true,
+        ...(brief?.images?.length ? { images: brief.images } : {}),
         ...(continuationTabId ? { tabId: continuationTabId } : {}),
         ...(model ? { model } : {}),
         ...(engine ? { engine } : {}),
@@ -107,7 +176,14 @@ export function useQuestionFlow(
       onContinue?.(tabId);
       flow.clear();
     },
-    [continuationTabId, designId, flow, getModelSelection, onContinue],
+    [
+      continuationTabId,
+      designId,
+      flow,
+      getGenerationBrief,
+      getModelSelection,
+      onContinue,
+    ],
   );
 
   const handleSubmit = useCallback(
@@ -129,13 +205,13 @@ export function useQuestionFlow(
         .filter(Boolean)
         .join("\n");
 
-      sendContinuation("Here are my answers — go ahead.", context);
+      void sendContinuation("Here are my answers — go ahead.", context);
     },
     [designId, sendContinuation],
   );
 
   const handleSkip = useCallback(() => {
-    sendContinuation(
+    void sendContinuation(
       "Skip the questions — decide for me.",
       designId
         ? `The user skipped the pre-generation questions for design ${designId}. Proceed with reasonable defaults. ${RESPONSIVE_GENERATION_REQUIREMENTS} Generate one polished first direction unless the original prompt explicitly requested options.`

package/corpus/templates/design/app/i18n/en-US.ts

@@ -25,7 +25,7 @@ const messages = {
     commentMode: "Comment",
     sendToAgent: "Send to agent",
     sendingToAgent: "Sending to agent…",
-    enterToPost: "Enter to post · Shift+Enter for a new line",
+    enterToPost: "Enter to post · Shift Enter for a new line",
     post: "Post",
     posting: "Posting…",
     postFailed: "Could not post this comment",

package/corpus/templates/design/app/i18n-data.ts

@@ -754,7 +754,7 @@ const enUS = {
         big: "Big nudge",
         unit: "px",
         description:
-          "Arrow keys move by the small amount and Shift+arrow by the big one. Inside an auto layout frame, arrows reorder the layer instead of moving it.",
+          "Arrow keys move by the small amount and Shift arrow by the big one. Inside an auto layout frame, arrows reorder the layer instead of moving it.",
       },
       keys: {
         or: "or",
@@ -1487,6 +1487,8 @@ const enUS = {
     websiteUrl: "Website-URL",
     add: "Add",
     githubRepository: "GitHub repository",
+    githubRef: "Branch, tag, or commit (optional)",
+    githubPaths: "Files or folders, comma-separated (optional)",
     privateRepoPrefix: "Private repos need a fine-grained token saved as",
     privateRepoSuffix: "with Contents read access.",
     localCodeFiles: "Connect code files",
@@ -1658,6 +1660,7 @@ const enUS = {
       logos: "Logos",
       assets: "Assets",
       savedCount: "{{count}} saved",
+      namedTokens: "Named tokens",
       colorLabels: {
         primary: "Primary",
         secondary: "Secondary",
@@ -1964,6 +1967,8 @@ const designLocaleOverrides = {
       websiteUrl: "网站URL",
       add: "添加",
       githubRepository: "GitHub 存储库",
+      githubRef: "分支、标签或提交（可选）",
+      githubPaths: "文件或文件夹，以逗号分隔（可选）",
       privateRepoPrefix: "私人仓库需要一个细粒度的令牌，另存为",
       privateRepoSuffix: "具有内容读取权限。",
       localCodeFiles: "连接代码文件",
@@ -2128,6 +2133,7 @@ const designLocaleOverrides = {
         logos: "标志",
         assets: "资产",
         savedCount: "已保存 {{count}} 个",
+        namedTokens: "具名代币",
         colorLabels: {
           primary: "基本的",
           secondary: "中学",
@@ -2379,6 +2385,8 @@ const designLocaleOverrides = {
       websiteUrl: "Sitio web URL",
       add: "Agregar",
       githubRepository: "repositorio GitHub",
+      githubRef: "Rama, etiqueta o commit (opcional)",
+      githubPaths: "Archivos o carpetas, separados por comas (opcional)",
       privateRepoPrefix:
         "Los repositorios privados necesitan un token detallado guardado como",
       privateRepoSuffix: "con acceso de lectura de contenidos.",
@@ -2558,6 +2566,7 @@ const designLocaleOverrides = {
         logos: "Logotipos",
         assets: "Activos",
         savedCount: "{{count}} guardado",
+        namedTokens: "Tokens con nombre",
         colorLabels: {
           primary: "Primario",
           secondary: "Secundario",
@@ -2814,6 +2823,9 @@ const designLocaleOverrides = {
       websiteUrl: "Site Web URL",
       add: "Ajouter",
       githubRepository: "référentiel GitHub",
+      githubRef: "Branche, tag ou commit (facultatif)",
+      githubPaths:
+        "Fichiers ou dossiers, séparés par des virgules (facultatif)",
       privateRepoPrefix:
         "Les dépôts privés nécessitent un jeton à granularité fine enregistré sous",
       privateRepoSuffix: "avec accès en lecture au contenu.",
@@ -2993,6 +3005,7 @@ const designLocaleOverrides = {
         logos: "Logos",
         assets: "Actifs",
         savedCount: "{{count}} enregistré",
+        namedTokens: "Jetons nommés",
         colorLabels: {
           primary: "Primaire",
           secondary: "Secondaire",
@@ -3249,6 +3262,8 @@ const designLocaleOverrides = {
       websiteUrl: "Website URL",
       add: "Hinzufügen",
       githubRepository: "GitHub-Repository",
+      githubRef: "Branch, Tag oder Commit (optional)",
+      githubPaths: "Dateien oder Ordner, durch Kommas getrennt (optional)",
       privateRepoPrefix:
         "Private Repos benötigen einen feinkörnigen Token, der unter gespeichert wird",
       privateRepoSuffix: "mit Lesezugriff auf Inhalte.",
@@ -3429,6 +3444,7 @@ const designLocaleOverrides = {
         logos: "Logos",
         assets: "Vermögenswerte",
         savedCount: "{{count}} gespeichert",
+        namedTokens: "Benannte Tokens",
         colorLabels: {
           primary: "Primär",
           secondary: "Sekundär",
@@ -3684,6 +3700,8 @@ const designLocaleOverrides = {
       websiteUrl: "ウェブサイト URL",
       add: "追加",
       githubRepository: "GitHub リポジトリ",
+      githubRef: "ブランチ、タグ、コミット（任意）",
+      githubPaths: "ファイルまたはフォルダー（カンマ区切り、任意）",
       privateRepoPrefix:
         "プライベート リポジトリには、次のように保存されたきめ細かいトークンが必要です。",
       privateRepoSuffix: "コンテンツ読み取りアクセス付き。",
@@ -3860,6 +3878,7 @@ const designLocaleOverrides = {
         logos: "ロゴ",
         assets: "資産",
         savedCount: "{{count}} 保存しました",
+        namedTokens: "名前付きトークン",
         colorLabels: {
           primary: "主要な",
           secondary: "二次",
@@ -4113,6 +4132,8 @@ const designLocaleOverrides = {
       websiteUrl: "웹사이트 URL",
       add: "추가하다",
       githubRepository: "GitHub 저장소",
+      githubRef: "브랜치, 태그 또는 커밋 (선택 사항)",
+      githubPaths: "파일 또는 폴더, 쉼표로 구분 (선택 사항)",
       privateRepoPrefix:
         "비공개 저장소에는 다음과 같이 저장된 세분화된 토큰이 필요합니다.",
       privateRepoSuffix: "콘텐츠 읽기 액세스 권한이 있습니다.",
@@ -4284,6 +4305,7 @@ const designLocaleOverrides = {
         logos: "로고",
         assets: "자산",
         savedCount: "{{count}}가 저장되었습니다.",
+        namedTokens: "이름이 지정된 토큰",
         colorLabels: {
           primary: "주요한",
           secondary: "반성",
@@ -4538,6 +4560,8 @@ const designLocaleOverrides = {
       websiteUrl: "Site URL",
       add: "Adicionar",
       githubRepository: "repositório GitHub",
+      githubRef: "Branch, tag ou commit (opcional)",
+      githubPaths: "Arquivos ou pastas, separados por vírgulas (opcional)",
       privateRepoPrefix:
         "Os repositórios privados precisam de um token refinado salvo como",
       privateRepoSuffix: "com acesso de leitura de conteúdo.",
@@ -4715,6 +4739,7 @@ const designLocaleOverrides = {
         logos: "Logotipos",
         assets: "Ativos",
         savedCount: "{{count}} salvo",
+        namedTokens: "Tokens nomeados",
         colorLabels: {
           primary: "Primário",
           secondary: "Secundário",
@@ -4967,6 +4992,8 @@ const designLocaleOverrides = {
       websiteUrl: "वेबसाइट URL",
       add: "जोड़ना",
       githubRepository: "GitHub रिपॉजिटरी",
+      githubRef: "ब्रांच, टैग या कमिट (वैकल्पिक)",
+      githubPaths: "फ़ाइलें या फ़ोल्डर, कॉमा से अलग (वैकल्पिक)",
       privateRepoPrefix:
         "निजी रेपो को एक बढ़िया टोकन के रूप में सहेजे जाने की आवश्यकता होती है",
       privateRepoSuffix: "सामग्री पढ़ने की पहुंच के साथ।",
@@ -5137,6 +5164,7 @@ const designLocaleOverrides = {
         logos: "लोगो",
         assets: "संपत्ति",
         savedCount: "{{count}} सहेजा गया",
+        namedTokens: "नामित टोकन",
         colorLabels: {
           primary: "प्राथमिक",
           secondary: "माध्यमिक",
@@ -5387,6 +5415,8 @@ const designLocaleOverrides = {
       websiteUrl: "موقع URL",
       add: "يضيف",
       githubRepository: "مستودع GitHub",
+      githubRef: "فرع أو وسم أو التزام (اختياري)",
+      githubPaths: "الملفات أو المجلدات، مفصولة بفواصل (اختياري)",
       privateRepoPrefix:
         "تحتاج عمليات إعادة الشراء الخاصة إلى رمز مميز محفوظ باسم",
       privateRepoSuffix: "مع محتويات الوصول للقراءة.",
@@ -5558,6 +5588,7 @@ const designLocaleOverrides = {
         logos: "الشعارات",
         assets: "أصول",
         savedCount: "تم حفظ {{count}}",
+        namedTokens: "الرموز المميزة المسماة",
         colorLabels: {
           primary: "أساسي",
           secondary: "ثانوي",

package/corpus/templates/design/app/i18n-keyboard-shortcuts.ts

@@ -58,7 +58,7 @@ export const keyboardShortcutLabels = {
     nudgeAmountSmall: "小距離",
     nudgeAmountBig: "大距離",
     nudgeAmountDescription:
-      "方向鍵以小距離移動，Shift+方向鍵以大距離移動。在自動版面配置框架內，方向鍵改為調整圖層順序。",
+      "方向鍵以小距離移動，Shift 方向鍵以大距離移動。在自動版面配置框架內，方向鍵改為調整圖層順序。",
   },
   "zh-CN": {
     title: "键盘快捷键",
@@ -76,7 +76,7 @@ export const keyboardShortcutLabels = {
     nudgeAmountSmall: "小距离",
     nudgeAmountBig: "大距离",
     nudgeAmountDescription:
-      "方向键以小距离移动，Shift+方向键以大距离移动。在自动布局框架内，方向键改为调整图层顺序。",
+      "方向键以小距离移动，Shift 方向键以大距离移动。在自动布局框架内，方向键改为调整图层顺序。",
   },
   "es-ES": {
     title: "Atajos de teclado",
@@ -95,7 +95,7 @@ export const keyboardShortcutLabels = {
     nudgeAmountSmall: "Desplazamiento pequeño",
     nudgeAmountBig: "Desplazamiento grande",
     nudgeAmountDescription:
-      "Las flechas mueven la cantidad pequeña y Mayús+flecha la grande. Dentro de un marco de autodiseño, las flechas reordenan la capa.",
+      "Las flechas mueven la cantidad pequeña y Mayús flecha la grande. Dentro de un marco de autodiseño, las flechas reordenan la capa.",
   },
   "fr-FR": {
     title: "Raccourcis clavier",
@@ -115,7 +115,7 @@ export const keyboardShortcutLabels = {
     nudgeAmountSmall: "Petit déplacement",
     nudgeAmountBig: "Grand déplacement",
     nudgeAmountDescription:
-      "Les flèches déplacent de la petite valeur et Maj+flèche de la grande. Dans un cadre en disposition automatique, les flèches réorganisent le calque.",
+      "Les flèches déplacent de la petite valeur et Maj flèche de la grande. Dans un cadre en disposition automatique, les flèches réorganisent le calque.",
   },
   "de-DE": {
     title: "Tastenkürzel",
@@ -135,7 +135,7 @@ export const keyboardShortcutLabels = {
     nudgeAmountSmall: "Kleiner Schritt",
     nudgeAmountBig: "Großer Schritt",
     nudgeAmountDescription:
-      "Pfeiltasten verschieben um den kleinen Wert, Umschalt+Pfeil um den großen. In einem Auto-Layout-Rahmen ordnen die Pfeiltasten die Ebene neu an.",
+      "Pfeiltasten verschieben um den kleinen Wert, Umschalt Pfeil um den großen. In einem Auto-Layout-Rahmen ordnen die Pfeiltasten die Ebene neu an.",
   },
   "ja-JP": {
     title: "キーボードショートカット",
@@ -153,7 +153,7 @@ export const keyboardShortcutLabels = {
     nudgeAmountSmall: "小さい移動量",
     nudgeAmountBig: "大きい移動量",
     nudgeAmountDescription:
-      "矢印キーは小さい移動量、Shift+矢印キーは大きい移動量で移動します。オートレイアウトフレーム内では、矢印キーはレイヤーの順序を変更します。",
+      "矢印キーは小さい移動量、Shift 矢印キーは大きい移動量で移動します。オートレイアウトフレーム内では、矢印キーはレイヤーの順序を変更します。",
   },
   "ko-KR": {
     title: "키보드 단축키",
@@ -171,7 +171,7 @@ export const keyboardShortcutLabels = {
     nudgeAmountSmall: "작은 이동",
     nudgeAmountBig: "큰 이동",
     nudgeAmountDescription:
-      "화살표 키는 작은 간격으로, Shift+화살표 키는 큰 간격으로 이동합니다. 오토 레이아웃 프레임 안에서는 화살표 키가 레이어 순서를 변경합니다.",
+      "화살표 키는 작은 간격으로, Shift 화살표 키는 큰 간격으로 이동합니다. 오토 레이아웃 프레임 안에서는 화살표 키가 레이어 순서를 변경합니다.",
   },
   "pt-BR": {
     title: "Atalhos de teclado",
@@ -191,7 +191,7 @@ export const keyboardShortcutLabels = {
     nudgeAmountSmall: "Deslocamento pequeno",
     nudgeAmountBig: "Deslocamento grande",
     nudgeAmountDescription:
-      "As setas movem pela distância pequena e Shift+seta pela grande. Dentro de um frame com layout automático, as setas reordenam a camada.",
+      "As setas movem pela distância pequena e Shift seta pela grande. Dentro de um frame com layout automático, as setas reordenam a camada.",
   },
   "hi-IN": {
     title: "कीबोर्ड शॉर्टकट",
@@ -209,7 +209,7 @@ export const keyboardShortcutLabels = {
     nudgeAmountSmall: "छोटी नज",
     nudgeAmountBig: "बड़ी नज",
     nudgeAmountDescription:
-      "ऐरो कुंजियाँ छोटी दूरी से और Shift+ऐरो बड़ी दूरी से ले जाती हैं। ऑटो लेआउट फ़्रेम के अंदर ऐरो कुंजियाँ लेयर का क्रम बदलती हैं।",
+      "ऐरो कुंजियाँ छोटी दूरी से और Shift ऐरो बड़ी दूरी से ले जाती हैं। ऑटो लेआउट फ़्रेम के अंदर ऐरो कुंजियाँ लेयर का क्रम बदलती हैं।",
   },
   "ar-SA": {
     title: "اختصارات لوحة المفاتيح",
@@ -227,7 +227,7 @@ export const keyboardShortcutLabels = {
     nudgeAmountSmall: "إزاحة صغيرة",
     nudgeAmountBig: "إزاحة كبيرة",
     nudgeAmountDescription:
-      "تحرّك مفاتيح الأسهم بالمقدار الصغير، وShift+سهم بالمقدار الكبير. داخل إطار التخطيط التلقائي، تعيد مفاتيح الأسهم ترتيب الطبقة.",
+      "تحرّك مفاتيح الأسهم بالمقدار الصغير، وShift سهم بالمقدار الكبير. داخل إطار التخطيط التلقائي، تعيد مفاتيح الأسهم ترتيب الطبقة.",
   },
 } satisfies Record<Exclude<LocaleCode, "en-US">, KeyboardShortcutLabels>;
 

package/corpus/templates/design/app/pages/DesignSystemSetup.tsx

@@ -43,6 +43,8 @@ import { cn } from "@/lib/utils";
 interface GitHubLink {
   id: string;
   url: string;
+  ref?: string;
+  include?: string[];
 }
 
 interface UploadedFile {
@@ -73,6 +75,12 @@ interface BuilderIndexInput {
   projectName?: string;
   description?: string;
   githubRepoUrl?: string;
+  githubSources?: Array<{
+    repoUrl: string;
+    ref?: string;
+    include?: string[];
+    exclude?: string[];
+  }>;
   connectedProjectId?: string;
   codeFiles?: Array<{
     filename: string;
@@ -93,6 +101,8 @@ export default function DesignSystemSetup() {
   const [websiteUrl, setWebsiteUrl] = useState("");
   const [websiteUrls, setWebsiteUrls] = useState<string[]>([]);
   const [githubUrl, setGithubUrl] = useState("");
+  const [githubRef, setGithubRef] = useState("");
+  const [githubPaths, setGithubPaths] = useState("");
   const [githubLinks, setGithubLinks] = useState<GitHubLink[]>([]);
   const [codeFiles, setCodeFiles] = useState<UploadedFile[]>([]);
   const [docFiles, setDocFiles] = useState<UploadedFile[]>([]);
@@ -308,10 +318,24 @@ export default function DesignSystemSetup() {
       setValidationError(t("designSystemSetup.errors.githubUrl"));
       return;
     }
-    setGithubLinks((prev) => [...prev, { id: crypto.randomUUID(), url }]);
+    const include = githubPaths
+      .split(/[\n,]/)
+      .map((path) => path.trim().replace(/^\/+|\/+$/g, ""))
+      .filter(Boolean);
+    setGithubLinks((prev) => [
+      ...prev,
+      {
+        id: crypto.randomUUID(),
+        url,
+        ...(githubRef.trim() ? { ref: githubRef.trim() } : {}),
+        ...(include.length > 0 ? { include: [...new Set(include)] } : {}),
+      },
+    ]);
     setGithubUrl("");
+    setGithubRef("");
+    setGithubPaths("");
     setValidationError(null);
-  }, [githubUrl, t]);
+  }, [githubPaths, githubRef, githubUrl, t]);
 
   const removeGithubLink = useCallback((id: string) => {
     setGithubLinks((prev) => prev.filter((l) => l.id !== id));
@@ -441,12 +465,26 @@ export default function DesignSystemSetup() {
     const normalizedWebsiteUrls = pendingWebsiteUrl
       ? [...websiteUrls, pendingWebsiteUrl]
       : websiteUrls;
+    const pendingGithubInclude = githubPaths
+      .split(/[\n,]/)
+      .map((path) => path.trim().replace(/^\/+|\/+$/g, ""))
+      .filter(Boolean);
     const normalizedGithubLinks = pendingGithubUrl
-      ? [...githubLinks, { id: "pending", url: pendingGithubUrl }]
+      ? [
+          ...githubLinks,
+          {
+            id: "pending",
+            url: pendingGithubUrl,
+            ...(githubRef.trim() ? { ref: githubRef.trim() } : {}),
+            ...(pendingGithubInclude.length > 0
+              ? { include: [...new Set(pendingGithubInclude)] }
+              : {}),
+          },
+        ]
       : githubLinks;
 
-    const isSingleGithubSource =
-      normalizedGithubLinks.length === 1 &&
+    const isGithubOnlySource =
+      normalizedGithubLinks.length > 0 &&
       normalizedWebsiteUrls.length === 0 &&
       codeFiles.length === 0 &&
       !builderIndexResult &&
@@ -455,10 +493,7 @@ export default function DesignSystemSetup() {
       assets.length === 0 &&
       !selectedProjectId;
 
-    if (isSingleGithubSource) {
-      const githubRepoUrl = normalizedGithubLinks[0]?.url;
-      if (!githubRepoUrl) return;
-
+    if (isGithubOnlySource) {
       setValidationError(null);
       try {
         await indexSystemMutation.mutateAsync({
@@ -467,7 +502,11 @@ export default function DesignSystemSetup() {
             [notes.trim(), customInstructions.trim()]
               .filter(Boolean)
               .join("\n\n") || undefined,
-          githubRepoUrl,
+          githubSources: normalizedGithubLinks.map((link) => ({
+            repoUrl: link.url,
+            ...(link.ref ? { ref: link.ref } : {}),
+            ...(link.include?.length ? { include: link.include } : {}),
+          })),
         });
         toast.success(t("designSystemSetup.githubIndexStarted"));
         navigate("/design-systems");
@@ -507,7 +546,15 @@ export default function DesignSystemSetup() {
 
     if (normalizedGithubLinks.length > 0) {
       parts.push(
-        `\n## Connect Code: GitHub Repositories\nStart Builder DSI indexing for each repository with \`index-design-system-with-builder\`:\n${normalizedGithubLinks.map((l) => `- ${l.url}`).join("\n")}\n\nBuilder is the source of truth for repo/code design-system indexing. The action also creates a local selectable proxy design system for Design flows. If Builder is not connected, stop and tell me to connect Builder (free tier available) from Settings instead of asking me to paste repository credentials into chat.`,
+        `\n## Connect Code: GitHub Repositories\nMake one call to \`index-design-system-with-builder\` with \`githubSources\` set to this JSON array:\n\n\`\`\`json\n${JSON.stringify(
+          normalizedGithubLinks.map((link) => ({
+            repoUrl: link.url,
+            ...(link.ref ? { ref: link.ref } : {}),
+            ...(link.include?.length ? { include: link.include } : {}),
+          })),
+          null,
+          2,
+        )}\n\`\`\`\n\nBuilder is the source of truth for repo/code design-system indexing. The action creates one local selectable proxy design system for Design flows. If Builder is not connected, stop and tell me to connect Builder (free tier available) from Settings instead of asking me to paste repository credentials into chat.`,
       );
     }
 
@@ -629,6 +676,8 @@ export default function DesignSystemSetup() {
     websiteUrl,
     websiteUrls,
     githubUrl,
+    githubRef,
+    githubPaths,
     githubLinks,
     codeFiles,
     builderIndexResult,
@@ -935,6 +984,22 @@ export default function DesignSystemSetup() {
                     {t("designSystemSetup.add")}
                   </Button>
                 </div>
+                <div className="grid gap-2 sm:grid-cols-2">
+                  <Input
+                    value={githubRef}
+                    onChange={(e) => setGithubRef(e.target.value)}
+                    placeholder={t("designSystemSetup.githubRef")}
+                    aria-label={t("designSystemSetup.githubRef")}
+                    className="bg-accent/50 border-border"
+                  />
+                  <Input
+                    value={githubPaths}
+                    onChange={(e) => setGithubPaths(e.target.value)}
+                    placeholder={t("designSystemSetup.githubPaths")}
+                    aria-label={t("designSystemSetup.githubPaths")}
+                    className="bg-accent/50 border-border"
+                  />
+                </div>
                 <p className="mt-2 text-xs text-muted-foreground/80">
                   {t("designSystemSetup.privateRepoPrefix")}{" "}
                   <a
@@ -954,6 +1019,13 @@ export default function DesignSystemSetup() {
                       >
                         <IconCheck className="w-3.5 h-3.5 text-green-400/60 shrink-0" />
                         <span className="truncate flex-1">{link.url}</span>
+                        {link.ref || link.include?.length ? (
+                          <span className="shrink-0 text-[10px] text-muted-foreground/70">
+                            {[link.ref, link.include?.join(", ")]
+                              .filter(Boolean)
+                              .join(" · ")}
+                          </span>
+                        ) : null}
                         <button
                           onClick={() => removeGithubLink(link.id)}
                           className="text-muted-foreground/70 hover:text-muted-foreground shrink-0 cursor-pointer"

package/corpus/templates/design/app/pages/DesignSystems.tsx

@@ -109,6 +109,8 @@ interface DesignSystemData {
   logos?: Array<{ url?: string; name?: string; variant?: string }>;
   defaults?: Record<string, unknown>;
   notes?: unknown;
+  /** The source system's own named vocabulary; absent on kits predating it. */
+  tokens?: unknown;
 }
 
 export default function DesignSystems() {
@@ -1105,10 +1107,22 @@ function getDetailTokens(
   const borders = data?.borders ?? {};
   const defaults = data?.defaults ?? {};
   const logos = data?.logos ?? [];
+  const namedTokenCount = Array.isArray(data?.tokens) ? data.tokens.length : 0;
   return [
     ...objectPreviewItems(t("designSystems.tokenPreview.spacing"), spacing),
     ...objectPreviewItems(t("designSystems.tokenPreview.borders"), borders),
     ...objectPreviewItems(t("designSystems.tokenPreview.defaults"), defaults),
+    // The seven color roles are a summary of an import, not its extent. Without
+    // this the panel renders a 200-token system identically to a 7-token one,
+    // which reads as "it only captured a few colors".
+    namedTokenCount > 0
+      ? {
+          label: t("designSystems.tokenPreview.namedTokens"),
+          value: t("designSystems.tokenPreview.savedCount", {
+            count: namedTokenCount,
+          }),
+        }
+      : null,
     logos.length > 0
       ? {
           label: t("designSystems.tokenPreview.logos"),