@loworbitstudio/visor-theme-engine 0.1.0 → 0.4.0

package/README.md

@@ -0,0 +1,29 @@
+# @loworbitstudio/visor-theme-engine
+
+Theme engine for the [Visor](https://visor.loworbit.studio) design system — shade generation, token mapping, font resolution, and import/export for `.visor.yaml` themes.
+
+## Installation
+
+```bash
+npm install @loworbitstudio/visor-theme-engine
+```
+
+## What It Does
+
+- Generates dark and light color scales from a brand anchor color using OKLCH
+- Maps theme configuration (`.visor.yaml`) to CSS custom properties
+- Resolves font declarations against the Visor fonts CDN
+- Exports theme bundles for use in any project
+- Provides a `docsAdapter` for registering themes in fumadocs sites
+
+## Usage
+
+Themes are typically managed via the Visor CLI (`visor theme sync`). Direct API usage is for advanced cases — building custom theme tooling or integrating with non-CLI workflows.
+
+```ts
+import { generateTheme } from '@loworbitstudio/visor-theme-engine'
+```
+
+## Documentation
+
+Full docs at [visor.loworbit.studio](https://visor.loworbit.studio).

package/dist/adapters/index.d.ts

@@ -1,4 +1,4 @@
-import { c as GeneratedPrimitives, i as SemanticTokens, R as ResolvedThemeConfig } from '../types-r7ae3WP2.js';
+import { c as GeneratedPrimitives, i as SemanticTokens, R as ResolvedThemeConfig } from '../types-DgAumoCX.js';
 
 /**
  * Adapter types for the Visor theme engine.

package/dist/adapters/index.js

@@ -5,10 +5,11 @@ import {
   generateDarkCss,
   generateLightCss,
   generatePrimitivesCss,
+  generateShadeScale,
   header,
   resolveThemeFonts,
   sectionComment
-} from "../chunk-ZLXFCNYF.js";
+} from "../chunk-NZF2MS4L.js";
 
 // src/adapters/layers.ts
 var LAYER_ORDER = "@layer visor-primitives, visor-semantic, visor-adaptive, visor-bridge;";
@@ -427,6 +428,7 @@ function docsAdapter(input, options) {
         lines.push("");
       }
     }
+    const scale = input.config.typography?.scale ?? 1;
     const seenFamilies = /* @__PURE__ */ new Set();
     for (const font of fontSlots) {
       if (font && font.source === "visor-fonts" && !seenFamilies.has(font.family)) {
@@ -439,6 +441,9 @@ function docsAdapter(input, options) {
           lines.push(`  font-weight: ${weight};`);
           lines.push(`  font-style: ${font.italic ? "italic" : "normal"};`);
           lines.push(`  font-display: ${font.display};`);
+          if (scale !== 1) {
+            lines.push(`  size-adjust: ${Math.round(scale * 100)}%;`);
+          }
           lines.push("}");
           lines.push("");
         }
@@ -480,6 +485,25 @@ function docsAdapter(input, options) {
   lines.push("");
   lines.push("\n/* \u2500\u2500 Section 2: Dark mode overrides \u2500\u2500 */");
   const darkDecls = generateSemanticDecls2(input.tokens, "dark");
+  const colorsDark = input.config["colors-dark"];
+  const darkPrimitiveOverrides = [];
+  if (colorsDark?.primary) {
+    const darkPrimary = generateShadeScale(colorsDark.primary, "primary");
+    for (const step of FULL_SHADE_STEPS) {
+      darkPrimitiveOverrides.push(`--color-primary-${step}: ${darkPrimary[step]};`);
+    }
+  }
+  if (colorsDark?.accent) {
+    const darkAccent = generateShadeScale(colorsDark.accent, "accent");
+    for (const step of FULL_SHADE_STEPS) {
+      darkPrimitiveOverrides.push(`--color-accent-${step}: ${darkAccent[step]};`);
+    }
+  }
+  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("");
+  }
   const categories = ["Text", "Surface", "Border", "Interactive"];
   const categoryDecls = [
     Object.entries(input.tokens.text).map(([n, v]) => `--text-${n}: ${v.dark};`),
@@ -503,6 +527,14 @@ function docsAdapter(input, options) {
     const inner = block(`${scopeClass}:not(.light)`, cat.entries);
     lines.push(`@media (prefers-color-scheme: dark) {
 ${inner.split("\n").map((l) => `  ${l}`).join("\n")}
+}`);
+    lines.push("");
+  }
+  if (darkPrimitiveOverrides.length > 0) {
+    lines.push(sectionComment2("Primitive overrides (dark) \u2014 prefers-color-scheme"));
+    const inner = block(`${scopeClass}:not(.light)`, darkPrimitiveOverrides);
+    lines.push(`@media (prefers-color-scheme: dark) {
+${inner.split("\n").map((l) => `  ${l}`).join("\n")}
 }`);
     lines.push("");
   }

package/dist/{chunk-ZLXFCNYF.js → chunk-NZF2MS4L.js}

@@ -467,8 +467,7 @@ function resolveThemeFonts(typography, options) {
   const warnings = [];
   let headingResolution = null;
   if (typography.heading?.family) {
-    const weights = [];
-    if (typography.heading.weight) weights.push(typography.heading.weight);
+    const weights = typography.heading.weights ? [...typography.heading.weights] : typography.heading.weight ? [typography.heading.weight] : [];
     headingResolution = resolveFont(typography.heading.family, {
       weights: weights.length > 0 ? weights : void 0,
       display,
@@ -481,10 +480,15 @@ function resolveThemeFonts(typography, options) {
   }
   let bodyResolution = null;
   if (typography.body?.family) {
-    const bodyWeights = [];
-    if (typography.body.weight) bodyWeights.push(typography.body.weight);
-    if (!bodyWeights.includes(400)) bodyWeights.push(400);
-    if (!bodyWeights.includes(700)) bodyWeights.push(700);
+    let bodyWeights;
+    if (typography.body.weights) {
+      bodyWeights = [...typography.body.weights];
+    } else {
+      bodyWeights = [];
+      if (typography.body.weight) bodyWeights.push(typography.body.weight);
+      if (!bodyWeights.includes(400)) bodyWeights.push(400);
+      if (!bodyWeights.includes(700)) bodyWeights.push(700);
+    }
     if (headingResolution && typography.body.family.toLowerCase() === headingResolution.family.toLowerCase()) {
       const mergedWeights = Array.from(
         /* @__PURE__ */ new Set([...headingResolution.weights, ...bodyWeights])
@@ -510,19 +514,22 @@ function resolveThemeFonts(typography, options) {
   }
   let displayResolution = null;
   if (typography.display?.family) {
-    const displayWeights = [];
-    if (typography.display.weight) displayWeights.push(typography.display.weight);
+    const displayWeights = typography.display.weights ? [...typography.display.weights] : typography.display.weight ? [typography.display.weight] : [];
     if (headingResolution && typography.display.family.toLowerCase() === headingResolution.family.toLowerCase()) {
-      const mergedWeights = Array.from(
-        /* @__PURE__ */ new Set([...headingResolution.weights, ...displayWeights])
-      ).sort((a, b) => a - b);
-      headingResolution = resolveFont(typography.heading.family, {
-        weights: mergedWeights,
-        display,
-        source: typography.heading.source,
-        org: typography.heading.org
-      });
-      displayResolution = headingResolution;
+      if (typography.heading?.weights) {
+        displayResolution = headingResolution;
+      } else {
+        const mergedWeights = Array.from(
+          /* @__PURE__ */ new Set([...headingResolution.weights, ...displayWeights])
+        ).sort((a, b) => a - b);
+        headingResolution = resolveFont(typography.heading.family, {
+          weights: mergedWeights,
+          display,
+          source: typography.heading.source,
+          org: typography.heading.org
+        });
+        displayResolution = headingResolution;
+      }
     } else if (bodyResolution && typography.display.family.toLowerCase() === bodyResolution.family.toLowerCase()) {
       const mergedWeights = Array.from(
         /* @__PURE__ */ new Set([...bodyResolution.weights, ...displayWeights])
@@ -957,9 +964,9 @@ var LIGHTNESS_TARGETS = {
   200: 0.87,
   300: 0.78,
   400: 0.65,
-  500: 0.55,
-  600: -1,
-  // placeholder — replaced by input L at anchor
+  500: -1,
+  // placeholder — replaced by input L at anchor (brand color lives at 500)
+  600: 0.45,
   700: 0.38,
   800: 0.3,
   900: 0.22,
@@ -979,8 +986,8 @@ var CHROMA_MULTIPLIERS = {
   950: 0.5
 };
 var ANCHOR_SHADE = {
-  primary: 600,
-  accent: 600,
+  primary: 500,
+  accent: 500,
   neutral: 500,
   success: 500,
   warning: 500,

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, R as ResolvedThemeConfig, c as GeneratedPrimitives, d as ThemeOutput, e as ThemeData, f as VisorThemeConfig, g as FullShadeScale, C as ColorRole, S as SelectiveShadeScale, h as RGB, P as ParsedColor, O as OKLCH, i as SemanticTokens, j as ShadeStep } from './types-r7ae3WP2.js';
-export { k as ColorFormat, l as FontSource, m as RGBA, n as SemanticTokenValue } from './types-r7ae3WP2.js';
+import { F as FontResolveOptions, a as FontResolution, V as VisorTypography, b as FontDisplayStrategy, T as ThemeFontResult, G as GoogleFontEntry, R as ResolvedThemeConfig, c as GeneratedPrimitives, d as ThemeOutput, e as ThemeData, f as VisorThemeConfig, g as FullShadeScale, C as ColorRole, S as SelectiveShadeScale, h as RGB, P as ParsedColor, O as OKLCH, i as SemanticTokens, j as ShadeStep } from './types-DgAumoCX.js';
+export { k as ColorFormat, l as FontSource, m as RGBA, n as SemanticTokenValue } from './types-DgAumoCX.js';
 
 /**
  * Font resolver — maps font family names to loadable font resources.

package/dist/index.js

@@ -31,7 +31,7 @@ import {
   rgbToHex,
   rgbToOklch,
   serializeColor
-} from "./chunk-ZLXFCNYF.js";
+} from "./chunk-NZF2MS4L.js";
 
 // src/pipeline.ts
 import { parse as parseYaml } from "yaml";
@@ -325,6 +325,8 @@ var KNOWN_TOP_LEVEL_KEYS = /* @__PURE__ */ new Set([
   "name",
   "version",
   "group",
+  "label",
+  "default-mode",
   "colors",
   "colors-dark",
   "typography",
@@ -353,7 +355,7 @@ var KNOWN_TYPOGRAPHY_KEYS = /* @__PURE__ */ new Set([
   "letter-spacing",
   "scale"
 ]);
-var KNOWN_TYPOGRAPHY_FONT_KEYS = /* @__PURE__ */ new Set(["family", "weight", "source", "org"]);
+var KNOWN_TYPOGRAPHY_FONT_KEYS = /* @__PURE__ */ new Set(["family", "weight", "weights", "source", "org"]);
 var KNOWN_TYPOGRAPHY_MONO_KEYS = /* @__PURE__ */ new Set(["family"]);
 var KNOWN_LETTER_SPACING_KEYS = /* @__PURE__ */ new Set(["tight", "normal", "wide"]);
 var KNOWN_SPACING_KEYS = /* @__PURE__ */ new Set(["base"]);
@@ -473,6 +475,15 @@ function validateConfig(config) {
   if (obj.version !== 1) {
     errors.push("'version' must be 1");
   }
+  if (obj.label !== void 0 && typeof obj.label !== "string") {
+    errors.push("'label' must be a string (optional display name override)");
+  }
+  if (obj["default-mode"] !== void 0) {
+    const mode = obj["default-mode"];
+    if (mode !== "dark" && mode !== "light") {
+      errors.push("'default-mode' must be either 'dark' or 'light'");
+    }
+  }
   if (typeof obj.colors !== "object" || obj.colors === null) {
     errors.push("'colors' is required and must be an object");
     return { valid: false, errors };
@@ -530,6 +541,11 @@ function validateConfig(config) {
       if (font && font.source === "visor-fonts" && !font.org) {
         errors.push(`'typography.${slot}.org' is required when source is 'visor-fonts'`);
       }
+      if (font && font.weights !== void 0) {
+        if (!Array.isArray(font.weights) || !font.weights.every((w) => typeof w === "number" && w > 0)) {
+          errors.push(`'typography.${slot}.weights' must be an array of positive numbers (e.g., [300, 500])`);
+        }
+      }
     }
   }
   if (obj.overrides !== void 0) {
@@ -636,19 +652,22 @@ function resolveConfig(config) {
         family: config.typography?.heading?.family ?? DEFAULTS.typography.heading.family,
         weight: config.typography?.heading?.weight ?? DEFAULTS.typography.heading.weight,
         ...config.typography?.heading?.source && { source: config.typography.heading.source },
-        ...config.typography?.heading?.org && { org: config.typography.heading.org }
+        ...config.typography?.heading?.org && { org: config.typography.heading.org },
+        ...config.typography?.heading?.weights && { weights: config.typography.heading.weights }
       },
       display: {
         family: config.typography?.display?.family ?? config.typography?.heading?.family ?? DEFAULTS.typography.heading.family,
         weight: config.typography?.display?.weight ?? 400,
         ...config.typography?.display?.source && { source: config.typography.display.source },
-        ...config.typography?.display?.org && { org: config.typography.display.org }
+        ...config.typography?.display?.org && { org: config.typography.display.org },
+        ...config.typography?.display?.weights && { weights: config.typography.display.weights }
       },
       body: {
         family: config.typography?.body?.family ?? DEFAULTS.typography.body.family,
         weight: config.typography?.body?.weight ?? DEFAULTS.typography.body.weight,
         ...config.typography?.body?.source && { source: config.typography.body.source },
-        ...config.typography?.body?.org && { org: config.typography.body.org }
+        ...config.typography?.body?.org && { org: config.typography.body.org },
+        ...config.typography?.body?.weights && { weights: config.typography.body.weights }
       },
       mono: {
         family: config.typography?.mono?.family ?? DEFAULTS.typography.mono.family
@@ -1835,6 +1854,51 @@ function checkRadiusScale(config, issues) {
     );
   }
 }
+function checkDarkLightParity(config, issues) {
+  if (!config.colors) return;
+  const colorKeys = Object.keys(config.colors).filter((k) => k !== "primary");
+  const hasDarkSection = config["colors-dark"] !== void 0;
+  if (colorKeys.length > 0 && !hasDarkSection) {
+    issues.push(
+      issue(
+        "warning",
+        "DARK_LIGHT_PARITY",
+        "Custom colors are set but no colors-dark section exists. Dark mode will use generated defaults which may not match your brand.",
+        "colors-dark"
+      )
+    );
+    return;
+  }
+  if (colorKeys.length > 0 && hasDarkSection) {
+    const lightKeys = new Set(Object.keys(config.colors));
+    const darkKeys = new Set(Object.keys(config["colors-dark"]));
+    for (const key of lightKeys) {
+      if (key === "primary") continue;
+      if (!darkKeys.has(key)) {
+        issues.push(
+          issue(
+            "warning",
+            "DARK_LIGHT_PARITY",
+            `Color "${key}" is set in colors but missing from colors-dark. Dark mode will use a generated default.`,
+            "colors-dark"
+          )
+        );
+      }
+    }
+    for (const key of darkKeys) {
+      if (!lightKeys.has(key)) {
+        issues.push(
+          issue(
+            "warning",
+            "DARK_LIGHT_PARITY",
+            `Color "${key}" is set in colors-dark but missing from colors. Light mode will use a generated default.`,
+            "colors"
+          )
+        );
+      }
+    }
+  }
+}
 function validate(config) {
   const errors = [];
   const warnings = [];
@@ -1866,6 +1930,7 @@ function validate(config) {
     checkColorSimilarity(typedConfig, warnings);
     checkMissingGlowShadow(typedConfig, warnings);
     checkRadiusScale(typedConfig, warnings);
+    checkDarkLightParity(typedConfig, warnings);
   }
   return {
     valid: errors.length === 0,

package/dist/{types-r7ae3WP2.d.ts → types-DgAumoCX.d.ts}

@@ -46,18 +46,24 @@ interface VisorTypography {
     heading?: {
         family: string;
         weight?: number;
+        /** Explicit list of font weights to load (overrides engine defaults) */
+        weights?: number[];
         source?: FontSource;
         org?: string;
     };
     display?: {
         family: string;
         weight?: number;
+        /** Explicit list of font weights to load (overrides engine defaults) */
+        weights?: number[];
         source?: FontSource;
         org?: string;
     };
     body?: {
         family: string;
         weight?: number;
+        /** Explicit list of font weights to load (overrides engine defaults) */
+        weights?: number[];
         source?: FontSource;
         org?: string;
     };
@@ -123,6 +129,10 @@ interface VisorThemeConfig {
     version: 1;
     /** Theme group for the docs site theme switcher (e.g. 'Visor', 'Client', 'Low Orbit'). Used by `visor theme sync`. */
     group?: string;
+    /** Optional display label override for the theme switcher (e.g. 'ENTR', 'SoleSpark'). Falls back to title-cased name. */
+    label?: string;
+    /** Default color mode to force when the theme is activated ('dark' or 'light'). If unset, user/system preference applies. */
+    "default-mode"?: "dark" | "light";
     colors: {
         primary: string;
         accent?: string;
@@ -150,18 +160,21 @@ interface VisorThemeConfig {
         heading?: {
             family?: string;
             weight?: number;
+            weights?: number[];
             source?: FontSource;
             org?: string;
         };
         display?: {
             family?: string;
             weight?: number;
+            weights?: number[];
             source?: FontSource;
             org?: string;
         };
         body?: {
             family?: string;
             weight?: number;
+            weights?: number[];
             source?: FontSource;
             org?: string;
         };
@@ -226,18 +239,21 @@ interface ResolvedThemeConfig {
         heading: {
             family: string;
             weight: number;
+            weights?: number[];
             source?: FontSource;
             org?: string;
         };
         display: {
             family: string;
             weight: number;
+            weights?: number[];
             source?: FontSource;
             org?: string;
         };
         body: {
             family: string;
             weight: number;
+            weights?: number[];
             source?: FontSource;
             org?: string;
         };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loworbitstudio/visor-theme-engine",
-  "version": "0.1.0",
+  "version": "0.4.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",
@@ -35,7 +35,12 @@
     "design-system",
     "theme",
     "oklch",
-    "tokens"
+    "tokens",
+    "react",
+    "css-variables",
+    "theming",
+    "color-system",
+    "wcag"
   ],
   "license": "MIT",
   "repository": {