@omniharmonic/openspace-theme 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,26 @@
+MIT License
+
+Copyright (c) 2026 The OpenSpace contributors
+
+This license covers everything in this repository except where a directory
+states otherwise: apps/studio and apps/hub are licensed under AGPL-3.0-only
+(see LICENSE-AGPL), and documentation and template designs are licensed under
+CC-BY-4.0.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,11 @@
-# Temporary Holding Version
+# @omniharmonic/openspace-theme
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Design tokens: OKLCH palettes, the contrast solver, type pairings and the Site Styles compiler.
+
+Part of [OpenSpace](https://github.com/omniharmonic/openspace), an open-source website builder. Most sites only depend on `@omniharmonic/openspace-site-kit` (and `@omniharmonic/openspace-cli` as a dev dependency); the other packages come along as its dependencies.
+
+Versions of the OpenSpace packages are released in lockstep.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,587 @@
+import { COLOR_SCALE_STEPS, COLOR_ROLES, ColorTheme, StyleChoices, Styles, CustomFont, BUTTON_STYLES, DENSITIES, ImageTreatment, MOTION_LEVELS, SHAPES, DtcgToken, DtcgValue, DtcgGroup } from '@omniharmonic/openspace-schema';
+
+/**
+ * Color math: OKLCH ⇄ OKLab ⇄ linear sRGB ⇄ sRGB (hex), CSS color parsing, and gamut mapping
+ * by chroma reduction. Matrices from Björn Ottosson's OKLab reference and CSS Color 4.
+ */
+/** OKLCH: lightness 0–1, chroma ≥ 0 (≈0–0.37 in sRGB), hue in degrees 0–360. */
+interface Oklch {
+    l: number;
+    c: number;
+    h: number;
+}
+/** OKLab: lightness 0–1, a/b opponent axes. */
+interface Oklab {
+    l: number;
+    a: number;
+    b: number;
+}
+/** RGB triple. Gamma-encoded sRGB or linear-light sRGB depending on context, channels 0–1. */
+interface Rgb {
+    r: number;
+    g: number;
+    b: number;
+}
+/** Below this chroma a color is treated as achromatic (hue is meaningless). */
+declare const ACHROMATIC_CHROMA = 0.0001;
+declare function srgbChannelToLinear(v: number): number;
+declare function linearChannelToSrgb(v: number): number;
+declare function srgbToLinear({ r, g, b }: Rgb): Rgb;
+declare function linearToSrgb({ r, g, b }: Rgb): Rgb;
+declare function linearSrgbToOklab({ r, g, b }: Rgb): Oklab;
+declare function oklabToLinearSrgb({ l: L, a, b }: Oklab): Rgb;
+declare function normalizeHue(h: number): number;
+declare function oklabToOklch({ l, a, b }: Oklab): Oklch;
+declare function oklchToOklab({ l, c, h }: Oklch): Oklab;
+declare function srgbToOklch(rgb: Rgb): Oklch;
+/** Unclamped sRGB (may fall outside 0–1 when the color is out of gamut). */
+declare function oklchToSrgb(color: Oklch): Rgb;
+declare function inSrgbGamut(color: Oklch): boolean;
+/**
+ * Map an OKLCH color into sRGB by reducing chroma (hue and lightness preserved) — binary search
+ * for the largest in-gamut chroma. Lightness is clamped to 0–1 first.
+ */
+declare function gamutMap(color: Oklch): Oklch;
+/** Gamut-mapped, clamped sRGB (0–1 channels). */
+declare function oklchToSrgbInGamut(color: Oklch): Rgb;
+/** sRGB (0–1) → lowercase `#rrggbb`. */
+declare function rgbToHex({ r, g, b }: Rgb): string;
+/** `#rgb`, `#rgba`, `#rrggbb` or `#rrggbbaa` → sRGB (alpha ignored). */
+declare function hexToRgb(hex: string): Rgb;
+/** OKLCH → gamut-mapped `#rrggbb`. */
+declare function oklchToHex(color: Oklch): string;
+declare function hexToOklch(hex: string): Oklch;
+/**
+ * Parse a CSS color (hex, `oklch()`, `oklab()`, `rgb()/rgba()`, `hsl()/hsla()`, `lab()`, `lch()`)
+ * into OKLCH. Out-of-gamut inputs are kept as-is; map with {@link gamutMap} before display.
+ */
+declare function parseColor(input: string): Oklch;
+/** True when {@link parseColor} accepts the input. */
+declare function isColor(input: string): boolean;
+/** Format as a CSS `oklch()` string, e.g. `oklch(0.62 0.09 145)`. */
+declare function formatOklch({ l, c, h }: Oklch): string;
+/** Any CSS color → gamut-mapped `#rrggbb`. */
+declare function toHex(input: string | Oklch): string;
+/** Shortest-path interpolation between two hues (t = 0 → a, 1 → b). */
+declare function mixHue(a: number, b: number, t: number): number;
+/** Euclidean distance in OKLab (ΔE_OK). */
+declare function deltaEOK(x: Oklch, y: Oklch): number;
+
+/** A semantic color role (doc 04 §3.1), e.g. `text-muted`. */
+type ColorRole = (typeof COLOR_ROLES)[number];
+/** A color scale step, 50–950. */
+type ScaleStep = (typeof COLOR_SCALE_STEPS)[number];
+/** An 11-step color scale. */
+type ColorScale<T = string> = Record<ScaleStep, T>;
+/** Interaction states the solver derives from `accent` (not schema roles; theme-internal). */
+declare const STATE_ROLES: readonly ["accent-hover", "accent-pressed"];
+type StateRole = (typeof STATE_ROLES)[number];
+/** Every color a section theme defines: the 14 semantic roles plus the accent states. */
+type ThemeRole = ColorRole | StateRole;
+
+/** WCAG 2.x relative luminance of an sRGB color (0 = black, 1 = white). */
+declare function relativeLuminance(color: string | Oklch): number;
+/** WCAG 2.x contrast ratio, 1–21. Colors are gamut-mapped and quantized to 8-bit sRGB first. */
+declare function contrastRatio(a: string | Oklch, b: string | Oklch): number;
+/** Contrast levels: `body` text, or `large` text and UI components (WCAG 1.4.3 / 1.4.11). */
+type ContrastLevel = "body" | "large";
+type ContrastMode = "standard" | "high";
+/** Minimum ratios. `standard` = WCAG 2.2 AA; `high` = AAA (7:1 body, 4.5:1 large/UI). */
+declare const CONTRAST_MINIMUMS: Record<ContrastMode, Record<ContrastLevel, number>>;
+interface ContrastPair {
+    fg: ThemeRole;
+    bg: ThemeRole;
+    level: ContrastLevel;
+    /** Which side the solver moves (default `fg`). State colors are always the side that moves. */
+    adjust?: "fg" | "bg";
+}
+/**
+ * Every role pair that must meet contrast in every section theme. Order matters to the solver:
+ * `accent` is settled against the backgrounds before `accent-text` is settled against `accent`.
+ * `border` is decorative (inputs use `text-muted`-strength outlines) and is not checked.
+ * The last four pairs cover the button hover/pressed fills ({@link STATE_PAIRS}).
+ */
+declare const CORE_CONTRAST_PAIRS: readonly ContrastPair[];
+/** Button hover/pressed fills: labels stay legible and the fill stays visible as UI. */
+declare const STATE_PAIRS: readonly ContrastPair[];
+declare const CONTRAST_PAIRS: readonly ContrastPair[];
+type ThemeColors = Record<ThemeRole, string>;
+type ThemeColorSet = Record<ColorTheme, ThemeColors>;
+interface ContrastFailure {
+    theme: ColorTheme;
+    fg: ThemeRole;
+    bg: ThemeRole;
+    fgColor: string;
+    bgColor: string;
+    ratio: number;
+    required: number;
+    level: ContrastLevel;
+    /** Nearest accessible replacement (lightness-only) for the side the solver adjusts: `fg`, or `bg` for state fills. */
+    suggestion: string;
+}
+/** List every failing text/background pair across the given themes. */
+declare function auditContrast(themes: Partial<ThemeColorSet>, options?: {
+    contrast?: ContrastMode;
+}): ContrastFailure[];
+/**
+ * Lightness-only search: the color closest in lightness to `color` (same hue, chroma reduced only
+ * as the gamut requires) that reaches `min` contrast against `against`. Returns `null` when even
+ * the darkest/lightest end of the line can't reach `min`. `direction` restricts the search to
+ * moving darker or lighter.
+ */
+type Direction = "darker" | "lighter" | "either";
+declare function solveLightness(color: Oklch, against: Oklch | string, min: number, direction?: Direction): Oklch | null;
+/**
+ * Nearest accessible version of `color` against `against`: same hue, lightness moved the least
+ * distance needed to reach `min` (default 4.5:1). Falls back to the higher-contrast extreme.
+ * Returns `#rrggbb`.
+ */
+declare function nearestAccessible(color: string, against: string, min?: number): string;
+
+/**
+ * Curated type pairings (doc 04 §4.1). Every family is SIL Open Font License, available from
+ * Google Fonts and Fontsource (self-hosted at build time — no third-party font requests).
+ */
+type FontCategory = "serif" | "sans-serif" | "monospace";
+interface FontFamilySpec {
+    /** CSS / Google Fonts family name. */
+    family: string;
+    category: FontCategory;
+    /** Weights to load (ascending). */
+    weights: number[];
+    /** Load italics for these weights too. */
+    italic?: boolean;
+    /** Fontsource package id (`@fontsource/<id>`); derived from the family name when omitted. */
+    fontsourceId?: string;
+    /** The family has an optical-size axis (`font-optical-sizing: auto` is meaningful). */
+    opticalSize?: boolean;
+}
+interface TypePairing {
+    id: string;
+    name: string;
+    heading: FontFamilySpec;
+    body: FontFamilySpec;
+    /** Weight for display/h1–h4. */
+    headingWeight: number;
+    /** Weight for running text. */
+    bodyWeight: number;
+    /** Weight for `<strong>`, buttons and nav. */
+    strongWeight: number;
+    /** Tracking for large headings (display, h1, h2); smaller headings get half. */
+    headingTracking: string;
+    /** Uppercase eyebrow tracking. */
+    eyebrowTracking: string;
+    /** Mood keywords for Studio's pairing picker. */
+    mood: string[];
+    /** Launch template that uses this pairing (doc 04 §7). */
+    template?: string;
+}
+/** System fallback stacks by category (appended after the web font). */
+declare const FALLBACK_STACKS: Record<FontCategory, string[]>;
+declare const TYPE_PAIRINGS: readonly TypePairing[];
+/** Pairing used when `choices.pairing` names an unknown id. */
+declare const DEFAULT_PAIRING_ID = "fraunces-hanken";
+declare function getPairing(id: string): TypePairing | undefined;
+/** `"Hanken Grotesk"` → `hanken-grotesk` */
+declare function fontsourceId(spec: FontFamilySpec): string;
+/** CSS `font-family` stack for one family: the web font, then the category's system stack. */
+declare function fontStack(spec: FontFamilySpec): string;
+/** Families of a pairing with merged weights (heading and body may share a family). */
+declare function pairingFamilies(p: TypePairing): FontFamilySpec[];
+/**
+ * Google Fonts CSS2 API URL for a pairing — for previews and the Studio font picker only;
+ * published sites self-host via Fontsource.
+ */
+declare function googleFontsUrl(p: TypePairing, display?: string): string;
+/** Fontsource npm packages to install for a pairing, e.g. `@fontsource/fraunces`. */
+declare function fontsourcePackages(p: TypePairing): string[];
+/**
+ * Fontsource CSS entry points per weight/style: module specifiers (`@fontsource/fraunces/400.css`)
+ * by default, or jsDelivr URLs with `{ cdn: true }`.
+ */
+declare function fontsourceCss(p: TypePairing, options?: {
+    cdn?: boolean;
+}): string[];
+
+type NeutralTint = "warm" | "cool" | "pure";
+/** Accent ladder lightness per step: perceptually even in OKLCH. */
+declare const ACCENT_LIGHTNESS: ColorScale<number>;
+declare const NEUTRAL_LIGHTNESS: ColorScale<number>;
+/**
+ * 11-step accent scale (50–950) from a brand color: fixed perceptual lightness ladder, hue held,
+ * chroma following the brand's and tapering toward the ends, each step gamut-mapped to sRGB.
+ */
+declare function accentScale(brand: string | Oklch): ColorScale<Oklch>;
+/**
+ * 11-step neutral scale tinted toward the brand. `warm` and `cool` lean the hue toward amber or
+ * blue (pulled 35% toward the brand hue); `pure` is achromatic gray.
+ */
+declare function neutralScale(brand: string | Oklch, tint: NeutralTint): ColorScale<Oklch>;
+/** The scale step whose lightness is closest to the color's (where the brand "sits"). */
+declare function nearestStep(color: string | Oklch): ScaleStep;
+
+interface PaletteInput {
+    brand: string;
+    neutral: NeutralTint;
+    contrast?: ContrastMode;
+}
+interface Palette {
+    brand: Oklch;
+    accent: ColorScale<Oklch>;
+    neutral: ColorScale<Oklch>;
+}
+declare function buildPalette(brand: string | Oklch, neutral: NeutralTint): Palette;
+type RoleSet = Record<ColorRole, Oklch>;
+/** Pick the candidate with the highest contrast against `bg`. */
+declare function bestOn(bg: Oklch, candidates: Oklch[]): Oklch;
+/** Label color for text sitting on `bg`: white or the darkest neutral, whichever contrasts more. */
+declare function onColor(bg: Oklch, palette: Palette): Oklch;
+/** The un-solved role sets for each section theme (doc 04 §3.2). */
+declare function themeRoles(palette: Palette): Record<ColorTheme, RoleSet>;
+interface ContrastAdjustment {
+    theme: ColorTheme;
+    role: ThemeRole;
+    from: string;
+    to: string;
+    /** The role it was adjusted against. */
+    against: ThemeRole;
+    required: number;
+}
+interface SolvedThemes {
+    themes: ThemeColorSet;
+    adjustments: ContrastAdjustment[];
+}
+/**
+ * Unsolved hover/pressed fills: the accent stepped in lightness away from its label (toward it
+ * only when the accent is already at black/white).
+ */
+declare function accentStates(accent: Oklch, label: Oklch): Record<StateRole, Oklch>;
+/**
+ * The contrast solver (doc 04 §3.3). Lightness only, hue never changes.
+ *
+ * 1. Polarity: each theme has light-on-dark or dark-on-light text. Every surface is moved (if
+ *    needed) so the pure extreme of that polarity clears the body minimum with headroom — this
+ *    makes all text/surface pairs jointly solvable.
+ * 2. For every pair in {@link CONTRAST_PAIRS}, the foreground moves the minimum distance (on
+ *    surfaces: only away from them, in the theme's polarity).
+ * 3. If a foreground can't get there (e.g. `accent-text` on a mid-tone `accent` in `high` mode),
+ *    the background moves instead — choosing the direction that keeps the background's own pairs
+ *    passing, flipping the foreground's polarity when that is what it takes.
+ *
+ * 4. Button states: `accent-hover` / `accent-pressed` step the accent's lightness away from its
+ *    label, then are solved against `accent-text` (body) and `background` (UI).
+ *
+ * `text-muted` is kept no stronger than `text`. Iterates until every pair passes.
+ */
+declare function solveThemes(roles: Record<ColorTheme, RoleSet>, mode?: ContrastMode): SolvedThemes;
+
+interface CompileWarning {
+    code: "invalid-brand" | "unknown-pairing" | "invalid-override" | "custom-token" | "contrast-adjusted" | "contrast-failure";
+    path?: string;
+    message: string;
+}
+interface CompileOptions {
+    /**
+     * Run the contrast solver (default `true`). With `false`, colors ship exactly as chosen and
+     * overridden, and `contrast.failures` lists what fails — what Studio shows before the
+     * one-click "nearest accessible" fix.
+     */
+    solve?: boolean;
+}
+interface ThemeTokens {
+    choices: StyleChoices;
+    pairing: TypePairing;
+    palette: {
+        brand: string;
+        brandOklch: string;
+        accent: ColorScale<string>;
+        neutral: ColorScale<string>;
+    };
+    /** Final role colors (`#rrggbb`) per section theme. */
+    themes: ThemeColorSet;
+    fonts: {
+        googleFontsUrl: string;
+        fontsource: string[];
+    };
+    /** Every emitted custom property, by where it is declared. */
+    vars: {
+        root: Record<string, string>;
+        themes: Record<ColorTheme, Record<string, string>>;
+        /** Declared on `:root` and every theme class so `var()` references resolve per section. */
+        themed: Record<string, string>;
+        imageTreatments: Record<string, Record<string, string>>;
+        reducedMotion: Record<string, string>;
+    };
+}
+interface CompiledStyles {
+    tokens: ThemeTokens;
+    css: string;
+    contrast: {
+        mode: ContrastMode;
+        adjustments: ContrastAdjustment[];
+        failures: ContrastFailure[];
+    };
+    warnings: CompileWarning[];
+}
+/** Override scope that targets every section theme: `color.all.<role>`. */
+declare const ALL_THEMES = "all";
+/**
+ * Compile `content/styles.json` into the full token set and the site's token stylesheet.
+ *
+ * Override paths (DTCG):
+ * - `color.all.<role>`: the role in **every** section theme;
+ * - `color.<role>`: the role in the default (light) theme only;
+ * - `color.<theme>.<role>`: the role in one section theme.
+ *   Precedence is theme > light > all. All three apply before the contrast solver runs; an
+ *   overridden `accent` gets a freshly picked `accent-text` unless that is overridden too, and
+ *   `accent-hover`/`accent-pressed` are always derived from the final accent.
+ * - `color.accent-500` / `color.neutral-200` / `color.brand` replace scale variables.
+ * - Every other path maps to `--os-<path>` (see `vars.ts`), e.g. `type.display.letterSpacing`.
+ */
+declare function compileStyles(styles: Styles, options?: CompileOptions): CompiledStyles;
+/** Deterministic token stylesheet. */
+declare function emitCss(tokens: ThemeTokens): string;
+
+/**
+ * Uploaded fonts (PRD §5.1 "Font uploads"): `@font-face` rules for a site's own font files and
+ * the font tokens that use them. The files publish with the site (`media/fonts/`), so the URLs
+ * are resolved by the caller (renderer: base path; Studio canvas: preview URLs).
+ */
+
+/** `"Family", <fallback stack>` for an uploaded family. */
+declare function customFontStack(font: CustomFont): string;
+/** The uploaded font a choice (`headingFont` / `bodyFont`) points at, if any. */
+declare function chosenCustomFont(styles: Pick<Styles, "fonts">, family: string | undefined): CustomFont | undefined;
+/** The available weight closest to `wanted` (ties go to the heavier one). */
+declare function nearestWeight(font: CustomFont, wanted: number): number;
+/**
+ * `@font-face` rules for every uploaded font in use (heading/body choices), or for all of them
+ * with `all: true` (Studio previews). `font-display: swap` keeps text visible while they load.
+ */
+declare function customFontFaces(styles: Pick<Styles, "fonts" | "choices">, url: (src: string) => string, opts?: {
+    all?: boolean;
+}): string;
+/** WOFF2 files worth preloading: the upright file nearest each chosen weight (heading, body). */
+declare function customFontPreloads(styles: Pick<Styles, "fonts" | "choices">, weights: {
+    heading: number;
+    body: number;
+}): string[];
+
+interface PaletteCandidate {
+    hex: string;
+    oklch: string;
+    l: number;
+    c: number;
+    h: number;
+    /** Share of (opaque, sampled) pixels in this cluster, 0–1. */
+    population: number;
+    /** Ranking score: population weighted by chroma, penalizing near-white/black. */
+    score: number;
+}
+interface ExtractOptions {
+    /** Number of clusters (default 6). */
+    k?: number;
+    /** Max candidates returned (default 5). */
+    count?: number;
+    /** Max pixels sampled (default 20 000; sampling is a fixed stride, so deterministic). */
+    maxSamples?: number;
+    /** Channels per pixel in `pixels` (default 4, RGBA). */
+    channels?: 3 | 4;
+}
+/**
+ * Brand color candidates from image pixels (logo or hero photo): weighted k-means in OKLab
+ * (samples weighted toward chromatic pixels), deterministic farthest-point seeding, clusters
+ * ranked by population × chroma. Near-white, near-black and gray clusters rank last; if the image
+ * is entirely achromatic the grays are still returned.
+ */
+declare function extractPalette(pixels: Uint8ClampedArray | Uint8Array | number[], options?: ExtractOptions): PaletteCandidate[];
+
+type Density = (typeof DENSITIES)[number];
+type Shape = (typeof SHAPES)[number];
+type ButtonStyle = (typeof BUTTON_STYLES)[number];
+type MotionLevel = (typeof MOTION_LEVELS)[number];
+/** Space steps (`3xs`…`3xl`) on a 4px base, in px, per density. */
+declare const SPACE_SCALES: Record<Density, Record<string, number>>;
+declare function spaceTokens(density: Density): Record<string, string>;
+declare function sectionTokens(density: Density): Record<string, string>;
+/** Content widths (doc 04 §2.2). */
+declare const WIDTH_TOKENS: {
+    readonly narrow: "720px";
+    readonly content: "1280px";
+    readonly wide: "1440px";
+};
+/** Radius scale + component radii (px) per shape. `full` is always a pill. */
+declare const RADIUS_SCALES: Record<Shape, Record<string, number>>;
+declare function radiusTokens(shape: Shape): Record<string, string>;
+declare const SHADOW_VALUES: Record<"none" | "sm" | "md" | "lg", string>;
+declare const BUTTON_ROLES: readonly ["primary", "secondary", "tertiary"];
+type ButtonRole = (typeof BUTTON_ROLES)[number];
+/** Per-role CSS properties a button reads; each becomes `--os-button-<role>-<prop>`. */
+declare const BUTTON_PROPS: readonly ["bg", "color", "border-color", "border-width", "radius", "padding-x", "padding-y", "text-decoration", "icon", "bg-hover", "color-hover", "border-color-hover", "bg-active", "color-active", "border-color-active"];
+type ButtonProp = (typeof BUTTON_PROPS)[number];
+declare function buttonTokens(style: ButtonStyle): Record<ButtonRole, Record<ButtonProp, string>>;
+declare const MOTION_PROPS: readonly ["enabled", "duration-fast", "duration-base", "duration-slow", "ease", "reveal-distance", "reveal-duration", "stagger", "hover-scale", "parallax"];
+type MotionProp = (typeof MOTION_PROPS)[number];
+declare const MOTION_VALUES: Record<MotionLevel, Record<MotionProp, string>>;
+declare const IMAGE_PROPS: readonly ["radius", "clip-path", "aspect-ratio", "filter", "blend", "backdrop", "overlay", "overlay-blend", "overlay-opacity", "frame-padding", "frame-color", "frame-border"];
+type ImageProp = (typeof IMAGE_PROPS)[number];
+/**
+ * Image treatment tokens. The renderer reads them on the image wrapper (`radius`, `clip-path`,
+ * `aspect-ratio`, `backdrop`, frame), the `<img>` (`filter`, `blend`) and a `::after` overlay.
+ * Duotone: a grayscale image multiplied over a light accent, then a dark accent lightened in.
+ */
+declare const IMAGE_TREATMENT_VALUES: Record<ImageTreatment, Record<ImageProp, string>>;
+
+interface FlatToken {
+    /** Path segments, e.g. `["type", "display", "letterSpacing"]`. */
+    path: string[];
+    token: DtcgToken;
+    /** `$type` from the token or the nearest enclosing group. */
+    type: string | undefined;
+}
+/** Flatten a DTCG group into tokens (sorted by path for deterministic output). */
+declare function flattenDtcg(group: DtcgGroup | undefined): FlatToken[];
+/** A value that is exactly one alias, e.g. `{color.accent-500}`. */
+declare const SOLE_ALIAS_RE: RegExp;
+/** `{color.accent-500}` → `var(--os-color-accent-500)` */
+declare function resolveAliases(value: string): string;
+declare function isSafeCssValue(value: string): boolean;
+/**
+ * Convert a DTCG `$value` to a CSS value, or `null` if it can't be represented safely.
+ * Composite `typography` tokens are expanded by the caller.
+ */
+declare function dtcgToCss(value: DtcgValue, type: string | undefined): string | null;
+
+interface CuratedPalette {
+    id: string;
+    name: string;
+    /** Brand color (OKLCH) the full palette is generated from. */
+    brand: string;
+    neutral: NeutralTint;
+    description: string;
+    /** Launch templates this palette was designed for (doc 04 §7). */
+    templates?: string[];
+}
+/** Named starting palettes for Studio's palette picker. */
+declare const curatedPalettes: readonly CuratedPalette[];
+declare function getCuratedPalette(id: string): CuratedPalette | undefined;
+
+/** Every typography preset: the nine content presets plus the UI-only `button` and `nav`. */
+declare const TYPE_PRESET_NAMES: readonly ["display", "h1", "h2", "h3", "h4", "lead", "body", "small", "eyebrow", "button", "nav"];
+type TypePresetName = (typeof TYPE_PRESET_NAMES)[number];
+/** Fluid scale parameters (doc 04 §4.2). Sizes interpolate between the two viewports. */
+declare const FLUID_TYPE: {
+    readonly minViewport: 360;
+    readonly maxViewport: 1440;
+    /** Body size (px) at the min / max viewport. */
+    readonly minBase: 16;
+    readonly maxBase: 18;
+    readonly minRatio: 1.2;
+    readonly maxRatio: 1.333;
+};
+/** Smallest rendered size (px) for any preset — keeps captions and eyebrows legible. */
+declare const MIN_FONT_SIZE_PX = 14;
+/**
+ * `clamp()` that moves linearly from `minPx` at the min viewport to `maxPx` at the max viewport.
+ * Sizes are emitted in rem so they respect the reader's font-size preference.
+ */
+declare function fluidClamp(minPx: number, maxPx: number, minViewport?: number, maxViewport?: number): string;
+/** Font size (px) for a scale step at the min and max viewport. */
+declare function stepSizes(step: number): {
+    min: number;
+    max: number;
+};
+interface TypePresetTokens {
+    "font-family": string;
+    "font-size": string;
+    "line-height": string;
+    "letter-spacing": string;
+    "font-weight": string;
+    "text-transform": string;
+}
+/** Typography preset tokens for a pairing. Families reference `--os-font-*` vars. */
+declare function typeScale(p: TypePairing): Record<TypePresetName, TypePresetTokens>;
+/** Font family + weight tokens for a pairing. */
+declare function fontTokens(p: TypePairing): Record<string, string>;
+
+/**
+ * The CSS custom-property contract. Every token the compiler emits is named here; the renderer's
+ * base stylesheet and blocks must reference tokens only through these names.
+ *
+ * Naming rule (also how DTCG override paths map to properties): path segments, camelCase turned
+ * kebab-case, joined with `-`, prefixed `--os-`. `type.display.letterSpacing` →
+ * `--os-type-display-letter-spacing`; `color.accent-500` → `--os-color-accent-500`.
+ *
+ * Where each lives in the compiled CSS:
+ * - `color.*` roles: per section theme, on `:root, .os-theme-light` and `.os-theme-<name>`.
+ * - `button.*`, `image.*`: re-declared on `:root` and every `.os-theme-*` so their `var()`
+ *   references resolve against the enclosing section's roles; `.os-image-<treatment>` classes
+ *   override `image.*` per block.
+ * - everything else: `:root`.
+ */
+
+declare const VAR_PREFIX = "--os-";
+/** `["type", "display", "letterSpacing"]` → `--os-type-display-letter-spacing` */
+declare function varName(...path: (string | number)[]): string;
+/** `var(--os-…)` for a path. */
+declare const cssVar: (...path: (string | number)[]) => string;
+/** Variable for a schema color token (`accent`, `text-muted`, `neutral-200`). */
+declare const colorVar: (token: string) => string;
+/** Section theme class: `.os-theme-dark` → `os-theme-dark`. */
+declare const themeClass: (theme: ColorTheme) => string;
+/** Per-block image treatment class. */
+declare const imageTreatmentClass: (treatment: string) => string;
+/** Space steps (schema `SPACE_TOKENS`). */
+declare const SPACE_STEPS: readonly ["none", "3xs", "2xs", "xs", "sm", "md", "lg", "xl", "2xl", "3xl"];
+/** Schema `RADIUS_TOKENS` plus component radii set by the shape choice. */
+declare const RADIUS_NAMES: readonly ["none", "sm", "md", "lg", "xl", "full", "button", "card", "input", "image"];
+/** Schema `SHADOW_TOKENS`. */
+declare const SHADOW_NAMES: readonly ["none", "sm", "md", "lg"];
+declare const TYPE_PROPS: readonly ["font-family", "font-size", "line-height", "letter-spacing", "font-weight", "text-transform"];
+/** The documented variable map. Values are custom-property names (`--os-…`). */
+declare const TOKEN_VARS: {
+    /** Semantic roles plus `accent-hover` / `accent-pressed` (theme-scoped, contrast-solved). */
+    readonly color: Record<ThemeRole, string>;
+    /** Accent scale `--os-color-accent-50` … `-950`. */
+    readonly accent: Record<100 | 500 | 200 | 50 | 300 | 400 | 600 | 700 | 800 | 900 | 950, string>;
+    /** Neutral scale `--os-color-neutral-50` … `-950`. */
+    readonly neutral: Record<100 | 500 | 200 | 50 | 300 | 400 | 600 | 700 | 800 | 900 | 950, string>;
+    /** The (gamut-mapped) brand color as chosen. */
+    readonly brand: string;
+    readonly font: {
+        readonly heading: string;
+        readonly body: string;
+        readonly weightHeading: string;
+        readonly weightBody: string;
+        readonly weightStrong: string;
+    };
+    /** Typography presets: `--os-type-<preset>-<css-property>`. */
+    readonly type: Record<"small" | "display" | "h1" | "h2" | "h3" | "h4" | "lead" | "body" | "eyebrow" | "button" | "nav", Record<"font-family" | "font-size" | "line-height" | "letter-spacing" | "font-weight" | "text-transform", string>>;
+    /** Max line length for running text (~70 characters). */
+    readonly measure: string;
+    readonly space: Record<"none" | "3xs" | "2xs" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl", string>;
+    readonly section: {
+        readonly padY: string;
+        readonly blockGap: string;
+        readonly gutter: string;
+    };
+    readonly width: {
+        readonly narrow: string;
+        readonly content: string;
+        readonly wide: string;
+    };
+    readonly radius: Record<"none" | "input" | "sm" | "md" | "lg" | "xl" | "full" | "image" | "button" | "card", string>;
+    readonly shadow: Record<"none" | "sm" | "md" | "lg", string>;
+    /** Buttons: `--os-button-<primary|secondary|tertiary>-<prop>`. */
+    readonly button: Record<"primary" | "secondary" | "tertiary", Record<"radius" | "color" | "icon" | "bg" | "border-color" | "border-width" | "padding-x" | "padding-y" | "text-decoration" | "bg-hover" | "color-hover" | "border-color-hover" | "bg-active" | "color-active" | "border-color-active", string>>;
+    readonly motion: Record<"stagger" | "parallax" | "enabled" | "duration-fast" | "duration-base" | "duration-slow" | "ease" | "reveal-distance" | "reveal-duration" | "hover-scale", string>;
+    readonly image: Record<"filter" | "radius" | "overlay" | "clip-path" | "aspect-ratio" | "blend" | "backdrop" | "overlay-blend" | "overlay-opacity" | "frame-padding" | "frame-color" | "frame-border", string>;
+};
+/** Every variable name in {@link TOKEN_VARS}, flattened, in declaration order. */
+declare function allTokenVars(): string[];
+/** Section theme class names, in schema order. */
+declare const THEME_CLASSES: string[];
+
+declare const name = "@omniharmonic/openspace-theme";
+
+export { ACCENT_LIGHTNESS, ACHROMATIC_CHROMA, ALL_THEMES, BUTTON_PROPS, BUTTON_ROLES, type ButtonProp, type ButtonRole, type ButtonStyle, CONTRAST_MINIMUMS, CONTRAST_PAIRS, CORE_CONTRAST_PAIRS, type ColorRole, type ColorScale, type CompileOptions, type CompileWarning, type CompiledStyles, type ContrastAdjustment, type ContrastFailure, type ContrastLevel, type ContrastMode, type ContrastPair, type CuratedPalette, DEFAULT_PAIRING_ID, type Density, type Direction, type ExtractOptions, FALLBACK_STACKS, FLUID_TYPE, type FlatToken, type FontCategory, type FontFamilySpec, IMAGE_PROPS, IMAGE_TREATMENT_VALUES, type ImageProp, MIN_FONT_SIZE_PX, MOTION_PROPS, MOTION_VALUES, type MotionLevel, type MotionProp, NEUTRAL_LIGHTNESS, type NeutralTint, type Oklab, type Oklch, type Palette, type PaletteCandidate, type PaletteInput, RADIUS_NAMES, RADIUS_SCALES, type Rgb, SHADOW_NAMES, SHADOW_VALUES, SOLE_ALIAS_RE, SPACE_SCALES, SPACE_STEPS, STATE_PAIRS, STATE_ROLES, type ScaleStep, type Shape, type SolvedThemes, type StateRole, THEME_CLASSES, TOKEN_VARS, TYPE_PAIRINGS, TYPE_PRESET_NAMES, TYPE_PROPS, type ThemeColorSet, type ThemeColors, type ThemeRole, type ThemeTokens, type TypePairing, type TypePresetName, type TypePresetTokens, VAR_PREFIX, WIDTH_TOKENS, accentScale, accentStates, allTokenVars, auditContrast, bestOn, buildPalette, buttonTokens, chosenCustomFont, colorVar, compileStyles, contrastRatio, cssVar, curatedPalettes, customFontFaces, customFontPreloads, customFontStack, deltaEOK, dtcgToCss, emitCss, extractPalette, flattenDtcg, fluidClamp, fontStack, fontTokens, fontsourceCss, fontsourceId, fontsourcePackages, formatOklch, gamutMap, getCuratedPalette, getPairing, googleFontsUrl, hexToOklch, hexToRgb, imageTreatmentClass, inSrgbGamut, isColor, isSafeCssValue, linearChannelToSrgb, linearSrgbToOklab, linearToSrgb, mixHue, name, nearestAccessible, nearestStep, nearestWeight, neutralScale, normalizeHue, oklabToLinearSrgb, oklabToOklch, oklchToHex, oklchToOklab, oklchToSrgb, oklchToSrgbInGamut, onColor, pairingFamilies, parseColor, radiusTokens, relativeLuminance, resolveAliases, rgbToHex, sectionTokens, solveLightness, solveThemes, spaceTokens, srgbChannelToLinear, srgbToLinear, srgbToOklch, stepSizes, themeClass, themeRoles, toHex, typeScale, varName };