← Back to list
01Issue
FeatureShippedSwamp CLIPublic
Assigneesskunk-ape
Relationships
#4939 stagecraft studio: a repository can define a theme (colours, fonts, corner rounding) for its studio
Opened by skunk-ape · 11/20/2026· Shipped 11/20/2026
Problem
The studio has one look: swamp-club's HUD style, in light and dark. Teams who run a factory want the studio to match their own look: colours, fonts and shape.
What to change
A repository can define one studio theme, which the studio uses for everyone who opens it. Viewers still switch between light and dark (and "system") as today. There is no per-viewer theme choice.
What a theme can set
- Colours: any of the studio's colour tokens (today about 50 CSS custom properties: canvas, panels, text, rules, accents, gate and severity colours, journal ticks), with separate light and dark values. A theme may supply light only, dark only, or both. Anything it leaves out keeps the built-in value.
- Fonts: the display, body and monospace faces. A theme can name a bundled face or ship its own font files from the repository (woff2), which the studio serves from its own origin.
- Shape: corner rounding, and other shape values the plan finds worth exposing, such as border width or the gaps between elements. Rounding is mostly hard-coded today (only two
border-radiusrules), so making it themeable means turning it into tokens.
How it's defined
- A theme file in the repository, named from the studio's configuration (the studio model's arguments). The plan picks the format (YAML or JSON) and the configuration key.
- Only known tokens can be set. Values are validated by kind (colour, length, font name or font file), so a theme can't inject CSS or load anything from another origin. The studio's CSP (
default-src 'self', no inline styles) stays as it is. - An invalid theme never breaks the page. The studio falls back to the built-in values for whatever is wrong and reports what it ignored and why.
- Colours that carry meaning (gate states, finding severity, work modes, journal ticks) are contrast-checked against their backgrounds (WCAG AA). A theme that fails gets a warning, not a refusal.
Done when
- A theme file sets colours (light and dark), fonts (bundled and repo-supplied) and corner rounding, and the studio shows it in both modes, locally and through
swamp serve, including under a path prefix. - Invalid tokens, values and font files are ignored with a clear report; a missing theme file is reported, not fatal.
- The light/dark/system switch still works with a theme.
- Docs list every themeable token with its kind and default. One example theme ships with the package. The PR has screenshots of the default and the example theme in light and dark.
- Tests cover validation, fallback, the contrast warning, and fonts served under the CSP.
Out of scope
Per-viewer themes, layout changes, arbitrary CSS, and editing a theme from the studio (it stays read-only).
02Bog Flow
Shipped
Click a lifecycle step above to view its details.
03Sludge Pulse
Sign in to post a ripple.