theme/theme/mod.rs
1//! The app theme: one token set, two concrete instances.
2
3use gpui::{Global, Hsla, SharedString};
4
5use crate::{Appearance, paint};
6
7mod family;
8mod glass;
9pub(crate) mod install;
10mod layout;
11mod palettes;
12mod syntax;
13pub(crate) mod typography;
14
15pub use family::{Seed, ThemeFamily, Variant};
16pub use layout::{ControlSize, Sizing};
17pub use syntax::{HighlightKind, SyntaxPalette};
18pub use typography::{Metrics, TextStyle, Typeset, base_text_size};
19
20/// The two shipped glasses — SwiftUI's `Glass.regular` and `Glass.clear`. A
21/// closed variant rather than knobs: Apple exposes no numbers on glass either,
22/// only the variant and a tint.
23#[derive(Debug, Clone, Copy, PartialEq, Eq)]
24pub enum Glass {
25 /// The everyday material: it blurs what it covers and dims it hard.
26 Regular,
27 /// Near-transparent — the backdrop reads through, bent only at the rim.
28 Clear,
29}
30
31/// SwiftUI's frost scale. Measured 2026-08-31: the five thicknesses are ONE
32/// material at five opacities — the tone implied by `tint / (1 - gain)` holds
33/// to within 9% across the scale, and the sigma does not move at all
34/// (23.1/20.2/21.0pt). So this is a knob, not five looks.
35#[derive(Debug, Clone, Copy, PartialEq, Eq)]
36pub enum Material {
37 UltraThin,
38 Thin,
39 Regular,
40 Thick,
41 UltraThick,
42}
43
44impl Material {
45 /// How much of the backdrop the material covers. Measured off SwiftUI in
46 /// dark; the steps come out even to within a point.
47 pub const fn opacity(self) -> f32 {
48 match self {
49 Material::UltraThin => 0.440,
50 Material::Thin => 0.543,
51 Material::Regular => 0.638,
52 Material::Thick => 0.737,
53 Material::UltraThick => 0.825,
54 }
55 }
56}
57
58/// Which surface a caller names. Material and glass are different things with
59/// different vocabularies — a material has thickness, a glass has a variant —
60/// and they meet only at the numbers they resolve to.
61#[derive(Debug, Clone, Copy, PartialEq, Eq)]
62pub enum SurfaceStyle {
63 Material(Material),
64 Glass(Glass),
65}
66
67/// The frost material, before a thickness picks its opacity.
68#[derive(Debug, Clone, Copy, PartialEq)]
69pub struct MaterialSpec {
70 /// The material's own tone, at full coverage.
71 pub tone: Hsla,
72 /// Its chroma push, as [`SurfaceSpec::saturation`].
73 pub saturation: f32,
74 /// Its sigma, which does not move with thickness.
75 pub blur: f32,
76 /// SwiftUI's frost has no lit rim at all — measured +0 at the boundary.
77 /// What is here is bezel's own hairline, the one the popover card used to
78 /// draw, moved to the surface that owes it.
79 pub edge: f32,
80 pub edge_width: f32,
81 pub edge_aa: f32,
82}
83
84impl MaterialSpec {
85 /// This material at one thickness.
86 pub fn at(&self, thickness: Material) -> SurfaceSpec {
87 let opacity = thickness.opacity();
88 SurfaceSpec {
89 gain: 1.0 - opacity,
90 saturation: self.saturation,
91 tint: self.tone.opacity(opacity),
92 blur: self.blur,
93 rim: 0.0,
94 reach: 0.0,
95 edge: self.edge,
96 edge_width: self.edge_width,
97 edge_aa: self.edge_aa,
98 // A wash has nothing to bend, so it needs one to lift off the page.
99 shadow: true,
100 }
101 }
102}
103
104/// One surface's numbers. `out = gain * saturated(backdrop) + tint`, over a
105/// backdrop blurred at `blur`.
106#[derive(Debug, Clone, Copy, PartialEq)]
107pub struct SurfaceSpec {
108 /// Slope of the transfer line. Below 1 compresses contrast toward
109 /// `tint`; above 1 it brightens and slightly expands, which is what light
110 /// `Clear` measures. Named for what it is, not for one of its directions.
111 pub gain: f32,
112 /// How far the backdrop's chroma is pushed from its own grey, before the
113 /// gain drops the level. A gain alone moves level and colour together, so
114 /// this is the only way a surface goes dark and keeps its colours. 1 is
115 /// the pass-through `Clear` measures.
116 pub saturation: f32,
117 /// Its offset — the look's own tone.
118 pub tint: Hsla,
119 /// Gaussian sigma under the lens, in logical pixels. It stands in for the
120 /// average attenuation of fine detail, which the real material gets from
121 /// snapshotting its backdrop coarsely.
122 pub blur: f32,
123 /// How far in from the rim the lens bends the backdrop, in logical pixels.
124 /// A length rather than a share of the box: the displacement curve measured
125 /// 2026-08-30 is one curve, the same from a 96pt box to a 320pt one and
126 /// from r24 to r84. Past it the backdrop is untouched.
127 pub rim: f32,
128 /// How far the outermost pixel drags what it samples, in logical pixels —
129 /// the far end of that same curve, measured at ~47pt.
130 pub reach: f32,
131 /// How much white the lit rim adds at the edge itself, 0..1.
132 pub edge: f32,
133 /// How far in that light falls off to nothing, in logical pixels. Even the
134 /// whole way round: measured 2026-08-30, the real rim reads the same on all
135 /// four sides.
136 pub edge_width: f32,
137 /// The coverage ramp at the shape's own boundary, in logical pixels. 0.5
138 /// is one device pixel at 2x — the plain rasteriser's answer; 0 is the hard
139 /// edge it replaced.
140 pub edge_aa: f32,
141 /// Whether the surface casts [`paint::surface_shadows`], painted outside
142 /// its shape.
143 pub shadow: bool,
144}
145
146impl SurfaceSpec {
147 /// The one backdrop this surface returns unchanged — `tint / (1 - gain)`,
148 /// opaque. What a renderer with no backdrop blur paints in its place: the
149 /// tint alone is a coverage over a blur, and with no blur under it the
150 /// backdrop reads through as itself.
151 ///
152 /// `None` where the line has no such point — a `gain` of 1 or above
153 /// brightens whatever it covers, and a `tint` carrying more light than the
154 /// surface covers exceeds white.
155 ///
156 /// `tint` is [`Self::tint`] unless a caller substituted its own.
157 pub fn flat(&self, tint: Hsla) -> Option<Hsla> {
158 let coverage = 1.0 - self.gain;
159 let l = tint.l * tint.a / coverage;
160 (coverage > 0.0 && l <= 1.0).then_some(Hsla { l, a: 1.0, ..tint })
161 }
162}
163
164impl SurfaceStyle {
165 /// The numbers this style resolves to against a theme.
166 pub fn spec(self, theme: &Theme) -> SurfaceSpec {
167 match self {
168 SurfaceStyle::Material(thickness) => theme.material.at(thickness),
169 SurfaceStyle::Glass(Glass::Regular) => theme.glass_regular,
170 SurfaceStyle::Glass(Glass::Clear) => theme.glass_clear,
171 }
172 }
173}
174
175/// The app theme. Two concrete instances — [`Theme::dark`] and [`Theme::light`].
176#[derive(Debug, Clone)]
177pub struct Theme {
178 /// Which appearance these tokens were built for.
179 pub appearance: Appearance,
180 /// The [`ThemeFamily`] these tokens came from, by name. `None` is the
181 /// shipped palette, the only one a [`Brand`](crate::Brand)'s tint rotates.
182 pub family: Option<SharedString>,
183
184 // ---- paint: neutral surfaces ----
185 /// Main content panel. Dark: the deepest plane (#060606). Light: pure white —
186 /// long-form content reads best on an unbroken white field.
187 pub bg: Hsla,
188 /// Shell / sidebar surface. Dark: one step *up* from `bg`. Light: one step
189 /// *down* (grey) — chrome recedes from the content plane in both, which is
190 /// the direction a naive invert gets backwards.
191 pub surface: Hsla,
192 /// Raised surface: opaque pills and chips that sit proud of the panel.
193 /// Dark: lighter than `surface`. Light: white, separated by `border` +
194 /// shadow rather than by lightness.
195 pub surface_raised: Hsla,
196
197 // ---- paint: elevation ladder ----
198 //
199 // Dark mode distinguishes floating planes by lightness, and the steps are
200 // *small* (#0e → #10 → #16 → #1e). They are not interchangeable: collapsing
201 // them onto one token visibly lifts popovers off their intended plane.
202 //
203 // Light mode cannot use the same trick, because the content plane is already
204 // white and there is nothing lighter to climb to. All three land on white and
205 // let `border` + shadow carry the separation instead — the standard light-UI
206 // answer, and the reason this is a ladder of tokens rather than an arithmetic
207 // offset applied to one.
208 /// Inline card resting on the main panel (auth gate, empty-state cards).
209 pub surface_card: Hsla,
210 /// Modal dialog, floating over a [`Theme::scrim`].
211 pub surface_dialog: Hsla,
212 /// Popover, menu and command-palette surface — the highest plane.
213 pub surface_overlay: Hsla,
214 /// Hover wash for interactive rows and buttons, on glass and off it alike:
215 /// `../desktop`'s `--color-hover`.
216 pub element_hover: Hsla,
217 /// Active/selected wash, one rung over the hover — `--color-active`.
218 pub element_active: Hsla,
219 /// Faintest hairline: dividers inside a card, nested frames.
220 pub border_faint: Hsla,
221 /// Hairline border.
222 pub border: Hsla,
223 /// Stronger border for focused/raised edges.
224 pub border_strong: Hsla,
225 /// Canvas workspace background.
226 pub canvas_bg: Hsla,
227 /// Canvas background grid dots.
228 pub canvas_grid: Hsla,
229
230 // ---- paint: text ----
231 /// Primary text. Translucent, like `text_muted` and `text_faint`: the
232 /// appearance's ink at the alpha [`Brand::ink`](crate::Brand::ink) sets.
233 pub text: Hsla,
234 /// Muted text: timestamps, secondary labels.
235 pub text_muted: Hsla,
236 /// Faint text: placeholders, disabled.
237 pub text_faint: Hsla,
238 /// One notch below `text_muted` — the diff file-path tone. It exists as its
239 /// own token rather than being folded into `text_muted` because the dark
240 /// value was sampled (#989898) and folding it would shift that label, which
241 /// is a palette change dressed up as a refactor.
242 pub text_dim: Hsla,
243
244 // ---- paint: high-contrast solid (primary buttons) ----
245 /// The maximum-contrast solid fill: near-white on dark, near-black on light.
246 /// This is the primary button plate.
247 pub solid: Hsla,
248 /// Label/icon color on top of [`Self::solid`] — its inverse.
249 pub on_solid: Hsla,
250
251 // ---- paint: accents ----
252 /// Accent — the emphasis weight for text and icons.
253 ///
254 /// **Neutral by default, and deliberately.** A component library that ships
255 /// a hue puts that hue in every app that installs it, and bezel had an
256 /// indigo running through spinners, pagination, date selection and list
257 /// markers before anyone chose it. The default is now the same lightness
258 /// with the chroma at zero.
259 ///
260 /// This is the token to brand:
261 ///
262 /// ```ignore
263 /// let mut theme = Theme::for_appearance(appearance);
264 /// theme.accent = my_brand_accent(appearance);
265 /// ```
266 ///
267 /// See [`crate::AppExt::set_palette`](crate::AppExt::set_palette), which is what
268 /// makes an override survive an appearance switch.
269 pub accent: Hsla,
270 /// Stronger accent for fills that carry [`Self::on_accent`] text. Neutral by
271 /// default, it is the maximum-contrast plate — a mid grey would not carry a
272 /// label the way the indigo it replaced did.
273 pub accent_strong: Hsla,
274 /// Label color on top of [`Self::accent_strong`].
275 pub on_accent: Hsla,
276 /// Danger — red (errors, stop button).
277 pub danger: Hsla,
278 /// Softer danger for secondary/inline error copy.
279 pub danger_muted: Hsla,
280 /// Warning — amber (offline notices, awaiting-input).
281 pub warning: Hsla,
282 /// Softer warning for secondary copy.
283 pub warning_muted: Hsla,
284 /// Success / online — emerald.
285 pub success: Hsla,
286 /// Working / streaming indicator — pink.
287 pub busy: Hsla,
288 /// Softer success for text on a success-tinted chip.
289 pub success_muted: Hsla,
290
291 // ---- paint: components ----
292 /// Hover tone for an *opaque* raised pill. Hover must brighten the plate in
293 /// dark mode, never swap it for a translucent wash (that made pills go
294 /// see-through — user-reported); in light mode it darkens instead, same idea.
295 pub surface_raised_hover: Hsla,
296 /// Recessed band behind a palette/picker header or footer strip. Translucent
297 /// so the glass still reads through.
298 pub band: Hsla,
299 /// The composer pill and other input plates.
300 ///
301 /// Its own token because "lifted" inverts between appearances. On dark, a
302 /// faint *white* wash over near-black reads as raised. The literal light
303 /// translation — a faint *black* wash on white — reads as **recessed**, a dent
304 /// rather than a plate, which is why the prompt looked like bare text on a
305 /// smudge. Light mode lifts the way light UIs actually do: pure white, with
306 /// the border and shadow carrying the elevation.
307 pub input_bg: Hsla,
308 /// Text-selection highlight in the composer and inputs.
309 ///
310 /// Opaque, painted under the text. Measured macOS 26, 2026-09-27, default
311 /// accent: `NSColor.selectedTextBackgroundColor` is `#B3D7FF` light and
312 /// `#3F638B` dark.
313 pub selection: Hsla,
314 /// Terminal block cursor. Opaque: the glyph under it is drawn in the
315 /// cell's background colour.
316 pub cursor: Hsla,
317 /// Text caret — [`Self::accent`]'s lightness.
318 ///
319 /// Measured macOS 26, 2026-08-31: `NSColor.textInsertionPointColor` is the
320 /// accent in both appearances, where `NSColor.textColor` is white and
321 /// black. So a caret is not the next glyph before you type it, which is
322 /// what this used to carry; the platform gives it its own role, and a brand
323 /// tints it here the way the system accent tints it there.
324 pub caret: Hsla,
325 /// Keyboard focus ring — a hairline, so it marks the control without
326 /// restating the label inside it.
327 pub ring: Hsla,
328 /// Where a dragged block would land in the block editor.
329 pub drop_line: Hsla,
330 /// Fill of the region a dragged pane would dock into, where no material
331 /// paints it. Translucent: the pane under it stays visible.
332 pub drop_target: Hsla,
333 /// Destructive-action button fill (danger plate, carries [`Self::on_accent`]).
334 pub danger_strong: Hsla,
335
336 // ---- paint: code & diff ----
337 /// Inline-code text. Neutral: code is already set apart by the mono face
338 /// and its wash, and a hue on top reads as a link rather than as code.
339 pub code_text: Hsla,
340 /// Inline-code wash behind [`Self::code_text`].
341 pub code_wash: Hsla,
342 /// Shared paint-only syntax palette.
343 pub syntax: SyntaxPalette,
344 /// Diff: added lines.
345 pub diff_add: Hsla,
346 /// Diff: deleted lines.
347 pub diff_del: Hsla,
348 /// Diff: hunk-header wash (bluish grey).
349 pub diff_hunk_bg: Hsla,
350
351 // ---- paint: terminal ----
352 /// The terminal grid's background, behind cells that paint none.
353 pub terminal_bg: Hsla,
354 /// The 16 named ANSI colours: 0-7 normal, 8-15 bright. Indexes 16-255 —
355 /// the xterm cube and grey ramp — are not part of a palette.
356 pub terminal_ansi: [Hsla; 16],
357
358 // ---- glass ----
359 //
360 // Numbers, so they flow with the appearance the way every other token
361 // does. `ui::surface` reads them off the theme it is handed;
362 // nothing here is a parameter on a component.
363 /// How opaque the tint over the blurred window is.
364 pub vibrancy_alpha: f32,
365 /// The fill of a floating content card over a translucent window, at full
366 /// coverage — see [`Self::content_bg`].
367 pub content_background: Hsla,
368 /// How much of the chrome [`Self::content_bg`] covers.
369 pub content_opacity: f32,
370 /// The tint over the blurred window, at full coverage — see
371 /// [`Self::vibrancy_tint`].
372 pub vibrancy_tone: Hsla,
373 /// The blur behind a translucent window, in native filter pixels with no
374 /// scale conversion. Zero leaves the window transparent and unblurred.
375 /// macOS alone; other platforms ignore it.
376 pub window_blur: f32,
377 /// Whether the window composites translucent, so the desktop reaches what
378 /// is painted over it — AppKit's vibrancy.
379 pub vibrancy: bool,
380 /// Whether components paint glass — translucent popovers and cards, and
381 /// the lens. An opaque window can still carry it.
382 pub glass: bool,
383 /// The surfaces this theme can paint. Blur belongs to the look, not to
384 /// the caller: Apple exposes no blur parameter on either family, only the
385 /// thickness or the variant.
386 pub material: MaterialSpec,
387 pub glass_regular: SurfaceSpec,
388 pub glass_clear: SurfaceSpec,
389 /// What the popover surfaces — menus, dialogs, sheets, tooltips — mount
390 /// on. They take no theme of their own, so this is where the choice
391 /// lives; a component that owns its surface names its own style instead.
392 pub popover_surface: SurfaceStyle,
393 /// What a docking drop preview paints on where [`LENSED`](crate::LENSED)
394 /// and [`Theme::glass`] hold; elsewhere it is a [`Theme::drop_target`]
395 /// wash.
396 pub drop_preview: SurfaceStyle,
397 /// What a dragged item's floating copy paints on — see
398 /// `ui::drag::ghost`.
399 pub carried_surface: SurfaceStyle,
400 /// Lens displacement amplitude, signed; negative inverts it.
401 pub glass_magnify: f32,
402 /// Per-channel spread of that displacement — the chromatic fringe.
403 pub glass_dispersion: f32,
404
405 // ---- fonts ----
406 /// UI font family — the name the text system resolves, not the bytes.
407 /// Defaults to the platform's own UI face; point it at your own family
408 /// once you have registered that font with the text system.
409 pub font_sans: SharedString,
410 /// The family prose is set in — what `markdown` shapes a document's body
411 /// with. Defaults to [`Self::font_sans`]; an app that sets it apart gives
412 /// documents a reading face while the chrome keeps the UI one.
413 pub font_body: SharedString,
414 /// Monospace family for code/terminal.
415 pub font_mono: SharedString,
416}
417
418impl Theme {
419 /// Selection wash resolved against this palette, including local previews.
420 pub fn card_selected_bg(&self) -> Hsla {
421 paint::card_selected_bg_for(self.appearance)
422 }
423
424 /// A list row's text at rest: [`Self::text`] selected, else
425 /// [`Self::text_faint`] archived, else [`Self::text_muted`].
426 pub fn row_text(&self, selected: bool, archived: bool) -> Hsla {
427 match (selected, archived) {
428 (true, _) => self.text,
429 (false, true) => self.text_faint,
430 (false, false) => self.text_muted,
431 }
432 }
433
434 /// Overlay ink at `alpha` — see [`ink`](crate::paint::ink).
435 pub fn ink(&self, alpha: f32) -> Hsla {
436 paint::ink_for(self.appearance, alpha)
437 }
438
439 /// The colour at `index` of the categorical set — a chart's series, a
440 /// label's tint: the accent, then the status colours, then hues between
441 /// them. Any index is valid; the set wraps.
442 pub fn categorical(&self, index: usize) -> Hsla {
443 let hue = |color: Hsla, degrees: f32| Hsla {
444 h: degrees / 360.0,
445 ..color
446 };
447 let palette = [
448 self.accent,
449 self.success,
450 self.warning,
451 self.danger,
452 hue(self.success, 185.0),
453 hue(self.accent, 270.0),
454 hue(self.danger, 330.0),
455 hue(self.warning, 50.0),
456 ];
457 palette[index % palette.len()]
458 }
459
460 /// Hairline ink at `alpha` — see [`hairline`](crate::paint::hairline).
461 pub fn hairline(&self, alpha: f32) -> Hsla {
462 paint::hairline_for(self.appearance, alpha)
463 }
464
465 /// State wash at `alpha` — see [`wash`](crate::paint::wash).
466 pub fn wash(&self, alpha: f32) -> Hsla {
467 paint::wash_for(self.appearance, alpha)
468 }
469}
470
471impl Default for Theme {
472 fn default() -> Self {
473 Self::dark()
474 }
475}
476
477impl Global for Theme {}