Introduction

The idea in one paragraph

Design decisions — spacing, type, color, borders, shadows, and how each of them changes at a breakpoint — live once, in a theme JSON. Components name them (density(4), palette(primary.main), @ds-button(contained)) and never write a breakpoint. The compiler turns that into ordinary CSS, refuses to emit anything it cannot resolve, and the same JSON is applied in the browser at run time and audited from the command line.

density(4) is written once. The theme says it is space(4) on a phone, space(5) from md and space(6) from xl; the compiler writes that ladder once, as custom properties in :root and min-width media queries, and the card reads var(--uxdsl__density__4). Change the theme line and every component that names density(4) follows, with no component edited. The gap shows the other half: a component can still say what changes at a breakpoint, by naming the theme's breakpoints instead of writing pixel widths.

What UXDSL is

• CSS with a few additions. A .uxdsl file is CSS, native nesting included, plus value functions (space(), density(), color(), palette(), radius(), border(), shadow(), and one per breakpoint, xs() … xl()), four directives (@ds-surface, @ds-button, @ds-input, @ds-typo) and a documented SCSS-style subset ($variables, @if/@else, @each over a list, @for, @mixin/@include, @content, @import). The Language page has the whole grammar.
• A compiler with one pipeline. The CLI (uxdsl build), the PostCSS plugin (uxdsl/postcss), the Vite plugin and the Webpack loader all run the same compile(). The output is plain CSS: custom properties and min-width media queries, nothing at run time.
• One theme model. One JSON, validated against one schema and merged over a reviewed base theme. The same file is compiled, applied in the browser with applyTheme, and audited with uxdsl theme --diff and uxdsl theme --contrast.
• Validated. Every reference is checked at build time. An unknown token, breakpoint, role or a misplaced directive is a UXD_* error with file, line, column and a suggestion — never a silent fallback. See Diagnostics.

What UXDSL is not

• Not Sass. It compiles the subset listed above; any other Sass feature fails with UXD_SCSS_UNSUPPORTED naming what to write instead.
• Not free of media queries. The output is media queries; you stop writing them in components. They are viewport min-width queries: there are no container queries — use native @container next to UXDSL.
• Not typed. The theme has a JSON Schema and every reference is checked at build time; the CSS itself is not type-checked.
• Not fluid. Values step at breakpoints. The base theme has no clamp() scales (a clamp() is still a valid literal value).
• Not a runtime styling library. Nothing needs JavaScript at run time. The optional runtime changes token values without a rebuild; a structural change — a new typography field, a new state, a moved threshold — is refused with UXD_THEME_STRUCTURE instead of half-applied.

Is it worth it?

"It is CSS variables plus media queries; I can write that." Yes — that is literally the output. UXDSL generates and checks that ladder from one definition per token, keeps the definitions in JSON so that the build, the runtime, the contrast audit and coding agents read the same thing, and turns a var() that would resolve to nothing into a build error. With five tokens, write it by hand.

Compared with

Not promised in 1.0

Container queries, fluid clamp() scales, DTCG import and export, modes other than dark, and editor completion of a project's own theme are recorded as possible additions. None is promised.