@beyondwork/docx-react-component 1.0.52 → 1.0.54

package/src/ui-tailwind/theme/tokens.css

@@ -0,0 +1,345 @@
+/*
+ * @beyondwork/docx-react-component — canonical design tokens
+ *
+ * Source of truth for every color, shadow, radius, space, and motion value
+ * consumed by the chrome and document surface. Values are copied verbatim
+ * from `docs/reference/designsystem.md` §10 (starter CSS). Any hex change
+ * happens HERE and in `tokens.ts` — never in a component file.
+ *
+ * Two-layer model:
+ *   1. Product names (TypeScript) — `BRAND_TOKENS.color.accent.primary`
+ *   2. CSS variables (this file)  — `var(--color-accent-primary)`
+ *
+ * See `docs/wiki/design-tokens.md` for narrative + eviction policy.
+ *
+ * Host overrides:
+ *   Allowed  — accent family, `--color-bg-app`, `--radius-*`, `--motion-*`
+ *   Locked   — semantic, change, comment, canvas, focus-ring
+ *   See `docs/reference/designsystem.md` §8.5 + §9.
+ */
+
+:root {
+  /* Backgrounds */
+  --color-bg-app: #F4F7F5;
+  --color-bg-chrome: #FAFCFA;
+  --color-bg-sidebar: #F1F6F2;
+  --color-bg-canvas: #FFFFFF;
+  --color-bg-elevated: #FFFFFF;
+  --color-bg-hover: #EAF6EF;
+  --color-bg-selected: #E2F2E8;
+  --color-bg-muted: #F7FAF8;
+  --color-bg-overlay: rgba(21, 26, 23, 0.08);
+
+  /* Borders */
+  --color-border-subtle: #E2EAE4;
+  --color-border-default: #D3DED6;
+  --color-border-strong: #BECDBF;
+  --color-border-accent: #8FC9AD;
+
+  /* Text */
+  --color-text-primary: #151A17;
+  --color-text-secondary: #5E6D63;
+  --color-text-tertiary: #8A978F;
+  --color-text-quiet: #A4AEA8;
+  --color-text-inverse: #F7FAF8;
+  --color-text-on-accent: #F7FAF8;
+  --color-text-on-soft-accent: #18563F;
+
+  /* Accent (host-overridable) */
+  --color-accent-primary: #1F6B4F;
+  --color-accent-primary-hover: #18563F;
+  --color-accent-primary-active: #124432;
+  --color-accent-secondary: #72D6AE;
+  --color-accent-secondary-hover: #5FC79C;
+  --color-accent-secondary-active: #49B785;
+  --color-accent-soft: #DDF1E4;
+  --color-accent-soft-hover: #CEEAD8;
+
+  /* Semantic (locked) */
+  --color-semantic-success: #1F8A5B;
+  --color-semantic-success-soft: #DDF3E8;
+  --color-semantic-warning: #D58B1E;
+  --color-semantic-warning-soft: #FBEFD8;
+  --color-semantic-error: #D95C67;
+  --color-semantic-error-soft: #FBE3E6;
+  --color-semantic-info: #2F8FCE;
+  --color-semantic-info-soft: #DCEFFC;
+
+  /* Field */
+  --color-field-fill: #F6FAF7;
+  --color-field-editable: #EEF8F0;
+  --color-field-focus: #DDF1E4;
+  --color-field-invalid: #FBE3E6;
+  --color-field-warning: #FBEFD8;
+
+  /* Status */
+  --color-status-ready: #1F8A5B;
+  --color-status-in-progress: #2F8FCE;
+  --color-status-paused: #8A978F;
+  --color-status-blocked: #D95C67;
+  --color-status-review: #1F6B4F;
+  --color-status-draft: #72907E;
+
+  /* Comment (locked) */
+  --color-comment-marker: #1F6B4F;
+  --color-comment-marker-hover: #18563F;
+  --color-comment-thread-bg: #F3FAF6;
+
+  /* Change (locked) */
+  --color-change-insertion: #DDF3E8;
+  --color-change-deletion: #FBE3E6;
+  --color-change-comment: #E8F4EC;
+  --color-change-selection: #DDF1E4;
+
+  /* Chart — categorical */
+  --color-chart-categorical-1: #1F6B4F;
+  --color-chart-categorical-2: #72D6AE;
+  --color-chart-categorical-3: #2F8FCE;
+  --color-chart-categorical-4: #D58B1E;
+  --color-chart-categorical-5: #7A6AF0;
+  --color-chart-categorical-6: #D95C67;
+  --color-chart-categorical-7: #5E8E7A;
+  --color-chart-categorical-8: #A7D9C1;
+
+  /* Chart — sequential */
+  --color-chart-sequential-1: #EAF6EF;
+  --color-chart-sequential-2: #D4EEDD;
+  --color-chart-sequential-3: #B4DFC8;
+  --color-chart-sequential-4: #8FC9AD;
+  --color-chart-sequential-5: #5FA985;
+  --color-chart-sequential-6: #1F6B4F;
+
+  /* Chart — diverging */
+  --color-chart-diverging-neg-strong: #C94B57;
+  --color-chart-diverging-neg: #E9979F;
+  --color-chart-diverging-neutral: #E9EFEA;
+  --color-chart-diverging-pos: #97D1B3;
+  --color-chart-diverging-pos-strong: #1F6B4F;
+
+  /* Scope tints (§3.7.1) */
+  --color-scope-tint-blocked: #FBE3E6;
+  --color-scope-tint-in-scope: #E2F2E8;
+  --color-scope-tint-suggest: #FBEFD8;
+  --color-scope-tint-comment: #F3FAF6;
+  --color-scope-tint-scheduled: #DCEFFC;
+  --color-scope-tint-proposed: #EAF6EF;
+
+  /* Shadows */
+  --shadow-soft: 0 6px 20px rgba(21, 26, 23, 0.06);
+  --shadow-float: 0 12px 32px rgba(21, 26, 23, 0.12);
+  --shadow-focus: 0 0 0 3px rgba(114, 214, 174, 0.28);
+
+  /* Radius (§4.3) */
+  --radius-sm: 10px;
+  --radius-md: 12px;
+  --radius-lg: 14px;
+  --radius-xl: 16px;
+  --radius-pill: 9999px;
+
+  /* Spacing (4px base) */
+  --space-1: 4px;
+  --space-2: 8px;
+  --space-3: 12px;
+  --space-4: 16px;
+  --space-5: 20px;
+  --space-6: 24px;
+  --space-8: 32px;
+  --space-10: 40px;
+  --space-12: 48px;
+  --space-16: 64px;
+
+  /* Motion (host-overridable) */
+  --motion-fast: 120ms;
+  --motion-default: 160ms;
+  --motion-slow: 220ms;
+}
+
+/*
+ * Dark palette (designsystem §3.4).
+ *
+ * Canonical selector is `[data-theme="dark"]`; `.dark` class is retained
+ * as a compat selector for one release cycle (existing harness markup
+ * uses it alongside the attribute). Remove `.dark` after an explicit
+ * consumer audit.
+ */
+[data-theme="dark"],
+.dark {
+  /* Backgrounds */
+  --color-bg-app: #0E1411;
+  --color-bg-chrome: #131B17;
+  --color-bg-sidebar: #16211B;
+  --color-bg-canvas: #1B2620;
+  --color-bg-elevated: #202E27;
+  --color-bg-hover: #21342A;
+  --color-bg-selected: #274234;
+  --color-bg-muted: #17211C;
+  --color-bg-overlay: rgba(0, 0, 0, 0.32);
+
+  /* Borders */
+  --color-border-subtle: #26352C;
+  --color-border-default: #32463A;
+  --color-border-strong: #405847;
+  --color-border-accent: #4F8E70;
+
+  /* Text */
+  --color-text-primary: #EFF7F2;
+  --color-text-secondary: #A5B7AC;
+  --color-text-tertiary: #7F9187;
+  --color-text-quiet: #67786F;
+  --color-text-inverse: #111613;
+  --color-text-on-accent: #0F1713;
+  --color-text-on-soft-accent: #DDF7E9;
+
+  /* Accent */
+  --color-accent-primary: #53B487;
+  --color-accent-primary-hover: #69C598;
+  --color-accent-primary-active: #84D8AE;
+  --color-accent-secondary: #9AE7C7;
+  --color-accent-secondary-hover: #B2F0D5;
+  --color-accent-secondary-active: #C7F6E0;
+  --color-accent-soft: #294235;
+  --color-accent-soft-hover: #31503F;
+
+  /* Semantic */
+  --color-semantic-success: #45C787;
+  --color-semantic-success-soft: #1E3A2C;
+  --color-semantic-warning: #E7B04D;
+  --color-semantic-warning-soft: #3E3117;
+  --color-semantic-error: #F07A84;
+  --color-semantic-error-soft: #3D2024;
+  --color-semantic-info: #64B6E8;
+  --color-semantic-info-soft: #183444;
+
+  /* Field */
+  --color-field-fill: #202D25;
+  --color-field-editable: #23372B;
+  --color-field-focus: #294235;
+  --color-field-invalid: #3D2024;
+  --color-field-warning: #3E3117;
+
+  /* Status */
+  --color-status-ready: #45C787;
+  --color-status-in-progress: #64B6E8;
+  --color-status-paused: #7F9187;
+  --color-status-blocked: #F07A84;
+  --color-status-review: #53B487;
+  --color-status-draft: #7DA38F;
+
+  /* Comment */
+  --color-comment-marker: #53B487;
+  --color-comment-marker-hover: #69C598;
+  --color-comment-thread-bg: #1A2A22;
+
+  /* Change */
+  --color-change-insertion: #1E3A2C;
+  --color-change-deletion: #3D2024;
+  --color-change-comment: #21342A;
+  --color-change-selection: #294235;
+
+  /* Chart — categorical */
+  --color-chart-categorical-1: #53B487;
+  --color-chart-categorical-2: #9AE7C7;
+  --color-chart-categorical-3: #64B6E8;
+  --color-chart-categorical-4: #E7B04D;
+  --color-chart-categorical-5: #A996FF;
+  --color-chart-categorical-6: #F07A84;
+  --color-chart-categorical-7: #7DA38F;
+  --color-chart-categorical-8: #355746;
+
+  /* Chart — sequential */
+  --color-chart-sequential-1: #16211B;
+  --color-chart-sequential-2: #1D2E25;
+  --color-chart-sequential-3: #274234;
+  --color-chart-sequential-4: #35654F;
+  --color-chart-sequential-5: #53B487;
+  --color-chart-sequential-6: #9AE7C7;
+
+  /* Chart — diverging */
+  --color-chart-diverging-neg-strong: #F07A84;
+  --color-chart-diverging-neg: #C76069;
+  --color-chart-diverging-neutral: #2A3530;
+  --color-chart-diverging-pos: #69C598;
+  --color-chart-diverging-pos-strong: #9AE7C7;
+
+  /* Scope tints (§3.7.2) */
+  --color-scope-tint-blocked: #3D2024;
+  --color-scope-tint-in-scope: #274234;
+  --color-scope-tint-suggest: #3E3117;
+  --color-scope-tint-comment: #1A2A22;
+  --color-scope-tint-scheduled: #183444;
+  --color-scope-tint-proposed: #21342A;
+
+  /* Shadows */
+  --shadow-soft: 0 8px 24px rgba(0, 0, 0, 0.28);
+  --shadow-float: 0 16px 40px rgba(0, 0, 0, 0.4);
+  --shadow-focus: 0 0 0 3px rgba(154, 231, 199, 0.22);
+}
+
+/*
+ * Reduced-motion contract (designsystem §4.6 / §7.3).
+ * Collapses every motion token so any transition consuming `var(--motion-*)`
+ * becomes functionally instant. Components MUST read these tokens — never
+ * hardcode a numeric duration.
+ */
+@media (prefers-reduced-motion: reduce) {
+  :root {
+    --motion-fast: 1ms;
+    --motion-default: 1ms;
+    --motion-slow: 1ms;
+  }
+}
+
+/*
+ * Density scale (designsystem §4.2 / Lane 6b.U5 consumer wiring).
+ *
+ * Components multiply spacing by `--space-density-multiplier`.
+ * Standard (1.0) is the default; compact (0.85) and comfortable (1.15)
+ * are opt-in via `data-density` on the root element.
+ * The hook `use-density.ts` reads and writes this attribute.
+ */
+:root {
+  --space-density-multiplier: 1;
+}
+:root[data-density="compact"] {
+  --space-density-multiplier: 0.85;
+}
+:root[data-density="standard"] {
+  --space-density-multiplier: 1;
+}
+:root[data-density="comfortable"] {
+  --space-density-multiplier: 1.15;
+}
+
+/*
+ * Back-compat aliases (temporary — remove after full consumer sweep).
+ *
+ * These bind pre-6a names to their post-6a equivalents so that the
+ * existing @theme {} block in editor-theme.css and already-shipped
+ * component markup continue to resolve during the phased migration.
+ */
+:root {
+  /* Legacy accent seed (was teal) → forest-green primary family */
+  --color-accent: var(--color-accent-primary);
+  /* Legacy single-name semantic tokens → canonical semantic family */
+  --color-danger: var(--color-semantic-error);
+  --color-danger-soft: var(--color-semantic-error-soft);
+  --color-warning: var(--color-semantic-warning);
+  --color-warning-soft: var(--color-semantic-warning-soft);
+  --color-success: var(--color-semantic-success);
+  --color-success-soft: var(--color-semantic-success-soft);
+  --color-info: var(--color-semantic-info);
+  --color-info-soft: var(--color-semantic-info-soft);
+  /* Legacy review markup names → change family */
+  --color-insert: var(--color-accent-primary);
+  --color-insert-soft: var(--color-change-insertion);
+  --color-delete: var(--color-semantic-error);
+  --color-delete-soft: var(--color-change-deletion);
+  --color-comment: var(--color-comment-marker);
+  --color-comment-soft: var(--color-change-comment);
+  --color-comment-strong: var(--color-comment-marker-hover);
+  /* Legacy L8 Phase A radius names → §4.3 scale */
+  --radius-panel: var(--radius-md);
+  --radius-card: var(--radius-sm);
+  --radius-control: var(--radius-sm);
+  --radius-page: 2px;
+}

package/src/ui-tailwind/theme/tokens.ts

@@ -0,0 +1,313 @@
+/**
+ * @beyondwork/docx-react-component — design-token manifest
+ *
+ * Single TypeScript surface that consumers import. Mirrors
+ * `docs/reference/designsystem.md` §3.1 (product token names) + §3.3/§3.4
+ * (values). Every key here has a CSS variable alias in
+ * `./tokens.css` — the pair is enforced by
+ * `test/ui-tailwind/token-coverage.test.ts`.
+ *
+ * Values below are the LIGHT-MODE hex values only. CSS variables own the
+ * light/dark fork; runtime reads resolve via `getComputedStyle`. Pure hex
+ * strings remain accessible for design-tool export, snapshot tests, and
+ * one-off cases where a consumer cannot enter the CSS cascade.
+ */
+
+export const BRAND_TOKENS = {
+  color: {
+    bg: {
+      app: "#F4F7F5",
+      chrome: "#FAFCFA",
+      sidebar: "#F1F6F2",
+      canvas: "#FFFFFF",
+      elevated: "#FFFFFF",
+      hover: "#EAF6EF",
+      selected: "#E2F2E8",
+      muted: "#F7FAF8",
+      overlay: "rgba(21, 26, 23, 0.08)",
+    },
+    border: {
+      subtle: "#E2EAE4",
+      default: "#D3DED6",
+      strong: "#BECDBF",
+      accent: "#8FC9AD",
+    },
+    text: {
+      primary: "#151A17",
+      secondary: "#5E6D63",
+      tertiary: "#8A978F",
+      quiet: "#A4AEA8",
+      inverse: "#F7FAF8",
+      onAccent: "#F7FAF8",
+      onSoftAccent: "#18563F",
+    },
+    accent: {
+      primary: "#1F6B4F",
+      primaryHover: "#18563F",
+      primaryActive: "#124432",
+      secondary: "#72D6AE",
+      secondaryHover: "#5FC79C",
+      secondaryActive: "#49B785",
+      soft: "#DDF1E4",
+      softHover: "#CEEAD8",
+    },
+    semantic: {
+      success: "#1F8A5B",
+      successSoft: "#DDF3E8",
+      warning: "#D58B1E",
+      warningSoft: "#FBEFD8",
+      error: "#D95C67",
+      errorSoft: "#FBE3E6",
+      info: "#2F8FCE",
+      infoSoft: "#DCEFFC",
+    },
+    field: {
+      fill: "#F6FAF7",
+      editable: "#EEF8F0",
+      focus: "#DDF1E4",
+      invalid: "#FBE3E6",
+      warning: "#FBEFD8",
+    },
+    status: {
+      ready: "#1F8A5B",
+      inProgress: "#2F8FCE",
+      paused: "#8A978F",
+      blocked: "#D95C67",
+      review: "#1F6B4F",
+      draft: "#72907E",
+    },
+    comment: {
+      marker: "#1F6B4F",
+      markerHover: "#18563F",
+      threadBg: "#F3FAF6",
+    },
+    change: {
+      insertion: "#DDF3E8",
+      deletion: "#FBE3E6",
+      comment: "#E8F4EC",
+      selection: "#DDF1E4",
+    },
+    scopeTint: {
+      blocked: "#FBE3E6",
+      inScope: "#E2F2E8",
+      suggest: "#FBEFD8",
+      comment: "#F3FAF6",
+      scheduled: "#DCEFFC",
+      proposed: "#EAF6EF",
+    },
+    chart: {
+      categorical: {
+        "1": "#1F6B4F",
+        "2": "#72D6AE",
+        "3": "#2F8FCE",
+        "4": "#D58B1E",
+        "5": "#7A6AF0",
+        "6": "#D95C67",
+        "7": "#5E8E7A",
+        "8": "#A7D9C1",
+      },
+      sequential: {
+        "1": "#EAF6EF",
+        "2": "#D4EEDD",
+        "3": "#B4DFC8",
+        "4": "#8FC9AD",
+        "5": "#5FA985",
+        "6": "#1F6B4F",
+      },
+      diverging: {
+        negStrong: "#C94B57",
+        neg: "#E9979F",
+        neutral: "#E9EFEA",
+        pos: "#97D1B3",
+        posStrong: "#1F6B4F",
+      },
+    },
+  },
+  shadow: {
+    soft: "0 6px 20px rgba(21, 26, 23, 0.06)",
+    float: "0 12px 32px rgba(21, 26, 23, 0.12)",
+    focus: "0 0 0 3px rgba(114, 214, 174, 0.28)",
+  },
+  radius: {
+    sm: "10px",
+    md: "12px",
+    lg: "14px",
+    xl: "16px",
+    pill: "9999px",
+  },
+  space: {
+    "1": "4px",
+    "2": "8px",
+    "3": "12px",
+    "4": "16px",
+    "5": "20px",
+    "6": "24px",
+    "8": "32px",
+    "10": "40px",
+    "12": "48px",
+    "16": "64px",
+  },
+  motion: {
+    fast: "120ms",
+    default: "160ms",
+    slow: "220ms",
+  },
+} as const;
+
+/**
+ * Dotted path tuple type used by the coverage test to enumerate every
+ * leaf of `BRAND_TOKENS`. Mirrors the `color.accent.primary` / `shadow.soft`
+ * form used throughout the spec.
+ */
+export type BrandTokens = typeof BRAND_TOKENS;
+export type BrandTokenPath =
+  | `color.bg.${keyof BrandTokens["color"]["bg"]}`
+  | `color.border.${keyof BrandTokens["color"]["border"]}`
+  | `color.text.${keyof BrandTokens["color"]["text"]}`
+  | `color.accent.${keyof BrandTokens["color"]["accent"]}`
+  | `color.semantic.${keyof BrandTokens["color"]["semantic"]}`
+  | `color.field.${keyof BrandTokens["color"]["field"]}`
+  | `color.status.${keyof BrandTokens["color"]["status"]}`
+  | `color.comment.${keyof BrandTokens["color"]["comment"]}`
+  | `color.change.${keyof BrandTokens["color"]["change"]}`
+  | `color.scopeTint.${keyof BrandTokens["color"]["scopeTint"]}`
+  | `color.chart.categorical.${keyof BrandTokens["color"]["chart"]["categorical"]}`
+  | `color.chart.sequential.${keyof BrandTokens["color"]["chart"]["sequential"]}`
+  | `color.chart.diverging.${keyof BrandTokens["color"]["chart"]["diverging"]}`
+  | `shadow.${keyof BrandTokens["shadow"]}`
+  | `radius.${keyof BrandTokens["radius"]}`
+  | `space.${keyof BrandTokens["space"]}`
+  | `motion.${keyof BrandTokens["motion"]}`;
+
+/**
+ * Converts a dotted product-token path into its CSS variable name.
+ *   productPathToCssVar("color.accent.primary") === "--color-accent-primary"
+ *   productPathToCssVar("color.chart.categorical.1") === "--color-chart-categorical-1"
+ *   productPathToCssVar("color.text.onAccent") === "--color-text-on-accent"
+ */
+export function productPathToCssVar(path: string): string {
+  const kebab = path
+    .split(".")
+    .join("-")
+    .replace(/([a-z])([A-Z])/g, "$1-$2")
+    .toLowerCase();
+  return `--${kebab}`;
+}
+
+/**
+ * Enumerates every leaf path in `BRAND_TOKENS`.
+ */
+export function enumerateBrandTokenPaths(): BrandTokenPath[] {
+  const out: string[] = [];
+  const walk = (node: unknown, prefix: string): void => {
+    if (node === null || typeof node !== "object") return;
+    for (const [key, value] of Object.entries(node as Record<string, unknown>)) {
+      const next = prefix === "" ? key : `${prefix}.${key}`;
+      if (typeof value === "string") out.push(next);
+      else walk(value, next);
+    }
+  };
+  walk(BRAND_TOKENS, "");
+  return out as BrandTokenPath[];
+}
+
+/**
+ * Host override contract (designsystem §8.5 / §9).
+ *
+ * Hosts MAY override these token families to match their brand / workspace.
+ */
+export const HOST_OVERRIDABLE_TOKENS = [
+  "color.accent.primary",
+  "color.accent.primaryHover",
+  "color.accent.primaryActive",
+  "color.accent.secondary",
+  "color.accent.secondaryHover",
+  "color.accent.secondaryActive",
+  "color.accent.soft",
+  "color.accent.softHover",
+  "color.bg.app",
+  "radius.sm",
+  "radius.md",
+  "radius.lg",
+  "radius.xl",
+  "radius.pill",
+  "motion.fast",
+  "motion.default",
+  "motion.slow",
+] as const satisfies readonly BrandTokenPath[];
+
+/**
+ * Hosts MUST NOT override these — semantic legibility, review markup,
+ * comment marker, canvas, and accessibility contract.
+ */
+export const HOST_LOCKED_TOKENS = [
+  "color.semantic.success",
+  "color.semantic.successSoft",
+  "color.semantic.warning",
+  "color.semantic.warningSoft",
+  "color.semantic.error",
+  "color.semantic.errorSoft",
+  "color.semantic.info",
+  "color.semantic.infoSoft",
+  "color.change.insertion",
+  "color.change.deletion",
+  "color.change.comment",
+  "color.change.selection",
+  "color.comment.marker",
+  "color.comment.markerHover",
+  "color.comment.threadBg",
+  "color.bg.canvas",
+  "shadow.focus",
+] as const satisfies readonly BrandTokenPath[];
+
+export type HostOverridableToken = (typeof HOST_OVERRIDABLE_TOKENS)[number];
+export type HostLockedToken = (typeof HOST_LOCKED_TOKENS)[number];
+
+/** Returns true if `path` is in the locked set (must not be overridden by hosts). */
+export function isTokenPathLocked(path: string): boolean {
+  return (HOST_LOCKED_TOKENS as readonly string[]).includes(path);
+}
+
+/**
+ * Dev-mode guard. Subscribes to attribute/style mutations on `document.documentElement`
+ * and emits `console.warn` if a host overrides a locked CSS variable.
+ *
+ * No-op in production (`process.env.NODE_ENV === "production"`) and in
+ * non-browser environments (SSR, test runners without DOM).
+ *
+ * Returns a teardown function. Call it to disconnect the observer.
+ */
+export function devGuardLockedTokens(
+  root: HTMLElement = typeof document !== "undefined"
+    ? document.documentElement
+    : (null as unknown as HTMLElement),
+): () => void {
+  if (
+    typeof document === "undefined" ||
+    root === null ||
+    (typeof (globalThis as Record<string, unknown>)["__WRE_DEV__"] !== "undefined" &&
+      !(globalThis as Record<string, unknown>)["__WRE_DEV__"])
+  ) {
+    return () => {};
+  }
+
+  const lockedVars = new Set(
+    (HOST_LOCKED_TOKENS as readonly string[]).map((p) => productPathToCssVar(p)),
+  );
+
+  const observer = new MutationObserver(() => {
+    const style = root.getAttribute("style") ?? "";
+    for (const v of lockedVars) {
+      if (style.includes(v)) {
+        console.warn(
+          `[docx-react-component] Host override of locked token "${v}" detected. ` +
+          `Overriding locked tokens may break review-workspace legibility contracts (§9.2). ` +
+          `See docs/reference/designsystem.md §9.`,
+        );
+      }
+    }
+  });
+
+  observer.observe(root, { attributes: true, attributeFilter: ["style"] });
+  return () => observer.disconnect();
+}