@caelo-cms/shared 0.10.24 → 0.10.26

package/src/seo.test.ts

@@ -16,17 +16,17 @@ describe("resolveCanonicalUrl", () => {
     expect(
       resolveCanonicalUrl({
         siteBaseUrl: "https://example.com",
-        pageSlug: "anything",
+        pagePath: "/anything",
         override: "https://canonical.example.com/x",
       }),
     ).toBe("https://canonical.example.com/x");
   });
 
-  it("renders home as the root path", () => {
+  it("renders the composed root path as the bare base URL", () => {
     expect(
       resolveCanonicalUrl({
         siteBaseUrl: "https://example.com",
-        pageSlug: "home",
+        pagePath: "/",
         override: null,
       }),
     ).toBe("https://example.com/");
@@ -36,7 +36,7 @@ describe("resolveCanonicalUrl", () => {
     expect(
       resolveCanonicalUrl({
         siteBaseUrl: "https://example.com/",
-        pageSlug: "about",
+        pagePath: "/about",
         override: null,
       }),
     ).toBe("https://example.com/about/");
@@ -47,18 +47,18 @@ describe("resolveCanonicalUrl", () => {
       expect(
         resolveCanonicalUrl({
           siteBaseUrl: "https://example.com",
-          pageSlug: "about",
+          pagePath: "/about",
           override: null,
           pageUrlStyle: "no-extension",
         }),
       ).toBe("https://example.com/about");
     });
 
-    it("keeps the root URL for the home page", () => {
+    it("keeps the root URL for the composed root path", () => {
       expect(
         resolveCanonicalUrl({
           siteBaseUrl: "https://example.com",
-          pageSlug: "home",
+          pagePath: "/",
           override: null,
           pageUrlStyle: "no-extension",
         }),
@@ -69,7 +69,7 @@ describe("resolveCanonicalUrl", () => {
       expect(
         resolveCanonicalUrl({
           siteBaseUrl: "https://example.com",
-          pageSlug: "about",
+          pagePath: "/about",
           override: null,
         }),
       ).toBe("https://example.com/about/");

package/src/seo.ts

@@ -8,7 +8,7 @@
  */
 
 import { z } from "zod";
-import { isHomeSlug } from "./i18n.js";
+import { trimSlashes } from "./url.js";
 
 export const CHANGEFREQ_VALUES = [
   "always",
@@ -108,39 +108,31 @@ export interface SiteSeoSettings {
 
 /**
  * Resolve the canonical URL for a page. If `pages_seo.canonical_url`
- * is set it wins; otherwise build `<siteBaseUrl>/<slug>` (home pages
- * canonicalize to the bare base URL). URL shaping beyond base + slug
- * becomes a plugin contribution on the URL composition point (#390).
+ * is set it wins; otherwise `<siteBaseUrl><pagePath>` — where
+ * `pagePath` is the COMPOSED public path from `pages.current_path`
+ * (#390: the URL composition point materializes prefixes, slug
+ * formats, and the home designation into that one column; canonical
+ * simply follows it).
  */
 export function resolveCanonicalUrl(args: {
   siteBaseUrl: string;
-  pageSlug: string;
+  /** The page's composed path (`pages.current_path`): leading slash,
+   *  "/" for the site root. */
+  pagePath: string;
   override: string | null;
   /**
    * v0.2.85 — page emission style. 'directory' (default) → URLs end
-   * in `/<slug>/`; 'no-extension' → URLs end in `/<slug>` (no
-   * trailing slash) to match what the bucket actually serves when
-   * pages are emitted as bare slugs.
+   * in `/…/`; 'no-extension' → no trailing slash, matching what the
+   * bucket serves when pages are emitted as bare files.
    */
   pageUrlStyle?: "directory" | "no-extension";
-  /**
-   * 0184 — explicit homepage designation. When true this page IS the
-   * site root and canonicalizes to `<base>/` regardless of its slug.
-   * Uses the same predicate (`isHomeSlug`) as the magic-slug fallback
-   * so canonical agrees with the emitted output path.
-   */
-  isHomePage?: boolean;
 }): string {
   if (args.override && args.override.length > 0) return args.override;
-  const base = args.siteBaseUrl.replace(/\/$/, "");
-  const isHome = args.isHomePage === true || isHomeSlug(args.pageSlug);
-  const cleanSlug = isHome ? "" : args.pageSlug;
+  const base = args.siteBaseUrl.endsWith("/") ? args.siteBaseUrl.slice(0, -1) : args.siteBaseUrl;
+  const trimmed = trimSlashes(args.pagePath);
+  if (trimmed.length === 0) return `${base}/`;
   const style = args.pageUrlStyle ?? "directory";
-  // Tail = the slug portion of the canonical URL, with the trailing
-  // shape dictated by the page-emission style. Home pages always
-  // resolve to the base URL (no tail) regardless of style.
-  const tail = cleanSlug ? (style === "no-extension" ? cleanSlug : `${cleanSlug}/`) : "";
-  return tail ? `${base}/${tail}` : `${base}/`;
+  return style === "no-extension" ? `${base}/${trimmed}` : `${base}/${trimmed}/`;
 }
 
 export interface SeoMetaInput {

package/src/template-engine-data-lists.test.ts

@@ -0,0 +1,90 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Plugin data lists in the template engine: `{{#name}}…{{/name}}` over
+ * data a plugin supplies per page, with the module owning the markup.
+ *
+ * The load-bearing case is the third one. Plugin activation is a hard
+ * state, so a module written while a plugin ran keeps its
+ * `{{#language_links}}` after the plugin is switched off. Rendering
+ * that as an empty string would be a silent fallback (CLAUDE.md §2) and
+ * would read to the operator as "the switcher vanished for no reason".
+ * It has to stay visible AND say which plugin to turn back on.
+ */
+
+import { describe, expect, it } from "bun:test";
+import { renderTemplate } from "./template-engine.js";
+
+const SWITCHER =
+  '<nav>{{#language_links}}<a href="{{href}}">{{label}}</a>{{/language_links}}</nav>';
+
+describe("template engine — plugin data lists", () => {
+  it("iterates a plugin list with the module's own markup", () => {
+    const r = renderTemplate({
+      html: SWITCHER,
+      fields: [],
+      dataLists: {
+        language_links: [
+          { href: "/", label: "English", locale: "en" },
+          { href: "/de", label: "Deutsch", locale: "de" },
+        ],
+      },
+    });
+    expect(r.html).toBe('<nav><a href="/">English</a><a href="/de">Deutsch</a></nav>');
+    expect(r.missingSlots).toEqual([]);
+  });
+
+  it("renders nothing for an empty list — that is data, not breakage", () => {
+    // A page with no published translations legitimately has no links.
+    const r = renderTemplate({
+      html: SWITCHER,
+      fields: [],
+      dataLists: { language_links: [] },
+    });
+    expect(r.html).toBe("<nav></nav>");
+    expect(r.missingSlots).toEqual([]);
+  });
+
+  it("stays loud and names the plugin when its plugin is switched off", () => {
+    const r = renderTemplate({
+      html: SWITCHER,
+      fields: [],
+      dormantDataLists: { language_links: "international-site" },
+    });
+    // Loud-raw: the section survives in the output rather than
+    // silently collapsing.
+    expect(r.html).toContain("{{#language_links}}");
+    expect(r.missingSlots).toContain(
+      "plugin-list-unavailable:language_links plugin=international-site",
+    );
+  });
+
+  it("keeps an unknown name a plain undeclared field", () => {
+    // No plugin claims it — this really is a typo, and must not be
+    // reported as a deactivated plugin.
+    const r = renderTemplate({ html: "<p>{{#nope}}x{{/nope}}</p>", fields: [] });
+    expect(r.missingSlots).toContain("field-not-declared:nope");
+  });
+
+  it("lets a module's own field win over a plugin list of the same name", () => {
+    // Module fields are resolved first by construction, so a plugin can
+    // never shadow content the author declared.
+    const r = renderTemplate({
+      html: "<ul>{{#items}}<li>{{label}}</li>{{/items}}</ul>",
+      fields: [{ name: "items", kind: "link-list" }],
+      contentValues: { items: [{ label: "authored", href: "/a" }] },
+      dataLists: { items: [{ label: "from-plugin" }] },
+    });
+    expect(r.html).toContain("authored");
+    expect(r.html).not.toContain("from-plugin");
+  });
+
+  it("leaves a key the items do not carry raw", () => {
+    const r = renderTemplate({
+      html: "{{#l}}<a href={{href}}>{{missing_key}}</a>{{/l}}",
+      fields: [],
+      dataLists: { l: [{ href: "/x" }] },
+    });
+    expect(r.html).toContain("{{missing_key}}");
+  });
+});

package/src/template-engine.ts

@@ -93,6 +93,24 @@ export interface RenderTemplateInput {
    * Preview-render path: built from RenderResolver walks.
    */
   readonly partials?: Readonly<Record<string, string>>;
+  /**
+   * Plugin-provided lists for THIS page, keyed by the claimed name a
+   * module iterates as `{{#name}}`. The plugin supplies the data, the
+   * module owns the markup — so a language switcher looks like the site
+   * it lives on instead of carrying a plugin's fixed HTML.
+   *
+   * Resolved per page, which is what lets a module carrying one sit in
+   * a LAYOUT and cover every page. The `staticRender` placeholder can't:
+   * it needs the page's own id baked into its HTML.
+   */
+  readonly dataLists?: Readonly<Record<string, ReadonlyArray<Readonly<Record<string, string>>>>>;
+  /**
+   * Names an INSTALLED plugin declares that are not live right now,
+   * mapped to the owning plugin. A module written while the plugin ran
+   * still says `{{#language_links}}`; this is what lets the render
+   * report "that plugin is switched off" instead of "unknown field".
+   */
+  readonly dormantDataLists?: Readonly<Record<string, string>>;
   /**
    * v0.11.1 (issue #76) — active theme's resolved asset URLs. When
    * present, `{{theme_logo_url}}` / `{{theme_logo_dark_url}}` /
@@ -243,7 +261,18 @@ export function renderTemplate(input: RenderTemplateInput): RenderTemplateOutput
 
   // 1. {{#name}}…{{/name}} sections.
   let html = sourceHtml.replace(SECTION_RE, (match, name: string, inner: string) =>
-    renderSection(match, name, inner, fieldByName, cvs, partials, missing, mkSentinel),
+    renderSection(
+      match,
+      name,
+      inner,
+      fieldByName,
+      cvs,
+      partials,
+      missing,
+      mkSentinel,
+      input.dataLists ?? {},
+      input.dormantDataLists ?? {},
+    ),
   );
 
   // 2. {{>name}} single partials.
@@ -333,9 +362,24 @@ function renderSection(
   partials: Readonly<Record<string, string>>,
   missing: string[],
   mkSentinel: (original: string) => string,
+  dataLists: Readonly<Record<string, ReadonlyArray<Readonly<Record<string, string>>>>>,
+  dormantLists: Readonly<Record<string, string>>,
 ): string {
   const field = fields.get(name);
   if (!field) {
+    // No declared field — a plugin may still offer this name. Module
+    // fields are looked up FIRST by construction, so a plugin can never
+    // shadow something the module's author declared.
+    const items = dataLists[name];
+    if (items) return renderDataList(inner, items);
+    // Declared by an installed plugin that is NOT running. Naming the
+    // plugin turns "unknown field" (hunt for a typo) into "switch that
+    // plugin back on", which is the actual fix.
+    const owner = dormantLists[name];
+    if (owner) {
+      missing.push(`plugin-list-unavailable:${name} plugin=${owner}`);
+      return mkSentinel(match);
+    }
     missing.push(`field-not-declared:${name}`);
     return mkSentinel(match);
   }
@@ -425,6 +469,33 @@ function renderTextList(
   return parts.join("");
 }
 
+/**
+ * Iterate a plugin-provided list, substituting each item's keys inside
+ * the section body.
+ *
+ * Unlike `link-list` no shape is imposed: the keys are whatever the
+ * plugin declared in `itemFields`, so a language switcher uses
+ * href/label/locale and a comment list something else entirely. A
+ * `{{key}}` the item does not carry is left raw, matching the engine's
+ * loud-raw rule everywhere else — a typo'd key stays visible instead of
+ * quietly rendering as nothing.
+ */
+function renderDataList(
+  inner: string,
+  items: ReadonlyArray<Readonly<Record<string, string>>>,
+): string {
+  const parts: string[] = [];
+  for (const item of items) {
+    let rendered = inner;
+    for (const [key, value] of Object.entries(item)) {
+      const escaped = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      rendered = rendered.replace(new RegExp(`\\{\\{\\s*${escaped}\\s*\\}\\}`, "g"), () => value);
+    }
+    parts.push(rendered);
+  }
+  return parts.join("");
+}
+
 function renderLinkList(
   name: string,
   inner: string,

package/src/theme-importers/loose.ts

@@ -46,7 +46,7 @@ export function importLoose(body: string): ThemeDocument {
   // ambiguity, per the v0.11.0 normalizer's failure surface).
   const normalized = normalizeTokens(obj);
   // Apply to an empty document so the result is a complete tokens tree.
-  const written = applyDtcgWrites({}, normalized.set, normalized.types);
+  const written = applyDtcgWrites({}, normalized.set, normalized.types, normalized.descriptions);
   return validateThemeTokens(written);
 }
 

package/src/theme-normalize.ts

@@ -48,6 +48,15 @@ export interface NormalizeResult {
     CanonicalPath,
     "color" | "dimension" | "typography" | "shadow" | "duration" | "cubicBezier" | "gradient"
   >;
+  /**
+   * issue #430 — the token's ROLE, per canonical path: what this token
+   * is for and, crucially, where it must NOT be used ("CTAs and links
+   * only — never large background fills"). Lifted off the `$description`
+   * of a DTCG envelope the caller passed in `set`, so a value and its
+   * role land in ONE write instead of a value call plus a prose-metadata
+   * call. The ops layer stores it back on the leaf as `$description`.
+   */
+  readonly descriptions: Record<CanonicalPath, string>;
   /** Echo-back list for the AI tool's result content. */
   readonly canonicalPaths: readonly CanonicalPath[];
 }
@@ -218,6 +227,7 @@ const DEFAULT_TIER = "sm"; // shadowSm / radiusMd default
 export function normalizeTokens(input: Record<string, unknown>): NormalizeResult {
   const set: Record<CanonicalPath, unknown> = {};
   const types: Record<CanonicalPath, NormalizeResult["types"][string]> = {};
+  const descriptions: Record<CanonicalPath, string> = {};
   const paths: CanonicalPath[] = [];
 
   for (const [rawName, rawValueIn] of Object.entries(input)) {
@@ -235,13 +245,35 @@ export function normalizeTokens(input: Record<string, unknown>): NormalizeResult
         // Not JSON after all — keep the literal string.
       }
     }
-    if (
-      rawValue !== null &&
-      typeof rawValue === "object" &&
-      !Array.isArray(rawValue) &&
-      "$value" in (rawValue as Record<string, unknown>)
-    ) {
-      rawValue = (rawValue as Record<string, unknown>).$value;
+    // issue #430 — the envelope may also carry `$description` (the token's
+    // role). Lift it BEFORE unwrapping, then re-attach it at the canonical
+    // path so "what this colour is for" survives the same call that sets
+    // the colour. Without this the role is silently dropped on the way in.
+    let envelopeDescription: string | undefined;
+    const isEnvelope =
+      rawValue !== null && typeof rawValue === "object" && !Array.isArray(rawValue);
+    if (isEnvelope && "$value" in (rawValue as Record<string, unknown>)) {
+      const envelope = rawValue as Record<string, unknown>;
+      if (typeof envelope.$description === "string" && envelope.$description.trim().length > 0) {
+        envelopeDescription = envelope.$description;
+      }
+      rawValue = envelope.$value;
+    } else if (isEnvelope && "$description" in (rawValue as Record<string, unknown>)) {
+      // ROLE-ONLY patch: `{$description}` with no `$value`. The anchor-page
+      // design review annotates tokens whose VALUES are already settled, so
+      // it must be able to write the role without restating (and risking
+      // drift on) every value. Resolve the path without the value — which
+      // only canonical / CSS-var names allow, since loose names infer their
+      // category FROM the value — and record no `set` entry, so
+      // applyDtcgWrites patches the leaf's metadata and leaves `$value` alone.
+      const role = (rawValue as Record<string, unknown>).$description;
+      // A blank role is nothing to write — same tolerance the value-carrying
+      // envelope gives it. The tool reports the resulting no-op.
+      if (typeof role !== "string" || role.trim().length === 0) continue;
+      const path = resolvePathWithoutValue(rawName);
+      descriptions[path] = role.trim();
+      if (!paths.includes(path)) paths.push(path);
+      continue;
     }
     const resolved = resolveOne(rawName, rawValue);
     // v0.11.0 fix (#45 review thread on theme-normalize.ts:149) —
@@ -273,10 +305,11 @@ export function normalizeTokens(input: Record<string, unknown>): NormalizeResult
     }
     set[resolved.path] = storedValue;
     types[resolved.path] = resolved.inferredType;
+    if (envelopeDescription !== undefined) descriptions[resolved.path] = envelopeDescription;
     paths.push(resolved.path);
   }
 
-  return { set, types, canonicalPaths: paths };
+  return { set, types, descriptions, canonicalPaths: paths };
 }
 
 interface ResolvedToken {
@@ -291,6 +324,35 @@ interface ResolvedToken {
   readonly compositeWrap?: string;
 }
 
+/**
+ * issue #430 — resolve a canonical path for a ROLE-ONLY patch, where no
+ * value is supplied to infer the category from.
+ *
+ * Only the two name forms that carry their own category work here:
+ * a canonical DTCG path (`color.primary`) and the CSS-var form
+ * (`--color-primary`) — which is what a caller annotating an existing
+ * theme naturally has, since it just read the document or the module CSS.
+ * A loose name (`primaryColor`) infers its category FROM the value, so
+ * without one it is genuinely unresolvable: say so rather than guess
+ * (CLAUDE.md §2).
+ */
+function resolvePathWithoutValue(rawName: string): CanonicalPath {
+  if (/^[a-z][a-z0-9_-]*(\.[a-z0-9_-]+)+$/i.test(rawName)) return rawName;
+  if (rawName.startsWith("--")) {
+    const stripped = rawName.slice(2);
+    const firstHyphen = stripped.indexOf("-");
+    if (firstHyphen > 0) {
+      const category = stripped.slice(0, firstHyphen);
+      const rest = stripped.slice(firstHyphen + 1);
+      // --font-heading / --text-heading are two emitted vars for ONE
+      // typography composite; a role belongs on the composite.
+      if (category === "font" || category === "text") return `typography.${rest}`;
+      return `${category}.${rest}`;
+    }
+  }
+  throw new UnknownTokenName(rawName, []);
+}
+
 function resolveOne(rawName: string, rawValue: unknown): ResolvedToken {
   // 1. Direct canonical DTCG paths: pass through unchanged. Typography
   //    sub-paths (`typography.X.fontFamily` / `.fontSize` / …) collapse

package/src/theme-render.ts

@@ -139,6 +139,41 @@ export function listThemeCssVarNames(tokens: ThemeDocument): readonly string[] {
   return [...names].sort();
 }
 
+/**
+ * issue #430 — map every emitted CSS variable name to the ROLE recorded
+ * on its token (`$description`): what the token is for and where it must
+ * not be used. Returns `{}` when no token carries a role.
+ *
+ * This is how a design decision reaches the point of use. The write-time
+ * design guard looks up the vars a module's CSS actually references and
+ * replays their roles back at the author, so "primary is for CTAs, never
+ * for large background fills" is enforced on page nine as firmly as on
+ * page one — without a separate design-system document to maintain.
+ *
+ * A composite (typography) emits several vars from one token; each
+ * inherits the same role, which is what a reader expects.
+ */
+export function listTokenRoles(tokens: ThemeDocument): Record<string, string> {
+  const flat = flattenTokens(tokens);
+  const resolveCache = new Map<string, unknown>();
+  const roles: Record<string, string> = {};
+  for (const { path, token } of flat) {
+    const description = (token as { $description?: unknown }).$description;
+    if (typeof description !== "string" || description.trim().length === 0) continue;
+    const category = path.split(".")[0] ?? "";
+    const value = resolveTokenValue(token, tokens, resolveCache, new Set([path]));
+    const lines: string[] = [];
+    emitTokenLines(category, path, value, lines, []);
+    for (const line of lines) {
+      const colon = line.indexOf(":");
+      if (colon <= 0) continue;
+      const name = line.slice(0, colon).trim();
+      if (name.startsWith("--")) roles[name] = description.trim();
+    }
+  }
+  return roles;
+}
+
 /**
  * Emit a Tailwind 4 `@theme inline { … }` block. The body re-uses the
  * same per-category emission as `renderThemeCss` so the variable names
@@ -387,6 +422,7 @@ function emitTypography(rest: string, value: unknown, out: string[]): void {
   const v = value as Record<string, unknown>;
   if (v.fontFamily !== undefined) out.push(`--font-${rest}:${asString(v.fontFamily)};`);
   if (v.fontSize !== undefined) out.push(`--text-${rest}:${asString(v.fontSize)};`);
+  if (v.fontStyle !== undefined) out.push(`--font-style-${rest}:${asString(v.fontStyle)};`);
   if (v.fontWeight !== undefined) out.push(`--font-weight-${rest}:${asString(v.fontWeight)};`);
   if (v.lineHeight !== undefined) out.push(`--leading-${rest}:${asString(v.lineHeight)};`);
   if (v.letterSpacing !== undefined) out.push(`--tracking-${rest}:${asString(v.letterSpacing)};`);

package/src/theme-token-roles.test.ts

@@ -0,0 +1,182 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * issue #430 — a token's ROLE is set in the same call as its value and
+ * must survive every later value-only edit.
+ *
+ * Before this, `applyDtcgWrites` rebuilt each leaf as `{$value, $type}`
+ * and silently dropped `$description`, so recording a role was pointless:
+ * the next `set_theme_tokens` erased it. These tests pin the write path
+ * (normalizer lifts the role off the DTCG envelope), the preserve path,
+ * and the lookup the design guard uses to replay roles at the point of
+ * use.
+ */
+
+import { describe, expect, it } from "bun:test";
+import { normalizeTokens } from "./theme-normalize.js";
+import { listTokenRoles } from "./theme-render.js";
+import { applyDtcgWrites, type ThemeDocument, validateThemeTokens } from "./themes.js";
+
+const ROLE = "CTAs and links only — never large background fills";
+
+function write(doc: ThemeDocument, set: Record<string, unknown>): ThemeDocument {
+  const n = normalizeTokens(set);
+  return applyDtcgWrites(doc, n.set, n.types, n.descriptions);
+}
+
+describe("token roles ride with the value (issue #430)", () => {
+  it("lifts $description off the envelope onto the canonical path", () => {
+    const n = normalizeTokens({
+      "color.primary": { $type: "color", $value: "#4f46e5", $description: ROLE },
+    });
+    expect(n.descriptions["color.primary"]).toBe(ROLE);
+    // The envelope is still unwrapped for the value itself.
+    expect(n.set["color.primary"]).toBe("#4f46e5");
+  });
+
+  it("stores the role on the leaf and keeps the document valid", () => {
+    const doc = write(
+      {},
+      {
+        "color.primary": { $type: "color", $value: "#4f46e5", $description: ROLE },
+      },
+    );
+    expect((doc.color as Record<string, { $description?: string }>).primary.$description).toBe(
+      ROLE,
+    );
+    expect(() => validateThemeTokens(doc)).not.toThrow();
+  });
+
+  it("PRESERVES the role across a later value-only edit", () => {
+    let doc = write(
+      {},
+      {
+        "color.primary": { $type: "color", $value: "#4f46e5", $description: ROLE },
+      },
+    );
+    doc = write(doc, { primaryColor: "#ff6600" });
+    const leaf = (doc.color as Record<string, { $value: unknown; $description?: string }>).primary;
+    expect(leaf.$value).toBe("#ff6600");
+    expect(leaf.$description).toBe(ROLE);
+  });
+
+  it("lets an explicit new role overwrite the old one", () => {
+    let doc = write(
+      {},
+      {
+        "color.primary": { $type: "color", $value: "#4f46e5", $description: ROLE },
+      },
+    );
+    doc = write(doc, {
+      "color.primary": { $type: "color", $value: "#4f46e5", $description: "Buttons only" },
+    });
+    expect((doc.color as Record<string, { $description?: string }>).primary.$description).toBe(
+      "Buttons only",
+    );
+  });
+
+  it("maps roles onto the CSS var names module CSS actually references", () => {
+    const doc = write(
+      {},
+      {
+        "color.primary": { $type: "color", $value: "#4f46e5", $description: ROLE },
+        "color.border": "#e5e5e5",
+      },
+    );
+    const roles = listTokenRoles(doc);
+    expect(roles["--color-primary"]).toBe(ROLE);
+    // A token with no recorded role contributes nothing — no invented text.
+    expect(roles["--color-border"]).toBeUndefined();
+  });
+
+  it("gives every var a typography composite emits the same role", () => {
+    const doc = write(
+      {},
+      {
+        "typography.heading": {
+          $type: "typography",
+          $value: { fontFamily: "Poppins, sans-serif", fontSize: "2rem" },
+          $description: "Section headings only",
+        },
+      },
+    );
+    const roles = listTokenRoles(doc);
+    expect(roles["--font-heading"]).toBe("Section headings only");
+    expect(roles["--text-heading"]).toBe("Section headings only");
+  });
+
+  it("ignores a blank role rather than storing an empty string", () => {
+    const n = normalizeTokens({
+      "color.primary": { $type: "color", $value: "#4f46e5", $description: "   " },
+    });
+    expect(n.descriptions["color.primary"]).toBeUndefined();
+  });
+});
+
+/**
+ * The anchor-page design review annotates tokens whose values are already
+ * settled. Restating each value just to attach a role is both a round-trip
+ * (read the document first) and a chance to drift one, so a `$value`-less
+ * envelope patches the metadata alone.
+ */
+describe("role-only patches (issue #430)", () => {
+  const DOC: ThemeDocument = {
+    color: { primary: { $type: "color", $value: "#4f46e5" } },
+    typography: {
+      heading: { $type: "typography", $value: { fontFamily: "Poppins, sans-serif" } },
+    },
+  };
+
+  it("sets the role and leaves $value and $type untouched", () => {
+    const doc = write(DOC, { "color.primary": { $description: ROLE } });
+    const leaf = (doc.color as Record<string, Record<string, unknown>>).primary;
+    expect(leaf.$value).toBe("#4f46e5");
+    expect(leaf.$type).toBe("color");
+    expect(leaf.$description).toBe(ROLE);
+  });
+
+  it("accepts the CSS-var form the AI reads off module CSS", () => {
+    const doc = write(DOC, { "--color-primary": { $description: ROLE } });
+    expect((doc.color as Record<string, Record<string, unknown>>).primary.$description).toBe(ROLE);
+  });
+
+  it("maps --font-<name> onto the typography composite", () => {
+    const doc = write(DOC, { "--font-heading": { $description: "Section headings only" } });
+    const leaf = (doc.typography as Record<string, Record<string, unknown>>).heading;
+    expect(leaf.$description).toBe("Section headings only");
+    expect(leaf.$value).toEqual({ fontFamily: "Poppins, sans-serif" });
+  });
+
+  it("annotates several tokens in ONE call", () => {
+    const doc = write(DOC, {
+      "color.primary": { $description: ROLE },
+      "typography.heading": { $description: "Section headings only" },
+    });
+    expect((doc.color as Record<string, Record<string, unknown>>).primary.$description).toBe(ROLE);
+    expect((doc.typography as Record<string, Record<string, unknown>>).heading.$description).toBe(
+      "Section headings only",
+    );
+  });
+
+  it("rejects a loose name — category is unresolvable without a value", () => {
+    expect(() => write(DOC, { primaryColor: { $description: ROLE } })).toThrow(/UnknownTokenName/);
+  });
+
+  it("rejects annotating a token that does not exist", () => {
+    expect(() => write(DOC, { "color.nonexistent": { $description: ROLE } })).toThrow(
+      /UnknownTokenName/,
+    );
+  });
+
+  it("a blank role-only patch writes nothing", () => {
+    const n = normalizeTokens({ "color.primary": { $description: "  " } });
+    expect(n.canonicalPaths).toHaveLength(0);
+    expect(n.descriptions).toEqual({});
+  });
+
+  it("still validates as a DTCG document afterwards", () => {
+    expect(() =>
+      validateThemeTokens(write(DOC, { "color.primary": { $description: ROLE } })),
+    ).not.toThrow();
+  });
+});