@agent-native/core 0.138.0 → 0.140.0

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

@@ -1,4 +1,10 @@
 import { defineAction } from "@agent-native/core";
+import {
+  brandKitRoleTokens,
+  classifyBrandKitToken,
+  friendlyTokenName,
+  resolveBrandKitTokens,
+} from "@agent-native/core/brand-kit/tokens";
 import { extractCssVars } from "@agent-native/core/server/design-token-utils";
 import { resolveAccess } from "@agent-native/core/sharing";
 import { eq } from "drizzle-orm";
@@ -12,52 +18,12 @@ import {
   resolveTweaksToCssVars,
 } from "../shared/resolve-tweaks.js";
 
-// ---------------------------------------------------------------------------
-// Token type classification
-// ---------------------------------------------------------------------------
-
-function classifyVar(
-  name: string,
-  value: string,
-): "color" | "typography" | "spacing" | "radius" | "shadow" | "other" {
-  const n = name.toLowerCase();
-  if (
-    /color|bg|background|text|border|accent|primary|secondary|surface|muted|foreground|fill|stroke/i.test(
-      n,
-    ) ||
-    /^(#[0-9a-fA-F]{3,8}|rgba?\(|hsla?\(|oklch\(|color\()/.test(value.trim())
-  ) {
-    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";
-}
-
-/** Derive a friendly display name from a CSS var name like `--primary-color`. */
-function friendlyName(cssVar: string): string {
-  return cssVar
-    .replace(/^--/, "")
-    .replace(/[-_]/g, " ")
-    .replace(/\b\w/g, (c) => c.toUpperCase());
-}
-
 // ---------------------------------------------------------------------------
 // Token entry shape
 // ---------------------------------------------------------------------------
 
 export interface DesignToken {
-  /** Human-readable display name, e.g. "Primary Color". */
+  /** The linked Brand Kit's own token name when it has one, else derived. */
   name: string;
   /** CSS custom property, e.g. "--primary-color". */
   cssVar: string;
@@ -67,6 +33,13 @@ export interface DesignToken {
   type: "color" | "typography" | "spacing" | "radius" | "shadow" | "other";
   /** Opaque source chip label, e.g. "globals.css" or "Brand Kit". */
   source: string;
+  /** Collection path from the Brand Kit, e.g. "Colors/Interactive". */
+  group?: string;
+  /**
+   * Which layer supplied the token. Filter on this, not on `source` — that is a
+   * free-text chip label (a filename, "Brand Kit", "Tweaks", …).
+   */
+  origin: "design" | "brand-kit";
   /**
    * True when the value comes from the design's own tweak selections (i.e.
    * the user has already customised this token in the editor).
@@ -74,6 +47,16 @@ export interface DesignToken {
   isTweakOverride?: boolean;
 }
 
+/** Layer of a token's provenance, before it is flattened into a DesignToken. */
+interface RawToken {
+  value: string;
+  source: string;
+  origin: DesignToken["origin"];
+  /** Present only when a Brand Kit supplied the token's own name. */
+  name?: string;
+  group?: string;
+}
+
 // ---------------------------------------------------------------------------
 // Action
 // ---------------------------------------------------------------------------
@@ -81,9 +64,11 @@ export interface DesignToken {
 export default defineAction({
   description:
     "Index the design tokens for a design as a friendly { name, cssVar, " +
-    "value, type, source } list. Parses CSS custom properties from the " +
+    "value, type, source, group } list. Parses CSS custom properties from the " +
     "design's HTML :root block, the linked Brand Kit / design system, and " +
-    "the user's applied tweak selections.  Returns tokens grouped by type " +
+    "the user's applied tweak selections. Tokens the linked Brand Kit stores " +
+    "by name keep that name and collection group; the rest get a name derived " +
+    "from their CSS variable. Returns tokens grouped by type " +
     "(color, typography, spacing, radius, shadow, other).",
   schema: z.object({
     designId: z.string().describe("Design project ID"),
@@ -109,19 +94,21 @@ export default defineAction({
       .from(schema.designFiles)
       .where(eq(schema.designFiles.designId, designId));
 
-    /** cssVar -> { value, source } */
-    const rawTokens: Map<string, { value: string; source: string }> = new Map();
+    /** cssVar -> latest layer that set it */
+    const rawTokens: Map<string, RawToken> = new Map();
     // Persisted Brand Kit JSON can outlive its schema. Keep one malformed token
     // from taking down the whole read action while preserving valid siblings.
     const setRawToken = (
       cssVar: string,
       value: unknown,
       source: unknown,
+      provenance: Omit<RawToken, "value" | "source">,
     ): void => {
       if (typeof value !== "string") return;
       rawTokens.set(cssVar, {
         value,
         source: typeof source === "string" && source ? source : "Unknown",
+        ...provenance,
       });
     };
 
@@ -138,7 +125,7 @@ export default defineAction({
       };
       extractCssVars(state, file.content);
       for (const [k, v] of Object.entries(state.cssCustomProperties)) {
-        setRawToken(k, v, file.filename);
+        setRawToken(k, v, file.filename, { origin: "design" });
       }
     }
 
@@ -165,38 +152,24 @@ export default defineAction({
       if (dsRow?.data) {
         try {
           const dsData = JSON.parse(dsRow.data) as Partial<DesignSystemData>;
-          // Flatten the Brand Kit's known token fields into CSS vars
-          const brandColors = dsData.colors ?? {};
-          const colorRoleMap: Record<string, string> = {
-            primary: "--color-primary",
-            secondary: "--color-secondary",
-            accent: "--color-accent",
-            background: "--color-background",
-            surface: "--color-surface",
-            text: "--color-text",
-            textMuted: "--color-text-muted",
-          };
-          for (const [role, cssVar] of Object.entries(colorRoleMap)) {
-            const v = (brandColors as Record<string, string>)[role];
-            if (v) setRawToken(cssVar, v, "Brand Kit");
-          }
-          // Border radius
-          if (dsData.borders?.radius) {
-            setRawToken("--radius", dsData.borders.radius, "Brand Kit");
+          // The role -> var mapping lives in core so a rewriter cannot drift.
+          for (const token of brandKitRoleTokens(dsData)) {
+            setRawToken(token.cssVar, token.value, "Brand Kit", {
+              origin: "brand-kit",
+            });
           }
-          // Spacing
-          if (dsData.spacing?.elementGap) {
+          // Layered after the roles: the kit's own names win over the
+          // seven-slot summary.
+          for (const token of resolveBrandKitTokens(dsData, "Brand Kit")) {
             setRawToken(
-              "--spacing-element-gap",
-              dsData.spacing.elementGap,
-              "Brand Kit",
-            );
-          }
-          if (dsData.spacing?.pagePadding) {
-            setRawToken(
-              "--spacing-page-padding",
-              dsData.spacing.pagePadding,
-              "Brand Kit",
+              token.cssVar,
+              token.value,
+              token.source ?? "Brand Kit",
+              {
+                origin: "brand-kit",
+                name: token.name,
+                ...(token.group ? { group: token.group } : {}),
+              },
             );
           }
         } catch {
@@ -250,20 +223,28 @@ export default defineAction({
       ...Object.keys(tweakSelections).filter(isDirectCssVarSelectionKey),
     ]);
     for (const [cssVar, value] of Object.entries(resolvedOverrides)) {
-      setRawToken(cssVar, value, tokenImportSources[cssVar] ?? "Tweaks");
+      // Retuning a value must not rename the token it came from.
+      const inherited = rawTokens.get(cssVar);
+      setRawToken(cssVar, value, tokenImportSources[cssVar] ?? "Tweaks", {
+        origin: inherited?.origin ?? "design",
+        ...(inherited?.name ? { name: inherited.name } : {}),
+        ...(inherited?.group ? { group: inherited.group } : {}),
+      });
     }
 
     // ------------------------------------------------------------------
     // 4. Build friendly token list
     // ------------------------------------------------------------------
     const tokens: DesignToken[] = [];
-    for (const [cssVar, { value, source }] of rawTokens) {
+    for (const [cssVar, { value, source, name, group, origin }] of rawTokens) {
       tokens.push({
-        name: friendlyName(cssVar),
+        name: name ?? friendlyTokenName(cssVar),
         cssVar,
         value,
-        type: classifyVar(cssVar, value),
+        type: classifyBrandKitToken(cssVar, value),
         source,
+        origin,
+        ...(group ? { group } : {}),
         isTweakOverride: tweakCssVars.has(cssVar),
       });
     }

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

@@ -4,6 +4,7 @@ import { eq } from "drizzle-orm";
 import { z } from "zod";
 
 import { getDb, schema } from "../server/db/index.js";
+import { assertStorableDesignSystemTokens } from "../server/lib/design-system-tokens.js";
 
 export default defineAction({
   description:
@@ -23,7 +24,11 @@ export default defineAction({
       .trim()
       .min(1, "data cannot be empty")
       .optional()
-      .describe("Updated JSON string of DesignSystemData"),
+      .describe(
+        "Updated JSON string of DesignSystemData. Replaces the whole object, so " +
+          "include the existing `tokens` array (the source system's named tokens) " +
+          "alongside any edit, or those names are dropped.",
+      ),
     assets: z
       .string()
       .optional()
@@ -36,16 +41,8 @@ export default defineAction({
       ),
   }),
   run: async ({ id, title, description, data, assets, customInstructions }) => {
-    // Validate that data/assets are valid JSON when provided
     if (data !== undefined) {
-      try {
-        const parsed = JSON.parse(data);
-        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-          throw new Error();
-        }
-      } catch {
-        throw new Error("data must be a valid JSON object string");
-      }
+      assertStorableDesignSystemTokens(data);
     }
     if (assets !== undefined) {
       try {

package/corpus/templates/design/app/components/design/EditPanel.tsx

@@ -155,6 +155,12 @@ import {
   vscodeDeepLink,
 } from "./edit-panel/code-inspect-helpers";
 import { ComponentSection } from "./edit-panel/component-section";
+import {
+  parseTokenReference,
+  resolveTokenNameForColor,
+  toDesignSystemColorSwatches,
+  type DesignSystemColorSwatch,
+} from "./edit-panel/design-system-swatches";
 import {
   type DocumentColorSourceFile,
   extractDocumentColorPalette,
@@ -383,6 +389,9 @@ export { deriveLockedAspectSize };
 export { mergeRotationValue, normalizeRotationDegrees };
 export { mixedElementFromSelection };
 export { authoredStyleValue, resolveInteractionStateValue };
+
+/** A `var()` reference names itself, so no kit lookup is needed to label it. */
+const EMPTY_SWATCHES: DesignSystemColorSwatch[] = [];
 export { isTextElement };
 export { ComponentSection };
 export { extractDocumentColorPalette, type DocumentColorSourceFile };
@@ -1467,12 +1476,15 @@ function PageProperties({
   styles,
   onStyleChange,
   onStylesChange,
+  designSystemColors,
   canvasBackground,
   onCanvasBackgroundChange,
 }: {
   styles: Record<string, string>;
   onStyleChange: StyleChangeHandler;
   onStylesChange?: StylesChangeHandler;
+  /** Kit tokens offered by name in the canvas/page background pickers. */
+  designSystemColors?: DesignSystemColorSwatch[];
   canvasBackground?: string | null;
   onCanvasBackgroundChange?: (value: string, meta?: StyleChangeMeta) => void;
 }) {
@@ -1503,6 +1515,7 @@ function PageProperties({
         <PanelSection title={t("editPanel.sections.canvas")}>
           <ColorInput
             label={t("editPanel.labels.background")}
+            designSystemColors={designSystemColors}
             value={canvasBackground ?? ""}
             // meta carries phase: "preview" while dragging vs "commit" on
             // release. Dropping it persists every tick and the picker jumps.
@@ -1513,6 +1526,7 @@ function PageProperties({
       <PanelSection title={t("editPanel.sections.page")}>
         <ColorInput
           label={t("editPanel.labels.background")}
+          designSystemColors={designSystemColors}
           value={styles.backgroundColor || ""}
           onChange={(v, meta) => onStyleChange("backgroundColor", v, meta)}
           backgroundImage={styles.backgroundImage}
@@ -1724,8 +1738,15 @@ function SelectionColorsProperties({
                       className="size-4 shrink-0 rounded-[3px] border border-border/60"
                       style={swatchStyle(color.value)}
                     />
-                    <span className="min-w-0 flex-1 truncate text-left uppercase tabular-nums">
-                      {selectionDisplayHex(color.value)}
+                    <span
+                      className={cn(
+                        "min-w-0 flex-1 truncate text-left tabular-nums",
+                        // Hex is conventionally upper-case; a token name is not.
+                        !parseTokenReference(color.value) && "uppercase",
+                      )}
+                    >
+                      {resolveTokenNameForColor(color.value, EMPTY_SWATCHES) ??
+                        selectionDisplayHex(color.value)}
                     </span>
                     <span className="shrink-0 tabular-nums text-muted-foreground">
                       {opacity}%
@@ -1920,6 +1941,24 @@ export const EditPanel = memo(function EditPanel({
     // eslint-disable-next-line react-hooks/exhaustive-deps -- keyed on filesContentKey (cheap length+id fingerprint) instead of `files` itself so an unstable-but-equal array identity from the parent doesn't force a full re-scan every render.
     [filesContentKey],
   );
+  // The linked Brand Kit's named colour tokens, for the fill picker. Shares
+  // react-query's cache with the Tokens panel, so opening both costs one fetch.
+  const { data: indexedTokens } = useActionQuery<{
+    tokens?: {
+      name: string;
+      cssVar: string;
+      value: string;
+      type: string;
+      group?: string;
+      source?: string;
+    }[];
+  }>("index-design-tokens", designId ? { designId } : undefined, {
+    enabled: Boolean(designId),
+  });
+  const designSystemColors = useMemo(
+    () => toDesignSystemColorSwatches(indexedTokens?.tokens),
+    [indexedTokens],
+  );
   const selectionAlreadyComponent =
     selectedCount === 1 &&
     (selectedElementAlreadyComponent ||
@@ -2326,6 +2365,7 @@ export const EditPanel = memo(function EditPanel({
               {!inspectorElement && !selectedScreenGeometry && (
                 <PageProperties
                   styles={pageStyles}
+                  designSystemColors={designSystemColors}
                   onStyleChange={onStyleChange}
                   onStylesChange={onStylesChange}
                   canvasBackground={canvasBackground}
@@ -2382,11 +2422,13 @@ export const EditPanel = memo(function EditPanel({
                     onStyleChange={onStyleChange}
                     onStylesChange={onStylesChange}
                     documentColorPalette={documentColorPalette}
+                    designSystemColors={designSystemColors}
                     glslShaderContext={glslShaderContext}
                     motionKeyframeContext={motionKeyframeFieldContext}
                     breakpointOverrideContext={breakpointOverrideFieldContext}
                   />
                   <StrokeProperties
+                    designSystemColors={designSystemColors}
                     element={stateResolvedInspectorElement ?? inspectorElement}
                     onStyleChange={onStyleChange}
                     onStylesChange={onStylesChange}
@@ -2397,6 +2439,7 @@ export const EditPanel = memo(function EditPanel({
                     element={stateResolvedInspectorElement ?? inspectorElement}
                     onStyleChange={onStyleChange}
                     onStylesChange={onStylesChange}
+                    designSystemColors={designSystemColors}
                     glslShaderContext={glslShaderContext}
                     motionKeyframeContext={motionKeyframeFieldContext}
                   />

package/corpus/templates/design/app/components/design/bridge/editor-chrome.bridge.ts

@@ -29,6 +29,8 @@
  */
 import { createCanvasGestureController } from "@agent-native/toolkit/canvas-interactions";
 
+import { collectAuthoredColorStyles } from "../../../../shared/authored-color-styles";
+
 declare var __READ_ONLY__: boolean;
 declare var __TEXT_EDITING_ENABLED__: boolean;
 declare var __EDITOR_CHROME_SCALE_X__: string;
@@ -1852,6 +1854,9 @@ declare var __SELECTED_LAYER_DRAG_PRIORITY__: boolean;
   // and `right` — only the inline style tells you which side was actually
   // set). Empty-string values are omitted so callers can treat key-absence as
   // "not authored".
+  // color/backgroundColor/borderColor/outlineColor are reported because
+  // getComputedStyle resolves `var()`: without the authored declaration the
+  // inspector cannot tell a design system token from the colour it resolves to.
   var INLINE_STYLE_PROPERTIES = [
     "position",
     "left",
@@ -1862,6 +1867,12 @@ declare var __SELECTED_LAYER_DRAG_PRIORITY__: boolean;
     "height",
     "transform",
     "whiteSpace",
+    "color",
+    "backgroundColor",
+    "borderColor",
+    "outlineColor",
+    "boxShadow",
+    "textShadow",
   ];
 
   function collectInlineStyles(el: Element): Record<string, string> {
@@ -2121,6 +2132,7 @@ declare var __SELECTED_LAYER_DRAG_PRIORITY__: boolean;
         whiteSpace: cs.whiteSpace,
       },
       inlineStyles: collectInlineStyles(el),
+      authoredColorStyles: collectAuthoredColorStyles(el),
       primitiveKind: el.getAttribute("data-an-primitive") || undefined,
       portableStyleSnapshot: collectPortableStyleSnapshot(el),
       boundingRect: {

package/corpus/templates/design/app/components/design/edit-panel/design-system-swatches.ts

@@ -0,0 +1,215 @@
+import { parseCssColorExtended, rgbaToHex } from "@shared/color-utils";
+
+/** One colour token from the design's linked Brand Kit, as the kit names it. */
+export interface DesignSystemColorSwatch {
+  name: string;
+  cssVar: string;
+  value: string;
+  group?: string;
+  source?: string;
+}
+
+interface IndexedToken {
+  name: string;
+  cssVar: string;
+  value: string;
+  type: string;
+  group?: string;
+  source?: string;
+  origin?: string;
+}
+
+/** Extended: the classifier stores `oklch()`/`color()` tokens as colours. */
+function normalizeHex(value: string): string | null {
+  const parsed = parseCssColorExtended(value.trim());
+  return parsed ? rgbaToHex(parsed).toUpperCase() : null;
+}
+
+/** Guards a cyclic alias chain (`--a: var(--b); --b: var(--a)`). */
+const MAX_ALIAS_DEPTH = 8;
+
+/**
+ * A token's value as a paintable literal, following aliases through the kit's
+ * own vocabulary. A kit legitimately defines one token as another, and dropping
+ * those loses a selectable token; painting them raw gives an empty swatch.
+ */
+function paintableTokenValue(
+  value: string,
+  byCssVar: ReadonlyMap<string, string>,
+  depth = 0,
+): string | null {
+  if (normalizeHex(value)) return value;
+  if (depth >= MAX_ALIAS_DEPTH) return null;
+  const reference = parseTokenReference(value);
+  if (!reference) return null;
+
+  const aliased = byCssVar.get(reference.cssVar);
+  if (aliased !== undefined) {
+    const resolved = paintableTokenValue(aliased, byCssVar, depth + 1);
+    if (resolved) return resolved;
+  }
+  return reference.fallback
+    ? paintableTokenValue(reference.fallback, byCssVar, depth + 1)
+    : null;
+}
+
+/**
+ * The linked kit's swatchable colour tokens from an `index-design-tokens`
+ * result, which mixes the design's own `:root` colours into the same list.
+ * Values that resolve to no colour at all are dropped, since they would paint
+ * an empty swatch.
+ */
+export function toDesignSystemColorSwatches(
+  tokens: readonly IndexedToken[] | undefined,
+  limit = 48,
+): DesignSystemColorSwatch[] {
+  if (!tokens) return [];
+  // Every token, not just kit ones: a kit alias may point at a design `:root`
+  // variable, and that still resolves to a real colour.
+  const byCssVar = new Map(tokens.map((token) => [token.cssVar, token.value]));
+  const seen = new Set<string>();
+  const out: DesignSystemColorSwatch[] = [];
+
+  for (const token of tokens) {
+    if (token.type !== "color") continue;
+    if (token.origin !== "brand-kit") continue;
+    const value = paintableTokenValue(token.value, byCssVar);
+    if (!value) continue;
+    if (seen.has(token.cssVar)) continue;
+    seen.add(token.cssVar);
+    out.push({
+      name: token.name,
+      cssVar: token.cssVar,
+      value,
+      ...(token.group ? { group: token.group } : {}),
+      ...(token.source ? { source: token.source } : {}),
+    });
+    if (out.length >= limit) break;
+  }
+
+  return out;
+}
+
+/**
+ * What to call a token in the picker: its CSS variable, minus the leading `--`.
+ *
+ * The indexed `name` is title-cased for tokens the kit never named ("Color
+ * Primary"), which reads as a different vocabulary than the kit's own
+ * `cds-background-brand` sitting next to it. The variable is what the design
+ * references, so it is the name worth showing.
+ */
+export function swatchLabel(swatch: DesignSystemColorSwatch): string {
+  return swatch.cssVar.replace(/^--/, "");
+}
+
+const TOKEN_REFERENCE_HEAD = /^var\(\s*(--[-_a-zA-Z0-9]+)\s*(,?)/;
+
+export interface TokenReference {
+  cssVar: string;
+  /** Literal after the comma. Absent for a bare `var(--x)`. */
+  fallback: string | null;
+}
+
+/**
+ * A fallback is itself a CSS value, so it can nest parentheses. Scanning to the
+ * balanced close rather than matching `[^()]+` is what keeps a function-valued
+ * token from reading as "not a token" and being dropped by the commit guard.
+ */
+export function parseTokenReference(value: string): TokenReference | null {
+  const trimmed = value.trim();
+  const head = TOKEN_REFERENCE_HEAD.exec(trimmed);
+  if (!head) return null;
+
+  let depth = 1;
+  let index = head[0].length;
+  for (; index < trimmed.length && depth > 0; index += 1) {
+    const char = trimmed[index];
+    if (char === "(") depth += 1;
+    else if (char === ")") depth -= 1;
+  }
+  // Anything after the matching `)` means this is not a lone reference.
+  if (depth !== 0 || index !== trimmed.length) return null;
+
+  const fallback = trimmed.slice(head[0].length, index - 1).trim();
+  if (fallback && !head[2]) return null;
+  return { cssVar: head[1], fallback: fallback || null };
+}
+
+/**
+ * The declaration to persist for a picked token.
+ *
+ * The fallback is not optional padding: outside the editor — an export, a
+ * published page, a design whose kit link was removed — nothing defines the
+ * custom property, and a bare `var(--x)` renders transparent.
+ */
+export function tokenReferenceValue(swatch: DesignSystemColorSwatch): string {
+  return `var(${swatch.cssVar}, ${swatch.value})`;
+}
+
+const HIDDEN_TOKEN_MIX =
+  /^color-mix\(\s*in\s+srgb\s*,\s*(var\(.+\))\s+0%\s*,\s*transparent\s*\)$/i;
+
+/**
+ * What to write when hiding a colour. Zeroing alpha needs literal channels,
+ * which a `var()` reference has none of — so a token is hidden as a 0% mix that
+ * keeps the reference inside the persisted CSS. React state would not survive
+ * the deselect/reselect that unmounts the inspector.
+ */
+export function hiddenColorWrite(
+  color: string,
+  zeroAlpha: (literal: string) => string | null,
+): string {
+  const reference = parseTokenReference(color);
+  if (reference) return `color-mix(in srgb, ${color} 0%, transparent)`;
+  return zeroAlpha(color) ?? "transparent";
+}
+
+/** The reference a hidden token colour carries, or null if it is not one. */
+export function hiddenTokenReference(value: string): string | null {
+  return HIDDEN_TOKEN_MIX.exec(value.trim())?.[1] ?? null;
+}
+
+/**
+ * Name the token a value came from, or null when that cannot be known. A
+ * `var()` reference names itself; a bare colour is matched by value, and a tie
+ * returns null — Carbon points four tokens at one blue.
+ */
+export function resolveTokenNameForColor(
+  value: string,
+  swatches: readonly DesignSystemColorSwatch[],
+): string | null {
+  const reference = parseTokenReference(value);
+  if (reference) return reference.cssVar.replace(/^--/, "");
+
+  const target = normalizeHex(value);
+  if (!target) return null;
+
+  let match: string | null = null;
+  for (const swatch of swatches) {
+    if (normalizeHex(swatch.value) !== target) continue;
+    if (match) return null;
+    match = swatchLabel(swatch);
+  }
+  return match;
+}
+
+/** Group swatches under their kit collection path, preserving token order. */
+export function groupColorSwatches(
+  swatches: readonly DesignSystemColorSwatch[],
+): { label: string | null; swatches: DesignSystemColorSwatch[] }[] {
+  const groups = new Map<
+    string,
+    { label: string | null; swatches: DesignSystemColorSwatch[] }
+  >();
+  for (const swatch of swatches) {
+    const label = swatch.group?.trim() || null;
+    const key = label ?? "";
+    const existing = groups.get(key);
+    if (existing) {
+      existing.swatches.push(swatch);
+      continue;
+    }
+    groups.set(key, { label, swatches: [swatch] });
+  }
+  return [...groups.values()];
+}

package/corpus/templates/design/app/components/design/edit-panel/document-colors.ts

@@ -1,6 +1,7 @@
 import { parseCssColor, rgbaToHex } from "@shared/color-utils";
 
 import type { ElementInfo } from "../types";
+import { authoredColorValue } from "./interaction-state-helpers";
 
 export interface DocumentColorSourceFile {
   id: string;
@@ -63,13 +64,16 @@ export interface SelectionColorValue {
 export function selectionColorValues(
   element: ElementInfo,
 ): SelectionColorValue[] {
-  const styles = element.computedStyles;
+  // Authored, not computed: getComputedStyle has already flattened `var()`.
   const rawValues: SelectionColorValue[] = [
-    { property: "color", value: styles.color },
-    { property: "backgroundColor", value: styles.backgroundColor },
-    { property: "borderColor", value: styles.borderColor },
-    { property: "outlineColor", value: styles.outlineColor },
-  ];
+    "color",
+    "backgroundColor",
+    "borderColor",
+    "outlineColor",
+  ].map((property) => ({
+    property,
+    value: authoredColorValue(element, property) as string,
+  }));
   const seen = new Set<string>();
   return rawValues
     .map((color) => ({ ...color, value: color.value?.trim() }))