@loworbitstudio/visor-theme-engine 0.17.1 → 0.19.0

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, C as ColorScheme, f as ThemeBrandResult, g as BrandStrategy, h as BrandStrategyContext, i as BrandStrategyIssue, j as BrandStrategyValidationResult, S as SerializedBrandStrategy, R as ResolvedThemeConfig, k as GeneratedPrimitives, l as ThemeOutput, m as ThemeData, n as VisorThemeConfig, o as FullShadeScale, p as ColorRole, q as SelectiveShadeScale, r as RGB, P as ParsedColor, O as OKLCH, s as SemanticTokens, t as ShadeStep } from './types-Cvm7vFwe.js';
-export { u as BRAND_VARIANTS, v as BRAND_VISIBILITIES, w as BrandAccessibility, x as BrandArchetype, y as BrandBoilerplate, z as BrandColorPairing, A as BrandColorUsage, D as BrandContrastTarget, E as BrandGoverns, H as BrandLexiconEntry, I as BrandMessaging, J as BrandPersonalityTrait, K as BrandPillar, L as BrandPositioning, M as BrandStrategyIssueSeverity, N as BrandToneEntry, Q as BrandVariant, U as BrandVisibility, W as BrandVoice, X as BrandVoiceTrait, Y as ColorFormat, Z as DEFAULT_BRAND_STRATEGY_SURFACES, _ as DEFAULT_BRAND_STRATEGY_TONE_STATES, $ as FontSource, a0 as GOVERNS_WILDCARD, a1 as RGBA, a2 as SemanticTokenValue } from './types-Cvm7vFwe.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, C as ColorScheme, f as ThemeBrandResult, g as BrandStrategy, h as BrandStrategyContext, i as BrandStrategyIssue, j as BrandStrategyValidationResult, S as SerializedBrandStrategy, R as ResolvedThemeConfig, k as GeneratedPrimitives, l as ThemeOutput, m as ThemeData, n as VisorThemeConfig, o as FullShadeScale, p as ColorRole, q as SelectiveShadeScale, r as RGB, P as ParsedColor, O as OKLCH, s as SemanticTokens, t as ShadeStep } from './types-DF5StphJ.js';
+export { u as BRAND_VARIANTS, v as BRAND_VISIBILITIES, w as BrandAccessibility, x as BrandArchetype, y as BrandBoilerplate, z as BrandColorPairing, A as BrandColorUsage, D as BrandContrastTarget, E as BrandGoverns, H as BrandLexiconEntry, I as BrandMessaging, J as BrandPersonalityTrait, K as BrandPillar, L as BrandPositioning, M as BrandStrategyIssueSeverity, N as BrandToneEntry, Q as BrandVariant, U as BrandVisibility, W as BrandVoice, X as BrandVoiceTrait, Y as COMPONENT_TOKEN_FAMILIES, Z as COMPONENT_TOKEN_FAMILY_BY_NAME, _ as ColorFormat, $ as ComponentTokenBinding, a0 as ComponentTokenBindings, a1 as ComponentTokenConsumer, a2 as ComponentTokenFamily, a3 as ComponentTokenSpec, a4 as DEFAULT_BRAND_STRATEGY_SURFACES, a5 as DEFAULT_BRAND_STRATEGY_TONE_STATES, a6 as FontSource, a7 as GOVERNS_WILDCARD, a8 as RGBA, a9 as ResolvedComponentTokens, aa as SemanticTokenValue, ab as allComponentTokenNames, ac as componentTokenName, ad as hasComponentBindings, ae as resolveComponentBindings, af as validateComponentBindings } from './types-DF5StphJ.js';
 
 /**
  * Font resolver — maps font family names to loadable font resources.
@@ -1025,6 +1025,125 @@ var properties = {
 			}
 		}
 	},
+	components: {
+		type: "object",
+		description: "Component-scoped theme bindings for the admin-UI families (VI-625). Keyed by family, then by token key; the value is a string (both modes) or { light, dark }. Every token falls back to its Tier-1 expression, so omitting this block renders exactly as before. Key names are validated against the contract in component-tokens.ts.",
+		additionalProperties: false,
+		properties: {
+			table: {
+				type: "object",
+				description: "Table head, row and cell treatment. The retro measured the same header cell rendered four ways across one admin app; binding this family pins it once. Keys: font-size, text-color, head-height, head-padding-x, head-font-family, head-font-size, head-font-weight, head-letter-spacing, head-text-transform, head-color, head-bg, row-border, row-hover-bg, row-selected-bg, cell-padding, cell-font-size, cell-color, cell-bg, cell-border-top, footer-bg, caption-color.",
+				additionalProperties: {
+					$ref: "#/$defs/componentTokenBinding"
+				}
+			},
+			"data-table": {
+				type: "object",
+				description: "The admin-ui Tier-2 data-table surface stack (D3). Shared between the Table primitive and the DataTable shell so a list page and its table read as one surface. Keys: header-bg, row-bg, container-radius, container-shadow, row-py, cell-px, header-font-size.",
+				additionalProperties: {
+					$ref: "#/$defs/componentTokenBinding"
+				}
+			},
+			chip: {
+				type: "object",
+				description: "Chip / filter-pill treatment. The retro found the same mono status chip at 8.5 / 9 / 9.5 / 10 / 11px with tracking .03–.14em across nine implementations; this family is the single dial. Keys: radius, border, bg, text-color, font-family, font-weight, letter-spacing, text-transform, sm-height, sm-padding-x, sm-font-size, md-height, md-padding-x, md-font-size, lg-height, lg-padding-x, lg-font-size, selected-bg, selected-border-color, selected-text-color.",
+				additionalProperties: {
+					$ref: "#/$defs/componentTokenBinding"
+				}
+			},
+			badge: {
+				type: "object",
+				description: "Badge treatment — the D3 Tier-2 `--badge-text-transform` / `-letter-spacing` / `-font-size` / `-font-weight` set, promoted from the admin-ui audit to a bindable contract. Keys: radius, border, font-family, font-weight, text-transform, letter-spacing, font-size, md-padding, md-gap.",
+				additionalProperties: {
+					$ref: "#/$defs/componentTokenBinding"
+				}
+			},
+			"status-badge": {
+				type: "object",
+				description: "Status-badge indicator dot and the mono readout label. Chrome is inherited from the Badge family. Keys: dot-size, dot-radius, mono-font-family, mono-font-size, mono-letter-spacing.",
+				additionalProperties: {
+					$ref: "#/$defs/componentTokenBinding"
+				}
+			},
+			"filter-bar": {
+				type: "object",
+				description: "The operator's named case: \"the filter bar above the table in many admin pages was pretty different from one to the next; that should be streamlined.\" Keys: bg, border, radius, padding, gap, text-color, dense-padding, dense-gap, control-radius, results-font-size, results-color.",
+				additionalProperties: {
+					$ref: "#/$defs/componentTokenBinding"
+				}
+			},
+			"page-header": {
+				type: "object",
+				description: "Page-header lockup. The retro found the page title rendered five ways across one app. Keys: gap, text-color, leading-gap, eyebrow-font-size, eyebrow-font-weight, eyebrow-letter-spacing, eyebrow-text-transform, eyebrow-color, title-family, title-size, title-leading, title-font-size, title-font-weight, title-letter-spacing, title-color, description-font-size, description-color, actions-gap.",
+				additionalProperties: {
+					$ref: "#/$defs/componentTokenBinding"
+				}
+			},
+			"empty-state": {
+				type: "object",
+				description: "Empty-state placard — surface, icon chip and copy scale. Keys: radius, text-color, gap, padding, bg, border, icon-size, icon-radius, icon-bg, icon-color, heading-font-family, heading-font-size, heading-font-weight, heading-color, description-font-size, description-color, actions-gap.",
+				additionalProperties: {
+					$ref: "#/$defs/componentTokenBinding"
+				}
+			},
+			banner: {
+				type: "object",
+				description: "Full-width notice bar. The retro found six separate banner systems across ~180 instances in one app; binding this family collapses them to one. Keys: padding, gap, font-size, radius, border-width, shadow, title-font-weight, description-font-size, info-bg, info-text-color, info-border-color, warning-bg, warning-text-color, warning-border-color, error-bg, error-text-color, error-border-color, success-bg, success-text-color, success-border-color.",
+				additionalProperties: {
+					$ref: "#/$defs/componentTokenBinding"
+				}
+			},
+			sidebar: {
+				type: "object",
+				description: "Sidebar chrome and nav-item treatment. The palette roles (`bg`, `text`, `border`, `accent-*`) already ship defaults from visor-core's `visor-semantic` layer and are read bare; the structural roles below are new in VI-625. Keys: bg, text, text-muted, border, accent-bg, accent-text, header-padding, footer-padding, content-padding, menu-gap, group-label-height, group-label-font-size, group-label-font-weight, group-label-letter-spacing, group-label-text-transform, item-radius, item-gap, item-font-size, item-font-weight, item-letter-spacing, item-text-transform, item-height, item-padding, item-active-font-weight.",
+				additionalProperties: {
+					$ref: "#/$defs/componentTokenBinding"
+				}
+			},
+			tabs: {
+				type: "object",
+				description: "Tab rail and trigger treatment, for both the segmented (`default`) and underlined (`line`) variants. Keys: list-radius, list-height, list-padding, list-color, list-bg, line-border-bottom, trigger-radius, trigger-padding, trigger-font-size, trigger-font-weight, trigger-letter-spacing, trigger-text-transform, trigger-color, trigger-active-bg, trigger-active-color, trigger-active-shadow, indicator-height, indicator-color.",
+				additionalProperties: {
+					$ref: "#/$defs/componentTokenBinding"
+				}
+			},
+			skeleton: {
+				type: "object",
+				description: "Loading-placeholder shimmer and the content-shape geometry the admin list/table/detail skeletons use. Keys: from, to, radius, duration, logo-width, logo-height, pill-width, pill-height, line-h1-height, line-heading-height, line-body-height, avatar-size, avatar-lg-size, badge-width, badge-height, row-gap, row-padding, row-border-bottom.",
+				additionalProperties: {
+					$ref: "#/$defs/componentTokenBinding"
+				}
+			},
+			spinner: {
+				type: "object",
+				description: "Inline loading ring — track, leading edge, per-size geometry and cycle length. Keys: track-color, edge-color, primary-edge-color, radius, duration, xs-size, xs-border-width, sm-size, sm-border-width, md-size, md-border-width.",
+				additionalProperties: {
+					$ref: "#/$defs/componentTokenBinding"
+				}
+			},
+			checkbox: {
+				type: "object",
+				description: "Control sizing — the D3 Tier-2 `--checkbox-size` / `-radius` / `-bg` / `-border` set, promoted from the admin-ui audit to a bindable contract. Keys: size, radius, bg, border, bg-checked, border-checked.",
+				additionalProperties: {
+					$ref: "#/$defs/componentTokenBinding"
+				}
+			},
+			surface: {
+				type: "object",
+				description: "The D3 Tier-2 surface-scale extremes. `elev` is the elevated control tier the chip family already reads; `screen` is the deepest chrome tier consumed by admin pattern shells (`design-prototypes/admin-ui/tokens.css`) rather than by a Visor component. Keys: elev, screen.",
+				additionalProperties: {
+					$ref: "#/$defs/componentTokenBinding"
+				}
+			},
+			"admin-ui": {
+				type: "object",
+				description: "Structural roles the admin-ui pattern owns. `marquee-family` is the display face for KPI hero figures and marquee page titles — the role the admin-ui portability audit named as the one piece of ENTR brand coupling a new theme must rebind. Keys: marquee-family.",
+				additionalProperties: {
+					$ref: "#/$defs/componentTokenBinding"
+				}
+			}
+		}
+	},
 	migrate: {
 		type: "object",
 		description: "Migration metadata consumed by `visor migrate` commands. Does not affect CSS generation or theme application.",
@@ -1041,6 +1160,26 @@ var properties = {
 	}
 };
 var $defs = {
+	componentTokenBinding: {
+		description: "A component-token binding: one string for both modes, or per-mode values.",
+		oneOf: [
+			{
+				type: "string"
+			},
+			{
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					light: {
+						type: "string"
+					},
+					dark: {
+						type: "string"
+					}
+				}
+			}
+		]
+	},
 	cssColor: {
 		type: "string",
 		description: "CSS color value. Accepts hex (#RGB, #RRGGBB, #RRGGBBAA), rgb()/rgba(), hsl()/hsla(), or oklch() formats.",

package/dist/index.js

@@ -1,5 +1,7 @@
 import {
   BRAND_VARIANTS,
+  COMPONENT_TOKEN_FAMILIES,
+  COMPONENT_TOKEN_FAMILY_BY_NAME,
   DEFAULT_VISOR_BRAND,
   FONT_WEIGHT_ALIASES,
   MATERIAL_TEXT_SLOTS,
@@ -7,11 +9,13 @@ import {
   VISOR_BRANDS_CDN,
   VISOR_DEFAULT_BRAND_PATH,
   VISOR_FONTS_CDN,
+  allComponentTokenNames,
   applyOverrides,
   buildVisorBrandUrl,
   buildVisorFontUrl,
   clampToSrgb,
   collectBrandPassthrough,
+  componentTokenName,
   compositeOverBackground,
   generateDarkCss,
   generateFullBundleCss,
@@ -25,6 +29,7 @@ import {
   getLuminance,
   googleFontsCatalog,
   hasBrandPassthrough,
+  hasComponentBindings,
   hexToOklch,
   hexToRgb,
   isValidColor,
@@ -40,13 +45,15 @@ import {
   parseRgba,
   resolveBrandSlot,
   resolveBrandSource,
+  resolveComponentBindings,
   resolveFont,
   resolveThemeBrand,
   resolveThemeFonts,
   rgbToHex,
   rgbToOklch,
-  serializeColor
-} from "./chunk-BUWBBUFG.js";
+  serializeColor,
+  validateComponentBindings
+} from "./chunk-32DC5DAR.js";
 
 // src/fonts/validate-coverage.ts
 var FONT_VAR_RE = /--font-(heading|display|body|sans|mono)\s*:\s*([^;]+);/g;
@@ -1050,6 +1057,125 @@ var visor_theme_schema_default = {
         }
       }
     },
+    components: {
+      type: "object",
+      description: "Component-scoped theme bindings for the admin-UI families (VI-625). Keyed by family, then by token key; the value is a string (both modes) or { light, dark }. Every token falls back to its Tier-1 expression, so omitting this block renders exactly as before. Key names are validated against the contract in component-tokens.ts.",
+      additionalProperties: false,
+      properties: {
+        table: {
+          type: "object",
+          description: "Table head, row and cell treatment. The retro measured the same header cell rendered four ways across one admin app; binding this family pins it once. Keys: font-size, text-color, head-height, head-padding-x, head-font-family, head-font-size, head-font-weight, head-letter-spacing, head-text-transform, head-color, head-bg, row-border, row-hover-bg, row-selected-bg, cell-padding, cell-font-size, cell-color, cell-bg, cell-border-top, footer-bg, caption-color.",
+          additionalProperties: {
+            $ref: "#/$defs/componentTokenBinding"
+          }
+        },
+        "data-table": {
+          type: "object",
+          description: "The admin-ui Tier-2 data-table surface stack (D3). Shared between the Table primitive and the DataTable shell so a list page and its table read as one surface. Keys: header-bg, row-bg, container-radius, container-shadow, row-py, cell-px, header-font-size.",
+          additionalProperties: {
+            $ref: "#/$defs/componentTokenBinding"
+          }
+        },
+        chip: {
+          type: "object",
+          description: "Chip / filter-pill treatment. The retro found the same mono status chip at 8.5 / 9 / 9.5 / 10 / 11px with tracking .03\u2013.14em across nine implementations; this family is the single dial. Keys: radius, border, bg, text-color, font-family, font-weight, letter-spacing, text-transform, sm-height, sm-padding-x, sm-font-size, md-height, md-padding-x, md-font-size, lg-height, lg-padding-x, lg-font-size, selected-bg, selected-border-color, selected-text-color.",
+          additionalProperties: {
+            $ref: "#/$defs/componentTokenBinding"
+          }
+        },
+        badge: {
+          type: "object",
+          description: "Badge treatment \u2014 the D3 Tier-2 `--badge-text-transform` / `-letter-spacing` / `-font-size` / `-font-weight` set, promoted from the admin-ui audit to a bindable contract. Keys: radius, border, font-family, font-weight, text-transform, letter-spacing, font-size, md-padding, md-gap.",
+          additionalProperties: {
+            $ref: "#/$defs/componentTokenBinding"
+          }
+        },
+        "status-badge": {
+          type: "object",
+          description: "Status-badge indicator dot and the mono readout label. Chrome is inherited from the Badge family. Keys: dot-size, dot-radius, mono-font-family, mono-font-size, mono-letter-spacing.",
+          additionalProperties: {
+            $ref: "#/$defs/componentTokenBinding"
+          }
+        },
+        "filter-bar": {
+          type: "object",
+          description: `The operator's named case: "the filter bar above the table in many admin pages was pretty different from one to the next; that should be streamlined." Keys: bg, border, radius, padding, gap, text-color, dense-padding, dense-gap, control-radius, results-font-size, results-color.`,
+          additionalProperties: {
+            $ref: "#/$defs/componentTokenBinding"
+          }
+        },
+        "page-header": {
+          type: "object",
+          description: "Page-header lockup. The retro found the page title rendered five ways across one app. Keys: gap, text-color, leading-gap, eyebrow-font-size, eyebrow-font-weight, eyebrow-letter-spacing, eyebrow-text-transform, eyebrow-color, title-family, title-size, title-leading, title-font-size, title-font-weight, title-letter-spacing, title-color, description-font-size, description-color, actions-gap.",
+          additionalProperties: {
+            $ref: "#/$defs/componentTokenBinding"
+          }
+        },
+        "empty-state": {
+          type: "object",
+          description: "Empty-state placard \u2014 surface, icon chip and copy scale. Keys: radius, text-color, gap, padding, bg, border, icon-size, icon-radius, icon-bg, icon-color, heading-font-family, heading-font-size, heading-font-weight, heading-color, description-font-size, description-color, actions-gap.",
+          additionalProperties: {
+            $ref: "#/$defs/componentTokenBinding"
+          }
+        },
+        banner: {
+          type: "object",
+          description: "Full-width notice bar. The retro found six separate banner systems across ~180 instances in one app; binding this family collapses them to one. Keys: padding, gap, font-size, radius, border-width, shadow, title-font-weight, description-font-size, info-bg, info-text-color, info-border-color, warning-bg, warning-text-color, warning-border-color, error-bg, error-text-color, error-border-color, success-bg, success-text-color, success-border-color.",
+          additionalProperties: {
+            $ref: "#/$defs/componentTokenBinding"
+          }
+        },
+        sidebar: {
+          type: "object",
+          description: "Sidebar chrome and nav-item treatment. The palette roles (`bg`, `text`, `border`, `accent-*`) already ship defaults from visor-core's `visor-semantic` layer and are read bare; the structural roles below are new in VI-625. Keys: bg, text, text-muted, border, accent-bg, accent-text, header-padding, footer-padding, content-padding, menu-gap, group-label-height, group-label-font-size, group-label-font-weight, group-label-letter-spacing, group-label-text-transform, item-radius, item-gap, item-font-size, item-font-weight, item-letter-spacing, item-text-transform, item-height, item-padding, item-active-font-weight.",
+          additionalProperties: {
+            $ref: "#/$defs/componentTokenBinding"
+          }
+        },
+        tabs: {
+          type: "object",
+          description: "Tab rail and trigger treatment, for both the segmented (`default`) and underlined (`line`) variants. Keys: list-radius, list-height, list-padding, list-color, list-bg, line-border-bottom, trigger-radius, trigger-padding, trigger-font-size, trigger-font-weight, trigger-letter-spacing, trigger-text-transform, trigger-color, trigger-active-bg, trigger-active-color, trigger-active-shadow, indicator-height, indicator-color.",
+          additionalProperties: {
+            $ref: "#/$defs/componentTokenBinding"
+          }
+        },
+        skeleton: {
+          type: "object",
+          description: "Loading-placeholder shimmer and the content-shape geometry the admin list/table/detail skeletons use. Keys: from, to, radius, duration, logo-width, logo-height, pill-width, pill-height, line-h1-height, line-heading-height, line-body-height, avatar-size, avatar-lg-size, badge-width, badge-height, row-gap, row-padding, row-border-bottom.",
+          additionalProperties: {
+            $ref: "#/$defs/componentTokenBinding"
+          }
+        },
+        spinner: {
+          type: "object",
+          description: "Inline loading ring \u2014 track, leading edge, per-size geometry and cycle length. Keys: track-color, edge-color, primary-edge-color, radius, duration, xs-size, xs-border-width, sm-size, sm-border-width, md-size, md-border-width.",
+          additionalProperties: {
+            $ref: "#/$defs/componentTokenBinding"
+          }
+        },
+        checkbox: {
+          type: "object",
+          description: "Control sizing \u2014 the D3 Tier-2 `--checkbox-size` / `-radius` / `-bg` / `-border` set, promoted from the admin-ui audit to a bindable contract. Keys: size, radius, bg, border, bg-checked, border-checked.",
+          additionalProperties: {
+            $ref: "#/$defs/componentTokenBinding"
+          }
+        },
+        surface: {
+          type: "object",
+          description: "The D3 Tier-2 surface-scale extremes. `elev` is the elevated control tier the chip family already reads; `screen` is the deepest chrome tier consumed by admin pattern shells (`design-prototypes/admin-ui/tokens.css`) rather than by a Visor component. Keys: elev, screen.",
+          additionalProperties: {
+            $ref: "#/$defs/componentTokenBinding"
+          }
+        },
+        "admin-ui": {
+          type: "object",
+          description: "Structural roles the admin-ui pattern owns. `marquee-family` is the display face for KPI hero figures and marquee page titles \u2014 the role the admin-ui portability audit named as the one piece of ENTR brand coupling a new theme must rebind. Keys: marquee-family.",
+          additionalProperties: {
+            $ref: "#/$defs/componentTokenBinding"
+          }
+        }
+      }
+    },
     migrate: {
       type: "object",
       description: "Migration metadata consumed by `visor migrate` commands. Does not affect CSS generation or theme application.",
@@ -1064,6 +1190,20 @@ var visor_theme_schema_default = {
     }
   },
   $defs: {
+    componentTokenBinding: {
+      description: "A component-token binding: one string for both modes, or per-mode values.",
+      oneOf: [
+        { type: "string" },
+        {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            light: { type: "string" },
+            dark: { type: "string" }
+          }
+        }
+      ]
+    },
     cssColor: {
       type: "string",
       description: "CSS color value. Accepts hex (#RGB, #RRGGBB, #RRGGBBAA), rgb()/rgba(), hsl()/hsla(), or oklch() formats.",
@@ -1310,7 +1450,8 @@ var KNOWN_TOP_LEVEL_KEYS = /* @__PURE__ */ new Set([
   "shadows",
   "strokeWidths",
   "motion",
-  "overrides"
+  "overrides",
+  "components"
 ]);
 var KNOWN_COLOR_KEYS = /* @__PURE__ */ new Set([
   "primary",
@@ -1557,6 +1698,9 @@ function checkUnknownKeys(obj, errors) {
       }
     }
   }
+  if (obj.components !== void 0) {
+    errors.push(...validateComponentBindings(obj.components));
+  }
 }
 function validateConfig(config) {
   const errors = [];
@@ -1964,6 +2108,9 @@ function resolveConfig(config) {
       ...config.motion?.["easing-overshoot"] !== void 0 ? { "easing-overshoot": config.motion["easing-overshoot"] } : {}
     },
     overrides: config.overrides,
+    // VI-625: component bindings pass through untouched — the contract in
+    // component-tokens.ts owns their shape, there is nothing to default.
+    components: config.components,
     originalColors,
     colorFormats
   };
@@ -2717,6 +2864,9 @@ function exportTheme(primitives, config) {
       output.overrides = overrides;
     }
   }
+  if (config.components && Object.keys(config.components).length > 0) {
+    output.components = config.components;
+  }
   return stringifyYaml(output, { lineWidth: 0 });
 }
 
@@ -4054,6 +4204,8 @@ function extractFromCSS(files, name = "extracted-theme") {
 export {
   BRAND_VARIANTS,
   BRAND_VISIBILITIES,
+  COMPONENT_TOKEN_FAMILIES,
+  COMPONENT_TOKEN_FAMILY_BY_NAME,
   DEFAULT_BRAND_STRATEGY_SURFACES,
   DEFAULT_BRAND_STRATEGY_TONE_STATES,
   DEFAULT_VISOR_BRAND,
@@ -4064,6 +4216,7 @@ export {
   VISOR_BRANDS_CDN,
   VISOR_DEFAULT_BRAND_PATH,
   VISOR_FONTS_CDN,
+  allComponentTokenNames,
   applyOverrides,
   assignSemanticTokens,
   buildVisorBrandUrl,
@@ -4073,6 +4226,7 @@ export {
   clampToSrgb,
   cleanFontValue,
   collectBrandPassthrough,
+  componentTokenName,
   compositeOverBackground,
   exportTheme,
   extractFromCSS,
@@ -4095,6 +4249,7 @@ export {
   getLuminance,
   googleFontsCatalog,
   hasBrandPassthrough,
+  hasComponentBindings,
   hexToOklch,
   hexToRgb,
   isValidColor,
@@ -4114,6 +4269,7 @@ export {
   parseRgba,
   resolveBrandSlot,
   resolveBrandSource,
+  resolveComponentBindings,
   resolveConfig,
   resolveFont,
   resolveThemeBrand,
@@ -4123,6 +4279,7 @@ export {
   serializeColor,
   validate,
   validateBrandStrategy,
+  validateComponentBindings,
   validateConfig,
   validateFontCoverage,
   visor_theme_schema_default as visorThemeSchema

package/dist/{types-Cvm7vFwe.d.ts → types-DF5StphJ.d.ts}

@@ -446,6 +446,157 @@ interface BrandStrategyContext {
     states?: ReadonlySet<string>;
 }
 
+/**
+ * Component-scoped theme-bindable token contract (VI-625).
+ *
+ * Visor themes have always been able to repaint the Tier-1 semantic surface
+ * (`--surface-*`, `--text-*`, `--border-*`, `--interactive-*`). That is enough
+ * to make an admin UI *functional*, but not enough to make it *look like one
+ * thing*: nothing stopped a page inventing its own table-header treatment, its
+ * own chip tracking, its own filter-bar padding. The AN-366 Fidelity-Mirror
+ * retro measured the result — 247 element categories across 13 families whose
+ * inconsistency traced to the substrate, not to any one component.
+ *
+ * This module is the answer: a **contract**, not new components. For every
+ * family in the admin kit it names the component-scoped custom properties a
+ * theme may bind, and — critically — the Tier-1 expression each one falls back
+ * to when the theme is silent.
+ *
+ * ## The two invariants
+ *
+ * 1. **Unbound renders identically.** Every token is consumed by its component
+ *    as `var(--<token>, <fallback>)` where `<fallback>` is byte-for-byte the
+ *    expression that shipped before the token existed. A theme that binds
+ *    nothing is pixel-identical to a theme from before this contract.
+ * 2. **Bound changes everything at once.** A theme that binds a token retunes
+ *    every consuming surface in one place, instead of each page re-deriving the
+ *    look in local CSS.
+ *
+ * Both are enforced by tests, not prose — see
+ * `components/ui/__tests__/component-token-contract.test.ts`.
+ *
+ * ## Authoring
+ *
+ * ```yaml
+ * # my-theme.visor.yaml
+ * components:
+ *   table:
+ *     head-height: "2.5rem"
+ *     head-text-transform: uppercase
+ *     head-letter-spacing: "0.06em"
+ *     head-bg:
+ *       light: "#f7f7f8"
+ *       dark: "#141418"
+ *   chip:
+ *     md-font-size: "11px"
+ *     letter-spacing: "0.04em"
+ * ```
+ *
+ * A bare string binds both modes; `{ light, dark }` binds them independently.
+ *
+ * ## Prior art
+ *
+ * VI-620 / VI-621 did exactly this for the dialog substrate
+ * (`--dialog-form-panel-border`, `--field-control-bg`, `--input-*`) and the
+ * field language stayed consistent across all twelve modals. This extends the
+ * same move to the page-level families. D3 additionally promotes the Playbook's
+ * admin-ui Tier-2 treatment layer
+ * (`design-prototypes/admin-ui/audits/admin-ui-theme-portability.md`) from prose
+ * in an audit doc to a first-class bindable contract.
+ *
+ * NOTE: this module is intentionally dependency-free (pure data + types) so it
+ * can be imported from the engine, from repo-root component tests, and from
+ * docs tooling without pulling in the pipeline.
+ */
+/** A single consuming declaration of a component-scoped token. */
+interface ComponentTokenConsumer {
+    /** Repo-relative path of the CSS module that reads the token. */
+    file: string;
+    /**
+     * The exact fallback expression the component uses, i.e. the `X` in
+     * `var(--token, X)`. `null` means the token is read bare (`var(--token)`)
+     * because a default is supplied elsewhere — visor-core's `visor-semantic`
+     * layer for the `--sidebar-*` palette roles.
+     */
+    fallback: string | null;
+}
+/** One theme-bindable, component-scoped custom property. */
+interface ComponentTokenSpec {
+    /** Key under `components.<family>` in `.visor.yaml`. */
+    key: string;
+    /** The CSS property (or properties) the token drives — documentation only. */
+    property: string;
+    /** What binding this token achieves, in one line. */
+    description: string;
+    /**
+     * Every place a Visor component reads this token. An empty array marks an
+     * **emit-only role**: the engine can emit it so a generated theme carries it,
+     * but the consumer is a pattern shell (the admin-ui prototype layer), not a
+     * Visor component.
+     */
+    consumers: ComponentTokenConsumer[];
+    /** Recommended value for an emit-only role, for the docs table. */
+    recommended?: string;
+}
+/** A family of component-scoped tokens a theme can bind as a unit. */
+interface ComponentTokenFamily {
+    /** Key under `components:` in `.visor.yaml`. */
+    family: string;
+    /**
+     * Custom-property prefix. The emitted name is `--<prefix>-<key>`.
+     * Every family declares one — there are no verbatim-key families.
+     */
+    prefix: string;
+    /** One-line summary for the docs page. */
+    description: string;
+    tokens: ComponentTokenSpec[];
+}
+/** Emitted custom-property name (without the leading `--`) for a family key. */
+declare function componentTokenName(family: ComponentTokenFamily, key: string): string;
+/**
+ * The full contract, in the D2 priority order the retro measured.
+ *
+ * Adding a family here is the ONLY registration step: the schema validator, the
+ * CSS emitter, the docs page test and the fallback-parity test all read this
+ * array.
+ */
+declare const COMPONENT_TOKEN_FAMILIES: readonly ComponentTokenFamily[];
+/** Family lookup by `.visor.yaml` key. */
+declare const COMPONENT_TOKEN_FAMILY_BY_NAME: ReadonlyMap<string, ComponentTokenFamily>;
+/** Every emitted custom-property name in the contract, without the `--`. */
+declare function allComponentTokenNames(): string[];
+/** A binding value: one string for both modes, or per-mode values. */
+type ComponentTokenBinding = string | {
+    light?: string;
+    dark?: string;
+};
+/** The `components:` block of a `.visor.yaml`. */
+type ComponentTokenBindings = Record<string, Record<string, ComponentTokenBinding>>;
+/** Resolved per-mode custom properties, keyed by name without the `--`. */
+interface ResolvedComponentTokens {
+    light: Record<string, string>;
+    dark: Record<string, string>;
+}
+/**
+ * Flatten a `components:` block into per-mode `--<name>: <value>` pairs.
+ *
+ * Unknown families / keys are skipped — `validateComponentBindings` is the place
+ * that reports them, so this stays a pure projection.
+ */
+declare function resolveComponentBindings(bindings: ComponentTokenBindings | undefined): ResolvedComponentTokens;
+/** True when any component token is bound. */
+declare function hasComponentBindings(bindings: ComponentTokenBindings | undefined): boolean;
+/**
+ * Validate a `components:` block against the contract.
+ *
+ * Returns human-readable error strings — unknown family, unknown key, or a value
+ * that is neither a string nor a `{ light, dark }` pair. An unknown key is an
+ * ERROR rather than a warning on purpose: a typo'd component token is silently
+ * inert at runtime (the component keeps resolving its fallback), which is
+ * exactly the failure mode this contract exists to end.
+ */
+declare function validateComponentBindings(bindings: unknown): string[];
+
 /**
  * Types for the Visor Theme Engine
  *
@@ -663,6 +814,16 @@ interface VisorThemeConfig {
         light?: Record<string, string>;
         dark?: Record<string, string>;
     };
+    /**
+     * VI-625: component-scoped theme bindings for the admin-UI families.
+     *
+     * Keyed by family (`table`, `chip`, `filter-bar`, …) then by token key; the
+     * value is a string (both modes) or `{ light, dark }`. Every key is declared
+     * in `component-tokens.ts`, and every consuming component falls back to its
+     * Tier-1 expression, so a theme that omits this block renders exactly as it
+     * did before the contract existed.
+     */
+    components?: ComponentTokenBindings;
     /**
      * Migration metadata — optional, additive, consumed by `visor migrate` commands.
      * Does not affect CSS generation or theme application.
@@ -813,6 +974,8 @@ interface ResolvedThemeConfig {
         light?: Record<string, string>;
         dark?: Record<string, string>;
     };
+    /** VI-625: component-scoped theme bindings, carried through unchanged. */
+    components?: ComponentTokenBindings;
     /** Original color strings from user input, for round-trip export. */
     originalColors?: Record<string, string>;
     /** Color format of each user-provided color, keyed by field name. */
@@ -854,4 +1017,4 @@ interface ThemeData {
     output: ThemeOutput;
 }
 
-export { type FontSource as $, type BrandColorUsage as A, type BrandSlot as B, type ColorScheme as C, type BrandContrastTarget as D, type BrandGoverns as E, type FontResolveOptions as F, type GoogleFontEntry as G, type BrandLexiconEntry as H, type BrandMessaging as I, type BrandPersonalityTrait as J, type BrandPillar as K, type BrandPositioning as L, type BrandStrategyIssueSeverity as M, type BrandToneEntry as N, type OKLCH as O, type ParsedColor as P, type BrandVariant as Q, type ResolvedThemeConfig as R, type SerializedBrandStrategy as S, type ThemeFontResult as T, type BrandVisibility as U, type VisorTypography as V, type BrandVoice as W, type BrandVoiceTrait as X, type ColorFormat as Y, DEFAULT_BRAND_STRATEGY_SURFACES as Z, DEFAULT_BRAND_STRATEGY_TONE_STATES as _, type FontResolution as a, GOVERNS_WILDCARD as a0, type RGBA as a1, type SemanticTokenValue as a2, type FontDisplayStrategy as b, type VisorBrand as c, type BrandSource as d, type BrandResolution as e, type ThemeBrandResult as f, type BrandStrategy as g, type BrandStrategyContext as h, type BrandStrategyIssue as i, type BrandStrategyValidationResult as j, type GeneratedPrimitives as k, type ThemeOutput as l, type ThemeData as m, type VisorThemeConfig as n, type FullShadeScale as o, type ColorRole as p, type SelectiveShadeScale as q, type RGB as r, type SemanticTokens as s, type ShadeStep as t, BRAND_VARIANTS as u, BRAND_VISIBILITIES as v, type BrandAccessibility as w, type BrandArchetype as x, type BrandBoilerplate as y, type BrandColorPairing as z };
+export { type ComponentTokenBinding as $, type BrandColorUsage as A, type BrandSlot as B, type ColorScheme as C, type BrandContrastTarget as D, type BrandGoverns as E, type FontResolveOptions as F, type GoogleFontEntry as G, type BrandLexiconEntry as H, type BrandMessaging as I, type BrandPersonalityTrait as J, type BrandPillar as K, type BrandPositioning as L, type BrandStrategyIssueSeverity as M, type BrandToneEntry as N, type OKLCH as O, type ParsedColor as P, type BrandVariant as Q, type ResolvedThemeConfig as R, type SerializedBrandStrategy as S, type ThemeFontResult as T, type BrandVisibility as U, type VisorTypography as V, type BrandVoice as W, type BrandVoiceTrait as X, COMPONENT_TOKEN_FAMILIES as Y, COMPONENT_TOKEN_FAMILY_BY_NAME as Z, type ColorFormat as _, type FontResolution as a, type ComponentTokenBindings as a0, type ComponentTokenConsumer as a1, type ComponentTokenFamily as a2, type ComponentTokenSpec as a3, DEFAULT_BRAND_STRATEGY_SURFACES as a4, DEFAULT_BRAND_STRATEGY_TONE_STATES as a5, type FontSource as a6, GOVERNS_WILDCARD as a7, type RGBA as a8, type ResolvedComponentTokens as a9, type SemanticTokenValue as aa, allComponentTokenNames as ab, componentTokenName as ac, hasComponentBindings as ad, resolveComponentBindings as ae, validateComponentBindings as af, type FontDisplayStrategy as b, type VisorBrand as c, type BrandSource as d, type BrandResolution as e, type ThemeBrandResult as f, type BrandStrategy as g, type BrandStrategyContext as h, type BrandStrategyIssue as i, type BrandStrategyValidationResult as j, type GeneratedPrimitives as k, type ThemeOutput as l, type ThemeData as m, type VisorThemeConfig as n, type FullShadeScale as o, type ColorRole as p, type SelectiveShadeScale as q, type RGB as r, type SemanticTokens as s, type ShadeStep as t, BRAND_VARIANTS as u, BRAND_VISIBILITIES as v, type BrandAccessibility as w, type BrandArchetype as x, type BrandBoilerplate as y, type BrandColorPairing as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loworbitstudio/visor-theme-engine",
-  "version": "0.17.1",
+  "version": "0.19.0",
   "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",