@loworbitstudio/visor-theme-engine 0.14.0 → 0.15.1

package/dist/adapters/index.d.ts

@@ -1,4 +1,4 @@
-import { g as GeneratedPrimitives, m as SemanticTokens, R as ResolvedThemeConfig } from '../types-BDRXkldG.js';
+import { g as GeneratedPrimitives, m as SemanticTokens, R as ResolvedThemeConfig } from '../types-zug1_eLX.js';
 
 /**
  * Adapter types for the Visor theme engine.

package/dist/adapters/index.js

@@ -3,6 +3,7 @@ import {
   MATERIAL_TEXT_SLOTS,
   SELECTIVE_SHADE_STEPS,
   aliasFamily,
+  block,
   buildVisorFontUrl,
   collectBrandPassthrough,
   fontStack,
@@ -19,7 +20,7 @@ import {
   resolveThemeBrand,
   resolveThemeFonts,
   sectionComment
-} from "../chunk-YDRQQIOB.js";
+} from "../chunk-DQ256PSE.js";
 
 // src/adapters/brand-passthrough.ts
 var SENTINEL_COLOR = "#ff00ff";
@@ -160,6 +161,51 @@ function nextjsAdapter(input, options) {
     lines.push(wrapInLayer("visor-brand", passthroughCss));
     lines.push("");
   }
+  const hostSelector = scopePrefix ?? ":root";
+  const lightModeSelector = `html:not(.dark) ${scopePrefix ?? ""}`.trim();
+  const darkModeSelector = `html.dark ${scopePrefix ?? ""}`.trim();
+  const prefersSelector = scopePrefix ? `${scopePrefix}:not(.light):not(.theme-light):not([data-theme="light"])` : ':root:not(.light):not(.theme-light):not([data-theme="light"])';
+  const semanticLines = [];
+  semanticLines.push("/* \u2500\u2500 Layer: Semantic aliases (VI-453) \u2500\u2500 */");
+  semanticLines.push(sectionComment("Discrete: Text size aliases (--text-N)"));
+  semanticLines.push(block(hostSelector, generateTextScaleAliasDecls()));
+  semanticLines.push("");
+  semanticLines.push(sectionComment("Discrete: Space aliases (--space-N)"));
+  semanticLines.push(block(hostSelector, generateSpaceAliasDecls(input.config)));
+  semanticLines.push("");
+  semanticLines.push(sectionComment("Intent aliases (light)"));
+  semanticLines.push(block(lightModeSelector, generateIntentDecls(input.tokens, "light")));
+  semanticLines.push("");
+  semanticLines.push(sectionComment("Hairline aliases (light)"));
+  semanticLines.push(block(lightModeSelector, generateHairlineDecls(input.tokens, "light")));
+  semanticLines.push("");
+  semanticLines.push(sectionComment("Intent aliases (dark) \u2014 manual toggle"));
+  semanticLines.push(block(darkModeSelector, generateIntentDecls(input.tokens, "dark")));
+  semanticLines.push("");
+  semanticLines.push(sectionComment("Hairline aliases (dark) \u2014 manual toggle"));
+  semanticLines.push(block(darkModeSelector, generateHairlineDecls(input.tokens, "dark")));
+  semanticLines.push("");
+  semanticLines.push(sectionComment("Intent aliases (dark) \u2014 prefers-color-scheme"));
+  {
+    const inner = block(prefersSelector, generateIntentDecls(input.tokens, "dark"));
+    semanticLines.push(`@media (prefers-color-scheme: dark) {
+${inner.split("\n").map((l) => `  ${l}`).join("\n")}
+}`);
+  }
+  semanticLines.push("");
+  semanticLines.push(sectionComment("Hairline aliases (dark) \u2014 prefers-color-scheme"));
+  {
+    const inner = block(prefersSelector, generateHairlineDecls(input.tokens, "dark"));
+    semanticLines.push(`@media (prefers-color-scheme: dark) {
+${inner.split("\n").map((l) => `  ${l}`).join("\n")}
+}`);
+  }
+  semanticLines.push("");
+  const semanticLayer = wrapInLayer("visor-semantic", semanticLines.join("\n").trim());
+  if (semanticLayer) {
+    lines.push(semanticLayer);
+    lines.push("");
+  }
   const lightBody = stripHeader(generateLightCss(input.tokens, { scopePrefix }));
   const darkBody = stripHeader(generateDarkCss(input.tokens, { scopePrefix }));
   lines.push(
@@ -415,7 +461,15 @@ function generateTypographyDecls(config, aliases) {
   for (const [name, value] of Object.entries(lineHeights)) {
     decls.push(`--line-height-${name}: ${value};`);
   }
-  decls.push("--letter-spacing-normal: 0.05em;");
+  const ls = config.typography["letter-spacing"];
+  decls.push(`--letter-spacing-xl: ${ls.xl};`);
+  decls.push(`--letter-spacing-lg: ${ls.lg};`);
+  decls.push(`--letter-spacing-md: ${ls.md};`);
+  decls.push(`--letter-spacing-sm: ${ls.sm};`);
+  decls.push(`--letter-spacing-xs: ${ls.xs};`);
+  decls.push(`--letter-spacing-tight: ${ls.tight};`);
+  decls.push(`--letter-spacing-normal: ${ls.md};`);
+  decls.push(`--letter-spacing-wide: ${ls.lg};`);
   return decls;
 }
 function generateShadowDecls(config) {
@@ -435,6 +489,7 @@ function generateMotionDecls(config) {
     "--motion-duration-300: 300ms;",
     `--motion-duration-500: ${config.motion["duration-slow"]};`,
     "--motion-duration-800: 800ms;",
+    "--motion-duration-1500: 1500ms;",
     "--motion-easing-linear: linear;",
     "--motion-easing-ease-in: cubic-bezier(0.4, 0, 1, 1);",
     "--motion-easing-ease-out: cubic-bezier(0, 0, 0.2, 1);",
@@ -489,7 +544,7 @@ function generateFumadocsBridgeDecls(tokens, mode) {
   }
   return decls;
 }
-function block(selector, decls) {
+function block2(selector, decls) {
   return [`${selector} {`, ...decls.map((d) => `  ${d}`), "}"].join("\n");
 }
 function sectionComment2(label) {
@@ -551,29 +606,29 @@ function docsAdapter(input, options) {
     "font-family: var(--font-sans);"
   ];
   lines.push(sectionComment2("Primitive: Colors"));
-  lines.push(block(scopeClass, [
+  lines.push(block2(scopeClass, [
     ...sharedDecls,
     "",
     ...generateColorDecls(input.primitives)
   ]));
   lines.push("");
   lines.push(sectionComment2("Primitive: Spacing"));
-  lines.push(block(scopeClass, generateSpacingDecls(input.config)));
+  lines.push(block2(scopeClass, generateSpacingDecls(input.config)));
   lines.push("");
   lines.push(sectionComment2("Primitive: Border Radius"));
-  lines.push(block(scopeClass, generateRadiusDecls(input.config)));
+  lines.push(block2(scopeClass, generateRadiusDecls(input.config)));
   lines.push("");
   lines.push(sectionComment2("Primitive: Typography"));
-  lines.push(block(scopeClass, generateTypographyDecls(input.config, aliasedFamilies)));
+  lines.push(block2(scopeClass, generateTypographyDecls(input.config, aliasedFamilies)));
   lines.push("");
   lines.push(sectionComment2("Primitive: Shadows"));
-  lines.push(block(scopeClass, generateShadowDecls(input.config)));
+  lines.push(block2(scopeClass, generateShadowDecls(input.config)));
   lines.push("");
   lines.push(sectionComment2("Primitive: Motion"));
-  lines.push(block(scopeClass, generateMotionDecls(input.config)));
+  lines.push(block2(scopeClass, generateMotionDecls(input.config)));
   lines.push("");
   lines.push(sectionComment2("Primitive: Miscellaneous"));
-  lines.push(block(scopeClass, generateMiscDecls()));
+  lines.push(block2(scopeClass, generateMiscDecls()));
   lines.push("");
   lines.push("\n/* \u2500\u2500 Section 2: Dark mode overrides \u2500\u2500 */");
   const darkDecls = generateSemanticDecls2(input.tokens, "dark");
@@ -597,7 +652,7 @@ function docsAdapter(input, options) {
   }
   if (darkPrimitiveOverrides.length > 0) {
     lines.push(sectionComment2("Primitive overrides (dark) \u2014 dark brand color anchors at shade 500"));
-    lines.push(block(`.dark ${scopeClass}`, darkPrimitiveOverrides));
+    lines.push(block2(`.dark ${scopeClass}`, darkPrimitiveOverrides));
     lines.push("");
   }
   const categories = ["Text", "Surface", "Border", "Interactive"];
@@ -609,7 +664,7 @@ function docsAdapter(input, options) {
   ];
   for (let i = 0; i < categories.length; i++) {
     lines.push(sectionComment2(`Adaptive: ${categories[i]} (dark) \u2014 manual toggle`));
-    lines.push(block(`.dark ${scopeClass}`, categoryDecls[i]));
+    lines.push(block2(`.dark ${scopeClass}`, categoryDecls[i]));
     lines.push("");
   }
   const pcsCategories = [
@@ -620,7 +675,7 @@ function docsAdapter(input, options) {
   ];
   for (const cat of pcsCategories) {
     lines.push(sectionComment2(`Adaptive: ${cat.label} (dark) \u2014 prefers-color-scheme`));
-    const inner = block(`${scopeClass}:not(.light):not(.theme-light):not([data-theme="light"])`, cat.entries);
+    const inner = block2(`${scopeClass}:not(.light):not(.theme-light):not([data-theme="light"])`, cat.entries);
     lines.push(`@media (prefers-color-scheme: dark) {
 ${inner.split("\n").map((l) => `  ${l}`).join("\n")}
 }`);
@@ -628,7 +683,7 @@ ${inner.split("\n").map((l) => `  ${l}`).join("\n")}
   }
   if (darkPrimitiveOverrides.length > 0) {
     lines.push(sectionComment2("Primitive overrides (dark) \u2014 prefers-color-scheme"));
-    const inner = block(`${scopeClass}:not(.light):not(.theme-light):not([data-theme="light"])`, darkPrimitiveOverrides);
+    const inner = block2(`${scopeClass}:not(.light):not(.theme-light):not([data-theme="light"])`, darkPrimitiveOverrides);
     lines.push(`@media (prefers-color-scheme: dark) {
 ${inner.split("\n").map((l) => `  ${l}`).join("\n")}
 }`);
@@ -643,38 +698,38 @@ ${inner.split("\n").map((l) => `  ${l}`).join("\n")}
   ];
   for (const cat of lightCategoryDecls) {
     lines.push(sectionComment2(`Adaptive: ${cat.label} (light)`));
-    lines.push(block(`html:not(.dark) ${scopeClass}`, cat.entries));
+    lines.push(block2(`html:not(.dark) ${scopeClass}`, cat.entries));
     lines.push("");
   }
   lines.push(sectionComment2("Fumadocs bridge: dark"));
-  lines.push(block(`.dark ${scopeClass}`, generateFumadocsBridgeDecls(input.tokens, "dark")));
+  lines.push(block2(`.dark ${scopeClass}`, generateFumadocsBridgeDecls(input.tokens, "dark")));
   lines.push("");
   lines.push(sectionComment2("Fumadocs bridge: light"));
-  lines.push(block(`html:not(.dark) ${scopeClass}`, generateFumadocsBridgeDecls(input.tokens, "light")));
+  lines.push(block2(`html:not(.dark) ${scopeClass}`, generateFumadocsBridgeDecls(input.tokens, "light")));
   lines.push("");
   const semanticLines = [];
   semanticLines.push("\n/* \u2500\u2500 Layer: Semantic aliases (VI-451) \u2500\u2500 */");
   semanticLines.push(sectionComment2("Discrete: Text size aliases (--text-N)"));
-  semanticLines.push(block(scopeClass, generateTextScaleAliasDecls()));
+  semanticLines.push(block2(scopeClass, generateTextScaleAliasDecls()));
   semanticLines.push("");
   semanticLines.push(sectionComment2("Discrete: Space aliases (--space-N)"));
-  semanticLines.push(block(scopeClass, generateSpaceAliasDecls(input.config)));
+  semanticLines.push(block2(scopeClass, generateSpaceAliasDecls(input.config)));
   semanticLines.push("");
   semanticLines.push(sectionComment2("Intent aliases (light)"));
-  semanticLines.push(block(`html:not(.dark) ${scopeClass}`, generateIntentDecls(input.tokens, "light")));
+  semanticLines.push(block2(`html:not(.dark) ${scopeClass}`, generateIntentDecls(input.tokens, "light")));
   semanticLines.push("");
   semanticLines.push(sectionComment2("Hairline aliases (light)"));
-  semanticLines.push(block(`html:not(.dark) ${scopeClass}`, generateHairlineDecls(input.tokens, "light")));
+  semanticLines.push(block2(`html:not(.dark) ${scopeClass}`, generateHairlineDecls(input.tokens, "light")));
   semanticLines.push("");
   semanticLines.push(sectionComment2("Intent aliases (dark) \u2014 manual toggle"));
-  semanticLines.push(block(`.dark ${scopeClass}`, generateIntentDecls(input.tokens, "dark")));
+  semanticLines.push(block2(`.dark ${scopeClass}`, generateIntentDecls(input.tokens, "dark")));
   semanticLines.push("");
   semanticLines.push(sectionComment2("Hairline aliases (dark) \u2014 manual toggle"));
-  semanticLines.push(block(`.dark ${scopeClass}`, generateHairlineDecls(input.tokens, "dark")));
+  semanticLines.push(block2(`.dark ${scopeClass}`, generateHairlineDecls(input.tokens, "dark")));
   semanticLines.push("");
   semanticLines.push(sectionComment2("Intent aliases (dark) \u2014 prefers-color-scheme"));
   {
-    const inner = block(`${scopeClass}:not(.light):not(.theme-light):not([data-theme="light"])`, generateIntentDecls(input.tokens, "dark"));
+    const inner = block2(`${scopeClass}:not(.light):not(.theme-light):not([data-theme="light"])`, generateIntentDecls(input.tokens, "dark"));
     semanticLines.push(`@media (prefers-color-scheme: dark) {
 ${inner.split("\n").map((l) => `  ${l}`).join("\n")}
 }`);
@@ -682,7 +737,7 @@ ${inner.split("\n").map((l) => `  ${l}`).join("\n")}
   semanticLines.push("");
   semanticLines.push(sectionComment2("Hairline aliases (dark) \u2014 prefers-color-scheme"));
   {
-    const inner = block(`${scopeClass}:not(.light):not(.theme-light):not([data-theme="light"])`, generateHairlineDecls(input.tokens, "dark"));
+    const inner = block2(`${scopeClass}:not(.light):not(.theme-light):not([data-theme="light"])`, generateHairlineDecls(input.tokens, "dark"));
     semanticLines.push(`@media (prefers-color-scheme: dark) {
 ${inner.split("\n").map((l) => `  ${l}`).join("\n")}
 }`);

package/dist/{chunk-YDRQQIOB.js → chunk-DQ256PSE.js}

@@ -1576,6 +1576,7 @@ function generateMotionPrimitives(config) {
   decls.push("--motion-duration-300: 300ms;");
   decls.push(`--motion-duration-500: ${config.motion["duration-slow"]};`);
   decls.push("--motion-duration-800: 800ms;");
+  decls.push("--motion-duration-1500: 1500ms;");
   decls.push("--motion-easing-linear: linear;");
   decls.push("--motion-easing-ease-in: cubic-bezier(0.4, 0, 1, 1);");
   decls.push("--motion-easing-ease-out: cubic-bezier(0, 0, 0.2, 1);");
@@ -1893,6 +1894,7 @@ export {
   hexToOklch,
   clampToSrgb,
   oklchToHex,
+  getLuminance,
   getContrastRatio,
   parseHex,
   parseRgba,
@@ -1914,6 +1916,7 @@ export {
   fontStack,
   header,
   sectionComment,
+  block2 as block,
   generatePrimitivesCss,
   generateSemanticCss,
   generateTextScaleAliasDecls,

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { F as FontResolveOptions, a as FontResolution, V as VisorTypography, b as FontDisplayStrategy, T as ThemeFontResult, G as GoogleFontEntry, c as VisorBrand, B as BrandSlot, d as BrandSource, e as BrandResolution, f as ThemeBrandResult, R as ResolvedThemeConfig, g as GeneratedPrimitives, h as ThemeOutput, i as ThemeData, j as VisorThemeConfig, k as FullShadeScale, C as ColorRole, S as SelectiveShadeScale, l as RGB, P as ParsedColor, O as OKLCH, m as SemanticTokens, n as ShadeStep } from './types-BDRXkldG.js';
-export { o as BRAND_VARIANTS, p as BrandVariant, q as ColorFormat, r as FontSource, s as RGBA, t as SemanticTokenValue } from './types-BDRXkldG.js';
+import { F as FontResolveOptions, a as FontResolution, V as VisorTypography, b as FontDisplayStrategy, T as ThemeFontResult, G as GoogleFontEntry, c as VisorBrand, B as BrandSlot, d as BrandSource, e as BrandResolution, f as ThemeBrandResult, R as ResolvedThemeConfig, g as GeneratedPrimitives, h as ThemeOutput, i as ThemeData, j as VisorThemeConfig, k as FullShadeScale, C as ColorRole, S as SelectiveShadeScale, l as RGB, P as ParsedColor, O as OKLCH, m as SemanticTokens, n as ShadeStep } from './types-zug1_eLX.js';
+export { o as BRAND_VARIANTS, p as BrandVariant, q as ColorFormat, r as FontSource, s as RGBA, t as SemanticTokenValue } from './types-zug1_eLX.js';
 
 /**
  * Font resolver — maps font family names to loadable font resources.
@@ -418,7 +418,7 @@ var properties = {
 				properties: {
 					family: {
 						type: "string",
-						description: "Google Fonts family name or CSS font stack."
+						description: "Font family name — Google Fonts name, Visor Fonts name, or CSS font stack."
 					},
 					weight: {
 						type: "integer",
@@ -433,7 +433,7 @@ var properties = {
 							"visor-fonts",
 							"local"
 						],
-						description: "Font source. Defaults to Google Fonts lookup, then local."
+						description: "Font source. Default: \"google-fonts\". Use \"visor-fonts\" for CDN-hosted fonts, \"local\" for self-hosted fonts."
 					},
 					org: {
 						type: "string",
@@ -448,7 +448,7 @@ var properties = {
 				properties: {
 					family: {
 						type: "string",
-						description: "Google Fonts family name or CSS font stack."
+						description: "Font family name — Google Fonts name, Visor Fonts name, or CSS font stack."
 					},
 					weight: {
 						type: "integer",
@@ -463,7 +463,7 @@ var properties = {
 							"visor-fonts",
 							"local"
 						],
-						description: "Font source. Defaults to Google Fonts lookup, then local."
+						description: "Font source. Default: \"google-fonts\". Use \"visor-fonts\" for CDN-hosted fonts, \"local\" for self-hosted fonts."
 					},
 					org: {
 						type: "string",
@@ -477,7 +477,7 @@ var properties = {
 				properties: {
 					family: {
 						type: "string",
-						description: "Google Fonts family name or CSS font stack."
+						description: "Font family name — Google Fonts name, Visor Fonts name, or CSS font stack."
 					},
 					weight: {
 						type: "integer",
@@ -492,7 +492,7 @@ var properties = {
 							"visor-fonts",
 							"local"
 						],
-						description: "Font source. Defaults to Google Fonts lookup, then local."
+						description: "Font source. Default: \"google-fonts\". Use \"visor-fonts\" for CDN-hosted fonts, \"local\" for self-hosted fonts."
 					},
 					org: {
 						type: "string",
@@ -514,19 +514,44 @@ var properties = {
 				type: "number",
 				description: "Type scale multiplier applied to the font-size ramp. Default: 1."
 			},
+			"text-on-light": {
+				type: "string",
+				description: "VI-375: text color placed on a LIGHT interactive background. Auto-picked for interactive *-text tokens whose paired *-bg has relative luminance > 0.5. Defaults to #FFFFFF (which deliberately still fails AA on a bright bg so the contrast validator flags it); set a readable near-black (e.g. #1E1F21) to clear the warning. Per-token overrides (overrides.{mode}.interactive-*-text) still win."
+			},
+			"text-on-dark": {
+				type: "string",
+				description: "VI-375: text color placed on a DARK interactive background. Auto-picked for interactive *-text tokens whose paired *-bg has relative luminance <= 0.5. Defaults to #FFFFFF. Per-token overrides still win."
+			},
 			"letter-spacing": {
 				type: "object",
-				description: "Letter spacing scale.",
+				description: "6-tier letter-spacing ramp (xl | lg | md | sm | xs | tight). Each value is a CSS length (e.g. \"0.1em\", \"0.44rem\", \"-0.01em\"). The legacy triad keys normal and wide remain valid for back-compat and map onto the ramp (normal->md, wide->lg, tight->tight).",
 				additionalProperties: false,
 				properties: {
+					xl: {
+						type: "string"
+					},
+					lg: {
+						type: "string"
+					},
+					md: {
+						type: "string"
+					},
+					sm: {
+						type: "string"
+					},
+					xs: {
+						type: "string"
+					},
 					tight: {
 						type: "string"
 					},
 					normal: {
-						type: "string"
+						type: "string",
+						description: "Deprecated legacy alias — maps to md."
 					},
 					wide: {
-						type: "string"
+						type: "string",
+						description: "Deprecated legacy alias — maps to lg."
 					}
 				}
 			},

package/dist/index.js

@@ -22,6 +22,7 @@ import {
   generateShadeScale,
   generateStylesheetLinks,
   getContrastRatio,
+  getLuminance,
   googleFontsCatalog,
   hasBrandPassthrough,
   hexToOklch,
@@ -45,7 +46,7 @@ import {
   rgbToHex,
   rgbToOklch,
   serializeColor
-} from "./chunk-YDRQQIOB.js";
+} from "./chunk-DQ256PSE.js";
 
 // src/fonts/validate-coverage.ts
 var FONT_VAR_RE = /--font-(heading|display|body|sans|mono)\s*:\s*([^;]+);/g;
@@ -307,7 +308,7 @@ var visor_theme_schema_default = {
           properties: {
             family: {
               type: "string",
-              description: "Google Fonts family name or CSS font stack."
+              description: "Font family name \u2014 Google Fonts name, Visor Fonts name, or CSS font stack."
             },
             weight: {
               type: "integer",
@@ -318,7 +319,7 @@ var visor_theme_schema_default = {
             source: {
               type: "string",
               enum: ["google-fonts", "visor-fonts", "local"],
-              description: "Font source. Defaults to Google Fonts lookup, then local."
+              description: 'Font source. Default: "google-fonts". Use "visor-fonts" for CDN-hosted fonts, "local" for self-hosted fonts.'
             },
             org: {
               type: "string",
@@ -333,7 +334,7 @@ var visor_theme_schema_default = {
           properties: {
             family: {
               type: "string",
-              description: "Google Fonts family name or CSS font stack."
+              description: "Font family name \u2014 Google Fonts name, Visor Fonts name, or CSS font stack."
             },
             weight: {
               type: "integer",
@@ -344,7 +345,7 @@ var visor_theme_schema_default = {
             source: {
               type: "string",
               enum: ["google-fonts", "visor-fonts", "local"],
-              description: "Font source. Defaults to Google Fonts lookup, then local."
+              description: 'Font source. Default: "google-fonts". Use "visor-fonts" for CDN-hosted fonts, "local" for self-hosted fonts.'
             },
             org: {
               type: "string",
@@ -358,7 +359,7 @@ var visor_theme_schema_default = {
           properties: {
             family: {
               type: "string",
-              description: "Google Fonts family name or CSS font stack."
+              description: "Font family name \u2014 Google Fonts name, Visor Fonts name, or CSS font stack."
             },
             weight: {
               type: "integer",
@@ -369,7 +370,7 @@ var visor_theme_schema_default = {
             source: {
               type: "string",
               enum: ["google-fonts", "visor-fonts", "local"],
-              description: "Font source. Defaults to Google Fonts lookup, then local."
+              description: 'Font source. Default: "google-fonts". Use "visor-fonts" for CDN-hosted fonts, "local" for self-hosted fonts.'
             },
             org: {
               type: "string",
@@ -391,14 +392,27 @@ var visor_theme_schema_default = {
           type: "number",
           description: "Type scale multiplier applied to the font-size ramp. Default: 1."
         },
+        "text-on-light": {
+          type: "string",
+          description: "VI-375: text color placed on a LIGHT interactive background. Auto-picked for interactive *-text tokens whose paired *-bg has relative luminance > 0.5. Defaults to #FFFFFF (which deliberately still fails AA on a bright bg so the contrast validator flags it); set a readable near-black (e.g. #1E1F21) to clear the warning. Per-token overrides (overrides.{mode}.interactive-*-text) still win."
+        },
+        "text-on-dark": {
+          type: "string",
+          description: "VI-375: text color placed on a DARK interactive background. Auto-picked for interactive *-text tokens whose paired *-bg has relative luminance <= 0.5. Defaults to #FFFFFF. Per-token overrides still win."
+        },
         "letter-spacing": {
           type: "object",
-          description: "Letter spacing scale.",
+          description: '6-tier letter-spacing ramp (xl | lg | md | sm | xs | tight). Each value is a CSS length (e.g. "0.1em", "0.44rem", "-0.01em"). The legacy triad keys normal and wide remain valid for back-compat and map onto the ramp (normal->md, wide->lg, tight->tight).',
           additionalProperties: false,
           properties: {
+            xl: { type: "string" },
+            lg: { type: "string" },
+            md: { type: "string" },
+            sm: { type: "string" },
+            xs: { type: "string" },
             tight: { type: "string" },
-            normal: { type: "string" },
-            wide: { type: "string" }
+            normal: { type: "string", description: "Deprecated legacy alias \u2014 maps to md." },
+            wide: { type: "string", description: "Deprecated legacy alias \u2014 maps to lg." }
           }
         },
         "cdn-overrides": {
@@ -695,12 +709,25 @@ var KNOWN_TYPOGRAPHY_KEYS = /* @__PURE__ */ new Set([
   "letter-spacing",
   "scale",
   "slots",
-  "cdn-overrides"
+  "cdn-overrides",
+  // VI-375: default text colors for interactive backgrounds (auto-picked by
+  // paired `*-bg` luminance; theme-overridable).
+  "text-on-light",
+  "text-on-dark"
 ]);
 var KNOWN_CDN_OVERRIDE_KEYS = /* @__PURE__ */ new Set(["visor-fonts"]);
 var KNOWN_TYPOGRAPHY_FONT_KEYS = /* @__PURE__ */ new Set(["family", "weight", "weights", "source", "org"]);
 var KNOWN_TYPOGRAPHY_MONO_KEYS = /* @__PURE__ */ new Set(["family", "weight", "weights", "source", "org"]);
-var KNOWN_LETTER_SPACING_KEYS = /* @__PURE__ */ new Set(["tight", "normal", "wide"]);
+var KNOWN_LETTER_SPACING_KEYS = /* @__PURE__ */ new Set([
+  "xl",
+  "lg",
+  "md",
+  "sm",
+  "xs",
+  "tight",
+  "normal",
+  "wide"
+]);
 var KNOWN_SLOT_NAMES = new Set(MATERIAL_TEXT_SLOTS);
 var KNOWN_SLOT_OVERRIDE_KEYS = /* @__PURE__ */ new Set(["size", "weight", "letter-spacing"]);
 var KNOWN_SPACING_KEYS = /* @__PURE__ */ new Set(["base"]);
@@ -780,6 +807,12 @@ function checkUnknownKeys(obj, errors) {
         }
       }
     }
+    for (const key of ["text-on-light", "text-on-dark"]) {
+      const value = typo[key];
+      if (value !== void 0 && (typeof value !== "string" || !isValidColor(value))) {
+        errors.push(`'typography.${key}' must be a valid CSS color (hex, rgba, hsla, or oklch)`);
+      }
+    }
     if (typeof typo["cdn-overrides"] === "object" && typo["cdn-overrides"] !== null) {
       for (const key of Object.keys(typo["cdn-overrides"])) {
         if (!KNOWN_CDN_OVERRIDE_KEYS.has(key)) {
@@ -1103,9 +1136,29 @@ var DEFAULTS = {
   },
   typography: {
     scale: 1,
+    // VI-375: default text colors for interactive backgrounds. Auto-picked for
+    // `*-text` tokens by the paired `*-bg` luminance. The defaults preserve the
+    // historical white-on-button behavior (both default to white), so a theme
+    // that only overrides a bright button bg STILL fails AA and raises a
+    // WCAG_CONTRAST warning — the operator must opt into a readable on-light
+    // color (e.g. ENTR's `text-on-light: "#1E1F21"`) to clear it. This keeps the
+    // fix loud rather than silently flipping every theme's button text.
+    "text-on-light": "#FFFFFF",
+    "text-on-dark": "#FFFFFF",
     heading: { family: DEFAULT_FONT_SANS, weight: 600 },
     body: { family: DEFAULT_FONT_SANS, weight: 400 },
-    mono: { family: DEFAULT_FONT_MONO }
+    mono: { family: DEFAULT_FONT_MONO },
+    // VI-447: default 6-tier letter-spacing ramp. em-based so it scales with
+    // type size; `md` is anchored at the historical `--letter-spacing-normal`
+    // value (0.05em) so existing themes emit byte-identical output.
+    "letter-spacing": {
+      xl: "0.16em",
+      lg: "0.1em",
+      md: "0.05em",
+      sm: "0.025em",
+      xs: "0.01em",
+      tight: "-0.01em"
+    }
   },
   spacing: { base: 4 },
   radius: { sm: 2, md: 4, lg: 8, xl: 12, pill: 9999 },
@@ -1146,6 +1199,17 @@ function resolveBrand(brand) {
     ...brand.custom && { custom: brand.custom }
   };
 }
+function resolveLetterSpacing(ls) {
+  const d = DEFAULTS.typography["letter-spacing"];
+  return {
+    xl: ls?.xl ?? d.xl,
+    lg: ls?.lg ?? ls?.wide ?? d.lg,
+    md: ls?.md ?? ls?.normal ?? d.md,
+    sm: ls?.sm ?? d.sm,
+    xs: ls?.xs ?? d.xs,
+    tight: ls?.tight ?? d.tight
+  };
+}
 function resolveConfig(config) {
   const colors = config.colors;
   const originalColors = {};
@@ -1194,6 +1258,8 @@ function resolveConfig(config) {
     "colors-dark": config["colors-dark"],
     typography: {
       scale: config.typography?.scale ?? DEFAULTS.typography.scale,
+      "text-on-light": config.typography?.["text-on-light"] ?? DEFAULTS.typography["text-on-light"],
+      "text-on-dark": config.typography?.["text-on-dark"] ?? DEFAULTS.typography["text-on-dark"],
       heading: {
         family: config.typography?.heading?.family ?? DEFAULTS.typography.heading.family,
         weight: config.typography?.heading?.weight ?? DEFAULTS.typography.heading.weight,
@@ -1225,7 +1291,8 @@ function resolveConfig(config) {
       ...config.typography?.["cdn-overrides"] && {
         "cdn-overrides": config.typography["cdn-overrides"]
       },
-      slots: config.typography?.slots ?? {}
+      slots: config.typography?.slots ?? {},
+      "letter-spacing": resolveLetterSpacing(config.typography?.["letter-spacing"])
     },
     brand: resolveBrand(config.brand),
     spacing: {
@@ -1274,6 +1341,10 @@ var CONFIG_BACKGROUND = "__CONFIG_BACKGROUND__";
 var CONFIG_SURFACE = "__CONFIG_SURFACE__";
 var CONFIG_DARK_BACKGROUND = "__CONFIG_DARK_BACKGROUND__";
 var CONFIG_DARK_SURFACE = "__CONFIG_DARK_SURFACE__";
+var DERIVE_ON_BG_PREFIX = "__DERIVE_ON_BG__";
+function deriveOnBg(pairedBgToken) {
+  return `${DERIVE_ON_BG_PREFIX}${pairedBgToken}`;
+}
 var SEMANTIC_TEXT_MAP = {
   primary: {
     light: { role: "neutral", shade: 900 },
@@ -1529,9 +1600,13 @@ var SEMANTIC_INTERACTIVE_MAP = {
     light: { role: "primary", shade: 800 },
     dark: { role: "primary", shade: 300 }
   },
+  // VI-375: was a hardcoded #ffffff constant in both modes — a blind spot that
+  // let a bright brand bg (ENTR dark mint) render white text at ~1.6:1. Now
+  // derives from the paired `primary-bg` luminance: light bg → text-on-light,
+  // dark bg → text-on-dark. Per-token override still wins.
   "primary-text": {
-    light: { constant: "#ffffff" },
-    dark: { constant: "#ffffff" }
+    light: { constant: deriveOnBg("primary-bg") },
+    dark: { constant: deriveOnBg("primary-bg") }
   },
   // VI-478: brand-derived alpha-overlay helpers (BL-193). `soft`/`glow` are
   // alpha overlays that track the theme's primary via color-mix (distinct from
@@ -1580,9 +1655,11 @@ var SEMANTIC_INTERACTIVE_MAP = {
     light: { role: "error", shade: 700 },
     dark: { role: "error", shade: 600 }
   },
+  // VI-375: derive from the paired `destructive-bg` luminance (was hardcoded
+  // #ffffff). Per-token override still wins.
   "destructive-text": {
-    light: { constant: "#ffffff" },
-    dark: { constant: "#ffffff" }
+    light: { constant: deriveOnBg("destructive-bg") },
+    dark: { constant: deriveOnBg("destructive-bg") }
   },
   // Ghost action
   "ghost-bg": {
@@ -1640,6 +1717,16 @@ var SEMANTIC_HAIRLINE_MAP = {
     dark: { constant: "rgba(255, 255, 255, 0.10)" }
   }
 };
+var INTERACTIVE_TEXT_BG_PAIRS = (() => {
+  const pairs = {};
+  for (const [name, mapping] of Object.entries(SEMANTIC_INTERACTIVE_MAP)) {
+    const light = mapping.light;
+    if ("constant" in light && light.constant.startsWith(DERIVE_ON_BG_PREFIX)) {
+      pairs[name] = light.constant.slice(DERIVE_ON_BG_PREFIX.length);
+    }
+  }
+  return pairs;
+})();
 var SEMANTIC_MAP = {
   text: SEMANTIC_TEXT_MAP,
   surface: SEMANTIC_SURFACE_MAP,
@@ -1677,6 +1764,66 @@ function resolveRef(ref, primitives, config) {
       return ref.constant;
   }
 }
+function pickTextForBg(bgValue, config) {
+  const parsed = parseColor(bgValue);
+  const luminance = parsed ? getLuminance(...parsed.rgb) : 0;
+  return luminance > 0.5 ? config.typography["text-on-light"] : config.typography["text-on-dark"];
+}
+function deriveInteractiveTextColors(interactive, config, opts = {}) {
+  const skip = opts.skipTokens ?? /* @__PURE__ */ new Set();
+  const modes = opts.modes ?? ["light", "dark"];
+  for (const [textToken, bgToken] of Object.entries(INTERACTIVE_TEXT_BG_PAIRS)) {
+    if (skip.has(textToken)) continue;
+    const textValue = interactive[textToken];
+    const bgValue = interactive[bgToken];
+    if (!textValue || !bgValue) continue;
+    const next = { ...textValue };
+    for (const mode of modes) {
+      next[mode] = pickTextForBg(bgValue[mode], config);
+    }
+    interactive[textToken] = next;
+  }
+}
+function reapplyInteractiveTextDerivation(tokens, config, overrides) {
+  if (!overrides) return tokens;
+  const skip = /* @__PURE__ */ new Set();
+  const bgOverriddenModes = /* @__PURE__ */ new Map();
+  for (const mode of ["light", "dark"]) {
+    const modeOverrides = overrides[mode];
+    if (!modeOverrides) continue;
+    for (const key of Object.keys(modeOverrides)) {
+      if (!key.startsWith("interactive-")) continue;
+      const tokenName = key.slice("interactive-".length);
+      if (tokenName in INTERACTIVE_TEXT_BG_PAIRS) {
+        skip.add(tokenName);
+      }
+      for (const [textToken, bgToken] of Object.entries(INTERACTIVE_TEXT_BG_PAIRS)) {
+        if (tokenName === bgToken) {
+          if (!bgOverriddenModes.has(textToken)) {
+            bgOverriddenModes.set(textToken, /* @__PURE__ */ new Set());
+          }
+          bgOverriddenModes.get(textToken).add(mode);
+        }
+      }
+    }
+  }
+  if (bgOverriddenModes.size === 0) return tokens;
+  const interactive = {};
+  for (const [name, value] of Object.entries(tokens.interactive)) {
+    interactive[name] = { ...value };
+  }
+  for (const [textToken, modes] of bgOverriddenModes) {
+    if (skip.has(textToken)) continue;
+    deriveInteractiveTextColors(interactive, config, {
+      // Re-derive only this token by skipping the others.
+      skipTokens: new Set(
+        Object.keys(INTERACTIVE_TEXT_BG_PAIRS).filter((t) => t !== textToken)
+      ),
+      modes: [...modes]
+    });
+  }
+  return { ...tokens, interactive };
+}
 function resolveMapping(mapping, lightPrimitives, darkPrimitives, config) {
   return {
     light: resolveRef(mapping.light, lightPrimitives, config),
@@ -1702,6 +1849,7 @@ function assignSemanticTokens(lightPrimitives, darkPrimitives, config) {
   for (const [name, mapping] of Object.entries(SEMANTIC_MAP.interactive)) {
     interactive[name] = resolveMapping(mapping, lightPrimitives, darkPrimitives, config);
   }
+  deriveInteractiveTextColors(interactive, config);
   for (const [name, mapping] of Object.entries(SEMANTIC_MAP.intent)) {
     intent[name] = resolveMapping(mapping, lightPrimitives, darkPrimitives, config);
   }
@@ -1770,6 +1918,7 @@ ${validation.errors.map((e) => `  - ${e}`).join("\n")}`
   const darkPrimitives = generateDarkPrimitives(resolved, primitives);
   let tokens = assignSemanticTokens(primitives, darkPrimitives, resolved);
   tokens = applyOverrides(tokens, resolved.overrides);
+  tokens = reapplyInteractiveTextDerivation(tokens, resolved, resolved.overrides);
   const output = {
     primitivesCss: generatePrimitivesCss(primitives, resolved),
     semanticCss: generateSemanticCss(tokens),
@@ -2193,7 +2342,7 @@ function checkTypeScaleCoherence(config, issues) {
 function checkLetterSpacing(config, issues) {
   const ls = config.typography?.["letter-spacing"];
   if (!ls) return;
-  for (const key of ["tight", "normal", "wide"]) {
+  for (const key of ["xl", "lg", "md", "sm", "xs", "tight", "normal", "wide"]) {
     const value = ls[key];
     if (value !== void 0) {
       if (typeof value !== "string" || !CSS_LENGTH_RE.test(value.trim())) {
@@ -2406,12 +2555,27 @@ function colorToRgb(color) {
 }
 var STANDARD_TEXT_TOKENS = ["primary", "secondary", "tertiary"];
 var STATUS_TEXT_TOKENS = ["error", "warning", "success", "info"];
+var INTERACTIVE_PAIRS_TO_VALIDATE = (() => {
+  const pairs = {};
+  for (const name of Object.keys(SEMANTIC_INTERACTIVE_MAP)) {
+    if (!name.endsWith("-text")) continue;
+    const bgToken = `${name.slice(0, -"-text".length)}-bg`;
+    if (bgToken in SEMANTIC_INTERACTIVE_MAP) {
+      pairs[name] = bgToken;
+    }
+  }
+  return pairs;
+})();
 function checkContrastWarnings(config, issues) {
   const resolved = resolveConfig(config);
   const lightPrimitives = generatePrimitives(resolved);
   const darkPrimitives = generateDarkPrimitives(resolved, lightPrimitives);
-  const tokens = applyOverrides(
-    assignSemanticTokens(lightPrimitives, darkPrimitives, resolved),
+  const tokens = reapplyInteractiveTextDerivation(
+    applyOverrides(
+      assignSemanticTokens(lightPrimitives, darkPrimitives, resolved),
+      resolved.overrides
+    ),
+    resolved,
     resolved.overrides
   );
   const lightBg = resolved.colors.background;
@@ -2474,7 +2638,10 @@ function checkContrastWarnings(config, issues) {
       );
     }
   }
-  const primaryOnBg = getContrastRatio(primary, lightBg, lightBgRgb);
+  const primaryBgToken = tokens.interactive["primary-bg"];
+  const lightPrimaryBg = primaryBgToken?.light ?? primary;
+  const darkPrimaryBg = primaryBgToken?.dark ?? darkPrimary;
+  const primaryOnBg = getContrastRatio(lightPrimaryBg, lightBg, lightBgRgb);
   if (primaryOnBg < CONTRAST_INTERACTIVE_AA) {
     issues.push(
       issue(
@@ -2485,7 +2652,7 @@ function checkContrastWarnings(config, issues) {
       )
     );
   }
-  const primaryOnSurface = getContrastRatio(primary, lightSurface, lightSurfaceRgb);
+  const primaryOnSurface = getContrastRatio(lightPrimaryBg, lightSurface, lightSurfaceRgb);
   if (primaryOnSurface < CONTRAST_INTERACTIVE_AA) {
     issues.push(
       issue(
@@ -2496,7 +2663,7 @@ function checkContrastWarnings(config, issues) {
       )
     );
   }
-  const darkPrimaryOnBg = getContrastRatio(darkPrimary, darkBg, darkBgRgb);
+  const darkPrimaryOnBg = getContrastRatio(darkPrimaryBg, darkBg, darkBgRgb);
   if (darkPrimaryOnBg < CONTRAST_INTERACTIVE_AA) {
     issues.push(
       issue(
@@ -2507,7 +2674,7 @@ function checkContrastWarnings(config, issues) {
       )
     );
   }
-  const darkPrimaryOnSurface = getContrastRatio(darkPrimary, darkSurface, darkSurfaceRgb);
+  const darkPrimaryOnSurface = getContrastRatio(darkPrimaryBg, darkSurface, darkSurfaceRgb);
   if (darkPrimaryOnSurface < CONTRAST_INTERACTIVE_AA) {
     issues.push(
       issue(
@@ -2518,6 +2685,33 @@ function checkContrastWarnings(config, issues) {
       )
     );
   }
+  for (const [textToken, bgToken] of Object.entries(INTERACTIVE_PAIRS_TO_VALIDATE)) {
+    const text = tokens.interactive[textToken];
+    const bg = tokens.interactive[bgToken];
+    if (!text || !bg) continue;
+    const lightRatio = getContrastRatio(text.light, bg.light, colorToRgb(bg.light));
+    if (lightRatio < CONTRAST_TEXT_AA) {
+      issues.push(
+        issue(
+          "warning",
+          "WCAG_CONTRAST",
+          `Light mode: interactive-${textToken} on interactive-${bgToken} has contrast ratio ${lightRatio.toFixed(2)}:1 (needs >= ${CONTRAST_TEXT_AA}:1)`,
+          `interactive.${textToken}`
+        )
+      );
+    }
+    const darkRatio = getContrastRatio(text.dark, bg.dark, colorToRgb(bg.dark));
+    if (darkRatio < CONTRAST_TEXT_AA) {
+      issues.push(
+        issue(
+          "warning",
+          "WCAG_CONTRAST",
+          `Dark mode: interactive-${textToken} on interactive-${bgToken} has contrast ratio ${darkRatio.toFixed(2)}:1 (needs >= ${CONTRAST_TEXT_AA}:1)`,
+          `interactive.${textToken}`
+        )
+      );
+    }
+  }
 }
 function checkColorSimilarity(config, issues) {
   const resolved = resolveConfig(config);

package/dist/{types-BDRXkldG.d.ts → types-zug1_eLX.d.ts}

@@ -294,6 +294,22 @@ interface VisorThemeConfig {
     };
     typography?: {
         scale?: number;
+        /**
+         * VI-375: text color placed on a LIGHT interactive background. Auto-picked
+         * for interactive `*-text` tokens whose paired `*-bg` resolves to a light
+         * color (relative luminance > 0.5). Defaults to `#FFFFFF` (preserving the
+         * historical white-on-button default, which deliberately still fails AA on
+         * a bright bg so the contrast validator flags it). Set a readable near-black
+         * (e.g. ENTR's `#1E1F21`) to clear the warning.
+         */
+        "text-on-light"?: string;
+        /**
+         * VI-375: text color placed on a DARK interactive background. Auto-picked
+         * for interactive `*-text` tokens whose paired `*-bg` resolves to a dark
+         * color (relative luminance <= 0.5). Theme-overridable. Defaults to
+         * `#FFFFFF`.
+         */
+        "text-on-dark"?: string;
         heading?: {
             family?: string;
             weight?: number;
@@ -322,9 +338,22 @@ interface VisorThemeConfig {
             source?: FontSource;
             org?: string;
         };
+        /**
+         * VI-447: 6-tier letter-spacing ramp (`xl | lg | md | sm | xs | tight`).
+         * Each value is a CSS length (e.g. `"0.1em"`, `"0.44rem"`, `"-0.01em"`).
+         * The legacy triad keys (`normal`, `wide`) stay valid for back-compat and
+         * map onto the ramp at resolve time (`normal`→md, `wide`→lg, `tight`→tight).
+         */
         "letter-spacing"?: {
+            xl?: string;
+            lg?: string;
+            md?: string;
+            sm?: string;
+            xs?: string;
             tight?: string;
+            /** @deprecated legacy alias — maps to `md`. */
             normal?: string;
+            /** @deprecated legacy alias — maps to `lg`. */
             wide?: string;
         };
         /**
@@ -429,6 +458,16 @@ interface ResolvedThemeConfig {
     "colors-dark"?: VisorThemeConfig["colors-dark"];
     typography: {
         scale: number;
+        /**
+         * VI-375: resolved default text color for LIGHT interactive backgrounds.
+         * Always present (defaults to `#1E1F21`); theme-overridable.
+         */
+        "text-on-light": string;
+        /**
+         * VI-375: resolved default text color for DARK interactive backgrounds.
+         * Always present (defaults to `#FFFFFF`); theme-overridable.
+         */
+        "text-on-dark": string;
         heading: {
             family: string;
             weight: number;
@@ -471,6 +510,19 @@ interface ResolvedThemeConfig {
          * consumes these; other adapters may ignore them.
          */
         slots: Partial<Record<MaterialTextSlot, TextSlotOverride>>;
+        /**
+         * VI-447: resolved 6-tier letter-spacing ramp. Always present — legacy
+         * triad input is folded onto the ramp and missing tiers fall back to the
+         * Visor default ramp, so every tier carries a CSS length.
+         */
+        "letter-spacing": {
+            xl: string;
+            lg: string;
+            md: string;
+            sm: string;
+            xs: string;
+            tight: string;
+        };
     };
     /**
      * Resolved brand block (VI-470). Always present — falls back to the Visor

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loworbitstudio/visor-theme-engine",
-  "version": "0.14.0",
+  "version": "0.15.1",
   "description": "Theme engine for the Visor design system — shade generation, token mapping, font resolution, and import/export for .visor.yaml themes.",
   "type": "module",
   "main": "./dist/index.js",

package/src/visor-theme.schema.json

@@ -100,7 +100,7 @@
           "properties": {
             "family": {
               "type": "string",
-              "description": "Google Fonts family name or CSS font stack."
+              "description": "Font family name — Google Fonts name, Visor Fonts name, or CSS font stack."
             },
             "weight": {
               "type": "integer",
@@ -111,7 +111,7 @@
             "source": {
               "type": "string",
               "enum": ["google-fonts", "visor-fonts", "local"],
-              "description": "Font source. Defaults to Google Fonts lookup, then local."
+              "description": "Font source. Default: \"google-fonts\". Use \"visor-fonts\" for CDN-hosted fonts, \"local\" for self-hosted fonts."
             },
             "org": {
               "type": "string",
@@ -126,7 +126,7 @@
           "properties": {
             "family": {
               "type": "string",
-              "description": "Google Fonts family name or CSS font stack."
+              "description": "Font family name — Google Fonts name, Visor Fonts name, or CSS font stack."
             },
             "weight": {
               "type": "integer",
@@ -137,7 +137,7 @@
             "source": {
               "type": "string",
               "enum": ["google-fonts", "visor-fonts", "local"],
-              "description": "Font source. Defaults to Google Fonts lookup, then local."
+              "description": "Font source. Default: \"google-fonts\". Use \"visor-fonts\" for CDN-hosted fonts, \"local\" for self-hosted fonts."
             },
             "org": {
               "type": "string",
@@ -151,7 +151,7 @@
           "properties": {
             "family": {
               "type": "string",
-              "description": "Google Fonts family name or CSS font stack."
+              "description": "Font family name — Google Fonts name, Visor Fonts name, or CSS font stack."
             },
             "weight": {
               "type": "integer",
@@ -162,7 +162,7 @@
             "source": {
               "type": "string",
               "enum": ["google-fonts", "visor-fonts", "local"],
-              "description": "Font source. Defaults to Google Fonts lookup, then local."
+              "description": "Font source. Default: \"google-fonts\". Use \"visor-fonts\" for CDN-hosted fonts, \"local\" for self-hosted fonts."
             },
             "org": {
               "type": "string",
@@ -184,14 +184,27 @@
           "type": "number",
           "description": "Type scale multiplier applied to the font-size ramp. Default: 1."
         },
+        "text-on-light": {
+          "type": "string",
+          "description": "VI-375: text color placed on a LIGHT interactive background. Auto-picked for interactive *-text tokens whose paired *-bg has relative luminance > 0.5. Defaults to #FFFFFF (which deliberately still fails AA on a bright bg so the contrast validator flags it); set a readable near-black (e.g. #1E1F21) to clear the warning. Per-token overrides (overrides.{mode}.interactive-*-text) still win."
+        },
+        "text-on-dark": {
+          "type": "string",
+          "description": "VI-375: text color placed on a DARK interactive background. Auto-picked for interactive *-text tokens whose paired *-bg has relative luminance <= 0.5. Defaults to #FFFFFF. Per-token overrides still win."
+        },
         "letter-spacing": {
           "type": "object",
-          "description": "Letter spacing scale.",
+          "description": "6-tier letter-spacing ramp (xl | lg | md | sm | xs | tight). Each value is a CSS length (e.g. \"0.1em\", \"0.44rem\", \"-0.01em\"). The legacy triad keys normal and wide remain valid for back-compat and map onto the ramp (normal->md, wide->lg, tight->tight).",
           "additionalProperties": false,
           "properties": {
+            "xl": { "type": "string" },
+            "lg": { "type": "string" },
+            "md": { "type": "string" },
+            "sm": { "type": "string" },
+            "xs": { "type": "string" },
             "tight": { "type": "string" },
-            "normal": { "type": "string" },
-            "wide": { "type": "string" }
+            "normal": { "type": "string", "description": "Deprecated legacy alias — maps to md." },
+            "wide": { "type": "string", "description": "Deprecated legacy alias — maps to lg." }
           }
         },
         "cdn-overrides": {