diff --git a/docs/features/site-import.md b/docs/features/site-import.md
index de6093e12..041964b7a 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,8 @@ 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
 ├── planCss.ts           — single CSS-source parse path (external sheets + per-page inline <style>) feeding shared plan accumulators
@@ -208,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. 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. |
 
@@ -296,7 +298,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..a39d99b7e 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 = `
@@ -509,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 17f80fd3b..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 } 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 {
@@ -82,3 +82,79 @@ describe('extractRootColorTokens', () => {
     expect(out[0].stylePriorities).toEqual({ '--brand': 'important' })
   })
 })
+
+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' },
+    ])
+    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 { 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 { 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(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 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 be4f5511d..b170e56ee 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,53 @@ 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('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.
+    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 +555,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..1da5be931 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 { normalizeImportedTokens } from './tokenNames'
 import { createCssPlanState, parseCssSourceIntoPlan } from './planCss'
 import { rewriteNpmCdnModuleImports } from './scriptDependencies'
 import { mergeScriptOrder, type PageScriptSequence } from './scriptOrder'
@@ -166,26 +168,38 @@ export function buildImportPlan({ fileMap, currentSite, options }: BuildImportPl
     buildAssetPlan(rawPagePlans, publishableCssFileResults, fileMap, rawStylesheetSources)
   warnings.push(...assetWarnings)
 
+  // 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, renames)
+
   // 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()],
-    [...cssPlan.fontTokensByVariable.values()],
+    pages,
+    styleRules,
+    colors,
+    fontTokens,
   )
 
   return {
-    pages: normalizedPagePlans,
-    styleRules: normalizedStyleRules,
+    pages,
+    styleRules,
     styleRuleSources,
     fonts,
     googleFonts: [...googleFontsByFamily.values()],
     conditions: [...cssPlan.conditionsById.values()],
     assets,
-    colors: [...cssPlan.colorsBySlug.values()],
-    fontTokens: [...cssPlan.fontTokensByVariable.values()],
+    colors,
+    fontTokens,
     scripts,
     linkedStylesheets,
     stylesheets,
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/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 36a2d7ee3..119f08c3a 100644
--- a/src/core/siteImport/index.ts
+++ b/src/core/siteImport/index.ts
@@ -46,6 +46,7 @@ export { applyAssetRewrites } from './applyAssetRewrites'
 // ── Phase 2 — colour-token extraction ─────────────────────────────────────────
 
 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 }
+}
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
+  })
+}