@assure-one/design-system 1.39.0 → 1.41.0

package/README.md

@@ -27,13 +27,23 @@ The single source of truth for visual design across all Assure products.
 pnpm add @assure-one/design-system
 ```
 
-Import the consumer stylesheet once in your root layout. Its bundled component
-utilities intentionally live below your app's Tailwind `utilities` layer, so
-local classes and responsive variants remain authoritative even when a bundler
-reorders CSS chunks:
+Load the design system's CSS from your app's global stylesheet, as the split
+entries, under one layer statement (Tailwind 4 in your build):
 
-```ts
-import "@assure-one/design-system/styles.css";
+```css
+/* src/app/globals.css — the layer statement is the first line of the file */
+@layer theme, base, ds, components, utilities;
+
+@import "tailwindcss";
+
+@import "@assure-one/design-system/css/tokens.css";
+@import "@assure-one/design-system/css/legacy-aliases.css"; /* optional */
+@import "@assure-one/design-system/css/tailwind.css";
+@import "@assure-one/design-system/css/shadcn.css"; /* optional */
+@import "@assure-one/design-system/css/base.css"; /* optional */
+@import "@assure-one/design-system/css/components.css";
+
+@import "./ds-preset.css"; /* your app's preset, optional */
 ```
 
 Then use components:
@@ -46,32 +56,42 @@ export default function Page() {
 }
 ```
 
-### The split CSS entries (experimental)
+### The split CSS entries
 
-`styles.css` stays the supported way to consume the design system, unchanged.
-Alongside it, the package now also publishes the individual stylesheets the new
-CSS mode is built from. They are **experimental**: nothing requires them yet,
-no component reads them, and importing them changes nothing on its own.
+The split entries are the documented default CSS integration since 1.40. Every
+design-system class is `ds:`-prefixed and compiled into `css/components.css`
+inside `@layer ds`, so your own utilities always win over component styles and
+your Tailwind build never has to scan our package.
 
-| Subpath                    | What it is                                                                                                                                                                                                                                                                                                                                                    |
-| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `./css/tokens.css`         | The `--ds-*` design tokens: `:root`, the colour scheme scope and the brand scopes. Usable without any component.                                                                                                                                                                                                                                              |
-| `./css/legacy-aliases.css` | Read-aliases from today's token names to the namespaced ones (`--color-surface: var(--ds-color-surface)`), for as long as your own CSS reads design-system token names.                                                                                                                                                                                       |
-| `./css/tailwind.css`       | A Tailwind `@theme` bridge, so `bg-surface/40`, `hover:text-fg-3` and `rounded-control` compile in _your_ build instead of silently producing nothing.                                                                                                                                                                                                        |
-| `./css/shadcn.css`         | The app-vocabulary bridge: `background`, `foreground`, `primary`, `muted`, `destructive`, the radius scale and the rest, each reading one `--app-*` input you can override.                                                                                                                                                                                   |
-| `./css/base.css`           | Optional document defaults: body background, ink, font and `color-scheme`. Ships no preflight, no element rules and no font import.                                                                                                                                                                                                                           |
-| `./css/components.css`     | The component utilities compiled with Tailwind's `ds` prefix (`ds:flex`, `ds:bg-surface`), inside `@layer ds` and bound to the `--ds-*` tokens. **Unused until the class-vocabulary flip (W1-11):** no component emits a prefixed class yet, so importing it styles nothing. Published so the file, its size and its hygiene can be reviewed before the flip. |
+| Subpath                    | What it is                                                                                                                                                                  |
+| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `./css/tokens.css`         | The `--ds-*` design tokens: `:root`, the colour scheme scope and the brand scopes. Usable without any component.                                                            |
+| `./css/legacy-aliases.css` | Read-aliases from today's token names to the namespaced ones (`--color-surface: var(--ds-color-surface)`), for as long as your own CSS reads design-system token names.     |
+| `./css/tailwind.css`       | A Tailwind `@theme` bridge, so `bg-surface/40`, `hover:text-fg-3` and `rounded-control` compile in _your_ build instead of silently producing nothing.                      |
+| `./css/shadcn.css`         | The app-vocabulary bridge: `background`, `foreground`, `primary`, `muted`, `destructive`, the radius scale and the rest, each reading one `--app-*` input you can override. |
+| `./css/base.css`           | Optional document defaults: body background, ink, font and `color-scheme`. Ships no preflight, no element rules and no font import.                                         |
+| `./css/components.css`     | The component utilities compiled with Tailwind's `ds` prefix (`ds:flex`, `ds:bg-surface`), inside `@layer ds` and bound to the `--ds-*` tokens.                             |
 
 Import order is `tokens.css` → `legacy-aliases.css` (optional) → `tailwind.css`
 → `shadcn.css` (optional) → `base.css` (optional) → `components.css`, after your own
 `@import "tailwindcss"` and under the layer statement
 `@layer theme, base, ds, components, utilities;`.
 [**`docs/integration/css.md`**](./docs/integration/css.md) has the full
-sequence, where the per-app preset goes, when the `@source` into our package may
-be removed, and the fixture run behind each of those claims. The reasoning lives
+sequence, where the per-app preset goes, why no `@source` into our package is
+needed, and the fixture run behind each of those claims. The reasoning lives
 in [ADR-004](./docs/adr/004-css-delivery-cascade.md) and
 [ADR-005](./docs/adr/005-app-vocabulary-bridge.md).
 
+### `styles.css` (deprecated)
+
+`@assure-one/design-system/styles.css` — the all-in-one sheet with its own
+preflight, a Google Fonts `@import` and the frozen unprefixed legacy utilities —
+is **deprecated since 1.40** (registry `C-CSS-STYLES`). It still ships, unchanged,
+and is removed in 3.0; the built file opens with a deprecation
+banner. Moving to the split entries is a deliberate visual change (document font
+size, fonts, preflight): follow [`docs/integration/css.md`](./docs/integration/css.md)
+§6 and [`docs/migration/1.40.md`](./docs/migration/1.40.md).
+
 ### Runtime brand theming (experimental)
 
 For a tenant colour known only at runtime, `@assure-one/design-system/tokens`
@@ -107,8 +127,9 @@ is required to get a readable lockup.
 ### The provider and the `/next` entry (experimental)
 
 Nothing requires a provider: every component renders English strings, formats
-with `en-US` and (for `LinkButton` / `Logo`) routes through `next/link` on its
-own. `DesignSystemProvider` is the one optional, thin, client-side provider
+with `en-US` and (for `LinkButton` / `Logo`) renders a plain `<a>` / `<img>`.
+On Next.js, render `NextDesignSystemProvider` to get `next/link` routing and
+`next/image`: the root imports no `next/*` since 2.0. `DesignSystemProvider` is the one optional, thin, client-side provider
 for what CSS cannot do — the generic strings, the locale, the text direction,
 the portal container, the link and image adapters, shared tooltip defaults and
 (opt-in) the toast region. It renders no DOM wrapper ([ADR-010](./docs/adr/010-design-system-provider.md)).
@@ -143,11 +164,10 @@ export default function RootLayout({ children }) {
   Pass the locale your app already knows server-side; the design system never
   reads `navigator.language` during render, so server and client HTML agree.
 - **`linkComponent` / `imageComponent`** — what `LinkButton` and `Logo` render
-  through. Without them the components keep their static `next/link` /
-  `next/image` imports until 2.0, so a Next.js app that renders no provider is
-  unchanged. A non-Next app passes its router's link; a Next.js app uses
-  `NextDesignSystemProvider` so it is ready for the 2.0 removal of the static
-  imports.
+  through. Without them the components render a plain `<a>` / `<img>` (full
+  page navigation). A non-Next app passes its router's link; a Next.js app uses
+  `NextDesignSystemProvider`. `next` is an optional peer, needed only by the
+  `/next` entry.
 - **`portalContainer`**, **`dir`**, **`tooltip`**, **`toasts`** — documented on
   the props. `toasts` mounts the toast region for `useToast()`; leave it off if
   you already render `ToastProvider`.

package/codemods/README.md

@@ -19,6 +19,9 @@ node node_modules/@assure-one/design-system/codemods/run.mjs CM-02 src --report
 
 # Everything this project is missing, in program order
 node node_modules/@assure-one/design-system/codemods/run.mjs upgrade --dry
+
+# Only what a project needs before 1.40 (docs/migration/1.40.md)
+node node_modules/@assure-one/design-system/codemods/run.mjs upgrade --to 1.40 --dry
 ```
 
 There is deliberately **no** `bin` entry and **no** `exports` entry for the
@@ -30,6 +33,7 @@ is `pnpm codemods <id> <paths>`.
 | Option                          | Effect                                                                         |
 | ------------------------------- | ------------------------------------------------------------------------------ |
 | `--dry`                         | report what would happen; write neither files nor the ledger                   |
+| `--to <version>`                | `upgrade` only: run the bundle that release needs (`--to 1.40`, see below)     |
 | `--root <dir>`                  | project root (default: the nearest `package.json` above the working directory) |
 | `--report <prefix>`             | write `<prefix>.json` and `<prefix>.md`                                        |
 | `--json <file>` / `--md <file>` | write one of the two                                                           |
@@ -96,6 +100,19 @@ entry. Report-only codemods and dry runs never touch it. The consumer scanner
 reads the file and the migration dashboard shows the applied ids
 (`migration-status/<app>.json` → `codemodLedger`).
 
+## `upgrade --to 1.40`
+
+`upgrade --to 1.40` runs, in program order, the codemods of the 1.40 bundle
+(`UPGRADE_TARGETS` in `lib/registry.mjs`): one per registry contract that 1.40
+removes or flips (plan §21.2) — CM-01, CM-04, CM-19, CM-12, and the finders
+CM-15 and CM-16. A transforming codemod already in the ledger is skipped, so
+the command is safe to repeat and safe from any 1.x; the report-only finders
+run every time. With `--report <prefix>` each codemod writes
+`<prefix>-<id>.json` and `.md`. The migration guide is
+[`docs/migration/1.40.md`](../docs/migration/1.40.md). `--to 2` (also `2.0`,
+`v2`) still works: it is the name the bundle had while Wave 9 was planned as
+2.0 (decision D11 shipped it as 1.40).
+
 ## Reports
 
 Every run produces the same report: a JSON document (`schema`, the codemod, the
@@ -136,8 +153,8 @@ Class R. W8-02 gave the shared Assure patterns the `/suite` entry and the
 frozen and product-owned modules `/legacy`. Both are re-export barrels over the
 same module instances the root exports, so moving an import is a pure path
 change: no duplicated React context, no behaviour difference. The root keeps
-every name through 1.x (registry `C-ROOT-SUITE`) and drops them in 2.0, so
-running this codemod early costs nothing and running it late is a 2.0 blocker.
+every name through 1.39 (registry `C-ROOT-SUITE`) and drops them in 1.40, so
+running this codemod early costs nothing and running it late is a 1.40 blocker.
 
 ```tsx
 import { Button, AgreementViewer, TimeLogger } from "@assure-one/design-system";
@@ -306,7 +323,7 @@ components with the same names, test files.
 
 Class R. `ProgressBar` and `ProgressRing` colour themselves **by value** when
 no colour is passed (`< 50%` brand, `≥ 50%` warning, `≥ 80%` success) — a
-business mapping the design system should not own, which 2.0 switches off
+business mapping the design system should not own, which 1.40 switches off
 (W9-10, contract C-PROGRESS). W3-21 added `intent`; passing it disables the
 rule. CM-19 makes every call site say what it renders today, so the flip
 changes nothing a consumer did not write down: `variant="<legacy word>"`
@@ -338,7 +355,7 @@ gets `size="md"` — the value the component resolves today
 (`defaultVariants.size`, 40px), so nothing moves on screen. It exists because
 a size _meaning_ can only change once no call site depends on the default:
 after CM-02, the D5 size flip (CM-03 phase 2, W9-06) touches nothing a
-consumer did not write down, and 2.0 gate G6 counts exactly this.
+consumer did not write down, and gate G6 counts exactly this.
 
 The attribute goes after `variant` when there is one (the order the
 applications use) and first otherwise, on its own line when the element's
@@ -357,7 +374,7 @@ scanner that measures G6 counts production files only).
 ### CM-12 — Button `type="submit"` where evident
 
 Class R. An untyped `Button` renders `<button>` without a `type`, which the
-browser treats as `submit`; 2.0 flips the default to `"button"` (W9-05,
+browser treats as `submit`; 1.40 flips the default to `"button"` (W9-05,
 C-BTN-TYPE, gate G4). CM-12 writes down, before the flip, which Buttons submit
 on purpose — and only where the file itself makes that evident:
 
@@ -598,8 +615,8 @@ yet — those are the candidates for new registry entries. `confidence` is `high
 for a token on the component itself, `medium` for a wrapper or a heuristic,
 `low` for an unmapped wrapper.
 
-CM-15 feeds 2.0 gate G7 (`consumerSelectors = 0` for the freezes with removal
-target 2.0). Use `--fail-on-findings` to gate on it. The committed findings for
+CM-15 feeds gate G7 (`consumerSelectors = 0` for the freezes with registry
+removal target 2.0, which 1.40 lifts). Use `--fail-on-findings` to gate on it. The committed findings for
 the four consumer apps are in `docs/codemods/`.
 
 ### CM-16 — `globals.css` analyser

package/codemods/lib/registry.mjs

@@ -22,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-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-B6rem2II.d.ts → brand-theme-ZYM867Jz.d.ts}

@@ -14,7 +14,7 @@ interface BrandThemeSeed {
      * `#rrggbb`. `undefined` or `null` means "the same as `brand`", which is what
      * the built-in `[data-ds-brand]` scopes do.
      */
-    accent?: string | null;
+    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"];