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 ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
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 ¶
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").
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 ¶
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 ¶
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 }
Source Files