Struct Theme 

pub struct Theme {

    pub appearance: Appearance,
    pub bg: Hsla,
    pub surface: Hsla,
    pub surface_raised: Hsla,
    pub surface_card: Hsla,
    pub surface_dialog: Hsla,
    pub surface_overlay: Hsla,
    pub element_hover: Hsla,
    pub element_active: Hsla,
    pub border: Hsla,
    pub border_strong: Hsla,
    pub text: Hsla,
    pub text_muted: Hsla,
    pub text_faint: Hsla,
    pub text_dim: Hsla,
    pub solid: Hsla,
    pub on_solid: Hsla,
    pub accent: Hsla,
    pub accent_strong: Hsla,
    pub on_accent: Hsla,
    pub danger: Hsla,
    pub danger_muted: Hsla,
    pub warning: Hsla,
    pub warning_muted: Hsla,
    pub success: Hsla,
    pub busy: Hsla,
    pub success_muted: Hsla,
    pub surface_raised_hover: Hsla,
    pub band: Hsla,
    pub input_bg: Hsla,
    pub selection: Hsla,
    pub cursor: Hsla,
    pub caret: Hsla,
    pub ring: Hsla,
    pub danger_strong: Hsla,
    pub code_text: Hsla,
    pub code_wash: Hsla,
    pub syntax: SyntaxPalette,
    pub diff_add: Hsla,
    pub diff_del: Hsla,
    pub diff_hunk_bg: Hsla,
    pub vibrancy_alpha: f32,
    pub vibrancy: bool,
    pub glass: bool,
    pub material: MaterialSpec,
    pub glass_regular: SurfaceSpec,
    pub glass_clear: SurfaceSpec,
    pub popover_surface: SurfaceStyle,
    pub glass_magnify: f32,
    pub glass_dispersion: f32,
    pub font_sans: SharedString,
    pub font_mono: SharedString,
    pub font_sans_fallback: SharedString,
    pub font_mono_fallback: SharedString,
}

The app theme. Two concrete instances — Theme::dark and Theme::light.

Fields

appearance: Appearance

Which appearance these tokens were built for.

bg: Hsla

Main content panel. Dark: the deepest plane (#060606). Light: pure white — long-form content reads best on an unbroken white field.

surface: Hsla

Shell / sidebar surface. Dark: one step up from bg. Light: one step down (grey) — chrome recedes from the content plane in both, which is the direction a naive invert gets backwards.

surface_raised: Hsla

Raised surface: opaque pills and chips that sit proud of the panel. Dark: lighter than surface. Light: white, separated by border + shadow rather than by lightness.

surface_card: Hsla

Inline card resting on the main panel (auth gate, empty-state cards).

surface_dialog: Hsla

Modal dialog, floating over a Theme::scrim.

surface_overlay: Hsla

Popover, menu and command-palette surface — the highest plane.

element_hover: Hsla

Hover wash for interactive rows and buttons, on glass and off it alike: ../desktop’s --color-hover.

element_active: Hsla

Active/selected wash, one rung over the hover — --color-active.

border: Hsla

Hairline border.

border_strong: Hsla

Stronger border for focused/raised edges.

text: Hsla

Primary text. ~17.5:1 on its own background in both appearances.

text_muted: Hsla

Muted text: timestamps, secondary labels. ~7.5–8:1.

text_faint: Hsla

Faint text: placeholders, disabled. ~4.5:1 — AA for body copy.

text_dim: Hsla

One notch below text_muted — the diff file-path tone. It exists as its own token rather than being folded into text_muted because the dark value was sampled (#989898) and folding it would shift that label, which is a palette change dressed up as a refactor.

solid: Hsla

The maximum-contrast solid fill: near-white on dark, near-black on light. This is the primary button plate.

on_solid: Hsla

Label/icon color on top of Self::solid — its inverse.

accent: Hsla

Accent — the emphasis weight for text and icons.

Neutral by default, and deliberately. A component library that ships a hue puts that hue in every app that installs it, and bezel had an indigo running through spinners, pagination, date selection and list markers before anyone chose it. The default is now the same lightness with the chroma at zero.

This is the token to brand:

let mut theme = Theme::for_appearance(appearance);
theme.accent = my_brand_accent(appearance);

See set_palette, which is what makes an override survive an appearance switch.

accent_strong: Hsla

Stronger accent for fills that carry Self::on_accent text. Neutral by default, it is the maximum-contrast plate — a mid grey would not carry a label the way the indigo it replaced did.

on_accent: Hsla

Label color on top of Self::accent_strong.

danger: Hsla

Danger — red (errors, stop button).

danger_muted: Hsla

Softer danger for secondary/inline error copy.

warning: Hsla

Warning — amber (offline notices, awaiting-input).

warning_muted: Hsla

Softer warning for secondary copy.

success: Hsla

Success / online — emerald.

busy: Hsla

Working / streaming indicator — pink.

success_muted: Hsla

Softer success for text on a success-tinted chip.

surface_raised_hover: Hsla

Hover tone for an opaque raised pill. Hover must brighten the plate in dark mode, never swap it for a translucent wash (that made pills go see-through — user-reported); in light mode it darkens instead, same idea.

band: Hsla

Recessed band behind a palette/picker header or footer strip. Translucent so the glass still reads through.

input_bg: Hsla

The composer pill and other input plates.

Its own token because “lifted” inverts between appearances. On dark, a faint white wash over near-black reads as raised. The literal light translation — a faint black wash on white — reads as recessed, a dent rather than a plate, which is why the prompt looked like bare text on a smudge. Light mode lifts the way light UIs actually do: pure white, with the border and shadow carrying the elevation.

selection: Hsla

Text-selection highlight in the composer and inputs.

cursor: Hsla

Terminal block cursor.

caret: Hsla

Text caret — Self::accent’s lightness.

Measured macOS 26, 2026-08-31: NSColor.textInsertionPointColor is the accent in both appearances, where NSColor.textColor is white and black. So a caret is not the next glyph before you type it, which is what this used to carry; the platform gives it its own role, and a brand tints it here the way the system accent tints it there.

ring: Hsla

Keyboard focus ring — a hairline, so it marks the control without restating the label inside it.

danger_strong: Hsla

Destructive-action button fill (danger plate, carries Self::on_accent).

code_text: Hsla

Inline-code text. Neutral: code is already set apart by the mono face and its wash, and a hue on top reads as a link rather than as code.

code_wash: Hsla

Inline-code wash behind Self::code_text.

syntax: SyntaxPalette

Shared paint-only syntax palette.

diff_add: Hsla

Diff: added lines.

diff_del: Hsla

Diff: deleted lines.

diff_hunk_bg: Hsla

Diff: hunk-header wash (bluish grey).

vibrancy_alpha: f32

How opaque the tint over the blurred window is.

vibrancy: bool

Whether the window composites translucent, so the desktop reaches what is painted over it — AppKit’s vibrancy.

glass: bool

Whether components paint glass — translucent popovers and cards, and the lens. An opaque window can still carry it.

material: MaterialSpec

The surfaces this theme can paint. Blur belongs to the look, not to the caller: Apple exposes no blur parameter on either family, only the thickness or the variant.

glass_regular: SurfaceSpec

glass_clear: SurfaceSpec

popover_surface: SurfaceStyle

What the popover surfaces — menus, dialogs, sheets, tooltips — mount on. They take no theme of their own, so this is where the choice lives; a component that owns its surface names its own style instead.

glass_magnify: f32

Lens displacement amplitude, signed; negative inverts it.

glass_dispersion: f32

Per-channel spread of that displacement — the chromatic fringe.

font_sans: SharedString

UI font family — the name the text system resolves, not the bytes. Point it at your own family once you have registered that font with the text system; a family nothing registered falls through to the fallback below.

font_mono: SharedString

Monospace family for code/terminal.

font_sans_fallback: SharedString

Explicit system fallbacks, for callers that want to skip the lookup.

font_mono_fallback: SharedString

Implementations

impl Theme

pub fn branded(brand: &Brand, appearance: Appearance) -> Self

The shipped palette for an appearance, rotated onto a brand. What Theme::install builds, without installing it — for previewing the appearance you are not currently painting.

impl Theme

pub fn vibrancy_tint(&self) -> Hsla

The frost tint painted over the blurred window background (macOS glass), at Brand::vibrancy_alpha. Dark: darker than surface, matched to the reference vibrancy scrim hsl(0 0% 3%). Light: the material’s own measured tone. Opaque, this IS the surface tone.

pub fn window_bg(&self) -> Hsla

The app’s root fill: the frost where glass is on, the opaque panel where it is not. What a root element paints instead of Self::bg, so a window that opens blurred is not then covered over by the paint that made the blur pointless.

pub fn glass_overlay(&self) -> Hsla

The translucent tint floating cards paint over their backdrop blur (see bezel::material). Dark: the reference .glass-surface menu tint verbatim — oklch(0.33 0 0 / 34%). The previous surface_overlay at 65% was tuned back when the tint had to approximate the composited recipe without a real blur; kept over the blur it buried the backdrop’s colour and menus read as flat grey slabs next to the hue-inheriting chrome (user report). At 34% the blurred backdrop carries the card and the mid-grey only lifts it off the plane. Light: heavier — a translucent white tint left menu text ghosting over whatever sat behind the popover, so light coverage steps up to keep rows on a known background.

pub fn input_glass_bg(&self) -> Hsla

The composer pill / question panel fill. Light’s input_bg is opaque white (the elevation ladder on an opaque page) — over glass it read as a solid slab in front of the frosted blur, so it thins to a translucent tint there (0.6 and then 0.45 both still read too bright over the 0.80 frost — lowered on user request). Dark’s 3% white wash is already glass-native.

pub fn card_glass_bg(&self) -> Hsla

Section-card fill — the group box, and the in-panel cards built like it.

Each appearance plates in the direction it has room in: dark lifts on a white wash (../desktop’s --color-card), light lands a near-opaque white card on the grey frost, at the coverage Self::glass_overlay already needs to keep rows on a known background. An opaque platform has no frost beneath the card, so it takes the grey below its white page.

pub fn scrim(&self) -> Hsla

The standard modal backdrop — see scrim.

pub fn window_background_appearance(&self) -> WindowBackgroundAppearance

How the platform should composite the window behind our paint.

This is a method rather than a constant because it has to be re-applied after every theme swap: gpui’s macOS backend tears the NSVisualEffectView out of the hierarchy whenever the value is anything but Blurred, and the re-apply in appearance::apply is what restores vibrancy when the user switches back to dark. See zed’s crates/zed/src/main.rs, which runs the same loop on every settings change.

impl Theme

pub fn install(appearance: Appearance, cx: &mut App)

Install the palette for appearance as the gpui global and point the context-free paint helpers at it. The only way the appearance should change — setting the global directly leaves current_appearance stale.

Which palette that is comes from set_palette, so an app with its own colours keeps them across a light/dark switch.

pub fn install_custom(theme: Theme, cx: &mut App)

Install a palette the caller built: brand colours, one retuned token, or a wholesale replacement. Theme is a plain struct with public fields, so the usual shape is Theme::light() with a few fields overwritten.

Use this rather than cx.set_global(theme). The context-free paint helpers (ink, hairline, wash, …) read current_appearance and not the global, so a palette installed around this one leaves them painting for whatever appearance was last installed — light washes over a dark palette, and nothing to point at.

One-shot: appearance::apply rebuilds the palette whenever the appearance changes, so what is installed here is replaced on a light/dark switch. For colours that survive that, register a builder with set_palette instead.

pub fn of(cx: &App) -> &Theme

Read the theme global.

impl Theme

pub const VIBRANCY_ALPHA: f32

The alpha Brand::vibrancy_alpha starts from. Matched by eye to a reference Electron app’s dark glass: its scrim is 0.76 over hsl(0 0% 3%), but sits on the under-window vibrancy MATERIAL, which pre-darkens the blur; a bare backdrop blur has no such layer, so ours runs heavier to land on the same perceived tone.

Opaque off macOS: Linux and Windows get no compositor-blur guarantee, and a merely transparent window would show raw desktop through the sidebar. An app that knows its compositor sets the brand field anyway.

pub const HEADER_HEIGHT: f32 = 44.0

Main-panel header height (the reference h-11) — in-card headers (changes pane).

pub const TITLEBAR_HEIGHT: f32 = 38.0

The unified window titlebar (traffic lights + cluster + tabs). Content rides Self::TITLEBAR_TOP_PAD lower than center so the air above matches the perceived gap to the inset card below (border + card body).

pub const TITLEBAR_TOP_PAD: f32 = 2.0

Downward shift of titlebar content within the bar.

pub const TRAFFIC_LIGHT_INSET: f32

Leading room the macOS traffic lights need where AppKit puts them — zed’s TRAFFIC_LIGHT_PADDING on the macOS 26 SDK (71.0 before it), and the same 78 ../desktop measured for its Tauri window. An app that moves the lights with TitlebarOptions::traffic_light_position owns this number too.

pub const STATUS_STRIP_HEIGHT: f32 = 24.0

Reserved status strip under the content outlet (the reference h-6) — the WorkingIndicator row; reserving it keeps the composer from shifting.

pub const TRANSCRIPT_FADE_BAND: f32 = 24.0

Height of the gradient that fades the transcript into the panel background at its bottom edge. The transcript’s last row must pad itself past this band so settled content (message text, the hover-revealed timestamp) never sits inside the fade when scrolled to the bottom.

pub const BUTTON_HEIGHT: f32 = 24.0

Button, text field and select-trigger height. Measured 2026-09-01: NSButton, NSTextField and NSPopUpButton all report 24 at .regular — Body’s 16pt line box with 4 above and below.

pub const CONTROL_HEIGHT_SMALL: f32 = 20.0

The same controls at .small.

pub const BASE_RADIUS: f32 = 8.0

Button, text field and select-trigger radius — the crate’s most-used corner after the derived ones, and unnamed until the concentric pass separated the eight sites that chose 8.0 from the ones that only arrived at it as 12 − 4.

Every other corner is a ratio of this one, so Brand::radius moves the whole set together.

pub const SPACE: f32 = 8.0

The gap between siblings. Measured on macOS 26, 2026-08-31: NSStackView().spacing, visual format’s -, and constraint(equalToSystemSpacingAfter:multiplier: 1) all report 8.

Carried by ui::stack::row and ui::stack::column, so a call site that wants the standard gap writes no number at all — SwiftUI’s shape, where VStack(spacing:) takes the system’s when given nothing.

pub const CONTENT_MARGIN: f32 = 20.0

The margin from content to its container’s edge. Same measurement, visual format’s |-.

pub fn bubble_radius() -> f32

Message bubble corner radius.

pub fn surface_radius() -> f32

Floating-surface corner radius — popovers, menus, the command palette, group boxes.

A glass surface paints this on its border and hands the same number to bezel::ui::surface’s backdrop blur. The two must agree: a blur cut to a different radius frosts square corners outside a round border, and it shows only on glass and only at the corners. So the radius is named once and read at both ends, rather than written twice sixty lines apart — which is how three independent 12.0s came to exist here.

pub fn panel_radius() -> f32

Panel / card corner radius.

pub fn button_radius() -> f32

Button, text field and select-trigger radius.

pub fn control_radius() -> f32

Small control radius (chips, tags, steppers) — a size down from Self::button_radius, for things that sit inside a control rather than being one.

pub const fn inset_radius(outer: f32, inset: f32) -> f32

The concentric child of a surface: a row inset by inset inside a container of radius outer keeps its corners parallel to the container’s, rather than looking pasted onto it.

This is SwiftUI’s ContainerRelativeShape rule done as arithmetic. gpui has no container shape to inherit at paint time, so the relationship is stated where the child is defined instead of resolved at runtime — which means a container that changes its padding carries its rows with it, and the derived value never becomes a constant of its own.

impl Theme

pub fn dark() -> Self

Build the dark theme. The surface tones are sampled straight from the reference screenshots of the original app (docs/reference): main panel #060606, shell/sidebar #0d0d0d.

pub fn light() -> Self

Build the light theme.

Neutrals are the same oklch scale read from the other end, but the roles are reassigned rather than mirrored (see the module docs): content plane white, chrome grey, raised surfaces white-plus-shadow. Text tones are picked to reproduce the dark theme’s contrast ratios, and accents drop from the 400 to the 600 step at identical hue so they clear WCAG AA on white instead of glowing.

pub fn for_appearance(appearance: Appearance) -> Self

Build the theme for an appearance.

impl Theme

pub fn ink(&self, alpha: f32) -> Hsla

Overlay ink at alpha — see ink.

pub fn hairline(&self, alpha: f32) -> Hsla

Hairline ink at alpha — see hairline.

pub fn wash(&self, alpha: f32) -> Hsla

State wash at alpha — see wash.

Trait Implementations

impl Clone for Theme

fn clone(&self) -> Theme

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Theme

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Theme

fn default() -> Self

Returns the “default value” for a type.

impl Global for Theme

impl ThemeExt for Theme

fn theme(&self) -> &Theme