Language

It is CSS

Anything that is not one of the constructs below passes through unchanged: selectors, properties, calc(),@media, @container, @layer, and native nesting (&:hover,.a { .b { } }), which is forwarded to the browser as written, not flattened. Names are case-insensitive (Space(1) compiles like space(1)). Every reference is checked against the effective theme when it is rewritten; an unknown one stops the build with a UXD_* code and a suggestion.

Token functions

Exactly one argument each — a key of the theme — plus an optional alpha on palette() and color(). They work in a declaration and inside a theme value.

.panel {
  padding: density(4);
  border: border(1);
  border-radius: radius(2);
  background: palette(surface.main);
  box-shadow: shadow(2);
}
.panel { border: border(1, red); }  /* UXD_EDGE_ARGUMENT: one argument; write the longhands after it */
.panel { color: palette(primary-main); }  /* UXD_PALETTE_SYNTAX: the one spelling is palette(primary.main) */

Responsive values

One function per breakpoint of the theme — xs() (from 0px), sm() (from 480px), md() (from 768px), lg() (from 1024px), xl() (from 1280px) with the base theme — wraps the value that applies from that width up. They compile to min-width media queries of the viewport; a theme that adds a breakpoint adds its function.

.layout {
  flex-direction: xs(column) md(row);
  padding: xs(1rem) xl(2rem) !important;
}
.hero { padding: md(2rem); }

• A value applies until a later breakpoint overrides it: md(row) still applies at xl.
• A lone group may start at any breakpoint (md(2rem) is “from md up”). When a value has other parts next to a group, every group needs a base, so the value has the same number of parts at every width.
• !important goes after the groups and applies at every breakpoint.
• A responsive value cannot nest in calc(), in another breakpoint, or under @keyframes, @font-face or @page; write the whole value per breakpoint, or put it on a custom property outside.

.a { padding: xs(1rem) xxl(2rem); }  /* UXD_BREAKPOINT_UNKNOWN: xxl is not a breakpoint of the theme */
.a { width: calc(100% - xs(1rem) md(2rem)); }  /* UXD_BREAKPOINT_CONTEXT: write xs(calc(100% - 1rem)) md(calc(100% - 2rem)) */
.a { padding: xs(1px !important) md(2px); }  /* UXD_BREAKPOINT_IMPORTANT: write xs(1px) md(2px) !important */
.a { padding: xs(); }  /* UXD_BREAKPOINT_EMPTY */

Directives

A directive applies a role from the theme to the rule it is written in. It must be a direct child of that rule — at the root of a file, or inside @media under the rule, it is UXD_DIRECTIVE_CONTEXT — and it is not itself responsive: put a responsive value on a property instead. Arguments are separated by spaces, the role first; a declaration written after the directive wins over the role’s.

.notice { @ds-surface(outlined info 2); }
.save { @ds-button(contained success); border-radius: radius(pill); }
.cta { @ds-button(contained); @ds-button(outlined); }  /* UXD_DIRECTIVE_DUPLICATE: one control directive per rule */
.panel { @ds-surface(glass); }  /* UXD_SURFACE_REFERENCE: the role is not in the theme */

@uxdsl theme;

For a PostCSS-only setup (one plugin configuration for every stylesheet, as in Next.js without the CLI): written once, at the top level of the one global stylesheet, it is where the theme’s :root is emitted. The plugin then runs with includeTheme: false everywhere else. A misspelled, repeated or nested marker is UXD_THEME_MARKER. See the quick start.

The SCSS-style subset

The CLI, the Vite plugin and the Webpack loader read .uxdsl with this subset of Sass, and only this. The standalone PostCSS plugin reads plain CSS with $variables at the root of a file.

Anything else Sass has fails with a located error naming what to write instead: @extend, @use,@function, Sass color and math functions and arithmetic outside calc() are UXD_SCSS_UNSUPPORTED;&__item (concatenating the parent selector, which native nesting cannot do) is UXD_NESTING_INVALID.

$tones: primary, success;
@mixin pad($size) { padding: $size; }
@each $tone in $tones {
  .tag--#{$tone} { @ds-surface(contained #{$tone}); @include pad(density(2)); }
}

Errors the language can raise

Read from DIAGNOSTIC_CATALOG; what to do about each one is on Diagnostics.