Styling

Theme tokens, the appearance audit, override layers, and glass.

Colors, sizes, and type come from the theme. The OS supplies most of the theme, so an app that reads tokens follows light and dark mode, the user's accent, matugen on Linux, and the next OS redesign without a code change. For the short list of rules, see donts.md.

Read tokens, never literals

cx.theme() returns the tokens for the window that's rendering:

Group	Tokens
Surfaces	`surface.base`, `surface.sidebar`, `surface.raised`, `surface.raised_hover`, `surface.overlay`
Text	`text.primary`, `text.secondary`, `text.tertiary`, `text.on_accent`, `text.danger`
Lines	`border.subtle`, `border.strong`, `separator`
Color roles	`accent`, `accent_container.{bg, fg}`, `selection`, `danger`, `success`, `warning`, `focus_ring`, `scrim`
Spacing	`spacing.{xs, sm, md, lg, xl}`, `spacing.content_margin`, `spacing.content_width`
Shape and size	`radius.{sm, md, lg, xl}`, `control.{small, regular, large}`
Type	`type_scale.{caption, footnote, body, headline, title, large_title}`, `fonts.{body, rounded, mono}`
Motion	`motion.{fast, normal, slow}`, `motion.spring`

Do:

let theme = cx.theme();
v_flex()
    .p(theme.spacing.content_margin)
    .gap(theme.spacing.sm)
    .child(text(title).text_size(theme.type_scale.title))
    .child(text(subtitle).text_color(theme.text.secondary))

Don't:

v_flex()
    .p(px(20.))
    .child(text(title).text_size(px(22.)).text_color(rgb(0x1c1c1e)))
    .child(text(subtitle).text_color(rgb(0x8e8e93)))

The second version is right in one appearance on one OS. In dark mode the text vanishes, under matugen it clashes, and the next macOS changes the system gray while this code stays put. nd check flags the color constructors (colour-literal), and the appearance audit catches the color no matter what produced it.

On macOS, nd reads the token values from the OS (NSColor semantic colors, text styles, control sizes), so even composed content matches the system. A px(..) is fine for a size that belongs to the content (an avatar, a sidebar's minimum width). Spacing, radii, control heights, and type sizes come from tokens.

Where colors may live

The one place where an app names colors is its theme file: src/theme.rs or anything under src/theme/. colour-literal allows constructors there and nowhere else.

// src/theme.rs
pub fn app() -> ThemeOverride {
    ThemeOverride::new().accent(rgb(0x3d6bff)).radius_scale(1.25)
}

pub fn brand_colors() -> [Hsla; 1] {
    [rgb(0x3d6bff).into()]
}

Pass a color that you name there on purpose (a brand tint, a tag color) to the audit with .allow(theme::brand_colors()). Any other color that isn't a token fails the audit.

The appearance audit

tests/appearance.rs runs in nd check and nd test. It renders every window that it lists in light and dark mode on each backend kind that the target links (and two matugen palettes on GPUI), and reads back every painted fill and text run. It fails when:

A color isn't a theme token or a state derived from one (hover, pressed, disabled).
Text is under WCAG contrast against what it sits on: 4.5:1, or 3:1 for large text (24 px, or 18.66 px bold).

Add a .window(..) for every window that the app opens. If the audit never sees a window, nobody checked that window's dark mode.

Overrides, from narrowest to widest

Defaults are native. Each layer below opts one thing out. Use the narrowest layer that does the job.

Layer	How	Right when
Element style	`.bg(..)`, `.text_color(..)`, `.font(..)`, `.rounded_*()` on a control	one control needs a tint or font. Native controls take what they can express (accent as bezel color, fonts). nd ignores what they can't express, with a dev warning
Per platform	`.on_macos(\|b\| b.bezel(Bezel::Glass))`, `.on_windows(..)`, `.on_linux(..)`, `.on_web(..)`	one OS needs a different variant. The closure runs only there, so you don't need `cfg`
Mapping	`.native(Mapping::Segmented)` on a `select`; `.drawn()`	another native control fits better, or native controls can't express the look. `.drawn()` needs a reason comment (`drawn-reason`)
Subtree theme	`.theme(\|t\| t.accent(..).radius_scale(1.5))` on a container	one region (a card, a sidebar section) has its own accent
Window theme	`window.set_theme(ThemeOverride::new().appearance(Appearance::Dark), cx)`	one window is always dark, or has its own accent
App theme	`Application::new(..).theme(theme::app())`, or `nd::theme::set_app_theme(cx, ..)` at runtime	brand accent and radius scale for the whole app
Patterns	`.pattern(Pattern::Drawn)` on a container, `Application::patterns(Patterns { .. })`, `[patterns]` in `nativedesktop.toml`	menus, tooltips, or popovers drawn by nd instead of the OS
Window chrome	`WindowOptions::main(..).titlebar(Titlebar::Custom)` with `titlebar()`	content runs under the titlebar, with the OS controls in their reserved inset

Never use .drawn() on a structural element (sidebar, toolbar, window controls) to get a look. That's the replica that the rule against replicas is about.

Glass and materials

glass() is a container on the system material: NSGlassEffectView on macOS 26 and later, NSVisualEffectView on earlier versions, Mica or Acrylic on Windows, and compositor blur on Linux where the compositor offers it.

glass().variant(GlassVariant::Clear).rounded_lg().p_3().child(text("Drafts sync when you are online."))

Shape follows Apple's HIG:

Glass the size of a control (64 pt or less on its short side) is a capsule, or a circle when it's square, unless the app gives it a radius (HIG, Buttons: "In general, prefer circular or capsule-shape buttons").
Larger glass is a surface and stays square unless you round it.
A custom component in a bar keeps its corner radius concentric with the bar's (HIG, Toolbars).

Round buttons are Bezel::Circle, the system's own glass circle on 26.

.tint(color) takes a color from the theme file. glass_group() merges nearby glass where the OS supports it. Never fake glass with a translucent fill and a blur of your own. A fake doesn't pick up the wallpaper, the window's activity, or the user's reduced-transparency setting.

Palettes on Linux

On Linux, the palette comes from matugen's ~/.config/<app>/theme.json. nd watches the file and applies it live (a half-written file keeps the last palette). A theme.toml in the app's config directory overrides tokens on every OS. Neither one needs app code, and both are why literals are banned.