@loworbitstudio/visor-theme-engine 0.1.0

package/dist/types-r7ae3WP2.d.ts

@@ -0,0 +1,314 @@
+/**
+ * Font resolution types for the Visor theme engine.
+ */
+/** Where a font is loaded from */
+type FontSource = "google-fonts" | "visor-fonts" | "local";
+/** CSS font-display strategy */
+type FontDisplayStrategy = "swap" | "block" | "fallback" | "optional" | "auto";
+/** A single resolved font */
+interface FontResolution {
+    /** The font family name as specified */
+    family: string;
+    /** Where this font comes from */
+    source: FontSource;
+    /** Google Fonts CSS URL (only for google-fonts source) */
+    cssUrl: string | null;
+    /** Weights available/requested for this font */
+    weights: number[];
+    /** Whether italic styles are available/requested */
+    italic: boolean;
+    /** The font-display strategy to use */
+    display: FontDisplayStrategy;
+    /** Font category (sans-serif, serif, monospace, etc.) for fallback selection */
+    category: string;
+    /** Human-readable message for local fonts needing manual setup */
+    guidance: string | null;
+    /** Organization namespace (only for visor-fonts source) */
+    org: string | null;
+}
+/** Options for resolving a single font */
+interface FontResolveOptions {
+    /** Weights to include (default: [400, 700]) */
+    weights?: number[];
+    /** Include italic variants (default: false) */
+    italic?: boolean;
+    /** font-display strategy (default: "swap") */
+    display?: FontDisplayStrategy;
+    /** Font category override for custom fonts (default: "sans-serif") */
+    category?: string;
+    /** Font source override — skips Google Fonts lookup when set */
+    source?: FontSource;
+    /** Organization namespace for visor-fonts CDN (required when source is "visor-fonts") */
+    org?: string;
+}
+/** Typography section from a .visor.yaml file */
+interface VisorTypography {
+    heading?: {
+        family: string;
+        weight?: number;
+        source?: FontSource;
+        org?: string;
+    };
+    display?: {
+        family: string;
+        weight?: number;
+        source?: FontSource;
+        org?: string;
+    };
+    body?: {
+        family: string;
+        weight?: number;
+        source?: FontSource;
+        org?: string;
+    };
+    mono?: {
+        family: string;
+        weight?: number;
+        source?: FontSource;
+        org?: string;
+    };
+    "letter-spacing"?: {
+        tight?: string;
+        normal?: string;
+        wide?: string;
+    };
+}
+/** Result of resolving all fonts for a theme */
+interface ThemeFontResult {
+    /** Resolved heading font (if specified) */
+    heading: FontResolution | null;
+    /** Resolved display font (if specified) */
+    display: FontResolution | null;
+    /** Resolved body font (if specified) */
+    body: FontResolution | null;
+    /** Resolved monospace font (if specified) */
+    mono: FontResolution | null;
+    /** Preconnect and preload link tags */
+    preloadLinks: string[];
+    /** CSS @font-face + custom property overrides */
+    css: string;
+    /** Warnings for fonts needing manual setup */
+    warnings: string[];
+}
+/** Entry in the Google Fonts catalog */
+interface GoogleFontEntry {
+    family: string;
+    weights: number[];
+    styles: string[];
+    category: string;
+}
+
+/**
+ * Types for the Visor Theme Engine
+ *
+ * Covers the full pipeline: .visor.yaml config → shade scales → semantic tokens → CSS output.
+ */
+
+type ShadeStep = 50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900 | 950;
+type ColorRole = "primary" | "accent" | "neutral" | "success" | "warning" | "error" | "info";
+type FullShadeScale = Record<ShadeStep, string>;
+type SelectiveShadeScale = Record<50 | 100 | 500 | 600 | 700 | 900, string>;
+type RGB = [number, number, number];
+type OKLCH = [number, number, number];
+type RGBA = [number, number, number, number];
+type ColorFormat = "hex" | "rgba" | "hsla" | "oklch";
+interface ParsedColor {
+    rgb: RGB;
+    alpha?: number;
+    format: ColorFormat;
+    original: string;
+}
+interface VisorThemeConfig {
+    name: string;
+    version: 1;
+    /** Theme group for the docs site theme switcher (e.g. 'Visor', 'Client', 'Low Orbit'). Used by `visor theme sync`. */
+    group?: string;
+    colors: {
+        primary: string;
+        accent?: string;
+        neutral?: string;
+        background?: string;
+        surface?: string;
+        success?: string;
+        warning?: string;
+        error?: string;
+        info?: string;
+    };
+    "colors-dark"?: {
+        primary?: string;
+        accent?: string;
+        neutral?: string;
+        background?: string;
+        surface?: string;
+        success?: string;
+        warning?: string;
+        error?: string;
+        info?: string;
+    };
+    typography?: {
+        scale?: number;
+        heading?: {
+            family?: string;
+            weight?: number;
+            source?: FontSource;
+            org?: string;
+        };
+        display?: {
+            family?: string;
+            weight?: number;
+            source?: FontSource;
+            org?: string;
+        };
+        body?: {
+            family?: string;
+            weight?: number;
+            source?: FontSource;
+            org?: string;
+        };
+        mono?: {
+            family?: string;
+            weight?: number;
+            source?: FontSource;
+            org?: string;
+        };
+        "letter-spacing"?: {
+            tight?: string;
+            normal?: string;
+            wide?: string;
+        };
+    };
+    spacing?: {
+        base?: number;
+    };
+    radius?: {
+        sm?: number;
+        md?: number;
+        lg?: number;
+        xl?: number;
+        pill?: number;
+    };
+    shadows?: {
+        xs?: string;
+        sm?: string;
+        md?: string;
+        lg?: string;
+        xl?: string;
+    };
+    motion?: {
+        "duration-fast"?: string;
+        "duration-normal"?: string;
+        "duration-slow"?: string;
+        easing?: string;
+    };
+    overrides?: {
+        light?: Record<string, string>;
+        dark?: Record<string, string>;
+    };
+}
+/** Config with all defaults resolved */
+interface ResolvedThemeConfig {
+    name: string;
+    version: 1;
+    colors: {
+        primary: string;
+        accent: string;
+        neutral: string | null;
+        background: string;
+        surface: string;
+        success: string;
+        warning: string;
+        error: string;
+        info: string;
+    };
+    "colors-dark"?: VisorThemeConfig["colors-dark"];
+    typography: {
+        scale: number;
+        heading: {
+            family: string;
+            weight: number;
+            source?: FontSource;
+            org?: string;
+        };
+        display: {
+            family: string;
+            weight: number;
+            source?: FontSource;
+            org?: string;
+        };
+        body: {
+            family: string;
+            weight: number;
+            source?: FontSource;
+            org?: string;
+        };
+        mono: {
+            family: string;
+        };
+    };
+    spacing: {
+        base: number;
+    };
+    radius: {
+        sm: number;
+        md: number;
+        lg: number;
+        xl: number;
+        pill: number;
+    };
+    shadows: {
+        xs: string;
+        sm: string;
+        md: string;
+        lg: string;
+        xl: string;
+    };
+    motion: {
+        "duration-fast": string;
+        "duration-normal": string;
+        "duration-slow": string;
+        easing: string;
+    };
+    overrides?: {
+        light?: Record<string, string>;
+        dark?: Record<string, string>;
+    };
+    /** 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. */
+    colorFormats?: Record<string, ColorFormat>;
+}
+interface GeneratedPrimitives {
+    primary: FullShadeScale;
+    accent: FullShadeScale;
+    neutral: FullShadeScale;
+    success: SelectiveShadeScale;
+    warning: SelectiveShadeScale;
+    error: SelectiveShadeScale;
+    info: SelectiveShadeScale;
+}
+interface SemanticTokenValue {
+    light: string;
+    dark: string;
+}
+interface SemanticTokens {
+    text: Record<string, SemanticTokenValue>;
+    surface: Record<string, SemanticTokenValue>;
+    border: Record<string, SemanticTokenValue>;
+    interactive: Record<string, SemanticTokenValue>;
+}
+interface ThemeOutput {
+    primitivesCss: string;
+    semanticCss: string;
+    lightCss: string;
+    darkCss: string;
+    fullBundleCss: string;
+}
+/** Full pipeline result including intermediate artifacts for adapter consumption. */
+interface ThemeData {
+    config: ResolvedThemeConfig;
+    primitives: GeneratedPrimitives;
+    tokens: SemanticTokens;
+    output: ThemeOutput;
+}
+
+export type { ColorRole as C, FontResolveOptions as F, GoogleFontEntry as G, OKLCH as O, ParsedColor as P, ResolvedThemeConfig as R, SelectiveShadeScale as S, ThemeFontResult as T, VisorTypography as V, FontResolution as a, FontDisplayStrategy as b, GeneratedPrimitives as c, ThemeOutput as d, ThemeData as e, VisorThemeConfig as f, FullShadeScale as g, RGB as h, SemanticTokens as i, ShadeStep as j, ColorFormat as k, FontSource as l, RGBA as m, SemanticTokenValue as n };

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@loworbitstudio/visor-theme-engine",
+  "version": "0.1.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",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./adapters": {
+      "import": "./dist/adapters/index.js",
+      "types": "./dist/adapters/index.d.ts"
+    },
+    "./fowt": {
+      "import": "./dist/fowt.js",
+      "types": "./dist/fowt.d.ts"
+    },
+    "./schema": "./src/visor-theme.schema.json"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "update-catalog": "tsx scripts/update-google-fonts-catalog.ts"
+  },
+  "files": [
+    "dist/",
+    "src/visor-theme.schema.json"
+  ],
+  "keywords": [
+    "visor",
+    "design-system",
+    "theme",
+    "oklch",
+    "tokens"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/low-orbit-studio/visor.git"
+  },
+  "homepage": "https://visor.loworbit.studio",
+  "bugs": {
+    "url": "https://github.com/low-orbit-studio/visor/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "yaml": "^2.8.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.4.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vitest": "^4.1.2"
+  }
+}

package/src/visor-theme.schema.json

@@ -0,0 +1,282 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://visor.loworbit.studio/schemas/visor-theme.schema.json",
+  "title": "Visor Theme",
+  "description": "Schema for .visor.yaml theme files — portable visual identity definitions for the Visor design system.",
+  "type": "object",
+  "required": ["name", "version", "colors"],
+  "additionalProperties": false,
+  "properties": {
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Human-readable theme name."
+    },
+    "version": {
+      "const": 1,
+      "description": "Schema version. Currently always 1."
+    },
+    "group": {
+      "type": "string",
+      "description": "Theme group for the docs site theme switcher (e.g. 'Visor', 'Client', 'Low Orbit'). Used by `visor theme sync`. Defaults to folder-based grouping when omitted."
+    },
+    "colors": {
+      "type": "object",
+      "description": "Color definitions for light mode. Only primary is required — all others have sensible defaults.",
+      "required": ["primary"],
+      "additionalProperties": false,
+      "properties": {
+        "primary": {
+          "$ref": "#/$defs/cssColor",
+          "description": "Brand color. Drives interactive-*, accent-*, text-link, border-focus tokens. Anchored at shade 600."
+        },
+        "accent": {
+          "$ref": "#/$defs/cssColor",
+          "description": "Secondary brand color. Defaults to primary if omitted."
+        },
+        "neutral": {
+          "$ref": "#/$defs/cssColor",
+          "description": "Base neutral color for generating the gray scale (50-950). Defaults to Tailwind Gray if omitted."
+        },
+        "background": {
+          "$ref": "#/$defs/cssColor",
+          "description": "Page background for light mode. Default: #FFFFFF."
+        },
+        "surface": {
+          "$ref": "#/$defs/cssColor",
+          "description": "Card/panel background for light mode. Default: #FFFFFF."
+        },
+        "success": {
+          "$ref": "#/$defs/cssColor",
+          "description": "Success status color. Default: #22C55E (Tailwind green-500)."
+        },
+        "warning": {
+          "$ref": "#/$defs/cssColor",
+          "description": "Warning status color. Default: #F59E0B (Tailwind amber-500)."
+        },
+        "error": {
+          "$ref": "#/$defs/cssColor",
+          "description": "Error status color. Default: #EF4444 (Tailwind red-500)."
+        },
+        "info": {
+          "$ref": "#/$defs/cssColor",
+          "description": "Info status color. Default: #0EA5E9 (Tailwind sky-500)."
+        }
+      }
+    },
+    "colors-dark": {
+      "type": "object",
+      "description": "Dark mode color overrides. Any key from colors can be overridden. Omitted keys inherit from the derived dark mode values (not from light mode).",
+      "additionalProperties": false,
+      "properties": {
+        "primary": { "$ref": "#/$defs/cssColor" },
+        "accent": { "$ref": "#/$defs/cssColor" },
+        "neutral": { "$ref": "#/$defs/cssColor" },
+        "background": { "$ref": "#/$defs/cssColor" },
+        "surface": { "$ref": "#/$defs/cssColor" },
+        "success": { "$ref": "#/$defs/cssColor" },
+        "warning": { "$ref": "#/$defs/cssColor" },
+        "error": { "$ref": "#/$defs/cssColor" },
+        "info": { "$ref": "#/$defs/cssColor" }
+      }
+    },
+    "typography": {
+      "type": "object",
+      "description": "Typography configuration. Defaults to system font stacks if omitted.",
+      "additionalProperties": false,
+      "properties": {
+        "heading": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "family": {
+              "type": "string",
+              "description": "Google Fonts family name or CSS font stack."
+            },
+            "weight": {
+              "type": "integer",
+              "minimum": 100,
+              "maximum": 900,
+              "description": "Font weight for headings. Default: 600."
+            },
+            "source": {
+              "type": "string",
+              "enum": ["google-fonts", "visor-fonts", "local"],
+              "description": "Font source. Defaults to Google Fonts lookup, then local."
+            },
+            "org": {
+              "type": "string",
+              "description": "Organization namespace for visor-fonts CDN (required when source is visor-fonts)."
+            }
+          }
+        },
+        "display": {
+          "type": "object",
+          "description": "Display/decorative font for hero text and splash screens. Falls back to heading font if omitted.",
+          "additionalProperties": false,
+          "properties": {
+            "family": {
+              "type": "string",
+              "description": "Google Fonts family name or CSS font stack."
+            },
+            "weight": {
+              "type": "integer",
+              "minimum": 100,
+              "maximum": 900,
+              "description": "Font weight for display text. Default: 400."
+            },
+            "source": {
+              "type": "string",
+              "enum": ["google-fonts", "visor-fonts", "local"],
+              "description": "Font source. Defaults to Google Fonts lookup, then local."
+            },
+            "org": {
+              "type": "string",
+              "description": "Organization namespace for visor-fonts CDN (required when source is visor-fonts)."
+            }
+          }
+        },
+        "body": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "family": {
+              "type": "string",
+              "description": "Google Fonts family name or CSS font stack."
+            },
+            "weight": {
+              "type": "integer",
+              "minimum": 100,
+              "maximum": 900,
+              "description": "Font weight for body text. Default: 400."
+            },
+            "source": {
+              "type": "string",
+              "enum": ["google-fonts", "visor-fonts", "local"],
+              "description": "Font source. Defaults to Google Fonts lookup, then local."
+            },
+            "org": {
+              "type": "string",
+              "description": "Organization namespace for visor-fonts CDN (required when source is visor-fonts)."
+            }
+          }
+        },
+        "mono": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "family": {
+              "type": "string",
+              "description": "Google Fonts family name or CSS font stack for monospace."
+            }
+          }
+        },
+        "scale": {
+          "type": "number",
+          "description": "Type scale multiplier applied to the font-size ramp. Default: 1."
+        },
+        "letter-spacing": {
+          "type": "object",
+          "description": "Letter spacing scale.",
+          "additionalProperties": false,
+          "properties": {
+            "tight": { "type": "string" },
+            "normal": { "type": "string" },
+            "wide": { "type": "string" }
+          }
+        }
+      }
+    },
+    "spacing": {
+      "type": "object",
+      "description": "Spacing configuration.",
+      "additionalProperties": false,
+      "properties": {
+        "base": {
+          "type": "number",
+          "minimum": 1,
+          "description": "Base spacing unit in pixels. Default: 4. Generates the full spacing scale."
+        }
+      }
+    },
+    "radius": {
+      "type": "object",
+      "description": "Border radius scale in pixels.",
+      "additionalProperties": false,
+      "properties": {
+        "sm": { "type": "number", "minimum": 0 },
+        "md": { "type": "number", "minimum": 0 },
+        "lg": { "type": "number", "minimum": 0 },
+        "xl": { "type": "number", "minimum": 0 },
+        "pill": { "type": "number", "minimum": 0, "description": "Default: 9999." }
+      }
+    },
+    "shadows": {
+      "type": "object",
+      "description": "Named shadow definitions as CSS box-shadow values.",
+      "additionalProperties": false,
+      "properties": {
+        "xs": { "type": "string" },
+        "sm": { "type": "string" },
+        "md": { "type": "string" },
+        "lg": { "type": "string" },
+        "xl": { "type": "string" }
+      }
+    },
+    "motion": {
+      "type": "object",
+      "description": "Motion/animation configuration.",
+      "additionalProperties": false,
+      "properties": {
+        "duration-fast": {
+          "type": "string",
+          "pattern": "^\\d+ms$",
+          "description": "Fast duration for micro-interactions. Default: 100ms."
+        },
+        "duration-normal": {
+          "type": "string",
+          "pattern": "^\\d+ms$",
+          "description": "Normal duration for standard transitions. Default: 200ms."
+        },
+        "duration-slow": {
+          "type": "string",
+          "pattern": "^\\d+ms$",
+          "description": "Slow duration for larger animations. Default: 500ms."
+        },
+        "easing": {
+          "type": "string",
+          "description": "Default easing curve as a CSS timing function."
+        }
+      }
+    },
+    "overrides": {
+      "type": "object",
+      "description": "Per-token escape hatch. Values replace derived tokens. Use CSS custom property names without the -- prefix as keys.",
+      "additionalProperties": false,
+      "properties": {
+        "light": {
+          "type": "object",
+          "description": "Token overrides applied in light mode.",
+          "additionalProperties": { "type": "string" }
+        },
+        "dark": {
+          "type": "object",
+          "description": "Token overrides applied in dark mode.",
+          "additionalProperties": { "type": "string" }
+        }
+      }
+    }
+  },
+  "$defs": {
+    "cssColor": {
+      "type": "string",
+      "description": "CSS color value. Accepts hex (#RGB, #RRGGBB, #RRGGBBAA), rgb()/rgba(), hsl()/hsla(), or oklch() formats.",
+      "anyOf": [
+        { "pattern": "^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$" },
+        { "pattern": "^rgba?\\(" },
+        { "pattern": "^hsla?\\(" },
+        { "pattern": "^oklch\\(" }
+      ]
+    }
+  }
+}