@loworbitstudio/visor-theme-engine

Theme engine for the Visor design system — shade generation, token mapping, font resolution, and import/export for .visor.yaml themes.

Installation

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.

import { generateTheme } from '@loworbitstudio/visor-theme-engine'

Migration

Themes pinned to `^0.4.x` with a custom mono font

Engine 0.5 expanded typography.mono to accept weight | weights | source | org (previously only family). Engine 0.6 added validate-coverage, which errors when any --font-* declaration names a family with no matching @font-face. The combination created a trap: themes pinned to ^0.4.x could only write mono: { family: X } (the only thing 0.4 allowed) and could not express the source/org fix the 0.6 error message points to.

To migrate:

Bump both @loworbitstudio/visor (the CLI) to ≥ 0.10 and @loworbitstudio/visor-theme-engine to ≥ 0.6 together. The CLI transitively pins its own engine copy (CLI 0.10 → engine ^0.6.0), so visor theme sync runs against the CLI-bundled engine, not the hoisted one — bumping the engine alone is silently insufficient.
Decide between inheritance and explicit declaration:
- Inheritance (preferred when applicable). If your mono slot's family matches another slot (heading, display, or body) with source/org set, leave typography.mono.source and typography.mono.org unset. The engine will inherit source/org from the matching slot. Match precedence: heading → display → body, case-insensitive.
```
typography:
  body:
    family: PP Model Mono
    weight: 400
    source: visor-fonts
    org: low-orbit-studio
  mono:
    family: PP Model Mono
    weight: 400
    # source/org inherited from body
```
- Explicit declaration. Otherwise, add source (and org for visor-fonts) directly:
```
typography:
  mono:
    family: PP Model Mono
    weight: 400
    source: visor-fonts        # or google-fonts, fontshare, local
    org: low-orbit-studio      # required for visor-fonts only
```

System mono fonts (SF Mono, JetBrains Mono, Source Code Pro, Menlo, etc.) are already on the validator's SYSTEM_FONTS list and never need source/org.

Documentation

Full docs at visor.loworbit.studio.