@multiplatform.one/theme 6.4.0 → 6.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multiplatform.one/theme",
-  "version": "6.4.0",
+  "version": "6.4.2",
   "description": "Tamagui theme system for multiplatform.one",
   "keywords": [
     "multiplatform",
@@ -53,8 +53,8 @@
     "@tamagui/toast": "2.0.0-rc.41",
     "@tamagui/web": "2.0.0-rc.41",
     "react-cookie": "^8.1.2",
-    "@multiplatform.one/store": "6.4.0",
-    "@multiplatform.one/platform": "6.4.0"
+    "@multiplatform.one/platform": "6.4.2",
+    "@multiplatform.one/store": "6.4.2"
   },
   "devDependencies": {
     "@tamagui/animations-css": "2.0.0-rc.41",
@@ -69,8 +69,8 @@
     "tamagui": "2.0.0-rc.41",
     "typescript": "~5.9.3",
     "vitest": "^4.1.5",
-    "@multiplatform.one/config": "6.4.0",
-    "@multiplatform.one/test-utils": "6.4.0"
+    "@multiplatform.one/config": "6.4.2",
+    "@multiplatform.one/test-utils": "6.4.2"
   },
   "peerDependencies": {
     "@tamagui/animations-css": "^2.0.0-rc",

package/src/dates.ts

@@ -12,6 +12,11 @@
  *                          current year elided (`year: "auto"`)
  *   - editing surfaces   → compact absolute with the year always shown
  *                          ("Jul 1, 2026") — pickers are precision contexts
+ *   - calendar chrome    → the day/month/time-of-day registers below
+ *                          (weekday and month names, "2 PM" hour ticks,
+ *                          "2:00 PM" times, "Tuesday, March 10" day names)
+ *   - date axis ticks    → compact absolute with `year: "never"`, because
+ *                          the surrounding chrome already states the year
  * No default may emit verbose locale output with seconds.
  */
 
@@ -21,9 +26,11 @@ export interface AbsoluteDateFormatOptions {
   /**
    * `"auto"` (default) elides the current year — the display register for
    * tables, feeds, and system events. `"always"` keeps it — the editing
-   * register for picker display values.
+   * register for picker display values. `"never"` drops it — the axis-tick
+   * register, where a wider label would collide with its neighbours and the
+   * period header carries the year.
    */
-  year?: "auto" | "always";
+  year?: "auto" | "always" | "never";
   /** Include the time component ("Aug 9, 3:30 PM"). Default false. */
   withTime?: boolean;
   /** BCP-47 locale forwarded to Intl. Default: system locale. */
@@ -78,7 +85,7 @@ export function formatAbsoluteDate(
     month: "short",
     day: "numeric",
   };
-  if (year === "always" || displayYear !== referenceYear) {
+  if (year === "always" || (year !== "never" && displayYear !== referenceYear)) {
     intlOptions.year = "numeric";
   }
   if (withTime) {
@@ -128,3 +135,134 @@ export function formatRelativeTimestamp(value: DateInput, now: number = Date.now
   const yr = Math.floor(day / 365);
   return `${Math.max(1, yr)}y ago`;
 }
+
+/** Clock-time shape ("HH:MM" / "HH:MM:SS") — how Frappe `Time` values arrive. */
+export const CLOCK_TIME = /^(\d{1,2}):(\d{2})(?::(\d{2}))?$/;
+
+export interface TimeOfDayFormatOptions {
+  /** BCP-47 locale forwarded to Intl. Default: system locale. */
+  locale?: string;
+  /** Minutes ride along by default; `false` is the hour-tick register. */
+  minutes?: boolean;
+  /** Pin the 12/24-hour clock. Default: whatever the locale uses. */
+  hour12?: boolean;
+}
+
+/**
+ * Time-of-day register ("2:00 PM", or "2 PM" with `minutes: false` for
+ * hour ticks) — calendar time grids, Frappe `Time` fields, and
+ * "last updated" chrome. Accepts a clock-time string as well as a date,
+ * and never emits seconds.
+ */
+export function formatTimeOfDay(value: DateInput, options: TimeOfDayFormatOptions = {}): string {
+  const { locale, minutes = true, hour12 } = options;
+  let date: Date | null = null;
+  if (typeof value === "string") {
+    const clock = value.trim().match(CLOCK_TIME);
+    if (clock) {
+      const parsed = new Date(2000, 0, 1, Number(clock[1]), Number(clock[2]));
+      if (!Number.isNaN(parsed.getTime())) date = parsed;
+    }
+  }
+  if (!date) {
+    const coerced = coerceDateInput(value);
+    if (!coerced) return typeof value === "string" ? value : "";
+    date = coerced.date;
+  }
+  const intlOptions: Intl.DateTimeFormatOptions = { hour: "numeric" };
+  if (minutes) intlOptions.minute = "2-digit";
+  if (hour12 !== undefined) intlOptions.hour12 = hour12;
+  try {
+    return date.toLocaleTimeString(locale, intlOptions);
+  } catch {
+    return typeof value === "string" ? value : "";
+  }
+}
+
+export interface DayLongFormatOptions {
+  locale?: string;
+  /** Lead with the weekday ("Tuesday, March 10"). Default true. */
+  weekday?: boolean;
+  /** Append the year ("Tuesday, March 10, 2026"). Default false. */
+  year?: boolean;
+}
+
+/**
+ * Long day register ("Tuesday, March 10") — calendar day headers and the
+ * accessible names that read a date aloud, where the compact absolute
+ * register is too terse to speak.
+ */
+export function formatDayLong(value: DateInput, options: DayLongFormatOptions = {}): string {
+  const coerced = coerceDateInput(value);
+  if (!coerced) return typeof value === "string" ? value : "";
+  const { locale, weekday = true, year = false } = options;
+  const intlOptions: Intl.DateTimeFormatOptions = { month: "long", day: "numeric" };
+  if (weekday) intlOptions.weekday = "long";
+  if (year) intlOptions.year = "numeric";
+  if (coerced.dateOnly) intlOptions.timeZone = "UTC";
+  try {
+    return coerced.date.toLocaleDateString(locale, intlOptions);
+  } catch {
+    return typeof value === "string" ? value : "";
+  }
+}
+
+export interface MonthYearFormatOptions {
+  locale?: string;
+  /** `"short"` ("Mar 2026", the tick register) or `"long"` ("March 2026"). */
+  month?: "short" | "long";
+}
+
+/** Month-year register ("Mar 2026") — period headers and month axis ticks. */
+export function formatMonthYear(value: DateInput, options: MonthYearFormatOptions = {}): string {
+  const coerced = coerceDateInput(value);
+  if (!coerced) return typeof value === "string" ? value : "";
+  const { locale, month = "short" } = options;
+  const intlOptions: Intl.DateTimeFormatOptions = { month, year: "numeric" };
+  if (coerced.dateOnly) intlOptions.timeZone = "UTC";
+  try {
+    return coerced.date.toLocaleDateString(locale, intlOptions);
+  } catch {
+    return typeof value === "string" ? value : "";
+  }
+}
+
+/** Day-of-month register ("10") — the densest date axis tick. */
+export function formatDayOfMonth(value: DateInput, options: { locale?: string } = {}): string {
+  const coerced = coerceDateInput(value);
+  if (!coerced) return typeof value === "string" ? value : "";
+  const intlOptions: Intl.DateTimeFormatOptions = { day: "numeric" };
+  if (coerced.dateOnly) intlOptions.timeZone = "UTC";
+  try {
+    return coerced.date.toLocaleDateString(options.locale, intlOptions);
+  } catch {
+    return String(coerced.date.getDate());
+  }
+}
+
+export interface WeekdayNamesOptions {
+  locale?: string;
+  /** `"short"` ("Mon"), `"long"` ("Monday") or `"narrow"` ("M"). */
+  style?: "short" | "long" | "narrow";
+  /** Week start, 0 = Sunday (default) — the index base callers rely on. */
+  firstDay?: number;
+}
+
+/** Weekday names for calendar chrome, in week order from `firstDay`. */
+export function getWeekdayNames(options: WeekdayNamesOptions = {}): string[] {
+  const { locale, style = "short", firstDay = 0 } = options;
+  const formatter = new Intl.DateTimeFormat(locale, { weekday: style, timeZone: "UTC" });
+  // 2004-01-04 is a Sunday, so day-of-week and offset line up.
+  return Array.from({ length: 7 }, (_, i) =>
+    formatter.format(new Date(Date.UTC(2004, 0, 4 + ((firstDay + i) % 7)))),
+  );
+}
+
+/** Month names for calendar chrome and picker headers, January first. */
+export function getMonthNames(
+  options: { locale?: string; style?: "long" | "short" } = {},
+): string[] {
+  const { locale, style = "long" } = options;
+  const formatter = new Intl.DateTimeFormat(locale, { month: style, timeZone: "UTC" });
+  return Array.from({ length: 12 }, (_, i) => formatter.format(new Date(Date.UTC(2000, i, 1))));
+}

package/src/index.ts

@@ -1,5 +1,6 @@
 export * from "./theme/index";
 export * from "./dates";
+export * from "./numbers";
 export * from "./devWarn";
 export * from "./keyboardFocusRing";
 export * from "./menuRow";

package/src/numbers.ts

@@ -0,0 +1,161 @@
+/**
+ * Canonical number / currency registers (LC-12 render channel, Axiom 9).
+ *
+ * One formatter owns every number the catalog renders — table aggregates,
+ * KPI values, report cells, chart value labels — so the same data class
+ * never speaks in two voices ("15400" in a group header beside "15,400" in
+ * the cell two rows below).
+ *
+ * Content class picks the register:
+ *   - cardinal / aggregate → `formatNumber` (grouped, ≤2 fraction digits)
+ *   - money                → `formatCurrency` (grouped, 2 fraction digits;
+ *                            `fractionDigits: "auto"` elides a whole-value
+ *                            `.00` for summary tiles)
+ *   - rate                 → `formatPercent` (value already carries percent
+ *                            units: 94.2 → "94.2%")
+ *
+ * Not covered (declared exemptions): chart AXIS tick labels, whose
+ * density-driven register is owned by `charts/math.ts#formatAxisTick`;
+ * app-land `useFormatNumber` / `useFormatCurrency` (i18n package), which
+ * bind the active UI language outside the catalog; and machine formats
+ * (export/serialization).
+ */
+
+export type NumberInput = number | string | null | undefined;
+
+export interface NumberFormatOptions {
+  /** BCP-47 locale forwarded to Intl. Default: system locale. */
+  locale?: string;
+  /** Pins min and max fraction digits together (fixed-precision columns). */
+  precision?: number;
+  minimumFractionDigits?: number;
+  /** House cap for the cardinal register. Default 2. */
+  maximumFractionDigits?: number;
+  /** Thousands grouping. Default true. */
+  grouping?: boolean;
+}
+
+export interface CurrencyFormatOptions extends NumberFormatOptions {
+  /** ISO 4217 code, e.g. "USD" — renders through Intl's currency style. */
+  currency?: string;
+  /**
+   * Currency symbol as handed over by Frappe-style adapters. Resolved to an
+   * ISO code when known, otherwise prefixed literally.
+   */
+  symbol?: string;
+  /**
+   * `"always"` (default) pins 2 fraction digits — the money register that
+   * keeps columns aligned. `"auto"` drops them for whole values — the
+   * summary-tile register (KPI cards read "$48,250", not "$48,250.00")
+   * while still showing cents when a value has them.
+   */
+  fractionDigits?: "always" | "auto";
+}
+
+export type PercentFormatOptions = NumberFormatOptions;
+
+/** Frappe adapters hand over a symbol; Intl's currency style wants a code. */
+const CURRENCY_SYMBOL_TO_CODE: Record<string, string> = {
+  $: "USD",
+  "€": "EUR",
+  "£": "GBP",
+  "¥": "JPY",
+  "₹": "INR",
+  "₩": "KRW",
+};
+
+/**
+ * ISO 4217 code for a currency symbol (or a code passed straight through).
+ * `undefined` when the symbol has no known code — callers prefix it.
+ */
+export function resolveCurrencyCode(symbol: string | undefined): string | undefined {
+  if (!symbol) return undefined;
+  if (/^[A-Za-z]{3}$/.test(symbol)) return symbol.toUpperCase();
+  return CURRENCY_SYMBOL_TO_CODE[symbol];
+}
+
+interface CoercedNumber {
+  num: number;
+}
+
+function coerceNumberInput(value: NumberInput): CoercedNumber | null {
+  if (value == null || value === "") return null;
+  if (typeof value === "number") return Number.isFinite(value) ? { num: value } : null;
+  const num = Number(value);
+  return Number.isFinite(num) ? { num } : null;
+}
+
+function resolveDigits(options: NumberFormatOptions): Pick<
+  Intl.NumberFormatOptions,
+  "minimumFractionDigits" | "maximumFractionDigits"
+> {
+  const { precision, minimumFractionDigits, maximumFractionDigits } = options;
+  if (precision != null) {
+    return { minimumFractionDigits: precision, maximumFractionDigits: precision };
+  }
+  const max = maximumFractionDigits ?? 2;
+  const min = minimumFractionDigits ?? 0;
+  return { minimumFractionDigits: min, maximumFractionDigits: Math.max(min, max) };
+}
+
+function formatWith(num: number, options: Intl.NumberFormatOptions, locale?: string): string {
+  try {
+    return new Intl.NumberFormat(locale, options).format(num);
+  } catch {
+    return String(num);
+  }
+}
+
+/**
+ * Cardinal / aggregate register — grouped digits, at most two fraction
+ * digits ("15,400", "5,133.33"). Empty input renders "" and an unparseable
+ * string passes through unchanged (honest passthrough — never invents).
+ */
+export function formatNumber(value: NumberInput, options: NumberFormatOptions = {}): string {
+  const coerced = coerceNumberInput(value);
+  if (!coerced) return typeof value === "string" ? value : "";
+  return formatWith(
+    coerced.num,
+    { ...resolveDigits(options), useGrouping: options.grouping ?? true },
+    options.locale,
+  );
+}
+
+/**
+ * Money register — grouped digits with two fraction digits, rendered with
+ * the currency's own symbol placement when the code is known ("$15,400.00",
+ * "₹15,400.00") and symbol-prefixed otherwise.
+ */
+export function formatCurrency(value: NumberInput, options: CurrencyFormatOptions = {}): string {
+  const coerced = coerceNumberInput(value);
+  if (!coerced) return typeof value === "string" ? value : "";
+  const { currency, symbol, fractionDigits = "always", locale, grouping } = options;
+  const hasExplicitDigits =
+    options.precision != null ||
+    options.minimumFractionDigits != null ||
+    options.maximumFractionDigits != null;
+  const wholeValue = Number.isInteger(coerced.num);
+  const digits = hasExplicitDigits
+    ? resolveDigits(options)
+    : fractionDigits === "auto" && wholeValue
+      ? { minimumFractionDigits: 0, maximumFractionDigits: 0 }
+      : { minimumFractionDigits: 2, maximumFractionDigits: 2 };
+  const code = currency ?? resolveCurrencyCode(symbol);
+  const useGrouping = grouping ?? true;
+  if (code) {
+    return formatWith(coerced.num, { ...digits, useGrouping, style: "currency", currency: code }, locale);
+  }
+  const amount = formatWith(coerced.num, { ...digits, useGrouping }, locale);
+  return symbol ? `${symbol}${amount}` : amount;
+}
+
+/**
+ * Rate register — the value already carries percent units (94.2 → "94.2%"),
+ * never a 0..1 ratio; ratios are converted by the caller that owns the unit.
+ */
+export function formatPercent(value: NumberInput, options: PercentFormatOptions = {}): string {
+  const formatted = formatNumber(value, options);
+  if (formatted === "") return "";
+  const coerced = coerceNumberInput(value);
+  return coerced ? `${formatted}%` : formatted;
+}

package/src/theme/knobs.ts

@@ -179,6 +179,25 @@ export const FontWeight = {
 } as const;
 export type FontWeight = (typeof FontWeight)[keyof typeof FontWeight];
 
+/**
+ * Page-title type step (D-11 hero-H1 dial, owner ruling 2026-08-12).
+ *
+ * `moderate` ($8 = 32px) is the product default: a page title is wayfinding,
+ * not content, so it does not spend the display scale's emphasis budget
+ * (Axiom 10) — and the 64px step is the direct amplifier of the DF-02 title
+ * clip. `display` ($10 = 64px) is the deliberate marketing/hero opt-in,
+ * reached through the `hero` preset or an explicit knob override; it is never
+ * the ambient default.
+ *
+ * Two values, not a token dial: a free size invites per-screen drift
+ * (Axiom 5), and the semantic level stays `headingLevel`'s job either way.
+ */
+export const PageTitleScale = {
+  Moderate: "moderate",
+  Display: "display",
+} as const;
+export type PageTitleScale = (typeof PageTitleScale)[keyof typeof PageTitleScale];
+
 // ── Animation ──────────────────────────────────────────────
 
 import type { AnimationName } from "./animations/index";
@@ -223,6 +242,11 @@ export interface Knobs {
   headingFont: HeadingFont;
   bodyFont: BodyFont;
   fontWeight: FontWeight;
+  /**
+   * Page-title step (D-11). Optional so existing preset/knob constructions
+   * stay valid; resolveKnobs defaults to `moderate`.
+   */
+  pageTitleScale?: PageTitleScale;
   animation: Animation;
   /** House: field label placement. Default top. */
   fieldLabelPlacement: FieldLabelPlacement;
@@ -263,6 +287,7 @@ export const defaultKnobs: Knobs = {
   headingFont: "sans-serif",
   bodyFont: "sans-serif",
   fontWeight: "regular",
+  pageTitleScale: "moderate",
   animation: "quick",
   fieldLabelPlacement: "top",
   requiredMarking: "minority",

package/src/theme/presets.ts

@@ -17,6 +17,7 @@ export const defaultPreset: Preset = {
     headingFont: "sans-serif",
     bodyFont: "sans-serif",
     fontWeight: "regular",
+    pageTitleScale: "moderate",
     animation: "quick",
     fieldLabelPlacement: "top",
     requiredMarking: "minority",
@@ -50,6 +51,7 @@ export const boldPreset: Preset = {
     headingFont: "sans-serif",
     bodyFont: "sans-serif",
     fontWeight: "bold",
+    pageTitleScale: "moderate",
     animation: "bouncy",
     fieldLabelPlacement: "top",
     requiredMarking: "minority",
@@ -67,3 +69,22 @@ export const boldPreset: Preset = {
   intents: defaultIntents,
   tints: ["pink", "purple", "pink", "purple", "pink", "purple", "pink"] as ThemeName[],
 };
+
+/**
+ * Marketing / hero surface preset (D-11 hero-H1 dial, owner ruling
+ * 2026-08-12). Identical to `defaultPreset` except the page title returns to
+ * the display step ($10 = 64px): product screens are wayfinding and take the
+ * moderate step by default, so the loud scale has to be ASKED for.
+ *
+ * @example Whole marketing app
+ * createDefaultThemeConfig({ presets: { default: defaultPreset, hero: heroPreset } })
+ *
+ * @example One hero region inside a product app (cascades onto the live preset)
+ * <Preset overrides={{ pageTitleScale: "display" }}>
+ *   <PageHeader title="Ship faster" />
+ * </Preset>
+ */
+export const heroPreset: Preset = {
+  ...defaultPreset,
+  knobs: { ...defaultPreset.knobs, pageTitleScale: "display" },
+};

package/src/theme/readableColor.ts

@@ -43,15 +43,16 @@ function resolveTokenValue(
 }
 
 /**
- * Readable text/glyph color to sit ON `fillToken` (e.g. "$accentBackground",
- * "$color8"): the scheme's paper (`$color1`) or ink (`$color12`) anchor,
- * whichever contrasts more on the resolved fill, returned as a concrete value
- * so no nested sub-theme can flip it. Returns `undefined` when any color fails
- * to resolve/parse — callers keep their own default in that case.
+ * Readable text/glyph color to sit ON `fill` (a token like "$accentBackground"
+ * / "$color8", or an already-resolved color value — e.g. the step returned by
+ * `useAccentTintedSurface`): the scheme's paper (`$color1`) or ink (`$color12`)
+ * anchor, whichever contrasts more on the resolved fill, returned as a concrete
+ * value so no nested sub-theme can flip it. Returns `undefined` when any color
+ * fails to resolve/parse — callers keep their own default in that case.
  */
-export function useReadableTextOn(fillToken: string): string | undefined {
+export function useReadableTextOn(fill_: string | undefined): string | undefined {
   const theme = useTamaguiTheme() as unknown as Record<string, { val?: unknown } | undefined>;
-  const fill = resolveTokenValue(theme, fillToken);
+  const fill = fill_?.startsWith("$") ? resolveTokenValue(theme, fill_) : fill_;
   const paper = resolveTokenValue(theme, "color1");
   const ink = resolveTokenValue(theme, "color12");
   return useMemo(() => {
@@ -99,3 +100,43 @@ export function useAccentOnSurface(): string {
     return best ?? ink;
   }, [c1, c2, ink, steps.join("|")]);
 }
+
+/**
+ * Accent-TINTED surface step — the accent-ramp analogue of a neutral surface
+ * tier, for selected/current chips that carry the accent language at surface
+ * strength rather than as a solid fill (LC-05: selected state is accent; the
+ * ViewSwitcher rider pins segmented-control strength at "tinted", not solid).
+ *
+ * Picks the accent step whose relative luminance sits closest to the neutral
+ * tier it replaces, so the chip stays a surface in BOTH schemes without a
+ * per-component light/dark fork: against this repo's stock accent ramp that
+ * resolves to a pale violet in light and a deep violet in dark, because the
+ * accent ramp flips with the scheme exactly as the neutral ramp does.
+ *
+ * Returns `undefined` when the accent ramp is absent or unparseable — callers
+ * keep their neutral default rather than render an unthemed chip.
+ */
+export function useAccentTintedSurface(neutralToken = "$color4"): string | undefined {
+  const theme = useTamaguiTheme() as unknown as Record<string, { val?: unknown } | undefined>;
+  const neutral = resolveTokenValue(theme, neutralToken);
+  const steps: (string | undefined)[] = [];
+  for (let i = 1; i <= 12; i++) steps.push(resolveTokenValue(theme, `accent${i}`));
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  return useMemo(() => {
+    const neutralHex = neutral ? normalizeToHex(neutral) : null;
+    if (!neutralHex) return undefined;
+    const target = relativeLuminance(neutralHex);
+    let best: string | undefined;
+    let bestDelta = Number.POSITIVE_INFINITY;
+    for (const step of steps) {
+      const hex = step ? normalizeToHex(step) : null;
+      if (!step || !hex) continue;
+      const delta = Math.abs(relativeLuminance(hex) - target);
+      if (delta < bestDelta) {
+        bestDelta = delta;
+        best = step;
+      }
+    }
+    return best;
+  }, [neutral, steps.join("|")]);
+}

package/src/theme/recipes.ts

@@ -1,4 +1,4 @@
-import type { ColorTokens, TransitionProp } from "tamagui";
+import type { ColorTokens, FontSizeTokens, TransitionProp } from "tamagui";
 import type { Knobs } from "./knobs";
 
 // ── State knob prop types (by concern) ───────────────────────────────────
@@ -154,6 +154,13 @@ export interface KnobProps {
   gapLg: { gap: string };
   sizeToken: string;
   heading: { fontFamily: string; fontWeight: string };
+  /**
+   * Page-title type step (D-11 hero-H1 dial) — the complete size fragment for
+   * the single page-title heading, spread whole onto the title node. Product
+   * screens land on the moderate step; the `hero` preset (or an explicit
+   * `pageTitleScale` override) re-opens the display scale for marketing.
+   */
+  pageTitle: { size: FontSizeTokens };
   /** color is set only for solid semantic-intent Buttons (error/warning/success). */
   body: { fontFamily: string; fontWeight: string; color?: ColorTokens };
   textWeight: { fontWeight: string };

package/src/theme/resolveKnobs.ts

@@ -1,5 +1,5 @@
 import { isWeb } from "@multiplatform.one/platform";
-import type { TransitionProp } from "tamagui";
+import type { FontSizeTokens, TransitionProp } from "tamagui";
 // Importing the class constant also mounts the corner-shape stylesheet at
 // theme load (web only, idempotent) — see cornerSmoothing.ts.
 import { cornerSmoothClassName } from "./cornerSmoothing";
@@ -9,7 +9,7 @@ import {
   STATE_LAYER_PRESS,
   withDefaultStateLayer,
 } from "./focusState";
-import type { CornerSmoothing, Knobs, StateKnobs } from "./knobs";
+import type { CornerSmoothing, Knobs, PageTitleScale, StateKnobs } from "./knobs";
 import type {
   ControlStateProps,
   DisabledRecipe,
@@ -101,6 +101,28 @@ const panelPaddingMap = {
   large: "$6",
 } as const;
 
+// ── Page-title step (D-11 hero-H1 dial) ───────────────────────
+// The one canonical definition of how big a page title is. On the heading
+// scale (1.4x Inter, defaults/fonts.ts) $8 = 32px and $10 = 64px, so
+// `moderate` lands in the page-title class while `display` keeps the
+// marketing hero step. Screens never pick a heading step by hand — they
+// spread `knobProps.pageTitle`, so one knob flip re-scales every title.
+const pageTitleSizeMap: Record<PageTitleScale, FontSizeTokens> = {
+  moderate: "$8",
+  display: "$10",
+};
+
+/**
+ * Resolve a page-title scale to its complete size fragment (D-11).
+ *
+ * Exported so a per-instance eject (`PageHeader titleScale="display"` on a
+ * marketing hero) resolves through the same table as the knob — never a
+ * second hardcoded step.
+ */
+export function resolvePageTitleScale(scale: PageTitleScale): { size: FontSizeTokens } {
+  return { size: pageTitleSizeMap[scale] };
+}
+
 // ── Container radius cap (Axiom 1 CLIP) ──────────────────────
 // A padded container's effective radius must not exceed its own padding:
 // past that, the corner curve sweeps through the cell where children sit
@@ -433,6 +455,7 @@ export function resolveKnobs(knobs: Knobs, override?: KnobPropsOverride): Resolv
       fontFamily: headingFontMap[knobs.headingFont],
       fontWeight: fontWeightValue,
     },
+    pageTitle: resolvePageTitleScale(knobs.pageTitleScale ?? "moderate"),
     body: {
       fontFamily: bodyFontValue,
       fontWeight: fontWeightValue,