# Colors

Binary UIKit names colors and surfaces by purpose. Components read semantic variables instead of fixed values or theme names.

<h2 id="purpose">Semantic roles</h2>

Canvas, surface, and sunken roles establish the base. Semantic layers assign colors to cards, controls, floating panels, chrome, selections, and prose.

<h2 id="anatomy">Palette structure</h2>

Graphite Light is the base and default. Zinc surfaces, dark neutral text, monochrome technical colors, and a graphite accent define its character.

Accent and status roles communicate selection, progress, warning, and failure. Filled status roles have explicit foreground variables, and controls use a separate thumb foreground.

<h2 id="usage">Provider overrides</h2>

Pass a named preset or a partial `BDThemeOverrides` object to `Provider.overrides`. Graphite Light remains active when `overrides` is absent.

The supported 2x2 model pairs Graphite and Blueprint styles with Light and Dark modes. Graphite Light uses the base tokens and needs no preset. The package exports `BD_PRESET_GRAPHITE_DARK`, `BD_PRESET_BLUEPRINT`, and `BD_PRESET_BLUEPRINT_DARK` for the other three combinations.

Graphite Dark keeps compact ledger geometry on near-black layers. Blueprint Light uses pale drafting paper, blue heading ink, and Cobalt actions. Blueprint Dark keeps the Blueprint geometry on deep blue layers with a brighter Cobalt accent.

The library has no global theme store, picker, or preset-name prop. An application can own a selection and pass the matching object to `Provider`.

<h2 id="details">Roles and states</h2>

Use accent for the primary action and current selection. Use success, warning, danger, and info for states with matching text or icons.

Components use semantic layer, foreground, stroke, focus, and thumb variables. They never inspect `theme.name` or branch by theme ID.

<h2 id="accessibility">Contrast</h2>

Check text, controls, focus rings, status foregrounds, and thumbs on every changed surface. Do not rely on color as the only status cue.

<h2 id="tokens">Tokens</h2>

Use `BD_THEME`, `BD_ACCENT`, and `bdBuildCssVars` when code needs the same values as CSS. Important families include `--bd-layer-*`, `--bd-accent*`, `--bd-{success,warning,danger,info}*`, `--bd-stroke*`, `--bd-focus-ring*`, and `--bd-thumb`.

<h2 id="related">Related</h2>

Start with [Provider](/docs/components/provider) for scope behavior and [Badge](/docs/components/badge) for semantic tones.