diff --git a/.changeset/theme-runtime-improvements.md b/.changeset/theme-runtime-improvements.md
new file mode 100644
index 000000000..15615ac41
--- /dev/null
+++ b/.changeset/theme-runtime-improvements.md
@@ -0,0 +1,14 @@
+---
+"@tiny-design/react": minor
+"@tiny-design/tokens": minor
+---
+
+Theme runtime and token registry improvements:
+
+- **Fix:** `base.css` now emits light defaults under `:root, [data-tiny-theme='light']`, so a scoped `<ConfigProvider theme="light">` inside a dark root flips correctly.
+- **New:** `getThemeStylesheet(theme, { selector? })` exported from `@tiny-design/tokens/resolve-theme` (and re-exported from `@tiny-design/react`) returns a CSS string for SSR injection to avoid theme FOUC.
+- **New:** `useActiveTheme()` exported from `@tiny-design/react` returns the effective `{ mode, themeConfig }` for the current subtree.
+- **New:** `useTheme()` is now context-aware (respects the nearest `ConfigProvider`'s theme) and accepts `{ initialMode }` for SSR hydration.
+- **New:** Typed token key unions in `dist/registry.d.ts` (`PrimitiveTokenKey`, `SemanticTokenKey`, `ComponentTokenKey`, `TokenKey`) and a `TypedThemeDocument` in `dist/presets.d.ts` for autocompletion.
+- **New:** Additive primitive token layer under `source/primitive/` with initial brand color scale and spacing scale.
+- **Build:** Token registry validation now checks `fallback` targets and `$type` vs `$value` compatibility.
diff --git a/packages/react/src/_utils/theme-store.ts b/packages/react/src/_utils/theme-store.ts
new file mode 100644
index 000000000..f2571c06a
--- /dev/null
+++ b/packages/react/src/_utils/theme-store.ts
@@ -0,0 +1,136 @@
+import type { ThemeMode } from '../config-provider/config-context';
+
+const STORAGE_KEY = 'ty-theme';
+const THEME_ATTR = 'data-tiny-theme';
+
+function readDomTheme(): ThemeMode | null {
+  if (typeof document === 'undefined') return null;
+  const value = document.documentElement.getAttribute(THEME_ATTR);
+  return value === 'light' || value === 'dark' || value === 'system' ? value : null;
+}
+
+function readStoredTheme(): ThemeMode | null {
+  if (typeof localStorage === 'undefined') return null;
+  const value = localStorage.getItem(STORAGE_KEY);
+  return value === 'light' || value === 'dark' || value === 'system' ? value : null;
+}
+
+function readInitialTheme(): ThemeMode {
+  return readDomTheme() ?? readStoredTheme() ?? 'light';
+}
+
+function applyTheme(mode: ThemeMode): void {
+  if (typeof document === 'undefined') return;
+  document.documentElement.setAttribute(THEME_ATTR, mode);
+}
+
+export function getSystemTheme(): 'light' | 'dark' {
+  if (typeof window === 'undefined') return 'light';
+  return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+}
+
+let currentMode: ThemeMode = readInitialTheme();
+const listeners = new Set<() => void>();
+let initialized = false;
+
+function emit(): void {
+  listeners.forEach((cb) => cb());
+}
+
+function ensureInitialized(): void {
+  if (initialized) return;
+  initialized = true;
+
+  // Respect any mode that's already on the DOM (e.g. written by an inline
+  // pre-hydration script) before we start broadcasting.
+  const dom = readDomTheme();
+  if (dom) {
+    currentMode = dom;
+  } else if (typeof document !== 'undefined') {
+    applyTheme(currentMode);
+  }
+
+  if (typeof window === 'undefined') return;
+
+  if (typeof window.matchMedia === 'function') {
+    const mql = window.matchMedia('(prefers-color-scheme: dark)');
+    const handler = () => {
+      if (currentMode === 'system') emit();
+    };
+    if (typeof mql.addEventListener === 'function') {
+      mql.addEventListener('change', handler);
+    } else if (typeof (mql as MediaQueryList).addListener === 'function') {
+      (mql as MediaQueryList).addListener(handler);
+    }
+  }
+
+  window.addEventListener('storage', (event) => {
+    if (event.key !== STORAGE_KEY) return;
+    const next =
+      event.newValue === 'light' || event.newValue === 'dark' || event.newValue === 'system'
+        ? event.newValue
+        : 'light';
+    currentMode = next;
+    applyTheme(currentMode);
+    emit();
+  });
+}
+
+export const themeStore = {
+  subscribe(cb: () => void): () => void {
+    ensureInitialized();
+    const syncFromDom = () => {
+      const dom = readDomTheme();
+      if (dom && dom !== currentMode) {
+        currentMode = dom;
+        cb();
+      }
+    };
+    listeners.add(cb);
+    syncFromDom();
+
+    const observer =
+      typeof MutationObserver !== 'undefined' && typeof document !== 'undefined'
+        ? new MutationObserver(syncFromDom)
+        : null;
+    observer?.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: [THEME_ATTR],
+    });
+
+    return () => {
+      listeners.delete(cb);
+      observer?.disconnect();
+    };
+  },
+  getSnapshot(): ThemeMode {
+    return readDomTheme() ?? currentMode;
+  },
+  getServerSnapshot(): ThemeMode {
+    return 'light';
+  },
+  setMode(next: ThemeMode): void {
+    ensureInitialized();
+    currentMode = next;
+    if (typeof localStorage !== 'undefined') {
+      try {
+        localStorage.setItem(STORAGE_KEY, next);
+      } catch {
+        /* ignore quota/privacy errors */
+      }
+    }
+    applyTheme(next);
+    emit();
+  },
+  /**
+   * Initialize the store with an explicit mode before any render. Useful for
+   * SSR hydration when the initial mode comes from a cookie or inline script.
+   */
+  hydrate(next: ThemeMode): void {
+    currentMode = next;
+    if (typeof document !== 'undefined') {
+      applyTheme(next);
+    }
+    initialized = true;
+  },
+};
diff --git a/packages/react/src/_utils/use-theme.ts b/packages/react/src/_utils/use-theme.ts
index 56bde0b44..a365409e5 100644
--- a/packages/react/src/_utils/use-theme.ts
+++ b/packages/react/src/_utils/use-theme.ts
@@ -1,137 +1,39 @@
-import { useSyncExternalStore, useCallback } from 'react';
+import { useSyncExternalStore, useCallback, useContext } from 'react';
 import type { ThemeMode } from '../config-provider/config-context';
+import { ConfigContext } from '../config-provider/config-context';
+import { getSystemTheme, themeStore } from './theme-store';
 
-const STORAGE_KEY = 'ty-theme';
-const THEME_ATTR = 'data-tiny-theme';
-
-function getSystemTheme(): 'light' | 'dark' {
-  if (typeof window === 'undefined') return 'light';
-  return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
-}
-
-function applyTheme(mode: ThemeMode): void {
-  if (typeof document === 'undefined') return;
-  document.documentElement.setAttribute(THEME_ATTR, mode);
-}
-
-function readDomTheme(): ThemeMode | null {
-  if (typeof document === 'undefined') return null;
-  const value = document.documentElement.getAttribute(THEME_ATTR);
-  return value === 'light' || value === 'dark' || value === 'system' ? value : null;
-}
-
-function readStoredTheme(): ThemeMode {
-  if (typeof localStorage === 'undefined') return 'light';
-  return (localStorage.getItem(STORAGE_KEY) as ThemeMode) || 'light';
-}
-
-function readInitialTheme(): ThemeMode {
-  return readDomTheme() ?? readStoredTheme();
-}
-
-// ---- Shared store ----
-let currentMode: ThemeMode = readInitialTheme();
-const listeners = new Set<() => void>();
-
-function getSnapshot(): ThemeMode {
-  return readDomTheme() ?? currentMode;
-}
-
-function getServerSnapshot(): ThemeMode {
-  return 'light';
-}
-
-function subscribe(cb: () => void): () => void {
-  const syncFromDom = () => {
-    const domTheme = readDomTheme();
-
-    if (domTheme && domTheme !== currentMode) {
-      currentMode = domTheme;
-      cb();
-    }
-  };
-
-  listeners.add(cb);
-  syncFromDom();
-
-  const observer =
-    typeof MutationObserver !== 'undefined' && typeof document !== 'undefined'
-      ? new MutationObserver(() => {
-          syncFromDom();
-        })
-      : null;
-
-  observer?.observe(document.documentElement, {
-    attributes: true,
-    attributeFilter: [THEME_ATTR],
-  });
-
-  return () => {
-    listeners.delete(cb);
-    observer?.disconnect();
-  };
-}
-
-function setThemeMode(next: ThemeMode): void {
-  currentMode = next;
-  if (typeof localStorage !== 'undefined') {
-    localStorage.setItem(STORAGE_KEY, next);
-  }
-  applyTheme(next);
-  listeners.forEach((cb) => cb());
+export interface UseThemeOptions {
+  /**
+   * Initial mode to hydrate the store with. Use on first mount for SSR to
+   * align with the mode written to the document by a pre-hydration script.
+   */
+  initialMode?: ThemeMode;
 }
 
-function emit(): void {
-  listeners.forEach((cb) => cb());
-}
-
-// Listen for system preference changes at module level
-if (typeof document !== 'undefined') {
-  applyTheme(currentMode);
-}
-
-if (typeof window !== 'undefined') {
-  if (typeof window.matchMedia === 'function') {
-    const mediaQueryList = window.matchMedia('(prefers-color-scheme: dark)');
-    const handleSystemThemeChange = () => {
-      if (currentMode === 'system') {
-        emit();
-      }
-    };
-
-    if (typeof mediaQueryList.addEventListener === 'function') {
-      mediaQueryList.addEventListener('change', handleSystemThemeChange);
-    } else if (typeof mediaQueryList.addListener === 'function') {
-      mediaQueryList.addListener(handleSystemThemeChange);
-    }
+export function useTheme(options?: UseThemeOptions) {
+  if (options?.initialMode) {
+    themeStore.hydrate(options.initialMode);
   }
 
-  window.addEventListener('storage', (event) => {
-    if (event.key !== STORAGE_KEY) {
-      return;
-    }
-
-    currentMode = event.newValue === 'light' || event.newValue === 'dark' || event.newValue === 'system'
-      ? event.newValue
-      : 'light';
-    applyTheme(currentMode);
-    emit();
-  });
-}
-
-// ---- Hook ----
-export function useTheme() {
-  const mode = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+  const contextMode = useContext(ConfigContext).theme;
+  const storeMode = useSyncExternalStore(
+    themeStore.subscribe,
+    themeStore.getSnapshot,
+    themeStore.getServerSnapshot
+  );
+  const mode: ThemeMode = contextMode ?? storeMode;
 
   const resolvedTheme: 'light' | 'dark' = mode === 'system' ? getSystemTheme() : mode;
 
-  const setMode = useCallback((newMode: ThemeMode) => {
-    setThemeMode(newMode);
+  const setMode = useCallback((next: ThemeMode) => {
+    themeStore.setMode(next);
   }, []);
 
   const toggle = useCallback(() => {
-    const resolved = currentMode === 'system' ? getSystemTheme() : currentMode;
-    setThemeMode(resolved === 'light' ? 'dark' : 'light');
+    const active = themeStore.getSnapshot();
+    const resolved = active === 'system' ? getSystemTheme() : active;
+    themeStore.setMode(resolved === 'light' ? 'dark' : 'light');
   }, []);
 
   return { mode, resolvedTheme, setMode, toggle };
diff --git a/packages/react/src/config-provider/config-context.tsx b/packages/react/src/config-provider/config-context.tsx
index bf9db6ae6..48d688033 100644
--- a/packages/react/src/config-provider/config-context.tsx
+++ b/packages/react/src/config-provider/config-context.tsx
@@ -3,6 +3,7 @@ import { SizeType } from '../_utils/props';
 import { SpaceSize } from '../space/types';
 import { Locale } from '../locale/types';
 import { SkeletonAnimation } from '../skeleton/types';
+import { themeStore } from '../_utils/theme-store';
 import { ThemeConfig } from './token-utils';
 
 export type ThemeMode = 'light' | 'dark' | 'system';
@@ -35,3 +36,30 @@ export const ConfigContext = React.createContext<ConfigContextProps>({
 export function useConfig(): ConfigContextProps {
   return React.useContext(ConfigContext);
 }
+
+/**
+ * Returns the theme that is actually taking effect in this part of the tree.
+ *
+ * Resolution order:
+ *   1. The nearest ConfigProvider's `theme` prop (scoped override)
+ *   2. The document-level theme store driven by `useTheme().setMode(...)`
+ *
+ * `themeConfig` is the full ThemeConfig object when the nearest provider was
+ * configured with one; otherwise undefined.
+ */
+export function useActiveTheme(): {
+  mode: ThemeMode | undefined;
+  themeConfig: ThemeConfig | undefined;
+} {
+  const ctx = React.useContext(ConfigContext);
+  const storeSnapshot = React.useSyncExternalStore(
+    themeStore.subscribe,
+    themeStore.getSnapshot,
+    themeStore.getServerSnapshot
+  );
+
+  return {
+    mode: ctx.theme ?? storeSnapshot,
+    themeConfig: ctx.themeConfig,
+  };
+}
diff --git a/packages/react/src/index.ts b/packages/react/src/index.ts
index aaaa8525a..55860a33c 100755
--- a/packages/react/src/index.ts
+++ b/packages/react/src/index.ts
@@ -180,4 +180,6 @@ export type * from './waterfall';
 
 export { useLocale } from './_utils/use-locale';
 export { useTheme } from './_utils/use-theme';
+export { useActiveTheme } from './config-provider/config-context';
+export { getThemeStylesheet } from '@tiny-design/tokens/resolve-theme';
 export type { ThemeMode } from './config-provider/config-context';
diff --git a/packages/tokens/runtime/resolve-theme.cjs b/packages/tokens/runtime/resolve-theme.cjs
index 6c11f52a9..54816341b 100644
--- a/packages/tokens/runtime/resolve-theme.cjs
+++ b/packages/tokens/runtime/resolve-theme.cjs
@@ -5,4 +5,5 @@ const runtime = require('./theme-runtime.cjs');
 module.exports = {
   resolveTheme: runtime.resolveTheme,
   tokenKeyToCssVar: runtime.tokenKeyToCssVar,
+  getThemeStylesheet: runtime.getThemeStylesheet,
 };
diff --git a/packages/tokens/runtime/resolve-theme.d.ts b/packages/tokens/runtime/resolve-theme.d.ts
index fe9c985be..71244a74d 100644
--- a/packages/tokens/runtime/resolve-theme.d.ts
+++ b/packages/tokens/runtime/resolve-theme.d.ts
@@ -40,19 +40,35 @@ export interface ResolvedThemeResult {
   normalizedDocument: ThemeConfig;
 }
 
+export interface ResolveThemeOptions {
+  strict?: boolean;
+  presets?: Record<string, ThemeDocument>;
+  registry?: {
+    tokens: Array<{
+      key: string;
+      category: 'semantic' | 'component' | 'primitive';
+      status: 'active' | 'deprecated' | 'internal';
+      defaultValue: string | number;
+    }>;
+  };
+}
+
+export interface GetThemeStylesheetOptions extends ResolveThemeOptions {
+  /** CSS selector prefix for the rule. Defaults to `:root`. */
+  selector?: string;
+}
+
 export function tokenKeyToCssVar(key: string): string;
 export function resolveTheme(
   input: ThemeConfig | ThemeDocument,
-  options?: {
-    strict?: boolean;
-    presets?: Record<string, ThemeDocument>;
-    registry?: {
-      tokens: Array<{
-        key: string;
-        category: 'semantic' | 'component' | 'primitive';
-        status: 'active' | 'deprecated' | 'internal';
-        defaultValue: string | number;
-      }>;
-    };
-  }
+  options?: ResolveThemeOptions
 ): ResolvedThemeResult;
+/**
+ * Returns a CSS string that applies the theme's overrides under the given
+ * selector. Safe to inline in a server-rendered `<style>` tag before hydration
+ * to avoid theme FOUC.
+ */
+export function getThemeStylesheet(
+  input: ThemeConfig | ThemeDocument,
+  options?: GetThemeStylesheetOptions
+): string;
diff --git a/packages/tokens/runtime/resolve-theme.mjs b/packages/tokens/runtime/resolve-theme.mjs
index 9b2ec0fac..297ccfa96 100644
--- a/packages/tokens/runtime/resolve-theme.mjs
+++ b/packages/tokens/runtime/resolve-theme.mjs
@@ -1 +1 @@
-export { resolveTheme, tokenKeyToCssVar } from './theme-runtime.mjs';
+export { getThemeStylesheet, resolveTheme, tokenKeyToCssVar } from './theme-runtime.mjs';
diff --git a/packages/tokens/runtime/theme-runtime.cjs b/packages/tokens/runtime/theme-runtime.cjs
index 0f189abd8..e0a60f3e2 100644
--- a/packages/tokens/runtime/theme-runtime.cjs
+++ b/packages/tokens/runtime/theme-runtime.cjs
@@ -361,8 +361,44 @@ function resolveTheme(input, options) {
   };
 }
 
+function escapeAttr(value) {
+  return String(value).replace(/"/g, '\\"');
+}
+
+function getThemeStylesheet(input, options) {
+  const opts = options || {};
+  const selector = opts.selector || ':root';
+  const result = resolveTheme(input, opts);
+  const mode = result.mode;
+
+  const overrides = [];
+  const merged = result.normalizedDocument && result.normalizedDocument.tokens;
+  const semanticOverrides = (merged && merged.semantic) || {};
+  const componentOverrides = (merged && merged.components) || {};
+
+  for (const [key, value] of Object.entries(semanticOverrides)) {
+    overrides.push(`  ${tokenKeyToCssVar(key)}: ${value};`);
+  }
+  for (const [key, value] of Object.entries(componentOverrides)) {
+    overrides.push(`  ${tokenKeyToCssVar(key)}: ${value};`);
+  }
+
+  if (mode) {
+    overrides.push(`  color-scheme: ${mode === 'system' ? 'light dark' : mode};`);
+  }
+
+  if (overrides.length === 0 && !mode) {
+    return '';
+  }
+
+  const attr = mode ? `[data-tiny-theme="${escapeAttr(mode)}"]` : '';
+  const lines = [`${selector}${attr} {`, ...overrides, '}'];
+  return lines.join('\n') + '\n';
+}
+
 module.exports = {
   defaultPresets,
+  getThemeStylesheet,
   mergeThemeDocuments,
   normalizeThemeInput,
   resolveTheme,
diff --git a/packages/tokens/runtime/theme-runtime.mjs b/packages/tokens/runtime/theme-runtime.mjs
index 9843909ff..6adac3415 100644
--- a/packages/tokens/runtime/theme-runtime.mjs
+++ b/packages/tokens/runtime/theme-runtime.mjs
@@ -349,8 +349,53 @@ function resolveTheme(input, options) {
   };
 }
 
+function escapeAttr(value) {
+  return String(value).replace(/"/g, '\\"');
+}
+
+/**
+ * Build a CSS stylesheet string that, when injected before hydration, applies
+ * the given theme without FOUC. Only overrides (not the full registry) are
+ * emitted — base.css already contains default values.
+ */
+function getThemeStylesheet(input, options) {
+  const opts = options || {};
+  const selector = opts.selector || ':root';
+  const result = resolveTheme(input, opts);
+  const mode = result.mode;
+
+  const lines = [];
+  const overrides = [];
+
+  const merged = result.normalizedDocument && result.normalizedDocument.tokens;
+  const semanticOverrides = (merged && merged.semantic) || {};
+  const componentOverrides = (merged && merged.components) || {};
+
+  for (const [key, value] of Object.entries(semanticOverrides)) {
+    overrides.push(`  ${tokenKeyToCssVar(key)}: ${value};`);
+  }
+  for (const [key, value] of Object.entries(componentOverrides)) {
+    overrides.push(`  ${tokenKeyToCssVar(key)}: ${value};`);
+  }
+
+  if (mode) {
+    overrides.push(`  color-scheme: ${mode === 'system' ? 'light dark' : mode};`);
+  }
+
+  if (overrides.length === 0 && !mode) {
+    return '';
+  }
+
+  const attr = mode ? `[data-tiny-theme="${escapeAttr(mode)}"]` : '';
+  lines.push(`${selector}${attr} {`);
+  lines.push(...overrides);
+  lines.push('}');
+  return lines.join('\n') + '\n';
+}
+
 export {
   defaultPresets,
+  getThemeStylesheet,
   mergeThemeDocuments,
   normalizeThemeInput,
   resolveTheme,
diff --git a/packages/tokens/scripts/build-runtime.js b/packages/tokens/scripts/build-runtime.js
index 4788c09d5..05804e63c 100644
--- a/packages/tokens/scripts/build-runtime.js
+++ b/packages/tokens/scripts/build-runtime.js
@@ -10,10 +10,39 @@ const PRESETS_DTS_PATH = path.join(DIST_DIR, 'presets.d.ts');
 const SCHEMA_DIST_DIR = path.join(DIST_DIR, 'schema');
 const THEME_SCHEMA_PATH = path.join(SOURCE_DIR, 'schema', 'theme.schema.json');
 
+const PRIMITIVE_DIR = path.join(SOURCE_DIR, 'primitive');
 const SEMANTIC_DIR = path.join(SOURCE_DIR, 'semantic');
 const COMPONENT_DIR = path.join(SOURCE_DIR, 'components');
 const THEMES_DIR = path.join(SOURCE_DIR, 'themes');
 
+const COLOR_FN_PREFIXES = [
+  'rgb',
+  'rgba',
+  'hsl',
+  'hsla',
+  'hwb',
+  'lab',
+  'lch',
+  'oklab',
+  'oklch',
+  'color',
+  'color-mix',
+  'linear-gradient',
+  'radial-gradient',
+  'conic-gradient',
+  'var',
+];
+const COLOR_FN_PATTERN = new RegExp(`^(${COLOR_FN_PREFIXES.join('|')})\\(.+\\)$`);
+const COLOR_KEYWORD_PATTERN = /^(transparent|currentColor|inherit|initial|unset|none)$/;
+const COLOR_HEX_PATTERN = /^#[0-9a-fA-F]{3,8}$/;
+const SINGLE_DIMENSION = '(auto|0|-?\\d*\\.?\\d+(px|em|rem|%|vh|vw|vmin|vmax|ch|ex)|calc\\(.+?\\)|var\\(.+?\\))';
+const DIMENSION_PATTERN = new RegExp(`^${SINGLE_DIMENSION}(\\s+${SINGLE_DIMENSION}){0,3}$`);
+const NUMBER_PATTERN = /^-?\d*\.?\d+$/;
+
+function looksLikeColor(value) {
+  return COLOR_HEX_PATTERN.test(value) || COLOR_KEYWORD_PATTERN.test(value) || COLOR_FN_PATTERN.test(value);
+}
+
 function mkdirp(dir) {
   fs.mkdirSync(dir, { recursive: true });
 }
@@ -103,9 +132,34 @@ function loadTokenFiles(dir, category) {
   });
 }
 
+function isReferenceValue(value) {
+  return typeof value === 'string' && /^\{[^}]+\}$/.test(value);
+}
+
+function typeMatchesValue(type, rawValue, tokenMap) {
+  if (isReferenceValue(rawValue)) {
+    const refKey = rawValue.slice(1, -1);
+    const refToken = tokenMap.get(refKey);
+    if (!refToken) return true;
+    return refToken.$type === type;
+  }
+  const value = String(rawValue).trim();
+  switch (type) {
+    case 'color':
+      return looksLikeColor(value);
+    case 'dimension':
+      return DIMENSION_PATTERN.test(value);
+    case 'number':
+      return NUMBER_PATTERN.test(value);
+    default:
+      return true;
+  }
+}
+
 function validateTokens(tokens) {
   const keys = new Set();
   const cssVars = new Set();
+  const tokenMap = new Map(tokens.map((t) => [t.key, t]));
 
   for (const token of tokens) {
     assert(!keys.has(token.key), `Duplicate token key: ${token.key}`);
@@ -118,6 +172,26 @@ function validateTokens(tokens) {
     if (token.category === 'component') {
       assert(token.component, `Missing component name for token: ${token.key}`);
     }
+
+    if (token.$type && !typeMatchesValue(token.$type, token.$value, tokenMap)) {
+      throw new Error(
+        `Token "${token.key}" declares $type "${token.$type}" but $value "${token.$value}" does not match.`
+      );
+    }
+  }
+
+  for (const token of tokens) {
+    if (!token.fallback) continue;
+    if (!token.fallback.startsWith('--ty-')) {
+      throw new Error(
+        `Token "${token.key}" has invalid fallback "${token.fallback}"; must reference a --ty-* custom property.`
+      );
+    }
+    if (!cssVars.has(token.fallback)) {
+      throw new Error(
+        `Token "${token.key}" fallback "${token.fallback}" does not match any registered CSS var.`
+      );
+    }
   }
 }
 
@@ -152,7 +226,9 @@ function buildRegistry(tokens) {
       type: token.$type,
       group: token.component
         ? token.component.charAt(0).toUpperCase() + token.component.slice(1)
-        : 'Semantic',
+        : token.category === 'primitive'
+          ? 'Primitive'
+          : 'Semantic',
       description: token.description || '',
       source: token.source,
       defaultValue: token.$value,
@@ -201,7 +277,9 @@ function buildBaseThemeCss(tokens, cssValues, tokenMap, lightTheme, darkTheme) {
   };
 
   const parts = [];
-  parts.push(buildThemeCss(tokens, cssValues, tokenMap, lightOverrides, ':root'));
+  parts.push(
+    buildThemeCss(tokens, cssValues, tokenMap, lightOverrides, ":root, [data-tiny-theme='light']")
+  );
   parts.push(buildThemeCss(tokens, cssValues, tokenMap, darkOverrides, "[data-tiny-theme='dark']"));
   parts.push('@media (prefers-color-scheme: dark) {');
   parts.push(buildThemeCss(tokens, cssValues, tokenMap, darkOverrides, "  [data-tiny-theme='system']").trimEnd());
@@ -211,7 +289,16 @@ function buildBaseThemeCss(tokens, cssValues, tokenMap, lightTheme, darkTheme) {
   return parts.join('\n');
 }
 
-function buildRegistryDts() {
+function buildKeyUnion(keys) {
+  if (keys.length === 0) return 'never';
+  return keys.map((k) => `'${k}'`).join('\n  | ');
+}
+
+function buildRegistryDts(tokens) {
+  const primitiveKeys = tokens.filter((t) => t.category === 'primitive').map((t) => t.key);
+  const semanticKeys = tokens.filter((t) => t.category === 'semantic').map((t) => t.key);
+  const componentKeys = tokens.filter((t) => t.category === 'component').map((t) => t.key);
+
   return `export type TokenCategory = 'primitive' | 'semantic' | 'component';
 export type TokenType =
   | 'color'
@@ -245,6 +332,17 @@ export interface TokenRegistryDocument {
   generatedAt: string;
   tokens: TokenRegistryEntry[];
 }
+
+export type PrimitiveTokenKey =
+  | ${buildKeyUnion(primitiveKeys)};
+
+export type SemanticTokenKey =
+  | ${buildKeyUnion(semanticKeys)};
+
+export type ComponentTokenKey =
+  | ${buildKeyUnion(componentKeys)};
+
+export type TokenKey = PrimitiveTokenKey | SemanticTokenKey | ComponentTokenKey;
 `;
 }
 
@@ -252,7 +350,9 @@ function buildPresetsDts(presets) {
   const ids = Object.keys(presets);
   const presetUnion = ids.length > 0 ? ids.map((id) => `'${id}'`).join(' | ') : 'string';
 
-  return `export type PresetThemeId = ${presetUnion};
+  return `import type { SemanticTokenKey, ComponentTokenKey } from './registry';
+
+export type PresetThemeId = ${presetUnion};
 
 export interface ThemeDocumentMeta {
   id?: string;
@@ -269,6 +369,14 @@ export interface ThemeDocumentTokens {
   components?: Record<string, string | number>;
 }
 
+/** Same shape as ThemeDocumentTokens but with typed, autocompleted keys. */
+export interface TypedThemeDocumentTokens {
+  semantic?: Partial<Record<SemanticTokenKey, string | number>> &
+    Record<string, string | number>;
+  components?: Partial<Record<ComponentTokenKey, string | number>> &
+    Record<string, string | number>;
+}
+
 export interface ThemeDocument {
   $schema?: string;
   meta?: ThemeDocumentMeta;
@@ -277,6 +385,15 @@ export interface ThemeDocument {
   tokens?: ThemeDocumentTokens;
 }
 
+/** Theme document with autocompletion and type-checking on token keys. */
+export interface TypedThemeDocument {
+  $schema?: string;
+  meta?: ThemeDocumentMeta;
+  mode: 'light' | 'dark' | 'system';
+  extends?: PresetThemeId | (string & {});
+  tokens?: TypedThemeDocumentTokens;
+}
+
 declare const presets: Record<PresetThemeId, ThemeDocument>;
 export default presets;
 `;
@@ -285,9 +402,10 @@ export default presets;
 function buildRuntimeTokens() {
   console.log('Building runtime tokens...\n');
 
+  const primitiveTokens = loadTokenFiles(PRIMITIVE_DIR, 'primitive');
   const semanticTokens = loadTokenFiles(SEMANTIC_DIR, 'semantic');
   const componentTokens = loadTokenFiles(COMPONENT_DIR, 'component');
-  const allTokens = [...semanticTokens, ...componentTokens];
+  const allTokens = [...primitiveTokens, ...semanticTokens, ...componentTokens];
   const themes = loadThemes();
 
   validateTokens(allTokens);
@@ -335,7 +453,7 @@ function buildRuntimeTokens() {
   fs.writeFileSync(path.join(DIST_CSS_DIR, 'light.css'), lightCss);
   fs.writeFileSync(path.join(DIST_CSS_DIR, 'dark.css'), darkCss);
   fs.writeFileSync(path.join(DIST_CSS_DIR, 'base.css'), baseCss);
-  fs.writeFileSync(REGISTRY_DTS_PATH, buildRegistryDts());
+  fs.writeFileSync(REGISTRY_DTS_PATH, buildRegistryDts(allTokens));
   fs.writeFileSync(PRESETS_DTS_PATH, buildPresetsDts(presets));
   fs.copyFileSync(THEME_SCHEMA_PATH, path.join(SCHEMA_DIST_DIR, 'theme.schema.json'));
 
diff --git a/packages/tokens/source/primitive/brand.json b/packages/tokens/source/primitive/brand.json
new file mode 100644
index 000000000..dfea438d3
--- /dev/null
+++ b/packages/tokens/source/primitive/brand.json
@@ -0,0 +1,52 @@
+{
+  "color.brand.50": {
+    "$value": "#f3eefa",
+    "$type": "color",
+    "description": "Brand palette 50 (lightest tint)."
+  },
+  "color.brand.100": {
+    "$value": "#ece3f7",
+    "$type": "color",
+    "description": "Brand palette 100."
+  },
+  "color.brand.200": {
+    "$value": "#c4a7e6",
+    "$type": "color",
+    "description": "Brand palette 200."
+  },
+  "color.brand.300": {
+    "$value": "#a882dc",
+    "$type": "color",
+    "description": "Brand palette 300."
+  },
+  "color.brand.400": {
+    "$value": "#8b62d0",
+    "$type": "color",
+    "description": "Brand palette 400."
+  },
+  "color.brand.500": {
+    "$value": "#6e41bf",
+    "$type": "color",
+    "description": "Brand palette 500 (base)."
+  },
+  "color.brand.600": {
+    "$value": "#5a30a8",
+    "$type": "color",
+    "description": "Brand palette 600."
+  },
+  "color.brand.700": {
+    "$value": "#4a2790",
+    "$type": "color",
+    "description": "Brand palette 700."
+  },
+  "color.brand.800": {
+    "$value": "#3a1f70",
+    "$type": "color",
+    "description": "Brand palette 800."
+  },
+  "color.brand.900": {
+    "$value": "#2a1650",
+    "$type": "color",
+    "description": "Brand palette 900 (darkest shade)."
+  }
+}
diff --git a/packages/tokens/source/primitive/spacing.json b/packages/tokens/source/primitive/spacing.json
new file mode 100644
index 000000000..ecc2c68dd
--- /dev/null
+++ b/packages/tokens/source/primitive/spacing.json
@@ -0,0 +1,52 @@
+{
+  "space.0": {
+    "$value": "0",
+    "$type": "dimension",
+    "description": "Zero spacing."
+  },
+  "space.1": {
+    "$value": "4px",
+    "$type": "dimension",
+    "description": "4px spacing step."
+  },
+  "space.2": {
+    "$value": "8px",
+    "$type": "dimension",
+    "description": "8px spacing step."
+  },
+  "space.3": {
+    "$value": "12px",
+    "$type": "dimension",
+    "description": "12px spacing step."
+  },
+  "space.4": {
+    "$value": "16px",
+    "$type": "dimension",
+    "description": "16px spacing step."
+  },
+  "space.5": {
+    "$value": "20px",
+    "$type": "dimension",
+    "description": "20px spacing step."
+  },
+  "space.6": {
+    "$value": "24px",
+    "$type": "dimension",
+    "description": "24px spacing step."
+  },
+  "space.8": {
+    "$value": "32px",
+    "$type": "dimension",
+    "description": "32px spacing step."
+  },
+  "space.10": {
+    "$value": "40px",
+    "$type": "dimension",
+    "description": "40px spacing step."
+  },
+  "space.12": {
+    "$value": "48px",
+    "$type": "dimension",
+    "description": "48px spacing step."
+  }
+}