From fd241f70cf46e7f6701ea8d449d7f46adbeec4a3 Mon Sep 17 00:00:00 2001
From: Emmanuel Ruiz <ehnruiz@gmail.com>
Date: Sat, 10 Oct 2026 21:50:13 -0400
Subject: [PATCH 1/2] fix(siteImport): rewrite var() references to the slug a
 colour token is emitted under

Site Import turned root colour custom properties into framework tokens,
which the framework emits under the normalised slug
(`--brand---neutral--700` -> `--brand-neutral-700`), but left the imported
`var()` references on the authored name, so they no longer resolved.

The slug is now settled at plan time by `normalizeImportedColorTokens`,
and every changed name is rewritten in the imported style rules and node
inline styles before conflict detection, so the conflict step and the
commit see the emitted name. Two names that normalise to the same slug
both survive with a numeric suffix instead of one being dropped at commit.

Token renames (normalisation and conflict renames) now also rename
declarations of the variable in other rules, their priorities, and raw
@keyframes CSS, so a `.dark { --bg: ... }` override follows its token.
Conflict rename targets skip the import's other token names and any
custom property the imported CSS declares, and a colour custom rename is
normalised like the slug it becomes.

The rename helpers move from conflicts.ts into siteImport/varRefs.ts,
which keeps conflicts.ts under the 700-line module budget.

Fixes #615
---
 docs/features/site-import.md                 |   7 +-
 src/__tests__/siteImport/applyImport.test.ts |  37 +++++
 src/__tests__/siteImport/colorTokens.test.ts |  49 +++++-
 src/__tests__/siteImport/conflicts.test.ts   | 118 +++++++++++++-
 src/core/siteImport/buildPlan.ts             |  30 +++-
 src/core/siteImport/colorTokens.ts           |  52 +++++++
 src/core/siteImport/conflicts.ts             | 117 ++++++--------
 src/core/siteImport/index.ts                 |   2 +-
 src/core/siteImport/varRefs.ts               | 154 +++++++++++++++++++
 9 files changed, 481 insertions(+), 85 deletions(-)
 create mode 100644 src/core/siteImport/varRefs.ts

diff --git a/docs/features/site-import.md b/docs/features/site-import.md
index de6093e12..f22ce4456 100644
--- a/docs/features/site-import.md
+++ b/docs/features/site-import.md
@@ -15,7 +15,7 @@ CSS declarations containing `var()`, `env()`, `clamp()`, `min()`, or `max()` pas
 - **Per-stylesheet import modes:** each top-level linked stylesheet either converts to editable style rules (default) or imports verbatim as a page-scoped `SiteFile` stylesheet (`options.stylesheetModes`, picked in the Review step). There are no generated scope classes — page isolation comes from the kept file's runtime scope.
 - `commitImportPlan(plan, adapter)` — uploads assets, then wraps all store writes in a single `adapter.commit` call → one Cmd+Z reverts the whole import.
 - Static imports load the current CMS draft into the editor store on demand when launched outside `/admin/site`; if no draft exists, the modal creates an empty site before analysis.
-- Conflict resolution: rename with a numeric suffix (default), overwrite, skip, or custom-rename — per page slug, per class name, per design token (colour / font CSS variable), and per divergent cross-stylesheet class definition, with category-level bulk actions. Token renames rewrite `var(--x)` references so imports stay faithful.
+- Conflict resolution: rename with a numeric suffix (default), overwrite, skip, or custom-rename — per page slug, per class name, per design token (colour / font CSS variable), and per divergent cross-stylesheet class definition, with category-level bulk actions. Token renames rewrite `var(--x)` references, and declarations of the same variable in other rules, so imports stay faithful.
 - What imports: pages, linked CSS plus unconditional local CSS `@import` graphs, `kind:'class'` and `kind:'ambient'` style rules, stylesheets kept as page-scoped files, `@keyframes`, uploadable media/font files, root CSS color tokens, root CSS font tokens, `@font-face` families, known external font stylesheet imports, safe extra HTML attributes on base modules, body-level classes/attributes/style metadata, bare DOM text nodes in mixed content, and executable HTML scripts as page-scoped runtime scripts. Module-script imports from known npm CDNs are rewritten to bare package imports and added to the site dependency manifest.
 - CMS bundle import preserves selected exported tables, rows, optional site shell, media, folders, and redirects using the same merge strategies as site transfer (`replace`, `merge-add`, `merge-overwrite`).
 - HTML forms import through the shared HTML importer as first-class form primitives (`base.form`, controls, labels, submit buttons), not as custom containers.
@@ -46,6 +46,7 @@ src/core/siteImport/
 ├── applyAssetRewrites.ts — patch fragment props + CSS/@keyframes url() with new media URLs (post-upload)
 ├── linkRewrite.ts       — rewrite intra-site <a href> to cms:page:<id> refs
 ├── conflicts.ts         — detect page-slug + class-name + design-token collisions; apply resolutions (incl. var(--x) rewrites)
+├── varRefs.ts           — rename a custom property across imported rules, inline styles and @keyframes (var(--x) refs + --x declarations)
 ├── adapter.ts           — SiteImportAdapter + SiteImportTransaction interfaces (the ONE transaction contract; the editor store implements it directly)
 ├── paths.ts             — dirname/joinPaths for FileMap-relative path resolution
 ├── planCss.ts           — single CSS-source parse path (external sheets + per-page inline <style>) feeding shared plan accumulators
@@ -208,7 +209,7 @@ interface ImportScript {
 | **HTML attributes** | Safe extra attributes on ordinary elements (`id`, ARIA, `role`, custom attrs, `data-*`, etc.) | Stored as `props.htmlAttributes` on base container/text/link/button/image modules so CSS selectors, anchors, classic scripts, accessibility attributes, and template runtime hooks such as `data-bg-src`, `data-aos`, and `data-bs-*` survive import. Users edit the same bag in the Properties panel's Attributes view. `class` is handled by the selector registry, inline `style` becomes `node.inlineStyles`, event handlers are stripped, and reserved Instatic/editor `data-*` names are not imported. Local asset URLs inside these attributes are uploaded and rewritten. |
 | **Style rules** | All rules from linked CSS files and their unconditional local `@import` graph | `expandLinkedCssImports` follows bundled local CSS imports first, then `cssToStyleRules` maps selector declaration blocks to `NewStyleRule` entries (class or ambient kind) and stores supported stylesheet-level rules such as `@keyframes` as ambient raw CSS rules |
 | **Media** | Uploadable images (JPEG, PNG, GIF, WebP, AVIF, SVG), videos, and fonts — including unreferenced files in the bundle | `buildAssetPlan` collects referenced assets and sweeps uploadable unreferenced files. Source companions such as `.scss`, sourcemaps, PHP mailers, `desktop.ini`, and README files are excluded before upload. An `<img>`'s authored `alt` is carried onto the asset and stored on the Media Library record at upload; `loading`, `decoding`, and `fetchpriority` map onto the Image module's first-class props when they hold a value the module offers (anything else keeps the module default). Uploaded assets are filed under folders mirroring their bundle path; a folder failure leaves the asset at the media root with an `asset-folder-failed` warning and never blocks the URL rewrite. |
-| **Color tokens** | CSS custom properties on `:root` / `html` / `body` that look like colours | `extractRootColorTokens` pulls them into `ImportColorToken[]`; they become framework palette tokens. The framework parses hex, rgb/rgba, and hsl/hsla into channels (deriving shades/tints/transparent steps); any other authored value (oklch(), color-mix(), …) still emits its base `--<slug>` verbatim so `var(--x)` references never break. A `--<slug>` that collides with an existing colour token surfaces as a `TokenConflict` (rename / skip / overwrite) |
+| **Color tokens** | CSS custom properties on `:root` / `html` / `body` that look like colours | `extractRootColorTokens` pulls them into `ImportColorToken[]`; they become framework palette tokens. The framework parses hex, rgb/rgba, and hsl/hsla into channels (deriving shades/tints/transparent steps); any other authored value (oklch(), color-mix(), …) still emits its base `--<slug>` verbatim so `var(--x)` references never break. The slug is the framework's normalised form (`--brand---neutral--700` → `--brand-neutral-700`), settled at plan time by `normalizeImportedColorTokens`; every imported `var()` reference and declaration of a renamed name is rewritten to it, and two names that normalise to the same slug both survive (the one already in normalised form keeps it, the other takes a `-2` suffix). A `--<slug>` that collides with an existing colour token surfaces as a `TokenConflict` (rename / skip / overwrite) |
 | **Fonts** | Self-hosted `@font-face` families with at least one bundled file, plus trusted Google CSS2 imports | `buildFontFamilies` in `assetPlan.ts` picks the best bundled format (woff2 → woff → ttf → otf); `extractGoogleFontImports` turns Google CSS2 `@import` rules into install requests. Commit uploads custom files via `tx.addFonts`, installs Google families through the CMS Google-font installer, then merges those returned `FontEntry` records via `tx.addInstalledFonts` |
 | **Font tokens** | Root `--font-*` variables with font-family stacks | `extractRootFontTokens` pulls them into `ImportFontToken[]`; committed via `tx.addFontTokens` after fonts so matching imported families can be assigned. A `--font-*` that collides with an existing font token surfaces as a `TokenConflict` (rename / skip / overwrite) |
 | **Scripts** | Executable inline scripts and JS files linked by imported HTML | Ordered so every page's document order holds at once (see `priority` above) and committed via `tx.addScripts` with page scope from the source HTML. Classic scripts remain plain `<script>` assets and bypass bundling; `type="module"` scripts keep module semantics. Module imports from known npm CDNs (`esm.sh`, `esm.run`, `unpkg`, jsDelivr npm URLs) are rewritten to bare package specifiers and recorded as runtime dependencies, so `https://esm.sh/@motion.page/sdk@1.2.4` becomes `@motion.page/sdk` plus `@motion.page/sdk: 1.2.4` in `packageJson.dependencies`. Non-executable script data such as `application/json`, import maps, and templates is skipped. |
@@ -296,7 +297,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. 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.
+- **`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. A rename target also skips the import's other token names and every custom property the imported CSS declares, so a renamed token never lands on a variable that is already in use. 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/src/__tests__/siteImport/applyImport.test.ts b/src/__tests__/siteImport/applyImport.test.ts
index 8246eb343..4a9d506f6 100644
--- a/src/__tests__/siteImport/applyImport.test.ts
+++ b/src/__tests__/siteImport/applyImport.test.ts
@@ -482,6 +482,43 @@ describe('buildImportPlan — structure', () => {
     expect(p.unusedCss).toContain('styles/unused.css')
   })
 
+  it('rewrites var() references to the slug a root colour token is emitted under (#615)', () => {
+    const html = `<!doctype html><html><head><link rel="stylesheet" href="style.css"></head><body>
+      <h1 class="title">Home</h1><a class="link" href="/">Link</a>
+      <p style="border-color: var(--brand---neutral--700, red)">Note</p>
+    </body></html>`
+    const css = `
+      :root {
+        --brand---neutral--700: #4f5459;
+        --brand-primary: #0575d6;
+        --alias: var(--brand---neutral--700);
+      }
+      .title { color: var(--brand---neutral--700); }
+      .link { color: var(--brand-primary); }
+      .dark { --brand---neutral--700: #000; }
+    `
+    const p = buildImportPlan({
+      fileMap: makeSinglePageFileMap(html, css),
+      currentSite: makeEmptySiteDocument(),
+    })
+
+    expect(p.colors).toEqual([
+      { slug: 'brand-neutral-700', value: '#4f5459' },
+      { slug: 'brand-primary', value: '#0575d6' },
+    ])
+    const rule = (selector: string) => p.styleRules.find((r) => r.selector === selector)
+    expect(rule('.title')?.styles.color).toBe('var(--brand-neutral-700)')
+    expect(rule('.link')?.styles.color).toBe('var(--brand-primary)')
+    expect(rule(':root')?.styles).toEqual({ '--alias': 'var(--brand-neutral-700)' })
+    // A non-root override follows the token to its new name.
+    expect(rule('.dark')?.styles).toEqual({ '--brand-neutral-700': '#000' })
+    const inline = Object.values(p.pages[0].nodeFragment.nodes)
+      .map((node) => node.inlineStyles)
+      .find((styles) => styles && 'borderColor' in styles)
+    expect(inline?.borderColor).toBe('var(--brand-neutral-700, red)')
+    expect(p.conflicts.tokens).toHaveLength(0)
+  })
+
   it('extracts root font variables into font tokens', () => {
     const html = `<!doctype html><html><head><link rel="stylesheet" href="style.css"></head><body><h1>Home</h1></body></html>`
     const css = `
diff --git a/src/__tests__/siteImport/colorTokens.test.ts b/src/__tests__/siteImport/colorTokens.test.ts
index 17f80fd3b..a6e66863f 100644
--- a/src/__tests__/siteImport/colorTokens.test.ts
+++ b/src/__tests__/siteImport/colorTokens.test.ts
@@ -3,7 +3,7 @@
  */
 
 import { describe, it, expect } from 'bun:test'
-import { extractRootColorTokens, isCssColorValue } from '@core/siteImport'
+import { extractRootColorTokens, isCssColorValue, normalizeImportedColorTokens } from '@core/siteImport'
 import type { NewStyleRule } from '@core/siteImport'
 
 function ambient(selector: string, styles: Record<string, unknown>): NewStyleRule {
@@ -82,3 +82,50 @@ describe('extractRootColorTokens', () => {
     expect(out[0].stylePriorities).toEqual({ '--brand': 'important' })
   })
 })
+
+describe('normalizeImportedColorTokens', () => {
+  it('gives each token its emitted slug and maps every changed name (#615)', () => {
+    const { colorTokens, renames } = normalizeImportedColorTokens([
+      { slug: 'brand---neutral--700', value: '#4f5459' },
+      { slug: 'brand-primary', value: '#0575d6' },
+      { slug: 'Brand-Accent', value: '#fc834b' },
+    ])
+    expect(colorTokens).toEqual([
+      { slug: 'brand-neutral-700', value: '#4f5459' },
+      { slug: 'brand-primary', value: '#0575d6' },
+      { slug: 'brand-accent', value: '#fc834b' },
+    ])
+    expect([...renames]).toEqual([
+      ['brand---neutral--700', 'brand-neutral-700'],
+      ['Brand-Accent', 'brand-accent'],
+    ])
+  })
+
+  it('keeps both tokens when two names normalise to the same slug', () => {
+    // The name already in emitted form keeps it, wherever it appears.
+    const { colorTokens, renames } = normalizeImportedColorTokens([
+      { slug: 'Brand', value: '#111' },
+      { slug: 'brand', value: '#222' },
+      { slug: 'brand--', value: '#333' },
+    ])
+    expect(colorTokens.map((t) => t.slug)).toEqual(['brand-2', 'brand', 'brand-3'])
+    expect([...renames]).toEqual([['Brand', 'brand-2'], ['brand--', 'brand-3']])
+  })
+
+  it('does not rename a token onto another variable the import declares', () => {
+    const { colorTokens, renames } = normalizeImportedColorTokens(
+      [{ slug: 'a--b', value: '#111' }, { slug: 'bg', value: '#fff' }],
+      // `a-b` is an unrelated variable; `bg` is the token's own override.
+      new Set(['a-b', 'bg']),
+    )
+    expect(colorTokens.map((t) => t.slug)).toEqual(['a-b-2', 'bg'])
+    expect([...renames]).toEqual([['a--b', 'a-b-2']])
+  })
+
+  it('returns no renames when every name is already in emitted form', () => {
+    const tokens = [{ slug: 'bg', value: '#fff' }, { slug: 'ink-2', value: '#000' }]
+    const { colorTokens, renames } = normalizeImportedColorTokens(tokens)
+    expect(colorTokens).toEqual(tokens)
+    expect(renames.size).toBe(0)
+  })
+})
diff --git a/src/__tests__/siteImport/conflicts.test.ts b/src/__tests__/siteImport/conflicts.test.ts
index be4f5511d..972e079d8 100644
--- a/src/__tests__/siteImport/conflicts.test.ts
+++ b/src/__tests__/siteImport/conflicts.test.ts
@@ -3,7 +3,8 @@
  */
 
 import { describe, it, expect } from 'bun:test'
-import { detectConflicts, applyConflictResolutions } from '@core/siteImport'
+import { detectConflicts, applyConflictResolutions, buildImportPlan } from '@core/siteImport'
+import { makeSinglePageFileMap } from './fixtures'
 import type {
   ImportPlan,
   PagePlan,
@@ -482,6 +483,41 @@ describe('detectConflicts — design tokens', () => {
   })
 })
 
+describe('detectConflicts — rename targets avoid the import\'s own names', () => {
+  it('does not auto-rename onto another imported token\'s slug', () => {
+    const { tokens } = detectConflicts(siteWithTokens(), [], [], [makeColorToken('bg'), makeColorToken('bg-2')], [])
+    expect(tokens).toHaveLength(1)
+    expect(tokens[0].defaultResolution.resolvedVariable).toBe('bg-3')
+  })
+
+  it('does not auto-rename onto a custom property the imported CSS declares', () => {
+    const rule: NewStyleRule = {
+      name: 'x', kind: 'class', selector: '.x', order: 0,
+      styles: { '--bg-2': '4px', '--font-primary-2': 'serif' }, contextStyles: {},
+    }
+    const { tokens } = detectConflicts(
+      siteWithTokens(), [], [rule], [makeColorToken('bg')], [makeFontToken('font-primary')],
+    )
+    expect(tokens.map((t) => t.defaultResolution.resolvedVariable)).toEqual(['bg-3', 'font-primary-3'])
+  })
+
+  it('keeps both colours when a normalised name and a conflict rename meet (#615)', () => {
+    // `--BG` normalises to `bg-2`, so the conflict rename of `--bg` must not
+    // take `bg-2` too, or one colour is lost at commit.
+    const html = `<!doctype html><html><head><link rel="stylesheet" href="style.css"></head><body><p class="u">x</p></body></html>`
+    const css = `:root { --bg: #111; --BG: #222; } .u { color: var(--BG); background: var(--bg); }`
+    const plan = buildImportPlan({ fileMap: makeSinglePageFileMap(html, css), currentSite: siteWithTokens() })
+    const result = applyConflictResolutions(plan, [], [], plan.conflicts.tokens)
+
+    expect(result.colors).toEqual([
+      { slug: 'bg-3', value: '#111' },
+      { slug: 'bg-2', value: '#222' },
+    ])
+    const u = result.styleRules.find((r) => r.selector === '.u')
+    expect(u?.styles).toMatchObject({ color: 'var(--bg-2)', background: 'var(--bg-3)' })
+  })
+})
+
 describe('applyConflictResolutions — design tokens', () => {
   it('rename: renames the imported colour token AND rewrites var(--bg) refs in style rules', () => {
     const rule: NewStyleRule = {
@@ -507,6 +543,86 @@ describe('applyConflictResolutions — design tokens', () => {
     expect(result.styleRules[0].styles.color).toBe('var(--ink)')
   })
 
+  it('custom rename: renames a colour token to its emitted slug and rewrites refs to it', () => {
+    const rule: NewStyleRule = {
+      name: 'hero',
+      kind: 'class',
+      selector: '.hero',
+      order: 0,
+      styles: { color: 'var(--bg)' },
+      contextStyles: {},
+    }
+    const plan = makeTokenPlan({ colors: [makeColorToken('bg')], styleRules: [rule] })
+    const res: TokenConflict = {
+      kind: 'color',
+      desiredVariable: 'bg',
+      existingTokenId: 'existing-color-id',
+      defaultResolution: { action: 'custom-rename', resolvedVariable: 'Hero BG' },
+    }
+    const result = applyConflictResolutions(plan, [], [], [res])
+
+    expect(result.colors[0].slug).toBe('hero-bg')
+    expect(result.styleRules[0].styles.color).toBe('var(--hero-bg)')
+  })
+
+  it('rename: renames a declaration of the token in a non-root rule, with its priority', () => {
+    const rule: NewStyleRule = {
+      name: 'dark',
+      kind: 'class',
+      selector: '.dark',
+      order: 0,
+      styles: { '--bg': '#000', '--other': '#111' },
+      stylePriorities: { '--bg': 'important' },
+      contextStyles: { 'bp-mobile': { '--bg': '#222' } },
+      contextStylePriorities: { 'bp-mobile': { '--bg': 'important' } },
+    }
+    const plan = makeTokenPlan({ colors: [makeColorToken('bg')], styleRules: [rule] })
+    const res: TokenConflict = {
+      kind: 'color',
+      desiredVariable: 'bg',
+      existingTokenId: 'existing-color-id',
+      defaultResolution: { action: 'auto-rename', resolvedVariable: 'bg-2' },
+    }
+    const [result] = applyConflictResolutions(plan, [], [], [res]).styleRules
+
+    expect(result.styles).toEqual({ '--bg-2': '#000', '--other': '#111' })
+    expect(result.stylePriorities).toEqual({ '--bg-2': 'important' })
+    expect(result.contextStyles).toEqual({ 'bp-mobile': { '--bg-2': '#222' } })
+    expect(result.contextStylePriorities).toEqual({ 'bp-mobile': { '--bg-2': 'important' } })
+  })
+
+  it('rename: renames a font token\'s declaration in another rule', () => {
+    const rule: NewStyleRule = {
+      name: 'serif', kind: 'class', selector: '.serif', order: 0,
+      styles: { '--font-primary': 'Georgia, serif', fontFamily: 'var(--font-primary)' }, contextStyles: {},
+    }
+    const plan = makeTokenPlan({ fontTokens: [makeFontToken('font-primary')], styleRules: [rule] })
+    const res: TokenConflict = {
+      kind: 'font',
+      desiredVariable: 'font-primary',
+      existingTokenId: 'existing-font-id',
+      defaultResolution: { action: 'auto-rename', resolvedVariable: 'font-primary-2' },
+    }
+    const [result] = applyConflictResolutions(plan, [], [], [res]).styleRules
+    expect(result.styles).toEqual({ '--font-primary-2': 'Georgia, serif', fontFamily: 'var(--font-primary-2)' })
+  })
+
+  it('rename: renames declarations and references inside raw @keyframes CSS', () => {
+    const rule: NewStyleRule = {
+      name: 'pulse', kind: 'ambient', selector: '@keyframes pulse', order: 0, styles: {}, contextStyles: {},
+      rawCss: '@keyframes pulse {\nfrom { --bg: #000; color: var(--bg); --bgx: #111; }\n}',
+    }
+    const plan = makeTokenPlan({ colors: [makeColorToken('bg')], styleRules: [rule] })
+    const res: TokenConflict = {
+      kind: 'color',
+      desiredVariable: 'bg',
+      existingTokenId: 'existing-color-id',
+      defaultResolution: { action: 'auto-rename', resolvedVariable: 'bg-2' },
+    }
+    const [result] = applyConflictResolutions(plan, [], [], [res]).styleRules
+    expect(result.rawCss).toBe('@keyframes pulse {\nfrom { --bg-2: #000; color: var(--bg-2); --bgx: #111; }\n}')
+  })
+
   it('rename: rewrites var refs inside node inlineStyles, preserving fallbacks', () => {
     const page: PagePlan = {
       source: 'index.html',
diff --git a/src/core/siteImport/buildPlan.ts b/src/core/siteImport/buildPlan.ts
index f9097919a..b25db7b90 100644
--- a/src/core/siteImport/buildPlan.ts
+++ b/src/core/siteImport/buildPlan.ts
@@ -24,7 +24,9 @@ import { makeHtmlPagePlan } from './htmlPagePlan'
 import { buildAssetPlan, type CssFileResult } from './assetPlan'
 import { partitionLinkedStylesheets } from './stylesheetPlan'
 import { detectCrossSheetClassConflicts } from './classCascades'
-import { detectConflicts } from './conflicts'
+import { detectConflicts, rewriteImportVarRefs } from './conflicts'
+import { declaredCustomProperties } from './varRefs'
+import { normalizeImportedColorTokens } from './colorTokens'
 import { createCssPlanState, parseCssSourceIntoPlan } from './planCss'
 import { rewriteNpmCdnModuleImports } from './scriptDependencies'
 import { mergeScriptOrder, type PageScriptSequence } from './scriptOrder'
@@ -166,25 +168,39 @@ export function buildImportPlan({ fileMap, currentSite, options }: BuildImportPl
     buildAssetPlan(rawPagePlans, publishableCssFileResults, fileMap, rawStylesheetSources)
   warnings.push(...assetWarnings)
 
+  // 5b. Colour tokens are emitted under their normalised slug
+  //     (`--brand---neutral--700` → `--brand-neutral-700`). Settle that name
+  //     now and rewrite the imported `var()` references to match, so the
+  //     conflict step and the commit both see the name that is emitted.
+  const { colorTokens: colors, renames: colorSlugRenames } = normalizeImportedColorTokens(
+    [...cssPlan.colorsBySlug.values()],
+    declaredCustomProperties(normalizedPagePlans, normalizedStyleRules),
+  )
+  const { pages, styleRules } = rewriteImportVarRefs(
+    normalizedPagePlans,
+    normalizedStyleRules,
+    colorSlugRenames,
+  )
+
   // 6. Detect conflicts against the current site — pages, class rules, and
   //    design tokens (colour + font) all flow through one resolution model.
   const conflicts = detectConflicts(
     currentSite,
-    normalizedPagePlans,
-    normalizedStyleRules,
-    [...cssPlan.colorsBySlug.values()],
+    pages,
+    styleRules,
+    colors,
     [...cssPlan.fontTokensByVariable.values()],
   )
 
   return {
-    pages: normalizedPagePlans,
-    styleRules: normalizedStyleRules,
+    pages,
+    styleRules,
     styleRuleSources,
     fonts,
     googleFonts: [...googleFontsByFamily.values()],
     conditions: [...cssPlan.conditionsById.values()],
     assets,
-    colors: [...cssPlan.colorsBySlug.values()],
+    colors,
     fontTokens: [...cssPlan.fontTokensByVariable.values()],
     scripts,
     linkedStylesheets,
diff --git a/src/core/siteImport/colorTokens.ts b/src/core/siteImport/colorTokens.ts
index 929742776..6b5dc2a41 100644
--- a/src/core/siteImport/colorTokens.ts
+++ b/src/core/siteImport/colorTokens.ts
@@ -17,6 +17,7 @@
  * rule) and drops the rule entirely when nothing else remains.
  */
 
+import { normalizeFrameworkColorSlug } from '@core/framework'
 import type { NewStyleRule, ImportColorToken } from './types'
 import { isRootScopeSelector } from './rootScope'
 
@@ -126,3 +127,54 @@ export function extractRootColorTokens(
 
   return { rules: out, colorTokens }
 }
+
+// ---------------------------------------------------------------------------
+// Emitted names
+// ---------------------------------------------------------------------------
+
+/**
+ * Give each extracted colour token the slug the framework will emit for it.
+ *
+ * The framework normalises every colour slug (`normalizeFrameworkColorSlug`:
+ * lowercase, every run of non-alphanumerics collapsed to one `-`), so an
+ * authored `--brand---neutral--700` is emitted as `--brand-neutral-700`. The
+ * returned `renames` map (`authored → emitted`, both without `--`) lists every
+ * name that changed, for rewriting the imported `var()` references.
+ *
+ * Two authored names can normalise to the same slug (`--Brand` and `--brand`).
+ * A name that is already in emitted form keeps it; the others take the first
+ * free `-2`, `-3`, ... suffix, so neither token is lost at commit. A new name
+ * also avoids `declared`, the other custom properties the imported CSS
+ * declares, so a renamed token never takes over an unrelated variable.
+ */
+export function normalizeImportedColorTokens(
+  tokens: ImportColorToken[],
+  declared: Set<string> = new Set(),
+): { colorTokens: ImportColorToken[]; renames: Map<string, string> } {
+  const slugs = new Map<ImportColorToken, string>()
+  const ownNames = new Set(tokens.map((token) => token.slug))
+  // A token's own name may be redeclared by an override (`.dark { --bg: … }`);
+  // only the names of other variables are off limits.
+  const claimed = new Set([...declared].filter((name) => !ownNames.has(name)))
+  for (const token of tokens) {
+    if (normalizeFrameworkColorSlug(token.slug) === token.slug) {
+      slugs.set(token, token.slug)
+      claimed.add(token.slug)
+    }
+  }
+
+  const renames = new Map<string, string>()
+  const colorTokens = tokens.map((token) => {
+    let slug = slugs.get(token)
+    if (slug === undefined) {
+      const base = normalizeFrameworkColorSlug(token.slug)
+      slug = base
+      for (let suffix = 2; claimed.has(slug); suffix++) slug = `${base}-${suffix}`
+      claimed.add(slug)
+      renames.set(token.slug, slug)
+    }
+    return slug === token.slug ? token : { ...token, slug }
+  })
+
+  return { colorTokens, renames }
+}
diff --git a/src/core/siteImport/conflicts.ts b/src/core/siteImport/conflicts.ts
index 80c30b096..5bfc1494c 100644
--- a/src/core/siteImport/conflicts.ts
+++ b/src/core/siteImport/conflicts.ts
@@ -39,6 +39,7 @@ import type { ImportFragment } from '@core/htmlImport'
 import { normalizeFrameworkColorSlug } from '@core/framework'
 import { isUntouchedFontRoleToken, normalizeFontTokenVariable, type FontToken } from '@core/fonts'
 import { applyCrossSheetClassResolutions, normalizeBindableClassRules } from './classCascades'
+import { declaredCustomProperties, rewriteRuleVarRefs, rewriteStyleBagVarRefs } from './varRefs'
 
 // ---------------------------------------------------------------------------
 // Detection
@@ -66,7 +67,12 @@ export function detectConflicts(
 ): ConflictDetectionResult {
   const pageConflicts = detectPageConflicts(currentSite, pagePlans)
   const ruleConflicts = detectRuleConflicts(currentSite, styleRules)
-  const tokenConflicts = detectTokenConflicts(currentSite, colorTokens, fontTokens)
+  const tokenConflicts = detectTokenConflicts(
+    currentSite,
+    colorTokens,
+    fontTokens,
+    declaredCustomProperties(pagePlans, styleRules),
+  )
   return { pages: pageConflicts, rules: ruleConflicts, tokens: tokenConflicts }
 }
 
@@ -188,12 +194,15 @@ function detectRuleConflicts(
  * 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).
+ * collisions are conflicts. A rename target must still avoid every other
+ * imported token's name and every custom property the imported CSS declares
+ * (`reserved`), or the renamed token would shadow or be shadowed by it.
  */
 function detectTokenConflicts(
   site: SiteDocument,
   colorTokens: ImportColorToken[],
   fontTokens: ImportFontToken[],
+  reserved: Set<string>,
 ): TokenConflict[] {
   const conflicts: TokenConflict[] = []
 
@@ -202,7 +211,11 @@ function detectTokenConflicts(
   for (const token of site.settings.framework?.colors?.tokens ?? []) {
     existingColorIds.set(normalizeFrameworkColorSlug(token.slug), token.id)
   }
-  const claimedColors = new Set(existingColorIds.keys())
+  const claimedColors = new Set([
+    ...existingColorIds.keys(),
+    ...colorTokens.map((token) => normalizeFrameworkColorSlug(token.slug)),
+    ...reserved,
+  ])
   for (const token of colorTokens) {
     const existingId = existingColorIds.get(normalizeFrameworkColorSlug(token.slug))
     if (!existingId) continue
@@ -221,7 +234,11 @@ function detectTokenConflicts(
   for (const token of site.settings.fonts?.tokens ?? []) {
     existingFonts.set(normalizeFontTokenVariable(token.variable), token)
   }
-  const claimedFonts = new Set(existingFonts.keys())
+  const claimedFonts = new Set([
+    ...existingFonts.keys(),
+    ...fontTokens.map((token) => normalizeFontTokenVariable(token.variable)),
+    ...reserved,
+  ])
   for (const token of fontTokens) {
     const existing = existingFonts.get(normalizeFontTokenVariable(token.variable))
     if (!existing) continue
@@ -387,8 +404,13 @@ function buildTokenRenameMaps(tokenResolutions: TokenConflict[]): TokenResolutio
   for (const r of tokenResolutions) {
     const res = r.defaultResolution
     const renames = r.kind === 'color' ? colorRenames : fontRenames
-    if (isRename(res) && res.resolvedVariable && res.resolvedVariable !== r.desiredVariable) {
-      renames.set(r.desiredVariable, res.resolvedVariable)
+    // A colour token is emitted under its normalised slug, so a custom rename
+    // (`My Brand`) must rename to that form or its references stop resolving.
+    const resolved = r.kind === 'color' && res.resolvedVariable
+      ? normalizeFrameworkColorSlug(res.resolvedVariable)
+      : res.resolvedVariable
+    if (isRename(res) && resolved && resolved !== r.desiredVariable) {
+      renames.set(r.desiredVariable, resolved)
     } else if (res.action === 'skip') {
       ;(r.kind === 'color' ? colorSkips : fontSkips).add(r.desiredVariable)
     }
@@ -427,6 +449,23 @@ function resolvePagePlans(
   })
 }
 
+/**
+ * Rewrite `var(--old)` → `var(--new)` for every name in `renames` across the
+ * imported style rules and every page's node inline styles. Used when the
+ * importer itself moves a token to a new name (colour slug normalisation).
+ */
+export function rewriteImportVarRefs(
+  pages: PagePlan[],
+  styleRules: NewStyleRule[],
+  renames: Map<string, string>,
+): { pages: PagePlan[]; styleRules: NewStyleRule[] } {
+  if (renames.size === 0) return { pages, styleRules }
+  return {
+    pages: resolvePagePlans(pages, new Map(), new Map(), renames),
+    styleRules: styleRules.map((rule) => rewriteRuleVarRefs(rule, renames)),
+  }
+}
+
 /** Apply rule name resolutions, then rewrite any token var references. */
 function resolveStyleRules(
   styleRules: NewStyleRule[],
@@ -574,69 +613,3 @@ function rewriteSelectorClasses(selector: string, classRenames: Map<string, stri
   }
   return rewritten
 }
-
-/**
- * Rewrite `var(--old)` → `var(--new)` references inside a style rule's base
- * `styles` and every `contextStyles` bag. Returns the same rule when no value
- * changes.
- */
-function rewriteRuleVarRefs(rule: NewStyleRule, renames: Map<string, string>): NewStyleRule {
-  const styles = rewriteStyleBagVarRefs(rule.styles, renames)
-  const rawCss = typeof rule.rawCss === 'string'
-    ? rewriteCssVarRefs(rule.rawCss, renames)
-    : rule.rawCss
-  let contextStyles = rule.contextStyles
-  if (contextStyles && Object.keys(contextStyles).length > 0) {
-    let ctxChanged = false
-    const nextCtx: Record<string, Record<string, unknown>> = {}
-    for (const [ctxId, bag] of Object.entries(contextStyles)) {
-      const nextBag = rewriteStyleBagVarRefs(bag as Record<string, unknown>, renames)
-      if (nextBag !== bag) ctxChanged = true
-      nextCtx[ctxId] = nextBag
-    }
-    if (ctxChanged) contextStyles = nextCtx as NewStyleRule['contextStyles']
-  }
-  return styles === rule.styles && contextStyles === rule.contextStyles && rawCss === rule.rawCss
-    ? rule
-    : {
-        ...rule,
-        styles: styles as NewStyleRule['styles'],
-        contextStyles,
-        ...(rawCss !== undefined ? { rawCss } : {}),
-      }
-}
-
-/**
- * Rewrite `var(--old)` references in every string value of a style bag. Returns
- * the same object reference when nothing changes.
- */
-function rewriteStyleBagVarRefs<T extends Record<string, unknown>>(
-  bag: T,
-  renames: Map<string, string>,
-): T {
-  let changed = false
-  const out: Record<string, unknown> = {}
-  for (const [key, value] of Object.entries(bag)) {
-    if (typeof value === 'string') {
-      const next = rewriteCssVarRefs(value, renames)
-      if (next !== value) changed = true
-      out[key] = next
-    } else {
-      out[key] = value
-    }
-  }
-  return changed ? (out as T) : bag
-}
-
-// Matches `var(--name` (optional leading whitespace), capturing the bare
-// custom-property name. The fallback/closing-paren tail is left untouched.
-const VAR_REF_RE = /var\(\s*--([A-Za-z0-9_-]+)/g
-
-/** Rewrite `var(--old)` → `var(--new)` for every name in `renames`. */
-function rewriteCssVarRefs(value: string, renames: Map<string, string>): string {
-  if (renames.size === 0 || !value.includes('var(')) return value
-  return value.replace(VAR_REF_RE, (match, name: string) => {
-    const next = renames.get(name)
-    return next ? match.replace(`--${name}`, `--${next}`) : match
-  })
-}
diff --git a/src/core/siteImport/index.ts b/src/core/siteImport/index.ts
index 36a2d7ee3..0e52592a8 100644
--- a/src/core/siteImport/index.ts
+++ b/src/core/siteImport/index.ts
@@ -45,7 +45,7 @@ export { applyAssetRewrites } from './applyAssetRewrites'
 
 // ── Phase 2 — colour-token extraction ─────────────────────────────────────────
 
-export { extractRootColorTokens, isCssColorValue } from './colorTokens'
+export { extractRootColorTokens, isCssColorValue, normalizeImportedColorTokens } from './colorTokens'
 
 // ── Phase 2 — font-token extraction ───────────────────────────────────────────
 
diff --git a/src/core/siteImport/varRefs.ts b/src/core/siteImport/varRefs.ts
new file mode 100644
index 000000000..87baf3ff9
--- /dev/null
+++ b/src/core/siteImport/varRefs.ts
@@ -0,0 +1,154 @@
+/**
+ * varRefs — rename custom properties across the imported CSS.
+ *
+ * When the importer moves a design token to a new name (a conflict rename, or
+ * the framework's normalised colour slug), every `var(--old)` reference and
+ * every `--old` declaration in the imported style rules, node inline styles
+ * and raw `@keyframes` CSS must follow it, or the imported design stops
+ * resolving to its own token.
+ */
+
+import type { NewStyleRule, PagePlan } from './types'
+
+/**
+ * Every custom property name (without `--`) the imported CSS declares: in style
+ * rules (base and per-context) and in node inline styles.
+ */
+export function declaredCustomProperties(
+  pages: PagePlan[],
+  styleRules: NewStyleRule[],
+): Set<string> {
+  const names = new Set<string>()
+  const collect = (bag: Record<string, unknown> | undefined) => {
+    for (const key of Object.keys(bag ?? {})) {
+      if (key.startsWith('--')) names.add(key.slice(2))
+    }
+  }
+  for (const rule of styleRules) {
+    collect(rule.styles)
+    for (const bag of Object.values(rule.contextStyles ?? {})) collect(bag)
+  }
+  for (const page of pages) {
+    for (const node of Object.values(page.nodeFragment.nodes)) collect(node.inlineStyles)
+  }
+  return names
+}
+
+/**
+ * Rewrite `var(--old)` → `var(--new)` references inside a style rule's base
+ * `styles` and every `contextStyles` bag. Returns the same rule when no value
+ * changes.
+ */
+export function rewriteRuleVarRefs(rule: NewStyleRule, renames: Map<string, string>): NewStyleRule {
+  const styles = rewriteStyleBagVarRefs(rule.styles, renames)
+  const stylePriorities = rule.stylePriorities
+    ? renameCustomPropertyKeys(rule.stylePriorities, renames)
+    : rule.stylePriorities
+  const rawCss = typeof rule.rawCss === 'string'
+    ? renameCssDeclarations(rewriteCssVarRefs(rule.rawCss, renames), renames)
+    : rule.rawCss
+  const contextStyles = mapContextBags(rule.contextStyles, (bag) => rewriteStyleBagVarRefs(bag, renames))
+  const contextStylePriorities = mapContextBags(
+    rule.contextStylePriorities,
+    (bag) => renameCustomPropertyKeys(bag, renames),
+  )
+  return styles === rule.styles
+    && stylePriorities === rule.stylePriorities
+    && contextStyles === rule.contextStyles
+    && contextStylePriorities === rule.contextStylePriorities
+    && rawCss === rule.rawCss
+    ? rule
+    : {
+        ...rule,
+        styles: styles as NewStyleRule['styles'],
+        contextStyles: contextStyles as NewStyleRule['contextStyles'],
+        ...(stylePriorities !== undefined ? { stylePriorities } : {}),
+        ...(contextStylePriorities !== undefined ? { contextStylePriorities } : {}),
+        ...(rawCss !== undefined ? { rawCss } : {}),
+      }
+}
+
+/** Map every per-context bag; returns the same record when no bag changes. */
+function mapContextBags<T extends Record<string, Record<string, unknown>>>(
+  record: T | undefined,
+  map: (bag: Record<string, unknown>) => Record<string, unknown>,
+): T | undefined {
+  if (!record || Object.keys(record).length === 0) return record
+  let changed = false
+  const out: Record<string, Record<string, unknown>> = {}
+  for (const [ctxId, bag] of Object.entries(record)) {
+    const next = map(bag)
+    if (next !== bag) changed = true
+    out[ctxId] = next
+  }
+  return changed ? (out as T) : record
+}
+
+/**
+ * Rewrite `var(--old)` references in every string value of a style bag, and
+ * rename a `--old` declaration itself, so an override in a non-root rule
+ * (`.dark { --bg: #000 }`) keeps overriding the renamed token. Returns the
+ * same object reference when nothing changes.
+ */
+export function rewriteStyleBagVarRefs<T extends Record<string, unknown>>(
+  bag: T,
+  renames: Map<string, string>,
+): T {
+  let changed = false
+  const out: Record<string, unknown> = {}
+  for (const [key, value] of Object.entries(bag)) {
+    const nextKey = renameCustomPropertyKey(key, renames)
+    if (nextKey !== key) changed = true
+    if (typeof value === 'string') {
+      const next = rewriteCssVarRefs(value, renames)
+      if (next !== value) changed = true
+      out[nextKey] = next
+    } else {
+      out[nextKey] = value
+    }
+  }
+  return changed ? (out as T) : bag
+}
+
+/** Rename `--old` keys of a property-keyed bag (e.g. declaration priorities). */
+function renameCustomPropertyKeys<T extends Record<string, unknown>>(
+  bag: T,
+  renames: Map<string, string>,
+): T {
+  if (!Object.keys(bag).some((key) => renameCustomPropertyKey(key, renames) !== key)) return bag
+  return Object.fromEntries(
+    Object.entries(bag).map(([key, value]) => [renameCustomPropertyKey(key, renames), value]),
+  ) as T
+}
+
+function renameCustomPropertyKey(key: string, renames: Map<string, string>): string {
+  if (!key.startsWith('--')) return key
+  const next = renames.get(key.slice(2))
+  return next ? `--${next}` : key
+}
+
+// Matches `var(--name` (optional leading whitespace), capturing the bare
+// custom-property name. The fallback/closing-paren tail is left untouched.
+const VAR_REF_RE = /var\(\s*--([A-Za-z0-9_-]+)/g
+
+// Matches a `--name:` declaration in raw CSS text (e.g. `@keyframes` bodies),
+// capturing what precedes it and the bare custom-property name.
+const DECLARATION_RE = /(^|[{;\s])--([A-Za-z0-9_-]+)(?=\s*:)/g
+
+/** Rename `--old:` declarations in raw CSS text for every name in `renames`. */
+function renameCssDeclarations(css: string, renames: Map<string, string>): string {
+  if (renames.size === 0 || !css.includes('--')) return css
+  return css.replace(DECLARATION_RE, (match, before: string, name: string) => {
+    const next = renames.get(name)
+    return next ? `${before}--${next}` : match
+  })
+}
+
+/** Rewrite `var(--old)` → `var(--new)` for every name in `renames`. */
+function rewriteCssVarRefs(value: string, renames: Map<string, string>): string {
+  if (renames.size === 0 || !value.includes('var(')) return value
+  return value.replace(VAR_REF_RE, (match, name: string) => {
+    const next = renames.get(name)
+    return next ? match.replace(`--${name}`, `--${next}`) : match
+  })
+}

From cec37f2b8a2e2e8db4db4e8439193b66664d889b Mon Sep 17 00:00:00 2001
From: Emmanuel Ruiz <ehnruiz@gmail.com>
Date: Sun, 11 Oct 2026 04:46:43 -0400
Subject: [PATCH 2/2] fix(siteImport): rewrite var() references to the variable
 a font token is emitted under

Site Import normalised a root `--font-*` variable at extraction
(`--font-Heading` -> `font-heading`), and the store emits that form, but
the imported `var(--font-Heading)` references kept the authored name and
no longer resolved. Two authored names that normalise alike were deduped
into one token, losing a font.

Extraction now keeps the authored variable, and `normalizeImportedTokens`
(new `siteImport/tokenNames.ts`) settles the emitted name of every
imported colour and font token at plan time, in one pass against one set
of claimed names, since both kinds share one CSS namespace. The
`authored -> emitted` renames go through the existing var() and
declaration rewrite, before conflict detection.

`normalizeImportedColorTokens` is replaced by `normalizeImportedTokens`.

Fixes #619
---
 docs/features/site-import.md                 |  5 +-
 src/__tests__/siteImport/applyImport.test.ts | 74 +++++++++++++++++
 src/__tests__/siteImport/colorTokens.test.ts | 71 ++++++++++++-----
 src/__tests__/siteImport/conflicts.test.ts   | 12 +++
 src/core/siteImport/buildPlan.ts             | 26 +++---
 src/core/siteImport/colorTokens.ts           | 52 ------------
 src/core/siteImport/fontTokens.ts            |  6 +-
 src/core/siteImport/index.ts                 |  3 +-
 src/core/siteImport/planCss.ts               |  2 +-
 src/core/siteImport/tokenNames.ts            | 84 ++++++++++++++++++++
 10 files changed, 242 insertions(+), 93 deletions(-)
 create mode 100644 src/core/siteImport/tokenNames.ts

diff --git a/docs/features/site-import.md b/docs/features/site-import.md
index f22ce4456..041964b7a 100644
--- a/docs/features/site-import.md
+++ b/docs/features/site-import.md
@@ -46,6 +46,7 @@ src/core/siteImport/
 ├── applyAssetRewrites.ts — patch fragment props + CSS/@keyframes url() with new media URLs (post-upload)
 ├── linkRewrite.ts       — rewrite intra-site <a href> to cms:page:<id> refs
 ├── conflicts.ts         — detect page-slug + class-name + design-token collisions; apply resolutions (incl. var(--x) rewrites)
+├── tokenNames.ts        — settle the emitted name of every imported colour + font token (authored → emitted renames)
 ├── varRefs.ts           — rename a custom property across imported rules, inline styles and @keyframes (var(--x) refs + --x declarations)
 ├── adapter.ts           — SiteImportAdapter + SiteImportTransaction interfaces (the ONE transaction contract; the editor store implements it directly)
 ├── paths.ts             — dirname/joinPaths for FileMap-relative path resolution
@@ -209,9 +210,9 @@ interface ImportScript {
 | **HTML attributes** | Safe extra attributes on ordinary elements (`id`, ARIA, `role`, custom attrs, `data-*`, etc.) | Stored as `props.htmlAttributes` on base container/text/link/button/image modules so CSS selectors, anchors, classic scripts, accessibility attributes, and template runtime hooks such as `data-bg-src`, `data-aos`, and `data-bs-*` survive import. Users edit the same bag in the Properties panel's Attributes view. `class` is handled by the selector registry, inline `style` becomes `node.inlineStyles`, event handlers are stripped, and reserved Instatic/editor `data-*` names are not imported. Local asset URLs inside these attributes are uploaded and rewritten. |
 | **Style rules** | All rules from linked CSS files and their unconditional local `@import` graph | `expandLinkedCssImports` follows bundled local CSS imports first, then `cssToStyleRules` maps selector declaration blocks to `NewStyleRule` entries (class or ambient kind) and stores supported stylesheet-level rules such as `@keyframes` as ambient raw CSS rules |
 | **Media** | Uploadable images (JPEG, PNG, GIF, WebP, AVIF, SVG), videos, and fonts — including unreferenced files in the bundle | `buildAssetPlan` collects referenced assets and sweeps uploadable unreferenced files. Source companions such as `.scss`, sourcemaps, PHP mailers, `desktop.ini`, and README files are excluded before upload. An `<img>`'s authored `alt` is carried onto the asset and stored on the Media Library record at upload; `loading`, `decoding`, and `fetchpriority` map onto the Image module's first-class props when they hold a value the module offers (anything else keeps the module default). Uploaded assets are filed under folders mirroring their bundle path; a folder failure leaves the asset at the media root with an `asset-folder-failed` warning and never blocks the URL rewrite. |
-| **Color tokens** | CSS custom properties on `:root` / `html` / `body` that look like colours | `extractRootColorTokens` pulls them into `ImportColorToken[]`; they become framework palette tokens. The framework parses hex, rgb/rgba, and hsl/hsla into channels (deriving shades/tints/transparent steps); any other authored value (oklch(), color-mix(), …) still emits its base `--<slug>` verbatim so `var(--x)` references never break. The slug is the framework's normalised form (`--brand---neutral--700` → `--brand-neutral-700`), settled at plan time by `normalizeImportedColorTokens`; every imported `var()` reference and declaration of a renamed name is rewritten to it, and two names that normalise to the same slug both survive (the one already in normalised form keeps it, the other takes a `-2` suffix). A `--<slug>` that collides with an existing colour token surfaces as a `TokenConflict` (rename / skip / overwrite) |
+| **Color tokens** | CSS custom properties on `:root` / `html` / `body` that look like colours | `extractRootColorTokens` pulls them into `ImportColorToken[]`; they become framework palette tokens. The framework parses hex, rgb/rgba, and hsl/hsla into channels (deriving shades/tints/transparent steps); any other authored value (oklch(), color-mix(), …) still emits its base `--<slug>` verbatim so `var(--x)` references never break. The slug is the framework's normalised form (`--brand---neutral--700` → `--brand-neutral-700`), settled at plan time by `normalizeImportedTokens` (`tokenNames.ts`); every imported `var()` reference and declaration of a renamed name is rewritten to it, and two names that normalise to the same slug both survive (the one already in normalised form keeps it, the other takes a `-2` suffix). A `--<slug>` that collides with an existing colour token surfaces as a `TokenConflict` (rename / skip / overwrite) |
 | **Fonts** | Self-hosted `@font-face` families with at least one bundled file, plus trusted Google CSS2 imports | `buildFontFamilies` in `assetPlan.ts` picks the best bundled format (woff2 → woff → ttf → otf); `extractGoogleFontImports` turns Google CSS2 `@import` rules into install requests. Commit uploads custom files via `tx.addFonts`, installs Google families through the CMS Google-font installer, then merges those returned `FontEntry` records via `tx.addInstalledFonts` |
-| **Font tokens** | Root `--font-*` variables with font-family stacks | `extractRootFontTokens` pulls them into `ImportFontToken[]`; committed via `tx.addFontTokens` after fonts so matching imported families can be assigned. A `--font-*` that collides with an existing font token surfaces as a `TokenConflict` (rename / skip / overwrite) |
+| **Font tokens** | Root `--font-*` variables with font-family stacks | `extractRootFontTokens` pulls them into `ImportFontToken[]`. The variable is the store's normalised form (`--font-Heading` → `--font-heading`), settled at plan time by `normalizeImportedTokens` together with the colour slugs (both kinds share one CSS namespace, so neither takes the other's name): references and declarations of a renamed name are rewritten, and two names that normalise to the same variable both survive. Committed via `tx.addFontTokens` after fonts so matching imported families can be assigned. A `--font-*` that collides with an existing font token surfaces as a `TokenConflict` (rename / skip / overwrite) |
 | **Scripts** | Executable inline scripts and JS files linked by imported HTML | Ordered so every page's document order holds at once (see `priority` above) and committed via `tx.addScripts` with page scope from the source HTML. Classic scripts remain plain `<script>` assets and bypass bundling; `type="module"` scripts keep module semantics. Module imports from known npm CDNs (`esm.sh`, `esm.run`, `unpkg`, jsDelivr npm URLs) are rewritten to bare package specifiers and recorded as runtime dependencies, so `https://esm.sh/@motion.page/sdk@1.2.4` becomes `@motion.page/sdk` plus `@motion.page/sdk: 1.2.4` in `packageJson.dependencies`. Non-executable script data such as `application/json`, import maps, and templates is skipped. |
 | **Stylesheets (kept)** | Top-level linked sheets the user opted into `mode: 'file'` | Flattened `@import` graph, Google imports stripped, `url()` normalised; committed via `tx.addStylesheets` as a `SiteFile` (`type: 'style'`) + `site.runtime.styles` entry scoped to the linking pages. Editable afterwards in the Site panel's Styles section and the code editor. |
 
diff --git a/src/__tests__/siteImport/applyImport.test.ts b/src/__tests__/siteImport/applyImport.test.ts
index 4a9d506f6..a39d99b7e 100644
--- a/src/__tests__/siteImport/applyImport.test.ts
+++ b/src/__tests__/siteImport/applyImport.test.ts
@@ -546,6 +546,80 @@ describe('buildImportPlan — structure', () => {
     expect(p.styleRules.find((rule) => rule.selector === 'h1')?.styles.fontFamily).toBe('var(--font-display)')
   })
 
+  it('rewrites var() references to the variable a root font token is emitted under (#619)', () => {
+    const html = `<!doctype html><html><head><link rel="stylesheet" href="style.css"></head><body>
+      <h1 class="title">Home</h1><p class="body">Body</p><p class="hero">Hero</p>
+    </body></html>`
+    const css = `
+      :root {
+        --font-Heading: "Acme Grotesk", serif;
+        --font-body--alt: "Inter", sans-serif;
+        --font-display: "Acme Grotesk", serif;
+      }
+      .title { font-family: var(--font-Heading); }
+      .body { font-family: var(--font-body--alt); }
+      .hero { font-family: var(--font-display); }
+      .dark { --font-Heading: Georgia, serif; }
+    `
+    const p = buildImportPlan({
+      fileMap: makeSinglePageFileMap(html, css),
+      currentSite: makeEmptySiteDocument(),
+    })
+
+    expect(p.fontTokens.map((t) => [t.name, t.variable])).toEqual([
+      ['Heading', 'font-heading'],
+      ['Body Alt', 'font-body-alt'],
+      ['Display', 'font-display'],
+    ])
+    const rule = (selector: string) => p.styleRules.find((r) => r.selector === selector)
+    expect(rule('.title')?.styles.fontFamily).toBe('var(--font-heading)')
+    expect(rule('.body')?.styles.fontFamily).toBe('var(--font-body-alt)')
+    expect(rule('.hero')?.styles.fontFamily).toBe('var(--font-display)')
+    // A non-root override follows the token to its new name.
+    expect(rule('.dark')?.styles).toEqual({ '--font-heading': 'Georgia, serif' })
+    expect(p.conflicts.tokens).toHaveLength(0)
+  })
+
+  it('keeps both font tokens when two names normalise to the same variable', () => {
+    const html = `<!doctype html><html><head><link rel="stylesheet" href="style.css"></head><body><h1>x</h1></body></html>`
+    const css = `
+      :root { --font-Heading: "Acme Grotesk", serif; --font-heading: "Inter", sans-serif; }
+      h1 { font-family: var(--font-Heading); }
+      h2 { font-family: var(--font-heading); }
+    `
+    const p = buildImportPlan({
+      fileMap: makeSinglePageFileMap(html, css),
+      currentSite: makeEmptySiteDocument(),
+    })
+
+    // The name already in emitted form keeps it; the other takes a suffix.
+    expect(p.fontTokens.map((t) => [t.name, t.variable, t.family])).toEqual([
+      ['Heading 2', 'font-heading-2', 'Acme Grotesk'],
+      ['Heading', 'font-heading', 'Inter'],
+    ])
+    expect(p.styleRules.find((r) => r.selector === 'h1')?.styles.fontFamily).toBe('var(--font-heading-2)')
+    expect(p.styleRules.find((r) => r.selector === 'h2')?.styles.fontFamily).toBe('var(--font-heading)')
+  })
+
+  it('does not give a font token the name of an imported colour token', () => {
+    const html = `<!doctype html><html><head><link rel="stylesheet" href="style.css"></head><body><h1>x</h1></body></html>`
+    const css = `
+      :root { --font-accent: #fc834b; --font-Accent: "Inter", sans-serif; }
+      h1 { color: var(--font-accent); font-family: var(--font-Accent); }
+    `
+    const p = buildImportPlan({
+      fileMap: makeSinglePageFileMap(html, css),
+      currentSite: makeEmptySiteDocument(),
+    })
+
+    expect(p.colors).toEqual([{ slug: 'font-accent', value: '#fc834b' }])
+    expect(p.fontTokens.map((t) => t.variable)).toEqual(['font-accent-2'])
+    expect(p.styleRules.find((r) => r.selector === 'h1')?.styles).toMatchObject({
+      color: 'var(--font-accent)',
+      fontFamily: 'var(--font-accent-2)',
+    })
+  })
+
   it('plans Google Fonts @import as installed font requests', () => {
     const html = `<!doctype html><html><head><link rel="stylesheet" href="style.css"></head><body><h1>Home</h1></body></html>`
     const css = `
diff --git a/src/__tests__/siteImport/colorTokens.test.ts b/src/__tests__/siteImport/colorTokens.test.ts
index a6e66863f..5393d0dfe 100644
--- a/src/__tests__/siteImport/colorTokens.test.ts
+++ b/src/__tests__/siteImport/colorTokens.test.ts
@@ -3,7 +3,7 @@
  */
 
 import { describe, it, expect } from 'bun:test'
-import { extractRootColorTokens, isCssColorValue, normalizeImportedColorTokens } from '@core/siteImport'
+import { extractRootColorTokens, isCssColorValue, normalizeImportedTokens } from '@core/siteImport'
 import type { NewStyleRule } from '@core/siteImport'
 
 function ambient(selector: string, styles: Record<string, unknown>): NewStyleRule {
@@ -83,14 +83,19 @@ describe('extractRootColorTokens', () => {
   })
 })
 
-describe('normalizeImportedColorTokens', () => {
-  it('gives each token its emitted slug and maps every changed name (#615)', () => {
-    const { colorTokens, renames } = normalizeImportedColorTokens([
-      { slug: 'brand---neutral--700', value: '#4f5459' },
-      { slug: 'brand-primary', value: '#0575d6' },
-      { slug: 'Brand-Accent', value: '#fc834b' },
-    ])
-    expect(colorTokens).toEqual([
+describe('normalizeImportedTokens', () => {
+  const font = (variable: string) => ({ name: variable, variable, family: 'Inter', fallback: 'sans-serif' })
+
+  it('gives each colour token its emitted slug and maps every changed name (#615)', () => {
+    const { colors, renames } = normalizeImportedTokens({
+      colors: [
+        { slug: 'brand---neutral--700', value: '#4f5459' },
+        { slug: 'brand-primary', value: '#0575d6' },
+        { slug: 'Brand-Accent', value: '#fc834b' },
+      ],
+      fonts: [],
+    })
+    expect(colors).toEqual([
       { slug: 'brand-neutral-700', value: '#4f5459' },
       { slug: 'brand-primary', value: '#0575d6' },
       { slug: 'brand-accent', value: '#fc834b' },
@@ -103,29 +108,53 @@ describe('normalizeImportedColorTokens', () => {
 
   it('keeps both tokens when two names normalise to the same slug', () => {
     // The name already in emitted form keeps it, wherever it appears.
-    const { colorTokens, renames } = normalizeImportedColorTokens([
-      { slug: 'Brand', value: '#111' },
-      { slug: 'brand', value: '#222' },
-      { slug: 'brand--', value: '#333' },
-    ])
-    expect(colorTokens.map((t) => t.slug)).toEqual(['brand-2', 'brand', 'brand-3'])
+    const { colors, renames } = normalizeImportedTokens({
+      colors: [
+        { slug: 'Brand', value: '#111' },
+        { slug: 'brand', value: '#222' },
+        { slug: 'brand--', value: '#333' },
+      ],
+      fonts: [],
+    })
+    expect(colors.map((t) => t.slug)).toEqual(['brand-2', 'brand', 'brand-3'])
     expect([...renames]).toEqual([['Brand', 'brand-2'], ['brand--', 'brand-3']])
   })
 
   it('does not rename a token onto another variable the import declares', () => {
-    const { colorTokens, renames } = normalizeImportedColorTokens(
-      [{ slug: 'a--b', value: '#111' }, { slug: 'bg', value: '#fff' }],
+    const { colors, renames } = normalizeImportedTokens(
+      { colors: [{ slug: 'a--b', value: '#111' }, { slug: 'bg', value: '#fff' }], fonts: [] },
       // `a-b` is an unrelated variable; `bg` is the token's own override.
       new Set(['a-b', 'bg']),
     )
-    expect(colorTokens.map((t) => t.slug)).toEqual(['a-b-2', 'bg'])
+    expect(colors.map((t) => t.slug)).toEqual(['a-b-2', 'bg'])
     expect([...renames]).toEqual([['a--b', 'a-b-2']])
   })
 
   it('returns no renames when every name is already in emitted form', () => {
-    const tokens = [{ slug: 'bg', value: '#fff' }, { slug: 'ink-2', value: '#000' }]
-    const { colorTokens, renames } = normalizeImportedColorTokens(tokens)
-    expect(colorTokens).toEqual(tokens)
+    const colorTokens = [{ slug: 'bg', value: '#fff' }, { slug: 'ink-2', value: '#000' }]
+    const { colors, fonts, renames } = normalizeImportedTokens({ colors: colorTokens, fonts: [font('font-body')] })
+    expect(colors).toEqual(colorTokens)
+    expect(fonts).toEqual([font('font-body')])
     expect(renames.size).toBe(0)
   })
+
+  it('does not rename a colour onto a font token\'s name (#619)', () => {
+    const { colors, fonts, renames } = normalizeImportedTokens({
+      colors: [{ slug: 'font--accent', value: '#fff' }],
+      fonts: [font('font-accent')],
+    })
+    expect(colors.map((t) => t.slug)).toEqual(['font-accent-2'])
+    expect(fonts.map((t) => t.variable)).toEqual(['font-accent'])
+    expect([...renames]).toEqual([['font--accent', 'font-accent-2']])
+  })
+
+  it('does not rename a font onto a colour token\'s name (#619)', () => {
+    const { colors, fonts, renames } = normalizeImportedTokens({
+      colors: [{ slug: 'font-accent', value: '#fff' }],
+      fonts: [font('font-Accent')],
+    })
+    expect(colors.map((t) => t.slug)).toEqual(['font-accent'])
+    expect(fonts.map((t) => [t.name, t.variable])).toEqual([['Accent 2', 'font-accent-2']])
+    expect([...renames]).toEqual([['font-Accent', 'font-accent-2']])
+  })
 })
diff --git a/src/__tests__/siteImport/conflicts.test.ts b/src/__tests__/siteImport/conflicts.test.ts
index 972e079d8..b170e56ee 100644
--- a/src/__tests__/siteImport/conflicts.test.ts
+++ b/src/__tests__/siteImport/conflicts.test.ts
@@ -501,6 +501,18 @@ describe('detectConflicts — rename targets avoid the import\'s own names', ()
     expect(tokens.map((t) => t.defaultResolution.resolvedVariable)).toEqual(['bg-3', 'font-primary-3'])
   })
 
+  it('detects an authored font variable against an existing token by its emitted name (#619)', () => {
+    const html = `<!doctype html><html><head><link rel="stylesheet" href="style.css"></head><body><p class="u">x</p></body></html>`
+    const css = `:root { --font-Primary: "Acme Grotesk", serif; } .u { font-family: var(--font-Primary); }`
+    const plan = buildImportPlan({ fileMap: makeSinglePageFileMap(html, css), currentSite: siteWithTokens() })
+
+    expect(plan.conflicts.tokens.map((t) => [t.kind, t.desiredVariable, t.defaultResolution.resolvedVariable]))
+      .toEqual([['font', 'font-primary', 'font-primary-2']])
+    const result = applyConflictResolutions(plan, [], [], plan.conflicts.tokens)
+    expect(result.fontTokens.map((t) => t.variable)).toEqual(['font-primary-2'])
+    expect(result.styleRules.find((r) => r.selector === '.u')?.styles.fontFamily).toBe('var(--font-primary-2)')
+  })
+
   it('keeps both colours when a normalised name and a conflict rename meet (#615)', () => {
     // `--BG` normalises to `bg-2`, so the conflict rename of `--bg` must not
     // take `bg-2` too, or one colour is lost at commit.
diff --git a/src/core/siteImport/buildPlan.ts b/src/core/siteImport/buildPlan.ts
index b25db7b90..1da5be931 100644
--- a/src/core/siteImport/buildPlan.ts
+++ b/src/core/siteImport/buildPlan.ts
@@ -26,7 +26,7 @@ import { partitionLinkedStylesheets } from './stylesheetPlan'
 import { detectCrossSheetClassConflicts } from './classCascades'
 import { detectConflicts, rewriteImportVarRefs } from './conflicts'
 import { declaredCustomProperties } from './varRefs'
-import { normalizeImportedColorTokens } from './colorTokens'
+import { normalizeImportedTokens } from './tokenNames'
 import { createCssPlanState, parseCssSourceIntoPlan } from './planCss'
 import { rewriteNpmCdnModuleImports } from './scriptDependencies'
 import { mergeScriptOrder, type PageScriptSequence } from './scriptOrder'
@@ -168,19 +168,17 @@ export function buildImportPlan({ fileMap, currentSite, options }: BuildImportPl
     buildAssetPlan(rawPagePlans, publishableCssFileResults, fileMap, rawStylesheetSources)
   warnings.push(...assetWarnings)
 
-  // 5b. Colour tokens are emitted under their normalised slug
-  //     (`--brand---neutral--700` → `--brand-neutral-700`). Settle that name
-  //     now and rewrite the imported `var()` references to match, so the
-  //     conflict step and the commit both see the name that is emitted.
-  const { colorTokens: colors, renames: colorSlugRenames } = normalizeImportedColorTokens(
-    [...cssPlan.colorsBySlug.values()],
+  // 5b. Colour and font tokens are emitted under their normalised name
+  //     (`--brand---neutral--700` → `--brand-neutral-700`, `--font-Heading` →
+  //     `--font-heading`). Settle those names now and rewrite the imported
+  //     `var()` references to match, so the conflict step and the commit both
+  //     see the name that is emitted. Both kinds share one CSS namespace and
+  //     are settled together.
+  const { colors, fonts: fontTokens, renames } = normalizeImportedTokens(
+    { colors: [...cssPlan.colorsBySlug.values()], fonts: [...cssPlan.fontTokensByVariable.values()] },
     declaredCustomProperties(normalizedPagePlans, normalizedStyleRules),
   )
-  const { pages, styleRules } = rewriteImportVarRefs(
-    normalizedPagePlans,
-    normalizedStyleRules,
-    colorSlugRenames,
-  )
+  const { pages, styleRules } = rewriteImportVarRefs(normalizedPagePlans, normalizedStyleRules, renames)
 
   // 6. Detect conflicts against the current site — pages, class rules, and
   //    design tokens (colour + font) all flow through one resolution model.
@@ -189,7 +187,7 @@ export function buildImportPlan({ fileMap, currentSite, options }: BuildImportPl
     pages,
     styleRules,
     colors,
-    [...cssPlan.fontTokensByVariable.values()],
+    fontTokens,
   )
 
   return {
@@ -201,7 +199,7 @@ export function buildImportPlan({ fileMap, currentSite, options }: BuildImportPl
     conditions: [...cssPlan.conditionsById.values()],
     assets,
     colors,
-    fontTokens: [...cssPlan.fontTokensByVariable.values()],
+    fontTokens,
     scripts,
     linkedStylesheets,
     stylesheets,
diff --git a/src/core/siteImport/colorTokens.ts b/src/core/siteImport/colorTokens.ts
index 6b5dc2a41..929742776 100644
--- a/src/core/siteImport/colorTokens.ts
+++ b/src/core/siteImport/colorTokens.ts
@@ -17,7 +17,6 @@
  * rule) and drops the rule entirely when nothing else remains.
  */
 
-import { normalizeFrameworkColorSlug } from '@core/framework'
 import type { NewStyleRule, ImportColorToken } from './types'
 import { isRootScopeSelector } from './rootScope'
 
@@ -127,54 +126,3 @@ export function extractRootColorTokens(
 
   return { rules: out, colorTokens }
 }
-
-// ---------------------------------------------------------------------------
-// Emitted names
-// ---------------------------------------------------------------------------
-
-/**
- * Give each extracted colour token the slug the framework will emit for it.
- *
- * The framework normalises every colour slug (`normalizeFrameworkColorSlug`:
- * lowercase, every run of non-alphanumerics collapsed to one `-`), so an
- * authored `--brand---neutral--700` is emitted as `--brand-neutral-700`. The
- * returned `renames` map (`authored → emitted`, both without `--`) lists every
- * name that changed, for rewriting the imported `var()` references.
- *
- * Two authored names can normalise to the same slug (`--Brand` and `--brand`).
- * A name that is already in emitted form keeps it; the others take the first
- * free `-2`, `-3`, ... suffix, so neither token is lost at commit. A new name
- * also avoids `declared`, the other custom properties the imported CSS
- * declares, so a renamed token never takes over an unrelated variable.
- */
-export function normalizeImportedColorTokens(
-  tokens: ImportColorToken[],
-  declared: Set<string> = new Set(),
-): { colorTokens: ImportColorToken[]; renames: Map<string, string> } {
-  const slugs = new Map<ImportColorToken, string>()
-  const ownNames = new Set(tokens.map((token) => token.slug))
-  // A token's own name may be redeclared by an override (`.dark { --bg: … }`);
-  // only the names of other variables are off limits.
-  const claimed = new Set([...declared].filter((name) => !ownNames.has(name)))
-  for (const token of tokens) {
-    if (normalizeFrameworkColorSlug(token.slug) === token.slug) {
-      slugs.set(token, token.slug)
-      claimed.add(token.slug)
-    }
-  }
-
-  const renames = new Map<string, string>()
-  const colorTokens = tokens.map((token) => {
-    let slug = slugs.get(token)
-    if (slug === undefined) {
-      const base = normalizeFrameworkColorSlug(token.slug)
-      slug = base
-      for (let suffix = 2; claimed.has(slug); suffix++) slug = `${base}-${suffix}`
-      claimed.add(slug)
-      renames.set(token.slug, slug)
-    }
-    return slug === token.slug ? token : { ...token, slug }
-  })
-
-  return { colorTokens, renames }
-}
diff --git a/src/core/siteImport/fontTokens.ts b/src/core/siteImport/fontTokens.ts
index dbc700b86..41c7a58c9 100644
--- a/src/core/siteImport/fontTokens.ts
+++ b/src/core/siteImport/fontTokens.ts
@@ -64,7 +64,7 @@ function unquoteFamily(raw: string): string {
   return trimmed
 }
 
-function tokenNameFromVariable(variable: string): string {
+export function tokenNameFromVariable(variable: string): string {
   const base = normalizeFontTokenVariable(variable).replace(/^font-/, '')
   const words = base.split('-').filter(Boolean)
   if (words.length === 0) return 'Font'
@@ -93,7 +93,9 @@ function importTokenFromDeclaration(prop: string, value: string): ImportFontToke
   if (!prop.startsWith('--font-')) return null
   if (!isFontFamilyLike(value)) return null
 
-  const variable = normalizeFontTokenVariable(prop)
+  // The authored name, kept so `normalizeImportedTokens` can map the
+  // imported `var()` references to the name the token is emitted under.
+  const variable = prop.slice(2)
   const parts = splitFontStack(value)
   if (parts.length === 0) return null
 
diff --git a/src/core/siteImport/index.ts b/src/core/siteImport/index.ts
index 0e52592a8..119f08c3a 100644
--- a/src/core/siteImport/index.ts
+++ b/src/core/siteImport/index.ts
@@ -45,7 +45,8 @@ export { applyAssetRewrites } from './applyAssetRewrites'
 
 // ── Phase 2 — colour-token extraction ─────────────────────────────────────────
 
-export { extractRootColorTokens, isCssColorValue, normalizeImportedColorTokens } from './colorTokens'
+export { extractRootColorTokens, isCssColorValue } from './colorTokens'
+export { normalizeImportedTokens } from './tokenNames'
 
 // ── Phase 2 — font-token extraction ───────────────────────────────────────────
 
diff --git a/src/core/siteImport/planCss.ts b/src/core/siteImport/planCss.ts
index 28717a84c..5ad644a10 100644
--- a/src/core/siteImport/planCss.ts
+++ b/src/core/siteImport/planCss.ts
@@ -32,7 +32,7 @@ export interface CssPlanState {
   conditionsById: Map<string, ConditionDef>
   /** Colour tokens pulled from root-scope rules, deduped by slug. */
   colorsBySlug: Map<string, ImportColorToken>
-  /** Font tokens pulled from root-scope rules, deduped by normalized variable. */
+  /** Font tokens pulled from root-scope rules, deduped by authored variable. */
   fontTokensByVariable: Map<string, ImportFontToken>
   cssFileResults: CssFileResult[]
 }
diff --git a/src/core/siteImport/tokenNames.ts b/src/core/siteImport/tokenNames.ts
new file mode 100644
index 000000000..a2bf384d6
--- /dev/null
+++ b/src/core/siteImport/tokenNames.ts
@@ -0,0 +1,84 @@
+/**
+ * tokenNames — settle the name each imported design token is emitted under.
+ *
+ * The store normalises every token name: colour slugs with
+ * `normalizeFrameworkColorSlug`, font variables with `normalizeFontTokenVariable`
+ * (lowercase, every run of non-alphanumerics collapsed to one `-`). So an
+ * authored `--brand---neutral--700` is emitted as `--brand-neutral-700` and
+ * `--font-Heading` as `--font-heading`. The importer settles those names at plan
+ * time and returns the `authored → emitted` map (names without `--`) that
+ * `rewriteImportVarRefs` applies to the imported `var()` references and
+ * declarations.
+ *
+ * Colour and font tokens share one CSS namespace, so both kinds are settled
+ * together against one set of claimed names.
+ */
+
+import { normalizeFrameworkColorSlug } from '@core/framework'
+import { normalizeFontTokenVariable } from '@core/fonts'
+import type { ImportColorToken, ImportFontToken } from './types'
+import { tokenNameFromVariable } from './fontTokens'
+
+interface NamedEntry {
+  name: string
+  normalize: (name: string) => string
+}
+
+/**
+ * Give each imported colour and font token its emitted name.
+ *
+ * A name already in emitted form keeps it. Any other takes its normalised form,
+ * or the first free `-2`, `-3`, ... suffix when that is taken by another token
+ * of either kind or by `declared`, the other custom properties the imported CSS
+ * declares. A token's own authored name in `declared` (an override such as
+ * `.dark { --bg: … }`) is not a conflict. Colours are settled before fonts.
+ */
+export function normalizeImportedTokens(
+  tokens: { colors: ImportColorToken[]; fonts: ImportFontToken[] },
+  declared: Set<string> = new Set(),
+): { colors: ImportColorToken[]; fonts: ImportFontToken[]; renames: Map<string, string> } {
+  const entries: NamedEntry[] = [
+    ...tokens.colors.map((token) => ({ name: token.slug, normalize: normalizeFrameworkColorSlug })),
+    ...tokens.fonts.map((token) => ({ name: token.variable, normalize: normalizeFontTokenVariable })),
+  ]
+  const { emitted, renames } = assignEmittedNames(entries, declared)
+  const fontOffset = tokens.colors.length
+
+  const colors = tokens.colors.map((token, i) =>
+    emitted[i] === token.slug ? token : { ...token, slug: emitted[i] },
+  )
+  const fonts = tokens.fonts.map((token, i) => {
+    const variable = emitted[fontOffset + i]
+    return variable === token.variable
+      ? token
+      : { ...token, name: tokenNameFromVariable(variable), variable }
+  })
+  return { colors, fonts, renames }
+}
+
+function assignEmittedNames(
+  entries: NamedEntry[],
+  declared: Set<string>,
+): { emitted: string[]; renames: Map<string, string> } {
+  const own = new Set(entries.map((entry) => entry.name))
+  const claimed = new Set([...declared].filter((name) => !own.has(name)))
+  const kept = new Set<string>()
+  for (const { name, normalize } of entries) {
+    if (normalize(name) === name) {
+      kept.add(name)
+      claimed.add(name)
+    }
+  }
+
+  const renames = new Map<string, string>()
+  const emitted = entries.map(({ name, normalize }) => {
+    if (kept.has(name)) return name
+    const base = normalize(name)
+    let next = base
+    for (let suffix = 2; claimed.has(next); suffix++) next = `${base}-${suffix}`
+    claimed.add(next)
+    renames.set(name, next)
+    return next
+  })
+  return { emitted, renames }
+}