Guide / Controls / Reference

Theming

The theme block on a layout controls colors, fonts, spacing, and per-control-type styling. Every control resolves its appearance from the active theme, and any control can override it locally via its own theme field.

Symbol
paintbrush.pointed.fill
Docs
Docs complete

Fields

114 fields, each with what it does.

Fields
FieldTypeDefaultWhat it does
pageBackgroundpageBackgroundcolor—

The solid colour behind the whole page

Paints the page with one flat colour behind every control.

headerBackgroundheaderBackgroundcolor—

The colour of the top bar

Fills the header bar with this colour in place of the default glass.

tabBarBackgroundtabBarBackgroundcolor—

The colour of the bottom tab bar

Fills the tab bar strip with this colour.

tabBarTinttabBarTintcolor—

The colour of the selected tab

Tints the selected tab icon and label; when unset the accent colour is used.

surfacePrimarysurfacePrimarycolor—

The colour of cards and controls

Fills cards and control backgrounds with this colour.

surfaceSecondarysurfaceSecondarycolor—

The colour of things inside a card

Fills surfaces nested inside a card, one level deeper than the card itself.

surfaceTertiarysurfaceTertiarycolor—

The colour of the deepest layer

Fills the deepest nested surfaces, such as wells inside nested cards.

accentColoraccentColorcolor—

Your main highlight colour

Colours gauges, toggles, sliders and other highlights, and the toggle, slider, stepper and progress tracks follow it unless they set their own.

foregroundColorforegroundColorcolor—

The main text colour

Draws primary text and icons in this colour; by default white in dark mode and black in light mode.

onAccentonAccentcolor—

Text colour on top of accent fills

Draws the text or icon on a filled accent button or band; unset, it picks white or black for the best contrast on each fill.

secondaryColorsecondaryColorcolor—

The softer text colour

Draws secondary text such as captions and sub-labels in this colour.

tertiaryColortertiaryColorcolor—

The faintest text colour

Draws the least prominent text, such as hints, in this colour.

borderColorborderColorcolor—

The colour of card outlines

Strokes the outline of cards and controls in this colour.

statusOKstatusOKcolor—

The good or success colour

Colours success states such as a status light that is on, a good change and success log lines.

statusWarnstatusWarncolor—

The warning colour

Colours warning states such as warn log lines and attention markers.

statusErrorstatusErrorcolor—

The error colour

Colours error states such as a status light that is off, a bad change and error log lines.

statusInfostatusInfocolor—

The information colour

Colours info log lines and other neutral notices.

scrimColorscrimColorcolor—

The dimming colour behind pop-ups

Dims the content behind chips, sheets and overlays; by default black at 35 percent in dark mode and white at 60 percent in light mode.

pageBackgroundGradientpageBackgroundGradientstring[]—

A blend of colours behind the page

Paints the page with a gradient running from top-left to bottom-right through the listed colours.

headerBackgroundGradientheaderBackgroundGradientstring[]—

A blend of colours in the top bar

Fills the header bar with a gradient through the listed colours.

accentGradientaccentGradientstring[]—

A blend of colours for highlights

Fills accent areas with a gradient through the listed colours instead of one flat accent.

borderWidthborderWidthnumber0–6step 0.5—

How thick card outlines are

Sets the stroke width of card and control outlines, with 0 meaning no outline.

cornerRadiuscornerRadiusnumber0–40 ptstep 112

How round the corners are

Rounds every card and control by this many points, and the smaller radii derive from it unless set.

controlPaddingcontrolPaddingnumber0–32step 1—

Space inside controls

Sets the gap between a control's edge and its content, and the spacing rungs derive from it unless set.

cardPaddingcardPaddingnumber0–32 ptstep 112

Space inside group cards

Sets the gap between a group card's edge and the controls inside it.

compactRadiuscompactRadiusnumber0–40step 1—

Corner roundness for small bits

Rounds small chips, badges and tick marks; unset, it is a third of the corner radius.

controlRadiuscontrolRadiusnumber0–40step 1—

Corner roundness for buttons and fields

Rounds buttons, fields and inner controls; unset, it is two thirds of the corner radius.

cardRadiuscardRadiusnumber0–40step 1—

Corner roundness for cards

Rounds group cards and containers; unset, it follows the corner radius.

compactSpacingcompactSpacingnumber0–32step 1—

The tightest gap

Sets small gaps inside a control; unset, it is half the control padding.

standardSpacingstandardSpacingnumber0–48step 1—

The normal gap

Sets the default gap between the parts of a control; unset, it equals the control padding.

sectionSpacingsectionSpacingnumber0–64step 1—

The big gap between sections

Sets the gap between groups or sections; unset, it is twice the control padding.

emphasizedBorderWidthemphasizedBorderWidthnumber0–8step 0.5—

The thicker outline for emphasis

Sets the stroke width used for emphasised lines such as chart outlines, heavier than the normal border.

labelFontSizelabelFontSizenumber8–32step 1—

Size of label text

Sets the size of control labels in points.

valueFontSizevalueFontSizenumber8–72step 1—

Size of value text

Sets the size of values shown on controls in points.

readoutFontSizereadoutFontSizenumber8–96step 1—

Size of the big number

Sets the size of the main readout in gauges and stat values in points.

captionFontSizecaptionFontSizenumber8–24step 1—

Size of small print

Sets the size of captions and small print in points.

blurEnabledblurEnabledon / off—

Frosted-glass blur on or off

Turns the blurred glass material behind cards on or off; off gives flat surfaces.

accentaccentcolor—

Pick one accent colour for the whole layout

Sets the accent from a colour name or hex, over the theme pack but under a control's own look.

surfacesurfacechoiceone of 3—

Glass, flat or paper cards

Switches the card material for the whole layout.

  • glassfrosted translucent cards, the default look
  • solidflat opaque grey cards with the blur turned off
  • paperwarm cream cards with the blur off and a hairline border
cornerscornerschoiceone of 3—

Sharp, soft or round corners

Sets one corner shape for the whole layout, and the smaller radii follow it.

  • sharp4 pt corners
  • soft12 pt corners
  • round22 pt corners
typetypechoiceone of 4—

The type style for the whole layout

Switches every text to one type design, replacing a custom font family.

  • systemthe normal system font
  • roundeda rounded system font
  • serifa serif font
  • monoa monospaced font
densitydensitynumber0.7–1.5step 0.05—

How roomy or tight things are

Scales the control and card padding by this factor, so 0.7 is tighter and 1.5 is roomier.

fontFamilyfontFamilytext—

A custom font by name

Draws text in the named font family instead of the system font.

fontDesignfontDesignchoiceone of 4—

The look of the system font

Switches the system font between its default, rounded, serif and monospaced designs.

  • defaultthe normal system design
  • roundeda rounded design
  • serifa serif design
  • monospaceda fixed-width design
valueFontWeightvalueFontWeighttext—

How bold value text is

Sets the weight of value text, for example semibold or bold.

toggletoggleobject—

Restyle every toggle

Holds the toggle look keys that apply to all toggles in this scope.

slidersliderobject—

Restyle every slider

Holds the slider look keys that apply to all sliders in this scope.

stepperstepperobject—

Restyle every stepper

Holds the stepper look keys that apply to all steppers in this scope.

segmentedsegmentedobject—

Restyle every segmented picker

Holds the segmented look keys that apply to all segmented pickers in this scope.

progressBarprogressBarobject—

Restyle every progress bar

Holds the progress bar look keys that apply to all progress bars in this scope.

lightlightobject—

Colours used only in light mode

Applies these colour overrides last, only while the app is showing light mode.

darkdarkobject—

Colours used only in dark mode

Applies these colour overrides last, only while the app is showing dark mode.

palettepaletteobject—

Name your colours once

Defines named colours that any colour field can reuse as a dollar-name reference.

primarypalette.primarycolor—

Your main colour role

Colours every slot that defaults to primary (a gauge arc, a button fill); unset, it is the accent colour.

secondarypalette.secondarycolor—

A second colour for two-tone controls

Colours slots and series entries that name secondary; unset, it is the primary colour.

tertiarypalette.tertiarycolor—

A third colour for series and accents

Colours slots and series entries that name tertiary; unset, it is the secondary colour.

neutralpalette.neutralcolor—

The quiet colour for tracks and ticks

Colours slots that default to neutral, such as tracks and grid lines at their own opacity; unset, it is the foreground colour.

pageBackgroundschemeOverride.pageBackgroundcolor—

The solid colour behind the whole page in this mode

When the app is in this block's mode, paints the page with one flat colour behind every control.

headerBackgroundschemeOverride.headerBackgroundcolor—

The colour of the top bar in this mode

When the app is in this block's mode, fills the header bar with this colour in place of the default glass.

tabBarBackgroundschemeOverride.tabBarBackgroundcolor—

The colour of the bottom tab bar in this mode

When the app is in this block's mode, fills the tab bar strip with this colour.

tabBarTintschemeOverride.tabBarTintcolor—

The colour of the selected tab in this mode

When the app is in this block's mode, tints the selected tab icon and label; when unset the accent colour is used.

surfacePrimaryschemeOverride.surfacePrimarycolor—

The colour of cards and controls in this mode

When the app is in this block's mode, fills cards and control backgrounds with this colour.

surfaceSecondaryschemeOverride.surfaceSecondarycolor—

The colour of things inside a card in this mode

When the app is in this block's mode, fills surfaces nested inside a card, one level deeper than the card itself.

surfaceTertiaryschemeOverride.surfaceTertiarycolor—

The colour of the deepest layer in this mode

When the app is in this block's mode, fills the deepest nested surfaces, such as wells inside nested cards.

accentColorschemeOverride.accentColorcolor—

Your main highlight colour in this mode

When the app is in this block's mode, colours gauges, toggles, sliders and other highlights, and the toggle, slider, stepper and progress tracks follow it unless they set their own.

foregroundColorschemeOverride.foregroundColorcolor—

The main text colour in this mode

When the app is in this block's mode, draws primary text and icons in this colour; by default white in dark mode and black in light mode.

onAccentschemeOverride.onAccentcolor—

Text colour on top of accent fills in this mode

When the app is in this block's mode, draws the text or icon on a filled accent button or band; unset, it picks white or black for the best contrast on each fill.

secondaryColorschemeOverride.secondaryColorcolor—

The softer text colour in this mode

When the app is in this block's mode, draws secondary text such as captions and sub-labels in this colour.

tertiaryColorschemeOverride.tertiaryColorcolor—

The faintest text colour in this mode

When the app is in this block's mode, draws the least prominent text, such as hints, in this colour.

borderColorschemeOverride.borderColorcolor—

The colour of card outlines in this mode

When the app is in this block's mode, strokes the outline of cards and controls in this colour.

statusOKschemeOverride.statusOKcolor—

The good or success colour in this mode

When the app is in this block's mode, colours success states such as a status light that is on, a good change and success log lines.

statusWarnschemeOverride.statusWarncolor—

The warning colour in this mode

When the app is in this block's mode, colours warning states such as warn log lines and attention markers.

statusErrorschemeOverride.statusErrorcolor—

The error colour in this mode

When the app is in this block's mode, colours error states such as a status light that is off, a bad change and error log lines.

statusInfoschemeOverride.statusInfocolor—

The information colour in this mode

When the app is in this block's mode, colours info log lines and other neutral notices.

scrimColorschemeOverride.scrimColorcolor—

The dimming colour behind pop-ups in this mode

When the app is in this block's mode, dims the content behind chips, sheets and overlays; by default black at 35 percent in dark mode and white at 60 percent in light mode.

pageBackgroundGradientschemeOverride.pageBackgroundGradientstring[]—

A blend of colours behind the page in this mode

When the app is in this block's mode, paints the page with a gradient running from top-left to bottom-right through the listed colours.

headerBackgroundGradientschemeOverride.headerBackgroundGradientstring[]—

A blend of colours in the top bar in this mode

When the app is in this block's mode, fills the header bar with a gradient through the listed colours.

accentGradientschemeOverride.accentGradientstring[]—

A blend of colours for highlights in this mode

When the app is in this block's mode, fills accent areas with a gradient through the listed colours instead of one flat accent.

trackColortoggle.trackColorcolor—

Toggle colour when off

Fills the toggle's track while the switch is off.

trackActiveColortoggle.trackActiveColorcolor—

Toggle colour when on

Fills the toggle's track while the switch is on; it follows the accent when unset.

trackRadiustoggle.trackRadiusnumber0–30step 1—

How round the toggle track is

Rounds the corners of the toggle's track.

trackHeighttoggle.trackHeightnumber8–60step 1—

How tall the toggle is

Sets the height of the toggle's track in points.

trackWidthtoggle.trackWidthnumber20–100step 1—

How wide the toggle is

Sets the width of the toggle's track in points.

knobColortoggle.knobColorcolor—

Knob colour when off

Fills the sliding knob while the switch is off.

knobActiveColortoggle.knobActiveColorcolor—

Knob colour when on

Fades the knob to this colour as the switch moves to on.

knobRadiustoggle.knobRadiusnumber0–30step 1—

How round the knob is

Rounds the corners of the toggle's knob.

knobSizetoggle.knobSizenumber8–50step 1—

How big the knob is

Sets the diameter of the toggle's knob in points.

knobShadowtoggle.knobShadowon / off—

Shadow under the knob

Draws or hides a soft shadow beneath the toggle knob.

trackColorslider.trackColorcolor—

Slider track colour

Fills the unfilled part of the slider's track.

trackActiveColorslider.trackActiveColorcolor—

Slider filled colour

Fills the part of the slider's track up to the thumb; it follows the accent when unset.

trackRadiusslider.trackRadiusnumber0–10step 1—

How round the slider track is

Rounds the corners of the slider's track.

trackHeightslider.trackHeightnumber2–20step 1—

How thick the slider track is

Sets the height of the slider's track in points.

thumbColorslider.thumbColorcolor—

Slider handle colour

Fills the draggable thumb of the slider.

thumbRadiusslider.thumbRadiusnumber0–20step 1—

How round the handle is

Rounds the corners of the slider's thumb.

thumbSizeslider.thumbSizenumber8–40step 1—

How big the handle is

Sets the diameter of the slider's thumb in points.

thumbShadowslider.thumbShadowon / off—

Shadow under the handle

Draws or hides a soft shadow beneath the slider thumb.

thumbBorderColorslider.thumbBorderColorcolor—

Outline colour of the handle

Strokes the edge of the slider thumb in this colour.

thumbBorderWidthslider.thumbBorderWidthnumber0–6step 0.5—

Outline thickness of the handle

Sets how thick the thumb's outline is; 0 draws none.

buttonColorstepper.buttonColorcolor—

Stepper button colour

Fills the plus and minus buttons; it follows the accent when unset.

buttonRadiusstepper.buttonRadiusnumber0–30step 1—

How round the stepper buttons are

Rounds the corners of the plus and minus buttons.

buttonSizestepper.buttonSizenumber20–64step 1—

How big the stepper buttons are

Sets the size of the plus and minus buttons in points.

iconColorstepper.iconColorcolor—

Colour of the plus and minus

Draws the plus and minus symbols in this colour.

stylestepper.styletext—

Which stepper layout to use

Names a stepper layout variant, horizontal unless set.

trackColorsegmented.trackColorcolor—

Segmented picker background

Fills the strip behind all the segments.

trackRadiussegmented.trackRadiusnumber0–30step 1—

How round the strip is

Rounds the corners of the strip behind the segments.

selectedColorsegmented.selectedColorcolor—

Colour of the chosen segment

Fills the pill behind the selected segment.

selectedRadiussegmented.selectedRadiusnumber0–30step 1—

How round the chosen pill is

Rounds the corners of the selected segment's pill.

selectedShadowsegmented.selectedShadowon / off—

Shadow under the chosen segment

Draws or hides a soft shadow beneath the selected segment's pill.

textColorsegmented.textColorcolor—

Text colour of unchosen segments

Draws the labels of segments that are not selected.

selectedTextColorsegmented.selectedTextColorcolor—

Text colour of the chosen segment

Draws the selected segment's label; unset, it picks black or white to suit the pill.

trackColorprogressBar.trackColorcolor—

Progress bar background

Fills the empty part of the progress bar.

trackActiveColorprogressBar.trackActiveColorcolor—

Progress bar fill colour

Fills the completed part of the progress bar; it follows the accent when unset.

trackRadiusprogressBar.trackRadiusnumber0–20step 1—

How round the bar is

Rounds the corners of the progress bar's track.

trackHeightprogressBar.trackHeightnumber2–30step 1—

How thick the bar is

Sets the height of the progress bar in points.

Examples

5 examples, each one a control you can paste into a layout.

One-accent dark layout

Sets a single accent, rounder corners and a rounded font, with a dark page gradient that only applies in dark mode.

JSON 11 lines
{
  "theme": {
    "accentColor": "#5AC8FA",
    "cornerRadius": 16,
    "fontDesign": "rounded",
    "dark": {
      "pageBackgroundGradient": ["#0A0F1E", "#0E1A33"],
      "foregroundColor": "#FFFFFF"
    }
  }
}

Palette tokens

Names colours once in palette so changing one entry recolours every field that uses it.

JSON 7 lines
{
  "theme": {
    "palette": { "brand": "#0A84FF", "ink": "#101418" },
    "accentColor": "$brand",
    "pageBackgroundGradient": ["$ink", "#1C2230"]
  }
}

Colour roles

Gives the layout a blue primary and a scheme-aware orange secondary; the Home tab's own palette makes primary green on that page, and one gauge's arc follows the secondary role.

JSON 19 lines
{
  "theme": {
    "palette": {
      "primary": "#0A84FF",
      "secondary": { "light": "#C2410C", "dark": "#FF9F0A" }
    }
  },
  "tabs": [
    {
      "title": "Home",
      "icon": "house",
      "grid": { "columns": 4, "rows": 6 },
      "palette": { "primary": "#34C759" },
      "children": [
        { "type": "gauge", "id": "c_cpu", "position": [0, 0], "span": [2, 2], "label": "CPU", "colors": { "arc": "secondary" } }
      ]
    }
  ]
}

Open in CAR-TER

Quick tokens

Uses the short theme tokens to switch to paper cards, sharp corners, a serif face and a tighter density.

JSON 9 lines
{
  "theme": {
    "accent": "orange",
    "surface": "paper",
    "corners": "sharp",
    "type": "serif",
    "density": 0.85
  }
}

Per-type sub-themes

Restyles every toggle, slider and progress bar in one place.

JSON 7 lines
{
  "theme": {
    "toggle": { "trackActiveColor": "#34C759", "knobShadow": false },
    "slider": { "thumbColor": "#FFFFFF", "trackHeight": 6 },
    "progressBar": { "trackActiveColor": "#5AC8FA", "trackHeight": 10 }
  }
}

The live builder above re-themes a small demo layout as you change values — flip light/dark, pick an accent, and adjust the shape, then copy the generated theme block.

Base Fields

Key Type Default Description
accentColor color #667eea Primary accent (gauges, toggles, highlights)
accentGradient color[] — 2+ color accent gradient
foregroundColor color auto Primary text (auto: white in dark, black in light)
onAccent color auto Text/icon colour drawn ON an accent or tint fill (filled buttons, solid stat-tile bands). Auto: white, or black when white would fall under 3:1 on that fill (so #FFD60A gets dark ink, #0A84FF white). Set it to force one ink everywhere
secondaryColor color auto Secondary text
tertiaryColor color auto Tertiary text
surfacePrimary color auto Card / control surface
surfaceSecondary color auto Nested surface
surfaceTertiary color auto Deepest surface
borderColor color auto Border stroke
borderWidth number 1 Border width
cornerRadius number 12 Control/card corner radius
controlPadding number 8 Inner control padding
cardPadding number 12 Group card padding
blurEnabled bool true Glass material blur
fontFamily string — Custom font (e.g. "Times New Roman")
fontDesign string default default, rounded, serif, monospaced
labelFontSize number 12 Label text size
valueFontSize number 14 Value text size
valueFontWeight string semibold Value weight
readoutFontSize number 17 Primary readout size (gauge and stat values)
captionFontSize number 11 Caption and small-print size
statusOK color #34C759 Success: status light on, good delta, log success
statusWarn color #FF9500 Warning: log warn, attention states
statusError color #FF453A Error: status light off, bad delta, log error
statusInfo color #5AC8FA Info: log info
scrimColor color auto Wash behind chips and overlays (dark: black 35%, light: white 60%)

Content tokens only: app chrome (chrome*, glassWave) is not a layout key and stays with the app.

Shape & Spacing Ladder

Controls draw from a small scale of radii and spacings rather than one-off numbers. Every rung is optional. Unset, it derives from the base fields above, so a layout that sets only cornerRadius or controlPadding keeps today's look.

Field Type Default (derived) Description
compactRadius number cornerRadius / 3 (4) Small chips, badges, tick marks
controlRadius number cornerRadius * 2 / 3 (8) Buttons, fields, inner controls
cardRadius number cornerRadius (12) Cards and group containers
compactSpacing number controlPadding / 2 (4) Tight gaps inside a control
standardSpacing number controlPadding (8) Default gap between control parts
sectionSpacing number controlPadding * 2 (16) Gap between groups or sections
emphasizedBorderWidth number 1.5 The one emphasis stroke beyond borderWidth

Colors are hex strings and may include alpha: "#RRGGBB" or "#RRGGBBAA".

Light & Dark Variants

Most palettes differ between modes. Put scheme-sensitive colors in light / dark sub-objects — they are applied last, on top of the base, for the active mode. Keep scheme-neutral values (accent, radius, fonts) in the base.

{
"theme": {
  "accentColor": "#5AC8FA",
  "cornerRadius": 16,
  "fontDesign": "rounded",
  "dark": {
    "pageBackgroundGradient": ["#0A0F1E", "#0E1A33"],
    "surfacePrimary": "#FFFFFF12",
    "foregroundColor": "#FFFFFF",
    "borderColor": "#FFFFFF1F"
  },
  "light": {
    "pageBackgroundGradient": ["#EAF0FB", "#D7E3F4"],
    "surfacePrimary": "#FFFFFFF2",
    "foregroundColor": "#0B1220",
    "borderColor": "#0B122014"
  }
}
}

A light / dark block accepts: pageBackground, pageBackgroundGradient, headerBackground, headerBackgroundGradient, tabBarBackground, tabBarTint, surfacePrimary/Secondary/Tertiary, foregroundColor, onAccent, secondaryColor, tertiaryColor, borderColor, accentColor, accentGradient, statusOK, statusWarn, statusError, statusInfo, scrimColor.

The whole app stays in lockstep with the device color scheme — see Appearance for colorScheme.

System layouts carry both palettes. With colorScheme: system (or none) the layout follows the device, so a palette written for one scheme breaks contrast in the other. The editor keeps such a layout balanced: scheme-sensitive colours live in light and dark, both blocks colour the same slots, and in each the text clears 4.5:1 on the page and the accent 3:1 (a missing palette is derived from the other, same hue with the lightness flipped). A layout that sets no page colours keeps the built-in palettes, which already flip. Layouts pinned to dark or light are not touched.

Page & Chrome

Key Type Description
pageBackground color Solid page background
pageBackgroundGradient color[] Page gradient (top-leading → bottom-trailing)
tabBarBackground color Tab bar fill
tabBarTint color Tab bar icon tint

Header chrome lives in Appearance (appearance.header), not the theme.

Per-Type Sub-Themes

Fine-tune a whole control family. Each is an object under the theme:

Sub-theme Notable keys
toggle trackColor, trackActiveColor, knobColor, trackWidth, trackHeight, knobSize, knobShadow
slider trackColor, trackActiveColor, thumbColor, thumbSize, thumbBorderColor, trackHeight
stepper buttonColor, iconColor, buttonSize, style
segmented trackColor, selectedColor, textColor, selectedTextColor
progressBar trackColor, trackActiveColor, trackHeight
{
"theme": {
  "toggle": { "trackActiveColor": "#34C759", "knobShadow": true },
  "slider": { "thumbColor": "#FFFFFF", "trackActiveColor": "#5AC8FA" }
}
}

Per-Control Overrides

Any control can override the theme for itself via its theme field — same keys as above plus its family's per-type keys. See Shadow opacity. A group takes the same theme object and hands it to everything inside it.

Palette Tokens

Name your colours once in theme.palette, then write "$name" in any colour field instead of a hex. Recolouring the layout ("make it blue") is then a one-key edit: change the palette entry and every field that refers to it follows.

{
"theme": {
  "palette": { "brand": "#0A84FF", "leaf": "#34C759", "ink": "#101418" },
  "accentColor": "$brand",
  "pageBackgroundGradient": ["$ink", "#1C2230"],
  "dark": { "foregroundColor": "$leaf" }
}
}
{ "type": "gauge", "id": "c_soil", "tint": "$leaf", "theme": { "trackColor": "$ink" } }
  • Where refs work: any string in a colour position — a key that names a colour (tint, accentColor, *Color, *Background, *Gradient, colors, fill, stroke), each element of an array under such a key, anything inside a theme object (layout, group or control, including light/dark and the per-type sub-themes), and the Appearance header fills. A ref in the styles section resolves exactly like one written inline.
  • Never rewritten: labels, text and other non-colour strings, and the wire blocks (sync, action, longPressAction, connection, sources, alerts, publishers, extensions). A label of "$brand" stays "$brand".
  • Palette values are literal colours (the same hex forms as everywhere else). A value that is itself a $ref, is not a string, or has a name other than letters, digits, _ and - is ignored with a warning. Up to 64 tokens.
  • Unknown tokens ("$nope") never crash and never render black: the field is dropped with a warning ("Repaired on load" in the Layout Hub) and falls back to whatever it would inherit.
  • Resolution happens at load. The saved file keeps the $name refs, so editors (the designer, carterkit, the MCP) edit tokens, not the hexes behind them. Children pushed at runtime into a dynamic group or tab resolve against the active layout's palette the same way, with the same unknown-token fallback.
  • Lint: carterkit's validate_layout and the MCP warn when a raw colour equals a palette token and suggest the $name.

Starting palettes: the playbook theme packs in layout-library/playbook/themes/<slug>.theme.json (24 packs of {theme, appearance, accentColor}) are the presets; copy one's theme and name its colours. Each of the 19 packs has a doc in ControlDocs/themes/<slug>.md whose frontmatter carries its vibe words, accent, light/dark notes, when to use, specimen reference and the tokens object to copy. The numeric style rules (one accent, card alpha 0F-24, cornerRadius 14-16, controlPadding 12 or less, 10 rows on iPhone, the 64n - 8 cell height, light/dark parity) are in Style Rules.

Colour roles

Four names in palette are roles: primary, secondary, tertiary and neutral. A control's doc lists the colours it draws as colour slots (a gauge's arc and track, a chart's series), each with a default role, and a layout repaints a slot through the control's colors key. Change a role and every slot that follows it changes with it.

{
"theme": {
  "palette": {
    "primary": "#0A84FF",
    "secondary": { "light": "#C2410C", "dark": "#FF9F0A" },
    "neutral": { "light": "#334155", "dark": "#CBD5E1" }
  }
}
}
{ "type": "gauge", "id": "c_cpu", "colors": { "arc": "secondary", "track": "[email protected]" } }
  • A role's value is a colour, or { "light": colour, "dark": colour } for the two schemes (one side alone covers both). Role values are literal colours, like every palette value.
  • Where palettes go: the layout's theme.palette, a tab's palette (same object, for that page), a group's or a control's theme.palette. The nearest level that names a role wins, role by role. A group or control that sets its own accentColor but no palette.primary gets primary back from that accent.
  • Unset roles keep today's look: primary is the accent colour, secondary is primary, tertiary is secondary, and neutral is the foreground colour. A layout without roles draws exactly what it drew before roles existed.
  • A slot value in colors (and a slot's default in its doc) is a role, a role at an opacity ([email protected]), a theme colour key (accentColor, foregroundColor, secondaryColor, tertiaryColor, surfacePrimary, surfaceSecondary, surfaceTertiary, borderColor, trackColor, statusOK, statusWarn, statusError, statusInfo, scrimColor, opacity allowed too), a $name token or a colour. A value that does not resolve falls back to the slot's default.
  • Series: a series slot takes an ordered list, "colors": { "series": ["primary", "secondary", "#FF9F0A"] }, or the bare list "colors": ["primary", "secondary"]. Series colours go to series in order. In a doc's series default, secondary and tertiary stand aside until a palette sets them (unset, they would repeat primary), so a chart with no palette keeps its hue walk.
  • Old keys still work: each slot names the existing key that also sets it (its alias, such as tint). A slot draws its colors entry first, then the old key, then its default.
  • $name is not a role: "$primary" reads a plain primary colour at load, once for both schemes. A role written as {light, dark} is not a token, so write primary (no $) in colors to follow the scheme.

Control docs declare their slots in frontmatter (colorSlots:, see Shadow opacity "Colour slots"). ResolvedTheme.resolve(slot:of:) is the one resolver; the controls move onto their slots in stages. Unit (arc, track), Axis bottom (main, series) and Border thickness (fill) draw through theirs.

Cascade

What a control finally draws with, from lowest to highest priority. This is the order ResolvedTheme and GridRenderer actually apply (pinned by the app's PaletteTokenTests.cascadeTable):

# Level Where Notes
1 Built-in defaults — Dark glass palette, accent #667eea
2 Light palette Appearance colorScheme When the layout renders light: black ink, light page #F2F2F7, light tracks. Never overrides a key the theme sets
3 Layout theme theme The base keys above. Per-type sub-themes (toggle, slider, stepper, progressBar) follow the accent unless they set their own colours
4 Scheme override theme.light / theme.dark Applied last at the layout level, for the active mode only. Its accentColor also becomes the accent the per-type tracks follow in that mode (a sub-theme's own colours still win)
5 Group theme group theme Applied over 4 for the group's label, card and every child, recursively through nested groups
6 Control theme control theme Applied over 5 for that control. An accentColor here also re-points the toggle / slider / stepper / progress tracks that were following the accent
7 Control tint control tint Most controls draw their accent as tint ?? theme accent, so tint beats even the control's own theme.accentColor

Two colour settings are not part of the cascade: - The top-level Layout Config accentColor tints the layout's card in the library, the layout switcher and the Glance Surfaces fallback. It does not colour controls inside the layout; set theme.accentColor for that. - Appearance holds the colour scheme and the header fills, not control colours.

Theming levels 3–6 are Pro features: without Pro the layout renders with the default glass theme (level 1–2) and the theme fields are ignored. tint always applies.

Generated from ControlDocs/theming.md. Something unclear or missing? Tell me.