@assure-one/design-system 1.31.0 → 1.33.0

package/README.md

@@ -11,6 +11,8 @@ 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.
 
 ## Install
@@ -38,6 +40,49 @@ export default function Page() {
 }
 ```
 
+### The split CSS entries (experimental)
+
+`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.
+
+| 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. |
+
+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
@@ -52,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/0.2.0-radix-migration.mjs

@@ -0,0 +1,315 @@
+/**
+ * @assure-one/design-system 0.1.x → 0.2.0 migration codemod
+ *
+ * Run from the consumer repo (firm or portal):
+ *
+ *   npx jscodeshift -t node_modules/@assure-one/design-system/codemods/0.2.0-radix-migration.mjs \
+ *     --extensions=tsx,ts,jsx,js \
+ *     --parser=tsx \
+ *     'src/**\/*.{ts,tsx,js,jsx}'
+ *
+ * Or, if you've copied the file locally:
+ *
+ *   npx jscodeshift -t ./codemods/0.2.0-radix-migration.mjs \
+ *     --extensions=tsx,ts,jsx,js --parser=tsx 'src/**\/*.{ts,tsx}'
+ *
+ * VERBOSE per-file logs:
+ *   VERBOSE=1 npx jscodeshift -t ... 'src/**\/*.tsx'
+ *
+ * What it does
+ * ------------
+ *   1. <Slider value={n} />        → <Slider value={[n]} />
+ *      <Slider defaultValue={n} /> → <Slider defaultValue={[n]} />
+ *      Adds a `// TODO 0.2.0: onValueChange now receives number[]` line above
+ *      any <Slider> with `onValueChange` so the consumer can review the body.
+ *
+ *   2. <Avatar><Image src=... alt=... /></Avatar>  (next/image inner)
+ *      → <Avatar src=... alt=... />
+ *      Drops the inner <Image>. If <Avatar> already has `src`, leaves it and
+ *      emits a TODO. If the <Image> isn't `next/image`, leaves it untouched.
+ *
+ *   3. useToast — no-op. `useToast()` already returned `{ toast }`; 0.2.0
+ *      adds `dismiss` (additive). Existing call sites keep working.
+ *
+ *   4. TeamMemberSelect — no-op. The `value: ""` (unassigned) contract is
+ *      preserved on the consumer-facing API; the `__unassigned__` sentinel
+ *      is internal only.
+ *
+ * Idempotent: running twice changes nothing the second time. Already-array
+ * Slider values and already-flattened Avatars are skipped.
+ */
+
+const SLIDER_NUMERIC_PROPS = ["value", "defaultValue"];
+const TODO_SLIDER = " TODO 0.2.0: onValueChange now receives number[] (was number) ";
+const TODO_SLIDER_IDENT =
+  " TODO 0.2.0: Slider value/defaultValue is now number[] — wrap in [] if this expression is still number ";
+const TODO_AVATAR_CONFLICT =
+  " TODO 0.2.0: <Avatar> already has src — could not auto-merge with inner next/image child ";
+const TODO_AVATAR_MERGED =
+  " TODO 0.2.0: review hoisted Avatar src/alt (was inner next/image child) ";
+
+export default function transformer(file, api) {
+  const j = api.jscodeshift;
+  const root = j(file.source);
+  let changed = false;
+  const log = [];
+
+  /* -------------------------------------------------------------------- */
+  /* Helpers                                                              */
+  /* -------------------------------------------------------------------- */
+
+  function jsxOpeningName(opening) {
+    const name = opening.name;
+    if (!name) return null;
+    if (name.type === "JSXIdentifier") return name.name;
+    return null;
+  }
+
+  function findAttr(opening, attrName) {
+    return opening.attributes?.find(
+      (a) =>
+        a.type === "JSXAttribute" &&
+        a.name?.type === "JSXIdentifier" &&
+        a.name.name === attrName,
+    );
+  }
+
+  function isAlreadyArrayExpression(attr) {
+    if (!attr || attr.type !== "JSXAttribute") return false;
+    const v = attr.value;
+    if (!v || v.type !== "JSXExpressionContainer") return false;
+    const expr = v.expression;
+    if (!expr) return false;
+    // already array literal
+    if (expr.type === "ArrayExpression") return true;
+    // identifier / member / call — assume the consumer is already passing an
+    // array; do not double-wrap. (Idempotency over a brittle type check.)
+    return (
+      expr.type === "Identifier" ||
+      expr.type === "MemberExpression" ||
+      expr.type === "CallExpression" ||
+      expr.type === "ConditionalExpression" ||
+      expr.type === "LogicalExpression"
+    );
+  }
+
+  function isScalarNumericLiteralExpression(attr) {
+    if (!attr || attr.type !== "JSXAttribute") return false;
+    const v = attr.value;
+    // Bare `value=42` is not legal JSX numeric, so we only care about expr
+    // containers wrapping a NumericLiteral or unary minus numeric.
+    if (!v || v.type !== "JSXExpressionContainer") return false;
+    const e = v.expression;
+    if (!e) return false;
+    if (e.type === "NumericLiteral" || e.type === "Literal") {
+      return typeof e.value === "number";
+    }
+    if (
+      e.type === "UnaryExpression" &&
+      e.operator === "-" &&
+      e.argument &&
+      (e.argument.type === "NumericLiteral" ||
+        (e.argument.type === "Literal" && typeof e.argument.value === "number"))
+    ) {
+      return true;
+    }
+    return false;
+  }
+
+  function wrapAttrInArray(attr) {
+    const expr = attr.value.expression;
+    attr.value = j.jsxExpressionContainer(j.arrayExpression([expr]));
+  }
+
+  function hasLeadingComment(node, text) {
+    const list = node.leadingComments || [];
+    return list.some((c) => c.value === text);
+  }
+
+  function addLeadingComment(path, text) {
+    const node = path.node;
+    if (hasLeadingComment(node, text)) return false;
+    node.comments = node.comments || [];
+    const comment = { type: "CommentLine", value: text, leading: true, trailing: false };
+    node.comments.unshift(comment);
+    // jscodeshift / recast also reads `leadingComments`
+    node.leadingComments = node.leadingComments || [];
+    node.leadingComments.unshift(comment);
+    return true;
+  }
+
+  /* -------------------------------------------------------------------- */
+  /* Detect imported local names                                          */
+  /*                                                                      */
+  /* We only want to touch <Slider> and <Avatar> when they come from      */
+  /* @assure-one/design-system (or are unambiguous globally). To stay     */
+  /* safe across the firm + portal codebases, we scope by import source.  */
+  /* -------------------------------------------------------------------- */
+
+  const dsLocalNames = new Set();
+  const nextImageLocalNames = new Set();
+
+  root.find(j.ImportDeclaration).forEach((path) => {
+    const src = path.node.source?.value;
+    if (!src) return;
+    if (src === "@assure-one/design-system") {
+      for (const spec of path.node.specifiers || []) {
+        if (spec.type === "ImportSpecifier" && spec.local?.name) {
+          dsLocalNames.add(spec.local.name);
+        }
+      }
+    }
+    if (src === "next/image") {
+      for (const spec of path.node.specifiers || []) {
+        if (
+          (spec.type === "ImportDefaultSpecifier" ||
+            spec.type === "ImportSpecifier") &&
+          spec.local?.name
+        ) {
+          nextImageLocalNames.add(spec.local.name);
+        }
+      }
+    }
+  });
+
+  // The DS exports `Slider` and `Avatar` under those exact names. If the
+  // consumer didn't import them from DS we leave their JSX alone — that
+  // avoids touching a local component that happens to share a name.
+  const sliderLocal = dsLocalNames.has("Slider") ? "Slider" : null;
+  const avatarLocal = dsLocalNames.has("Avatar") ? "Avatar" : null;
+
+  /* -------------------------------------------------------------------- */
+  /* Change 1 — Slider value/defaultValue scalar → array                  */
+  /* -------------------------------------------------------------------- */
+
+  if (sliderLocal) {
+    root
+      .find(j.JSXElement, {
+        openingElement: { name: { type: "JSXIdentifier", name: sliderLocal } },
+      })
+      .forEach((path) => {
+        const opening = path.node.openingElement;
+
+        let wrappedAny = false;
+        let needsIdentTodo = false;
+        for (const propName of SLIDER_NUMERIC_PROPS) {
+          const attr = findAttr(opening, propName);
+          if (!attr) continue;
+          if (isScalarNumericLiteralExpression(attr)) {
+            wrapAttrInArray(attr);
+            changed = true;
+            wrappedAny = true;
+            log.push(`Slider: ${propName}={n} → ${propName}={[n]}`);
+            continue;
+          }
+          if (isAlreadyArrayExpression(attr)) {
+            // Could be Identifier / MemberExpression / CallExpression / etc.
+            // We can't tell from AST whether it's number[] (already migrated)
+            // or number (needs migration). Leave it and emit a TODO so the
+            // consumer reviews. Idempotent on the array-literal case.
+            const v = attr.value?.expression;
+            if (v && v.type !== "ArrayExpression") {
+              needsIdentTodo = true;
+            }
+          }
+        }
+        if (needsIdentTodo) {
+          if (addLeadingComment(path, TODO_SLIDER_IDENT)) {
+            changed = true;
+            log.push("Slider: added value/defaultValue identifier TODO comment");
+          }
+        }
+
+        // TODO comment for onValueChange
+        const onValueChange = findAttr(opening, "onValueChange");
+        if (onValueChange) {
+          if (addLeadingComment(path, TODO_SLIDER)) {
+            changed = true;
+            log.push("Slider: added onValueChange TODO comment");
+          }
+        }
+      });
+  }
+
+  /* -------------------------------------------------------------------- */
+  /* Change 2 — Avatar with next/image child → flat src/alt props         */
+  /* -------------------------------------------------------------------- */
+
+  if (avatarLocal && nextImageLocalNames.size > 0) {
+    root
+      .find(j.JSXElement, {
+        openingElement: { name: { type: "JSXIdentifier", name: avatarLocal } },
+      })
+      .forEach((path) => {
+        const el = path.node;
+        const opening = el.openingElement;
+        const children = el.children || [];
+
+        // Find a single next/image child (ignoring whitespace text nodes)
+        const meaningful = children.filter(
+          (c) =>
+            !(
+              c.type === "JSXText" &&
+              (c.value === "" || /^\s*$/.test(c.value))
+            ),
+        );
+        if (meaningful.length !== 1) return;
+        const child = meaningful[0];
+        if (child.type !== "JSXElement") return;
+        const childName = jsxOpeningName(child.openingElement);
+        if (!childName || !nextImageLocalNames.has(childName)) return;
+
+        // Don't merge if Avatar already has src — emit TODO and skip
+        const existingSrc = findAttr(opening, "src");
+        if (existingSrc) {
+          if (addLeadingComment(path, TODO_AVATAR_CONFLICT)) {
+            changed = true;
+            log.push("Avatar: src conflict — TODO comment added");
+          }
+          return;
+        }
+
+        // Hoist src + alt from <Image>
+        const childOpening = child.openingElement;
+        const srcAttr = findAttr(childOpening, "src");
+        const altAttr = findAttr(childOpening, "alt");
+        if (!srcAttr) return; // nothing to hoist
+
+        const newAttrs = [...opening.attributes];
+        newAttrs.push(j.jsxAttribute(j.jsxIdentifier("src"), srcAttr.value));
+        if (altAttr && !findAttr(opening, "alt")) {
+          newAttrs.push(j.jsxAttribute(j.jsxIdentifier("alt"), altAttr.value));
+        }
+        opening.attributes = newAttrs;
+
+        // Self-close the Avatar (no remaining children)
+        opening.selfClosing = true;
+        el.closingElement = null;
+        el.children = [];
+
+        addLeadingComment(path, TODO_AVATAR_MERGED);
+        changed = true;
+        log.push("Avatar: hoisted next/image src/alt and removed inner element");
+      });
+  }
+
+  /* -------------------------------------------------------------------- */
+  /* Done                                                                 */
+  /* -------------------------------------------------------------------- */
+
+  if (!changed) return null;
+
+  if (process.env.VERBOSE) {
+    // eslint-disable-next-line no-console
+    console.log(`[0.2.0-radix-migration] ${file.path}`);
+    for (const line of log) {
+      // eslint-disable-next-line no-console
+      console.log(`  - ${line}`);
+    }
+  }
+
+  return root.toSource({ quote: "double" });
+}
+
+// jscodeshift parser hint
+export const parser = "tsx";