Theme

The families

A theme is a partial override of the base theme that ships in the package (uxdsl/theme/base.json): write only what you change. These are every family the schema knows, with the keys the base theme defines.

Where the theme comes from

uxdsl.theme.json next to uxdsl.config.cjs (or in the working directory) — or uxdsl.theme.js / .cjs exporting the theme object when it is computed. The CLI, the PostCSS plugin, the Vite plugin and the Webpack loader discover the same file; a theme option passed to one of them wins. Point $schema at the packaged schema and an editor validates and completes it:

{
  "$schema": "./node_modules/uxdsl/schema/theme.schema.json",
  "breakpoints": { "md": 800 },
  "palette": { "primary": { "main": "color(green.700)" } }
}

How an override merges

Objects merge key by key; a string — a responsive expression included — replaces the whole value. This override and the result deepMergeTheme gave when this page was built:

{
  "palette": {
    "primary": {
      "main": "color(green.700)"
    }
  },
  "spacing": {
    "4": "0.875rem"
  }
}

palette.primary → {"main":"color(green.700)","light":"color(purple.500)","dark":"color(purple.900)","contrast":"color(white)"}
spacing["4"]   → "0.875rem"   spacing["5"] → "1rem"

uxdsl theme prints the effective theme and uxdsl theme --diff labels every leaf project or default (Tooling).

Values

Every leaf is a nonempty string (a breakpoint width is a number), written in one grammar on every path:

• a literal CSS value: "0.75rem", "0 1px 2px rgba(0, 0, 0, 0.1)";
• a token function: space(4), color(gray.300), palette(surface.light), radius(2), border(1), shadow(2);
• a responsive expression over the theme’s breakpoints, xs(space(4)) md(space(5)) — not in spacing, colors, palette or fonts.families;
• var(--…) as the escape hatch.

validateTheme (uxdsl/theme) is the one validator: the plugin, the CLI, generateThemeCss and applyTheme all call it, and nothing is coerced. A number where a string belongs, as this page’s build found:

UXD_THEME_INVALID breakpoints.md: UXD_THEME_INVALID: Expected a finite number of pixels, got a string (at breakpoints.md).
UXD_THEME_INVALID spacing.4: UXD_THEME_INVALID: Expected a nonempty string, got number 12 (at spacing.4).

Dark mode

modes.dark.palette redefines palette values for dark mode, and nothing else has a dark variant. The compiled CSS applies them under prefers-color-scheme: dark unless <html data-theme="light">, and always under data-theme="dark". Components keep naming palette(…); a switch only sets the attribute:

document.documentElement.setAttribute('data-theme', 'dark')   // or 'light'; remove it to follow the OS

The compiled ladder is on Colors & palette; a dark key you omit keeps its light value.

Fonts

fonts.google lists Google Fonts families; the compiled stylesheet and generateThemeCss lead with their @import, before every other rule. The base theme’s, encoded by googleFontsImportUrls:

https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap

{ "fonts": { "google": [] } } opts out: no import, and no request to Google. fonts.families names the stacks (--uxdsl__font__ui, --uxdsl__font__code).

The active theme, as JSON

The theme this site is showing. Edit it and the page follows through applyTheme; a change of structure is refused. Nothing is saved to a file.