@gridui/theme

GridUI theme. Part of the GridUI React monorepo.

Theme owns semantic token values for color, spacing, typography, focus, motion, and appearance. Grid applies those values to page geometry and structural boundaries; the other Core families apply them to functional surfaces. Theme does not own the structure or state of those components.

Import compiled styles.css for token definitions, opt into reset.css when the application wants document defaults, and use tailwind.css as the explicit raw Tailwind adapter. Shared responsive value resolution and spacing-variable construction live in the React-free @gridui/style-utils/responsive entry.

Palette scopes

Import paletteClass and its Palette type from @gridui/theme, and load @gridui/theme/styles.css. The helper returns a class for a native element; it adds no React dependency, wrapper, landmark, gutter, or structural boundary.

import { paletteClass } from "@gridui/theme";

<section className={paletteClass("brand")}>
    <div className={paletteClass("neutral")}>
        A neutral surface inside the brand region.
        <aside className={paletteClass("brand")}>Brand again.</aside>
    </div>
</section>

paletteClass() and paletteClass("inherit") return no scope class and preserve inherited colors. paletteClass("neutral") explicitly resets to the registered neutral palette. The other choices are brand, warning, and danger. Use one palette class on each surface. All four choices set their own semantic colors and native foreground/background; application utilities can still choose layout or override the painted foreground/background.

Applications register their neutral colors through --gridui-neutral-* source tokens. These are separate from the currently active --gridui-background, --gridui-foreground, and other semantic output tokens. Register at the document root so every nested reset restores the same application palette, for example:

:root {
    --gridui-neutral-background: light-dark(#f7f2e8, #18221e);
    --gridui-neutral-foreground: light-dark(#203c30, #e4eadf);
    --gridui-neutral-muted: light-dark(#5e7066, #aebeb2);
    --gridui-neutral-border: light-dark(#bccbbf, #435c4c);
    --gridui-neutral-link: var(--gridui-neutral-foreground);
    --gridui-neutral-accent-background: var(--gridui-neutral-foreground);
    --gridui-neutral-accent-foreground: var(--gridui-neutral-background);
    --gridui-neutral-surface: light-dark(#e8ede4, #25372d);
}

The built-in neutral source defaults retain the existing document colors. Existing root semantic overrides continue to style the document, but applications must register their --gridui-neutral-* source colors before using explicit neutral resets; those resets cannot infer an application's earlier overrides. For neutral registration, link defaults to the scope's active accent background when --gridui-neutral-link is omitted; locally registering only a neutral accent therefore also updates its derived link and focus colors.

Brand, warning, and danger retain their existing --gridui-<palette>-* source roles and default aliases for compatibility with direct token consumers. Their base source roles are independent: locally overriding a foreground does not rewrite an inherited link or accent source that already has a configured value. Supply the matching source roles when customizing those existing palettes. The scope still resolves all interaction-derived outputs against the resulting local base palette; it does not infer application color choices.

Every scope remaps background, foreground, muted, border, link, and accent colors, then resolves control borders, focus, surfaces, selection tint, and decoration at that same element. These outputs do not reuse an ancestor's already-computed interaction colors. Hover outlines derive from that local focus color; disabled and selected controls keep consuming the same local semantic tokens. Optional source overrides are control-border, focus-color, surface-hover, selection-tint, and decoration, alongside surface, under the chosen --gridui-<palette>- prefix. The selection source maps to the existing --gridui-brand-tint semantic output. Neutral also provides source defaults for surface and decoration; non-neutral choices retain their existing derived Grid tone formulas when these overrides are omitted.

Grid frame tones reuse this Theme owner. Their existing tone="neutral" means inheritance, preserving existing nested-frame behavior; an explicit reset is a separate paletteClass("neutral") on the caller's native content surface. Grid continues to own seams and region geometry.

Palette inheritance follows the DOM. A portal mounted outside the scoped surface uses its actual DOM host's palette. Supply an appropriate public portal container or apply the scope class to a caller-owned host when local overlay colors are required; Theme does not add application state or portal wrappers.

Sticky application chrome uses --gridui-z-sticky (4), above content, structural boundaries and interaction outlines, and below overlay and modal layers. All component stacking levels come from Theme tokens.

See the repository README for CSS setup, supported environments, development, and release requirements.

See quarterly release history for prepared release notes and consumption records.