@nordmanai/nif 0.0.0-stage → 0.2.0

package/registry/ui/lib/appearance/appearanceState.ts

@@ -0,0 +1,240 @@
+import {
+  NM_ACCENT_PRESETS,
+  NM_APPEARANCE_CONTRAST,
+  NM_APPEARANCE_DEFAULTS,
+  NM_APPEARANCE_MODES,
+  NM_APPEARANCE_STORAGE_KEY,
+  NM_UI_FONT_SIZE_PX,
+  NM_UI_FONT_WEIGHT,
+  NM_UI_ICON_SIZE_PX,
+  NM_UI_RADIUS_PERCENT,
+  NM_UI_SPACE_PERCENT,
+  findThemePreset,
+  type NmAccentPreset,
+  type NmAppearanceMode,
+} from '../../config/nm-appearance.ts';
+import { normalizeHexColor } from './color.ts';
+
+export type NmAppearanceState = {
+  mode: NmAppearanceMode;
+  themePresetId: string;
+  accentPreset: NmAccentPreset;
+  customAccentHex: string;
+  backgroundHex: string;
+  foregroundHex: string;
+  uiFontSizePx: number;
+  uiFontWeight: number;
+  uiIconSizePx: number;
+  uiRadiusPercent: number;
+  uiSpacePercent: number;
+  contrast: number;
+};
+
+export { NM_APPEARANCE_STORAGE_KEY };
+
+function isMode(value: unknown): value is NmAppearanceMode {
+  return typeof value === 'string' && (NM_APPEARANCE_MODES as readonly string[]).includes(value);
+}
+
+function isAccentPreset(value: unknown): value is NmAccentPreset {
+  return typeof value === 'string' && (NM_ACCENT_PRESETS as readonly string[]).includes(value);
+}
+
+function clampInt(value: unknown, min: number, max: number, fallback: number): number {
+  const n = typeof value === 'number' ? value : Number(value);
+  if (!Number.isFinite(n)) {
+    return fallback;
+  }
+  return Math.min(max, Math.max(min, Math.round(n)));
+}
+
+function prefersDarkColorScheme(): boolean {
+  if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') {
+    return true;
+  }
+  return window.matchMedia('(prefers-color-scheme: dark)').matches;
+}
+
+export function resolveAppearanceScheme(
+  mode: NmAppearanceMode,
+  prefersDark: boolean = prefersDarkColorScheme(),
+): 'light' | 'dark' {
+  if (mode === 'light') {
+    return 'light';
+  }
+  if (mode === 'dark') {
+    return 'dark';
+  }
+  return prefersDark ? 'dark' : 'light';
+}
+
+export function createDefaultAppearanceState(): NmAppearanceState {
+  const base: NmAppearanceState = {
+    mode: NM_APPEARANCE_DEFAULTS.mode,
+    themePresetId: NM_APPEARANCE_DEFAULTS.themePresetId,
+    accentPreset: NM_APPEARANCE_DEFAULTS.accentPreset,
+    customAccentHex: NM_APPEARANCE_DEFAULTS.customAccentHex,
+    backgroundHex: NM_APPEARANCE_DEFAULTS.backgroundHex,
+    foregroundHex: NM_APPEARANCE_DEFAULTS.foregroundHex,
+    uiFontSizePx: NM_APPEARANCE_DEFAULTS.uiFontSizePx,
+    uiFontWeight: NM_APPEARANCE_DEFAULTS.uiFontWeight,
+    uiIconSizePx: NM_APPEARANCE_DEFAULTS.uiIconSizePx,
+    uiRadiusPercent: NM_APPEARANCE_DEFAULTS.uiRadiusPercent,
+    uiSpacePercent: NM_APPEARANCE_DEFAULTS.uiSpacePercent,
+    contrast: NM_APPEARANCE_CONTRAST.default,
+  };
+  return applyThemePresetPalette(base);
+}
+
+export function paletteForPreset(
+  themePresetId: string,
+  scheme: 'light' | 'dark',
+): { backgroundHex: string; foregroundHex: string } {
+  const preset =
+    findThemePreset(themePresetId) ?? findThemePreset(NM_APPEARANCE_DEFAULTS.themePresetId)!;
+  const pair = scheme === 'dark' ? preset.dark : preset.light;
+  return {
+    backgroundHex: pair.canvas,
+    foregroundHex: pair.foreground,
+  };
+}
+
+/** Saved settings from before the website palette keep following the Nordman theme. */
+const LEGACY_NORDMAN_COLORS: Readonly<Record<string, 'light' | 'dark'>> = {
+  '#000000/#ffffff': 'dark',
+  '#fcfaf6/#0a0a0a': 'light',
+};
+
+function currentNordmanColors(
+  themePresetId: string,
+  backgroundHex: string,
+  foregroundHex: string,
+): { backgroundHex: string; foregroundHex: string } {
+  const key = `${backgroundHex}/${foregroundHex}`.toLowerCase();
+  const scheme = LEGACY_NORDMAN_COLORS[key];
+  if (themePresetId !== NM_APPEARANCE_DEFAULTS.themePresetId || scheme == null) {
+    return { backgroundHex, foregroundHex };
+  }
+  return paletteForPreset(themePresetId, scheme);
+}
+
+export function parseAppearanceState(raw: unknown): NmAppearanceState {
+  const defaults = createDefaultAppearanceState();
+  if (!raw || typeof raw !== 'object') {
+    return defaults;
+  }
+  const record = raw as Record<string, unknown>;
+  const themePresetId =
+    typeof record.themePresetId === 'string' && findThemePreset(record.themePresetId)
+      ? record.themePresetId
+      : defaults.themePresetId;
+
+  const colors = currentNordmanColors(
+    themePresetId,
+    normalizeHexColor(
+      typeof record.backgroundHex === 'string' ? record.backgroundHex : defaults.backgroundHex,
+      defaults.backgroundHex,
+    ),
+    normalizeHexColor(
+      typeof record.foregroundHex === 'string' ? record.foregroundHex : defaults.foregroundHex,
+      defaults.foregroundHex,
+    ),
+  );
+
+  return {
+    mode: isMode(record.mode) ? record.mode : defaults.mode,
+    themePresetId,
+    accentPreset: isAccentPreset(record.accentPreset) ? record.accentPreset : defaults.accentPreset,
+    customAccentHex: normalizeHexColor(
+      typeof record.customAccentHex === 'string'
+        ? record.customAccentHex
+        : defaults.customAccentHex,
+      defaults.customAccentHex,
+    ),
+    ...colors,
+    uiFontSizePx: clampInt(
+      record.uiFontSizePx,
+      NM_UI_FONT_SIZE_PX.min,
+      NM_UI_FONT_SIZE_PX.max,
+      defaults.uiFontSizePx,
+    ),
+    uiFontWeight: Math.round(
+      clampInt(record.uiFontWeight, NM_UI_FONT_WEIGHT.min, NM_UI_FONT_WEIGHT.max, defaults.uiFontWeight) / 100,
+    ) * 100,
+    uiIconSizePx: clampInt(
+      record.uiIconSizePx,
+      NM_UI_ICON_SIZE_PX.min,
+      NM_UI_ICON_SIZE_PX.max,
+      defaults.uiIconSizePx,
+    ),
+    uiRadiusPercent: clampInt(
+      record.uiRadiusPercent,
+      NM_UI_RADIUS_PERCENT.min,
+      NM_UI_RADIUS_PERCENT.max,
+      defaults.uiRadiusPercent,
+    ),
+    uiSpacePercent: clampInt(
+      record.uiSpacePercent,
+      NM_UI_SPACE_PERCENT.min,
+      NM_UI_SPACE_PERCENT.max,
+      defaults.uiSpacePercent,
+    ),
+    contrast: clampInt(
+      record.contrast,
+      NM_APPEARANCE_CONTRAST.min,
+      NM_APPEARANCE_CONTRAST.max,
+      defaults.contrast,
+    ),
+  };
+}
+
+export function readStoredAppearanceState(): NmAppearanceState | null {
+  if (typeof window === 'undefined') {
+    return null;
+  }
+  try {
+    const raw = window.localStorage.getItem(NM_APPEARANCE_STORAGE_KEY);
+    if (!raw) {
+      return null;
+    }
+    return parseAppearanceState(JSON.parse(raw));
+  } catch {
+    return null;
+  }
+}
+
+export function writeStoredAppearanceState(state: NmAppearanceState): void {
+  if (typeof window === 'undefined') {
+    return;
+  }
+  window.localStorage.setItem(NM_APPEARANCE_STORAGE_KEY, JSON.stringify(state));
+}
+
+export function mergeThemePresetColors(
+  state: NmAppearanceState,
+  scheme: 'light' | 'dark',
+): NmAppearanceState {
+  // The Custom theme keeps whatever colours the person chose.
+  if (state.themePresetId === 'custom') {
+    return state;
+  }
+  const { backgroundHex, foregroundHex } = paletteForPreset(state.themePresetId, scheme);
+  const preset = findThemePreset(state.themePresetId);
+  const next: NmAppearanceState = {
+    ...state,
+    backgroundHex: normalizeHexColor(backgroundHex, state.backgroundHex),
+    foregroundHex: normalizeHexColor(foregroundHex, state.foregroundHex),
+  };
+  if (next.accentPreset === 'default' && preset) {
+    next.customAccentHex = normalizeHexColor(preset.swatch, next.customAccentHex);
+  }
+  return next;
+}
+
+/** Sync background and foreground (and default accent) from the active theme preset + mode. */
+export function applyThemePresetPalette(
+  state: NmAppearanceState,
+  prefersDark: boolean = prefersDarkColorScheme(),
+): NmAppearanceState {
+  return mergeThemePresetColors(state, resolveAppearanceScheme(state.mode, prefersDark));
+}

package/registry/ui/lib/appearance/applyAppearance.ts

@@ -0,0 +1,36 @@
+import type { NmAppearanceState } from './appearanceState.ts';
+import { NM_APPEARANCE_APPLIED_EVENT, NM_APPEARANCE_CSS_VARS } from '../../config/nm-appearance.ts';
+import { resolveAppearanceScheme } from './appearanceState.ts';
+import { deriveAppearanceTokens } from './deriveTokens.ts';
+import { createLogger } from '../../kit-logger.ts';
+
+const logger = createLogger('interface-appearance-apply');
+
+function prefersDarkColorScheme(): boolean {
+  if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') {
+    return true;
+  }
+  return window.matchMedia('(prefers-color-scheme: dark)').matches;
+}
+
+export function clearAppliedAppearance(root: HTMLElement = document.documentElement): void {
+  NM_APPEARANCE_CSS_VARS.forEach((property) => {
+    root.style.removeProperty(property);
+  });
+}
+
+export function applyAppearanceState(
+  state: NmAppearanceState,
+  root: HTMLElement = document.documentElement,
+): { scheme: 'light' | 'dark' } {
+  const scheme = resolveAppearanceScheme(state.mode, prefersDarkColorScheme());
+  const tokens = deriveAppearanceTokens(state, scheme);
+  logger.debug('apply', 'appearance', { mode: state.mode, scheme, theme: state.themePresetId });
+  Object.entries(tokens).forEach(([property, value]) => {
+    root.style.setProperty(property, value);
+  });
+  if (typeof window !== 'undefined') {
+    window.dispatchEvent(new CustomEvent(NM_APPEARANCE_APPLIED_EVENT));
+  }
+  return { scheme };
+}

package/registry/ui/lib/appearance/cloudOrbAppearance.ts

@@ -0,0 +1,36 @@
+import type { CloudAppearance } from 'orb-ui';
+import { mixHex } from './color.ts';
+
+export function deriveCloudOrbAppearance(
+  accent: string,
+  canvas: string,
+  fg: string,
+): CloudAppearance {
+  return {
+    deepColor: mixHex(accent, canvas, 0.55),
+    upperColor: mixHex(accent, fg, 0.28),
+    lowerColor: mixHex(accent, canvas, 0.12),
+    highlightColor: mixHex(accent, fg, 0.62),
+    launchColor: mixHex(accent, canvas, 0.38),
+    spinnerColor: accent,
+  };
+}
+
+export function cloudOrbAppearanceCssVars(appearance: CloudAppearance): Record<string, string> {
+  return {
+    '--orb-ui-cloud-appearance-deepColor': appearance.deepColor,
+    '--orb-ui-cloud-appearance-upperColor': appearance.upperColor,
+    '--orb-ui-cloud-appearance-lowerColor': appearance.lowerColor,
+    '--orb-ui-cloud-appearance-highlightColor': appearance.highlightColor,
+    '--orb-ui-cloud-appearance-launchColor': appearance.launchColor,
+    '--orb-ui-cloud-appearance-spinnerColor': appearance.spinnerColor,
+  };
+}
+
+export function deriveCloudOrbAppearanceTokens(
+  accent: string,
+  canvas: string,
+  fg: string,
+): Record<string, string> {
+  return cloudOrbAppearanceCssVars(deriveCloudOrbAppearance(accent, canvas, fg));
+}

package/registry/ui/lib/appearance/color.ts

@@ -0,0 +1,96 @@
+const HEX_PATTERN = /^#([0-9a-fA-F]{6})$/;
+
+export function isHexColor(value: string): boolean {
+  return HEX_PATTERN.test(value);
+}
+
+export function normalizeHexColor(value: string, fallback: string): string {
+  const trimmed = value.trim();
+  if (!trimmed.startsWith('#')) {
+    const withHash = `#${trimmed}`;
+    if (isHexColor(withHash)) {
+      return withHash.toUpperCase();
+    }
+  }
+  if (isHexColor(trimmed)) {
+    return trimmed.toUpperCase();
+  }
+  return fallback.toUpperCase();
+}
+
+export function hexToRgbTriplet(hex: string): string {
+  const normalized = normalizeHexColor(hex, '#000000').slice(1);
+  const r = Number.parseInt(normalized.slice(0, 2), 16);
+  const g = Number.parseInt(normalized.slice(2, 4), 16);
+  const b = Number.parseInt(normalized.slice(4, 6), 16);
+  return `${r} ${g} ${b}`;
+}
+
+function channel(value: number): number {
+  return Math.min(255, Math.max(0, Math.round(value)));
+}
+
+/** Mix hex `color` toward `target` by amount in [0, 1]. */
+export function mixHex(color: string, target: string, amount: number): string {
+  const a = normalizeHexColor(color, '#000000').slice(1);
+  const b = normalizeHexColor(target, '#000000').slice(1);
+  const t = Math.min(1, Math.max(0, amount));
+  const parse = (hex: string, start: number) => Number.parseInt(hex.slice(start, start + 2), 16);
+  const ar = parse(a, 0);
+  const ag = parse(a, 2);
+  const ab = parse(a, 4);
+  const br = parse(b, 0);
+  const bg = parse(b, 2);
+  const bb = parse(b, 4);
+  const r = channel(ar + (br - ar) * t);
+  const g = channel(ag + (bg - ag) * t);
+  const bl = channel(ab + (bb - ab) * t);
+  return `#${r.toString(16).padStart(2, '0')}${g.toString(16).padStart(2, '0')}${bl.toString(16).padStart(2, '0')}`.toUpperCase();
+}
+
+function relativeLuminance(hex: string): number {
+  const [r, g, b] = hexToRgbTriplet(hex).split(' ').map((value) => {
+    const unit = Number(value) / 255;
+    return unit <= 0.03928 ? unit / 12.92 : ((unit + 0.055) / 1.055) ** 2.4;
+  });
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+/** WCAG contrast ratio between two colours, from 1 to 21. */
+export function contrastRatio(first: string, second: string): number {
+  const a = relativeLuminance(first);
+  const b = relativeLuminance(second);
+  return (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05);
+}
+
+export function hexToHsl(hex: string): { hue: number; saturation: number; lightness: number } {
+  const [r, g, b] = hexToRgbTriplet(hex).split(' ').map((value) => Number(value) / 255);
+  const max = Math.max(r, g, b);
+  const min = Math.min(r, g, b);
+  const delta = max - min;
+  const lightness = (max + min) / 2;
+  if (delta === 0) {
+    return { hue: 0, saturation: 0, lightness };
+  }
+  const saturation = delta / (1 - Math.abs(2 * lightness - 1));
+  let sector = (r - g) / delta + 4;
+  if (max === r) {
+    sector = ((g - b) / delta + 6) % 6;
+  } else if (max === g) {
+    sector = (b - r) / delta + 2;
+  }
+  return { hue: sector * 60, saturation, lightness };
+}
+
+export function hslToHex(hue: number, saturation: number, lightness: number): string {
+  const chroma = (1 - Math.abs(2 * lightness - 1)) * saturation;
+  const part = (offset: number): number => {
+    const turn = (offset + hue / 30) % 12;
+    const value = lightness - (chroma / 2) * Math.max(-1, Math.min(turn - 3, 9 - turn, 1));
+    return channel(value * 255);
+  };
+  const hex = [part(0), part(8), part(4)]
+    .map((value) => value.toString(16).padStart(2, '0'))
+    .join('');
+  return `#${hex}`.toUpperCase();
+}

package/registry/ui/lib/appearance/deriveTokens.ts

@@ -0,0 +1,218 @@
+import type { NmAppearanceState } from './appearanceState.ts';
+import {
+  NM_ACCENT_HEX,
+  NM_APPEARANCE_CONTRAST,
+  NM_THEME_PRESETS,
+  NM_UI_FONT_SIZE_PX,
+  NM_UI_FONT_WEIGHT,
+  NM_UI_ICON_SIZE_PX,
+  NM_UI_RADIUS_PERCENT,
+  NM_UI_SPACE_PERCENT,
+  findThemePreset,
+} from '../../config/nm-appearance.ts';
+import { NM_SITE_PALETTE } from '../../config/nm-site-palette.ts';
+import { deriveCloudOrbAppearanceTokens } from './cloudOrbAppearance.ts';
+import { hexToRgbTriplet, mixHex, normalizeHexColor } from './color.ts';
+import { deriveMarkTokens } from './markTokens.ts';
+import { NM_RADIUS_SCALE_VAR } from '../../config/nm-radius.ts';
+
+export type NmDerivedAppearanceTokens = Record<string, string>;
+
+/** The accent colour that is in effect for these settings. */
+export function resolveAccentHex(state: NmAppearanceState): string {
+  if (state.accentPreset === 'custom') {
+    return normalizeHexColor(state.customAccentHex, '#D2BB9C');
+  }
+  if (state.accentPreset === 'default' && state.themePresetId === 'custom') {
+    return normalizeHexColor(state.customAccentHex, '#D2BB9C');
+  }
+  if (state.accentPreset === 'default') {
+    const preset = findThemePreset(state.themePresetId);
+    return preset?.swatch ?? NM_THEME_PRESETS[0].swatch;
+  }
+  return NM_ACCENT_HEX[state.accentPreset];
+}
+
+/** Contrast adjusts container surface mix strength only (0 = subtle, max = strong). */
+function surfaceMixStrength(contrast: number, scheme: 'light' | 'dark'): number {
+  const t = contrast / NM_APPEARANCE_CONTRAST.max;
+  const min = scheme === 'dark' ? 0.06 : 0.05;
+  const max = scheme === 'dark' ? 0.42 : 0.38;
+  return min + t * (max - min);
+}
+
+function deriveIconTokens(uiIconSizePx: number): Record<string, string> {
+  const iconPx = `${uiIconSizePx}px`;
+  const smPx = Math.max(NM_UI_ICON_SIZE_PX.min, uiIconSizePx - 4);
+  return {
+    '--nm-icon-button': iconPx,
+    '--nm-icon-sm': `${smPx}px`,
+    '--nm-rail-icon': iconPx,
+  };
+}
+
+function deriveUiControlTokens(uiFontSizePx: number, uiIconSizePx: number): Record<string, string> {
+  const padPx = 8;
+  const iconControlPx = uiIconSizePx + padPx * 2;
+  const chipMinPx = Math.max(iconControlPx, uiFontSizePx + padPx * 2);
+  return {
+    '--nm-ui-chip-min-height': `${chipMinPx}px`,
+  };
+}
+
+function deriveRadiusScale(uiRadiusPercent: number): Record<string, string> {
+  const scale = uiRadiusPercent / NM_UI_RADIUS_PERCENT.default;
+  return {
+    [NM_RADIUS_SCALE_VAR]: String(scale),
+  };
+}
+
+function deriveSpaceScale(uiSpacePercent: number): Record<string, string> {
+  return {
+    '--nm-space-scale': String(uiSpacePercent / NM_UI_SPACE_PERCENT.default),
+  };
+}
+
+/** The setting is Regular. The heavier weights step up a hundred each, and light steps down. */
+function deriveWeightTokens(base: number): Record<string, string> {
+  const step = (by: number) => String(Math.min(NM_UI_FONT_WEIGHT.max, Math.max(NM_UI_FONT_WEIGHT.min, base + by)));
+  return {
+    '--nm-weight-light': step(-100),
+    '--nm-weight-regular': step(0),
+    '--nm-weight-medium': step(100),
+    '--nm-weight-semibold': step(200),
+    '--nm-weight-bold': step(300),
+  };
+}
+
+function deriveTypeTokens(uiFontSizePx: number): Record<string, string> {
+  const uiScale = uiFontSizePx / NM_UI_FONT_SIZE_PX.default;
+  const bodyPx = `${uiFontSizePx}px`;
+  const uiSmPx = `${Math.max(NM_UI_FONT_SIZE_PX.min, uiFontSizePx - 2)}px`;
+
+  return {
+    '--nm-type-body': bodyPx,
+    '--nm-type-ui': bodyPx,
+    '--control-fs': bodyPx,
+    '--nm-type-ui-sm': uiSmPx,
+    '--nm-type-lede': `${uiScale * 1.5}rem`,
+    '--nm-type-section': `${uiScale * 2.5}rem`,
+    '--nm-type-card': `${uiScale * 2}rem`,
+    '--nm-type-caption': `${uiScale * 0.75}rem`,
+    '--markdown-font-size': bodyPx,
+    '--font-size-base': bodyPx,
+    '--font-size-sm': uiSmPx,
+  };
+}
+
+/** Overrides ThemeProvider inline colors so Chat chrome uses appearance SSOT. */
+function deriveLibreChatBridge(
+  tokens: NmDerivedAppearanceTokens,
+  accent: string,
+): Record<string, string> {
+  const accentRgb = hexToRgbTriplet(accent);
+  return {
+    '--text-primary': tokens['--nm-fg-rgb']!,
+    '--text-secondary': tokens['--nm-fg-subtle-rgb']!,
+    '--text-tertiary': tokens['--nm-stroke-rgb']!,
+    '--text-muted': tokens['--nm-fg-muted-rgb']!,
+    '--presentation': tokens['--nm-canvas-rgb']!,
+    '--surface-primary': tokens['--nm-canvas-rgb']!,
+    '--surface-chat': tokens['--nm-canvas-rgb']!,
+    '--surface-secondary': tokens['--nm-panel-rgb']!,
+    '--surface-secondary-alt': tokens['--nm-line-rgb']!,
+    '--surface-tertiary': tokens['--nm-raised-rgb']!,
+    '--surface-primary-alt': tokens['--nm-raised-rgb']!,
+    '--surface-dialog': tokens['--nm-panel-rgb']!,
+    '--surface-hover': tokens['--nm-panel-rgb']!,
+    '--surface-active': tokens['--nm-line-rgb']!,
+    '--border-light': tokens['--nm-line-rgb']!,
+    '--border-medium': tokens['--nm-stroke-rgb']!,
+    '--link': accentRgb,
+    '--link-hover': accentRgb,
+    '--link-visited': accentRgb,
+    '--accent-primary': accentRgb,
+    '--ring-primary': accentRgb,
+    '--brand-purple': accentRgb,
+    '--nordman-accent': accentRgb,
+  };
+}
+
+/** The untouched Nordman theme shows the website palette; anything else mixes its own surfaces. */
+function usesSitePalette(
+  state: NmAppearanceState,
+  scheme: 'light' | 'dark',
+  canvas: string,
+  fg: string,
+): boolean {
+  const site = NM_SITE_PALETTE[scheme];
+  return (
+    state.themePresetId === NM_THEME_PRESETS[0].id &&
+    state.contrast === NM_APPEARANCE_CONTRAST.default &&
+    canvas.toLowerCase() === site.canvas &&
+    fg.toLowerCase() === site.fg
+  );
+}
+
+export function deriveAppearanceTokens(
+  state: NmAppearanceState,
+  scheme: 'light' | 'dark',
+): NmDerivedAppearanceTokens {
+  const canvas = normalizeHexColor(state.backgroundHex, '#000000');
+  const fg = normalizeHexColor(state.foregroundHex, '#ffffff');
+  const accent = resolveAccentHex(state);
+  const mix = surfaceMixStrength(state.contrast, scheme);
+
+  const site = usesSitePalette(state, scheme, canvas, fg) ? NM_SITE_PALETTE[scheme] : null;
+  const panel = site?.panel ?? mixHex(canvas, fg, mix);
+  const raised = site?.raised ?? mixHex(canvas, fg, mix * 0.72);
+  const inset = site?.inset ?? mixHex(canvas, fg, mix * 0.85);
+  const line = site?.line ?? mixHex(canvas, fg, Math.min(0.55, mix + 0.12));
+  const lineStrong = site?.lineStrong ?? mixHex(canvas, fg, Math.min(0.6, mix + 0.17));
+  const stroke = site?.stroke ?? mixHex(canvas, fg, Math.min(0.65, mix + 0.22));
+  const fgMuted = site?.muted ?? mixHex(fg, canvas, 0.22);
+  const fgSubtle = site?.subtle ?? mixHex(fg, canvas, 0.38);
+
+  const nmTokens: NmDerivedAppearanceTokens = {
+    '--nm-canvas': canvas,
+    '--nm-fg': fg,
+    '--nm-fg-muted': fgMuted,
+    '--nm-fg-subtle': fgSubtle,
+    '--nm-stroke': stroke,
+    '--nm-line': line,
+    '--nm-line-strong': lineStrong,
+    '--nm-divider': mixHex(canvas, fg, (state.contrast / NM_APPEARANCE_CONTRAST.max) * 0.5),
+    '--nm-panel': panel,
+    '--nm-raised': raised,
+    '--nm-inset': inset,
+    '--nm-canvas-rgb': hexToRgbTriplet(canvas),
+    '--nm-fg-rgb': hexToRgbTriplet(fg),
+    '--nm-fg-muted-rgb': hexToRgbTriplet(fgMuted),
+    '--nm-fg-subtle-rgb': hexToRgbTriplet(fgSubtle),
+    '--nm-stroke-rgb': hexToRgbTriplet(stroke),
+    '--nm-line-rgb': hexToRgbTriplet(line),
+    '--nm-panel-rgb': hexToRgbTriplet(panel),
+    '--nm-raised-rgb': hexToRgbTriplet(raised),
+    '--nm-inset-rgb': hexToRgbTriplet(inset),
+    '--sand': accent,
+    '--nm-accent': accent,
+    '--nm-accent-rgb': hexToRgbTriplet(accent),
+    ...deriveCloudOrbAppearanceTokens(accent, canvas, fg),
+    ...deriveMarkTokens(accent, canvas, fg),
+    ...deriveTypeTokens(state.uiFontSizePx),
+    ...deriveWeightTokens(state.uiFontWeight),
+    ...deriveIconTokens(state.uiIconSizePx),
+    ...deriveUiControlTokens(state.uiFontSizePx, state.uiIconSizePx),
+    ...deriveRadiusScale(state.uiRadiusPercent),
+    ...deriveSpaceScale(state.uiSpacePercent),
+  };
+
+  return {
+    ...nmTokens,
+    ...deriveLibreChatBridge(nmTokens, accent),
+  };
+}
+
+export function themeModeFromAppearance(mode: NmAppearanceState['mode']): string {
+  return mode;
+}

package/registry/ui/lib/appearance/index.ts

@@ -0,0 +1,6 @@
+export * from '../../config/nm-appearance.ts';
+export * from './appearanceState.ts';
+export * from './applyAppearance.ts';
+export * from './color.ts';
+export * from './deriveTokens.ts';
+export * from './readLayoutMetrics.ts';

package/registry/ui/lib/appearance/markTokens.ts

@@ -0,0 +1,49 @@
+import { contrastRatio, hexToHsl, hslToHex, mixHex } from './color.ts';
+
+/** Text smaller than 18px needs 4.5:1. The margin covers rounding in the mix. */
+const MARK_MIN_CONTRAST = 4.6;
+const MARK_SURFACE_MIX = 0.09;
+const MARK_HUE_STEP = 120;
+const MARK_SATURATION = { min: 0.4, max: 0.7 };
+const MARK_LIGHTNESS_STEP = 0.02;
+
+function readableMark(
+  hue: number,
+  saturation: number,
+  backgrounds: readonly string[],
+  fg: string,
+): string {
+  const canvas = backgrounds[0] ?? '#000000';
+  const darkCanvas = contrastRatio(canvas, '#FFFFFF') > contrastRatio(canvas, '#000000');
+  const direction = darkCanvas ? 1 : -1;
+  for (
+    let lightness = darkCanvas ? 0.68 : 0.42;
+    lightness >= 0 && lightness <= 1;
+    lightness += direction * MARK_LIGHTNESS_STEP
+  ) {
+    const color = hslToHex(hue, saturation, lightness);
+    if (backgrounds.every((background) => contrastRatio(color, background) >= MARK_MIN_CONTRAST)) {
+      return color;
+    }
+  }
+  return fg;
+}
+
+/** Three text highlights from the accent's hue and its two even neighbours, readable on the theme. */
+export function deriveMarkTokens(
+  accent: string,
+  canvas: string,
+  fg: string,
+): Record<string, string> {
+  const surface = mixHex(canvas, fg, MARK_SURFACE_MIX);
+  const { hue, saturation } = hexToHsl(accent);
+  const vivid = Math.min(MARK_SATURATION.max, Math.max(MARK_SATURATION.min, saturation));
+  const mark = (offset: number) =>
+    readableMark((hue + offset) % 360, vivid, [canvas, surface], fg);
+  return {
+    '--nm-mark-primary': mark(0),
+    '--nm-mark-secondary': mark(MARK_HUE_STEP),
+    '--nm-mark-tertiary': mark(MARK_HUE_STEP * 2),
+    '--nm-mark-surface': surface,
+  };
+}