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]
}37 fields, each with what it does.
| Field | Type | Default | What it does |
|---|---|---|---|
typetype | choiceone of 46 | — | What kind of control this is Decides which control is drawn and which other fields apply to it.
|
idid | text | — | The control's unique name Lets stored values, sync targets and show/hide rules point at this control; it never appears on screen. |
positionposition | list | — | Which cell it sits in Places the control's top-left corner at this row and column of the grid, counting from 0. |
spanspan | list | — | How many cells it covers Makes the control cover this many rows and columns, so a larger span draws it bigger. |
landscapelandscape | object | — | Where it goes when the phone is on its side Moves or hides the control while an iPhone is in landscape; portrait is unchanged. |
regularregular | object | — | Where it goes on an iPad Moves or hides the control on a wide iPad page. |
namename | text | — | A friendly name for editing Gives the control a readable name in the editor; it is not shown on the page. |
actionaction | object | — | What happens when you tap it Runs this command each time the control is used. |
longPressActionlongPressAction | object | — | What happens when you press and hold Runs this command when the control is held down. |
longPressGrouplongPressGroup | object | — | A pop-up of extra controls on hold Opens a small panel of more controls when the control is held down. |
snapshotActionsnapshotAction | object | — | What happens when the camera takes a photo Runs this command on the camera's shutter and passes the picture along as the image. |
syncsync | object[] | — | Where live values come from Listens for outside updates and shows each new value on the control. |
visiblevisible | object | — | When to show it Shows the control only while the condition is true and hides it otherwise. |
enabledenabled | object | — | When it can be used Dims the control and ignores touches while the condition is false. |
rolerole | choiceone of 1 | — | Make a button submit a form Makes pressing a button inside a form submit that form.
|
fieldfield | text | — | Which form entry it fills Makes an input inside a form write to this draft field instead of one named after its id. |
themetheme | object | — | Look overrides for this one control Changes theme values such as colors and corner roundness for this control only. |
colorscolors | object | — | 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. |
unsupportedTypeunsupportedType | text | — | Set by the app, not by you Marks a control the app did not recognise and replaced; you never write it yourself. |
carouselStylecarouselStyle | choiceone of 3 | — | The look of a carousel's panel Chooses the chrome drawn around a carousel's pages.
|
carouselPeekcarouselPeek | number0–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. |
sortboardConfigsortboardConfig | object | — | The extra settings for this control Holds this control type's own settings; it only affects a control of the matching type. |
compassConfigcompassConfig | object | — | The extra settings for this control Holds this control type's own settings; it only affects a control of the matching type. |
pinboardConfigpinboardConfig | object | — | The extra settings for this control Holds this control type's own settings; it only affects a control of the matching type. |
canvasConfigcanvasConfig | object | — | The extra settings for this control Holds this control type's own settings; it only affects a control of the matching type. |
symbolConfigsymbolConfig | object | — | The extra settings for this control Holds this control type's own settings; it only affects a control of the matching type. |
statTileConfigstatTileConfig | object | — | The extra settings for this control Holds this control type's own settings; it only affects a control of the matching type. |
Background on/offhideBackground | on / off | false (off) | Remove the card behind it Turned on, the glass card disappears and the control floats on the page. |
BackgroundbackgroundColor | color | — | The card's color Fills the card behind the control with this color instead of the theme's. |
Background opacitybackgroundOpacity | number0–1 | — | How see-through the card is Fades the card fill from clear (0) to solid (1). |
Glass or solidbackgroundMaterial | choiceone of 2 | — | Frosted glass or a flat color Chooses how the card fill is drawn.
|
PaddingbackgroundPadding | number0–32 ptstep 1 | 8 | Space inside the card Sets the gap between the card edge and the control, in points. |
Corner radiusbackgroundCornerRadius | number0–40 ptstep 1 | 12 | How rounded the card is Rounds the card's corners, from square to 40 points. |
Border widthbackgroundBorderWidth | number0–8 ptstep 0.5 | 1 | How thick the card outline is Sets the card outline thickness in points; 0 removes it. |
Border colourbackgroundBorderColor | color | — | The card outline color Colors the outline around the card. |
ShadowbackgroundShadow | number0–24 ptstep 1 | 0 | A soft shadow under the card Lifts the card with a blurred drop shadow, 0 for none up to 24 points. |
Shadow opacitybackgroundShadowOpacity | number0–1step 0.05 | 0.3 | How dark the shadow is Sets the shadow's strength from 0 to 1; needs a shadow size above 0. |
3 examples, each one a control you can paste into a layout.
Puts a toggle in the second column of the first row and gives it an editor name.
{
"type": "toggle",
"id": "lamp",
"name": "Desk lamp",
"label": "Lamp",
"position": [0, 1],
"span": [1, 2]
}Removes the glass card so the control sits straight on the page, with its own spot when the phone is on its side.
{
"type": "symbol",
"id": "status-icon",
"position": [0, 0],
"span": [2, 2],
"hideBackground": true,
"landscape": { "position": [0, 0], "span": [1, 1] }
}Gives the card a solid navy fill, a larger corner radius, a thin border and a soft shadow.
{
"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
}| 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 |
| 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 |
| 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.
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 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.
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.
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.
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.
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.
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.
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.
position / span map to size; grid modesfallback and requires for older appsaction and longPressAction worksync delivers live valuesvisible and enabled workGenerated from ControlDocs/control-def.md. Something unclear or missing? Tell me.