I just shipped a feature I'm excited about: theme specifications for Gesttalt. It's a way to define your design tokens in a structured TOML file and have them automatically transformed into CSS custom properties.

The Problem

When building themes, it's easy for design decisions to become scattered across CSS files. Colors get hardcoded, spacing becomes inconsistent, and before you know it, your theme is a patchwork of magic numbers.

The Solution

Gesttalt now supports an optional theme/theme.toml file that follows the Theme UI specification. Define your design tokens once:

[colors]
text = "#1a1a1a"
background = "#f5f3ef"
primary = "#1a1a1a"
muted = "#666666"

[colors.bg]
default = "#f5f3ef"
alt = "#eae7e1"
card = "#ffffff"

[fonts]
body = "'Spectral', serif"
monospace = "ui-monospace, monospace"

[fontSizes]
values = ["0.75rem", "1rem", "1.5rem", "2rem", "3rem"]

[space]
values = ["0", "0.5rem", "1rem", "2rem", "4rem"]

[radii]
small = "0.25rem"
default = "0.5rem"
large = "1rem"

During build, Gesttalt generates css/theme.css with all your tokens as CSS custom properties:

:root {
  --color-text: #1a1a1a;
  --color-background: #f5f3ef;
  --color-bg-default: #f5f3ef;
  --color-bg-alt: #eae7e1;
  --font-body: 'Spectral', serif;
  --fontSize-0: 0.75rem;
  --fontSize-1: 1rem;
  --space-0: 0;
  --space-1: 0.5rem;
  --radii-small: 0.25rem;
  /* ... */
}

Then reference them in your CSS:

body {
  font-family: var(--font-body);
  color: var(--color-text);
  background: var(--color-background);
}

.card {
  padding: var(--space-3);
  border-radius: var(--radii-default);
}

Why This Matters

• Consistency - All design decisions live in one place
• Maintainability - Change a color once, it updates everywhere
• Portability - The Theme UI spec is an established standard
• Optional - If you don't need it, just don't create the file

The feature is completely optional. Existing themes continue to work without any changes. But for new themes, or when refactoring existing ones, this provides a clean foundation for systematic design.

Check the SPEC.md for the full documentation on supported scales and naming conventions.