@phis/ui 0.1.0 → 0.2.0

package/theme/phi-theme-mode.d.ts

@@ -2,42 +2,93 @@ import type { PhiThemeMode } from "./phi-theme-presets";
 /**
  * How a viewer wants to see a Site. It is never part of a Theme: a Theme record and its drafts carry
  * only light or dark, the half of the Theme being authored. `system` exists only here, as a person's
- * preference - stored in their user settings once those exist - or as the browser speaking for them.
+ * preference - stored on their account as `user_accounts.theme_mode`, where it is the absence of a
+ * value - or as the browser speaking for them.
  */
 export type PhiThemeModePreference = PhiThemeMode | "system";
 /**
- * The preference of a viewer who has stated none, which today is every viewer: follow the browser.
- * A stored user setting is meant to replace this value where it is read.
+ * The preference of a viewer who has stated none: follow the browser.
+ *
+ * It is what the cookie's absence means, and the cookie mirrors the account, so this is also what an
+ * account with no stored mode resolves to. Somebody who chooses "System" in Settings is choosing this
+ * rather than storing something else.
  */
 export declare const PHI_DEFAULT_THEME_MODE_PREFERENCE: PhiThemeModePreference;
 /**
  * Carries the browser's `prefers-color-scheme` answer from one request to the next, so a viewer on
  * `system` is rendered in the right projection server-side instead of correcting itself after
  * hydration. It holds what the browser reported, never what a person chose.
+ *
+ * It exists only where it changes an answer, and only for as long as it does: written when the browser
+ * says `dark`, deleted when it says anything else, and without an expiry, so it lasts the visit it
+ * helps and leaves nothing behind. `light` is never stored because absence already means it -- see
+ * `resolvePhiThemeMode` -- so the common viewer is asked for no storage at all.
+ *
+ * That is a § 25 TDDDG question and not a preference: keeping something in a device is exempt only
+ * where it is needed for the service somebody asked for, and a year-long copy of a value the browser
+ * repeats on request is hard to call needed. One visit is easy to call needed, because without it every
+ * page of that visit arrives in the wrong projection and corrects itself on screen
+ * ([design/CONSENT.md](../design/CONSENT.md)).
  */
 export declare const PHI_COLOR_SCHEME_COOKIE = "phis_color_scheme";
+/**
+ * What a viewer chose, as against what their browser reported. Absent means they have chosen nothing
+ * and follow the browser, which is why `system` is stored by deleting it rather than as a third value.
+ *
+ * It is a second cookie rather than a second meaning for the first, because the two answer different
+ * questions and the answers can disagree -- somebody reading in a dark room on a light Site is the
+ * whole point of a switch. One value carrying both could not say which of them was the decision.
+ */
+export declare const PHI_THEME_MODE_COOKIE = "phis_theme_mode";
 export declare function normalizePhiThemeModePreference(value: unknown): PhiThemeModePreference;
 /** Reads the cookie value written by the bootstrap script; anything else means "not asked yet". */
 export declare function normalizePhiColorSchemeHint(value: unknown): PhiThemeMode | null;
 /**
  * The one place that decides what a viewer is shown before anyone overrides it live. A stated light
  * or dark preference is kept; `system` follows the browser and falls back to light when the browser
- * states nothing or has not been asked yet. The Theme record's own mode takes no part: a live
- * `themeMode` or `theme` signal - the Builder's switch, a draft preview - is what overrides this, in
- * any Area, and only for as long as the page stays open.
+ * states nothing or has not been asked yet. That fallback is what lets the hint cookie exist only for
+ * `dark`: light needs no cookie because it is what no cookie already means.
+ *
+ * The Theme record's own mode takes no part: a live `themeMode` or `theme` signal - the Builder's
+ * switch, a draft preview - is what overrides this, in any Area, and only for as long as the page
+ * stays open.
  */
 export declare function resolvePhiThemeMode(preference: unknown, browserHint?: PhiThemeMode | null): PhiThemeMode;
 /**
- * Inline script for the document head, emitted only for a viewer on `system`. It marks the root
- * element before first paint and writes the hint cookie, so the very next request already renders
- * the right projection: the first view may still swing once, every later navigation is quiet.
+ * Inline script for the document head, emitted only for a viewer the render believes is on `system`.
+ * It marks the root element before first paint and writes the hint cookie, so the very next request
+ * already renders the right projection: the first view may still swing once, every later navigation
+ * is quiet.
+ *
+ * It asks for the stated preference itself because one render cannot be told it. The static tree is
+ * one document per locale and mode and reads nothing of the request (`createPhiNextStaticRootLayout`);
+ * the proxy picks which of the two a viewer is served, preference first. Marking the root from the
+ * browser's answer alone would undo exactly that pick -- a viewer who chose light on a dark machine
+ * would watch the page turn dark again -- so a stated preference ends the script before anything else.
+ * It writes no hint either: a hint is read only where no preference was stated, so recording one for
+ * somebody who stated theirs would store a value nothing asks for. Going back to `system` writes it
+ * from the live provider, at the moment it starts to matter.
+ *
+ * The light branch deletes rather than stores, which also sweeps the year-long cookie earlier versions
+ * left in a returning browser.
  */
 export declare function buildPhiThemeModeBootstrapScript(preference: PhiThemeModePreference): string | null;
 /**
  * Client-side counterpart of the bootstrap script, for a system preference that changes while the
  * page is open. Writing the hint here keeps the next server render in step with what is on screen.
+ *
+ * Light deletes instead of storing, for the reason on the cookie above: absence is already light, so a
+ * stored `light` would be a value in somebody's device that changes no answer.
  */
 export declare function writePhiColorSchemeHint(mode: PhiThemeMode): void;
+/**
+ * Keeps what a viewer chose, so the next document opens the way the last one closed -- including the
+ * static one, which the proxy picks with this cookie before any script of ours runs.
+ *
+ * Going back to `system` deletes it rather than storing the word, so "follow the browser" is one state
+ * everywhere instead of an absent cookie and a stored value that have to be kept saying the same thing.
+ */
+export declare function writePhiThemeModePreference(preference: PhiThemeModePreference): void;
 /** Keeps `<html>` in step with the projection on screen, including after a live Theme signal. */
 export declare function applyPhiThemeModeToDocument(mode: PhiThemeMode): void;
 /**
@@ -45,3 +96,29 @@ export declare function applyPhiThemeModeToDocument(mode: PhiThemeMode): void;
  * instead of reaching for `next/headers` themselves.
  */
 export declare function readPhiColorSchemeHintFromCookieHeader(cookieHeader?: string | null): PhiThemeMode | null;
+/** The stated preference from the same header; anything but light or dark reads as `system`. */
+export declare function readPhiThemeModePreferenceFromCookieHeader(cookieHeader?: string | null): PhiThemeModePreference;
+/**
+ * The preference a mounted page acts on: the one it was handed, unless that is `system` and the viewer's
+ * cookie says otherwise.
+ *
+ * The static tree is one document per locale and mode for everybody, so it hands every viewer `system`
+ * -- the proxy has already used the cookie to pick which document this viewer gets. Following the
+ * browser from there overrode the choice after hydration: a viewer who chose light on a dark system got
+ * the dark palette back and a `phis_color_scheme=dark` written for the next page.
+ */
+export declare function resolvePhiMountedThemeModePreference(handed: PhiThemeModePreference, cookieHeader?: string | null): PhiThemeModePreference;
+/**
+ * The account's copy of the choice, where there is an account to write it to.
+ *
+ * The switch in a Header is the same setting as the Settings panel, offered in one gesture instead of
+ * three, so it stores in the same place: a signed-in person changing it here should find it changed on
+ * their next browser too (SETTINGS.md, "the same theme choice, stored on the account"). Without a
+ * session the endpoint answers 401 and the cookie written beside this call is the whole answer, which
+ * is the right one for somebody who has no account to remember it in.
+ *
+ * Nothing is awaited by the caller and nothing is reported: the mode is already on screen, the cookie
+ * already carries it, and a failed write means only that the next browser will not know. Saying so
+ * where nobody asked would make a stated preference look like a failed action.
+ */
+export declare function storePhiThemeModePreferenceOnAccount(preference: PhiThemeModePreference): Promise<void>;

package/theme/phi-theme-mode.js

@@ -1,14 +1,38 @@
+import { requestPhiJson } from "../helpers/client-json-request";
 /**
- * The preference of a viewer who has stated none, which today is every viewer: follow the browser.
- * A stored user setting is meant to replace this value where it is read.
+ * The preference of a viewer who has stated none: follow the browser.
+ *
+ * It is what the cookie's absence means, and the cookie mirrors the account, so this is also what an
+ * account with no stored mode resolves to. Somebody who chooses "System" in Settings is choosing this
+ * rather than storing something else.
  */
 export const PHI_DEFAULT_THEME_MODE_PREFERENCE = "system";
 /**
  * Carries the browser's `prefers-color-scheme` answer from one request to the next, so a viewer on
  * `system` is rendered in the right projection server-side instead of correcting itself after
  * hydration. It holds what the browser reported, never what a person chose.
+ *
+ * It exists only where it changes an answer, and only for as long as it does: written when the browser
+ * says `dark`, deleted when it says anything else, and without an expiry, so it lasts the visit it
+ * helps and leaves nothing behind. `light` is never stored because absence already means it -- see
+ * `resolvePhiThemeMode` -- so the common viewer is asked for no storage at all.
+ *
+ * That is a § 25 TDDDG question and not a preference: keeping something in a device is exempt only
+ * where it is needed for the service somebody asked for, and a year-long copy of a value the browser
+ * repeats on request is hard to call needed. One visit is easy to call needed, because without it every
+ * page of that visit arrives in the wrong projection and corrects itself on screen
+ * ([design/CONSENT.md](../design/CONSENT.md)).
  */
 export const PHI_COLOR_SCHEME_COOKIE = "phis_color_scheme";
+/**
+ * What a viewer chose, as against what their browser reported. Absent means they have chosen nothing
+ * and follow the browser, which is why `system` is stored by deleting it rather than as a third value.
+ *
+ * It is a second cookie rather than a second meaning for the first, because the two answer different
+ * questions and the answers can disagree -- somebody reading in a dark room on a light Site is the
+ * whole point of a switch. One value carrying both could not say which of them was the decision.
+ */
+export const PHI_THEME_MODE_COOKIE = "phis_theme_mode";
 export function normalizePhiThemeModePreference(value) {
     return value === "light" || value === "dark" ? value : "system";
 }
@@ -19,9 +43,12 @@ export function normalizePhiColorSchemeHint(value) {
 /**
  * The one place that decides what a viewer is shown before anyone overrides it live. A stated light
  * or dark preference is kept; `system` follows the browser and falls back to light when the browser
- * states nothing or has not been asked yet. The Theme record's own mode takes no part: a live
- * `themeMode` or `theme` signal - the Builder's switch, a draft preview - is what overrides this, in
- * any Area, and only for as long as the page stays open.
+ * states nothing or has not been asked yet. That fallback is what lets the hint cookie exist only for
+ * `dark`: light needs no cookie because it is what no cookie already means.
+ *
+ * The Theme record's own mode takes no part: a live `themeMode` or `theme` signal - the Builder's
+ * switch, a draft preview - is what overrides this, in any Area, and only for as long as the page
+ * stays open.
  */
 export function resolvePhiThemeMode(preference, browserHint) {
     const normalized = normalizePhiThemeModePreference(preference);
@@ -31,31 +58,63 @@ export function resolvePhiThemeMode(preference, browserHint) {
     return browserHint ?? "light";
 }
 /**
- * Inline script for the document head, emitted only for a viewer on `system`. It marks the root
- * element before first paint and writes the hint cookie, so the very next request already renders
- * the right projection: the first view may still swing once, every later navigation is quiet.
+ * Inline script for the document head, emitted only for a viewer the render believes is on `system`.
+ * It marks the root element before first paint and writes the hint cookie, so the very next request
+ * already renders the right projection: the first view may still swing once, every later navigation
+ * is quiet.
+ *
+ * It asks for the stated preference itself because one render cannot be told it. The static tree is
+ * one document per locale and mode and reads nothing of the request (`createPhiNextStaticRootLayout`);
+ * the proxy picks which of the two a viewer is served, preference first. Marking the root from the
+ * browser's answer alone would undo exactly that pick -- a viewer who chose light on a dark machine
+ * would watch the page turn dark again -- so a stated preference ends the script before anything else.
+ * It writes no hint either: a hint is read only where no preference was stated, so recording one for
+ * somebody who stated theirs would store a value nothing asks for. Going back to `system` writes it
+ * from the live provider, at the moment it starts to matter.
+ *
+ * The light branch deletes rather than stores, which also sweeps the year-long cookie earlier versions
+ * left in a returning browser.
  */
 export function buildPhiThemeModeBootstrapScript(preference) {
     if (preference !== "system") {
         return null;
     }
     return `(function(){try{` +
+        `if(/(?:^|;\\s*)${PHI_THEME_MODE_COOKIE}=(?:light|dark)(?:;|$)/.test(document.cookie)){return;}` +
         `var d=window.matchMedia('(prefers-color-scheme: dark)').matches;` +
         `var m=d?'dark':'light';` +
+        `if(d){if(document.cookie.indexOf('${PHI_COLOR_SCHEME_COOKIE}=dark')<0){` +
+        `document.cookie='${PHI_COLOR_SCHEME_COOKIE}=dark;path=/;samesite=lax';}}` +
+        `else if(document.cookie.indexOf('${PHI_COLOR_SCHEME_COOKIE}=')>=0){` +
+        `document.cookie='${PHI_COLOR_SCHEME_COOKIE}=;path=/;max-age=0;samesite=lax';}` +
         `var r=document.documentElement;` +
         `r.dataset.phiThemeMode=m;` +
         `r.style.colorScheme=m;` +
-        `if(document.cookie.indexOf('${PHI_COLOR_SCHEME_COOKIE}='+m)<0){` +
-        `document.cookie='${PHI_COLOR_SCHEME_COOKIE}='+m+';path=/;max-age=31536000;samesite=lax';}` +
         `}catch(e){}})();`;
 }
 /**
  * Client-side counterpart of the bootstrap script, for a system preference that changes while the
  * page is open. Writing the hint here keeps the next server render in step with what is on screen.
+ *
+ * Light deletes instead of storing, for the reason on the cookie above: absence is already light, so a
+ * stored `light` would be a value in somebody's device that changes no answer.
  */
 export function writePhiColorSchemeHint(mode) {
-    document.cookie =
-        `${PHI_COLOR_SCHEME_COOKIE}=${mode};path=/;max-age=31536000;samesite=lax`;
+    document.cookie = mode === "dark"
+        ? `${PHI_COLOR_SCHEME_COOKIE}=dark;path=/;samesite=lax`
+        : `${PHI_COLOR_SCHEME_COOKIE}=;path=/;max-age=0;samesite=lax`;
+}
+/**
+ * Keeps what a viewer chose, so the next document opens the way the last one closed -- including the
+ * static one, which the proxy picks with this cookie before any script of ours runs.
+ *
+ * Going back to `system` deletes it rather than storing the word, so "follow the browser" is one state
+ * everywhere instead of an absent cookie and a stored value that have to be kept saying the same thing.
+ */
+export function writePhiThemeModePreference(preference) {
+    document.cookie = preference === "system"
+        ? `${PHI_THEME_MODE_COOKIE}=;path=/;max-age=0;samesite=lax`
+        : `${PHI_THEME_MODE_COOKIE}=${preference};path=/;max-age=31536000;samesite=lax`;
 }
 /** Keeps `<html>` in step with the projection on screen, including after a live Theme signal. */
 export function applyPhiThemeModeToDocument(mode) {
@@ -63,11 +122,8 @@ export function applyPhiThemeModeToDocument(mode) {
     root.dataset.phiThemeMode = mode;
     root.style.colorScheme = mode;
 }
-/**
- * Picks the hint out of a raw `Cookie` request header, for the server helpers that are handed one
- * instead of reaching for `next/headers` themselves.
- */
-export function readPhiColorSchemeHintFromCookieHeader(cookieHeader) {
+/** One pass over a raw `Cookie` header, for the readers below. */
+function readCookieValue(cookieHeader, name) {
     if (!cookieHeader) {
         return null;
     }
@@ -76,9 +132,62 @@ export function readPhiColorSchemeHintFromCookieHeader(cookieHeader) {
         if (separator < 0) {
             continue;
         }
-        if (part.slice(0, separator).trim() === PHI_COLOR_SCHEME_COOKIE) {
-            return normalizePhiColorSchemeHint(part.slice(separator + 1).trim());
+        if (part.slice(0, separator).trim() === name) {
+            return part.slice(separator + 1).trim();
         }
     }
     return null;
 }
+/**
+ * Picks the hint out of a raw `Cookie` request header, for the server helpers that are handed one
+ * instead of reaching for `next/headers` themselves.
+ */
+export function readPhiColorSchemeHintFromCookieHeader(cookieHeader) {
+    return normalizePhiColorSchemeHint(readCookieValue(cookieHeader, PHI_COLOR_SCHEME_COOKIE));
+}
+/** The stated preference from the same header; anything but light or dark reads as `system`. */
+export function readPhiThemeModePreferenceFromCookieHeader(cookieHeader) {
+    return normalizePhiThemeModePreference(readCookieValue(cookieHeader, PHI_THEME_MODE_COOKIE));
+}
+/**
+ * The preference a mounted page acts on: the one it was handed, unless that is `system` and the viewer's
+ * cookie says otherwise.
+ *
+ * The static tree is one document per locale and mode for everybody, so it hands every viewer `system`
+ * -- the proxy has already used the cookie to pick which document this viewer gets. Following the
+ * browser from there overrode the choice after hydration: a viewer who chose light on a dark system got
+ * the dark palette back and a `phis_color_scheme=dark` written for the next page.
+ */
+export function resolvePhiMountedThemeModePreference(handed, cookieHeader) {
+    return handed !== "system" ? handed : readPhiThemeModePreferenceFromCookieHeader(cookieHeader);
+}
+/**
+ * The account's copy of the choice, where there is an account to write it to.
+ *
+ * The switch in a Header is the same setting as the Settings panel, offered in one gesture instead of
+ * three, so it stores in the same place: a signed-in person changing it here should find it changed on
+ * their next browser too (SETTINGS.md, "the same theme choice, stored on the account"). Without a
+ * session the endpoint answers 401 and the cookie written beside this call is the whole answer, which
+ * is the right one for somebody who has no account to remember it in.
+ *
+ * Nothing is awaited by the caller and nothing is reported: the mode is already on screen, the cookie
+ * already carries it, and a failed write means only that the next browser will not know. Saying so
+ * where nobody asked would make a stated preference look like a failed action.
+ */
+export async function storePhiThemeModePreferenceOnAccount(preference) {
+    try {
+        /*
+         * A preference that cannot be saved stays applied for this visit. The cookie already carries it, so
+         * there is nothing to tell somebody who only changed how the page looks -- whether the token, the
+         * network or the session was missing, and whatever the answer says.
+         */
+        await requestPhiJson("/api/auth/profile/theme", {
+            method: "PATCH",
+            body: { themeMode: preference },
+            csrf: true,
+        });
+    }
+    catch {
+        // Offline, or no session. The cookie stands; see above for why this stays quiet.
+    }
+}

package/theme/phi-theme-placeholder-logo.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The Logo a phis installation ships with: an empty frame with "your logo" in it, one per mode.
+ *
+ * A Set carries a Logo and the core Set is what a Site that has stated nothing runs on, so whatever
+ * stands here is the mark every fresh installation wears until somebody replaces it. That is exactly
+ * why it is not a mark. A real one belongs to whoever owns it, and putting ours there would both brand
+ * somebody else's Site and read as a decision rather than as a blank waiting to be filled. A dashed
+ * frame reads as a blank.
+ *
+ * Three to one, the shape a wordmark tends to have, so that replacing it moves nothing around it. Drawn
+ * in the mode's own text base at less than full strength: legible, and quiet enough that nobody mistakes
+ * it for a design.
+ *
+ * Inline, and URL-encoded rather than base64 so the drawing stays readable next to what uses it. A Set
+ * lives in code; the save that takes a Logo into a Site's record uploads it into the Media library, so
+ * no Site depends on this file for a Logo it kept.
+ */
+export declare const PHI_THEME_PLACEHOLDER_LOGO_LIGHT: string;
+export declare const PHI_THEME_PLACEHOLDER_LOGO_DARK: string;

package/theme/phi-theme-placeholder-logo.js

@@ -0,0 +1,31 @@
+/**
+ * The Logo a phis installation ships with: an empty frame with "your logo" in it, one per mode.
+ *
+ * A Set carries a Logo and the core Set is what a Site that has stated nothing runs on, so whatever
+ * stands here is the mark every fresh installation wears until somebody replaces it. That is exactly
+ * why it is not a mark. A real one belongs to whoever owns it, and putting ours there would both brand
+ * somebody else's Site and read as a decision rather than as a blank waiting to be filled. A dashed
+ * frame reads as a blank.
+ *
+ * Three to one, the shape a wordmark tends to have, so that replacing it moves nothing around it. Drawn
+ * in the mode's own text base at less than full strength: legible, and quiet enough that nobody mistakes
+ * it for a design.
+ *
+ * Inline, and URL-encoded rather than base64 so the drawing stays readable next to what uses it. A Set
+ * lives in code; the save that takes a Logo into a Site's record uploads it into the Media library, so
+ * no Site depends on this file for a Logo it kept.
+ */
+/** The mode's text base, as `PHI_CORE_THEME_PRESET_PLUGINS` states it. */
+const LIGHT_INK = "#223A61";
+const DARK_INK = "#DCE7F8";
+function placeholderLogo(ink) {
+    const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 480 160" width="480" height="160">`
+        + `<rect x="6" y="6" width="468" height="148" rx="13" fill="none"`
+        + ` stroke="${ink}" stroke-opacity=".45" stroke-width="6" stroke-dasharray="21 13"/>`
+        + `<text x="240" y="80" fill="${ink}" fill-opacity=".7" font-size="52" font-weight="600"`
+        + ` font-family="system-ui, sans-serif" text-anchor="middle" dominant-baseline="central">your logo</text>`
+        + `</svg>`;
+    return `data:image/svg+xml,${encodeURIComponent(svg)}`;
+}
+export const PHI_THEME_PLACEHOLDER_LOGO_LIGHT = placeholderLogo(LIGHT_INK);
+export const PHI_THEME_PLACEHOLDER_LOGO_DARK = placeholderLogo(DARK_INK);

package/theme/phi-theme-presets.d.ts

@@ -73,12 +73,18 @@ export declare const PHI_CORE_THEME_PRESET_PLUGINS: readonly [{
                     readonly colorTextBase: "#223A61";
                     readonly colorBgBase: "#ffffff";
                 };
+                readonly overrides: {
+                    readonly colorFillQuaternary: "rgba(34, 58, 97, 0.03)";
+                };
             };
             readonly dark: {
                 readonly seed: {
                     readonly colorTextBase: "#DCE7F8";
                     readonly colorBgBase: "#050914";
                 };
+                readonly overrides: {
+                    readonly colorFillQuaternary: "rgba(220, 231, 248, 0.06)";
+                };
             };
         };
     };

package/theme/phi-theme-presets.js

@@ -1,3 +1,4 @@
+import { assertPhiThemeVocabulary } from "./phi-theme-tokens";
 /**
  * The seeds that belong to a mode rather than to the palette as a whole.
  *
@@ -51,12 +52,37 @@ export const PHI_CORE_THEME_PRESET_PLUGINS = [
                         colorTextBase: "#223A61",
                         colorBgBase: "#ffffff",
                     },
+                    /*
+                     * The quietest filling, stated rather than derived.
+                     *
+                     * Ant Design derives it as the base text colour at 2% (`themes/default/colors.js`), and at two
+                     * per cent of a deep blue on white nothing is there: the ground of a Collapsible title, a
+                     * striped Table row and a Tree's alternating row all read as plain background, and the surface
+                     * that was supposed to separate itself from the page did not. Half again as much is enough to
+                     * see and still quiet.
+                     *
+                     * Half again, and not more, because the four fillings are a LADDER -- 0.15, 0.06, 0.04, 0.02 in
+                     * this mode -- and this is its lowest rung. Anything from 0.04 up would put the quietest
+                     * filling level with or above the one above it, and a ground meant to recede would start
+                     * shouting over the one that is meant to carry a hover.
+                     */
+                    overrides: {
+                        colorFillQuaternary: "rgba(34, 58, 97, 0.03)",
+                    },
                 },
                 dark: {
                     seed: {
                         colorTextBase: "#DCE7F8",
                         colorBgBase: "#050914",
                     },
+                    /*
+                     * The same step in the dark, where the ladder is 0.18, 0.12, 0.08, 0.04 and the rung above is
+                     * therefore twice as far away. A pale blue over near-black carries further than a deep blue
+                     * over white, so the same proportion -- half again -- lands at 0.06 and stays clear of 0.08.
+                     */
+                    overrides: {
+                        colorFillQuaternary: "rgba(220, 231, 248, 0.06)",
+                    },
                 },
             },
         },
@@ -118,5 +144,20 @@ export function resolvePhiThemePaletteTokens(palette, mode) {
  * one function so the two can never disagree.
  */
 export function resolvePhiThemeColorTokens(preset, sitePalette, mode) {
+    /*
+     * Held to the vocabulary here, and the two sides separately, because this is where they are still
+     * telling apart: once they are merged a bad key belongs to nobody. Every colour consumer comes
+     * through this function, so a Theme is read the same strict way whoever asks.
+     */
+    assertPhiThemeVocabulary({
+        palette: preset.palette,
+        modeSeedKeys: PHI_THEME_PALETTE_MODE_SEED_KEYS,
+        source: `The Theme palette block "${preset.key}"`,
+    });
+    assertPhiThemeVocabulary({
+        palette: sitePalette,
+        modeSeedKeys: PHI_THEME_PALETTE_MODE_SEED_KEYS,
+        source: "The Site's own Theme",
+    });
     return resolvePhiThemePaletteTokens(mergePhiThemePalettes(preset.palette, sitePalette), mode);
 }

package/theme/phi-theme-runtime.js

@@ -35,7 +35,7 @@ export function resolvePhiThemeRuntimePayload(theme, catalog = PHI_CORE_THEME_BL
             fonts: resolvePhiThemeEffectiveFonts(theme?.fonts, composition.fonts),
             brand: {
                 ...(theme?.brand ?? {}),
-                logo: resolvePhiThemeEffectiveLogo(theme?.brand?.logo, composition.logoSet),
+                logo: resolvePhiThemeEffectiveLogo(theme?.brand?.logo, composition.markSet),
             },
             style: {
                 ...(theme?.style ?? {}),

package/theme/phi-theme-tokens.d.ts

@@ -0,0 +1,79 @@
+import type { GlobalToken } from "antd/es/theme/interface";
+import type { PhiThemePalette } from "./phi-theme-presets";
+/**
+ * The token vocabulary of this house, stated once.
+ *
+ * The names are Ant Design's spelling and they stay that way: `colorPrimary`, `paddingSM` and
+ * `controlHeight` are this house's words too, a Site has them stored under those names, and the
+ * Theme workspace writes them under those names. Nothing here renames anything.
+ *
+ * What this file adds is the boundary. Until it existed the Client read from `GlobalToken`, an open
+ * surface of some four hundred names, so the ones actually in use were an accident of what somebody
+ * typed rather than something the package promised. Below is the promise: every name a render may
+ * read, and no other. A Widget that wants one that is not here adds it here first, which is the
+ * moment somebody decides whether the house has that word.
+ *
+ * The value types come from Ant Design, and deliberately only in the line that derives them. That is
+ * the bridge in one place and it is also the drift check: a name Ant Design drops or renames stops
+ * compiling here, in the list, rather than in the forty files that read it. When Ant Design is one day
+ * swapped out, this derivation becomes an explicit record and nothing above it moves -- the names are
+ * the contract, the thing that computes their values is not.
+ *
+ * Who may still speak Ant Design directly is a separate question, and `scripts/validate-control-boundaries.mjs`
+ * answers it: the alias resolver, the root adapter, the two font helpers and this file.
+ */
+export declare const PHI_THEME_TOKEN_KEYS: readonly ["colorBgContainer", "colorBgElevated", "colorBgMask", "colorBgSpotlight", "colorBorder", "colorBorderSecondary", "colorSplit", "colorFillAlter", "colorFill", "colorBgLayout", "colorFillQuaternary", "colorFillSecondary", "colorFillTertiary", "colorText", "colorTextBase", "colorTextHeading", "colorTextSecondary", "colorTextTertiary", "colorTextQuaternary", "colorTextDescription", "colorTextDisabled", "colorTextLabel", "colorTextPlaceholder", "colorTextLightSolid", "colorPrimary", "colorPrimaryBg", "colorPrimaryBgHover", "colorPrimaryBorder", "colorPrimaryBorderHover", "colorPrimaryHover", "colorPrimaryActive", "colorPrimaryText", "colorPrimaryTextHover", "colorPrimaryTextActive", "colorInfo", "colorInfoBg", "colorInfoBgHover", "colorInfoBorder", "colorInfoBorderHover", "colorInfoText", "colorInfoTextHover", "colorSuccess", "colorSuccessBg", "colorSuccessBgHover", "colorSuccessBorderHover", "colorSuccessText", "colorWarning", "colorWarningBg", "colorWarningBgHover", "colorWarningBorderHover", "colorWarningText", "colorError", "colorErrorBg", "colorErrorText", "colorErrorTextHover", "colorErrorTextActive", "colorLink", "colorLinkHover", "colorLinkActive", "padding", "paddingXXS", "paddingXS", "paddingSM", "paddingMD", "paddingLG", "paddingXL", "margin", "marginXXS", "marginXS", "marginSM", "marginMD", "marginLG", "marginXL", "marginXXL", "sizeXS", "sizeSM", "sizeMD", "sizeLG", "borderRadius", "borderRadiusXS", "borderRadiusSM", "borderRadiusLG", "borderRadiusOuter", "lineWidth", "lineType", "boxShadow", "boxShadowSecondary", "boxShadowTertiary", "controlHeight", "controlHeightSM", "controlHeightLG", "fontFamily", "fontFamilyCode", "fontSize", "fontSizeSM", "fontSizeLG", "fontSizeXL", "fontSizeHeading1", "fontSizeHeading2", "fontSizeHeading3", "fontSizeHeading4", "fontSizeHeading5", "fontWeightStrong", "lineHeight", "lineHeightLG", "lineHeightHeading1", "lineHeightHeading2", "lineHeightHeading3", "lineHeightHeading4", "lineHeightHeading5", "motionDurationMid", "motionDurationSlow", "motionEaseInOut", "motionEaseOut"];
+/**
+ * The names this house adds to Ant Design's set.
+ *
+ * `buildPhiThemeTokens` hands Ant Design the whole structural scale, `paddingXXL` included, and the
+ * cssVar pass emits a variable for every token it is given -- so `--ant-padding-xxl` is on the page
+ * even though `AliasToken` has no such field. The name is therefore real, usable from CSS, and
+ * invisible to the type, which is exactly why it has to be stated somewhere.
+ *
+ * It is a separate list and not one more entry above, because `PhiThemeTokens` is cut from Ant
+ * Design's type and a name Ant Design does not know cannot be cut from it. A Client Component that
+ * needs one of these reads it as a CSS variable, the way a Server Component does.
+ */
+export declare const PHI_THEME_OWN_TOKEN_KEYS: readonly ["paddingXXL"];
+export type PhiThemeTokenKey = (typeof PHI_THEME_TOKEN_KEYS)[number];
+/**
+ * The resolved Theme, in the names above and their Ant Design value types.
+ *
+ * This is what `usePhiConfig().token` hands a Client Component and what the Server's own token record
+ * is cut from, so both sides read one list rather than two that drift.
+ */
+export type PhiThemeTokens = Pick<GlobalToken, PhiThemeTokenKey>;
+/**
+ * The colours a palette seeds, shared by both modes.
+ *
+ * Ant Design derives the rest from these six. Everything else a palette wants to say outright is an
+ * override, which is held to the vocabulary above -- the difference matters, because a seed is an
+ * input to the derivation and an override is a result of it stated by hand.
+ */
+export declare const PHI_THEME_PALETTE_SEED_KEYS: readonly ["colorPrimary", "colorInfo", "colorSuccess", "colorWarning", "colorError", "colorLink"];
+/**
+ * What `style.token` may hold beyond the vocabulary: Ant Design's own seed flags.
+ *
+ * `wireframe` is not a token with a value on the page, it is the switch that decides how Ant Design
+ * derives the rest. The Theme workspace writes it, so a Site has it stored, so it is said here.
+ */
+export declare const PHI_THEME_STYLE_SEED_KEYS: readonly ["wireframe"];
+/**
+ * A stored Theme, held to the vocabulary before anything is derived from it.
+ *
+ * Read strictly, the way a stored Widget config is: a name this package does not have is a mistake
+ * somebody made, and deriving a Theme past it hides the mistake -- the page comes up, nothing reports
+ * anything, and one thing an author set is simply not there. The throw names the key and where it
+ * stood, because a Theme is folded from several places and "colorPrimry" says nothing about which.
+ *
+ * Mode seeds are checked against `PHI_THEME_PALETTE_MODE_SEED_KEYS`, which is the list that already
+ * decides what belongs to a mode rather than to the palette as a whole.
+ */
+export declare function assertPhiThemeVocabulary({ palette, styleToken, modeSeedKeys, source, }: {
+    palette?: PhiThemePalette | null;
+    styleToken?: Record<string, unknown> | null;
+    modeSeedKeys: readonly string[];
+    /** What is being read -- a Site record, a Module's block -- so the message can say whose key it is. */
+    source: string;
+}): void;