# Adaptive Matrix — full documentation

> Adaptive Matrix is a PostCSS 8 plugin that compiles px to responsive units against the design width of the file each px was drawn on, rather than against a single global width. Pages, a mobile component library and a desktop component library come from different design files; giving each its own canvas is what lets all three scale correctly at once. Output is bounded fluid clamp(), with text kept zoomable for WCAG 1.4.4. Component-library canvases are built in, so the default configuration is already correct for a project that uses one.

Every documentation page follows, concatenated in reading order. Each section is labelled with its path in the repository.


---

<!-- source: docs/getting-started.md -->

# Getting started

**English** · [简体中文](./getting-started.zh-CN.md)

## Install

```bash
npm i -D postcss postcss-adaptive-matrix
```

## Minimal configuration

With a single design file:

```js
// postcss.config.mjs
import adaptiveMatrix from 'postcss-adaptive-matrix'

export default {
  plugins: [
    adaptiveMatrix({
      defaultProfile: 'app',
      profiles: {
        app: {
          designWidth: 375,
          fluid: { minWidth: 320, maxWidth: 480 },
        },
      },
    }),
  ],
}
```

`designWidth` is the width of the design file; `fluid` is the range across which a size keeps following the viewport. Outside that range the size stops — which is the biggest difference from a plain `vw` setup, see [Bounded fluid sizing](#bounded-fluid-sizing).

## Two design files: app + desktop

When the design team delivers two canvases, use `appPcPreset`:

```js
import adaptiveMatrix, { appPcPreset } from 'postcss-adaptive-matrix'

export default {
  plugins: [
    adaptiveMatrix(
      appPcPreset({
        appDesignWidth: 375,
        pcDesignWidth: 1440,
        rootSelector: '#app',
      }),
    ),
  ],
}
```

What the preset decides for you:

| | App | Desktop |
| --- | --- | --- |
| Design width | 375 | 1440 |
| Fluid range | 320 – 480 | 1024 – 1920 |
| Applies when | default | `@media (min-width: 768px)` |

## Writing your CSS

Put everything both ends share — layout structure, colour, interaction states — in the base selector. Only what genuinely differs in size goes into `@adaptive pc`. Do not maintain two copies of the page:

```css
.product-card {
  display: grid;
  gap: 12px;
  padding: 16px;
  border-radius: 12px;
}

@adaptive pc {
  .product-card {
    grid-template-columns: 320px 1fr;
    gap: 32px;
    padding: 32px;
  }
}
```

Output:

```css
.product-card {
  display: grid;
  gap: clamp(10.24px, 3.2vw, 15.36px);
  padding: clamp(13.65333px, 4.26667vw, 20.48px);
  border-radius: clamp(10.24px, 3.2vw, 15.36px);
}

@media (min-width: 768px) {
  .product-card {
    grid-template-columns: clamp(227.55556px, 22.22222vw, 426.66667px) 1fr;
    gap: clamp(22.75556px, 2.22222vw, 42.66667px);
    padding: clamp(22.75556px, 2.22222vw, 42.66667px);
  }
}
```

Ordinary rules convert on the default `app` canvas; the `@adaptive pc` block converts on the 1440 canvas and is wrapped in the desktop media query.

## The other kind of two-ended project: two page trees, split by folder

The style above is **one page, two design files** — shared parts written once, differences in `@adaptive pc`.

The other common arrangement is **two page trees**: `src/mobile/**` and `src/pc/**`, each complete on its own, with routing or the entry point deciding which one you land in. Such a project needs no `@adaptive` in its CSS at all — file routing is enough:

```js
{
  defaultProfile: 'app',
  profiles: {
    app: { designWidth: 750, fluid: { minWidth: 320, maxWidth: 600 } },
    pc:  { designWidth: 1440, fluid: { minWidth: 1024, maxWidth: 1920 } },
  },
  routes: [
    { profile: 'pc',  file: [/[\\/]pc[\\/]/] },
    { profile: 'app', file: [/[\\/]mobile[\\/]/] },
  ],
}
```

The same `padding: 32px` converts against whichever design file its folder belongs to:

| File | Output |
| --- | --- |
| `src/mobile/home/index.vue` | `clamp(13.65333px, 4.26667vw, 25.6px)` |
| `src/pc/home/index.vue` | `clamp(22.75556px, 2.22222vw, 42.66667px)` |

**The key point: file routing only decides which design file to convert against. It never wraps a rule in a media query.** That is exactly what this kind of project needs — which page tree is displayed has already been decided by routing, and CSS should not decide it a second time. Both outputs above are unconditional.

An SFC's `from` carries a query string (`index.vue?vue&type=style&index=0&lang.css`), so write `file` patterns as "contains" rather than anchoring them to the end — see [Build tool integration](./integration.md#3-a-vue-sfc-path-carries-a-query-string).

### Which canvas do shared components land on

`src/components/**` is used by both ends and matches neither route, so it falls through to `defaultProfile`. Three choices:

1. **Just use the default canvas** — correct when the component is meant to look the same on mobile and desktop;
2. **Split one more folder level by purpose**, `src/components/mobile/**` and `src/components/pc/**`, each matching a route;
3. **Use `@adaptive pc` inside the component** — but under this section's configuration that has a trap, below.

### The trap: with no `query`, `@adaptive` becomes an unconditional rule

Neither profile in this section has a `query`, because switching is not CSS's job here. But the moment someone writes this in a shared component:

```css
.shared-card { padding: 32px }
@adaptive pc { .shared-card { padding: 48px } }
```

the `pc` canvas has no `query`, so there is no wrapper to put it in and the block is unwrapped instead — both rules are unconditional, and the second one comes later in the file, so **it wins at every viewport**:

```css
.shared-card { padding: clamp(13.65333px, 4.26667vw, 25.6px) }
.shared-card { padding: clamp(34.13333px, 3.33333vw, 64px) }   /* always the one that applies */
```

The compiler warns about this and offers two exits: give `pc` a `query`, or write `query: false` to state that switching happens outside CSS (one artifact per end, or a canvas chosen by environment variable). Once `query: false` is written the warning stops — that is a question you have already answered.

`@adaptive app` on its own canvas does not warn: there is no switch, and unwrapping loses nothing.

### Component libraries need no attention

Vant on mobile and Element Plus on desktop both live in `node_modules` and match neither folder route, so each is claimed by the built-in registry — Vant on the 375 canvas, Element Plus left in real pixels. No extra configuration.

The one thing to watch is that **your routes take priority over library routes**, so write folder patterns specifically enough: `/[\\/]pc[\\/]/` only matches a standalone `pc` segment, whereas `/pc/` would catch any dependency with those three letters anywhere in its path.

## Bounded fluid sizing

![The bounded fluid range](./assets/en/fluid-range.svg)

**A breakpoint and a fluid range are not the same thing.** A breakpoint decides which layout applies; a fluid range decides across which span sizes keep scaling.

In the configuration above, the app rules apply all the way up to 768px, but sizes stop growing at 480px — so a 600px tablet does not get a phone UI crudely blown up. Desktop applies from 768px, but sizes hold their floor below 1024px, so a narrow window is not over-compressed.

## Text

Font sizes do not use plain `vw`; they use a `rem + vw` hybrid:

```css
.title { font-size: 16px }
```

```css
.title { font-size: clamp(0.94867rem, calc(0.65rem + 1.49333vw), 1.098rem) }
```

The static part is in `rem`, so the browser's text-zoom setting keeps working (WCAG 1.4.4). Text in plain `vw` swallows the user's zoom choice entirely. The mix is controlled by `fontFluidity`, default `0.35`; at the design width the result is still exactly the design value.

## The root container

Pass `rootSelector` and the plugin appends a low-priority `@layer adaptive-matrix`:

- the root element gets `inline-size: 100%` and is centred horizontally;
- app and desktop each stop growing at their fluid ceiling;
- `env(safe-area-inset-*)` safe-area variables are injected;
- the root column width and gutter are published as variables, and `position: fixed` is corrected against them.

That last one deserves its own note: once the page is a centred column, `position: fixed` falls back to the viewport as its containing block, so a bottom navigation bar sticks to the window edges, out of line with the content column it belongs to. `appPcPreset` corrects this by default; pass `fixedContainingBlock: false` if you do not want it. See [Configuration reference](./configuration.md#fixedcontainingblock).

A project that already manages its own root container can simply omit `rootSelector`, and the plugin injects no global CSS at all.

### Component-based projects must say where to inject

This foundation is global, but PostCSS only ever sees one file at a time and has no way to deduplicate across files. So by default every processed file gets a copy.

For a project with a single global stylesheet, that is exactly right. Vue and Svelte projects are the opposite: **every component's `<style>` block is a separate file**, so the default means handing 150 components their own copy of the safe-area variables and root column rules.

Point it at the entry stylesheet and it is injected once:

```js
appPcPreset({
  rootSelector: '#app',
  rootInjectTo: 'src/styles/main',   // a string matches by "contains"
})
```

Regular expressions and functions are accepted too, with the same rules as `include`. When writing `root` directly the field is `root.injectTo`.

A pattern that matches nothing is not an error — it just injects nothing. Confirming with the [CLI](./cli.md) is the safest move; the entry file should show added declarations like `+ inline-size 100%`:

```bash
npx adaptive-matrix src/styles/main.css -c postcss.config.mjs
```

## Component libraries

Nothing to configure. The 11 built-in mainstream libraries convert against their own design canvas, desktop libraries keep real pixels, and theme tokens are recognised by name and take the text hybrid formula. For the full list and how to override, see [Component libraries](./libraries.md).

## Turning it off locally

```css
/* adaptive-ignore-next */
width: 320px;

height: 44px; /* adaptive-ignore */

/* adaptive-ignore-rule */
.widget { width: 300px }
```

These three comments **survive into the output**. An ignored `40px` and a `40px` nobody ever looked at are indistinguishable, so if the comment were dropped, a second compilation pass (which is exactly what happens when a pre-compiled dependency is compiled again by its consumer) would convert it. Any minifier removes the comments themselves.

For broader exclusions use `propList`, `selectorExclude`, `valueExclude`, `exclude`, or route a section of CSS to `profile: false`.

## Widths worth testing

Visual regression at least at: 320, 375, 480, 767, 768, 1024, 1440, 1920, 2560.

Also test: 200% browser text zoom, the iOS safe area, the Android WebView on-screen keyboard, landscape orientation, and any component using container queries.


---

<!-- source: docs/integration.md -->

# Build tool integration

**English** · [简体中文](./integration.zh-CN.md)

This is a standard PostCSS 8 plugin, so it works anywhere PostCSS can be configured. Below is how to wire it into each tool, plus a few places where things go wrong silently.

## Vite

`postcss.config.mjs` (recommended — it keeps this out of `vite.config.ts`):

```js
import adaptiveMatrix, { appPcPreset } from 'postcss-adaptive-matrix'
import autoprefixer from 'autoprefixer'

export default {
  plugins: [
    adaptiveMatrix(appPcPreset({ rootSelector: '#app' })),
    autoprefixer(),
  ],
}
```

Or inside `vite.config.ts`:

```ts
export default defineConfig({
  css: {
    postcss: {
      plugins: [adaptiveMatrix(appPcPreset({ rootSelector: '#app' }))],
    },
  },
})
```

**Not both.** As soon as Vite sees `css.postcss` as an inline object it stops reading `postcss.config.*`.

## Nuxt

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  postcss: {
    plugins: {
      'postcss-adaptive-matrix': { /* options */ },
      autoprefixer: {},
    },
  },
})
```

Nuxt uses the object form, keyed by package name. To use `appPcPreset` you have to go back to the array form in `postcss.config.mjs` — a preset returns an object, which cannot be expressed as a package-name key.

## Webpack

```js
// postcss.config.js
module.exports = {
  plugins: [
    require('postcss-adaptive-matrix')(require('postcss-adaptive-matrix').appPcPreset()),
    require('autoprefixer'),
  ],
}
```

`postcss-loader` goes after `css-loader` and before any preprocessor loader:

```js
use: ['style-loader', 'css-loader', 'postcss-loader', 'sass-loader']
```

## Taro

```js
// config/index.js
const config = {
  mini: { postcss: { /* Taro's own plugin configuration */ } },
  h5: {
    postcss: {
      'postcss-adaptive-matrix': {
        enable: true,
        config: { defaultProfile: 'app', profiles: { /* ... */ } },
      },
    },
  },
}
```

On the mini-program side, use a single canvas: mini programs have no `@media`, so `query: false` is mandatory, and `rpx` is already doing something similar — stacking two conversions doubles the effect.

---

## Four ways to fail silently

### 1. Plugin order

Put it **before** `autoprefixer`. `autoprefixer` does not prefix `clamp()`, so the wrong order is not an error — it is just a wasted pass.

Putting it **after** a nesting plugin such as `postcss-nesting` is fine too — both orders are correct, because a nested `@adaptive` is now handled properly (see [Architecture](./architecture.md#nesting)).

Sass and Less are not part of this discussion: a preprocessor finishes before PostCSS starts, so PostCSS already receives expanded CSS.

### 2. `from` is mandatory

Everything that decides a canvas by file path — the `file` channel in `routes`, `include` / `exclude`, and component-library path matching — depends on PostCSS's `from`.

Vite, Webpack, Nuxt and Taro all pass it. But if you hand-write `postcss(...).process(css)` without `from`, the file path degrades to an empty string and every `file` match silently stops working — no error, the component libraries simply stop being claimed.

```js
// wrong
await postcss([adaptiveMatrix(options)]).process(css)

// right
await postcss([adaptiveMatrix(options)]).process(css, { from: '/abs/path/app.css' })
```

### 3. A Vue SFC path carries a query string

The `from` Vite gives a `<style>` block looks like this:

```
/project/src/views/mobile/home/index.vue?vue&type=style&index=0&lang.scss
```

Write `file` patterns as **contains**, not anchored to the end:

```js
routes: [{ profile: 'mobile', file: [/[\\/]mobile[\\/]/] }]   // right
routes: [{ profile: 'mobile', file: [/\.mobile\.scss$/] }]     // never matches an SFC
```

Windows and POSIX use different separators, hence `[\\/]` rather than `/`.

### 4. The root foundation is repeated per file in a component-based project

Once `rootSelector` / `root` is configured, the plugin appends a global foundation. It is global, but PostCSS only ever sees one file at a time and has no way to deduplicate across files — so by default **every file gets a copy**.

In Vue and Svelte every component's `<style>` block is a separate file, so 150 components mean 150 copies of the safe-area variables and root column rules. Not an error, just a needlessly larger bundle.

```js
appPcPreset({
  rootSelector: '#app',
  rootInjectTo: 'src/styles/main',   // inject only into the entry
})
```

Conversely, a pattern that matches nothing injects nothing, also without an error. Run `npx adaptive-matrix src/styles/main.css` to confirm the added declarations appear in the entry file.

---

## Atomic CSS: Tailwind and UnoCSS

Utility CSS goes through PostCSS too, so it gets converted too — which is what you want: `p-4` and a hand-written `padding: 16px` mean the same size and should produce the same result.

**But the default configuration reads none of it, and says nothing.** Install the plugin, run a build, and your hand-written CSS scales while the utilities stay put; from then on the two size systems drift. There are two reasons, depending on which major version you use.

One wrapper solves both:

```js
import adaptiveMatrix, { appPcPreset, withAtomicCss } from 'postcss-adaptive-matrix'

export default {
  plugins: [adaptiveMatrix(withAtomicCss(appPcPreset({ rootSelector: '#app' })))],
}
```

`withAtomicCss` **wraps** rather than replaces: your existing `profiles`, `routes` and `root` are all kept, and it only adds the two things needed. Here is what each of those two is unblocking.

### Obstacle one: the unit is rem

Tailwind 3 and UnoCSS `presetUno` / `presetWind3` write lengths directly in `rem`:

```css
.p-4      { padding: 1rem }          /* not 16px */
.text-lg  { font-size: 1.125rem; line-height: 1.75rem }
.border   { border-width: 1px }      /* borders are still px */
.p-\[13px\] { padding: 13px }        /* bracketed arbitrary values are px too */
```

Both units appear in the same stylesheet. So what you need to read is **both**, not `rem` instead of `px`: reading only `rem` misses every border width and bracketed value, and reading only `px` misses spacing and font sizes. The first thing `withAtomicCss` does is add `rem` to `unitToConvert`.

If your page sets `html { font-size: 62.5% }`, add `rootValue: 10` so the reading and writing ends change together — see [Configuration reference](./configuration.md#unittoconvert-and-rootvalue).

### Obstacle two: the length is not in the utility at all

Tailwind 4 and UnoCSS `presetWind4` changed shape — there is no length in the utility, only a variable reference:

```css
:root { --spacing: 0.25rem; --text-lg: 1.125rem; --radius-lg: 0.5rem }

.p-4       { padding: calc(var(--spacing) * 4) }
.gap-8     { gap: calc(var(--spacing) * 8) }
.rounded-lg{ border-radius: var(--radius-lg) }
.text-lg   { font-size: var(--text-lg) }
```

`var()` is opaque; the compiler cannot see through it. So the theme tokens have to be claimed **at the source**. Custom properties are not converted by default (they must be explicitly claimed, or `transformCustomProperties` enabled), and the route `withAtomicCss` adds is exactly that claim.

Once the tokens are claimed, the utilities are correct without being touched:

```css
--spacing: clamp(3.41333px, 1.06667vw, 5.12px);
.p-4 { padding: calc(var(--spacing) * 4) }
```

`calc(clamp(a, b, c) * 4)` is equivalent to `clamp(4a, 4b, 4c)` (multiplication by a positive coefficient passes through a clamp), and the result is digit-for-digit identical to converting `16px` directly.

The claimed token prefixes are `--spacing`, `--text-`, `--leading-`, `--radius-`, `--container-`. Three are **deliberately absent**:

| Not claimed | Why |
| --- | --- |
| `--breakpoint-*` | It is the width at which a canvas **switches**. Scaling it moves the breakpoint itself, and nothing anywhere would say so |
| `--tracking-*` | Published in `em`, and the font size the `em` hangs off is already fluid — scaling again compounds it |
| `--shadow-*` | A shadow's pixels are depth drawn at screen scale, not a length measured on a design file |

Length families you extend the theme with are added via `tokenPrefixes`:

```js
withAtomicCss(appPcPreset(), { tokenPrefixes: ['--gutter-', '--size-'] })
```

### Font-size tokens stay zoomable

A name like `--text-lg` does not look like a font property, but a font size is exactly what it carries. The default `textProperties` includes `--text-*` and `--leading-*`, so it gets precisely the same `rem + vw` hybrid as a hand-written `font-size`, and browser text zoom is unaffected:

```css
--text-lg: clamp(1.06725rem, calc(0.73125rem + 1.68vw), 1.23525rem);
```

This does nothing for an unclaimed token — it decides **how** an already-converting length is written, not whether it converts.

### This section was written against real output

The three cases under `conformance/cases/atomic/` take their input from the **actual published output** of Tailwind CSS 4.3.3, UnoCSS 66.7.5 `presetWind3` and UnoCSS 66.7.5 `presetWind4` — not hand-written imitations, because the two shapes above differ far too much for a hand-written copy to be anything but what you imagined. Re-capture with `scripts/capture-atomic.mjs`.

Neither framework is a devDependency: the captured CSS is the entire input, and tying `npm test` to someone else's release schedule buys no extra information.

### The other route

If you would rather not configure anything, make the framework emit px instead: UnoCSS has `@unocss/preset-rem-to-px`, and Tailwind 3 has `theme.spacing`. Tailwind 4 has no such route — its shape is token indirection, which has nothing to do with units.

### Which canvas utilities use

Utilities have no distinguishing class-name prefix, so they use `defaultProfile`. To send a group of utilities to another canvas, use the `selector` channel in `routes`; to move the theme tokens as a whole, use `withAtomicCss(base, { profile: 'pc' })`.

## On-demand component imports

On-demand importers such as `unplugin-vue-components` still end up importing CSS files from `node_modules`, so the path channel matches as usual and no extra configuration is needed.

But do **not** add `exclude: [/node_modules/]` for "performance" — that excludes the component libraries' CSS entirely, so the components fall back to raw pixels and stop lining up with your scaled page. That is precisely the problem [Component libraries](./libraries.md) exists to solve.

## Verifying

After changing configuration, running the output is more reliable than reading the configuration:

```bash
npx adaptive-matrix src/styles/app.css -c postcss.config.mjs
```

The output is a per-declaration before/after, with no build to start and no browser to open. The "`from` is mandatory" trap above can also be rehearsed with `--from` before you ship. See [CLI preview](./cli.md).

## This page was run against a real build

Every claim on this page about Vite is verified by a **real Vite build** in `test/vite.test.ts`, rather than simulated with `postcss().process`. The scaffold includes an auto-discovered `postcss.config.mjs`, a dependency stylesheet imported from `node_modules`, and a `<style>` block supplied the same way `@vitejs/plugin-vue` supplies one. It then asserts that:

- Vite really does find and apply the config file (when it does not, the build still succeeds and the stylesheet passes through untouched, with nothing anywhere saying so);
- dependency CSS lands on the component-library canvas via its `node_modules` path, producing output **byte-for-byte identical** to the equivalent size on the page;
- an SFC id with a query string is matched by a contains-style `file` route;
- building the same input twice produces identical output (watch and HMR run the same pipeline over and over);
- conversely, an end-anchored pattern like `/\.mobile\.css$/` really does leave the SFC block silently on the default canvas — point 3 above, turned from something remembered into something verified.

There is no real Webpack build. All `postcss-loader` does is call `postcss.process` with a `from`, and what has actually broken in a Webpack setting is whether the CommonJS entry can be called directly (fixed in 0.4.0), which `test/package.test.ts` verifies against the built artifact itself. Pulling in a whole Webpack toolchain for a path with almost no independent risk is not worth it.


---

<!-- source: docs/cli.md -->

# CLI preview

**English** · [简体中文](./cli.zh-CN.md)

Change one `designWidth`, move a `fluid` range, and seeing the effect normally means rebuilding and comparing by eye in a browser. This command shortens that to one keystroke:

```bash
npx adaptive-matrix src/styles/app.css
```

```
src/styles/app.css
  profiles: app (default), pc, +5 library canvases
  .page
    padding    16px → clamp(13.65333px, 4.26667vw, 20.48px)
    font-size  16px → clamp(0.94867rem, calc(0.65rem + 1.49333vw), 1.098rem)
  @media (min-width: 768px) › .page
    padding    48px → clamp(34.13333px, 3.33333vw, 64px)
  3 converted, 0 left as authored
```

What it prints is a **before/after list per declaration**, not the whole stylesheet. A build tool's output runs to thousands of lines, and what you actually want to confirm is usually a handful of numbers.

## Usage

```
adaptive-matrix <file...> [options]
cat app.css | adaptive-matrix --from src/app.css
```

| Option | Effect |
| --- | --- |
| `-c, --config <path>` | A module whose default export is the plugin options, or a `.json` file of options |
| `--from <path>` | Treat the input as living at this path |
| `--profile <name>` | Override `defaultProfile` |
| `--targets <list>` | Audit the output against the oldest browsers you support, e.g. `"safari 14, ios_saf 13"` |
| `--all` | List unchanged declarations too |
| `--css` | Print the compiled stylesheet instead of the comparison |
| `--color` / `--no-color` | Force colour on/off; with neither it follows the terminal and honours `NO_COLOR` |
| `-h, --help` | Help |

Exit codes: `0` when everything is fine, `1` for a bad argument, an unreadable file, or an invalid configuration. So it drops straight into a shell condition.

## Reading a configuration

Without `-c` the built-in defaults are used, and the header tells you which canvases are active.

```bash
npx adaptive-matrix src/app.css -c postcss.config.mjs
```

The config module must default-export the **plugin options object**, not a PostCSS config. When the two differ, write a separate file:

```js
// adaptive.config.mjs
import { appPcPreset } from 'postcss-adaptive-matrix'
export default appPcPreset({ appDesignWidth: 375, pcDesignWidth: 1440 })
```

A TypeScript config needs a loader:

```bash
npx tsx node_modules/postcss-adaptive-matrix/dist/cli.js src/app.css -c adaptive.config.ts
```

(Node 22.6+ strips types natively, so `npx adaptive-matrix -c adaptive.config.ts` also runs, but it prints an experimental warning and only supports erasable syntax.)

### A JSON configuration

A path ending in `.json` is read as a file of options rather than imported. Name the [published schema](https://moresyl.github.io/postcss-adaptive-matrix/schema/options.json) in `$schema` and your editor will complete the option names, show each one's description, and flag a value that is out of range — before you run anything:

```json
{
  "$schema": "https://moresyl.github.io/postcss-adaptive-matrix/schema/options.json",
  "defaultProfile": "app",
  "profiles": {
    "app": { "designWidth": 375, "fluid": { "minWidth": 320, "maxWidth": 600 } },
    "pc": { "designWidth": 1440, "fluid": { "minWidth": 1024, "maxWidth": 1920 } }
  }
}
```

`$schema` is not an option; it is dropped when the file is read.

What JSON cannot hold is a `RegExp` or a function, so a config that routes by a regular expression, or computes `designWidth` per file, has to stay JavaScript. The schema marks those places with `x-also`.

The configuration is validated before the first stylesheet is read, so a misspelled `defaultProfile` or a reversed `fluid` range produces the compiler's own message rather than a screenful of comparisons followed by an error.

A missing `default` (`export const options = {...}`) or an uncalled preset (`export default appPcPreset` rather than `appPcPreset({...})`) is an error. Both used to run silently on the built-in defaults — the header still listed canvases, the comparison still looked right, and nothing anywhere said your configuration had never been read.

## Rehearsing file routing

Deciding a canvas by path is the easiest thing to misconfigure and the hardest to notice — a wrong pattern is not an error, the route just silently fails to match (see [Build tool integration](./integration.md#2-from-is-mandatory)). `--from` exists to rehearse routing before you ship:

```bash
# The same CSS, pretending it lives under desktop/
npx adaptive-matrix scratch.css -c adaptive.config.mjs --from src/desktop/scratch.css
```

Different numbers between the two runs mean the route matched. Identical numbers mean it did not.

A Vue SFC path carries a query string; copy it in verbatim:

```bash
npx adaptive-matrix scratch.css --from 'src/views/mobile/home/index.vue?vue&type=style&lang.scss'
```

## Going backwards at a breakpoint

Two design files can each be right and still disagree at the seam. This check looks for exactly one thing: **the window gets wider and a size gets smaller.**

```
  shrinks .card font-size gets smaller at 768px: 17.57px → 16.18px
          clamp(0.94867rem, ...) → clamp(1.01125rem, ...). Widening the window makes this smaller — the two canvases disagree here.
```

`.card`'s font size is 16px on the app file and 18px on the desktop file; both are reasonable on their own. But by 767px the app canvas has already grown it to 17.57px, while the desktop canvas starts at 16.18px. Widen the browser by one pixel and the body text jumps down.

It is worth a dedicated check because it **only appears at that one width**: each design file renders correctly on its own, and the 375 and 1440 you debug at every day are both fine.

Every formula this compiler emits is non-decreasing in **absolute value** across viewport width, and never changes sign. So a size going backwards can only come from a canvas change across a breakpoint. That also makes the check complete: this class of problem cannot escape to some other width.

### Only values the compiler produced

"Can only come from a canvas change" holds only for **formulas this compiler produced**. An unconverted stylesheet that shrinks at a breakpoint is usually doing so on purpose:

```css
/* Quasar 2.19's own stylesheet */
.q-tooltip { padding: 6px 10px }
@media (max-width: 599.98px) { .q-tooltip { padding: 8px 16px } }
```

A bigger tap target on a phone, tightened up above 600px — both numbers were written by a person who compared them. Quasar is a "keep pixels" entry, neither side was converted, and reporting it would be noise.

So a report requires **at least one side to be a compiler-produced formula**. There is no unwrapped spelling of a bounded fluid size: every viewport-dependent length this compiler emits sits inside `clamp()` / `min()` / `max()` / `calc()` (no exception across all 69 conformance fixtures), which is how the check decides. One side converted and the other not still reports — that is precisely a canvas change, and nobody compared those two numbers.

Substitution happens before the decision, so "the declaration is just `var(--x)` and the formula is in the token" counts too.

It compares absolute values rather than signed numbers: a negative length (a negative margin, a bleed) grows by moving away from zero, so the formula compiled from `-16px` gets smaller as the window widens. A sign change across the breakpoint is never reported — zero is a boundary the compiler itself never crosses, so meeting it here means the two design files intended different things, and which one is right is not something this check can decide.

What to change is your call — raise the desktop font size, drop `pcFluidMin` from 1024 to 768, or narrow the app file's `fluid.maxWidth`. The tool only tells you where the seam is.

The check is deliberately narrow, preferring silence to a false positive: it compares only identical selector strings, does no specificity reasoning, and expands no shorthands. It skips the whole group on `@supports`, `@container`, media queries that are not pure width, groups spanning cascade layers, and values it cannot evaluate to a number such as `env()`, `%` or container units.

### Theme tokens are substituted

Component libraries almost never write literal sizes. Of Vant 4.10.0's 3198 ordinary declarations, 1173 read entirely through `var()` — a check that gave up at the first `var(` would see a small slice, and precisely the slice that avoids the layer this plugin adapts.

So custom properties in the same stylesheet are substituted first, then evaluated:

```css
:root,:host { --card-width: 40px }
.card { width: var(--card-width) }
@media (min-width: 768px) { .card { width: 20px } }
```

`.card` drops from 40px to 20px at 768px, which is only visible after substitution.

Substitution happens only when the value is decided by **viewport width alone**; both conditions must hold:

- Declared only on `:root` / `:host` / `html`, with no second copy elsewhere. One `.van-theme-dark { --card-width: ... }` abandons the whole thing — the element's value then depends on whether an ancestor carries that class, which width cannot answer.
- Every declaration is either unconditional or inside a pure pixel-width `@media`. Declarations inside `@supports`, `@container` or an orientation query abandon it as well.

A token rewritten at a breakpoint is itself a seam, even if the rule consuming it is written once:

```css
:root { --card-width: 40px }
@media (min-width: 768px) { :root { --card-width: 20px } }
.card { width: var(--card-width) }   /* written once, still reported */
```

The fallback in `var(--x, 16px)` is used only when `--x` really is undeclared — matching the browser. If `--x` is declared but its value is unknowable (the theme class above), nothing is reported, rather than taking the fallback as the answer.

The custom-property declaration itself (the `--x: ...` line) is still not checked. It is not a length on screen, and its direction is decided by whoever consumes it — this plugin's own `--adaptive-root-width` is inverted: it feeds `max(0px, (100vw - var(--adaptive-root-width)) / 2)`, where a smaller value exists to make the gutter bigger. Skipping it is not ignoring it: the declaration that consumes it is checked, and after substitution its direction is meaningful.

Measured (the complete Vant 4.10.0 stylesheet, 195 KB): evaluable value components rise from 622 (17.6%) to 1309 (36.9%), with 779 tokens collected. The rest are keywords, colours and percentages — never viewport-dependent lengths.

On false positives: across the 69 conformance fixtures, this repository's example project, and the published stylesheets of 10 component libraries (Vant, NutUI, Varlet, antd-mobile 1x/2x, Taro UI, Element Plus, Ant Design, Arco Design, Quasar — about 3.2 MB of CSS), the `shrinks` count is 0 everywhere. See [Component libraries](./libraries.md#this-table-was-checked).

To fail a build on it, the same check is exported from the package:

```js
import postcss from 'postcss'
import adaptiveMatrix, { findContinuityIssues } from 'postcss-adaptive-matrix'

const result = await postcss([adaptiveMatrix(options)]).process(css, { from })
const issues = findContinuityIssues(result.root)
if (issues.length) throw new Error(`${issues.length} breakpoint regressions`)
```

## Syntax your target browsers cannot read

`--targets` takes a list of "browser + the oldest version you intend to support" and checks each one against the **compiled output**:

```bash
npx adaptive-matrix src/app.css -c adaptive.config.mjs --targets "ios_saf 13, chrome 90"
```

```
  needs @layer — iOS Safari 13 < 15.4, Chrome 90 < 99
          from: root.layer, which appPcPreset sets to 'adaptive-matrix' ...
          seen: @layer adaptive-matrix { :where(#app) {
          if unsupported: The whole @layer block is dropped, so the entire root
          foundation goes with it ...
          instead: root.layer: false emits the same rules unwrapped. ...
  needs clamp(), min(), max() — iOS Safari 13 < 13.4-13.7
```

The order of those four lines is deliberate: **what disappears** first, **what to switch to** second. "iOS Safari 13 is too old" is not actionable on its own, and what has always mattered about a CSS support gap is how much goes with it — an unreadable value takes its declaration, an unreadable selector takes its rule, an unreadable at-rule takes its whole block.

The `clamp()` line above misses by **a point release**: 13.4 has it. That is exactly the gap a human comparing version numbers overlooks.

When every target is new enough, there is one line:

```
  every target reads all 7 CSS features in this output
```

Known names: `chrome`, `edge`, `safari`, `firefox`, `ios_saf`, `samsung`; `android` and `webview` map to `chrome`. An unrecognised name is an error and exits `1` rather than being skipped silently — a target quietly dropped is worse than no audit at all, because it reads like a pass.

For the full feature × version matrix, the degradation path for each feature and the programmatic API, see [Browser support and degradation](./compatibility.md).

## Seeing the whole output

To hand the result to another tool, use `--css`:

```bash
npx adaptive-matrix src/app.css --css > out.css
```

In `--css` mode stdout is CSS only; warnings go to stderr. So the redirected file is clean, directly parseable CSS, while the warnings still appear in your terminal rather than being swallowed.

## Reading the output

- `16px → clamp(...)` — converted
- a grey line with no arrow — left as authored (only shown with `--all`). Hairlines, lengths inside `@font-face`, and declarations marked by an ignore comment appear here
- `+ ...` — a declaration the compiler added, such as the root foundation or a `preserveOriginal` fallback
- `@media (min-width: 768px) › .page` — where the declaration sits, outermost first. This is what `@adaptive pc` compiles to, and seeing the same `.page` twice is normal
- `warning ...` — a compiler warning, passed through verbatim
- `shrinks ...` — a size going backwards across a breakpoint, see [Going backwards at a breakpoint](#going-backwards-at-a-breakpoint)
- `needs ...` — syntax a target browser cannot read; only with `--targets`, see [Syntax your target browsers cannot read](#syntax-your-target-browsers-cannot-read)

The header's `+5 library canvases` are the canvases of the built-in component libraries. They are generated from the registry and are not names you can write in `@adaptive`, so only the count is reported. For the full list see [Component libraries](./libraries.md).


---

<!-- source: docs/libraries.md -->

# Component libraries

**English** · [简体中文](./libraries.zh-CN.md)

## The problem

A component library has its own design file, and it is not necessarily yours. Vant is drawn on 375, your pages may be drawn on 750, and Element Plus has no design file at all — it is drawn in real pixels and was never meant to scale.

The traditional answer is to add `node_modules` to an ignore list. That only changes the shape of the problem: the page scales while the components stay put, and the two stop lining up. Not ignoring them stretches the components against a canvas that was never theirs. Those are the only two options an ignore list offers, and neither is right.

The correct answer is to give each design file its own canvas. **That is the default — there is nothing to configure.**

## The effect

```js
adaptiveMatrix({
  defaultProfile: 'app',
  profiles: {
    app: { designWidth: 750, fluid: { minWidth: 320, maxWidth: 600 } },
  },
})
```

```css
/* Input — 16px in all four places */
:root       { --van-padding-md: 16px }
.van-cell   { padding: 16px }
.el-input   { padding: 16px }
.page-hero  { padding: 16px }
```

```css
/* Output */
:root       { --van-padding-md: clamp(13.65333px, 4.26667vw, 25.6px) }
.van-cell   { padding: clamp(13.65333px, 4.26667vw, 25.6px) }
.el-input   { padding: 16px }
.page-hero  { padding: clamp(6.82667px, 2.13333vw, 12.8px) }
```

The three Vant items convert on 375, Element Plus is left alone, and the page converts on 750. Three different results, each of them correct.

## The built-in list

Mobile — converted against their own design canvas:

| Name | Design width | Class prefix | Token prefix | Prefix hit rate |
| --- | --- | --- | --- | --- |
| `vant` | 375 | `van-` | `--van-` | 1288/1407 |
| `nutui` | 375 | `nut-` | `--nut-` | 1398/1497 |
| `varlet` | 375 | `var-` | — † | 1749/1879 |
| `antd-mobile` | 375 | `adm-` | `--adm-` | 798/829 |
| `antd-mobile-2x` | 750 | `adm-` ‡ | `--adm-` ‡ | 798/829 |
| `taro-ui` | 750 | `at-` * | — | 711/722 |

Desktop — drawn in real pixels, where the correct adaptation is to leave them alone:

| Name | Design width | Class prefix | Token prefix | Prefix hit rate |
| --- | --- | --- | --- | --- |
| `element-plus` | keep pixels | `el-` | `--el-` | 3180/3251 |
| `antd` | keep pixels | `ant-` | — | 5941/6050 |
| `arco-design` | keep pixels | `arco-` | — | 3462/3763 |
| `naive-ui` | keep pixels | `n-` * | — | generated at runtime |
| `quasar` | keep pixels | `q-` * | — | 2080/3363 |
| `mui` | keep pixels | `Mui` | — | generated at runtime |

Every entry also matches by package path (`/vant/`, `/@nutui/` and so on), so it works whether or not the output is still split into files.

The three prefixes marked `*` are not enabled in automatic mode; why is below. † see [Tokens without a prefix](#tokens-without-a-prefix), ‡ see [One prefix, two canvases](#one-prefix-two-canvases).

### This table was checked

"Prefix hit rate" is the number of rules containing that prefix in the library's **published stylesheet** ÷ the total rule count — measured, not copied from documentation. The verification script is in the repository and you can run it yourself:

```bash
npx tsx scripts/verify-libraries.ts          # all of them
npx tsx scripts/verify-libraries.ts vant     # one
```

It downloads each library's published artifact, compiles it with a realistic `node_modules` path, and then checks: whether the prefix and token prefix really exist, which canvas the route lands on, whether the result is idempotent, whether there are warnings, and whether the breakpoint seam check produces a false positive. All 12 entries currently pass.

**One column it does not cover: design width.** A stylesheet does not reveal how wide the file it was drawn on was; that column comes from each library's own documentation and the script cannot check it.

`naive-ui` and `mui` generate their styles at runtime, so there is no stylesheet on disk — nothing goes through PostCSS and there is nothing to check. The entries are still useful: they are "keep pixels", so your hand-written `.n-button` overrides are not scaled.

The list is readable from code:

```js
import { BUILT_IN_LIBRARIES } from 'postcss-adaptive-matrix'
```

## How matching works

An entry offers up to three channels, and matching any one of them assigns the CSS to that library's canvas:

- **Class prefix** — without the dot. `'van-'` matches `.van-cell` and `.page .van-cell`, but not `.caravan-slot`;
- **Custom-property prefix** — such as `'--van-'`. Being claimed is itself the switch, so this is not gated by `transformCustomProperties`; that option governs variables you wrote;
- **File path** — the fallback for when the build output is still split into files.

Priority: property name > selector > file path.

A selector beats a file path because the selector is part of the CSS itself, whereas a path only reflects how the build tool happened to arrange files at the time — once a bundler inlines a dependency, the path is gone. The reasoning for property names is the same and stronger: theme tokens are declared on `:root` and leave no trace of their origin beyond their name.

## A rule can only have one answer

A selector list can straddle canvases:

```css
.van-cell, .page-hero { padding: 16px }
```

`.van-cell` belongs to the Vant canvas and `.page-hero` to the default one, but `padding: 16px` has only one value to emit — CSS cannot give one declaration a different result per selector in the list. The compiler compiles the whole rule on the first canvas that matches, and the other selector gets a conversion that is not its own.

This warns, naming the selector that lost. Splitting into two rules fixes it:

```css
.van-cell { padding: 16px }
.page-hero { padding: 16px }
```

Commas inside attribute values are not selector boundaries and are never split.

Commas inside `:is()` and `:where()` are argument separators rather than selector boundaries, but the ambiguity they create is exactly the same one — `:is(.van-cell, .page-hero)` is still one declaration wanted on two canvases — so they warn too. What differs is the price of the fix, and the warning works that out rather than leaving it to you: `:is()` matches every branch at the specificity of its **highest** one, so pulling the branches apart is free only when they already agree. When they do not, the warning says so and names what the split would cost:

```
Selector list inside :is() spans more than one canvas: ".page-hero" belongs to app
but the whole rule is compiled against library:vant, because one declaration can
only have one result. Give each branch its own rule. Splitting is not
specificity-neutral: :is() matches every branch at its highest, 1-1-0, so
".page-hero" would drop to 0-1-0.
```

## What a selector is *about*

`:not()` and `:has()` do not route at all — not their arguments, anyway:

```css
.page-hero:not(.van-cell) { padding: 16px }
```

This rule styles page elements. It styles exactly the ones that are **not** Vant cells. Reading `.van-cell` out of it and sending the rule to Vant's 375 canvas gives a padding twice the size the author asked for, and nothing in the output says so. The same goes for `:has()`: `.page-card:has(.van-icon)` is a page card, whatever it happens to contain.

So routing looks at the **subject** of the selector, and the arguments of `:not()` and `:has()` are removed before anything is matched. `:is()` and `:where()` are the opposite case — their arguments *are* alternatives for the subject — which is why those are kept, and why they are the ones that can straddle canvases and warn.

This matters more than the hand-written example suggests, because atomic CSS frameworks emit these shapes constantly. One `space-x-4` compiles to `:where(& > :not([hidden]) ~ :not([hidden]))` in Tailwind 4, to a flat `> :not([hidden]) ~ :not([hidden])` in UnoCSS wind3, and to native nesting in UnoCSS wind4 — three unrelated spellings of one utility, all of them putting a selector inside a functional pseudo-class whose argument names an element the rule does not style.

## Theme tokens

A token whose name contains a text-property word takes the `rem + vw` hybrid rather than the plain `vw` of an ordinary length:

```css
:root {
  --van-font-size-md: 14px;
  --van-cell-font-size: 14px;
}
```

Both are recognised as font sizes. Emitted as ordinary lengths, the library's text would stop responding to browser zoom — the user increases the font size, your own text grows, and the text inside components does not.

### Tokens without a prefix

Varlet's custom properties carry no library prefix: they are simply `--field-padding`, `--icon-size-md`, `--card-width`, declared on a bare `:root`. So the registry gives it **no `tokenPrefix`**: claiming those names means claiming `--card-width` itself, any project may define a variable of the same name, and a false match is silent.

The blast radius is small — Varlet's own stylesheet matches by path and lands on the 375 canvas as usual. But if you override the theme **in your own CSS**, as the official docs suggest:

```css
/* your own file: not under @varlet, and no prefix to recognise */
:root { --field-padding: 16px }
```

that line is not claimed, and needs an explicit route:

```js
adaptiveMatrix({
  routes: [{ profile: 'library:varlet', property: ['--field-', '--icon-size-'] }],
})
```

### One prefix, two canvases

antd-mobile publishes the same stylesheet twice: `bundle/` drawn on 375 and `2x/bundle/` drawn on 750. The class names and token names are identical (measured on 5.42.3: every length in the latter is exactly double the former, `font-size: 16px` against `32px`), and **only the path tells them apart**.

Routing on the `.adm-` prefix alone would convert the 2x artifact against 375, making every size on the page exactly twice what it should be — no error, no warning, just uniformly too big.

So the `antd-mobile-2x` entry is **path-scoped**: its prefix channel only counts when the path matches too. Path-scoped routes are tested before unscoped ones, because "class name plus path" is more specific than "class name alone":

- compiling `2x/bundle/style.css` → the 750 canvas;
- compiling `bundle/style.css` → the 375 canvas;
- when a bundler has inlined the dependency and the path no longer exists → falls back to 375, which is the default artifact.

Both entries are present in automatic mode, with nothing to configure. When your own library has the same shape, `scoped: true` is the same switch:

```js
adaptiveMatrix({
  libraries: [
    { name: 'acme-2x', designWidth: 750, prefix: 'acme-', file: [/[\\/]acme[\\/]2x[\\/]/], scoped: true },
  ],
})
```

`scoped` without `file` is an error — the path scope is the entire reason it may claim someone else's prefix, and without it the entry degrades into a duplicate decided by declaration order.

## Prefixes held back in automatic mode

The prefixes of `naive-ui` (`.n-`), `quasar` (`.q-`) and `taro-ui` (`.at-`) really are the official ones, but they are also hard to tell apart from ordinary application class names. In automatic mode those three **match by file path only**.

Naming the library explicitly states that its prefix is safe in this codebase, and the prefix channel comes back:

```js
adaptiveMatrix({ libraries: ['vant', 'naive-ui'] })
```

A false match is silent — it scales an element against the wrong canvas, or skips an element that should have scaled, with no error and no warning. The default is strict because a wrong adaptation is harder to find than a missing one.

## Overriding a built-in entry

Use `extends` to change one field and inherit the rest. `name` is inherited too, so diagnostics and the derived canvas name still point at the library a reader recognises:

```js
adaptiveMatrix({
  libraries: [{ extends: 'vant', designWidth: 750 }],
})
```

That is the only entry point. Each library synthesises a canvas named `library:<name>`, and `library:` is a reserved prefix — writing `'library:vant'` directly in `profiles` would be overwritten by the synthesised result and therefore have no effect, so that configuration is an error that points you back to `extends`.

## Adding a library that is not listed

```js
adaptiveMatrix({
  libraries: [
    'vant',
    {
      name: 'acme-ui',
      designWidth: 375,
      prefix: 'acme-',
      tokenPrefix: '--acme-',
      file: [/[\\/]@acme[\\/]ui[\\/]/],
    },
  ],
})
```

Providing an array means only the listed entries are enabled — in the configuration above, every built-in other than Vant and acme-ui is off.

## Turning it off

```js
adaptiveMatrix({ libraries: false })
```

You can still handle things yourself with explicit `routes`, `exclude: /node_modules/`, `selectorExclude` and the comment directives.

## Types

```ts
type LibraryEntry =
  | string                                              // a built-in name
  | LibraryAdaptation                                   // a complete definition
  | (Partial<LibraryAdaptation> & { extends: string })  // adjust a built-in

interface LibraryAdaptation {
  name: string
  designWidth: number | false
  prefix?: string | string[]
  tokenPrefix?: string | string[]
  file?: FileMatcher | FileMatcher[]
  scoped?: boolean
  basedOn?: string
}
```

`basedOn` says which profile's fluid range, unit and strategy to borrow; it defaults to `defaultProfile`. The derived canvas replaces only `designWidth`, so it stops growing at the same viewport width as the page — which is exactly why the components and the page stay aligned.

A derived canvas also inherits its profile's `textAnchorWidth` (which by default is that profile's `designWidth`), see below.

### Where a library canvas anchors its text

A library canvas and a page canvas describe **the same design in two sets of units**: with Vant on 375 and the page on 750, Vant's 16px and the page's 32px are the same size, and after compilation they must render identically at any viewport.

Ordinary lengths get this for free — both reduce to `value ÷ canvas`. Text does not: to keep browser text zoom working, text retains a fixed `rem` component, and a fixed length only means anything relative to some width. If each canvas anchored to itself, that `rem` would be off by a factor of two:

```text
page 32px on 750  → clamp(1.59867rem, calc(1.3rem  + 1.49333vw), 1.86rem)
Vant 16px on 375  → clamp(0.94867rem, calc(0.65rem + 1.49333vw), 1.098rem)   ← before the fix
```

The fluid terms are already identical; the whole difference is in the static term. At a 390px viewport that is 26.62px against 16.22px — Vant's text about 40% too small, and invisible at both 375 and 1440 (each design file is correct on its own). **A 750-file project using Vant is one of the most common mobile combinations there is.**

So a derived canvas takes its text anchor from the profile it belongs to, and both sides produce the same formula. This is the default and needs no configuration. For the reasoning and the derivation see [Which canvas the static part anchors to](./architecture.md#which-canvas-the-static-part-anchors-to).

Entries expand into routes appended after `routes`, so your explicit routes always win.


---

<!-- source: docs/configuration.md -->

# Configuration reference

**English** · [简体中文](./configuration.zh-CN.md)

Every option, its type and its default. If you are just starting, read [Getting started](./getting-started.md) first.

## Top-level options

| Option | Default | Meaning |
| --- | --- | --- |
| `profiles` | app/desktop preset | The map of design canvases |
| `defaultProfile` | `app` | The canvas ordinary CSS uses |
| `routes` | `[]` | Reassign a canvas by selector, property name, breakpoint or file |
| `libraries` | `'auto'` | Component-library adaptation; all built-ins on by default |
| `atRuleName` | `adaptive` | Custom at-rule name |
| `strategy` | `clamp` | `clamp`, or the compatibility-oriented `viewport` |
| `unit` | `vw` | `vw`, `vi`, `cqw`, `cqi` |
| `precision` | `5` | 0–12 decimal places |
| `unitToConvert` | `['px']` | The input unit(s) to read; a single string is accepted too |
| `rootValue` | `16` | How many pixels one `rem` is worth |
| `minPixelValue` | `0` | Absolute values below this are not converted |
| `hairline` | `1` | Hairline threshold that is never converted |
| `fontFluidity` | `0.35` | Text fluidity ratio, 0–1 |
| `textProperties` | font-related properties | Properties that use the zoomable hybrid formula |
| `propList` | `['*']` | Property list supporting `*` and `!` |
| `selectorExclude` | `[]` | Exclude by substring or regular expression |
| `valueExclude` | `[]` | Exclude by value |
| `include` / `exclude` | none | File string, regular expression, function, or an array |
| `transformCustomProperties` | `false` | Whether to convert `--token` values |
| `preserveOriginal` | `false` | Keep the original declaration in front as a fallback |
| `root` | `false` | The optional root layout foundation |
| `unknownProfile` | `warn` | `warn`, `error`, `ignore` |

`propList` example:

```js
propList: ['*', '!border*', '!box-shadow']
```

The `*` is not optional. An exclude-only `['!border*']` matches no property at all, which means the entire stylesheet goes unconverted — that configuration is an error rather than a silent no-op.

### Configuration is always validated first

A configuration usually lives in a `.mjs` file with no type checking behind it, and getting these fields wrong fails **silently**. So all of the following are errors raised before the first stylesheet is read:

| What you wrote | The consequence |
| --- | --- |
| `unit: 'vm'` | Emits `4.267vm`. That is not a length, so the browser drops the whole declaration and the element keeps its inherited value |
| `strategy: 'viewpoint'` | Silently falls back to `clamp`, looking exactly like a setting that took effect |
| `unitToConvert: ''` / `[]` | Matches no length, indistinguishable from not installing the plugin |
| `rootValue: 0` | Every `rem` reads as 0, and the writing end divides by zero |
| `atRuleName: 'media'` | Every `@media` in the stylesheet is read as a canvas name and rewritten. At-keywords are case-insensitive, so `MEDIA` is the same collision |
| `root.selector: ''` | Compiles to `:where()`, which is a parse error — the whole foundation, safe-area variables included, is discarded |
| `textAnchorWidth: 0` | Division by zero, turning every text length into `Infinity` |

`unit` and `strategy` are validated at profile level too.

### unknownProfile

When the canvas name in `@adaptive ghost` does not exist:

| Value | Behaviour |
| --- | --- |
| `warn` | Warn, and leave the at-rule as written |
| `error` | Fail the build |
| `ignore` | Say nothing, and leave the at-rule as written |

Both `warn` and `ignore` leave the original text, and a browser that cannot read `@adaptive` **discards the whole block** — everything inside it disappears. The only difference is whether anyone told you. Canvas names are case-sensitive (they are keys you wrote in `profiles`), so `@adaptive PC` does not find `pc`.

A block-less `@adaptive pc;` warns separately: with no block, nothing is compiled onto that canvas, and it is not rewritten into a `@media`.

### unitToConvert and rootValue

```ts
unitToConvert?: string | readonly string[]   // default 'px'
rootValue?: number                           // default 16
```

By default only `px` is read. An array reads several units at once, which atomic CSS projects need — see [Build tool integration](./integration.md#atomic-css-tailwind-and-unocss):

```js
unitToConvert: ['px', 'rem']
```

There is exactly one conversion rule between units: **`rem` becomes pixels via `rootValue`; every other unit is read at face value.**

`em` is read at face value too, deliberately. `em` is relative to the font size an element inherits, which is only known at runtime, and no build-time constant can stand in for it. Treating `em` as `rem` is correct only where the two happen to be equal — a minority of places in any stylesheet.

`rootValue` governs both ends:

- when reading, how many pixels `1rem` is worth;
- when writing, what the static part of a text size is divided by to become `rem`.

So a page with `html { font-size: 62.5% }` sets `rootValue: 10`, and `3.2rem` and `32px` produce exactly the same output, both correct. Configuring only one end would be wrong at the other, which is why there is no second option here.

The `minPixelValue` and `hairline` thresholds are in **pixels**, not face value. A framework writing a hairline as `0.0625rem` and you writing `1px` are the same line, and `hairline` stops both.

## AdaptiveRoute

```ts
interface AdaptiveRoute {
  profile: string | false
  file?: FileMatcher | FileMatcher[]
  selector?: (string | RegExp) | (string | RegExp)[]
  property?: string | string[]
  media?: MediaMatcher | MediaMatcher[]
}

interface MediaMatcher {
  minWidth?: number
  maxWidth?: number
}
```

Reassigns matching CSS to another canvas; `profile: false` keeps the pixels unconverted. Strings match by "contains" and regular expressions by `test`; `property` matches custom property names by prefix; `media` matches the widths an enclosing `@media` confines the rule to — see [Breakpoints](#breakpoints).

Every channel a route declares must match. To let a class name and a file match independently, write two routes.

Splitting two non-responsive ends by directory is the most common use:

```js
adaptiveMatrix({
  defaultProfile: 'pc',
  profiles: {
    pc:     { designWidth: 1920, fluid: { minWidth: 1280, maxWidth: 2560 } },
    mobile: { designWidth: 750,  fluid: { minWidth: 320,  maxWidth: 600  } },
  },
  routes: [{ profile: 'mobile', file: [/[\\/]mobile[\\/]/] }],
})
```

Both canvases are resolved inside the same plugin instance, so they cannot overwrite each other and you do not need to register the plugin once per end — a piece of CSS is converted exactly once, and the first canvas that matches is the final answer.

Resolution priority, highest first:

1. an enclosing `@adaptive <profile>` — the author has already said so;
2. a matching `property` route;
3. a matching `selector` route;
4. a matching `media` route;
5. a matching `file` route;
6. `defaultProfile`.

A selector beats a file path because the selector is part of the CSS itself, whereas a path only reflects how the build tool happened to arrange files at the time; once a bundler inlines a dependency, the path is gone. The reasoning for property names is the same and stronger: theme tokens are declared on `:root` and leave no trace of their origin beyond their name.

A selector beats a width band for a different reason: a component library is drawn on its own canvas at every viewport width, and a breakpoint does not change which design file the component came from. To override a library's own component *at* a breakpoint, say both — see below.

## Breakpoints

A responsive stylesheet is one file holding two design files. The phone numbers were measured on a 750 mock; the numbers inside `@media (min-width: 1024px)` were measured on a 1440 one. Nothing in the CSS says so, and compiling the whole file against one canvas is not a near miss:

```css
/* defaultProfile 'app': designWidth 750, fluid 320–600 */
@media (min-width: 1024px) {
  .hero { padding: 40px }        /* → clamp(17.07px, 5.33vw, 32px) */
}
```

That rule is only ever live from 1024px up, which is past where the phone canvas stops scaling — so the `clamp()` is already pinned to its maximum everywhere the rule applies. The padding is a constant 32px at every width, forever. The compiler ran, the output looks compiled, and not one value moves.

A `media` route gives the breakpoint the design file it was drawn on:

```js
adaptiveMatrix({
  defaultProfile: 'app',
  profiles: {
    app: { designWidth: 750,  fluid: { minWidth: 320,  maxWidth: 600  } },
    pc:  { designWidth: 1440, fluid: { minWidth: 1024, maxWidth: 1920 } },
  },
  routes: [{ media: { minWidth: 1024 }, profile: 'pc' }],
})
// .hero → clamp(28.44px, 2.78vw, 53.33px)
```

Matching is by **implication, not by text**. `{ minWidth: 1024 }` claims any rule that cannot apply below 1024px, so it matches all of these:

| Query | Band it is live in | Claimed |
| --- | --- | --- |
| `(min-width: 1024px)` | 1024px and up | yes |
| `screen and (min-width: 1200px)` | 1200px and up | yes |
| `(min-width: 64rem)` | 1024px and up | yes |
| `(min-width: 1024px) and (max-width: 1600px)` | 1024–1600px | yes |
| `(min-width: 768px)` | 768px and up | no — it reaches below 1024 |

Nesting is conjunction, so `@media (min-width: 900px) { @media (min-width: 1100px) { … } }` is live from 1100px up and is claimed.

`rem` and `em` resolve at **16px**, not at `rootValue` and not at the root element's font size. A media query is evaluated before any declaration could change `font-size`, so it cannot depend on the cascade it selects — `64rem` is 1024px even in a stylesheet whose `html` is `62.5%`. Utility frameworks write every breakpoint this way.

A query the compiler cannot read — a comma, `not`, `only`, or any non-width feature — is claimed by **nothing**. That is a refusal, not a "matches everything": routing a rule on a condition nobody checked is how a canvas mistake gets made rather than caught. `@container` never counts either; it bounds an element, and `vw` has never been about the element.

To redraw a component library's own component at a breakpoint, name both — a selector route on its own would apply at every width, and a width band on its own loses to the library:

```js
routes: [{ selector: ['.van-'], media: { minWidth: 1024 }, profile: 'pc' }]
```

### The warning you get for free

You do not have to know about any of this to find the problem. When a rule converts a length and its band lies entirely outside its canvas's fluid range, the compiler says so:

```
Every converted length here is a constant: this rule is live from 1024px up, but canvas
"app" stops scaling outside 320px–600px, so its clamp() is pinned to its maximum across
that whole range. The numbers in a breakpoint are usually measured on a different design
file — give it one with a route: { media: { minWidth: 1024 }, profile: '…' }.
```

This is arithmetic, not a heuristic: two numbers that do not overlap. It is reported once per canvas per band per file, and only for rules that actually converted something — a breakpoint that only changes `display` and `color` has no lengths to be constant about.

## libraries

```ts
type LibraryEntry =
  | string                                              // a built-in name
  | LibraryAdaptation                                   // a complete definition
  | (Partial<LibraryAdaptation> & { extends: string })  // adjust a built-in

libraries?: LibraryEntry[] | 'auto' | false
```

Default `'auto'`: every built-in is active, so a project using Vant or Element Plus needs no configuration. `false` turns the whole thing off. Providing an array enables only the listed entries.

Entries expand into routes appended after `routes` — explicit routes always win.

For the built-in list, the matching channels and how to override or extend, see [Component libraries](./libraries.md).

## Profile

```ts
interface AdaptiveProfile {
  designWidth: number | ((context: { file: string; profile: string }) => number)
  fluid: { minWidth: number; maxWidth: number }
  query?: string | {
    type?: 'media' | 'container'
    condition: string
    name?: string
  } | false
  unit?: 'vw' | 'vi' | 'cqw' | 'cqi'
  strategy?: 'clamp' | 'viewport'
  fontFluidity?: number
  textAnchorWidth?: number | ((context: { file: string; profile: string }) => number)
  rootMaxWidth?: number
}
```

`query: false` removes the `@adaptive` wrapper but keeps the rules inside it, which suits building separate artifacts with the profile chosen by environment.

`textAnchorWidth` defaults to `designWidth` and affects text only: text keeps a fixed `rem` component (so browser zoom keeps working), and a fixed length only means something relative to some width. A hand-written canvas anchoring to its own design width is correct; but when two canvases describe **the same design in two sets of units** (a library drawn on 375, pages drawn on 750, where Vant's 16px is the page's 32px), anchoring each to itself leaves the two misaligned at every viewport. Library canvases therefore always inherit the anchor of the profile they belong to, with nothing to configure. For the reasoning and the measurements see [Which canvas the static part anchors to](./architecture.md#which-canvas-the-static-part-anchors-to).

## RootFoundationOptions

```ts
interface RootFoundationOptions {
  selector: string
  center?: boolean
  container?: boolean
  containerName?: string
  safeAreaVariables?: boolean
  layer?: string | false
  logical?: boolean
  fixedContainingBlock?: boolean
  injectTo?: FileMatcher | FileMatcher[]
}
```

No global styles are injected by default. This is enabled only by configuring `root` explicitly or passing `rootSelector` to `appPcPreset`.

### injectTo

Limits which files receive the foundation; by default, all of them.

The foundation is global, but PostCSS only ever sees one file at a time and cannot deduplicate across files. A single-stylesheet project wants the default; in a Vue or Svelte project every component's `<style>` block is a separate file, so the default becomes one copy per component.

```js
root: { selector: '#app', injectTo: 'src/styles/main' }
```

Matching works exactly like `include`: a string matches by "contains", a regular expression tests the path, and a function decides for itself. The `appPcPreset` field is `rootInjectTo`.

A pattern that matches nothing is not an error — it just injects nothing. Use the [CLI preview](./cli.md) to confirm the added declarations appear in the entry file.

### logical

Default `true`: the foundation is written with logical properties — `inline-size`, `margin-inline`, `max-inline-size`.

Set it to `false` and it writes `width`, `margin-left` / `margin-right` and `max-width` instead. The two are equivalent on a horizontal page, so this switch has exactly one purpose: **a fallback for browsers that cannot read logical properties** (below Safari 15 / iOS 15.0 / Chrome 89).

It deserves its own switch because it is the only syntax this plugin emits whose failure still leaves a page that looks fine: without `margin-inline: auto` the column is exactly the right width and sits against the left edge of the screen; without `max-inline-size` it goes full-bleed. Neither looks like a fault. For the complete failure list and the degradation path for each, see [Browser support and degradation](./compatibility.md).

The `appPcPreset` field is `rootLogical`; likewise `rootLayer`, which passes through to `layer`.

### fixedContainingBlock

When a profile sets `rootMaxWidth`, the page becomes a centred column, and `position: fixed` falls back to the viewport as its containing block — the fixed element sticks to the window edges, out of line with the content column it belongs to.

Enabled, the compiler publishes two variables:

| Variable | Meaning |
| --- | --- |
| `--adaptive-root-width` | The root column width at the current breakpoint, or `100vw` with no ceiling |
| `--adaptive-root-gutter` | `max(0px, (100vw - column width) / 2)`, i.e. the gutter on one side |

and does three things to rules that themselves declare `position: fixed`:

- `left` / `right` / `inset-inline-*` become the gutter when they are `0`, and `calc(original + gutter)` when they are not; `auto` is left alone;
- `width` / `inline-size` and friends become `min(100%, column width)` when they are `100%`;
- the block axis (`top` / `bottom`) is untouched — a centred column only constrains the inline axis.

When the column equals the viewport, the gutter is `0`, so narrow-screen output is identical to what you would have written by hand. The correction is idempotent and does not reprocess a value that already contains these variables.

Only the rule's own `position` declaration is considered: inheriting positioning from elsewhere is not something CSS allows you to observe statically, and guessing would be worse than missing.

It is on by default when `appPcPreset` is given a `rootSelector` — both of that preset's profiles set `rootMaxWidth`, which is exactly the configuration where the problem appears. Turn it off with `appPcPreset({ rootSelector: '#app', fixedContainingBlock: false })`.

## Legacy WebView mode

```js
adaptiveMatrix({
  ...appPcPreset(),
  strategy: 'viewport',
  preserveOriginal: true,
})
```

This emits the original `px` followed by the `vw`. Whether to use it should be decided by your real target browsers; modern projects should prefer the default `clamp`.

"Real target browsers" does not have to be a guess — `npx adaptive-matrix src/app.css --targets "ios_saf 13, chrome 90"` lists every piece of syntax in the output beyond your targets, along with what is lost when it is unsupported and the switch that turns it off. See [Browser support and degradation](./compatibility.md).


---

<!-- source: docs/architecture.md -->

# Architecture and formulas

**English** · [简体中文](./architecture.zh-CN.md)

Where the numbers come from, and what the compiler deliberately does not do. For a quick option lookup see the [Configuration reference](./configuration.md).

## The pipeline

1. On initialisation, `libraries` is expanded into routes appended after `routes`.
2. `include` / `exclude` are applied by file path.
3. Each rule's canvas is resolved, with the priority given in the [Configuration reference](./configuration.md#adaptiveroute): `@adaptive` > property route > selector route > file route > `defaultProfile`.
4. Declarations are walked over the PostCSS AST, with properties and values passing through the filters.
5. Values are parsed with `postcss-value-parser`, skipping strings and URL functions.
6. Target lengths are converted into bounded fluid expressions.
7. Once a rule's declarations are done, if `fixedContainingBlock` is enabled and the rule itself declares `position: fixed`, its inline-axis insets and width are corrected.
8. `@adaptive` is rewritten as `@media` or `@container`.
9. If explicitly enabled, the low-priority root foundation layer is appended last.

Step 7 comes after step 6, so what it wraps is the converted fluid value rather than the original pixels.

## Ordinary lengths

Let the design width be `D`, the design value `P`, and the fluid lower and upper bounds `L` and `U`.

```text
preferred = P / D × 100vw
minimum   = P × L / D px
maximum   = P × U / D px
result    = clamp(minimum, preferred, maximum)
```

Negative numbers reorder the bounds, so `clamp()`'s minimum is always below its maximum.

### Monotonicity

With `D`, `L` and `U` positive, the **absolute value** of the expression above is non-decreasing in viewport width: inside the range it follows linearly with the sign of `P`, outside it is constant, and it never changes sign.

For positive `P` that is simply "non-decreasing". For negative `P` the formula is non-increasing — `-16px` on a 375 file compiles to `clamp(-20.48px, -4.26667vw, -13.65333px)`, whose value drops as the viewport widens. Negative lengths (negative margins, bleeds, reverse offsets) grow by moving away from zero, so the quantity that is actually conserved is the absolute value, not the signed number.

That property has one direct use: nothing in the output where "the viewport widens and the absolute size gets smaller" can come from the formula itself. It can only come from a canvas change across a breakpoint — two design files giving contradictory numbers for the same element. The CLI uses this for its seam check (see [Going backwards at a breakpoint](./cli.md#going-backwards-at-a-breakpoint)), and the check is complete for this class of problem: it cannot escape to some other width.

Comparing absolute values is not a detail. The first version of the check compared signed numbers, and was therefore inverted for every negative length: a desktop file asking for a deeper bleed got reported, while a bleed that nearly vanished at the breakpoint did not.

## Text lengths and accessibility

Text in plain `vw` cannot respond adequately to browser text zoom. Let `F` be `fontFluidity`:

```text
preferred = P × (1 - F) rem-part + P × F / D × 100vw
```

The static part and both bounds use `rem`; the fluid part uses `vw`/`cqi`. The default `F = 0.35` is still exactly the design value at the design width, while balancing window changes against browser zoom.

Using `rem` for the bounds too is the crucial step. When the user raises the default font size, the fluid part does not follow but the lower bound does — so at high zoom levels `clamp()` lands on its lower bound, the formula degenerates to pure `rem`, and zoom is fully effective again.

Measured in Chrome (375px viewport, default configuration, `font-size: 16px`):

| Root font size | Actual body size | Relative |
| --- | --- | --- |
| 16px | 16.00px | 100% |
| 20px | 18.97px | 119% |
| 24px | 22.77px | 142% |
| 32px | 30.36px | 190% |

In the same set of measurements, `width` and `padding` stayed at 343px / 16px throughout — only the text responds to zoom, layout sizes do not inflate with it.

These numbers cover one cross-section of the default configuration. Projects should still run WCAG 200% zoom acceptance; a compilation formula is no substitute for real accessibility testing.

### Which canvas the static part anchors to

`P × (1 - F)` is a fixed length that does not vary with the viewport, so it only means something relative to **some width**. By default that is the profile's own design width: 16px on a 1440 file is 16px at 1440, exactly as written.

Library canvases are different. Vant is drawn on 375 and the page on 750, and the two describe **the same design in two sets of units** — Vant's 16px and the page's 32px are the same size. If each anchored to its own canvas, the two `rem` parts would differ by a factor of two and never line up at any viewport:

```text
page 32px on 750  → clamp(1.59867rem, calc(1.3rem  + 1.49333vw), 1.86rem)
Vant 16px on 375  → clamp(0.94867rem, calc(0.65rem + 1.49333vw), 1.098rem)   ← before the fix
```

The fluid term `1.49333vw` is already identical on both sides (`P × F / D` cancels proportionally with the canvas); the whole difference is in the static term. Measured at a 390px viewport: 26.62px for the page, 16.22px for Vant — Vant's text about 40% too small, in a pairing that is extremely common on mobile.

So the static part anchors to `textAnchorWidth`, and a library canvas always inherits the anchor of the profile it belongs to. The implementation is equivalent to "convert the length into the anchor canvas's units first, then apply the formula as usual":

```text
P_anchor = P × A / D          A = textAnchorWidth
preferred = P_anchor × (1 - F) rem-part + P_anchor × F / A × 100vw
```

The fluid term is entirely unchanged (`P_anchor × F / A ≡ P × F / D`); only the static term is normalised. For non-text lengths `F = 1`, the static term is always 0, and the output is byte-for-byte unchanged — which also explains why only text was misaligned before, while `padding` was always correct.

`textAnchorWidth` can also be set explicitly on a profile, for hand-written canvases with the same relationship between them.

## Container queries

When a profile's `query.type` is `container`, `@adaptive` emits `@container`. You normally set `unit` to `cqi` at the same time, so component sizes depend on their own container rather than the browser window.

The container must be established by the application's existing layout or by `root.container`. Do not let an element query itself; choose a stable ancestor container for a reusable component.

## What is never converted

- `url()`, `local()`, `format()`;
- quoted strings;
- `clamp()`, `min()`, `max()` that already contain a viewport or container unit — see below;
- declarations inside `@font-face`, `@page`, `@property`, `@counter-style` — those describe a resource or a page box, not an element. A print margin turned into `vw` is not the same margin;
- CSS custom properties by default (except those claimed by a library `tokenPrefix` — being claimed is itself the switch);
- values below `minPixelValue`;
- absolute values at or below `hairline`;
- anything excluded by a filter or a comment.

## Idempotence

Inside `clamp()` / `min()` / `max()`, as soon as a viewport or container unit is present, the `px` in there is left alone.

Such an expression is **an already-written bounded fluid value** — possibly by the author, possibly by this plugin on a previous pass. Its `px` are that expression's own bounds, not a size measured off a design file, and converting again means scaling twice.

The direct result is idempotent output: the same CSS run once and run three times gives identical results. Neither the plugin being registered twice in a PostCSS chain, nor a component library that was pre-compiled and then compiled again by its consumer, produces nested clamps.

The scope is deliberately limited to those three functions. `calc(100vw - 32px)` converts as usual — that `32px` really is a design-file size that simply happens to sit next to a viewport unit.

Idempotence covers two more things beyond length conversion:

- **Ignore comments survive into the output.** An ignored `40px` and a `40px` nobody ever looked at are indistinguishable, so if the comment were dropped, the second pass would convert it. Any minifier removes the comments, and an author's "don't touch this" has to survive more than one pass.
- **The root foundation is injected only once.** The output carries a `/* postcss-adaptive-matrix foundation */` marker, and a second pass that sees it skips the whole section — so a fixed ceiling like `max-inline-size: 480px` is never mistaken for a design-file size and scaled again, and no second copy is stacked on.

The conformance suite asserts this for **every** case: recompiling the output must return it unchanged.

## Nesting

In native CSS nesting, declarations inside `@adaptive` and inside conditional group rules (`@media`, `@supports`, `@layer`, `@container`, `@scope`, `@starting-style`) belong to the outer element and convert as usual:

```css
.card {
  padding: 16px;          /* default canvas */

  @adaptive pc {
    padding: 32px;        /* pc canvas, rewritten as @media */
  }
}
```

Inside an at-rule the plugin does not know, nested **rules** are still processed but **direct declarations** are not — treating them as element styles in an unknown context would be guessing.

## The limits of the fixed correction

`fixedContainingBlock` is the one place the compiler rewrites positioning, and it is deliberately narrow:

- it must be enabled explicitly (`appPcPreset` enables it when it establishes a centred column, because that is exactly the configuration where the problem appears);
- it only handles a rule that **itself** declares `position: fixed`. Inherited positioning from another rule cannot be observed statically, and guessing from selector combinations would create hidden runtime coupling;
- it only handles the inline axis;
- it only substitutes on unambiguous shapes such as `0` or `100%`, adding with `calc()` otherwise, and it is idempotent.

Beyond that, the compiler does not guess at design intent, does not move sidebars for you, and injects no JavaScript. Complex layouts belong in CSS Grid, Flexbox, container queries and explicit rules per end.


---

<!-- source: docs/runtime.md -->

# Optional runtime

**English** · [简体中文](./runtime.zh-CN.md)

The compiler itself emits no JavaScript at all. This module is a separate entry point, **not needed by default**, and is only worth importing when CSS viewport units disagree with the area the user can actually see.

```js
import { observeAdaptiveViewport } from 'postcss-adaptive-matrix/runtime'

const observer = observeAdaptiveViewport()
// when the component unmounts or the page is left
observer.destroy()
```

## When you need it

CSS `vw` / `vh` refer to the **layout viewport**, which browsers deliberately hold still when the on-screen keyboard appears or the page is pinch-zoomed. Most of the time that is the right behaviour. In a few situations it is not:

| Situation | What you see |
| --- | --- |
| A mobile keyboard opens | `100vh` is still the full screen height, and the bottom button is behind the keyboard |
| The user pinch-zooms | Viewport units do not change, and fixed elements drift off screen |
| The iOS Safari address bar collapses or expands | `100vh` differs from the visible height by one address bar |
| A WebView / Capacitor / Tauri shell | The host's visible area does not match the layout viewport |

All of that is information only `VisualViewport` can see, and CSS cannot reach. This observer reads it and writes it out as CSS variables.

## The variables it publishes

Written to `document.documentElement` after the call (changeable with `target`):

| Variable | Meaning |
| --- | --- |
| `--adaptive-width` | Visible width (a bare px number, no unit) |
| `--adaptive-height` | Visible height |
| `--adaptive-layout-height` | Layout viewport height, i.e. `window.innerHeight` |
| `--adaptive-keyboard-height` | Height obscured by the keyboard, `0` when there is none |
| `--adaptive-scale` | The current pinch-zoom factor |
| `--adaptive-vh` | 1% of the visible height, **with a px unit** |
| `--adaptive-vw` | 1% of the visible width, **with a px unit** |

The first five are bare numbers, so using them in arithmetic means adding the unit yourself (`calc(var(--adaptive-keyboard-height) * 1px)`); the last two already carry a unit and can be used directly as replacements for `vh` / `vw`.

## Typical use

A true full-screen height, unaffected by the address bar:

```css
.screen {
  min-block-size: calc(var(--adaptive-vh, 1vh) * 100);
}
```

The `1vh` fallback matters — with the runtime not loaded, or on the SSR first paint, the style still holds.

A bottom action bar that avoids the keyboard:

```css
.action-bar {
  position: fixed;
  inset-block-end: calc(var(--adaptive-keyboard-height, 0) * 1px);
}
```

## Options

```ts
observeAdaptiveViewport({
  prefix: 'adaptive',        // variable prefix, with or without the leading --
  target: document.documentElement,
  window: globalThis.window, // inject for multi-window setups or tests
  document: globalThis.document,
})
```

Returns:

```ts
interface AdaptiveViewportObserver {
  update(): AdaptiveViewportSnapshot | null   // trigger a read manually, returns this reading
  destroy(): void                             // remove every listener
}
```

## SSR

With no `window` the constructor does not throw; the returned observer does nothing and `update()` returns `null`. So it can be called unconditionally at module top level, with no `if (typeof window !== 'undefined')` wrapper.

But the server-rendered first paint will not have these variables, so **write a fallback everywhere you use one**, or the first frame gets an empty value.

## Cost

Updates are coalesced through `requestAnimationFrame`, so it writes at most once per frame, and every listener is `passive`. Not using it costs nothing — it is a separate entry point and is never pulled into the main bundle.


---

<!-- source: docs/compatibility.md -->

# Browser support and degradation

**English** · [简体中文](./compatibility.zh-CN.md)

The compiler emits more than numbers. `clamp()` is syntax, `@layer` is syntax, and so are `:where(#app)`, `env(safe-area-inset-top)` and `inline-size` — each with its own support threshold, and those thresholds span nearly a decade.

This page lists every threshold, and answers the same question for each one: **when it is unsupported, what disappears, and what switching it off costs.**

## CSS does not error, it discards

That is the premise of this whole page. A browser that meets CSS it cannot read does not throw, does not fall back to the previous value, and leaves nothing in the console. It treats the part it cannot read **as if it had never been written**. How much is discarded depends on which layer the unreadable thing is in:

| What it cannot read | What is voided | Example |
| --- | --- | --- |
| A value | That declaration | `padding: clamp(...)` → the element has no padding |
| A selector | That whole rule | `:where(#app) { ... }` → every declaration of the root container |
| An at-rule | Everything in that block | `@layer { ... }` → the entire root foundation |

So the order to work through is not "which feature is newest" but **how much is lost**. That is the order below, and the order of the `COMPAT_FEATURES` table in the code.

## Minimum versions

| Feature | Chrome | Edge | Safari | iOS Safari | Firefox | Samsung |
| --- | --- | --- | --- | --- | --- | --- |
| `@layer` | 99 | 99 | 15.4 | 15.4 | 97 | 18.0 |
| `:where()` ¹ | 88 | 88 | 14 | 14.0 | 78 | 15.0 |
| `:has()` ³ | 105 | 105 | 15.4 | 15.4 | **121** | 20 |
| `@container` / `container-type` | 106 | 106 | 16.0 | 16.0 | 110 | 20 |
| `clamp()` `min()` `max()` | 79 | 79 | 13.1 | 13.4 | 75 | 12.0 |
| `cqw` / `cqi` | 105 | 105 | 16.0 | 16.0 | 110 | 20 |
| `vi` ² | 108 | 108 | 15.4 | 15.4 | 101 | 21 |
| `inline-size` / `margin-inline` | 89 | 89 | 15 | 15.0 | 66 | 15.0 |
| `var()` | 49 | 16 | 10 | 10.0 | 31 | 5.0 |
| `env(safe-area-inset-*)` | 69 | 79 | 11.1 | 11.3 | 65 | 10.1 |
| `vw` | 26 | 16 | 6.1 | 8 | 19 | 4 |
| Native nesting ³ | 120 | 120 | 17.2 | 17.2 | 117 | 25 |

¹ caniuse has no separate entry for `:where()`, so this uses `:is()`. Not a stand-in of convenience: both come from the same section of the specification and shipped together in Chrome 88, Firefox 78 and Safari 14.
² Likewise, `vi` uses the `svh` / `lvh` / `dvh` entry — same spec batch, same releases.
³ Neither `:has()` nor native nesting is **emitted** by the compiler; both are listed because they reach your output through your own CSS or a component library, and shipping them is still shipping them. Nesting cannot be detected without guessing, so it is not; `:has()` can, so it is. See below.

Read that `:has()` row across rather than down. Chrome had it in 2022 and Safari before that, and Firefox did not until the end of 2023 — the widest gap in the table between the first browser and the last. It is the one row where a stylesheet can look completely correct in three browsers while losing whole rules in the fourth.

Data from caniuse-lite `1.0.30001809`, baked into `src/core/compat-data.ts` by `scripts/capture-compat.mjs`.

## Feature by feature: what is lost, how to switch it off

### `@layer` — the biggest single loss

**What emits it**: `root.layer`. `appPcPreset` sets it to `'adaptive-matrix'` whenever a `rootSelector` is given.

**What is lost**: the entire `@layer` block is voided, so the root foundation goes **all at once** — the centred column, the safe-area variables and the fixed-position correction disappear together. This is the largest single loss in the table.

**How to switch it off**: `root: { layer: false }` emits the same rules unwrapped. The cost is cascade position: the foundation used to lose to your own CSS automatically by sitting in a lower layer, and without that it competes at ordinary specificity. Places you used to override casually may now need a real selector.

### `:where()`

**What emits it**: every rule of the root foundation, with `root.selector` wrapped inside it.

**What is lost**: an unreadable selector voids the whole rule — the same outcome as losing `@layer`, just one rule at a time.

**How to switch it off**: `root: false`, removing the foundation entirely. Blunt, but it is the supported path. There is no option to emit a bare selector, because **zero specificity is the entire reason it is there**: it lets your CSS override the foundation without a specificity fight. Offering that switch would be offering a switch that silently changes cascade behaviour.

### `:has()`

**What emits it**: nothing here. It arrives from your own CSS or from a component library, survives the pass untouched, and ships.

**What is lost**: the whole rule, like any unreadable selector. What makes it worth its own row is not the size of the failure but *when* support arrived. `:has()` is the newest selector in everyday use, and the four engines are years apart on it — Chrome 105 in August 2022, Safari 15.4 before that, Firefox not until 121 in December 2023. A stylesheet that has been reviewed in Chrome and Safari can be silently missing rules in an older Firefox.

**How to switch it off**: not a switch — a rewrite. Express the condition on the element itself: a class the component already sets when it has the child, or `:not(:empty)` where that is what `:has(*)` was standing in for.

Routing is not affected either way. A `:has()` argument names what an element *contains*, not which design file it was drawn on, so it is removed before a rule's canvas is decided — `.page-card:has(.van-icon)` is a page card, whatever it happens to hold. See [Component libraries](./libraries.md#what-a-selector-is-about).

### `@container` and the container units `cqw` / `cqi`

**What emits it**: `root.container: true`; a profile with `query: { type: 'container' }`; `unit: 'cqw'` or `'cqi'`.

**What is lost**: the `container-type` declaration is voided, which is quiet; an `@container` block is voided entirely, which is not — a profile that switches on a container query stops switching, and every canvas other than the default disappears. Container units behave like `clamp()`: they take their declaration with them.

**How to switch it off**: `root: { container: false }`, a profile query using `type: 'media'`, and `unit` back to `'vw'`. A media query measures the viewport rather than an ancestor — and unless the component really does reflow independently inside a draggable panel, the viewport was what you wanted anyway.

### `clamp()` / `min()` / `max()`

**What emits it**: every converted length under `strategy: 'clamp'` (the default), plus the gutter arithmetic in `root.fixedContainingBlock`.

**What is lost**: every declaration containing one is voided, and the property falls back to its inherited or initial value. Not "the size is a bit off" — **no size at all**.

**How to switch it off**: two options, which stack.

```js
adaptiveMatrix({
  ...appPcPreset(),
  strategy: 'viewport',    // bare vw, with no bounds
  preserveOriginal: true,  // keep an original px declaration in front
})
```

`strategy: 'viewport'` switches to bare viewport lengths, supported almost everywhere, at the cost of having no bounds — the design scales straight past both ends of the fluid range. `preserveOriginal` is the other half: the original pixel value is kept as a preceding declaration, so a browser that drops the fluid one lands on the design-file size rather than on nothing.

### Logical properties `inline-size` / `margin-inline` / `max-inline-size`

**What emits it**: the root foundation, whenever `root` is configured.

**What is lost**: one declaration at a time. **This is the only entry in the table whose failure still looks like a working page**: without `margin-inline: auto` the column is exactly the right width, sitting firmly against the left edge of the screen; without `max-inline-size` it goes full-bleed. Neither looks like "unsupported" — both look deliberate. And precisely because it does not look like a fault, it is likelier to ship than a visible collapse like `@layer`.

**How to switch it off**: `root: { logical: false }` writes `width`, `margin-left` / `margin-right` and `max-width` instead. Nothing is lost on a horizontal page — the two spellings are the same thing until the writing mode changes.

```js
appPcPreset({ rootSelector: '#app', rootLogical: false })
// or
adaptiveMatrix({ root: { selector: '#app', logical: false } })
```

### `vi`

**What emits it**: `unit: 'vi'`.

**What is lost**: the declaration is voided.

**How to switch it off**: `unit: 'vw'` (the default). `vi` follows the writing mode, and the two differ only with vertical text or a rotated root element; on a horizontal page they measure the same length, and `vw` has been there since Safari 6.1.

### `env(safe-area-inset-*)`

**What emits it**: `root.safeAreaVariables`.

**What is lost**: this one is worth stating precisely, because the fallback argument does something other than what it looks like. The `0px` in `env(safe-area-inset-top, 0px)` covers the case where **the browser knows the environment variable but has no value for it** — not the case where the browser has never heard of `env()`. In the latter, `--adaptive-safe-top` holds an unreadable value, and every declaration reading it through `var()` is voided together at computed-value time.

**How to switch it off**: `root: { safeAreaVariables: false }`. Every browser without `env()` also predates the notches it exists to avoid — there is nothing to compensate for.

### `var()`

**What emits it**: `root.safeAreaVariables` and `root.fixedContainingBlock`, plus any design tokens of your own that pass through the compiler.

**What is lost**: the declaration is voided.

**How to switch it off**: `safeAreaVariables: false` + `fixedContainingBlock: false` removes the ones the compiler introduces. Supported since Safari 10 / Chrome 49, so this row is usually there to be ticked rather than acted on.

### `vw`

**What emits it**: `unit: 'vw'` (the default), and the root column arithmetic.

**What is lost**: the declaration is voided.

**How to switch it off**: you cannot, and you do not need to. This is the oldest entry in the table (Safari 6.1, 2013), older than every other row. Switching it off means not adapting at all.

### Native nesting

**What emits it**: nobody. The compiler **reads** nested rules — including an `@adaptive` nested inside one — and writes each declaration back where it was. Nesting in your output can only be there because it was in your source.

**What to do**: flatten it before shipping. Sass and Less already do; plain CSS has postcss-nesting. The audit **deliberately does not guess**: pattern-matching native nesting would misread ordinary CSS as nested, and a false report is worse than no report.

## The whole audit in one command

Give `--targets` a list of "browser + the oldest version you intend to support":

```bash
npx adaptive-matrix src/app.css -c adaptive.config.mjs --targets "ios_saf 13, chrome 90"
```

```
  needs @layer — iOS Safari 13 < 15.4, Chrome 90 < 99
          from: root.layer, which appPcPreset sets to 'adaptive-matrix' whenever a rootSelector is given
          seen: @layer adaptive-matrix { :where(#app) {
          if unsupported: The whole @layer block is dropped, so the entire root
          foundation goes with it — the centred column, the safe-area variables
          and the fixed-position correction all vanish at once.
          instead: root.layer: false emits the same rules unwrapped. ...
  needs :where() — iOS Safari 13 < 14.0-14.4
  needs clamp(), min(), max() — iOS Safari 13 < 13.4-13.7
  needs inline-size, margin-inline, max-inline-size — iOS Safari 13 < 15.0-15.1
```

(That is the real output for this repository's `examples/app-pc`, with only the long sentences truncated. Note the `clamp()` line: iOS Safari 13 misses by a point release, not a major one — 13.4 has it. That is exactly the gap the eye skips when comparing version numbers by hand.)

When every target is new enough there is one line:

```
  every target reads all 7 CSS features in this output
```

Known names: `chrome`, `edge`, `safari`, `firefox`, `ios_saf`, `samsung`; `android` and `webview` map to `chrome` (which is what they run anyway). An unrecognised name **is an error and exits 1** rather than being skipped silently — a target quietly dropped is worse than no audit at all, because it reads like a pass.

### The audit reads the output, not the configuration

That is the only way to guarantee the audit and the output never drift apart. A feature that reaches the stylesheet through a preset, through a component-library route, or through your own hand-written CSS is a feature you shipped, and reading the output sees all of them. There is far too much that cannot be read out of a configuration.

## Failing the build

The same checks are exported from the package, without going through the CLI:

```js
import postcss from 'postcss'
import adaptiveMatrix, { auditCompatibility } from 'postcss-adaptive-matrix'

const result = await postcss([adaptiveMatrix(options)]).process(css, { from })
const audit = auditCompatibility(result.root.toString(), {
  ios_saf: 13,
  chrome: 90,
})

if (audit.unknownBrowsers.length) throw new Error('a target name is misspelled')
for (const { feature, shortfalls } of audit.findings) {
  console.error(feature.title, '→', shortfalls.map((s) => `${s.name} ${s.target} < ${s.since}`))
}
if (audit.findings.length) process.exit(1)
```

`auditCompatibility(css, targets)` returns `{ findings, satisfied, unknownBrowsers }`. Also exported: `detectFeatures(css)` (features only, no version comparison), `COMPAT_FEATURES` (the full feature table, where the `failure` and `fallback` prose lives), `FEATURE_SUPPORT` (the version data) and `compatFeature(id)`. Fully typed.

## What the data is, and is not

**The versions are baked into the package; caniuse-lite is only a devDependency.** "Which version a feature became usable in" is history and will not change again, so the plugin needs no runtime dependency for it and the audit works offline.

**Usage share is deliberately not consulted.** Whether 0.4% of users count is a decision about your project, not a fact about this stylesheet. `browserslist` is already the place that answers that question.

**`--targets` takes explicit "name + version" pairs, not a browserslist query.** A query would pull in the browserslist package, answers a question about your users rather than about this stylesheet, and — crucially — **the same query changes meaning as the database updates**: a build that passes today goes red next month on a data refresh, with not one character of code changed. Explicit version numbers do not do that.

**It scans for the version from which support was never lost again**, not the first version showing a `y`. A few features shipped and were then withdrawn, and the former is the answer to "safe from this version on". A caniuse range such as `13.4-13.7` is a span it does not track separately, and the audit takes the low end.

## This is not a substitute for real devices

To be clear about what this audit proves: **every target browser can parse every piece of syntax in this CSS.** That is all.

It does not prove the page looks right on that device. Real devices test something else — rendering differences, the keyboard pushing the viewport up, the height jump when the address bar collapses, a WebView's custom behaviour. The [optional runtime](./runtime.md) has patches for those, but that is a different problem.

Conversely, real devices cannot test version thresholds either: the iPhone on your desk runs iOS 17, and the fact that it reads `@layer` says nothing about iOS 15.4 and below. Testing that needs a cupboard of old devices rather than one good one. The audit does exactly that half — and does it more completely than a cupboard would.

## Related

- [Configuration reference](./configuration.md) — the full semantics of every switch above
- [CLI preview](./cli.md) — `--targets` and the rest of the options
- [Optional runtime](./runtime.md) — keyboards, address bars, WebViews
- [Release and compatibility](./release.md) — artifact formats and Node versions


---

<!-- source: docs/migration.md -->

# Migration guide

**English** · [简体中文](./migration.zh-CN.md)

Migrating from any "convert px to viewport units" setup follows the same steps: get the output to line up first, then enable the new capabilities one at a time. Map concepts rather than hunting for an identically named option.

## Step one: swap in the equivalent only

Introduce no new features yet; get the new output as close to the old as possible:

```js
adaptiveMatrix({
  defaultProfile: 'app',
  profiles: {
    app: {
      designWidth: 375,     // your old viewport base width
      fluid: { minWidth: 320, maxWidth: 480 },
      query: false,         // do not generate a media query wrapper
    },
  },
  precision: 5,             // your old decimal places
  strategy: 'viewport',     // plain vw, the same shape as before
  libraries: false,         // component-library adaptation off for now too
})
```

`strategy: 'viewport'` emits unbounded `vw`, byte-comparable with a traditional setup. At this point the only differences should be rounding.

## Step two: map the concepts

| What you used to configure | Where it lives here |
| --- | --- |
| Design file width / viewport base width | a profile's `designWidth` |
| Decimal places | `precision` |
| Output unit | `unit`, or a profile's `unit` |
| Property allow/deny list | `propList` (supports `*` and `!`) |
| Selector blacklist | `selectorExclude` |
| Value blacklist | `valueExclude` |
| Minimum pixel value to convert | `minPixelValue` |
| File include/exclude | `include` / `exclude`, which also accept functions |
| Keep the original declaration as a fallback | `preserveOriginal: true` |
| Root container selector | `root.selector` |
| Maximum desktop display width | `fluid.maxWidth` + `rootMaxWidth` |
| Ignore comments | `adaptive-ignore` / `adaptive-ignore-next` / `adaptive-ignore-rule` |

Two things need a different idea rather than a different name:

**Landscape is not a global switch.** Create a landscape profile with an explicit media query, and landscape gets its own design width and scaling range instead of a ratio derived from portrait.

**Desktop width is not a design width.** If desktop is just the mobile version centred, it has no design file of its own: use the app profile with `rootMaxWidth`. If desktop has its own design file, give it its own `designWidth` and put the differences in `@adaptive pc`. Those two used to be expressed by the same option; here they are two different structures.

## Step three: enable the rest

Once the visuals match, turn things on in order:

1. Put `strategy` back to the default `clamp` — sizes gain a floor and a ceiling, and stop growing without limit on a large screen;
2. Remove `query: false`, or switch to `appPcPreset` to bring in a desktop profile;
3. Drop `libraries: false`, so component libraries adapt on their own canvases (see [Component libraries](./libraries.md)). This step usually lets you delete the entire ignore list your old setup needed for them;
4. Configure `root` when you want a centred column, and `fixedContainingBlock` handles fixed-position elements along with it.

## Acceptance

- Keep the old output as a visual baseline;
- Cover 320, 375, 480, 768, 1024, 1440, 1920;
- Check fixed/sticky elements, modals, third-party components and input methods;
- Run 200% browser zoom and keyboard navigation tests — the text hybrid formula pays off exactly there, and only a real test verifies it.


---

<!-- source: docs/release.md -->

# Release and compatibility

**English** · [简体中文](./release.zh-CN.md)

## The release gate

```bash
npm ci
npm run check
npm run pack:check
```

`check` must pass TypeScript, coverage, the tests and the ESM/CJS build together. The coverage gate is 80% for lines/functions/statements and 75% for branches.

## Artifacts

- `dist/index.js` / `dist/index.cjs`: the PostCSS plugin, the presets and the type helpers;
- `dist/runtime.js` / `dist/runtime.cjs`: the optional VisualViewport observer;
- matching `.d.ts` files and sourcemaps.

## Browser policy

The compiler runs on Node.js; browsers only ever receive CSS. The default output depends on `clamp()`, and container profiles additionally depend on container query units. Sacrificing modern capabilities for every user in the name of a hypothetical old environment is not recommended.

Whether your real target browsers can read your output does not have to be estimated:

```bash
npx adaptive-matrix src/app.css -c adaptive.config.mjs --targets "ios_saf 13, chrome 90"
```

Every piece of syntax in the output beyond your targets is listed, along with what is lost when it is unsupported and the switch that turns it off. For the full feature × version matrix see [Browser support and degradation](./compatibility.md).

## Versioning policy

- patch: fixes to conversion, types or documentation, with no change to default output semantics;
- minor: new optional profiles, strategies or runtime variables;
- major: a change to the default formula, the directives, the output order, or the minimum runtime.


---

<!-- source: docs/agents.md -->

# Documentation for agents

**English** · [简体中文](./agents.zh-CN.md)

Most of the people who read this documentation next will not be people. A coding agent asked to wire this plugin into a project fetches one or two URLs and works from whatever is at them — it does not browse a sidebar, and it does not benefit from a search box. So the same documentation is published a second time in shapes a model can consume directly, generated from the same sources as the pages you are reading, which is what stops the two from drifting apart.

Everything below is a plain `GET`. Nothing needs a key, a session, or JavaScript.

## The entry point

| URL | What it is |
| --- | --- |
| [`/llms.txt`](https://moresyl.github.io/postcss-adaptive-matrix/llms.txt) | A curated index: one line per page, with a sentence on why you would open it |
| [`/llms-full.txt`](https://moresyl.github.io/postcss-adaptive-matrix/llms-full.txt) | Every page concatenated in reading order, for a model with the context window to spare |
| [`/zh/llms.txt`](https://moresyl.github.io/postcss-adaptive-matrix/zh/llms.txt) | The same index in Chinese |
| [`/zh/llms-full.txt`](https://moresyl.github.io/postcss-adaptive-matrix/zh/llms-full.txt) | The same full text in Chinese |

Both follow the [llms.txt](https://llmstxt.org) convention. Start with `llms.txt` — it is about 3 KB — and fetch the two pages the task actually needs. `llms-full.txt` is roughly 150 KB and is the right choice only when the task is open-ended.

## Any page, as Markdown

Every page is served as its own source. Append `.md` to the page's path:

```
https://moresyl.github.io/postcss-adaptive-matrix/docs/configuration.md
https://moresyl.github.io/postcss-adaptive-matrix/zh/docs/configuration.md
```

A directory index is `index.md` — `/docs/` is `/docs/index.md`. This is the same file the repository holds, not a rendering of it turned back into text: no navigation, no theme, no code-block chrome to strip.

Three buttons above the outline on every page use this: **Copy as Markdown**, **View raw Markdown**, and **Ask Claude**, which opens the page in a conversation with the question already attached.

## Every option, as data

```
https://moresyl.github.io/postcss-adaptive-matrix/schema/options.json
```

A [JSON Schema](https://json-schema.org/) draft 2020-12 document covering every option: its type, its permitted values, its range, and its default. Prose is the wrong shape for a question like *is `precision` an integer and what is its ceiling* — this answers it without being read as English at all.

Three things are worth knowing about it:

- **The defaults are the compiler's.** They are read out of the option resolver when the file is generated, not transcribed. A default that changes in the code changes here in the same commit.
- **The property tables are type-checked against the source interfaces.** An option that exists but is not described here fails the build, and so does a described option that no longer exists.
- **Both languages travel inside it.** `description` is English; `x-description-zh` is the Chinese. There is one document, not one per language, because a type is not a translation.

JSON cannot express a `RegExp` or a predicate function, and several options accept those. Where that is the case the schema describes the JSON-representable form and names the rest in `x-also`:

```json
"selectorExclude": {
  "type": "array",
  "items": { "type": "string", "x-also": "RegExp" }
}
```

The schema is also something to write against, not only to read. The CLI accepts a `.json` config, so a file that names this document in `$schema` is checked by the editor as it is typed:

```json
{
  "$schema": "https://moresyl.github.io/postcss-adaptive-matrix/schema/options.json",
  "defaultProfile": "app"
}
```

```bash
npx adaptive-matrix src/app.css -c adaptive.config.json
```

## Getting a useful answer out of an agent

The plugin's whole premise is the thing a model is most likely to skip past, so it is worth stating in the prompt: **a `px` cannot be converted until you know which design file it was drawn on.** An agent that assumes one global design width will produce a configuration that compiles and is wrong — the pages will scale and the component library will not, or the other way round.

Two prompts that tend to work:

> Read `https://moresyl.github.io/postcss-adaptive-matrix/llms.txt`, then configure this project. Our app screens are drawn on a 375 canvas and our admin screens on 1440. We use Vant.

> Fetch `https://moresyl.github.io/postcss-adaptive-matrix/schema/options.json` and check my `postcss.config.js` against it. Explain any option whose value is not the default and why it might have been set.

If the answer needs to be verified rather than trusted, the [conformance suite](../conformance/README.md) is a set of input/output pairs as pure data, and the [CLI](./cli.md) compiles a stylesheet and prints the result without touching the build.

## Where to go next

- [Documentation index](./README.md) — the pages themselves
- [Configuration reference](./configuration.md) — the same options as prose
- [Playground](./playground.md) — the compiler running in the page, for checking an answer by hand


---

<!-- source: conformance/README.md -->

# Conformance Suite

**English** · [简体中文](./README.zh-CN.md)

A language-neutral description of what this compiler must produce.

Every case is plain data — CSS text and JSON. Nothing in this directory imports
the reference implementation, so any implementation in any language can be
validated against it by walking `cases/` and comparing strings.

The suite is the normative definition of the transform. When behaviour and suite
disagree, the suite wins until a case is deliberately updated in the same commit
that changes the behaviour.

## Layout

```
cases/<group>/<name>/
  case.json      required — metadata and plugin options
  input.css      required — source stylesheet
  expected.css   required — exact expected output
```

## `case.json`

```jsonc
{
  "description": "One sentence describing the guarantee under test.",
  "from": "/project/src/app.css",   // optional, default "/project/src/app.css"
  "options": { },                    // optional, default {}
  "warnings": ["substring"]          // optional, default []
}
```

- `options` is passed verbatim to the compiler.
- `warnings` lists substrings that must each appear in exactly one emitted
  warning. The count must match the number of warnings emitted.

### Encoding regular expressions

JSON has no regex literal, so options that accept a pattern also accept a
tagged object:

```json
{ "$regex": "\\.module\\.css$", "$flags": "i" }
```

An implementation without regex support may skip cases that use this form and
must report them as skipped rather than passed.

## The universal invariant

Beyond matching `expected.css`, every case must satisfy one rule that has no
fixture of its own:

> Compiling `expected.css` again must return it byte for byte.

It has no fixture because it is not a feature — it has to hold everywhere. A
package that ships pre-compiled CSS goes through the consuming application's
pipeline a second time, and a framework preset can register the compiler twice
without saying so. Neither situation announces itself, so an implementation that
is idempotent for the cases someone thought to write down is not idempotent.

Three behaviours exist only to satisfy it: bounded expressions that already
carry a viewport unit are left alone, ignore directives survive into the output,
and the root foundation is introduced by a marker comment that suppresses a
second injection.

## Deliberately out of scope

Options that take a **callback** (`designWidth` as a function, function file
matchers) cannot be expressed as data and are therefore not covered here. They
are exercised by the reference implementation's own unit tests. Keeping them out
of the suite is intentional: the suite must stay portable.

## Running

```bash
npm test                    # verifies every case
npm run conformance:update  # rewrites expected.css from current behaviour
```

`conformance:update` is a snapshot refresh. Always read the resulting diff — an
unexpected change there is a behaviour regression, not a formatting detail.

## Output normalisation

Comparison is done on the exact output string with only these normalisations:

1. `\r\n` is normalised to `\n`.
2. A single trailing newline is ignored.

Whitespace inside the CSS is significant, because preserving author formatting
is itself a guarantee of this compiler.


---

<!-- source: examples/app-pc/README.md -->

# App + desktop example

**English** · [简体中文](./README.zh-CN.md)

Build the compiler once in the repository root, then process `input.css` with any PostCSS runner:

```bash
npm run build
node dist/cli.js examples/app-pc/input.css \
  -c examples/app-pc/adaptive.config.mjs \
  --targets "ios_saf 13, chrome 90"
```

`adaptive.config.mjs` holds the options; `postcss.config.mjs` imports them, so running this through PostCSS instead compiles exactly the same thing. `--targets` is optional and prints the browser-support audit after the table.

What this example shows:

- a 375 app design file and a 1440 desktop design file in one build;
- safe-area variables for notched screens;
- hairline preservation, so a 1px border stays 1px;
- text written as `rem + vw`, so browser zoom still reaches it;
- a root container capped at a maximum width and centred.


---

<!-- source: CHANGELOG.md -->

# Changelog

**English** · [简体中文](./CHANGELOG.zh-CN.md)

## 0.7.0 — 2026-08-11

### JSON configuration

- The CLI now accepts `adaptive.config.json`, strips its `$schema` metadata before compilation, and reports malformed or non-object JSON without exposing an internal stack trace.
- The published JSON Schema describes `$schema`, so editors can complete and validate a JSON configuration against the same option model used by the documentation site.
- JSON files are read with `readFile` and `JSON.parse`, preserving the package's Node 18 support; JavaScript configuration remains available for regular expressions and predicate functions.

### Quality gates

- Added ESLint, Prettier, VitePress source type-checking, documentation-site builds, and stricter coverage thresholds to `npm run check` and CI.
- Added a ratio-based performance budget that compares compiler cost with PostCSS parse-and-print cost, avoiding unstable absolute timing limits on shared runners.
- Expanded evaluator, selector scanner, CLI, schema, stdin, compatibility and error-path coverage; coverage now reaches 98.10% statements, 93.59% branches and 99.35% lines.
- Fixed two issues found by the new checks: serialising a value-parser node through an unsupported path and allowing an unknown value to stringify as `[object Object]` in generated output.

## 0.6.0 — 2026-08-11

### Breakpoints have a canvas now

- **New `media` route matcher.** A responsive stylesheet is one file holding two design files: the phone numbers were measured on a 750 mock and the ones inside `@media (min-width: 1024px)` on a 1440 one. Nothing in the CSS says so, and until now nothing could. `routes: [{ media: { minWidth: 1024 }, profile: 'pc' }]` gives the breakpoint the design file it was drawn on.
- This was not a near miss, which is why it is worth a feature rather than a note. `@media (min-width: 1024px) { .hero { padding: 40px } }` on a 750 canvas bounded at 600px compiled to `clamp(17.07px, 5.33vw, 32px)` — and that rule is only ever live from 1024px up, past where the canvas stops scaling, so the `clamp()` was already pinned to its maximum everywhere the rule applies. The padding was a constant 32px at every width, forever. The compiler ran, the output looked compiled, and not one value moved.
- **Matching is by implication rather than by text.** `{ minWidth: 1024 }` claims any rule that cannot apply below 1024px, so `screen and (min-width: 1200px)` and `(min-width: 1024px) and (max-width: 1600px)` are both claimed, and nesting composes because nesting is conjunction. Comparing the params as a string would have missed the `screen and` — and a design canvas is a fact about which widths a rule reaches, not about how the query was spelled.
- **`rem` and `em` in a media query resolve at 16px**, not at `rootValue` and not at the root element's font size. A query is evaluated before any declaration could change `font-size`, so it cannot depend on the cascade it selects: `64rem` is 1024px even in a stylesheet whose `html` is `62.5%`. This is a fact about the query rather than an assumption about the page, and reading only `px` would have left every Tailwind and UnoCSS project — which write every breakpoint in `rem` — unreadable. The continuity check reads the same parser and gained the same reach.
- A query the compiler cannot read — a comma, `not`, `only`, or any non-width feature — is claimed by **nothing**. That is a refusal, not a "matches everything": routing a rule on a condition nobody verified is how a canvas mistake gets made rather than caught. `@container` never counts either; it bounds an element, and `vw` has never been about the element.
- A `selector` route still outranks a width band, because a component library is drawn on its own canvas at every viewport width and a breakpoint does not change which design file a component came from. A route may name both — `{ selector: ['.van-'], media: { minWidth: 1024 }, profile: 'pc' }` — which is how "this component is redrawn at the desktop breakpoint" is said.
- An empty band (`{}`) and a reversed one (`minWidth: 1024, maxWidth: 600`) are configuration errors that throw. The first matches every rule in the stylesheet, which is a slow way of changing `defaultProfile`; the second matches nothing. Both read as working configuration, so neither may be left to be discovered from the output.

### The dead-band warning

- **You do not have to know any of the above to find the problem.** When a rule converts a length and the band it is live in lies entirely outside its canvas's fluid range, the compiler now says so, names both ranges, and gives the route that fixes it. This is arithmetic rather than a heuristic — two intervals that do not overlap — and it is the failure the multi-canvas model exists to prevent, arriving through the one door the model never watched.
- Reported once per canvas per band per file, and **only for rules that actually converted something**. A breakpoint that changes `display` and `color` is ordinary CSS with no lengths to be constant about, and warning on those would bury the report in the places it does not apply. The first version did exactly that, which is what the test for it was written from.
- The suggested fix adapts: when a selector route chose the canvas, the message asks for `{ selector: […], media: … }`, because a bare media route loses to a selector route and would have changed nothing. Advice that does not work is worse than no advice.
- **`appPcPreset` now reads its own breakpoint as well as writing it.** The preset already said "the desktop design file takes over at 768px" — that number set each profile's `query`, so an `@adaptive pc` block came out wrapped correctly. It just never *read* a media query, so a hand-written `@media (min-width: 768px)` block compiled against the phone canvas: the preset disagreeing with itself. Both directions are now routed, and the `max-width` half is stated explicitly rather than left to `defaultProfile`, so the pair keeps meaning what it says if the preset is spread over a desktop-first configuration.
- Two conformance cases, `breakpoints/media-route` and `breakpoints/dead-band`, covering what is claimed, what is refused, and the one-report-per-band rule.

### Selector routing

- Fixed **`:not()` and `:has()` arguments deciding which canvas a rule lands on**. `.page-hero:not(.van-cell)` styles page elements — precisely the ones that are *not* Vant cells — and was being sent to Vant's 375 canvas because the substring `.van-cell` appeared somewhere in the text. Every length in such a rule came out at exactly twice its intended size, silently. Routing now reads the **subject** of the selector: the arguments of `:not()` and `:has()` name an element other than the one being styled and are removed before matching, while `:is()` / `:where()` / `:matches()` / `-*-any()` arguments are kept, since those genuinely are alternatives for the subject. Measured against 22,761 rules in 11 published component-library stylesheets, 1,035 of which contain `:not()` or `:has()`: **zero** change canvas, because library CSS always carries its own prefix outside the exclusion. The fix costs nothing and closes a hole that application code walks into.
- **`:is()` and `:where()` lists spanning two canvases now warn.** This was previously documented as undetectable. `:is(.van-cell, .page-hero) { padding: 16px }` is one declaration wanted on two canvases, the same problem as a comma-separated list one bracket deeper, and it was going through unreported.
- The warning states **what splitting would cost**, computed rather than left to the reader: `:is()` matches every branch at the specificity of its highest one, so pulling the branches apart is free only when they already agree. When they do not, the warning names the drop — `:is() matches every branch at its highest, 1-1-0, so ".page-hero" would drop to 0-1-0`. This is what makes the advice actionable; a warning whose fix silently changes the cascade is a warning people learn to ignore. One report per rule: the remaining lists have the same cause and the same fix.
- New `src/core/selectors.ts`, dependency-free: `splitSelectorList`, `routingSelector`, `nestedSelectorLists`, `specificity`, `compareSpecificity`, `formatSpecificity`, `splitIsSpecificityNeutral`. Splitting is string-aware and attribute-aware, so `[data-x="a)b"], .c` splits into two — naive bracket counting gets that wrong. Specificity follows Selectors Level 4, including `:where()` counting zero, `:is()` / `:not()` / `:has()` taking their highest branch, `:nth-child(n of S)` counting as a pseudo-class plus the highest of `S`, and the four legacy single-colon pseudo-elements (`:before`, `:after`, `:first-line`, `:first-letter`) counting as elements. 40 new unit tests.

### Browser support audit

- **`:has()` is now audited.** It is the newest selector in everyday use and the four engines are years apart on it — Chrome 105 (Aug 2022), Safari 15.4, and Firefox not until 121 (Dec 2023). That spread is the widest in the table, and the failure is selector-level: the whole rule is dropped. A stylesheet reviewed in Chrome and Safari can be silently missing rules in an older Firefox. The compiler emits no `:has()`; it arrives from your own CSS or a component library and survives the pass, which is exactly why an audit that reads the *output* sees it. Unlike native nesting it is unmistakable in the text, so it is reported rather than guessed at.
- `css-has` added to `scripts/capture-compat.mjs` and regenerated into `src/core/compat-data.ts`; still no runtime dependency.

### A documentation site

- **The documentation is published as a site**, in both languages, at `https://moresyl.github.io/postcss-adaptive-matrix/`. It is built out of the repository rather than out of a copy of it: `srcDir` is the repository root, so `docs/README.md` linking to `../conformance/README.md` reaches a real page here for the same reason it does on GitHub, and no file moved. Search, dark mode, an edit link and a last-updated stamp come with it.
- The one thing that had to be designed rather than configured is the language switcher. VitePress resolves a relative link against the page's *rewritten* location, so `[English](./README.md)` at the top of a Chinese page — correct on GitHub — resolves back to the Chinese page on the site. Links are therefore resolved in the **repository**, against the source path, and emitted as absolute site URLs. Moving a page cannot break them.
- **Every option is published as data** at `/schema/options.json`: a JSON Schema 2020-12 document with each option's type, permitted values, range and default. Prose is the wrong shape for "is `precision` an integer and what is its ceiling".
- Two things stop it being decoration. Its property tables are typed over the source interfaces, so an option that exists but is not described fails `tsc`, and so does a described option that no longer exists. And every default is read out of `resolveOptions()` when the file is generated rather than transcribed, so a default that changes in the code changes here in the same commit. A test closes the gap the type system cannot see — that the default printed in the configuration reference is that same default — and found one disagreement immediately: `unitToConvert` resolves to a list, and both reference tables said `'px'`.
- Both languages travel inside the one schema: `description` is English, `x-description-zh` is Chinese. A type is not a translation. `x-also` names the JavaScript-only forms — a `RegExp`, a predicate function — that JSON cannot express but a config file accepts.
- **The compiler runs in the reader's browser.** The plugin has one runtime dependency and no Node API in its path, so the published source is imported straight into the playground page and PostCSS runs client-side. There is no service behind it and nothing to keep in sync with a release. The options pane evaluates as a JavaScript expression rather than parsing as JSON, because half of what is worth trying cannot be written in JSON. Six samples, one per question people actually ask, including a configuration the compiler warns about.
- **`llms.txt` and `llms-full.txt` per language**, following the llms.txt convention, and the raw Markdown of every page served at the page's path plus `.md` — so "give this page to a model" is a fetch rather than a scrape of rendered HTML. Three buttons above the outline use it: copy as Markdown, view raw, and open the page in a conversation.
- New `docs/agents.md` / `docs/agents.zh-CN.md` gathers those endpoints in one place, including what belongs in a prompt: an agent that assumes one global design width writes a configuration that compiles and is wrong.
- Deployed by `.github/workflows/docs.yml` on push to `main`. `tsconfig.json` now covers `docs/.vitepress`, so the site's own source is type-checked with everything else.

### Documentation

- New `scripts/check-docs.mjs`, wired into `npm run check` and therefore into CI. It verifies that every local link resolves, that every `#anchor` matches a real heading, and that **every page has its counterpart in the other language and links to it near the top**. The pairing check is the one that earns its keep: the two languages are written separately rather than translated, which is what makes them read properly and also what lets one of them quietly not exist. It found two — `CODE_OF_CONDUCT` had only a Chinese version under an English filename, and the example README had both languages stacked in one file.
- The anchor check splits on `/\r?\n/`. On Windows every file here is CRLF, and a trailing `\r` defeats `$` in a non-multiline pattern while also not being matched by `.` — so a naive split finds no headings at all and reports every anchor in the repository as broken. That is not hypothetical; it is what the first version of this check did.
- `examples/app-pc` gained `adaptive.config.mjs`, exporting the options alone; `postcss.config.mjs` now imports them. The two runners want different shapes — PostCSS wants `{ plugins: [...] }`, the CLI wants the options — and writing the canvases out twice is how the two end up describing different designs. The example READMEs now give a command that actually runs, including `--targets`.

### Performance

- `routingSelector` returns immediately for a selector with no `:` in it, which is most of them, and the reduction now happens inside `forSelector` — after the check that skips selector routing entirely. A project with `libraries: false` no longer pays anything at all for the feature. Compiler time on the utility-framework corpus: 4.38ms → 3.58ms.

### Conformance

- The atomic fixtures gained `space-x-4` and `divide-y-2`, which had left the suite with **no functional pseudo-classes at all** despite being everyday utilities. One utility, three unrelated real shapes: Tailwind 4 wraps the whole thing in `:where(...)`, UnoCSS wind3 writes a flat `> :not([hidden]) ~ :not([hidden])`, and UnoCSS wind4 emits *native nesting* with `&`. All three now produce an identical `clamp(1.70667px, 0.53333vw, 2.56px)` for the same 2px, the `border` hairline survives in all three, and wind4's native nesting is written back unchanged.
- New `test/idempotence.test.ts`: **compiling compiled output changes nothing**, across nine configurations × eight stylesheets. The conformance suite already asserted this per fixture, but only under the options that fixture declares — what was uncovered is the cross product of the switches that change the *shape* of the output, and the shape is what a second pass has to survive. A second pass is not hypothetical: a package that ships pre-compiled CSS goes through the consuming application's pipeline again, and so does a monorepo that compiles a shared component library and then the app importing it.
- The case that wanted pinning down is atomic mode with static text. Atomic mode adds `rem` to `unitToConvert`, and text is normally written as `rem + vw` — the `vw` is what tells a second pass the value is already compiled. With `fontFluidity: 0` there is no `vw`: `32px` becomes a bare `2rem`, which the next pass reads as a design length and converts again. It survives, but nothing defends it — `rootValue` is used at both ends, so writing ÷16 and reading ×16 are exact inverses and the value is its own fixed point. That is a property of the arithmetic rather than a rule anyone wrote down, and if either end of that division moves the failure is silent: no error, no warning, just text a little smaller on every save in a watch loop.

### Types

- Every array-valued option now accepts a `readonly` array: `routes`, `libraries`, `textProperties`, `propList`, `selectorExclude`, `valueExclude`, `include`, `exclude`, `root.injectTo`, and the `file` / `selector` / `property` / `prefix` / `tokenPrefix` fields of routes and library definitions. `unitToConvert` already did, which made the API inconsistent: a configuration written with `as const` — the natural way to write one in TypeScript — type-errored on every field but that one.

## 0.5.0 — 2026-08-10

### Documentation

- **Every documentation file is now bilingual**: `X.md` in English, `X.zh-CN.md` in Chinese, cross-linked at the top of each page. That covers the README, all 11 docs pages, the conformance suite description, the contributing guide, the security policy and this file. The English is not a machine translation of the Chinese — the same point wants different sentences in each language, so the two versions were written separately.
- The English artwork lives in `docs/assets/en/` and was redrawn for English: Chinese labels are short, so substituting the text would overflow the cards, and the dashed plain-vw line would run under `tracks the viewport`.
- The canvas-model diagram no longer names third-party libraries. The model has nothing to do with whose library it is; "a mobile component library / 375 design file" and "a desktop component library / no design file · real pixels" say exactly the same thing, and the diagram is about this compiler from start to finish.

### Browser support audit and degradation

- New `auditCompatibility(css, targets)`: give it "browser + the oldest version you support" and it lists every piece of syntax in the output beyond your targets, what is lost when it is unsupported, and the switch that turns it off. The audit reads the **compiled stylesheet text** rather than the configuration — the only way audit and output can never drift apart, and it sees features that arrive via a preset, via a component-library route or via hand-written CSS alike. Also exported: `detectFeatures`, `COMPAT_FEATURES`, `FEATURE_SUPPORT`, `compatFeature`, fully typed.
- New CLI flag `--targets "safari 14, ios_saf 13"`, printing a `needs` section after the comparison. The order of those lines is deliberate: what is lost first, what to switch to second — "iOS Safari 13 is too old" is not actionable on its own, and what has always mattered about a CSS support gap is **how much goes with it**. CSS does not error, it discards: an unreadable value takes its declaration, an unreadable selector takes its rule, an unreadable at-rule takes its whole block, all silently. So the feature table is ordered by how much is lost, not by which feature is newest.
- Covers 11 features: `@layer`, `:where()`, `@container` / container units, `clamp()` / `min()` / `max()`, `vi`, logical properties, `var()`, `env(safe-area-inset-*)`, `vw`, and native nesting. The compiler does not emit native nesting (nesting it reads is written back as it was); it is listed because it is a question that gets asked, and because pattern-matching it would misread ordinary CSS as nested — a false report is worse than no report.
- Version data is baked into `src/core/compat-data.ts` from caniuse-lite by `scripts/capture-compat.mjs`. caniuse-lite stays a devDependency, the plugin adds no runtime dependency, and the audit works offline. "Which version a feature became usable in" is history and will not change again; **usage share is deliberately not consulted** — whether 0.4% of users count is a decision about your project, and `browserslist` is already the place that answers it. The scan takes the version from which support was never lost again, not the first version showing a `y` (a few features shipped and were then withdrawn).
- `--targets` takes explicit names and versions, not a browserslist query: a query would pull in the browserslist package, answers a question about your users rather than about this stylesheet, and **the same query changes meaning as the database updates** — not one character of code changes and next month the build goes red. An unrecognised target name is an error that exits `1` rather than being skipped silently: a target quietly dropped is worse than no audit, because it reads like a pass.
- caniuse has no separate entries for `:where()` or `vi`, so the `:is()` and `svh`/`lvh`/`dvh` entries are used, marked in the data as proxies rather than measurements. Both pairs come from the same section of the specification and shipped together (`:where()` / `:is()`: Chrome 88, Firefox 78, Safari 14).
- New `root.logical` (preset field `rootLogical`): set to `false`, the foundation writes `width` / `margin-left` / `margin-right` / `max-width` instead of `inline-size` / `margin-inline` / `max-inline-size`. **This is a real gap found while building the audit** — logical properties are the only syntax the compiler emits whose failure still leaves a page that looks fine: without `margin-inline: auto` the column is exactly the right width, sitting against the left edge of the screen; without `max-inline-size` it goes full-bleed. Neither looks like a fault, so it is likelier to ship than a visible collapse, and until now no switch avoided it. The two spellings are equivalent on a horizontal page, so switching costs nothing. The preset also gained `rootLayer`, passed through to `layer` — also a support switch, and reaching it should not cost you the preset.
- New documentation page: [Browser support and degradation](docs/compatibility.md) — the feature × minimum-version matrix, a per-feature "what emits it / what is lost / how to switch it off and what that costs", and the boundary of what this audit **cannot** replace (it only proves your target browsers can parse the syntax in this CSS; rendering differences, keyboards and address bars are different problems). Conversely, a real device cannot test a version threshold either — the iOS 17 in your hand reads `@layer`, which says nothing about 15.4 and below.

### Breakpoint check

- Fixed **two `shrinks` false positives that fired reliably on the default preset with no configuration at all**: `root.fixedContainingBlock` rewrites a fixed element's `left: 0` into `left: var(--adaptive-root-gutter)`, and that gutter is **meant** to step at a breakpoint — as the column goes from 480 to 1920, the gutter correctly drops from 143.96px to 0. Read as a design length that is a regression; read as itself it is the correction working. The variable is now substituted with `0px` before comparison rather than skipping the group entirely, so the `clamp()` in `left: calc(clamp(…) + var(--adaptive-root-gutter))` is still checked. A check that shouts on the default configuration is a check people learn to skip.

### Atomic CSS (Tailwind / UnoCSS)

- Fixed **no utility class being converted at all**, silently: hand-written CSS scaled, utilities did not, and the two size systems drifted apart with no error. Each major version was blocked in a different place. The older ones (Tailwind 3, UnoCSS `presetUno` / `presetWind3`) write lengths in `rem` while the compiler only read `px`; the newer ones (Tailwind 4, UnoCSS `presetWind4`) moved lengths entirely into theme tokens, so `.p-4` compiles to `padding: calc(var(--spacing) * 4)` — there is no length in the utility to read, and custom properties are not converted by default.
- `unitToConvert` now accepts an array, reading several units in one pass. This is not a nicety: both frameworks emit both units in the same stylesheet — spacing and font sizes in `rem`, border widths and bracketed arbitrary values like `p-[13px]` in `px`, all describing the same design file. Reading only `rem` misses every border, reading only `px` misses every gap, and both single choices are wrong. `rem` becomes pixels via `rootValue`; every other unit is read at face value.
- Fixed `unitToConvert: 'rem'` having always treated `1.5rem` as 1.5 pixels: with no conversion before comparison it fell below the `minPixelValue` and `hairline` thresholds and whole stylesheets were skipped. Both thresholds are now judged in **pixels** — `0.0625rem` and `1px` are the same hairline, and how you spell it does not change how thin it is.
- New `rootValue` (default 16), one ruler shared by both ends: it decides how many pixels a `rem` input is worth, and how many `rem` a text size's static part is written as. A project with `html { font-size: 62.5% }` sets `rootValue: 10`.
- New `withAtomicCss(base, options?)`: **wraps** rather than replaces an existing configuration, adding `rem` to `unitToConvert` and claiming the theme token prefixes `--spacing`, `--text-`, `--leading-`, `--radius-`, `--container-`. Claiming the source is enough and the utilities need no changes — `calc(clamp(a, b, c) * 4)` is identically `clamp(4a, 4b, 4c)` (multiplication by a positive coefficient passes through a clamp), and the output is digit-for-digit identical to converting `16px` directly. Three families are deliberately not claimed: `--breakpoint-*` is the width at which a canvas **switches**, so scaling it moves the breakpoint itself; `--tracking-*` is published in `em`, and the font size it hangs off is already fluid, so scaling again compounds it; `--shadow-*` pixels are depth drawn at screen scale. Add your own length families with `tokenPrefixes`.
- The default `textProperties` now includes `--text-*` and `--leading-*`: when a font size is published as a token its name does not look like a font property, and missing it means that font size **loses browser zoom**. This only decides how an already-converting length is written, not whether it converts, so it does nothing for an unclaimed token.
- New conformance cases `atomic/{tailwind-v4,unocss-wind3,unocss-wind4}`, whose input is the **actual published output** of all three (Tailwind 4.3.3 and two UnoCSS 66.7.5 presets), re-capturable with `scripts/capture-atomic.mjs`. The two major-version shapes differ far too much for a hand-written copy to be anything but what you imagined. Neither framework is a devDependency: the captured CSS is the entire input, and tying `npm test` to someone else's release schedule buys no extra information.
- A regular expression passed to a route's `property` channel now throws a `TypeError` immediately, explaining the correct form. The other two channels accept regexes; this one takes string prefixes only, and the previous behaviour was a mid-run `prefix.toLowerCase is not a function`.

**Breaking (types)**: `ResolvedAdaptiveMatrixOptions.unitToConvert` changes from `string` to `string[]`; `AdaptiveMatrixOptions.unitToConvert` widens to `string | readonly string[]`, so passing a string still works. `findContinuityIssues` gained an optional second parameter, `rootFontSize`.

### Compiler

- Fixed cross-canvas text sizing: **when the project canvas and a library canvas differ, all of that library's text was wrong**. Ordinary lengths always agreed (both reduce to `value ÷ canvas`); text did not — text keeps a fixed `rem` component so browser zoom stays effective, and that fixed length used to anchor to each canvas separately. With Vant on 375 and the page on 750 the two describe the same design in two sets of units, so Vant's 16px and the page's 32px are the same size — yet at a 390px viewport they rendered as 16.22px and 26.62px, **about 40% too small**, and invisible at both 375 and 1440. A 750-file project using Vant is one of the most common mobile combinations there is; antd-mobile's 1x/2x pair of artifacts is the same situation.
- New profile field `textAnchorWidth`: the width the static part of text anchors to, defaulting to `designWidth`. A library canvas always inherits the anchor of the profile it belongs to, so there is nothing to configure. The equivalent form is "convert the length into the anchor canvas's units first, then apply the formula as usual": the fluid term is exactly unchanged (`P × F / D` cancels proportionally with the canvas), and only the static term is normalised. For non-text lengths `fontFluidity = 1` and the static term is always 0, so the output is byte-for-byte unchanged, and `strategy: 'viewport'` is unaffected too.
- New property test: "the same design on a different canvas is the same size". Across random canvases and random scale factors, `V px on D` and `V×k px on D×k` must agree at every viewport. The conformance suite can only cover canvas combinations someone thought to write down, and this bug only surfaced when two canvases were present at once.

### Compiler and validation

- `@adaptive <canvas>` landing on a profile with no `query` now warns. Projects split by folder (`src/mobile/**` and `src/pc/**`, one page tree each) usually have no `query` on either profile — switching is not CSS's job there. Writing `@adaptive pc { ... }` in a shared component then reads as "these rules are for desktop", but compiles to unconditional rules that come later in the file and therefore **win at every viewport**, with nothing anywhere saying so. `query: false` does not warn: that is an author stating explicitly that switching happens outside CSS. An `@adaptive` pointing at its own canvas does not warn either: there is no switch, and unwrapping loses nothing.
- New documentation section, "two page trees, split by folder", stating that file routing only decides which design file to convert against and never adds a media query, plus the trade-offs around shared components, component libraries and route specificity.

### Build tool integration

- New real Vite build test: the scaffold has a `postcss.config.mjs` that Vite discovers for itself, a dependency stylesheet imported from `node_modules`, and a `<style>` block supplied the way `@vitejs/plugin-vue` supplies one. Until now nothing verified a single claim in the integration documentation — and when those claims stop holding, the build still succeeds and only the stylesheet is wrong. Now verified: the config is found and applied; a dependency lands on the component-library canvas via its `node_modules` path with output byte-for-byte identical to the equivalent size on the page; an SFC id with a query string is matched by a contains-style `file` route; and a second build produces identical output.
- The documented trap "an end-anchored regex never matches an SFC" is now a test too: building with `/\.mobile\.css$/` asserts that the `<style>` block really is left silently on the default canvas while the rest of the output is unchanged. A claim like that only counts once it has been verified from the other side.

### Optional runtime

- Fixed a frame leak in `observeAdaptiveViewport`: `update()` is a public method, yet it cleared the scheduler's frame handle. Calling `update()` manually and then `destroy()` left an already-queued frame neither recorded nor cancelled, so it landed on a destroyed observer on the next tick. Only the scheduler clears the handle now, `destroy()` zeroes it, and a repeated `destroy()` no longer cancels a handle the host has already recycled and reissued.
- Filled in the runtime tests: the fallback for old WebViews with no `visualViewport`, negative keyboard heights from iOS rubber-band scrolling, per-field non-numeric readings, event coalescing, destroy timing, and reading the globals when called with no arguments — the path every browser user actually takes. Branch coverage 72% → 100%.

### Component libraries

- New `scripts/verify-libraries.ts`: downloads each built-in library's **published artifact**, compiles it with a realistic `node_modules` path, and checks whether the prefix really exists, which canvas the route lands on, whether the result is idempotent, whether there are warnings, and whether the seam check produces a false positive. Until now every registry entry except Vant was written from documentation with no evidence; the three items below were all found by this script.
- Fixed antd-mobile: the library publishes the same stylesheet twice, `bundle/` drawn on 375 and `2x/bundle/` on 750, with identical class and token names (measured on 5.42.3, every length in the latter exactly double the former). The `.adm-` prefix route used to convert the 2x artifact against 375, making every size on the page exactly twice what it should be, with no error and no warning. New `antd-mobile-2x` entry, active in automatic mode with nothing to configure.
- New `scoped`: restricts `prefix` and `tokenPrefix` to only count when `file` matches too. When one prefix maps to two canvases, only the path tells them apart. Path-scoped routes are tested before unscoped ones because they are more specific; when the path does not exist (a bundler inlined the dependency), it falls back to the unscoped one. `scoped` without `file` is an error.
- Removed Varlet's `tokenPrefix: '--var-'`: that library's custom properties carry no prefix at all — they are `--field-padding`, `--icon-size-md`, declared on a bare `:root`, and the rule matched nothing. Claiming those names means claiming `--card-width` itself, and the registry only takes unambiguous prefixes, so nothing was added; the documentation shows the explicit route instead.
- The documentation now carries measured prefix hit rates, and states that **the design width column cannot be checked** (a stylesheet does not reveal how wide the file it was drawn on was), and that `naive-ui` and `mui` generate their styles at runtime with no stylesheet on disk.

### Breakpoint seam check

- Only reports when **at least one side is a compiler-produced formula**. It used to read a library's own deliberate breakpoint difference as a seam: Quasar's `.q-tooltip` is `padding: 8px 16px` on a phone and `6px 10px` above 600px, a tap-target trade-off where both numbers were written and compared by a person. The completeness argument "a regression can only come from a canvas change" covers only formulas this compiler produced, and does not hold for a stylesheet left as authored. One side converted and the other not still reports.
- Conformance cases now use compiler-shaped values. Over a dozen negative cases used a bare `40px`, which after this gate would pass because they were never compiled rather than because of the thing each was meant to verify.

## 0.4.0 — 2026-08-09

### Breakpoint seam check

- New breakpoint seam check: the CLI points out declarations where widening the viewport makes a size smaller, with the actual pixel values on both sides. Two design files can each be right and still disagree at the seam, and this class of problem only appears at one width — the 375 and 1440 you debug at every day are both fine. The check is also exported as `findContinuityIssues(root)` so a build can fail on it.
- The comparison is on **absolute value**, and a sign change across the breakpoint is never reported. The absolute value of every formula the compiler emits is non-decreasing in viewport width and never changes sign, so an absolute-value regression can only come from a canvas change across a breakpoint. Comparing signed numbers was inverted for every negative length: negative margins and bleeds grow by moving away from zero.
- The check substitutes theme tokens from the same stylesheet. Component libraries almost never write literal sizes — of Vant 4.10.0's 3198 ordinary declarations, 1173 read entirely through `var()`, so giving up at the first `var(` means avoiding precisely the layer this plugin adapts. Substitution happens only when the value is decided by viewport width alone: the token must be declared only on `:root` / `:host` / `html` with no second copy elsewhere, and every declaration must be either unconditional or inside a pure pixel-width `@media`. A token rewritten at a breakpoint is itself a seam, even if the rule consuming it is written once. Measured (the complete Vant 4.10.0 stylesheet): evaluable value components 622 → 1309 (17.6% → 36.9%), with 779 tokens collected.
- Measured false positives: across the 69 conformance fixtures, the Vant stylesheet above, and this repository's example project, the `shrinks` count is 0 everywhere.
- New `evaluateLength`: evaluates the compiler's `clamp()` / `min()` / `max()` / `calc()` at a given viewport width. `env()`, `%` and container units return `null` rather than a guessed number.

### Packaging and types

- Fixed the CommonJS entry: `require('postcss-adaptive-matrix')` returned a namespace object, so calling it directly threw `plugin is not a function` and `.default` was mandatory. But `plugins: [require('postcss-adaptive-matrix')({ ... })]` is the universal shape of every `postcss.config.js` — this repository's own Webpack documentation example was wrong. `module.exports` is now the plugin itself, with `.default` and the named exports still available as properties.
- Fixed the CommonJS type entry, in two places: `types` in `exports` existed only at the top level, so CJS consumers got the ESM `.d.ts`; and `.d.cts` itself only declared named exports, so `import x = require('postcss-adaptive-matrix')` reported "has no call signatures" — code that ran while the editor showed red. `require` now points at `.d.cts`, which describes the real shape with `export =`, types are preserved through a merged namespace, and `import type { AdaptiveMatrixOptions }` still works. The ESM entry and its types are unaffected.
- New tests against the built artifact itself: every other test imports from `src`, but what `require` receives and which file types resolve to are decided by the build and by `package.json`, and importing from source can never test that. `npm run check` therefore builds before testing.

### Compiler and validation

- A selector list that straddles canvases (`.van-cell, .page-hero { ... }`) now warns and names the selector that lost. One declaration can only have one answer, and the previous behaviour silently compiled the whole rule on the first canvas that matched.
- `@adaptive pc;` (no block) used to be rewritten as `@media (min-width: 768px);` — not valid CSS, while the rules the author meant to put on that canvas stayed on the original one. It now warns and is left as written.
- The CLI's `-c` no longer falls back silently to the built-in defaults when the config module is missing `default` or the preset was never called. Both used to run to completion and print a comparison that looked correct, with nothing anywhere saying the configuration had not been read.
- New configuration validation: the values of `unit` and `strategy`, an empty `unitToConvert`, an `atRuleName` colliding with an at-rule CSS already defines, and an empty `root.selector`. Getting any of these wrong fails silently, and a wrong `unit` emits outright invalid CSS.
- New property-based random tests: using `evaluateLength` as the oracle, design-width identity, absolute-value monotonicity, constancy outside the range, linearity inside it and idempotence are verified across hundreds of generated canvases. The conformance suite can only cover design widths someone thought to write down.

## 0.3.0

- New `adaptive-matrix` CLI preview: a per-declaration before/after, with `--from` to verify file routing before you ship and `--css` to emit the full output while warnings go to stderr.
- Fixed nesting: declarations inside `@media` / `@supports` / `@layer` / `@container` / `@scope` / `@starting-style` are now converted, while lengths inside `@font-face` / `@page` / `@property` / `@counter-style` are left as written.
- Fixed idempotence: `clamp()` / `min()` / `max()` that already carry a viewport unit are no longer converted a second time.
- Fixed idempotence of the root foundation: the output carries a `/* postcss-adaptive-matrix foundation */` marker, so recompiling neither scales a fixed ceiling like `max-inline-size: 480px` as if it were a design-file size, nor stacks on a second copy.
- Ignore comments (the `adaptive-ignore` family) are no longer removed from the output. An ignored value carries no trace of itself, so once the comment is gone a second pass converts the size the author explicitly excluded; minifiers remove the comments, so shipped size is unaffected.
- The conformance suite gained an idempotence assertion for every case: recompiling the output must return it unchanged.
- Fixed duplicate declarations: every repetition of a declaration within one rule is now converted. Only the first used to be, while the cascade uses the last — so the conversion was effectively lost.
- Numbers with exponents are supported: `1e2px` is 100px, which used to be skipped silently, and `min(1e2vw, 50px)` is no longer misjudged as having no viewport unit.
- Fixed at-rule casing: `@ADAPTIVE` / `@Adaptive` are equivalent to `@adaptive`, matching CSS's case-insensitivity for at-keywords. They used to go unrecognised, and the browser discarded the whole block with no indication.
- New `root.injectTo` (`rootInjectTo` on the preset): limits which files receive the root foundation. In a component-based project every `<style>` block is a separate file, so the default injects one copy into each.
- An exclude-only `propList` (such as `['!border*']`) is now an error — it matches no property, which means the entire stylesheet goes unconverted.
- Using the reserved `library:` prefix in `profiles` is now an error pointing back at `libraries: [{ extends }]` — it used to be silently overwritten by the synthesised library canvas.
- The unknown-canvas warning no longer lists internally synthesised library canvases, and explains that the browser discards the whole at-rule; under `unknownProfile: 'error'` the error no longer suggests enabling an option that is already enabled.
- New registry invariant tests, covering prefix ambiguity, canvas values and the short-prefix policy in automatic mode.
- Restructured the documentation, adding getting started, build tool integration, component libraries, optional runtime and CLI preview, with SVG diagrams.

## 0.2.0

- Added component-library canvases, automatic recognition, route overrides and design-token adaptation.
- Added the fixed root containing block correction and desktop offset handling.
- Decoupled the compilation core from the PostCSS adapter layer, exposing the resolved multi-canvas configuration.
- Established 50+ conformance fixtures, 133 tests and a benchmarking tool.
- Rewrote the multi-canvas model, component library, architecture and migration documentation.

## 0.1.0

- First implementation of the app/desktop multi-canvas compilation model.
- Bounded fluid sizing, zoomable text, and media-query and container-query profiles.
- Dynamic design widths, file/property/selector/value filters and ignore directives.
- Optional root layout, safe-area variables and the VisualViewport runtime.
- Published ESM, CommonJS and TypeScript types.