From 0ae53fa9c26f5187bd304d1844ed98741fd0b2f6 Mon Sep 17 00:00:00 2001
From: DavidBabinec <hello@davidbabinec.com>
Date: Tue, 13 Oct 2026 16:25:54 +0200
Subject: [PATCH 1/4] feat(fonts): seed heading, body and mono font role tokens
 on new sites

New sites had no font tokens and the codebase disagreed on names (docs said
font-primary, the AI prompt said font-heading), so content made for one site
did not resolve in another. Every brand-new site now starts with fallback-only
font-heading, font-body and font-mono tokens, the Core preset adds any a site
lacks without touching existing ones, and docs, schema comments and the AI
prompt use the role names. Existing sites are not migrated.
---
 docs/editor.md                                |   2 +-
 docs/features/agent.md                        |   2 +-
 docs/features/publisher.md                    |   2 +-
 docs/features/site-import.md                  |   2 +-
 docs/features/site-shell.md                   |  17 +-
 server/ai/tools/site/systemPrompt.ts          |   7 +-
 server/ai/tools/site/writeTools.ts            |   2 +-
 server/handlers/cms/setup.ts                  |   6 +-
 server/repositories/setup.ts                  |  17 ++
 server/repositories/site.ts                   |   2 +-
 src/__tests__/agent/tokenDigest.test.ts       |  13 ++
 src/__tests__/agent/tokenTools.test.ts        |  32 +++-
 src/__tests__/fonts/fontRoleTokens.test.ts    | 146 ++++++++++++++++++
 src/__tests__/server/setupFontRoles.test.ts   |  44 ++++++
 .../dashboard/components/OnboardingPanel.tsx  |   4 +-
 .../FontsSection/FontTokenDialog.tsx          |   7 +-
 .../FontsSection/FontsSection.tsx             |   6 +-
 .../pages/site/store/slices/site/defaults.ts  |   4 +-
 .../store/slices/site/framework/manage.ts     |  10 +-
 .../FrameworkManagerDialog.tsx                |  12 +-
 src/core/fonts/css.ts                         |   2 +-
 src/core/fonts/describe.ts                    |   6 +-
 src/core/fonts/index.ts                       |   1 +
 src/core/fonts/roles.ts                       |  84 ++++++++++
 src/core/fonts/schemas.ts                     |   6 +-
 src/core/framework/manageFramework.ts         |  42 +++--
 src/core/page-tree/index.ts                   |   2 +-
 src/core/page-tree/siteSettings.ts            |  21 ++-
 src/core/siteImport/types.ts                  |   6 +-
 29 files changed, 452 insertions(+), 55 deletions(-)
 create mode 100644 src/__tests__/fonts/fontRoleTokens.test.ts
 create mode 100644 src/__tests__/server/setupFontRoles.test.ts
 create mode 100644 src/core/fonts/roles.ts

diff --git a/docs/editor.md b/docs/editor.md
index 8ed3fdb9b..69a8b69f8 100644
--- a/docs/editor.md
+++ b/docs/editor.md
@@ -564,7 +564,7 @@ Property controls are driven by the selected node's module schema (`src/core/mod
 
 At the top of the Properties Panel, the selector picker is the single entry point for CSS rules that affect the selected element. Assigned class rules render as removable `TagPill` chips and are stored on `node.classIds`; matching ambient rules render as non-removable `TagPill` chips because they apply by selector matching, not assignment. Ambient rules that match only through a universal subject (`*`, `body.x *`, `*::before`) never render as pills — they style every element in their scope and stay reachable through the dropdown and the Selectors panel instead. The dropdown searches both class rules and ambient selectors, is capped to the picker width budget, and ellipsizes long selector labels instead of expanding across the editor. Ambient rows that do not match the selected canvas element stay visible but disabled with the mismatch reason, and selector-shaped input such as `.hero .title`, `h1`, or `a:hover` creates an ambient rule instead of a class.
 
-The Framework panel's **Type** tab stores Google/custom font assets and editable font tokens together under `site.settings.fonts`. Installed font assets own the self-hosted `@font-face` files; font tokens own the builder-facing variables such as `--font-primary`, the assigned font asset, and the fallback stack. The property-panel `font-family` control is a rich picker: token rows write `var(--font-primary)` so the selected node or class keeps following future token swaps, direct font rows write a concrete family stack as an escape hatch, and the text input still accepts manual values.
+The Framework panel's **Type** tab stores Google/custom font assets and editable font tokens together under `site.settings.fonts`. Installed font assets own the self-hosted `@font-face` files; font tokens own the builder-facing variables such as `--font-heading`, the assigned font asset, and the fallback stack. New sites start with the three role tokens `--font-heading`, `--font-body` and `--font-mono` as system-font fallbacks, and the "Manage framework" dialog adds any of them a site lacks (see [site-shell.md](features/site-shell.md) → font role tokens); the new-token dialog pre-fills the first missing role name. The property-panel `font-family` control is a rich picker: token rows write `var(--font-heading)` so the selected node or class keeps following future token swaps, direct font rows write a concrete family stack as an escape hatch, and the text input still accepts manual values.
 
 When the user clicks a rule in the Selectors Panel, the Properties Panel switches to **selector-editing mode** — the body shows style controls for that rule directly, and the header renders `SelectorHeader` with the rule's CSS selector, an inline rename input, and a delete button. The delete and rename actions are only shown for non-generated rules and require `site.style.edit`.
 
diff --git a/docs/features/agent.md b/docs/features/agent.md
index 699dc72a5..012768c08 100644
--- a/docs/features/agent.md
+++ b/docs/features/agent.md
@@ -577,7 +577,7 @@ Drivers that support explicit prompt-cache controls (Anthropic) apply `cache_con
 `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` is the literal `'__SYSTEM_PROMPT_DYNAMIC_BOUNDARY__'`, declared **once** in `server/ai/runtime/types.ts` and imported everywhere — prompt builders and every driver. A duplicate definition would silently break prompt caching on whichever driver drifted. Gated by `ai-driver-shared-helpers.test.ts`.
 
 **Static prefix key rules** (full text lives in `server/ai/tools/site/systemPrompt.ts`):
-- **Design system first.** Establish or reuse tokens before/while building (`site_set_color_tokens`, `site_set_type_scale`, `site_set_spacing_scale`, `site_set_font_tokens`), then reference them in CSS (`var(--<slug>)`, `var(--text-l)`, `var(--space-m)`, `var(--<font-var>)`) instead of raw hex/px/font-family. The dynamic suffix's `Tokens —` line shows what already exists; `(none …)` means no design system yet.
+- **Design system first.** Establish or reuse tokens before/while building (`site_set_color_tokens`, `site_set_type_scale`, `site_set_spacing_scale`, `site_set_font_tokens`), then reference them in CSS (`var(--<slug>)`, `var(--text-l)`, `var(--space-m)`, `var(--font-heading)`) instead of raw hex/px/font-family. Fonts use the role tokens `font-heading`, `font-body` and `font-mono`, which new sites already have; the prompt tells the model to change a typeface by updating the role token rather than inventing a new font variable. The dynamic suffix's `Tokens —` line shows what already exists; `(none …)` means no design system yet.
 - Structure as HTML (`site_insert_html` / `site_replace_node_html`); style with CSS in the same payload — a `<style>` block and/or `class=` attributes referencing the design tokens. The importer classifies selectors, so the agent never hand-builds classes at insert time.
 - `<style>` blocks inside imported HTML are parsed: class-bearing selectors become Selectors-panel classes while preserving complex selector text, class-free selectors (`a:hover`) become ambient rules, and supported `@keyframes` publish as raw keyframes CSS. `style=` attributes land on the node's inline styles. These are applied — not stripped.
 - CSS-only edits use an explicit `site_apply_css` operation: merge for additive patches, remove-properties for stale declarations, replace only with the selector's complete desired CSS, and delete for whole exact rules. Read the document first before destructive operations; grouped and ungrouped selectors are different identities.
diff --git a/docs/features/publisher.md b/docs/features/publisher.md
index f843d8c31..c31f99cf6 100644
--- a/docs/features/publisher.md
+++ b/docs/features/publisher.md
@@ -355,7 +355,7 @@ Two invariants:
 
 Both call sites read through the one helper so publish and Live preview can't drift.
 
-Installed fonts are emitted through the CSS bundle, not external `<link>` tags. The font CSS includes self-hosted `@font-face` rules for `site.settings.fonts.items` plus `:root` declarations for editable tokens such as `--font-primary`. A page rule can therefore keep `font-family: var(--font-primary)` while the token assignment changes site-wide.
+Installed fonts are emitted through the CSS bundle, not external `<link>` tags. The font CSS includes self-hosted `@font-face` rules for `site.settings.fonts.items` plus `:root` declarations for editable tokens such as `--font-heading`. A page rule can therefore keep `font-family: var(--font-heading)` while the token assignment changes site-wide.
 
 Plugins inject at four anchors. The order matters — see [docs/features/plugin-system.md](plugin-system.md) for the splicing rules.
 
diff --git a/docs/features/site-import.md b/docs/features/site-import.md
index 50d5cd5eb..d367ab873 100644
--- a/docs/features/site-import.md
+++ b/docs/features/site-import.md
@@ -296,7 +296,7 @@ The escape hatch for "this sheet's resets/styles must not leak into other pages
 
 - **`PageConflict`** — a desired slug collides with an existing page slug or with another slug in the same import batch.
 - **`RuleConflict`** — a `kind:'class'` rule's name collides with an existing class name. Ambient rules never conflict. One row per name even when the name arrives as several cascade fragments (they rename together).
-- **`TokenConflict`** — a design-token CSS custom property collides with an existing token. One type covers both colour tokens (keyed by `--<slug>`, against `framework.colors.tokens`) and font tokens (keyed by `--font-*`, against `fonts.tokens`), since both are just a `--var` contract referenced by `var(--x)` in the imported CSS. Imported tokens are deduped per kind upstream, so only site-vs-import collisions occur.
+- **`TokenConflict`** — a design-token CSS custom property collides with an existing token. One type covers both colour tokens (keyed by `--<slug>`, against `framework.colors.tokens`) and font tokens (keyed by `--font-*`, against `fonts.tokens`), since both are just a `--var` contract referenced by `var(--x)` in the imported CSS. Imported tokens are deduped per kind upstream, so only site-vs-import collisions occur. New sites start with the font role tokens `font-heading`, `font-body` and `font-mono`, so an import that defines one of those variables surfaces a font conflict there too; choosing overwrite binds the site's role token to the imported stack.
 - **`CrossSheetClassConflict`** — two imported page cascades define the same class differently (see "Cross-sheet class conflicts" above). Keyed by `(desiredName, definitionId)`; resolutions apply FIRST in `applyConflictResolutions` so a renamed definition no longer participates in the site-vs-import conflict on the original name.
 
 Page slugs can be slash-delimited public paths. Root `index.html` stays the homepage slug `index`; nested `index.html` files use their directory route, so `documentation/index.html` imports as `/documentation` and does not collide with `download-version/index.html`.
diff --git a/docs/features/site-shell.md b/docs/features/site-shell.md
index 67694b229..0242b4718 100644
--- a/docs/features/site-shell.md
+++ b/docs/features/site-shell.md
@@ -143,7 +143,19 @@ type SiteSettings = {
 
 The Colors / Framework Scale / Typography panels write to these sub-trees. All values are emitted into the published `framework.css` by `buildSiteFrameworkCss(site)` via `buildFrameworkPlan(settings)`, which returns the merged `:root` variable block and the locked utility classes from a single ordered traversal per family. (`generateFrameworkRootCss` / `generateFrameworkUtilityClasses` remain for single-output callers such as the canvas preview and the editor's class reconciler.)
 
-`fonts` is the installed font library and font-token contract (`src/core/fonts/`). `fonts.items` is the installed self-hosted font asset library (Google downloads and custom media-backed font files). `fonts.tokens` is the editable builder-facing contract: each token owns a stable CSS variable such as `font-primary`, an optional assigned `FontEntry` id, and a fallback stack. The publisher emits those as `:root { --font-primary: "Family", sans-serif; }`; editor controls should prefer `font-family: var(--font-primary)` over raw family names when the design should follow future font swaps.
+`fonts` is the installed font library and font-token contract (`src/core/fonts/`). `fonts.items` is the installed self-hosted font asset library (Google downloads and custom media-backed font files). `fonts.tokens` is the editable builder-facing contract: each token owns a stable CSS variable such as `font-heading`, an optional assigned `FontEntry` id, and a fallback stack. The publisher emits those as `:root { --font-heading: "Family", sans-serif; }`; editor controls should prefer `font-family: var(--font-heading)` over raw family names when the design should follow future font swaps.
+
+**Font role tokens** (`src/core/fonts/roles.ts`). Three role variables are the shared contract that templates, copied sections and the AI agent write against, so content made for one site renders in another:
+
+| Token | Name | Use | Seeded fallback |
+|-------|------|-----|-----------------|
+| `font-heading` | Heading | headings and display type | `system-ui, -apple-system, Segoe UI, Roboto, sans-serif` |
+| `font-body` | Body | running text | same system sans stack |
+| `font-mono` | Mono | code, data and mono labels | `ui-monospace, SFMono-Regular, Menlo, Consolas, monospace` |
+
+They are seeded fallback-only (no `familyId`), so a new site renders them without downloading anything; the user binds real families in the Fonts panel. Nothing styles `body` or headings with them automatically: the publisher reset pins `body` to the system stack and authored CSS opts in with `var(--font-body)` / `var(--font-heading)`.
+
+**New-site settings.** `createNewSiteSettings()` (`src/core/page-tree/siteSettings.ts`) is what every brand-new site starts with: `{ shortcuts: {}, fonts: { items: [], tokens: <the three role tokens> } }`. First-run setup writes it into the new shell (`newSiteShellStorage()` in `server/repositories/site.ts`) and the editor's draft bootstrap uses it through `createDefaultSiteDocument`. `DEFAULT_SITE_SETTINGS` (`{ shortcuts: {} }`) stays the read-time fallback for a stored shell without settings, so an existing site never gains tokens on upgrade. Applying the Core Framework preset (Full or Variables only) adds whichever role tokens a site lacks, matched by variable, and never changes tokens the site already has; choosing None leaves font tokens alone.
 
 **Variable normalization** (`src/admin/pages/site/store/slices/site/fontActions.ts`): the `variable` field stores a slug without the leading `--`. User input is trimmed, lowercased, and invalid character runs replaced with `-`. Leading `--` is stripped before storage. Duplicate variables within a site are rejected. Examples: `--font Brand` → `font-brand`, `Editorial` → `font-editorial`.
 
@@ -761,7 +773,7 @@ A plugin canvas module can then `import * as THREE from 'three'` and it resolves
 - [docs/reference/design-tokens.md](../reference/design-tokens.md) — editor token catalog
 - Source-of-truth files:
   - `src/core/page-tree/siteDocument.ts` — `SiteShellSchema`, `SiteDocument`, `parseSiteDocument`
-  - `src/core/page-tree/siteSettings.ts` — `SiteSettingsSchema`, `DEFAULT_SITE_SETTINGS`, `parseSiteSettings`
+  - `src/core/page-tree/siteSettings.ts` — `SiteSettingsSchema`, `DEFAULT_SITE_SETTINGS`, `createNewSiteSettings`, `parseSiteSettings`
   - `src/core/page-tree/breakpoint.ts` — `BreakpointSchema`, `DEFAULT_BREAKPOINTS`
   - `src/core/page-tree/condition.ts` — `ConditionDefSchema`, `conditionId`, `conditionLabel`, `makeConditionDef`, `parseConditions`
   - `src/core/page-tree/styleRule.ts` — `StyleRuleSchema`
@@ -769,6 +781,7 @@ A plugin canvas module can then `import * as THREE from 'three'` and it resolves
   - `src/core/framework/generate.ts` — `buildFrameworkPlan`, `generateFrameworkRootCss`, `generateFrameworkUtilityClasses`
   - `src/core/fonts/schemas.ts` — `SiteFontsSettingsSchema`, `FontEntry`, `FontToken`
   - `src/core/fonts/css.ts` — `generateFontsCss`
+  - `src/core/fonts/roles.ts` — `FONT_ROLES`, `buildFontRoleTokens`, `mergeFontRoleTokens`
   - `src/core/files/schemas.ts` — `SiteFileSchema`, `SiteFileType`, `SiteFileBlobSchema`
   - `src/core/site-dependencies/manifest.ts` — `SitePackageJsonSchema`
   - `src/core/site-runtime/schemas.ts` — `SiteRuntimeConfigSchema`
diff --git a/server/ai/tools/site/systemPrompt.ts b/server/ai/tools/site/systemPrompt.ts
index 8c76d284b..e0853240a 100644
--- a/server/ai/tools/site/systemPrompt.ts
+++ b/server/ai/tools/site/systemPrompt.ts
@@ -27,7 +27,8 @@ Building:
 Design system first:
 - A consistent design comes from TOKENS, not repeated literals. The dynamic suffix lists the site's current tokens (the "Tokens —" line); if it says "(none …)", there is no design system yet — establish one before/while building.
 - Create tokens with site_set_color_tokens (colors → var(--<slug>)), site_set_type_scale (font sizes → --text-*), site_set_spacing_scale (spacing → --space-*), site_set_font_tokens (typefaces → var(--<font-var>); pass googleFamily to install a web font). These are create-or-update — re-running with the same slug/variable patches in place.
-- Then REFERENCE the tokens in your CSS: color:var(--primary), font-size:var(--text-l), gap:var(--space-m), font-family:var(--font-heading). Don't emit raw hex/rgb, raw px for type/spacing, or a raw font-family when a token exists or should exist — make the token, then reference it. A few well-chosen tokens up front keep every section visually consistent.
+- Fonts use three ROLE tokens: font-heading (headings, display type), font-body (running text), font-mono (code, data, mono labels). New sites already have all three as system-font fallbacks. To change a typeface, update the role token (site_set_font_tokens with variable "font-heading" + googleFamily) instead of inventing a new font variable; add one only for a genuinely extra role.
+- Then REFERENCE the tokens in your CSS: color:var(--primary), font-size:var(--text-l), gap:var(--space-m), font-family:var(--font-heading) on headings and var(--font-body) on running text. Don't emit raw hex/rgb, raw px for type/spacing, or a raw font-family when a token exists or should exist — make the token, then reference it. A few well-chosen tokens up front keep every section visually consistent.
 
 Structure as HTML, styling as CSS:
 - Structure goes in site_insert_html/site_replace_node_html as semantic HTML. Style it with CSS in the SAME call: a <style> block and/or class= attributes (the importer turns these into reusable classes + ambient rules), referencing the design tokens above. This is the clean default; do NOT hand-build classes node-by-node.
@@ -107,6 +108,10 @@ function describeTokenDigest(tokens: SnapshotTokens): string {
   if (parts.length === 0) {
     return 'Tokens: (none — no design system yet; establish one first with site_set_color_tokens / site_set_type_scale / site_set_spacing_scale / site_set_font_tokens)'
   }
+  // A new site starts with only the font role tokens: still no design system.
+  if (tokens.colors.length === 0 && tokens.typography.length === 0 && tokens.spacing.length === 0) {
+    parts.push('(no colors, type or spacing yet; establish them first with site_set_color_tokens / site_set_type_scale / site_set_spacing_scale)')
+  }
   return `Tokens — ${parts.join('; ')}`
 }
 
diff --git a/server/ai/tools/site/writeTools.ts b/server/ai/tools/site/writeTools.ts
index 465445cda..45dd9851c 100644
--- a/server/ai/tools/site/writeTools.ts
+++ b/server/ai/tools/site/writeTools.ts
@@ -368,7 +368,7 @@ const setFontTokensTool: AiTool = {
   execution: 'browser',
   requiredCapabilities: SITE_STYLE_CAPS,
   description:
-    'Create or update FONT tokens — named typefaces referenced as `var(--<variable>)`. Pass `googleFamily` (e.g. "Inter") to install a new Google web font (downloads the files, then binds the token to it); `variants` defaults to ["400","700"] and `subsets` to ["latin"]. Pass `familyId` to reference an already-installed family. Pass neither for a fallback-only/system token. Create-or-update is keyed by `variable` (defaults from `name`). Prefer exactly one of `googleFamily` or `familyId`; if both are sent, `googleFamily` wins and the stale `familyId` is ignored.',
+    'Create or update FONT tokens — named typefaces referenced as `var(--<variable>)`. Pass `googleFamily` (e.g. "Inter") to install a new Google web font (downloads the files, then binds the token to it); `variants` defaults to ["400","700"] and `subsets` to ["latin"]. Pass `familyId` to reference an already-installed family. Pass neither for a fallback-only/system token. Create-or-update is keyed by `variable` (defaults from `name`). Prefer the role variables `font-heading`, `font-body` and `font-mono`: new sites start with them as fallback-only system stacks, so setting a typeface means updating the role token. Prefer exactly one of `googleFamily` or `familyId`; if both are sent, `googleFamily` wins and the stale `familyId` is ignored.',
   inputSchema: SetFontTokensInputSchema,
 }
 
diff --git a/server/handlers/cms/setup.ts b/server/handlers/cms/setup.ts
index 332efe437..24158471d 100644
--- a/server/handlers/cms/setup.ts
+++ b/server/handlers/cms/setup.ts
@@ -18,7 +18,7 @@
 import { nanoid } from 'nanoid'
 import type { DbClient } from '../../db/client'
 import { hashPassword } from '../../auth/tokens'
-import { createSite, getSetupStatus } from '../../repositories/setup'
+import { createSite, getSetupStatus, newSiteShellStorage } from '../../repositories/setup'
 import { createUser } from '../../repositories/users'
 import { createAuditEvent } from '../../repositories/audit'
 import { createDataRow } from '../../repositories/data'
@@ -80,7 +80,7 @@ export async function handleSetupRoutes(req: Request, db: DbClient): Promise<Res
     return serializeCollabAwareWrite(async () => {
       let homePageId = ''
       const response = await db.transaction(async (tx) => {
-        await createSite(tx, siteName, {})
+        await createSite(tx, siteName, newSiteShellStorage())
         const owner = await createUser(tx, {
           id: nanoid(),
           email,
@@ -142,7 +142,7 @@ interface PublicSiteIdentity {
  * favicon resolve to null. TypeBox objects allow extra properties by default,
  * so validating only `faviconUrl` still type-checks it with zero `as` casts
  * while staying immune to unrelated settings fields. Every level is optional
- * so a freshly-created site (`settings_json = {}`) yields a null favicon
+ * so a shell without stored settings (`settings_json = {}`) yields a null favicon
  * instead of throwing.
  */
 const StoredSiteIdentitySchema = Type.Object({
diff --git a/server/repositories/setup.ts b/server/repositories/setup.ts
index b855349a2..70ab53a0a 100644
--- a/server/repositories/setup.ts
+++ b/server/repositories/setup.ts
@@ -1,6 +1,8 @@
 import { MAIN_BRANCH_ID } from '@core/branches'
+import { createNewSiteSettings, type SiteShell } from '@core/page-tree'
 import type { DbClient } from '../db/client'
 import { nowIso } from '@core/utils/isoDate'
+import { CMS_SITE_SCHEMA_VERSION } from './site'
 
 interface SetupStatus {
   hasSite: boolean
@@ -59,6 +61,21 @@ export function resetSetupStatusCacheForTests(): void {
   settledStatusByDb = new WeakMap()
 }
 
+/**
+ * The `settings_json` payload first-run setup writes for a brand-new site. It
+ * carries only the new-site settings (font role tokens); every other shell
+ * field takes its read-time default in `readStoredShell` (`./site`).
+ */
+export function newSiteShellStorage(): {
+  cmsSiteSchemaVersion: typeof CMS_SITE_SCHEMA_VERSION
+  site: Pick<SiteShell, 'settings'>
+} {
+  return {
+    cmsSiteSchemaVersion: CMS_SITE_SCHEMA_VERSION,
+    site: { settings: createNewSiteSettings() },
+  }
+}
+
 export async function createSite(
   db: DbClient,
   name: string,
diff --git a/server/repositories/site.ts b/server/repositories/site.ts
index 695de5158..f24ebf455 100644
--- a/server/repositories/site.ts
+++ b/server/repositories/site.ts
@@ -33,7 +33,7 @@ import { notifyShellWrite, serializeCollabAwareWrite } from './rowWriteEvents'
 import type { SiteRow } from '../types'
 import { nowIso } from '@core/utils/isoDate'
 
-const CMS_SITE_SCHEMA_VERSION = 1
+export const CMS_SITE_SCHEMA_VERSION = 1
 
 interface StoredSitePayload {
   cmsSiteSchemaVersion: 1
diff --git a/src/__tests__/agent/tokenDigest.test.ts b/src/__tests__/agent/tokenDigest.test.ts
index dd1ec555a..cfaeea2b7 100644
--- a/src/__tests__/agent/tokenDigest.test.ts
+++ b/src/__tests__/agent/tokenDigest.test.ts
@@ -40,11 +40,24 @@ function currentSuffix(): string {
 describe('token digest in the dynamic suffix', () => {
   it('emits the empty-state sentinel when no design system exists', () => {
     freshStore()
+    useEditorStore.setState((state) => {
+      delete state.site!.settings.fonts
+    })
     const suffix = currentSuffix()
     expect(suffix).toContain('Tokens: (none')
     expect(suffix).toContain('site_set_color_tokens')
   })
 
+  it('lists a new site\'s font role tokens and still asks for colors, type and spacing', () => {
+    freshStore()
+    const suffix = currentSuffix()
+    expect(suffix).toContain('--font-heading')
+    expect(suffix).toContain('--font-body')
+    expect(suffix).toContain('--font-mono')
+    expect(suffix).toContain('no colors, type or spacing yet')
+    expect(suffix).toContain('site_set_color_tokens')
+  })
+
   it('summarizes colors, type, spacing and fonts once established', async () => {
     freshStore()
     await executeAgentTool('site_set_color_tokens', { tokens: [{ slug: 'primary', lightValue: '#3b82f6' }] })
diff --git a/src/__tests__/agent/tokenTools.test.ts b/src/__tests__/agent/tokenTools.test.ts
index 3c3534410..102577f52 100644
--- a/src/__tests__/agent/tokenTools.test.ts
+++ b/src/__tests__/agent/tokenTools.test.ts
@@ -234,17 +234,33 @@ describe('executeAgentTool — set_font_tokens', () => {
   it('creates a fallback-only token with no install', async () => {
     freshStore()
     const result = await executeAgentTool('site_set_font_tokens', {
-      tokens: [{ name: 'Body', variable: 'font-body', fallback: 'sans-serif' }],
+      tokens: [{ name: 'Accent', variable: 'font-accent', fallback: 'serif' }],
     })
 
     const { tokens } = expectData<{ tokens: Array<{ variable: string; ref: string; action: string }> }>(result)
-    expect(tokens[0].variable).toBe('font-body')
-    expect(tokens[0].ref).toBe('var(--font-body)')
+    expect(tokens[0].variable).toBe('font-accent')
+    expect(tokens[0].ref).toBe('var(--font-accent)')
     expect(tokens[0].action).toBe('created')
 
+    // Added beside the three role tokens a new site starts with.
     const stored = site().settings.fonts!.tokens!
-    expect(stored).toHaveLength(1)
-    expect(stored[0].familyId).toBeUndefined()
+    expect(stored.map((t) => t.variable)).toEqual(['font-heading', 'font-body', 'font-mono', 'font-accent'])
+    expect(stored[3].familyId).toBeUndefined()
+  })
+
+  it('updates a seeded role token in place instead of adding a new one', async () => {
+    freshStore()
+    const result = await executeAgentTool('site_set_font_tokens', {
+      tokens: [{ name: 'Body', fallback: 'Georgia, serif' }],
+    })
+
+    const { tokens } = expectData<{ tokens: Array<{ variable: string; action: string }> }>(result)
+    expect(tokens[0].variable).toBe('font-body')
+    expect(tokens[0].action).toBe('updated')
+
+    const stored = site().settings.fonts!.tokens!
+    expect(stored).toHaveLength(3)
+    expect(stored.find((t) => t.variable === 'font-body')!.fallback).toBe('Georgia, serif')
   })
 
   it('installs a Google web font and binds the token to it', async () => {
@@ -310,7 +326,9 @@ describe('executeAgentTool — set_font_tokens', () => {
     })
     expect(result.ok).toBe(false)
     expect(result.error).toContain('Unknown font family')
-    // No token created on failure.
-    expect(site().settings.fonts?.tokens ?? []).toHaveLength(0)
+    // The seeded Heading role token is left as it was on failure.
+    const tokens = site().settings.fonts?.tokens ?? []
+    expect(tokens).toHaveLength(3)
+    expect(tokens.find((t) => t.variable === 'font-heading')!.familyId).toBeUndefined()
   })
 })
diff --git a/src/__tests__/fonts/fontRoleTokens.test.ts b/src/__tests__/fonts/fontRoleTokens.test.ts
new file mode 100644
index 000000000..d1f25e029
--- /dev/null
+++ b/src/__tests__/fonts/fontRoleTokens.test.ts
@@ -0,0 +1,146 @@
+/**
+ * Font role tokens: every new site starts with `font-heading`, `font-body` and
+ * `font-mono`; the Core preset adds the ones a site lacks; existing sites read
+ * through the settings fallback never gain them.
+ */
+import { beforeEach, describe, expect, it } from 'bun:test'
+import {
+  FONT_ROLES,
+  buildFontRoleTokens,
+  generateFontTokenVariablesCss,
+  mergeFontRoleTokens,
+  parseSiteFontsSettings,
+  suggestFontTokenName,
+  type FontToken,
+  type SiteFontsSettings,
+} from '@core/fonts'
+import { applyFrameworkPreset } from '@core/framework'
+import { DEFAULT_SITE_SETTINGS, createNewSiteSettings } from '@core/page-tree'
+import { useEditorStore } from '@site/store/store'
+import { makeSite } from '../fixtures'
+
+const ROLE_VARIABLES = ['font-heading', 'font-body', 'font-mono']
+
+function variables(fonts: SiteFontsSettings | undefined): string[] {
+  return (fonts?.tokens ?? []).map((token) => token.variable)
+}
+
+function customHeading(): FontToken {
+  return {
+    id: 'mine',
+    name: 'Display',
+    variable: 'font-heading',
+    familyId: 'fam-1',
+    fallback: 'serif',
+    order: 0,
+    createdAt: 1,
+    updatedAt: 1,
+  }
+}
+
+describe('font role tokens', () => {
+  it('builds fallback-only system-stack tokens for heading, body and mono', () => {
+    const tokens = buildFontRoleTokens()
+    expect(tokens.map((t) => [t.name, t.variable])).toEqual([
+      ['Heading', 'font-heading'],
+      ['Body', 'font-body'],
+      ['Mono', 'font-mono'],
+    ])
+    for (const token of tokens) expect(token.familyId).toBeUndefined()
+    expect(tokens[2].fallback).toContain('monospace')
+    expect(new Set(tokens.map((t) => t.id)).size).toBe(3)
+  })
+
+  it('survives the tolerant settings parser unchanged', () => {
+    const fonts: SiteFontsSettings = { items: [], tokens: buildFontRoleTokens() }
+    expect(parseSiteFontsSettings(structuredClone(fonts))).toEqual(fonts)
+  })
+
+  it('emits the role variables into :root', () => {
+    const css = generateFontTokenVariablesCss({ items: [], tokens: buildFontRoleTokens() })
+    expect(css).toContain('--font-heading: system-ui')
+    expect(css).toContain('--font-body: system-ui')
+    expect(css).toContain('--font-mono: ui-monospace')
+  })
+
+  it('merge adds only the missing roles and keeps an existing token untouched', () => {
+    const existing: SiteFontsSettings = { items: [], tokens: [customHeading()] }
+    const merged = mergeFontRoleTokens(existing)
+    expect(variables(merged)).toEqual(ROLE_VARIABLES)
+    expect(merged.tokens![0]).toEqual(customHeading())
+    expect(merged.tokens!.map((t) => t.order)).toEqual([0, 1, 2])
+    // Pure: the input keeps its single token.
+    expect(existing.tokens).toHaveLength(1)
+  })
+
+  it('merge matches by normalized variable and returns the input when complete', () => {
+    const complete: SiteFontsSettings = { items: [], tokens: buildFontRoleTokens() }
+    expect(mergeFontRoleTokens(complete)).toBe(complete)
+    expect(variables(mergeFontRoleTokens(undefined))).toEqual(ROLE_VARIABLES)
+  })
+
+  it('suggests the first missing role name for a new token', () => {
+    expect(suggestFontTokenName([])).toBe('Heading')
+    expect(suggestFontTokenName([{ variable: 'font-heading' }])).toBe('Body')
+    expect(suggestFontTokenName(FONT_ROLES)).toBe('Accent')
+  })
+})
+
+describe('new-site settings', () => {
+  it('seed every role token for a brand-new site', () => {
+    expect(variables(createNewSiteSettings().fonts)).toEqual(ROLE_VARIABLES)
+  })
+
+  it('leave the read-time fallback without fonts, so existing sites are not modified', () => {
+    expect(DEFAULT_SITE_SETTINGS.fonts).toBeUndefined()
+  })
+
+  it('are what the editor store creates a draft site with', () => {
+    const site = useEditorStore.getState().createSite('Fresh')
+    expect(variables(site.settings.fonts)).toEqual(ROLE_VARIABLES)
+  })
+})
+
+describe('Core preset font roles', () => {
+  it('adds the role tokens a site lacks for full and variables', () => {
+    for (const target of ['full', 'variables'] as const) {
+      const next = applyFrameworkPreset({ fonts: { items: [], tokens: [customHeading()] } }, target)
+      expect(variables(next.fonts)).toEqual(ROLE_VARIABLES)
+      expect(next.fonts!.tokens![0]).toEqual(customHeading())
+    }
+  })
+
+  it('leaves font tokens alone when removing the framework', () => {
+    const fonts: SiteFontsSettings = { items: [], tokens: [customHeading()] }
+    const next = applyFrameworkPreset({ fonts }, 'none')
+    expect(next.framework).toBeUndefined()
+    expect(next.fonts).toBe(fonts)
+  })
+
+  describe('store action', () => {
+    beforeEach(() => {
+      useEditorStore.setState({
+        site: makeSite(),
+        activePageId: 'page-1',
+        _historyPast: [],
+        _historyFuture: [],
+      } as Parameters<typeof useEditorStore.setState>[0])
+    })
+
+    it('setFrameworkPreset adds the role tokens to a site without fonts', () => {
+      expect(useEditorStore.getState().site!.settings.fonts).toBeUndefined()
+      useEditorStore.getState().setFrameworkPreset('full')
+      expect(variables(useEditorStore.getState().site!.settings.fonts)).toEqual(ROLE_VARIABLES)
+    })
+
+    it('setFrameworkPreset keeps the tokens a site already has', () => {
+      useEditorStore.setState((state) => {
+        state.site!.settings.fonts = { items: [], tokens: [customHeading()] }
+      })
+      useEditorStore.getState().setFrameworkPreset('variables')
+      const fonts = useEditorStore.getState().site!.settings.fonts
+      expect(variables(fonts)).toEqual(ROLE_VARIABLES)
+      expect(fonts!.tokens![0]).toEqual(customHeading())
+    })
+  })
+})
diff --git a/src/__tests__/server/setupFontRoles.test.ts b/src/__tests__/server/setupFontRoles.test.ts
new file mode 100644
index 000000000..db8675b15
--- /dev/null
+++ b/src/__tests__/server/setupFontRoles.test.ts
@@ -0,0 +1,44 @@
+/**
+ * First-run setup seeds the font role tokens into the new site's shell, while
+ * a shell that already exists without settings keeps reading without them:
+ * upgrading never injects tokens into a live site.
+ */
+import { describe, expect, it } from 'bun:test'
+import type { DbClient } from '../../../server/db'
+import { handleCmsRequest } from '../../../server/handlers/cms'
+import { MAIN_SCOPE } from '../../../server/branches/scope'
+import { createSite } from '../../../server/repositories/setup'
+import { getDraftSite } from '../../../server/repositories/site'
+import { createTestDb } from '../helpers/createTestDb'
+
+async function runSetup(db: DbClient): Promise<Response> {
+  return await handleCmsRequest(
+    new Request('http://localhost/admin/api/cms/setup', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ siteName: 'Test', email: 'owner@example.com', password: 'long-enough-password' }),
+    }),
+    db,
+  )
+}
+
+describe('setup font role tokens', () => {
+  it('seeds font-heading, font-body and font-mono into a brand-new site', async () => {
+    const { db } = await createTestDb()
+    expect((await runSetup(db)).status).toBe(201)
+
+    const shell = await getDraftSite(db, MAIN_SCOPE)
+    const tokens = shell?.settings.fonts?.tokens ?? []
+    expect(tokens.map((t) => t.variable)).toEqual(['font-heading', 'font-body', 'font-mono'])
+    expect(tokens.every((t) => t.familyId === undefined)).toBe(true)
+    expect(shell?.settings.shortcuts).toEqual({})
+  })
+
+  it('does not add tokens to an existing shell stored without settings', async () => {
+    const { db } = await createTestDb()
+    await createSite(db, 'Existing', {})
+
+    const shell = await getDraftSite(db, MAIN_SCOPE)
+    expect(shell?.settings.fonts).toBeUndefined()
+  })
+})
diff --git a/src/admin/pages/dashboard/components/OnboardingPanel.tsx b/src/admin/pages/dashboard/components/OnboardingPanel.tsx
index 09d2b7a3d..db5829ed2 100644
--- a/src/admin/pages/dashboard/components/OnboardingPanel.tsx
+++ b/src/admin/pages/dashboard/components/OnboardingPanel.tsx
@@ -138,7 +138,9 @@ export function OnboardingPanel({ facts, onDismiss, onFrameworkImported }: Onboa
       const loaded = await cmsAdapter.loadSite('default')
       if (!loaded) throw new Error('Site is not ready yet — finish setup first.')
       const { site, shellSeq } = loaded
-      site.settings.framework = applyFrameworkPreset(site.settings.framework, target)
+      const next = applyFrameworkPreset(site.settings, target)
+      site.settings.framework = next.framework
+      site.settings.fonts = next.fonts
       // Regenerate / prune the generated `framework:` utility classes (and strip
       // stale classIds off nodes) to match the new settings — the same reconcile
       // the in-editor store runs. Without it, removing the framework here would
diff --git a/src/admin/pages/site/panels/TypographyPanel/FontsSection/FontTokenDialog.tsx b/src/admin/pages/site/panels/TypographyPanel/FontsSection/FontTokenDialog.tsx
index a8408a4fc..bf5e20a7b 100644
--- a/src/admin/pages/site/panels/TypographyPanel/FontsSection/FontTokenDialog.tsx
+++ b/src/admin/pages/site/panels/TypographyPanel/FontsSection/FontTokenDialog.tsx
@@ -14,6 +14,8 @@ import styles from './FontsSection.module.css'
 
 interface FontTokenDialogProps {
   token?: FontToken
+  /** Name pre-filled when creating a token (ignored when editing `token`). */
+  defaultName: string
   fonts: FontEntry[]
   onCancel: () => void
   onSave: (input: {
@@ -26,13 +28,14 @@ interface FontTokenDialogProps {
 
 export function FontTokenDialog({
   token,
+  defaultName,
   fonts,
   onCancel,
   onSave,
 }: FontTokenDialogProps) {
   const firstFont = fonts[0]
-  const [name, setName] = useState(token?.name ?? 'Primary')
-  const [variable, setVariable] = useState(token?.variable ?? suggestFontTokenVariable(token?.name ?? 'Primary'))
+  const [name, setName] = useState(token?.name ?? defaultName)
+  const [variable, setVariable] = useState(token?.variable ?? suggestFontTokenVariable(defaultName))
   const [familyId, setFamilyId] = useState(token?.familyId ?? firstFont?.id ?? '')
   const [fallback, setFallback] = useState(token?.fallback ?? defaultFontTokenFallback(firstFont))
   const [error, setError] = useState<string | null>(null)
diff --git a/src/admin/pages/site/panels/TypographyPanel/FontsSection/FontsSection.tsx b/src/admin/pages/site/panels/TypographyPanel/FontsSection/FontsSection.tsx
index 1566ee67f..0ff4874be 100644
--- a/src/admin/pages/site/panels/TypographyPanel/FontsSection/FontsSection.tsx
+++ b/src/admin/pages/site/panels/TypographyPanel/FontsSection/FontsSection.tsx
@@ -25,6 +25,7 @@ import {
   defaultFontTokenFallback,
   resolveFontTokenStack,
   sortFontTokens,
+  suggestFontTokenName,
 } from '@core/fonts'
 import { deleteCmsFontFamily } from '@core/persistence/cmsFonts'
 import { EditSolidIcon } from 'pixel-art-icons/icons/edit-solid'
@@ -68,7 +69,9 @@ export function FontsSection() {
   function ensureTokenForFont(entry: FontEntry) {
     const currentTokens = useEditorStore.getState().site?.settings.fonts?.tokens ?? EMPTY_TOKENS
     if (currentTokens.some((token) => token.familyId === entry.id)) return
-    const tokenName = currentTokens.length === 0 ? 'Primary' : entry.family
+    // A site with no tokens yet gets a role token (`font-heading` first) so
+    // the first family lands on a shared role name, not a family-named one.
+    const tokenName = currentTokens.length === 0 ? suggestFontTokenName(currentTokens) : entry.family
     createFontToken({
       name: tokenName,
       variable: tokenName,
@@ -289,6 +292,7 @@ export function FontsSection() {
       {(tokenDialogOpen || editToken) && (
         <FontTokenDialog
           token={editToken ?? undefined}
+          defaultName={suggestFontTokenName(fontTokens)}
           fonts={fonts}
           onCancel={() => {
             setTokenDialogOpen(false)
diff --git a/src/admin/pages/site/store/slices/site/defaults.ts b/src/admin/pages/site/store/slices/site/defaults.ts
index 879cd8706..ecb440671 100644
--- a/src/admin/pages/site/store/slices/site/defaults.ts
+++ b/src/admin/pages/site/store/slices/site/defaults.ts
@@ -7,7 +7,7 @@ import {
   type Page,
   type SiteDocument,
   DEFAULT_BREAKPOINTS,
-  DEFAULT_SITE_SETTINGS,
+  createNewSiteSettings,
   createNode,
   createDefaultSiteExplorerOrganization,
 } from '@core/page-tree'
@@ -39,7 +39,7 @@ export function createDefaultSiteDocument(name: string): SiteDocument {
     packageJson: clonePackageJson(DEFAULT_SITE_PACKAGE_JSON),
     runtime: cloneSiteRuntimeConfig(DEFAULT_SITE_RUNTIME),
     breakpoints: DEFAULT_BREAKPOINTS,
-    settings: structuredClone(DEFAULT_SITE_SETTINGS),
+    settings: createNewSiteSettings(),
     styleRules: {},
     explorer: createDefaultSiteExplorerOrganization(),
     createdAt: Date.now(),
diff --git a/src/admin/pages/site/store/slices/site/framework/manage.ts b/src/admin/pages/site/store/slices/site/framework/manage.ts
index 562ba80a2..e3c37e5c3 100644
--- a/src/admin/pages/site/store/slices/site/framework/manage.ts
+++ b/src/admin/pages/site/store/slices/site/framework/manage.ts
@@ -2,8 +2,8 @@
  * Core Framework lifecycle store action — the editor side of the Manage
  * Framework dialog.
  *
- * `setFrameworkPreset` mutates `site.settings.framework` inside `mutateSite` and
- * then calls `reconcileFrameworkClasses(draft)`, which regenerates the desired
+ * `setFrameworkPreset` mutates `site.settings.framework` (and adds any missing
+ * font role tokens to `site.settings.fonts`) inside `mutateSite` and then calls `reconcileFrameworkClasses(draft)`, which regenerates the desired
  * framework class registry, prunes the rest, and strips stale `framework:`
  * classIds off every node. Because it runs through `mutateSite`, it is recorded
  * in the editor's undo history.
@@ -24,9 +24,11 @@ export function createFrameworkManagerActions({
       if (!site) throw new Error('[siteSlice] Site document is not initialized')
       if (target === 'none' && !site.settings.framework) return
       // Compute from the (frozen) live settings; assign inside the draft.
-      const next = applyFrameworkPreset(site.settings.framework, target)
+      const next = applyFrameworkPreset(site.settings, target)
       mutateSite((draftSite) => {
-        draftSite.settings.framework = next
+        draftSite.settings.framework = next.framework
+        // Font role tokens are only written when the preset added one.
+        if (next.fonts !== site.settings.fonts) draftSite.settings.fonts = next.fonts
         reconcileFrameworkClasses(draftSite)
         return true
       })
diff --git a/src/admin/shared/dialogs/FrameworkManagerDialog/FrameworkManagerDialog.tsx b/src/admin/shared/dialogs/FrameworkManagerDialog/FrameworkManagerDialog.tsx
index 0e4306b84..856de189c 100644
--- a/src/admin/shared/dialogs/FrameworkManagerDialog/FrameworkManagerDialog.tsx
+++ b/src/admin/shared/dialogs/FrameworkManagerDialog/FrameworkManagerDialog.tsx
@@ -155,7 +155,9 @@ export function FrameworkManagerDialog({
     confirmFrameworkChange({
       actionLabel: confirmActionLabel(),
       applyChange: (draft) => {
-        draft.settings.framework = applyFrameworkPreset(draft.settings.framework, target)
+        const next = applyFrameworkPreset(draft.settings, target)
+        draft.settings.framework = next.framework
+        draft.settings.fonts = next.fonts
       },
       commit: runApply,
     })
@@ -205,10 +207,10 @@ export function FrameworkManagerDialog({
       }
     >
       <p className={styles.lede}>
-        Seed your design tokens from the Core Framework defaults — colors, a
-        fluid type scale, a spacing scale, and their utility classes. Pick the
-        state you want; switching adds what's missing and strips what the new
-        state drops.
+        Seed your design tokens from the Core Framework defaults: colors, a
+        fluid type scale, a spacing scale, heading / body / mono font tokens,
+        and their utility classes. Pick the state you want; switching adds
+        what's missing and strips what the new state drops.
       </p>
 
       <div
diff --git a/src/core/fonts/css.ts b/src/core/fonts/css.ts
index 30c058f11..ef401a8f0 100644
--- a/src/core/fonts/css.ts
+++ b/src/core/fonts/css.ts
@@ -150,7 +150,7 @@ export function familySlug(family: string): string {
 }
 
 /**
- * Generate the `:root { --font-primary: "Family", fallback; }` block from the
+ * Generate the `:root { --font-heading: "Family", fallback; }` block from the
  * site's editable font tokens. Installed families do not emit direct variables;
  * authored styles should bind to tokens so family swaps preserve declarations.
  */
diff --git a/src/core/fonts/describe.ts b/src/core/fonts/describe.ts
index e8d906d02..ebd7513c3 100644
--- a/src/core/fonts/describe.ts
+++ b/src/core/fonts/describe.ts
@@ -1,7 +1,7 @@
 /**
  * Token digest for the site's font library — the fonts counterpart to
  * `describeFrameworkTokens`. Each font token is reported with the CSS variable
- * the stylesheet emits (`--font-primary`), the `var(--…)` reference to drop
+ * the stylesheet emits (`--font-heading`), the `var(--…)` reference to drop
  * into a style value, and the resolved family + fallback so the agent can pick
  * a token by appearance.
  */
@@ -10,9 +10,9 @@ import type { SiteFontsSettings } from './schemas'
 import { fontTokenCssVariable, fontTokenValueExpr, resolveFontTokenStack, sortFontTokens } from './tokens'
 
 interface FontTokenDescriptor {
-  /** Display name, e.g. "Primary". */
+  /** Display name, e.g. "Heading". */
   name: string
-  /** CSS custom property incl. leading dashes, e.g. "--font-primary". */
+  /** CSS custom property incl. leading dashes, e.g. "--font-heading". */
   cssVar: string
   /** `var(--…)` expression ready to drop into a `font-family` value. */
   ref: string
diff --git a/src/core/fonts/index.ts b/src/core/fonts/index.ts
index 3093af824..fc744e0a8 100644
--- a/src/core/fonts/index.ts
+++ b/src/core/fonts/index.ts
@@ -9,6 +9,7 @@ export * from './types'
 export * from './schemas'
 export * from './variants'
 export * from './tokens'
+export * from './roles'
 export * from './css'
 export * from './googleDirectory'
 export * from './preview'
diff --git a/src/core/fonts/roles.ts b/src/core/fonts/roles.ts
new file mode 100644
index 000000000..c067cb9d4
--- /dev/null
+++ b/src/core/fonts/roles.ts
@@ -0,0 +1,84 @@
+/**
+ * Font role tokens: the three font tokens every new site starts with.
+ *
+ *   • `font-heading` ("Heading"): headings and display type
+ *   • `font-body`    ("Body"): running text
+ *   • `font-mono`    ("Mono"): code, data and mono labels
+ *
+ * Content written against these variables (templates, copied sections, AI
+ * output) renders in any site, because every site that has them binds the
+ * same names. They are seeded fallback-only (no `familyId`) with system
+ * stacks, so a new site renders without downloading anything; the user binds
+ * real families later in the Fonts panel.
+ *
+ * Seeded by `createNewSiteSettings` (`@core/page-tree`) for brand-new sites and
+ * added by the Core Framework preset (`applyFrameworkPreset`) to sites that
+ * lack them. Existing sites are never migrated.
+ */
+
+import { nanoid } from 'nanoid'
+import type { FontToken, SiteFontsSettings } from './schemas'
+import { normalizeFontTokenVariable } from './tokenStrings'
+
+/** System sans-serif stack, stored in its sanitized (unquoted) form. */
+const SYSTEM_SANS_STACK = 'system-ui, -apple-system, Segoe UI, Roboto, sans-serif'
+const SYSTEM_MONO_STACK = 'ui-monospace, SFMono-Regular, Menlo, Consolas, monospace'
+
+interface FontRole {
+  name: string
+  variable: string
+  fallback: string
+}
+
+export const FONT_ROLES: readonly FontRole[] = [
+  { name: 'Heading', variable: 'font-heading', fallback: SYSTEM_SANS_STACK },
+  { name: 'Body', variable: 'font-body', fallback: SYSTEM_SANS_STACK },
+  { name: 'Mono', variable: 'font-mono', fallback: SYSTEM_MONO_STACK },
+]
+
+function roleToken(role: FontRole, order: number, now: number): FontToken {
+  return {
+    id: nanoid(),
+    name: role.name,
+    variable: role.variable,
+    fallback: role.fallback,
+    order,
+    createdAt: now,
+    updatedAt: now,
+  }
+}
+
+/** Fresh fallback-only tokens for every font role, in role order. */
+export function buildFontRoleTokens(): FontToken[] {
+  const now = Date.now()
+  return FONT_ROLES.map((role, index) => roleToken(role, index, now))
+}
+
+/**
+ * Add the font role tokens a site is missing, matching by variable. Tokens the
+ * site already has (including a customized `font-heading`) are left exactly as
+ * they are. Returns the input object itself when nothing is missing, so callers
+ * can skip a no-op write by reference comparison.
+ */
+export function mergeFontRoleTokens(fonts: SiteFontsSettings | undefined): SiteFontsSettings {
+  const existing = fonts?.tokens ?? []
+  const have = new Set(existing.map((token) => normalizeFontTokenVariable(token.variable)))
+  const missing = FONT_ROLES.filter((role) => !have.has(role.variable))
+  if (fonts && missing.length === 0) return fonts
+
+  const now = Date.now()
+  let order = existing.reduce((max, token) => Math.max(max, token.order + 1), 0)
+  return {
+    items: fonts?.items ?? [],
+    tokens: [...existing, ...missing.map((role) => roleToken(role, order++, now))],
+  }
+}
+
+/**
+ * Name to pre-fill when the user adds a font token: the first role the site
+ * does not have yet, else a generic accent name.
+ */
+export function suggestFontTokenName(tokens: ReadonlyArray<Pick<FontToken, 'variable'>>): string {
+  const have = new Set(tokens.map((token) => normalizeFontTokenVariable(token.variable)))
+  return FONT_ROLES.find((role) => !have.has(role.variable))?.name ?? 'Accent'
+}
diff --git a/src/core/fonts/schemas.ts b/src/core/fonts/schemas.ts
index 62ecf5f39..dab86d82d 100644
--- a/src/core/fonts/schemas.ts
+++ b/src/core/fonts/schemas.ts
@@ -214,7 +214,11 @@ function parseFontEntry(raw: unknown): FontEntry | null {
 const FontTokenSchema = Type.Object({
   id: Type.String({ minLength: 1 }),
   name: Type.String({ minLength: 1 }),
-  /** CSS custom-property slug without the leading dashes, e.g. `font-primary`. */
+  /**
+   * CSS custom-property slug without the leading dashes, e.g. `font-heading`.
+   * New sites start with the role tokens `font-heading`, `font-body` and
+   * `font-mono` (see `./roles`).
+   */
   variable: Type.String({ minLength: 1 }),
   /** Optional installed FontEntry id. Missing means fallback-only/system token. */
   familyId: Type.Optional(Type.String({ minLength: 1 })),
diff --git a/src/core/framework/manageFramework.ts b/src/core/framework/manageFramework.ts
index c79df475a..4fe29d3f2 100644
--- a/src/core/framework/manageFramework.ts
+++ b/src/core/framework/manageFramework.ts
@@ -8,6 +8,8 @@
  *     existing / customized tokens. Empty input ⇒ a fresh full preset.
  *   • setFrameworkUtilities — flip utility-class generation on/off without
  *     touching the `:root` variables (the 'full' ⇄ 'variables' switch).
+ *   • applyFrameworkPreset: the declarative target state, which also adds the
+ *     font role tokens (`font-heading`, `font-body`, `font-mono`) a site lacks.
  *
  * All are pure: they compute a new `FrameworkSettings`; the store action assigns
  * it onto the draft and runs `reconcileFrameworkClasses`.
@@ -17,6 +19,7 @@ import type {
   FrameworkSpacingGroup,
   FrameworkTypographyGroup,
 } from '@core/framework-schema'
+import { mergeFontRoleTokens, type SiteFontsSettings } from '@core/fonts'
 import {
   buildCoreFrameworkSettings,
   coreFrameworkColorUtilitiesForSlug,
@@ -88,22 +91,39 @@ export function setFrameworkUtilities(
   return next
 }
 
+/** The slice of `SiteSettings` the Core preset owns. */
+export interface FrameworkPresetSettings {
+  framework?: FrameworkSettings
+  fonts?: SiteFontsSettings
+}
+
 /**
- * Compute the framework settings for a declarative target state — the single
- * source of truth shared by the store action, the onboarding importer, and the
- * dialog's change-preview. 'none' clears the framework; 'full' / 'variables'
- * merge the preset (add-missing) and flip utility generation to match.
+ * Compute the settings for a declarative target state: the single source of
+ * truth shared by the store action, the onboarding importer, and the dialog's
+ * change-preview.
+ *
+ *   • 'none' clears the framework. Font tokens are site content, not framework
+ *     output, so they are returned untouched.
+ *   • 'full' / 'variables' merge the preset (add-missing), flip utility
+ *     generation to match, and add any font role token the site lacks (matched
+ *     by variable; existing tokens are never changed).
+ *
+ * `fonts` in the result is the input object itself when no role token was
+ * missing, so callers can skip a no-op write by reference comparison.
  */
 export function applyFrameworkPreset(
-  existing: FrameworkSettings | undefined,
+  settings: FrameworkPresetSettings,
   target: FrameworkPreset,
-): FrameworkSettings | undefined {
-  if (target === 'none') return undefined
+): FrameworkPresetSettings {
+  if (target === 'none') return { framework: undefined, fonts: settings.fonts }
   const includeUtilities = target === 'full'
-  return setFrameworkUtilities(
-    mergeCoreFrameworkSettings(existing, { includeUtilities }),
-    includeUtilities,
-  )
+  return {
+    framework: setFrameworkUtilities(
+      mergeCoreFrameworkSettings(settings.framework, { includeUtilities }),
+      includeUtilities,
+    ),
+    fonts: mergeFontRoleTokens(settings.fonts),
+  }
 }
 
 /**
diff --git a/src/core/page-tree/index.ts b/src/core/page-tree/index.ts
index e53a029e6..da462b2de 100644
--- a/src/core/page-tree/index.ts
+++ b/src/core/page-tree/index.ts
@@ -69,7 +69,7 @@ export type {
 
 // Defaults
 export { DEFAULT_BREAKPOINTS, breakpointMediaQuery, defaultBreakpointMediaQuery } from './breakpoint'
-export { DEFAULT_SITE_SETTINGS } from './siteSettings'
+export { DEFAULT_SITE_SETTINGS, createNewSiteSettings } from './siteSettings'
 
 // Condition helpers
 export { conditionId, conditionLabel, makeConditionDef, parseConditions } from './condition'
diff --git a/src/core/page-tree/siteSettings.ts b/src/core/page-tree/siteSettings.ts
index ac01486bf..f31e221fb 100644
--- a/src/core/page-tree/siteSettings.ts
+++ b/src/core/page-tree/siteSettings.ts
@@ -27,7 +27,7 @@
 import { Type, type Static } from '@core/utils/typeboxHelpers'
 import { compiledCheck } from '@core/utils/typeboxCompiler'
 import { FrameworkSettingsSchema } from '@core/framework-schema'
-import { SiteFontsSettingsSchema, parseSiteFontsSettings } from '@core/fonts'
+import { SiteFontsSettingsSchema, buildFontRoleTokens, parseSiteFontsSettings } from '@core/fonts'
 
 // ---------------------------------------------------------------------------
 // SiteSettingsSchema
@@ -52,10 +52,29 @@ export type SiteSettings = Static<typeof SiteSettingsSchema>
 // Defaults
 // ---------------------------------------------------------------------------
 
+/**
+ * Read-time fallback for a stored shell whose settings are missing or not an
+ * object. Deliberately minimal: an existing site read through this fallback
+ * must render exactly as it did before, so new-site seeds do not belong here.
+ */
 export const DEFAULT_SITE_SETTINGS: SiteSettings = {
   shortcuts: {},
 }
 
+/**
+ * Settings a brand-new site starts with: the font role tokens (`font-heading`,
+ * `font-body`, `font-mono`) as fallback-only system stacks, so content made for
+ * one site references the same variables in any other. Used by every site
+ * creation path (first-run setup and the editor's draft bootstrap); never
+ * applied to sites that already exist.
+ */
+export function createNewSiteSettings(): SiteSettings {
+  return {
+    shortcuts: {},
+    fonts: { items: [], tokens: buildFontRoleTokens() },
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Tolerant parsing
 // ---------------------------------------------------------------------------
diff --git a/src/core/siteImport/types.ts b/src/core/siteImport/types.ts
index 76f584e8d..0fbd283fb 100644
--- a/src/core/siteImport/types.ts
+++ b/src/core/siteImport/types.ts
@@ -243,7 +243,7 @@ export interface ImportColorToken {
 
 /**
  * A root-scope `--font-*` custom property pulled from imported CSS. Committed
- * into `site.settings.fonts.tokens` so `font-family: var(--font-primary)` keeps
+ * into `site.settings.fonts.tokens` so `font-family: var(--font-body)` keeps
  * resolving through the builder's editable font-token model.
  */
 export interface ImportFontToken {
@@ -549,7 +549,7 @@ export interface CrossSheetClassConflict {
 }
 
 /**
- * A design-token CSS custom property (`--bg`, `--font-primary`) extracted from
+ * A design-token CSS custom property (`--bg`, `--font-body`) extracted from
  * the import that collides with an existing token in the site.
  *
  * Both colour tokens (keyed by `--<slug>`) and font tokens (keyed by
@@ -567,7 +567,7 @@ export interface TokenConflict {
   kind: 'color' | 'font'
   /**
    * The CSS custom-property name without the leading `--` the importer wanted
-   * (e.g. `bg` for `--bg`, `font-primary` for `--font-primary`).
+   * (e.g. `bg` for `--bg`, `font-body` for `--font-body`).
    */
   desiredVariable: string
   /** ID of the existing token (framework colour / font token) that owns the name. */

From 1c1b6f4c3db7ad4534f6c31038c59ad75637921d Mon Sep 17 00:00:00 2001
From: DavidBabinec <hello@davidbabinec.com>
Date: Tue, 13 Oct 2026 16:31:30 +0200
Subject: [PATCH 2/4] fix(site-import): fill an untouched font role token
 instead of renaming

Seeding font-heading, font-body and font-mono on new sites made an imported
static site that defines one of those variables collide with the seed and get
renamed to font-body-2, leaving the role token on the system stack. A role
token that is still exactly as seeded is a placeholder, so the conflict now
defaults to overwrite; a role token the user edited keeps the rename default.
---
 docs/features/site-import.md                  |   2 +-
 docs/features/site-shell.md                   |   2 +-
 src/__tests__/fonts/fontRoleTokens.test.ts    |  10 ++
 .../siteImport/fontRoleImport.test.ts         | 120 ++++++++++++++++++
 src/core/fonts/roles.ts                       |  21 ++-
 src/core/siteImport/conflicts.ts              |  28 +++-
 6 files changed, 172 insertions(+), 11 deletions(-)
 create mode 100644 src/__tests__/siteImport/fontRoleImport.test.ts

diff --git a/docs/features/site-import.md b/docs/features/site-import.md
index d367ab873..de6093e12 100644
--- a/docs/features/site-import.md
+++ b/docs/features/site-import.md
@@ -296,7 +296,7 @@ The escape hatch for "this sheet's resets/styles must not leak into other pages
 
 - **`PageConflict`** — a desired slug collides with an existing page slug or with another slug in the same import batch.
 - **`RuleConflict`** — a `kind:'class'` rule's name collides with an existing class name. Ambient rules never conflict. One row per name even when the name arrives as several cascade fragments (they rename together).
-- **`TokenConflict`** — a design-token CSS custom property collides with an existing token. One type covers both colour tokens (keyed by `--<slug>`, against `framework.colors.tokens`) and font tokens (keyed by `--font-*`, against `fonts.tokens`), since both are just a `--var` contract referenced by `var(--x)` in the imported CSS. Imported tokens are deduped per kind upstream, so only site-vs-import collisions occur. New sites start with the font role tokens `font-heading`, `font-body` and `font-mono`, so an import that defines one of those variables surfaces a font conflict there too; choosing overwrite binds the site's role token to the imported stack.
+- **`TokenConflict`** — a design-token CSS custom property collides with an existing token. One type covers both colour tokens (keyed by `--<slug>`, against `framework.colors.tokens`) and font tokens (keyed by `--font-*`, against `fonts.tokens`), since both are just a `--var` contract referenced by `var(--x)` in the imported CSS. Imported tokens are deduped per kind upstream, so only site-vs-import collisions occur. Token conflicts default to auto-rename, with one exception: when the existing font token is an untouched seeded role token (`font-heading`, `font-body` or `font-mono` with its seeded name and fallback and no bound family, checked by `isUntouchedFontRoleToken` in `src/core/fonts/roles.ts`), the default is overwrite. The imported family and fallback land on the role token and imported rules keep `var(--font-body)`, so importing into a new site behaves as if the token were absent. A role token the user has edited keeps the rename default.
 - **`CrossSheetClassConflict`** — two imported page cascades define the same class differently (see "Cross-sheet class conflicts" above). Keyed by `(desiredName, definitionId)`; resolutions apply FIRST in `applyConflictResolutions` so a renamed definition no longer participates in the site-vs-import conflict on the original name.
 
 Page slugs can be slash-delimited public paths. Root `index.html` stays the homepage slug `index`; nested `index.html` files use their directory route, so `documentation/index.html` imports as `/documentation` and does not collide with `download-version/index.html`.
diff --git a/docs/features/site-shell.md b/docs/features/site-shell.md
index 0242b4718..95f6c8291 100644
--- a/docs/features/site-shell.md
+++ b/docs/features/site-shell.md
@@ -155,7 +155,7 @@ The Colors / Framework Scale / Typography panels write to these sub-trees. All v
 
 They are seeded fallback-only (no `familyId`), so a new site renders them without downloading anything; the user binds real families in the Fonts panel. Nothing styles `body` or headings with them automatically: the publisher reset pins `body` to the system stack and authored CSS opts in with `var(--font-body)` / `var(--font-heading)`.
 
-**New-site settings.** `createNewSiteSettings()` (`src/core/page-tree/siteSettings.ts`) is what every brand-new site starts with: `{ shortcuts: {}, fonts: { items: [], tokens: <the three role tokens> } }`. First-run setup writes it into the new shell (`newSiteShellStorage()` in `server/repositories/site.ts`) and the editor's draft bootstrap uses it through `createDefaultSiteDocument`. `DEFAULT_SITE_SETTINGS` (`{ shortcuts: {} }`) stays the read-time fallback for a stored shell without settings, so an existing site never gains tokens on upgrade. Applying the Core Framework preset (Full or Variables only) adds whichever role tokens a site lacks, matched by variable, and never changes tokens the site already has; choosing None leaves font tokens alone.
+**New-site settings.** `createNewSiteSettings()` (`src/core/page-tree/siteSettings.ts`) is what every brand-new site starts with: `{ shortcuts: {}, fonts: { items: [], tokens: <the three role tokens> } }`. First-run setup writes it into the new shell (`newSiteShellStorage()` in `server/repositories/site.ts`) and the editor's draft bootstrap uses it through `createDefaultSiteDocument`. `DEFAULT_SITE_SETTINGS` (`{ shortcuts: {} }`) stays the read-time fallback for a stored shell without settings, so an existing site never gains tokens on upgrade. Applying the Core Framework preset (Full or Variables only) adds whichever role tokens a site lacks, matched by variable, and never changes tokens the site already has; choosing None leaves font tokens alone. Site import treats a role token that is still exactly as seeded as a placeholder: an imported `--font-body` fills it in place instead of being renamed (see [site-import.md](site-import.md) → `TokenConflict`).
 
 **Variable normalization** (`src/admin/pages/site/store/slices/site/fontActions.ts`): the `variable` field stores a slug without the leading `--`. User input is trimmed, lowercased, and invalid character runs replaced with `-`. Leading `--` is stripped before storage. Duplicate variables within a site are rejected. Examples: `--font Brand` → `font-brand`, `Editorial` → `font-editorial`.
 
diff --git a/src/__tests__/fonts/fontRoleTokens.test.ts b/src/__tests__/fonts/fontRoleTokens.test.ts
index d1f25e029..9917017a1 100644
--- a/src/__tests__/fonts/fontRoleTokens.test.ts
+++ b/src/__tests__/fonts/fontRoleTokens.test.ts
@@ -8,6 +8,7 @@ import {
   FONT_ROLES,
   buildFontRoleTokens,
   generateFontTokenVariablesCss,
+  isUntouchedFontRoleToken,
   mergeFontRoleTokens,
   parseSiteFontsSettings,
   suggestFontTokenName,
@@ -79,6 +80,15 @@ describe('font role tokens', () => {
     expect(variables(mergeFontRoleTokens(undefined))).toEqual(ROLE_VARIABLES)
   })
 
+  it('recognises an untouched seed and rejects any edit to it', () => {
+    const [heading] = buildFontRoleTokens()
+    expect(isUntouchedFontRoleToken(heading)).toBe(true)
+    expect(isUntouchedFontRoleToken({ ...heading, familyId: 'fam-1' })).toBe(false)
+    expect(isUntouchedFontRoleToken({ ...heading, fallback: 'serif' })).toBe(false)
+    expect(isUntouchedFontRoleToken({ ...heading, name: 'Display' })).toBe(false)
+    expect(isUntouchedFontRoleToken({ ...heading, variable: 'font-display' })).toBe(false)
+  })
+
   it('suggests the first missing role name for a new token', () => {
     expect(suggestFontTokenName([])).toBe('Heading')
     expect(suggestFontTokenName([{ variable: 'font-heading' }])).toBe('Body')
diff --git a/src/__tests__/siteImport/fontRoleImport.test.ts b/src/__tests__/siteImport/fontRoleImport.test.ts
new file mode 100644
index 000000000..cc5ccfd6c
--- /dev/null
+++ b/src/__tests__/siteImport/fontRoleImport.test.ts
@@ -0,0 +1,120 @@
+/**
+ * Importing a static site that defines a font role variable into a new site.
+ *
+ * New sites start with seeded `font-heading` / `font-body` / `font-mono` tokens.
+ * An imported `--font-body` must fill the untouched seed in place (default
+ * overwrite) so references keep `var(--font-body)`, while a role token the user
+ * edited keeps the pre-existing default (rename to `font-body-2`).
+ *
+ * Drives the real store commit through `createSiteImportAdapter`.
+ */
+
+import { beforeEach, describe, expect, it } from 'bun:test'
+import '@modules/base'
+import { useEditorStore } from '@site/store/store'
+import { applyConflictResolutions, buildImportPlan, commitImportPlan } from '@core/siteImport'
+import type { FileMap, ImportPlan, SiteImportAdapter } from '@core/siteImport'
+import type { FontEntry } from '@core/fonts'
+import { createSiteImportAdapter } from '@admin/modals/SiteImport/shared/createSiteImportAdapter'
+
+const enc = new TextEncoder()
+const FONT_URL = 'https://fonts.googleapis.com/css2?family=Manrope:wght@400;700&display=swap'
+const HTML =
+  '<!doctype html><html><head><link rel="stylesheet" href="style.css"></head><body><p>Hi</p></body></html>'
+const CSS = `
+  @import url("${FONT_URL}");
+  :root { --font-body: "Manrope", sans-serif; }
+  p { font-family: var(--font-body); }
+`
+
+function fileMap(): FileMap {
+  return {
+    files: {
+      'index.html': { bytes: enc.encode(HTML), mimeType: 'text/html' },
+      'style.css': { bytes: enc.encode(CSS), mimeType: 'text/css' },
+    },
+  }
+}
+
+const MANROPE: FontEntry = {
+  id: 'font_manrope',
+  source: 'google',
+  family: 'Manrope',
+  variants: ['400', '700'],
+  subsets: ['latin'],
+  files: [{ variant: '400', subset: 'latin', path: '/uploads/fonts/manrope/400.woff2', format: 'woff2' }],
+  createdAt: 1,
+  updatedAt: 1,
+}
+
+function plan(): ImportPlan {
+  return buildImportPlan({ fileMap: fileMap(), currentSite: useEditorStore.getState().site! })
+}
+
+async function commit(built: ImportPlan): Promise<void> {
+  const resolved = applyConflictResolutions(
+    built,
+    built.conflicts.pages,
+    built.conflicts.rules,
+    built.conflicts.tokens,
+    built.conflicts.crossSheetClasses,
+  )
+  const adapter: SiteImportAdapter = {
+    ...createSiteImportAdapter({ sessionId: 'font-role-import-test' }),
+    uploadAsset: async () => {
+      throw new Error('this fixture has no assets')
+    },
+    installGoogleFont: async () => structuredClone(MANROPE),
+  }
+  await commitImportPlan(resolved, adapter)
+}
+
+function fontTokens() {
+  return useEditorStore.getState().site!.settings.fonts?.tokens ?? []
+}
+
+function paragraphFontFamilies(): unknown[] {
+  return Object.values(useEditorStore.getState().site!.styleRules)
+    .filter((rule) => rule.selector === 'p')
+    .map((rule) => rule.styles.fontFamily)
+}
+
+describe('site import into a new site with font role tokens', () => {
+  beforeEach(() => {
+    useEditorStore.setState({ site: null } as Parameters<typeof useEditorStore.setState>[0])
+    useEditorStore.getState().createSite('New')
+  })
+
+  it('fills an untouched seeded role token instead of renaming the import', async () => {
+    const built = plan()
+    const conflict = built.conflicts.tokens.find((c) => c.desiredVariable === 'font-body')
+    expect(conflict?.defaultResolution.action).toBe('overwrite')
+
+    await commit(built)
+
+    const tokens = fontTokens()
+    expect(tokens.map((t) => t.variable)).toEqual(['font-heading', 'font-body', 'font-mono'])
+    const body = tokens.find((t) => t.variable === 'font-body')!
+    expect(body.familyId).toBe('font_manrope')
+    expect(body.fallback).toBe('sans-serif')
+    expect(paragraphFontFamilies()).toEqual(['var(--font-body)'])
+  })
+
+  it('keeps the rename default when the user edited the role token', async () => {
+    useEditorStore.setState((state) => {
+      const body = state.site!.settings.fonts!.tokens!.find((t) => t.variable === 'font-body')!
+      body.fallback = 'Georgia, serif'
+    })
+
+    const built = plan()
+    const conflict = built.conflicts.tokens.find((c) => c.desiredVariable === 'font-body')
+    expect(conflict?.defaultResolution).toEqual({ action: 'auto-rename', resolvedVariable: 'font-body-2' })
+
+    await commit(built)
+
+    const tokens = fontTokens()
+    expect(tokens.find((t) => t.variable === 'font-body')!.fallback).toBe('Georgia, serif')
+    expect(tokens.find((t) => t.variable === 'font-body-2')!.familyId).toBe('font_manrope')
+    expect(paragraphFontFamilies()).toEqual(['var(--font-body-2)'])
+  })
+})
diff --git a/src/core/fonts/roles.ts b/src/core/fonts/roles.ts
index c067cb9d4..09d154c92 100644
--- a/src/core/fonts/roles.ts
+++ b/src/core/fonts/roles.ts
@@ -13,12 +13,13 @@
  *
  * Seeded by `createNewSiteSettings` (`@core/page-tree`) for brand-new sites and
  * added by the Core Framework preset (`applyFrameworkPreset`) to sites that
- * lack them. Existing sites are never migrated.
+ * lack them. Existing sites are never migrated. Site import overwrites a role
+ * token that is still an untouched seed (`isUntouchedFontRoleToken`).
  */
 
 import { nanoid } from 'nanoid'
 import type { FontToken, SiteFontsSettings } from './schemas'
-import { normalizeFontTokenVariable } from './tokenStrings'
+import { normalizeFontTokenVariable, sanitizeFontFallbackStack } from './tokenStrings'
 
 /** System sans-serif stack, stored in its sanitized (unquoted) form. */
 const SYSTEM_SANS_STACK = 'system-ui, -apple-system, Segoe UI, Roboto, sans-serif'
@@ -74,6 +75,22 @@ export function mergeFontRoleTokens(fonts: SiteFontsSettings | undefined): SiteF
   }
 }
 
+/**
+ * True when `token` is a role token exactly as it was seeded: a `FONT_ROLES`
+ * variable with the seeded name and fallback stack and no bound family. A role
+ * token the user has bound, renamed or re-stacked is no longer a seed. Site
+ * import overwrites an untouched seed instead of renaming the imported token.
+ */
+export function isUntouchedFontRoleToken(
+  token: Pick<FontToken, 'name' | 'variable' | 'familyId' | 'fallback'>,
+): boolean {
+  if (token.familyId) return false
+  const variable = normalizeFontTokenVariable(token.variable)
+  const role = FONT_ROLES.find((r) => r.variable === variable)
+  if (!role) return false
+  return token.name === role.name && sanitizeFontFallbackStack(token.fallback) === role.fallback
+}
+
 /**
  * Name to pre-fill when the user adds a font token: the first role the site
  * does not have yet, else a generic accent name.
diff --git a/src/core/siteImport/conflicts.ts b/src/core/siteImport/conflicts.ts
index af8e17b60..80c30b096 100644
--- a/src/core/siteImport/conflicts.ts
+++ b/src/core/siteImport/conflicts.ts
@@ -37,7 +37,7 @@ import {
 } from '@core/page-tree'
 import type { ImportFragment } from '@core/htmlImport'
 import { normalizeFrameworkColorSlug } from '@core/framework'
-import { normalizeFontTokenVariable } from '@core/fonts'
+import { isUntouchedFontRoleToken, normalizeFontTokenVariable, type FontToken } from '@core/fonts'
 import { applyCrossSheetClassResolutions, normalizeBindableClassRules } from './classCascades'
 
 // ---------------------------------------------------------------------------
@@ -185,6 +185,8 @@ function detectRuleConflicts(
  * A colour token conflicts when its `--<slug>` (normalised) already exists in
  * `site.settings.framework.colors.tokens`; a font token conflicts when its
  * `--font-*` variable (normalised) already exists in `site.settings.fonts.tokens`.
+ * Conflicts default to auto-rename, except a font conflict against an untouched
+ * seeded role token (`isUntouchedFontRoleToken`), which defaults to overwrite.
  * Imported tokens are deduped per kind upstream, so only site-vs-import
  * collisions are possible here (no intra-batch case).
  */
@@ -215,19 +217,31 @@ function detectTokenConflicts(
   }
 
   // ── Font tokens — keyed by normalised variable ────────────────────────────
-  const existingFontIds = new Map<string, string>()
+  const existingFonts = new Map<string, FontToken>()
   for (const token of site.settings.fonts?.tokens ?? []) {
-    existingFontIds.set(normalizeFontTokenVariable(token.variable), token.id)
+    existingFonts.set(normalizeFontTokenVariable(token.variable), token)
   }
-  const claimedFonts = new Set(existingFontIds.keys())
+  const claimedFonts = new Set(existingFonts.keys())
   for (const token of fontTokens) {
-    const existingId = existingFontIds.get(normalizeFontTokenVariable(token.variable))
-    if (!existingId) continue
+    const existing = existingFonts.get(normalizeFontTokenVariable(token.variable))
+    if (!existing) continue
+    // A role token still exactly as a new site seeded it (`font-body`, …) is a
+    // placeholder, not a user choice: the import fills it in place so
+    // `var(--font-body)` keeps its name. An edited role token keeps the rename.
+    if (isUntouchedFontRoleToken(existing)) {
+      conflicts.push({
+        kind: 'font',
+        desiredVariable: token.variable,
+        existingTokenId: existing.id,
+        defaultResolution: { action: 'overwrite' },
+      })
+      continue
+    }
     const resolved = nextAvailableVariable(token.variable, claimedFonts, normalizeFontTokenVariable)
     conflicts.push({
       kind: 'font',
       desiredVariable: token.variable,
-      existingTokenId: existingId,
+      existingTokenId: existing.id,
       defaultResolution: { action: 'auto-rename', resolvedVariable: resolved },
     })
     claimedFonts.add(normalizeFontTokenVariable(resolved))

From 8e645cceeb2071671aee6e246d8cb49305dc3f51 Mon Sep 17 00:00:00 2001
From: DavidBabinec <hello@davidbabinec.com>
Date: Tue, 13 Oct 2026 16:37:42 +0200
Subject: [PATCH 3/4] docs(fonts): describe role tokens in terms of shared
 content

The rationale now names imported pages, copied sections and AI output as the content the role variables serve.
---
 docs/features/site-shell.md | 2 +-
 src/core/fonts/roles.ts     | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/features/site-shell.md b/docs/features/site-shell.md
index 95f6c8291..238cf5078 100644
--- a/docs/features/site-shell.md
+++ b/docs/features/site-shell.md
@@ -145,7 +145,7 @@ The Colors / Framework Scale / Typography panels write to these sub-trees. All v
 
 `fonts` is the installed font library and font-token contract (`src/core/fonts/`). `fonts.items` is the installed self-hosted font asset library (Google downloads and custom media-backed font files). `fonts.tokens` is the editable builder-facing contract: each token owns a stable CSS variable such as `font-heading`, an optional assigned `FontEntry` id, and a fallback stack. The publisher emits those as `:root { --font-heading: "Family", sans-serif; }`; editor controls should prefer `font-family: var(--font-heading)` over raw family names when the design should follow future font swaps.
 
-**Font role tokens** (`src/core/fonts/roles.ts`). Three role variables are the shared contract that templates, copied sections and the AI agent write against, so content made for one site renders in another:
+**Font role tokens** (`src/core/fonts/roles.ts`). Three role variables are the shared contract that imported pages, copied sections and the AI agent write against, so content made for one site renders in another:
 
 | Token | Name | Use | Seeded fallback |
 |-------|------|-----|-----------------|
diff --git a/src/core/fonts/roles.ts b/src/core/fonts/roles.ts
index 09d154c92..69617471c 100644
--- a/src/core/fonts/roles.ts
+++ b/src/core/fonts/roles.ts
@@ -5,8 +5,8 @@
  *   • `font-body`    ("Body"): running text
  *   • `font-mono`    ("Mono"): code, data and mono labels
  *
- * Content written against these variables (templates, copied sections, AI
- * output) renders in any site, because every site that has them binds the
+ * Content written against these variables (imported pages, copied sections,
+ * AI output) renders in any site, because every site that has them binds the
  * same names. They are seeded fallback-only (no `familyId`) with system
  * stacks, so a new site renders without downloading anything; the user binds
  * real families later in the Fonts panel.

From cc4f6f8985a59fe5e20820ff6e559d5ddc7430f6 Mon Sep 17 00:00:00 2001
From: DavidBabinec <hello@davidbabinec.com>
Date: Tue, 13 Oct 2026 16:51:35 +0200
Subject: [PATCH 4/4] test(framework): read the framework from the preset
 result in root font size tests

applyFrameworkPreset now returns { framework, fonts }, so the root font size tests read .framework; one of them passed only because it read an absent property.
---
 src/__tests__/framework/rootFontSize.test.ts | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/__tests__/framework/rootFontSize.test.ts b/src/__tests__/framework/rootFontSize.test.ts
index ea679cfed..151141c24 100644
--- a/src/__tests__/framework/rootFontSize.test.ts
+++ b/src/__tests__/framework/rootFontSize.test.ts
@@ -53,7 +53,7 @@ function canvasCss(framework: FrameworkSettings) {
 
 describe('framework root font size', () => {
   it('a new Core framework sets html font-size to 62.5% in the published CSS and the canvas', () => {
-    const framework = applyFrameworkPreset(undefined, 'full')!
+    const framework = applyFrameworkPreset({}, 'full').framework!
     expect(framework.preferences?.emitRootFontSize).toBe(true)
 
     const published = buildSiteFrameworkCss(siteWithFramework(framework))
@@ -66,7 +66,7 @@ describe('framework root font size', () => {
   })
 
   it('the variables-only preset opts in too', () => {
-    const framework = applyFrameworkPreset(undefined, 'variables')!
+    const framework = applyFrameworkPreset({}, 'variables').framework!
     expect(generateFrameworkRootCss(framework)).toStartWith(ROOT_62_5)
   })
 
@@ -90,7 +90,7 @@ describe('framework root font size', () => {
   it('re-applying the preset keeps an existing site off', () => {
     const withLegacyPreferences = buildCoreFrameworkSettings({ includeUtilities: false })
     withLegacyPreferences.preferences = { ...LEGACY_PREFERENCES }
-    const reapplied = applyFrameworkPreset(withLegacyPreferences, 'full')!
+    const reapplied = applyFrameworkPreset({ framework: withLegacyPreferences }, 'full').framework!
     expect(reapplied.preferences?.emitRootFontSize).toBeUndefined()
     expect(generateFrameworkRootCss(reapplied)).not.toMatch(/^html\s*\{/m)