Rebuild Assembly in UnoCSS preset and move docs to VitePress

.artifacts.yml

@@ -4,6 +4,6 @@ publisher:
   - filter: on-branch
     name: publisher-branches
     config:
-      node_version: 18.x
+      node_version: 24.x
       site_build_dir: _site
       npm_build_script: build

.eslintrc.json

@@ -2,5 +2,23 @@
   "extends": [
     "@mapbox/eslint-config-mapbox",
     "prettier"
+  ],
+  "rules": {
+    "node/no-unsupported-features/es-syntax": [
+      "error",
+      { "ignores": ["dynamicImport"] }
+    ]
+  },
+  "overrides": [
+    {
+      "files": ["*.mjs", "docs/.vitepress/**/*.js"],
+      "parserOptions": {
+        "ecmaVersion": 2022,
+        "sourceType": "module"
+      },
+      "rules": {
+        "node/no-unsupported-features/es-syntax": "off"
+      }
+    }
   ]
 }

.gitignore

@@ -1,7 +1,6 @@
 node_modules
 *.log
 dist
-_tmp_assembly
-_batfish*
 _site
+docs/.vitepress/cache
 .DS_Store

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 2.0.0
+
+- [breaking] Rebuild Assembly's CSS pipeline on [UnoCSS](https://unocss.dev/). Class names and `buildUserAssets` stay compatible; the generated stylesheet's formatting, comments, and source maps may differ. Node.js 24+ is required.
+- [add] Export `presetAssembly()` for on-demand UnoCSS builds that keep Assembly class names. Pass `{ safelist: true }` only when you want the full prebuilt utility set.
+- [add] `examples/jit` — a sample app that generates only the utilities used in its markup (no reset or component preflight).
+- [internal] Assembly utilities are UnoCSS rules in `src/preset/`. Reset and component CSS live in `src/preset/base.css`. The package build is `src/build-*.js`. The documentation site is VitePress under `docs/`.
+
 ## 1.16.0
 - [add] `ai` icon
 

MIGRATION_GUIDES.md

@@ -1,5 +1,32 @@
 # Migration Guides
 
+## 2.0.0
+
+Version 2.0.0 rebuilds Assembly with [UnoCSS](https://unocss.dev/) while keeping the existing class names and `buildUserAssets` API.
+
+You do not need to change class names in markup. Continue to use `assembly.css` / `assembly.js`, or keep calling `Assembly.buildUserAssets`.
+
+What can change:
+
+- The contents of `assembly.css` are generated by UnoCSS, so whitespace, comments, rule order, and source maps may differ from 1.x. Selectors and declarations for public classes stay the same.
+- Layout-scale media variants (`px12-mm`, `w-1/2-ml`, and so on) now use the same custom media queries you pass to `buildUserAssets`, instead of the hardcoded default breakpoints.
+- `@mapbox/assembly` now depends on `@unocss/core` (used when creating custom builds) and requires Node.js 24+.
+
+New: you can use Assembly as an UnoCSS preset for on-demand CSS:
+
+```js
+import { defineConfig } from 'unocss';
+import { presetAssembly } from '@mapbox/assembly';
+
+export default defineConfig({
+  presets: [presetAssembly()]
+});
+```
+
+`presetAssembly()` tree-shakes utilities from your source. The prebuilt `assembly.css` uses `presetAssembly({ safelist: true })`. Reset, forms, buttons, and other component CSS are preflight and always included.
+
+The generated CSS still uses Assembly's CSS variables and custom media queries, so it needs a PostCSS step with `postcss-custom-properties` and `postcss-custom-media`. See [`presetAssembly` in the README](README.md#presetassemblyoptions) for the config.
+
 ## 1.0.0+
 
 Version 1.0.0 of Assembly introduces breaking changes – learn how to resolve them with this handy guide.

README.md

@@ -26,6 +26,45 @@ Assembly exposes a JS module for creating custom builds. Why might you want to c
 - You want to append extra stylesheets that also use Assembly's variables and media queries.
 - You want to reduce file-size by picking and choosing the color variants you need.
 
+### presetAssembly([options])
+
+Returns an [UnoCSS preset](https://unocss.dev/guide/presets) that generates Assembly class names on demand. Utilities, media variants, and color modifiers are tree-shaken from your source. Reset, form, and other component CSS is included as preflight.
+
+```js
+import { defineConfig } from 'unocss';
+import { presetAssembly } from '@mapbox/assembly';
+
+export default defineConfig({
+  presets: [presetAssembly()]
+});
+```
+
+The generated CSS uses Assembly's CSS variables (`var(--blue)`) and custom media queries (`@media (--m-screen)`), which browsers can't resolve on their own. Run it through PostCSS with the same plugins `buildUserAssets` uses, pointed at Assembly's variable and media query definitions:
+
+```js
+// postcss.config.js
+const variables = require('@mapbox/assembly/src/variables.json');
+const mediaQueries = require('@mapbox/assembly/src/media-queries.json');
+
+module.exports = {
+  plugins: [
+    require('postcss-custom-properties')({
+      preserve: false,
+      importFrom: { customProperties: variables }
+    }),
+    require('postcss-custom-media')({
+      importFrom: { customMedia: mediaQueries }
+    })
+  ]
+};
+```
+
+`importFrom` requires `postcss-custom-properties@12` and `postcss-custom-media@8`; later major versions removed it. To change a variable or breakpoint, override its entry in these objects. `examples/jit/build.mjs` shows the full pipeline.
+
+The prebuilt `assembly.css` is generated with `presetAssembly({ safelist: true })` so every class is present. Do not pass `safelist: true` in an app that wants on-demand CSS.
+
+`options.colorVariants` and `options.files` match the `buildUserAssets` options of the same names. Variable overrides are applied in the PostCSS step above, not by the preset.
+
 ### buildUserAssets(outdir[, options])
 
 Returns a Promise that resolves when all assets have been written to `outdir`.
@@ -125,30 +164,27 @@ Assembly strives for flat, single rule declarations and avoids overrides wheneve
 
 ### Media query class variants
 
-Media query class variants (e.g. `block-mm` as a variant of `block`) are automatically generated and added to the CSS build with `scripts/build-media-variants.js`. If you want to generate media variants for a new class, or change which classes get media variants, you'll need to modify the lists in that file.
+Media query class variants (e.g. `block-mm` as a variant of `block`) are generated by the Assembly UnoCSS preset (`src/preset/variants.js`). The prebuilt stylesheet includes `-mm`, `-ml`, and `-mxl` variants for the classes listed in `src/preset/media-classes.js` plus every layout-scale utility. If you use `presetAssembly()` on demand, those suffixes work for any matching utility.
 
 ## Development
 
 ### Tools
 
+- [UnoCSS](https://unocss.dev/) generates Assembly utilities from `presetAssembly()` (`src/preset/utilities.js`, layout scales, color rules, media-query variants, and `src/preset/base.css` for reset/forms).
 - [PostCSS](http://postcss.org/) for processing CSS. PostCSS parses CSS and runs it through plugins, and these are the plugins we're using:
   - [Autoprefixer](https://autoprefixer.github.io/) automatically adds vendor prefixes.
   - [postcss-custom-properties](https://github.com/postcss/postcss-custom-properties) allows us to use variables for values, with the [CSS custom properties syntax](https://developer.mozilla.org/en-US/docs/Web/CSS/--*).
   - [postcss-custom-media](https://github.com/postcss/postcss-custom-media) allows us to use variables for media queries, with the [CSS custom media queries syntax](https://www.w3.org/TR/2016/WD-mediaqueries-4-20160126/#custom-mq).
-  - [concat-with-sourcemaps](https://github.com/floridoo/concat-with-sourcemaps) allows us to split our CSS into multiple stylesheets.
-- [stylelint](http://stylelint.io/) lints our CSS.
 - SVGs
   - [svgstore](https://github.com/svgstore/svgstore) compiles our SVGs into a SVG "sprite" of sorts, allowing us to use [the latest and greatest SVG-based icon system](https://css-tricks.com/svg-sprites-use-better-icon-fonts/).
-- Documentation
-  - [documentation-css](https://github.com/documentationjs/documentation-css) parses annotation comments in the CSS, outputting objects that can be used to build documentation.
-- [Batfish](https://github.com/mapbox/batfish) powers the website.
+- [VitePress](https://vitepress.dev/) powers the website.
 
 ### Install and start
 
 ```bash
 npm ci # Installs your `node_modules`
 
-npm start # Builds everything, starts a dev server, rebuilds & reloads on changes
+npm run dev # Builds CSS/JS, starts the VitePress docs server
 
 npm run build:js # Build SVGs and other JS
 ```