@bendyline/squisq 2.0.1 → 2.1.0

package/src/schemas/PageStyle.ts

@@ -0,0 +1,213 @@
+/**
+ * Page Style — the theme's art-direction layer for Page (linear) mode.
+ *
+ * Slides render through fixed-viewport SVG templates; pages render through
+ * a small closed vocabulary of variable-height HTML section layouts
+ * (`PageSectionKind`). A `ThemePageStyle` is how a theme art-directs that
+ * page rendition: it picks a design family, sets page-wide tokens
+ * (column widths, spacing, dividers, hero treatment, image framing …),
+ * and can override how individual section kinds or block templates map
+ * onto the section vocabulary.
+ *
+ * Design principles (mirrors the rest of the Theme schema):
+ * - Fully JSON-serializable — rides the `squisq-custom-themes` frontmatter
+ *   codec unchanged.
+ * - Closed enums everywhere so renderers can switch exhaustively and the
+ *   validator can reject typos.
+ * - Optional on `Theme`; `resolvePageStyle`/`defaultPageStyle` derive a
+ *   complete style from existing theme fields when absent, so legacy and
+ *   customizer themes keep working without edits.
+ */
+
+// ============================================
+// Section vocabulary
+// ============================================
+
+/**
+ * The closed set of page section layouts. Every block template maps onto
+ * one of these kinds (see `doc/page/sectionExtractors.ts`); themes may
+ * remap via `ThemePageStyle.sections` / `.templates`.
+ */
+export const PAGE_SECTION_KINDS = [
+  'hero',
+  'banner',
+  'stat-band',
+  'quote-band',
+  'feature-split',
+  'media-figure',
+  'gallery',
+  'callout',
+  'card-grid',
+  'item-list',
+  'timeline-rail',
+  'table-section',
+  'canvas-embed',
+  'prose',
+  'footer',
+] as const;
+
+export type PageSectionKind = (typeof PAGE_SECTION_KINDS)[number];
+
+/** Relative visual weight of a section within the page. */
+export type PageEmphasis = 'lead' | 'strong' | 'standard' | 'quiet';
+
+/** Which background treatment a section sits on. */
+export type PageBackground = 'base' | 'alternate' | 'accent' | 'media';
+
+// ============================================
+// Design families + tokens
+// ============================================
+
+/**
+ * Broad page design personalities. A family selects the structural
+ * skeleton (how sections compose); tokens parameterize it per theme.
+ */
+export const PAGE_DESIGN_FAMILIES = [
+  'clean',
+  'editorial',
+  'brutalist',
+  'terminal',
+  'cinematic',
+  'documentary',
+  'organic',
+  'soft',
+] as const;
+
+export type PageDesignFamily = (typeof PAGE_DESIGN_FAMILIES)[number];
+
+/** How headings announce themselves across the page. */
+export interface PageHeadingTreatment {
+  /** Small label above headings: none, plain kicker, "01 —" numbering, or a mono tag. */
+  eyebrow: 'none' | 'kicker' | 'numbered' | 'mono-tag';
+  /** Overall heading size register. */
+  scale: 'regular' | 'display' | 'oversized';
+  /** Optional case transform for headings/eyebrows. */
+  case?: 'none' | 'uppercase';
+  /** Optional decoration under headings. */
+  underline?: 'none' | 'accent-bar' | 'full-rule';
+}
+
+/**
+ * Page-wide design tokens. Structural CSS reads these via
+ * `--squisq-page-*` custom properties (see `doc/pageCss.ts`).
+ */
+export interface PageTokens {
+  /** Reading-column max width in px (prose, callouts, quotes). */
+  contentMaxWidth: number;
+  /** Wide-band inner max width in px (figures, tables, feature splits). */
+  wideMaxWidth: number;
+  /** Vertical rhythm between sections. */
+  sectionSpacing: 'compact' | 'comfortable' | 'generous';
+  /** Corner radius for cards, media frames, panels (px). */
+  cornerRadius: number;
+  /** Divider treatment between sections. */
+  divider: 'none' | 'gap-only' | 'hairline' | 'thick-rule' | 'double-rule' | 'dotted';
+  /** How section backgrounds vary down the page. */
+  backgroundRhythm: 'flat' | 'alternate' | 'accent-bands' | 'tinted-panels';
+  /** Hero (cover/title) composition. */
+  heroStyle: 'stacked' | 'split' | 'full-bleed' | 'letterbox' | 'oversized-type';
+  /** Heading voice across the page. */
+  headingTreatment: PageHeadingTreatment;
+  /** Frame treatment for photographic media. */
+  imageFraming: 'flush' | 'rounded' | 'bordered' | 'polaroid' | 'letterboxed' | 'circle-accent';
+  /** Shadow language for elevated elements. */
+  shadow: 'none' | 'soft' | 'crisp' | 'heavy';
+  /** Decoration on quote sections. */
+  quoteMark: 'none' | 'oversized-glyph' | 'accent-bar';
+  /** Treatment of large stat numerals. */
+  numeralStyle: 'plain' | 'oversized' | 'boxed' | 'mono';
+  /** Optional page background pattern. */
+  pattern?: 'none' | 'dots' | 'grid' | 'diagonal' | 'noise';
+}
+
+// ============================================
+// Overrides + accent rotation
+// ============================================
+
+/**
+ * A theme's override for one section kind or one block template —
+ * remap the kind, force a variant, adjust emphasis/background, or pass
+ * freeform scalar hints the section renderer understands.
+ */
+export interface PageSectionOverride {
+  kind?: PageSectionKind;
+  variant?: string;
+  emphasis?: PageEmphasis;
+  background?: PageBackground;
+  /** Freeform scalar hints (e.g. `dropCap: true`, `frame: "terminal"`). */
+  hints?: Record<string, string | number | boolean>;
+}
+
+/** How named color schemes rotate across accent-bearing sections. */
+export interface PageAccentRotation {
+  strategy: 'primary-only' | 'cycle' | 'alternate-two' | 'none';
+  /**
+   * ColorScheme names (keys of `theme.colorSchemes`) to rotate through.
+   * Defaults to all schemes in insertion order.
+   */
+  schemes?: string[];
+}
+
+// ============================================
+// ThemePageStyle
+// ============================================
+
+/**
+ * The complete page art direction for a theme. Optional on `Theme`;
+ * `defaultPageStyle(theme)` derives one from existing theme fields.
+ */
+export interface ThemePageStyle {
+  family: PageDesignFamily;
+  tokens: PageTokens;
+  /** Per-section-kind overrides. */
+  sections?: Partial<Record<PageSectionKind, PageSectionOverride>>;
+  /** Per-template overrides (canonical template ids); win over `sections`. */
+  templates?: Record<string, PageSectionOverride>;
+  accentRotation: PageAccentRotation;
+}
+
+// ============================================
+// Enum sets (shared by the validator + defaults)
+// ============================================
+
+export const PAGE_SECTION_SPACINGS = ['compact', 'comfortable', 'generous'] as const;
+export const PAGE_DIVIDERS = [
+  'none',
+  'gap-only',
+  'hairline',
+  'thick-rule',
+  'double-rule',
+  'dotted',
+] as const;
+export const PAGE_BACKGROUND_RHYTHMS = [
+  'flat',
+  'alternate',
+  'accent-bands',
+  'tinted-panels',
+] as const;
+export const PAGE_HERO_STYLES = [
+  'stacked',
+  'split',
+  'full-bleed',
+  'letterbox',
+  'oversized-type',
+] as const;
+export const PAGE_EYEBROWS = ['none', 'kicker', 'numbered', 'mono-tag'] as const;
+export const PAGE_HEADING_SCALES = ['regular', 'display', 'oversized'] as const;
+export const PAGE_HEADING_CASES = ['none', 'uppercase'] as const;
+export const PAGE_HEADING_UNDERLINES = ['none', 'accent-bar', 'full-rule'] as const;
+export const PAGE_IMAGE_FRAMINGS = [
+  'flush',
+  'rounded',
+  'bordered',
+  'polaroid',
+  'letterboxed',
+  'circle-accent',
+] as const;
+export const PAGE_SHADOWS = ['none', 'soft', 'crisp', 'heavy'] as const;
+export const PAGE_QUOTE_MARKS = ['none', 'oversized-glyph', 'accent-bar'] as const;
+export const PAGE_NUMERAL_STYLES = ['plain', 'oversized', 'boxed', 'mono'] as const;
+export const PAGE_PATTERNS = ['none', 'dots', 'grid', 'diagonal', 'noise'] as const;
+export const PAGE_EMPHASES = ['lead', 'strong', 'standard', 'quiet'] as const;
+export const PAGE_BACKGROUNDS = ['base', 'alternate', 'accent', 'media'] as const;
+export const PAGE_ACCENT_STRATEGIES = ['primary-only', 'cycle', 'alternate-two', 'none'] as const;

package/src/schemas/Theme.ts

@@ -23,6 +23,7 @@
 import type { LayoutHints } from './LayoutStrategy.js';
 import type { AnimationType, ImageTreatment, TransitionType } from './Doc.js';
 import type { PersistentLayerConfig } from './BlockTemplates.js';
+import type { ThemePageStyle } from './PageStyle.js';
 import { THEME_SCHEMA_VERSION } from './themeConstants.js';
 import { validateTheme } from './themeValidator.js';
 import { cloneAndFreezeData } from '../internal/immutable.js';
@@ -236,6 +237,12 @@ export interface Theme {
   colorSchemes: Record<string, ThemeColorScheme>;
   /** Optional persistent layers baked into the theme */
   persistentLayers?: PersistentLayerConfig;
+  /**
+   * Optional page art direction for Page (linear) mode. When absent,
+   * `resolvePageStyle`/`defaultPageStyle` derive one from the fields above,
+   * so legacy themes render pages without declaring this.
+   */
+  pageStyle?: ThemePageStyle;
 }
 
 // ============================================

package/src/schemas/index.ts

@@ -5,6 +5,8 @@ export * from './Media.js';
 export * from './BlockTemplates.js';
 export * from './CustomTemplates.js';
 export * from './Theme.js';
+export * from './PageStyle.js';
+export * from './pageStyleDefaults.js';
 export * from './themeLibrary.js';
 export * from './themeValidator.js';
 export * from './themeCompile.js';

package/src/schemas/pageStyleDefaults.ts

@@ -0,0 +1,204 @@
+/**
+ * Page Style Defaults
+ *
+ * Derives a complete `ThemePageStyle` from a theme's existing fields so
+ * legacy themes, customizer themes, and file-inferred themes get a
+ * coherent page art direction without declaring one. Built-in themes
+ * ship explicit `pageStyle` blocks in their JSON; this derivation is the
+ * fallback used by `compileTheme` and by `resolvePageStyle` at read time.
+ *
+ * Derivation signals:
+ * - `renderStyle.name` → design family (documentary → documentary,
+ *   magazine → editorial, bold → brutalist, tech-dark → terminal, …)
+ * - `style.borderRadius` → cornerRadius + rounded vs flush image framing
+ * - `style.imageTreatment` (mono/duotone) → letterboxed framing
+ * - `style.textShadow` → shadow language
+ * - `persistentLayers` patternBackground → page pattern
+ */
+
+import type { Theme } from './Theme.js';
+import type {
+  PageDesignFamily,
+  PageTokens,
+  ThemePageStyle,
+  PageHeadingTreatment,
+} from './PageStyle.js';
+
+/** renderStyle.name → design family. Unknown names fall back to 'clean'. */
+const FAMILY_BY_RENDER_STYLE: Record<string, PageDesignFamily> = {
+  standard: 'clean',
+  minimalist: 'clean',
+  documentary: 'documentary',
+  magazine: 'editorial',
+  bold: 'brutalist',
+  'tech-dark': 'terminal',
+  cinematic: 'cinematic',
+  'warm-earth': 'organic',
+  'morning-light': 'soft',
+  gezellig: 'soft',
+};
+
+interface FamilyDefaults {
+  sectionSpacing: PageTokens['sectionSpacing'];
+  divider: PageTokens['divider'];
+  backgroundRhythm: PageTokens['backgroundRhythm'];
+  heroStyle: PageTokens['heroStyle'];
+  headingTreatment: PageHeadingTreatment;
+  quoteMark: PageTokens['quoteMark'];
+  numeralStyle: PageTokens['numeralStyle'];
+  accentStrategy: ThemePageStyle['accentRotation']['strategy'];
+}
+
+const FAMILY_DEFAULTS: Record<PageDesignFamily, FamilyDefaults> = {
+  clean: {
+    sectionSpacing: 'comfortable',
+    divider: 'hairline',
+    backgroundRhythm: 'alternate',
+    heroStyle: 'stacked',
+    headingTreatment: { eyebrow: 'kicker', scale: 'regular', underline: 'none' },
+    quoteMark: 'accent-bar',
+    numeralStyle: 'plain',
+    accentStrategy: 'cycle',
+  },
+  editorial: {
+    sectionSpacing: 'comfortable',
+    divider: 'double-rule',
+    backgroundRhythm: 'flat',
+    heroStyle: 'split',
+    headingTreatment: { eyebrow: 'kicker', scale: 'display', underline: 'none' },
+    quoteMark: 'oversized-glyph',
+    numeralStyle: 'oversized',
+    accentStrategy: 'alternate-two',
+  },
+  brutalist: {
+    sectionSpacing: 'compact',
+    divider: 'thick-rule',
+    backgroundRhythm: 'accent-bands',
+    heroStyle: 'oversized-type',
+    headingTreatment: { eyebrow: 'kicker', scale: 'oversized', case: 'uppercase' },
+    quoteMark: 'none',
+    numeralStyle: 'oversized',
+    accentStrategy: 'cycle',
+  },
+  terminal: {
+    sectionSpacing: 'compact',
+    divider: 'hairline',
+    backgroundRhythm: 'tinted-panels',
+    heroStyle: 'stacked',
+    headingTreatment: { eyebrow: 'mono-tag', scale: 'regular', underline: 'none' },
+    quoteMark: 'none',
+    numeralStyle: 'mono',
+    accentStrategy: 'primary-only',
+  },
+  cinematic: {
+    sectionSpacing: 'generous',
+    divider: 'gap-only',
+    backgroundRhythm: 'flat',
+    heroStyle: 'full-bleed',
+    headingTreatment: { eyebrow: 'kicker', scale: 'display', case: 'uppercase' },
+    quoteMark: 'none',
+    numeralStyle: 'oversized',
+    accentStrategy: 'primary-only',
+  },
+  documentary: {
+    sectionSpacing: 'generous',
+    divider: 'thick-rule',
+    backgroundRhythm: 'flat',
+    heroStyle: 'letterbox',
+    headingTreatment: { eyebrow: 'numbered', scale: 'display', underline: 'none' },
+    quoteMark: 'accent-bar',
+    numeralStyle: 'boxed',
+    accentStrategy: 'primary-only',
+  },
+  organic: {
+    sectionSpacing: 'comfortable',
+    divider: 'thick-rule',
+    backgroundRhythm: 'tinted-panels',
+    heroStyle: 'stacked',
+    headingTreatment: { eyebrow: 'kicker', scale: 'regular', underline: 'accent-bar' },
+    quoteMark: 'oversized-glyph',
+    numeralStyle: 'boxed',
+    accentStrategy: 'alternate-two',
+  },
+  soft: {
+    sectionSpacing: 'comfortable',
+    divider: 'dotted',
+    backgroundRhythm: 'tinted-panels',
+    heroStyle: 'split',
+    headingTreatment: { eyebrow: 'kicker', scale: 'regular', underline: 'none' },
+    quoteMark: 'oversized-glyph',
+    numeralStyle: 'plain',
+    accentStrategy: 'alternate-two',
+  },
+};
+
+/** Read the first patternBackground pattern from a theme's persistent layers. */
+function derivePattern(theme: Theme): PageTokens['pattern'] {
+  const layers = [
+    ...(theme.persistentLayers?.bottomLayers ?? []),
+    ...(theme.persistentLayers?.topLayers ?? []),
+  ];
+  for (const layer of layers) {
+    if (
+      typeof layer === 'object' &&
+      layer !== null &&
+      'template' in layer &&
+      (layer as { template?: unknown }).template === 'patternBackground'
+    ) {
+      const config = (layer as { config?: { pattern?: unknown } }).config;
+      const pattern = config?.pattern;
+      if (
+        pattern === 'dots' ||
+        pattern === 'grid' ||
+        pattern === 'diagonal' ||
+        pattern === 'noise'
+      ) {
+        return pattern;
+      }
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Derive a complete `ThemePageStyle` from a theme's existing fields.
+ * Deterministic and read-only; explicit `theme.pageStyle` always wins
+ * (callers check before deriving — see `resolvePageStyle`).
+ */
+export function defaultPageStyle(theme: Theme): ThemePageStyle {
+  const family = FAMILY_BY_RENDER_STYLE[theme.renderStyle?.name ?? ''] ?? 'clean';
+  const defaults = FAMILY_DEFAULTS[family];
+
+  const cornerRadius = theme.style?.borderRadius ?? 6;
+  const treatmentType = theme.style?.imageTreatment?.type;
+  const imageFraming: PageTokens['imageFraming'] =
+    treatmentType === 'mono' || treatmentType === 'duotone'
+      ? 'letterboxed'
+      : cornerRadius > 0
+        ? 'rounded'
+        : 'flush';
+
+  const tokens: PageTokens = {
+    contentMaxWidth: 760,
+    wideMaxWidth: 1100,
+    sectionSpacing: defaults.sectionSpacing,
+    cornerRadius,
+    divider: defaults.divider,
+    backgroundRhythm: defaults.backgroundRhythm,
+    heroStyle: defaults.heroStyle,
+    headingTreatment: { ...defaults.headingTreatment },
+    imageFraming,
+    shadow: theme.style?.textShadow ? 'soft' : 'none',
+    quoteMark: defaults.quoteMark,
+    numeralStyle: defaults.numeralStyle,
+  };
+
+  const pattern = derivePattern(theme);
+  if (pattern) tokens.pattern = pattern;
+
+  return {
+    family,
+    tokens,
+    accentRotation: { strategy: defaults.accentStrategy },
+  };
+}

package/src/schemas/themeCompile.ts

@@ -22,6 +22,7 @@ import type {
 } from './Theme.js';
 import { THEME_SCHEMA_VERSION, createTheme } from './Theme.js';
 import { assertTheme } from './themeValidator.js';
+import { defaultPageStyle } from './pageStyleDefaults.js';
 import {
   oklchLighten,
   oklchDarken,
@@ -210,6 +211,12 @@ export function compileTheme(partial: DeepPartial<Theme>, opts: CompileOptions =
     });
   }
 
+  // Step 2b: fill page art direction from existing fields when absent, so
+  // every compiled theme carries an explicit, serializable pageStyle.
+  if (!merged.pageStyle) {
+    merged.pageStyle = defaultPageStyle(merged);
+  }
+
   // Step 3: validate
   return assertTheme(merged, `compiled theme "${merged.id}"`);
 }

package/src/schemas/themeValidator.ts

@@ -14,6 +14,26 @@ import type { Theme, ThemeColorPalette } from './Theme.js';
 import { THEME_SCHEMA_VERSION } from './themeConstants.js';
 import { isHex } from './colorUtils.js';
 import { isTransitionType } from './Transitions.js';
+import {
+  PAGE_SECTION_KINDS,
+  PAGE_DESIGN_FAMILIES,
+  PAGE_SECTION_SPACINGS,
+  PAGE_DIVIDERS,
+  PAGE_BACKGROUND_RHYTHMS,
+  PAGE_HERO_STYLES,
+  PAGE_EYEBROWS,
+  PAGE_HEADING_SCALES,
+  PAGE_HEADING_CASES,
+  PAGE_HEADING_UNDERLINES,
+  PAGE_IMAGE_FRAMINGS,
+  PAGE_SHADOWS,
+  PAGE_QUOTE_MARKS,
+  PAGE_NUMERAL_STYLES,
+  PAGE_PATTERNS,
+  PAGE_EMPHASES,
+  PAGE_BACKGROUNDS,
+  PAGE_ACCENT_STRATEGIES,
+} from './PageStyle.js';
 
 export interface ValidationError {
   path: string;
@@ -28,6 +48,28 @@ export interface ValidationResult {
 }
 
 const VALID_FALLBACK = new Set(['serif', 'sans-serif', 'monospace', 'system-ui']);
+const VALID_SECTION_KINDS = new Set<string>(PAGE_SECTION_KINDS);
+const VALID_DESIGN_FAMILIES = new Set<string>(PAGE_DESIGN_FAMILIES);
+const VALID_PAGE_EMPHASES = new Set<string>(PAGE_EMPHASES);
+const VALID_PAGE_BACKGROUNDS = new Set<string>(PAGE_BACKGROUNDS);
+const VALID_ACCENT_STRATEGIES = new Set<string>(PAGE_ACCENT_STRATEGIES);
+/** PageTokens enum fields → their allowed values. */
+const PAGE_TOKEN_ENUMS: Record<string, Set<string>> = {
+  sectionSpacing: new Set<string>(PAGE_SECTION_SPACINGS),
+  divider: new Set<string>(PAGE_DIVIDERS),
+  backgroundRhythm: new Set<string>(PAGE_BACKGROUND_RHYTHMS),
+  heroStyle: new Set<string>(PAGE_HERO_STYLES),
+  imageFraming: new Set<string>(PAGE_IMAGE_FRAMINGS),
+  shadow: new Set<string>(PAGE_SHADOWS),
+  quoteMark: new Set<string>(PAGE_QUOTE_MARKS),
+  numeralStyle: new Set<string>(PAGE_NUMERAL_STYLES),
+};
+const HEADING_TREATMENT_ENUMS: Record<string, { values: Set<string>; required: boolean }> = {
+  eyebrow: { values: new Set<string>(PAGE_EYEBROWS), required: true },
+  scale: { values: new Set<string>(PAGE_HEADING_SCALES), required: true },
+  case: { values: new Set<string>(PAGE_HEADING_CASES), required: false },
+  underline: { values: new Set<string>(PAGE_HEADING_UNDERLINES), required: false },
+};
 const VALID_TITLE_WEIGHT = new Set(['normal', 'bold']);
 const VALID_GRADIENT_PRESETS = new Set([
   'dark-vignette',
@@ -340,6 +382,143 @@ class V {
       arr.forEach((entry, i) => this.persistentLayer(`${path}.${side}[${i}]`, entry));
     }
   }
+
+  scalarHints(path: string, v: unknown): void {
+    if (!this.isObject(v)) {
+      this.err(path, 'expected object');
+      return;
+    }
+    for (const key of Object.keys(v)) {
+      const t = typeof v[key];
+      if (t !== 'string' && t !== 'number' && t !== 'boolean') {
+        this.err(`${path}.${key}`, `expected string|number|boolean, got ${t}`);
+      }
+    }
+  }
+
+  pageSectionOverride(path: string, v: unknown): void {
+    if (!this.isObject(v)) {
+      this.err(path, 'expected object');
+      return;
+    }
+    if (v.kind !== undefined && (!this.isString(v.kind) || !VALID_SECTION_KINDS.has(v.kind))) {
+      this.err(`${path}.kind`, `expected one of: ${PAGE_SECTION_KINDS.join(', ')}`);
+    }
+    if (v.variant !== undefined && !this.isString(v.variant)) {
+      this.err(`${path}.variant`, 'expected string');
+    }
+    if (
+      v.emphasis !== undefined &&
+      (!this.isString(v.emphasis) || !VALID_PAGE_EMPHASES.has(v.emphasis))
+    ) {
+      this.err(`${path}.emphasis`, `expected one of: ${PAGE_EMPHASES.join(', ')}`);
+    }
+    if (
+      v.background !== undefined &&
+      (!this.isString(v.background) || !VALID_PAGE_BACKGROUNDS.has(v.background))
+    ) {
+      this.err(`${path}.background`, `expected one of: ${PAGE_BACKGROUNDS.join(', ')}`);
+    }
+    if (v.hints !== undefined) this.scalarHints(`${path}.hints`, v.hints);
+  }
+
+  pageTokens(path: string, v: unknown): void {
+    if (!this.isObject(v)) {
+      this.err(path, 'expected object');
+      return;
+    }
+    for (const k of ['contentMaxWidth', 'wideMaxWidth', 'cornerRadius']) {
+      if (!this.isNumber(v[k])) {
+        this.err(`${path}.${k}`, 'expected number');
+      }
+    }
+    for (const [k, values] of Object.entries(PAGE_TOKEN_ENUMS)) {
+      if (!this.isString(v[k]) || !values.has(v[k] as string)) {
+        this.err(`${path}.${k}`, `expected one of: ${Array.from(values).join(', ')}`);
+      }
+    }
+    if (v.pattern !== undefined) {
+      if (!this.isString(v.pattern) || !(PAGE_PATTERNS as readonly string[]).includes(v.pattern)) {
+        this.err(`${path}.pattern`, `expected one of: ${PAGE_PATTERNS.join(', ')}`);
+      }
+    }
+    const ht = v.headingTreatment;
+    if (!this.isObject(ht)) {
+      this.err(`${path}.headingTreatment`, 'expected object');
+      return;
+    }
+    for (const [k, spec] of Object.entries(HEADING_TREATMENT_ENUMS)) {
+      const val = ht[k];
+      if (val === undefined) {
+        if (spec.required) this.err(`${path}.headingTreatment.${k}`, 'required');
+        continue;
+      }
+      if (!this.isString(val) || !spec.values.has(val)) {
+        this.err(
+          `${path}.headingTreatment.${k}`,
+          `expected one of: ${Array.from(spec.values).join(', ')}`,
+        );
+      }
+    }
+  }
+
+  pageStyle(path: string, v: unknown): void {
+    if (!this.isObject(v)) {
+      this.err(path, 'expected object');
+      return;
+    }
+    if (!this.isString(v.family) || !VALID_DESIGN_FAMILIES.has(v.family)) {
+      this.err(`${path}.family`, `expected one of: ${PAGE_DESIGN_FAMILIES.join(', ')}`);
+    }
+    if (v.tokens === undefined) {
+      this.err(`${path}.tokens`, 'required');
+    } else {
+      this.pageTokens(`${path}.tokens`, v.tokens);
+    }
+    if (v.sections !== undefined) {
+      if (!this.isObject(v.sections)) {
+        this.err(`${path}.sections`, 'expected object map');
+      } else {
+        for (const key of Object.keys(v.sections)) {
+          if (!VALID_SECTION_KINDS.has(key)) {
+            this.err(`${path}.sections.${key}`, `unknown section kind`);
+            continue;
+          }
+          this.pageSectionOverride(`${path}.sections.${key}`, v.sections[key]);
+        }
+      }
+    }
+    if (v.templates !== undefined) {
+      if (!this.isObject(v.templates)) {
+        this.err(`${path}.templates`, 'expected object map');
+      } else {
+        for (const key of Object.keys(v.templates)) {
+          this.pageSectionOverride(`${path}.templates.${key}`, v.templates[key]);
+        }
+      }
+    }
+    if (v.accentRotation === undefined) {
+      this.err(`${path}.accentRotation`, 'required');
+    } else if (!this.isObject(v.accentRotation)) {
+      this.err(`${path}.accentRotation`, 'expected object');
+    } else {
+      const rotation = v.accentRotation;
+      if (!this.isString(rotation.strategy) || !VALID_ACCENT_STRATEGIES.has(rotation.strategy)) {
+        this.err(
+          `${path}.accentRotation.strategy`,
+          `expected one of: ${PAGE_ACCENT_STRATEGIES.join(', ')}`,
+        );
+      }
+      if (rotation.schemes !== undefined) {
+        if (
+          !Array.isArray(rotation.schemes) ||
+          rotation.schemes.some((s) => typeof s !== 'string')
+        ) {
+          this.err(`${path}.accentRotation.schemes`, 'expected array of strings');
+        }
+      }
+    }
+  }
 }
 
 export function validateTheme(input: unknown): ValidationResult {
@@ -403,6 +582,10 @@ export function validateTheme(input: unknown): ValidationResult {
     v.persistentLayers('persistentLayers', input.persistentLayers);
   }
 
+  if (input.pageStyle !== undefined) {
+    v.pageStyle('pageStyle', input.pageStyle);
+  }
+
   if (v.errors.length === 0) {
     return { valid: true, errors: [], theme: input as unknown as Theme };
   }