Files
gpui-native-kit/crates/theme/src/lib.rs
T
reya b08516211c Unify theme sizing and spacing on Base UI metrics
- Read only mode, accent, accessibility, and native window material from the OS.
- Replace platform palettes, metrics, type ramps, borders, and elevations with unified tokens.
- Align controls, overlays, and data rows with Base UI sizing.
2026-11-16 18:27:44 +07:00

741 lines
24 KiB
Rust

//! The theme engine: reads the running system theme, resolves it through
//! presets and overrides, and installs the tokens every component paints
//! from.
//!
//! Pipeline (plan §4.5): `ThemeSource` snapshot → `resolve` overlay chain →
//! `Theme` global → all windows repaint. Watchers re-run the pipeline on
//! real OS change events.
mod colors;
mod definition;
mod presets;
mod ramps;
mod resolve;
mod source;
mod system;
mod typography;
pub use colors::{ColorTokens, MaterialTokens};
pub use definition::ThemeDefinition;
pub use ramps::{AccentShades, Oklch};
pub use resolve::{Ramps, ResolvedTheme};
pub use system::{AccessibilityPreferences, SourceKind, SystemTheme};
pub use typography::{TextRole, TypeMetrics, Typeset, Typography};
use gpui::{
App, Global, Hsla, Pixels, SpringConfig, WindowAppearance, WindowBackgroundAppearance, hsla, px,
};
use std::time::Duration;
/// The hairline width of the control border every button and field paints.
pub const BORDER_WIDTH: Pixels = px(1.0);
/// The tallest an anchored popup's list may grow.
pub const POPUP_MAX_HEIGHT: Pixels = px(320.0);
/// The widest a tooltip may grow.
pub const TOOLTIP_MAX_WIDTH: Pixels = px(360.0);
/// How far a tooltip sits from the pointer.
pub const TOOLTIP_OFFSET: Pixels = px(1.0);
/// The caret's thickness.
pub const CARET_WIDTH: Pixels = px(1.5);
/// The IME preedit underline's thickness.
pub const UNDERLINE_WIDTH: Pixels = px(1.0);
/// How far one wheel line scrolls, as a multiple of the line height.
pub const WHEEL_LINE_HEIGHT: f32 = 20.0;
/// How far one keyboard arrow step moves a resize seam.
pub const RESIZE_KEYBOARD_STEP: Pixels = px(32.0);
/// The inset around a window's edge that starts a resize gesture.
pub const WINDOW_RESIZE_INSET: Pixels = px(4.0);
/// The pad macOS reserves for its traffic lights at a strip's leading edge.
pub const TRAFFIC_LIGHT_PAD: Pixels = px(78.0);
/// The width of a Windows caption button.
pub const WINDOWS_CAPTION_WIDTH: Pixels = px(36.0);
/// Windows paints its caption close-button hover red in every theme.
pub const WINDOWS_CLOSE_HOVER: Hsla = hsla(0.986043, 0.863406, 0.488235, 1.0);
/// The close-button hover dimmed while pressed.
pub const WINDOWS_CLOSE_PRESSED: Hsla = hsla(0.986043, 0.863406, 0.488235, 0.8);
/// The close glyph's color over the red hover.
pub const WINDOWS_CLOSE_FOREGROUND: Hsla = gpui::white();
/// The width a sidebar opens at.
pub const SIDEBAR_DEFAULT_WIDTH: Pixels = px(240.0);
/// The narrowest a sidebar may be dragged.
pub const SIDEBAR_MIN_WIDTH: Pixels = px(160.0);
/// The widest a sidebar may be dragged.
pub const SIDEBAR_MAX_WIDTH: Pixels = px(480.0);
/// The size a pane starts at before its group has measured the extent.
pub const PANE_DEFAULT_SIZE: Pixels = px(200.0);
/// The floor a pane keeps while dragging unless the caller lowers it.
pub const PANE_MIN_SIZE: Pixels = px(48.0);
/// The hairline a resize seam paints on a shared boundary.
pub const HAIRLINE_WIDTH: Pixels = px(0.5);
/// How much of the window shadow's strength survives losing focus.
pub const INACTIVE_SHADOW_OPACITY: f32 = 0.7;
/// The spread of the keyboard focus ring.
pub const FOCUS_RING_SPREAD: Pixels = px(3.0);
/// How far a pushed alert slides in on entry.
pub const ENTER_SLIDE_DISTANCE: Pixels = px(24.0);
/// The widest a toast may grow.
pub const TOAST_MAX_WIDTH: Pixels = px(480.0);
/// One revolution of the spinner.
pub const SPINNER_PERIOD: Duration = Duration::from_millis(800);
/// One sweep of the indeterminate progress bar.
pub const PROGRESS_ANIMATION_PERIOD: Duration = Duration::from_millis(1500);
/// How long an autohide scrollbar thumb stays fully visible before fading.
pub const SCROLLBAR_AUTOHIDE_DELAY: Duration = Duration::from_millis(700);
/// How long the autohide scrollbar's fade runs.
pub const SCROLLBAR_FADE_DURATION: Duration = Duration::from_millis(250);
/// How much a change wash tints the rows it covers.
pub const WASH_ALPHA: f32 = 0.14;
/// The stronger wash under number gutters and intra-line word changes.
pub const WASH_ALPHA_STRONG: f32 = 0.34;
/// The subtle wash that sets the number gutter off from the code.
pub const WASH_ALPHA_GUTTER: f32 = 0.18;
/// The soft wash that marks the active code row.
pub const WASH_ALPHA_SOFT: f32 = 0.45;
/// How far a scrolling list renders past its viewport.
pub const CODE_OVERSCROLL_MAX: Pixels = px(400.0);
/// The spring every control's toggle and segment animations ride.
pub const CONTROL_SPRING: SpringConfig = SpringConfig::new(500., 35., 1.);
/// The monospace advance estimate as a share of the text size.
pub const MONO_ADVANCE_RATIO: f32 = 0.62;
/// How much a pixel avatar's tint washes over its background.
pub const PIXEL_AVATAR_TINT_ALPHA: f32 = 0.16;
/// Pixel avatar cell lightness multipliers.
pub const PIXEL_AVATAR_LIGHT_LIFT: f32 = 1.6;
pub const PIXEL_AVATAR_LIGHT_CAP: f32 = 0.95;
pub const PIXEL_AVATAR_DARK_FACTOR: f32 = 0.45;
pub const PIXEL_AVATAR_DARK_FLOOR: f32 = 0.18;
/// The default window material transparency, as a percent (0 opaque, 100 the lightest fill).
pub const DEFAULT_TRANSPARENCY: u8 = 80;
/// The light-mode floor of the material fill.
pub const MIN_MATERIAL_FILL_LIGHT: f32 = 0.45;
/// The dark-mode floor of the material fill.
pub const MIN_MATERIAL_FILL_DARK: f32 = 0.15;
/// The opacity of the grain overlay's noise.
pub const GRAIN_ALPHA: f32 = 0.08;
/// Light or dark, resolved from the system appearance.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, serde::Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum ThemeVariant {
#[default]
Light,
Dark,
}
impl ThemeVariant {
fn from_appearance(appearance: WindowAppearance) -> Self {
match appearance {
WindowAppearance::Light | WindowAppearance::VibrantLight => Self::Light,
WindowAppearance::Dark | WindowAppearance::VibrantDark => Self::Dark,
}
}
/// Classifies a surface by its lightness, for platforms that state no mode.
pub fn by_lightness(background: Hsla) -> Self {
if background.l >= 0.5 {
Self::Light
} else {
Self::Dark
}
}
}
/// A named control size class.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub enum Size {
Small,
/// The default.
#[default]
Medium,
Large,
}
/// The resolved theme, installed as the app-wide global.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct Theme {
pub variant: ThemeVariant,
pub colors: ColorTokens,
/// The translucent paints over the window's native material.
pub material: MaterialTokens,
pub ramps: Ramps,
pub radius: Radius,
pub spacing: Spacing,
pub elevations: Elevations,
/// Overlay transition timing; gpui's animation primitives do the rest.
pub motion: Motion,
/// Overlay scrollbar geometry.
pub scrollbar: Scrollbar,
/// The height the window's titlebar strips draw at.
pub titlebar_height: Pixels,
/// The theme's root font size; rem-based sizing scales with it.
pub root_font_size: Pixels,
/// The monospace family, for code surfaces.
pub mono_font: &'static str,
/// The type ladder, resolved at the root font size.
pub typography: Typography,
pub sizes: SizeTable,
pub accessibility: AccessibilityPreferences,
/// The material a window should open with, after accessibility.
pub window_background: WindowBackgroundAppearance,
}
impl Global for Theme {}
impl Theme {
/// Reads the theme global. Panics before `init`.
pub fn global(cx: &App) -> &Self {
cx.global::<Self>()
}
fn from_resolved(resolved: ResolvedTheme) -> Self {
Self {
variant: resolved.variant,
colors: resolved.colors,
material: resolved.material,
ramps: resolved.ramps,
radius: resolved.radius,
spacing: resolved.spacing,
elevations: resolved.elevations,
motion: resolved.motion,
scrollbar: resolved.scrollbar,
titlebar_height: resolved.titlebar_height,
root_font_size: resolved.root_font_size,
mono_font: resolved.mono_font,
typography: resolved.typography,
sizes: resolved.sizes,
accessibility: resolved.accessibility,
window_background: resolved.window_background,
}
}
/// Installs the engine global, its platform watchers, and the initial resolved theme.
pub fn init(cx: &mut App) {
let mut engine = ThemeEngine {
source: source::platform_source(),
mode_override: None,
preset: None,
custom: None,
};
engine.source.install_watchers(cx.to_async());
cx.set_global(engine);
reapply(cx);
}
/// Synchronizes the theme from the window's appearance.
pub fn sync_from_window(window: &mut gpui::Window, cx: &mut App) {
let window_variant = ThemeVariant::from_appearance(window.appearance());
let theme = cx.global::<Theme>();
let engine = cx.global::<ThemeEngine>();
if engine.mode_override.is_none() && theme.variant != window_variant {
reapply(cx);
}
}
/// Sizes the window's rem to the theme's root font size.
pub fn sync_window_rem_size(window: &mut gpui::Window, cx: &App) {
let theme = cx.global::<Theme>();
window.set_rem_size(theme.root_font_size);
}
}
/// Corner radii components paint from; grows one class at a time.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct Radius {
/// Small controls: checkbox and radio indicators.
pub sm: Pixels,
pub control: Pixels,
/// Floating layers: popovers, menus, dialogs.
pub overlay: Pixels,
/// Pill and circle shapes.
pub full: Pixels,
}
impl Default for Radius {
fn default() -> Self {
Self {
sm: px(4.),
control: px(6.),
overlay: px(10.),
full: px(9999.),
}
}
}
/// The spacing rhythm: paddings and gaps step by this unit.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct Spacing {
pub unit: Pixels,
}
/// One layer of a floating panel's drop shadow.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct Shadow {
pub offset_x: Pixels,
pub offset_y: Pixels,
pub blur_radius: Pixels,
pub spread_radius: Pixels,
/// Translucent black, like every native overlay shadow.
pub color: Hsla,
}
impl Shadow {
fn none() -> Self {
Self {
offset_x: px(0.),
offset_y: px(0.),
blur_radius: px(0.),
spread_radius: px(0.),
color: colors::scrim(0.),
}
}
fn black(offset_x: f32, offset_y: f32, blur_radius: f32, alpha: f32) -> Self {
Self {
offset_x: px(offset_x),
offset_y: px(offset_y),
blur_radius: px(blur_radius),
spread_radius: px(0.),
color: colors::scrim(alpha),
}
}
}
/// The drop shadow stack of a floating layer.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct Elevation {
/// Key shadow first, ambient grounding second.
pub layers: [Shadow; 2],
}
impl Elevation {
/// No shadow: dark floating layers separate by border.
fn none() -> Self {
Self {
layers: [Shadow::none(), Shadow::none()],
}
}
fn single(key: Shadow) -> Self {
Self {
layers: [key, Shadow::none()],
}
}
fn layered(key: Shadow, ambient: Shadow) -> Self {
Self {
layers: [key, ambient],
}
}
/// How far the shadow layers paint past the element's bounds.
pub fn bleed(self) -> Pixels {
self.layers.iter().fold(px(0.), |bleed, layer| {
if layer.color.a > 0. {
bleed.max(
layer.offset_x.abs().max(layer.offset_y.abs())
+ layer.blur_radius
+ layer.spread_radius,
)
} else {
bleed
}
})
}
/// The gpui shadow list an overlay panel paints with.
pub fn shadows(self) -> Vec<gpui::BoxShadow> {
self.layers
.iter()
.filter(|layer| layer.color.a > 0.)
.map(|layer| gpui::BoxShadow {
color: layer.color,
offset: gpui::point(layer.offset_x, layer.offset_y),
blur_radius: layer.blur_radius,
spread_radius: layer.spread_radius,
inset: false,
})
.collect()
}
}
/// The drop shadows of each floating layer class.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct Elevations {
/// Popovers, menus, and pushed alerts ride above content.
pub popover: Elevation,
/// Modal dialogs sit higher with a wider one.
pub dialog: Elevation,
/// Raised plates inside controls — a selected segmented segment.
pub control: Elevation,
}
impl Elevations {
pub(crate) fn for_variant(variant: ThemeVariant) -> Self {
if variant == ThemeVariant::Dark {
return Self {
popover: Elevation::none(),
dialog: Elevation::none(),
control: Elevation::single(Shadow::black(0., 1., 2., 0.25)),
};
}
Self {
popover: Elevation::layered(
Shadow::black(0., 4., 24., 0.12),
Shadow::black(0., 1., 1., 0.05),
),
dialog: Elevation::layered(
Shadow::black(0., 8., 40., 0.14),
Shadow::black(0., 1., 2., 0.06),
),
control: Elevation::single(Shadow::black(0., 1., 2., 0.1)),
}
}
}
/// Overlay transition timings.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct Motion {
/// The enter transition of popovers, menus, and dialogs.
pub overlay: Duration,
}
impl Default for Motion {
fn default() -> Self {
Self {
overlay: Duration::from_millis(200),
}
}
}
/// Overlay scrollbar presentation.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct Scrollbar {
/// The painted thumb's thickness.
pub width: Pixels,
/// Edge padding between the thumb and the viewport it floats over.
pub inset: Pixels,
/// The thumb never shrinks below this length, so it stays grabbable.
pub min_thumb: Pixels,
/// Whether the platform's scrollbars hide while idle.
pub autohide: bool,
}
impl Default for Scrollbar {
fn default() -> Self {
Self {
width: px(8.),
inset: px(2.),
min_thumb: px(24.),
autohide: false,
}
}
}
/// The control metrics for one size class.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct ControlMetrics {
/// Push buttons, toggles, and field rows.
pub control_height: Pixels,
/// Text fields; slightly taller than buttons, as native fields are.
pub input_height: Pixels,
/// Horizontal padding inside controls.
pub padding_x: Pixels,
/// Label text size.
pub text_size: Pixels,
/// Icons and on/off indicators.
pub icon_size: Pixels,
/// Icons inline with dense content — menu rows, badges, chevrons.
pub dense_icon_size: Pixels,
/// Selection indicators — checkboxes, radios, and switch knobs.
pub indicator_size: Pixels,
/// Avatars.
pub avatar_size: Pixels,
/// Dense label text.
pub caption_size: Pixels,
/// Tight horizontal padding inside pills, segments, fields, and icon-only buttons.
pub dense_padding_x: Pixels,
/// The inset between a control's edge and a raised inner plate.
pub plate_inset: Pixels,
/// The band height of multi-segment strips.
pub strip_height: Pixels,
/// The height of one menu row.
pub menu_item_height: Pixels,
/// Switch track height, width, and knob size.
pub switch_height: Pixels,
pub switch_width: Pixels,
pub switch_knob: Pixels,
}
/// The control metrics for every size class.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct SizeTable {
pub small: ControlMetrics,
pub medium: ControlMetrics,
pub large: ControlMetrics,
}
impl SizeTable {
pub fn with_root_font_size(rem_size: Pixels) -> Self {
struct ClassFactors {
control_height: f32,
input_height: f32,
padding_x: f32,
text_size: f32,
icon_size: f32,
dense_icon_size: f32,
indicator_size: f32,
avatar_size: f32,
caption_size: f32,
dense_padding_x: f32,
plate_inset: f32,
strip_height: f32,
menu_item_height: f32,
switch_height: f32,
switch_width: f32,
switch_knob: f32,
}
let small = ClassFactors {
control_height: 1.75,
input_height: 1.75,
padding_x: 0.5,
text_size: 0.75,
icon_size: 0.875,
dense_icon_size: 0.75,
indicator_size: 0.875,
avatar_size: 1.5,
caption_size: 0.75,
dense_padding_x: 0.5,
plate_inset: 0.125,
strip_height: 1.75,
menu_item_height: 1.75,
switch_height: 1.125,
switch_width: 2.0,
switch_knob: 0.75,
};
let medium = ClassFactors {
control_height: 2.0,
input_height: 2.0,
padding_x: 0.75,
text_size: 0.875,
icon_size: 1.0,
dense_icon_size: 0.75,
indicator_size: 1.0,
avatar_size: 2.0,
caption_size: 0.75,
dense_padding_x: 0.5,
plate_inset: 0.125,
strip_height: 2.0,
menu_item_height: 2.0,
switch_height: 1.25,
switch_width: 2.25,
switch_knob: 0.875,
};
let large = ClassFactors {
control_height: 2.5,
input_height: 2.5,
padding_x: 1.0,
text_size: 1.0,
icon_size: 1.25,
dense_icon_size: 0.9375,
indicator_size: 1.25,
avatar_size: 2.5,
caption_size: 0.875,
dense_padding_x: 0.75,
plate_inset: 0.1875,
strip_height: 2.5,
menu_item_height: 2.25,
switch_height: 1.5,
switch_width: 2.75,
switch_knob: 1.125,
};
let metrics = |f: &ClassFactors| ControlMetrics {
control_height: rem_size * f.control_height,
input_height: rem_size * f.input_height,
padding_x: rem_size * f.padding_x,
text_size: rem_size * f.text_size,
icon_size: rem_size * f.icon_size,
dense_icon_size: rem_size * f.dense_icon_size,
indicator_size: rem_size * f.indicator_size,
avatar_size: rem_size * f.avatar_size,
caption_size: rem_size * f.caption_size,
dense_padding_x: rem_size * f.dense_padding_x,
plate_inset: rem_size * f.plate_inset,
strip_height: rem_size * f.strip_height,
menu_item_height: rem_size * f.menu_item_height,
switch_height: rem_size * f.switch_height,
switch_width: rem_size * f.switch_width,
switch_knob: rem_size * f.switch_knob,
};
Self {
small: metrics(&small),
medium: metrics(&medium),
large: metrics(&large),
}
}
/// The metrics for `size`.
pub fn resolve(&self, size: Size) -> ControlMetrics {
match size {
Size::Small => self.small,
Size::Medium => self.medium,
Size::Large => self.large,
}
}
}
/// User customizations layered over the resolved theme.
#[derive(Clone, Copy, Debug, Default, PartialEq)]
pub struct CustomTheme {
pub root_font_size: Option<Pixels>,
pub sm_radius: Option<Pixels>,
pub control_radius: Option<Pixels>,
pub overlay_radius: Option<Pixels>,
pub popover_elevation: Option<Elevation>,
pub dialog_elevation: Option<Elevation>,
pub control_elevation: Option<Elevation>,
/// Window material transparency as a percent (0 opaque, 100 pure blur).
///
/// Note: windows platform is not supported
pub transparency: Option<u8>,
}
/// The engine's knobs and its platform source.
struct ThemeEngine {
source: Box<dyn source::ThemeSource>,
mode_override: Option<ThemeVariant>,
preset: Option<(&'static str, ThemeDefinition)>,
custom: Option<CustomTheme>,
}
impl Global for ThemeEngine {}
/// Reads the resolved theme global from any app context.
pub trait ActiveTheme {
fn theme(&self) -> &Theme;
}
impl ActiveTheme for App {
fn theme(&self) -> &Theme {
Theme::global(self)
}
}
/// Reapplies the theme to the application.
pub(crate) fn reapply(cx: &mut App) {
let (preset, mode_override, custom, system) = {
let engine = cx.global::<ThemeEngine>();
let system_appearance = ThemeVariant::from_appearance(cx.window_appearance());
let preset = engine.preset.as_ref().map(|(_, def)| def.clone());
let mode_override = engine.mode_override;
let custom = engine.custom;
let variant = mode_override
.or(preset.as_ref().and_then(|def| def.mode()))
.unwrap_or(system_appearance);
(
preset,
mode_override,
custom,
engine.source.snapshot(variant),
)
};
let resolved = resolve::resolve(&system, preset.as_ref(), mode_override, custom);
cx.set_reduce_motion(resolved.accessibility.reduce_motion);
cx.set_global(Theme::from_resolved(resolved));
cx.refresh_windows();
}
/// Forces a variant, independent of the OS. `None` follows the system.
pub fn set_mode_override(variant: Option<ThemeVariant>, cx: &mut App) {
let engine = cx.global_mut::<ThemeEngine>();
engine.mode_override = variant;
reapply(cx);
}
/// Installs a built-in preset, or `None` to follow the system again.
pub fn set_preset(name: Option<&str>, cx: &mut App) -> anyhow::Result<()> {
let preset = name
.map(|name| {
presets::builtin(name).ok_or_else(|| {
anyhow::anyhow!(
"unknown preset: {name}; available: {}",
presets::preset_names().collect::<Vec<_>>().join(", ")
)
})
})
.transpose()?;
let engine = cx.global_mut::<ThemeEngine>();
engine.preset = preset;
reapply(cx);
Ok(())
}
/// Installs the user's custom theme, or `None` to follow the current scheme.
pub fn set_custom_theme(custom: Option<CustomTheme>, cx: &mut App) {
let engine = cx.global_mut::<ThemeEngine>();
engine.custom = custom;
reapply(cx);
}
/// The variant the mode override forces, if any.
pub fn mode_override(cx: &App) -> Option<ThemeVariant> {
let engine = cx.global::<ThemeEngine>();
engine.mode_override
}
/// The installed custom theme, if any.
pub fn custom_theme(cx: &App) -> Option<CustomTheme> {
let engine = cx.global::<ThemeEngine>();
engine.custom
}
/// The active preset name, if one is installed.
pub fn active_preset(cx: &App) -> Option<&'static str> {
let engine = cx.global::<ThemeEngine>();
engine.preset.as_ref().map(|(name, _)| *name)
}
/// Clears the mode override and preset; the theme follows the system again.
pub fn follow_system(cx: &mut App) {
let engine = cx.global_mut::<ThemeEngine>();
engine.mode_override = None;
engine.preset = None;
reapply(cx);
}
/// Which adapter produced the current system snapshot.
pub fn detected_source(cx: &App) -> &'static str {
let engine = cx.global::<ThemeEngine>();
engine.source.label()
}
#[cfg(test)]
mod tests {
use super::*;
use gpui::Rgba;
#[test]
fn the_windows_close_colors_match_the_legacy_hex() {
let hover = Hsla::from(gpui::rgba(0xE81123FF));
let pressed = hover.opacity(0.8);
for (token, expected) in [
(WINDOWS_CLOSE_HOVER, hover),
(WINDOWS_CLOSE_PRESSED, pressed),
] {
let (token, expected) = (Rgba::from(token), Rgba::from(expected));
assert!((token.r - expected.r).abs() < 1e-4);
assert!((token.g - expected.g).abs() < 1e-4);
assert!((token.b - expected.b).abs() < 1e-4);
assert!((token.a - expected.a).abs() < 1e-4);
}
assert_eq!(WINDOWS_CLOSE_FOREGROUND, gpui::white());
}
}