@adea-ai/ui 0.124.0 → 0.125.0

package/dist/r/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/dist/r/src/lib/themes.ts

@@ -36,7 +36,6 @@
 import {
   ACCENTS,
   accentForeground,
-  accentRoles,
   chartSeries,
   getAccent,
   getTheme,
@@ -58,6 +57,7 @@ import {
 } from '@adea-ai/themes'
 import { shadcnVariables } from '@adea-ai/themes/adapters/shadcn'
 import { oklchToHex, parseColor } from '@adea-ai/themes/oklch'
+import { accentOverrideVariables, resolveAccentRoles, type AccentRoles } from './accent-roles'
 import { isThemeAccentId } from './theme-accents'
 
 export { isThemeAccentId } from './theme-accents'
@@ -566,26 +566,51 @@ export function accentVariables(
   pair: { lightThemeId: string; darkThemeId: string } = {
     lightThemeId: defaultLightThemeId,
     darkThemeId: defaultDarkThemeId,
-  }
+  },
+  options: AccentVariableOptions = {}
 ): Record<string, string> | undefined {
+  const roles = accentRolesForSelection(accentId, appearance, pair, options)
+  return roles ? accentOverrideVariables(roles) : undefined
+}
+
+/** What an accent is held to when it is resolved against a surface. */
+export type AccentVariableOptions = {
+  /** The surface the accent must read on: the variant's `colors.background`. */
+  background?: string
+  /**
+   * The contrast floor against `background`. Absent, a preset is painted verbatim
+   * and only a custom `#rrggbb` is held to the default floor.
+   */
+  floor?: number
+  /** The variant the accent is applied to, so the tint takes its measured strength. */
+  variantId?: string
+}
+
+/**
+ * An accent selection resolved to the full {@link AccentRoles}, against a theme
+ * pair. {@link accentVariables} is the document half of this; an element-scoped
+ * paint (`paintAccentRoles`) wants all of it, including the tint.
+ */
+export function accentRolesForSelection(
+  accentId: string,
+  appearance: ThemeAppearance,
+  pair: { lightThemeId: string; darkThemeId: string } = {
+    lightThemeId: defaultLightThemeId,
+    darkThemeId: defaultDarkThemeId,
+  },
+  options: AccentVariableOptions = {}
+): AccentRoles | undefined {
   if (accentId === 'theme') return undefined
-  const { light, dark } = recordPair(pair.lightThemeId, pair.darkThemeId)
-  const preset = resolveAccentPreset(accentId, light, dark)
-  if (!preset) return undefined
-
-  // `--primary-subtle` is deliberately not here. It is a `color-mix()` over
-  // `var(--primary)`, so the theme's own declaration (`themeCssVariables`, or the
-  // default block in `theme.css`) already follows the accent; and its strength is the
-  // *theme's*, measured by `primarySubtleAlpha` to hold body text at 4.5:1 for every
-  // accent the theme offers. Writing one here would replace that measured strength
-  // with whatever this function was given, which is how an accent used to undo it.
-  const roles = accentRoles(preset, appearance)
-  return {
-    '--primary': roles.primary,
-    '--primary-foreground': roles.primaryForeground,
-    '--primary-hover': roles.primaryHover,
-    '--ring': roles.ring,
-  }
+  const record = options.variantId ? getTheme(options.variantId) : undefined
+  return resolveAccentRoles(accentId, {
+    target: record ?? appearance,
+    background: options.background,
+    floor: options.floor,
+    // Only an `ansi-*` id needs the pair's offering, and measuring it is not free.
+    themeAccents: isThemeAccentId(accentId)
+      ? themeAccentsFor(pair.lightThemeId, pair.darkThemeId)
+      : undefined,
+  })
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adea-ai/ui",
-  "version": "0.124.0",
+  "version": "0.125.0",
   "description": "The Adea design system: Kobalte-backed Solid components, semantic OKLCH tokens, and the app-shell layout primitives shared by Adea and Cortana.",
   "keywords": [
     "adea",

package/registry.json

@@ -2644,6 +2644,11 @@
       ],
       "registryDependencies": [],
       "files": [
+        {
+          "path": "src/lib/accent-roles.ts",
+          "type": "registry:lib",
+          "target": "lib/accent-roles.ts"
+        },
         {
           "path": "src/lib/appearance-font-settings.ts",
           "type": "registry:lib",

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

@@ -8,6 +8,7 @@ import {
   type ThemeAppearance,
   type ThemeVariant,
 } from '#lib/themes'
+import { isCustomAccent } from '#lib/accent-roles'
 import { resolvedDensity, type ThemeSelection } from './theme-state'
 
 /**
@@ -35,6 +36,12 @@ export type ThemeDocumentOptions = {
    * must return the full map; a name it drops is not written.
    */
   transformTokens?: (tokens: Record<string, string>) => Record<string, string>
+  /**
+   * The contrast an accent is held to against the variant's background. Absent, a
+   * preset is painted verbatim (the catalogue measured it for its own themes) and
+   * only a custom `#rrggbb` is held to the default floor of 3:1.
+   */
+  accentContrastFloor?: number
 }
 
 /**
@@ -53,7 +60,11 @@ export function themeDocumentTokens(
   options: ThemeDocumentOptions = {}
 ): { tokens: Record<string, string>; accented: boolean } {
   const properties = { ...themeCssVariables(state.variant) }
-  const accent = accentVariables(state.selection.accent, state.appearance, state.selection)
+  const accent = accentVariables(state.selection.accent, state.appearance, state.selection, {
+    background: state.variant.colors.background,
+    floor: options.accentContrastFloor,
+    variantId: state.variant.id,
+  })
   if (accent) Object.assign(properties, accent)
   return {
     tokens: options.transformTokens ? options.transformTokens(properties) : properties,
@@ -92,8 +103,13 @@ export function applyThemeToRoot(
   root.dataset['appearance'] = state.appearance
   root.style.colorScheme = state.appearance
 
+  // A custom colour has no stylesheet block to select, and its value is the
+  // attribute's worst possible content, so it is reported as `custom`.
   if (!accented) root.removeAttribute('data-accent')
-  else root.dataset['accent'] = state.selection.accent
+  else
+    root.dataset['accent'] = isCustomAccent(state.selection.accent)
+      ? 'custom'
+      : state.selection.accent
 
   applyAppearanceFontSettings(
     root,

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

@@ -1,3 +1,4 @@
+import { normalizeCustomAccent } from '#lib/accent-roles'
 import { accentPresets } from '#lib/tokens'
 import { normalizeAppearanceEditorFontSettings } from '#lib/appearance-font-settings'
 import { defaultDarkThemeId, defaultLightThemeId, isThemeAccentId, themeById } from '#lib/themes'
@@ -67,13 +68,15 @@ function readSelection(storageKey: string): ThemeSelection {
           : defaultDarkThemeId,
       // A theme accent is kept whenever it names a slot, even one the stored pair
       // cannot offer: the id is role-shaped so it survives a theme switch, and an
-      // unoffered slot already resolves to the theme's own primary when applied.
+      // unoffered slot already resolves to the theme's own primary when applied. A
+      // custom `#rrggbb` is kept in its one stored spelling; its readability is
+      // settled when it is painted, not when it is read.
       accent:
         typeof parsed.accent === 'string' &&
         (accentPresets.some((preset) => preset.id === parsed.accent) ||
           isThemeAccentId(parsed.accent))
           ? parsed.accent
-          : defaultThemeSelection.accent,
+          : (normalizeCustomAccent(parsed.accent) ?? defaultThemeSelection.accent),
       font: fonts.ui.family,
       fonts,
       // Every axis has to be read back here, or it is lost twice: the provider's

package/src/components/theme/theme-provider.tsx

@@ -17,6 +17,7 @@ import {
   type ThemePersistence,
 } from './theme-persistence'
 import {
+  accentRolesForState,
   initialThemeSelection,
   mergeRegistry,
   mergeThemeSelection,
@@ -111,6 +112,15 @@ export type ThemeProviderProps = {
    * element to `<head>` for two frames on every change.
    */
   disableTransitionOnChange?: boolean
+  /**
+   * The contrast ratio an accent is held to against the variant's background,
+   * repaired to the nearest passing colour when it falls short. Absent, presets
+   * are painted verbatim — the catalogue measured them for its own themes — and
+   * only a custom `#rrggbb` is held to 3:1. A host that adds themes the catalogue
+   * never measured passes 3 to hold the presets to it as well; for the catalogue's
+   * own themes the floor changes no preset.
+   */
+  accentContrastFloor?: number
 }
 
 export function ThemeProvider(props: ThemeProviderProps) {
@@ -123,6 +133,7 @@ export function ThemeProvider(props: ThemeProviderProps) {
     'themes',
     'transformTokens',
     'disableTransitionOnChange',
+    'accentContrastFloor',
   ])
   const storageKey = () => local.storageKey ?? 'adea-appearance'
   const persistence = local.persistence ?? localStoragePersistence(storageKey)
@@ -184,7 +195,10 @@ export function ThemeProvider(props: ThemeProviderProps) {
       appearance: shown().appearance,
       variant: shown().variant,
     }
-    const options = { transformTokens: local.transformTokens }
+    const options = {
+      transformTokens: local.transformTokens,
+      accentContrastFloor: local.accentContrastFloor,
+    }
     const apply = () => {
       written = applyThemeToRoot(document.documentElement, state, options, written)
     }
@@ -212,6 +226,13 @@ export function ThemeProvider(props: ThemeProviderProps) {
       setDraft(next ? { ...next } : undefined)
     },
     previewing: () => draft() !== undefined,
+    accentRolesFor: (accent, variantId) =>
+      accentRolesForState(accent, variantId, {
+        selection: selection(),
+        variant: variant(),
+        registry: registry(),
+        accentContrastFloor: local.accentContrastFloor,
+      }),
     setSelection(patch) {
       const next = mergeThemeSelection(selection(), patch)
       setSelectionState(next)

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

@@ -4,7 +4,9 @@ import {
   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,
@@ -41,8 +43,12 @@ export type ThemeSelection = {
   darkThemeId: string
   /**
    * An `accentPresets` id, a theme accent id from `themeAccents()` (`ansi-blue`…),
-   * or `theme` for the variant's own primary. A theme accent the current pair does
-   * not offer falls back to the variant's own primary.
+   * `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. */
@@ -129,6 +135,14 @@ export type ThemeContextValue = {
   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. */
@@ -158,7 +172,13 @@ export function mergeThemeSelection(
     fonts = normalizeAppearanceEditorFontSettings(merged.fonts, merged.font).settings
   }
 
-  return { ...merged, fonts, font: fonts.ui.family }
+  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,
+  }
 }
 
 /**
@@ -223,3 +243,32 @@ export function mergeRegistry(
 ): 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,