/** * The theme knob catalog: typed metadata for the style variables that themes * are expected to turn, keyed by variable name. * * This is a side catalog over `variables.ts` - `StyleVariable` stays the * authored and rendered value form, and the catalog adds the metadata that * value form can't carry: what kind of value a knob takes (which widget edits * it), which axis of the theme space it moves, how much leverage it has (its * control size in the editor), and which tier of the two-tier theme policy it * belongs to. Defaults and base/dark slots are not duplicated here - join * against `default_variables` by name. * * The catalog deliberately covers only the knob tier, not every variable: * the internal ramp intermediates, color stops, and tokens stay out, and the * contextual hooks the base styles read have their own catalog in * `style_hooks.ts`. A catalog entry may be a hook (`hook: true`) consumed by * `style.css` with per-site fallbacks rather than a declared variable - it * exists here so themes can set it without tripping the no-invented-variables * check. * * @module */ import type { StyleVariableName } from './variable.ts'; import { border_radius_variants, border_width_variants, duration_variants, intent_variants, line_height_variants, palette_variants, space_variants } from './variable_data.ts'; /** * Matches a `var(--hue_X)` palette-letter binding, capturing the letter - * the value form `bindable` hue knobs default to. It accepts the whitespace * the theme checks do when they follow a binding, so a value the gates read * as bound to a letter reads that way here too. */ export const HUE_BINDING_MATCHER: RegExp = /^\s*var\(\s*--hue_([a-j])\s*\)\s*$/u; // the border-style keywords the shape knobs offer; `inset`/`outset` derive // their light and dark edges from the border color, which is what makes a // beveled raised/pressed pair expressible const BORDER_STYLE_VALUES = [ 'solid', 'dashed', 'dotted', 'double', 'groove', 'ridge', 'inset', 'outset', 'none' ]; /** * The value kind of a knob, determining the editor widget and how the value * validates. `text` is the unenriched fallback kind. */ export type KnobKind = | 'hue' // OKLCH hue angle in degrees | 'number' // unitless scalar (multipliers, curves, chroma, weights) | 'percent' | 'length' // CSS length like '0.8rem' | 'time' // CSS time in seconds like '0.2s' | 'color' | 'font_stack' | 'enum' | 'shadow' // box-shadow value list | 'text'; /** * The axis of the theme-space taxonomy a knob moves. */ export type KnobAxis = 'color' | 'shape' | 'density' | 'depth' | 'typography' | 'motion' | 'decoration'; /** * Leverage tier: how much of the system a knob reshapes, which the editor * renders as control size through the matching `sized_*` composite (`lg` * headline knobs down to `sm` escape hatches). */ export type KnobLeverage = 'lg' | 'md' | 'sm'; /** * The two-tier theme policy: semantic-tier knobs (intent bindings + levers) * are safe for registry themes; palette-tier knobs (the letter hues) mark a * theme as an exemplar. */ export type KnobTier = 'semantic' | 'palette'; export interface ThemeKnob { name: StyleVariableName; kind: KnobKind; axis: KnobAxis; leverage: KnobLeverage; tier: KnobTier; /** * The safe envelope for scalar kinds - editor sliders clamp to it, while * direct numeric entry may exceed it knowingly. */ range?: [number, number]; step?: number; /** Allowed values for the `enum` kind. */ values?: Array; /** * True for knobs consumed by `style.css` via `var()` fallbacks instead of * being declared in `default_variables`. Only for knobs whose fallbacks * differ per site, so no single declared default exists - * `heading_font_weight`, whose per-tier fallbacks flatten when set. */ hook?: boolean; /** * True for hue knobs whose default is a palette-letter binding * (`var(--hue_X)`) - the intent and neutral hues. Editors render these as * a letter picker with a custom-angle escape, and edits may write either a * binding or a literal angle. */ bindable?: boolean; } const hue = ( name: StyleVariableName, leverage: KnobLeverage, tier: KnobTier = 'semantic', bindable = false ): ThemeKnob => ({ name, kind: 'hue', axis: 'color', leverage, tier, range: [0, 360], step: 1, ...(bindable ? { bindable } : null) }); // a slot chroma multiplier: [0, 1] is the safe envelope (1 = at the gamut // caps); direct entry above 1 knowingly clips, like the global chroma_scale const chroma_multiplier = (name: StyleVariableName, tier: KnobTier): ThemeKnob => ({ name, kind: 'number', axis: 'color', leverage: 'sm', tier, range: [0, 1], step: 0.01 }); // an escape-hatch-leverage CSS length token, pinnable under its family's scale knob const length_knob = (name: StyleVariableName, axis: KnobAxis): ThemeKnob => ({ name, kind: 'length', axis, leverage: 'sm', tier: 'semantic' }); const lightness_ramp = (family: string): Array => [ { name: `${family}_lightness_00`, kind: 'number', axis: 'color', leverage: 'md', tier: 'semantic', range: [0, 1], step: 0.001 }, { name: `${family}_lightness_100`, kind: 'number', axis: 'color', leverage: 'md', tier: 'semantic', range: [0, 1], step: 0.001 }, { name: `${family}_lightness_curve`, kind: 'number', axis: 'color', leverage: 'md', tier: 'semantic', range: [0.2, 4], step: 0.01 } ]; /** * The theme knobs in editor display order: by axis, high leverage first, * with the palette tier last within the color axis. */ export const theme_knobs: ReadonlyArray = [ // color - the leverage core hue('hue_neutral', 'lg', 'semantic', true), { name: 'neutral_chroma', kind: 'number', axis: 'color', leverage: 'lg', tier: 'semantic', range: [0, 0.1], step: 0.001 }, { // the ground's own tint - the shared chroma shape leaves the page // untinted at any neutral_chroma, so a tinted page is this knob; it // fades over the near-ground shade stops so raised surfaces keep the // cast; the stops render it held to sRGB at the ground's lightness // (worst hue, both ends), and a light ground near white has little // room - at the default light ground the slider is inert past ~0.014 name: 'shade_chroma_00', kind: 'number', axis: 'color', leverage: 'md', tier: 'semantic', range: [0, 0.03], step: 0.001 }, { // the fraction of the way the ground moves from the theme's own // lightness toward white (light) or near-black (dark) - a ground // already past the end stays put - bending the shade and text curves // with it, and moving the default control border toward a stronger // stop. The domain is 0 to 1, but the safe envelope stops at 0.75: // the gates hold to about 0.88 (marquee's text stops leave sRGB from // about 0.9), but past 0.75 the ground is within a step of white or // near-black, so the sunken input fill (`input_fill`) stops reading, a // tinted ground loses its cast in light, and every theme's surfaces // converge on the same lightness, for little more text contrast. The // high-contrast modifier sits at // `HIGH_CONTRAST` (0.5), and the OS `prefers-contrast: more` preference // raises the effective value to it name: 'contrast', kind: 'number', axis: 'color', leverage: 'lg', tier: 'semantic', range: [0, 0.75], step: 0.01 }, hue('hue_accent', 'lg', 'semantic', true), { name: 'chroma_scale', kind: 'number', axis: 'color', leverage: 'lg', tier: 'semantic', range: [0, 2], step: 0.05 }, hue('hue_positive', 'md', 'semantic', true), hue('hue_negative', 'md', 'semantic', true), hue('hue_caution', 'md', 'semantic', true), hue('hue_info', 'md', 'semantic', true), // intent chroma-character twins - pair with a binding to a muted slot ...intent_variants.map((i) => chroma_multiplier(`${i}_chroma_scale`, 'semantic')), ...lightness_ramp('palette'), ...lightness_ramp('shade'), ...lightness_ramp('text'), { name: 'palette_chroma_min', kind: 'number', axis: 'color', leverage: 'md', tier: 'semantic', range: [0, 0.06], step: 0.001 }, { // requests up to the per-stop gamut caps; chroma_scale pushes past them name: 'palette_chroma_max', kind: 'number', axis: 'color', leverage: 'md', tier: 'semantic', range: [0, 0.125], step: 0.001 }, { name: 'chroma_curve', kind: 'number', axis: 'color', leverage: 'md', tier: 'semantic', range: [0.2, 4], step: 0.01 }, { // mid-ramp so borders read against both the page background and fills name: 'border_color_lightness', kind: 'number', axis: 'color', leverage: 'sm', tier: 'semantic', range: [0, 1], step: 0.001 }, { // the default derives from the neutral (calc(var(--neutral_chroma) * k)); // setting a literal number pins the border family's chroma name: 'border_color_chroma', kind: 'number', axis: 'color', leverage: 'sm', tier: 'semantic', range: [0, 0.15], step: 0.001 }, { // the role every default border paints through - by default `shade_30` // mixed a quarter of the way toward `shade_50`, all the way as contrast // rises to the high value; repoint it at another stop // (or a text stop, for opaque high-contrast rules) to move them all. A // repointed border is the theme's own and doesn't follow `--contrast` name: 'border_color', kind: 'color', axis: 'color', leverage: 'md', tier: 'semantic' }, { // the sunken fill of inputs; at an extreme ground it has nowhere to go name: 'input_fill', kind: 'color', axis: 'color', leverage: 'sm', tier: 'semantic' }, { // the embedded `.panel`'s fill, translucent ink by default so panels // stack; an opaque value makes a card (white on a tinted page) // TODO the gates don't pair text with it yet; neither is `input_fill` name: 'panel_fill', kind: 'color', axis: 'color', leverage: 'sm', tier: 'semantic' }, // color - micro-surface variables consumed by style.css { name: 'caret_color', kind: 'color', axis: 'color', leverage: 'sm', tier: 'semantic' }, { name: 'scrollbar_thumb_color', kind: 'color', axis: 'color', leverage: 'sm', tier: 'semantic' }, { name: 'scrollbar_track_color', kind: 'color', axis: 'color', leverage: 'sm', tier: 'semantic' }, { // how muted disabled UI reads - a perceptual/color move, not motion name: 'disabled_opacity', kind: 'percent', axis: 'color', leverage: 'sm', tier: 'semantic', range: [0, 100], step: 1 }, // color - the palette tier (moving these makes a theme an exemplar) ...palette_variants.map((l) => hue(`hue_${l}`, 'sm', 'palette')), // per-slot chroma multipliers - a slot's chroma character under chroma_scale ...palette_variants.map((l) => chroma_multiplier(`palette_${l}_chroma_scale`, 'palette')), // shape { name: 'radius_scale', kind: 'number', axis: 'shape', leverage: 'lg', tier: 'semantic', range: [0, 3], step: 0.05 }, { // a floor under every radius tier, which radius_scale can't express name: 'border_radius_min', kind: 'length', axis: 'shape', leverage: 'md', tier: 'semantic' }, { // buttons and form fields (not checkboxes), apart from the surface tiers name: 'control_radius', kind: 'length', axis: 'shape', leverage: 'md', tier: 'semantic' }, { name: 'border_style', kind: 'enum', axis: 'shape', leverage: 'md', tier: 'semantic', values: BORDER_STYLE_VALUES }, { // buttons split off the global style so a theme can raise them against // sunken fields, the way beveled system chrome does name: 'button_border_style', kind: 'enum', axis: 'shape', leverage: 'sm', tier: 'semantic', values: BORDER_STYLE_VALUES }, { name: 'button_border_style_active', kind: 'enum', axis: 'shape', leverage: 'sm', tier: 'semantic', values: BORDER_STYLE_VALUES }, { // the gap between an element's border and its focus/active ring name: 'outline_offset', kind: 'length', axis: 'shape', leverage: 'sm', tier: 'semantic' }, { // the focus ring's line; `none` would remove every ring, so it's left out name: 'outline_style', kind: 'enum', axis: 'shape', leverage: 'sm', tier: 'semantic', values: BORDER_STYLE_VALUES.filter((v) => v !== 'none') }, // the focus ring's width, a tier of the border width ladder by default length_knob('outline_width_focus', 'shape'), length_knob('border_width', 'shape'), ...border_width_variants.map((v) => length_knob(`border_width_${v}`, 'shape')), ...border_radius_variants.map((v) => length_knob(`border_radius_${v}`, 'shape')), // density { name: 'space_scale', kind: 'number', axis: 'density', leverage: 'lg', tier: 'semantic', range: [0.25, 2], step: 0.05 }, ...space_variants.map((v) => length_knob(`space_${v}`, 'density')), // depth { name: 'shadow_alpha_scale', kind: 'number', axis: 'depth', leverage: 'lg', tier: 'semantic', range: [0, 2], step: 0.05 }, { name: 'shadow_color_umbra', kind: 'color', axis: 'depth', leverage: 'md', tier: 'semantic' }, { name: 'shadow_color_highlight', kind: 'color', axis: 'depth', leverage: 'md', tier: 'semantic' }, { name: 'shadow_color_glow', kind: 'color', axis: 'depth', leverage: 'md', tier: 'semantic' }, { name: 'shadow_color_shroud', kind: 'color', axis: 'depth', leverage: 'md', tier: 'semantic' }, // the dialog/fullscreen ::backdrop dim { name: 'backdrop_color', kind: 'color', axis: 'depth', leverage: 'sm', tier: 'semantic' }, { name: 'button_shadow', kind: 'shadow', axis: 'depth', leverage: 'md', tier: 'semantic' }, { name: 'button_shadow_hover', kind: 'shadow', axis: 'depth', leverage: 'md', tier: 'semantic' }, { name: 'button_shadow_active', kind: 'shadow', axis: 'depth', leverage: 'md', tier: 'semantic' }, // the surface shadows: a floating `.pane` and an embedded `.panel` { name: 'pane_shadow', kind: 'shadow', axis: 'depth', leverage: 'md', tier: 'semantic' }, { name: 'panel_shadow', kind: 'shadow', axis: 'depth', leverage: 'md', tier: 'semantic' }, // typography { // the body font; the three stacks below stay what they say they are name: 'font_family', kind: 'font_stack', axis: 'typography', leverage: 'lg', tier: 'semantic' }, { // where the size ladder starts: every step, body text included, so // small text keeps its proportion to body; 0.0625 is 1px of body text name: 'font_size_scale', kind: 'number', axis: 'typography', leverage: 'lg', tier: 'semantic', range: [0.75, 1.5], step: 0.0625 }, { // the ratio between font size steps above `md` - down flattens the // heading hierarchy, up dramatizes it; body and small text stay put // (the `sized_lg`/`sized_xl` composites step up the same ladder, so they follow) name: 'type_scale_ratio', kind: 'number', axis: 'typography', leverage: 'lg', tier: 'semantic', range: [1.1, 1.5], step: 0.002 }, { name: 'font_family_sans', kind: 'font_stack', axis: 'typography', leverage: 'md', tier: 'semantic' }, { name: 'font_family_serif', kind: 'font_stack', axis: 'typography', leverage: 'md', tier: 'semantic' }, { name: 'font_family_mono', kind: 'font_stack', axis: 'typography', leverage: 'md', tier: 'semantic' }, { name: 'heading_font_family', kind: 'font_stack', axis: 'typography', leverage: 'md', tier: 'semantic' }, { // heading tracking - tighten it under heavy display type, open it for // small capitals; an em value follows each heading tier's size name: 'heading_letter_spacing', kind: 'length', axis: 'typography', leverage: 'sm', tier: 'semantic' }, { name: 'font_weight', kind: 'number', axis: 'typography', leverage: 'md', tier: 'semantic', range: [100, 900], step: 100 }, { // setting this flattens the per-tier heading weight ladder deliberately name: 'heading_font_weight', kind: 'number', axis: 'typography', leverage: 'md', tier: 'semantic', range: [100, 900], step: 100, hook: true }, { // how a link is marked at rest; hover and selected carry their own name: 'text_decoration', kind: 'enum', axis: 'typography', leverage: 'md', tier: 'semantic', values: ['none', 'underline', 'underline dotted', 'underline dashed'] }, ...line_height_variants.map((v): ThemeKnob => ({ name: `line_height_${v}`, kind: 'number', axis: 'typography', leverage: 'sm', tier: 'semantic', range: [0.8, 3], step: 0.05 })), // motion ...duration_variants.map((n): ThemeKnob => ({ name: `duration_${n}`, kind: 'time', axis: 'motion', leverage: 'sm', tier: 'semantic', range: [0, 5], step: 0.01 })), // decoration { name: 'background_image', kind: 'text', axis: 'decoration', leverage: 'md', tier: 'semantic' } ]; /** * The theme-space axes in editor display order, with display titles. */ export const theme_knob_axes: ReadonlyArray<{ axis: KnobAxis; title: string }> = [ { axis: 'color', title: 'Color' }, { axis: 'shape', title: 'Shape' }, { axis: 'density', title: 'Density' }, { axis: 'depth', title: 'Depth' }, { axis: 'typography', title: 'Typography' }, { axis: 'motion', title: 'Motion' }, { axis: 'decoration', title: 'Decoration' } ]; /** * The catalog indexed by variable name. */ export const theme_knob_by_name: ReadonlyMap = new Map( theme_knobs.map((k) => [k.name, k]) ); /** * Names of hook knobs - consumed by `style.css` via fallbacks, not declared * in `default_variables`. Theme validation unions these with the declared * variable names. */ export const theme_knob_hook_names: ReadonlySet = new Set( theme_knobs.filter((k) => k.hook).map((k) => k.name) );