theme/brand.rs
1//! Brand: one hue for the greys, one for the accent, one radius, and the
2//! text ink.
3//!
4//! Apart from the text ink, a brand moves hue alone: every other lightness in
5//! `palettes.rs` stays as the palette set it.
6
7use gpui::{App, Global, Hsla};
8
9use crate::{Appearance, color, theme::Theme};
10
11/// A hue and how much of it, in oklch terms. `chroma: 0.0` is the shipped
12/// neutral, so [`Brand::default`] reproduces the built-in palette exactly.
13#[derive(Debug, Clone, Copy, PartialEq, Default)]
14pub struct Tint {
15 /// oklch hue, in degrees.
16 pub hue: f32,
17 /// oklch chroma. Neutral ramps live near 0.01–0.05; an accent carries more.
18 pub chroma: f32,
19}
20
21impl Tint {
22 pub const NONE: Self = Self {
23 hue: 0.0,
24 chroma: 0.0,
25 };
26
27 pub const fn new(hue: f32, chroma: f32) -> Self {
28 Self { hue, chroma }
29 }
30}
31
32/// The greys a UI is built on, as oklch hue and chroma.
33///
34/// Tailwind's five neutral families at their 500 step (tailwindcss.com/docs/colors,
35/// read 2026-08-24) — the same list shadcn offers as its base colour, and the
36/// reason these are quoted rather than invented: a neutral that carries hue is
37/// a judgement someone else has already made five times.
38pub const BASE_COLORS: [(&str, Tint); 5] = [
39 ("Neutral", Tint::NONE),
40 ("Stone", Tint::new(58.071, 0.013)),
41 ("Zinc", Tint::new(285.938, 0.016)),
42 ("Gray", Tint::new(264.364, 0.027)),
43 ("Slate", Tint::new(257.417, 0.046)),
44];
45
46/// The alpha of each text role over the appearance's ink — white in dark,
47/// black in light.
48#[derive(Debug, Clone, Copy, PartialEq)]
49pub struct TextInk {
50 /// [`Theme::text`].
51 pub text: f32,
52 /// [`Theme::text_muted`].
53 pub muted: f32,
54 /// [`Theme::text_faint`].
55 pub faint: f32,
56}
57
58impl TextInk {
59 /// The role at `alpha` over `appearance`'s ink.
60 pub fn color(appearance: Appearance, alpha: f32) -> Hsla {
61 match appearance {
62 Appearance::Dark => gpui::hsla(0.0, 0.0, 1.0, alpha),
63 Appearance::Light => gpui::hsla(0.0, 0.0, 0.0, alpha),
64 }
65 }
66
67 /// Writes [`Theme::text`], [`Theme::text_muted`] and [`Theme::text_faint`]
68 /// for the theme's appearance.
69 pub fn paint(&self, theme: &mut Theme) {
70 let appearance = theme.appearance;
71 theme.text = Self::color(appearance, self.text);
72 theme.text_muted = Self::color(appearance, self.muted);
73 theme.text_faint = Self::color(appearance, self.faint);
74 }
75}
76
77/// Text ink for both appearances.
78#[derive(Debug, Clone, Copy, PartialEq)]
79pub struct Ink {
80 pub dark: TextInk,
81 pub light: TextInk,
82}
83
84impl Ink {
85 /// AppKit's label, secondary and tertiary label colours. Muted is under
86 /// 4.5:1 on white, and faint is under 3:1 in both appearances.
87 pub const APPKIT: Self = Self {
88 dark: TextInk {
89 text: 0.85,
90 muted: 0.55,
91 faint: 0.25,
92 },
93 light: TextInk {
94 text: 0.85,
95 muted: 0.50,
96 faint: 0.26,
97 },
98 };
99
100 /// Text and muted at 4.5:1 or more and faint at 3:1 or more, on
101 /// [`Theme::bg`] and [`Theme::surface`] in both appearances.
102 pub const ACCESSIBLE: Self = Self {
103 dark: TextInk {
104 text: 0.85,
105 muted: 0.52,
106 faint: 0.40,
107 },
108 light: TextInk {
109 text: 0.85,
110 muted: 0.56,
111 faint: 0.43,
112 },
113 };
114
115 pub fn for_appearance(&self, appearance: Appearance) -> TextInk {
116 match appearance {
117 Appearance::Dark => self.dark,
118 Appearance::Light => self.light,
119 }
120 }
121}
122
123/// Whether the window composites translucent — AppKit's vibrancy, and Mica.
124///
125/// Three-valued rather than a bool because the honest answer depends on the
126/// appearance, and the appearance moves under the app: the OS switches at
127/// sunset. A bool would have to be rewritten by whoever noticed, and nothing
128/// outside this crate is told when a palette is installed.
129#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
130pub enum Vibrancy {
131 /// Frost where the palette is built for it, which is dark alone.
132 ///
133 /// Light's glass tokens sit near 85% opacity — see [`Theme::glass_overlay`],
134 /// [`Theme::card_glass_bg`] and [`Theme::input_glass_bg`], each tuned there
135 /// because a translucent white tint left text ghosting over whatever sat
136 /// behind it. Light pays for the blur and shows almost none of it, so it is
137 /// not asked for unless an app says so.
138 #[default]
139 Auto,
140 /// Frost in both appearances. What an app asks for when it has tuned its
141 /// own light palette to carry one.
142 On,
143 /// Opaque in both. What a Reduce-transparency switch sets.
144 Off,
145}
146
147impl Vibrancy {
148 /// Whether to composite translucent for `appearance`.
149 ///
150 /// The platform gate rides on [`Vibrancy::Auto`] rather than on the caller:
151 /// it asks for a frost only where the compositor paints one behind the
152 /// window ([`frosted_window`](crate::frosted_window)), since a window that is merely transparent
153 /// shows raw desktop through the sidebar. An app that knows its compositor
154 /// says [`Vibrancy::On`] and gets it anywhere.
155 pub fn on(self, appearance: Appearance) -> bool {
156 match self {
157 Self::Auto => crate::frosted_window() && matches!(appearance, Appearance::Dark),
158 Self::On => true,
159 Self::Off => false,
160 }
161 }
162}
163
164/// What an app changes about the shipped palette without redesigning it.
165///
166/// Installed as a gpui [`Global`]; [`Theme::install`] applies it to whatever
167/// palette is registered, so it survives a light/dark switch and composes with
168/// [`set_palette`](crate::set_palette) rather than competing with it.
169#[derive(Debug, Clone, Copy, PartialEq)]
170pub struct Brand {
171 /// The hue every grey in the palette carries.
172 pub tint: Tint,
173 /// The emphasis hue. Left neutral, the accent follows [`Self::tint`] like
174 /// any other grey — which is what the shipped palette already is.
175 pub accent: Tint,
176 /// The base corner radius; every other corner is a ratio of it. See
177 /// [`Theme::BASE_RADIUS`].
178 pub radius: f32,
179 /// How opaque the tint over the blurred window is. See
180 /// [`Theme::VIBRANCY_ALPHA`], where it starts, and [`Theme::vibrancy_tint`].
181 pub vibrancy_alpha: f32,
182 /// Whether the window composites translucent, which is a question about
183 /// the appearance as much as about the app — see [`Vibrancy`].
184 pub vibrancy: Vibrancy,
185 /// Whether components paint glass. Separate from [`Self::vibrancy`]:
186 /// SwiftUI's material blends within the window, so an opaque window can
187 /// still carry glass — which is what a Reduce-transparency setting asks
188 /// for and the system's own does not do. The converse is a platform
189 /// answer: a Mica window carries no glass, since the blur a card lays over
190 /// the content it covers is [`LENSED`](crate::LENSED) and Mica is not.
191 pub glass: bool,
192 /// The text roles' alphas. [`Ink::APPKIT`] is what the palettes ship.
193 pub ink: Ink,
194}
195
196impl Global for Brand {}
197
198impl Default for Brand {
199 fn default() -> Self {
200 Self {
201 tint: Tint::NONE,
202 accent: Tint::NONE,
203 radius: Theme::BASE_RADIUS,
204 vibrancy_alpha: Theme::VIBRANCY_ALPHA,
205 vibrancy: Vibrancy::Auto,
206 glass: crate::LENSED,
207 ink: Ink::APPKIT,
208 }
209 }
210}
211
212/// The accent's lightness in each appearance — indigo-400's and indigo-600's,
213/// the two steps `palettes.rs` picked so an accent clears WCAG AA on its own
214/// background rather than glowing on one and vanishing on the other.
215const ACCENT_L: (f32, f32) = (0.673, 0.511);
216
217/// The lightness of a *plate* carrying [`Theme::on_accent`], taken from
218/// `danger_strong` — the palette's existing chromatic plate, already tuned to
219/// hold a label in both appearances.
220const PLATE_L: (f32, f32) = (0.58, 0.51);
221
222impl Theme {
223 /// The shipped palette for an appearance, rotated onto a brand. What
224 /// [`Theme::install`] builds, without installing it — for previewing the
225 /// appearance you are not currently painting.
226 pub fn branded(brand: &Brand, appearance: Appearance) -> Self {
227 let mut theme = Self::for_appearance(appearance);
228 brand.apply(&mut theme);
229 theme
230 }
231}
232
233impl Brand {
234 /// Rotate a palette onto this brand's hues.
235 pub fn apply(&self, theme: &mut Theme) {
236 // The one place the appearance and the brand are both in hand, and it
237 // already runs on every install — which is every light/dark switch,
238 // from the OS or from a person. Resolving here is what keeps vibrancy
239 // right across a sunset without anyone outside watching for one.
240 theme.vibrancy = self.vibrancy.on(theme.appearance);
241 // Left where the brand put it, even when the window is opaque: every
242 // reader of the tint is behind a `vibrancy` gate already
243 // ([`Theme::window_bg`]), and an app that turns the frost back on
244 // wants the coverage it tuned, not a value that was overwritten while
245 // nothing was looking at it.
246 theme.vibrancy_alpha = self.vibrancy_alpha;
247 theme.glass = self.glass;
248 self.ink.for_appearance(theme.appearance).paint(theme);
249 // Every colour token, with the rule doing the choosing: a token that is
250 // already grey takes the tint, and one that already carries a hue —
251 // danger, warning, success — is semantic and keeps it. Translucent ink
252 // is skipped because it paints over whatever is beneath it, which is
253 // tinted already.
254 let tokens: [&mut Hsla; 39] = [
255 &mut theme.bg,
256 &mut theme.surface,
257 &mut theme.surface_raised,
258 &mut theme.surface_card,
259 &mut theme.surface_dialog,
260 &mut theme.surface_overlay,
261 &mut theme.element_hover,
262 &mut theme.element_active,
263 &mut theme.border,
264 &mut theme.border_strong,
265 &mut theme.text,
266 &mut theme.text_muted,
267 &mut theme.text_faint,
268 &mut theme.text_dim,
269 &mut theme.solid,
270 &mut theme.on_solid,
271 &mut theme.accent,
272 &mut theme.accent_strong,
273 &mut theme.on_accent,
274 &mut theme.danger,
275 &mut theme.danger_muted,
276 &mut theme.warning,
277 &mut theme.warning_muted,
278 &mut theme.success,
279 &mut theme.busy,
280 &mut theme.success_muted,
281 &mut theme.surface_raised_hover,
282 &mut theme.band,
283 &mut theme.input_bg,
284 &mut theme.selection,
285 &mut theme.cursor,
286 &mut theme.caret,
287 &mut theme.ring,
288 &mut theme.danger_strong,
289 &mut theme.code_text,
290 &mut theme.code_wash,
291 &mut theme.diff_add,
292 &mut theme.diff_del,
293 &mut theme.diff_hunk_bg,
294 ];
295 let syntax: [&mut Hsla; 24] = [
296 &mut theme.syntax.comment,
297 &mut theme.syntax.keyword,
298 &mut theme.syntax.string,
299 &mut theme.syntax.string_special,
300 &mut theme.syntax.escape,
301 &mut theme.syntax.number,
302 &mut theme.syntax.boolean,
303 &mut theme.syntax.type_name,
304 &mut theme.syntax.type_builtin,
305 &mut theme.syntax.constructor,
306 &mut theme.syntax.function,
307 &mut theme.syntax.function_builtin,
308 &mut theme.syntax.macro_name,
309 &mut theme.syntax.property,
310 &mut theme.syntax.constant,
311 &mut theme.syntax.variable,
312 &mut theme.syntax.variable_special,
313 &mut theme.syntax.parameter,
314 &mut theme.syntax.operator,
315 &mut theme.syntax.punctuation,
316 &mut theme.syntax.tag,
317 &mut theme.syntax.attribute,
318 &mut theme.syntax.label,
319 &mut theme.syntax.invalid,
320 ];
321 for slot in tokens.into_iter().chain(syntax) {
322 if slot.a == 1.0 && slot.s <= f32::EPSILON {
323 *slot = color::tint(*slot, self.tint.hue, self.tint.chroma);
324 }
325 }
326
327 if self.accent.chroma > 0.0 {
328 let light = theme.appearance == Appearance::Light;
329 let (accent_l, plate_l) = if light {
330 (ACCENT_L.1, PLATE_L.1)
331 } else {
332 (ACCENT_L.0, PLATE_L.0)
333 };
334 theme.accent = color::oklch(accent_l, self.accent.chroma, self.accent.hue);
335 theme.accent_strong = color::oklch(plate_l, self.accent.chroma, self.accent.hue);
336 // Whichever label the plate can actually hold. The shipped accent is
337 // the maximum-contrast neutral, where the answer is always the
338 // inverse; a chromatic plate at a yellow hue is bright enough that
339 // the inverse would be the unreadable one.
340 theme.on_accent = label_on(theme.accent_strong, theme);
341 }
342 }
343}
344
345/// Whichever of the palette's two extremes the plate can actually hold.
346fn label_on(plate: Hsla, theme: &Theme) -> Hsla {
347 let (a, b) = (theme.solid, theme.on_solid);
348 if color::contrast_ratio(plate, a) >= color::contrast_ratio(plate, b) {
349 a
350 } else {
351 b
352 }
353}
354
355/// Read the installed brand (the default before one is set).
356pub fn brand(cx: &App) -> Brand {
357 cx.try_global::<Brand>().copied().unwrap_or_default()
358}
359
360/// Install a brand and repaint every window with it.
361///
362/// Colours are read imperatively at paint time, so nothing observes the theme
363/// global — the same reason [`appearance::apply`](crate::appearance::apply)
364/// refreshes rather than notifies.
365pub fn set_brand(brand: Brand, cx: &mut App) {
366 cx.set_global(brand);
367 Theme::install(crate::paint::current_appearance(), cx);
368 // Crossing 1.0 is what puts the `NSVisualEffectView` in or takes it out,
369 // and nothing else does it — a repaint alone leaves a window that was
370 // opaque at boot opaque forever.
371 crate::appearance::reapply_window_background(cx);
372 cx.refresh_windows();
373}