@terpjs/contract 0.9.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@terpjs/contract",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "type": "module",
   "description": "Terp frontend contract \u2014 the OpenAPI-generated TypeScript client, design tokens, and the stack-agnostic module/route/nav + auth types.",
   "exports": {

package/scripts/build-tokens.mjs

@@ -31,6 +31,23 @@ const buildDir = mkdtempSync(join(tmpdir(), "terp-tokens-"));
 
 const read = (name) => JSON.parse(readFileSync(join(packageRoot, name), "utf8"));
 
+/**
+ * WCAG 2.1 AA for normal-size text — the floor every theme is held to unless `themes.json`
+ * raises it. Declared here because the manifest publishes an effective floor per theme and
+ * the contrast gate reads it back; the constant has one home, on the writing side.
+ */
+const AA_NORMAL_TEXT = 4.5;
+
+/**
+ * WCAG 2.1 SC 1.4.11, non-text contrast: the bar for a control's visual boundary and for a
+ * state or focus indicator. Published once at the top level rather than per theme, and that is
+ * the claim: it is FLAT across every theme, including the one that raises its text floor to
+ * AAA, because WCAG defines no AAA tier for non-text contrast. A consumer holding the
+ * `nonTextPairs` section to a theme's raised text floor would be enforcing a standard nobody
+ * wrote; one holding it to nothing would read the section as decorative.
+ */
+const UI_COMPONENT = 3;
+
 const registry = read("themes.json");
 const themes = registry.themes;
 const base = themes.find((theme) => theme.name === registry.base);
@@ -94,6 +111,34 @@ for (const theme of themes) {
 }
 rmSync(buildDir, { recursive: true, force: true });
 
+/**
+ * The appearance switch: the one theme fact CSS can consume but cannot select on.
+ *
+ * `color-scheme` already records whether a theme reads light or dark, and it is the right
+ * answer for native chrome — but there is no selector for it, so nothing in a stylesheet can
+ * branch on it. Anything that must render one way under a light theme and another under a dark
+ * one therefore needs the same fact in custom-property form. Its first consumer is `AppShell`'s
+ * brand mark: the bundled icons all stroke in `currentColor`, but a company logo usually cannot,
+ * and a dark-ink one is invisible on three of the five shipped themes.
+ *
+ * Derived rather than declared per theme, and that is the whole reason it lives here. A
+ * stylesheet enumerating which themes are dark is a list that rots the first time one is added,
+ * silently — the wrong mark, on the new theme only. `appearance` is required by `themes.json`,
+ * validated above, and named in the registry's own comment as one of the four things a theme
+ * file cannot imply. So a sixth theme cannot forget to answer.
+ *
+ * Values are `block` / `none` rather than any particular layout keyword: a consumer centres
+ * from the BOX around the thing it is showing, so a theme never has to know what layout that
+ * consumer uses.
+ *
+ * Deliberately NOT in the token manifest, and the two gates that had to be widened for it say
+ * why in their own files: it is a mechanism, not a design knob, and a theme editor offering
+ * `block` / `none` as an editable pair offers a way to break the switch.
+ */
+const appearanceSwitch = (appearance) =>
+  `  --appearance-show-light: ${appearance === "light" ? "block" : "none"};
+  --appearance-show-dark: ${appearance === "dark" ? "block" : "none"};`;
+
 const themeBlocks = overlays
   .map(
     (theme) => `
@@ -101,6 +146,7 @@ const themeBlocks = overlays
    ${theme.description} */
 [data-theme='${theme.name}'] {
   color-scheme: ${theme.appearance};
+${appearanceSwitch(theme.appearance)}
 ${compiled.get(theme.name)}
 }
 `,
@@ -118,6 +164,9 @@ const output = `/**
      text-field carets) into the ${base.appearance} palette so it never renders as foreign
      OS-${base.appearance === "light" ? "dark" : "light"} chrome. Each theme block below sets its own. */
   color-scheme: ${base.appearance};
+  /* The appearance as something a stylesheet can branch on — see appearanceSwitch above.
+     color-scheme records the same fact and no selector can read it. */
+${appearanceSwitch(base.appearance)}
 ${compiled.get(base.name)}
 }
 ${themeBlocks}
@@ -125,6 +174,7 @@ ${themeBlocks}
 @media (prefers-color-scheme: dark) {
   :root:not([data-theme]) {
     color-scheme: ${systemDark.appearance};
+${appearanceSwitch(systemDark.appearance).replace(/^ {2}/gm, "    ")}
 ${compiled.get(systemDark.name).replace(/^ {2}/gm, "    ")}
   }
 }
@@ -183,11 +233,18 @@ const manifest = {
   // alone rather than hard-coding the list it happens to know about.
   base: registry.base,
   systemDark: registry.systemDark,
-  themes: themes.map(({ name, label, appearance, description }) => ({
+  themes: themes.map(({ name, label, appearance, description, minimumContrast }) => ({
     name,
     label,
     appearance,
     description,
+    // The ratio this theme's declared text pairings must reach, published as a NUMBER on every
+    // theme rather than only on the one that raises it. A consumer that saw the field only on
+    // `contrast` would have to know WCAG's AA constant to interpret its absence, and would then
+    // be free to interpret it differently from the gate — which is the one thing this file
+    // exists to prevent. `tokens.contrast.test.js` reads this value instead of re-deriving it,
+    // so the published floor IS the enforced floor.
+    minimumContrast: minimumContrast ?? AA_NORMAL_TEXT,
   })),
   tokens: [...baseTokens.entries()].map(([name, token]) => ({
     name,
@@ -204,6 +261,9 @@ const manifest = {
     ),
     themeable: overlays.some((theme) => sources.get(theme.name).has(name)),
   })),
+  // The floor for the `nonTextPairs` section below — flat across themes, unlike the per-theme
+  // text floor above. Named at the top level so the two sections cannot be read as sharing a bar.
+  nonTextMinimumContrast: UI_COMPONENT,
   textPairs: pairs.textPairs,
   // Both sections, because a consumer that can only see the text pairings would read the
   // absence of a boundary pairing as "no requirement" rather than "held elsewhere".

package/src/appearance-mechanism.js

@@ -0,0 +1,19 @@
+/**
+ * Per-theme custom properties that are NOT design tokens, as an exact list.
+ *
+ * Two gates are stated over "non-colour" tokens and mean it: geometry is theme-invariant
+ * (`tokens.themes.test.js`), and the manifest names every token the base root declares
+ * (`tokens.manifest.test.js`). This pair is neither — it is the theme's own `appearance` in
+ * the one form a stylesheet can branch on, because `color-scheme` records the same fact and no
+ * selector can read it. The values are `block` / `none`, so it varies per theme by
+ * construction and belongs in no theme editor.
+ *
+ * Hand-written rather than imported from the generator that emits it, and that is the point:
+ * a third such property appearing in `tokens.css` fails both gates until someone adds it here
+ * with a reason. Importing the generator's own list would make every future addition
+ * self-approving.
+ */
+export const APPEARANCE_MECHANISM_TOKENS = [
+  "--appearance-show-light",
+  "--appearance-show-dark",
+];

package/src/icons.ts

@@ -0,0 +1,98 @@
+/**
+ * The bundled icon names, as data the contract publishes.
+ *
+ * Contract cannot import react-core — the dependency runs the other way — so the glyphs
+ * themselves stay in react-core and only their NAMES live here. That split is what lets
+ * `NavItem.icon` be a checked name on a manifest that knows nothing about React: an app naming
+ * an icon this set does not contain gets a typecheck error where it used to get a silent letter
+ * tile, and a future non-React adapter reads the same list.
+ *
+ * `as const` is load-bearing rather than stylistic. Without it the array widens to `string[]`,
+ * {@link IconName} becomes `string`, and every check built on it still compiles while asserting
+ * nothing at all — the whole change would ship and do nothing. That is what the
+ * `@ts-expect-error` guard beside the glyph table in react-core exists to catch: remove the
+ * `as const` here and the directive there becomes unused, which is itself an error.
+ *
+ * Kept in the glyph table's declaration order rather than sorted, so the two read as one list.
+ * react-core holds the table to this set exhaustively in both directions with `satisfies`, so a
+ * glyph added without a name here, or a name added without a glyph, is a compile error at the
+ * table rather than a runtime blank.
+ */
+export const ICON_NAMES = [
+  "home",
+  "list",
+  "folder",
+  "users",
+  "shield",
+  "settings",
+  "sun",
+  "moon",
+  "monitor",
+  "moon-stars",
+  "sunset",
+  "contrast",
+  "document",
+  "chart",
+  "calendar",
+  "inbox",
+  "audit",
+  "hub",
+  "plus",
+  "edit",
+  "trash",
+  "search",
+  "check",
+  "x",
+  "chevron-down",
+  "chevron-right",
+  "chevron-left",
+  "arrow-left",
+  "external",
+  "logout",
+  "user",
+  "bell",
+  "key",
+  "globe",
+  "lock",
+  "tag",
+  "mail",
+  "refresh",
+  "filter",
+  "download",
+  "upload",
+  "star",
+  "heart",
+  "database",
+  "code",
+  "truck",
+  "cart",
+  "wallet",
+  "map-pin",
+  "clock",
+  "link",
+  "grid",
+  "book",
+  "briefcase",
+  "building",
+  "clipboard",
+  "layers",
+  "send",
+  "phone",
+  "image",
+  "video",
+  "music",
+  "wrench",
+  "zap",
+  "eye",
+  "eye-off",
+] as const;
+
+/**
+ * A name {@link ICON_NAMES} contains — the type `NavItem.icon` and `Icon` accept.
+ *
+ * Deliberately NOT the type of `NavIcon.name`, which stays `string`. `NavIcon` falls back to the
+ * label's initial in a tile, so an unknown name there is a designed, visible behaviour with a
+ * specimen of its own; `Icon` renders nothing at all, which is silence, and silence is the thing
+ * this type exists to make impossible.
+ */
+export type IconName = (typeof ICON_NAMES)[number];

package/src/index.ts

@@ -5,5 +5,7 @@ export type { components, operations, paths } from "./schema";
 
 // Stack-agnostic UI contract: the module/route/nav manifest and the auth/session shape.
 export { defineModuleManifest } from "./manifest";
-export type { ModuleManifest, ModuleRoute, NavItem, RoleName } from "./manifest";
+export { ICON_NAMES } from "./icons";
+export type { IconName } from "./icons";
+export type { ModuleManifest, ModuleRoute, NavGroup, NavItem, RoleName } from "./manifest";
 export type { AccessToken, Action, AuthSession, Credentials, CurrentUser } from "./auth";

package/src/manifest.ts

@@ -10,6 +10,8 @@
  */
 
 /** A role name as understood by the app's backend (e.g. "viewer" | "editor" | "admin"). */
+import type { IconName } from "./icons";
+
 export type RoleName = string;
 
 export interface ModuleRoute {
@@ -26,6 +28,25 @@ export interface ModuleRoute {
   view: string;
   /** Minimum role required to see the route; omitted = any authenticated user. */
   role?: RoleName;
+  /**
+   * Also require this named permission grant — the caller must hold it in
+   * `CurrentUser.permissions`.
+   *
+   * **ANDed with `role`**, and that is deliberately what the server does: a `Policy` carrying a
+   * `Permission` enforces the permission's role floor *and* the grant, so a client checking
+   * only one would disagree with the endpoint in one direction or the other. The same reasoning
+   * the `Authorized` component's `permission` prop already records.
+   *
+   * Deliberately not a combinator. The server's own declaration is one ref per read and one per
+   * write (`AuthzRef = Role | Permission | Roles`), so an any-of here could express a gate no
+   * `Policy` can declare — and a client gate that cannot correspond to a server gate can only
+   * drift from the endpoint it mirrors.
+   *
+   * A *display* and *routing* gate only; the server re-checks every request. Fails closed:
+   * unknown or misspelled names are simply absent from the grant list, and an app that mounts
+   * no grant capability has an empty list, which correctly hides everything that names one.
+   */
+  permission?: string;
   /**
    * Query-string keys this route reads, e.g. `["status", "page"]`.
    *
@@ -47,10 +68,101 @@ export interface NavItem {
   label: string;
   /** Destination path; should match a {@link ModuleRoute.path}. */
   to: string;
-  /** Icon identifier the stack maps to its own icon set. */
-  icon?: string;
+  /**
+   * Which bundled glyph the item shows, by name.
+   *
+   * A **checked** name ({@link IconName}), which is the one deliberately breaking part of the
+   * navigation model: a misspelled icon used to render the label's first letter in a tile, which
+   * looks like a considered fallback rather than like a typo, so it survived review and shipped.
+   * It is now a typecheck error at the manifest. Runtime behaviour is unchanged — the fallback
+   * still exists and still handles the honest case of an item with no icon at all.
+   */
+  icon?: IconName;
   /** Minimum role required to show the nav item. */
   role?: RoleName;
+  /**
+   * Also require this named permission grant — the caller must hold it in
+   * `CurrentUser.permissions`.
+   *
+   * **ANDed with `role`**, and that is deliberately what the server does: a `Policy` carrying a
+   * `Permission` enforces the permission's role floor *and* the grant, so a client checking
+   * only one would disagree with the endpoint in one direction or the other. The same reasoning
+   * the `Authorized` component's `permission` prop already records.
+   *
+   * Deliberately not a combinator. The server's own declaration is one ref per read and one per
+   * write (`AuthzRef = Role | Permission | Roles`), so an any-of here could express a gate no
+   * `Policy` can declare — and a client gate that cannot correspond to a server gate can only
+   * drift from the endpoint it mirrors.
+   *
+   * A *display* and *routing* gate only; the server re-checks every request. Fails closed:
+   * unknown or misspelled names are simply absent from the grant list, and an app that mounts
+   * no grant capability has an empty list, which correctly hides everything that names one.
+   */
+  permission?: string;
+  /**
+   * Match the URL exactly rather than as a segment-aligned prefix.
+   *
+   * The default is the prefix, and that is the useful behaviour: a detail page under a section
+   * keeps the section's tab lit, so `/records/123` leaves "Records" current. Set this where a
+   * destination should own only itself — typically a landing page that also has children in the
+   * nav, where the parent would otherwise stay lit on every child.
+   *
+   * It does not decide WHICH item is current when several match; that is a property of the set,
+   * and the adapter resolves it by longest match. This only says whether this item is a
+   * candidate at all.
+   */
+  exact?: boolean;
+  /**
+   * The {@link NavGroup} this item belongs to, by id.
+   *
+   * An item naming a group the app has not declared falls into the default headerless group
+   * rather than disappearing, and that is the deliberate direction to fail. A group is declared
+   * once by the **app**; the item is declared by a **module** that ships on its own schedule, so
+   * an id with no declaration yet is the normal first-run state of a module the app has not
+   * finished adopting. Silently dropping the link would hide a working screen and report nothing.
+   */
+  group?: string;
+  /**
+   * Sort key against the item's siblings inside its group.
+   *
+   * Absent is 0, so a positive number sorts below every unordered sibling and a negative one
+   * above — CSS `order` semantics, which is the vocabulary this framework already speaks.
+   * The sort is stable, so items that tie keep their declaration order and a manifest that
+   * declares no order anywhere renders exactly as it does today.
+   */
+  order?: number;
+}
+
+/**
+ * A named section of the primary navigation, declared once by the **app**.
+ *
+ * A group spans modules — a "Sales" group holds items contributed by several of them — so no
+ * module can own its label or its position, and it is the one part of the navigation model that
+ * cannot live on a module manifest. Items reference it by {@link NavItem.group}.
+ *
+ * Declaring groups is optional and additive: an app that declares none renders one flat,
+ * unlabelled list, which is what every app renders today.
+ */
+export interface NavGroup {
+  /** Referenced by {@link NavItem.group}. */
+  id: string;
+  /**
+   * Rendered above the group's list.
+   *
+   * `null` renders **no label element at all** — a positioning-only group, which is how an app
+   * places its otherwise-ungrouped items somewhere other than the end without inventing a
+   * heading for them. Required rather than optional so that "no label" is a decision the
+   * declaration states, not an omission.
+   */
+  label: string | null;
+  /**
+   * Sort key against sibling groups.
+   *
+   * Absent is 0 and the sort is stable, so groups that tie keep declaration order. The default
+   * headerless group is **not** part of this sort: it is always emitted last. See
+   * `groupNav` in `@terpjs/react-core` for why.
+   */
+  order?: number;
 }
 
 export interface ModuleManifest {

package/src/tokens.contrast.test.js

@@ -22,6 +22,7 @@ const here = (name) => fileURLToPath(new URL(name, import.meta.url));
 
 const tokensCss = fs.readFileSync(here("./tokens.css"), "utf8");
 const registry = JSON.parse(fs.readFileSync(here("../themes.json"), "utf8"));
+const manifest = JSON.parse(fs.readFileSync(here("./tokens.manifest.json"), "utf8"));
 
 /** WCAG 2.1 AA, normal-size text. Large text and UI boundaries would be 3.0. */
 const AA_NORMAL_TEXT = 4.5;
@@ -35,8 +36,12 @@ const AAA_NORMAL_TEXT = 7;
  * floor to AAA, because WCAG defines no AAA tier for non-text contrast — `minimumContrast` in
  * themes.json is a promise about reading, and inventing a stricter non-text bar from it would
  * be this file asserting a standard nobody wrote.
+ *
+ * Read from the manifest for the same reason `floorFor` is: both bars are published so a theme
+ * editor can hold an app's palette to them, and a bar that is published in one place and
+ * enforced from another is two numbers wearing one name.
  */
-const UI_COMPONENT = 3;
+const UI_COMPONENT = manifest.nonTextMinimumContrast;
 
 /**
  * Pairings the framework renders as text, read from the shared data file.
@@ -186,12 +191,18 @@ function contrastRatio(a, b) {
 }
 
 /**
- * The ratio a theme's pairings must reach. AA for normal text by default; a theme may declare
- * a higher floor in `themes.json`, which is how the high-contrast theme's promise is a gate
- * rather than a sentence in its description.
+ * The ratio a theme's pairings must reach — read from the MANIFEST, not from `themes.json`.
+ *
+ * AA for normal text by default; a theme may declare a higher floor in the registry, which is
+ * how the high-contrast theme's promise is a gate rather than a sentence in its description.
+ * The indirection is the point: the manifest publishes an effective floor per theme so the
+ * Studio's theme editor and an agent can hold an app's own palette to the same bar this gate
+ * holds the framework's. Reading it back here means the published floor and the enforced floor
+ * are one number. Re-deriving it from the registry on this side would let the manifest publish
+ * 4.5 for a theme this file measures at 7 and neither would notice.
  */
 const floorFor = (name) =>
-  registry.themes.find((theme) => theme.name === name)?.minimumContrast ?? AA_NORMAL_TEXT;
+  manifest.themes.find((theme) => theme.name === name)?.minimumContrast ?? AA_NORMAL_TEXT;
 
 /**
  * Every pairing in *list*, in every registered theme, tagged with its ratchet key and the

package/src/tokens.css

@@ -7,6 +7,10 @@
      text-field carets) into the light palette so it never renders as foreign
      OS-dark chrome. Each theme block below sets its own. */
   color-scheme: light;
+  /* The appearance as something a stylesheet can branch on — see appearanceSwitch above.
+     color-scheme records the same fact and no selector can read it. */
+  --appearance-show-light: block;
+  --appearance-show-dark: none;
   --color-brand-primary: #2563eb;
   --color-brand-primary-contrast: #ffffff;
   --color-brand-primary-hover: #1d4ed8;
@@ -77,6 +81,9 @@
   --density-compact-control-min-height: 2rem;
   --density-compact-cell-pad-y: 0.5rem;
   --density-compact-cell-pad-x: 0.5rem;
+  --density-comfortable-control-min-height: 2.25rem;
+  --density-comfortable-cell-pad-y: 0.75rem;
+  --density-comfortable-cell-pad-x: 0.75rem;
   --radius-sm: 0.25rem;
   --radius-md: 0.5rem;
   --radius-lg: 0.75rem;
@@ -88,10 +95,16 @@
   --z-index-base: 0;
   --z-index-sticky: 30;
   --z-index-backdrop: 40;
+  --z-index-skip-link: 45;
   --z-index-drawer: 50;
   --z-index-popover: 60;
   --z-index-tooltip: 70;
   --z-index-toast: 100;
+  --shell-sidebar-width-expanded: 15rem;
+  --shell-sidebar-width-collapsed: 4rem;
+  --shell-header-height: 3rem;
+  --shell-content-max-width: 80rem;
+  --shell-brand-size: 1.75rem;
   --breakpoint-sm: 480px;
   --breakpoint-md: 768px;
   --breakpoint-lg: 1024px;
@@ -130,6 +143,8 @@
    The slate-neutral dark counterpart to light, and the theme the OS dark preference selects. */
 [data-theme='dark'] {
   color-scheme: dark;
+  --appearance-show-light: none;
+  --appearance-show-dark: block;
   --color-brand-primary: #1d4ed8;
   --color-brand-primary-contrast: #ffffff;
   --color-brand-primary-hover: #2563eb;
@@ -184,6 +199,8 @@
    A near-black dark for low light and OLED displays: cooler neutrals, a deeper canvas than dark, and a deeper accent that holds a white label at AA. */
 [data-theme='midnight'] {
   color-scheme: dark;
+  --appearance-show-light: none;
+  --appearance-show-dark: block;
   --color-brand-primary: #0b4ea8;
   --color-brand-primary-contrast: #ffffff;
   --color-brand-primary-hover: #1158c7;
@@ -238,6 +255,8 @@
    A warm violet-tinted dark. Its neutrals sit in a different hue family from dark and midnight, which is what proves a theme is a palette rather than a lightness setting. */
 [data-theme='twilight'] {
   color-scheme: dark;
+  --appearance-show-light: none;
+  --appearance-show-dark: block;
   --color-brand-primary: #5b21b6;
   --color-brand-primary-contrast: #ffffff;
   --color-brand-primary-hover: #6d28d9;
@@ -292,6 +311,8 @@
    A high-contrast light theme: white surfaces, near-black text, darkened accents and visible borders. Every declared text pairing reaches AAA, not just AA. Not wired to `prefers-contrast: more` — that needs a dark high-contrast counterpart first, or a user who asked for both more contrast and dark would be handed a light theme. */
 [data-theme='contrast'] {
   color-scheme: light;
+  --appearance-show-light: block;
+  --appearance-show-dark: none;
   --color-brand-primary: #0842a0;
   --color-brand-primary-contrast: #ffffff;
   --color-brand-primary-hover: #05275a;
@@ -346,6 +367,8 @@
 @media (prefers-color-scheme: dark) {
   :root:not([data-theme]) {
     color-scheme: dark;
+    --appearance-show-light: none;
+    --appearance-show-dark: block;
     --color-brand-primary: #1d4ed8;
     --color-brand-primary-contrast: #ffffff;
     --color-brand-primary-hover: #2563eb;

package/src/tokens.manifest.json

@@ -7,31 +7,36 @@
       "name": "light",
       "label": "Light",
       "appearance": "light",
-      "description": "The default. Carries every token, including the geometry the other themes inherit."
+      "description": "The default. Carries every token, including the geometry the other themes inherit.",
+      "minimumContrast": 4.5
     },
     {
       "name": "dark",
       "label": "Dark",
       "appearance": "dark",
-      "description": "The slate-neutral dark counterpart to light, and the theme the OS dark preference selects."
+      "description": "The slate-neutral dark counterpart to light, and the theme the OS dark preference selects.",
+      "minimumContrast": 4.5
     },
     {
       "name": "midnight",
       "label": "Midnight",
       "appearance": "dark",
-      "description": "A near-black dark for low light and OLED displays: cooler neutrals, a deeper canvas than dark, and a deeper accent that holds a white label at AA."
+      "description": "A near-black dark for low light and OLED displays: cooler neutrals, a deeper canvas than dark, and a deeper accent that holds a white label at AA.",
+      "minimumContrast": 4.5
     },
     {
       "name": "twilight",
       "label": "Twilight",
       "appearance": "dark",
-      "description": "A warm violet-tinted dark. Its neutrals sit in a different hue family from dark and midnight, which is what proves a theme is a palette rather than a lightness setting."
+      "description": "A warm violet-tinted dark. Its neutrals sit in a different hue family from dark and midnight, which is what proves a theme is a palette rather than a lightness setting.",
+      "minimumContrast": 4.5
     },
     {
       "name": "contrast",
       "label": "High contrast",
       "appearance": "light",
-      "description": "A high-contrast light theme: white surfaces, near-black text, darkened accents and visible borders. Every declared text pairing reaches AAA, not just AA. Not wired to `prefers-contrast: more` — that needs a dark high-contrast counterpart first, or a user who asked for both more contrast and dark would be handed a light theme."
+      "description": "A high-contrast light theme: white surfaces, near-black text, darkened accents and visible borders. Every declared text pairing reaches AAA, not just AA. Not wired to `prefers-contrast: more` — that needs a dark high-contrast counterpart first, or a user who asked for both more contrast and dark would be handed a light theme.",
+      "minimumContrast": 7
     }
   ],
   "tokens": [
@@ -787,6 +792,30 @@
       },
       "themeable": false
     },
+    {
+      "name": "--density-comfortable-control-min-height",
+      "category": "density",
+      "values": {
+        "light": "2.25rem"
+      },
+      "themeable": false
+    },
+    {
+      "name": "--density-comfortable-cell-pad-y",
+      "category": "density",
+      "values": {
+        "light": "0.75rem"
+      },
+      "themeable": false
+    },
+    {
+      "name": "--density-comfortable-cell-pad-x",
+      "category": "density",
+      "values": {
+        "light": "0.75rem"
+      },
+      "themeable": false
+    },
     {
       "name": "--radius-sm",
       "category": "radius",
@@ -875,6 +904,14 @@
       },
       "themeable": false
     },
+    {
+      "name": "--z-index-skip-link",
+      "category": "zIndex",
+      "values": {
+        "light": "45"
+      },
+      "themeable": false
+    },
     {
       "name": "--z-index-drawer",
       "category": "zIndex",
@@ -907,6 +944,46 @@
       },
       "themeable": false
     },
+    {
+      "name": "--shell-sidebar-width-expanded",
+      "category": "shell",
+      "values": {
+        "light": "15rem"
+      },
+      "themeable": false
+    },
+    {
+      "name": "--shell-sidebar-width-collapsed",
+      "category": "shell",
+      "values": {
+        "light": "4rem"
+      },
+      "themeable": false
+    },
+    {
+      "name": "--shell-header-height",
+      "category": "shell",
+      "values": {
+        "light": "3rem"
+      },
+      "themeable": false
+    },
+    {
+      "name": "--shell-content-max-width",
+      "category": "shell",
+      "values": {
+        "light": "80rem"
+      },
+      "themeable": false
+    },
+    {
+      "name": "--shell-brand-size",
+      "category": "shell",
+      "values": {
+        "light": "1.75rem"
+      },
+      "themeable": false
+    },
     {
       "name": "--breakpoint-sm",
       "category": "breakpoint",
@@ -1164,6 +1241,7 @@
       "themeable": false
     }
   ],
+  "nonTextMinimumContrast": 3,
   "textPairs": [
     {
       "id": "body-on-card",
@@ -1353,6 +1431,13 @@
       "fg": "--color-fg-muted",
       "bg": "--color-status-danger-soft",
       "layer": "semantic"
+    },
+    {
+      "id": "sidebar-nav-link-hover",
+      "label": "a hovered sidebar navigation link",
+      "fg": "--color-sidebar-fg",
+      "bg": "--color-sidebar-accent",
+      "layer": "semantic"
     }
   ],
   "nonTextPairs": [

package/src/tokens.manifest.test.js

@@ -3,6 +3,7 @@ import { fileURLToPath } from "node:url";
 
 import { describe, expect, it } from "vitest";
 
+import { APPEARANCE_MECHANISM_TOKENS } from "./appearance-mechanism.js";
 import { parseRules } from "./css-rules.js";
 
 // The published token manifest: the same tokens as machine-readable data.
@@ -44,8 +45,22 @@ describe("token manifest", () => {
     // Either direction is a real failure: a token missing from the manifest is invisible to
     // every tool that reads it, and a token in the manifest that the sheet does not declare
     // is a control that would silently do nothing.
+    //
+    // The appearance switch is the exception and is subtracted by name. It is the theme's own
+    // `appearance` in the form a stylesheet can branch on, not a value anyone designs, and its
+    // values are `block` / `none` — a theme editor offering that pair offers a way to break the
+    // switch rather than a way to theme anything. The list is exact, so a third such property
+    // has to arrive here and say the same thing about itself.
     const manifestNames = manifest.tokens.map((token) => token.name).sort();
-    expect(manifestNames).toEqual([...base.keys()].sort());
+    const declaredNames = [...base.keys()].filter(
+      (name) => !APPEARANCE_MECHANISM_TOKENS.includes(name),
+    );
+    expect(manifestNames).toEqual(declaredNames.sort());
+    // And they really are declared — subtracting a name that is not there would hide a
+    // manifest gap rather than an exemption.
+    for (const name of APPEARANCE_MECHANISM_TOKENS) {
+      expect(base.has(name), `${name} is not declared on the base root`).toBe(true);
+    }
   });
 
   it("publishes the theme list the sheet was generated from", () => {
@@ -55,11 +70,12 @@ describe("token manifest", () => {
     expect(manifest.base).toBe(registry.base);
     expect(manifest.systemDark).toBe(registry.systemDark);
     expect(manifest.themes).toEqual(
-      registry.themes.map(({ name, label, appearance, description }) => ({
+      registry.themes.map(({ name, label, appearance, description, minimumContrast }) => ({
         name,
         label,
         appearance,
         description,
+        minimumContrast: minimumContrast ?? 4.5,
       })),
     );
     for (const theme of manifest.themes) {
@@ -67,6 +83,37 @@ describe("token manifest", () => {
     }
   });
 
+  it("publishes an effective contrast floor on every theme, never below AA", () => {
+    // The floor is published as a number on EVERY theme, including the four that take the
+    // default, because the consumer this file exists for is a theme editor holding an app's own
+    // palette to the same bar. A field present only on `contrast` would make the other four
+    // "unknown", and a consumer that guesses is a consumer that can disagree with the gate.
+    //
+    // `tokens.contrast.test.js` reads these numbers rather than the registry, so a wrong value
+    // here does not merely mislead a reader — it moves the bar the framework's own palettes are
+    // measured against, and the theme-list assertion above is what stops it from moving.
+    for (const theme of manifest.themes) {
+      expect(typeof theme.minimumContrast, `${theme.name} floor type`).toBe("number");
+      expect(theme.minimumContrast, `${theme.name} floor`).toBeGreaterThanOrEqual(4.5);
+    }
+    // And the mechanism must still be exercised by at least one theme, or "publishes a floor"
+    // decays into publishing the same constant five times.
+    expect(
+      manifest.themes.filter((theme) => theme.minimumContrast > 4.5).map((t) => t.name),
+    ).not.toEqual([]);
+    // The non-text floor is one number for the whole file, not one per theme, because WCAG
+    // defines no AAA tier for non-text contrast. Published at the top level so the two pairing
+    // sections cannot be read as sharing a bar — and asserted as BELOW every text floor, which
+    // is the relationship a consumer would otherwise have to infer.
+    expect(manifest.nonTextMinimumContrast).toBe(3);
+    for (const theme of manifest.themes) {
+      expect(
+        manifest.nonTextMinimumContrast,
+        `${theme.name}: the non-text bar must not exceed the text bar`,
+      ).toBeLessThan(theme.minimumContrast);
+    }
+  });
+
   it("records the value each token resolves to, in every theme", () => {
     // `values` carries only the themes that declare the token; a theme absent from it inherits
     // the base value. That is the cascade stated as data, so both halves are checked: a

package/src/tokens.themes.test.js

@@ -3,6 +3,7 @@ import { fileURLToPath } from "node:url";
 
 import { describe, expect, it } from "vitest";
 
+import { APPEARANCE_MECHANISM_TOKENS } from "./appearance-mechanism.js";
 import { parseRules } from "./css-rules.js";
 
 // The token sheet's theme structure. `tokens.guard.test.ts` in react-core proves every
@@ -132,11 +133,31 @@ describe("token sheet themes", () => {
     // Space, radius, font and shadow are theme-invariant by design: declared once and
     // inherited. Re-declaring one in a single theme is how a theme quietly grows its
     // own spacing scale.
+    //
+    // The appearance switch is the one non-colour that varies per theme, and it is subtracted
+    // by name rather than by a pattern — a prefix exemption would let a whole family through.
     const theme = declarationsFor(selector);
-    const geometry = [...theme.keys()].filter((token) => !isColour(token));
+    const geometry = [...theme.keys()].filter(
+      (token) => !isColour(token) && !APPEARANCE_MECHANISM_TOKENS.includes(token),
+    );
     expect(geometry).toEqual([]);
   });
 
+  it.each(overlayCases)("declares the whole appearance switch in $selector", ({ selector }) => {
+    // The other direction, and the one that matters: half a switch is worse than none. A theme
+    // declaring `show-light` and forgetting `show-dark` inherits the base value for the second,
+    // so a dark theme would display BOTH marks — and the gate above would say nothing, because
+    // subtracting a token from a check is not the same as requiring it.
+    const theme = declarationsFor(selector);
+    const declared = APPEARANCE_MECHANISM_TOKENS.filter((token) => theme.has(token));
+    expect(declared).toEqual(APPEARANCE_MECHANISM_TOKENS);
+    // And exactly one of the two shows, or the switch is not a switch.
+    const shown = APPEARANCE_MECHANISM_TOKENS.filter(
+      (token) => theme.get(token) === "block",
+    );
+    expect(shown).toHaveLength(1);
+  });
+
   it.each([{ name: BASE.name, appearance: BASE.appearance, selector: BASE_SELECTOR }, ...overlayCases])(
     "opts native chrome into the $appearance palette in $selector",
     ({ appearance, selector }) => {

package/token-pairs.json

@@ -1,5 +1,5 @@
 {
-  "$comment": "Token pairings the framework renders, as data, in two sections held to two different bars. `textPairs` are foreground/background pairs painted as TEXT and held to WCAG 2.1 AA for normal text; `nonTextPairs` are the visual boundaries and state indicators SC 1.4.11 asks 3:1 of — a focus indicator, the border that says which control is active, the outline of a control against its surface. Two consumers read both: tokens.contrast.test.js measures each pairing at its own bar, and the generated token manifest publishes them so a theme editor or an agent can tell which tokens must stay legible against which. A pair of token names appears in one section only: the text bar is the stricter of the two, so restating a text pairing under a non-text name would add a case that cannot fail unless the stricter one already has, and would overstate how much the ratchets cover. Purely decorative marks stay absent from both sections — WCAG sets no ratio for a divider or for an aria-hidden ornament, and asserting one would teach the next reader to ignore this file. Names are CSS custom properties because that is the vocabulary a theme author writes and a manifest consumer reads. A pairing earns its place here even when no specimen paints it, and two of them are exactly that: axe measures the pixels a lane renders, so a surface that only appears on a state no specimen can reach - a failed sign-in, a failed create - has no lane coverage at all, and the declared pairing is the only gate it will ever have.",
+  "$comment": "The sidebar's edge (--color-sidebar-border against the canvas) is deliberately NOT declared: WCAG 1.4.11 covers UI components and graphical objects needed to understand content, and a decorative separator beside a sidebar that already differs in background is neither. Declaring it would fail at ~1.2:1 in four themes and the only ways out would be darkening a decorative line everywhere or booking an allowance the ratchet may not grow. Token pairings the framework renders, as data, in two sections held to two different bars. `textPairs` are foreground/background pairs painted as TEXT and held to WCAG 2.1 AA for normal text; `nonTextPairs` are the visual boundaries and state indicators SC 1.4.11 asks 3:1 of — a focus indicator, the border that says which control is active, the outline of a control against its surface. Two consumers read both: tokens.contrast.test.js measures each pairing at its own bar, and the generated token manifest publishes them so a theme editor or an agent can tell which tokens must stay legible against which. A pair of token names appears in one section only: the text bar is the stricter of the two, so restating a text pairing under a non-text name would add a case that cannot fail unless the stricter one already has, and would overstate how much the ratchets cover. Purely decorative marks stay absent from both sections — WCAG sets no ratio for a divider or for an aria-hidden ornament, and asserting one would teach the next reader to ignore this file. Names are CSS custom properties because that is the vocabulary a theme author writes and a manifest consumer reads. A pairing earns its place here even when no specimen paints it, and two of them are exactly that: axe measures the pixels a lane renders, so a surface that only appears on a state no specimen can reach - a failed sign-in, a failed create - has no lane coverage at all, and the declared pairing is the only gate it will ever have.",
   "textPairs": [
     {
       "id": "body-on-card",
@@ -189,6 +189,13 @@
       "fg": "--color-fg-muted",
       "bg": "--color-status-danger-soft",
       "layer": "semantic"
+    },
+    {
+      "id": "sidebar-nav-link-hover",
+      "label": "a hovered sidebar navigation link",
+      "fg": "--color-sidebar-fg",
+      "bg": "--color-sidebar-accent",
+      "layer": "semantic"
     }
   ],
   "nonTextPairs": [

package/tokens.json

@@ -103,6 +103,15 @@
         "padY": { "value": "0.5rem" },
         "padX": { "value": "0.5rem" }
       }
+    },
+    "comfortable": {
+      "control": {
+        "minHeight": { "value": "2.25rem" }
+      },
+      "cell": {
+        "padY": { "value": "0.75rem" },
+        "padX": { "value": "0.75rem" }
+      }
     }
   },
   "radius": {
@@ -121,11 +130,21 @@
     "base": { "value": "0" },
     "sticky": { "value": "30" },
     "backdrop": { "value": "40" },
+    "skipLink": { "value": "45" },
     "drawer": { "value": "50" },
     "popover": { "value": "60" },
     "tooltip": { "value": "70" },
     "toast": { "value": "100" }
   },
+  "shell": {
+    "sidebarWidth": {
+      "expanded": { "value": "15rem" },
+      "collapsed": { "value": "4rem" }
+    },
+    "headerHeight": { "value": "3rem" },
+    "contentMaxWidth": { "value": "80rem" },
+    "brandSize": { "value": "1.75rem" }
+  },
   "breakpoint": {
     "sm": { "value": "480px" },
     "md": { "value": "768px" },