Theme TOML Specification

The theme.toml file is the Anchor of Truth for StarVision. It provides explicit values that override any visual analysis.

Scope: theme.toml drives the wireframe --wf-* variable layer (the low-fidelity design-system preview). It is not a Web Awesome site theme. See docs/theme-design.guide.md for --wa-* token authoring.

Schema Definition

1. [theme]

Metadata and global behavior settings.

Key	Type	Description
`id`	String	Unique slug for the theme (e.g., `tamagui`).
`label`	String	Human-readable name (e.g., `Tamagui`).

Note: Themes no longer declare a single mode. All themes must support both light and dark via separate CSS blocks (:root.wa-light[data-wf-theme="id"] and :root.wa-dark[data-wf-theme="id"]). Web Awesome’s wa-dark/wa-light classes, synced from Starlight, drive mode switching.

2. [brand]

Core color palette. Values map to --wf-color-* variables.

Key	Variable	Default/Typical
`primary`	`--wf-color-primary`	`#5E6AD2`
`primary_text`	`--wf-color-primary-text`	`#FFFFFF`
`bg`	`--wf-color-bg`	`#FFFFFF`
`bg_light`	`--wf-color-bg-light`	`#F7FAFC`
`bg_elevated`	`--wf-color-bg-elevated`	`#FFFFFF`
`text`	`--wf-color-text`	`#1A202C`
`text_muted`	`--wf-color-text-muted`	`#718096`
`border`	`--wf-color-border`	`#E2E8F0`
`border_dark`	`--wf-color-border-dark`	`#CBD5E0`

3. [semantic]

Status and feedback colors.

Key	Variable	Default/Typical
`success`	`--wf-color-success`	`#38A169`
`warning`	`--wf-color-warning`	`#DD6B20`
`danger`	`--wf-color-danger`	`#E53E3E`

4. [geometry]

Radii, weights, and spacing.

Key	Variable	Default/Typical
`radius_card`	`--wf-radius-card`	`12px`
`radius_button`	`--wf-radius-button`	`8px`
`border_width`	`--wf-border-width`	`1px`
`spacing_gap`	`--wf-spacing-gap`	`1rem`

5. [font]

Custom typefaces. Optional — omit to inherit the site font. When provided, StarVision emits an @import for the declared family and sets the --wf-font-* variables.

Key	Variable	Notes
`body`	`--wf-font-body`	Body and label text. Include full CSS font-family string.
`heading`	`--wf-font-heading`	Heading elements. Defaults to `body` value if omitted.
`mono`	`--wf-font-mono`	Code and value text.

Usage Guidelines

Partial Manifests: You only need to define what is known. StarVision will visual-best-fit the rest.
Naming: Keys use snake_case in TOML, mapping to kebab-case CSS variables.
Both Modes Required: The generated CSS file must include a light block and a dark block using the compound selector pattern — see get_instructions("starspec/fragments/wireframe/theme-selector-pattern").
Font loading: If [font] keys are provided, add an @import for the font family above the variable blocks in the generated CSS.

Example

[theme]
id = "tamagui"
label = "Tamagui"

[brand]
# Light mode values
primary = "#3a9e50"
bg = "#ffffff"
text = "#000000"

[brand.dark]
# Dark mode overrides — only specify what differs
primary = "#32d74b"
bg = "#111111"
text = "#ebebeb"

[semantic]
success = "#3a9e50"
warning = "#e5a300"
danger  = "#e54d2e"

[geometry]
radius_card   = "10px"
radius_button = "6px"
spacing_gap   = "0.75rem"

[font]
body    = '"Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif'
heading = '"Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif'
mono    = '"JetBrains Mono", "Fira Code", "Menlo", monospace'