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