Guide / Controls / Reference

Internal

A field that many controls describe the same way is written once, here, and each control doc points at it. This file is the one place its type, range, default, title, hints and help live.

Docs
Docs in progress

Fields

5 fields, each with what it does.

Fields
FieldTypeDefaultWhat it does
Show confirmationconfirmon / offfalse (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 secondforecastRatenumber-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 reachforecastTargetnumber-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 fromforecastTimeFromtext—

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.

iconMapiconMapobject—

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.

Theme fields
FieldTypeDefaultWhat it does
Accent colortheme.accentColorcolor#667eea

The theme's highlight color

Tints the accents wherever no color is set directly.

Border colortheme.borderColorcolor#FFFFFF1A

The outline around the control

Colors the card's outline.

Border thicknesstheme.borderWidthnumber0–5step 0.51

How thick the outline is

Sets the outline width from 0 (none) to 5 points.

Inner spacingtheme.controlPaddingnumber0–24step 18

Breathing room inside the edge

Adds 0 to 24 points between the control's edge and its content.

Corner roundnesstheme.cornerRadiusnumber0–30step 112

How rounded the corners are

Rounds the control's corners from square (0) to 30 points.

Text colortheme.foregroundColorcolor#FFFFFF

The main text color

Colors the primary text on the control.

Title text sizetheme.labelFontSizenumber8–24step 112

How big the title is

Sets the title text size from 8 to 24 points.

Second text colortheme.secondaryColorcolor#FFFFFF99

The color of the less important text

Colors the quieter supporting text.

Background colortheme.surfacePrimarycolor#FFFFFF0F

The card's fill color

Fills the card behind the control with this color.

Second background colortheme.surfaceSecondarycolor#FFFFFF0A

Second background color

Fills the nested surface inside the card with this color.

Faint text colortheme.tertiaryColorcolor#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: a themeFields: entry uses a shared theme key, a fields: entry uses a shared control field.
  • The lines under use: override the shared entry. Only default, 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's ControlDocLoader and carterkit's catalog.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), a theme: list (a theme token; an unlisted colour token is colour, any other look), internal when it is deprecated or a container whose grouped leaves carry the editors, a groups: list, a fields: list, then the patterns (suffixes:, prefixes:, types:, in the order the categories are written). Left over, a bool is behaviour, a number or enum is look when it is a Style-tab or scrub / look field and behaviour otherwise, and anything else is content.
  • 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 its categories (always: true shows 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 (or a|b, the first one the control has) is a shared petal, own the control's own petal fields (its depth: hold hints 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's theme.cornerRadius is the Background chip's Corners petal, so it lives there and never takes a row (aif-8whty.5).
  • The control chip holds the content and behaviour fields (home: control). The doc names it on its first field, chip: Range; that field is the chip's tap.
  • Other homes. home: binding fields are edited in the Binding view, canvas: fields on the canvas (place and size), and a part bool in the parts tray. internal: lists what has no editor on purpose (identity keys and containers); ControlDocHintTests and EveryFieldHasAHomeTests fail on any other field without a home.

Generated from ControlDocs/shared-fields.md. Something unclear or missing? Tell me.