admin-ui-starter-kit 0.5.0 → 0.6.2

package/.agents/skills/component-library-rules/references/components/base__css-variables.md

@@ -0,0 +1,810 @@
+---
+id: base/css-variables
+title: "CSS Variables"
+description: "Token reference for the compact structural contract that controls typography, spacing, density, controls, rows, surfaces, media, and shell dimensions."
+layer: base
+family: "Foundations"
+sourcePath: src/css/themes/shadcn.default.css + src/css/tokens/*
+examples:
+  - ScalePreview
+  - RuntimeOverrideDemo
+  - VariableExplorer
+imports:
+  - @/components/base/badge
+  - @/components/base/buttons
+  - @/components/base/cards
+  - @/components/base/display/icon-badge
+  - @/components/base/forms/fields
+  - @/components/base/item
+  - @/components/composed/data-display/metadata
+  - @/components/typography
+tags:
+  - base
+  - foundations
+  - *
+  - css
+  - variables
+  - token
+  - reference
+---
+
+# CSS Variables
+
+Token reference for the compact structural contract that controls typography, spacing, density, controls, rows, surfaces, media, and shell dimensions.
+
+**Layer:** `base`
+**Source:** `src/css/themes/shadcn.default.css + src/css/tokens/*`
+
+## Overview
+
+The package uses shadcn theme variables in `src/css/themes/shadcn.default.css`
+for color, radius, shadow, charts, sidebar, and base surfaces. Library-specific
+scale lives in `src/css/tokens/*`: text scale, spacing scale, density, shared
+action/control height, row rhythm, surface padding, media sizing, shell sizing,
+and Tailwind utility aliases that route classes like `h-control`,
+`h-action`, `gap-space-md`, `py-row-y`, `px-surface`, and `size-avatar`
+through CSS variables.
+
+Normal examples omit redundant `size` props. Consumers should tune scale from
+`:root`, a theme stylesheet, a density wrapper such as
+`[data-density='compact']`, or `<UIProvider>` defaults. Component `size` props
+are intentionally narrow where they exist (`default` / `small` for controls,
+forms, tables, badges, items, and cards). Prefer the structural variables for
+product-wide changes.
+
+## Scale behavior
+
+<Example name="ScalePreview" source={examplesSource}>
+	<Examples.ScalePreview />
+</Example>
+
+<Example name="RuntimeOverrideDemo" source={examplesSource}>
+	<Examples.RuntimeOverrideDemo />
+</Example>
+
+## Reference
+
+The explorer parses the standalone token files and lists the public structural
+contract by default. Component-family compatibility aliases are intentionally
+absent; new code must use the compact structural contract.
+
+<Example name="VariableExplorer" source={examplesSource} layout="flush">
+	<Examples.VariableExplorer />
+</Example>
+
+## Usage notes
+
+- Use root scale knobs first: `--text-scale`, `--space-scale`, and
+  `--density-scale`.
+- Use structural variables when a product needs more precision, such as
+  `--height-action`, `--height-control`, `--rounded-radius`, `--control-x`,
+  `--row-y`, `--surface-x`, `--icon`, `--avatar`, or
+  `--shell-sidebar-width`.
+- Use Tailwind aliases inside package components and app CSS instead of
+  arbitrary `var(...)` utilities: `h-control`, `text-sm`,
+  `gap-space-md`, `py-row-y`, `px-surface`, `size-icon`, `bg-card`.
+- Keep shadcn color, radius, and shadow variables in
+  `src/css/themes/shadcn.default.css`. Sizing, density, states, layout, and
+  component knobs belong in `src/css/tokens/*`.
+
+## Examples
+
+```tsx
+import { useMemo, useState, type CSSProperties, type ReactNode } from 'react';
+import { Database, Layers3, Rows3, Save, Search, Settings2, SlidersHorizontal, Sparkles, Type } from 'lucide-react';
+
+import foundationCss from '@/css/tokens/foundation.css?raw';
+import primitivesCss from '@/css/tokens/primitives.css?raw';
+import layoutCss from '@/css/tokens/layout.css?raw';
+import componentsCss from '@/css/tokens/components.css?raw';
+import { Badge } from '@/components/base/badge';
+import { Button } from '@/components/base/buttons';
+import { SmartCard } from '@/components/base/cards';
+import { IconBadge } from '@/components/base/display/icon-badge';
+import { MetadataList } from '@/components/composed/data-display/metadata';
+import { Input } from '@/components/base/forms/fields';
+import {
+	Item,
+	ItemActions,
+	ItemContent,
+	ItemDescription,
+	ItemGroup,
+	ItemMedia,
+	ItemTitle,
+} from '@/components/base/item';
+import { Text } from '@/components/typography';
+import { cn } from '@/lib/utils';
+
+type TokenGroup =
+	| 'Scale knobs'
+	| 'Fonts'
+	| 'Typography'
+	| 'Spacing'
+	| 'Shape'
+	| 'Actions'
+	| 'Controls'
+	| 'Rows'
+	| 'Surfaces'
+	| 'Media'
+	| 'Shell'
+	| 'Other';
+
+type CssVariableRecord = {
+	id: string;
+	source: string;
+	name: string;
+	value: string;
+	purpose: string;
+	scope: string;
+	group: TokenGroup;
+	utility: string;
+};
+
+const GROUP_META: Record<TokenGroup, { icon: typeof Type; description: string }> = {
+	'Scale knobs': {
+		icon: SlidersHorizontal,
+		description: 'Inherited multipliers that tighten or relax whole subtrees.',
+	},
+	Fonts: {
+		icon: Type,
+		description: 'Font stacks shared by typography and code surfaces.',
+	},
+	Typography: {
+		icon: Type,
+		description: 'Text sizes consumed by Text, Heading, Label, and text utilities.',
+	},
+	Spacing: {
+		icon: Layers3,
+		description: 'Neutral spacing scale for gaps, margins, and padding.',
+	},
+	Shape: {
+		icon: Layers3,
+		description: 'Package radius aliases that can be scoped separately from shadcn radius.',
+	},
+	Actions: {
+		icon: Save,
+		description: 'Clickable action heights for buttons, icon buttons, and command triggers.',
+	},
+	Controls: {
+		icon: Save,
+		description: 'Shared button, input, select, combobox, date picker, and trigger measurements.',
+	},
+	Rows: {
+		icon: Rows3,
+		description: 'List, command, menu, filter, activity, global-search, and table row rhythm.',
+	},
+	Surfaces: {
+		icon: Layers3,
+		description: 'Card, form section, empty state, and feature surface padding.',
+	},
+	Media: {
+		icon: Sparkles,
+		description: 'Icon and avatar sizing shared across rows, badges, metadata, and controls.',
+	},
+	Shell: {
+		icon: Database,
+		description: 'Top-level app shell height and sidebar width.',
+	},
+	Other: {
+		icon: Settings2,
+		description: 'Supporting structural variables outside the public contract.',
+	},
+};
+
+const GROUP_ORDER: TokenGroup[] = [
+	'Scale knobs',
+	'Fonts',
+	'Typography',
+	'Spacing',
+	'Shape',
+	'Actions',
+	'Controls',
+	'Rows',
+	'Surfaces',
+	'Media',
+	'Shell',
+	'Other',
+];
+
+const customScopeStyle = {
+	'--text-scale': '0.98',
+	'--space-scale': '0.9',
+	'--density-scale': '0.88',
+} as CSSProperties;
+
+const relaxedScopeStyle = {
+	'--space-scale': '1.08',
+	'--density-scale': '1.05',
+} as CSSProperties;
+
+export function ScalePreview() {
+	return (
+		<div className="grid gap-3 lg:grid-cols-3">
+			<ScaleSurface label="Default" note="Root tokens without a density override." />
+			<ScaleSurface label="Compact" note="Uses data-density='compact' on the wrapper." density="compact" />
+			<ScaleSurface label="Comfortable" note="Uses data-density='comfortable' on the wrapper." density="comfortable" />
+		</div>
+	);
+}
+
+export function RuntimeOverrideDemo() {
+	return (
+		<div className="grid gap-3 lg:grid-cols-2">
+			<SmartCard
+				title="Inherited defaults"
+				description="Components omit size props and resolve through UIProvider defaults plus the CSS variables."
+				headerEnd={<Badge variant="success">Ready</Badge>}
+			>
+				<ComponentStack />
+			</SmartCard>
+			<div style={customScopeStyle}>
+				<SmartCard
+					title="Scoped override"
+					description="A consuming app can override scale variables at :root or any wrapping element."
+					headerEnd={<Badge variant="info">Scoped</Badge>}
+				>
+					<ComponentStack />
+				</SmartCard>
+			</div>
+		</div>
+	);
+}
+
+export function VariableExplorer() {
+	const allRecords = useMemo(
+		() => parseCssVariables([
+			{ source: 'tokens/foundation.css', css: foundationCss },
+			{ source: 'tokens/primitives.css', css: primitivesCss },
+			{ source: 'tokens/layout.css', css: layoutCss },
+			{ source: 'tokens/components.css', css: componentsCss },
+		]),
+		[],
+	);
+	const records = useMemo(
+		() => allRecords.filter(isPublicStructuralVariable),
+		[allRecords],
+	);
+	const [query, setQuery] = useState('');
+	const [group, setGroup] = useState<TokenGroup | 'All'>('All');
+	const groups = useMemo(() => groupRecords(records), [records]);
+	const availableGroups = GROUP_ORDER.filter((name) => groups[name]?.length);
+	const filteredRecords = records.filter((record) => {
+		const matchesGroup = group === 'All' || record.group === group;
+		const haystack = `${record.name} ${record.scope} ${record.purpose} ${record.value} ${record.utility}`.toLowerCase();
+		return matchesGroup && haystack.includes(query.toLowerCase().trim());
+	});
+	const hasFilter = group !== 'All' || query.trim().length > 0;
+	const resetFilters = () => {
+		setQuery('');
+		setGroup('All');
+	};
+
+	return (
+		<div className="grid max-h-[44rem] gap-4 overflow-auto p-4 lg:max-h-none lg:grid-cols-[18rem_minmax(0,1fr)] lg:overflow-visible">
+			<aside className="rounded-md border border-border bg-background p-3">
+				<div className="mb-3">
+					<Text weight="semibold">Families</Text>
+					<Text size="xs" type="secondary" className="mt-1">
+						Public structural tokens only. Theme colors remain in themes/shadcn.default.css.
+					</Text>
+				</div>
+				<div className="space-y-1">
+					<VariableGroupButton
+						active={group === 'All'}
+						count={records.length}
+						icon={SlidersHorizontal}
+						label="Public tokens"
+						onClick={() => setGroup('All')}
+					/>
+					{availableGroups.map((name) => {
+						const Icon = GROUP_META[name].icon;
+						return (
+							<VariableGroupButton
+								key={name}
+								active={group === name}
+								count={groups[name].length}
+								icon={Icon}
+								label={name}
+								onClick={() => setGroup(name)}
+								tone="info"
+							/>
+						);
+					})}
+				</div>
+			</aside>
+
+			<div className="min-w-0 space-y-3">
+				<div className="flex flex-col gap-3 rounded-md border border-border bg-card px-3 py-3 md:flex-row md:items-center md:justify-between">
+					<div className="flex min-w-0 flex-1 flex-col gap-2 sm:flex-row sm:items-center">
+						<Input
+							startIcon={Search}
+							value={query}
+							onChange={(event) => setQuery(event.target.value)}
+							placeholder="Search variables, utilities, or purpose"
+							className="w-full sm:max-w-sm"
+						/>
+						{group !== 'All' && (
+							<Badge variant="secondary" className="w-fit">
+								{group}
+							</Badge>
+						)}
+					</div>
+					<div className="flex shrink-0 items-center gap-2">
+						<Text size="xs" type="secondary">
+							{filteredRecords.length} of {records.length}
+						</Text>
+						{!!hasFilter && (
+							<Button
+								type="button"
+								size="small"
+								variant="secondary"
+								buttonStyle="ghost"
+								onClick={resetFilters}
+							>
+								Clear
+							</Button>
+						)}
+					</div>
+				</div>
+
+				<div className="overflow-hidden rounded-md border border-border bg-background">
+					<div className="max-h-[42rem] overflow-auto">
+						<table className="w-full min-w-312 border-collapse text-sm">
+							<thead className="sticky top-0 z-10 bg-muted/95 text-left backdrop-blur">
+							<tr className="border-b border-border">
+								<HeaderCell className="w-48">Source</HeaderCell>
+								<HeaderCell className="w-72">Variable</HeaderCell>
+								<HeaderCell className="w-80">Default</HeaderCell>
+								<HeaderCell className="w-68">Tailwind utility</HeaderCell>
+								<HeaderCell>What it controls</HeaderCell>
+							</tr>
+						</thead>
+							<tbody>
+								{filteredRecords.map((record) => (
+									<tr key={record.id} className="border-b border-border/70 transition-colors hover:bg-muted/25 last:border-b-0">
+										<BodyCell>
+											<div className="space-y-1">
+												<Text size="inherit" type="secondary">{record.source}</Text>
+												<Badge variant="secondary">{record.scope}</Badge>
+											</div>
+										</BodyCell>
+										<BodyCell>
+											<code className="rounded-sm bg-muted/70 px-1.5 py-0.5 font-mono text-sm text-foreground">{record.name}</code>
+										</BodyCell>
+										<BodyCell>
+											<code className="font-mono text-sm text-muted-foreground">{record.value}</code>
+										</BodyCell>
+										<BodyCell>
+											<Text size="inherit" type={record.utility === 'Runtime variable' ? 'secondary' : undefined}>
+												{record.utility}
+											</Text>
+										</BodyCell>
+										<BodyCell>
+											<Text size="inherit" type="secondary">{record.purpose}</Text>
+										</BodyCell>
+									</tr>
+								))}
+							</tbody>
+						</table>
+						{filteredRecords.length === 0 && (
+							<div className="px-4 py-8 text-center">
+								<Text type="secondary">No variables match the current filters.</Text>
+							</div>
+						)}
+					</div>
+				</div>
+			</div>
+		</div>
+	);
+}
+
+export const VariableReference = VariableExplorer;
+
+function VariableGroupButton({
+	active,
+	count,
+	icon: Icon,
+	label,
+	onClick,
+	tone = 'muted',
+}: {
+	active: boolean;
+	count: number;
+	icon: typeof Type;
+	label: string;
+	onClick: () => void;
+	tone?: 'info' | 'muted';
+}) {
+	return (
+		<Button
+			type="button"
+			variant="secondary"
+			buttonStyle="ghost"
+			aria-pressed={active}
+			onClick={onClick}
+			className={cn(
+				'h-auto min-h-0 w-full justify-start rounded-md px-2 py-1.5 text-left shadow-none',
+				active ? 'bg-muted text-foreground' : 'text-muted-foreground hover:bg-muted/70 hover:text-foreground',
+			)}
+		>
+			<IconBadge icon={Icon} size="small" tone={tone} />
+			<span className="min-w-0 flex-1">
+				<span className="block truncate text-sm font-medium leading-5">{label}</span>
+			</span>
+			<span className="text-xxs tabular-nums text-muted-foreground">{count}</span>
+		</Button>
+	);
+}
+
+function ScaleSurface({
+	label,
+	note,
+	density,
+}: {
+	label: string;
+	note: string;
+	density?: 'compact' | 'comfortable';
+}) {
+	return (
+		<div
+			data-density={density}
+			className="rounded-md border border-border bg-background px-surface-sm py-surface-sm"
+		>
+			<div className="mb-3 flex items-center justify-between gap-space-md">
+				<div>
+					<Text weight="semibold">{label}</Text>
+					<Text size="xs" type="secondary">{note}</Text>
+				</div>
+				<Badge variant={density === 'compact' ? 'warning' : density === 'comfortable' ? 'info' : 'secondary'}>
+					{density ?? 'root'}
+				</Badge>
+			</div>
+			<ComponentStack />
+		</div>
+	);
+}
+
+function ComponentStack() {
+	return (
+		<div className="space-y-space-lg">
+			<div className="flex flex-wrap items-center gap-space-md">
+				<Button icon={Save}>Save</Button>
+				<Button variant="secondary" buttonStyle="outline">Preview</Button>
+				<Badge variant="success" dot>Live</Badge>
+			</div>
+			<Input startIcon={Search} placeholder="Search customers" />
+			<ItemGroup>
+				<Item>
+					<ItemMedia variant="icon">
+						<Database />
+					</ItemMedia>
+					<ItemContent>
+						<ItemTitle>Customer profile</ItemTitle>
+						<ItemDescription>Rows, media, metadata, and actions share the display and row scales.</ItemDescription>
+					</ItemContent>
+					<ItemActions>
+						<Badge variant="info">Synced</Badge>
+					</ItemActions>
+				</Item>
+			</ItemGroup>
+			<div style={relaxedScopeStyle} className="rounded-md border border-dashed border-border px-3 py-2">
+				<MetadataList
+					layout="horizontal"
+					items={[
+						{ label: 'Scale', value: 'local' },
+						{ label: 'Rows', value: 'loose' },
+						{ label: 'Display', value: '1.04x' },
+					]}
+				/>
+			</div>
+		</div>
+	);
+}
+
+function HeaderCell({ children, className }: { children: string; className?: string }) {
+	return (
+		<th className={cn('px-surface py-row-y text-xs font-semibold uppercase tracking-wide text-muted-foreground', className)}>
+			{children}
+		</th>
+	);
+}
+
+function BodyCell({ children }: { children: ReactNode }) {
+	return <td className="whitespace-normal break-words px-surface py-row-y-lg align-top">{children}</td>;
+}
+
+function parseCssVariables(sources: { source: string; css: string }[]): CssVariableRecord[] {
+	return sources.flatMap(({ source, css }) => parseCssSource(source, css));
+}
+
+function parseCssSource(source: string, css: string): CssVariableRecord[] {
+	const records: CssVariableRecord[] = [];
+	const contextStack: string[] = [];
+	let activeComment: string | null = null;
+	let pendingComment: string[] | null = null;
+
+	css.split('\n').forEach((line, lineIndex) => {
+		const trimmed = line.trim();
+
+		if (pendingComment) {
+			pendingComment.push(cleanCommentLine(trimmed));
+			if (trimmed.includes('*/')) {
+				activeComment = normalizeComment(pendingComment.join(' '));
+				pendingComment = null;
+			}
+			return;
+		}
+
+		if (trimmed.startsWith('/*')) {
+			if (trimmed.includes('*/')) {
+				activeComment = normalizeComment(cleanCommentLine(trimmed));
+			} else {
+				pendingComment = [cleanCommentLine(trimmed)];
+			}
+			return;
+		}
+
+		const openContext = getOpenContext(trimmed);
+		if (openContext) {
+			contextStack.push(openContext);
+			activeComment = null;
+		}
+
+		const variable = trimmed.match(/^(--[a-zA-Z0-9-]+):\s*(.+);$/);
+		if (variable) {
+			const [, name, value] = variable;
+			const scope = resolveScope(contextStack);
+			records.push({
+				id: `${source}-${lineIndex}-${scope}-${name}`,
+				source,
+				name,
+				value,
+				purpose: activeComment ?? inferPurpose(name),
+				scope,
+				group: inferGroup(name, scope),
+				utility: inferUtility(name, scope),
+			});
+			activeComment = null;
+		} else if (trimmed && !trimmed.startsWith('*') && !trimmed.endsWith('{') && trimmed !== '}') {
+			activeComment = null;
+		}
+
+		if (trimmed === '}') {
+			contextStack.pop();
+		}
+	});
+
+	return records;
+}
+
+function getOpenContext(line: string): string | null {
+	const utility = line.match(/^@utility\s+([a-zA-Z0-9-]+)\s*\{/);
+	if (utility) return `@utility ${utility[1]}`;
+	if (line.startsWith('@theme inline')) return '@theme inline';
+	if (line.startsWith(':root')) return ':root';
+	const density = line.match(/^\[data-density=['"]([^'"]+)['"]\]\s*\{/);
+	if (density) return `[data-density='${density[1]}']`;
+	if (line.startsWith('@layer ')) return line.replace(/\s*\{$/, '');
+	return null;
+}
+
+function resolveScope(stack: string[]): string {
+	const meaningful = [...stack].reverse().find((item) => !item.startsWith('@layer'));
+	return meaningful ?? 'global';
+}
+
+function cleanCommentLine(line: string): string {
+	return line
+		.replace(/^\/\*/, '')
+		.replace(/\*\/$/, '')
+		.replace(/^\s*\*\s?/, '')
+		.trim();
+}
+
+function normalizeComment(comment: string): string {
+	return comment.replace(/\s+/g, ' ').trim();
+}
+
+function groupRecords(records: CssVariableRecord[]): Record<TokenGroup, CssVariableRecord[]> {
+	return GROUP_ORDER.reduce((acc, group) => {
+		acc[group] = records.filter((record) => record.group === group);
+		return acc;
+	}, {} as Record<TokenGroup, CssVariableRecord[]>);
+}
+
+function inferGroup(name: string, scope: string): TokenGroup {
+	if (name.includes('scale')) return 'Scale knobs';
+	if (name.startsWith('--font-')) return 'Fonts';
+	if (name.startsWith('--text-')) return 'Typography';
+	if (name.startsWith('--space-')) return 'Spacing';
+	if (name.startsWith('--rounded-')) return 'Shape';
+	if (name.startsWith('--height-action')) return 'Actions';
+	if (name.startsWith('--height-control')) return 'Controls';
+	if (name.startsWith('--control-')) return 'Controls';
+	if (name.startsWith('--row-')) return 'Rows';
+	if (name.startsWith('--surface-')) return 'Surfaces';
+	if (name.startsWith('--icon-') || name.startsWith('--avatar-')) return 'Media';
+	if (name.startsWith('--shell-')) return 'Shell';
+	if (scope === '@theme inline' && name.startsWith('--spacing-space-')) return 'Spacing';
+	if (scope === '@theme inline' && name.startsWith('--radius-radius')) return 'Shape';
+	if (scope === '@theme inline' && name.startsWith('--spacing-action-')) return 'Actions';
+	if (scope === '@theme inline' && name.startsWith('--spacing-control-')) return 'Controls';
+	if (scope === '@theme inline' && name.startsWith('--spacing-row-')) return 'Rows';
+	if (scope === '@theme inline' && name.startsWith('--spacing-surface-')) return 'Surfaces';
+	if (scope === '@theme inline' && (name.startsWith('--spacing-icon-') || name.startsWith('--spacing-avatar-'))) return 'Media';
+	if (scope === '@theme inline' && name.startsWith('--spacing-shell-')) return 'Shell';
+	return 'Other';
+}
+
+function inferUtility(name: string, scope: string): string {
+	if (name.startsWith('--font-')) return name.replace('--font-', 'font-');
+	if (name.startsWith('--text-') && !name.includes('--line-height')) return name.replace('--text-', 'text-');
+	if (name.startsWith('--text-') && name.includes('--line-height')) return 'Paired line-height';
+	if (name.startsWith('--spacing-')) return `spacing key: ${name.replace('--spacing-', '')}`;
+	if (name.startsWith('--radius-')) return name.replace('--radius-', 'rounded-');
+	if (name.startsWith('--color-')) return `color key: ${name.replace('--color-', '')}`;
+	if (scope.startsWith('@utility')) return scope;
+	return 'Runtime variable';
+}
+
+const PUBLIC_ROOT_VARIABLES = new Set([
+	'--text-scale',
+	'--space-scale',
+	'--density-scale',
+	'--rounded-radius-sm',
+	'--rounded-radius',
+	'--rounded-radius-lg',
+	'--height-action-xs',
+	'--height-action-sm',
+	'--height-action',
+	'--height-action-lg',
+	'--height-control-sm',
+	'--height-control',
+	'--height-control-lg',
+	'--space-2xs',
+	'--space-xs',
+	'--space-sm',
+	'--space-md',
+	'--space-lg',
+	'--space-xl',
+	'--space-2xl',
+	'--control-height-sm',
+	'--control-height',
+	'--control-height-lg',
+	'--control-x-sm',
+	'--control-x',
+	'--control-gap-small',
+	'--control-gap',
+	'--control-y-offset',
+	'--row-x',
+	'--row-y-sm',
+	'--row-y',
+	'--row-y-lg',
+	'--surface-x-sm',
+	'--surface-x',
+	'--surface-y-sm',
+	'--surface-y',
+	'--icon-sm',
+	'--icon',
+	'--icon-lg',
+	'--avatar-sm',
+	'--avatar',
+	'--avatar-lg',
+	'--upload-avatar-small',
+	'--upload-avatar',
+	'--upload-avatar-large',
+	'--shell-header-height',
+	'--shell-header-control-size',
+	'--shell-sidebar-width',
+	'--shell-sidebar-width-expanded',
+	'--shell-sidebar-width-current',
+	'--popover-content-pad',
+]);
+
+const PUBLIC_THEME_VARIABLES = new Set([
+	'--font-heading',
+	'--font-sans',
+	'--font-mono',
+	'--text-xxs',
+	'--text-xs',
+	'--text-sm',
+	'--text-base',
+	'--text-lg',
+	'--text-xl',
+	'--text-2xl',
+	'--text-3xl',
+	'--text-4xl',
+	'--text-5xl',
+	'--spacing-space-2xs',
+	'--spacing-space-xs',
+	'--spacing-space-sm',
+	'--spacing-space-md',
+	'--spacing-space-lg',
+	'--spacing-space-xl',
+	'--spacing-space-2xl',
+	'--radius-radius-sm',
+	'--radius-radius',
+	'--radius-radius-lg',
+	'--spacing-action-xs',
+	'--spacing-action-sm',
+	'--spacing-action',
+	'--spacing-action-lg',
+	'--spacing-row-x',
+	'--spacing-row-y-sm',
+	'--spacing-row-y',
+	'--spacing-row-y-lg',
+	'--spacing-surface-sm',
+	'--spacing-surface',
+	'--spacing-shell-header',
+	'--spacing-shell-header-control',
+	'--spacing-shell-sidebar',
+]);
+
+const PUBLIC_TOKEN_SOURCES = new Set([
+	'tokens/foundation.css',
+	'tokens/primitives.css',
+	'tokens/layout.css',
+	'tokens/components.css',
+]);
+
+function isPublicStructuralVariable(record: CssVariableRecord): boolean {
+	if (!PUBLIC_TOKEN_SOURCES.has(record.source)) return false;
+	if (record.scope === ':root') return PUBLIC_ROOT_VARIABLES.has(record.name);
+	if (record.scope === '@theme inline') return PUBLIC_THEME_VARIABLES.has(record.name);
+	return false;
+}
+
+function inferPurpose(name: string): string {
+	if (name.startsWith('--color-')) return `Tailwind color alias for ${name.replace('--color-', '').replace(/-/g, ' ')}.`;
+	if (name.startsWith('--shadow-')) return `Shadow elevation token ${name.replace('--shadow-', '')}.`;
+	if (name === '--radius') return 'Central shadcn radius token that derived radius utilities alias.';
+	if (name.startsWith('--radius-')) return `Derived radius token for rounded-${name.replace('--radius-', '')}.`;
+	if (name.startsWith('--sidebar-')) return `Sidebar theme token for ${name.replace('--sidebar-', '').replace(/-/g, ' ')}.`;
+	if (name.startsWith('--chart-')) return `Chart palette token for multi-series charts, not semantic status color.`;
+	if (name.startsWith('--inverse-')) return `Inverse-surface token for dark or artwork-backed surfaces.`;
+	if (name.endsWith('-foreground')) return `Readable foreground token paired with ${name.replace(/^--/, '').replace(/-foreground$/, '').replace(/-/g, ' ')}.`;
+	if (isThemePaletteVariable(name)) return `Shadcn theme color token for ${name.replace(/^--/, '').replace(/-/g, ' ')}.`;
+	return `Controls ${name.replace(/^--/, '').replace(/-/g, ' ')}.`;
+}
+
+function isThemePaletteVariable(name: string): boolean {
+	return [
+		'--background',
+		'--foreground',
+		'--card',
+		'--card-foreground',
+		'--popover',
+		'--popover-foreground',
+		'--primary',
+		'--primary-foreground',
+		'--secondary',
+		'--secondary-foreground',
+		'--muted',
+		'--muted-foreground',
+		'--accent',
+		'--accent-foreground',
+		'--destructive',
+		'--destructive-foreground',
+		'--success',
+		'--success-foreground',
+		'--info',
+		'--info-foreground',
+		'--warning',
+		'--warning-foreground',
+		'--error',
+		'--error-foreground',
+		'--main',
+		'--main-foreground',
+		'--border',
+		'--input',
+		'--ring',
+	].includes(name) || name.startsWith('--inverse-') || name.startsWith('--sidebar-') || name.startsWith('--chart-');
+}
+```
+
+## Example exports
+
+- `ScalePreview`
+- `RuntimeOverrideDemo`
+- `VariableExplorer`
+