From ecc49131fe293c9e7c0ccc572be7056e936bdc99 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 9 Jul 2026 11:35:01 +0000
Subject: [PATCH 1/9] Add design-token extraction API for button-like elements

New, additive /api/design-tokens endpoint: scrapes a URL's HTML+CSS,
finds button/.button/.btn/[role=button] elements via linkedom, matches
CSS rules against them with element.matches(), and resolves the CSS
cascade (specificity, !important, source order) to surface only
design-token-relevant declarations (background/color/border/shadow/
font, not spacing) per element and per interaction state
(hover/focus/active/disabled). Results are grouped into suggested
token combinations. No existing files were modified.
---
 src/routes/api/design-tokens/+server.ts       |  35 +++
 .../api/design-tokens/component-presets.ts    |  36 +++
 src/routes/api/design-tokens/design-tokens.ts |  29 ++
 .../api/design-tokens/extract-tokens.test.ts  | 106 ++++++++
 .../api/design-tokens/extract-tokens.ts       | 254 ++++++++++++++++++
 5 files changed, 460 insertions(+)
 create mode 100644 src/routes/api/design-tokens/+server.ts
 create mode 100644 src/routes/api/design-tokens/component-presets.ts
 create mode 100644 src/routes/api/design-tokens/design-tokens.ts
 create mode 100644 src/routes/api/design-tokens/extract-tokens.test.ts
 create mode 100644 src/routes/api/design-tokens/extract-tokens.ts

diff --git a/src/routes/api/design-tokens/+server.ts b/src/routes/api/design-tokens/+server.ts
new file mode 100644
index 00000000..26d0a371
--- /dev/null
+++ b/src/routes/api/design-tokens/+server.ts
@@ -0,0 +1,35 @@
+export const prerender = false
+
+import { error, json } from '@sveltejs/kit'
+import { get_design_tokens } from './design-tokens'
+import { COMPONENT_PRESETS, type Component } from './component-presets'
+import type { RequestHandler } from './$types'
+
+export const GET: RequestHandler = async ({ setHeaders, url }) => {
+	let analyzeUrl = url.searchParams.get('url')
+
+	if (analyzeUrl === null) {
+		return json({ error: 'Missing URL' }, { status: 400 })
+	}
+
+	let component = url.searchParams.get('component') ?? 'button'
+
+	if (!(component in COMPONENT_PRESETS)) {
+		return json({ error: `Unsupported component: ${component}` }, { status: 400 })
+	}
+
+	try {
+		let result = await get_design_tokens(analyzeUrl, component as Component)
+
+		if ('error' in result) {
+			return json({ error: result.error })
+		}
+
+		setHeaders({ 'Cache-Control': 's-maxage=600' })
+
+		return json(result)
+	} catch (err) {
+		console.error(err)
+		error(500, 'An unexpected error occurred.')
+	}
+}
diff --git a/src/routes/api/design-tokens/component-presets.ts b/src/routes/api/design-tokens/component-presets.ts
new file mode 100644
index 00000000..6c70cb73
--- /dev/null
+++ b/src/routes/api/design-tokens/component-presets.ts
@@ -0,0 +1,36 @@
+export const COMPONENT_PRESETS = {
+	button: ['button', '.button', '.btn', '[role="button"]']
+} as const
+
+export type Component = keyof typeof COMPONENT_PRESETS
+
+// Prefix-matched against declaration.property. Intentionally excludes
+// spacing/layout props (margin, padding, width, gap, position, display, ...).
+export const DESIGN_TOKEN_PROPERTY_PREFIXES = [
+	'background',
+	'color',
+	'border',
+	'outline',
+	'box-shadow',
+	'font',
+	'line-height',
+	'text-decoration',
+	'fill',
+	'stroke',
+	'accent-color',
+	'caret-color'
+]
+
+// Dynamic/interaction pseudo-classes that never structurally "match" a static
+// DOM (linkedom has no real hover/focus state) - stripped before .matches(),
+// remembered as a "state" bucket for the resulting tokens.
+export const STATE_PSEUDO_CLASSES = [
+	'hover',
+	'focus',
+	'focus-visible',
+	'focus-within',
+	'active',
+	'disabled',
+	'visited',
+	'target'
+]
diff --git a/src/routes/api/design-tokens/design-tokens.ts b/src/routes/api/design-tokens/design-tokens.ts
new file mode 100644
index 00000000..53dfaefe
--- /dev/null
+++ b/src/routes/api/design-tokens/design-tokens.ts
@@ -0,0 +1,29 @@
+import { parseHTML } from 'linkedom'
+import { get_css, USER_AGENT } from '../get-css/get-css'
+import { extract_design_tokens, group_suggestions } from './extract-tokens'
+import type { Component } from './component-presets'
+
+export async function get_design_tokens(url: string, component: Component = 'button') {
+	let [html_response, css_origins] = await Promise.all([
+		fetch(url, { headers: { 'User-Agent': USER_AGENT } }),
+		get_css(url)
+	])
+
+	if ('error' in css_origins) {
+		return css_origins
+	}
+
+	if (!html_response.ok) {
+		return { error: { url, statusCode: html_response.status, message: html_response.statusText } }
+	}
+
+	let { document } = parseHTML(await html_response.text())
+	let css = css_origins.map((origin) => origin.css).join('\n')
+	let results = extract_design_tokens(document, css, component)
+
+	return {
+		component,
+		elements: results.length,
+		suggestions: group_suggestions(results)
+	}
+}
diff --git a/src/routes/api/design-tokens/extract-tokens.test.ts b/src/routes/api/design-tokens/extract-tokens.test.ts
new file mode 100644
index 00000000..f9c0072e
--- /dev/null
+++ b/src/routes/api/design-tokens/extract-tokens.test.ts
@@ -0,0 +1,106 @@
+import { test, expect } from 'vitest'
+import { parseHTML } from 'linkedom'
+import { extract_design_tokens, group_suggestions } from './extract-tokens'
+
+function make_document(html: string) {
+	return parseHTML(html).document
+}
+
+test('only design-token properties are extracted, not spacing', () => {
+	let document = make_document('<button class="btn">Buy</button>')
+	let css = '.btn { background: red; padding: 8px; margin: 4px; }'
+
+	let [result] = extract_design_tokens(document, css, 'button')
+
+	expect(result.tokens.base).toEqual({ background: 'red' })
+})
+
+test('higher specificity wins regardless of source order', () => {
+	let document = make_document('<button id="save" class="btn">Save</button>')
+	let css = `
+		#save.btn { background: green; }
+		.btn { background: blue; }
+	`
+
+	let [result] = extract_design_tokens(document, css, 'button')
+
+	expect(result.tokens.base.background).toBe('green')
+})
+
+test('equal specificity: later rule in source order wins', () => {
+	let document = make_document('<button class="btn">Save</button>')
+	let css = `
+		.btn { background: blue; }
+		.btn { background: green; }
+	`
+
+	let [result] = extract_design_tokens(document, css, 'button')
+
+	expect(result.tokens.base.background).toBe('green')
+})
+
+test('!important beats higher specificity', () => {
+	let document = make_document('<button id="save" class="btn">Save</button>')
+	let css = `
+		#save.btn { background: green; }
+		.btn { background: blue !important; }
+	`
+
+	let [result] = extract_design_tokens(document, css, 'button')
+
+	expect(result.tokens.base.background).toBe('blue')
+})
+
+test(':hover and :disabled produce separate state buckets layered on top of base', () => {
+	let document = make_document('<button class="btn">Save</button>')
+	let css = `
+		.btn { background: blue; }
+		.btn:hover { background: darkblue; }
+		.btn:disabled { background: grey; }
+	`
+
+	let [result] = extract_design_tokens(document, css, 'button')
+
+	expect(result.tokens.base.background).toBe('blue')
+	expect(result.tokens.hover.background).toBe('darkblue')
+	expect(result.tokens.disabled.background).toBe('grey')
+})
+
+test('pseudo-element rules are excluded entirely', () => {
+	let document = make_document('<button class="btn">Save</button>')
+	let css = '.btn::before { background: red; } .btn { color: black; }'
+
+	let [result] = extract_design_tokens(document, css, 'button')
+
+	expect(result.tokens.base).toEqual({ color: 'black' })
+})
+
+test('finds button-like elements via the button/.button/.btn/[role=button] preset', () => {
+	let document = make_document(`
+		<button>Native</button>
+		<div class="button">Div button</div>
+		<span class="btn">Span btn</span>
+		<a role="button">Link button</a>
+		<div>Not a button</div>
+	`)
+	let css = 'button, .button, .btn, [role="button"] { color: black; }'
+
+	let results = extract_design_tokens(document, css, 'button')
+
+	expect(results).toHaveLength(4)
+})
+
+test('group_suggestions dedupes structurally identical buttons', () => {
+	let document = make_document(`
+		<button class="btn">One</button>
+		<button class="btn">Two</button>
+	`)
+	let css = '.btn { background: blue; }'
+
+	let results = extract_design_tokens(document, css, 'button')
+	let suggestions = group_suggestions(results)
+
+	expect(results).toHaveLength(2)
+	expect(suggestions).toHaveLength(1)
+	expect(suggestions[0].count).toBe(2)
+})
diff --git a/src/routes/api/design-tokens/extract-tokens.ts b/src/routes/api/design-tokens/extract-tokens.ts
new file mode 100644
index 00000000..ab6881ee
--- /dev/null
+++ b/src/routes/api/design-tokens/extract-tokens.ts
@@ -0,0 +1,254 @@
+import { parse, walk, parse_selector_list, STYLE_RULE, DECLARATION } from '@projectwallace/css-parser'
+import { calculateSpecificity, compareSpecificity, type Specificity } from '@projectwallace/css-analyzer'
+import { COMPONENT_PRESETS, DESIGN_TOKEN_PROPERTY_PREFIXES, STATE_PSEUDO_CLASSES, type Component } from './component-presets'
+
+export type TokenDeclaration = {
+	property: string
+	value: string
+	important: boolean
+}
+
+export type Rule = {
+	selector_text: string
+	declarations: TokenDeclaration[]
+	order_index: number
+}
+
+/** Walk a stylesheet once and collect every style rule (incl. ones nested in @media/@supports). */
+export function parse_rules(css: string): Rule[] {
+	let ast
+	try {
+		ast = parse(css, { parse_selectors: false })
+	} catch {
+		return []
+	}
+
+	let rules: Rule[] = []
+	let order_index = 0
+
+	walk(ast, (node) => {
+		if (node.type === STYLE_RULE) {
+			let selector_text = node.has_prelude ? node.prelude.text : ''
+			let declarations: TokenDeclaration[] = []
+
+			if (node.has_block) {
+				for (let child of node.block.children) {
+					if (child.type === DECLARATION) {
+						declarations.push({
+							property: child.property,
+							value: child.value?.text ?? '',
+							important: child.is_important
+						})
+					}
+				}
+			}
+
+			rules.push({ selector_text, declarations, order_index: order_index++ })
+		}
+	})
+
+	return rules
+}
+
+export type ParsedSelector = {
+	text: string
+	specificity: Specificity
+}
+
+/** Split a rule's (possibly comma-separated) selector text into individual selectors with their specificity. */
+export function parse_individual_selectors(selector_list_text: string): ParsedSelector[] {
+	if (!selector_list_text.trim()) return []
+
+	try {
+		let ast = parse_selector_list(selector_list_text)
+		if (!ast.has_children) return []
+
+		let specificities = calculateSpecificity(ast)
+		let result: ParsedSelector[] = []
+
+		for (let i = 0; i < ast.children.length; i++) {
+			let node = ast.children[i]
+			let specificity = specificities[i]
+			if (node && specificity) {
+				result.push({ text: node.text, specificity })
+			}
+		}
+
+		return result
+	} catch {
+		return []
+	}
+}
+
+const STATE_PSEUDO_REGEX = new RegExp(`:(?:${STATE_PSEUDO_CLASSES.join('|')})\\b`, 'g')
+
+/**
+ * A static DOM has no real :hover/:focus state, so element.matches() can never
+ * see it. Strip interaction pseudo-classes off before matching and remember
+ * which state(s) they represented instead.
+ */
+export function strip_state_pseudo_classes(selector: string): { structural: string; states: string[] } {
+	let states: string[] = []
+	let structural = selector.replace(STATE_PSEUDO_REGEX, (match) => {
+		let state = match.slice(1)
+		if (!states.includes(state)) states.push(state)
+		return ''
+	})
+	return { structural: structural.trim(), states }
+}
+
+export function filter_design_tokens(declarations: TokenDeclaration[]): TokenDeclaration[] {
+	return declarations.filter((decl) => DESIGN_TOKEN_PROPERTY_PREFIXES.some((prefix) => decl.property.startsWith(prefix)))
+}
+
+export type PropertyMatch = {
+	/** Empty array = applies unconditionally (base state). */
+	states: string[]
+	selector_text: string
+	property: string
+	value: string
+	important: boolean
+	specificity: Specificity
+	order_index: number
+}
+
+/** For every element, find every rule whose selector structurally matches it and collect its design-token declarations. */
+export function match_elements(elements: Element[], rules: Rule[]): Map<Element, PropertyMatch[]> {
+	let result = new Map<Element, PropertyMatch[]>()
+
+	for (let rule of rules) {
+		let token_declarations = filter_design_tokens(rule.declarations)
+		if (token_declarations.length === 0) continue
+
+		for (let selector of parse_individual_selectors(rule.selector_text)) {
+			// Pseudo-elements (::before, ::after, ...) style a generated box, not the element itself - out of scope for v1.
+			if (selector.text.includes('::')) continue
+
+			let { structural, states } = strip_state_pseudo_classes(selector.text)
+			if (!structural) continue
+
+			for (let element of elements) {
+				let matches: boolean
+				try {
+					matches = element.matches(structural)
+				} catch {
+					continue
+				}
+				if (!matches) continue
+
+				let entries = result.get(element)
+				if (!entries) {
+					entries = []
+					result.set(element, entries)
+				}
+
+				for (let decl of token_declarations) {
+					entries.push({
+						states,
+						selector_text: selector.text,
+						property: decl.property,
+						value: decl.value,
+						important: decl.important,
+						specificity: selector.specificity,
+						order_index: rule.order_index
+					})
+				}
+			}
+		}
+	}
+
+	return result
+}
+
+export type ResolvedTokens = { base: Record<string, string> } & Record<string, Record<string, string>>
+
+/** Resolve the CSS cascade (!important > specificity > source order) per state, layering each state's overrides on top of the base state. */
+export function resolve_tokens(matches: PropertyMatch[]): ResolvedTokens {
+	let all_states = new Set<string>()
+	for (let match of matches) {
+		for (let state of match.states) all_states.add(state)
+	}
+
+	function resolve_for(predicate: (match: PropertyMatch) => boolean): Record<string, string> {
+		let sorted = matches.filter(predicate).toSorted((a, b) => {
+			if (a.important !== b.important) return a.important ? 1 : -1
+			// compareSpecificity(x, y) is negative when x is MORE specific than y (descending
+			// comparator), so args are flipped here to get ascending order - least specific
+			// first, most specific last, so the last entry in the sorted array "wins".
+			let specificity_comparison = compareSpecificity(b.specificity, a.specificity)
+			if (specificity_comparison !== 0) return specificity_comparison
+			return a.order_index - b.order_index
+		})
+
+		let resolved: Record<string, string> = {}
+		for (let entry of sorted) {
+			resolved[entry.property] = entry.value
+		}
+		return resolved
+	}
+
+	let result: ResolvedTokens = { base: resolve_for((match) => match.states.length === 0) }
+
+	for (let state of all_states) {
+		result[state] = resolve_for((match) => match.states.length === 0 || match.states.includes(state))
+	}
+
+	return result
+}
+
+export type ComponentTokenResult = {
+	tag: string
+	class_name: string
+	matched_selectors: string[]
+	tokens: ResolvedTokens
+}
+
+export function extract_design_tokens(document: Document, css: string, component: Component): ComponentTokenResult[] {
+	let selector = COMPONENT_PRESETS[component].join(', ')
+	let elements = Array.from(document.querySelectorAll(selector)) as Element[]
+	if (elements.length === 0) return []
+
+	let rules = parse_rules(css)
+	let matches_by_element = match_elements(elements, rules)
+
+	let results: ComponentTokenResult[] = []
+	for (let element of elements) {
+		let matches = matches_by_element.get(element)
+		if (!matches || matches.length === 0) continue
+
+		results.push({
+			tag: element.tagName.toLowerCase(),
+			class_name: element.getAttribute('class') ?? '',
+			matched_selectors: Array.from(new Set(matches.map((match) => match.selector_text))),
+			tokens: resolve_tokens(matches)
+		})
+	}
+
+	return results
+}
+
+export type Suggestion = {
+	tokens: ResolvedTokens
+	count: number
+	examples: string[]
+}
+
+/** Group elements that resolved to an identical base token set - the simplest possible "suggested combination" list. */
+export function group_suggestions(results: ComponentTokenResult[]): Suggestion[] {
+	let groups = new Map<string, Suggestion>()
+
+	for (let result of results) {
+		let key = JSON.stringify(result.tokens.base)
+		let example = result.class_name ? `${result.tag}.${result.class_name.trim().split(/\s+/).join('.')}` : result.tag
+
+		let group = groups.get(key)
+		if (group) {
+			group.count++
+			if (group.examples.length < 5) group.examples.push(example)
+		} else {
+			groups.set(key, { tokens: result.tokens, count: 1, examples: [example] })
+		}
+	}
+
+	return Array.from(groups.values()).toSorted((a, b) => b.count - a.count)
+}

From cf34363e163ebf0ef70596c5940fc065bf38052e Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 9 Jul 2026 12:42:31 +0000
Subject: [PATCH 2/9] Add debug page to inspect /api/design-tokens output

New (public)/component-tokens page reuses the existing CSS-form URL
submit flow (same pattern as lint-css), fetches the design-tokens API
for the submitted URL, and renders the raw JSON in a <pre> so the
extracted token combinations can be eyeballed. File/raw-CSS tabs of
the form are present but unused. No existing files were modified.
---
 .../(public)/component-tokens/+page.svelte    | 77 +++++++++++++++++++
 1 file changed, 77 insertions(+)
 create mode 100644 src/routes/(public)/component-tokens/+page.svelte

diff --git a/src/routes/(public)/component-tokens/+page.svelte b/src/routes/(public)/component-tokens/+page.svelte
new file mode 100644
index 00000000..31830e36
--- /dev/null
+++ b/src/routes/(public)/component-tokens/+page.svelte
@@ -0,0 +1,77 @@
+<script lang="ts">
+	import { browser } from '$app/environment'
+	import Seo from '$components/Seo.svelte'
+	import Hero from '$components/Hero.svelte'
+	import Container from '$components/Container.svelte'
+	import Form from '$components/css-form/Form.svelte'
+	import PrettyJson from '$components/PrettyJson.svelte'
+	import { get_css_state } from '$lib/css-state.svelte'
+
+	let css_state = get_css_state()
+	let loading = $state(false)
+	let result: unknown = $state()
+	let error: string | undefined = $state()
+
+	let effective_url = $derived(css_state.url)
+
+	async function fetch_tokens(url: string) {
+		loading = true
+		error = undefined
+		result = undefined
+		try {
+			let response = await fetch(`/api/design-tokens?url=${encodeURIComponent(url)}`)
+			let data = await response.json()
+			if (!response.ok || (data && typeof data === 'object' && 'error' in data)) {
+				let api_error = (data as { error?: unknown })?.error
+				error =
+					typeof api_error === 'string' ? api_error : ((api_error as { message?: string })?.message ?? 'Something went wrong.')
+			} else {
+				result = data
+			}
+		} catch {
+			error = 'Something went wrong.'
+		} finally {
+			loading = false
+		}
+	}
+
+	$effect(() => {
+		if (browser && effective_url) {
+			fetch_tokens(effective_url)
+		}
+	})
+</script>
+
+<Seo
+	title="Component Design Tokens"
+	description="Inspect suggested design token combinations for button-like components on any URL."
+/>
+
+<Hero>
+	<Form on_url_submit={() => false} external_loading={loading}>
+		{#snippet title()}
+			<h1 class="font-heading">Component Design Tokens</h1>
+		{/snippet}
+	</Form>
+</Hero>
+
+<Container>
+	{#if loading}
+		<p>Loading&hellip;</p>
+	{:else if error}
+		<p class="error-msg">{error}</p>
+	{:else if result}
+		<PrettyJson json={JSON.stringify(result, null, 2)} />
+	{/if}
+</Container>
+
+<style>
+	.font-heading {
+		font-size: var(--size-5xl);
+	}
+
+	.error-msg {
+		color: var(--error-300);
+		font-weight: var(--font-medium);
+	}
+</style>

From 059fea402dd170a4ceac28eb810781eddf2bcc67 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 9 Jul 2026 12:51:00 +0000
Subject: [PATCH 3/9] Return tokens for every component preset in a single
 response

/api/design-tokens no longer takes a ?component= selector; it now runs
the extraction pipeline once per known preset (button, heading) and
returns a report keyed by component name. Also adds the heading
(h1/.h1/.heading-1) preset, and switches to the non-deprecated
compareSpecificity export from @projectwallace/css-analyzer/selectors
(the main-index one is documented as its inverse, which is why the
cascade sort previously needed flipped arguments).
---
 .../(public)/component-tokens/+page.svelte    |  6 ++-
 src/routes/api/design-tokens/+server.ts       |  9 +---
 .../api/design-tokens/component-presets.ts    |  3 +-
 src/routes/api/design-tokens/design-tokens.ts | 12 ++---
 .../api/design-tokens/extract-tokens.test.ts  | 33 +++++++++++-
 .../api/design-tokens/extract-tokens.ts       | 50 ++++++++++++++-----
 6 files changed, 80 insertions(+), 33 deletions(-)

diff --git a/src/routes/(public)/component-tokens/+page.svelte b/src/routes/(public)/component-tokens/+page.svelte
index 31830e36..55b5a530 100644
--- a/src/routes/(public)/component-tokens/+page.svelte
+++ b/src/routes/(public)/component-tokens/+page.svelte
@@ -24,7 +24,9 @@
 			if (!response.ok || (data && typeof data === 'object' && 'error' in data)) {
 				let api_error = (data as { error?: unknown })?.error
 				error =
-					typeof api_error === 'string' ? api_error : ((api_error as { message?: string })?.message ?? 'Something went wrong.')
+					typeof api_error === 'string'
+						? api_error
+						: ((api_error as { message?: string })?.message ?? 'Something went wrong.')
 			} else {
 				result = data
 			}
@@ -44,7 +46,7 @@
 
 <Seo
 	title="Component Design Tokens"
-	description="Inspect suggested design token combinations for button-like components on any URL."
+	description="Inspect suggested design token combinations for common components on any URL."
 />
 
 <Hero>
diff --git a/src/routes/api/design-tokens/+server.ts b/src/routes/api/design-tokens/+server.ts
index 26d0a371..f373e3a5 100644
--- a/src/routes/api/design-tokens/+server.ts
+++ b/src/routes/api/design-tokens/+server.ts
@@ -2,7 +2,6 @@ export const prerender = false
 
 import { error, json } from '@sveltejs/kit'
 import { get_design_tokens } from './design-tokens'
-import { COMPONENT_PRESETS, type Component } from './component-presets'
 import type { RequestHandler } from './$types'
 
 export const GET: RequestHandler = async ({ setHeaders, url }) => {
@@ -12,14 +11,8 @@ export const GET: RequestHandler = async ({ setHeaders, url }) => {
 		return json({ error: 'Missing URL' }, { status: 400 })
 	}
 
-	let component = url.searchParams.get('component') ?? 'button'
-
-	if (!(component in COMPONENT_PRESETS)) {
-		return json({ error: `Unsupported component: ${component}` }, { status: 400 })
-	}
-
 	try {
-		let result = await get_design_tokens(analyzeUrl, component as Component)
+		let result = await get_design_tokens(analyzeUrl)
 
 		if ('error' in result) {
 			return json({ error: result.error })
diff --git a/src/routes/api/design-tokens/component-presets.ts b/src/routes/api/design-tokens/component-presets.ts
index 6c70cb73..397be4ab 100644
--- a/src/routes/api/design-tokens/component-presets.ts
+++ b/src/routes/api/design-tokens/component-presets.ts
@@ -1,5 +1,6 @@
 export const COMPONENT_PRESETS = {
-	button: ['button', '.button', '.btn', '[role="button"]']
+	button: ['button', '.button', '.btn', '[role="button"]'],
+	heading: ['h1', '.h1', '.heading-1']
 } as const
 
 export type Component = keyof typeof COMPONENT_PRESETS
diff --git a/src/routes/api/design-tokens/design-tokens.ts b/src/routes/api/design-tokens/design-tokens.ts
index 53dfaefe..9391ee5a 100644
--- a/src/routes/api/design-tokens/design-tokens.ts
+++ b/src/routes/api/design-tokens/design-tokens.ts
@@ -1,9 +1,8 @@
 import { parseHTML } from 'linkedom'
 import { get_css, USER_AGENT } from '../get-css/get-css'
-import { extract_design_tokens, group_suggestions } from './extract-tokens'
-import type { Component } from './component-presets'
+import { extract_all_design_tokens } from './extract-tokens'
 
-export async function get_design_tokens(url: string, component: Component = 'button') {
+export async function get_design_tokens(url: string) {
 	let [html_response, css_origins] = await Promise.all([
 		fetch(url, { headers: { 'User-Agent': USER_AGENT } }),
 		get_css(url)
@@ -19,11 +18,6 @@ export async function get_design_tokens(url: string, component: Component = 'but
 
 	let { document } = parseHTML(await html_response.text())
 	let css = css_origins.map((origin) => origin.css).join('\n')
-	let results = extract_design_tokens(document, css, component)
 
-	return {
-		component,
-		elements: results.length,
-		suggestions: group_suggestions(results)
-	}
+	return extract_all_design_tokens(document, css)
 }
diff --git a/src/routes/api/design-tokens/extract-tokens.test.ts b/src/routes/api/design-tokens/extract-tokens.test.ts
index f9c0072e..679b7df8 100644
--- a/src/routes/api/design-tokens/extract-tokens.test.ts
+++ b/src/routes/api/design-tokens/extract-tokens.test.ts
@@ -1,6 +1,6 @@
 import { test, expect } from 'vitest'
 import { parseHTML } from 'linkedom'
-import { extract_design_tokens, group_suggestions } from './extract-tokens'
+import { extract_design_tokens, extract_all_design_tokens, group_suggestions } from './extract-tokens'
 
 function make_document(html: string) {
 	return parseHTML(html).document
@@ -90,6 +90,37 @@ test('finds button-like elements via the button/.button/.btn/[role=button] prese
 	expect(results).toHaveLength(4)
 })
 
+test('finds heading-like elements via the h1/.h1/.heading-1 preset', () => {
+	let document = make_document(`
+		<h1>Native</h1>
+		<div class="h1">Div heading</div>
+		<span class="heading-1">Span heading</span>
+		<h2>Not an h1</h2>
+	`)
+	let css = 'h1, .h1, .heading-1 { color: black; }'
+
+	let results = extract_design_tokens(document, css, 'heading')
+
+	expect(results).toHaveLength(3)
+})
+
+test('extract_all_design_tokens reports every component preset in a single pass', () => {
+	let document = make_document(`
+		<h1 class="h1">Title</h1>
+		<button class="btn">Buy</button>
+		<button class="btn">Sell</button>
+	`)
+	let css = '.h1 { color: black; } .btn { background: blue; }'
+
+	let report = extract_all_design_tokens(document, css)
+
+	expect(Object.keys(report)).toEqual(['button', 'heading'])
+	expect(report.button.elements).toBe(2)
+	expect(report.button.suggestions[0].tokens.base).toEqual({ background: 'blue' })
+	expect(report.heading.elements).toBe(1)
+	expect(report.heading.suggestions[0].tokens.base).toEqual({ color: 'black' })
+})
+
 test('group_suggestions dedupes structurally identical buttons', () => {
 	let document = make_document(`
 		<button class="btn">One</button>
diff --git a/src/routes/api/design-tokens/extract-tokens.ts b/src/routes/api/design-tokens/extract-tokens.ts
index ab6881ee..a5f56797 100644
--- a/src/routes/api/design-tokens/extract-tokens.ts
+++ b/src/routes/api/design-tokens/extract-tokens.ts
@@ -1,6 +1,12 @@
 import { parse, walk, parse_selector_list, STYLE_RULE, DECLARATION } from '@projectwallace/css-parser'
-import { calculateSpecificity, compareSpecificity, type Specificity } from '@projectwallace/css-analyzer'
-import { COMPONENT_PRESETS, DESIGN_TOKEN_PROPERTY_PREFIXES, STATE_PSEUDO_CLASSES, type Component } from './component-presets'
+import { calculateSpecificity, type Specificity } from '@projectwallace/css-analyzer'
+import { compareSpecificity } from '@projectwallace/css-analyzer/selectors'
+import {
+	COMPONENT_PRESETS,
+	DESIGN_TOKEN_PROPERTY_PREFIXES,
+	STATE_PSEUDO_CLASSES,
+	type Component
+} from './component-presets'
 
 export type TokenDeclaration = {
 	property: string
@@ -98,7 +104,9 @@ export function strip_state_pseudo_classes(selector: string): { structural: stri
 }
 
 export function filter_design_tokens(declarations: TokenDeclaration[]): TokenDeclaration[] {
-	return declarations.filter((decl) => DESIGN_TOKEN_PROPERTY_PREFIXES.some((prefix) => decl.property.startsWith(prefix)))
+	return declarations.filter((decl) =>
+		DESIGN_TOKEN_PROPERTY_PREFIXES.some((prefix) => decl.property.startsWith(prefix))
+	)
 }
 
 export type PropertyMatch = {
@@ -170,15 +178,16 @@ export function resolve_tokens(matches: PropertyMatch[]): ResolvedTokens {
 	}
 
 	function resolve_for(predicate: (match: PropertyMatch) => boolean): Record<string, string> {
-		let sorted = matches.filter(predicate).toSorted((a, b) => {
-			if (a.important !== b.important) return a.important ? 1 : -1
-			// compareSpecificity(x, y) is negative when x is MORE specific than y (descending
-			// comparator), so args are flipped here to get ascending order - least specific
-			// first, most specific last, so the last entry in the sorted array "wins".
-			let specificity_comparison = compareSpecificity(b.specificity, a.specificity)
-			if (specificity_comparison !== 0) return specificity_comparison
-			return a.order_index - b.order_index
-		})
+		let sorted = matches
+			.filter((match) => predicate(match))
+			.toSorted((a, b) => {
+				if (a.important !== b.important) return a.important ? 1 : -1
+				// Ascending order: least specific first, most specific last, so the
+				// last entry in the sorted array "wins" the cascade.
+				let specificity_comparison = compareSpecificity(a.specificity, b.specificity)
+				if (specificity_comparison !== 0) return specificity_comparison
+				return a.order_index - b.order_index
+			})
 
 		let resolved: Record<string, string> = {}
 		for (let entry of sorted) {
@@ -252,3 +261,20 @@ export function group_suggestions(results: ComponentTokenResult[]): Suggestion[]
 
 	return Array.from(groups.values()).toSorted((a, b) => b.count - a.count)
 }
+
+export type ComponentReport = { elements: number; suggestions: Suggestion[] }
+
+/** Run the full extraction pipeline for every known component preset, keyed by component name. */
+export function extract_all_design_tokens(document: Document, css: string): Record<Component, ComponentReport> {
+	let report = {} as Record<Component, ComponentReport>
+
+	for (let component of Object.keys(COMPONENT_PRESETS) as Component[]) {
+		let results = extract_design_tokens(document, css, component)
+		report[component] = {
+			elements: results.length,
+			suggestions: group_suggestions(results)
+		}
+	}
+
+	return report
+}

From 868ed9be03fc0f6d394047b913c463614bdb6345 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 9 Jul 2026 13:00:36 +0000
Subject: [PATCH 4/9] Fix "Something went wrong" on every URL by resolving it
 before fetch

get_design_tokens fetched the raw, unresolved url string directly for
the page's HTML, unlike get_css which normalizes it through
resolve_url() first. Any protocol-less input (e.g. "example.com" -
literally the form's own placeholder text) made the native fetch()
throw "Invalid URL" inside the Promise.all, which propagated past the
try/catch in +server.ts as a generic 500 that the page always reported
as "Something went wrong."

Now the url is validated/normalized via resolve_url() up front (same
as get_css), and the HTML fetch failure is caught and turned into a
proper structured error instead of an uncaught rejection.
---
 src/routes/api/design-tokens/design-tokens.ts | 21 ++++++++++++++++---
 1 file changed, 18 insertions(+), 3 deletions(-)

diff --git a/src/routes/api/design-tokens/design-tokens.ts b/src/routes/api/design-tokens/design-tokens.ts
index 9391ee5a..84a3b3f4 100644
--- a/src/routes/api/design-tokens/design-tokens.ts
+++ b/src/routes/api/design-tokens/design-tokens.ts
@@ -1,10 +1,19 @@
 import { parseHTML } from 'linkedom'
 import { get_css, USER_AGENT } from '../get-css/get-css'
 import { extract_all_design_tokens } from './extract-tokens'
+import { resolve_url } from '../../../lib/resolve-url.js'
 
 export async function get_design_tokens(url: string) {
+	let resolved_url = resolve_url(url)
+
+	if (resolved_url === undefined) {
+		return {
+			error: { url, statusCode: 400, message: 'The URL is not valid. Are you sure you entered a URL and not CSS?' }
+		}
+	}
+
 	let [html_response, css_origins] = await Promise.all([
-		fetch(url, { headers: { 'User-Agent': USER_AGENT } }),
+		fetch(resolved_url, { headers: { 'User-Agent': USER_AGENT } }).catch(() => undefined),
 		get_css(url)
 	])
 
@@ -12,8 +21,14 @@ export async function get_design_tokens(url: string) {
 		return css_origins
 	}
 
-	if (!html_response.ok) {
-		return { error: { url, statusCode: html_response.status, message: html_response.statusText } }
+	if (html_response === undefined || !html_response.ok) {
+		return {
+			error: {
+				url,
+				statusCode: html_response?.status ?? 502,
+				message: html_response?.statusText ?? 'Could not fetch the page HTML to find components on.'
+			}
+		}
 	}
 
 	let { document } = parseHTML(await html_response.text())

From b319bed4faeb9f476d1f91c90ffe6ef67a2de003 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 9 Jul 2026 14:05:23 +0000
Subject: [PATCH 5/9] Treat padding as a design token property

padding is part of a component's visual shape, not just layout noise
like margin/width/gap - add it to the design-token property allowlist
alongside the already-present outline.
---
 src/routes/api/design-tokens/component-presets.ts   | 5 +++--
 src/routes/api/design-tokens/extract-tokens.test.ts | 4 ++--
 2 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/src/routes/api/design-tokens/component-presets.ts b/src/routes/api/design-tokens/component-presets.ts
index 397be4ab..c1da83fd 100644
--- a/src/routes/api/design-tokens/component-presets.ts
+++ b/src/routes/api/design-tokens/component-presets.ts
@@ -6,7 +6,7 @@ export const COMPONENT_PRESETS = {
 export type Component = keyof typeof COMPONENT_PRESETS
 
 // Prefix-matched against declaration.property. Intentionally excludes
-// spacing/layout props (margin, padding, width, gap, position, display, ...).
+// layout props (margin, width, gap, position, display, ...).
 export const DESIGN_TOKEN_PROPERTY_PREFIXES = [
 	'background',
 	'color',
@@ -19,7 +19,8 @@ export const DESIGN_TOKEN_PROPERTY_PREFIXES = [
 	'fill',
 	'stroke',
 	'accent-color',
-	'caret-color'
+	'caret-color',
+	'padding'
 ]
 
 // Dynamic/interaction pseudo-classes that never structurally "match" a static
diff --git a/src/routes/api/design-tokens/extract-tokens.test.ts b/src/routes/api/design-tokens/extract-tokens.test.ts
index 679b7df8..61fbeab6 100644
--- a/src/routes/api/design-tokens/extract-tokens.test.ts
+++ b/src/routes/api/design-tokens/extract-tokens.test.ts
@@ -6,13 +6,13 @@ function make_document(html: string) {
 	return parseHTML(html).document
 }
 
-test('only design-token properties are extracted, not spacing', () => {
+test('design-token properties are extracted, layout properties like margin are not', () => {
 	let document = make_document('<button class="btn">Buy</button>')
 	let css = '.btn { background: red; padding: 8px; margin: 4px; }'
 
 	let [result] = extract_design_tokens(document, css, 'button')
 
-	expect(result.tokens.base).toEqual({ background: 'red' })
+	expect(result.tokens.base).toEqual({ background: 'red', padding: '8px' })
 })
 
 test('higher specificity wins regardless of source order', () => {

From 1d8f6b2275c2ebff27afd4c16f61e0d367a0b11c Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 9 Jul 2026 14:14:18 +0000
Subject: [PATCH 6/9] Tighten the button preset selectors

Drop the bare "button" tag selector in favor of more specific matches:
button[type="submit"], input[type="button"], .button/.btn classes,
[role="button"], and suffix classes like [class*="-button"] and
[class*="-btn"].
---
 src/routes/api/design-tokens/component-presets.ts | 10 +++++++++-
 .../api/design-tokens/extract-tokens.test.ts      | 15 +++++++++++----
 2 files changed, 20 insertions(+), 5 deletions(-)

diff --git a/src/routes/api/design-tokens/component-presets.ts b/src/routes/api/design-tokens/component-presets.ts
index c1da83fd..8220d022 100644
--- a/src/routes/api/design-tokens/component-presets.ts
+++ b/src/routes/api/design-tokens/component-presets.ts
@@ -1,5 +1,13 @@
 export const COMPONENT_PRESETS = {
-	button: ['button', '.button', '.btn', '[role="button"]'],
+	button: [
+		'button[type="submit"]',
+		'input[type="button"]',
+		'.button',
+		'.btn',
+		'[role="button"]',
+		'[class*="-button"]',
+		'[class*="-btn"]'
+	],
 	heading: ['h1', '.h1', '.heading-1']
 } as const
 
diff --git a/src/routes/api/design-tokens/extract-tokens.test.ts b/src/routes/api/design-tokens/extract-tokens.test.ts
index 61fbeab6..017a862e 100644
--- a/src/routes/api/design-tokens/extract-tokens.test.ts
+++ b/src/routes/api/design-tokens/extract-tokens.test.ts
@@ -75,19 +75,26 @@ test('pseudo-element rules are excluded entirely', () => {
 	expect(result.tokens.base).toEqual({ color: 'black' })
 })
 
-test('finds button-like elements via the button/.button/.btn/[role=button] preset', () => {
+test('finds button-like elements via the button preset, but not a plain <button>', () => {
 	let document = make_document(`
-		<button>Native</button>
+		<button>Native, no type attribute</button>
+		<button type="submit">Submit</button>
+		<input type="button" value="Click" />
 		<div class="button">Div button</div>
 		<span class="btn">Span btn</span>
 		<a role="button">Link button</a>
+		<div class="primary-button">Primary</div>
+		<div class="cta-btn">CTA</div>
 		<div>Not a button</div>
 	`)
-	let css = 'button, .button, .btn, [role="button"] { color: black; }'
+	let css = `
+		button[type="submit"], input[type="button"], .button, .btn, [role="button"],
+		[class*="-button"], [class*="-btn"] { color: black; }
+	`
 
 	let results = extract_design_tokens(document, css, 'button')
 
-	expect(results).toHaveLength(4)
+	expect(results).toHaveLength(7)
 })
 
 test('finds heading-like elements via the h1/.h1/.heading-1 preset', () => {

From 1d48ef259c3b7717991d266aa135de6eff79de2e Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 9 Jul 2026 14:21:30 +0000
Subject: [PATCH 7/9] Exclude link-styled elements from the button preset

Wrap the button preset's selectors in :is(...):not([class*="-link"])
so fuzzy matchers like [class*="-button"] don't pick up elements whose
class also identifies them as a link (e.g. "nav-link"). Component
presets are now single compound selector strings instead of arrays
joined with a comma.
---
 src/routes/api/design-tokens/component-presets.ts | 15 +++++----------
 .../api/design-tokens/extract-tokens.test.ts      | 14 ++++++++++++++
 src/routes/api/design-tokens/extract-tokens.ts    |  2 +-
 3 files changed, 20 insertions(+), 11 deletions(-)

diff --git a/src/routes/api/design-tokens/component-presets.ts b/src/routes/api/design-tokens/component-presets.ts
index 8220d022..6b8f442e 100644
--- a/src/routes/api/design-tokens/component-presets.ts
+++ b/src/routes/api/design-tokens/component-presets.ts
@@ -1,14 +1,9 @@
 export const COMPONENT_PRESETS = {
-	button: [
-		'button[type="submit"]',
-		'input[type="button"]',
-		'.button',
-		'.btn',
-		'[role="button"]',
-		'[class*="-button"]',
-		'[class*="-btn"]'
-	],
-	heading: ['h1', '.h1', '.heading-1']
+	// [class*="-button"]/[class*="-btn"] are broad enough to also catch links styled
+	// as buttons, so exclude anything whose class also says it's a link (e.g. "nav-link").
+	button:
+		':is(button[type="submit"], input[type="button"], .button, .btn, [role="button"], [class*="-button"], [class*="-btn"]):not([class*="-link"])',
+	heading: 'h1, .h1, .heading-1'
 } as const
 
 export type Component = keyof typeof COMPONENT_PRESETS
diff --git a/src/routes/api/design-tokens/extract-tokens.test.ts b/src/routes/api/design-tokens/extract-tokens.test.ts
index 017a862e..2bafc245 100644
--- a/src/routes/api/design-tokens/extract-tokens.test.ts
+++ b/src/routes/api/design-tokens/extract-tokens.test.ts
@@ -97,6 +97,20 @@ test('finds button-like elements via the button preset, but not a plain <button>
 	expect(results).toHaveLength(7)
 })
 
+test('excludes elements whose class also says "link", even if it also looks like a button', () => {
+	let document = make_document(`
+		<div class="primary-button">Real button</div>
+		<a class="cta-button nav-link">Link styled as a button</a>
+		<div class="primary-btn footer-link">Also a link</div>
+	`)
+	let css = '[class*="-button"], [class*="-btn"] { color: black; }'
+
+	let results = extract_design_tokens(document, css, 'button')
+
+	expect(results).toHaveLength(1)
+	expect(results[0].class_name).toBe('primary-button')
+})
+
 test('finds heading-like elements via the h1/.h1/.heading-1 preset', () => {
 	let document = make_document(`
 		<h1>Native</h1>
diff --git a/src/routes/api/design-tokens/extract-tokens.ts b/src/routes/api/design-tokens/extract-tokens.ts
index a5f56797..66d92258 100644
--- a/src/routes/api/design-tokens/extract-tokens.ts
+++ b/src/routes/api/design-tokens/extract-tokens.ts
@@ -213,7 +213,7 @@ export type ComponentTokenResult = {
 }
 
 export function extract_design_tokens(document: Document, css: string, component: Component): ComponentTokenResult[] {
-	let selector = COMPONENT_PRESETS[component].join(', ')
+	let selector = COMPONENT_PRESETS[component]
 	let elements = Array.from(document.querySelectorAll(selector)) as Element[]
 	if (elements.length === 0) return []
 

From 671d6783e336a04f375dc31e514975d869254367 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 9 Jul 2026 14:28:00 +0000
Subject: [PATCH 8/9] Also exclude colon-delimited link classes from the button
 preset

[class*="-link"] only caught hyphen-delimited class names (e.g.
"nav-link"). Add a second :not([class*=":link"]) clause so
colon-delimited variants (e.g. "pd:link") are excluded too.
---
 src/routes/api/design-tokens/component-presets.ts   | 5 +++--
 src/routes/api/design-tokens/extract-tokens.test.ts | 7 ++++---
 2 files changed, 7 insertions(+), 5 deletions(-)

diff --git a/src/routes/api/design-tokens/component-presets.ts b/src/routes/api/design-tokens/component-presets.ts
index 6b8f442e..e04587c9 100644
--- a/src/routes/api/design-tokens/component-presets.ts
+++ b/src/routes/api/design-tokens/component-presets.ts
@@ -1,8 +1,9 @@
 export const COMPONENT_PRESETS = {
 	// [class*="-button"]/[class*="-btn"] are broad enough to also catch links styled
-	// as buttons, so exclude anything whose class also says it's a link (e.g. "nav-link").
+	// as buttons, so exclude anything whose class also says it's a link, whether
+	// hyphen-delimited ("nav-link") or colon-delimited ("pd:link").
 	button:
-		':is(button[type="submit"], input[type="button"], .button, .btn, [role="button"], [class*="-button"], [class*="-btn"]):not([class*="-link"])',
+		':is(button[type="submit"], input[type="button"], .button, .btn, [role="button"], [class*="-button"], [class*="-btn"]):not([class*="-link"]):not([class*=":link"])',
 	heading: 'h1, .h1, .heading-1'
 } as const
 
diff --git a/src/routes/api/design-tokens/extract-tokens.test.ts b/src/routes/api/design-tokens/extract-tokens.test.ts
index 2bafc245..486d4a55 100644
--- a/src/routes/api/design-tokens/extract-tokens.test.ts
+++ b/src/routes/api/design-tokens/extract-tokens.test.ts
@@ -97,11 +97,12 @@ test('finds button-like elements via the button preset, but not a plain <button>
 	expect(results).toHaveLength(7)
 })
 
-test('excludes elements whose class also says "link", even if it also looks like a button', () => {
+test('excludes elements whose class also says "link", hyphen- or colon-delimited', () => {
 	let document = make_document(`
 		<div class="primary-button">Real button</div>
-		<a class="cta-button nav-link">Link styled as a button</a>
-		<div class="primary-btn footer-link">Also a link</div>
+		<a class="cta-button nav-link">Hyphen-delimited link</a>
+		<div class="primary-btn footer-link">Also a hyphen-delimited link</div>
+		<div class="cta-btn pd:link">Colon-delimited link</div>
 	`)
 	let css = '[class*="-button"], [class*="-btn"] { color: black; }'
 

From 76b1aec5b27e89d9123f082e21b69bba41201ee0 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 9 Jul 2026 17:57:49 +0000
Subject: [PATCH 9/9] Add opt-in resolution of :root/html CSS custom properties

New independent module (src/lib/resolve-css-variables.ts) that:
- extracts the winning value of every custom property declared
  unconditionally on :root or html (same cascade rules as elsewhere -
  specificity, !important, source order - explicitly skipping anything
  nested inside a conditional at-rule like @media, since that can't be
  known without evaluating the condition)
- substitutes var(--name[, fallback]) references in an arbitrary value
  string against that map, recursively resolving chained references
  and falling back gracefully on unknown/circular references

Framework-agnostic and reusable outside this feature. Wired into
/api/design-tokens (now returns root_custom_properties alongside the
existing per-component report) and into the component-tokens debug
page as a checkbox that resolves variables client-side, instantly,
using data already in the initial response.
---
 src/lib/resolve-css-variables.test.ts         | 133 ++++++++++++++
 src/lib/resolve-css-variables.ts              | 168 ++++++++++++++++++
 .../(public)/component-tokens/+page.svelte    |  37 +++-
 src/routes/api/design-tokens/design-tokens.ts |   6 +-
 4 files changed, 342 insertions(+), 2 deletions(-)
 create mode 100644 src/lib/resolve-css-variables.test.ts
 create mode 100644 src/lib/resolve-css-variables.ts

diff --git a/src/lib/resolve-css-variables.test.ts b/src/lib/resolve-css-variables.test.ts
new file mode 100644
index 00000000..9825c1d0
--- /dev/null
+++ b/src/lib/resolve-css-variables.test.ts
@@ -0,0 +1,133 @@
+import { test, expect } from 'vitest'
+import { extract_root_custom_properties, resolve_css_value } from './resolve-css-variables'
+
+test('extracts custom properties declared on :root', () => {
+	let result = extract_root_custom_properties(':root { --primary-color: blue; --radius: 4px; }')
+
+	expect(result).toEqual(
+		new Map([
+			['--primary-color', 'blue'],
+			['--radius', '4px']
+		])
+	)
+})
+
+test('extracts custom properties declared on html', () => {
+	let result = extract_root_custom_properties('html { --primary-color: green; }')
+
+	expect(result).toEqual(new Map([['--primary-color', 'green']]))
+})
+
+test('ignores custom properties declared on any other selector', () => {
+	let result = extract_root_custom_properties('.theme-dark { --primary-color: black; }')
+
+	expect(result.size).toBe(0)
+})
+
+test('ignores custom properties nested inside a conditional at-rule', () => {
+	let result = extract_root_custom_properties(`
+		@media (prefers-color-scheme: dark) {
+			:root { --primary-color: black; }
+		}
+	`)
+
+	expect(result.size).toBe(0)
+})
+
+test('ignores non-custom-property declarations', () => {
+	let result = extract_root_custom_properties(':root { --primary-color: blue; font-size: 16px; }')
+
+	expect(result).toEqual(new Map([['--primary-color', 'blue']]))
+})
+
+test('resolves the cascade between multiple :root/html declarations of the same property', () => {
+	// html has lower specificity than :root, so :root should win regardless of source order
+	let result = extract_root_custom_properties(`
+		:root { --primary-color: blue; }
+		html { --primary-color: green; }
+	`)
+
+	expect(result.get('--primary-color')).toBe('blue')
+})
+
+test('equal specificity: the later declaration wins', () => {
+	let result = extract_root_custom_properties(`
+		:root { --primary-color: blue; }
+		:root { --primary-color: green; }
+	`)
+
+	expect(result.get('--primary-color')).toBe('green')
+})
+
+test('!important beats higher specificity', () => {
+	let result = extract_root_custom_properties(`
+		:root { --primary-color: blue !important; }
+		:root { --primary-color: green; }
+	`)
+
+	expect(result.get('--primary-color')).toBe('blue')
+})
+
+test('resolve_css_value substitutes a known variable', () => {
+	let custom_properties = new Map([['--primary-color', 'blue']])
+
+	expect(resolve_css_value('var(--primary-color)', custom_properties)).toBe('blue')
+	expect(resolve_css_value('1px solid var(--primary-color)', custom_properties)).toBe('1px solid blue')
+})
+
+test('resolve_css_value leaves an unknown variable without a fallback untouched', () => {
+	expect(resolve_css_value('var(--unknown)', new Map())).toBe('var(--unknown)')
+})
+
+test('resolve_css_value uses the fallback when the variable is unknown', () => {
+	expect(resolve_css_value('var(--unknown, red)', new Map())).toBe('red')
+})
+
+test('resolve_css_value ignores the fallback when the variable is known', () => {
+	let custom_properties = new Map([['--primary-color', 'blue']])
+
+	expect(resolve_css_value('var(--primary-color, red)', custom_properties)).toBe('blue')
+})
+
+test('resolve_css_value resolves a fallback that itself contains commas inside a function', () => {
+	expect(resolve_css_value('var(--unknown, rgb(1, 2, 3))', new Map())).toBe('rgb(1, 2, 3)')
+})
+
+test('resolve_css_value resolves chained variable references', () => {
+	let custom_properties = new Map([
+		['--space', 'var(--space-2)'],
+		['--space-2', '8px']
+	])
+
+	expect(resolve_css_value('var(--space)', custom_properties)).toBe('8px')
+})
+
+test('resolve_css_value resolves a fallback that is itself a variable reference', () => {
+	let custom_properties = new Map([['--space-2', '8px']])
+
+	expect(resolve_css_value('var(--gap, var(--space-2))', custom_properties)).toBe('8px')
+})
+
+test('resolve_css_value resolves multiple variables within one value', () => {
+	let custom_properties = new Map([
+		['--c1', 'red'],
+		['--c2', 'blue']
+	])
+
+	expect(resolve_css_value('linear-gradient(90deg, var(--c1), var(--c2))', custom_properties)).toBe(
+		'linear-gradient(90deg, red, blue)'
+	)
+})
+
+test('resolve_css_value breaks a circular reference instead of looping forever', () => {
+	let custom_properties = new Map([
+		['--a', 'var(--b)'],
+		['--b', 'var(--a)']
+	])
+
+	expect(resolve_css_value('var(--a)', custom_properties)).toBe('var(--a)')
+})
+
+test('resolve_css_value leaves values without var() untouched', () => {
+	expect(resolve_css_value('16px', new Map())).toBe('16px')
+})
diff --git a/src/lib/resolve-css-variables.ts b/src/lib/resolve-css-variables.ts
new file mode 100644
index 00000000..b4e730de
--- /dev/null
+++ b/src/lib/resolve-css-variables.ts
@@ -0,0 +1,168 @@
+import { parse, traverse, parse_selector_list, STYLE_RULE, AT_RULE, DECLARATION } from '@projectwallace/css-parser'
+import { calculateSpecificity, type Specificity } from '@projectwallace/css-analyzer'
+import { compareSpecificity } from '@projectwallace/css-analyzer/selectors'
+
+const ROOT_SELECTORS = new Set([':root', 'html'])
+
+type CustomPropertyDeclaration = {
+	value: string
+	specificity: Specificity
+	important: boolean
+	order_index: number
+}
+
+/**
+ * Resolve the winning value for every custom property declared on `:root` or `html`,
+ * ignoring anything nested inside a conditional at-rule (@media, @supports, ...) since
+ * its value can't be known without evaluating that condition. This intentionally only
+ * covers the cases we can be fully sure of - not every custom property on the page.
+ */
+export function extract_root_custom_properties(css: string): Map<string, string> {
+	let ast
+	try {
+		ast = parse(css, { parse_selectors: false })
+	} catch {
+		return new Map()
+	}
+
+	let declarations_by_property = new Map<string, CustomPropertyDeclaration[]>()
+	let order_index = 0
+	let at_rule_depth = 0
+
+	traverse(ast, {
+		enter(node) {
+			if (node.type === AT_RULE) {
+				at_rule_depth++
+				return
+			}
+
+			if (node.type !== STYLE_RULE || at_rule_depth > 0 || !node.has_prelude || !node.has_block) {
+				return
+			}
+
+			let selector_ast
+			try {
+				selector_ast = parse_selector_list(node.prelude.text)
+			} catch {
+				return
+			}
+			if (!selector_ast.has_children) return
+
+			let specificities = calculateSpecificity(selector_ast)
+			let root_specificity: Specificity | undefined
+
+			for (let i = 0; i < selector_ast.children.length; i++) {
+				if (ROOT_SELECTORS.has(selector_ast.children[i].text.trim().toLowerCase())) {
+					root_specificity = specificities[i]
+					break
+				}
+			}
+			if (!root_specificity) return
+
+			for (let child of node.block.children) {
+				if (child.type === DECLARATION && child.property.startsWith('--')) {
+					let entries = declarations_by_property.get(child.property)
+					if (!entries) {
+						entries = []
+						declarations_by_property.set(child.property, entries)
+					}
+					entries.push({
+						value: child.value?.text ?? '',
+						specificity: root_specificity,
+						important: child.is_important,
+						order_index: order_index++
+					})
+				}
+			}
+		},
+		leave(node) {
+			if (node.type === AT_RULE) {
+				at_rule_depth--
+			}
+		}
+	})
+
+	let resolved = new Map<string, string>()
+	for (let [property, entries] of declarations_by_property) {
+		let winner = entries.toSorted((a, b) => {
+			if (a.important !== b.important) return a.important ? 1 : -1
+			let specificity_comparison = compareSpecificity(a.specificity, b.specificity)
+			if (specificity_comparison !== 0) return specificity_comparison
+			return a.order_index - b.order_index
+		})[entries.length - 1]!
+		resolved.set(property, winner.value)
+	}
+
+	return resolved
+}
+
+function find_top_level_comma(text: string): number {
+	let depth = 0
+	for (let i = 0; i < text.length; i++) {
+		if (text[i] === '(') depth++
+		else if (text[i] === ')') depth--
+		else if (text[i] === ',' && depth === 0) return i
+	}
+	return -1
+}
+
+/**
+ * Substitute every var(--name) / var(--name, fallback) occurrence in `value` using
+ * `custom_properties`, recursively resolving chained references (a variable whose own
+ * value contains another var() call). Falls back to the fallback expression - resolving
+ * it too - when the variable isn't in the map, and leaves a var() call untouched when it
+ * can't be resolved at all (unknown property, no fallback, or a circular reference).
+ */
+export function resolve_css_value(
+	value: string,
+	custom_properties: Map<string, string>,
+	seen: Set<string> = new Set()
+): string {
+	let result = ''
+	let index = 0
+
+	while (index < value.length) {
+		let var_start = value.indexOf('var(', index)
+		if (var_start === -1) {
+			result += value.slice(index)
+			break
+		}
+
+		result += value.slice(index, var_start)
+
+		let depth = 0
+		let content_start = var_start + 'var('.length
+		let content_end = content_start
+		for (; content_end < value.length; content_end++) {
+			if (value[content_end] === '(') depth++
+			else if (value[content_end] === ')') {
+				if (depth === 0) break
+				depth--
+			}
+		}
+
+		if (content_end >= value.length) {
+			// Unterminated var(...) - nothing sensible to do but keep the rest verbatim.
+			result += value.slice(var_start)
+			break
+		}
+
+		let inner = value.slice(content_start, content_end)
+		let comma_index = find_top_level_comma(inner)
+		let name = (comma_index === -1 ? inner : inner.slice(0, comma_index)).trim()
+		let fallback = comma_index === -1 ? undefined : inner.slice(comma_index + 1).trim()
+
+		if (custom_properties.has(name) && !seen.has(name)) {
+			let next_seen = new Set([...seen, name])
+			result += resolve_css_value(custom_properties.get(name)!, custom_properties, next_seen)
+		} else if (fallback === undefined) {
+			result += value.slice(var_start, content_end + 1)
+		} else {
+			result += resolve_css_value(fallback, custom_properties, seen)
+		}
+
+		index = content_end + 1
+	}
+
+	return result
+}
diff --git a/src/routes/(public)/component-tokens/+page.svelte b/src/routes/(public)/component-tokens/+page.svelte
index 55b5a530..251c3e56 100644
--- a/src/routes/(public)/component-tokens/+page.svelte
+++ b/src/routes/(public)/component-tokens/+page.svelte
@@ -6,14 +6,38 @@
 	import Form from '$components/css-form/Form.svelte'
 	import PrettyJson from '$components/PrettyJson.svelte'
 	import { get_css_state } from '$lib/css-state.svelte'
+	import { resolve_css_value } from '$lib/resolve-css-variables'
 
 	let css_state = get_css_state()
 	let loading = $state(false)
 	let result: unknown = $state()
 	let error: string | undefined = $state()
+	let resolve_variables = $state(false)
 
 	let effective_url = $derived(css_state.url)
 
+	function deep_resolve_css_values(value: unknown, custom_properties: Map<string, string>): unknown {
+		if (typeof value === 'string') {
+			return resolve_css_value(value, custom_properties)
+		}
+		if (Array.isArray(value)) {
+			return value.map((item) => deep_resolve_css_values(item, custom_properties))
+		}
+		if (value && typeof value === 'object') {
+			return Object.fromEntries(
+				Object.entries(value).map(([key, item]) => [key, deep_resolve_css_values(item, custom_properties)])
+			)
+		}
+		return value
+	}
+
+	let displayed_result = $derived.by(() => {
+		if (!result || !resolve_variables) return result
+		let data = result as { root_custom_properties?: Record<string, string> }
+		let custom_properties = new Map(Object.entries(data.root_custom_properties ?? {}))
+		return deep_resolve_css_values(result, custom_properties)
+	})
+
 	async function fetch_tokens(url: string) {
 		loading = true
 		error = undefined
@@ -63,7 +87,11 @@
 	{:else if error}
 		<p class="error-msg">{error}</p>
 	{:else if result}
-		<PrettyJson json={JSON.stringify(result, null, 2)} />
+		<label class="resolve-toggle">
+			<input type="checkbox" bind:checked={resolve_variables} />
+			Resolve CSS variables declared on <code>:root</code>/<code>html</code>
+		</label>
+		<PrettyJson json={JSON.stringify(displayed_result, null, 2)} />
 	{/if}
 </Container>
 
@@ -76,4 +104,11 @@
 		color: var(--error-300);
 		font-weight: var(--font-medium);
 	}
+
+	.resolve-toggle {
+		display: flex;
+		align-items: center;
+		gap: var(--space-1);
+		margin-block-end: var(--space-3);
+	}
 </style>
diff --git a/src/routes/api/design-tokens/design-tokens.ts b/src/routes/api/design-tokens/design-tokens.ts
index 84a3b3f4..58a05e53 100644
--- a/src/routes/api/design-tokens/design-tokens.ts
+++ b/src/routes/api/design-tokens/design-tokens.ts
@@ -2,6 +2,7 @@ import { parseHTML } from 'linkedom'
 import { get_css, USER_AGENT } from '../get-css/get-css'
 import { extract_all_design_tokens } from './extract-tokens'
 import { resolve_url } from '../../../lib/resolve-url.js'
+import { extract_root_custom_properties } from '../../../lib/resolve-css-variables.js'
 
 export async function get_design_tokens(url: string) {
 	let resolved_url = resolve_url(url)
@@ -34,5 +35,8 @@ export async function get_design_tokens(url: string) {
 	let { document } = parseHTML(await html_response.text())
 	let css = css_origins.map((origin) => origin.css).join('\n')
 
-	return extract_all_design_tokens(document, css)
+	return {
+		components: extract_all_design_tokens(document, css),
+		root_custom_properties: Object.fromEntries(extract_root_custom_properties(css))
+	}
 }