Theme configuration reference

Look up every theme configuration group, default, range, merge rule, and validation failure.

Color, modes, and semantic status

color.light.primary is the only required value. Hex colors accept three or six digits.
color.light.secondary is derived from primary when omitted.
color.dark is partial and inherits missing anchors from light.
color.method defaults to analogous; supported values are analogous, monochromatic, and glass.
color.fixShade defaults to true. It centers the source at shade 500; false places it near its inferred lightness.
defaultTheme defaults to system. semantic values can be shared, then overridden under semantic.light or semantic.dark.

Scale and interaction fields

Scale field	Valid range	Default or derivation
`unit`	> 0	unset; derives several scales when set
`controlHeight`	> 0	40px at comfortable density
`spacing`	> 0	unit or 20% of control height
`radius`	>= 0	unit or 8px
`shadow`	>= 0	0.5
`border`	>= 0	1px
`focus`	>= 0	3px or 0.375× unit
`motion`	>= 0	1×
`opacity`	0–1	0.58
`blur`	>= 0	22px or 2.75× unit
`glassAlpha`	0–1	0.62

Interaction defaults are hoverLift 1px, hoverShadow 1, activeScale 0.98, focusAlpha 0.28, disabledOpacity equal to the scale opacity, and transition equal to the motion multiplier.

Typography and viewport fields

fontFamily is the shared fallback. textFontFamily and headingFontFamily override it independently.
bodySize defaults to 16px, captionSize to 13px, labelSize to 14px, and headingScale to 1.24 unless unit derives the first three.
All typography sizes and headingScale must be positive.
viewport defaults to rootMin 14, rootMax 16, minWidth 320, and maxWidth 960.
The generated root font-size uses clamp, so rem-backed dimensions scale smoothly between viewport bounds.
rootMin may equal rootMax for a fixed root size; minWidth must remain lower than maxWidth.

Output, breakpoints, and token overrides

Generated token names use the canonical --tui prefix.
output.selector defaults to :root and darkSelector defaults to the data-tavo-theme dark selector.
includeMediaQuery defaults to true but emits a system-dark query only when defaultTheme is system.
breakpoint defaults are sm 480, md 768, and lg 1024 and must be strictly ascending.
The current web package compiles responsive props and sx at its published breakpoints; changing config emits different token/build data but does not rebuild packaged media queries.
tokens.light and tokens.dark are arbitrary name-to-string maps applied after generation.

Accessibility configuration

Without accessibility.contrast, theme generation produces no contrast warnings.
AA checks at 4.5:1 and AAA checks at 7:1 for six supported token pairs.
failOnViolation defaults to false. When true, buildThemeTokens and buildTheme throw when warnings exist.
auditThemeA11y converts those thrown violations into error-severity structured issues.
Token overrides can create violations after palette generation, so run the audit on the final project config.

Compare preset starting values

minimal: monochromatic, square quiet surfaces, no shadows, comfortable density, reduced motion.
glass: translucent glass color method, 22px blur, stronger surface rounding and moderate shadow.
enterprise: analogous fixed-shade palette, compact density, restrained radii and shadows.
editorial: spacious density, larger surface radius and heading scale, half-pixel borders.
dense: compact density, 36px medium controls, small radii and quiet shadows.
mobile: spacious density, 46px controls, larger control and surface radii, glass method.
monochrome: strict black primary, monochromatic method, zero radius and shadow.