Theme architecture
Building light and dark from semantic tokens
How Gummy UI separates canvas, surface, ink, focus, fruit families, and component-local material so themes can change without rewriting behavior.
By Gummy UI · Published
Name purpose before colour
The Gummy base theme defines semantic canvas, surface, ink, line, focus, and fruit-family values. Components consume those roles or derive local material variables from them. A raspberry action does not need to repeat a raw colour throughout every selector, and body copy does not need to know which dark canvas happens to be active.
This vocabulary lets design review discuss relationships: ink against a stable plane, focus against the surrounding shell, or a fruit rim against its core. The values use OKLCH notation, which makes lightness and chroma easier to compare, but the token’s purpose remains more important than its numeric format.
Treat dark mode as its own optical system
Dark mode is not produced by inverting the finished light interface. The canvas becomes a chromatic dark field, stable reading surfaces gain enough separation, and local gel can become brighter without placing luminous colour behind text. Shadows, lines, muted ink, and focus all need relationships appropriate to the darker environment.
Component-local overrides are sometimes necessary because translucency blends with its surroundings. Those overrides still derive from shared families and remain scoped to the component’s anatomy. This avoids a global dark-mode patch that fixes one surface while flattening every other material.
Keep theme choice in the browser
The public site reads and writes the selected light or dark theme in local storage. An inline bootstrap applies the stored choice or system preference before the page is painted. The theme builder also operates in the browser and produces a portable CSS override; it does not upload a configuration or create an account record.
That local behavior is reflected in the current privacy page. If future account sync or analytics changes the data flow, the implementation and notice will need to change together. For the present public baseline, theme experimentation stays on the device.
Review states in both themes
A theme is not complete because the resting button looks attractive. Focus, disabled, selected, validation, overlay, loading, and dense content states can expose contrast or blending problems that the default misses. Stable text pairs receive token-level checks, while representative components are inspected in light and dark Lab contexts.
The browser-local builder is best used as an exploration and export tool, not as proof that every arbitrary combination is accessible. A copied theme should be reviewed with the actual content and states it will support. The component catalogue provides the source and behavior contract needed for that review.