Styling

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

Colours, sizes and type come from the theme. The OS supplies most of the theme, so an app that reads tokens follows light and dark, the user's accent, matugen on Linux and the next OS redesign without a change. Rules in short: donts.md.

Read tokens, never literals

cx.theme() returns the tokens for the window being rendered:

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`
Colour 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 one 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 grey while this stays put. nd check flags the colour constructors (colour-literal); the appearance audit catches the colour whatever produced it.

On macOS the token values themselves are read from the OS (NSColor semantic colours, 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 colours may live

The one place an app names colours 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()]
}

A colour named there on purpose (a brand tint, a tag colour) is passed to the audit with .allow(theme::brand_colors()); anything else that is not a token fails it.

The appearance audit

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

a colour is not 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 the app opens. A window the audit never sees is a window whose dark mode nobody checked.

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 colour, fonts); what they cannot is ignored with a dev warning
Per platform	`.on_macos(\|b\| b.bezel(Bezel::Glass))`, `.on_windows(..)`, `.on_linux(..)`, `.on_web(..)`	one OS deserves a different variant. The closure runs only there, so no `cfg`
Mapping	`.native(Mapping::Segmented)` on a `select`; `.drawn()`	another native control fits better, or the look cannot be expressed natively. `.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 reach for .drawn() on a structural element (sidebar, toolbar, window controls) to get a look. That is the replica the rule against replicas is about.

Glass and materials

glass() is a container on the system material: NSGlassEffectView on macOS 26 and later, NSVisualEffectView below, Mica or Acrylic on Windows, 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."))

.tint(color) takes a colour from the theme file, glass_group() merges nearby glass where the OS does that. Never fake glass with a translucent fill and a blur of your own: it does not 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, watched and applied live (a half-written file keeps the last palette). A theme.toml in the app's config directory overrides tokens on every OS. Neither needs app code; both are why literals are banned.