Colors & palette

Colors are the values; the palette gives them roles, with a dark value where one differs, and components name the role.

Full spectrum of generated color scales. Click any swatch to adjust the global theme variable.
Usage example: background: color(blue.500)

Interactive Playground

Background FamilyBackground ShadeText FamilyText Shade

Live Color Preview

ColorUsage.uxdsl

.my-element {
  background-color: color(blue.600);
  color: color(gray.50);
}

Every color of the collection; click a swatch to change it

blue

indigo

purple

pink

red

orange

yellow

green

teal

cyan

gray

Live Palette Preview

.my-element{

background:palette(primary-main);

color:palette(primary-contrast);

}

Token-Aware Colors: Use palette() to access semantic colors (primary, success, surface) and their variants (main, light, dark).

Theme uxdsl.theme.json, merged over the base theme

{
  "colors": {
    "blue": {
      "500": "#3b82f6",
      "700": "#1d4ed8"
    }
  },
  "palette": {
    "primary": {
      "main": "color(blue.700)",
      "contrast": "color(white)"
    }
  },
  "modes": {
    "dark": {
      "palette": {
        "primary": {
          "main": "color(blue.500)",
          "contrast": "color(black)"
        }
      }
    }
  }
}

UXDSL you write example.uxdsl

.cta {
  background: palette(primary.main);
  color: palette(primary.contrast);
}
.swatch { background: color(blue.700); }
.scrim { background: color(black, 0.5); }

CSS you get compiled by uxdsl; :root shows only these tokens

:root {
  --uxdsl__palette__primary-main: var(--uxdsl__color__blue-700);
  --uxdsl__palette__primary-contrast: var(--uxdsl__color__white);
  --uxdsl__color__blue-500: #3b82f6;
  --uxdsl__color__blue-700: #1d4ed8;
}
@media (prefers-color-scheme: dark) {
  :root:not([data-theme='light']) {
    --uxdsl__palette__primary-main: var(--uxdsl__color__blue-500);
    --uxdsl__palette__primary-contrast: var(--uxdsl__color__black);
  }
}
:root[data-theme='dark'] {
  --uxdsl__palette__primary-main: var(--uxdsl__color__blue-500);
  --uxdsl__palette__primary-contrast: var(--uxdsl__color__black);
}
.cta {
  background: var(--uxdsl__palette__primary-main);
  color: var(--uxdsl__palette__primary-contrast);
}
.swatch { background: var(--uxdsl__color__blue-700); }
.scrim { background: color-mix(in srgb, var(--uxdsl__color__black) 50%, transparent); }

Rules

Colors are values; the palette gives them roles. colors holds families of shades (gray.50 … gray.950) and single names; palette holds roles (primary, surface, text, …), each with variants (main, light, dark, contrast, …).
In a component, name a role: palette(primary.main). Name a color only for a color identity — a swatch, a brand mark. palette(primary) means palette(primary.main).
A palette value references a color ("main": "color(blue.700)") and follows it; a copied hex does not. A shade number is a key, not a lightness; contrast is the foreground the theme assigns, not a guarantee — the contrast gate checks it.
Dark mode is modes.dark.palette: only the keys that change. The compiled CSS applies them under prefers-color-scheme: dark and under data-theme="dark"; components never know which mode is active.
An alpha is the second argument, 0 to 1: palette(primary.main, 0.1) compiles to color-mix(… transparent). The dashed spelling (palette(primary-main)) is UXD_PALETTE_SYNTAX; an unknown variant is UXD_PALETTE_REFERENCE with the variants that exist.
A family is a tone for @ds-surface, @ds-button and @ds-input when it has main, dark and contrast.

.cta { background: palette(primary.main); color: palette(primary.contrast); }
.overlay { background: color(black, 0.5); }
.badge { color: palette(primary.mian); }  /* UXD_PALETTE_REFERENCE: primary has main, light, dark, contrast */

The guides for coding agents are on For AI agents.