@assure-one/design-system 1.38.0 → 1.40.0

package/codemods/lib/registry.mjs

@@ -3,6 +3,7 @@
  * codemods listed here can be run by id; the sequence is the plan's.
  */
 export const CODEMODS = [
+  { id: "CM-01", module: "../transforms/cm-01-entry-imports.mjs" },
   { id: "CM-05", module: "../transforms/cm-05-button-icon-slots.mjs" },
   { id: "CM-13", module: "../transforms/cm-13-tooltip-delay.mjs" },
   { id: "CM-07", module: "../transforms/cm-07-input-size.mjs" },
@@ -21,6 +22,33 @@ export const CODEMODS = [
   { id: "CM-20", module: "../transforms/cm-20-select-sentinels.mjs" },
 ];
 
+/**
+ * `upgrade --to <version>`: the codemods a 1.x project runs before it installs
+ * that release, by the registry contracts the release removes or flips (plan
+ * §21.2). Applied in program order; transforming ones already in the ledger
+ * are skipped, report-only ones run every time.
+ *
+ * 1.40 (Wave 9, D11) — CM-01 root suite/legacy/accidental exports leave the
+ * root (C-ROOT-SUITE, C-ROOT-ACCIDENTAL) · CM-04 `variant="accent"` removed
+ * (C-BTN-ACCENT) · CM-19 Progress auto-colour off by default (C-PROGRESS) ·
+ * CM-12 Button `type="button"` default (C-BTN-TYPE) · CM-15 the 1.40 DOM
+ * freezes are lifted (C-DOM-*, C-TOAST-ARIALABEL) · CM-16 `styles.css`
+ * deprecated (C-CSS-STYLES). CM-02 is not in it: D5 keeps today's size scale.
+ */
+export const UPGRADE_TARGETS = {
+  "1.40": ["CM-01", "CM-04", "CM-19", "CM-12", "CM-15", "CM-16"],
+};
+
+/** Older names of a target: the 1.40 bundle was `--to 2` while Wave 9 was planned as 2.0. */
+const UPGRADE_ALIASES = { 2: "1.40" };
+
+/** The bundle for `--to 1.40`, `1.40.0`, `v1.40` (or the alias `--to 2`, `2.0`, `v2`…), in program order, or `null`. */
+export function upgradeBundle(to) {
+  const [major, minor] = String(to).trim().replace(/^v/i, "").split(".");
+  const ids = UPGRADE_TARGETS[UPGRADE_ALIASES[major] ?? `${major}.${Number(minor)}`];
+  return ids ? CODEMODS.filter((c) => ids.includes(c.id)).map((c) => c.id) : null;
+}
+
 export const findCodemod = (id) =>
   CODEMODS.find((c) => c.id.toLowerCase() === String(id).toLowerCase()) ?? null;
 

package/codemods/lib/runner.mjs

@@ -170,14 +170,19 @@ const countBy = (items, key) => {
   return Object.fromEntries([...map].sort(([a], [b]) => (a < b ? -1 : 1)));
 };
 
-/** Codemods a project has not applied yet, in program order. */
-export async function pendingCodemods(root) {
+/**
+ * Codemods a project has not applied yet, in program order. With `only` (an
+ * `upgrade --to` bundle) the list is limited to those ids and keeps their
+ * report-only codemods, which never enter the ledger.
+ */
+export async function pendingCodemods(root, { only = null } = {}) {
   const { CODEMODS } = await import("./registry.mjs");
   const ids = appliedIds(readLedger(root));
   const out = [];
   for (const { id } of CODEMODS) {
+    if (only && !only.includes(id)) continue;
     const mod = await loadCodemod(id);
     out.push({ ...mod.meta, applied: ids.has(id) });
   }
-  return out.filter((m) => m.class !== "X" && !m.applied);
+  return out.filter((m) => (m.class === "X" ? Boolean(only) : !m.applied));
 }

package/codemods/run.mjs

@@ -7,9 +7,12 @@
  *   node node_modules/@assure-one/design-system/codemods/run.mjs list
  *   node node_modules/@assure-one/design-system/codemods/run.mjs CM-15 src --dry
  *   node node_modules/@assure-one/design-system/codemods/run.mjs upgrade --dry
+ *   node node_modules/@assure-one/design-system/codemods/run.mjs upgrade --to 1.40 --dry
  *
  * Options
  *   --dry                 report only; write neither files nor the ledger
+ *   --to <version>        upgrade: only the codemods that release needs (`--to 1.40`;
+ *                         `--to 2` is an alias)
  *   --root <dir>          project root (default: nearest package.json above cwd)
  *   --report <prefix>     write <prefix>.json and <prefix>.md
  *   --json <file>         write the JSON report
@@ -27,11 +30,12 @@ import { dirname, resolve } from "node:path";
 import { findProjectRoot } from "./lib/files.mjs";
 import { installedDsVersion } from "./lib/environment.mjs";
 import { renderMarkdown, renderSummary } from "./lib/report.mjs";
-import { CODEMODS, loadAll } from "./lib/registry.mjs";
+import { readLedger } from "./lib/ledger.mjs";
+import { CODEMODS, UPGRADE_TARGETS, loadAll, upgradeBundle } from "./lib/registry.mjs";
 import { Refused, pendingCodemods, runCodemod } from "./lib/runner.mjs";
 
 const FLAGS = new Set(["--dry", "--print", "--quiet", "--fail-on-findings", "--help", "-h"]);
-const VALUES = new Set(["--root", "--report", "--json", "--md"]);
+const VALUES = new Set(["--root", "--report", "--json", "--md", "--to"]);
 
 function parseArgs(argv) {
   const options = {};
@@ -55,7 +59,7 @@ class UsageError extends Error {}
 const usage = () => `Usage:
   run.mjs list
   run.mjs <CM-ID> [paths…] [--dry] [--root dir] [--report prefix] [--print] [--fail-on-findings]
-  run.mjs upgrade [paths…] [--dry]
+  run.mjs upgrade [paths…] [--to <version>] [--dry]
 
 Codemods: ${CODEMODS.map((c) => c.id).join(", ")} (design system ${installedDsVersion()})
 `;
@@ -112,7 +116,21 @@ async function main(argv) {
   }
 
   if (command === "upgrade") {
-    const pending = await pendingCodemods(root);
+    const only = options.to ? upgradeBundle(options.to) : null;
+    if (options.to && !only) {
+      throw new UsageError(
+        `--to ${options.to}: no upgrade bundle (known: ${Object.keys(UPGRADE_TARGETS).join(", ")}; 2 is an alias of 1.40)`,
+      );
+    }
+    const pending = await pendingCodemods(root, { only });
+    if (only) {
+      const recorded = new Set(readLedger(root).applied.map((e) => e.id));
+      const skipped = only.filter((id) => recorded.has(id));
+      say(
+        `Upgrade to ${options.to}: ${pending.map((m) => m.id).join(", ")}` +
+          (skipped.length ? `; already in the ledger: ${skipped.join(", ")}` : ""),
+      );
+    }
     if (!pending.length) {
       say(`Nothing to apply in ${root}; the ledger is up to date.`);
       return 0;
@@ -125,8 +143,12 @@ async function main(argv) {
         dry: Boolean(options.dry),
       });
       say(renderSummary(report));
+      for (const warning of report.warnings) say(`! ${warning}`);
       if (options.print) process.stdout.write(renderMarkdown(report));
-      for (const path of writeReport(report, options)) say(`Report: ${path}`);
+      const prefix = options.report && pending.length > 1 ? `${options.report}-${meta.id}` : null;
+      for (const path of writeReport(report, prefix ? { report: prefix } : options))
+        say(`Report: ${path}`);
+      if (report.ledger.recorded) say(`Recorded ${meta.id} in ${root}/${report.ledger.file}`);
       if (options["fail-on-findings"] && report.summary.registered) code = 1;
     }
     return code;

package/codemods/transforms/cm-01-entry-imports.mjs

@@ -0,0 +1,202 @@
+/**
+ * CM-01 — root imports → `/suite` and `/legacy` (class R; plan §29 seq 1,
+ * registry `C-ROOT-SUITE`, lands with W8-02).
+ *
+ * W8-02 gave the shared Assure patterns their own entry and put the frozen and
+ * product-owned modules behind `/legacy`. Both are re-export barrels over the
+ * very same module instances the root exports, so moving an import is a pure
+ * path change: no duplicated context, no behaviour difference, nothing to test
+ * afterwards. The root keeps the names through 1.x and drops them in 2.0.
+ *
+ * ## What it rewrites
+ *
+ * ```tsx
+ * import { Button, AgreementViewer, TimeLogger } from "@assure-one/design-system";
+ * ```
+ *
+ * becomes
+ *
+ * ```tsx
+ * import { Button } from "@assure-one/design-system";
+ * import { AgreementViewer } from "@assure-one/design-system/suite";
+ * import { TimeLogger } from "@assure-one/design-system/legacy";
+ * ```
+ *
+ * A declaration whose names all move keeps its shape and only its module
+ * specifier changes. `import type` and per-specifier `type` prefixes, aliases
+ * (`X as Y`), quote style and a default import are preserved; the default
+ * import always stays on the root.
+ *
+ * Which entry owns which name comes from `codemods/lib/entry-map.mjs`, which
+ * `pnpm entry-map` generates from `architecture/entry-map.json` — so the
+ * installed copy of the codemod always knows the map of its own version.
+ *
+ * ## What it reports
+ *
+ * | rule               | action  | severity | why                                                                                     |
+ * | ------------------ | ------- | -------- | --------------------------------------------------------------------------------------- |
+ * | `moved-to-suite`   | applied | low      | shared Assure patterns now import from `/suite`                                          |
+ * | `moved-to-legacy`  | applied | low      | frozen modules with no known consumer now import from `/legacy`                          |
+ * | `product-owned`    | applied | medium   | the import moved to `/legacy`, but the module is leaving for a product repository        |
+ * | `namespace-import` | review  | high     | `import * as DS` cannot be split; the named members have to be imported one by one first |
+ *
+ * Imports already on `/suite` or `/legacy` are not touched (idempotency), and
+ * neither is a name the root still owns. Test files are skipped.
+ */
+import { ENTRY_BY_SYMBOL, ENTRY_SPECIFIER, PRODUCT_TARGET } from "../lib/entry-map.mjs";
+import { applyEdits } from "../lib/jsx-edit.mjs";
+import { analyseForms } from "../lib/forms.mjs";
+
+export const meta = {
+  id: "CM-01",
+  title: "Root imports of suite, legacy and product-owned names → /suite and /legacy",
+  class: "R",
+  oneShot: false,
+  requires: { codemods: [], dsVersion: null },
+  parses: ["code"],
+  includeTests: false,
+  usesTypeScript: true,
+  usesPostcss: false,
+  registryIds: ["C-ROOT-SUITE"],
+};
+
+export const RULES = {
+  "moved-to-suite": { action: "applied", severity: "low" },
+  "moved-to-legacy": { action: "applied", severity: "low" },
+  "product-owned": { action: "applied", severity: "medium" },
+  "namespace-import": { action: "review", severity: "high" },
+};
+
+const ROOT = "@assure-one/design-system";
+
+/** The entry that owns an imported name, or `null` when the root keeps it. */
+export const entryOf = (name) => ENTRY_BY_SYMBOL[name] ?? null;
+
+const ruleFor = (name, entry) =>
+  PRODUCT_TARGET[name] ? "product-owned" : entry === "suite" ? "moved-to-suite" : "moved-to-legacy";
+
+/** One `import …` statement built from the specifiers of the original one. */
+function declaration({ typeOnly, defaultName, specifiers, quote, semi }, specifier) {
+  const clause = [defaultName, specifiers.length ? `{ ${specifiers.join(", ")} }` : null].filter(
+    Boolean,
+  );
+  return `import ${typeOnly ? "type " : ""}${clause.join(", ")} from ${quote}${specifier}${quote}${semi}`;
+}
+
+export function transform(file, { ts }) {
+  const facts = analyseForms(ts, file.source, file.rel);
+  const sf = facts.sf;
+  const findings = [];
+  const edits = [];
+
+  for (const stmt of sf.statements) {
+    if (!ts.isImportDeclaration(stmt) || !ts.isStringLiteral(stmt.moduleSpecifier)) continue;
+    if (stmt.moduleSpecifier.text !== ROOT) continue;
+    const clause = stmt.importClause;
+    if (!clause) continue;
+
+    const line = sf.getLineAndCharacterOfPosition(stmt.getStart(sf)).line + 1;
+    const base = { line, registryId: "C-ROOT-SUITE", component: null, gate: null };
+
+    // `import * as DS` — the members are reached through the namespace, so the
+    // import cannot be split by name. Only worth reporting when the file
+    // actually reads a name that moved.
+    if (clause.namedBindings && ts.isNamespaceImport(clause.namedBindings)) {
+      const ns = clause.namedBindings.name.text;
+      const used = new Set();
+      const visit = (node) => {
+        if (
+          ts.isPropertyAccessExpression(node) &&
+          ts.isIdentifier(node.expression) &&
+          node.expression.text === ns &&
+          entryOf(node.name.text)
+        ) {
+          used.add(node.name.text);
+        }
+        if (ts.isQualifiedName(node) && ts.isIdentifier(node.left) && node.left.text === ns) {
+          if (entryOf(node.right.text)) used.add(node.right.text);
+        }
+        ts.forEachChild(node, visit);
+      };
+      ts.forEachChild(sf, visit);
+      if (used.size) {
+        findings.push({
+          ...base,
+          rule: "namespace-import",
+          ...RULES["namespace-import"],
+          match: `import * as ${ns}`,
+          detail: { namespace: ns, symbols: [...used].sort() },
+        });
+      }
+      continue;
+    }
+
+    const named = clause.namedBindings;
+    if (!named || !ts.isNamedImports(named)) continue;
+
+    const buckets = { root: [], suite: [], legacy: [] };
+    const movedNames = { suite: [], legacy: [] };
+    for (const element of named.elements) {
+      const imported = (element.propertyName ?? element.name).text;
+      const entry = entryOf(imported);
+      const bucket = entry ?? "root";
+      buckets[bucket].push(element.getText(sf));
+      if (entry) movedNames[entry].push(imported);
+    }
+    if (!movedNames.suite.length && !movedNames.legacy.length) continue;
+
+    const text = stmt.getText(sf);
+    const shape = {
+      typeOnly: clause.isTypeOnly,
+      defaultName: clause.name ? clause.name.text : null,
+      quote: stmt.moduleSpecifier.getText(sf)[0],
+      semi: text.endsWith(";") ? ";" : "",
+    };
+    const rows = [];
+    if (buckets.root.length || shape.defaultName) {
+      rows.push(declaration({ ...shape, specifiers: buckets.root }, ROOT));
+    }
+    for (const entry of ["suite", "legacy"]) {
+      if (!buckets[entry].length) continue;
+      rows.push(
+        declaration(
+          { ...shape, defaultName: null, specifiers: buckets[entry] },
+          ENTRY_SPECIFIER[entry],
+        ),
+      );
+    }
+    edits.push({ pos: stmt.getStart(sf), end: stmt.getEnd(), text: rows.join("\n") });
+
+    for (const entry of ["suite", "legacy"]) {
+      const byRule = new Map();
+      for (const name of movedNames[entry]) {
+        const rule = ruleFor(name, entry);
+        if (!byRule.has(rule)) byRule.set(rule, []);
+        byRule.get(rule).push(name);
+      }
+      for (const [rule, names] of byRule) {
+        findings.push({
+          ...base,
+          rule,
+          ...RULES[rule],
+          match: `{ ${names.sort().join(", ")} }`,
+          detail: {
+            from: ROOT,
+            to: ENTRY_SPECIFIER[entry],
+            symbols: names,
+            ...(rule === "product-owned"
+              ? { owners: [...new Set(names.map((n) => PRODUCT_TARGET[n]))].sort() }
+              : {}),
+          },
+        });
+      }
+    }
+  }
+
+  return {
+    output: edits.length ? applyEdits(file.source, edits) : file.source,
+    findings,
+    notTransformed: [],
+    parseErrors: facts.parseErrors,
+  };
+}

package/codemods/transforms/cm-15-dom-selectors.mjs

@@ -17,8 +17,9 @@
  *
  * Findings without a registry id are reported as `unregistered`: they are
  * DOM coupling the registry does not track yet. Radix `data-state`-style
- * attributes, ARIA roles and cmdk attributes are permanent contracts
- * (P-DATA-STATE, P-ROLES, C-CMDK-ATTR) and are not reported.
+ * attributes, ARIA roles, cmdk attributes and the `dl/dt/dd` of
+ * MetadataGrid/DataItem are permanent contracts (P-DATA-STATE, P-ROLES,
+ * C-CMDK-ATTR, P-NATIVE-TABLE) and are not reported.
  *
  * Never modifies files.
  */
@@ -185,16 +186,19 @@ const TAG_RULES = [
   { id: "C-DOM-12", components: /^ProgressBar$/, test: has(/role/) },
   { id: "C-DOM-13", components: /^(?:DataTableHeader|DataTableHead)$/, test: has(/button/) },
   { id: "C-DOM-15", components: /^DocumentRequestCard/, test: any },
-  {
-    id: "C-DOM-16",
-    components: /^(?:MetadataGrid|DataItem)$/,
-    test: has(/(?:^|[_>\s])(?:dt|dd|span)\b/),
-  },
+  { id: "C-DOM-16", components: /^(?:MetadataGrid|DataItem)$/, test: has(/(?:^|[_>\s])span\b/) },
 ];
 
 const ruleFor = (component, reach) =>
   TAG_RULES.find((r) => r.components.test(component) && r.test(reach)) ?? null;
 
+// `dl/dt/dd` inside MetadataGrid/DataItem are permanent (P-NATIVE-TABLE;
+// only the `span` part of C-DOM-16 is frozen), so selectors on them are not
+// reported.
+const isPermanent = (component, reach) =>
+  /^(?:MetadataGrid|DataItem)$/.test(component) &&
+  /(?:^|[_>\s])(?:dl|dt|dd)\b/.test(reach.selector);
+
 /**
  * Whether an unmapped selector on a *wrapper* element is worth reporting: it
  * must name an element, `*`, or a `data-`/`role` attribute. A wrapper selector
@@ -310,6 +314,7 @@ function codeFindings(file, ts) {
         const reach = domReach(token);
         if (!reach) continue;
         const rule = ruleFor(usage.component, reach) ?? ruleFor(usage.base, reach);
+        if (!rule && isPermanent(usage.base, reach)) continue;
         add({
           line,
           registryId: rule?.id ?? null,
@@ -332,6 +337,7 @@ function codeFindings(file, ts) {
           .map((c) => ({ c, rule: ruleFor(c, reach) }))
           .filter((x) => x.rule && x.rule.test !== any);
         const hit = rules[0];
+        if (!hit && el.dsDescendants.some((c) => isPermanent(c, reach))) continue;
         if (!hit && !namesStructure(reach.selector)) continue;
         add({
           line,
@@ -381,12 +387,13 @@ function codeFindings(file, ts) {
       });
     }
 
-    // 4. MetadataGrid / DataItem wrappers style dt/dd from anywhere in the file.
+    // 4. MetadataGrid / DataItem wrappers style their `span` from anywhere in
+    //    the file (`dt/dd` are permanent, see `isPermanent`).
     if (used.has("MetadataGrid") || used.has("DataItem")) {
       const reported = new Set(findings.map((f) => `${f.line}${f.match}`));
       for (const { token, line } of facts.fileTokens) {
         const reach = domReach(token);
-        if (!reach || !/(?:^|[_>\s])(?:dt|dd)\b/.test(reach.selector)) continue;
+        if (!reach || !/(?:^|[_>\s])span\b/.test(reach.selector)) continue;
         if (reported.has(`${line}${token}`)) continue;
         add({
           line,

package/dist/brand-scope-BOHId6BY.d.ts

@@ -0,0 +1,58 @@
+import * as React$1 from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * Brand scope — ambient product theming.
+ *
+ * The `brand` color family (bg-brand, hover:bg-brand-hover, bg-brand-bg,
+ * border-brand-line, text-fg-on-brand, plus the accent/focus/primary
+ * interaction tokens) follows the nearest `[data-brand]` scope and defaults to
+ * Pro. Authors type the STATE only; the product comes from the scope. Set it
+ * once high in the tree — ideally on the same root as the `.dark` class
+ * (`<html>`/`<body>`) — so Radix-portalled surfaces inherit it through the DOM.
+ *
+ *   <html data-brand="tax">           // whole shell renders teal
+ *   <div {...brandScope("audit")}>    // a subtree renders blue
+ *
+ * For the rarer case of multiple scopes on one page WITH portalled content
+ * (a Dialog/Popover that escapes its scoped subtree to document.body), wrap the
+ * region in <BrandScope> / <BrandScopeProvider> and have the portalled
+ * `*Content` re-stamp `data-brand={useBrandScope()}` on its own element.
+ */
+type BrandProduct = "pro" | "audit" | "books" | "tax";
+/**
+ * `data-brand` attribute object to spread on any element (mirrors
+ * `serviceToneStyle`). This is the primary API for opting a subtree into a
+ * product without naming the product in a utility class.
+ */
+declare function brandScope(product: BrandProduct): {
+    "data-brand": BrandProduct;
+};
+/** Every product, in suite order — for switchers and story matrices. */
+declare const BRAND_PRODUCTS: BrandProduct[];
+/** Human label for a product, for switchers and headings. */
+declare const brandLabel: Record<BrandProduct, string>;
+/**
+ * Provides the active product to descendants so portalled surfaces can
+ * re-stamp `data-brand` on themselves via {@link useBrandScope}. Purely a
+ * structural carrier — the visual theming still comes from the `[data-brand]`
+ * attribute in the DOM, not from this context.
+ */
+declare function BrandScopeProvider({ product, children, }: {
+    product: BrandProduct;
+    children: React.ReactNode;
+}): react_jsx_runtime.JSX.Element;
+/** Read the ambient product from the nearest provider (defaults to Pro). */
+declare function useBrandScope(): BrandProduct;
+interface BrandScopeProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** The product this subtree renders as. */
+    product: BrandProduct;
+}
+/**
+ * Convenience wrapper that stamps `data-brand` on a `<div>` AND provides the
+ * product via context, so a portalled descendant can re-stamp itself. Use
+ * `brandScope()` directly when you want the attribute on your own element.
+ */
+declare const BrandScope: React$1.ForwardRefExoticComponent<BrandScopeProps & React$1.RefAttributes<HTMLDivElement>>;
+
+export { BRAND_PRODUCTS as B, type BrandProduct as a, brandLabel as b, BrandScope as c, type BrandScopeProps as d, BrandScopeProvider as e, brandScope as f, useBrandScope as u };

package/dist/brand-theme-ZYM867Jz.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The seed a host supplies per tenant.
+ *
+ * @experimental Gated by decision D7.
+ */
+interface BrandThemeSeed {
+    /**
+     * The brand fill, as `#rgb` or `#rrggbb`. Drives the `action.brand` family,
+     * the focus ring and the brand gradient.
+     */
+    brand: string;
+    /**
+     * An optional second hue for the `action.accent` family, as `#rgb` or
+     * `#rrggbb`. `undefined` or `null` means "the same as `brand`", which is what
+     * the built-in `[data-ds-brand]` scopes do.
+     */
+    accent?: string | null | undefined;
+}
+/** Every custom property `createBrandTheme()` sets, in output order. */
+declare const BRAND_THEME_PROPERTIES: readonly ["--ds-color-action-brand-bg", "--ds-color-action-brand-bg-hover", "--ds-color-action-brand-bg-active", "--ds-color-action-brand-bg-disabled", "--ds-color-action-brand-subtle-bg", "--ds-color-action-brand-subtle-bg-hover", "--ds-color-action-brand-subtle-bg-active", "--ds-color-action-brand-border", "--ds-color-action-brand-ring", "--ds-color-action-brand-fg", "--ds-color-action-accent-bg", "--ds-color-action-accent-bg-strong", "--ds-color-action-accent-bg-hover", "--ds-color-action-accent-bg-active", "--ds-color-action-accent-subtle-bg", "--ds-color-action-accent-ring", "--ds-color-action-accent-fg", "--ds-color-border-focus", "--ds-focus-ring-color", "--ds-focus-ring-border", "--ds-gradient-brand", "--ds-compat-color-brand-soft", "--ds-compat-color-brand-soft-foreground"];
+/** One of the custom properties `createBrandTheme()` sets. */
+type BrandThemeProperty = (typeof BRAND_THEME_PROPERTIES)[number];
+/**
+ * The style object `createBrandTheme()` returns: every property of
+ * {@link BRAND_THEME_PROPERTIES} with a CSS value.
+ *
+ * React types `style` as `CSSProperties`, which has no index signature for
+ * custom properties, so spread it or cast it at the call site:
+ * `style={{ ...createBrandTheme(seed) }}`.
+ *
+ * @experimental Gated by decision D7.
+ */
+type BrandTheme = {
+    readonly [P in BrandThemeProperty]: string;
+};
+/**
+ * Turn a tenant's colours into the design system's brand and accent tokens.
+ *
+ * ```tsx
+ * const theme = createBrandTheme({ brand: firm.primaryColor, accent: firm.accentColor });
+ * return <div style={{ ...theme }}>{children}</div>;
+ * ```
+ *
+ * Apply it to the element that scopes the brand — `<body>` for a whole-tenant
+ * theme, a wrapper for a preview. The properties are the same ones a built-in
+ * `[data-ds-brand]` scope declares, so anything reading them (every design
+ * system component, and any application CSS reading `--ds-*`) follows.
+ *
+ * @param seed - `brand`, and optionally `accent` (decision D7).
+ * @returns A frozen object of custom property names to CSS values.
+ * @throws TypeError when the seed is not an object, carries an unknown key, or
+ * a colour is missing or not `#rgb`/`#rrggbb`.
+ *
+ * @experimental Gated by decision D7. The property set may grow, and the seed
+ * shape may change, until D7 is resolved.
+ */
+declare function createBrandTheme(seed: BrandThemeSeed): BrandTheme;
+
+export { BRAND_THEME_PROPERTIES as B, type BrandTheme as a, type BrandThemeProperty as b, type BrandThemeSeed as c, createBrandTheme as d };