@agent-native/core 0.139.0 → 0.140.0

package/corpus/README.md

@@ -31,4 +31,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 
 ## Generated Counts
 
-- template files: 7654
+- template files: 7658

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

@@ -73,6 +73,14 @@ interface DesignSystemData {
     name: string;
     variant: "light" | "dark" | "auto";
   }[];
+  tokens?: {
+    name: string;      // The source system's own name, e.g. "interactive-01"
+    cssVar: string;    // e.g. "--cds-interactive-01"
+    value: string;     // e.g. "#0F62FE" or "0.5rem"
+    type: "color" | "typography" | "spacing" | "radius" | "shadow" | "other";
+    group?: string;    // Collection path, e.g. "Colors/Interactive"
+    source?: string;   // e.g. "Carbon v11" or "globals.css"
+  }[];
   imageStyle?: {
     referenceUrls: string[];
     styleDescription: string;  // e.g., "Clean, minimal product photography"
@@ -82,6 +90,29 @@ interface DesignSystemData {
 }
 ```
 
+### The seven color roles are a summary, not the vocabulary
+
+`colors` exists so a generated page can be themed from any brand. It is **not**
+where a real design system goes. Carbon has `interactive-01`, Material has
+`md-sys-color-primary-container`; mapping those onto `secondary` throws away the
+only name the design team uses, and the Brand Kit page then shows the wrong
+label for a token the user recognises.
+
+So when a source names its tokens, populate **both**: `colors` for generation,
+and `tokens` for the real vocabulary. `tokens` is capped at 500 entries, every
+`cssVar` must be a valid custom property, and values may not contain `;`, `{`,
+`}`, `<`, `>`, or CSS comments — `create-design-system` and
+`update-design-system` reject the whole write and name the offending entries
+rather than storing a partial vocabulary that would read as a smaller system.
+
+`update-design-system` replaces the entire `data` object, so carry the existing
+`tokens` array through any edit or those names are lost.
+
+A kit with no stored `tokens` falls back to whatever names its `customCSS`
+declares, which is why the production templates already display real Carbon,
+Material, and Primer token names. Prefer real stored `tokens` when a source
+gives them to you.
+
 `imageStyle.styleDescription` is not just metadata — fold it into every
 `generate-asset` prompt for a design linked to this system, alongside the
 subject/composition/lighting direction described in the design-generation
@@ -456,7 +487,11 @@ When the user provides multiple sources, call all applicable import actions in p
 3. **Cross-reference with website** — validates colors/fonts are actually deployed
 4. **Documents supplement** — presentations may reveal brand colors not in code
 5. **Images inform mood** — color temperature, density, visual style
-6. **Aggregate into DesignSystemData** — merge all extracted tokens, resolve conflicts
+6. **Aggregate into DesignSystemData** — merge all extracted tokens, resolve
+   conflicts, and carry every extracted name into `tokens`. The import actions
+   return `cssCustomProperties` keyed by the source's real variable names; those
+   keys are the vocabulary, so do not reduce them to the seven `colors` roles and
+   drop the rest.
 7. **Call `create-design-system`** with the combined result
 8. **Link to design** via `update-design --designSystemId`
 
@@ -509,6 +544,14 @@ When generating a design that has a linked design system, replace all default CS
 }
 ```
 
+### Reference named tokens, do not inline their values
+
+`get-design-system` injects the kit's colour tokens and this requirement into
+the generation context, so follow it there: write `var(--cds-link-primary,
+#0f62fe)` rather than the colour. The fallback is required — exports and
+kit-less designs define no custom properties, and a bare `var()` renders
+transparent.
+
 Also update the Google Fonts `<link>` tag to include the design system's fonts:
 
 ```html

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

@@ -388,6 +388,263 @@ export const editorChromeBridgeScript: string = `"use strict";
     };
   }
 
+  // shared/authored-color-styles.ts
+  var AUTHORED_COLOR_PROPERTIES = [
+    "color",
+    "backgroundColor",
+    "borderColor",
+    "outlineColor",
+    // Not colours themselves, but the only place a shadow's colour keeps its name.
+    "boxShadow",
+    "textShadow"
+  ];
+  var SHORTHAND_FALLBACK = {
+    backgroundColor: "background",
+    borderColor: "border",
+    outlineColor: "outline"
+  };
+  var INHERITED_PROPERTIES = ["color"];
+  var RESET_KEYWORDS = /* @__PURE__ */ new Set([
+    "initial",
+    "inherit",
+    "unset",
+    "revert",
+    "revert-layer"
+  ]);
+  function isAuthoredColor(value) {
+    return typeof value === "string" && value !== "" && !RESET_KEYWORDS.has(value.trim().toLowerCase());
+  }
+  var LINE_STYLE_KEYWORDS = /* @__PURE__ */ new Set([
+    "none",
+    "hidden",
+    "solid",
+    "dashed",
+    "dotted",
+    "double",
+    "groove",
+    "ridge",
+    "inset",
+    "outset"
+  ]);
+  var LINE_WIDTH = /^(thin|medium|thick|-?\\d*\\.?\\d+[a-z%]*)$/i;
+  function splitTopLevel(value) {
+    const parts = [];
+    let depth = 0;
+    let current = "";
+    for (const char of value) {
+      if (char === "(") depth += 1;
+      else if (char === ")") depth -= 1;
+      if (depth === 0 && /\\s/.test(char)) {
+        if (current) parts.push(current);
+        current = "";
+        continue;
+      }
+      current += char;
+    }
+    if (current) parts.push(current);
+    return parts;
+  }
+  function lineShorthandColor(value) {
+    const rest = splitTopLevel(value).filter((part) => {
+      const lower = part.toLowerCase();
+      return !LINE_STYLE_KEYWORDS.has(lower) && !LINE_WIDTH.test(part);
+    });
+    return rest.length === 1 ? rest[0] : null;
+  }
+  function shorthandColorValue(shorthand, value) {
+    const trimmed = value.trim();
+    if (!trimmed) return null;
+    if (/url\\(|gradient\\(/i.test(trimmed)) return null;
+    if (/^var\\(.*\\)$/.test(trimmed)) return trimmed;
+    if (shorthand === "border" || shorthand === "outline") {
+      return lineShorthandColor(trimmed);
+    }
+    return /\\s/.test(trimmed) ? null : trimmed;
+  }
+  function selectorSpecificity(selector) {
+    const cleaned = selector.replace(/\\\\./g, "").replace(/\\[[^\\]]*\\]/g, " :attr ").replace(/\\(([^()]*)\\)/g, " ");
+    const count = (pattern) => (cleaned.match(pattern) ?? []).length;
+    const ids = count(/#[\\w-]+/g);
+    const classes = count(/\\.[\\w-]+/g) + count(/:(?!:)[\\w-]+/g);
+    const types = count(/(?:^|[\\s>+~])[a-zA-Z][\\w-]*/g) + count(/::[\\w-]+/g);
+    return ids * 1e4 + classes * 100 + types;
+  }
+  function matchedSpecificity(element, selectorText) {
+    let best = -1;
+    for (const selector of selectorText.split(",")) {
+      const trimmed = selector.trim();
+      if (!trimmed) continue;
+      try {
+        if (!element.matches(trimmed)) continue;
+      } catch {
+        continue;
+      }
+      best = Math.max(best, selectorSpecificity(trimmed));
+    }
+    return best;
+  }
+  var INLINE_SPECIFICITY = Number.MAX_SAFE_INTEGER;
+  function beats(next, current) {
+    if (!current) return true;
+    if (next.important !== current.important) return next.important;
+    if (next.specificity !== current.specificity) {
+      return next.specificity > current.specificity;
+    }
+    return next.order >= current.order;
+  }
+  function readRules(element, rules, out, counter) {
+    if (!rules) return;
+    for (let index = 0; index < rules.length; index += 1) {
+      const rule = rules[index];
+      if (!rule) continue;
+      const declaresOwnStyles = Boolean(rule.selectorText && rule.style);
+      if (!declaresOwnStyles) {
+        if (!rule.cssRules) continue;
+        if (rule.conditionText === void 0) {
+          readRules(element, rule.cssRules, out, counter);
+          continue;
+        }
+        let applies = false;
+        try {
+          applies = typeof window !== "undefined" && typeof window.matchMedia === "function" ? window.matchMedia(rule.conditionText).matches : false;
+        } catch {
+          applies = false;
+        }
+        if (applies) readRules(element, rule.cssRules, out, counter);
+        continue;
+      }
+      if (rule.cssRules?.length) {
+        readRules(element, rule.cssRules, out, counter);
+      }
+      if (!rule.selectorText || !rule.style) continue;
+      const specificity = matchedSpecificity(element, rule.selectorText);
+      if (specificity < 0) continue;
+      const order = counter.order++;
+      const style = rule.style;
+      const priority = (name) => style.getPropertyPriority?.(name) === "important";
+      const offer = (property, value, cssName) => {
+        const candidate = {
+          value,
+          important: priority(cssName),
+          specificity,
+          order
+        };
+        if (beats(candidate, out[property])) out[property] = candidate;
+      };
+      for (const property of AUTHORED_COLOR_PROPERTIES) {
+        const declared = style[property];
+        if (isAuthoredColor(declared)) {
+          offer(property, declared, cssPropertyName(property));
+          continue;
+        }
+        const shorthand = SHORTHAND_FALLBACK[property];
+        if (!shorthand) continue;
+        const shorthandValue = style[shorthand];
+        if (typeof shorthandValue !== "string") continue;
+        const colorOnly = shorthandColorValue(shorthand, shorthandValue);
+        if (colorOnly) offer(property, colorOnly, shorthand);
+      }
+    }
+  }
+  function cssPropertyName(property) {
+    return property.replace(/[A-Z]/g, (c) => \`-\${c.toLowerCase()}\`);
+  }
+  function authoredMatchesPainted(element, property, authored) {
+    const view = element.ownerDocument?.defaultView;
+    if (!view || typeof view.getComputedStyle !== "function") return true;
+    let painted = "";
+    try {
+      painted = view.getComputedStyle(element)[property] ?? "";
+    } catch {
+      return true;
+    }
+    if (!painted) return true;
+    const probe = element.ownerDocument.createElement("span");
+    const name = cssPropertyName(property);
+    probe.style.setProperty("display", "none");
+    probe.style.setProperty(name, authored);
+    if (!probe.style.getPropertyValue(name)) return false;
+    element.appendChild(probe);
+    let resolved = "";
+    try {
+      resolved = view.getComputedStyle(probe)[property] ?? "";
+    } catch {
+      resolved = "";
+    }
+    probe.remove();
+    return resolved === "" || resolved === painted;
+  }
+  function collectForElement(element) {
+    const ranked = {};
+    const counter = { order: 0 };
+    try {
+      const doc = element.ownerDocument;
+      const sheets = [
+        ...Array.from(doc?.styleSheets ?? []),
+        ...Array.from(
+          doc?.adoptedStyleSheets ?? []
+        )
+      ];
+      for (const sheet of sheets) {
+        let rules;
+        try {
+          rules = sheet.cssRules;
+        } catch {
+          continue;
+        }
+        readRules(element, rules, ranked, counter);
+      }
+    } catch (error) {
+      console.warn(
+        "[design] could not read stylesheets for authored colours; token names will fall back to resolved values",
+        error
+      );
+    }
+    const inline = element.style;
+    if (inline) {
+      const order = counter.order++;
+      for (const property of AUTHORED_COLOR_PROPERTIES) {
+        const value = inline[property];
+        if (!isAuthoredColor(value)) continue;
+        const candidate = {
+          value,
+          important: inline.getPropertyPriority?.(cssPropertyName(property)) === "important",
+          specificity: INLINE_SPECIFICITY,
+          order
+        };
+        if (beats(candidate, ranked[property])) ranked[property] = candidate;
+      }
+    }
+    const out = {};
+    for (const [property, candidate] of Object.entries(ranked)) {
+      out[property] = candidate.value;
+    }
+    return out;
+  }
+  function collectAuthoredColorStyles(element) {
+    const out = collectForElement(element);
+    for (const property of Object.keys(out)) {
+      if (!authoredMatchesPainted(element, property, out[property])) {
+        delete out[property];
+      }
+    }
+    for (const property of INHERITED_PROPERTIES) {
+      if (out[property]) continue;
+      let ancestor = element.parentElement;
+      while (ancestor) {
+        const inherited = collectForElement(ancestor)[property];
+        if (inherited) {
+          if (authoredMatchesPainted(element, property, inherited)) {
+            out[property] = inherited;
+          }
+          break;
+        }
+        ancestor = ancestor.parentElement;
+      }
+    }
+    return out;
+  }
+
   // app/components/design/bridge/editor-chrome.bridge.ts
   (function() {
     if (window.__anEditorChromeBridge) return;
@@ -1633,7 +1890,13 @@ export const editorChromeBridgeScript: string = `"use strict";
       "width",
       "height",
       "transform",
-      "whiteSpace"
+      "whiteSpace",
+      "color",
+      "backgroundColor",
+      "borderColor",
+      "outlineColor",
+      "boxShadow",
+      "textShadow"
     ];
     function collectInlineStyles(el) {
       var styles = {};
@@ -1837,6 +2100,7 @@ export const editorChromeBridgeScript: string = `"use strict";
           whiteSpace: cs.whiteSpace
         },
         inlineStyles: collectInlineStyles(el),
+        authoredColorStyles: collectAuthoredColorStyles(el),
         primitiveKind: el.getAttribute("data-an-primitive") || void 0,
         portableStyleSnapshot: collectPortableStyleSnapshot(el),
         boundingRect: {

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

@@ -8,6 +8,7 @@ import { nanoid } from "nanoid";
 import { z } from "zod";
 
 import { getDb, schema } from "../server/db/index.js";
+import { assertStorableDesignSystemTokens } from "../server/lib/design-system-tokens.js";
 import {
   DESIGN_SYSTEM_TEMPLATE_IDS,
   getProductionDesignSystemTemplate,
@@ -39,7 +40,13 @@ export const createDesignSystemSchema = z
       .min(1, "data is required")
       .optional()
       .describe(
-        "JSON string of DesignSystemData (required without templateId; templates supply their verified token snapshot)",
+        "JSON string of DesignSystemData (required without templateId; templates supply their verified token snapshot). " +
+          "Include a `tokens` array whenever the source names its tokens: " +
+          // guard:allow-raw-color — an agent-facing payload example, not a styled value
+          '[{ "name": "interactive-01", "cssVar": "--cds-interactive-01", "value": "#0F62FE", ' +
+          '"type": "color", "group": "Colors/Interactive", "source": "Carbon v11" }]. ' +
+          "The seven `colors` roles are a summary for generation, not a place to squash a " +
+          "real system's vocabulary into — send both.",
       ),
     assets: z
       .string()
@@ -111,15 +118,7 @@ export default defineAction({
       throw new Error("title and data are required");
     }
 
-    // Validate that data is valid JSON and not an empty primitive.
-    try {
-      const parsed = JSON.parse(resolvedData);
-      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-        throw new Error();
-      }
-    } catch {
-      throw new Error("data must be a valid JSON object string");
-    }
+    assertStorableDesignSystemTokens(resolvedData);
     if (assets) {
       try {
         JSON.parse(assets);

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

@@ -1,4 +1,8 @@
 import { defineAction } from "@agent-native/core";
+import {
+  brandKitRoleTokens,
+  resolveBrandKitTokens,
+} from "@agent-native/core/brand-kit/tokens";
 import {
   hydrateBuilderDesignSystemReference,
   parseBuilderDesignSystemProxyReference,
@@ -61,6 +65,54 @@ function formatTokenValues(tokenValues: Record<string, string>): string[] {
   ];
 }
 
+const MAX_LISTED_TOKENS = 40;
+
+/**
+ * Require generated CSS to reference tokens rather than paste their values. A
+ * colour cannot identify a token afterwards — Carbon points four at one blue.
+ */
+function tokenReferenceDirective(data: unknown): string[] {
+  if (!data || typeof data !== "object") return [];
+  const kit = data as {
+    tokens?: unknown;
+    customCSS?: unknown;
+    colors?: object | null;
+    borders?: { radius?: string } | null;
+    spacing?: object | null;
+  };
+  const tokens = [
+    ...resolveBrandKitTokens(kit),
+    ...brandKitRoleTokens(kit),
+  ].filter((token) => token.type === "color");
+  if (tokens.length === 0) return [];
+
+  const seen = new Set<string>();
+  const listed: string[] = [];
+  for (const token of tokens) {
+    if (seen.has(token.cssVar)) continue;
+    seen.add(token.cssVar);
+    listed.push(`- ${token.cssVar}: ${token.value}`);
+    if (listed.length >= MAX_LISTED_TOKENS) break;
+  }
+
+  return [
+    "",
+    "### Reference these color tokens, do not paste their values",
+    "Write the token reference with its value as a fallback:",
+    // guard:allow-raw-color — the do/don't example shown to the generating agent
+    "  background: var(--color-accent, #0f62fe);   /* yes */",
+    // guard:allow-raw-color — the counter-example it must not copy
+    "  background: #0f62fe;                        /* no  */",
+    "The fallback is required — exports and unlinked designs define no custom",
+    "properties, and a bare var() renders transparent there. Define every token",
+    "you reference in the screen's `:root` block too.",
+    ...listed,
+    seen.size > MAX_LISTED_TOKENS
+      ? `- …and ${seen.size - MAX_LISTED_TOKENS} more; call get-design-system for the full set.`
+      : "",
+  ];
+}
+
 function buildDesignSystemAgentContext({
   id,
   title,
@@ -82,6 +134,7 @@ function buildDesignSystemAgentContext({
     "## Selected Design System Context",
     `Use "${title}" (id: ${id}) as the visual source of truth for this generation.`,
     "Apply these tokens, assets, and usage notes before choosing colors, type, spacing, radius, imagery, or component language.",
+    ...tokenReferenceDirective(parseJson(data)),
   ];
 
   if (description?.trim()) {

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

@@ -1,4 +1,9 @@
 import { defineAction } from "@agent-native/core";
+import {
+  classifyBrandKitToken as classifyVar,
+  friendlyTokenName as friendlyName,
+  isColorTokenValue as isColorValue,
+} from "@agent-native/core/brand-kit/tokens";
 import { buildDeepLink } from "@agent-native/core/server";
 import {
   CODE_MAX_FILES,
@@ -116,70 +121,6 @@ function designDeepLink(designId: string): string {
   });
 }
 
-function classifyVar(name: string, value: string): ImportedTokenType {
-  const n = name.toLowerCase();
-  if (
-    /color|bg|background|text|border|accent|primary|secondary|surface|muted|foreground|fill|stroke/i.test(
-      n,
-    ) ||
-    isColorValue(value)
-  ) {
-    return "color";
-  }
-  if (/font|size|leading|tracking|weight|heading|body|type/i.test(n)) {
-    return "typography";
-  }
-  if (/radius|rounded/i.test(n)) return "radius";
-  if (/spacing|gap|padding|margin|space/i.test(n)) return "spacing";
-  if (/shadow|blur|drop/i.test(n)) return "shadow";
-  return "other";
-}
-
-function isColorValue(value: string): boolean {
-  const normalized = value.trim().toLowerCase();
-  if (
-    /^(#[0-9a-fA-F]{3,8}|rgba?\(|hsla?\(|oklch\(|color\()/i.test(normalized)
-  ) {
-    return true;
-  }
-  return [
-    "red",
-    "blue",
-    "green",
-    "yellow",
-    "orange",
-    "purple",
-    "pink",
-    "cyan",
-    "magenta",
-    "teal",
-    "navy",
-    "maroon",
-    "coral",
-    "salmon",
-    "gold",
-    "silver",
-    "gray",
-    "grey",
-    "indigo",
-    "violet",
-    "lime",
-    "olive",
-    "aqua",
-    "fuchsia",
-    "crimson",
-    "turquoise",
-    "ivory",
-    "beige",
-    "lavender",
-    "tan",
-    "khaki",
-    "plum",
-    "orchid",
-    "sienna",
-  ].includes(normalized);
-}
-
 function toKebab(value: string): string {
   return (
     value
@@ -193,13 +134,6 @@ function toKebab(value: string): string {
   );
 }
 
-function friendlyName(cssVar: string): string {
-  return cssVar
-    .replace(/^--/, "")
-    .replace(/[-_]/g, " ")
-    .replace(/\b\w/g, (c) => c.toUpperCase());
-}
-
 function normalizeValue(value: string): string {
   return value
     .trim()