npm - @terpjs/react-core - Versions diffs - 0.6.1 → 0.7.0 - Mend

@terpjs/react-core 0.6.1 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (23) hide show

package/README.md +12 -2
package/package.json +2 -2
package/src/AppShell.tsx +1 -1
package/src/HubPage.tsx +1 -1
package/src/LoadingState.tsx +1 -1
package/src/ModuleNav.tsx +1 -1
package/src/icons.tsx +24 -0
package/src/locale.tsx +3 -0
package/src/markers.test.ts +245 -0
package/src/raw.d.ts +15 -1
package/src/styles.ts +4 -4
package/src/theme.test.tsx +39 -0
package/src/theme.themes.test.ts +124 -0
package/src/theme.tsx +38 -11
package/src/tokens.guard.test.ts +3 -12
package/src/ui/Badge.tsx +8 -1
package/src/ui/Checkbox.tsx +1 -1
package/src/ui/Combobox.tsx +1 -1
package/src/ui/Radio.tsx +1 -1
package/src/ui/Switch.tsx +1 -1
package/src/ui/Tabs.tsx +2 -2
package/src/ui/Tooltip.tsx +1 -1
package/src/uiText.tsx +9 -0

package/README.md CHANGED Viewed

@@ -20,7 +20,17 @@ JSDoc, so your editor shows the same guidance inline. **Never deep-import** from
   or `useRealtimeChannel()` for typed SSE/WebSocket subscriptions. The hook mints a
   one-use connection ticket through the generated client; bearer tokens never enter URLs.
 - **Design tokens, not inline colours** — style with the CSS variables from
-  `@terpjs/contract` (`var(--color-*)`, `var(--space-*)`, `var(--font-*)`).
+  `@terpjs/contract` (`var(--color-*)`, `var(--space-*)`, `var(--font-*)`). The full list,
+  with each token's per-theme values and the foreground/background pairings the contrast gate
+  enforces, is published as `@terpjs/contract/tokens.manifest.json` — read it rather than
+  inferring names from the compiled sheet.
+- **The accent is two tokens, and mixing them up is a contrast bug.**
+  `--color-brand-primary` is the accent as a *filled surface*, and the only thing that may sit
+  on it is `--color-brand-primary-contrast`. `--color-fg-accent` is the accent as *ink or a
+  boundary* against one of the app's own surfaces — accent text, a selected-tab underline, a
+  focus ring, a checkbox's `accent-color`. One token cannot do both: in a dark theme the
+  surface use needs a value dark enough to hold a white label and the ink use needs one light
+  enough to read on a dark canvas, and there is no value satisfying both.
 - **User-facing text is `UiText`** — every text prop accepts a plain string or an
   `{id, message}` descriptor, so apps can localize via `UiTextProvider` without
   react-core taking an i18n dependency.
@@ -43,7 +53,7 @@ JSDoc, so your editor shows the same guidance inline. **Never deep-import** from
 | `LoginView` | The standard sign-in screen: username/password, plus optional SSO provider buttons via `ssoProviders` and a dev-only credential-fill button via `devCredentials` (gate it on `import.meta.env.DEV`). |
 | `useSso`, `parseSsoCallback`, `fetchSsoAuthorizationUrl`, `completeSsoCallback` | The SSO login seam (ADR 0058): `useSso().begin(provider)` opens an OIDC flow; `TerpProvider` completes the `/auth/callback/{provider}` redirect landing into a normal session on boot. `renderTerpApp({ ssoProviders })` wires the buttons in one line. |
 | `RequireAuth` | Renders children only with a session; pairs with the router so the app mounts only when signed in. |
-| `ThemeProvider`, `ThemeToggle`, `useTheme` | Light/dark/system theming: applies `data-theme` on `<html>` (the token stylesheet carries both palettes) and persists the choice. `renderTerpApp` mounts it for every app; the shell header uses an icon-only, token-themed `variant="inline"` menu. |
+| `ThemeProvider`, `ThemeToggle`, `useTheme` | Theming over the five shipped palettes — `light`, `dark`, `midnight`, `twilight`, `contrast` — plus `system` to follow the OS preference. Applies `data-theme` on `<html>` (the token stylesheet carries every palette) and persists the choice. `defaultTheme` is how an app ships on a named theme. `renderTerpApp` mounts it for every app; the shell header uses an icon-only, token-themed `variant="inline"` menu. |
 | `LocaleProvider`, `LanguageSwitcher`, `useLocale`, `LOCALE_EN`, `LOCALE_NL` | The language seam over `UiTextProvider`: per-locale string catalogs, a persisted active locale, and an icon-only, token-themed menu in the shell header once an app declares a second locale. English and Dutch catalogs ship complete; `renderTerpApp({ locales })` wires them. |
 | `UserMenu`, `userInitials` | The signed-in user's menu, pinned by `buildAppRouter` to the bottom of the sidebar: an initials avatar trigger opening the identity block, **Settings** (the built-in profile page) and sign-out. Collapses to the avatar in the icon rail. |
 | `ProfileView` | The built-in profile / settings page (`/profile`): the server-validated identity, theme + language preferences, and sign-out. |

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@terpjs/react-core",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "type": "module",
   "description": "Terp React stack core — typed @terpjs/contract client provider, auth session, capability gates, TanStack Router adapter, app shell, page archetypes, DataView and token-styled UI primitives. First frontend stack; see README.md for the component catalog.",
   "exports": {
@@ -13,7 +13,7 @@
   },
   "dependencies": {
     "@tanstack/react-router": "^1.170.16",
-    "@terpjs/contract": "^0.6.1"
+    "@terpjs/contract": "^0.7.0"
   },
   "peerDependencies": {
     "react": "^18.3.0 || ^19.0.0",

package/src/AppShell.tsx CHANGED Viewed

@@ -93,7 +93,7 @@ export const NAV_LINK_COLLAPSED_STYLE: CSSProperties = {
 /** Merged over {@link NAV_LINK_STYLE} on the active route's link. */
 export const NAV_LINK_ACTIVE_STYLE: CSSProperties = {
   background: "var(--color-brand-primary-soft)",
-  color: "var(--color-brand-primary)",
+  color: "var(--color-fg-accent)",
   fontWeight: "var(--font-weight-semibold)" as CSSProperties["fontWeight"],
 };

package/src/HubPage.tsx CHANGED Viewed

@@ -124,7 +124,7 @@ const iconTileStyle: CSSProperties = {
   flexShrink: 0,
   borderRadius: "var(--radius-md)",
   background: "var(--color-brand-primary-soft)",
-  color: "var(--color-brand-primary)",
+  color: "var(--color-fg-accent)",
 };
 const titleTextStyle: CSSProperties = {

package/src/LoadingState.tsx CHANGED Viewed

@@ -73,7 +73,7 @@ const wrapStyle: CSSProperties = {
   fontSize: "var(--font-size-sm)",
 };
-const spinnerColorStyle: CSSProperties = { color: "var(--color-brand-primary)" };
+const spinnerColorStyle: CSSProperties = { color: "var(--color-fg-accent)" };
 /**
  * Standard inline loading indicator: a spinner plus a short label, announced

package/src/ModuleNav.tsx CHANGED Viewed

@@ -41,7 +41,7 @@ const linkStyle: CSSProperties = {
 const activeLinkStyle: CSSProperties = {
   color: "var(--color-neutral-900)",
-  borderBottomColor: "var(--color-brand-primary)",
+  borderBottomColor: "var(--color-fg-accent)",
 };
 /**

package/src/icons.tsx CHANGED Viewed

@@ -77,6 +77,30 @@ export const ICON_GLYPHS: Record<string, ReactNode> = {
       <path d="M8 21h8M12 17v4" />
     </svg>
   ),
+  // The three glyphs below exist for the named themes. `moon` and `sun` were already
+  // taken by dark and light, and a theme picker where two entries share a glyph is a
+  // picker whose icons carry no information.
+  "moon-stars": (
+    <svg {...svgProps}>
+      <path d="M20.5 15.6A8 8 0 0 1 9.4 4.5 8.4 8.4 0 1 0 20.5 15.6Z" />
+      <path d="M17 3v3M15.5 4.5h3M20.5 8v2M19.5 9h2" />
+    </svg>
+  ),
+  sunset: (
+    <svg {...svgProps}>
+      <path d="M12 4v2M5.6 7.6l1.4 1.4M17 9l1.4-1.4M3 15h1.5M19.5 15H21" />
+      <path d="M8 15a4 4 0 0 1 8 0" />
+      <path d="M3 19h18" />
+    </svg>
+  ),
+  contrast: (
+    <svg {...svgProps}>
+      <circle cx="12" cy="12" r="9" />
+      {/* Filled half, so the glyph reads as contrast rather than as a plain circle.
+          Stroked shapes elsewhere use `currentColor`; so does this fill. */}
+      <path d="M12 3a9 9 0 0 0 0 18Z" fill="currentColor" stroke="none" />
+    </svg>
+  ),
   document: (
     <svg {...svgProps}>
       <path d="M6 3h8l4 4v14H6Z" />

package/src/locale.tsx CHANGED Viewed

@@ -67,6 +67,9 @@ export const LOCALE_NL: LocaleCatalog = {
     theme: "Thema",
     themeLight: "Licht",
     themeDark: "Donker",
+    themeMidnight: "Middernacht",
+    themeTwilight: "Schemering",
+    themeContrast: "Hoog contrast",
     themeSystem: "Systeem",
     language: "Taal",
     admin: "Beheer",

package/src/markers.test.ts ADDED Viewed

@@ -0,0 +1,245 @@
+import { describe, expect, it } from "vitest";
+// The `data-terp` marker inventory, pinned.
+//
+// A marker names a sanctioned component's rendered root. Two things already read them: the
+// layout contract's runtime slot check (ADR 0079) verifies the identity of the components a
+// body slot contains, and `TERP_STYLES_CSS` hangs every hover/active/disabled/selected
+// declaration off them. So a marker is not decoration — it is the join between a component
+// and both its enforcement and its styling.
+//
+// Nothing held that join in place. A renamed marker silently unstyles a component (the
+// stylesheet rule stops matching, and no test asserts the rule matched anything) and
+// silently widens a layout slot. Renaming is also exactly what a refactor does casually,
+// because the string looks like a debug hook.
+//
+// Two sides are scanned separately and that separation is the whole point of this file:
+// `styles.ts` *consumes* markers as CSS selectors, every component *produces* them as DOM
+// attributes. Scanning them together is worse than not testing at all — the selectors in
+// the sheet re-supply any name a component stopped rendering, so deleting a marker from a
+// component leaves the inventory intact and the suite green while the app loses its styling.
+//
+// The ambient `ImportMeta.glob` type lives in raw.d.ts, shared with the other scanning tests.
+const sources = import.meta.glob("./**/*.{ts,tsx}", {
+  query: "?raw",
+  import: "default",
+  eager: true,
+});
+/** The single module holding the framework stylesheet: markers appear there as selectors. */
+const STYLESHEET = "./styles.ts";
+/**
+ * Every marker a component renders today.
+ *
+ * Adding a component adds a name here. Renaming one is a breaking change to both the
+ * stylesheet and the layout contract, so it belongs in a release note.
+ */
+const MARKERS = [
+  "alert",
+  "appshell-brand",
+  "appshell-nav",
+  "badge",
+  "breadcrumbs",
+  "button",
+  "card",
+  "card-actions",
+  "card-header",
+  "checkbox",
+  "dataview",
+  "dataview-card",
+  "dataview-row",
+  "dataview-row-open",
+  "dataview-table",
+  "dataview-toolbar",
+  "detail-list",
+  "dialog",
+  "drawer-focus-end",
+  "drawer-focus-start",
+  "empty-state",
+  "error-state",
+  "hubcard",
+  "hubcard-body",
+  "hubcard-description",
+  "hubcard-link",
+  "hubcard-stat",
+  "hubcard-title",
+  "iconbutton",
+  "input",
+  "loading-state",
+  "menu",
+  "menu-item",
+  "module-nav",
+  "nav-icon",
+  "popover",
+  "popover-panel",
+  "radio",
+  "resource-list",
+  "spinner-ring",
+  "stack",
+  "switch",
+  "tab",
+  "tabs",
+  "tooltip",
+];
+/**
+ * Styled surfaces that render no marker, and therefore cannot be reached by an attribute
+ * selector or verified by a slot check.
+ *
+ * A ratchet that shrinks only: this list is the worklist for moving component styling out
+ * of inline `style={}` and into the sheet, because a surface with no marker has nothing for
+ * a rule to match. Providers, hooks, module manifests and view compositions are deliberately
+ * absent — they render no styled root of their own.
+ *
+ * `Badge` and `Tooltip` have graduated: both own a single styled element, so marking them
+ * changed no DOM and no pixels. What is left does *not* reduce to adding an attribute, and
+ * the reason splits into two shapes worth knowing before the styling migration is planned:
+ *
+ *   - **Delegates its root.** `theme.tsx` (ThemeToggle) and `locale.tsx` (LanguageSwitcher)
+ *     return a bare `Menu` in their `inline` variant — the variant the app shell header
+ *     actually uses — so their root already carries `data-terp="menu"` and is
+ *     indistinguishable from any other menu. `UserMenu` is the same shape. Marking them
+ *     means either threading a marker through `Menu` or introducing a wrapper element.
+ *   - **Returns a fragment.** `Markdown` emits a sequence of block elements with no root at
+ *     all. A marker requires a wrapper, and a wrapper is a new block box in every consumer's
+ *     layout.
+ *
+ * Both are styling decisions with visible consequences, not bookkeeping, so they belong to
+ * the migration itself rather than to preparation for it. The archetypes, `Field`,
+ * `PageActions` and the DataView internals are still unexamined.
+ */
+const UNMARKED_STYLED_SURFACES = [
+  "./DetailPage.tsx",
+  "./Field.tsx",
+  "./LoginView.tsx",
+  "./OverviewPage.tsx",
+  "./PageActions.tsx",
+  "./ProfileView.tsx",
+  "./UserMenu.tsx",
+  "./dataview/DataViewColumnSettings.tsx",
+  "./dataview/DataViewExpandableRow.tsx",
+  "./dataview/DataViewRowActions.tsx",
+  "./files.tsx",
+  "./locale.tsx",
+  "./theme.tsx",
+  "./ui/Markdown.tsx",
+];
+/**
+ * `text` with comments removed, so prose naming a marker cannot stand in for rendering one.
+ *
+ * Line comments are only stripped from a `//` that does not follow a colon, which keeps
+ * `https://` inside a string intact. Approximate by design: the result is fed to a marker
+ * regex, never compiled.
+ */
+function stripComments(text: string) {
+  return text.replace(/\/\*[\s\S]*?\*\//g, "").replace(/(^|[^:])\/\/.*$/gm, "$1");
+}
+/**
+ * Marker values authored in `text`, in any of the forms the package actually uses:
+ * `data-terp="x"`, `data-terp={"x"}`, `data-terp={open ? "x" : "y"}`, and `"data-terp": "x"`.
+ *
+ * A regex anchored to `data-terp="…"` alone misses the conditional form — which is how the
+ * DataView row markers are written — so renaming one of those would not fail anything.
+ */
+function markersIn(text: string) {
+  const source = stripComments(text);
+  const found = new Set<string>();
+  const attribute = /data-terp["']?\s*[=:]\s*/g;
+  for (let match = attribute.exec(source); match; match = attribute.exec(source)) {
+    const rest = source.slice(match.index + match[0].length);
+    // An expression container may hold several literals (a ternary); a bare literal holds
+    // one. Read only as far as the value actually extends, so the next attribute's string
+    // is never absorbed.
+    const scope = rest.startsWith("{") ? expressionAt(rest) : rest.slice(0, firstLiteralEnd(rest));
+    for (const literal of scope.matchAll(/["']([a-z0-9-]+)["']/g)) {
+      found.add(literal[1]!);
+    }
+  }
+  return found;
+}
+/** The `{ … }` expression starting at `text[0]`, brace-matched. */
+function expressionAt(text: string) {
+  let depth = 0;
+  for (let index = 0; index < text.length; index += 1) {
+    if (text[index] === "{") depth += 1;
+    else if (text[index] === "}") {
+      depth -= 1;
+      if (depth === 0) return text.slice(0, index + 1);
+    }
+  }
+  return text;
+}
+/** The end of the single quoted literal starting at `text[0]`, or 0 when there is none. */
+function firstLiteralEnd(text: string) {
+  const quote = text[0];
+  if (quote !== '"' && quote !== "'") return 0;
+  const close = text.indexOf(quote, 1);
+  return close === -1 ? 0 : close + 1;
+}
+const production = Object.entries(sources).filter(([file]) => !file.includes(".test."));
+const components = production.filter(([file]) => file !== STYLESHEET);
+/** Markers a component renders as a DOM attribute. */
+const rendered = new Set(components.flatMap(([, text]) => [...markersIn(text)]));
+/** Markers the framework stylesheet targets as `[data-terp="…"]` selectors. */
+const styled = new Set(
+  [...(sources[STYLESHEET] ?? "").matchAll(/\[data-terp=["']([a-z0-9-]+)["']\]/g)].map(
+    (match) => match[1]!,
+  ),
+);
+describe("data-terp markers", () => {
+  it("reads both sides of the join it is asserting about", () => {
+    expect(components.length).toBeGreaterThan(0);
+    expect(sources[STYLESHEET], `${STYLESHEET} is not in the scanned source`).toBeDefined();
+    expect(rendered.size).toBeGreaterThan(0);
+    expect(styled.size).toBeGreaterThan(0);
+    // The two sets must be gathered from different files, or the separation is cosmetic.
+    expect(components.some(([file]) => file === STYLESHEET)).toBe(false);
+  });
+  it("renders exactly the pinned inventory", () => {
+    // Sorted both sides so the diff on failure names the added or removed marker rather
+    // than showing two long reordered lists.
+    expect([...rendered].sort()).toEqual([...MARKERS].sort());
+  });
+  it("pins the inventory in sorted order with no duplicates", () => {
+    // The list is read by humans during review; an unsorted or duplicated entry makes an
+    // addition look like a rename.
+    expect(MARKERS).toEqual([...new Set(MARKERS)].sort());
+  });
+  it("styles no marker that no component renders", () => {
+    // A selector matching nothing is dead styling that reads as live: the rule is right
+    // there in the sheet, so the state it describes looks handled when it is not.
+    expect([...styled].filter((marker) => !rendered.has(marker)).sort()).toEqual([]);
+  });
+  it("keeps the unmarked-surface worklist accurate", () => {
+    // One direction only: a file that gained a marker must leave the list, or the ratchet
+    // stops meaning anything. It deliberately does not assert the converse — every
+    // provider, hook and manifest in the package renders no marker legitimately, so
+    // requiring the list to name every unmarked file would make it a list of everything.
+    // A *new* unmarked primitive is therefore caught at review, not here.
+    const stillUnmarked = components
+      .filter(([, text]) => markersIn(text).size === 0)
+      .map(([file]) => file);
+    expect(
+      UNMARKED_STYLED_SURFACES.filter((file) => !stillUnmarked.includes(file)),
+      "these now render a marker — remove them from the worklist",
+    ).toEqual([]);
+    expect(
+      UNMARKED_STYLED_SURFACES,
+      "the worklist must stay sorted and duplicate-free",
+    ).toEqual([...new Set(UNMARKED_STYLED_SURFACES)].sort());
+  });
+});

package/src/raw.d.ts CHANGED Viewed

@@ -1,7 +1,21 @@
 /**
- * Minimal Node file access for the token guard test only — the package keeps
+ * Minimal ambient declarations for the source-scanning tests only — the package keeps
  * `"types": []` so component source never sees ambient Node globals.
+ *
+ * Both live here rather than inline in the tests that use them: a global augmentation
+ * repeated in two files is a TS2717 the moment the copies disagree, and they disagree
+ * silently until someone widens one of them.
  */
 declare module "node:fs" {
   export function readFileSync(path: URL | string, encoding: "utf-8"): string;
 }
+// Declared at top level, not inside `declare global`: this file is a global script (it has
+// no imports or exports), so the interface merges with the ambient `ImportMeta` directly —
+// `declare global` is only meaningful from inside a module.
+interface ImportMeta {
+  glob: (
+    pattern: string,
+    options: { query: "?raw"; import: "default"; eager: true },
+  ) => Record<string, string>;
+}

package/src/styles.ts CHANGED Viewed

@@ -141,7 +141,7 @@ html {
 [data-terp="input"]:focus,
 [data-terp="input"]:focus-visible {
   outline: none;
-  border-color: var(--color-brand-primary) !important;
+  border-color: var(--color-fg-accent) !important;
   box-shadow: 0 0 0 3px var(--color-focus-ring) !important;
 }
 [data-terp="input"]::placeholder {
@@ -241,12 +241,12 @@ label:has([data-terp="switch"]:disabled) {
   transition: border-color 150ms ease, box-shadow 150ms ease, transform 150ms ease;
 }
 [data-terp="hubcard"]:hover {
-  border-color: var(--color-brand-primary) !important;
+  border-color: var(--color-fg-accent) !important;
   box-shadow: var(--shadow-sm);
   transform: translateY(-1px);
 }
 [data-terp="hubcard"]:hover [data-terp="hubcard-title"] {
-  color: var(--color-brand-primary) !important;
+  color: var(--color-fg-accent) !important;
 }
 /* Breadcrumb links -------------------------------------------------------- */
@@ -283,7 +283,7 @@ label:has([data-terp="switch"]:disabled) {
 }
 [data-terp="menu-item"][data-selected="true"] {
   background: var(--color-brand-primary-soft) !important;
-  color: var(--color-brand-primary) !important;
+  color: var(--color-fg-accent) !important;
 }
 /* Dialogs: ::backdrop cannot be set inline, so the dim layer lives here and

package/src/theme.test.tsx CHANGED Viewed

@@ -34,6 +34,45 @@ describe("ThemeProvider + ThemeToggle", () => {
     expect(window.localStorage.getItem(THEME_STORAGE_KEY)).toBe("dark");
   });
+  it("applies a named theme beyond light and dark", () => {
+    // The named themes are the reason the semantic token layer exists. They are compiled,
+    // contrast-gated and published, and none of that reaches a user unless the control can
+    // actually pin one — so the whole path is exercised for one of them.
+    render(
+      <ThemeProvider>
+        <ThemeToggle />
+      </ThemeProvider>,
+    );
+    fireEvent.click(screen.getByRole("button", { name: "Theme" }));
+    fireEvent.click(screen.getByRole("menuitemradio", { name: "Midnight" }));
+    expect(document.documentElement.getAttribute("data-theme")).toBe("midnight");
+    expect(window.localStorage.getItem(THEME_STORAGE_KEY)).toBe("midnight");
+  });
+  it("offers every shipped theme, not only light and dark", () => {
+    // `theme.themes.test.ts` proves the list matches the contract's; this proves the list
+    // reaches the menu, which is a different failure — a name in `THEMES` that never renders.
+    render(
+      <ThemeProvider>
+        <ThemeToggle />
+      </ThemeProvider>,
+    );
+    fireEvent.click(screen.getByRole("button", { name: "Theme" }));
+    for (const label of ["Light", "Dark", "Midnight", "Twilight", "High contrast", "System"]) {
+      expect(screen.getByRole("menuitemradio", { name: label })).toBeInTheDocument();
+    }
+  });
+  it("accepts a named theme as the app default", () => {
+    // How an app ships on a named theme: one prop, no other change anywhere.
+    render(
+      <ThemeProvider defaultTheme="contrast">
+        <ThemeToggle />
+      </ThemeProvider>,
+    );
+    expect(document.documentElement.getAttribute("data-theme")).toBe("contrast");
+  });
   it("restores a persisted choice over the app default", () => {
     window.localStorage.setItem(THEME_STORAGE_KEY, "light");
     render(

package/src/theme.themes.test.ts ADDED Viewed

@@ -0,0 +1,124 @@
+import { readFileSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+import { DEFAULT_STRINGS } from "./uiText";
+// react-core's theme list against the contract's published one.
+//
+// `Theme` in `theme.tsx` is a hand-written union of the stylesheet's theme names, and
+// `THEME_ICONS` and the label map are records over it. That is a restatement of a published
+// contract, so it can drift from it — and both directions fail quietly:
+//
+//   * A theme the sheet ships that this union omits is a palette no app can ever select. It
+//     is compiled, gated for contrast and completeness, published in the manifest, and
+//     unreachable.
+//   * A theme this union offers that the sheet has no block for is a menu entry that sets
+//     `data-theme` to a value nothing matches, so the app silently renders the base theme
+//     while the control reports the choice took.
+//
+// The union is not derived from the manifest at runtime on purpose: react-core publishes
+// unbuilt TypeScript and imports nothing but React, so resolving a sibling package's JSON
+// module would add a bundler and tsconfig requirement to every consumer. A test reading the
+// file from disk is the same discipline the other mirrored tables in this repo use — the copy
+// stays a copy, and the copy is checked.
+const manifest: {
+  base: string;
+  systemDark: string;
+  themes: { name: string; label: string; appearance: "light" | "dark" }[];
+} = JSON.parse(
+  readFileSync(new URL("../../contract/src/tokens.manifest.json", import.meta.url), "utf-8"),
+);
+// Read as source rather than imported, because the union is a type: it does not survive to
+// runtime, and `THEMES` alone would not prove the type and the array agree.
+const themeSource = readFileSync(new URL("./theme.tsx", import.meta.url), "utf-8");
+/** The names in `export type Theme = "a" | "b" | …`. */
+function unionMembers(): string[] {
+  const match = /export type Theme =([^;]+);/.exec(themeSource);
+  if (!match) throw new Error("theme.tsx: could not find `export type Theme`");
+  return [...match[1]!.matchAll(/"([a-z-]+)"/g)].map((entry) => entry[1]!);
+}
+/** The names in the `THEMES` array literal. */
+function themesArray(): string[] {
+  const match = /const THEMES: readonly Theme\[\] = \[([^\]]+)\]/.exec(themeSource);
+  if (!match) throw new Error("theme.tsx: could not find the `THEMES` array");
+  return [...match[1]!.matchAll(/"([a-z-]+)"/g)].map((entry) => entry[1]!);
+}
+/** The keys of a `Record<Theme, …>` literal assigned to `name`. */
+function recordKeys(name: string): string[] {
+  const match = new RegExp(`const ${name}: Record<Theme, [^>]+> = \\{([^}]+)\\}`).exec(
+    themeSource,
+  );
+  if (!match) throw new Error(`theme.tsx: could not find \`${name}\``);
+  return [...match[1]!.matchAll(/^\s*([a-z-]+):/gm)].map((entry) => entry[1]!);
+}
+/** Every theme the stylesheet ships, in registry order. */
+const shipped = manifest.themes.map((theme) => theme.name);
+/** What the control offers: every shipped theme, plus the OS-preference entry. */
+const OS_PREFERENCE = "system";
+const expected = [...shipped, OS_PREFERENCE];
+describe("react-core's theme list", () => {
+  it("reads the sources it is asserting about", () => {
+    // Every assertion below is a comparison against a regex match. A regex that stopped
+    // matching — a reformatted union, a renamed constant — would compare two empty lists and
+    // report green, which is the one failure mode a parity test cannot afford.
+    expect(shipped.length).toBeGreaterThanOrEqual(3);
+    expect(unionMembers().length).toBe(expected.length);
+    expect(themesArray().length).toBe(expected.length);
+  });
+  it("offers exactly the themes the contract ships, plus system", () => {
+    // The union is the app-facing type: a theme missing here cannot be passed to
+    // `ThemeProvider` at all, however completely the stylesheet defines it.
+    expect(unionMembers()).toEqual(expected);
+  });
+  it("lists them in the same order in the THEMES array", () => {
+    // `THEMES` is what `ThemeToggle` maps over and what `readStoredTheme` validates against,
+    // so a name in the type but not the array is selectable in code and absent from the menu.
+    expect(themesArray()).toEqual(expected);
+  });
+  it("gives every theme an icon, and no two the same", () => {
+    // A picker whose entries share a glyph is a picker whose icons carry no information, and
+    // the trigger renders the active theme's icon — so a duplicate makes two states identical.
+    expect(recordKeys("THEME_ICONS")).toEqual(expected);
+    const glyphs = [...themeSource.matchAll(/^\s{2}([a-z-]+): "([a-z-]+)",$/gm)]
+      .filter((entry) => expected.includes(entry[1]!))
+      .map((entry) => entry[2]!);
+    expect(glyphs).toHaveLength(expected.length);
+    expect(new Set(glyphs).size).toBe(glyphs.length);
+  });
+  it("has a translated label for every theme", () => {
+    // The label map is `Record<Theme, string>` so the compiler catches a missing entry, but
+    // not one pointing at a string key that does not exist in the catalog.
+    for (const name of expected) {
+      const key = `theme${name[0]!.toUpperCase()}${name.slice(1)}`;
+      expect(
+        Object.hasOwn(DEFAULT_STRINGS, key),
+        `${name} needs a ${key} string (LOCALE_NL's completeness gate then forces the Dutch one)`,
+      ).toBe(true);
+    }
+  });
+  it("keeps the OS-preference entry from colliding with a theme name", () => {
+    // "system" is a sentinel, not a theme: it means *remove* `data-theme` and let the sheet's
+    // `prefers-color-scheme` block decide. A shipped theme actually named `system` would make
+    // the sentinel ambiguous — selecting it would clear the attribute rather than pin the
+    // theme, and the two would be indistinguishable in storage.
+    expect(shipped).not.toContain(OS_PREFERENCE);
+    // Both ends of what the sentinel resolves to have to be themes the control also offers,
+    // or "System" would render a palette the user cannot pick deliberately.
+    expect(shipped).toContain(manifest.systemDark);
+    expect(shipped).toContain(manifest.base);
+  });
+});

package/src/theme.tsx CHANGED Viewed

@@ -7,16 +7,37 @@ import { useStrings } from "./uiText";
 /**
  * The visual theme: an explicit choice, or "system" to follow the OS preference.
- * The token stylesheet (`@terpjs/contract/tokens.css`) carries both palettes: it applies
- * the dark colours under `<html data-theme="dark">` and — with no attribute — under
- * `@media (prefers-color-scheme: dark)`, so "system" simply removes the attribute.
+ *
+ * The token stylesheet (`@terpjs/contract/tokens.css`) carries every palette: it applies
+ * each named theme's colours under `<html data-theme="<name>">` and — with no attribute —
+ * applies the dark palette under `@media (prefers-color-scheme: dark)`, so "system" simply
+ * removes the attribute.
+ *
+ * The names are the stylesheet's, so this union is a restatement of a published contract
+ * and could drift from it silently — a theme the sheet ships that no app can select, or one
+ * this offers that resolves to nothing. `theme.themes.test.ts` holds it against the token
+ * manifest. The union is written out rather than derived from the manifest at runtime because
+ * react-core publishes unbuilt source and imports nothing but React: resolving a JSON module
+ * from a sibling package would add a requirement to every consumer's bundler and tsconfig,
+ * which is the consumption-model change the framework spends real effort avoiding.
  */
-export type Theme = "light" | "dark" | "system";
+export type Theme = "light" | "dark" | "midnight" | "twilight" | "contrast" | "system";
+const THEMES: readonly Theme[] = [
+  "light",
+  "dark",
+  "midnight",
+  "twilight",
+  "contrast",
+  "system",
+];
-const THEMES: readonly Theme[] = ["light", "dark", "system"];
 const THEME_ICONS: Record<Theme, string> = {
   light: "sun",
   dark: "moon",
+  midnight: "moon-stars",
+  twilight: "sunset",
+  contrast: "contrast",
   system: "monitor",
 };
@@ -46,10 +67,13 @@ export interface ThemeProviderProps {
 }
 /**
- * Owns the light/dark theme choice: applies it as `data-theme` on `<html>` (the token
- * stylesheet does the rest — no component changes anywhere) and persists it in
- * `localStorage`. `renderTerpApp` mounts one for every app; pair with {@link ThemeToggle}
- * (the default {@link UserMenu} already includes it).
+ * Owns the theme choice: applies it as `data-theme` on `<html>` (the token stylesheet does
+ * the rest — no component changes anywhere) and persists it in `localStorage`.
+ * `renderTerpApp` mounts one for every app; pair with {@link ThemeToggle} (the default
+ * {@link UserMenu} already includes it).
+ *
+ * `defaultTheme` is how an app ships on a named theme — `defaultTheme="midnight"` and
+ * nothing else — since it applies until the user chooses otherwise.
  */
 export function ThemeProvider({ defaultTheme = "system", children }: ThemeProviderProps) {
   const [theme, setThemeState] = useState<Theme>(() => {
@@ -93,8 +117,8 @@ export interface ThemeToggleProps {
 }
 /**
- * The standard theme control: a token-themed light/dark/system menu. Renders nothing
- * outside a {@link ThemeProvider}, so shared chrome (the shell header) can
+ * The standard theme control: a token-themed menu over every shipped theme plus "system".
+ * Renders nothing outside a {@link ThemeProvider}, so shared chrome (the shell header) can
  * include it unconditionally.
  */
 export function ThemeToggle({ variant = "stacked" }: ThemeToggleProps) {
@@ -106,6 +130,9 @@ export function ThemeToggle({ variant = "stacked" }: ThemeToggleProps) {
   const labels: Record<Theme, string> = {
     light: strings.themeLight,
     dark: strings.themeDark,
+    midnight: strings.themeMidnight,
+    twilight: strings.themeTwilight,
+    contrast: strings.themeContrast,
     system: strings.themeSystem,
   };
   const menu = (

package/src/tokens.guard.test.ts CHANGED Viewed

@@ -7,18 +7,9 @@ const tokensCss = readFileSync(
   "utf-8",
 );
-// Typed locally so the package keeps its deliberate `"types": []` isolation:
-// react-core source must never see ambient Node globals. The source scan uses
-// Vite's raw glob; only the CSS sheet needs fs (declared minimally in raw.d.ts).
-declare global {
-  interface ImportMeta {
-    glob: (
-      pattern: string,
-      options: { query: "?raw"; import: "default"; eager: true },
-    ) => Record<string, string>;
-  }
-}
+// The package keeps its deliberate `"types": []` isolation: react-core source must never
+// see ambient Node globals. The source scan uses Vite's raw glob and the sheet needs fs;
+// both are declared minimally in raw.d.ts, shared with the other scanning tests.
 const sources = import.meta.glob("./**/*.{ts,tsx}", {
   query: "?raw",
   import: "default",

package/src/ui/Badge.tsx CHANGED Viewed

@@ -55,6 +55,13 @@ const badgeStyle = (tone: BadgeTone): CSSProperties => ({
 /** Small token-styled status pill — flat soft tint with a matching text colour. */
 export function Badge({ label, children, tone = "neutral" }: BadgeProps) {
   const resolve = useUiText();
-  return <span style={badgeStyle(tone)}>{resolve((label ?? children) as UiText)}</span>;
+  // `data-tone` alongside the marker: the tone is currently readable only from the inline
+  // colour values, so a stylesheet rule cannot address "the warning pill" at all. Naming it
+  // as an attribute is what lets tone styling move out of `style={}` later.
+  return (
+    <span data-terp="badge" data-tone={tone} style={badgeStyle(tone)}>
+      {resolve((label ?? children) as UiText)}
+    </span>
+  );
 }

package/src/ui/Checkbox.tsx CHANGED Viewed

@@ -18,7 +18,7 @@ const labelStyle: CSSProperties = {
 const inputStyle: CSSProperties = {
   inlineSize: "1rem",
   blockSize: "1rem",
-  accentColor: "var(--color-brand-primary)",
+  accentColor: "var(--color-fg-accent)",
   cursor: "pointer",
 };

package/src/ui/Combobox.tsx CHANGED Viewed

@@ -80,7 +80,7 @@ const optionStyle = (active: boolean, selected: boolean, disabled: boolean): CSS
   color: disabled
     ? "var(--color-neutral-400)"
     : selected
-      ? "var(--color-brand-primary)"
+      ? "var(--color-fg-accent)"
       : "var(--color-neutral-900)",
   cursor: disabled ? "not-allowed" : "pointer",
   fontWeight: selected ? "var(--font-weight-semibold)" as never : "var(--font-weight-normal)" as never,

package/src/ui/Radio.tsx CHANGED Viewed

@@ -27,7 +27,7 @@ const labelStyle: CSSProperties = {
 const inputStyle: CSSProperties = {
   inlineSize: "1rem",
   blockSize: "1rem",
-  accentColor: "var(--color-brand-primary)",
+  accentColor: "var(--color-fg-accent)",
   cursor: "pointer",
 };

package/src/ui/Switch.tsx CHANGED Viewed

@@ -18,7 +18,7 @@ const labelStyle: CSSProperties = {
 const inputStyle: CSSProperties = {
   inlineSize: "2.25rem",
   blockSize: "1.25rem",
-  accentColor: "var(--color-brand-primary)",
+  accentColor: "var(--color-fg-accent)",
   cursor: "pointer",
   transition: "background-color 150ms ease",
 };

package/src/ui/Tabs.tsx CHANGED Viewed

@@ -22,8 +22,8 @@ const tabStyle = (selected: boolean): CSSProperties => ({
     : "var(--font-weight-medium)") as never,
   padding: "var(--space-2) var(--space-3)",
   border: 0,
-  borderBlockEnd: selected ? "2px solid var(--color-brand-primary)" : "2px solid transparent",
-  color: selected ? "var(--color-brand-primary)" : "var(--color-neutral-600)",
+  borderBlockEnd: selected ? "2px solid var(--color-fg-accent)" : "2px solid transparent",
+  color: selected ? "var(--color-fg-accent)" : "var(--color-neutral-600)",
   background: "transparent",
   cursor: "pointer",
   marginBlockEnd: "-1px",

package/src/ui/Tooltip.tsx CHANGED Viewed

@@ -59,7 +59,7 @@ export function Tooltip({ content, children }: TooltipProps) {
           setOpen(false);
         },
       })}
-      <span id={id} role="tooltip" hidden={!open} style={tooltipStyle}>
+      <span id={id} role="tooltip" data-terp="tooltip" hidden={!open} style={tooltipStyle}>
         {resolve(content)}
       </span>
     </span>

package/src/uiText.tsx CHANGED Viewed

@@ -100,6 +100,12 @@ export interface TerpStrings {
   themeLight: string;
   /** {@link ThemeToggle} option: the dark theme. */
   themeDark: string;
+  /** {@link ThemeToggle} option: the near-black dark theme. */
+  themeMidnight: string;
+  /** {@link ThemeToggle} option: the violet-tinted dark theme. */
+  themeTwilight: string;
+  /** {@link ThemeToggle} option: the high-contrast theme. */
+  themeContrast: string;
   /** {@link ThemeToggle} option: follow the OS preference. */
   themeSystem: string;
   /** Label of the {@link LanguageSwitcher} select. */
@@ -239,6 +245,9 @@ export const DEFAULT_STRINGS: TerpStrings = {
   theme: "Theme",
   themeLight: "Light",
   themeDark: "Dark",
+  themeMidnight: "Midnight",
+  themeTwilight: "Twilight",
+  themeContrast: "High contrast",
   themeSystem: "System",
   language: "Language",
   admin: "Admin",