UXDSL Monorepo

UXDSL is a design-system-oriented CSS dialect with compiler + runtime tooling.

One package: uxdsl (next release: 0.5.0-beta.9)

npm i -D uxdsl
npx uxdsl init
npx uxdsl build

The compiler, the CLI, the Vite plugin, the Webpack loader and the browser theme runtime are one package, uxdsl, with one entry point per job: uxdsl (compile()), uxdsl/postcss, uxdsl/vite, uxdsl/webpack, uxdsl/runtime, uxdsl/theme, uxdsl/language, uxdsl/config and uxdsl/engine (tooling, exempt from semver). It ships in 0.5.0-beta.9, its first release under that name. 0.5.0-beta.8 (2026-10-08, record) was the last release published as five packages; no 0.5.0-beta.7 was ever published. The old → new import table is in the CHANGELOG; the five former names are deprecated in favour of uxdsl (release record and publish steps). npm run verify:1.0 is the release gate: one tarball, installed the documented way, plus real Vite, Webpack, Next.js and Chrome runs.

The project: stability policy · roadmap · release records · what is in docs/ · report a bug, ask a question or suggest an idea.

The release notes below describe what was published at the time, under the package names of the time.

0.5.0-beta.6 — published

Published to npm on 2026-09-23, with latest and beta on it; the release record has the registry reads, the checksums and what was verified. FEAT-008 delivered it: one shared compiler behind the CLI, compile(), Vite and Webpack; located diagnostics with UXD_* codes; strict flag parsing; the reviewed base theme shipped as the library default; @ds-typo emitting only what the theme defines; source maps; applyTheme(json) at run time; exported types, defineConfig and a generated theme JSON Schema; and reference validation that no longer grows quadratically (24,000 lines: 63.3 s → 0.79 s).

npm run verify:beta6 ran the release gate against real tarballs (replaced by verify:1.0). Its automated portion passed; as of 2026-09-28, external validation against a real consumer project is still pending and is listed, with the known limitations, in the release record. The most important of those — the packaged base theme not passing its own contrast gate (123 failing pairs as of 2026-09-28) — is closed by stability phase 5 (unreleased): checkThemeContrast on packages/uxdsl/src/theme/base.json with the shipped base.contrast-exceptions.json now reports passed: true — 1004 pairs checked, 0 failing, 111 excepted (the canvas-identity families surface, light and dark used as a tone and drawn on the page, covered by three pattern exceptions and still listed pair by pair, never counted as passing); uxdsl theme --contrast in a zero-config project exits 0 and prints the same report. What came next was planned in FEAT-009 and shipped as 0.5.0-beta.8.

0.5.0-beta.5 — published

npm install -D uxdsl-cli@beta postcss-uxdsl@beta
npx uxdsl init
npm run uxdsl:build

Import src/uxdsl.css once (from src/app/layout.tsx: import '../uxdsl.css'). Run npm run uxdsl:watch alongside the app's development server. After adding or removing .uxdsl files, run npx uxdsl generate-entry. See postcss-uxdsl's README for a 60-second tour of the syntax itself — responsive values, palette tokens, density, buttons, and live theming with no rebuild.

FEAT-006, based on a real consumer's CI report: --strict-theme (on build and theme alike) takes a family scope (--strict-theme=palette,breakpoints, or strictTheme: ['palette', 'breakpoints']), fixing a false positive where the unscoped check flagged any documented partial theme override — not just in typography_details, but in the zero-config palette example this project's own README uses — as "incomplete". Since the stability plan's phase 2 the scope is required: the bare flag is refused with the scoped form spelled out. validateTheme's top-level "Unknown theme family" warning also actually prints from a real uxdsl build/watch for the first time; previously only the playground's theme editor called that function. Entirely additive — no migration steps needed from beta.4. (beta.5 also shipped a parallel warning one level deeper, for entry names inside typography_details/palette/fonts.families; MIG-B6-01 of FEAT-007 removed it as a false positive — those three families are open registries.)

See the migration recipe and the published release record. npm run verify:beta5 installed all five packages from fresh tarballs and exercised the full scenario end to end, as verify:beta4/verify:beta3/verify:beta2 did for theirs; verify:1.0 now runs every one of those checks against the one package.

Previous prereleases are recorded in docs/releases/0.5.0-beta.4.md, docs/releases/0.5.0-beta.3.md and docs/releases/0.5.0-beta.2.md.

FEAT-002 migration verification

The published 0.5.0-beta.1 contract uses --uxdsl__<family>__<key>. Use the shipped uxdsl/scripts/codemod-namespace.js in preview mode before migrating selected consumer CSS/JSON; explicit mappings protect host tokens and handle custom typography roles. See the migration guide. The beta.1 release is recorded in docs/releases/0.5.0-beta.1.md. Follow-up installation hardening is tracked in FEAT-003.

The five npm packages were published as 0.5.0-beta.1 with coordinated internal dependencies. Both latest and beta pointed to that release at the time. Their current tags are recorded in docs/releases/0.5.0-beta.8.md (npm view <package> dist-tags). The release script accepts beta versions and updates the CLI's actual dependency on postcss-uxdsl.

VS Code now suggests radius(key) and shadow(key) inside Surface, Button and Input directives using generated shared-language metadata. That comes from the uxdsl-vscode extension, which is not yet published on the VS Code Marketplace or Open VSX (its packaging is on the roadmap): it is installed from a .vsix built from packages/uxdsl-vscode. How to install it, and the typed config and theme $schema that work without it, are in uxdsl-cli's "Editor support". CLI consumers must use the same theme overrides across integrations and regenerate their CSS when adopting the namespace; no automatic legacy aliases are provided.

npm test includes reference-integrity, migration and cascade regressions. npm run verify:cssmodules-build builds and installs the compiler tarball, checks a real Next.js strict CSS Modules build with a negative control, and verifies Chrome computed styles in light/dark at responsive boundaries. Set UXDSL_CHROME_PATH for non-default Chrome locations.

AI agent guide

Read AGENTS.md for UXDSL responsibilities, configuration examples, change-scope rules and verification scenarios. It also explains how to reuse the guide in a consuming project; npm installation alone does not load agent instructions. Keep this guide aligned when changing primitive behavior or AI documentation.

Shared Borders and Radii engine

packages/uxdsl/src/edges.ts owns Border/Radius defaults, token conversion, responsive rules, CSS generation and viewport inspection. PostCSS, runtime generateThemeCss, and the Borders preview consume it. Configure borders and radii in the theme JSON; values may be literal CSS or responsive expressions. The built-in presets are uxdsl/theme/base.json's; the theme JSON is the only source of a preset (a @theme block is UXD_THEME_BLOCK_REMOVED since stability phase 3).

The language has one spelling per construct (stability phase 3): border(k), radius(k), shadow(k), space(k) and density(k) take exactly one argument, a Palette or Color entry is palette(family.variant)/color(family.shade), and a directive is @ds-x(role [tone] [size] [radius(k)] [shadow(k)]); every other spelling is a located UXD_* error naming the grammar, and uxdsl/scripts/codemod-canonical-grammar.js rewrites the removed ones. See the uxdsl README, "The canonical grammar".

Migration notes for 0.5.0-beta.1 (not included in npm 0.4.0):

• JSON entries win over shared defaults.
• Components now consume CSS variables, so runtime theme replacement updates their presets and local longhand overrides persist across breakpoints.
• Borders/Radii definitions no longer leak across independent compilations. Include legacy definitions in each build that requires them.
• Undefined references fail instead of producing implicit fallback ramps. Define custom tokens explicitly; radius-0 is the explicit square-corner preset.
• Existing preset color/style arguments retain their legacy behavior (ignored). Use subsequent CSS longhands for deliberate local overrides.
• Validation covers definitions, references at consumption and responsive bases; it is not a complete CSS or accessibility validator.

Run npm test for shared-engine and integration contracts. The documentation at /docs/borders explains JSON, legacy input, runtime behavior and agent guidance.

Shared Shadows engine

src/shadows.ts owns Shadow defaults, generation and inspection. Its responsive preset compiler is shared with Borders/Radii, while the family-specific APIs stay separate. PostCSS and runtime consume the same shadows JSON map; the demo uses that engine with scoped previews. shadow() preserves CSS variable references, including layered, inset, static and responsive values (the former elevation() alias was removed in stability phase 3).

Since 0.5.0-beta.1, undefined Shadow references are errors, shadow-0 is explicitly none, and the previous cross-compilation Shadow cache and fallback table are removed (the legacy @theme definitions that followed were removed in stability phase 3). These changes are not included in the already published npm 0.4.0 release.

Shared Surfaces engine

src/surfaces.ts owns the six-field container composition, defaults, responsive variable generation, tone/size composition and inspection. PostCSS, runtime and the preview share it. JSON fields override same-compilation legacy pack fields, which override defaults. Custom roles inherit contained defaults for missing fields. Surface definitions no longer leak between compilations. Unknown roles and fields fail explicitly. Built-in contained now has a valid 1px solid border treatment; outlined uses an explicit neutral border rather than ignored helper arguments.

Buttons and inputs reuse Surface base composition; their own states and packs were unified afterwards, in the same release (see "Shared Button engine" and "Shared Input engine" below). Documentation puts the AI implementation guide after the demo. These changes shipped in 0.5.0-beta.1; they are not in 0.4.0.

Feature roadmap

What comes next is in docs/ROADMAP.md. The sections below record how the shared language engine (FEAT-001) was built.

Shared language foundation (in progress)

uxdsl/language owns responsive selection and Density rule generation, and exports the breakpoint and Density defaults (since MIG-B6-29 their values are read from packages/uxdsl/src/theme/base.json). PostCSS, the runtime theme generator and the Density playground delegate to this module. Existing runtime breakpoint exports remain compatible. The module has no DOM or Node built-in dependencies; a production browser bundle remains to be measured.

Run npm test for shared language tests, existing core import tests and generated artifact drift checks. Run npm run generate:language after changing language defaults or completion metadata. This regenerates the default theme .css/.uxdsl files, the theme manifest, the theme JSON Schema, and the VS Code completion data, grammar and CSS custom data (scripts/generate-language-artifacts.js).

When this foundation landed it was not full engine unification: other token families, strict reference validation, process-global compiler caches, full editor schema/diagnostics and browser verification were left to FEAT-001. The sections below and the audit record which of those have since landed. Density-15's former reference to space-17 was reconciled before 0.5.0-beta.1: the shipped Density scale stays within Spacing 1–16.

Density documentation examples

/docs/densities explains Density with a theme JSON excerpt, a breakpoint mapping table, UXDSL alongside equivalent plain CSS, and two live boxes sharing Density 4. A third box uses fixed space(4) for comparison. The Russian Doll compares levels measured from the same content. All live examples follow the browser viewport.

To check locally, start the Next.js playground and resize the browser across the theme breakpoints. Edit the active Density 4 rule and verify both responsive boxes change while the fixed comparison does not. Edits are local to the demo. The JSON and CSS are explicitly labeled reference examples; the live definition reflects edits. The former iframe viewport simulator was removed after reported interaction failures.

AI documentation guidance

Breakpoints documentation reads shared engine defaults for its JSON/table and explains inclusive viewport thresholds, inherited property values and Density dependencies. It preserves the live editor and cards, labels their local spacing exception, and includes an AI guide for local versus shared changes.

Colors and Palette pages use ColorDocumentation for a shared configuration example, UXDSL/CSS equivalents and topic-specific AI scenarios. Colors supply values; Palette assigns roles through explicit references or independent literals. The guides distinguish reference propagation from matching hex values and include checks for modes, shared consumers and foreground/background contrast.

UXDSL builds on standard CSS. Spacing defines the base scale; Density is its responsive layer and the preferred default for component spacing. Direct Spacing is for intentional stable values, and CSS remains available for finer control. SpacingPrinciple shares this guidance across both pages and their AI guides.

Density pages end with DensityAgentGuidance, including token-selection rules, theme and component examples, local-exception guidance and breakpoint verification. AgentGuidance is the shared presentation component: pass a unique id, a title and documentation as children. Keep topic content in a separate component and render it from the page after its examples. The guide is visible in server-rendered HTML and supports direct anchor links without JavaScript or an accordion.

Spacing pages follow the same pattern: SpacingExplanation introduces the theme scale, UXDSL/CSS equivalents, units and the relationship to Density. Live padding and gap examples consume the existing runtime variables. SpacingAgentGuidance ends the page with token-selection rules, local versus shared change examples and verification scenarios. Playground spacing edits persist browser overrides and update its custom theme model; they do not write source JSON files.

Main packages

• packages/uxdsl — the uxdsl package: compiler (PostCSS plugin), compile(), the uxdsl CLI, the Vite plugin, the Webpack loader and the theme runtime.
• packages/uxdsl-vscode — VS Code language support (released separately, as a VSIX).
• packages/_deprecated/* — the last versions of the five former package names, re-exporting uxdsl (prepared, not published).
• packages/playground / packages/playground-nextjs — Demo apps.

Breakpoint source of truth

Breakpoint defaults are defined once, in the breakpoints family of:

• packages/uxdsl/src/theme/base.json

DEFAULT_BREAKPOINTS is derived from it (packages/uxdsl/src/language.ts, exported by uxdsl/theme). Please reuse this shared default map (DEFAULT_BREAKPOINTS) in integrations and demos rather than redefining the values.

Default values:

{ xs: 0, sm: 480, md: 768, lg: 1024, xl: 1280 }

Since stability phase 1 the theme's breakpoints family is the only place a threshold is configured. The PostCSS plugin no longer has a breakpoints option: a value forwarded to it — from a breakpoints key in uxdsl.config.cjs through the CLI or compile(), or from a breakpoints option of uxdsl/vite/uxdsl/webpack — is ignored with a UXD_OPTION_REMOVED warning, and the build compiles against the theme's map. Put the thresholds in the theme ({ "breakpoints": { "md": 800 } } in uxdsl.theme.json, or the adapter's theme option). See the changelog.

Quick start (Next.js playground)

1. Open a terminal in packages/playground-nextjs.
2. Install deps: npm install.
3. Build UXDSL CSS: npm run uxdsl:build.
4. Start app: npm run dev.

Commit policy for npm package updates

To keep npm consumers and viewers informed, commits now enforce a docs update step for publishable packages.

• If code changes are staged under packages/<pkg>/ (non-private npm packages), you must also stage:
  • packages/<pkg>/README.md, or
  • root README.md
• If a file that defines default visual output is staged (listed in scripts/verify-docs-update.js, e.g. packages/uxdsl/src/theme/base.json), you must also stage packages/uxdsl/CHANGELOG.md.

This runs automatically in pre-commit via:

• npm run verify:docs

You can run it manually before committing.

NPM release auto-increment workflow

Before publish commands, ensure npm auth is active:

• npm whoami
• if needed: npm login

If your npm account enforces 2FA for publish, pass OTP when running release:

• NPM_OTP=123456 npm run release:patch
• or node scripts/release.js --bump patch --otp 123456

Use automated semver bumping for all publishable UXDSL packages (publish by default):

• Patch: npm run release:patch
• Minor: npm run release:minor
• Major: npm run release:major

Bump-only variants (no publish):

• Patch: npm run release:patch:bump-only
• Minor: npm run release:minor:bump-only
• Major: npm run release:major:bump-only

You can run these from repo root or from packages/playground-nextjs (proxied scripts are available there too).

You can also include a short tweak note (stored in packages/uxdsl/docs/integrations/compile.md):

• node scripts/release.js --bump patch --note "small parser fix"

Shared Button engine (0.5.0-beta.1)

Button JSON roles (surface, base, states), PostCSS, runtime and the documentation preview now use src/buttons.ts. Custom roles, Palette tones, numeric Density/Radius sizes and responsive state fields share the same implementation. Default packs are generated; cross-build Button caches are removed. Import legacy packs in each compilation. Explicit base fields override Surface composition. Default hover/selected states follow the selected tone; custom Palette assignments remain explicit. Missing/invalid roles and fields fail instead of silently falling back. Existing values update through theme CSS; changing role structure requires regenerating component CSS. See the Buttons docs and AGENTS.md for semantics and migration details.

Shared Input engine (0.5.0-beta.1)

Input JSON roles (surface, base, states), PostCSS, runtime and the preview now share src/inputs.ts. Custom roles, tones, numeric sizes, responsive fields, placeholder and underline treatments use the same engine. Default packs are generated; process-global Input caches and demo state simulations are removed. Import legacy packs in each build. Existing values can update through managed theme CSS; structural changes require regenerated component CSS too.

Migration: all configured base fields now apply; state aliases map to CSS correctly. Default focus/error borders use explicit semantic colors instead of ignored Border arguments. Placeholder/disabled colors use Palette references. Native focus outlines and appearance are preserved; default width remains 100%. Unknown fields and roles fail explicitly. See Inputs docs and AGENTS.md for supported controls and semantics.

Unified engine audit (0.5.0-beta.1)

Whole-theme build/runtime parity and compilation isolation now have regression tests. Density JSON/defaults, foundation variables and modes, token normalization and responsive values are shared; Buttons and Inputs reuse one control engine. The current Density demo uses the shared parser and scoped theme CSS. See the audit for ownership, migration, verification scope and explicit limits, including the historical playground and schema-aware editor work.