@uniweb/theming 0.1.1 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/theming",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Theming utilities for the Uniweb platform — shade generation, CSS generation, theme processing",
   "type": "module",
   "exports": {
@@ -26,10 +26,10 @@
   "engines": {
     "node": ">=20.19"
   },
-  "scripts": {
-    "test": "vitest run"
-  },
   "devDependencies": {
     "vitest": "^3.2.1"
+  },
+  "scripts": {
+    "test": "vitest run"
   }
-}
+}

package/src/css-generator.js

@@ -26,6 +26,7 @@ const DEFAULT_CONTEXT_TOKENS = {
     'ring': 'var(--primary-500)',
     'link': 'var(--primary-600)',
     'link-hover': 'var(--primary-700)',
+    'accent': 'var(--accent-600)',
     'primary': 'var(--primary-600)',
     'primary-foreground': 'white',
     'primary-hover': 'var(--primary-700)',
@@ -54,6 +55,7 @@ const DEFAULT_CONTEXT_TOKENS = {
     'ring': 'var(--primary-500)',
     'link': 'var(--primary-600)',
     'link-hover': 'var(--primary-700)',
+    'accent': 'var(--accent-600)',
     'primary': 'var(--primary-600)',
     'primary-foreground': 'white',
     'primary-hover': 'var(--primary-700)',
@@ -72,7 +74,7 @@ const DEFAULT_CONTEXT_TOKENS = {
     'info-subtle': '#eff6ff',
   },
   dark: {
-    'section': 'var(--neutral-900)',
+    'section': 'var(--neutral-950)',
     'card': 'var(--neutral-800)',
     'muted': 'var(--neutral-700)',
     'body': 'var(--neutral-50)',
@@ -82,6 +84,7 @@ const DEFAULT_CONTEXT_TOKENS = {
     'ring': 'var(--primary-500)',
     'link': 'var(--primary-400)',
     'link-hover': 'var(--primary-300)',
+    'accent': 'var(--accent-400)',
     'primary': 'var(--primary-500)',
     'primary-foreground': 'white',
     'primary-hover': 'var(--primary-400)',
@@ -150,55 +153,36 @@ function generatePaletteVars(palettes) {
  *
  * @param {string} context - Context name (light, medium, dark)
  * @param {Object} tokens - Token overrides
+ * @param {Object} colorVars - Context-aware foundation color vars: { light: {...}, dark: {...} }
  * @returns {string} CSS for context class
  */
-function generateContextCSS(context, tokens = {}) {
+function generateContextCSS(context, tokens = {}, colorVars = {}) {
   const defaultTokens = DEFAULT_CONTEXT_TOKENS[context] || DEFAULT_CONTEXT_TOKENS.light
   const mergedTokens = { ...defaultTokens, ...tokens }
 
-  const vars = generateVarDeclarations(mergedTokens)
+  // Merge context-aware color vars into the context class
+  const contextColorVars = colorVars[context] || {}
+  const allVars = { ...mergedTokens, ...contextColorVars }
+
+  const vars = generateVarDeclarations(allVars)
 
-  return `.context-${context} {\n${vars}\n  background-color: var(--section);\n}`
+  return `.context-${context} {\n${vars}\n}`
 }
 
 /**
  * Generate dark scheme CSS (for site-wide dark mode toggle)
  *
  * @param {Object} config - Appearance configuration
+ * @param {Object} darkOverrides - Dark context token overrides
+ * @param {Object} colorVars - Context-aware foundation color vars: { light: {...}, dark: {...} }
  * @returns {string} CSS for dark scheme support
  */
-function generateDarkSchemeCSS(config = {}) {
-  const { respectSystemPreference = true } = config
+function generateDarkSchemeCSS(config = {}, darkOverrides = {}, colorVars = {}) {
+  const respectSystemPreference = config.default === 'system'
 
-  // Dark scheme tokens - similar to dark context but at root level
-  const darkTokens = {
-    'section': 'var(--neutral-950)',
-    'card': 'var(--neutral-900)',
-    'muted': 'var(--neutral-800)',
-    'body': 'var(--neutral-50)',
-    'heading': 'white',
-    'subtle': 'var(--neutral-400)',
-    'border': 'var(--neutral-800)',
-    'ring': 'var(--primary-500)',
-    'link': 'var(--primary-400)',
-    'link-hover': 'var(--primary-300)',
-    'primary': 'var(--primary-500)',
-    'primary-foreground': 'white',
-    'primary-hover': 'var(--primary-400)',
-    'primary-border': 'transparent',
-    'secondary': 'var(--neutral-800)',
-    'secondary-foreground': 'var(--neutral-100)',
-    'secondary-hover': 'var(--neutral-700)',
-    'secondary-border': 'var(--neutral-600)',
-    'success': '#4ade80',
-    'success-subtle': '#052e16',
-    'warning': '#fbbf24',
-    'warning-subtle': '#451a03',
-    'error': '#f87171',
-    'error-subtle': '#450a0a',
-    'info': '#60a5fa',
-    'info-subtle': '#172554',
-  }
+  // Merge default dark tokens with user element overrides and dark color vars
+  const darkColorVars = colorVars.dark || {}
+  const darkTokens = { ...DEFAULT_CONTEXT_TOKENS.dark, ...darkOverrides, ...darkColorVars }
 
   const vars = generateVarDeclarations(darkTokens)
 
@@ -218,28 +202,177 @@ function generateDarkSchemeCSS(config = {}) {
   return css
 }
 
+// Generic CSS font families that should not trigger font loading
+const GENERIC_FAMILIES = new Set([
+  'serif', 'sans-serif', 'monospace', 'cursive', 'fantasy',
+  'system-ui', 'ui-monospace', 'ui-serif', 'ui-sans-serif', 'ui-rounded',
+  'math', 'emoji', 'fangsong',
+  'inherit', 'initial', 'revert', 'unset',
+])
+
 /**
- * Generate font CSS
+ * Extract font family names actually used by body/heading/mono slots.
+ *
+ * Only considers slots the user explicitly configured (tracked via _userSlots
+ * from the processor). Default system font stacks are ignored so they don't
+ * trigger unnecessary font loading.
  *
  * @param {Object} fonts - Font configuration
- * @returns {string} CSS for fonts
+ * @returns {Set<string>} Lowercase family names referenced by user-set slots
+ */
+function extractUsedFamilies(fonts) {
+  const used = new Set()
+  const slots = fonts._userSlots || ['body', 'heading', 'mono']
+
+  for (const slot of slots) {
+    const value = fonts[slot]
+    if (!value) continue
+
+    for (const segment of value.split(',')) {
+      const name = segment.trim().replace(/^["']|["']$/g, '').toLowerCase()
+      if (name && !GENERIC_FAMILIES.has(name)) {
+        used.add(name)
+      }
+    }
+  }
+
+  return used
+}
+
+/**
+ * Filter a Google Fonts URL to only include families in the used set.
+ *
+ * @param {string} url - Google Fonts CSS URL
+ * @param {Set<string>} usedFamilies - Lowercase family names to keep
+ * @returns {string|null} Filtered URL, or null if no families remain
+ */
+function filterGoogleFontsUrl(url, usedFamilies) {
+  try {
+    const parsed = new URL(url)
+    const familyParams = parsed.searchParams.getAll('family')
+    if (familyParams.length === 0) return url
+
+    const kept = familyParams.filter((param) => {
+      // "Montserrat:wght@400;700" → "montserrat"
+      const name = param.split(':')[0].trim().toLowerCase()
+      return usedFamilies.has(name)
+    })
+
+    if (kept.length === 0) return null
+
+    // Rebuild URL with only kept families
+    parsed.searchParams.delete('family')
+    for (const f of kept) {
+      parsed.searchParams.append('family', f)
+    }
+    return parsed.toString()
+  } catch {
+    return url // malformed URL — keep as-is
+  }
+}
+
+/**
+ * Check whether a URL points to Google Fonts.
+ */
+function isGoogleFontsUrl(url) {
+  try {
+    return new URL(url).hostname === 'fonts.googleapis.com'
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Generate font CSS and external link tags.
+ *
+ * @param {Object} fonts - Font configuration
+ * @returns {{ css: string, links: string }} css for <style>, links for <head>
  */
 function generateFontCSS(fonts = {}) {
-  const lines = []
+  const cssLines = []
+  const linkTags = []
+
+  const usedFamilies = extractUsedFamilies(fonts)
+
+  // --- @font-face rules from faces[] (filtered to used families) ---
+  // Also generate <link rel="preload"> hints so browsers fetch fonts early
+  const PRELOAD_TYPE = { woff2: 'font/woff2', woff: 'font/woff', truetype: 'font/ttf', opentype: 'font/otf' }
+
+  if (fonts.faces && Array.isArray(fonts.faces)) {
+    for (const face of fonts.faces) {
+      if (!face.family || !face.src) continue
+      if (!usedFamilies.has(face.family.toLowerCase())) continue
+
+      const format = face.format || (face.src.endsWith('.woff2') ? 'woff2' : 'woff')
+      cssLines.push(
+        `@font-face {`,
+        `  font-family: ${face.family};`,
+        `  src: url('${face.src}') format('${format}');`,
+        `  font-weight: ${face.weight || 400};`,
+        `  font-style: ${face.style || 'normal'};`,
+        `  font-display: swap;`,
+        `}`,
+      )
+
+      const mimeType = PRELOAD_TYPE[format]
+      if (mimeType) {
+        linkTags.push(`<link rel="preload" href="${face.src}" as="font" type="${mimeType}" crossorigin>`)
+      }
+    }
+    if (cssLines.length > 0) {
+      cssLines.push('') // blank line after @font-face block
+    }
+  }
+
+  // --- External imports → <link> tags (filtered to used families) ---
+  const googleUrls = []
 
-  // Font imports
   if (fonts.import && Array.isArray(fonts.import)) {
-    for (const font of fonts.import) {
-      if (font.url) {
-        lines.push(`@import url('${font.url}');`)
+    for (const entry of fonts.import) {
+      if (!entry.url) continue
+
+      if (isGoogleFontsUrl(entry.url)) {
+        const filtered = filterGoogleFontsUrl(entry.url, usedFamilies)
+        if (filtered) googleUrls.push(filtered)
+      } else {
+        linkTags.push(`<link rel="stylesheet" href="${entry.url}">`)
       }
     }
-    if (lines.length > 0) {
-      lines.push('') // Empty line after imports
+  }
+
+  // Merge Google Fonts into a single <link> with preconnect
+  if (googleUrls.length > 0) {
+    // Collect all family params from all URLs into one
+    const allFamilies = []
+    let display = 'swap'
+    for (const url of googleUrls) {
+      try {
+        const parsed = new URL(url)
+        allFamilies.push(...parsed.searchParams.getAll('family'))
+        if (parsed.searchParams.get('display')) {
+          display = parsed.searchParams.get('display')
+        }
+      } catch {
+        // skip malformed
+      }
+    }
+
+    if (allFamilies.length > 0) {
+      const merged = new URL('https://fonts.googleapis.com/css2')
+      for (const f of allFamilies) {
+        merged.searchParams.append('family', f)
+      }
+      merged.searchParams.set('display', display)
+
+      linkTags.unshift(
+        `<link rel="preconnect" href="https://fonts.googleapis.com">`,
+        `<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>`,
+        `<link rel="stylesheet" href="${merged.toString()}">`,
+      )
     }
   }
 
-  // Font family variables
+  // --- :root font variables ---
   const fontVars = []
   if (fonts.body) {
     fontVars.push(`  --font-body: ${fonts.body};`)
@@ -252,14 +385,33 @@ function generateFontCSS(fonts = {}) {
   }
 
   if (fontVars.length > 0) {
-    lines.push(':root {')
-    lines.push(...fontVars)
-    lines.push('}')
+    cssLines.push(':root {')
+    cssLines.push(...fontVars)
+    cssLines.push('}')
   }
 
-  return lines.join('\n')
+  return {
+    css: cssLines.join('\n'),
+    links: linkTags.join('\n'),
+  }
 }
 
+// Theme token names reserved by the theming engine — foundation vars must not use these
+const RESERVED_VAR_NAMES = new Set([
+  // Semantic color tokens
+  'section', 'card', 'muted', 'body', 'heading', 'subtle',
+  'border', 'ring', 'link', 'link-hover', 'accent',
+  // Action tokens
+  'primary', 'primary-foreground', 'primary-hover', 'primary-border',
+  'secondary', 'secondary-foreground', 'secondary-hover', 'secondary-border',
+  // Status tokens
+  'success', 'success-subtle', 'warning', 'warning-subtle',
+  'error', 'error-subtle', 'info', 'info-subtle',
+])
+
+// Palette shade pattern: primary-50, neutral-950, accent-300, etc.
+const PALETTE_SHADE_RE = /^(primary|secondary|accent|neutral)-\d+$/
+
 /**
  * Generate foundation-specific CSS variables
  *
@@ -274,6 +426,12 @@ function generateFoundationVars(vars = {}) {
   const declarations = []
 
   for (const [name, config] of Object.entries(vars)) {
+    if (RESERVED_VAR_NAMES.has(name) || PALETTE_SHADE_RE.test(name)) {
+      console.warn(
+        `Warning: Foundation var '${name}' collides with a theme token. ` +
+        `Rename it to avoid unexpected behavior (e.g., '${name}-value' or '${name}-size').`
+      )
+    }
     const value = typeof config === 'object' ? config.default : config
     if (value !== undefined) {
       declarations.push(`  --${name}: ${value};`)
@@ -296,7 +454,7 @@ function generateFoundationVars(vars = {}) {
  * @param {Object} config.fonts - Font configuration
  * @param {Object} config.appearance - Appearance settings (dark mode, etc.)
  * @param {Object} config.foundationVars - Foundation-specific variables
- * @returns {string} Complete CSS string
+ * @returns {{ css: string, links: string }} CSS string and font link tags
  */
 export function generateThemeCSS(config = {}) {
   const {
@@ -305,14 +463,15 @@ export function generateThemeCSS(config = {}) {
     fonts = {},
     appearance = {},
     foundationVars = {},
+    colorVars = {},
   } = config
 
   const sections = []
 
-  // 1. Font imports and variables
-  const fontCSS = generateFontCSS(fonts)
-  if (fontCSS) {
-    sections.push('/* Typography */\n' + fontCSS)
+  // 1. Font face rules and variables (links returned separately)
+  const fontResult = generateFontCSS(fonts)
+  if (fontResult.css) {
+    sections.push('/* Typography */\n' + fontResult.css)
   }
 
   // 2. Color palettes
@@ -321,15 +480,17 @@ export function generateThemeCSS(config = {}) {
   sections.push(`/* Color Palettes */\n:root {\n${paletteVars}\n}`)
 
   // 3. Default semantic tokens (applied to :root for global defaults)
-  const defaultTokens = { ...DEFAULT_CONTEXT_TOKENS.light, ...(contexts.light || {}) }
+  // Include light color vars in the :root defaults
+  const lightColorVars = colorVars.light || {}
+  const defaultTokens = { ...DEFAULT_CONTEXT_TOKENS.light, ...(contexts.light || {}), ...lightColorVars }
   const defaultVars = generateVarDeclarations(defaultTokens)
-  sections.push(`/* Default Semantic Tokens */\n:root {\n${defaultVars}\n}`)
+  sections.push(`/* Default Semantic Tokens */\n:root {\n${defaultVars}\n}\n\n/* Section backgrounds — applied once, resolves via context tokens */\n[id^="section-"] {\n  background-color: var(--section);\n}`)
 
   // 4. Context classes
   const contextCSS = [
-    generateContextCSS('light', contexts.light),
-    generateContextCSS('medium', contexts.medium),
-    generateContextCSS('dark', contexts.dark),
+    generateContextCSS('light', contexts.light, colorVars),
+    generateContextCSS('medium', contexts.medium, colorVars),
+    generateContextCSS('dark', contexts.dark, colorVars),
   ]
   sections.push('/* Color Contexts */\n' + contextCSS.join('\n\n'))
 
@@ -339,9 +500,9 @@ export function generateThemeCSS(config = {}) {
     sections.push('/* Foundation Variables */\n' + foundationCSS)
   }
 
-  // 6. Dark scheme support (if enabled)
-  if (appearance.allowToggle || appearance.schemes?.includes('dark')) {
-    sections.push(generateDarkSchemeCSS(appearance))
+  // 6. Dark scheme support (if enabled, default is dark, or follows system preference)
+  if (appearance.allowToggle || appearance.default === 'dark' || appearance.default === 'system' || appearance.schemes?.includes('dark')) {
+    sections.push(generateDarkSchemeCSS(appearance, contexts.dark, colorVars))
   }
 
   // 7. Site background (if specified in theme.yml)
@@ -364,7 +525,10 @@ export function generateThemeCSS(config = {}) {
     }
   }
 
-  return sections.join('\n\n')
+  return {
+    css: sections.join('\n\n'),
+    links: fontResult.links,
+  }
 }
 
 /**
@@ -391,10 +555,16 @@ export function getDefaultColors() {
   return { ...DEFAULT_COLORS }
 }
 
+/**
+ * Extract used font families (useful for testing)
+ */
+export { extractUsedFamilies }
+
 export default {
   generateThemeCSS,
   generateContextCSS,
   generatePaletteVars,
   getDefaultContextTokens,
   getDefaultColors,
+  extractUsedFamilies,
 }

package/src/index.js

@@ -24,6 +24,7 @@ export {
   generatePaletteVars,
   getDefaultContextTokens,
   getDefaultColors,
+  extractUsedFamilies,
 } from './css-generator.js'
 
 // Theme processing
@@ -34,6 +35,12 @@ export {
   foundationHasVars,
 } from './processor.js'
 
+// Value normalization
+export { normalizeTokenValue } from './normalize.js'
+
+// Section override CSS
+export { buildSectionOverrides } from './section-overrides.js'
+
 // Default export for convenience
 import { processTheme } from './processor.js'
 import { generateThemeCSS } from './css-generator.js'
@@ -44,14 +51,15 @@ import { generateThemeCSS } from './css-generator.js'
  * @param {Object} themeYml - Raw theme.yml content
  * @param {Object} options - Processing options
  * @param {Object} options.foundationVars - Foundation variables
- * @returns {{ css: string, config: Object, errors: string[], warnings: string[] }}
+ * @returns {{ css: string, links: string, config: Object, errors: string[], warnings: string[] }}
  */
 export function buildTheme(themeYml = {}, options = {}) {
   const { config, errors, warnings } = processTheme(themeYml, options)
-  const css = generateThemeCSS(config)
+  const { css, links } = generateThemeCSS(config)
 
   return {
     css,
+    links,
     config,
     errors,
     warnings,

package/src/normalize.js

@@ -0,0 +1,98 @@
+/**
+ * Token Value Normalizer
+ *
+ * Converts stored token values into valid CSS. This is the single source
+ * of truth for normalizing values from all origins:
+ *
+ * - theme.yml contexts: bare palette refs like `neutral-500`
+ * - Section overrides (DB): `rgba(var(--primary-900) / 1.00)`
+ * - Frontmatter overrides: bare palette refs like `neutral-900`
+ *
+ * Also supports the opacity shorthand: `neutral-500/20` → 20% opacity.
+ *
+ * @module @uniweb/theming/normalize
+ */
+
+const SHADE_LEVELS = new Set([50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950])
+
+// Matches bare palette reference: "primary-500", "neutral-900", "--accent-200"
+const PALETTE_REF_RE = /^([a-z][a-z0-9]*)-(\d+)$/
+
+// Matches bare palette reference with opacity: "neutral-500/20", "primary-600/50"
+const PALETTE_REF_OPACITY_RE = /^([a-z][a-z0-9]*-\d+)\/(\d+)$/
+
+// Matches rgba(var(--X) / Y) — the DB storage format for token values with opacity
+const RGBA_VAR_RE = /^rgba\(\s*(var\(--[^)]+\))\s*\/\s*([\d.]+)\s*\)$/
+
+/**
+ * Normalize a token value to valid CSS.
+ *
+ * Handles all stored formats and produces CSS that works with any color format
+ * (OKLCH, RGB, hex) by using var() references and color-mix() for opacity.
+ *
+ * @param {string} value - The stored token value
+ * @returns {string} Valid CSS value
+ *
+ * @example
+ * // Bare palette reference
+ * normalizeTokenValue('neutral-500')     // → 'var(--neutral-500)'
+ *
+ * // Palette reference with opacity
+ * normalizeTokenValue('neutral-500/20')  // → 'color-mix(in srgb, var(--neutral-500) 20%, transparent)'
+ *
+ * // DB format — full opacity (strip wrapper)
+ * normalizeTokenValue('rgba(var(--primary-900) / 1.00)')  // → 'var(--primary-900)'
+ *
+ * // DB format — partial opacity (convert to color-mix)
+ * normalizeTokenValue('rgba(var(--primary-900) / 0.50)')  // → 'color-mix(in srgb, var(--primary-900) 50%, transparent)'
+ *
+ * // Already valid CSS — pass through
+ * normalizeTokenValue('var(--neutral-500)')  // → 'var(--neutral-500)'
+ * normalizeTokenValue('white')               // → 'white'
+ * normalizeTokenValue('#ff0000')             // → '#ff0000'
+ */
+export function normalizeTokenValue(value) {
+  if (typeof value !== 'string') return value
+
+  // 1. Check for rgba(var(--X) / Y) — DB storage format
+  const rgbaMatch = value.match(RGBA_VAR_RE)
+  if (rgbaMatch) {
+    const varRef = rgbaMatch[1]
+    const opacity = parseFloat(rgbaMatch[2])
+    if (opacity >= 0.999) return varRef
+    return `color-mix(in srgb, ${varRef} ${Math.round(opacity * 100)}%, transparent)`
+  }
+
+  // 2. Already a CSS function (var(), color-mix(), rgb(), etc.) — pass through
+  if (value.includes('(')) return value
+
+  // 3. Hex color — pass through
+  if (value.startsWith('#')) return value
+
+  // 4. Strip leading dashes (--primary-500 → primary-500)
+  const bare = value.replace(/^-{0,2}/, '')
+
+  // 5. Check for palette reference with opacity: "neutral-500/20"
+  const opacityMatch = bare.match(PALETTE_REF_OPACITY_RE)
+  if (opacityMatch) {
+    const ref = opacityMatch[1]
+    const pct = parseInt(opacityMatch[2], 10)
+    const refMatch = ref.match(PALETTE_REF_RE)
+    if (refMatch && SHADE_LEVELS.has(parseInt(refMatch[2], 10))) {
+      if (pct >= 100) return `var(--${ref})`
+      return `color-mix(in srgb, var(--${ref}) ${pct}%, transparent)`
+    }
+  }
+
+  // 6. Check for bare palette reference: "neutral-500", "primary-600"
+  const paletteMatch = bare.match(PALETTE_REF_RE)
+  if (paletteMatch) {
+    const shade = parseInt(paletteMatch[2], 10)
+    if (SHADE_LEVELS.has(shade)) {
+      return `var(--${bare})`
+    }
+  }
+
+  // 7. Anything else — pass through (named colors like 'white', 'transparent', etc.)
+  return value
+}

package/src/processor.js

@@ -10,6 +10,7 @@
 
 import { isValidColor, generatePalettes } from './shade-generator.js'
 import { getDefaultColors, getDefaultContextTokens } from './css-generator.js'
+import { normalizeTokenValue } from './normalize.js'
 
 /**
  * Named neutral presets mapping to Tailwind gray families
@@ -31,6 +32,10 @@ const DEFAULT_INLINE = {
     color: 'var(--link)',
     'font-weight': '600',
   },
+  callout: {
+    color: 'var(--accent)',
+    'font-weight': '600',
+  },
   muted: {
     color: 'var(--subtle)',
   },
@@ -85,45 +90,6 @@ const DEFAULT_CODE_THEME = {
   selection: '#45475a',       // Selection background
 }
 
-/**
- * Valid shade levels for palette references
- */
-const SHADE_LEVELS = new Set([50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950])
-
-/**
- * Resolve context token values to valid CSS.
- *
- * Content authors write palette references as bare names: `primary-500`,
- * `neutral-200`. This is the natural syntax in theme.yml. The processor
- * resolves these to `var(--primary-500)` etc. Plain CSS values (hex, var(),
- * named colors) pass through as-is — that's the escape hatch.
- *
- * @param {string} value - The token value from theme.yml
- * @returns {string} Valid CSS value
- */
-function normalizePaletteRef(value) {
-  if (typeof value !== 'string') return value
-
-  // Already a CSS function (var(), rgb(), etc.) — pass through
-  if (value.includes('(')) return value
-
-  // Hex color — pass through
-  if (value.startsWith('#')) return value
-
-  // Bare palette reference: "primary-500", "--primary-500"
-  const bare = value.replace(/^-{0,2}/, '')
-  const match = bare.match(/^([a-z][a-z0-9]*)-(\d+)$/)
-
-  if (match) {
-    const shade = parseInt(match[2], 10)
-    if (SHADE_LEVELS.has(shade)) {
-      return `var(--${bare})`
-    }
-  }
-
-  return value
-}
-
 /**
  * Validate color configuration
  *
@@ -287,9 +253,16 @@ function validateCodeTheme(code) {
   return { valid: errors.length === 0, errors }
 }
 
+/**
+ * Context-aware var types (stored per light/dark context)
+ */
+const CONTEXT_AWARE_TYPES = new Set(['color', 'gradient'])
+
 /**
  * Validate foundation variables configuration
  *
+ * Accepts enriched var schema: { default, description, label, type, options, group, globalOnly }
+ *
  * @param {Object} vars - Foundation variables
  * @returns {{ valid: boolean, errors: string[] }}
  */
@@ -375,30 +348,60 @@ function normalizeAppearance(appearance) {
 /**
  * Merge foundation variables with site overrides
  *
- * @param {Object} foundationVars - Variables from foundation vars.js
+ * Splits variables into two groups based on their type:
+ * - flat: context-independent vars (text, select, untyped) → foundationVars
+ * - colorVars: context-aware vars (color, gradient) → stored per light/dark context
+ *
+ * @param {Object} foundationVars - Variables from foundation vars.js (with enriched schema)
  * @param {Object} siteVars - Site-level variable overrides
- * @returns {Object} Merged variables
+ * @returns {{ flat: Object, colorVars: Object }} Split variables
  */
 function mergeFoundationVars(foundationVars = {}, siteVars = {}) {
-  const merged = {}
+  const flat = {}
+  const colorVars = {}
 
-  // Start with foundation defaults
+  // Start with foundation defaults, split by type
   for (const [name, config] of Object.entries(foundationVars)) {
-    merged[name] = typeof config === 'object' ? { ...config } : { default: config }
+    const cfg = typeof config === 'object' ? { ...config } : { default: config }
+    const isContextAware = CONTEXT_AWARE_TYPES.has(cfg.type)
+
+    if (isContextAware) {
+      // Default value applies to all contexts
+      const defaultVal = cfg.default || ''
+      colorVars[name] = { light: defaultVal, dark: defaultVal }
+    } else {
+      flat[name] = cfg
+    }
   }
 
   // Apply site overrides
   for (const [name, value] of Object.entries(siteVars)) {
-    if (merged[name]) {
-      // Override the default value
-      merged[name].default = value
+    // Look up type from foundation schema
+    const schemaCfg = foundationVars[name]
+    const type = typeof schemaCfg === 'object' ? schemaCfg?.type : undefined
+    const isContextAware = CONTEXT_AWARE_TYPES.has(type)
+
+    if (isContextAware) {
+      if (typeof value === 'object' && value !== null && (value.light || value.dark)) {
+        // Per-context override: { light: '#fff', dark: '#000' }
+        colorVars[name] = { ...(colorVars[name] || {}), ...value }
+      } else {
+        // Scalar override: apply same value to all contexts
+        const strVal = String(value)
+        colorVars[name] = { light: strVal, dark: strVal }
+      }
     } else {
-      // New variable from site
-      merged[name] = { default: value }
+      if (flat[name]) {
+        // Override the default value
+        flat[name].default = value
+      } else {
+        // New variable from site
+        flat[name] = { default: value }
+      }
     }
   }
 
-  return merged
+  return { flat, colorVars }
 }
 
 /**
@@ -469,7 +472,7 @@ export function processTheme(rawConfig = {}, options = {}) {
     const normalized = {}
 
     for (const [token, value] of Object.entries(overrides)) {
-      normalized[token] = normalizePaletteRef(value)
+      normalized[token] = normalizeTokenValue(value)
     }
 
     contexts[name] = { ...defaultContexts[name], ...normalized }
@@ -480,12 +483,17 @@ export function processTheme(rawConfig = {}, options = {}) {
     ...DEFAULT_FONTS,
     ...(rawConfig.fonts || {}),
   }
+  // Track which font slots the user explicitly set (vs inherited defaults).
+  // Used by extractUsedFamilies to avoid loading fonts referenced only in defaults.
+  const userFonts = rawConfig.fonts || {}
+  fonts._userSlots = ['body', 'heading', 'mono'].filter((s) => userFonts[s] !== undefined)
 
   // Normalize and process appearance
   const appearance = normalizeAppearance(rawConfig.appearance)
 
   // Merge foundation variables with site overrides
-  const mergedFoundationVars = mergeFoundationVars(
+  // Splits into context-independent (flat) and context-aware (colorVars)
+  const { flat: mergedFoundationVars, colorVars } = mergeFoundationVars(
     foundationVars,
     rawConfig.vars || rawConfig.foundationVars || {}
   )
@@ -517,7 +525,8 @@ export function processTheme(rawConfig = {}, options = {}) {
     contexts,
     fonts,
     appearance,
-    foundationVars: mergedFoundationVars,
+    foundationVars: mergedFoundationVars, // Context-independent vars only
+    colorVars,   // Context-aware vars: { light: {...}, dark: {...} }
     code,        // Code block theme for runtime injection
     background,  // Site-level background CSS value
     inline,      // Inline text style definitions

package/src/section-overrides.js

@@ -0,0 +1,216 @@
+/**
+ * Section Override CSS Builder
+ *
+ * Builds a single CSS string from all section-level overrides on a page.
+ * Follows the same pattern as buildTheme() for global CSS:
+ * all overrides are pre-built into a <style id="uniweb-page-overrides"> tag.
+ *
+ * @module @uniweb/theming/section-overrides
+ */
+
+import { generatePalettes } from './shade-generator.js'
+import { normalizeTokenValue } from './normalize.js'
+
+/**
+ * Check if a block has any section-level overrides worth emitting.
+ *
+ * @param {Object} standardOptions - Block's standardOptions
+ * @returns {boolean}
+ */
+function hasOverrides(standardOptions) {
+  if (!standardOptions) return false
+
+  const { colors, foundationStyles } = standardOptions
+
+  if (foundationStyles && Object.keys(foundationStyles).length > 0) return true
+  if (!colors) return false
+
+  const hasColors =
+    colors.colors?.light && Object.keys(colors.colors.light).length > 0
+  const hasElements =
+    colors.elements &&
+    Object.values(colors.elements).some(
+      (ctx) => ctx && Object.keys(ctx).length > 0
+    )
+  return hasColors || hasElements
+}
+
+/**
+ * Build CSS variable declarations for base palette overrides.
+ * Base palette is context-independent — always stored under the 'light' key.
+ *
+ * @param {Object} baseColors - e.g. { primary: "#3b82f6", accent: "#f59e0b" }
+ * @returns {string[]} CSS declaration lines
+ */
+function buildPaletteVars(baseColors) {
+  if (!baseColors || Object.keys(baseColors).length === 0) return []
+
+  const vars = []
+  const palettes = generatePalettes(baseColors)
+
+  for (const [name, shades] of Object.entries(palettes)) {
+    for (const [level, value] of Object.entries(shades)) {
+      vars.push(`  --${name}-${level}: ${value};`)
+    }
+  }
+
+  return vars
+}
+
+/**
+ * Build CSS variable declarations for semantic token overrides.
+ *
+ * @param {Object} elements - e.g. { heading: "rgba(var(--primary-900) / 1.00)", ... }
+ * @returns {string[]} CSS declaration lines
+ */
+function buildElementVars(elements) {
+  if (!elements || Object.keys(elements).length === 0) return []
+
+  const vars = []
+  for (const [token, value] of Object.entries(elements)) {
+    if (value === '' || value == null) continue
+    vars.push(`  --${token}: ${normalizeTokenValue(value)};`)
+  }
+  return vars
+}
+
+/**
+ * Build CSS variable declarations for foundation style overrides.
+ *
+ * @param {Object} styles - e.g. { "border-radius": "0.5rem" }
+ * @returns {string[]} CSS declaration lines
+ */
+function buildFoundationVars(styles) {
+  if (!styles || Object.keys(styles).length === 0) return []
+
+  const vars = []
+  for (const [name, value] of Object.entries(styles)) {
+    if (value === '' || value == null || typeof value === 'object') continue
+    vars.push(`  --${name}: ${value};`)
+  }
+  return vars
+}
+
+/**
+ * Split foundation styles into flat (context-independent) and
+ * context-keyed (color/gradient) values.
+ *
+ * Flat values: { "radius-xl": "1.5rem" }
+ * Context-keyed values: { "colorful-bg": { light: "linear-gradient(...)", dark: "..." } }
+ *
+ * @param {Object} styles - Foundation styles object
+ * @returns {{ flat: Object, contexts: Object }} - flat styles + { light: {...}, dark: {...} }
+ */
+function splitFoundationStyles(styles) {
+  if (!styles || Object.keys(styles).length === 0) return { flat: {}, contexts: {} }
+
+  const flat = {}
+  const contexts = {}
+
+  for (const [name, value] of Object.entries(styles)) {
+    if (value == null) continue
+    if (typeof value === 'object') {
+      // Context-keyed: { light: "...", dark: "..." }
+      for (const [ctx, ctxVal] of Object.entries(value)) {
+        if (ctxVal === '' || ctxVal == null) continue
+        if (!contexts[ctx]) contexts[ctx] = {}
+        contexts[ctx][name] = ctxVal
+      }
+    } else {
+      flat[name] = value
+    }
+  }
+
+  return { flat, contexts }
+}
+
+/**
+ * Build a CSS rule for a section with its overrides.
+ *
+ * @param {string} selector - CSS selector (e.g. "#section-42")
+ * @param {string[]} vars - CSS declaration lines
+ * @returns {string} CSS rule string (empty if no vars)
+ */
+function buildRule(selector, vars) {
+  if (vars.length === 0) return ''
+  return `${selector} {\n${vars.join('\n')}\n}\n`
+}
+
+/**
+ * Build section override CSS for all blocks on a page.
+ *
+ * Takes an array of block-like objects and appearance config,
+ * returns a CSS string ready for injection into a <style> tag.
+ *
+ * Works with both Block instances and plain data objects — only reads:
+ * - block.stableId || block.id — for CSS selector
+ * - block.themeName — '' for Auto, 'light'/'medium'/'dark' for Pinned
+ * - block.standardOptions — { colors, foundationStyles }
+ * - block.componentVars — merged meta.js defaults + frontmatter overrides
+ *
+ * @param {Array<Object>} blocks - Block data objects
+ * @param {Object} appearance - Theme appearance config
+ * @param {boolean} appearance.allowToggle - Whether scheme toggle is enabled
+ * @param {string} appearance.default - Default scheme ('light' or 'dark')
+ * @returns {string} CSS string (empty if no overrides)
+ */
+export function buildSectionOverrides(blocks, appearance = {}) {
+  if (!blocks || blocks.length === 0) return ''
+
+  let css = ''
+
+  for (const block of blocks) {
+    const hasStandardOverrides = hasOverrides(block.standardOptions)
+    const hasComponentVars = block.componentVars && Object.keys(block.componentVars).length > 0
+
+    if (!hasStandardOverrides && !hasComponentVars) continue
+
+    const { colors, foundationStyles } = block.standardOptions || {}
+    const sectionId = block.stableId || block.id
+    const selector = `#section-${sectionId}`
+
+    const isAuto = !block.themeName
+    const hasToggle = appearance.allowToggle
+
+    // Base palette is context-independent (always under 'light' key)
+    const paletteVars = buildPaletteVars(colors?.colors?.light)
+
+    // Split foundation styles: flat (context-independent) + context-keyed (color/gradient)
+    const { flat: flatFoundation, contexts: ctxFoundation } = splitFoundationStyles(foundationStyles)
+    const foundationVars = buildFoundationVars(flatFoundation)
+
+    // Component-level CSS vars are context-independent
+    const compVars = buildFoundationVars(block.componentVars)
+
+    if (isAuto && hasToggle) {
+      // Dual rules: light-scoped elements + dark-scoped elements
+      const lightElementVars = buildElementVars(colors?.elements?.light)
+      const darkElementVars = buildElementVars(colors?.elements?.dark)
+
+      // Context-aware foundation vars (color/gradient types)
+      const lightFoundationCtx = buildFoundationVars(ctxFoundation.light)
+      const darkFoundationCtx = buildFoundationVars(ctxFoundation.dark)
+
+      // Context-independent rule: palette + flat foundation + component vars (apply in both schemes)
+      const sharedVars = [...paletteVars, ...foundationVars, ...compVars]
+      css += buildRule(selector, sharedVars)
+
+      // Light-only overrides (elements + context-aware foundation vars)
+      css += buildRule(`:root:not(.scheme-dark) ${selector}`, [...lightElementVars, ...lightFoundationCtx])
+
+      // Dark-only overrides (elements + context-aware foundation vars)
+      css += buildRule(`.scheme-dark ${selector}`, [...darkElementVars, ...darkFoundationCtx])
+    } else {
+      // Single context: when toggle is off, always use 'light' bucket
+      // (overrides are context-independent); when toggle is on, use pinned context
+      const ctx = hasToggle ? (block.themeName || 'light') : 'light'
+      const elementVars = buildElementVars(colors?.elements?.[ctx])
+      const ctxFoundationVars = buildFoundationVars(ctxFoundation[ctx])
+
+      const allVars = [...paletteVars, ...elementVars, ...foundationVars, ...compVars, ...ctxFoundationVars]
+      css += buildRule(selector, allVars)
+    }
+  }
+
+  return css
+}