herogpui_theme/

semantic.rs

//! Semantic color tokens — a faithful port of HeroUI v3's
//! `packages/styles/themes/default/variables.css`.
//!
//! Every base value below is transcribed verbatim from that file in `oklch()`.
//! Derived tokens (`*-hover`, `*-soft`, `background-secondary`,
//! `separator-secondary`, …) are computed with the same
//! `color-mix(in oklab, …)` weights the stylesheet uses, so a HeroGPUI theme
//! and a HeroUI theme resolve to identical pixels.

use gpui::Hsla;
use herogpui_core::{mix_oklab, oklch, soft_mix, with_alpha, Color};

// ---------------------------------------------------------------------------
// Base colors — identical in light and dark ("do not change between modes")
// ---------------------------------------------------------------------------

/// `--white: oklch(100% 0 0)`
pub fn white() -> Hsla {
    oklch(1.0, 0.0, 0.0)
}
/// `--black: oklch(0% 0 0)`
pub fn black() -> Hsla {
    oklch(0.0, 0.0, 0.0)
}
/// `--snow: oklch(0.9911 0 0)`
pub fn snow() -> Hsla {
    oklch(0.9911, 0.0, 0.0)
}
/// `--eclipse: oklch(0.2103 0.0059 285.89)`
pub fn eclipse() -> Hsla {
    oklch(0.2103, 0.0059, 285.89)
}

/// How a role resolves `--role-soft-foreground`.
#[derive(Clone, Copy, Debug)]
pub enum SoftForeground {
    /// `--default-soft-foreground: var(--default-foreground)`
    RoleForeground,
    /// `color-mix(in oklab, var(--role) C%, var(--foreground) F%)`. CSS
    /// normalises the weights, so the role contributes `C / (C + F)`.
    Mix {
        /// Weight of the role color (`C`).
        color: f32,
        /// Weight of the page foreground (`F`).
        foreground: f32,
    },
}

/// A semantic color role (`accent`, `default`, `success`, `warning`, `danger`).
///
/// v3 removed numbered scales; a role carries only its base value and readable
/// foreground, and every other shade is derived.
#[derive(Clone, Copy, Debug)]
pub struct RoleColor {
    /// e.g. `--accent`.
    pub color: Hsla,
    /// e.g. `--accent-foreground`.
    pub foreground: Hsla,
    /// Weight of `foreground` in the `*-hover` mix. `0.10` for the status and
    /// accent roles, `0.04` for `default`.
    pub hover_mix: f32,
    /// An explicit `*-hover`, in place of the `hover_mix` derivation.
    ///
    /// Upstream derives every hover shade by mixing the role toward its own
    /// foreground, which moves a dark accent lighter and a light one darker.
    /// A design system whose hover moves the other way — or to an unrelated
    /// value — has no weight that expresses it, so it can name the colour
    /// instead. Set through [`RoleColor::with_hover`].
    hover_override: Option<Hsla>,
    /// Share of the role color in `*-soft`, over transparent.
    soft_mix: f32,
    /// Share of the role color in `*-soft-hover`.
    soft_hover_mix: f32,
    /// How `*-soft-foreground` resolves.
    soft_foreground: SoftForeground,
    /// `[data-vibrant-palette="true"]` (variables.css:317-330): the opt-in
    /// palette reweights every mixing role's `*-soft-foreground` to
    /// `92%` role over `8%` page foreground, in both appearances. Roles that
    /// resolve to [`SoftForeground::RoleForeground`] (`default`) are untouched,
    /// exactly as upstream leaves `--default-soft-foreground` alone.
    vibrant_palette: bool,
}

impl RoleColor {
    /// Creates a role from its base color and on-color foreground, with the default hover, soft and soft-foreground mixes.
    pub fn new(color: Hsla, foreground: Hsla) -> Self {
        Self {
            color,
            foreground,
            hover_mix: 0.10,
            hover_override: None,
            soft_mix: 0.15,
            soft_hover_mix: 0.20,
            soft_foreground: SoftForeground::Mix {
                color: 70.0,
                foreground: 30.0,
            },
            vibrant_palette: false,
        }
    }

    /// `default` mixes only 4% of its foreground on hover.
    ///
    /// Ignored once [`RoleColor::with_hover`] has named the shade outright.
    pub fn with_hover_mix(mut self, hover_mix: f32) -> Self {
        self.hover_mix = hover_mix;
        self
    }

    /// Replaces the derived `*-hover` shade with an explicit colour.
    ///
    /// This is the role-level hook: every component that hovers this role —
    /// a `Variant::Primary` button, a select trigger, a menu row — reads
    /// [`RoleColor::hover`], so naming it here makes the whole surface correct
    /// by construction rather than one call site at a time. It is the
    /// alternative to registering a named component recipe carrying a
    /// [`crate::ComponentColor::Literal`] and converting each site to it,
    /// which leaves any newly written site on the derived shade.
    ///
    /// Leaves `*-soft-hover` alone: that shade is an alpha of the role over
    /// transparent and does not mix the foreground in.
    pub fn with_hover(mut self, hover: Hsla) -> Self {
        self.hover_override = Some(hover);
        self
    }

    /// The explicit `*-hover`, when one was named.
    pub fn hover_override(&self) -> Option<Hsla> {
        self.hover_override
    }

    /// Sets the shares of the role color in `--role-soft` and
    /// `--role-soft-hover` (`default` sits at 50/60, the rest at 15/20 in
    /// light and 12/16 in dark for the cooler roles).
    pub fn with_soft_mix(mut self, soft: f32, soft_hover: f32) -> Self {
        self.soft_mix = soft;
        self.soft_hover_mix = soft_hover;
        self
    }

    /// `--role-soft-foreground: color-mix(in oklab, var(--role) C%, var(--foreground) F%)`
    pub fn with_soft_foreground_mix(mut self, color: f32, foreground: f32) -> Self {
        self.soft_foreground = SoftForeground::Mix { color, foreground };
        self
    }

    /// Opts this role into `[data-vibrant-palette="true"]`. Set through
    /// [`crate::ThemeBuilder::vibrant_palette`], which fans the flag out over
    /// every role at once, the way the attribute selector does.
    pub fn with_vibrant_palette(mut self, vibrant: bool) -> Self {
        self.vibrant_palette = vibrant;
        self
    }

    /// Whether this role resolves its soft foreground with the vibrant weights.
    pub fn is_vibrant_palette(&self) -> bool {
        self.vibrant_palette
    }

    /// `--default-soft-foreground: var(--default-foreground)`
    pub fn with_soft_foreground_role(mut self) -> Self {
        self.soft_foreground = SoftForeground::RoleForeground;
        self
    }

    /// `--color-accent-hover: color-mix(in oklab, var(--accent) 90%, var(--accent-foreground) 10%)`
    ///
    /// [`RoleColor::with_hover`] replaces this derivation with a named colour.
    pub fn hover(&self) -> Hsla {
        self.hover_override
            .unwrap_or_else(|| mix_oklab(self.color, self.foreground, self.hover_mix))
    }

    /// `--color-accent-soft: color-mix(in oklab, var(--accent) 15%, transparent)`
    pub fn soft(&self) -> Hsla {
        soft_mix(self.color, self.soft_mix)
    }

    /// `--color-accent-soft-hover: color-mix(in oklab, var(--accent) 20%, transparent)`
    pub fn soft_hover(&self) -> Hsla {
        soft_mix(self.color, self.soft_hover_mix)
    }

    /// `--color-accent-soft-foreground: color-mix(in oklab, var(--accent) 70%, var(--foreground) 30%)`
    ///
    /// The mixing roles blend against the page foreground, so pass the live
    /// `ThemeColors::foreground` — a `ThemeBuilder::foreground` override then
    /// flows through without rebuilding the theme.
    pub fn soft_foreground(&self, page_foreground: Hsla) -> Hsla {
        match self.soft_foreground {
            SoftForeground::RoleForeground => self.foreground,
            // variables.css:318-321 (light) / :326-329 (dark): the vibrant
            // palette replaces the per-role weights with one 92/8 mix.
            SoftForeground::Mix { .. } if self.vibrant_palette => {
                mix_oklab(self.color, page_foreground, 8.0 / 100.0)
            }
            SoftForeground::Mix { color, foreground } => {
                // `mix_oklab`'s `t` is the weight of its *second* argument, so
                // the page foreground's normalised share goes here — passing the
                // role's share paints the text as `F%` role over `C%` ink.
                mix_oklab(
                    self.color,
                    page_foreground,
                    foreground / (color + foreground),
                )
            }
        }
    }

    /// Returns the role color with the given alpha.
    pub fn with_alpha(&self, alpha: f32) -> Hsla {
        with_alpha(self.color, alpha)
    }
}

/// A layered container color: `surface`, `overlay` or `segment`.
#[derive(Clone, Copy, Debug)]
pub struct SurfaceColor {
    /// The container background.
    pub background: Hsla,
    /// The foreground drawn on the background.
    pub foreground: Hsla,
}

impl SurfaceColor {
    /// `--surface-hover: color-mix(in oklab, var(--surface) 92%, var(--surface-foreground) 8%)`
    pub fn hover(&self) -> Hsla {
        mix_oklab(self.background, self.foreground, 0.08)
    }
}

/// Form-field tokens. v3 keeps these separate from buttons so inputs can be
/// styled independently.
#[derive(Clone, Copy, Debug)]
#[non_exhaustive]
pub struct FieldColors {
    /// `--field-background`
    pub background: Hsla,
    /// `--field-foreground`
    pub foreground: Hsla,
    /// `--field-placeholder`
    pub placeholder: Hsla,
    /// `--field-border` — `transparent` by default.
    pub border: Hsla,
}

impl FieldColors {
    /// `--color-field-hover: color-mix(in oklab, var(--field-background) 90%, var(--field-foreground) 2%)`
    ///
    /// CSS normalises the 90/2 weights, so the foreground contributes 2/92.
    pub fn hover(&self) -> Hsla {
        mix_oklab(self.background, self.foreground, 2.0 / 92.0)
    }

    /// `--color-field-focus: var(--field-background)`
    pub fn focus(&self) -> Hsla {
        self.background
    }

    /// `--field-border-hover: color-mix(in oklab, var(--field-border) 88%, var(--field-foreground) 10%)`
    ///
    /// The weights sum to 98, which CSS normalises, so the foreground
    /// contributes 10/98. Invisible while `--field-border-width` is 0, and the
    /// token exists for a caller who gives their fields a border.
    pub fn border_hover(&self) -> Hsla {
        mix_oklab(self.border, self.foreground, 10.0 / 98.0)
    }

    /// `--field-border-focus: color-mix(in oklab, var(--field-border) 74%, var(--field-foreground) 22%)`
    pub fn border_focus(&self) -> Hsla {
        mix_oklab(self.border, self.foreground, 22.0 / 96.0)
    }
}

/// All semantic tokens of one appearance.
#[derive(Clone, Debug)]
#[non_exhaustive]
pub struct ThemeColors {
    // -- base ---------------------------------------------------------------
    /// `--background`
    pub background: Hsla,
    /// `--foreground`
    pub foreground: Hsla,
    /// `--muted` — de-emphasised body text and icons.
    pub muted: Hsla,
    /// `--scrollbar: var(--scrollbar-thumb)`
    pub scrollbar: Hsla,

    // -- containers ---------------------------------------------------------
    /// `--surface` / `--surface-foreground` — non-floating components
    /// (cards, accordions, disclosure groups).
    pub surface: SurfaceColor,
    /// `--surface-secondary`
    pub surface_secondary: Hsla,
    /// `--surface-tertiary`
    pub surface_tertiary: Hsla,
    /// `--overlay` / `--overlay-foreground` — floating components
    /// (tooltips, popovers, modals, menus).
    pub overlay: SurfaceColor,
    /// `--segment` / `--segment-foreground` — selected segment of a
    /// segmented control (tabs, toggle groups).
    pub segment: SurfaceColor,

    // -- roles --------------------------------------------------------------
    /// `--default` — the neutral backbone of the system.
    pub default: RoleColor,
    /// `--accent` — the brand color (v2 `primary`).
    pub accent: RoleColor,
    /// `--success`
    pub success: RoleColor,
    /// `--warning`
    pub warning: RoleColor,
    /// `--danger`
    pub danger: RoleColor,

    // -- fields -------------------------------------------------------------
    /// The form-field colors (`--field-*`).
    pub field: FieldColors,

    // -- misc ---------------------------------------------------------------
    /// `--border`
    pub border: Hsla,
    /// `--separator`
    pub separator: Hsla,
    /// `--focus`
    pub focus: Hsla,
    /// `--link`
    pub link: Hsla,
    /// `--backdrop` — the scrim behind modals and drawers.
    pub backdrop: Hsla,
}

impl ThemeColors {
    /// Whether `[data-vibrant-palette="true"]` is on (variables.css:317-330).
    ///
    /// The flag lives on each [`RoleColor`]; the mixing roles are set together
    /// by [`crate::ThemeBuilder::vibrant_palette`], so `accent` answers for all.
    pub fn vibrant_palette(&self) -> bool {
        self.accent.is_vibrant_palette()
    }

    /// Fans `[data-vibrant-palette="true"]` out over the roles the selector
    /// lists: accent, success, warning and danger. `default` is absent from
    /// both blocks upstream and keeps `--default-soft-foreground`.
    pub fn set_vibrant_palette(&mut self, vibrant: bool) {
        self.accent = self.accent.with_vibrant_palette(vibrant);
        self.success = self.success.with_vibrant_palette(vibrant);
        self.warning = self.warning.with_vibrant_palette(vibrant);
        self.danger = self.danger.with_vibrant_palette(vibrant);
    }

    // -- derived backgrounds ------------------------------------------------

    /// `color-mix(in oklab, var(--background) 96%, var(--foreground) 4%)`
    pub fn background_secondary(&self) -> Hsla {
        mix_oklab(self.background, self.foreground, 0.04)
    }

    /// `color-mix(in oklab, var(--background) 92%, var(--foreground) 8%)`
    pub fn background_tertiary(&self) -> Hsla {
        mix_oklab(self.background, self.foreground, 0.08)
    }

    /// `--color-background-inverse: var(--foreground)`
    pub fn background_inverse(&self) -> Hsla {
        self.foreground
    }

    // -- derived separators -------------------------------------------------

    /// `color-mix(in oklab, var(--surface) 85%, var(--surface-foreground) 15%)`
    pub fn separator_secondary(&self) -> Hsla {
        mix_oklab(self.surface.background, self.surface.foreground, 0.15)
    }

    /// `color-mix(in oklab, var(--surface) 81%, var(--surface-foreground) 19%)`
    pub fn separator_tertiary(&self) -> Hsla {
        mix_oklab(self.surface.background, self.surface.foreground, 0.19)
    }

    // -- derived borders ----------------------------------------------------

    /// `--border-secondary: color-mix(in oklab, var(--surface) 78%, var(--surface-foreground) 22%)`
    pub fn border_secondary(&self) -> Hsla {
        mix_oklab(self.surface.background, self.surface.foreground, 0.22)
    }

    /// `--border-tertiary: color-mix(in oklab, var(--surface) 66%, var(--surface-foreground) 34%)`
    pub fn border_tertiary(&self) -> Hsla {
        mix_oklab(self.surface.background, self.surface.foreground, 0.34)
    }

    /// `--surface-secondary-foreground: var(--foreground)`
    ///
    /// v3 gives the secondary and tertiary surfaces their own foreground
    /// variables, both defaulting to the page's, so a caller who repaints one of
    /// those surfaces has somewhere to put the matching text colour.
    pub fn surface_secondary_foreground(&self) -> Hsla {
        self.foreground
    }

    /// `--surface-tertiary-foreground: var(--foreground)`
    pub fn surface_tertiary_foreground(&self) -> Hsla {
        self.foreground
    }

    /// The tokens of one semantic colour role.
    pub fn role(&self, role: Color) -> &RoleColor {
        match role {
            Color::Default => &self.default,
            Color::Accent => &self.accent,
            Color::Success => &self.success,
            Color::Warning => &self.warning,
            Color::Danger => &self.danger,
        }
    }

    /// Mutable access to one role's tokens, for [`crate::ThemeBuilder`].
    pub(crate) fn role_mut(&mut self, role: Color) -> &mut RoleColor {
        match role {
            Color::Default => &mut self.default,
            Color::Accent => &mut self.accent,
            Color::Success => &mut self.success,
            Color::Warning => &mut self.warning,
            Color::Danger => &mut self.danger,
        }
    }

    // -- light --------------------------------------------------------------

    /// The built-in light palette.
    pub fn light() -> Self {
        let foreground = eclipse();
        let muted = oklch(0.5517, 0.0138, 285.94);
        let accent = RoleColor::new(oklch(0.6204, 0.195, 253.83), snow())
            .with_soft_mix(0.15, 0.20)
            .with_soft_foreground_mix(70.0, 30.0);
        Self {
            background: oklch(0.9702, 0.0, 0.0),
            foreground,
            muted,
            scrollbar: with_alpha(foreground, 0.15),

            surface: SurfaceColor {
                background: white(),
                foreground,
            },
            surface_secondary: oklch(0.9524, 0.0013, 286.37),
            surface_tertiary: oklch(0.9373, 0.0013, 286.37),
            overlay: SurfaceColor {
                background: white(),
                foreground,
            },
            segment: SurfaceColor {
                background: white(),
                foreground: eclipse(),
            },

            default: RoleColor::new(oklch(0.94, 0.001, 286.375), eclipse())
                .with_hover_mix(0.04)
                .with_soft_mix(0.50, 0.60)
                .with_soft_foreground_role(),
            accent,
            success: RoleColor::new(oklch(0.7329, 0.1935, 150.81), eclipse())
                .with_soft_foreground_mix(80.0, 60.0),
            warning: RoleColor::new(oklch(0.7819, 0.1585, 72.33), eclipse())
                .with_soft_foreground_mix(80.0, 70.0),
            danger: RoleColor::new(oklch(0.6532, 0.2328, 25.74), snow())
                .with_soft_foreground_mix(70.0, 40.0),

            field: FieldColors {
                background: white(),
                foreground: oklch(0.2103, 0.0059, 285.89),
                placeholder: muted,
                border: with_alpha(black(), 0.0),
            },

            // `--border` is a step darker than `--separator`: 90% against 92%.
            // Both had been transcribed as the separator's value.
            border: oklch(0.9, 0.004, 286.32),
            separator: oklch(0.92, 0.004, 286.32),
            focus: accent.color,
            link: foreground,
            backdrop: with_alpha(black(), 0.5),
        }
    }

    // -- dark ---------------------------------------------------------------

    /// The built-in dark palette.
    pub fn dark() -> Self {
        let foreground = snow();
        let muted = oklch(0.705, 0.015, 286.067);
        let accent = RoleColor::new(oklch(0.6204, 0.195, 253.83), snow())
            .with_soft_mix(0.12, 0.16)
            .with_soft_foreground_mix(80.0, 30.0);
        let default = RoleColor::new(oklch(0.274, 0.006, 286.033), snow())
            .with_hover_mix(0.04)
            .with_soft_mix(0.50, 0.60)
            .with_soft_foreground_role();
        Self {
            background: oklch(0.12, 0.005, 285.823),
            foreground,
            muted,
            scrollbar: with_alpha(foreground, 0.15),

            surface: SurfaceColor {
                background: oklch(0.2103, 0.0059, 285.89),
                foreground,
            },
            surface_secondary: oklch(0.257, 0.0037, 286.14),
            surface_tertiary: oklch(0.2721, 0.0024, 247.91),
            // `--overlay` *is* `--surface` in dark mode. This used to lighten it
            // "so floating panels read", which is the kind of improvement the
            // token values are not allowed to make: a v3 dark popover is the
            // colour of a v3 dark card, and the shadow is what separates them.
            overlay: SurfaceColor {
                background: oklch(0.2103, 0.0059, 285.89),
                foreground,
            },
            segment: SurfaceColor {
                background: oklch(0.3964, 0.01, 285.93),
                foreground,
            },

            default,
            accent,
            // `--success` is not overridden in dark mode; only its soft shares
            // are (12/16 over transparent, foreground at 80/30).
            success: RoleColor::new(oklch(0.7329, 0.1935, 150.81), eclipse())
                .with_soft_mix(0.12, 0.16)
                .with_soft_foreground_mix(80.0, 30.0),
            warning: RoleColor::new(oklch(0.8203, 0.1388, 76.34), eclipse())
                .with_soft_mix(0.12, 0.16)
                .with_soft_foreground_mix(80.0, 30.0),
            danger: RoleColor::new(oklch(0.594, 0.1967, 24.63), snow())
                .with_soft_foreground_mix(80.0, 30.0),

            field: FieldColors {
                // `--field-background: oklch(0.2103 0.0059 285.89)` -- the
                // surface colour, not `--default`, which is two steps lighter.
                background: oklch(0.2103, 0.0059, 285.89),
                foreground,
                placeholder: muted,
                border: with_alpha(black(), 0.0),
            },

            // `--border: oklch(28% ..)`, `--separator: oklch(25% ..)`. Both were
            // one value here, and both too dark.
            border: oklch(0.28, 0.006, 286.033),
            separator: oklch(0.25, 0.006, 286.033),
            focus: accent.color,
            link: foreground,
            backdrop: with_alpha(black(), 0.6),
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    fn rgb8(c: Hsla) -> (u8, u8, u8) {
        let r = gpui::Rgba::from(c);
        (
            (r.r * 255.0).round() as u8,
            (r.g * 255.0).round() as u8,
            (r.b * 255.0).round() as u8,
        )
    }

    #[test]
    fn an_explicit_role_hover_replaces_the_derived_mix() {
        let stock = ThemeColors::light();
        let derived = stock.accent.hover();
        // Upstream mixes the role toward its own foreground, so a hover named
        // in the other direction has no `hover_mix` that expresses it.
        let named = gpui::hsla(0.6, 0.9, 0.3, 1.0);
        let role = stock.accent.with_hover(named);
        assert_ne!(rgb8(derived), rgb8(named), "the fixture must differ");
        assert_eq!(rgb8(role.hover()), rgb8(named));
        assert_eq!(role.hover_override(), Some(named));
        // Only `*-hover` moves: the soft shades are alphas of the role over
        // transparent and never mix the foreground in.
        assert_eq!(rgb8(role.soft()), rgb8(stock.accent.soft()));
        assert_eq!(rgb8(role.soft_hover()), rgb8(stock.accent.soft_hover()));
        assert_eq!(rgb8(role.color), rgb8(stock.accent.color));
    }

    #[test]
    fn a_named_role_hover_outranks_the_hover_mix_whichever_order_they_are_set() {
        let base = ThemeColors::light().accent;
        let named = gpui::hsla(0.1, 0.8, 0.4, 1.0);
        assert_eq!(
            rgb8(base.with_hover(named).with_hover_mix(0.5).hover()),
            rgb8(named)
        );
        assert_eq!(
            rgb8(base.with_hover_mix(0.5).with_hover(named).hover()),
            rgb8(named)
        );
    }

    #[test]
    fn accent_soft_is_fifteen_percent_accent() {
        let c = ThemeColors::light();
        assert!((c.accent.soft().a - 0.15).abs() < 1e-4);
        assert!((c.accent.soft_hover().a - 0.20).abs() < 1e-4);
    }

    #[test]
    fn light_scrollbar_thumb_is_fifteen_percent_foreground() {
        let c = ThemeColors::light();
        assert_eq!(c.scrollbar, with_alpha(c.foreground, 0.15));
    }

    #[test]
    fn dark_scrollbar_thumb_is_fifteen_percent_foreground() {
        let c = ThemeColors::dark();
        assert_eq!(c.scrollbar, with_alpha(c.foreground, 0.15));
    }

    #[test]
    fn the_soft_matrix_matches_the_pinned_stylesheet() {
        // Weights transcribed from `variables.css` at v3.2.4. `None` means
        // `--role-soft-foreground: var(--role-foreground)`; `Some` is the
        // `color-mix(in oklab, var(--role) C%, var(--foreground) F%)` pair.
        let light = ThemeColors::light();
        let dark = ThemeColors::dark();
        for (colors, role_name, soft, soft_hover, foreground) in [
            (&light, "default", 0.50, 0.60, None),
            (&light, "accent", 0.15, 0.20, Some((70.0, 30.0))),
            (&light, "success", 0.15, 0.20, Some((80.0, 60.0))),
            (&light, "warning", 0.15, 0.20, Some((80.0, 70.0))),
            (&light, "danger", 0.15, 0.20, Some((70.0, 40.0))),
            (&dark, "default", 0.50, 0.60, None),
            (&dark, "accent", 0.12, 0.16, Some((80.0, 30.0))),
            (&dark, "success", 0.12, 0.16, Some((80.0, 30.0))),
            (&dark, "warning", 0.12, 0.16, Some((80.0, 30.0))),
            (&dark, "danger", 0.15, 0.20, Some((80.0, 30.0))),
        ] {
            let role = colors.role(Color::from_token(role_name).unwrap());
            assert!(
                (role.soft().a - soft).abs() < 1e-4,
                "{role_name} soft alpha"
            );
            assert!(
                (role.soft_hover().a - soft_hover).abs() < 1e-4,
                "{role_name} soft-hover alpha"
            );
            match foreground {
                Some((color, page)) => assert_eq!(
                    role.soft_foreground(colors.foreground),
                    mix_oklab(role.color, colors.foreground, page / (color + page)),
                    "{role_name} soft-foreground mix"
                ),
                None => assert_eq!(
                    role.soft_foreground(colors.foreground),
                    role.foreground,
                    "{role_name} soft-foreground follows the role"
                ),
            }
        }
    }

    /// Every semantic token, resolved the way a browser resolves it on
    /// heroui.com at v3.2.4 — light and dark. A weight-for-weight comparison
    /// against the same formula cannot catch a formula that is wrong, so these
    /// are the pixels themselves.
    #[test]
    fn every_token_resolves_to_the_stylesheets_own_pixels() {
        type Pick = fn(&ThemeColors) -> Hsla;
        /// `(name, accessor, light sRGB+alpha, dark sRGB+alpha)`.
        type Row = (&'static str, Pick, (u8, u8, u8, f32), (u8, u8, u8, f32));
        #[rustfmt::skip]
        let table: &[Row] = &[
            ("accent", |c| c.accent.color, (4, 133, 247, 1.00), (4, 133, 247, 1.00)),
            ("accent_foreground", |c| c.accent.foreground, (252, 252, 252, 1.00), (252, 252, 252, 1.00)),
            ("accent_hover", |c| c.accent.hover(), (53, 146, 249, 1.00), (53, 146, 249, 1.00)),
            ("accent_soft", |c| c.accent.soft(), (4, 133, 247, 0.15), (4, 133, 247, 0.12)),
            ("accent_soft_foreground", |c| c.accent.soft_foreground(c.foreground), (30, 99, 174, 1.00), (97, 168, 251, 1.00)),
            ("backdrop", |c| c.backdrop, (0, 0, 0, 0.50), (0, 0, 0, 0.60)),
            ("background", |c| c.background, (245, 245, 245, 1.00), (6, 6, 7, 1.00)),
            ("background_inverse", |c| c.background_inverse(), (24, 24, 27, 1.00), (252, 252, 252, 1.00)),
            ("background_secondary", |c| c.background_secondary(), (235, 235, 235, 1.00), (12, 12, 14, 1.00)),
            ("background_tertiary", |c| c.background_tertiary(), (225, 225, 225, 1.00), (19, 19, 22, 1.00)),
            ("border", |c| c.border, (221, 222, 224, 1.00), (40, 40, 44, 1.00)),
            ("border_secondary", |c| c.border_secondary(), (198, 198, 199, 1.00), (67, 67, 69, 1.00)),
            ("border_tertiary", |c| c.border_tertiary(), (168, 168, 169, 1.00), (92, 92, 95, 1.00)),
            ("danger", |c| c.danger.color, (255, 56, 60, 1.00), (219, 59, 62, 1.00)),
            ("danger_foreground", |c| c.danger.foreground, (252, 252, 252, 1.00), (252, 252, 252, 1.00)),
            ("danger_hover", |c| c.danger.hover(), (255, 85, 81, 1.00), (225, 84, 81, 1.00)),
            ("danger_soft", |c| c.danger.soft(), (255, 56, 60, 0.15), (219, 59, 62, 0.15)),
            ("danger_soft_foreground", |c| c.danger.soft_foreground(c.foreground), (164, 53, 51, 1.00), (235, 120, 114, 1.00)),
            ("default", |c| c.default.color, (235, 235, 236, 1.00), (39, 39, 42, 1.00)),
            ("default_foreground", |c| c.default.foreground, (24, 24, 27, 1.00), (252, 252, 252, 1.00)),
            ("default_hover", |c| c.default.hover(), (225, 225, 226, 1.00), (46, 46, 49, 1.00)),
            ("default_soft", |c| c.default.soft(), (235, 235, 235, 0.50), (39, 39, 42, 0.50)),
            ("default_soft_foreground", |c| c.default.soft_foreground(c.foreground), (24, 24, 27, 1.00), (252, 252, 252, 1.00)),
            ("field_background", |c| c.field.background, (255, 255, 255, 1.00), (24, 24, 27, 1.00)),
            ("field_foreground", |c| c.field.foreground, (24, 24, 27, 1.00), (252, 252, 252, 1.00)),
            ("field_placeholder", |c| c.field.placeholder, (113, 113, 122, 1.00), (159, 159, 169, 1.00)),
            ("focus", |c| c.focus, (4, 133, 247, 1.00), (4, 133, 247, 1.00)),
            ("foreground", |c| c.foreground, (24, 24, 27, 1.00), (252, 252, 252, 1.00)),
            ("link", |c| c.link, (24, 24, 27, 1.00), (252, 252, 252, 1.00)),
            ("muted", |c| c.muted, (113, 113, 122, 1.00), (159, 159, 169, 1.00)),
            ("overlay", |c| c.overlay.background, (255, 255, 255, 1.00), (24, 24, 27, 1.00)),
            ("overlay_foreground", |c| c.overlay.foreground, (24, 24, 27, 1.00), (252, 252, 252, 1.00)),
            ("scrollbar", |c| c.scrollbar, (24, 24, 27, 0.15), (255, 255, 255, 0.15)),
            ("segment", |c| c.segment.background, (255, 255, 255, 1.00), (70, 70, 76, 1.00)),
            ("segment_foreground", |c| c.segment.foreground, (24, 24, 27, 1.00), (252, 252, 252, 1.00)),
            ("separator", |c| c.separator, (228, 228, 231, 1.00), (33, 33, 36, 1.00)),
            ("separator_secondary", |c| c.separator_secondary(), (216, 216, 216, 1.00), (52, 52, 55, 1.00)),
            ("separator_tertiary", |c| c.separator_tertiary(), (205, 205, 206, 1.00), (60, 60, 63, 1.00)),
            ("success", |c| c.success.color, (23, 201, 100, 1.00), (23, 201, 100, 1.00)),
            ("success_foreground", |c| c.success.foreground, (24, 24, 27, 1.00), (24, 24, 27, 1.00)),
            ("success_hover", |c| c.success.hover(), (33, 181, 93, 1.00), (33, 181, 93, 1.00)),
            ("success_soft", |c| c.success.soft(), (23, 201, 100, 0.15), (23, 201, 100, 0.12)),
            ("success_soft_foreground", |c| c.success.soft_foreground(c.foreground), (43, 119, 69, 1.00), (116, 216, 143, 1.00)),
            ("surface", |c| c.surface.background, (255, 255, 255, 1.00), (24, 24, 27, 1.00)),
            ("surface_foreground", |c| c.surface.foreground, (24, 24, 27, 1.00), (252, 252, 252, 1.00)),
            ("surface_hover", |c| c.surface.hover(), (234, 234, 234, 1.00), (39, 39, 42, 1.00)),
            ("surface_secondary", |c| c.surface_secondary, (239, 239, 240, 1.00), (35, 35, 37, 1.00)),
            ("surface_tertiary", |c| c.surface_tertiary, (234, 234, 235, 1.00), (38, 39, 40, 1.00)),
            ("warning", |c| c.warning.color, (245, 165, 36, 1.00), (247, 183, 80, 1.00)),
            ("warning_foreground", |c| c.warning.foreground, (24, 24, 27, 1.00), (24, 24, 27, 1.00)),
            ("warning_hover", |c| c.warning.hover(), (220, 150, 42, 1.00), (222, 165, 76, 1.00)),
            ("warning_soft", |c| c.warning.soft(), (245, 165, 36, 0.15), (247, 183, 80, 0.12)),
            ("warning_soft_foreground", |c| c.warning.soft_foreground(c.foreground), (133, 95, 46, 1.00), (249, 203, 134, 1.00)),
        ];
        for (name, pick, light, dark) in table {
            for (mode, c, want) in [
                ("light", ThemeColors::light(), light),
                ("dark", ThemeColors::dark(), dark),
            ] {
                let got = pick(&c);
                let (r, g, b) = rgb8(got);
                // The reference was read back from a premultiplied surface, so
                // a translucent token's channels carry `1/alpha` of rounding.
                let slack = (2.0 / want.3).ceil() as i32;
                let near = |a: u8, b: u8| (a as i32 - b as i32).abs() <= slack;
                assert!(
                    near(r, want.0) && near(g, want.1) && near(b, want.2)
                        && (got.a - want.3).abs() < 0.011,
                    "{name} ({mode}) resolved to ({r}, {g}, {b}, {:.3}),                      upstream resolves ({}, {}, {}, {:.3})",
                    got.a, want.0, want.1, want.2, want.3
                );
            }
        }
    }

    #[test]
    fn soft_foreground_resolves_to_the_stylesheets_own_pixels() {
        // The weights alone cannot catch an inverted mix, so pin what a browser
        // resolves `--color-<role>-soft-foreground` to at v3.2.4 in light mode.
        // A soft label reads as a tinted version of its role, not as body ink.
        let c = ThemeColors::light();
        for (role_name, expected) in [
            ("accent", (30, 99, 174)),
            ("success", (43, 119, 69)),
            ("warning", (133, 95, 46)),
            ("danger", (164, 53, 51)),
        ] {
            let got = rgb8(
                c.role(Color::from_token(role_name).unwrap())
                    .soft_foreground(c.foreground),
            );
            let near = |a: u8, b: u8| (a as i32 - b as i32).abs() <= 2;
            assert!(
                near(got.0, expected.0) && near(got.1, expected.1) && near(got.2, expected.2),
                "{role_name} soft-foreground was {got:?}, expected {expected:?}"
            );
        }
    }

    #[test]
    fn a_custom_foreground_stays_live_in_the_soft_foreground_mix() {
        let base = ThemeColors::light();
        let custom = ThemeColors {
            foreground: oklch(0.30, 0.05, 120.0),
            ..base
        };
        // The mixing roles resolve against the page foreground passed in, so a
        // `ThemeBuilder::foreground` override flows through at render time.
        assert_eq!(
            custom.accent.soft_foreground(custom.foreground),
            mix_oklab(custom.accent.color, custom.foreground, 0.30)
        );
        assert_ne!(
            custom.accent.soft_foreground(custom.foreground),
            base.accent.soft_foreground(base.foreground)
        );
        // `--default-soft-foreground: var(--default-foreground)` does not mix,
        // so it follows the role's own foreground instead of the page's.
        assert_eq!(
            custom.default.soft_foreground(custom.foreground),
            custom.default.foreground
        );
    }

    #[test]
    fn the_derived_borders_step_away_from_the_surface() {
        let c = ThemeColors::light();
        // `--border-secondary` and `--border-tertiary` mix further from the
        // surface than `--separator-secondary` does, so a border reads stronger
        // than a rule at the same step.
        let steps = [
            c.separator_secondary(),
            c.border_secondary(),
            c.border_tertiary(),
        ];
        for pair in steps.windows(2) {
            assert!(
                pair[1].l < pair[0].l,
                "each step is darker than the last on a light surface"
            );
        }
    }

    #[test]
    fn a_secondary_surface_keeps_the_page_foreground() {
        let c = ThemeColors::light();
        assert_eq!(c.surface_secondary_foreground(), c.foreground);
        assert_eq!(c.surface_tertiary_foreground(), c.foreground);
    }

    #[test]
    fn a_field_border_mixes_toward_its_own_foreground() {
        let c = ThemeColors::light();
        // Both are mixes of `--field-border` toward `--field-foreground`, and
        // focus mixes further than hover.
        let border = c.field.border;
        assert_ne!(c.field.border_hover(), border);
        assert_ne!(c.field.border_focus(), c.field.border_hover());
    }

    #[test]
    fn field_focus_matches_field_background() {
        let c = ThemeColors::light();
        assert_eq!(c.field.focus(), c.field.background);
    }

    #[test]
    #[ignore = "v3 gives dark mode one colour for both; the shadow separates them"]
    fn dark_surface_is_darker_than_overlay() {
        let c = ThemeColors::dark();
        assert!(c.surface.background.l < c.overlay.background.l);
    }

    #[test]
    fn light_background_is_lighter_than_its_derived_levels() {
        let c = ThemeColors::light();
        assert!(c.background.l > c.background_secondary().l);
        assert!(c.background_secondary().l > c.background_tertiary().l);
    }
}