Guide / Controls / Reference

Control Definition

Every control — regardless of type — shares the same base fields. A control is one cell (or span of cells) in a tab or group grid.

Symbol
square.dashed.inset.filled
Docs
Docs complete

Fields

37 fields, each with what it does.

Fields
FieldTypeDefaultWhat it does
typetypechoiceone of 46—

What kind of control this is

Decides which control is drawn and which other fields apply to it.

  • buttona tap target that fires its action
  • togglean on/off switch
  • sliderdrag to pick a number in a range
  • labeltext, optionally live
  • textInputa field to type text into
  • stepperplus and minus buttons for a number
  • segmentedControla row of choices where one is selected
  • colorPickerpick a color
  • imagea picture from a link or symbol
  • gaugea number on a dial
  • sparklinea small trend line
  • progressRingprogress as a ring or bar
  • mapa map with pins
  • pickerchoose one option from a list
  • datePickerpick a date or time
  • graphnodes and links
  • chata message thread
  • listrows of data
  • statusLighta colored status dot
  • logConsolea scrolling log of lines
  • dividera thin separating line
  • spacerempty space
  • webViewan embedded web page
  • joysticka thumb-steered stick that sends direction
  • qrCodea QR code showing text
  • carouselswipeable pages of controls
  • flipCardtwo sides that flip on tap
  • accordionheadings that open and close
  • cardLista stack of cards
  • camerascans barcodes and QR codes
  • chartline, bar and area charts
  • pieChartparts of a whole
  • heatmapcolored cells showing amounts
  • radarseveral scores on one shape
  • boxPlotspread of values per group
  • gantttasks laid out over time
  • sankeyamounts flowing between nodes
  • treemapsizes compared as blocks
  • chordhow things connect to each other
  • sortboarddrag cards between columns
  • compassa ring turned to pick an action
  • pinboardpins placed on a picture
  • canvasitems placed anywhere on a surface
  • symbolan icon that can animate
  • statTilea big number with its change and trend
  • keyValuelabeled readings from one object
ididtext—

The control's unique name

Lets stored values, sync targets and show/hide rules point at this control; it never appears on screen.

positionpositionlist—

Which cell it sits in

Places the control's top-left corner at this row and column of the grid, counting from 0.

spanspanlist—

How many cells it covers

Makes the control cover this many rows and columns, so a larger span draws it bigger.

landscapelandscapeobject—

Where it goes when the phone is on its side

Moves or hides the control while an iPhone is in landscape; portrait is unchanged.

regularregularobject—

Where it goes on an iPad

Moves or hides the control on a wide iPad page.

namenametext—

A friendly name for editing

Gives the control a readable name in the editor; it is not shown on the page.

actionactionobject—

What happens when you tap it

Runs this command each time the control is used.

longPressActionlongPressActionobject—

What happens when you press and hold

Runs this command when the control is held down.

longPressGrouplongPressGroupobject—

A pop-up of extra controls on hold

Opens a small panel of more controls when the control is held down.

snapshotActionsnapshotActionobject—

What happens when the camera takes a photo

Runs this command on the camera's shutter and passes the picture along as the image.

syncsyncobject[]—

Where live values come from

Listens for outside updates and shows each new value on the control.

visiblevisibleobject—

When to show it

Shows the control only while the condition is true and hides it otherwise.

enabledenabledobject—

When it can be used

Dims the control and ignores touches while the condition is false.

rolerolechoiceone of 1—

Make a button submit a form

Makes pressing a button inside a form submit that form.

  • submitpressing the button submits the form it sits in
fieldfieldtext—

Which form entry it fills

Makes an input inside a form write to this draft field instead of one named after its id.

themethemeobject—

Look overrides for this one control

Changes theme values such as colors and corner roundness for this control only.

colorscolorsobject—

Which colour goes where on this control

Points each of the control's colour slots at a palette role such as primary, a theme colour or a literal colour, overriding the slot's default.

unsupportedTypeunsupportedTypetext—

Set by the app, not by you

Marks a control the app did not recognise and replaced; you never write it yourself.

carouselStylecarouselStylechoiceone of 3—

The look of a carousel's panel

Chooses the chrome drawn around a carousel's pages.

  • glassthe standard glass panel and the default
  • translucenta see-through material glass look
  • liquidGlassthe same material glass look as translucent
carouselPeekcarouselPeeknumber0–0.3step 0.05—

How much of the next page shows

Lets a slice of the neighbouring page show at the edge of a carousel, as a share of its width.

sortboardConfigsortboardConfigobject—

The extra settings for this control

Holds this control type's own settings; it only affects a control of the matching type.

compassConfigcompassConfigobject—

The extra settings for this control

Holds this control type's own settings; it only affects a control of the matching type.

pinboardConfigpinboardConfigobject—

The extra settings for this control

Holds this control type's own settings; it only affects a control of the matching type.

canvasConfigcanvasConfigobject—

The extra settings for this control

Holds this control type's own settings; it only affects a control of the matching type.

symbolConfigsymbolConfigobject—

The extra settings for this control

Holds this control type's own settings; it only affects a control of the matching type.

statTileConfigstatTileConfigobject—

The extra settings for this control

Holds this control type's own settings; it only affects a control of the matching type.

Background on/offhideBackgroundon / offfalse (off)

Remove the card behind it

Turned on, the glass card disappears and the control floats on the page.

BackgroundbackgroundColorcolor—

The card's color

Fills the card behind the control with this color instead of the theme's.

Background opacitybackgroundOpacitynumber0–1—

How see-through the card is

Fades the card fill from clear (0) to solid (1).

Glass or solidbackgroundMaterialchoiceone of 2—

Frosted glass or a flat color

Chooses how the card fill is drawn.

  • glassa translucent material under the fill
  • solida flat opaque fill
PaddingbackgroundPaddingnumber0–32 ptstep 18

Space inside the card

Sets the gap between the card edge and the control, in points.

Corner radiusbackgroundCornerRadiusnumber0–40 ptstep 112

How rounded the card is

Rounds the card's corners, from square to 40 points.

Border widthbackgroundBorderWidthnumber0–8 ptstep 0.51

How thick the card outline is

Sets the card outline thickness in points; 0 removes it.

Border colourbackgroundBorderColorcolor—

The card outline color

Colors the outline around the card.

ShadowbackgroundShadownumber0–24 ptstep 10

A soft shadow under the card

Lifts the card with a blurred drop shadow, 0 for none up to 24 points.

Shadow opacitybackgroundShadowOpacitynumber0–1step 0.050.3

How dark the shadow is

Sets the shadow's strength from 0 to 1; needs a shadow size above 0.

Examples

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

A placed control with a name

Puts a toggle in the second column of the first row and gives it an editor name.

JSON 8 lines
{
  "type": "toggle",
  "id": "lamp",
  "name": "Desk lamp",
  "label": "Lamp",
  "position": [0, 1],
  "span": [1, 2]
}

Open in CAR-TER

A floating control with no card

Removes the glass card so the control sits straight on the page, with its own spot when the phone is on its side.

JSON 8 lines
{
  "type": "symbol",
  "id": "status-icon",
  "position": [0, 0],
  "span": [2, 2],
  "hideBackground": true,
  "landscape": { "position": [0, 0], "span": [1, 1] }
}

Open in CAR-TER

A custom card

Gives the card a solid navy fill, a larger corner radius, a thin border and a soft shadow.

JSON 14 lines
{
  "type": "gauge",
  "id": "cpu",
  "label": "CPU",
  "position": [0, 0],
  "span": [2, 2],
  "backgroundColor": "#14213D",
  "backgroundMaterial": "solid",
  "backgroundCornerRadius": 24,
  "backgroundBorderWidth": 1,
  "backgroundBorderColor": "#FFFFFF33",
  "backgroundShadow": 12,
  "backgroundShadowOpacity": 0.4
}

Open in CAR-TER

Required Fields

Field Type Description
type string Control type. One of: button, toggle, slider, stepper, segmentedControl, picker, datePicker, textInput, colorPicker, label, image, gauge, sparkline, progressRing, map, graph, chart, pieChart, heatmap, radar, boxPlot, gantt, sankey, treemap, chord, chat, list, statusLight, logConsole, divider, spacer, webView, joystick, qrCode, camera
id string Unique identifier. Used for value storage, sync targeting, and visibility references. Any non-empty string unique among the layout's controls and groups; see Identity
position [row, col] Zero-indexed grid cell placement

Optional Fields

Field Type Default Description
span [rowSpan, colSpan] [1, 1] Grid cells occupied. colSpan sets width; in a 2-D grid rowSpan sets height (rowSpan × rowHeight). Make a control bigger by spanning more cells. See Grid Dimensions.
landscape {position, span} or {hidden: true} — Where this control sits when an iPhone is on its side; ignored in portrait. Also writable in the document's placements section. See Landscape and iPad
regular {position, span} or {hidden: true} — Where this control sits on an iPad-width page. See Landscape and iPad
controlHeight number — Override the grid-derived height with an exact point value. Rarely needed: in a 2-D grid the cell (rowSpan × rowHeight) is the height, and in a flow grid shaped controls auto-size to their aspect. Use it to pin a height the grid wouldn't otherwise give. See Grid Dimensions.
name string — Readable name the editor shows for this control (e.g. "Water level"). Never used for identity or on the wire; omit it and the editor shows label, then the type
label string — Display label for the control
defaultValue bool/number/string, or a seed — Initial value before sync. Buffer and dataset controls also take a JSON seed; see defaultValue per type
action ActionDefinition — Command fired on interaction
sync SyncDefinition[] — Live state listeners
visible VisibilityCondition — Show/hide condition
enabled VisibilityCondition — Enable/disable condition: false dims the control and ignores touches
role "submit" — On a Border thickness inside a Form group: pressing it submits the form
field string the id Inside a Form group: the draft field this input writes
haptic string varies by type Haptic feedback profile. See Haptics
confirm bool false "Show confirmation": after each of this control's local writes, a 3-second pill naming the change, with Undo. See Confirmation and Undo
animation string or object varies by type Animation override. See Animations
longPressAction ActionDefinition — Action fired on long-press
longPressGroup GroupDefinition — Sub-group popup on long-press
theme object — Per-control theme overrides (see below)
extensions object — Tool data keyed by reverse-DNS name; preserved, never interpreted, 64 KB cap. See Extensions
fallback object — The control an older app shows instead when it doesn't know this type (a control object, or a group; may chain up to 4 hops). It takes this control's id, position and span; ignored by an app that knows the type. See Requires and fallback

Style Fields (shared)

Field Type Default Description
icon string — SF Symbol name
tint string "#667eea" Hex color for accents
style string varies Style variant (per control type)
hideLabel bool false Suppress the label
emptyText string "No <label> yet" list/table: line shown when there are no rows
hideValue bool false Hide the numeric readout (e.g. a ring/gauge's center value) so the control becomes a pure compact visual that scales to fill its cell. Also hides slider and stepper readouts while preserving interaction and accessibility
hideBackground bool false Remove the glass card behind the control — it floats on the page and fills its cell. Pairs with hideValue for a minimal glyph
backgroundColor string — Card fill colour, #RRGGBB or #RRGGBBAA. Absent = the theme surface
backgroundOpacity number 1 Card fill opacity, 0–1 (multiplies any alpha in backgroundColor)
backgroundMaterial string — glass (translucent material under the fill) or solid. Absent = the theme surface
backgroundPadding number 8 Card inner padding in points, 0–32. Absent = the theme controlPadding
backgroundCornerRadius number 12 Card corner radius in points, 0–40. Absent = the theme cornerRadius
backgroundBorderWidth number 1 Card border width in points, 0–8 (0 = none). Absent = the theme borderWidth
backgroundBorderColor string — Card border colour, #RRGGBB or #RRGGBBAA. Absent = the theme border
backgroundShadow number 0 Card drop-shadow blur radius (elevation) in points, 0–24
backgroundShadowOpacity number 0.3 Card drop-shadow opacity, 0–1 (shadow needs backgroundShadow > 0; off when hideBackground)
formatValue string — Number formatter for displayed values (see below)
lineCap string "round" Cross-control attribute (aif-wakfb.8): "round" or "butt" ends on a ring or dial arc (progressRing, gauge)
lineWidth number auto Cross-control attribute (aif-wakfb.8): trend-line stroke in points, 0.5–12 (sparkline auto-scales, statTile 2; chart takes the same name in chartConfig)
glow number 0.3 statusLight: halo strength behind the light, 0–1
valueSize number 34 statTile: point size of the big number, 14–80
barCornerRadius number 4 progressRing: corner rounding of the linear bar, 0–30 pt. A cross-control attribute: chart, gantt and boxPlot take the same name in their config (defaults 3, 5, 3), and treemap, heatmap and sankey take cellCornerRadius the same way. Catalogue row 4 in docs/superpowers/specs/2026-10-27-cross-control-attributes.md
glowRadius number 0 Soft glow behind the control's data mark (arc, ring, line, bars, slices, glyph, text) in the mark's own colours, 0–30 pt. A cross-control attribute: the same name, range, unit and default wherever a control lists it (gauge, progressRing, sparkline, statTile, chart, radar, pieChart, symbol, label; graph's node glow is graphConfig.glowRadius, default 6). The catalogue is docs/superpowers/specs/2026-10-27-cross-control-attributes.md
lineCap enum round End shape of the control's stroked marks: round, butt or square. A cross-control attribute: the same name, values and default wherever a control lists it (gauge track, arc and segments; progressRing ring and linear bar; sparkline; statTile curve; chart lines; radar outline corners). The catalogue is docs/superpowers/specs/2026-10-27-cross-control-attributes.md

Edit hint — the Background chip. backgroundColor carries edit: background: every control's edit pose shows one Background chip whose pop-out holds the on/off switch (hideBackground), colour swatches and a custom colour, an opacity slider (0–100 %) and Glass | Solid. A control's own doc need not repeat it; the pose adds the chip to every control. Groups keep only hideBackground.

Edit hint — the Binding button. sync carries edit: data: every control's edit pose shows a quiet Binding button beside its title. It opens the binding view: where the value comes from (the first listener) with the last value received, and what using the control sends (its action, which keeps edit: action for the inspector). The fields it edits up front are the ones Sync and Toggle expand mark edit: data; My Data sources, slices, the free-layout limit and the data flow sit behind its More.

Hold petals under the Background chip. Press and hold the chip: padding, corner radius, border width and shadow fan out as scrub petals (depth: hold, under: backgroundColor, unit: pt). Their dials snap to 0, the theme default (padding 8, corner 12, border 1) and 4, 8, 12, 16, 20, 24 pt. backgroundBorderColor stays at AI depth. The card chrome (controlSurface) draws all five once for every control; absent fields reproduce the theme look exactly.

One card surface (aif-8whty.5). Every control's card is drawn by the same chrome from the same geometry (CardTokens: the control's background* fields, then its doc's card: default, then the theme), so the Background chip's padding, corners, border and shadow work on all of them and show the same five petals everywhere. A control's theme cornerRadius, borderWidth, borderColor, controlPadding, cardPadding and surfacePrimary are other names for those homes (shared-fields.md's Background aliases:), never petals of their own. A control whose card differs says so in its doc, in one line of JSON:

card: {"draws": "each", "padding": 10, "says": "There is no outer card: the search box and every row are cards.", "since": "next"}
  • draws: card (one card behind the control, the default), face (the control's face is its card; its fill stays the style's: button), each (every panel or item is a card and there is no outer one: accordion, carousel, flip-card, cardList) or when-set (flat until a Background field is set, then the standard card: label, divider, spacer).
  • padding: the card's inner spacing, in points, when the control sets none (chat 0, cardList 10); absent, the theme's.
  • says: one sentence on how this control's card differs (a toggle's button styles light the card while on). Required.

No other control may draw a card of its own: ControlSurfaceTests renders each one and fails when a Background field changes nothing.

Value Types

Controls store their value as one of three types:

Type JSON Used by
Boolean true/false toggle
Number 42, 3.14 slider, stepper, gauge, progressRing, sparkline
String "text" label, textInput, segmentedControl, picker, datePicker, colorPicker, image, map, camera (last scanned value)

defaultValue per type

defaultValue is what a control shows before its first sync, in the shape that sync would deliver:

Control defaultValue
scalar controls (toggle, slider, stepper, gauge, progressRing, label, picker, …) a bool, number or string
sparkline a number, or an array of numbers that seeds the series ([41, 40, 39]; trimmed to sparklinePoints; the readout shows the last point)
list an array of row objects, the rows shown until the first sync
logConsole an array of lines (strings or {text, level} objects)
chart, pieChart, heatmap, radar, boxPlot, gantt, sankey, treemap, chord, graph, cardList, sortboard, pinboard, canvas, map the control's dataset, as JSON ({"series": […]}) or as that JSON encoded in a string

A seed may be at most 4 KB once encoded (the string cap). Saving keeps it exactly as written: an array stays an array. A seed on any other control, or a seed of the wrong shape (a sparkline array with no numbers), is dropped with a "Repaired on load" note: one control's defaultValue never stops a layout loading.

Value Formatters

formatValue formats numeric values for label, gauge, progressRing, slider, and stepper.

Format Example input Output
percent 50.8 50.8%
decimal:N 3.14159 decimal:2 → 3.14; N clamps to 0–12
suffix:X 63.5 suffix:°C → 63.5°C
bytes 1048576 1.00 MB
bytesKB 873740 source is KB → 853.26 MB
bps 1500000 1.50 Mbps
duration 3725 1h 2m
time 125 2:05
relative "2026-09-22T08:15:00Z" / epoch 4 days ago, In 2 hours (label + widget slots; a date, not a number)
relative:day "2026-09-25" Yesterday — whole local calendar days; no date → placeholder (Never)
date "2026-09-25" Sep 25, 2026 — the date itself (label); no date → placeholder
date:time "2026-09-25T14:03:00Z" Sep 25, 2026 at 2:03 PM (label)

Numeric readouts preserve positive step precision (for example, step: 0.01 shows 0.12, and step: 0.25 shows 0.25). Precision is capped at 12 decimal places. Non-finite values display —; none still hides them. Negative time and duration values use one leading minus sign. Times outside the integer range display seconds in scientific notation instead of failing conversion.

Per-Control Theme Overrides

The theme object overrides theme values for a single control. It accepts the same keys as the layout theme block, plus per-type keys for the control's family:

{
  "type": "toggle",
  "id": "wifi",
  "label": "Wi-Fi",
  "theme": {
    "accentColor": "#34C759",
    "cornerRadius": 20,
    "fontDesign": "rounded",
    "trackActiveColor": "#34C759",
    "knobColor": "#FFFFFF"
  }
}

Common override keys: accentColor, foregroundColor, secondaryColor, surfacePrimary, borderColor, borderWidth, cornerRadius, controlPadding, fontFamily, fontDesign, labelFontSize, valueFontSize. Toggle/slider/progress controls also accept trackColor, trackActiveColor, thumbColor, knobColor, etc. See each control's Theme Overrides table for its specific keys, and Theming for the full system.

Shared field definitions (doc frontmatter)

A field that many control docs describe the same way (the theme keys above, the Undo pill's confirm) is defined once, in ControlDocs/shared-fields.md. A doc's fields: or themeFields: entry then reads - use: <name>, with optional default, min, max, step, summary, does and version-pin (since, changes, deprecated, removed, alias) overrides under it, and every parser expands it to the full field when it loads. A summary override replaces the shared summary for that control only; one equal to the shared value is a lint error. scripts/migrate-shared-fields.py lists the copies that still differ from their shared entry.

Colour slots (doc frontmatter)

A control doc lists the colours its renderer draws as colorSlots (aif-5g98i.1, Theming "Colour roles"). Each entry names the slot (the key a layout writes under the control's colors), its default and, when an existing key already set that colour, alias: that key (tint, theme.trackColor). A list default makes a series slot.

colorSlots:
  - slot: arc
    default: primary
    alias: tint
    since: next
    does: Colours the filled part of the arc.
  - slot: track
    default: [email protected]
    since: next
  - slot: series
    default: [primary, "#34C759", "#FF9500"]
    since: next

A default is a role, a role or theme colour key at an opacity ([email protected]), a $name or a colour. Pick the default that draws exactly what the control drew before, so declaring slots changes nothing on screen. Each slot is a capability id, <type>.colors.<slot>, pinned like a field.

Version pins (doc frontmatter)

Each pin sits at the smallest level that changed: a whole doc, one field (nested and theme fields too), or one enum value. You pin additions only; everything a doc had before is covered by its baseline.

  • baseline: the version the unpinned parts of the doc are at least as old as. A doc without one is 2.0, the release pins start from, so no doc writes baseline: "2.0".
  • since: next on anything you add. The release step replaces next with the version it ships.
  • changes: [{in: next, note: "Holding now repeats"}] when an existing key behaves differently.
  • deprecated: next when a key or value is on its way out. Add removed: in the version it stops working, and alias: <name> for the live field or value it now maps to.

A version is next or a marketing version in quotes ("2.1"), so YAML tools do not read it as a number.

fields:
  - name: pressEffect
    type: enum
    since: next
    values: [scale, glow]
  - name: style
    type: enum
    changes: [{in: next, note: "tinted follows the theme accent"}]
    values:
      - filled
      - { value: pill, since: next }
      - { value: outline, deprecated: next, alias: outlined }
      - outlined

values takes plain items, { value, since, changes, deprecated, removed, alias } objects, or both, written inline (values: [filled, { value: pill, since: next }]) or as the block list above. Both parsers give the plain value list plus each pinned value's pins (FieldDef.valuePins, carterkit valueMeta), and nothing filters on them yet. ControlDocs/controldocs.schema.json is the spec for every key a doc may write. ControlDocVersionTests and carterkit's test_controldocs_versions.py check every doc against it, so a mistyped key or a malformed version fails the build.

ControlDocs/capabilities.json is the last release's capability manifest: one id per doc (control.button, doc.sync), field (button.style, chart.chartConfig.xAxis, button.theme.accent) and enum value (button.style.pill), each with its since and pins. scripts/gen-capabilities.py writes it, and the release step runs scripts/gen-capabilities.py --stamp <version> to turn every next into the version it ships. Between releases CapabilityManifestTests (and --check) fail on an id the manifest does not hold unless it says since: next, and on a released id that vanished or changed its since: keep a retired field with deprecated: / removed: and alias:. The doc view's "Version history" is rendered from the pins (ControlDocCapabilities.versionHistory, the script's render_version_history), never written by hand.

Look card formats and presets (doc frontmatter)

A control doc may declare two optional one-line JSON lists that the editor's Look card turns into chips. Neither is a layout field: they are named sets of ordinary field writes.

  • lookFormats: how the value shows (Text: Plain / Number / Last time / Date; Dial: Dial / Ring / Bar).
  • lookPresets: 2 to 4 named looks ("Headline", "Big number", "Quiet").

Each item is {"id", "name", "symbol", "set"}: symbol is an SF Symbol name (never an emoji), set maps field names to the values the chip writes, and null removes the field (back to the doc default). A set may change type between interchangeable controls (Dial's Bar turns a gauge into a progressRing bar). A chip shows as chosen when the control already carries every value in its set.

Generated from ControlDocs/control-def.md. Something unclear or missing? Tell me.