@adea-ai/ui 0.123.1 → 0.125.0

package/src/components/theme/theme-state.ts

@@ -0,0 +1,274 @@
+import {
+  DEFAULT_APPEARANCE_EDITOR_FONT_SETTINGS,
+  normalizeAppearanceEditorFontSettings,
+  type AppearanceEditorFontSettings,
+} from '#lib/appearance-font-settings'
+import type { AccentPreset } from '@adea-ai/themes'
+import { normalizeCustomAccent, type AccentRoles } from '#lib/accent-roles'
+import {
+  accentRolesForSelection,
+  defaultDarkThemeId,
+  defaultLightThemeId,
+  resolveVariant,
+  type ThemeAppearance,
+  type ThemeVariant,
+} from '#lib/themes'
+
+/**
+ * The pure half of the theme provider: what a selection is, how two selections
+ * merge, and what a selection resolves to.
+ *
+ * Nothing here touches the document, storage or a signal, so each rule can be
+ * tested by calling it. `ThemeProvider` owns the reactivity and wires these to it;
+ * `theme-document.ts` owns the writes; `theme-persistence.ts` owns the store.
+ */
+
+/**
+ * Four independent choices, and keeping them independent is the point:
+ *
+ *   - **appearance** — light, dark, or follow the system.
+ *   - **a theme per appearance** — so a user can run Catppuccin Mocha by night and
+ *     Solarized Light by day without re-choosing when the system flips.
+ *   - **an accent** — adea's six presets, or one of the accents the selected theme
+ *     pair carries itself (`ansi-blue`…), which re-colour the interactive roles on
+ *     top of whichever theme is active.
+ *   - **fonts** — separate family and size choices for UI, content and code.
+ */
+export type ThemeSelection = {
+  /** `system` follows `prefers-color-scheme` and updates when it changes. */
+  appearance: ThemeAppearance | 'system'
+  /** The variant to use when the resolved appearance is light. */
+  lightThemeId: string
+  /** The variant to use when the resolved appearance is dark. */
+  darkThemeId: string
+  /**
+   * An `accentPresets` id, a theme accent id from `themeAccents()` (`ansi-blue`…),
+   * `theme` for the variant's own primary, or a custom colour as `#rrggbb`. A theme
+   * accent the current pair does not offer falls back to the variant's own primary.
+   *
+   * A custom colour is stored lower case and is raised to the contrast floor when it
+   * is painted, never when it is stored: the selection keeps what the user chose.
+   * Anything else that is not an id is dropped at paint, not rejected here.
+   */
+  accent: string
+  /** UI-family alias for consumers of the original single-font preference. */
+  font: string
+  /** UI, content and code font settings. Omitted legacy records are migrated from `font`. */
+  fonts?: AppearanceEditorFontSettings
+  /**
+   * `comfortable` is the system's default geometry; `compact` moves the control
+   * ladder down one rung.
+   *
+   * Optional, and defaulted on read, so a preference stored before density existed
+   * keeps working and `ThemeSelection` stays assignable without it.
+   */
+  density?: ThemeDensity
+}
+
+/**
+ * The two density rungs.
+ *
+ * `comfortable` is the geometry in `theme.css`, so it is the absence of an
+ * attribute rather than a value: a document that ships no `data-density` at all
+ * renders correctly, which is what keeps this additive.
+ */
+export type ThemeDensity = 'comfortable' | 'compact'
+
+/**
+ * Deliberately lists only the fields every consumer has always had. A field added
+ * to {@link ThemeSelection} later gets no default here: `JSON.stringify` drops an
+ * `undefined`, so a store written by a consumer that never sets the field stays
+ * byte-identical to what it was before the field existed.
+ */
+export const defaultThemeSelection: ThemeSelection = {
+  appearance: 'system',
+  lightThemeId: defaultLightThemeId,
+  darkThemeId: defaultDarkThemeId,
+  accent: 'theme',
+  font: 'system',
+  fonts: DEFAULT_APPEARANCE_EDITOR_FONT_SETTINGS,
+  density: 'comfortable',
+}
+
+/**
+ * A stored selection's density, defaulted.
+ *
+ * The stored value is read through here rather than trusted, because a preference
+ * written before density existed has no `density` key and a hand-edited store may
+ * hold anything.
+ */
+export function resolvedDensity(selection: ThemeSelection): ThemeDensity {
+  return selection.density === 'compact' ? 'compact' : 'comfortable'
+}
+
+export type ThemeContextValue = {
+  /** The preference as stored. A {@link ThemeContextValue.preview} does not change it. */
+  selection: () => ThemeSelection
+  /** What the preference resolves to right now, after `system`. */
+  resolvedAppearance: () => ThemeAppearance
+  /** The variant in use. */
+  variant: () => ThemeVariant
+  /** Update part of the preference. */
+  setSelection: (patch: Partial<ThemeSelection>) => void
+  /**
+   * The built-in catalogue, so a picker does not import it separately. A plain
+   * array: {@link ThemeContextValue.allThemes} is the one that follows a host's
+   * extra themes.
+   */
+  themes: readonly ThemeVariant[]
+  /**
+   * The accents the selected light/dark pair carries, offered beside the presets.
+   * Follows the selection: a different theme pair may offer different slots.
+   */
+  themeAccents: () => readonly AccentPreset[]
+  /**
+   * The built-in catalogue followed by the provider's `themes` prop. Reactive when
+   * that prop is a function that reads signals.
+   */
+  allThemes: () => readonly ThemeVariant[]
+  /**
+   * Paint the document from `draft` laid over the stored selection, without
+   * persisting it or changing what {@link ThemeContextValue.selection} returns.
+   * `undefined` ends the preview. A {@link ThemeContextValue.setSelection} ends it
+   * too, because the committed selection is then what should be showing.
+   */
+  preview: (draft: Partial<ThemeSelection> | undefined) => void
+  /** True while a {@link ThemeContextValue.preview} draft is on the document. */
+  previewing: () => boolean
+  /**
+   * The roles `accent` paints over `variantId` (default: the variant in use), held
+   * to the provider's `accentContrastFloor`, for an element-scoped override with
+   * `paintAccentRoles` — a workspace that carries its own colour. `undefined` for
+   * `null`, for `theme`, for an id that resolves to nothing, and for a variant the
+   * registry does not hold: each means "keep the inherited accent".
+   */
+  accentRolesFor: (accent: string | null, variantId?: string) => AccentRoles | undefined
+}
+
+/** A selection with the `undefined` keys of a patch left out. */
+function definedOnly<T extends object>(value: T): Partial<T> {
+  return Object.fromEntries(
+    Object.entries(value).filter(([, entry]) => entry !== undefined)
+  ) as Partial<T>
+}
+
+/** Keep the deprecated single-font view synchronized with the UI axis. */
+export function mergeThemeSelection(
+  base: ThemeSelection,
+  patch: Partial<ThemeSelection>
+): ThemeSelection {
+  const merged = { ...base, ...patch }
+  let fonts: AppearanceEditorFontSettings
+
+  if (patch.fonts !== undefined) {
+    fonts = normalizeAppearanceEditorFontSettings(patch.fonts).settings
+  } else if (patch.font !== undefined) {
+    const currentFonts = normalizeAppearanceEditorFontSettings(base.fonts, base.font).settings
+    fonts = normalizeAppearanceEditorFontSettings({
+      ...currentFonts,
+      ui: { ...currentFonts.ui, family: patch.font },
+    }).settings
+  } else {
+    fonts = normalizeAppearanceEditorFontSettings(merged.fonts, merged.font).settings
+  }
+
+  return {
+    ...merged,
+    // One spelling for a custom colour, so equal choices compare and store equal.
+    accent: normalizeCustomAccent(merged.accent) ?? merged.accent,
+    fonts,
+    font: fonts.ui.family,
+  }
+}
+
+/**
+ * The selection a provider starts from: the defaults, then whatever the store
+ * returned, then `initial`.
+ *
+ * `initial` wins over the store on every mount. That precedence is part of the
+ * contract Cortana relies on (its `initial` pins `appearance` and `font`), and it
+ * is why the store's answer is only the middle layer. A store that returned
+ * nothing, or threw, or answered with explicit `undefined`s, leaves the defaults
+ * standing for those fields.
+ */
+export function initialThemeSelection(
+  stored: Partial<ThemeSelection> | undefined,
+  initial: Partial<ThemeSelection> | undefined
+): ThemeSelection {
+  const base = mergeThemeSelection(defaultThemeSelection, definedOnly(stored ?? {}))
+  return mergeThemeSelection(base, initial ?? {})
+}
+
+/** `system` resolved against what the operating system reports. */
+export function resolveAppearance(
+  preference: ThemeSelection['appearance'],
+  system: ThemeAppearance
+): ThemeAppearance {
+  return preference === 'system' ? system : preference
+}
+
+/** The theme id the selection names for a resolved appearance. */
+export function selectedThemeId(selection: ThemeSelection, appearance: ThemeAppearance): string {
+  return appearance === 'dark' ? selection.darkThemeId : selection.lightThemeId
+}
+
+/**
+ * What a selection paints: the resolved appearance and the variant for it.
+ *
+ * An id the registry does not hold resolves to the appearance's default rather than
+ * being rewritten (see `resolveVariant`), so the selection a host stores is never
+ * changed by being unresolvable.
+ */
+export function resolveThemeState(
+  selection: ThemeSelection,
+  system: ThemeAppearance,
+  registry: readonly ThemeVariant[]
+): { appearance: ThemeAppearance; variant: ThemeVariant } {
+  const appearance = resolveAppearance(selection.appearance, system)
+  return {
+    appearance,
+    variant: resolveVariant(registry, selectedThemeId(selection, appearance), appearance),
+  }
+}
+
+/**
+ * The registry a provider resolves against: the catalogue, then the host's extras.
+ *
+ * The catalogue wins an id collision, because it is listed first and `resolveVariant`
+ * takes the first match: a host's variant can add a theme but cannot shadow one.
+ */
+export function mergeRegistry(
+  builtin: readonly ThemeVariant[],
+  extra: readonly ThemeVariant[] | undefined
+): readonly ThemeVariant[] {
+  return extra && extra.length > 0 ? [...builtin, ...extra] : builtin
+}
+
+/**
+ * The roles an accent paints over a variant, for {@link ThemeContextValue.accentRolesFor}.
+ *
+ * Resolved against the committed selection's theme pair, so an `ansi-*` accent means
+ * the same colour here as it does on `<html>`.
+ */
+export function accentRolesForState(
+  accent: string | null,
+  variantId: string | undefined,
+  state: {
+    selection: ThemeSelection
+    variant: ThemeVariant
+    registry: readonly ThemeVariant[]
+    accentContrastFloor?: number
+  }
+): AccentRoles | undefined {
+  if (accent === null) return undefined
+  const variant =
+    variantId === undefined
+      ? state.variant
+      : state.registry.find((candidate) => candidate.id === variantId)
+  if (!variant) return undefined
+  return accentRolesForSelection(accent, variant.appearance, state.selection, {
+    background: variant.colors.background,
+    floor: state.accentContrastFloor,
+    variantId: variant.id,
+  })
+}

package/src/index.ts

@@ -117,6 +117,14 @@ export * from './components/composites/workspace-mark'
 
 /* --- Library ------------------------------------------------------------- */
 export { cn } from './lib/utils'
+export {
+  isCustomAccent,
+  normalizeCustomAccent,
+  paintAccentRoles,
+  resolveAccentRoles,
+  type AccentRoles,
+  type AccentTarget,
+} from './lib/accent-roles'
 export {
   controlInteractive,
   controlSize,
@@ -135,6 +143,7 @@ export {
   defaultLightThemeId,
   isThemeAccentId,
   resolveAccentPreset,
+  resolveVariant,
   themeAccentsFor,
   themeById,
   themeCssVariables,
@@ -142,8 +151,10 @@ export {
   themeRecordById,
   themeRecords,
   themesForAppearance,
+  tokensAsHex,
   validateTheme,
   validateThemeRegistry,
+  variantFromRecord,
   withAccent,
   type ThemeAppearance,
   type ThemeColors,

package/src/lib/accent-roles.ts

@@ -0,0 +1,338 @@
+/*
+ * Copyright (c) 2026 Wing
+ * SPDX-License-Identifier: MIT
+ *
+ * The colour helpers, the contrast gate and the custom-accent grammar are
+ * substantially translated from Zeron's `Color` and `AccentRoles`
+ * (https://github.com/zeronsh/zeron), as Adea's accepted port of them in
+ * `packages/ui/src/components/appearance.ts` expresses it. Extracted here so the
+ * shared provider and Adea run one implementation; `@adea-ai/themes` owns the
+ * colour engine (parsing, contrast, repair, the preset values and their roles).
+ * See NOTICE.
+ */
+
+import {
+  ACCENTS,
+  accentRoles,
+  accentValue,
+  primarySubtleCss,
+  type AccentPreset,
+  type AccentRoles as CatalogueAccentRoles,
+} from '@adea-ai/themes'
+import {
+  contrastRatio as canonicalContrastRatio,
+  oklchToHex,
+  parseColor as parseCanonicalColor,
+  repairContrast,
+  type Oklch,
+} from '@adea-ai/themes/oklch'
+import type { ThemeAppearance } from './themes'
+
+/**
+ * Accent colour maths and the roles an accent paints.
+ *
+ * Three questions live here, and none of them touches the document or a signal:
+ *
+ *   - **What colour is this?** `parseColor`, `colorToHex`, `contrastRatio` and
+ *     `ensureContrast` are the hex helpers a host needs around an accent (an
+ *     imported theme's colours, a colour field). Hex is the host preference format;
+ *     the catalogue's colour engine does the maths.
+ *   - **Is this accent readable on this surface?** The *contrast floor*. A preset is
+ *     curated, so the catalogue already measured it against its own themes and the
+ *     floor is the identity for it; a custom `#rrggbb` is anyone's choice, so it is
+ *     raised until it clears the floor and can never ship unreadable. A host that
+ *     imports themes (whose backgrounds the catalogue never saw) turns the floor on
+ *     for presets too.
+ *   - **Which custom properties does an accent own?** `AccentRoles`, written on
+ *     `<html>` by the provider and onto one element by {@link paintAccentRoles}.
+ */
+
+/* Hex is the host preference format; the shared Themes package owns colour maths. */
+
+export type RgbColor = Readonly<{ r: number; g: number; b: number; a: number }>
+
+const HEX = /^#([0-9a-fA-F]+)$/
+
+/** Parse a hex colour (`#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`). `undefined` for anything else. */
+export function parseColor(value: string): RgbColor | undefined {
+  const match = HEX.exec(value.trim())
+  const digits = match?.[1]
+  if (!digits) return undefined
+  if (digits.length === 3 || digits.length === 4) {
+    // Each nibble is doubled: `#abc` is `#aabbcc`.
+    const [r, g, b, a] = [...digits].map((digit) => Number.parseInt(digit + digit, 16))
+    return { r: r!, g: g!, b: b!, a: a ?? 255 }
+  }
+  if (digits.length === 6 || digits.length === 8) {
+    const byte = (index: number) => Number.parseInt(digits.slice(index, index + 2), 16)
+    return { r: byte(0), g: byte(2), b: byte(4), a: digits.length === 8 ? byte(6) : 255 }
+  }
+  return undefined
+}
+
+function toHexByte(value: number): string {
+  return value.toString(16).padStart(2, '0')
+}
+
+/** `#rrggbb`, or `#rrggbbaa` when the colour is not opaque. */
+export function colorToHex(color: RgbColor): string {
+  const opaque = `#${toHexByte(color.r)}${toHexByte(color.g)}${toHexByte(color.b)}`
+  return color.a === 255 ? opaque : `${opaque}${toHexByte(color.a)}`
+}
+
+function blendOver(foreground: RgbColor, background: RgbColor): RgbColor {
+  const alpha = foreground.a / 255
+  const blend = (front: number, back: number) => Math.round(front * alpha + back * (1 - alpha))
+  return {
+    r: blend(foreground.r, background.r),
+    g: blend(foreground.g, background.g),
+    b: blend(foreground.b, background.b),
+    a: 255,
+  }
+}
+
+function toCanonicalColor(color: RgbColor): Oklch | undefined {
+  return parseCanonicalColor(colorToHex({ ...color, a: 255 }))
+}
+
+/** WCAG contrast ratio between two colours. Alpha composites over the background first. */
+export function contrastRatio(
+  foreground: RgbColor | string,
+  background: RgbColor | string
+): number {
+  const front = typeof foreground === 'string' ? parseColor(foreground) : foreground
+  const back = typeof background === 'string' ? parseColor(background) : background
+  if (!front || !back) return 0
+  const opaqueFront = front.a === 255 ? front : blendOver(front, back)
+  const foregroundColor = toCanonicalColor(opaqueFront)
+  const backgroundColor = toCanonicalColor(back)
+  if (!foregroundColor || !backgroundColor) return 0
+  return canonicalContrastRatio(foregroundColor, backgroundColor)
+}
+
+const WHITE: RgbColor = { r: 255, g: 255, b: 255, a: 255 }
+const WHITE_OKLCH: Oklch = { l: 1, c: 0, h: 0 }
+
+/**
+ * The nearest colour to `source` that reaches `minimum` against `canvas`, as hex.
+ *
+ * The catalogue's `repairContrast` is asked for a little more than the floor, in
+ * 0.001 steps up to 0.05, because the result is rounded to 8-bit hex and the
+ * rounded colour is what is measured: asking for exactly the floor can land a hair
+ * under it after rounding. If nothing in that range survives the rounding, white or
+ * black stands in, whichever clears the floor.
+ */
+function repairedHex(source: Oklch, canvas: Oklch, minimum: number): string {
+  for (let margin = 0; margin <= 0.05; margin = Number((margin + 0.001).toFixed(3))) {
+    const repaired = repairContrast(source, canvas, minimum + margin)
+    if (!repaired.satisfied) continue
+    const hex = oklchToHex(repaired.color)
+    const rounded = parseCanonicalColor(hex)
+    if (rounded && canonicalContrastRatio(rounded, canvas) >= minimum) return hex
+  }
+  return canonicalContrastRatio(WHITE_OKLCH, canvas) >= minimum ? '#ffffff' : '#000000'
+}
+
+/** Preserve the host hex shape while delegating contrast repair to the catalogue. */
+export function ensureContrast(color: RgbColor, background: RgbColor, minimum: number): RgbColor {
+  if (contrastRatio(color, background) >= minimum) return color
+
+  const renderedColor = color.a === 255 ? color : blendOver(color, background)
+  const source = toCanonicalColor(renderedColor)
+  const canvas = toCanonicalColor(background)
+  if (!source || !canvas) return color
+  return parseColor(repairedHex(source, canvas, minimum))!
+}
+
+/** The contrast an accent is held to against its surface unless the host sets another. */
+export const DEFAULT_ACCENT_CONTRAST_FLOOR = 3
+
+/**
+ * Normalise a custom accent against a surface: unparseable input is rejected
+ * (`undefined`), and any accepted colour is raised to `minimum` so an accent can
+ * never ship unreadable. Accepts every CSS hex length; for the stored grammar use
+ * {@link normalizeCustomAccent}.
+ */
+export function normalizeAccentValue(
+  value: string,
+  background: string,
+  minimum: number = DEFAULT_ACCENT_CONTRAST_FLOOR
+): string | undefined {
+  const parsed = parseColor(value)
+  if (!parsed) return undefined
+  const backdrop = parseColor(background) ?? WHITE
+  return colorToHex(ensureContrast(parsed, backdrop, minimum))
+}
+
+/**
+ * The stored form of a custom accent: `#rrggbb`, six digits, opaque, lower case.
+ *
+ * Deliberately narrower than {@link parseColor}. A stored accent is compared,
+ * deduplicated and used as an attribute, so it has one spelling; a host that
+ * accepts `#abc` in a field expands it before storing. Anything else — a name, an
+ * `rgb()`, a short or alpha form, a non-string — is not an accent and returns
+ * `undefined`.
+ */
+export function normalizeCustomAccent(value: unknown): string | undefined {
+  return typeof value === 'string' && /^#[0-9a-fA-F]{6}$/.test(value)
+    ? value.toLowerCase()
+    : undefined
+}
+
+/** Whether a selection's accent is the custom `#rrggbb` form (any letter case). */
+export function isCustomAccent(value: unknown): boolean {
+  return normalizeCustomAccent(value) !== undefined
+}
+
+/**
+ * The roles an accent paints, as CSS values: the catalogue's `AccentRoles`, so the
+ * provider, the generated stylesheet and a host's own paint cannot disagree about
+ * what a role is. `primarySubtle` is an expression over `var(--primary)`; the
+ * document writer never sets it (see {@link accentOverrideVariables}), an element
+ * paint must.
+ */
+export type AccentRoles = CatalogueAccentRoles
+
+/** What an accent resolves against: the surface it sits on and the theme it sits in. */
+export type AccentTarget = {
+  /** The theme, or only its appearance. A theme gives the tint its measured strength. */
+  target: Parameters<typeof accentRoles>[1]
+  /** The surface the accent must read on. Without it nothing can be measured or repaired. */
+  background: string | undefined
+  /**
+   * The contrast to hold the accent to against `background`. Absent, a preset is
+   * painted verbatim and a custom colour is held to {@link DEFAULT_ACCENT_CONTRAST_FLOOR}.
+   */
+  floor?: number
+  /**
+   * The accents the selected theme pair carries (`ansi-blue`…), for an id that is
+   * neither a preset nor a colour.
+   */
+  themeAccents?: readonly AccentPreset[]
+}
+
+function appearanceOf(target: AccentTarget['target']): ThemeAppearance {
+  return typeof target === 'string' ? target : target.appearance
+}
+
+/**
+ * `value` raised to `floor` against `background` as hex, or `value` itself when it
+ * already clears the floor, is not a colour, or there is no surface to measure it on.
+ *
+ * Returning the argument itself is what makes the floor the identity for a preset
+ * that already reads: the caller compares and keeps the catalogue's own roles.
+ */
+function gateColor(value: string, background: string | undefined, floor: number): string {
+  const source = parseCanonicalColor(value)
+  const canvas = background ? parseCanonicalColor(background) : undefined
+  if (!source || !canvas) return value
+  if (canonicalContrastRatio(source, canvas) >= floor) return value
+  return repairedHex(source, canvas, floor)
+}
+
+/**
+ * The roles for a preset (or a custom colour made into one), held to the floor.
+ *
+ * A preset that clears the floor keeps the catalogue's roles untouched. One that
+ * does not is repaired to the nearest passing colour and the whole role set is
+ * rebuilt from the repaired value, so the label, hover and ring follow it instead
+ * of describing a colour that is no longer on screen.
+ */
+export function accentRolesForPreset(
+  preset: AccentPreset,
+  context: AccentTarget
+): AccentRoles | undefined {
+  const appearance = appearanceOf(context.target)
+  const requested = accentValue(preset, appearance)
+  if (!parseCanonicalColor(requested)) return undefined
+
+  const floor = context.floor
+  if (floor === undefined) return accentRoles(preset, context.target)
+
+  const gated = gateColor(requested, context.background, floor)
+  if (gated === requested) return accentRoles(preset, context.target)
+
+  const roles = accentRoles({ ...preset, light: gated, dark: gated }, context.target)
+  // The tint's strength is measured against the primary it will sit over, and the
+  // repaired primary is not one the theme's own measurement saw.
+  return { ...roles, primarySubtle: primarySubtleCss(context.target, '--primary', [gated]) }
+}
+
+/**
+ * Resolve an accent selection to its roles, or `undefined` when it overrides nothing.
+ *
+ * `undefined` is "use the theme's own primary": the literal `theme`, an id that is
+ * neither a preset, an offered theme accent nor a colour, and a colour that does not
+ * parse. A host that wants one of those to mean something else decides before
+ * asking (Adea's codec maps a stored `theme` to its default preset when it reads).
+ */
+export function resolveAccentRoles(accent: string, context: AccentTarget): AccentRoles | undefined {
+  if (accent === 'theme') return undefined
+
+  const custom = normalizeCustomAccent(accent)
+  if (custom) {
+    const floor = context.floor ?? DEFAULT_ACCENT_CONTRAST_FLOOR
+    return accentRolesForPreset(
+      { id: 'custom', label: 'Custom', description: '', light: custom, dark: custom },
+      { ...context, floor }
+    )
+  }
+
+  const preset =
+    ACCENTS.find((candidate) => candidate.id === accent) ??
+    context.themeAccents?.find((candidate) => candidate.id === accent)
+  return preset ? accentRolesForPreset(preset, context) : undefined
+}
+
+/**
+ * The custom properties an accent override owns on `<html>`.
+ *
+ * `--primary-subtle` is deliberately not among them. It is a `color-mix()` over
+ * `var(--primary)`, so on the same element it follows an accent by itself, and its
+ * strength is the theme's, measured to keep body text at 4.5:1 on the tint.
+ * Writing one here would replace that measurement with the argument's.
+ */
+export function accentOverrideVariables(roles: AccentRoles): Record<string, string> {
+  return {
+    '--primary': roles.primary,
+    '--primary-foreground': roles.primaryForeground,
+    '--primary-hover': roles.primaryHover,
+    '--ring': roles.ring,
+  }
+}
+
+/** The custom properties {@link paintAccentRoles} writes and clears. */
+export const ACCENT_PAINT_PROPERTIES = [
+  '--primary',
+  '--primary-foreground',
+  '--primary-hover',
+  '--primary-subtle',
+  '--ring',
+] as const
+
+/**
+ * Scope an accent to one element and its descendants.
+ *
+ * Unlike the document, an element must write `--primary-subtle` too. A custom
+ * property that uses `var()` is resolved where it is declared, so the tint inherited
+ * from `<html>` is already a mix over *`<html>`'s* primary and an element that only
+ * overrides `--primary` would keep the old tint. Declared here, the same expression
+ * resolves against this element's primary.
+ *
+ * `undefined` clears every property, and the element inherits the document's accent
+ * again.
+ */
+export function paintAccentRoles(
+  element: { style: Pick<CSSStyleDeclaration, 'setProperty' | 'removeProperty'> },
+  roles: AccentRoles | undefined
+): void {
+  if (!roles) {
+    for (const property of ACCENT_PAINT_PROPERTIES) element.style.removeProperty(property)
+    return
+  }
+  element.style.setProperty('--primary', roles.primary)
+  element.style.setProperty('--primary-foreground', roles.primaryForeground)
+  element.style.setProperty('--primary-hover', roles.primaryHover)
+  element.style.setProperty('--primary-subtle', roles.primarySubtle)
+  element.style.setProperty('--ring', roles.ring)
+}

package/src/lib/appearance-font-settings.ts

@@ -181,7 +181,7 @@ export function normalizeAppearanceEditorFontSettings(
  * stylesheet and survives CSS import reordering.
  */
 export function applyAppearanceFontSettings(
-  root: HTMLElement,
+  root: Pick<HTMLElement, 'removeAttribute' | 'setAttribute' | 'style'>,
   value: unknown
 ): NormalizedAppearanceEditorFontSettings {
   const normalized = normalizeAppearanceEditorFontSettings(value)