Fields
5 fields, each with what it does.
| Field | Type | Default | What it does |
|---|---|---|---|
Show confirmationconfirm | on / off | false (off) | A short note with Undo after each tap Shows a pill naming the change with an Undo button for 3 seconds after each local write. |
Change per secondforecastRate | number-1000–1000step 0.01 | — | How fast it is expected to change Keeps moving the shown value by this much per second, -1000 to 1000, from the last real reading. |
Expected to reachforecastTarget | number-1000000–1000000step 1 | — | The number it should reach Moves the shown value toward this number, between -1,000,000 and 1,000,000, until a real reading replaces it. |
Arrival time fromforecastTimeFrom | text | — | Which control says when it arrives Takes the arrival time from another control's value (epoch seconds or ISO date) so the guess lands on time. |
iconMapiconMap | object | — | Show different symbols for different values Swaps the glyph to the symbol listed for the incoming value, with default catching any other value. |
Theme fields
Restyle one control by setting these in its theme object; a layout's theme sets them for every control.
| Field | Type | Default | What it does |
|---|---|---|---|
Accent colortheme.accentColor | color | #667eea | The theme's highlight color Tints the accents wherever no color is set directly. |
Border colortheme.borderColor | color | #FFFFFF1A | The outline around the control Colors the card's outline. |
Border thicknesstheme.borderWidth | number0–5step 0.5 | 1 | How thick the outline is Sets the outline width from 0 (none) to 5 points. |
Inner spacingtheme.controlPadding | number0–24step 1 | 8 | Breathing room inside the edge Adds 0 to 24 points between the control's edge and its content. |
Corner roundnesstheme.cornerRadius | number0–30step 1 | 12 | How rounded the corners are Rounds the control's corners from square (0) to 30 points. |
Text colortheme.foregroundColor | color | #FFFFFF | The main text color Colors the primary text on the control. |
Title text sizetheme.labelFontSize | number8–24step 1 | 12 | How big the title is Sets the title text size from 8 to 24 points. |
Second text colortheme.secondaryColor | color | #FFFFFF99 | The color of the less important text Colors the quieter supporting text. |
Background colortheme.surfacePrimary | color | #FFFFFF0F | The card's fill color Fills the card behind the control with this color. |
Second background colortheme.surfaceSecondary | color | #FFFFFF0A | Second background color Fills the nested surface inside the card with this color. |
Faint text colortheme.tertiaryColor | color | #FFFFFF4D | The faintest text color Colors the faintest text and ink. |
Using a shared field
Inside a doc's fields: or themeFields:, write - use: <name> in place of the whole entry:
themeFields:
- use: borderColor
- use: cornerRadius
does: Rounds the board's corners from square (0) to 30 points.
use:looks the name up in the same section of this file: athemeFields:entry uses a shared theme key, afields:entry uses a shared control field.- The lines under
use:override the shared entry. Onlydefault,min,max,step,summary,does(when the effect on this control differs) and the version pins (since,changes,deprecated,removed,alias; control-def.md "Version pins") may be overridden. Any other key is a lint error, and so is an override that repeats the shared value. - An unknown name is a lint error, and the field is left out of that doc.
- Both parsers expand
use:when they load: the app'sControlDocLoaderand carterkit'scatalog.parse_doc. Every consumer (the inspector, the editor, carterkit, the MCP) sees the full field, exactly as if the doc had written it out.
Adding or changing a shared field
Edit the entry here and every doc that uses it changes with it. To add one, write the full entry in the right
section, then run scripts/migrate-shared-fields.py: it lists every copy, and with --write it turns the
copies that already match (apart from the allowed overrides) into use: lines. A copy that differs anywhere
else is reported, never merged: the wording is the author's call. --candidates 3 lists the fields copied
into three or more docs that have no shared entry yet.
This file has no type: or label:, so no parser treats it as a control.
The editor's chips and categories
chips:, categories:, internal: and canvas: are the settings taxonomy
(docs/superpowers/specs/2026-11-06-settings-taxonomy.md): every field of every control resolves to one
category, and every category has one home in the control editor. Both parsers read them (the app's
ControlDocLoader.taxonomy, carterkit's catalog.parse_taxonomy), and scripts/settings-taxonomy.py reads the
same lists, so there is one copy.
- A field's category is the first that matches: its own
category:(only where the lists are wrong for that control), atheme:list (a theme token; an unlisted colour token iscolour, any otherlook),internalwhen it is deprecated or a container whose grouped leaves carry the editors, agroups:list, afields:list, then the patterns (suffixes:,prefixes:,types:, in the order the categories are written). Left over, a bool isbehaviour, a number or enum islookwhen it is a Style-tab orscrub/lookfield andbehaviourotherwise, and anything else iscontent. - The bar is at most five chips in a fixed order: the control chip, then the shared chips by
order. A shared chip shows when the control has a field of one of itscategories(always: trueshows it on every control).tap:names the field the chip opens on (a*matches any prefix or suffix); the rest are rows in the chip's tray, drawn from each field's type.petals:are the hold petals, five at most: a name (ora|b, the first one the control has) is a shared petal,ownthe control's own petal fields (itsdepth: holdhints first) in the slots the shared ones leave.petalTitles:names a shared petal the same on every control.aliases:maps a doc field to the chip's field it is another name for: a control'stheme.cornerRadiusis the Background chip's Corners petal, so it lives there and never takes a row (aif-8whty.5). - The control chip holds the
contentandbehaviourfields (home: control). The doc names it on its first field,chip: Range; that field is the chip's tap. - Other homes.
home: bindingfields are edited in the Binding view,canvas:fields on the canvas (place and size), and apartbool in the parts tray.internal:lists what has no editor on purpose (identity keys and containers);ControlDocHintTestsandEveryFieldHasAHomeTestsfail on any other field without a home.
Generated from ControlDocs/shared-fields.md. Something unclear or missing? Tell me.