GuidesColors and themingOne colors.json feeds every platform's colour handling: the palette per mode, the generated ColorManager, and — on web — the Tailwind `@theme` block. `jui build` also registers colours for you: a raw hex in a layout is extracted into the palette and the layout is rewritten to reference the name. This page covers what that does, when it helps, and where it stops short of a curated palette.8 min read
1. The palette file`Resources/colors.json` sits next to `strings.json` and is distributed to every platform by `jui build`. Its shape is themed: a `modes` list, a `fallback_mode` used when a key is missing from the current mode, a `systemModeMapping` that says which mode the OS appearance selects, and one `{ key: hex }` object per mode. A flat `{ key: hex }` file from an older project is still accepted — the first build migrates it into the themed shape and says so in the log. A key starting with `_` (`_comment`) is a note, at the top level or inside a palette: not a colour and not a mode, and it stays where it was when the build writes the file back. Every other reader of colors.json takes them as notes too: the image modes of section 7, the colour swatches in the generated spec documents, and, as jsonui-cli measured them, Android's code generation and KotlinJsonUI's Dynamic mode.The file travels the same route as strings.json — see /guides/localization for the other half of the Resources pipeline. Keys are mode-agnostic on the layout side: a layout says `"fontColor": "ink_muted"` and the runtime picks the value for whichever mode is current. Two modes may give the same key completely different values — that is the point.
Resources/colors.json
{ "modes": ["light", "dark"], "fallback_mode": "light", "systemModeMapping": { "light": "light", "dark": "dark" }, "light": { "ink": "#0B1220", "ink_muted": "#475467", "surface": "#FFFFFF", "accent": "#2563EB" }, "dark": { "ink": "#F6F5F1", "ink_muted": "#D1CFC7", "surface": "#16161A", "accent": "#D4A574" }}2. Colours register themselvesDuring `jui build`, every layout is scanned for colour-bearing attributes (`background`, `fontColor`, `borderColor`, `tintColor`, `tapBackground`, `caretColor`, and their siblings — /reference/attributes/style lists them with their per-platform notes). A literal hex is looked up in the palette; if it is not there it is added under a generated name, and the distributed layout is rewritten to reference the name instead of the hex. Binding expressions are skipped — `@{...}` is left exactly as written.• The generated name is derived from the colour itself: brightness picks the prefix (`white` / `pale` / `light` / `medium` / `dark` / `deep` / `black`) and the dominant channel adds a suffix (`_red`, `_green`, `_cyan`, …). `#123456` became `dark_cyan` and `#FE4A49` became `medium_red` in a measured run. Descriptive, not meaningful — that is what makes it a placeholder rather than a design token.• A hex that already exists in the palette resolves to that key instead of creating a new one. This is why a layout written with `#475467` ends up referencing `ink_muted`: the build recognised the value. It also means writing a light-mode hex silently opts that node into the token — including the token's dark value.• Extraction writes to the distributed tree, not to what you author. Your layout keeps its hex; the per-platform copy carries the name, and the new entry lands in that copy's palette in a single mode (`extract_into_mode`, defaulting to `light`). Nothing in your source directory changes, so the registration is regenerated on every build rather than remembered.• A name that is not a hex and not in any palette is recorded in `Resources/defined_colors.json` rather than dropped, so a typo or a colour you have not defined yet shows up in one place instead of failing silently at runtime. The file is an output only: it is rebuilt from the layouts on every build and never read back, so a name drops out once no layout uses it. Measured on web: a name drops out once the layout stops using it.
jui build
# you write # the build distributes{ "background": "#123456" } { "background": "dark_cyan" }{ "fontColor": "#475467" } { "fontColor": "ink_muted" } [INFO] Extracting colors from 133 files (0 skipped)...[INFO] Replaced colors in 84 files[INFO] Updated colors.json with 2 new colors across 1 mode(s)[WARN] Color 'dark_cyan' is not defined for every mode in colors.json — Tailwind @theme cannot resolve it (resolving to #123456).3. What each platform getsThe palette is compiled, not shipped as data: each platform gets a generated ColorManager holding every mode's palette, plus the machinery to say which mode is current.On web there is a second output: `theme.css`, a `@generated` Tailwind v4 `@theme static` block with one `--color-<name>` variable per token, plus a `:root[data-theme="<mode>"]` rule re-binding those variables for every non-base mode. It also gives the mode `systemModeMapping` picks for the OS's dark under `@media (prefers-color-scheme: dark)` while nothing has set `data-theme`, so the page follows the OS before any script runs, and with scripts off; and `static` emits every variable, used by a class or not, because a bound colour reads it. The build prints the one `@import` line to add to your global stylesheet; after that, new tokens flow through without touching CSS again. The build also writes `colorModeScript`: render it in `<head>` (`<script dangerouslySetInnerHTML={{ __html: colorModeScript }} />`) and a mode the visitor chose is on the page before the first paint. theme.css and a chosen mode's `<style>` also set `color-scheme`, so the browser's own parts (text fields, selects, checkboxes, scrollbars) are drawn light or dark with the colours. A mode the OS appearance maps to takes that scheme; any other mode takes what colors.json's `colorSchemes` says (`"colorSchemes": {"sepia": "dark"}`), and one it does not mention is light, which `jui build` says once per build until you declare it. This site leaves `color-scheme` to theme.css; measured in Chromium on a local build, a chosen dark mode with the OS light has its browser parts dark before the page's scripts run.
per-platform output
Platform | Generated from colors.json | How a screen reads a colour---------+---------------------------------+---------------------------------------iOS | ColorManager.swift | ColorManager.color(for: "accent") | (ColorMode enum, systemMode- | -> UIColor?, or the SwiftUI Color | Mapping keyed by UIUser- | accessor for a static name | InterfaceStyle) |Android | ColorManager.kt | ColorManager.compose.color("accent") | (object, currentMode is a | -> Compose Color; recomposition is | mutableStateOf) | automatic on a mode changeWeb | ColorManager.ts + theme.css | class `bg-accent` for a static name; | (@theme block + per-mode | ColorManager.resolveColor(x) when the | :root[data-theme="<mode>"]) | value lands in an inline style4. Switching theme at runtimeEvery platform's ColorManager exposes the same three ideas — the current mode, a way to set it, and a way to hear about changes. What differs is only how the change reaches the view layer.• Following the OS is the default until a mode is chosen. `systemModeMapping` maps the system appearance onto your mode names, so a project whose modes are not called light and dark still tracks the OS. iOS reads `UIUserInterfaceStyle` (`applySystemMode`, or feed it a `UITraitCollection` or a SwiftUI `ColorScheme`), Android reads the system dark-theme flag, and web subscribes to `matchMedia('(prefers-color-scheme: dark)')`. A kept choice is read first on every platform (web `localStorage` under `jsonui-color-mode`, Android `SharedPreferences`, iOS `UserDefaults`), and the OS decides only when there is none. Android's generated screens call `ColorManager.compose.FollowSystem()` at the top, which reads the kept choice and hands the OS appearance over during composition, so the first frame has the mode; iOS's generated views pass their `colorScheme` to `ColorManager.applySystemMode` on appear and on change.• `setMode` is an explicit choice: it stops following the OS on every platform and is kept for the next launch or visit, and `followSystemMode = true` (`setFollowSystemMode(true)` on Android) goes back to the OS and keeps that. An unknown mode name is ignored with a warning rather than applied.• Propagation is per platform: Compose holds `currentMode` in a `mutableStateOf` so recomposition is automatic; iOS publishes it on an observable object and hands it to `SwiftJsonUIConfiguration.setThemeMode`, which the generated views observe in a project that has a ColorManager (Dynamic draws again with it, as jsonui-cli measured it); web notifies subscribers — the generated `useColorMode` hook wraps that in `useSyncExternalStore` — and puts a mode that differs from what theme.css already draws into a `<style id="jsonui-color-mode">` in `<head>`, not an attribute on `<html>`, which React renders and would report as a hydration mismatch. This documentation site also mirrors the mode onto `<html data-color-mode>` after hydration for its own hand-written rules. Measured here on this site, built locally, in Chromium: with the OS dark the page drew dark before the app's scripts ran and with scripts off; a mode chosen with the toggle stayed after a reload; no console error. iOS and Android were read from the generated code; no device was run.
5. Static names vs bound coloursA colour written in the layout and a colour handed over by the ViewModel take different paths on web. A static name becomes a Tailwind class backed by the theme variable, so the theme follows with no JavaScript at all. A bound value cannot become a class — it lands in an inline style. The generated code writes it with `ColorManager.cssColor`, which turns a theme name into `var(--color-<name>)`, so it follows the mode in CSS as a class does and a server render draws no other colour; any other value is what `resolveColor` gives.The resolver takes a palette key or any CSS colour: a key becomes the current mode's value (falling back to `fallback_mode`), and a hex, `rgb()` or CSS colour name passes through untouched. It deliberately does not warn on an unresolved value — it cannot tell a mistyped key from a legitimate CSS colour name, and a warning per render would be noise. iOS and Android resolve bound colours by name too. `resolveColor` and `color()` return the hex; only the generated components use `cssColor`.
generated web output
// static token -> Tailwind class, follows the theme with no JS<span className="text-ink_muted bg-surface">…</span> // bound colour -> inline style, resolved through the palettestyle={{ backgroundColor: ColorManager.resolveColor(data.statusBg), color: ColorManager.resolveColor(data.statusFg) }}6. A token is theme-safe only when every mode defines itThe web `@theme` block mirrors mode-complete names only — names present in every mode. A name defined in one mode cannot be a theme variable, because there would be nothing to swap it to. When the mapper meets one, it resolves the name back to its fallback hex and emits that literal (`bg-[#123456]`) so the colour still renders, and warns once per name that the value will not follow the theme.This is exactly what an auto-registered colour is: it lands in one mode, so it warns until a human gives it the other modes' values. The warning is the handover point between the build's placeholder and your palette — it is not something to silence.
7. A picture per modeAn image can change with the colour mode. Put `<name>.<mode>.svg` beside `<name>.svg` in `docs/screens/images` — `logo.dark.svg`, or a mode of your own such as `logo.sepia.svg` — and write `logo` in the layout. The picture follows the same mode as the colours: the OS until a mode is chosen, then the kept choice. An image with no picture for a mode is drawn with its own picture, and a bound image name takes the same route as a written one.• Web keeps `src` as the base picture and adds `content: var(--image-<name>)`. theme.css binds that variable under the colours' own selectors (`:root`, `:root[data-theme]`, the OS's dark), and a chosen mode's `<style>` from colorModeScript binds it too, so the picture is right at the first paint with no script. With no theme.css imported the variable is unbound and the `src` is drawn.• iOS writes `Image(ColorManager.image("logo"))` and Android `painterResource(ColorManager.compose.drawable(R.drawable.logo, "dark" to R.drawable.logo__dark, ...))`; a mode's picture becomes the drawable `logo__dark`, because an Android resource name cannot hold a dot. A bound name goes through `ColorManager.image(...)` on iOS and `ColorManager.compose.drawableName(...)` on Android.• A `<name>.<x>.svg` beside `<name>.svg` whose `x` is not a mode of colors.json stops `jui build` with `ERROR [image-modes]` and exit 1. The check skips a `_` note in colors.json (section 1).
8. Things worth knowing before you rely on itAutomatic registration is a safety net for hexes that slipped into a layout. It is not a palette designer, and a few of its edges are sharp.• Promote, do not accumulate. A generated name like `medium_red` says nothing about intent; give the colour a real name in `colors.json` for every mode and use that name in the layout. Until you do, the build repeats the same warning every run.• A hex that matches a token is a token. Copying `#2563EB` out of a design file gives you `accent`, which in dark mode is a completely different colour. If you wanted a fixed colour rather than the token, do not spell it with the token's light-mode value.• JsonUI hex is alpha-first (`#AARRGGBB`), which CSS cannot parse — it reads `#RRGGBBAA`. The theme emitter converts 8-digit values to `rgba()` for you; a non-hex value (a CSS colour name, say) is simply skipped when the token list is built. The web reorders an 8-digit hex on every other path too: a colour written into a class or a style, a shadow's colour, and what the generated `ColorManager`'s `color()` and `resolveColor()` return at run time, so a bound colour or a colors.json key resolved at run time draws as declared. The drawn colours are jsonui-cli's measurement in Chromium.• A bound colour follows the mode by itself on web only when it is a theme name, because it reaches CSS as the variable. A hex, an `rgb()` or a name defined in one mode only is resolved at render time, so a mode switch reaches it on the next render — the same constraint Compose's `ColorManager.compose.color` has — and so is a colour drawn inside an SVG data URI, such as SelectBox's caret, which cannot read a CSS variable. Static names have no such gap: the CSS variable changes underneath them.
Keep reading
Adding a new languageThe same Resources pipeline for strings.json, locale by locale./guides/localization
Style attributesEvery colour-bearing attribute, with its per-platform notes./reference/attributes/style
ReactJsonUIHow token classes and theme.css fit into the web output./platforms/react