@assure-one/design-system 1.32.0 → 1.33.0

package/README.md

@@ -11,6 +11,7 @@ The single source of truth for visual design across all Assure products.
 - [**`CHANGELOG.md`**](./CHANGELOG.md) — release-by-release log of what shipped.
 - [**`CONTRIBUTING.md`**](./CONTRIBUTING.md) — dev loop, release flow, versioning, pitfalls.
 - [**`CLAUDE.md`**](./CLAUDE.md) — invariants and conventions for AI assistants working in this repo.
+- [**`docs/integration/css.md`**](./docs/integration/css.md) — how an application loads our CSS: layer order, import sequence, the compatibility preset, removing `@source`, runtime brand theming.
 - [**`docs/testing.md`**](./docs/testing.md) — rendering the real package in your app's Jest tests (`@assure-one/design-system/testing`, experimental).
 - [**`claude-skills/`**](./claude-skills) — drop-in Claude Code skill for consuming projects.
 
@@ -53,15 +54,35 @@ no component reads them, and importing them changes nothing on its own.
 | `./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. |
-
-Import order, once the mode is supported end to end, is
-`tokens.css` → `tailwind.css` → `shadcn.css` (optional) → `base.css`
-(optional), after your own `@import "tailwindcss"`. The integration guide with
-the full sequence, the layer statement and the per-app preset lands with the
-rest of Wave 1; until then the reasoning lives in
-[ADR-004](./docs/adr/004-css-delivery-cascade.md) and
+| `./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. |
+
+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
+in [ADR-004](./docs/adr/004-css-delivery-cascade.md) and
 [ADR-005](./docs/adr/005-app-vocabulary-bridge.md).
 
+### Runtime brand theming (experimental)
+
+For a tenant colour known only at runtime, `@assure-one/design-system/tokens`
+exports `createBrandTheme()`: a validated seed becomes the custom properties a
+built-in brand scope declares, ready to spread into a `style` attribute.
+
+```tsx
+import { createBrandTheme } from "@assure-one/design-system/tokens";
+
+<div style={{ ...createBrandTheme({ brand: "#2258d8", accent: "#f59e0b" }) }}>…</div>;
+```
+
+It is pure and SSR-deterministic, clamps a fill too pale to read against the
+canvas, and guarantees WCAG AA for every foreground it emits. The seed shape is
+gated by decision D7 and may change while that decision is open — see
+[`docs/integration/css.md`](./docs/integration/css.md#5-runtime-brand-theming).
+
 ## Develop
 
 ```bash
@@ -76,14 +97,24 @@ See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the full dev loop, including iter
 
 ## Architecture
 
-3-tier token system (W3C Design Tokens spec compatible):
+3-tier token system, authored as DTCG JSON in [`tokens/src`](./tokens/README.md)
+and generated into `src/tokens/` and the `./css/*` entries (ADR-003):
 
-```
-reference   →   system (semantic)   →   component
-color.navy.700  →  color.action.primary.bg  →  button.primary.bg
-```
+| Tier | Example (namespaced name → value) | Reads |
+| --- | --- | --- |
+| reference | `--ds-ref-brand-pro-fg: #6c42f8` | a literal; the raw ramps, one per brand |
+| system (semantic) | `--ds-color-action-brand-bg: var(--ds-ref-brand-pro-fg)` | the reference tier; **this is the public contract** |
+| component | `--ds-menu-item-hover-bg: var(--ds-color-canvas-sunken)` | the system tier; only where a component must be themable on its own |
+
+Components consume **system tokens**, never reference values directly. Themes
+(colour scheme, per-product brand, a runtime brand from `createBrandTheme()`)
+re-map system → reference without touching component code.
 
-Components consume **system tokens**, never reference values directly. Themes (light, dark, per-product accent) re-map system → reference without touching component code.
+Every token has two published spellings: the namespaced `--ds-*` name above and
+the legacy name it ships as today (`--color-brand`, `--color-pro-fg`,
+`--color-menu-item-hover-bg`). `css/legacy-aliases.css` declares
+`<legacy>: var(<--ds-* name>)` in the same scopes, so both resolve to the same
+value — proved by `pnpm tokens:ds-check`.
 
 ## Releases
 

package/codemods/README.md

@@ -102,12 +102,72 @@ the list a human has to pick up — spread props, dynamic expressions, conflicti
 
 | Id    | Class | What it does                                                                                                                        |
 | ----- | ----- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| CM-14 | X     | hidden-input mirror finder: hidden `<input name>` a consumer added because a design-system control posts nothing                    |
 | CM-15 | X     | DOM-selector finder: consumer code that depends on the internal DOM of design-system components, mapped to registry `C-DOM-*` ids   |
 | CM-16 | X     | `globals.css` analyser: `@source` into the package, duplicate preflight, colliding `@theme` keys, unlayered globals, legacy `var()` |
+| CM-20 | X     | Select sentinel finder: option values standing in for "no value", and the line where each is converted back                         |
 
 The remaining ids of plan §29 land with the waves that ship their replacement
 APIs.
 
+### CM-14 — hidden-input mirror finder
+
+Report-only, **for ever**: deleting a mirror changes what the server receives,
+and plan §29 never automates that. It is the input to W4-04 (native form
+participation) and to the registry contract `C-HIDDEN-MIRRORS`.
+
+The applications do not put a mirror next to its control — they collect the
+mirrors at the top of the `<form>` and bind the control far below ([CU §18]).
+"Next to" is therefore read as _bound to the same state_:
+
+| Rule                        | Contract         | Found                                                                          |
+| --------------------------- | ---------------- | ------------------------------------------------------------------------------ |
+| `mirror-shared-binding`     | C-HIDDEN-MIRRORS | the hidden input's `value` reads a binding a design-system control is bound to |
+| `mirror-in-form`            | C-HIDDEN-MIRRORS | same `<form>` as a control that posts nothing today; nothing ties the two      |
+| `unregistered-hidden-input` | (unregistered)   | no control to mirror — a value the server supplied (a token, an id)            |
+
+Each finding names the control, the field name and whether that control takes
+`name` **today** (`yes`) or only after Wave 4 (`planned`); severity is `high`
+when the control takes `name` and the call site already passes it, because the
+form then posts the field twice.
+
+The third rule is why the report reconciles with the audit's census of every
+hidden `<input>` ([CU §24]): CM-14 reports the same population, classified,
+rather than a smaller number with no explanation. It does not look across
+files — a mirror whose control lives elsewhere lands in `mirror-in-form` or
+`unregistered-hidden-input` and says so. An `<input type={expr}>` whose type is
+computed appears in "could not be transformed".
+
+The `name` capability table lives in the transform, and
+`tests/codemods/cm-14.test.mjs` checks it against the design system's own
+sources so it cannot describe components this version does not ship.
+
+### CM-20 — Select sentinel finder
+
+Report-only, **for ever**: replacing a sentinel with `null` changes what the
+server receives. It is the input to W4-08 (`Select value: string | null`) and
+to the registry contract `C-SELECT-EMPTY`.
+
+The spellings are **found, not assumed**. The registry names `"none"` and
+`"__unassigned__"`; the applications use far more, and `"none"` is also a real
+domain value. CM-20 reports a spelling only where the file itself proves it
+stands in for nothing:
+
+| Rule                  | Contract       | Found                                                             |
+| --------------------- | -------------- | ----------------------------------------------------------------- |
+| `empty-string-value`  | C-SELECT-EMPTY | `value=""` on a Select-family control or an option                |
+| `sentinel-dunder`     | C-SELECT-EMPTY | a `__…__` spelling used as a Select value                         |
+| `sentinel-constant`   | C-SELECT-EMPTY | a no-value-named constant used as a Select value                  |
+| `sentinel-word`       | C-SELECT-EMPTY | `none`/`all`/… **with** a no-value label or a round trip          |
+| `sentinel-discovered` | C-SELECT-EMPTY | any other spelling the file converts to nothing                   |
+| `sentinel-conversion` | C-SELECT-EMPTY | the line that maps a reported sentinel to `null`/`undefined`/`""` |
+
+A known word with no evidence at all is **not** reported: CM-20 would rather
+miss a sentinel than invite someone to change a value the backend depends on.
+Sentinels outside the Select family — grouping keys, tab ids, route segments —
+are out of scope even when the spelling matches, and nothing is followed across
+files.
+
 ### CM-15 — DOM-selector finder
 
 Report-only. It never modifies a file; the runner throws if it tries. What it

package/codemods/lib/forms.mjs

@@ -0,0 +1,253 @@
+/**
+ * Form-shaped source facts, shared by the two report-only finders of the
+ * forms wave (plan §16): CM-14 (hidden-input mirrors) and CM-20 (Select
+ * sentinels).
+ *
+ * `lib/jsx.mjs` answers "which class tokens sit on which design-system
+ * component" and therefore only records elements that carry a class
+ * attribute. A hidden `<input type="hidden" name="x" value={x} />` carries
+ * none, and a sentinel lives in a prop value, not in a class token — so the
+ * forms codemods need a different view of the same tree:
+ *
+ * - **every** JSX element, design-system and raw alike, in document order;
+ * - each element's attributes, with the string literals and the identifiers
+ *   of the expression behind them (the identifiers are what tie a mirror to
+ *   the control it mirrors);
+ * - the nearest `<form>` ancestor, because the applications do not put a
+ *   mirror next to its control — they collect the mirrors at the top of the
+ *   form ([CU §18]);
+ * - top-level `const NAME = "literal"` declarations, because the sentinels
+ *   are named constants (`const NONE_VALUE = "__none__"`).
+ *
+ * As everywhere in `codemods/lib`, the TypeScript module is passed in: a
+ * codemod never imports a parser itself (`lib/environment.mjs`).
+ */
+import { DS_PACKAGE, createSourceFile } from "./jsx.mjs";
+
+export { DS_PACKAGE };
+
+const isDsSpecifier = (s) => s === DS_PACKAGE || s.startsWith(`${DS_PACKAGE}/`);
+
+/** Attributes whose value is the control's current value, in binding order. */
+export const VALUE_PROPS = ["value", "defaultValue", "checked", "defaultChecked", "selected"];
+
+/** Attributes through which a control writes its value back. */
+export const CHANGE_PROPS = [
+  "onValueChange",
+  "onCheckedChange",
+  "onChange",
+  "onSelect",
+  "onRemove",
+  "onSelectionChange",
+];
+
+/**
+ * Parses one file into form facts.
+ *
+ * Returns:
+ * - `sf`, `lineOf` — the source file and a node → line helper
+ * - `imports` — design-system local name → exported name
+ * - `namespaces` — local names of `import * as X from the package`
+ * - `elements` — every JSX element, in document order, as described below
+ * - `constants` — top-level `const` name → `{ text, line }` for string consts
+ * - `componentsUsed` — the design-system base names used as JSX
+ * - `parseErrors`
+ *
+ * An element is
+ * `{ index, parent, tag, base, component, isDs, line, props, spread, form }`
+ * where `props` is a Map of attribute name → `{ literals, identifiers, text,
+ * line, expression }` and `form` is the index of the nearest `<form>`
+ * ancestor (or `null`).
+ */
+export function analyseForms(ts, text, rel) {
+  const sf = createSourceFile(ts, text, rel);
+  const lineOf = (node) => sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1;
+
+  const imports = new Map();
+  const namespaces = new Set();
+  for (const stmt of sf.statements) {
+    if (!ts.isImportDeclaration(stmt) || !ts.isStringLiteral(stmt.moduleSpecifier)) continue;
+    if (!isDsSpecifier(stmt.moduleSpecifier.text)) continue;
+    const clause = stmt.importClause;
+    if (!clause || clause.isTypeOnly) continue;
+    const bindings = clause.namedBindings;
+    if (bindings && ts.isNamespaceImport(bindings)) namespaces.add(bindings.name.text);
+    else if (bindings && ts.isNamedImports(bindings)) {
+      for (const el of bindings.elements) {
+        if (!el.isTypeOnly) imports.set(el.name.text, (el.propertyName ?? el.name).text);
+      }
+    }
+  }
+
+  /** Top-level `const NAME = "text"`, the shape the sentinels are declared in. */
+  const constants = new Map();
+  for (const stmt of sf.statements) {
+    const list = ts.isVariableStatement(stmt) ? stmt.declarationList : null;
+    if (!list || !(list.flags & ts.NodeFlags.Const)) continue;
+    for (const decl of list.declarations) {
+      if (!ts.isIdentifier(decl.name) || !decl.initializer) continue;
+      const init = decl.initializer;
+      if (ts.isStringLiteral(init) || ts.isNoSubstitutionTemplateLiteral(init)) {
+        constants.set(decl.name.text, { text: init.text, line: lineOf(init) });
+      }
+    }
+  }
+
+  /** String literals inside an expression, at any depth below JSX. */
+  const literalsIn = (node, out = []) => {
+    if (!node) return out;
+    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
+      out.push(node.text);
+      return out;
+    }
+    if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node) || ts.isJsxFragment(node)) {
+      return out;
+    }
+    // A block body: `forEachChild` stops at the first truthy return, and the
+    // accumulator is always truthy.
+    ts.forEachChild(node, (child) => {
+      literalsIn(child, out);
+    });
+    return out;
+  };
+
+  /**
+   * Identifier names an expression reads. Member names (`a.b`), object keys
+   * and JSX subtrees are excluded: what matters is which bindings the value
+   * depends on, so that two attributes reading `entityType` can be recognised
+   * as two views of the same state.
+   */
+  const identifiersIn = (node, out = new Set()) => {
+    if (!node) return out;
+    if (ts.isIdentifier(node)) {
+      const parent = node.parent;
+      const isMemberName = parent && ts.isPropertyAccessExpression(parent) && parent.name === node;
+      const isKey =
+        parent &&
+        (ts.isPropertyAssignment(parent) || ts.isPropertySignature(parent)) &&
+        parent.name === node;
+      if (!isMemberName && !isKey) out.add(node.text);
+      return out;
+    }
+    if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node) || ts.isJsxFragment(node)) {
+      return out;
+    }
+    ts.forEachChild(node, (child) => {
+      identifiersIn(child, out);
+    });
+    return out;
+  };
+
+  const resolveTag = (tag) => {
+    const members = [];
+    let current = tag;
+    while (ts.isPropertyAccessExpression(current)) {
+      members.unshift(current.name.text);
+      current = current.expression;
+    }
+    if (!ts.isIdentifier(current)) return null;
+    const root = current.text;
+    if (namespaces.has(root) && members.length) {
+      return { base: members[0], component: members.join(".") };
+    }
+    const base = imports.get(root);
+    if (!base) return null;
+    return { base, component: [base, ...members].join(".") };
+  };
+
+  const elements = [];
+  const openingOf = (node) => (ts.isJsxElement(node) ? node.openingElement : node);
+
+  const record = (node, parent, form) => {
+    const opening = openingOf(node);
+    const info = resolveTag(opening.tagName);
+    const tag = opening.tagName.getText(sf);
+    const props = new Map();
+    let spread = false;
+    for (const attr of opening.attributes.properties) {
+      if (ts.isJsxSpreadAttribute(attr)) {
+        spread = true;
+        continue;
+      }
+      if (!ts.isJsxAttribute(attr)) continue;
+      const name = attr.name.getText(sf);
+      const init = attr.initializer;
+      if (init === undefined) {
+        // A bare attribute (`required`) is the boolean `true`.
+        props.set(name, {
+          literals: [],
+          identifiers: [],
+          text: "true",
+          line: lineOf(attr),
+          expression: false,
+        });
+        continue;
+      }
+      const inner = ts.isJsxExpression(init) ? (init.expression ?? null) : init;
+      const isLiteral =
+        inner !== null && (ts.isStringLiteral(inner) || ts.isNoSubstitutionTemplateLiteral(inner));
+      props.set(name, {
+        literals: inner ? literalsIn(inner) : [],
+        identifiers: inner ? [...identifiersIn(inner)] : [],
+        text: inner ? inner.getText(sf) : null,
+        line: lineOf(attr),
+        expression: Boolean(inner) && !isLiteral,
+      });
+    }
+    const entry = {
+      index: elements.length,
+      parent,
+      tag,
+      base: info?.base ?? null,
+      component: info?.component ?? null,
+      isDs: Boolean(info),
+      line: lineOf(opening),
+      props,
+      spread,
+      form,
+      node,
+    };
+    elements.push(entry);
+    return entry;
+  };
+
+  const walk = (node, parent, form) => {
+    if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) {
+      const entry = record(node, parent, form);
+      const nextForm = /^(?:form|Form)$/.test(entry.tag) ? entry.index : form;
+      ts.forEachChild(node, (child) => walk(child, entry.index, nextForm));
+      return;
+    }
+    ts.forEachChild(node, (child) => walk(child, parent, form));
+  };
+  walk(sf, null, null);
+
+  const parseErrors = (sf.parseDiagnostics ?? []).map((d) => ({
+    line: d.start === undefined ? null : sf.getLineAndCharacterOfPosition(d.start).line + 1,
+    message: ts.flattenDiagnosticMessageText(d.messageText, " "),
+  }));
+
+  return {
+    sf,
+    lineOf,
+    literalsIn,
+    identifiersIn: (node) => [...identifiersIn(node)],
+    imports,
+    namespaces,
+    elements,
+    constants,
+    componentsUsed: new Set(elements.filter((e) => e.isDs).map((e) => e.base)),
+    parseErrors,
+  };
+}
+
+/** The literal value of an attribute when it is a single string, else `null`. */
+export const literalValue = (prop) =>
+  prop && !prop.expression && prop.literals.length === 1 ? prop.literals[0] : null;
+
+/** Whether `inner` is `outer` or sits below it in the element tree. */
+export function isWithin(elements, inner, outer) {
+  if (outer === null || inner === null) return false;
+  for (let i = inner; i !== null; i = elements[i].parent) if (i === outer) return true;
+  return false;
+}

package/codemods/lib/registry.mjs

@@ -3,8 +3,10 @@
  * codemods listed here can be run by id; the sequence is the plan's.
  */
 export const CODEMODS = [
+  { id: "CM-14", module: "../transforms/cm-14-hidden-mirrors.mjs" },
   { id: "CM-15", module: "../transforms/cm-15-dom-selectors.mjs" },
   { id: "CM-16", module: "../transforms/cm-16-globals-css.mjs" },
+  { id: "CM-20", module: "../transforms/cm-20-select-sentinels.mjs" },
 ];
 
 export const findCodemod = (id) =>