@sesamehr/react-design-system 3.3.1 → 3.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sesamehr/react-design-system",
-  "version": "3.3.1",
+  "version": "3.4.1",
   "description": "Sesame HR React design system — components and design tokens",
   "license": "MIT",
   "type": "module",
@@ -14,6 +14,7 @@
       "require": "./dist/react-design-system.umd.cjs"
     },
     "./style.css": "./dist/react-design-system.css",
+    "./preflight.css": "./dist/preflight.css",
     "./assets/styles/mainTheme.css": "./src/assets/styles/mainTheme.css",
     "./lib/utils": {
       "types": "./dist/lib/utils.d.ts",
@@ -56,8 +57,9 @@
     "@radix-ui/react-slot": "^1.2.3",
     "@radix-ui/react-switch": "^1.2.5",
     "@radix-ui/react-tabs": "^1.1.12",
+    "@radix-ui/react-toast": "^1.2.24",
     "@radix-ui/react-tooltip": "^1.2.7",
-    "@sesame/orxata-icons": "1.8.0",
+    "@sesame/orxata-icons": "1.8.1",
     "@tailwindcss/vite": "^4.1.13",
     "@tanstack/react-table": "^8.21.2",
     "@tanstack/react-virtual": "^3.14.13",

package/src/assets/styles/theme-v2.css

@@ -6,7 +6,7 @@
  * Aligns with Figma: 3. Mode → 2. Theme → 1. TailwindCSS
  *
  * DS EXTENSIONS (pending design approval):
- * - success, neutral-*, font-*, border-*, bg-*
+ * - success, neutral-*, border-*, bg-*
  *
  * Dark mode: .dark class on <html>
  */
@@ -16,13 +16,19 @@
    =========================================== */
 
 :root {
-  /* Font */
-  --font-primary: var(--color-indigo-950);
-  --font-secondary: var(--color-slate-500);
-  --font-tertiary: var(--color-slate-400);
-  --font-error: var(--color-red-600);
-  --font-success: var(--color-green-600);
-  --font-warning: var(--color-amber-500);
+  /* No `font-*` family, for the same reason v3 has none: every one of them was
+     a second name for a semantic declared in this same file. `--font-primary`
+     and `--foreground` are both indigo-950 here (white in dark),
+     `--font-secondary` and `--muted-foreground` both slate-500 (slate-300),
+     and the feedback three are `--error` / `--success` / `--warning`. The
+     values below are untouched; only the aliases are gone, so nothing that
+     reactivates this file loses a colour — `text-foreground` and
+     `text-muted-foreground` resolve here exactly as they do under v3.
+
+     `--font-tertiary` (slate-400) is the one with no equivalent, in v2 as in
+     v3. Its call sites read `--muted-foreground` now, which in this file's
+     dark block is slate-300 — a step lighter rather than darker. Academic
+     while `mainTheme.css` imports v3 and nothing imports this. */
 
   /* Border */
   --border-default: var(--color-slate-200);
@@ -65,14 +71,6 @@
 }
 
 .dark {
-  /* Font */
-  --font-primary: var(--color-white);
-  --font-secondary: var(--color-slate-300);
-  --font-tertiary: var(--color-slate-400);
-  --font-error: var(--color-red-400);
-  --font-success: var(--color-green-600);
-  --font-warning: var(--color-amber-500);
-
   /* Border */
   --border-default: var(--color-slate-700);
   --border-hover: var(--color-indigo-400);
@@ -192,12 +190,6 @@
 /* Expose tokens to Tailwind */
 @theme inline {
   /* DS tokens */
-  --color-font-primary: var(--font-primary);
-  --color-font-secondary: var(--font-secondary);
-  --color-font-tertiary: var(--font-tertiary);
-  --color-font-error: var(--font-error);
-  --color-font-success: var(--font-success);
-  --color-font-warning: var(--font-warning);
   --color-border-default: var(--border-default);
   --color-border-hover: var(--border-hover);
   --color-bg-base: var(--bg-base);

package/src/assets/styles/theme-v3.css

@@ -20,18 +20,21 @@
  */
 
 :root {
-  --font-primary: var(--color-zinc-900);
-  --font-secondary: var(--color-zinc-500);
-  --font-tertiary: var(--color-zinc-400);
-  --font-error: var(--color-red-500);
-  --font-success: var(--color-green-500);
-  --font-warning: var(--color-amber-500);
-  --font-info: var(--color-blue-500);
-
   --border-default: var(--color-zinc-200);
   --border-hover: var(--color-brand-300);
 
-  --success: var(--color-green-500);
+  /* Not the 500 every other semantic colour takes, and `--success-500` sitting
+     just below holding green-500 makes that look like a slip. It is not: the
+     v3 board binds `success` to green-700 and its hover to green-800, because
+     white text on green-500 does not clear contrast on a filled button. The
+     `-100/-300/-500` beneath are a tint ramp with the shade in the name, and
+     they are a different thing from the semantic colour.
+
+     Same shape for `--error`, which is red-600 rather than red-500, and for
+     `--brand-hover`, which *darkens* to brand-600 — it used to mix towards
+     white, which is the opposite of what every hover on that board does. */
+  --success: var(--color-green-700);
+  --success-hover: var(--color-green-800);
   --success-foreground: var(--color-white);
   --success-100: var(--color-green-100);
   --success-300: var(--color-green-300);
@@ -55,9 +58,24 @@
   --neutral-950: var(--color-zinc-950);
 
   --brand: var(--color-brand-500);
-  --brand-hover: color-mix(in srgb, var(--color-brand-500) 90%, white);
+  --brand-hover: var(--color-brand-600);
+  --brand-active: var(--color-brand-700);
   --brand-foreground: var(--color-white);
 
+  /* A brand *surface*, not a brand fill: the 100 tint carrying the 700 of the
+     same hue, which is what clears 4.5:1 on it. Figma's `brand-subtle`
+     description names Button's outline and ghost hover, and the board binds the
+     family on Tag, Stepper, Mention and IconPicker too.
+
+     `-active` is the pressed/hover step on such a surface and `-border` the 1px
+     line around one. Both are brand-200 today, and they stay two names because
+     the board binds them to two different properties — repainting the line must
+     not drag the pressed fill with it. */
+  --brand-subtle: var(--color-brand-100);
+  --brand-subtle-foreground: var(--color-brand-700);
+  --brand-subtle-border: var(--color-brand-200);
+  --brand-subtle-active: var(--color-brand-200);
+
   --background-custom: #f5f5f7;
   --background-custom-gradient: #e0e7ee;
 
@@ -70,6 +88,29 @@
   --background: var(--color-white);
   --foreground: var(--color-zinc-900);
 
+  /* There is no `font-*` colour family here, and that is the answer rather
+     than an omission. Figma v3 carries 434 colour variables across 14
+     collections and not one of them is a font colour: text colour comes from
+     the same semantic as everything else that means it. `--font-primary` was
+     this file's second name for `--foreground`, `--font-secondary` for
+     `--muted-foreground`, and `--font-error` / `--font-success` /
+     `--font-warning` / `--font-info` forwarded to `--error` / `--success` /
+     `--warning` / `--info` — so message text could never drift from the
+     control border that shares its meaning, which is the only thing the
+     aliases bought.
+
+     `--font-tertiary` was the one with no counterpart at all. Figma deleted
+     the concept, so placeholder text, weekday headers and the scrollbar thumb
+     read `--muted-foreground` now: zinc-500 where they used to be zinc-400.
+
+     Three roles are easy to confuse, so to say which is which:
+     `--muted-foreground` is grey *text on the page background*, `--success` is
+     a green *fill*, and `--success-foreground` is white text sitting *on* that
+     fill. A green message under a field is `text-success`; a filled success
+     button is `bg-success text-success-foreground`.
+
+     `theme-v3.test.ts` fails if any of the seven comes back. */
+
   --card: var(--color-white);
   --card-foreground: var(--color-zinc-900);
 
@@ -80,6 +121,7 @@
   --primary-foreground: var(--color-white);
 
   --secondary: var(--color-zinc-100);
+  --secondary-hover: var(--color-zinc-200);
   --secondary-foreground: var(--color-zinc-900);
 
   --muted: var(--color-zinc-200);
@@ -88,10 +130,26 @@
   --accent: var(--color-zinc-100);
   --accent-foreground: var(--color-zinc-900);
 
-  --success: var(--color-green-500);
+  --success: var(--color-green-700);
+  --success-hover: var(--color-green-800);
   --success-foreground: var(--color-white);
+  /* A semantic colour used as a *surface* instead of as a fill behind white
+     text: the 100 tint for the background, the 700 of the same hue for the
+     text and the icon sitting on it, which is what clears 4.5:1 there. The v3
+     board names the pair `*-subtle` / `*-subtle-foreground` and binds it on
+     Alert. `muted` already had this shape under its plain name — `--muted` is
+     the tint and `--muted-foreground` the text on it — so there is no
+     `--muted-subtle` to add. */
+  --success-subtle: var(--color-green-100);
+  --success-subtle-foreground: var(--color-green-700);
   --warning: var(--color-amber-500);
-  --warning-foreground: var(--color-white);
+  /* Dark on amber, which looks inverted next to every other `*-foreground`
+     here, and is the only pairing that passes: white on amber-500 is 2.1:1,
+     zinc-950 on it is 9.3:1. Figma binds `warning-foreground` to zinc/950 in
+     both modes. */
+  --warning-foreground: var(--color-zinc-950);
+  --warning-subtle: var(--color-amber-100);
+  --warning-subtle-foreground: var(--color-amber-700);
   /* The one semantic name for this red. Figma's Primitive collection calls it
      `error`, so the code does too. There used to be a `--destructive` beside it
      holding the identical value — two names for one colour, which means two
@@ -99,16 +157,81 @@
      red. The *component* variant stays `destructive` (Button, Badge and
      StatusBadge), which is also what Figma names that style: the action is
      destructive, the colour is error. */
-  --error: var(--color-red-500);
+  --error: var(--color-red-600);
+  --error-hover: var(--color-red-700);
   --error-foreground: var(--color-white);
-  --info: var(--color-blue-500);
+  --error-subtle: var(--color-red-100);
+  --error-subtle-foreground: var(--color-red-700);
+  /* blue-600, not the 500 most semantic colours take — same reason `--success`
+     is green-700. `--info-foreground` is white, and white on blue-500 reaches
+     only 3.8:1; on blue-600 it is 5.2:1. Figma binds `info` to blue/600. */
+  --info: var(--color-blue-600);
   --info-foreground: var(--color-white);
+  --info-subtle: var(--color-blue-100);
+  --info-subtle-foreground: var(--color-blue-700);
+
+  /* Content that is *yours*, or that matched what you typed — a mention of you,
+     a search hit. Figma binds it to the same amber-100 as `--warning-subtle`,
+     and it is deliberately a separate name rather than an alias of it: one says
+     "look, this is about you" and the other says "careful". Re-pointing either
+     must not drag the other along. */
+  --highlight: var(--color-amber-100);
+  --highlight-hover: var(--color-amber-200);
+  --highlight-foreground: var(--color-amber-900);
 
   --border: var(--color-zinc-200);
+  --border-strong: var(--color-zinc-300);
   --input: var(--color-zinc-200);
-  --ring: var(--color-zinc-200);
+  /* The focus colour for every control, and the only one: `Semantic-Colors`
+     binds `ring` to brand/500 and describes it as the focus-visible ring at
+     >= 3:1 contrast in both modes.
+
+     Two geometries read it, which is why a focused Button and a focused Input
+     look different without either being drift. The Accessibility board
+     (node 1600:30) sets out the split:
+
+       - Outside and separated -- the default, and what Button, Icon button,
+         Checkbox, RadioButton and Switch draw:
+         `0 0 0 2px var(--color-background), 0 0 0 4px var(--color-ring)`,
+         which `ring-2 ring-offset-2 ring-offset-background` emits. Drawn with
+         shadows, so the control is the same size focused as at rest.
+       - Inside -- for a control that already has a border to recolour, or whose
+         pieces sit flush: every text field, Select, Combobox, InputOtp. The
+         border turns `ring`. An outside ring on a column of form fields would
+         climb over its neighbours, which the same board warns about.
+
+     Destructive and success controls swap the colour for their own and keep the
+     geometry; `OxButton`'s destructive variant is the live case. */
+  --ring: var(--color-brand-500);
+  /* Figma's value (red-200), mirrored so the scale still matches the
+     collection -- but nothing in `src` reads it. The variable's own description
+     scopes it to Horchata, and the component boards paint an invalid control's
+     focus ring with `error` instead: the Textarea board's `Error (Focus)`
+     variant (node 1096:14751) binds that ring to `error`, not to this. Do not
+     re-point it to make a component work; reach for `--error`. */
   --ring-error: var(--color-red-200);
 
+  /* The glass behind a modal, a drawer or a sheet. Figma
+     `Semantic-Colors/overlay` (Overlay board, node 1845:51257) aliases
+     `base/alpha-60`, whose name counts the opacity of what shows *through* it
+     and whose value is therefore 0.4 — white at 40%, not 60. Paired with
+     `backdrop-blur-lg` at the call site, which is the 16px the component's
+     effect is bound to.
+
+     Figma's dark mode points the same semantic name at `base/black-alpha-40`,
+     black at 40%. There is no `.dark` block in v3 yet, so that value is
+     recorded here rather than declared, for whoever wires dark mode up. */
+  --overlay: var(--color-alpha-60);
+
+  /* The overlay a control tints itself with while it is hovered, focused or
+     pressed, drawn at 8–30% paint opacity over the colour underneath — the
+     scale Figma's `Semantic-Colors` prints in the variable's own description.
+     White is the only value it takes in either mode, because it is meant for
+     coloured surfaces: a brand-filled switch track, a chip, a filled button.
+     Over a near-white surface it has nothing to lighten, which is a reason to
+     pick a darker surface rather than a reason to tint it a different colour. */
+  --state-layer: var(--color-white);
+
   --chart-1: var(--color-brand-400);
   --chart-2: var(--color-brand-500);
   --chart-3: var(--color-brand-600);
@@ -123,7 +246,7 @@
   --category-3: var(--color-amber-500); /* amber */
   --category-4: var(--color-teal-500); /* teal */
   --category-5: var(--color-orange-500); /* orange */
-  --category-6: var(--color-zinc-500); /* zinc */
+  --category-6: var(--color-zinc-700); /* zinc */
   --category-7: var(--color-red-500); /* red */
   --category-8: var(--color-yellow-500); /* yellow */
   --category-9: var(--color-lime-500); /* lime */
@@ -154,13 +277,6 @@
    emission: without it Tailwind only declares the variables some generated
    utility happens to mention. Kept in step with the Vue package's copy. */
 @theme static inline {
-  --color-font-primary: var(--font-primary);
-  --color-font-secondary: var(--font-secondary);
-  --color-font-tertiary: var(--font-tertiary);
-  --color-font-error: var(--font-error);
-  --color-font-success: var(--font-success);
-  --color-font-warning: var(--font-warning);
-  --color-font-info: var(--font-info);
   --color-border-default: var(--border-default);
   --color-border-hover: var(--border-hover);
   --color-bg-base: var(--bg-base);
@@ -180,8 +296,16 @@
   --color-neutral-950: var(--neutral-950);
   --color-brand: var(--brand);
   --color-brand-hover: var(--brand-hover);
+  --color-brand-active: var(--brand-active);
   --color-brand-foreground: var(--brand-foreground);
+  --color-brand-subtle: var(--brand-subtle);
+  --color-brand-subtle-foreground: var(--brand-subtle-foreground);
+  --color-brand-subtle-border: var(--brand-subtle-border);
+  --color-brand-subtle-active: var(--brand-subtle-active);
   --color-success: var(--success);
+  --color-success-hover: var(--success-hover);
+  --color-success-subtle: var(--success-subtle);
+  --color-success-subtle-foreground: var(--success-subtle-foreground);
   --color-success-foreground: var(--success-foreground);
   --color-success-100: var(--success-100);
   --color-success-300: var(--success-300);
@@ -202,6 +326,7 @@
   --color-primary: var(--primary);
   --color-primary-foreground: var(--primary-foreground);
   --color-secondary: var(--secondary);
+  --color-secondary-hover: var(--secondary-hover);
   --color-secondary-foreground: var(--secondary-foreground);
   --color-muted: var(--muted);
   --color-muted-foreground: var(--muted-foreground);
@@ -209,14 +334,27 @@
   --color-accent-foreground: var(--accent-foreground);
   --color-warning: var(--warning);
   --color-warning-foreground: var(--warning-foreground);
+  --color-warning-subtle: var(--warning-subtle);
+  --color-warning-subtle-foreground: var(--warning-subtle-foreground);
   --color-error: var(--error);
+  --color-error-hover: var(--error-hover);
   --color-error-foreground: var(--error-foreground);
+  --color-error-subtle: var(--error-subtle);
+  --color-error-subtle-foreground: var(--error-subtle-foreground);
   --color-info: var(--info);
   --color-info-foreground: var(--info-foreground);
+  --color-info-subtle: var(--info-subtle);
+  --color-info-subtle-foreground: var(--info-subtle-foreground);
+  --color-highlight: var(--highlight);
+  --color-highlight-hover: var(--highlight-hover);
+  --color-highlight-foreground: var(--highlight-foreground);
   --color-border: var(--border);
+  --color-border-strong: var(--border-strong);
   --color-input: var(--input);
   --color-ring: var(--ring);
   --color-ring-error: var(--ring-error);
+  --color-state-layer: var(--state-layer);
+  --color-overlay: var(--overlay);
   --color-chart-1: var(--chart-1);
   --color-chart-2: var(--chart-2);
   --color-chart-3: var(--chart-3);

package/src/assets/styles/theme-v3.test.ts

@@ -0,0 +1,242 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+
+/**
+ * jsdom and happy-dom apply no CSS, so a computed colour here is always empty
+ * and a token that resolves to nothing looks exactly like one that resolves.
+ * The stylesheet text is the only thing that can be pinned, so it is what these
+ * assert — the same approach as `internal/Listbox/ListboxItem.test.tsx`.
+ *
+ * Two halves have to hold together for a token to be usable at all, and each
+ * fails silently without the other:
+ *
+ * - the `:root` declaration, which gives it a value;
+ * - the `@theme static inline` entry, which is what makes Tailwind emit a
+ *   `--color-*` custom property and a `bg-*` / `text-*` / `border-*` utility
+ *   for it. Declare only the first and `@apply bg-brand-subtle` is an unknown
+ *   utility; expose only the second and the utility paints with nothing.
+ */
+const here = dirname(fileURLToPath(import.meta.url));
+const theme = readFileSync(join(here, 'theme-v3.css'), 'utf8');
+const src = join(here, '..', '..');
+
+/** `--name: value;`, whitespace flattened, comments irrelevant. */
+const declares = (name: string, value: string) =>
+  new RegExp(
+    `^\\s*${name}:\\s*${value.replace(/[()\-*]/g, '\\$&')};`,
+    'm'
+  ).test(theme);
+
+/** The `@theme static inline` block, which is the last one in the file. */
+const themeBlock = theme.slice(theme.indexOf('@theme static inline'));
+
+/** `--brand-subtle` is exposed as `--color-brand-subtle`, so drop one dash. */
+const exposes = (name: string) =>
+  themeBlock.includes(`--color${name.slice(1)}: var(${name});`);
+
+describe('theme-v3 brand-subtle', () => {
+  const family = {
+    '--brand-subtle': 'var(--color-brand-100)',
+    '--brand-subtle-foreground': 'var(--color-brand-700)',
+    '--brand-subtle-border': 'var(--color-brand-200)',
+    '--brand-subtle-active': 'var(--color-brand-200)',
+  };
+
+  it.each(Object.entries(family))(
+    'should declare %s as the Figma binding %s',
+    (name, value) => {
+      expect(declares(name, value)).toBe(true);
+    }
+  );
+
+  it.each(Object.keys(family))('should expose %s as a utility', name => {
+    expect(exposes(name)).toBe(true);
+  });
+});
+
+describe('theme-v3 highlight', () => {
+  const family = {
+    '--highlight': 'var(--color-amber-100)',
+    '--highlight-hover': 'var(--color-amber-200)',
+    '--highlight-foreground': 'var(--color-amber-900)',
+  };
+
+  it.each(Object.entries(family))(
+    'should declare %s as the Figma binding %s',
+    (name, value) => {
+      expect(declares(name, value)).toBe(true);
+    }
+  );
+
+  it.each(Object.keys(family))('should expose %s as a utility', name => {
+    expect(exposes(name)).toBe(true);
+  });
+
+  /**
+   * `--highlight` and `--warning-subtle` are both amber-100 in the v3 file, so
+   * one looks like a redundant copy of the other. They are not: "this is about
+   * you" and "careful" are different questions and Figma names them
+   * separately, so each has to keep its own declaration rather than alias the
+   * other — otherwise repainting one silently repaints the other.
+   */
+  it('should keep --highlight independent of --warning-subtle', () => {
+    expect(declares('--warning-subtle', 'var(--color-amber-100)')).toBe(true);
+    expect(theme).not.toContain('--highlight: var(--warning-subtle)');
+    expect(theme).not.toContain('--warning-subtle: var(--highlight)');
+  });
+});
+
+/**
+ * Every one of these reached for a ramp step directly and carried a comment
+ * naming the token it was standing in for. The tokens exist now, so the comment
+ * is gone and the call site has to be the semantic name — and must not quietly
+ * drift back, which is the only thing a reader of this file would not notice.
+ *
+ * `Button` was on this list and is not any more: `Outline` and `Ghost` are
+ * neutral now, so it reaches for no brand token at all and there is no call site
+ * left to pin. Its own suite asserts `brand-subtle` appears nowhere in the file,
+ * which is the stronger version of the same check.
+ */
+describe('theme-v3 semantic call sites', () => {
+  const callSites: [string, string[], string[]][] = [
+    [
+      'Display/Tag/Tag.module.css',
+      ['var(--color-brand-subtle)'],
+      ['var(--color-brand-100)'],
+    ],
+    [
+      'Navigation/Stepper/Stepper.module.css',
+      ['bg-brand-subtle'],
+      ['bg-brand-100'],
+    ],
+    [
+      'Navigation/Stepper/StepperItem.module.css',
+      ['bg-brand-subtle', 'text-brand-subtle-foreground'],
+      ['bg-brand-100', 'text-brand-700'],
+    ],
+    [
+      'Navigation/Stepper/StepperSubsteps.module.css',
+      ['border-brand-subtle-border'],
+      ['border-brand-200'],
+    ],
+    [
+      'Display/Mention/Mention.module.css',
+      ['bg-brand-subtle', 'bg-highlight', 'text-highlight-foreground'],
+      ['bg-amber-100', 'text-amber-900', 'var(--color-amber-200)'],
+    ],
+    [
+      'Forms/Inputs/IconPicker/IconPickerItem.module.css',
+      ['bg-brand-subtle'],
+      ['bg-brand-100'],
+    ],
+  ];
+
+  it.each(callSites)('should use the token in %s', (file, wanted, retired) => {
+    const css = readFileSync(join(src, file), 'utf8');
+    for (const token of wanted) expect(css).toContain(token);
+    for (const stale of retired) expect(css).not.toContain(stale);
+  });
+});
+
+/**
+ * The `font-*` colour family is retired. Six of the seven were a second name
+ * for a semantic this file already declares — `--font-primary` for
+ * `--foreground`, `--font-secondary` for `--muted-foreground`, and the
+ * feedback four forwarding to `--error` / `--success` / `--warning` /
+ * `--info` — and `--font-tertiary` had no Figma counterpart at all, so its
+ * call sites took `--muted-foreground` and went one shade darker.
+ *
+ * Half of this is self-policing and half is not, which is why the two halves
+ * are asserted separately:
+ *
+ * - Taking a name out of `@theme static inline` makes `@apply text-font-primary`
+ *   an unknown utility, and the build says so. Putting the entry *back* is the
+ *   silent move: the utility starts resolving again, under a name Figma does
+ *   not have, and nothing else would complain.
+ * - A bare `:root` declaration with no `@theme` entry is invisible both ways —
+ *   no utility, no error, just a variable nobody reads.
+ */
+describe('theme-v3 retired font-* family', () => {
+  const retired = [
+    '--font-primary',
+    '--font-secondary',
+    '--font-tertiary',
+    '--font-error',
+    '--font-success',
+    '--font-warning',
+    '--font-info',
+  ];
+
+  it.each(retired)('should not declare %s', name => {
+    expect(declares(name, '[^;]+')).toBe(false);
+  });
+
+  it.each(retired)('should not expose %s as a utility', name => {
+    expect(themeBlock).not.toContain(`--color${name.slice(1)}:`);
+  });
+
+  /**
+   * `--font-sans`, `--font-mono` and `--font-weight-*` share the prefix and are
+   * Tailwind's own font-family and weight tokens. Nothing above should have
+   * taken them with it.
+   */
+  it('should keep the font-family tokens, which are a different family', () => {
+    expect(
+      theme.includes('--font-sans') || themeBlock.includes('--font-sans')
+    ).toBe(true);
+  });
+});
+
+/**
+ * One red, and `--error` is where it lives. Figma's `Semantic-Colors` binds
+ * `error` to red/600 and has no second red for the same meaning, so another
+ * name holding the same value could only ever be drift — `--destructive` was
+ * collapsed into this one for exactly that reason, and `--font-error` held
+ * red-500 against it until the whole `font-*` family was retired, which is why
+ * `OxFieldGroup` drew a message and a border in two different reds.
+ */
+describe('theme-v3 error family', () => {
+  it('should give the error family a single red', () => {
+    expect(declares('--error', 'var(--color-red-600)')).toBe(true);
+  });
+
+  it('should not reintroduce a second name holding the same red', () => {
+    expect(declares('--destructive', '[^;]+')).toBe(false);
+  });
+
+  /**
+   * Figma's value, mirrored for parity, and deliberately unread: the component
+   * boards paint an invalid control's focus ring with `error` instead. Pinned
+   * so re-pointing it looks like the change it is.
+   */
+  it('should keep ring-error at the value the collection holds', () => {
+    expect(declares('--ring-error', 'var(--color-red-200)')).toBe(true);
+  });
+});
+
+/**
+ * `--ring` is the focus colour for every control and the only one, which is
+ * what makes it the override a consumer re-points to restyle focus. A focus
+ * state spelled `brand` resolves to the same value today and stops tracking the
+ * moment that happens.
+ */
+describe('theme-v3 focus ring', () => {
+  it('should bind the focus ring to the brand colour', () => {
+    expect(declares('--ring', 'var(--color-brand-500)')).toBe(true);
+  });
+
+  it.each([
+    '--error',
+    '--error-hover',
+    '--error-foreground',
+    '--error-subtle',
+    '--error-subtle-foreground',
+    '--ring',
+    '--ring-error',
+  ])('should expose %s as a utility as well as declaring it', name => {
+    expect(declares(name, '[^;]+')).toBe(true);
+    expect(exposes(name)).toBe(true);
+  });
+});