@abreen/tada 1.16.1 → 1.16.2

package/README.md

@@ -221,6 +221,20 @@ themeColor: hsl(351 70% 40%)
 tintAmount: 0
 defaultFont: serif
 defaultContrast: high
+fontOverrides:
+  serif:
+    regular: fonts/body-regular.woff2
+    tuning:
+      scale: 1.125
+      lineHeight: 1.5
+      headingScale: 0.9
+      headingWeight: 400
+  serifMono:
+    regular: fonts/mono-regular.woff2
+    features: [ss02]
+    tuning:
+      scale: 0.94
+      lineHeight: 1.5
 features:
   search: true
   favicon: true
@@ -249,6 +263,7 @@ vars:
 | `tintAmount` | *Optional*, percentage (0-100) of tint to apply (default `100`) |
 | `defaultFont` | *Optional*, initial font pairing: `sans` or `serif` (default `sans`) |
 | `defaultContrast` | *Optional*, initial neutral-palette contrast: `standard` or `high` (default `standard`) |
+| `fontOverrides` | *Optional*, custom serif and serif-monospace WOFF2 faces from `public/`; each configured family requires `regular` and may include styled faces, OpenType `features`, and font-specific `tuning` |
 | `faviconSymbol` | *Optional*, the text to use instead of `symbol` in the favicon |
 | `features.search` | Enable search UI and Pagefind index generation |
 | `features.favicon` | Enable automatically generated favicons |

package/assets/material-symbols/celebration_24px.svg

@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" height="24" viewBox="0 -960 960 960" width="24"><path d="m80-80 200-560 360 360L80-80Zm132-132 282-100-182-182-100 282Zm370-246-42-42 224-224q32-32 77-32t77 32l24 24-42 42-24-24q-14-14-35-14t-35 14L582-458ZM422-618l-42-42 24-24q14-14 14-34t-14-34l-26-26 42-42 26 26q32 32 32 76t-32 76l-24 24Zm80 80-42-42 144-144q14-14 14-35t-14-35l-64-64 42-42 64 64q32 32 32 77t-32 77L502-538Zm160 160-42-42 64-64q32-32 77-32t77 32l64 64-42 42-64-64q-14-14-35-14t-35 14l-64 64ZM212-212Z"/></svg>
+<svg xmlns="http://www.w3.org/2000/svg" height="24" viewBox="0 -960 960 960" width="24"><path d="m70.91-65.41 210.05-587.74 377.93 377.93L70.91-65.41Zm150.18-149.94L492.8-312 317.74-487.07l-96.65 271.72Zm370.24-239.06L545.74-500l219.93-219.93q33.44-33.44 80.71-33.44 47.27 0 80.71 33.44l24 24-45.83 45.58-24-24q-14-14-35-14t-35 14L591.33-454.41ZM423.91-621.59l-45.58-45.82 22.56-22.57q14-14 14-34t-14-34l-26-26 45.59-45.59 26 26q33.43 33.44 33.43 79.71 0 46.27-33.43 79.71l-22.57 22.56ZM507.74-538l-45.83-45.59 141.13-141.13q14-14 14-35t-14-35l-64-64 45.83-45.58 64 64q33.43 33.43 33.43 80.58t-33.43 80.59L507.74-538Zm167.17 167.41-45.58-45.82 62.56-62.57q33.44-33.43 80.71-33.43 47.27 0 80.7 33.43l64 64-45.82 45.83-64-64q-14-14-35-14t-35 14l-62.57 62.56ZM221.09-215.35Z"/></svg>

package/assets/material-symbols/close_24px.svg

@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" height="24" viewBox="0 -960 960 960" width="24"><path d="m256-200-56-56 224-224-224-224 56-56 224 224 224-224 56 56-224 224 224 224-56 56-224-224-224 224Z"/></svg>
+<svg xmlns="http://www.w3.org/2000/svg" height="24" viewBox="0 -960 960 960" width="24"><path d="M256-192.35 192.35-256l224-224-224-224L256-767.65l224 224 224-224L767.65-704l-224 224 224 224L704-192.35l-224-224-224 224Z"/></svg>

package/assets/material-symbols/contrast_20px.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" height="20" viewBox="0 -960 960 960" width="20"><path d="M327.89-118.47q-71.43-30.6-125.13-84.29-53.69-53.7-84.29-125.13-30.6-71.44-30.6-152.61 0-81.17 30.6-152.11 30.6-70.93 84.29-124.63 53.7-53.69 125.13-84.29 71.44-30.6 152.61-30.6 81.17 0 152.11 30.6 70.93 30.6 124.63 84.29 53.69 53.7 84.29 124.63 30.6 70.94 30.6 152.11 0 81.17-30.6 152.61-30.6 71.43-84.29 125.13-53.7 53.69-124.63 84.29-70.94 30.6-152.11 30.6-81.17 0-152.61-30.6Zm190.98-54.88q115.09-14.95 192.67-100.9Q789.13-360.2 789.13-480q0-119.09-77.59-205.27-77.58-86.19-192.67-101.14v613.06Z"/></svg>

package/assets/material-symbols/contrast_rtl_off_20px.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" height="20" viewBox="0 -960 960 960" width="20"><path d="m771.83-84.98-70.81-70.56q-49.95 32.71-105.75 50.19-55.8 17.48-115.24 17.48-80.94 0-152.37-30.62-71.44-30.62-125-84.17-53.55-53.56-84.17-125-30.62-71.43-30.62-152.37 0-59.44 17.48-115.24t50.19-105.75L88.8-768l53.4-53.39 683.02 683.02-53.39 53.39ZM480-170.87q43.04 0 83.45-12.52 40.4-12.52 77.68-33.04L480-377.57v206.7Zm327.09-92.41-61.37-60.13q20.29-36.49 31.85-75.73 11.56-39.25 11.56-80.86 0-129.04-90.16-219.09-90.16-90.04-218.97-90.04v198.76L263.28-807.09q48.16-31.54 103.34-48.29Q421.8-872.13 480-872.13q81.91 0 152.84 30.62 70.94 30.62 124.5 84.17 53.55 53.56 84.17 124.5 30.62 70.93 30.62 152.84 0 58.2-16.75 113.38-16.75 55.18-48.29 103.34Z"/></svg>

package/assets/material-symbols/info_20px.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" height="20" viewBox="0 -960 960 960" width="20"><path d="M440.41-284.41h79.18V-528h-79.18v243.59Zm68.44-322.47q11.93-11.67 11.93-28.91 0-17.24-11.66-29.12-11.67-11.87-28.91-11.87-17.24 0-29.12 11.66-11.87 11.67-11.87 28.91 0 17.24 11.72 29.12 11.73 11.87 28.85 11.87t29.06-11.66ZM480.28-87.87q-81.19 0-152.62-30.62-71.44-30.62-125-84.17-53.55-53.56-84.17-124.95Q87.87-399 87.87-480.46q0-81.45 30.62-152.38 30.62-70.94 84.17-124.5 53.56-53.55 124.95-84.17 71.39-30.62 152.85-30.62 81.45 0 152.38 30.62 70.94 30.62 124.5 84.17 53.55 53.56 84.17 124.72 30.62 71.16 30.62 152.34 0 81.19-30.62 152.62-30.62 71.44-84.17 125-53.56 53.55-124.72 84.17-71.16 30.62-152.34 30.62Zm-.28-83q129.04 0 219.09-90.04 90.04-90.05 90.04-219.09 0-129.04-90.04-219.09-90.05-90.04-219.09-90.04-129.04 0-219.09 90.04-90.04 90.05-90.04 219.09 0 129.04 90.04 219.09 90.05 90.04 219.09 90.04ZM480-480Z"/></svg>

package/assets/material-symbols/info_40px.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" height="40" viewBox="0 -960 960 960" width="40"><path d="M445.72-277.05h72.56V-520h-72.56v242.95Zm62.24-326.08q11.36-11.11 11.36-27.54 0-17.17-11.3-28.58-11.3-11.4-28.01-11.4-16.88 0-28.11 11.4-11.22 11.41-11.22 28.5 0 16.53 11.37 27.63 11.36 11.11 27.95 11.11t27.96-11.12ZM480.2-73.3q-84.44 0-158.48-31.96-74.03-31.96-129.27-87.19-55.23-55.24-87.19-129.3Q73.3-395.82 73.3-480.31q0-84.5 31.96-158.58 31.96-74.09 87.17-129t129.28-86.94q74.08-32.03 158.59-32.03t158.61 32.02q74.11 32.02 129 86.91 54.9 54.88 86.92 129.08 32.03 74.2 32.03 158.67 0 84.46-32.03 158.5-32.03 74.03-86.94 129.12t-129.08 87.17Q564.64-73.3 480.2-73.3Zm.13-75.76q138.05 0 234.33-96.51 96.28-96.52 96.28-234.76 0-138.05-96.16-234.33-96.15-96.28-234.86-96.28-137.79 0-234.33 96.16-96.53 96.15-96.53 234.86 0 137.79 96.51 234.33 96.52 96.53 234.76 96.53ZM480-480Z"/></svg>

package/assets/material-symbols/menu_24px.svg

@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" height="24" viewBox="0 -960 960 960" width="24"><path d="M120-240v-80h720v80H120Zm0-200v-80h720v80H120Zm0-200v-80h720v80H120Z"/></svg>
+<svg xmlns="http://www.w3.org/2000/svg" height="24" viewBox="0 -960 960 960" width="24"><path d="M111.87-228.28v-91h736.26v91H111.87Zm0-206.22v-91h736.26v91H111.87Zm0-206.22v-91h736.26v91H111.87Z"/></svg>

package/assets/material-symbols/open_in_new_20px.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" height="20" viewBox="0 -960 960 960" width="20"><path d="M218.87-135.87q-34.48 0-58.74-24.26-24.26-24.26-24.26-58.74v-522.26q0-34.48 24.26-58.74 24.26-24.26 58.74-24.26H480v83H218.87v522.26h522.26V-480h83v261.13q0 34.48-24.26 58.74-24.26 24.26-58.74 24.26H218.87ZM394.41-336 336-394.41l346.72-346.72H576v-83h248.13V-576h-83v-106.72L394.41-336Z"/></svg>

package/assets/material-symbols/search_20px.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" height="20" viewBox="0 -960 960 960" width="20"><path d="M764.52-134.91 523.85-375.59q-29.76 21.05-65.44 33.07-35.67 12.02-76.29 12.02-102.19 0-173.86-71.67-71.67-71.68-71.67-173.83t71.67-173.83q71.67-71.67 173.83-71.67 102.15 0 173.82 71.67 71.68 71.68 71.68 173.86 0 40.86-12.02 76.3-12.03 35.43-33.07 64.95l240.91 241.15-58.89 58.66ZM382.09-413.5q67.84 0 115.17-47.33 47.33-47.32 47.33-115.17t-47.33-115.17q-47.33-47.33-115.17-47.33-67.85 0-115.18 47.33-47.32 47.32-47.32 115.17t47.32 115.17q47.33 47.33 115.18 47.33Z"/></svg>

package/assets/material-symbols/smart_display_24px.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" height="24" viewBox="0 -960 960 960" width="24"><path d="M379.28-296.65 664.3-480 379.28-663.35v366.7ZM162.87-151.87q-37.78 0-64.39-26.61t-26.61-64.39v-474.26q0-37.78 26.61-64.39t64.39-26.61h634.26q37.78 0 64.39 26.61t26.61 64.39v474.26q0 37.78-26.61 64.39t-64.39 26.61H162.87Zm0-91h634.26v-474.26H162.87v474.26Zm0 0v-474.26 474.26Z"/></svg>

package/assets/material-symbols/south_east_20px.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" height="20" viewBox="0 -960 960 960" width="20"><path d="M380.41-208.59v-83h229.35L183.87-717.48l58.65-58.65 425.89 425.89v-229.35h83v371h-371Z"/></svg>

package/assets/material-symbols/warning_20px.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" height="20" viewBox="0 -960 960 960" width="20"><path d="M41.07-139.93 480-872.13l438.93 732.2H41.07Zm139.91-79.42h598.04L480-717.3 180.98-219.35Zm325.24-56.14q10.98-10.76 10.98-26.21 0-15.45-10.77-26.31t-26.22-10.86q-15.45 0-26.43 10.65t-10.98 26.1q0 15.45 10.77 26.42 10.77 10.98 26.22 10.98t26.43-10.77ZM444-384h72v-189.37h-72V-384Zm36-84.33Z"/></svg>

package/assets/material-symbols/warning_40px.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" height="40" viewBox="0 -960 960 960" width="40"><path d="M34.18-116.57 480-886.86l445.82 770.29H34.18Zm126.17-72.97h639.3L480-741.09 160.35-189.54Zm346.79-59.03q9.9-10.02 9.9-24.47 0-14.46-10.02-24.24-10.01-9.78-24.47-9.78-14.46 0-24.35 9.9-9.9 9.89-9.9 24.35t10.01 24.35q10.02 9.9 24.47 9.9 14.46 0 24.36-10.01ZM449.33-352H516v-213.85h-66.67V-352ZM480-465.31Z"/></svg>

package/build/bundle.ts

@@ -19,6 +19,13 @@ import type { SiteVariables } from './types';
 import timezones from '../src/timezone/timezones.json' with { type: 'json' };
 import pkg from '../package.json' with { type: 'json' };
 import { renderMaterialSymbolVariables } from './material-symbols';
+import {
+  getSerifFontStack,
+  getSerifMonoFontStack,
+  renderCustomFontFaceScss,
+  renderCustomFontTuningScss,
+  renderFontFeatureSettings,
+} from './custom-fonts';
 
 interface BunBuildPlugin {
   name: string;
@@ -62,6 +69,10 @@ function renderThemeScss(siteVariables: SiteVariables): string {
   const bgTraceLineActive = `hsl(${traceLineActiveHue}deg 100% 86%)`;
   const bgTraceLineActiveDark = `hsl(${traceLineActiveHue}deg 90% 18%)`;
   const materialSymbolVariables = renderMaterialSymbolVariables();
+  const customFontFaces = renderCustomFontFaceScss(siteVariables.fontOverrides);
+  const customFontTuning = renderCustomFontTuningScss(
+    siteVariables.fontOverrides,
+  );
 
   const renderedTemplate = _.template(template)({
     ...theme,
@@ -73,11 +84,19 @@ function renderThemeScss(siteVariables: SiteVariables): string {
     linkColorHoverDark,
     bgTraceLineActive,
     bgTraceLineActiveDark,
+    serifFontStack: getSerifFontStack(siteVariables.fontOverrides),
+    serifMonoFontStack: getSerifMonoFontStack(siteVariables.fontOverrides),
+    serifFontFeatureSettings: renderFontFeatureSettings(
+      siteVariables.fontOverrides?.serif,
+    ),
+    serifMonoFontFeatureSettings: renderFontFeatureSettings(
+      siteVariables.fontOverrides?.serifMono,
+    ),
   });
-  const rendered = renderedTemplate.replace(
-    '/* TADA_MATERIAL_SYMBOL_VARIABLES */',
-    materialSymbolVariables,
-  );
+  const rendered = renderedTemplate
+    .replace('/* TADA_CUSTOM_FONT_FACES */', customFontFaces)
+    .replace('/* TADA_CUSTOM_FONT_TUNING */', customFontTuning)
+    .replace('/* TADA_MATERIAL_SYMBOL_VARIABLES */', materialSymbolVariables);
 
   const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'tada-'));
   const configDir = path.join(tmpDir, 'config');

package/build/custom-fonts.ts

@@ -0,0 +1,300 @@
+import fs from 'fs';
+import path from 'path';
+import * as fontkit from 'fontkit';
+import type { FontFamilyOverride, FontOverrides } from './types';
+
+export const CUSTOM_FONT_FACE_DEFINITIONS = Object.freeze({
+  regular: Object.freeze({ fontStyle: 'normal', fontWeight: 400 }),
+  italic: Object.freeze({ fontStyle: 'italic', fontWeight: 400 }),
+  bold: Object.freeze({ fontStyle: 'normal', fontWeight: 700 }),
+  boldItalic: Object.freeze({ fontStyle: 'italic', fontWeight: 700 }),
+});
+
+export const CUSTOM_FONT_FAMILY_DEFINITIONS = Object.freeze({
+  serif: Object.freeze({ configKey: 'serif', cssFamily: 'Tada Custom Serif' }),
+  serifMono: Object.freeze({
+    configKey: 'serifMono',
+    cssFamily: 'Tada Custom Serif Mono',
+  }),
+});
+
+export type CustomFontFamilyKey = keyof typeof CUSTOM_FONT_FAMILY_DEFINITIONS;
+export type CustomFontFaceKey = keyof typeof CUSTOM_FONT_FACE_DEFINITIONS;
+
+const FACE_KEYS = Object.freeze(
+  Object.keys(CUSTOM_FONT_FACE_DEFINITIONS) as CustomFontFaceKey[],
+);
+const FAMILY_KEYS = Object.freeze(
+  Object.keys(CUSTOM_FONT_FAMILY_DEFINITIONS) as CustomFontFamilyKey[],
+);
+
+interface ParsedFont {
+  availableFeatures: readonly string[];
+}
+
+export interface CustomFontValidationOptions {
+  fontOverrides: FontOverrides | undefined;
+  publicDir: string;
+  publicFiles: ReadonlySet<string>;
+  readFile?: (filePath: string) => Buffer;
+  parseFont?: (contents: Buffer) => ParsedFont;
+}
+
+export function isValidPublicWoff2Path(filePath: string): boolean {
+  if (
+    filePath.length === 0 ||
+    filePath.startsWith('/') ||
+    /^[A-Za-z]:/.test(filePath) ||
+    filePath.includes('\\') ||
+    filePath.includes('?') ||
+    filePath.includes('#') ||
+    !filePath.endsWith('.woff2')
+  ) {
+    return false;
+  }
+
+  const segments = filePath.split('/');
+  return segments.every(
+    segment => segment.length > 0 && segment !== '.' && segment !== '..',
+  );
+}
+
+export function resolvePublicFontPath(
+  publicDir: string,
+  filePath: string,
+): string {
+  return path.resolve(publicDir, ...filePath.split('/'));
+}
+
+export function encodePublicAssetPath(filePath: string): string {
+  return filePath
+    .split('/')
+    .map(segment => encodeURIComponent(segment).replaceAll("'", '%27'))
+    .join('/');
+}
+
+export function renderFontFeatureSettings(
+  family: FontFamilyOverride | undefined,
+): string {
+  return family?.features?.length
+    ? family.features.map(feature => `'${feature}'`).join(', ')
+    : 'normal';
+}
+
+export function renderCustomFontFaceScss(
+  fontOverrides: FontOverrides | undefined,
+): string {
+  const rules: string[] = [];
+  for (const familyKey of FAMILY_KEYS) {
+    const family = fontOverrides?.[familyKey];
+    if (!family) {
+      continue;
+    }
+    const cssFamily = CUSTOM_FONT_FAMILY_DEFINITIONS[familyKey].cssFamily;
+    for (const faceKey of FACE_KEYS) {
+      const filePath = family[faceKey];
+      if (!filePath) {
+        continue;
+      }
+      const face = CUSTOM_FONT_FACE_DEFINITIONS[faceKey];
+      rules.push(`  @font-face {
+    font-family: '${cssFamily}';
+    font-style: ${face.fontStyle};
+    font-weight: ${face.fontWeight};
+    src: url('${encodePublicAssetPath(filePath)}') format('woff2');
+    font-display: swap;
+  }`);
+    }
+  }
+  return rules.join('\n\n');
+}
+
+const HEADING_SIZES = Object.freeze({
+  h1: 2.5,
+  h2: 1.5,
+  h3: 1.17,
+  h4: 1,
+  h5: 0.83,
+  h6: 0.67,
+});
+
+function formatCssNumber(value: number): string {
+  return Number(value.toFixed(4)).toString();
+}
+
+export function renderCustomFontTuningScss(
+  fontOverrides: FontOverrides | undefined,
+): string {
+  const rules: string[] = [];
+  const serifTuning = fontOverrides?.serif?.tuning;
+  const monoTuning = fontOverrides?.serifMono?.tuning;
+  const rootSelector = ":root[data-font-preference='serif']";
+
+  if (serifTuning?.scale !== undefined) {
+    rules.push(
+      `  ${rootSelector} {\n    --font-size: ${formatCssNumber(serifTuning.scale)}rem;\n  }`,
+    );
+  }
+
+  if (serifTuning?.lineHeight !== undefined) {
+    rules.push(
+      `  ${rootSelector} main.body {\n    line-height: ${formatCssNumber(serifTuning.lineHeight)};\n  }`,
+    );
+  }
+
+  if (
+    serifTuning?.scale !== undefined ||
+    serifTuning?.lineHeight !== undefined
+  ) {
+    rules.push(
+      `  ${rootSelector} main.body > :is(footer, .appearance-pickers, .slides-header, .file-header) {\n    font-size: var(--font-size);\n    line-height: var(--line-height);\n  }`,
+    );
+  }
+
+  if (
+    serifTuning?.scale !== undefined ||
+    serifTuning?.headingScale !== undefined
+  ) {
+    const headingScale = serifTuning.headingScale ?? 1;
+    for (const [heading, size] of Object.entries(HEADING_SIZES)) {
+      rules.push(
+        `  ${rootSelector} .main-content ${heading}:not(.file-title) { font-size: ${formatCssNumber(size * headingScale)}rem; }`,
+      );
+      rules.push(
+        `  ${rootSelector} body.is-presenting .main-content .slide ${heading}:not(.file-title) { font-size: ${formatCssNumber(size * headingScale)}em; }`,
+      );
+    }
+  }
+
+  if (serifTuning?.headingWeight !== undefined) {
+    rules.push(
+      `  ${rootSelector} .main-content :is(h1, h2, h3, h4, h5, h6):not(.file-title) {\n    font-weight: ${serifTuning.headingWeight};\n  }`,
+    );
+  }
+
+  if (monoTuning?.scale !== undefined || monoTuning?.lineHeight !== undefined) {
+    const declarations: string[] = [];
+    if (monoTuning.scale !== undefined) {
+      declarations.push(
+        `--mono-font-size: ${formatCssNumber(monoTuning.scale)}em;`,
+      );
+    }
+    if (monoTuning.lineHeight !== undefined) {
+      declarations.push(
+        `--mono-line-height: ${formatCssNumber(monoTuning.lineHeight)};`,
+      );
+    }
+    rules.push(`  ${rootSelector} {\n    ${declarations.join('\n    ')}\n  }`);
+  }
+
+  return rules.join('\n\n');
+}
+
+export function getSerifFontStack(
+  fontOverrides: FontOverrides | undefined,
+): string {
+  const custom = fontOverrides?.serif
+    ? `'${CUSTOM_FONT_FAMILY_DEFINITIONS.serif.cssFamily}', `
+    : '';
+  return `${custom}'Source Serif 4', 'Times New Roman', 'Times', serif`;
+}
+
+export function getSerifMonoFontStack(
+  fontOverrides: FontOverrides | undefined,
+): string {
+  const custom = fontOverrides?.serifMono
+    ? `'${CUSTOM_FONT_FAMILY_DEFINITIONS.serifMono.cssFamily}', `
+    : '';
+  return `${custom}'Libertinus Mono', 'Courier New', 'Courier', monospace`;
+}
+
+function defaultParseFont(contents: Buffer): ParsedFont {
+  const font = fontkit.create(contents) as fontkit.Font;
+  return { availableFeatures: font.availableFeatures };
+}
+
+function validateFamily(
+  familyKey: CustomFontFamilyKey,
+  family: FontFamilyOverride,
+  options: Required<
+    Pick<CustomFontValidationOptions, 'readFile' | 'parseFont'>
+  > &
+    Pick<CustomFontValidationOptions, 'publicDir' | 'publicFiles'>,
+): string[] {
+  const diagnostics: string[] = [];
+  const parsedFaces: Partial<Record<CustomFontFaceKey, ParsedFont>> = {};
+
+  for (const faceKey of FACE_KEYS) {
+    const filePath = family[faceKey];
+    if (!filePath) {
+      continue;
+    }
+    const configPath = `fontOverrides.${familyKey}.${faceKey}`;
+    if (!isValidPublicWoff2Path(filePath)) {
+      diagnostics.push(
+        `${configPath} must be a public-relative POSIX path ending in .woff2`,
+      );
+      continue;
+    }
+
+    const absolutePath = resolvePublicFontPath(options.publicDir, filePath);
+    if (!options.publicFiles.has(absolutePath)) {
+      diagnostics.push(`${configPath} "${filePath}" does not exist in public/`);
+      continue;
+    }
+
+    let contents: Buffer;
+    try {
+      contents = options.readFile(absolutePath);
+    } catch {
+      diagnostics.push(`${configPath} "${filePath}" could not be read`);
+      continue;
+    }
+    if (contents.subarray(0, 4).toString('ascii') !== 'wOF2') {
+      diagnostics.push(`${configPath} "${filePath}" is not a WOFF2 font`);
+      continue;
+    }
+    try {
+      parsedFaces[faceKey] = options.parseFont(contents);
+    } catch {
+      diagnostics.push(`${configPath} "${filePath}" is not a valid WOFF2 font`);
+    }
+  }
+
+  for (const feature of family.features ?? []) {
+    for (const faceKey of FACE_KEYS) {
+      const parsed = parsedFaces[faceKey];
+      if (parsed && !parsed.availableFeatures.includes(feature)) {
+        diagnostics.push(
+          `fontOverrides.${familyKey}.features "${feature}" is not supported by fontOverrides.${familyKey}.${faceKey}`,
+        );
+      }
+    }
+  }
+
+  return diagnostics;
+}
+
+export function validateCustomFontOverrides(
+  options: CustomFontValidationOptions,
+): string[] {
+  const readFile = options.readFile ?? fs.readFileSync;
+  const parseFont = options.parseFont ?? defaultParseFont;
+  const diagnostics: string[] = [];
+
+  for (const familyKey of FAMILY_KEYS) {
+    const family = options.fontOverrides?.[familyKey];
+    if (family) {
+      diagnostics.push(
+        ...validateFamily(familyKey, family, {
+          publicDir: options.publicDir,
+          publicFiles: options.publicFiles,
+          readFile,
+          parseFont,
+        }),
+      );
+    }
+  }
+
+  return diagnostics;
+}

package/build/generate-fonts.ts

@@ -2,6 +2,7 @@ import fs from 'fs';
 import path from 'path';
 import { getPackageDir } from './utils/paths';
 import { makeLogger } from './log';
+import type { SiteVariables } from './types';
 
 const log = makeLogger(import.meta.url);
 const FONTS_DIR = path.join(getPackageDir(), 'fonts');
@@ -17,10 +18,35 @@ export const DEFAULT_FONT_PRELOAD_FILES = {
   ],
 } as const;
 
+export interface DefaultFontPreloadFile {
+  filePath: string;
+  source: 'package' | 'public';
+}
+
 export function getDefaultFontPreloadFiles(
-  defaultFont: 'sans' | 'serif' | undefined,
-): readonly string[] {
-  return DEFAULT_FONT_PRELOAD_FILES[defaultFont ?? 'sans'];
+  siteVariables: Pick<SiteVariables, 'defaultFont' | 'fontOverrides'>,
+): readonly DefaultFontPreloadFile[] {
+  if ((siteVariables.defaultFont ?? 'sans') === 'sans') {
+    return DEFAULT_FONT_PRELOAD_FILES.sans.map(filePath => ({
+      filePath,
+      source: 'package',
+    }));
+  }
+
+  return [
+    siteVariables.fontOverrides?.serif?.regular
+      ? {
+          filePath: siteVariables.fontOverrides.serif.regular,
+          source: 'public',
+        }
+      : { filePath: DEFAULT_FONT_PRELOAD_FILES.serif[0], source: 'package' },
+    siteVariables.fontOverrides?.serifMono?.regular
+      ? {
+          filePath: siteVariables.fontOverrides.serifMono.regular,
+          source: 'public',
+        }
+      : { filePath: DEFAULT_FONT_PRELOAD_FILES.serif[1], source: 'package' },
+  ];
 }
 
 export function copyFonts(distDir: string): void {

package/build/material-symbols.ts

@@ -5,43 +5,78 @@ import { getPackageDir } from './utils/paths';
 export const MATERIAL_SYMBOL_CONFIG = Object.freeze({
   family: 'Material Symbols Outlined',
   fill: 0,
-  weight: 400,
+  weight: 500,
   grade: 0,
-  opticalSize: 24,
+  opticalSizes: Object.freeze([20, 24, 40] as const),
   viewBox: '0 -960 960 960',
-  source:
-    'https://github.com/google/material-design-icons/tree/master/symbols/web',
+  source: 'https://fonts.google.com/icons',
 } as const);
 
 export const MATERIAL_SYMBOLS = Object.freeze({
-  tada: Object.freeze({ cssVariable: '--icon-tada', symbol: 'celebration' }),
+  tada: Object.freeze({
+    cssVariable: '--icon-tada',
+    symbol: 'celebration',
+    opticalSize: 24,
+  }),
   contrastStandard: Object.freeze({
     cssVariable: '--icon-contrast-standard',
     symbol: 'contrast_rtl_off',
+    opticalSize: 20,
   }),
   contrastHigh: Object.freeze({
     cssVariable: '--icon-contrast-high',
     symbol: 'contrast',
+    opticalSize: 20,
+  }),
+  info: Object.freeze({
+    cssVariable: '--icon-info',
+    symbol: 'info',
+    opticalSize: 40,
+  }),
+  infoCompact: Object.freeze({
+    cssVariable: '--icon-info-compact',
+    symbol: 'info',
+    opticalSize: 20,
+  }),
+  warning: Object.freeze({
+    cssVariable: '--icon-warning',
+    symbol: 'warning',
+    opticalSize: 40,
+  }),
+  warningCompact: Object.freeze({
+    cssVariable: '--icon-warning-compact',
+    symbol: 'warning',
+    opticalSize: 20,
+  }),
+  parent: Object.freeze({
+    cssVariable: '--icon-parent',
+    symbol: 'south_east',
+    opticalSize: 20,
+  }),
+  search: Object.freeze({
+    cssVariable: '--icon-search',
+    symbol: 'search',
+    opticalSize: 20,
   }),
-  info: Object.freeze({ cssVariable: '--icon-info', symbol: 'info' }),
-  warning: Object.freeze({ cssVariable: '--icon-warning', symbol: 'warning' }),
-  parent: Object.freeze({ cssVariable: '--icon-parent', symbol: 'south_east' }),
-  search: Object.freeze({ cssVariable: '--icon-search', symbol: 'search' }),
   externalLink: Object.freeze({
     cssVariable: '--icon-external-link',
-    symbol: 'north_east',
+    symbol: 'open_in_new',
+    opticalSize: 20,
   }),
-  headingAnchor: Object.freeze({
-    cssVariable: '--icon-heading-anchor',
-    symbol: 'tag',
+  headingPresent: Object.freeze({
+    cssVariable: '--icon-heading-present',
+    symbol: 'smart_display',
+    opticalSize: 24,
   }),
   headerMenu: Object.freeze({
     cssVariable: '--icon-header-menu',
     symbol: 'menu',
+    opticalSize: 24,
   }),
   headerClose: Object.freeze({
     cssVariable: '--icon-header-close',
     symbol: 'close',
+    opticalSize: 24,
   }),
 } as const);
 
@@ -56,11 +91,14 @@ function getAssetPath(packageDir: string, symbol: MaterialSymbol): string {
   return path.join(
     packageDir,
     'assets/material-symbols',
-    `${symbol.symbol}_${MATERIAL_SYMBOL_CONFIG.opticalSize}px.svg`,
+    `${symbol.symbol}_${symbol.opticalSize}px.svg`,
   );
 }
 
-function isConfiguredSvg(svg: string): boolean {
+function isConfiguredSvg(
+  svg: string,
+  opticalSize: MaterialSymbol['opticalSize'],
+): boolean {
   const svgTag = svg.match(/<svg\b[^>]*>/)?.[0];
   if (!svgTag) {
     return false;
@@ -70,8 +108,8 @@ function isConfiguredSvg(svg: string): boolean {
     new RegExp(`\\b${name}=["']${value}["']`).test(svgTag);
 
   return (
-    hasAttribute('width', String(MATERIAL_SYMBOL_CONFIG.opticalSize)) &&
-    hasAttribute('height', String(MATERIAL_SYMBOL_CONFIG.opticalSize)) &&
+    hasAttribute('width', String(opticalSize)) &&
+    hasAttribute('height', String(opticalSize)) &&
     hasAttribute('viewBox', MATERIAL_SYMBOL_CONFIG.viewBox)
   );
 }
@@ -94,14 +132,14 @@ export function renderMaterialSymbolVariables({
         );
       }
 
-      if (!isConfiguredSvg(svg)) {
+      if (!isConfiguredSvg(svg, symbol.opticalSize)) {
         throw new Error(
-          `Material Symbol "${symbol.symbol}" does not match the configured ${MATERIAL_SYMBOL_CONFIG.opticalSize}px SVG format: ${assetPath}`,
+          `Material Symbol "${symbol.symbol}" does not match the configured ${symbol.opticalSize}px SVG format: ${assetPath}`,
         );
       }
 
       const dataUri = `data:image/svg+xml,${encodeURIComponent(svg.trim())}`;
-      return `  ${symbol.cssVariable}: url("${dataUri}");`;
+      return `  ${symbol.cssVariable}: url("${dataUri}");\n  ${symbol.cssVariable}-size: ${symbol.opticalSize}px;`;
     })
     .join('\n');
 }

package/build/pipeline.ts

@@ -45,7 +45,7 @@ export async function runPipeline(
   let published = false;
 
   try {
-    const configDiagnostics = validateConfig(scan);
+    const configDiagnostics = validateConfig(scan, siteVariables);
     if (configDiagnostics.length > 0) {
       throw new Error(configDiagnostics[0].message);
     }

package/build/types.d.ts

@@ -3,6 +3,32 @@ import type { TadaProjectScan } from './source-model';
 
 export type PlainTextLanguage = 'text' | 'txt' | 'plain';
 
+export interface SerifFontTuning {
+  scale?: number;
+  lineHeight?: number;
+  headingScale?: number;
+  headingWeight?: 400 | 700;
+}
+
+export interface SerifMonoFontTuning {
+  scale?: number;
+  lineHeight?: number;
+}
+
+export interface FontFamilyOverride<Tuning = unknown> {
+  regular: string;
+  italic?: string;
+  bold?: string;
+  boldItalic?: string;
+  features?: string[];
+  tuning?: Tuning;
+}
+
+export interface FontOverrides {
+  serif?: FontFamilyOverride<SerifFontTuning>;
+  serifMono?: FontFamilyOverride<SerifMonoFontTuning>;
+}
+
 /** Site configuration loaded from site.dev.yaml/yml/json or site.prod.yaml/yml/json */
 export interface SiteVariables {
   base: string;
@@ -18,6 +44,7 @@ export interface SiteVariables {
   defaultTimeZone: string;
   defaultFont?: 'sans' | 'serif';
   defaultContrast?: 'standard' | 'high';
+  fontOverrides?: FontOverrides;
   features: FeatureConfig;
   extensionToShikiLanguage?: Record<
     string,