A UXDSL error names a UXD_* code, the file, line and column, and shows the line. The code is stable and searchable; the message says what exists instead (the configured breakpoints, the available preset keys, a close name). Nothing falls back silently: an unknown breakpoint, preset, role or reference stops the build.
These are captured by scripts/capture-capabilities.js, which also fails when a case stops producing the code it is listed under — so a change to a diagnostic cannot leave this page showing the old one. The runtime reports its own codes on a result instead of throwing: UXD_THEME_NOT_INITIALIZED and UXD_THEME_STRUCTURE are produced live by the sandbox on the Runtime page.
UXD_BREAKPOINT_UNKNOWN — A breakpoint the theme does not configuresrc/example.uxdsl
.hero {
padding: xs(1rem) xxl(2rem);
}$ uxdsl build --entry src/example.uxdsl --out dist/example.css
[uxdsl] Error: postcss-uxdsl: src/example.uxdsl:2:3: UXD_BREAKPOINT_UNKNOWN: xxl(...) is not a configured breakpoint or a known CSS function; configured breakpoints: xs, sm, md, lg, xl.
1 | .hero {
> 2 | padding: xs(1rem) xxl(2rem);
| ^
3 | }
4 |UXD_SHADOW_REFERENCE — A shadow preset that does not existsrc/example.uxdsl
.card {
box-shadow: shadow(9);
}$ uxdsl build --entry src/example.uxdsl --out dist/example.css
[uxdsl] Error: postcss-uxdsl: src/example.uxdsl:2:15: UXD_SHADOW_REFERENCE: shadow(9) does not exist; available keys: 0–5.
1 | .card {
> 2 | box-shadow: shadow(9);
| ^
3 | }
4 |UXD_EDGE_REFERENCE — A radius preset that does not existsrc/example.uxdsl
.card {
border-radius: radius(12);
}$ uxdsl build --entry src/example.uxdsl --out dist/example.css
[uxdsl] Error: postcss-uxdsl: src/example.uxdsl:2:18: UXD_EDGE_REFERENCE: radius(12) does not exist; available keys: 0–5, circle, full, pill.
1 | .card {
> 2 | border-radius: radius(12);
| ^
3 | }
4 |UXD_DENSITY_REFERENCE — A fractional Density referencesrc/example.uxdsl
.card {
padding: density(2.5);
}$ uxdsl build --entry src/example.uxdsl --out dist/example.css
[uxdsl] Error: postcss-uxdsl: src/example.uxdsl:2:12: UXD_DENSITY_REFERENCE: density(2.5) does not exist; available keys: 0–15. Did you mean "2"?
1 | .card {
> 2 | padding: density(2.5);
| ^
3 | }
4 |UXD_TYPO_REFERENCE — A typography role the theme does not definesrc/example.uxdsl
.title {
@ds-typo(hero);
}$ uxdsl build --entry src/example.uxdsl --out dist/example.css
[uxdsl] Error: postcss-uxdsl: src/example.uxdsl:2:3: UXD_TYPO_REFERENCE: ds-typo(hero) does not exist; available keys: body, body-sm, caption, code, default, h1, h2, h3, h4, h5, h6, p, pre, small, span, subtitle2, tag.
1 | .title {
> 2 | @ds-typo(hero);
| ^
3 | }
4 |UXD_SURFACE_REFERENCE — A Surface role that does not existsrc/example.uxdsl
.panel {
@ds-surface(glass);
}$ uxdsl build --entry src/example.uxdsl --out dist/example.css
[uxdsl] Error: postcss-uxdsl: src/example.uxdsl:2:3: UXD_SURFACE_REFERENCE: Undefined surface or palette family glass.
1 | .panel {
> 2 | @ds-surface(glass);
| ^
3 | }
4 |UXD_DIRECTIVE_CONTEXT — A directive outside the rule it stylessrc/example.uxdsl
@media (min-width: 768px) {
@ds-surface(contained);
}$ uxdsl build --entry src/example.uxdsl --out dist/example.css
[uxdsl] Error: postcss-uxdsl: src/example.uxdsl:2:3: UXD_DIRECTIVE_CONTEXT: Directives apply to a whole rule and are not responsive; use responsive values on the properties instead, e.g. padding: xs(…) md(…).
1 | @media (min-width: 768px) {
> 2 | @ds-surface(contained);
| ^
3 | }
4 |UXD_DIRECTIVE_UNKNOWN — A directive UXDSL does not havesrc/example.uxdsl
.card {
@ds-card(contained);
}$ uxdsl build --entry src/example.uxdsl --out dist/example.css
[uxdsl] Error: postcss-uxdsl: src/example.uxdsl:2:3: UXD_DIRECTIVE_UNKNOWN: Unknown directive @ds-card.
1 | .card {
> 2 | @ds-card(contained);
| ^
3 | }
4 |UXD_TOKEN_ALPHA — An alpha outside 0–1src/example.uxdsl
.overlay {
background: palette(primary-main, 2);
}$ uxdsl build --entry src/example.uxdsl --out dist/example.css
[uxdsl] Error: postcss-uxdsl: src/example.uxdsl:2:3: UXD_TOKEN_ALPHA: Expected a number between 0 and 1.
1 | .overlay {
> 2 | background: palette(primary-main, 2);
| ^
3 | }
4 |UXD_TYPO_BP — A negative breakpoint in the theme (reported by the first engine that validates the map: Typography)uxdsl.theme.json
{
"breakpoints": {
"xs": 0,
"sm": 480,
"md": -1,
"lg": 1024,
"xl": 1280
}
}src/example.uxdsl
.a {
padding: space(3);
}$ uxdsl build --entry src/example.uxdsl --out dist/example.css
[uxdsl] Error: uxdsl.theme.json: UXD_TYPO_BP: Typography requires distinct non-negative breakpoint widths and a zero-width base (at breakpoints).UXD_TYPO_FIELD — A typography field the engine does not supportuxdsl.theme.json
{
"typography_details": {
"h1": {
"opacity": "0.8"
}
}
}src/example.uxdsl
.a {
padding: space(3);
}$ uxdsl build --entry src/example.uxdsl --out dist/example.css
[uxdsl] Error: uxdsl.theme.json: UXD_TYPO_FIELD: Invalid h1.opacity (at typography_details.h1.opacity).UXD_REFERENCE_MISSING — A theme value pointing at a token that does not existuxdsl.theme.json
{
"palette": {
"primary": {
"main": "var(--uxdsl__color__brand-500)"
}
}
}src/example.uxdsl
.a {
color: palette(primary-main);
}$ uxdsl build --entry src/example.uxdsl --out dist/example.css
[uxdsl] Error: src/example.uxdsl:2:3: UXD_REFERENCE_MISSING: color -> --uxdsl__palette__primary-main -> --uxdsl__color__brand-500 has no definition in the active theme/scope. Define it or declare its external provider.
UXD_REFERENCE_MISSING: --uxdsl__palette__primary-main -> --uxdsl__color__brand-500 has no definition in the active theme/scope. Define it or declare its external provider.
UXD_REFERENCE_MISSING: --uxdsl__button__outlined-selected-bg -> --uxdsl__palette__primary-main -> --uxdsl__color__brand-500 has no definition in the active theme/scope. Define it or declare its external provider.
UXD_REFERENCE_MISSING: --uxdsl__button__outlined-selected-border -> --uxdsl__palette__primary-main -> --uxdsl__color__brand-500 has no definition in the active theme/scope. Define it or declare its external provider.
UXD_REFERENCE_MISSING: --uxdsl__button__outlined-tone-primary-selected-bg -> --uxdsl__palette__primary-main -> --uxdsl__color__brand-500 has no definition in the active theme/scope. Define it or declare its external provider.
UXD_REFERENCE_MISSING: --uxdsl__button__outlined-tone-primary-selected-border -> --uxdsl__palette__primary-main -> --uxdsl__color__brand-500 has no definition in the active theme/scope. Define it or declare its external provider.
UXD_REFERENCE_MISSING: --uxdsl__input__contained-base-caret -> --uxdsl__palette__primary-main -> --uxdsl__color__brand-500 has no definition in the active theme/scope. Define it or declare its external provider.
UXD_REFERENCE_MISSING: --uxdsl__input__contained-tone-primary-base-caret -> --uxdsl__palette__primary-main -> --uxdsl__color__brand-500 has no definition in the active theme/scope. Define it or declare its external provider.
UXD_REFERENCE_MISSING: --uxdsl__input__contained-focus-border -> --uxdsl__palette__primary-main -> --uxdsl__color__brand-500 has no definition in the active theme/scope. Define it or declare its external provider.
UXD_REFERENCE_MISSING: --uxdsl__input__contained-tone-primary-focus-border -> --uxdsl__palette__primary-main -> --uxdsl__color__brand-500 has no definition in the active theme/scope. Define it or declare its external provider.
UXD_REFERENCE_MISSING: --uxdsl__input__outlined-base-caret -> --uxdsl__palette__primary-main -> --uxdsl__color__brand-500 has no definition in the active theme/scope. Define it or declare its external provider.
UXD_REFERENCE_MISSING: --uxdsl__input__outlined-tone-primary-base-caret -> --uxdsl__palette__primary-main -> --uxdsl__color__brand-500 has no definition in the active theme/scope. Define it or declare its external provider.
UXD_REFERENCE_MISSING: --uxdsl__input__outlined-focus-border -> --uxdsl__palette__primary-main -> --uxdsl__color__brand-500 has no definition in the active theme/scope. Define it or declare its external provider.
UXD_REFERENCE_MISSING: --uxdsl__input__outlined-tone-primary-focus-border -> --uxdsl__palette__primary-main -> --uxdsl__color__brand-500 has no definition in the active theme/scope. Define it or declare its external provider.
UXD_REFERENCE_MISSING: --uxdsl__input__underline-base-caret -> --uxdsl__palette__primary-main -> --uxdsl__color__brand-500 has no definition in the active theme/scope. Define it or declare its external provider.
UXD_REFERENCE_MISSING: --uxdsl__input__underline-tone-primary-base-caret -> --uxdsl__palette__primary-main -> --uxdsl__color__brand-500 has no definition in the active theme/scope. Define it or declare its external provider.
UXD_REFERENCE_MISSING: --uxdsl__input__underline-focus-underline -> --uxdsl__palette__primary-main -> --uxdsl__color__brand-500 has no definition in the active theme/scope. Define it or declare its external provider.
UXD_REFERENCE_MISSING: --uxdsl__input__underline-tone-primary-focus-underline -> --uxdsl__palette__primary-main -> --uxdsl__color__brand-500 has no definition in the active theme/scope. Define it or declare its external provider.elevation() and rounded()Two aliases the language accepts: elevation(n) is shadow(n) and rounded(n) is radius(n). An alias does not change stacking order or add a scale — it is the same reference under another name. Compiled both ways, and measured in this page's own stylesheet:
.with-alias {
box-shadow: elevation(2);
border-radius: rounded(2);
}
.with-name {
box-shadow: shadow(2);
border-radius: radius(2);
}$ uxdsl build --entry src/aliases.uxdsl --out dist/aliases.css --no-include-theme
.with-alias {
box-shadow: var(--uxdsl__shadow__2);
border-radius: var(--uxdsl__radius__2);
}
.with-name {
box-shadow: var(--uxdsl__shadow__2);
border-radius: var(--uxdsl__radius__2);
}elevation(2) · rounded(2)shadow(2) · radius(2)Measuring…