Guide / Controls / Reference

Appearance

The appearance block on a layout controls the app shell — color scheme, header bar, status bar, and background image. Colors and control styling live in theme; appearance is about the chrome around your grid.

Symbol
macwindow
Docs
Docs complete

Fields

5 fields, each with what it does.

Fields
FieldTypeDefaultWhat it does
colorSchemecolorSchemechoiceone of 3—

Light, dark or follow the phone

Switches the whole app between light and dark, or follows the device live.

  • systemfollow the phone's light or dark setting
  • darkalways dark
  • lightalways light
showHeadershowHeaderon / off—

Show the top bar

Shows or hides the header bar above the grid.

statusBarStylestatusBarStylechoiceone of 3—

Colour of the clock and battery

Sets whether the status bar text and icons are light or dark.

  • autopicks whichever reads against the page
  • lightlight text for dark backgrounds
  • darkdark text for light backgrounds
headerheaderobject—

How the top bar looks

Styles the header bar as see-through, frosted or filled with a colour that extends into the status bar.

backgroundImagebackgroundImageobject—

A picture behind everything

Draws an image behind all controls on every tab, with optional blur, opacity and overlay.

Examples

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

Pin the app to dark

Always dark with a see-through header and light status bar text.

JSON 7 lines
{
"appearance": {
  "colorScheme": "dark",
  "statusBarStyle": "light",
  "header": { "style": "transparent" }
}
}

Filled gradient header

A colored header that follows light and dark mode and extends into the status bar.

JSON 10 lines
{
"appearance": {
  "colorScheme": "system",
  "header": {
    "style": "color",
    "dark": ["#0A0F1E", "#0E1A33"],
    "light": "#EAF0FBF2"
  }
}
}

Blurred photo background

A bundled image behind the grid, softened and darkened for readability, with no header bar.

JSON 6 lines
{
"appearance": {
  "showHeader": false,
  "backgroundImage": { "asset": "bg", "blur": 20, "opacity": 0.5, "overlay": "#00000080" }
}
}
"appearance": {
  "colorScheme": "system",
  "showHeader": true,
  "statusBarStyle": "auto",
  "header": { "style": "transparent" },
  "backgroundImage": { "asset": "bg", "blur": 20, "opacity": 0.5 }
}

Omit header for a transparent bar — the page background shows through the bar and the status bar. Provide a color/gradient for a filled bar that extends up into the status bar.

Field Type Description
style transparent / material / color Inferred as color when light/dark are set; otherwise transparent
light color or color[] Fill for light mode — a hex string or a 2+ color gradient
dark color or color[] Fill for dark mode
"header": {
  "style": "color",
  "dark":  ["#0A0F1E", "#0E1A33"],
  "light": "#EAF0FBF2"
}
  • transparent — no fill; seamless with the page. No divider.
  • material — frosted glass bar (stays within the safe area).
  • color — solid or gradient fill that bleeds into the status bar. If the active mode's fill is missing, it falls back to transparent.

Background Image

Field Type Default Description
url string — Remote image URL (loaded async)
asset string — Bundled image asset name
contentMode fill / fit fill Scaling mode
blur number — Gaussian blur radius
opacity number 1.0 Image opacity (0–1)
overlay color — Hex overlay for readability (e.g. "#00000080")

The image sits above the page background/gradient and below all controls, on every tab.

  • Theming — Colors, fonts, per-control styling, light/dark variants
  • Layout Config — Where appearance lives

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