theme

Documentation

Overview

Package theme adapts design-system-spec (DSS) documents into UIForge themes.

UIForge components consume a fixed set of semantic CSS custom properties (--uiforge-primary, --uiforge-surface, --uiforge-text-muted, ...) named after DSS's semantic vocabulary. This package generates the binding layer from any DSS document to that contract, so reliant services keep their own brand tokens — and their own CSS variable prefix — while UIForge components stay brand-agnostic. White-labeling is expressed as values bound per page scope, never by renaming UIForge's internal contract.

Index

• func ValidTokenKeys() []string
• func ValidateTokens(tokens map[string]string) []string
• type Mode
• type Options
• type Theme
  • func FromDesignSystem(ds *dss.DesignSystem, opts Options) (*Theme, error)
  • func FromDesignSystemWithModes(ds *dss.DesignSystem, opts Options) (*Theme, *uispec.ThemeRef, error)
  • func (t *Theme) CSS(selector string) string
  • func (t *Theme) CSSWithModes(selector string, modes map[string]map[string]string) string
  • func (t *Theme) ThemeRef(id string, mode Mode) *uispec.ThemeRef

Functions

func ValidTokenKeys

func ValidTokenKeys() []string

ValidTokenKeys returns the token keys UIForge themes may use — the canonical contract defined by uispec.ValidThemeTokenKeys (the DSS semantic vocabulary plus UIForge's non-color category keys).

func ValidateTokens

func ValidateTokens(tokens map[string]string) []string

ValidateTokens reports theme token keys that are not part of the UIForge token contract. Unknown keys are not fatal — renderers emit them verbatim — but components will never read them.

Types

type Mode

type Mode string

Mode selects which per-token color value to use — "light", "dark", or any other mode a DSS document declares (e.g. "high-contrast").

const (
	// ModeDefault uses each token's base value.
	ModeDefault Mode = ""
	// ModeLight prefers the token's light-mode value when one is defined.
	ModeLight Mode = "light"
	// ModeDark prefers the token's dark-mode value when one is defined.
	ModeDark Mode = "dark"
)

type Options

type Options struct {
	// SourcePrefix is the host design system's CSS variable prefix (e.g.
	// "--plexus"). When set, generated values reference the host's own
	// variables — var(--plexus-cyan, #06b6d4) — so the host stylesheet stays
	// authoritative and the brand can restyle at runtime. When empty, raw
	// token values are emitted. The source prefix follows the DSS output
	// mapping convention: colors as --{prefix}-{id}, fonts as
	// --{prefix}-font-{id}, radii as --{prefix}-radius-{id}.
	SourcePrefix string

	// Mode selects which mode's per-token value to use — any mode the DSS
	// document declares. Tokens without a value for the selected mode fall
	// back to their base value.
	Mode Mode

	// Density selects the page's default density ID — any key present in
	// the DSS document's Foundations.Densities (e.g. "comfortable",
	// "compact", or a document-specific name). It's copied through to the
	// generated ThemeRef.Density; FromDesignSystemWithModes resolves every
	// declared density's scale into ThemeRef.Densities regardless of this
	// selection, so renderers can switch among them at runtime.
	Density string
}

Options configures theme generation.

type Theme

type Theme struct {
	// Tokens maps UIForge token keys (DSS semantics such as "primary",
	// "surface", "text-muted", plus "font-family" and "radius") to CSS
	// values or var() references.
	Tokens map[string]string
}

Theme is a resolved set of UIForge token bindings.

func FromDesignSystem

func FromDesignSystem(ds *dss.DesignSystem, opts Options) (*Theme, error)

FromDesignSystem builds a UIForge theme from a DSS document.

Colors are keyed by their declared semantic (first token per semantic wins). The first font family (preferring id "sans") becomes "font-family"; the "md" border radius (or the first defined) becomes "radius".

func FromDesignSystemWithModes

func FromDesignSystemWithModes(ds *dss.DesignSystem, opts Options) (*Theme, *uispec.ThemeRef, error)

FromDesignSystemWithModes builds a theme whose base tokens use each token's default value and whose Modes overlays carry the per-mode values that differ from the base — enabling runtime mode switching without regenerating the theme. Overlays are generated for every mode the DSS document declares (declaredModes), so a document with a "high-contrast" mode produces a "high-contrast" overlay alongside light/dark.

It also resolves every density the document declares (Foundations. Densities) into ref.Densities, keyed by ID, and copies opts.Density through as ref.Density — renderers look up ref.Densities[ref.Density] for the --uiforge-density scale factor, so no DSS access is needed at render time.

func (*Theme) CSS

func (t *Theme) CSS(selector string) string

CSS renders the theme as a stylesheet block that binds UIForge's semantic custom properties under the given selector (e.g. ":root" or a host element selector for scoped, multi-tenant embedding). Output is sorted for deterministic generation.

func (*Theme) CSSWithModes

func (t *Theme) CSSWithModes(selector string, modes map[string]map[string]string) string

CSSWithModes renders the base tokens under the selector plus one override block per mode, keyed by the data-uiforge-mode attribute the renderers set:

selector { --uiforge-...: base }
selector[data-uiforge-mode="dark"] { --uiforge-...: overlay }

func (*Theme) ThemeRef

func (t *Theme) ThemeRef(id string, mode Mode) *uispec.ThemeRef

ThemeRef converts the theme into a uispec.ThemeRef for embedding directly in a PageSpec. The renderers apply each token as --uiforge-<key> on the page root, which scopes the brand to that page instance.