# Adaptive Matrix — 全部文档

> Adaptive Matrix 是一个 PostCSS 8 插件：每个 px 按它所在设计稿的宽度换算，而不是按全局唯一的宽度换算。页面、移动端组件库、桌面端组件库来自不同的设计稿，给每张稿子一张自己的画布，是让三者同时缩放正确的前提。产物是有上下界的 clamp()，文字保持可缩放以满足 WCAG 1.4.4。常见组件库的画布已经内置，用了组件库的项目默认配置就是对的。

下面是全部文档页面，按阅读顺序拼接。每一节的开头标注了它在仓库中的路径。


---

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

# 快速上手

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

## 安装

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

## 最小配置

只有一张设计稿时：

```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` 是设计稿宽度，`fluid` 是尺寸继续跟随视口变化的区间。区间之外尺寸停住——这是与纯 `vw` 方案最大的区别，详见[有界流体](#有界流体)。

## 双设计稿：App + PC

设计团队交付两个画布时用 `appPcPreset`：

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

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

预设给出的约定：

| | App | PC |
| --- | --- | --- |
| 设计宽度 | 375 | 1440 |
| 流体区间 | 320 ~ 480 | 1024 ~ 1920 |
| 生效条件 | 默认 | `@media (min-width: 768px)` |

## 写业务 CSS

基础选择器写两端共有的部分——布局结构、颜色、交互状态。只把尺寸真正不同的内容放进 `@adaptive pc`，不要维护两份页面：

```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;
  }
}
```

输出：

```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);
  }
}
```

普通规则按默认 `app` 画布转换；`@adaptive pc` 块按 1440 画布转换，并包裹进 PC 媒体查询。

## 另一种双端：两套页面代码，按文件夹分

上面那种写法是**一套页面、两张稿**——共有的部分只写一遍，差异放进 `@adaptive pc`。

还有一种常见做法是**两套页面代码**：`src/mobile/**` 和 `src/pc/**` 各自完整一份，路由或入口决定进哪一套。这种项目不需要在 CSS 里写 `@adaptive`，用文件路由就够了：

```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[\\/]/] },
  ],
}
```

同样一行 `padding: 32px`，落在哪个文件夹就按哪张稿换算：

| 文件 | 产物 |
| --- | --- |
| `src/mobile/home/index.vue` | `clamp(13.65333px, 4.26667vw, 25.6px)` |
| `src/pc/home/index.vue` | `clamp(22.75556px, 2.22222vw, 42.66667px)` |

**关键一点：文件路由只决定"按哪张稿换算"，不会给规则套媒体查询。** 这正是这类项目需要的——哪套页面显示已经由路由/入口决定了，CSS 不该再管一遍。上面两条产物都是无条件的。

SFC 的 `from` 带 query 串（`index.vue?vue&type=style&index=0&lang.css`），所以 `file` 要按包含写、不要锚定结尾，见[构建工具集成](./integration.zh-CN.md#3-vue-sfc-的路径带-query-串)。

### 共用组件落在哪张画布上

`src/components/**` 两边都用，两条路由都不命中，于是走 `defaultProfile`。三个选择：

1. **就用默认画布**——组件本来就该在移动端和 PC 端长一样时，这是对的；
2. **按用途再拆一层文件夹**，`src/components/mobile/**` 与 `src/components/pc/**`，各自命中路由；
3. **在组件里用 `@adaptive pc`**——但这条在本节的配置下有个坑，见下。

### 坑：`query` 没设置时 `@adaptive` 会变成无条件规则

这一节的两个 profile 都没有 `query`，因为切换本来就不由 CSS 负责。但一旦有人在共用组件里写：

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

`pc` 画布没有 `query`,外壳无处可套,于是被拆开——两条规则都是无条件的,而后一条在文件里更靠后,**在任何视口都会赢**:

```css
.shared-card { padding: clamp(13.65333px, 4.26667vw, 25.6px) }
.shared-card { padding: clamp(34.13333px, 3.33333vw, 64px) }   /* 永远是这条生效 */
```

编译器会为此告警并给出两个出口：给 `pc` 加上 `query`，或者写 `query: false` 表明切换发生在 CSS 之外（一端一个产物、或按环境变量选画布）。写了 `query: false` 就不再提示——那是你已经回答过的问题。

同一张画布上的 `@adaptive app` 不告警：没有切换，拆开也不丢东西。

### 组件库不用管

移动端的 Vant、PC 端的 Element Plus 都在 `node_modules` 里，两条文件夹路由都不命中，各自由内置注册表认领——Vant 走 375 画布，Element Plus 保留像素。不需要额外配置。

唯一要注意的是**你写的路由优先于组件库路由**，所以文件夹正则要写得足够具体：`/[\\/]pc[\\/]/` 只匹配路径里独立的 `pc` 段，而 `/pc/` 这种写法会误伤任何路径里带 `pc` 三个字母的依赖。

## 有界流体

![有界流体区间](./assets/fluid-range.svg)

**断点和流体区间不是一回事。** 断点决定哪套布局生效，流体区间决定尺寸在哪段区间里继续缩放。

上面的配置里，App 规则在 768px 之前一直生效，但尺寸到 480px 就停止放大——600px 宽的小平板因此不会看到被粗暴放大的手机 UI。PC 从 768px 起生效，但尺寸在 1024px 以下保持下限，窄窗口不会被过度压缩。

## 文字

字号不走纯 `vw`，而是 `rem + vw` 的混合公式：

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

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

静态部分用 `rem`，因此浏览器的文字缩放设置依然有效（WCAG 1.4.4）。纯 `vw` 文字会把用户的缩放选择完全吃掉。混合比例由 `fontFluidity` 控制，默认 `0.35`；在设计宽度处结果仍严格等于设计值。

## 根容器

传入 `rootSelector` 后，插件追加一个低优先级的 `@layer adaptive-matrix`：

- 根元素 `inline-size: 100%`，水平居中；
- App 与 PC 各自在流体上限处停止增长；
- 注入 `env(safe-area-inset-*)` 安全区变量；
- 发布根列宽与留白变量，并据此修正 `position: fixed`。

最后一条值得单独说：页面一旦成为居中的列，`position: fixed` 会退回以视口为包含块，底部导航栏就贴到了窗口两端，与它所在的内容列错开。`appPcPreset` 默认修正这一点，不需要时传 `fixedContainingBlock: false`。参见[配置参考](./configuration.zh-CN.md#fixedcontainingblock)。

已经自己管理根容器的项目省略 `rootSelector` 即可，插件不会注入任何全局 CSS。

### 组件化项目要指定注入位置

这段基础样式是全局的，但 PostCSS 一次只看见一个文件，没有跨文件去重的余地。所以默认每个被处理的文件都会拿到一份。

只有一份全局样式表的项目，这正是想要的。Vue / Svelte 项目则相反：**每个组件的 `<style>` 块都是独立的一个文件**，默认行为等于给 150 个组件各塞一份安全区变量和根列规则。

指到入口样式表上，就只注入一次：

```js
appPcPreset({
  rootSelector: '#app',
  rootInjectTo: 'src/styles/main',   // 字符串按「包含」匹配
})
```

也接受正则和函数，规则与 `include` 一致。直接写 `root` 时对应字段是 `root.injectTo`。

匹配不上不会报错，只是一份都不注入。用[命令行](./cli.zh-CN.md)确认一下最稳妥——入口文件应当出现 `+ inline-size 100%` 这类新增声明：

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

## 组件库

不需要配置。内置的 11 个主流库按各自设计画布换算，桌面端组件库保留真实像素，主题 token 按名字识别并走文字混合公式。完整清单与覆盖方式见[组件库适配](./libraries.zh-CN.md)。

## 局部关闭

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

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

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

这三个注释会**保留在产物里**。被忽略的 `40px` 和没人管过的 `40px` 长得一模一样，注释一旦被吃掉，产物再过一遍编译（预编译的依赖被消费方再编译一次就是这种情况）就会把它换算了。注释本身会被任何压缩器去掉。

范围更大的排除用 `propList`、`selectorExclude`、`valueExclude`、`exclude`，或用 `routes` 把某一片 CSS 改派到 `profile: false`。

## 验收尺寸

建议至少在这些宽度做视觉回归：320、375、480、767、768、1024、1440、1920、2560。

另测：浏览器 200% 文字缩放、iOS 安全区、Android WebView 软键盘、横屏、以及使用容器查询的组件。


---

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

# 构建工具集成

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

插件是标准 PostCSS 8 插件，凡是能配 PostCSS 的地方都能用。下面是各工具的接法，以及几个会静默出错的点。

## Vite

`postcss.config.mjs`（推荐，与 `vite.config.ts` 解耦）：

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

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

或写在 `vite.config.ts` 里：

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

**两者不能同时存在。** Vite 一旦发现 `css.postcss` 是内联对象，就不再读 `postcss.config.*`。

## Nuxt

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

Nuxt 用的是对象形式，键是包名。要用 `appPcPreset` 就得改回 `postcss.config.mjs` 数组形式——预设返回的是一个对象，没法用包名键表达。

## Webpack

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

`postcss-loader` 要排在 `css-loader` 之后、预处理器 loader 之前：

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

## Taro

```js
// config/index.js
const config = {
  mini: { postcss: { /* Taro 自己的插件配置 */ } },
  h5: {
    postcss: {
      'postcss-adaptive-matrix': {
        enable: true,
        config: { defaultProfile: 'app', profiles: { /* ... */ } },
      },
    },
  },
}
```

小程序端建议只用单画布：小程序没有 `@media`，`query: false` 是必须的，`rpx` 也已经在做类似的事，两套换算叠加会翻倍。

---

## 四个静默出错的点

### 1. 插件顺序

放在 `autoprefixer` **之前**。`autoprefixer` 不会给 `clamp()` 加前缀，顺序反了不报错，只是白跑一趟。

放在 `postcss-nesting` 这类展开嵌套的插件**之后**也可以——两种顺序都正确，因为嵌套的 `@adaptive` 现在能正常处理（见[架构](./architecture.zh-CN.md#嵌套)）。

Sass / Less 不属于这个话题：预处理器在 PostCSS 之前跑完，PostCSS 拿到的已经是展开后的 CSS。

### 2. `from` 必须传

按文件路径判定画布的功能——`routes` 的 `file` 通道、`include` / `exclude`、组件库的路径匹配——全部依赖 PostCSS 的 `from`。

Vite、Webpack、Nuxt、Taro 都会传。但如果你手写 `postcss(...).process(css)` 而不传 `from`，文件路径退化成空串，所有 `file` 匹配静默失效——不报错，只是组件库不再被认领。

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

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

### 3. Vue SFC 的路径带 query 串

Vite 给 `<style>` 块的 `from` 长这样：

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

写 `file` 匹配时按**包含**去写，不要锚定结尾：

```js
routes: [{ profile: 'mobile', file: [/[\\/]mobile[\\/]/] }]   // 对
routes: [{ profile: 'mobile', file: [/\.mobile\.scss$/] }]     // SFC 匹配不到
```

Windows 与 POSIX 的分隔符不同，所以用 `[\\/]` 而不是 `/`。

### 4. 组件化项目的根容器基础样式会逐文件重复

配了 `rootSelector` / `root` 之后，插件会追加一段全局基础样式。它是全局的，但 PostCSS 一次只看见一个文件，没有跨文件去重的余地——所以默认**每个文件各一份**。

Vue / Svelte 里每个组件的 `<style>` 块都是独立文件，于是 150 个组件就是 150 份安全区变量和根列规则。不报错，只是产物白白变大。

```js
appPcPreset({
  rootSelector: '#app',
  rootInjectTo: 'src/styles/main',   // 只注入入口这一份
})
```

反过来，匹配不上就一份都没有，同样不报错。用 `npx adaptive-matrix src/styles/main.css` 确认入口文件里出现了新增声明。

---

## 原子化 CSS：Tailwind 与 UnoCSS

工具类 CSS 同样经过 PostCSS，所以同样会被换算——这正是你要的：`p-4` 和你手写的 `padding: 16px` 说的是同一个尺寸，应该得到同一个结果。

**但默认配置一个都读不到，而且不报错。** 装上插件跑一遍，手写的部分被换算了、工具类原样不动，两套尺寸从此对不齐。原因有两个，取决于你用的大版本。

包一层就都解决了：

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

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

`withAtomicCss` 是**包装**不是替换：你原有的 `profiles`、`routes`、`root` 全部保留，它只往上加需要的两件事。下面解释这两件事分别在挡什么。

### 挡路的第一件事：单位是 rem

Tailwind 3、UnoCSS `presetUno` / `presetWind3` 把长度直接写成 `rem`：

```css
.p-4      { padding: 1rem }          /* 不是 16px */
.text-lg  { font-size: 1.125rem; line-height: 1.75rem }
.border   { border-width: 1px }      /* 边框仍然是 px */
.p-\[13px\] { padding: 13px }        /* 方括号任意值也是 px */
```

同一张表里两种单位都有。所以要读的是**两种**，不是把 `px` 改成 `rem`：只读 `rem` 会漏掉所有边框宽度和方括号值，只读 `px` 会漏掉间距和字号。`withAtomicCss` 做的第一件事就是把 `rem` 加进 `unitToConvert`。

页面如果写了 `html { font-size: 62.5% }`，再配一个 `rootValue: 10`，读和写两头一起改，见[配置参考](./configuration.zh-CN.md#unittoconvert-与-rootvalue)。

### 挡路的第二件事：长度根本不在工具类里

Tailwind 4 和 UnoCSS `presetWind4` 换了形状——工具类里没有长度，只有一个变量引用：

```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()` 是不透明的，编译器看不进去。所以要在**源头**认领这些主题 token。自定义属性默认不换算（要么被显式认领，要么开 `transformCustomProperties`），`withAtomicCss` 加的正是这条认领路由。

认领 token 之后工具类不用动也对了：

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

`calc(clamp(a, b, c) * 4)` 等价于 `clamp(4a, 4b, 4c)`（正系数下乘法可以穿过 clamp），结果与直接换算 `16px` 逐位相同。

被认领的 token 前缀：`--spacing`、`--text-`、`--leading-`、`--radius-`、`--container-`。三个**故意不在**列表里：

| 没认领 | 原因 |
| --- | --- |
| `--breakpoint-*` | 它是画布**切换**的宽度。缩放它等于移动断点本身，而且没有任何地方会提示 |
| `--tracking-*` | 用 `em` 发布，而 `em` 依附的字号已经被做成流体了，再缩一次是叠加 |
| `--shadow-*` | 阴影的像素是按屏幕尺度画的层次感，不是设计稿上量出来的长度 |

主题里自己扩展的长度族用 `tokenPrefixes` 补：

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

### 字号 token 照样可缩放

`--text-lg` 这种名字不长得像字体属性，但它承载的就是字号。默认的 `textProperties` 里包含 `--text-*` 与 `--leading-*`，所以它拿到的是和手写 `font-size` 完全相同的 `rem + vw` 混合公式，浏览器文字缩放不受影响：

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

这一条对没有被认领的 token 不起作用——它只决定一个已经要换算的长度**怎么写**，不决定它换不换算。

### 这一节是对着真实产物写的

`conformance/cases/atomic/` 下的三个用例，输入是 Tailwind CSS 4.3.3、UnoCSS 66.7.5 `presetWind3`、UnoCSS 66.7.5 `presetWind4` 的**真实产物原文**，不是手写的仿制品——上面那两种形状的差别大到手写必然写成想象中的样子。用 `scripts/capture-atomic.mjs` 重新抓取。

这两个框架不是 devDependency：抓下来的 CSS 就是全部输入，把 `npm test` 绑在别人的发版节奏上换不来额外信息。

### 另一条路

不想加配置也可以让框架输出 px：UnoCSS 的 `@unocss/preset-rem-to-px`，Tailwind 3 改 `theme.spacing`。Tailwind 4 没有这条路——它的形状是 token 间接引用，与单位无关。

### 工具类走哪张画布

工具类没有类名前缀特征，所以它们走 `defaultProfile`。要让某一批工具类走别的画布，用 `routes` 的 `selector` 通道；主题 token 整体改派用 `withAtomicCss(base, { profile: 'pc' })`。

## 组件库按需引入

`unplugin-vue-components` 之类的按需引入，最终仍然是从 `node_modules` 里引 CSS 文件，路径通道照常命中，不需要额外配置。

但**不要**为了"性能"加 `exclude: [/node_modules/]`——那会把组件库的 CSS 整个排除在外，组件就回到原始像素，和你缩放后的页面对不齐。这正是[组件库适配](./libraries.zh-CN.md)要解决的问题。

## 校验

改完配置，跑一遍产物比看配置可靠：

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

输出是逐条声明的前后对照，不用启动构建、不用开浏览器。上面那个「`from` 必须传」的坑，也可以用 `--from` 先试一遍再上线。完整用法见[命令行预览](./cli.zh-CN.md)。

## 这一篇是跑过真实构建的

本文关于 Vite 的每一条说法都由 `test/vite.test.ts` 里的**真实 Vite 构建**验证，而不是靠 `postcss().process` 模拟。构建脚手架包含一个自动发现的 `postcss.config.mjs`、一份从 `node_modules` 里引入的依赖 CSS、以及一个由 `@vitejs/plugin-vue` 同款方式提供的 `<style>` 块，然后断言：

- 配置文件确实被 Vite 找到并生效（没生效时构建照样成功、样式表原样输出，没有任何地方会说话）；
- 依赖的 CSS 按 `node_modules` 路径落到组件库画布，产出与页面上等价尺寸**逐字节相同**；
- 带 query 串的 SFC id 能被包含式 `file` 路由命中；
- 同样的输入再构建一次，产物完全一致（watch / HMR 会反复跑同一条流水线）；
- 反过来，用 `/\.mobile\.css$/` 这种锚定结尾的写法，SFC 块确实静默留在默认画布上——上面第 3 条说的就是这件事，这条测试让它成为验证过的事实而不是记忆。

Webpack 侧没有起真实构建。`postcss-loader` 做的事就是带着 `from` 调 `postcss.process`，而 Webpack 场景真正出过问题的是 CommonJS 入口能不能直接调用（0.4.0 修复），那一条由 `test/package.test.ts` 针对构建产物本身验证。为一条几乎没有独立风险的路径引入整套 Webpack 依赖，不划算。


---

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

# 命令行预览

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

改一个 `designWidth`、挪一次 `fluid` 区间，要看效果就得重新构建，再去浏览器里肉眼比对。这条命令把这一步缩短成一次回车：

```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
```

输出的是**逐条声明的前后对照**，不是整份 CSS。构建工具跑出来的产物动辄几千行，而你想确认的通常只有那么几个数字。

## 用法

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

| 选项 | 作用 |
| --- | --- |
| `-c, --config <path>` | 默认导出插件选项的模块，或一个写着选项的 `.json` 文件 |
| `--from <path>` | 把输入当作位于这个路径 |
| `--profile <name>` | 覆盖 `defaultProfile` |
| `--targets <list>` | 按你要支持的最低浏览器版本审计产物，如 `"safari 14, ios_saf 13"` |
| `--all` | 连未改动的声明一起列出 |
| `--css` | 打印编译后的完整 CSS，而不是对照表 |
| `--color` / `--no-color` | 强制开/关颜色；都不写则跟随终端，并遵守 `NO_COLOR` |
| `-h, --help` | 帮助 |

退出码：一切正常为 `0`，参数错误、文件读不到、配置非法为 `1`。所以可以直接串进 shell 判断。

## 读配置

不传 `-c` 就用内置默认值，表头会告诉你当前是哪几个画布。

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

配置模块要默认导出**插件选项对象**，不是 PostCSS 配置。两者不一样时单独写一个：

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

TypeScript 配置需要一个加载器：

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

（Node 22.6+ 自带类型擦除，直接 `npx adaptive-matrix -c adaptive.config.ts` 也能跑，但会打一条 experimental 警告，且只支持可擦除的写法。）

### 用 JSON 写配置

路径以 `.json` 结尾时，按文件读取，不走 `import`。在 `$schema` 里写上[已发布的 JSON Schema](https://moresyl.github.io/postcss-adaptive-matrix/schema/options.json)，编辑器就能补全选项名、显示每一项的说明，并在取值越界时当场标出来——不用等到跑起来：

```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` 不是配置项，读取时会被丢掉。

JSON 装不下正则和函数，所以按正则路由、或按文件动态算 `designWidth` 的配置只能继续用 JavaScript 写。Schema 里这些位置都用 `x-also` 标了出来。

配置在读第一个样式文件之前就会被校验，所以 `defaultProfile` 写错、`fluid` 区间反了，报的是编译器自己的那句话，不会先刷一屏对照表再报错。

`default` 漏写（`export const options = {...}`）或预设忘了调用（`export default appPcPreset` 而不是 `appPcPreset({...})`）都会直接报错。这两种写法此前会静默地用内置默认值跑完——表头照样列出画布，对照表看着也对，没有任何地方说过你的配置根本没被读到。

## 验证文件路由

按路径判定画布是最容易配错、又最不容易发现的一项——写错了不报错，只是路由静默失效（见[构建工具集成](./integration.zh-CN.md#2-from-必须传)）。`--from` 就是用来在上线前把路由试一遍的：

```bash
# 同一份 CSS，假装它在 desktop 目录下
npx adaptive-matrix scratch.css -c adaptive.config.mjs --from src/desktop/scratch.css
```

两次输出的数字不一样，说明路由命中了。一样，就是没命中。

Vue SFC 的路径带 query 串，照抄进去即可：

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

## 断点处的倒退

两张设计稿各自都对，接缝处未必对。这个检查专门找一种情况：**窗口变宽，某个尺寸反而变小了。**

```
  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` 的字号在 App 稿上写 16px、PC 稿上写 18px，两个数字单独看都合理。但 App 稿到 767px 时已经流体放大到 17.57px，而 PC 稿从 768px 起步只有 16.18px。于是把浏览器拉宽一个像素，正文字号会突然变小。

之所以值得单独检查，是因为它**只在那一个宽度上出现**：两张稿子各自渲染都正常，日常调试的 375 和 1440 也都正常。

编译器输出的每一条公式，其**绝对值**在视口宽度上都是单调不减的，而且全程不变号。所以一旦出现倒退，来源只能是跨断点换了画布。这也意味着这个检查是完备的：这一类问题不会漏报到别的宽度上去。

### 只检查编译器自己产出的值

上面那句「来源只能是跨断点换了画布」只对**本编译器产出的公式**成立。没被换算的样式表在断点处变小，往往是作者有意为之：

```css
/* Quasar 2.19 自己的样式表 */
.q-tooltip { padding: 6px 10px }
@media (max-width: 599.98px) { .q-tooltip { padding: 8px 16px } }
```

手机上点击区域大一些，600px 往上收窄——两个数字都是人手写下的，作者比对过。Quasar 是「保留像素」条目，两侧都没被换算，报它没有意义。

所以只有**至少一侧是编译器产出的公式**时才报。有界流体尺寸没有不带包装的写法，编译器产出的视口相关长度一律在 `clamp()` / `min()` / `max()` / `calc()` 里（69 份一致性套件产物中无一例外），据此判断。一侧换算、另一侧没有，照样报——那正是一次跨画布，而且没有人比对过这两个数字。

代入发生在判断之前，所以「声明只写了 `var(--x)`、公式在 token 里」也算数。

比的是绝对值而不是数值：负长度（负外边距、外溢）本来就靠远离零来变大，`-16px` 编译出的公式是越宽越小的。断点两侧变号则一律不报——零是编译器自己不会跨过去的界，在这里遇到它说明两张稿的意图本就不同，谁对谁错不是这个检查能判断的。

怎么改由你决定——抬高 PC 稿的字号、把 `pcFluidMin` 从 1024 降到 768、或者收窄 App 稿的 `fluid.maxWidth`。工具只负责告诉你接缝在哪。

检查刻意收得很窄，宁可不报也不误报：只比对同一个选择器串、不做优先级推算、不展开简写；遇到 `@supports`、`@container`、非纯宽度的媒体查询、跨层叠层的分组，以及 `env()` / `%` / 容器单位这类算不出数值的值，整组跳过。

### 主题 token 会被代入

组件库的尺寸几乎不写字面量。Vant 4.10.0 的 3198 条普通声明里，有 1173 条完全经 `var()` 读取——检查若在第一个 `var(` 就放弃，看到的就只是一小片，而且恰好避开了本插件要适配的那一层。

所以同一份样式表里的自定义属性会先被代入，再求值：

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

这里 `.card` 在 768px 处从 40px 掉到 20px，代入之后才看得见。

代入只在值由**视口宽度单独决定**时进行，两条都要满足：

- 只声明在 `:root` / `:host` / `html` 上，别处没有第二份。`.van-theme-dark { --card-width: ... }` 一出现就整个放弃——元素的取值取决于祖先有没有那个 class，这不是宽度能回答的。
- 每一处声明要么无条件，要么位于纯像素宽度的 `@media` 里。`@supports`、`@container`、方向查询里的声明同样放弃。

token 本身在断点处被改写也算一次接缝，即使消费它的规则只写了一次：

```css
:root { --card-width: 40px }
@media (min-width: 768px) { :root { --card-width: 20px } }
.card { width: var(--card-width) }   /* 只有一条，照样报 */
```

`var(--x, 16px)` 的兜底值只在 `--x` 确实没被声明时使用——这与浏览器一致。若 `--x` 被声明了但取值不可知（比如上面的主题 class），则不报，而不是拿兜底值当答案。

自定义属性声明本身（`--x: ...` 这一条）仍然不检查。它不是屏幕上的长度，方向对不对由消费方决定——本插件自己的 `--adaptive-root-width` 就是反的：它喂给 `max(0px, (100vw - var(--adaptive-root-width)) / 2)`，值变小正是为了让留白变大。跳过它不等于忽略它：消费它的那条声明会被检查，代入之后它的方向才有意义。

实测（Vant 4.10.0 完整样式表，195 KB）：可求值的值分量从 622 条（17.6%）升到 1309 条（36.9%），收录 779 个 token。剩下的是关键字、颜色和百分比——本来就不是视口相关的长度。

误报方面：69 份一致性套件产物、本仓库示例工程，以及 10 个组件库的已发布样式表（Vant、NutUI、Varlet、antd-mobile 1x/2x、Taro UI、Element Plus、Ant Design、Arco Design、Quasar，合计约 3.2 MB CSS），`shrinks` 报告数均为 0。见[组件库适配](./libraries.zh-CN.md#这张表是核对过的)。

要让构建直接失败，同一个检查也从包里导出：

```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} 处断点倒退`)
```

## 目标浏览器读不懂的语法

`--targets` 收一串「浏览器 + 你打算支持的最低版本」，逐条对着**编译产物**核：

```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
```

四行的顺序是有意的：先说**丢什么**，再说**换成什么**。「iOS Safari 13 太老了」单独拿出来没法行动，而 CSS 支持缺口真正要紧的一直是「跟着一起消失的有多少」——值读不懂丢一条声明，选择器读不懂丢一整条规则，`@` 规则读不懂丢一整块。

上面 `clamp()` 那条差的是**一个小版本**：13.4 就有了。人工比对版本号时这种差距最容易看漏。

目标全都够用时只有一行：

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

已知名字：`chrome`、`edge`、`safari`、`firefox`、`ios_saf`、`samsung`；`android`、`webview` 归到 `chrome`。名字不认识会报错并以 `1` 退出，不会静默跳过——被悄悄丢掉的目标比没有审计更糟，因为它读起来像通过了。

完整的特性 × 版本表、每一项的降级路径，以及编程式 API，见[浏览器特性支持与降级](./compatibility.zh-CN.md)。

## 看整份产物

要接着给别的工具处理，用 `--css`：

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

`--css` 模式的 stdout 只有 CSS，警告走 stderr。所以重定向出来的文件是干净的、可直接解析的 CSS，而警告依然会出现在终端里——不会被悄悄吞掉。

## 读懂输出

- `16px → clamp(...)` —— 换算了
- 灰色无箭头的一行 —— 原样保留（`--all` 才显示）。细线、`@font-face` 里的长度、被忽略注释标记的声明都在这里
- `+ ...` —— 编译器新增的声明，比如根容器基础样式、`preserveOriginal` 的降级值
- `@media (min-width: 768px) › .page` —— 声明所在位置由外向内。`@adaptive pc` 编译后就是这个样子，同一个 `.page` 出现两次是正常的
- `warning ...` —— 编译器的告警，原样透传
- `shrinks ...` —— 跨断点时尺寸倒退，见[断点处的倒退](#断点处的倒退)
- `needs ...` —— 目标浏览器读不懂的语法，只在传了 `--targets` 时出现，见[目标浏览器读不懂的语法](#目标浏览器读不懂的语法)

表头的 `+5 library canvases` 是内置组件库各自的画布。它们由注册表生成，不是你能在 `@adaptive` 里写的名字，所以只报个数。完整清单见[组件库适配](./libraries.zh-CN.md)。


---

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

# 组件库适配

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

## 问题

组件库有自己的设计稿，而且未必和你的一致。Vant 画在 375 上，你的页面可能画在 750 上，Element Plus 则根本没有设计稿——它按真实像素绘制，本来就不该缩放。

传统做法是把 `node_modules` 加进忽略名单。这只会把问题换个形状：页面缩放而组件不动，两者从此对不齐。反过来不忽略，组件就按错误的画布被拉变形。忽略名单能给出的选项只有这两个，都不对。

正确的做法是给每张设计稿一个画布。**这是默认行为，不需要配置。**

## 效果

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

```css
/* 输入 —— 四处都写 16px */
:root       { --van-padding-md: 16px }
.van-cell   { padding: 16px }
.el-input   { padding: 16px }
.page-hero  { padding: 16px }
```

```css
/* 输出 */
: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) }
```

Vant 的三项按 375 换算，Element Plus 原样保留，页面按 750 换算。三个不同的结果，各自都对。

## 内置清单

移动端——按各自设计画布换算：

| 名称 | 设计宽度 | 类名前缀 | Token 前缀 | 前缀命中率 |
| --- | --- | --- | --- | --- |
| `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 |

桌面端——按真实像素绘制，正确的适配就是不动它：

| 名称 | 设计宽度 | 类名前缀 | Token 前缀 | 前缀命中率 |
| --- | --- | --- | --- | --- |
| `element-plus` | 保留像素 | `el-` | `--el-` | 3180/3251 |
| `antd` | 保留像素 | `ant-` | — | 5941/6050 |
| `arco-design` | 保留像素 | `arco-` | — | 3462/3763 |
| `naive-ui` | 保留像素 | `n-` * | — | 运行时生成 |
| `quasar` | 保留像素 | `q-` * | — | 2080/3363 |
| `mui` | 保留像素 | `Mui` | — | 运行时生成 |

每一项同时按包路径匹配（如 `/vant/`、`/@nutui/`），因此产物是否分文件都能工作。

标 `*` 的三个前缀在自动模式下不启用，原因见下。† 见[没有前缀的 token](#没有前缀的-token)，‡ 见[同一个前缀，两张画布](#同一个前缀两张画布)。

### 这张表是核对过的

「前缀命中率」是该库**已发布样式表**里含此前缀的规则数 ÷ 总规则数，实测得到，不是照文档抄的。核对脚本在仓库里，可以自己跑：

```bash
npx tsx scripts/verify-libraries.ts          # 全部
npx tsx scripts/verify-libraries.ts vant     # 单个
```

它会下载每个库的发布产物，用真实的 `node_modules` 路径编译，然后检查：前缀与 token 前缀是否真的存在、路由落到哪张画布、是否幂等、有无告警、断点接缝检查是否误报。当前 12 项全部通过。

**未覆盖的一项：设计宽度。** 一张 CSS 里看不出它画在多宽的稿子上，这一列来自各库自己的文档，脚本核对不了。

`naive-ui` 与 `mui` 的样式在运行时生成，磁盘上没有样式表——不经过 PostCSS，也就无从核对。条目仍然有用：它们是「保留像素」，所以你手写的 `.n-button` 覆盖样式不会被缩放。

清单可以从代码读取：

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

## 匹配方式

一个条目最多提供三条通道，命中任意一条即归属该库的画布：

- **类名前缀**——不带点。`'van-'` 匹配 `.van-cell` 与 `.page .van-cell`，不匹配 `.caravan-slot`；
- **自定义属性前缀**——如 `'--van-'`。被认领本身就是开关，所以不受 `transformCustomProperties` 约束；那个开关管的是你自己写的变量；
- **文件路径**——构建产物仍然分文件时的兜底。

优先级：属性名 > 选择器 > 文件路径。

选择器高于文件路径，是因为选择器属于 CSS 本身，而路径只反映构建工具当时怎么摆放文件——打包器一旦把依赖内联进产物，路径就没了。属性名的理由相同且更强：主题 token 声明在 `:root` 上，除了名字之外不留任何来源痕迹。

## 一条规则只能有一个结果

选择器列表是有可能跨画布的：

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

`.van-cell` 归 Vant 画布，`.page-hero` 归默认画布，但 `padding: 16px` 只有一个值可以输出——CSS 无法让同一条声明对列表里不同的选择器给出不同结果。编译器取第一个命中的画布编译整条规则，另一个选择器就拿到了不属于它的换算。

这种情况会告警，并指出是哪个选择器落空了。拆成两条规则即可：

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

属性值里的逗号不是选择器边界，永远不拆。

`:is()`、`:where()` 里的逗号是参数分隔符而非选择器边界，但它造成的歧义与上面完全是同一个——`:is(.van-cell, .page-hero)` 依然是一条声明想要两个画布——所以同样会告警。不同的只是修复的代价，而这笔账由告警替你算：`:is()` 以其**最高**的那一支的特异度匹配每一支，因此把分支拆开只有在它们本来就一致时才是免费的。不一致时，告警会说出来，并指明拆分要付什么：

```
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.
```

## 一个选择器到底在说谁

`:not()` 和 `:has()` 根本不参与路由——至少它们的参数不参与：

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

这条规则修饰的是页面元素，而且恰恰是那些**不是** Vant cell 的元素。从中读出 `.van-cell` 并把整条规则送去 Vant 的 375 画布，得到的 padding 正好是作者要的两倍，而产物里没有任何东西会提示这件事。`:has()` 同理：`.page-card:has(.van-icon)` 是一张页面卡片，不管它里面装了什么。

所以路由看的是选择器的**主体**，`:not()` 与 `:has()` 的参数在做任何匹配之前就被摘掉。`:is()` 和 `:where()` 是反过来的一类——它们的参数**就是**主体的候选项——所以那些被保留，也正因如此它们才是会跨画布、会告警的那一类。

这件事比上面这个手写例子看起来更要紧，因为原子化 CSS 框架成批产出这些形状。同一个 `space-x-4`，Tailwind 4 编译成 `:where(& > :not([hidden]) ~ :not([hidden]))`，UnoCSS wind3 编译成扁平的 `> :not([hidden]) ~ :not([hidden])`，UnoCSS wind4 则直接产出原生嵌套——一个工具类三种毫不相干的写法，而三者都把一个选择器塞进了功能性伪类里，且那个参数指的并不是这条规则修饰的元素。

## 主题 token

名字含有文字属性词段的 token 走 `rem + vw` 混合公式，而不是普通长度的纯 `vw`：

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

两个都识别为字号。若按普通长度输出，组件库的文字将不再响应浏览器缩放——用户调大字号，页面上你写的文字变大了，组件里的没变。

### 没有前缀的 token

Varlet 的自定义属性不带库前缀，直接叫 `--field-padding`、`--icon-size-md`、`--card-width`，声明在一个光秃秃的 `:root` 上。注册表因此**不给它写 `tokenPrefix`**：认领这些名字等于认领 `--card-width` 本身，而任何一个项目都可能自己定义同名变量，误命中是静默的。

影响范围有限——Varlet 自己的样式表按路径匹配，照常落到 375 画布。但如果你按官方做法在**项目 CSS 里**覆盖主题：

```css
/* 你自己的文件，路径不在 @varlet 下，名字也没有前缀可认 */
:root { --field-padding: 16px }
```

这一条不会被认领，需要显式写一条路由：

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

### 同一个前缀，两张画布

antd-mobile 把同一份样式表发布了两次：`bundle/` 画在 375 上，`2x/bundle/` 画在 750 上。类名和 token 名一模一样（实测 5.42.3：后者每一个长度恰好是前者的两倍，`font-size: 16px` 对应 `32px`），**只有路径能区分**。

只按 `.adm-` 前缀路由的话，2x 产物会按 375 换算，页面上每一个尺寸都是应有的两倍——没有报错，没有告警，全局偏大。

所以 `antd-mobile-2x` 这个条目是**限定路径**的：它的前缀通道要求路径同时命中才算数。限定路径的路由先于不限定的路由测试，因为「类名加路径」比「只有类名」更具体：

- 编译 `2x/bundle/style.css` → 750 画布；
- 编译 `bundle/style.css` → 375 画布；
- 打包器把依赖内联、路径已经不存在时 → 退回 375，因为那是默认产物。

自动模式下两条都在，不需要配置。自己的库有同样情况时，`scoped: true` 是同一个开关：

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

`scoped` 却不给 `file` 会直接报错——限定路径是它认领别人前缀的全部理由，没有路径就退化成一个靠声明顺序决定胜负的重复条目。

## 自动模式下被保留的前缀

`naive-ui`（`.n-`）、`quasar`（`.q-`）、`taro-ui`（`.at-`）的前缀确实是官方前缀，但也和普通业务类名难以区分。自动模式下这三项**只按文件路径匹配**。

显式写出库名即表示该前缀在当前代码库中安全，此时前缀通道恢复：

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

误命中是静默的——它会按错误画布缩放某个元素，或跳过本该缩放的元素，没有报错也没有警告。默认从严，是因为错误的适配比没有适配更难发现。

## 覆盖内置项

用 `extends` 只改一项，其余继承。`name` 也随之继承，诊断信息与派生画布名仍指向读者认得的那个库：

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

这是唯一的入口。每个库会合成一张名为 `library:<名字>` 的画布，`library:` 是保留前缀——在 `profiles` 里直接写 `'library:vant'` 会被合成结果覆盖，等于白写，所以这种配置直接报错并指回 `extends`。

## 添加未收录的库

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

给出数组即表示只启用列出的条目——上面的配置里，除 Vant 和 acme-ui 外的内置库都不生效。

## 关闭

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

之后仍可用 `routes` 显式改派、`exclude: /node_modules/`、`selectorExclude` 和注释指令自行处理。

## 类型

```ts
type LibraryEntry =
  | string                                              // 内置名称
  | LibraryAdaptation                                   // 完整定义
  | (Partial<LibraryAdaptation> & { extends: string })  // 基于内置项修改

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

`basedOn` 指定借用哪张 profile 的流体区间、单位与策略，默认 `defaultProfile`。派生画布只替换 `designWidth`，因此它与页面在同一个视口宽度上停止增长——这正是组件和页面能保持对齐的原因。

派生画布还会继承所属 profile 的 `textAnchorWidth`（默认就是该 profile 的 `designWidth`），见下。

### 库画布的文字锚点

组件库画布与页面画布描述的是**同一份设计的两套单位**：Vant 画在 375、页面画在 750 时，Vant 的 16px 和页面的 32px 就是同一个尺寸，编译后在同一视口下必须渲染成同一个大小。

普通长度自动成立——两边都归结为 `值 ÷ 画布`。文字不然：为了让浏览器的文字缩放依然有效，文字保留了一段固定的 `rem`，而固定长度必须锚在某个宽度上。若两张画布各锚自己，这段 `rem` 会差整整一倍：

```text
页面 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)   ← 修正前
```

流体项两边本就相同，差的全在静态项。390px 视口下前者 26.62px、后者 16.22px——Vant 的文字小了约 40%，且 375 与 1440 上都看不出来（两张稿各自都对）。**750 稿的项目配 Vant 是国内移动端最常见的组合之一。**

因此派生画布的文字锚点取所属 profile 的设计宽度，两边产出同一个公式。这是默认行为，不需要配置。原理与推导见[静态部分锚在哪张画布上](./architecture.zh-CN.md#静态部分锚在哪张画布上)。

条目展开成若干条路由，追加在 `routes` 之后，所以你写的显式路由永远优先。


---

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

# 配置参考

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

全部选项、类型与默认值。上手请先读[快速上手](./getting-started.zh-CN.md)。

## 顶层配置

| 配置 | 默认值 | 说明 |
| --- | --- | --- |
| `profiles` | App/PC 预设 | 多设计画布映射 |
| `defaultProfile` | `app` | 普通 CSS 使用的画布 |
| `routes` | `[]` | 按选择器、属性名、断点或文件改派画布 |
| `libraries` | `'auto'` | 组件库适配，默认启用全部内置项 |
| `atRuleName` | `adaptive` | 自定义 At-rule 名称 |
| `strategy` | `clamp` | `clamp` 或兼容型 `viewport` |
| `unit` | `vw` | `vw`、`vi`、`cqw`、`cqi` |
| `precision` | `5` | 0~12 位小数 |
| `unitToConvert` | `['px']` | 读取的输入单位，也可以只传一个字符串 |
| `rootValue` | `16` | 一个 `rem` 折合多少像素 |
| `minPixelValue` | `0` | 小于该绝对值不转换 |
| `hairline` | `1` | 不转换的细线阈值 |
| `fontFluidity` | `0.35` | 文字流体比例，0~1 |
| `textProperties` | 字体相关属性 | 使用可缩放混合公式的属性 |
| `propList` | `['*']` | 支持 `*` 与 `!` 的属性表 |
| `selectorExclude` | `[]` | 字符串包含或正则排除 |
| `valueExclude` | `[]` | 属性值排除 |
| `include` / `exclude` | 无 | 文件字符串、正则、函数或数组 |
| `transformCustomProperties` | `false` | 是否转换 `--token` 值 |
| `preserveOriginal` | `false` | 是否保留原声明作为前置回退 |
| `root` | `false` | 可选根布局基础样式 |
| `unknownProfile` | `warn` | `warn`、`error`、`ignore` |

`propList` 示例：

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

`*` 不能省。只写排除项的 `['!border*']` 在语义上匹配不到任何属性，等于整份样式表都不换算——这种配置会直接报错，不会静默生效。

### 配置一律先校验

配置多半写在 `.mjs` 里，没有任何类型检查兜底，而这些字段写错的后果都是**静默的**——所以下列情况一律在读第一个样式文件之前就报错：

| 写法 | 后果 |
| --- | --- |
| `unit: 'vm'` | 输出 `4.267vm`。它不是长度，浏览器整条声明丢弃，元素保留继承值 |
| `strategy: 'viewpoint'` | 静默回退到 `clamp`，看起来像设置生效了 |
| `unitToConvert: ''` / `[]` | 匹配不到任何长度，与没装插件无法区分 |
| `rootValue: 0` | 每个 `rem` 读成 0，输出侧再除零 |
| `atRuleName: 'media'` | 样式表里每个 `@media` 都被当成画布名读取并改写。At-keyword 大小写不敏感，`MEDIA` 是同一个冲突 |
| `root.selector: ''` | 编译成 `:where()`，这是解析错误——整段基础样式连同安全区变量一起被丢弃 |
| `textAnchorWidth: 0` | 除零，文字长度整列变成 `Infinity` |

`unit` 与 `strategy` 在 profile 级别同样校验。

### unknownProfile

`@adaptive ghost` 里的画布名不存在时：

| 取值 | 行为 |
| --- | --- |
| `warn` | 告警，at-rule 原样保留 |
| `error` | 直接中断构建 |
| `ignore` | 不出声，at-rule 原样保留 |

`warn` 与 `ignore` 都保留原文，而浏览器读不懂 `@adaptive`，会把**整块丢弃**——块里的样式全部消失。区别只在于有没有人告诉你。画布名区分大小写（它是你自己在 `profiles` 里写的键），`@adaptive PC` 找不到 `pc`。

`@adaptive pc;` 这种没有块的写法会单独告警：没有块就没有任何东西被编译到那张画布上，它不会被改写成 `@media`。

### unitToConvert 与 rootValue

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

默认只读 `px`。传数组可以一次读多种单位——原子化 CSS 项目需要这个，见[构建工具集成](./integration.zh-CN.md#原子化-csstailwind-与-unocss)：

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

单位之间的换算规则只有一条：**`rem` 按 `rootValue` 折成像素，其它单位按面值读。**

`em` 也按面值读，这是刻意的。`em` 相对的是元素继承来的字号，那是运行时才知道的事，构建期没有任何常数能替它。把 `em` 当 `rem` 处理，只在两者恰好相等的地方是对的——而那在一份样式表里是少数。

`rootValue` 同时管两头：

- 读的时候，`1rem` 折成多少像素；
- 写的时候，文字的静态部分除以多少变成 `rem`。

所以页面写了 `html { font-size: 62.5% }` 就配 `rootValue: 10`，`3.2rem` 与 `32px` 会得到完全一样的产物，两边都对。只配一头会错一头，因此这里没有第二个选项可配。

`minPixelValue` 与 `hairline` 的阈值是**像素**，不是面值。框架把发丝线写成 `0.0625rem`、你手写成 `1px`，是同一根线，都会被 `hairline` 拦下。

## 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
}
```

把匹配到的 CSS 改派到另一张画布，`profile: false` 则保留像素不转换。字符串按「包含」匹配，正则按 `test` 匹配；`property` 按前缀匹配自定义属性名；`media` 匹配的是外层 `@media` 把这条规则限死在哪段宽度里——见[断点](#断点)。

一条路由声明了几条通道，就要几条同时命中。想让类名和文件各自独立生效，写成两条路由。

按目录划分两套互不响应的端口，是最常见的用法：

```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[\\/]/] }],
})
```

两张画布在同一个插件实例里判定，因此不会互相覆盖，也不需要为每一端各挂一次插件——同一段 CSS 只会被换算一次，先命中的画布就是最终结果。

判定优先级从高到低：

1. 外层 `@adaptive <profile>`——作者已经明确指定；
2. 命中的 `property` 路由；
3. 命中的 `selector` 路由；
4. 命中的 `media` 路由；
5. 命中的 `file` 路由；
6. `defaultProfile`。

选择器高于文件路径，是因为选择器属于 CSS 本身，而路径只反映构建工具当时怎么摆放文件；打包器一旦把依赖内联进产物，路径就没了。属性名的理由相同且更强：主题 token 声明在 `:root` 上，除了名字之外不留任何来源痕迹。

选择器高于宽度区间，理由则是另一回事：组件库在任何视口宽度下都画在它自己那张画布上，跨过一个断点并不会改变这个组件出自哪份设计稿。要在断点处覆盖组件库自己的组件，就把两者都写上——见下文。

## 断点

一份响应式样式表，是一个文件里装着两份设计稿。手机端那些数字量自 750 的稿子，`@media (min-width: 1024px)` 里那些量自 1440 的稿子。CSS 里没有任何地方写着这件事，而整个文件按一张画布编译，也不是「差一点」这么简单：

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

这条规则只在 1024px 以上生效，而那已经越过手机画布停止缩放的地方——所以在它生效的每一个宽度上，`clamp()` 早就顶死在上界了。这个 padding 永远是 32px。编译器跑过了，产物看着也像编译过，可没有一个值动过。

`media` 路由把这段断点交还给它原本那份设计稿：

```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)
```

匹配靠的是**蕴含关系，不是文本**。`{ minWidth: 1024 }` 认领的是「不可能在 1024px 以下生效」的规则，所以下面这些都算：

| 查询 | 生效区间 | 是否认领 |
| --- | --- | --- |
| `(min-width: 1024px)` | 1024px 及以上 | 是 |
| `screen and (min-width: 1200px)` | 1200px 及以上 | 是 |
| `(min-width: 64rem)` | 1024px 及以上 | 是 |
| `(min-width: 1024px) and (max-width: 1600px)` | 1024–1600px | 是 |
| `(min-width: 768px)` | 768px 及以上 | 否——它够得到 1024 以下 |

嵌套是「且」的关系，所以 `@media (min-width: 900px) { @media (min-width: 1100px) { … } }` 的生效区间是 1100px 及以上，会被认领。

`rem` 与 `em` 一律按 **16px** 折算，既不看 `rootValue`，也不看根元素的字号。媒体查询在任何声明能改动 `font-size` 之前就要求值，因此它不能依赖它自己所筛选的那一层层叠——哪怕样式表里 `html` 写着 `62.5%`，`64rem` 也还是 1024px。原子化框架的断点全都是这么写的。

编译器读不懂的查询——带逗号、带 `not`、带 `only`，或者任何非宽度特性——**谁都不认领**。这是「拒绝作答」，不是「全都匹配」：按一个没人核对过的条件去改派规则，正是画布错误产生的方式，而不是被抓住的方式。`@container` 同样从不参与计数；它约束的是元素，而 `vw` 从来就与元素无关。

要在断点处重画组件库自己的组件，两者都得写上——只写选择器会在所有宽度上生效，只写宽度区间又会输给组件库：

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

### 白送的那条告警

上面这些你一条都不用先知道，也能发现问题。只要一条规则确实换算了长度、而它的生效区间又整个落在所属画布的流体区间之外，编译器就会说出来：

```
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: '…' }.
```

这是算术，不是启发式：两个区间的数字压根不相交。每个文件里，同一张画布配同一段区间只报一次，而且只对真的换算了东西的规则报——一段只改 `display` 和 `color` 的断点里没有长度，也就无所谓常量不常量。

## libraries

```ts
type LibraryEntry =
  | string                                              // 内置名称
  | LibraryAdaptation                                   // 完整定义
  | (Partial<LibraryAdaptation> & { extends: string })  // 基于内置项修改

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

默认 `'auto'`：全部内置库生效，使用 Vant 或 Element Plus 的项目不需要任何配置。`false` 整体关闭。给出数组则只启用列出的条目。

条目展开成若干条路由，追加在 `routes` 之后——显式路由永远优先。

内置清单、匹配通道、覆盖与扩展方式见 [组件库适配](./libraries.zh-CN.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` 会移除 `@adaptive` 外壳但保留内部规则，适合构建不同产物时由环境选择 profile。

`textAnchorWidth` 默认等于 `designWidth`，只影响文字：文字有一段固定的 `rem`（用于保留浏览器缩放），固定长度必须相对某个宽度才有意义。手写画布用自己的设计宽度是对的；但当两张画布描述的是**同一份设计的两套单位**时（组件库画在 375、页面画在 750，Vant 的 16px 就是页面的 32px），各自锚在自己身上会让两边在任何视口下都对不上。组件库画布因此一律继承所属 profile 的锚点，无需配置。原理与实测见[静态部分锚在哪张画布上](./architecture.zh-CN.md#静态部分锚在哪张画布上)。

## RootFoundationOptions

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

默认不注入全局样式。只有显式配置 `root` 或在 `appPcPreset` 传 `rootSelector` 才启用。

### injectTo

限定哪些文件接收这段基础样式，默认全部。

基础样式是全局的，而 PostCSS 一次只看见一个文件，无法跨文件去重。单一样式表的项目正需要默认行为；Vue / Svelte 项目里每个组件的 `<style>` 块都是独立文件，默认就变成了每个组件一份。

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

匹配方式与 `include` 相同：字符串按包含判断，正则按路径测试，函数自行决定。`appPcPreset` 的对应字段是 `rootInjectTo`。

匹配不上不报错，只是一份都不注入——用[命令行预览](./cli.zh-CN.md)确认入口文件里出现了新增声明。

### logical

默认 `true`，基础样式写逻辑属性：`inline-size`、`margin-inline`、`max-inline-size`。

设为 `false` 改写 `width`、`margin-left` / `margin-right`、`max-width`。横排页面上两者等价，所以这个开关只有一个用途：**给读不懂逻辑属性的浏览器兜底**（Safari 15 / iOS 15.0 / Chrome 89 以下）。

它值得单独有个开关，是因为这是本插件产出的语法里唯一一个失败之后页面看起来还正常的：丢掉 `margin-inline: auto`，列宽完全正确、贴在屏幕左边；丢掉 `max-inline-size`，列铺满整屏。两种都不像故障。完整的失败清单与降级路径见[浏览器特性支持与降级](./compatibility.zh-CN.md)。

`appPcPreset` 的对应字段是 `rootLogical`；同理还有 `rootLayer`，透传到 `layer`。

### fixedContainingBlock

某个 profile 设了 `rootMaxWidth` 时，页面成为居中的列，而 `position: fixed` 会退回以视口为包含块——固定元素贴到窗口两端，与它所在的内容列错开。

开启后编译器发布两个变量：

| 变量 | 含义 |
| --- | --- |
| `--adaptive-root-width` | 当前断点下的根列宽，未设上限时为 `100vw` |
| `--adaptive-root-gutter` | `max(0px, (100vw - 列宽) / 2)`，即单侧留白 |

并对自身声明了 `position: fixed` 的规则做三件事：

- `left` / `right` / `inset-inline-*` 为 `0` 时替换为留白，非零时改为 `calc(原值 + 留白)`，`auto` 不动；
- `width` / `inline-size` 等为 `100%` 时改为 `min(100%, 列宽)`；
- 块轴（`top` / `bottom`）不处理——居中列只约束行内轴。

列宽等于视口时留白为 `0`，因此窄屏输出与手写完全一致。修正幂等，已含这两个变量的值不再二次处理。

只看规则自身的 `position` 声明：从别处继承定位是 CSS 不允许静态观察的，猜测比漏掉更糟。

`appPcPreset` 传了 `rootSelector` 时默认开启——该预设的两张 profile 都设了 `rootMaxWidth`，正是会出现这一问题的配置。用 `appPcPreset({ rootSelector: '#app', fixedContainingBlock: false })` 关闭。

## 旧 WebView 模式

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

这会输出原始 `px` 后再输出 `vw`。是否使用该方案应由真实目标浏览器决定；现代项目优先使用默认 `clamp`。

「真实目标浏览器」不必靠猜——`npx adaptive-matrix src/app.css --targets "ios_saf 13, chrome 90"` 会把产物里每一处超出目标的语法列出来，连同不支持时丢掉的东西和关掉它的开关。见[浏览器特性支持与降级](./compatibility.zh-CN.md)。


---

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

# 架构与转换公式

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

数字是怎么算出来的，以及编译器刻意不做的事。选项速查见[配置参考](./configuration.zh-CN.md)。

## 编译流程

1. 插件初始化时把 `libraries` 展开成路由，追加在 `routes` 之后。
2. 根据文件路径执行 `include` / `exclude`。
3. 为每条规则解析归属画布，优先级见[配置参考](./configuration.zh-CN.md#adaptiveroute)：`@adaptive` > 属性名路由 > 选择器路由 > 文件路由 > `defaultProfile`。
4. 使用 PostCSS AST 遍历声明，属性和值经过过滤器。
5. 使用 `postcss-value-parser` 解析值，跳过字符串和 URL 函数。
6. 把目标长度转换成有界流体表达式。
7. 规则内声明处理完毕后，若启用 `fixedContainingBlock` 且该规则自身声明了 `position: fixed`，修正其行内轴 inset 与宽度。
8. 把 `@adaptive` 改写为 `@media` 或 `@container`。
9. 如显式启用，最后追加低优先级根布局基础层。

第 7 步在第 6 步之后，因此它包裹的是换算后的流体值而不是原始像素。

## 普通长度

设设计宽度为 `D`、设计值为 `P`、流体下限和上限为 `L`、`U`。

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

负数会对边界重新排序，保证 `clamp()` 的最小值始终小于最大值。

### 单调性

`D`、`L`、`U` 为正数时，上式的**绝对值**对视口宽度单调不减：区间内按 `P` 的符号线性跟随，区间外是常数，且全程不改变符号。

`P` 为正时这就是「单调不减」。`P` 为负时公式是单调不增的——`-16px` 在 375 稿上编译成 `clamp(-20.48px, -4.26667vw, -13.65333px)`，视口越宽值越小。负长度（负外边距、外溢、反向偏移）本来就是靠远离零来变大的，所以真正守恒的量是绝对值，不是数值本身。

这条性质有个直接用处：产物里任何「视口变宽、尺寸绝对值反而变小」的现象都不可能来自公式本身，只可能来自跨断点换了画布——也就是两张设计稿在同一个元素上给了互相矛盾的数字。命令行据此做接缝检查（见[断点处的倒退](./cli.zh-CN.md#断点处的倒退)），而且这个检查在这一类问题上是完备的：不会漏到别的宽度上去。

按绝对值比较不是细节。最早那版检查直接比数值，于是对每一条负长度都是反的：PC 稿要求更深的外溢会被报出来，而外溢在断点处几乎消失反倒不报。

## 文字长度与可访问性

纯 `vw` 文字无法充分响应浏览器文字缩放。设 `F` 为 `fontFluidity`：

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

静态部分和上下界使用 `rem`，流体部分使用 `vw/cqi`。默认 `F = 0.35`，在设计宽度处仍严格等于设计值，同时在窗口变化与浏览器缩放之间取得平衡。

上下界同样用 `rem` 是关键的一步。用户把默认字号调大后，流体部分不跟着变，但下界跟着变——于是在高缩放档位上，`clamp()` 会落到下界，公式退化成纯 `rem`，缩放重新完全生效。

Chrome 实测（375px 视口，默认配置，`font-size: 16px`）：

| 根字号 | 正文实际字号 | 相对 |
| --- | --- | --- |
| 16px | 16.00px | 100% |
| 20px | 18.97px | 119% |
| 24px | 22.77px | 142% |
| 32px | 30.36px | 190% |

同一组测量里，`width` 与 `padding` 全程保持 343px / 16px 不变——只有文字随缩放变化，布局尺寸不会跟着膨胀。

这组数字只覆盖默认配置的一个断面。项目应继续执行 WCAG 200% 缩放验收；编译公式不能替代真实可访问性测试。

### 静态部分锚在哪张画布上

`P × (1 - F)` 是一段固定长度，不随视口变化，所以它必须相对**某一个宽度**才有意义。默认就是 profile 自己的设计宽度：1440 稿上的 16px 就是 1440 处的 16px，说的是什么就是什么。

但组件库画布不是这样。Vant 画在 375 上，页面画在 750 上，两者描述的是**同一份设计的两套单位**——Vant 的 16px 和页面的 32px 是同一个尺寸。此时若各自锚在自己的画布上，两个 `rem` 部分会差整整一倍，在任何视口下都对不上：

```text
页面 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)   ← 修正前
```

流体项 `1.49333vw` 两边本来就相同（`P × F / D` 与画布同比例约掉了），差的全在静态项。实测 390px 视口下页面 26.62px、Vant 16.22px，Vant 的文字小了约 40%——而这是国内移动端相当常见的一组搭配。

所以静态部分锚定的是 `textAnchorWidth`，组件库画布一律继承所属 profile 的锚点。实现上等价于「先把长度换算成锚点画布的单位，再照常套公式」：

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

流体项完全不变（`P_anchor × F / A ≡ P × F / D`），只有静态项被归一化。非文字长度 `F = 1`，静态项恒为 0，产物逐字节不变——这也解释了为什么此前只有文字对不上，`padding` 一直是对的。

`textAnchorWidth` 也可以在 profile 上显式设置，用于手写画布之间存在同样换算关系的场合。

## 容器查询

Profile 的 `query.type` 为 `container` 时，`@adaptive` 输出 `@container`。通常同时把 `unit` 设为 `cqi`，使组件尺寸依赖自身容器而不是浏览器窗口。

容器必须由应用已有布局或 `root.container` 建立。不要让元素查询自己；为可复用组件选择稳定的祖先容器。

## 不转换范围

- `url()`、`local()`、`format()`；
- 引号字符串；
- 已含视口/容器单位的 `clamp()`、`min()`、`max()`——见下；
- `@font-face`、`@page`、`@property`、`@counter-style` 里的声明——它们描述的是资源或页面盒子，不是元素。打印边距换成 `vw` 不是同一个边距；
- 默认的 CSS 自定义属性（被组件库 `tokenPrefix` 认领的除外——认领本身即是开关）；
- 小于 `minPixelValue` 的值；
- 不超过 `hairline` 的绝对值；
- 过滤器或注释明确排除的内容。

## 幂等

`clamp()` / `min()` / `max()` 内部只要已经出现视口或容器单位，里面的 `px` 就原样保留。

这类表达式是**已经写好的有界流体值**——可能出自作者之手，也可能出自本插件上一趟。它的 `px` 是这个表达式自己的边界，不是从设计稿上量来的尺寸，再换算一次等于缩放两次。

直接结果是产物幂等：同一段 CSS 跑一遍和跑三遍结果完全相同。插件在 PostCSS 链里被挂了两次、或者组件库预编译过又被消费方编译一次，都不会产生嵌套 `clamp`。

范围刻意只限这三个函数。`calc(100vw - 32px)` 照常转换——那里的 `32px` 确实是设计稿尺寸，只是恰好挨着一个视口单位。

幂等不止于长度换算，还包括另外两件事：

- **忽略注释保留在产物里。** 被忽略的 `40px` 和没人管过的 `40px` 长得一模一样，注释一旦被吃掉，第二趟就会把它换算了。注释会被任何压缩器去掉，而作者的「别动这里」必须活过一趟以上。
- **根容器基础样式只注入一次。** 产物开头有 `/* postcss-adaptive-matrix foundation */` 标记，第二趟见到它就整段跳过——既不会把 `max-inline-size: 480px` 这类固定上限当成设计稿尺寸再缩放，也不会叠出第二份。

一致性套件对**每一个**样例都断言了这一点：把产物再编译一遍必须原样返回。

## 嵌套

原生 CSS 嵌套里，`@adaptive` 与条件组规则（`@media`、`@supports`、`@layer`、`@container`、`@scope`、`@starting-style`）内部的声明属于外层元素，照常转换：

```css
.card {
  padding: 16px;          /* 默认画布 */

  @adaptive pc {
    padding: 32px;        /* pc 画布，并改写成 @media */
  }
}
```

插件没见过的 at-rule，内部的**规则**仍然会被处理，**直接声明**不会——未知语境下按元素样式处理是猜测。

## fixed 修正的边界

`fixedContainingBlock` 是唯一一处编译器改写定位的地方，它刻意做得很窄：

- 需要显式开启（`appPcPreset` 在建立居中列时默认开启，因为那正是问题出现的配置）；
- 只处理**规则自身**声明了 `position: fixed` 的情况。从其它规则继承定位无法静态观察，按选择器组合去推测会制造隐藏的运行时耦合；
- 只处理行内轴；
- 只在值为 `0` 或 `100%` 这类无歧义形态上做替换，其余一律用 `calc()` 叠加，且幂等。

除此之外，编译器不猜测设计意图，不自动移动侧栏，也不注入 JavaScript。复杂布局应由 CSS Grid、Flexbox、容器查询和明确的端口规则表达。


---

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

# 可选运行时

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

编译器本身不产生任何 JavaScript。这个模块是单独的入口，**默认不需要**，只有当 CSS 的视口单位和用户看到的可视区域对不上时才引入。

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

const observer = observeAdaptiveViewport()
// 组件卸载 / 页面离开时
observer.destroy()
```

## 什么时候需要它

CSS 的 `vw` / `vh` 指的是**布局视口**，浏览器有意让它在软键盘弹出、页面被捏合缩放时保持不动。多数情况这是对的行为。但有几种场景下它不是：

| 场景 | 现象 |
| --- | --- |
| 移动端软键盘弹起 | `100vh` 仍是全屏高，底部按钮被键盘盖住 |
| 用户双指捏合缩放 | 视口单位不变，固定元素飘出屏幕 |
| iOS Safari 地址栏收起/展开 | `100vh` 与实际可视高度差一条地址栏 |
| WebView / Capacitor / Tauri 外壳 | 宿主给的可视区域与布局视口不一致 |

这些都是 `VisualViewport` 才能看到的信息，CSS 拿不到。这个观察器把它读出来写成 CSS 变量。

## 发布的变量

调用后写在 `document.documentElement` 上（可用 `target` 改）：

| 变量 | 含义 |
| --- | --- |
| `--adaptive-width` | 可视区域宽度（px 数值，无单位） |
| `--adaptive-height` | 可视区域高度 |
| `--adaptive-layout-height` | 布局视口高度，即 `window.innerHeight` |
| `--adaptive-keyboard-height` | 软键盘遮挡高度，无键盘时为 `0` |
| `--adaptive-scale` | 当前捏合缩放倍数 |
| `--adaptive-vh` | 可视高度的 1%，**带 px 单位** |
| `--adaptive-vw` | 可视宽度的 1%，**带 px 单位** |

前五个是裸数值，要参与计算得自己加单位（`calc(var(--adaptive-keyboard-height) * 1px)`）；后两个已经带单位，可以直接当 `vh` / `vw` 的替代品用。

## 典型用法

真·全屏高度，不受地址栏影响：

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

回退值 `1vh` 很重要——运行时没加载、或者在 SSR 首屏时，样式依然成立。

底部操作栏避开软键盘：

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

## 选项

```ts
observeAdaptiveViewport({
  prefix: 'adaptive',        // 变量前缀，写不写开头的 -- 都行
  target: document.documentElement,
  window: globalThis.window, // 多窗口 / 测试时注入
  document: globalThis.document,
})
```

返回：

```ts
interface AdaptiveViewportObserver {
  update(): AdaptiveViewportSnapshot | null   // 手动触发一次，返回本次读数
  destroy(): void                             // 解绑全部监听
}
```

## SSR

没有 `window` 时构造函数不报错，返回的观察器什么也不做，`update()` 返回 `null`。所以可以无条件在模块顶层调用，不需要包 `if (typeof window !== 'undefined')`。

但服务端渲染的首屏 HTML 里不会有这些变量，因此**每处使用都要写回退值**，否则首帧会拿到空值。

## 开销

更新走 `requestAnimationFrame` 合并，一帧最多写一次；监听全部是 `passive`。不使用时不引入——它是独立入口，不会被主包带进去。


---

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

# 浏览器特性支持与降级

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

编译器产出的不只是数字。`clamp()` 是语法，`@layer` 是语法，`:where(#app)`、`env(safe-area-inset-top)`、`inline-size` 全都是语法——每一项都有自己的支持门槛，而它们的门槛差了将近十年。

这一页把门槛列全，并且对每一项回答同一个问题：**不支持的时候，丢掉的是什么，以及关掉它要付什么代价。**

## CSS 不报错，它丢弃

这是整页的前提。浏览器遇到读不懂的 CSS 不会抛异常、不会退回上一个值、也不会在控制台留话，它只是把读不懂的那一段**当作没写过**。丢弃的范围取决于读不懂的东西在哪一层：

| 读不懂的是 | 作废的是 | 例子 |
| --- | --- | --- |
| 一个值 | 这条声明 | `padding: clamp(...)` → 这个元素没有 padding |
| 一个选择器 | 这条规则整块 | `:where(#app) { ... }` → 根容器的所有声明 |
| 一条 @规则 | 这个块里的全部 | `@layer { ... }` → 整套根基础样式 |

所以排查顺序不是按「哪个特性更新」，而是按**丢得多**。下面的顺序、以及 `COMPAT_FEATURES` 表在代码里的顺序，都是这么排的。

## 最低版本

| 特性 | 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 |
| 原生嵌套 ³ | 120 | 120 | 17.2 | 17.2 | 117 | 25 |

¹ caniuse 没有 `:where()` 的独立条目，这里取 `:is()`。不是凑数：两者出自同一节规范，在 Chrome 88、Firefox 78、Safari 14 同批发布。
² 同理，`vi` 走 `svh` / `lvh` / `dvh` 那个条目——同一批规范、同一批发布。
³ `:has()` 与原生嵌套编译器都**不产出**；列在这里是因为它们经由你自己的 CSS 或组件库进入产物，发出去了就是发出去了。嵌套不靠猜就识别不了，所以不识别；`:has()` 识别得了，所以识别。见下文。

`:has()` 那一行要横着读。Chrome 2022 年就有了，Safari 更早，Firefox 直到 2023 年底才有——表里首尾差距最大的一行。也是唯一一行会出现「三个浏览器里看起来完全正确，第四个里整条规则不见了」的。

数据取自 caniuse-lite `1.0.30001809`，由 `scripts/capture-compat.mjs` 烘焙进 `src/core/compat-data.ts`。

## 逐项：丢什么，怎么关

### `@layer` —— 丢得最多的一项

**谁产出它**：`root.layer`。`appPcPreset` 只要给了 `rootSelector` 就会设成 `'adaptive-matrix'`。

**丢什么**：整个 `@layer` 块作废，根基础样式**一次性全没**——居中的列、安全区变量、固定定位修正，一起消失。这是表里单项损失最大的一条。

**怎么关**：`root: { layer: false }`，同样的规则不加包装地输出。代价是层叠位置：基础样式原本靠「在更低的层」必输给你自己的 CSS，去掉之后就要按普通优先级和你竞争。原来随手就能覆盖的地方，可能得写成真选择器。

### `:where()`

**谁产出它**：每一条根基础样式规则，`root.selector` 被包在里面。

**丢什么**：选择器读不懂，规则整条作废——和丢 `@layer` 同样的结果，只是一条一条丢。

**怎么关**：`root: false`，把基础样式整个去掉。生硬，但这是受支持的路径。没有「输出裸选择器」的选项，因为**零优先级正是它存在的理由**：它让你的 CSS 不必打优先级官司就能覆盖基础样式。给了那个开关，等于给了一个静悄悄改变层叠行为的开关。

### `:has()`

**谁产出它**：这里没有谁。它从你自己的 CSS 或组件库进来，原样穿过这一趟编译，然后被发出去。

**丢什么**：和任何读不懂的选择器一样，整条规则作废。它值得单列一行，不是因为损失有多大，而是因为支持是**什么时候**到的。`:has()` 是日常在用的选择器里最新的一个，四个引擎之间隔了好几年——Chrome 105 是 2022 年 8 月，Safari 15.4 还更早，Firefox 要到 2023 年 12 月的 121。一份在 Chrome 和 Safari 上都验收过的样式表，在旧一点的 Firefox 里可能正无声地少着若干条规则。

**怎么关**：这不是开关的事，是改写的事。把条件改成表达在元素自己身上：组件在有那个子元素时本来就会加的类名，或者在 `:has(*)` 其实想说「非空」的地方用 `:not(:empty)`。

路由不受影响。`:has()` 的参数说的是这个元素**装着**什么，而不是它画在哪张设计稿上，因此在判定规则归属画布之前就被摘掉了——`.page-card:has(.van-icon)` 是一张页面卡片，不管它里面装了什么。见[组件库适配](./libraries.zh-CN.md#一个选择器到底在说谁)。

### `@container` 与容器单位 `cqw` / `cqi`

**谁产出它**：`root.container: true`；`query: { type: 'container' }` 的 profile；`unit: 'cqw'` 或 `'cqi'`。

**丢什么**：`container-type` 声明作废，这一条很安静；`@container` 块整个作废，这一条不安静——靠容器查询切换的 profile 不再切换，默认画布之外的画布全部消失。容器单位则和 `clamp()` 一样，连着声明一起丢。

**怎么关**：`root: { container: false }`，profile 查询改用 `type: 'media'`，`unit` 改回 `'vw'`。媒体查询量的是视口而不是祖先元素——除非组件真的会在一个可拖拽的面板里独立重排，否则你要的本来就是视口。

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

**谁产出它**：`strategy: 'clamp'`（默认）下的每一个换算长度，以及 `root.fixedContainingBlock` 的留白算术。

**丢什么**：每条带它的声明作废，属性退回继承值或初始值。不是「尺寸有点不对」，是**根本没有尺寸**。

**怎么关**：两个选项，可以叠加。

```js
adaptiveMatrix({
  ...appPcPreset(),
  strategy: 'viewport',    // 输出裸的 vw，不带上下界
  preserveOriginal: true,  // 前面再留一条原始 px 声明
})
```

`strategy: 'viewport'` 换成裸视口长度，支持面几乎无死角，代价是没有边界——设计会一路缩放出流体区间的两端。`preserveOriginal` 是另一半：原始像素值作为前一条声明保留下来，丢掉流体那条的浏览器落在设计稿尺寸上，而不是落在虚无里。

### 逻辑属性 `inline-size` / `margin-inline` / `max-inline-size`

**谁产出它**：根基础样式，只要配了 `root`。

**丢什么**：逐条作废。**这是表里唯一一个失败之后页面看起来还挺正常的**：丢了 `margin-inline: auto`，列宽完全正确、稳稳地贴在屏幕左边；丢了 `max-inline-size`，列直接铺满。两种结果都不像「不支持」，像是有人这么设计的。正因为不像故障，它比 `@layer` 那种一眼可见的崩塌更容易活着上线。

**怎么关**：`root: { logical: false }`，改写 `width`、`margin-left` / `margin-right`、`max-width`。横排页面上什么都不损失——两种拼法在书写模式变化之前是同一件事。

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

### `vi`

**谁产出它**：`unit: 'vi'`。

**丢什么**：声明作废。

**怎么关**：`unit: 'vw'`（默认值）。`vi` 跟随书写模式，两者只在竖排文字或旋转过的根元素上才有区别；横排页面上它们量的是同一段长度，而 `vw` 从 Safari 6.1 就有了。

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

**谁产出它**：`root.safeAreaVariables`。

**丢什么**：这一条值得说准确，因为兜底参数做的事和它看起来要做的事不一样。`env(safe-area-inset-top, 0px)` 里的 `0px`，兜的是**浏览器认识这个环境变量但没有值**的情况——不是浏览器压根没听说过 `env()` 的情况。后者会让 `--adaptive-safe-top` 持有一个读不懂的值，而所有通过 `var()` 读它的声明在计算值阶段一起作废。

**怎么关**：`root: { safeAreaVariables: false }`。所有没有 `env()` 的浏览器，也都早于它要绕开的那些刘海——没有需要补偿的东西。

### `var()`

**谁产出它**：`root.safeAreaVariables` 和 `root.fixedContainingBlock`，以及你自己 CSS 里经过编译器的设计 token。

**丢什么**：声明作废。

**怎么关**：`safeAreaVariables: false` + `fixedContainingBlock: false` 去掉编译器引入的那几个。Safari 10 / Chrome 49 就支持了，所以这一条通常是拿来打勾的，不是拿来动的。

### `vw`

**谁产出它**：`unit: 'vw'`（默认），以及根列宽的算术。

**丢什么**：声明作废。

**怎么关**：没有，也不需要。这是表里最老的一项（Safari 6.1，2013 年），比其余每一条都早。关掉它等于不做自适应。

### 原生嵌套

**谁产出它**：没有人。编译器**读**嵌套规则——包括嵌在里面的 `@adaptive`——然后把每条声明写回原处。嵌套出现在你的产物里，只可能是因为它本来就在你的源码里。

**怎么办**：上线前拍平。Sass 和 Less 本来就会拍，纯 CSS 用 postcss-nesting。审计**刻意不去猜**：靠模式识别原生嵌套会把普通 CSS 误读成嵌套，报错比不报更糟。

## 一条命令跑完审计

给 `--targets` 一串「浏览器 + 你打算支持的最低版本」：

```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
```

（上面是本仓库 `examples/app-pc` 的真实输出，只截短了长句。注意 `clamp()` 那条：iOS Safari 13 差的不是一个大版本，是一个小版本——13.4 就有了。这种差距肉眼比对版本号时最容易看漏。）

目标全都够用时只有一行：

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

已知名字：`chrome`、`edge`、`safari`、`firefox`、`ios_saf`、`samsung`；`android` 和 `webview` 归到 `chrome`（那本来就是它们跑的东西）。名字不认识**会报错并以 1 退出**，不会静默跳过——一个被悄悄丢掉的目标比没有审计更糟，因为它读起来像通过了。

### 审计读的是产物，不是配置

这是唯一能保证审计和输出永远不会走偏的做法。经预设、经组件库路由、经你自己手写 CSS 进入样式表的特性，都是你发出去的特性，读产物就都能看见。配置里读不出来的东西太多了。

## 让构建直接失败

同一套检查从包里导出，不经过命令行：

```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('目标名字写错了')
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)` 返回 `{ findings, satisfied, unknownBrowsers }`。另外导出的还有 `detectFeatures(css)`（只认特性、不比版本）、`COMPAT_FEATURES`（完整的特性表，`failure` 和 `fallback` 文案就在里面）、`FEATURE_SUPPORT`（版本数据）、`compatFeature(id)`。类型齐全。

## 数据的口径

**版本号烘焙进包里，caniuse-lite 只是 devDependency。** 「某个特性从哪个版本开始能用」是不会再变的历史；插件因此不需要为它增加任何运行时依赖，离线也能审计。

**故意不看使用率。** 0.4% 的用户算不算数，是关于你的项目的决定，不是关于这份样式表的事实。`browserslist` 已经是回答那个问题的地方了。

**`--targets` 收的是显式的「名字 + 版本」，不是 browserslist 查询。** 查询要拉进 browserslist 包，回答的是关于你的用户的问题而不是关于这份样式表的问题，而且**同一条查询会随着数据库更新而改变含义**——今天通过的构建，下个月数据一更就红了，而代码一个字没动。显式版本号不会这样。

**扫描的是「从此再没断过支持」的版本**，而不是第一个出现 `y` 的版本。个别特性发布后又被撤回过，取前者才是「从这个版本起可以放心」的答案。caniuse 写成 `13.4-13.7` 的区间是它自己不单独跟踪的版本段，审计取低端。

## 这不能代替真机

说清楚这份审计能证明什么：**你的目标浏览器都能解析这份 CSS 里的每一处语法。** 仅此而已。

它不能证明页面在那台设备上好看。真机测的是别的东西——渲染差异、软键盘顶起视口、地址栏收起时的高度跳变、WebView 的自定义行为。这些在[可选运行时](./runtime.zh-CN.md)里有对应的补丁，但那是另一个问题。

反过来说，版本门槛这件事真机也测不了：手上那台 iPhone 是 iOS 17，它读得懂 `@layer` 这个事实，对「iOS 15.4 以下读不懂」没有任何说明力。要把这件事测出来，需要的是一柜子旧设备，而不是一台好设备。审计做的正是这一半——而且做得比一柜子设备更全。

## 相关

- [配置参考](./configuration.zh-CN.md) —— 上面每个开关的完整语义
- [命令行预览](./cli.zh-CN.md) —— `--targets` 和其余选项
- [可选运行时](./runtime.zh-CN.md) —— 软键盘、地址栏、WebView
- [发布与兼容性](./release.zh-CN.md) —— 产物格式与 Node 版本


---

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

# 迁移指南

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

从任何一种「px 换算成视口单位」的方案迁移，步骤都一样：先让输出对齐，再逐步启用新能力。按概念对照，不必逐个配置项去找同名替代。

## 第一步：只换等价物

先不引入任何新特性，让新旧产物尽可能接近：

```js
adaptiveMatrix({
  defaultProfile: 'app',
  profiles: {
    app: {
      designWidth: 375,     // 原来的视口基准宽度
      fluid: { minWidth: 320, maxWidth: 480 },
      query: false,         // 不生成媒体查询外壳
    },
  },
  precision: 5,             // 原来的小数位数
  strategy: 'viewport',     // 输出纯 vw，与旧方案同形
  libraries: false,         // 组件库适配也先关掉
})
```

`strategy: 'viewport'` 输出的是不带边界的 `vw`，与传统方案逐字节可比。此时差异只应来自舍入。

## 第二步：概念对照

| 你原来配置的东西 | 这里的位置 |
| --- | --- |
| 设计稿宽度 / 视口基准宽度 | profile 的 `designWidth` |
| 小数位数 | `precision` |
| 输出单位 | `unit`，或某个 profile 的 `unit` |
| 属性白/黑名单 | `propList`（支持 `*` 与 `!`） |
| 选择器黑名单 | `selectorExclude` |
| 属性值黑名单 | `valueExclude` |
| 最小转换像素值 | `minPixelValue` |
| 文件包含/排除 | `include` / `exclude`，额外支持函数 |
| 保留原声明作为回退 | `preserveOriginal: true` |
| 根容器选择器 | `root.selector` |
| 桌面端最大展示宽度 | `fluid.maxWidth` + `rootMaxWidth` |
| 忽略注释 | `adaptive-ignore` / `adaptive-ignore-next` / `adaptive-ignore-rule` |

两处需要换个想法，而不是换个名字：

**横屏不是全局开关。** 新建一个 landscape profile 并给它明确的媒体查询，横屏就拥有自己的设计宽度和缩放区间，而不是从竖屏推算出来的比例。

**桌面宽度不是设计宽度。** 如果 PC 只是把移动版居中展示，那它没有自己的设计稿，用 app profile 加 `rootMaxWidth` 即可。如果 PC 有独立设计稿，就给它独立的 `designWidth`，把差异写进 `@adaptive pc`。这两件事以前常被同一个配置项表达，在这里是两种不同的结构。

## 第三步：逐项启用

确认视觉一致后，按顺序打开：

1. `strategy` 改回默认 `clamp`——尺寸获得上下界，大屏不再无限放大；
2. 移除 `query: false`，或改用 `appPcPreset` 引入 PC profile；
3. 删掉 `libraries: false`，组件库按各自画布适配（详见 [组件库适配](./libraries.zh-CN.md)）。这一步通常可以顺带删掉原方案里为组件库写的整段忽略名单；
4. 需要居中列时配置 `root`，`fixedContainingBlock` 会一并处理固定定位元素。

## 验收

- 保存旧产物作为视觉基线；
- 覆盖 320、375、480、768、1024、1440、1920；
- 检查 fixed/sticky、弹窗、第三方组件和输入法；
- 执行 200% 浏览器缩放与键盘导航测试——文字混合公式的收益正是在这里体现，也只有真实测试能验证。


---

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

# 发布与兼容性

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

## 发布门禁

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

`check` 必须同时通过 TypeScript、覆盖率、测试和 ESM/CJS 构建。覆盖率门禁为行/函数/语句 80%，分支 75%。

## 产物

- `dist/index.js` / `dist/index.cjs`：PostCSS 插件、预设、类型辅助；
- `dist/runtime.js` / `dist/runtime.cjs`：可选 VisualViewport 观察器；
- 对应 `.d.ts` 和 sourcemap。

## 浏览器策略

编译器运行在 Node.js，浏览器只接收 CSS。默认输出依赖 `clamp()`；容器 profile 额外依赖容器查询单位。不建议为了理论上的旧环境牺牲所有用户的现代能力。

「真实目标浏览器读不读得懂这份产物」不必靠估：

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

产物里每一处超出目标的语法都会被列出来，连同不支持时丢掉的东西和关掉它的开关。完整的特性 × 版本表见[浏览器特性支持与降级](./compatibility.zh-CN.md)。

## 版本策略

- patch：修复转换、类型或文档，不改变默认输出语义；
- minor：新增可选 profile、策略、运行时变量；
- major：默认公式、指令、输出顺序或最低运行环境变化。


---

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

# 面向 AI 的文档

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

接下来读这份文档的，多半不是人。一个被要求把这个插件接进项目的编码 Agent，只会抓一两个 URL，然后拿抓到的东西干活——它不会翻侧边栏，搜索框对它也没有意义。所以同一份文档还会以模型能直接消费的形态再发布一遍，并且和你正在读的页面出自同一份源文件，这正是两者不会各说各话的原因。

下面全部是普通的 `GET`，不需要密钥、不需要会话、不需要执行 JavaScript。

## 入口

| URL | 是什么 |
| --- | --- |
| [`/zh/llms.txt`](https://moresyl.github.io/postcss-adaptive-matrix/zh/llms.txt) | 精选索引：一页一行，外加一句「什么时候该打开它」 |
| [`/zh/llms-full.txt`](https://moresyl.github.io/postcss-adaptive-matrix/zh/llms-full.txt) | 全部页面按阅读顺序拼接，给上下文窗口足够大的模型 |
| [`/llms.txt`](https://moresyl.github.io/postcss-adaptive-matrix/llms.txt) | 同一份索引的英文版 |
| [`/llms-full.txt`](https://moresyl.github.io/postcss-adaptive-matrix/llms-full.txt) | 同一份全文的英文版 |

两者都遵循 [llms.txt](https://llmstxt.org) 约定。先取 `llms.txt`（约 3 KB），再按需要抓那两页就够了；`llms-full.txt` 约 150 KB，只有任务本身是开放式的时候才值得整份读。

## 任何一页，都可以直接拿到 Markdown

每一页都同时以源文件形式提供。在页面路径后面加 `.md`：

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

目录首页是 `index.md`——`/zh/docs/` 对应 `/zh/docs/index.md`。这就是仓库里的那个文件本身，而不是把渲染结果反推回文本：没有导航、没有主题、也没有需要剥掉的代码块外壳。

每一页大纲上方的三个按钮用的就是这条路径：**复制为 Markdown**、**查看原始 Markdown**，以及**用 Claude 提问**——它会把这一页连同问题一起带进对话。

## 全部配置项，以数据形式提供

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

一份 [JSON Schema](https://json-schema.org/) draft 2020-12 文档，覆盖每一个配置项：类型、允许值、取值范围、默认值。像「`precision` 是不是整数、上限是多少」这种问题，散文不是合适的载体——这份文档不需要被当成英文读就能回答它。

有三点值得知道：

- **默认值来自编译器本身。** 它们是在生成这份文件时从选项解析器里读出来的，不是抄过来的。代码里的默认值一变，这里在同一个提交里跟着变。
- **属性表按源接口做了类型校验。** 存在却没被描述的配置项会让构建失败，被描述却已经不存在的同样如此。
- **中英文都在同一份文档里。** `description` 是英文，`x-description-zh` 是中文。只有一份文档而不是每种语言一份，因为类型不是翻译。

JSON 写不出 `RegExp`，也写不出判断函数，而有几个配置项恰好接受它们。遇到这种情况，Schema 描述能用 JSON 表达的那一半，剩下的写进 `x-also`：

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

Schema 不只是拿来读的，也是拿来照着写的。命令行支持 `.json` 配置，只要在 `$schema` 里指向这份文档，编辑器在你敲的时候就会校验：

```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
```

## 怎么让 Agent 给出有用的答案

这个插件最核心的前提，恰恰是模型最容易一带而过的那一句，所以值得写进提示词里：**在知道一个 `px` 画在哪份设计稿上之前，它没法被换算。** 一个默认「全局只有一个设计稿宽度」的 Agent，会给出一份能编译、但是错的配置——页面缩放了组件库没有，或者反过来。

两种通常管用的问法：

> 先读 `https://moresyl.github.io/postcss-adaptive-matrix/zh/llms.txt`，再给这个项目做配置。我们的 App 页面画在 375 稿上，后台页面画在 1440 稿上，用了 Vant。

> 抓 `https://moresyl.github.io/postcss-adaptive-matrix/schema/options.json`，拿它核对我的 `postcss.config.js`。凡是取值不等于默认值的配置项，逐条说明它是什么、为什么可能会被这么设。

如果答案需要被验证而不是被相信：[一致性套件](../conformance/README.zh-CN.md)是一组纯数据的输入/输出对，[命令行](./cli.zh-CN.md)可以在不碰构建的前提下编译一份样式表并打印结果。

## 接着看哪里

- [文档索引](./README.zh-CN.md)——页面本身
- [配置参考](./configuration.zh-CN.md)——同一批配置项的散文版
- [在线试验场](./playground.zh-CN.md)——编译器就跑在页面里，可以随手验证一个答案


---

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

# 一致性套件

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

对这个编译器必须产出什么的、与语言无关的描述。

每个用例都是纯数据——CSS 文本与 JSON。这个目录里没有任何东西 import 参考实现，因此任何语言的任何实现都可以通过遍历 `cases/` 并比对字符串来做验收。

这套用例是本转换的**规范定义**。行为与用例不一致时，以用例为准，直到某个用例在改变行为的同一个提交里被有意更新。

> 用例文本本身保持英文，因为它面向的是其它语言的实现者。使用说明请见 [docs/](../docs/README.zh-CN.md)。

## 目录结构

```
cases/<group>/<name>/
  case.json      必需 —— 元数据与插件选项
  input.css      必需 —— 源样式表
  expected.css   必需 —— 精确的期望输出
```

## `case.json`

```jsonc
{
  "description": "One sentence describing the guarantee under test.",
  "from": "/project/src/app.css",   // 可选，默认 "/project/src/app.css"
  "options": { },                    // 可选，默认 {}
  "warnings": ["substring"]          // 可选，默认 []
}
```

- `options` 原样传给编译器。
- `warnings` 列出的每个子串必须恰好出现在一条告警里，且条数要与实际发出的告警数相等。

### 正则表达式的编码方式

JSON 没有正则字面量，所以接受模式的选项同时接受一个带标签的对象：

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

不支持正则的实现可以跳过使用这种形式的用例，但必须报告为「跳过」而不是「通过」。

## 那条通用不变量

除了要与 `expected.css` 一致，每个用例还必须满足一条没有专属 fixture 的规则：

> 把 `expected.css` 再编译一遍，必须逐字节返回原文。

它没有专属 fixture，是因为它不是一个特性——它必须处处成立。发布预编译 CSS 的包会再经过消费方应用的流水线一次，框架预设也可能不声不响地把编译器注册两遍。两种情况都不会自报家门，所以「对某人恰好写下来的那些用例幂等」的实现，其实并不幂等。

有三条行为的存在只是为了满足它：已经带视口单位的有界表达式不再处理、忽略指令保留在产物里、根基础样式由一条标记注释引入以抑制第二次注入。

## 刻意不覆盖的部分

接受**回调**的选项（`designWidth` 写成函数、函数式文件匹配器）无法表达成数据，因此不在这里覆盖，改由参考实现自己的单元测试验证。把它们排除在外是有意的：这套用例必须保持可移植。

## 运行

```bash
npm test                    # 校验全部用例
npm run conformance:update  # 按当前行为重写 expected.css
```

`conformance:update` 是一次快照刷新。务必读一遍产生的 diff——那里出现意料之外的变化，是行为回归，不是格式细节。

## 输出归一化

比对针对精确的输出字符串，只做这两项归一化：

1. `\r\n` 归一为 `\n`；
2. 忽略结尾的单个换行。

CSS 内部的空白是有意义的，因为保留作者的排版本身就是这个编译器的一项保证。


---

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

# App + PC 示例

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

先在仓库根目录构建一次，再用任意 PostCSS runner 处理 `input.css`：

```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` 里放的是配置本身，`postcss.config.mjs` 直接 import 它，所以改用 PostCSS 跑编译出来的是同一份东西。`--targets` 可选，加上之后会在对照表后面输出浏览器支持审计。

这个示例展示：

- App 375 设计稿与 PC 1440 设计稿在同一次构建里共存；
- 刘海屏的安全区变量；
- 细线保留，1px 边框还是 1px；
- 文字写成 `rem + vw`，浏览器缩放仍然够得着；
- 根容器限宽并居中。


---

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

# 更新日志

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

## 0.7.0 — 2026-08-11

### JSON 配置

- 命令行现在接受 `adaptive.config.json`，编译前会移除 `$schema` 元数据；JSON 损坏或顶层不是对象时，会给出清晰错误而不暴露内部调用栈。
- 发布的 JSON Schema 已描述 `$schema`，编辑器可以用与文档站相同的选项模型补全并校验 JSON 配置。
- JSON 文件通过 `readFile` 与 `JSON.parse` 读取，继续支持 Node 18；需要正则或判断函数时仍可使用 JavaScript 配置。

### 质量门禁

- `npm run check` 与 CI 新增 ESLint、Prettier、VitePress 源码类型检查、文档站构建，以及更严格的覆盖率阈值。
- 新增基于比值的性能预算，用编译器耗时对比 PostCSS 自身的解析与打印耗时，避免共享 runner 上不稳定的绝对毫秒限制。
- 补齐求值器、选择器扫描器、CLI、Schema、stdin、兼容性与错误路径测试；覆盖率达到语句 98.10%、分支 93.59%、行 99.35%。
- 新检查发现并修复两处真实问题：通过不受支持的路径序列化 value-parser 节点，以及未知值可能在生成产物中被写成 `[object Object]`。

## 0.6.0 — 2026-08-11

### 断点终于有了自己的画布

- **新增 `media` 路由通道。** 一份响应式样式表，是一个文件里装着两份设计稿：手机端那些数字量自 750 的稿子，`@media (min-width: 1024px)` 里那些量自 1440 的稿子。CSS 里没有任何地方写着这件事，而在此之前也没有任何地方能写。`routes: [{ media: { minWidth: 1024 }, profile: 'pc' }]` 把这段断点交还给它原本那份设计稿。
- 这不是「差一点」，所以它值一个特性而不是一句备注。750 画布、流体区间上界 600px 时，`@media (min-width: 1024px) { .hero { padding: 40px } }` 编译出的是 `clamp(17.07px, 5.33vw, 32px)`——而这条规则只在 1024px 以上生效，那已经越过画布停止缩放的地方，所以在它生效的每一个宽度上，`clamp()` 早就顶死在上界了。这个 padding 永远是 32px。编译器跑过了，产物看着也像编译过，可没有一个值动过。
- **匹配靠的是蕴含关系，不是文本。** `{ minWidth: 1024 }` 认领的是「不可能在 1024px 以下生效」的规则，因此 `screen and (min-width: 1200px)` 和 `(min-width: 1024px) and (max-width: 1600px)` 都算数，嵌套也天然成立——嵌套本来就是「且」。拿 params 当字符串比对会漏掉那个 `screen and`；而画布是「这条规则够得到哪些宽度」的事实，不是「这个查询是怎么拼写的」的事实。
- **媒体查询里的 `rem` 与 `em` 一律按 16px 折算**，既不看 `rootValue`，也不看根元素的字号。查询在任何声明能改动 `font-size` 之前就要求值，因此它不能依赖它自己所筛选的那一层层叠：哪怕样式表里 `html` 写着 `62.5%`，`64rem` 也还是 1024px。这是关于查询本身的事实，不是关于页面的假设；而只认 `px` 会让所有 Tailwind 与 UnoCSS 项目——它们的断点全写成 `rem`——变成读不懂的东西。断点连续性检查用的是同一个解析器，覆盖面一并扩到了这里。
- 编译器读不懂的查询——带逗号、带 `not`、带 `only`，或者任何非宽度特性——**谁都不认领**。这是「拒绝作答」，不是「全都匹配」：按一个没人核对过的条件去改派规则，正是画布错误产生的方式，而不是被抓住的方式。`@container` 同样从不参与计数；它约束的是元素，而 `vw` 从来就与元素无关。
- `selector` 路由仍然高于宽度区间：组件库在任何视口宽度下都画在它自己那张画布上，跨过一个断点并不改变这个组件出自哪份设计稿。一条路由可以同时写上两者——`{ selector: ['.van-'], media: { minWidth: 1024 }, profile: 'pc' }`——这才是「这个组件在桌面断点处被重画了」的说法。
- 空区间（`{}`）和反向区间（`minWidth: 1024, maxWidth: 600`）都是配置错误，直接抛出。前者匹配样式表里的每一条规则，等于用一种更慢的方式改 `defaultProfile`；后者一条都匹配不到。两者看上去都像能用的配置，所以都不能留给用户从产物里去发现。

### 死区告警

- **上面这些你一条都不用先知道，也能发现问题。** 只要一条规则确实换算了长度、而它的生效区间又整个落在所属画布的流体区间之外，编译器就会说出来，把两段区间的数字都报出来，并给出能修好它的那条路由。这是算术而不是启发式——两个区间压根不相交——而它正是多画布模型本来要防的那种失败，只不过是从模型唯一没盯住的那道门进来的。
- 每个文件里，同一张画布配同一段区间只报一次，而且**只对真的换算了东西的规则报**。一段只改 `display` 和 `color` 的断点是再普通不过的 CSS，里面没有长度，也就无所谓常量不常量；对这些报警会把真正该看的那条淹掉。第一版就是这么干的，那条测试正是从这里写出来的。
- 建议的修法会随情况变：当画布是被 `selector` 路由定下的，消息会改成让你写 `{ selector: […], media: … }`——因为光一条 media 路由会输给 selector 路由，照做等于什么都没做。不管用的建议，比没有建议更糟。
- **`appPcPreset` 现在不只写自己的断点，也读它。** 这个预设本来就宣称「桌面设计稿从 768px 起接管」——那个数字设定了两个 profile 的 `query`，所以 `@adaptive pc` 块能被正确地包上媒体查询。它只是从来不*读*媒体查询，于是手写的 `@media (min-width: 768px)` 块仍旧按手机画布编译：预设自己跟自己打架。现在两个方向都路由了，而且 `max-width` 那一半是显式写出来的、没有留给 `defaultProfile` 兜底——这样即便有人把预设摊进一份桌面优先的配置里，这一对路由说的仍然是它字面上说的那件事。
- 新增两个一致性用例 `breakpoints/media-route` 与 `breakpoints/dead-band`，覆盖「认领什么、拒绝什么，以及同一段区间只报一次」。

### 选择器路由

- 修正 **`:not()` 与 `:has()` 的参数在决定规则落到哪块画布**。`.page-hero:not(.van-cell)` 修饰的是页面元素——恰恰是那些*不是* Vant cell 的元素——却因为文本里某处出现了 `.van-cell` 这串字符而被送去 Vant 的 375 画布。这类规则里每一个长度都会变成应有尺寸的整两倍，而且是静默的。路由现在读的是选择器的**主体**：`:not()` 与 `:has()` 的参数指的是被修饰元素之外的另一个元素，在匹配之前就被摘掉；`:is()` / `:where()` / `:matches()` / `-*-any()` 的参数保留，因为那些确实是主体的候选项。在 11 份已发布组件库样式表、22,761 条规则上实测，其中 1,035 条含 `:not()` 或 `:has()`：画布归属**零**变化——库 CSS 的自身前缀总是落在被摘掉的部分之外。这个修复不付任何代价，堵上的是应用代码会一头撞进去的洞。
- **`:is()` / `:where()` 内部跨画布的列表现在会告警。** 此前文档把它写成「查不出来」。`:is(.van-cell, .page-hero) { padding: 16px }` 是一条声明想要两个画布，和逗号列表是同一个问题、只深了一层括号，而它一直在无声通过。
- 告警会说出**拆分要付什么代价**，是算出来的而不是丢给读者：`:is()` 以其最高的那一支的特异度匹配每一支，所以把分支拆开只有在它们本来就一致时才是免费的。不一致时，告警指明降幅——`:is() matches every branch at its highest, 1-1-0, so ".page-hero" would drop to 0-1-0`。这才让建议可执行；一个照做之后会悄悄改变层叠的告警，是会被学会无视的告警。每条规则只报一次：剩下的列表成因相同、修法相同。
- 新增 `src/core/selectors.ts`，零依赖：`splitSelectorList`、`routingSelector`、`nestedSelectorLists`、`specificity`、`compareSpecificity`、`formatSpecificity`、`splitIsSpecificityNeutral`。拆分识别字符串与属性选择器，`[data-x="a)b"], .c` 会正确拆成两支——只数括号会拆错。特异度按 Selectors Level 4 计算，含 `:where()` 计零、`:is()` / `:not()` / `:has()` 取最高分支、`:nth-child(n of S)` 计一个伪类加 `S` 的最高分支，以及四个单冒号历史写法的伪元素（`:before`、`:after`、`:first-line`、`:first-letter`）按元素计。新增 40 条单元测试。

### 浏览器特性支持审计

- **`:has()` 纳入审计。** 它是日常在用的选择器里最新的一个，四个引擎之间隔了好几年——Chrome 105（2022 年 8 月）、Safari 15.4，而 Firefox 要到 121（2023 年 12 月）。这是表里首尾差距最大的一行，而且失败发生在选择器层面：整条规则作废。一份在 Chrome 和 Safari 上验收过的样式表，在旧一点的 Firefox 里可能正无声地少着若干条规则。编译器不产出 `:has()`，它从你自己的 CSS 或组件库进来、原样穿过这一趟——而这正是「读**产物**」的审计能看见它的原因。与原生嵌套不同，它在文本里毫不含糊，所以是识别出来的，不是猜的。
- `scripts/capture-compat.mjs` 加入 `css-has` 并重新烘焙进 `src/core/compat-data.ts`；仍然不引入任何运行时依赖。

### 文档站

- **文档以站点形式发布**，中英双语，地址 `https://moresyl.github.io/postcss-adaptive-matrix/`。它是从仓库本身构建的，而不是从仓库的一份拷贝：`srcDir` 就是仓库根目录，所以 `docs/README.md` 里那条指向 `../conformance/README.md` 的链接，在站点上和在 GitHub 上是同一个道理，没有一个文件因此挪位置。搜索、暗色模式、编辑本页、最后更新时间一并到位。
- 唯一需要设计而不是配置的，是语言切换。VitePress 按页面**改写后**的位置解析相对链接，于是中文页顶部那句 `[English](./README.md)`——在 GitHub 上完全正确——在站点上会解回中文页自己。所以链接改为在**仓库里**按源文件路径解析，输出为绝对站内地址。页面再怎么挪，链接也断不了。
- **全部配置项以数据形式发布**在 `/schema/options.json`：一份 JSON Schema 2020-12 文档，含每个配置项的类型、允许值、取值范围与默认值。像「`precision` 是不是整数、上限多少」这种问题，散文不是合适的载体。
- 有两件事让它不至于沦为摆设。它的属性表按源接口做了类型标注，所以存在却没被描述的配置项会让 `tsc` 失败，被描述却已经不存在的同样如此。默认值则是在生成这份文件时从 `resolveOptions()` 里读出来的，不是抄的——代码里的默认值一变，这里在同一个提交里跟着变。还有一条测试补上了类型系统看不见的那一环：配置参考里印着的默认值，和上面这个是不是同一个。它当场查出一处不一致——`unitToConvert` 解析后是列表，而两份参考表都写着 `'px'`。
- 中英文都装在同一份 Schema 里：`description` 是英文，`x-description-zh` 是中文。类型不是翻译。`x-also` 则标注那些只有 JavaScript 能写、JSON 表达不了但配置文件接受的形式——正则、判断函数。
- **编译器就跑在读者自己的浏览器里。** 插件只有一个运行时依赖，链路上没有任何 Node API，所以发布出去的那份源码被直接引进试验场页面，PostCSS 在客户端运行。背后没有服务，也没有任何需要跟着版本同步的东西。配置栏按 JavaScript 表达式求值而不是按 JSON 解析，因为值得一试的东西有一半是 JSON 写不出来的。六个示例，每个对应一个真的有人问的问题，其中一个专门演示会触发告警的配置。
- **每种语言各有一份 `llms.txt` 与 `llms-full.txt`**，遵循 llms.txt 约定；每一页的原始 Markdown 也在「页面路径 + `.md`」上直接提供——于是「把这一页交给模型」是一次抓取，而不是把渲染后的 HTML 再刮回文本。大纲上方的三个按钮用的就是它：复制为 Markdown、查看原始 Markdown、把这一页带进对话。
- 新增 `docs/agents.md` / `docs/agents.zh-CN.md`，把这些入口集中到一页，并写清提示词里该有什么：一个默认「全局只有一个设计稿宽度」的 Agent，写出来的配置能编译，但是错的。
- 由 `.github/workflows/docs.yml` 在推送到 `main` 时部署。`tsconfig.json` 现在也覆盖 `docs/.vitepress`，站点自己的源码和其余代码一起做类型检查。

### 文档

- 新增 `scripts/check-docs.mjs`，接进 `npm run check`，因而也进了 CI。它校验每个本地链接可达、每个 `#锚点` 对得上真实标题，以及**每一页都有另一种语言的对应页、并且在顶部链接过去**。真正划算的是最后一条：两种语言是分别写的而不是翻译的——这既是它们读起来顺的原因，也是其中一份可以悄悄不存在的原因。它当场查出两处：`CODE_OF_CONDUCT` 只有中文内容却挂着英文文件名，示例 README 把两种语言堆在同一个文件里。
- 锚点检查按 `/\r?\n/` 切行。Windows 上这里每个文件都是 CRLF，行尾的 `\r` 会让非多行模式下的 `$` 匹配不上，而 `.` 也不匹配它——于是直接按 `'\n'` 切会一条标题都找不到，把仓库里所有锚点全报成坏的。这不是假想，这是这个检查第一版的真实表现。
- `examples/app-pc` 新增 `adaptive.config.mjs`，单独导出配置本身；`postcss.config.mjs` 改为 import 它。两个 runner 要的形状不同——PostCSS 要 `{ plugins: [...] }`，CLI 要配置本身——而把画布写两遍正是两边最后描述出两张不同设计稿的方式。示例 README 现在给的是真能跑起来的命令，含 `--targets`。

### 性能

- `routingSelector` 对不含 `:` 的选择器立即返回，而绝大多数选择器都不含；同时这道还原挪进了 `forSelector` 内部——在「压根不做选择器路由」的那道判断之后。配了 `libraries: false` 的项目现在为这个特性一分钱都不用付。utility-framework 语料上的编译器耗时：4.38ms → 3.58ms。

### 一致性套件

- 原子化用例补入 `space-x-4` 与 `divide-y-2`。此前整个套件里**一个功能性伪类都没有**，而这两个是日常工具类。同一个工具类，三种毫不相干的真实形状：Tailwind 4 把整体裹进 `:where(...)`，UnoCSS wind3 写成扁平的 `> :not([hidden]) ~ :not([hidden])`，UnoCSS wind4 直接产出带 `&` 的*原生嵌套*。现在同样的 2px 在三者中都得到一模一样的 `clamp(1.70667px, 0.53333vw, 2.56px)`，`border` 的细线三者都保住，wind4 的原生嵌套原样写回。
- 新增 `test/idempotence.test.ts`：**把编译产物再编译一遍，什么都不该变**，九种配置 × 八份样式表。一致性套件本来就对每个用例断言了这一点，但只在那个用例自己声明的选项下断言——没被覆盖的是那些会改变产物**形状**的开关之间的组合，而第二趟要扛住的正是形状。第二趟不是假想：一个发布预编译 CSS 的包，会再经过使用方应用的构建流水线；monorepo 里先编译共享组件库、再编译引用它的应用，也是同一回事。
- 真正需要钉死的是原子化模式配上静态字号。原子化会把 `rem` 加进 `unitToConvert`，而文字通常写成 `rem + vw`——那个 `vw` 就是告诉第二趟「这个值已经编译过了」的记号。`fontFluidity: 0` 之下没有 `vw`：`32px` 变成光秃秃的 `2rem`，下一趟会把它当成设计稿长度再换算一次。它扛住了，但没有任何东西在守着它——`rootValue` 两端用的是同一个，写的时候 ÷16、读的时候 ×16，互为精确的逆运算，这个值是它自己的不动点。这是算术的性质，不是谁写下来的规则；这道除法的任意一端一挪，失败都是静默的：不报错、不告警，只是每存一次盘文字就小一点。

### 类型

- 所有取数组的选项现在都接受 `readonly` 数组：`routes`、`libraries`、`textProperties`、`propList`、`selectorExclude`、`valueExclude`、`include`、`exclude`、`root.injectTo`，以及路由与库定义里的 `file` / `selector` / `property` / `prefix` / `tokenPrefix`。`unitToConvert` 本来就接受，这让 API 自相矛盾：用 `as const` 写的配置——在 TypeScript 里这是最自然的写法——除了那一个字段之外每个都报类型错误。

## 0.5.0 — 2026-08-10

### 文档

- **全部描述文件改为中英双语**：`X.md` 为英文、`X.zh-CN.md` 为中文，每页顶部互链。覆盖 README、docs 全部 11 篇、一致性套件说明、贡献指南、安全策略与本文件。英文不是把中文机翻一遍——同一件事在两种语言里该由不同的句子承担，所以两版是分别写的。
- 英文版配套的图放在 `docs/assets/en/`，是按英文重画的：中文标签短，直接替换会撑出卡片，`tracks the viewport` 还会被虚线从下面穿过。
- 画布模型图移除第三方库名。模型与是哪家库无关，「移动端组件库 / 375 设计稿」「桌面端组件库 / 无设计稿 · 真实像素」说的是同一件事，而整张图从头到尾只在讲本编译器自己。

### 浏览器特性支持审计与降级

- 新增 `auditCompatibility(css, targets)`：给一串「浏览器 + 你要支持的最低版本」，逐条列出产物里超出目标的语法、不支持时丢掉的东西、以及关掉它的开关。审计读的是**编译产物文本**而不是配置——这是让审计和输出永远不会走偏的唯一做法，经预设、经组件库路由、经手写 CSS 进来的特性一样能看见。同时导出 `detectFeatures`、`COMPAT_FEATURES`、`FEATURE_SUPPORT`、`compatFeature`，类型齐全。
- 命令行新增 `--targets "safari 14, ios_saf 13"`，在对照表之后输出 `needs` 段。四行的顺序是有意的：先说丢什么，再说换成什么——「iOS Safari 13 太老了」单独拿出来没法行动，而 CSS 支持缺口真正要紧的一直是**跟着一起消失的有多少**。CSS 不报错，它丢弃：值读不懂丢一条声明，选择器读不懂丢一整条规则，`@` 规则读不懂丢一整块，全程无声。特性表因此按「丢得多」排序，不按「谁更新」。
- 覆盖 11 项：`@layer`、`:where()`、`@container` / 容器单位、`clamp()` / `min()` / `max()`、`vi`、逻辑属性、`var()`、`env(safe-area-inset-*)`、`vw`、原生嵌套。原生嵌套本编译器不产出（读进来的嵌套原样写回），列入是因为它是会被问到的问题，而靠模式识别它会把普通 CSS 误读成嵌套——报错比不报更糟。
- 版本数据由 `scripts/capture-compat.mjs` 从 caniuse-lite 烘焙进 `src/core/compat-data.ts`，caniuse-lite 只是 devDependency，插件不增加任何运行时依赖，离线可审计。「某特性从哪个版本开始能用」是不会再变的历史；**使用率则故意不看**——0.4% 的用户算不算数是关于你的项目的决定，`browserslist` 已经是回答那个问题的地方。取的是「从此再没断过支持」的版本而非第一个出现 `y` 的版本（个别特性发布后被撤回过）。
- `--targets` 收显式的名字与版本，不收 browserslist 查询：查询要拉进 browserslist 包，回答的是关于用户的问题而不是关于这份样式表的问题，而且**同一条查询会随数据库更新而改变含义**——代码一个字没动，下个月构建就红了。不认识的目标名报错并以 `1` 退出，不静默跳过：被悄悄丢掉的目标比没有审计更糟，因为它读起来像通过了。
- caniuse 没有 `:where()` 和 `vi` 的独立条目，改用 `:is()` 与 `svh`/`lvh`/`dvh` 条目，并在数据里标出这是代理而非实测。两组都出自同一节规范、同批发布（`:where()` / `:is()`：Chrome 88、Firefox 78、Safari 14）。
- 新增 `root.logical`（预设字段 `rootLogical`）：设为 `false` 时基础样式改写 `width` / `margin-left` / `margin-right` / `max-width`，而不是 `inline-size` / `margin-inline` / `max-inline-size`。**这是审计过程中发现的真实缺口**——逻辑属性是编译器产出的语法里唯一一个失败之后页面看起来还正常的：丢掉 `margin-inline: auto`，列宽完全正确、贴在屏幕左边；丢掉 `max-inline-size`，列铺满整屏。两种都不像故障，因而比一眼可见的崩塌更容易活着上线，而此前没有任何开关能避开它。横排页面上两种拼法等价，关掉不损失任何东西。预设同时新增 `rootLayer`，透传到 `layer`——同样是支持开关，不该为了够到它而放弃预设。
- 文档新增[浏览器特性支持与降级](docs/compatibility.zh-CN.md)：特性 × 浏览器最低版本表、逐项的「谁产出它 / 丢什么 / 怎么关、代价是什么」，以及这份审计**不能**代替真机测试的边界（它只能证明目标浏览器解析得了这份 CSS 的语法；渲染差异、软键盘、地址栏是别的问题）。反过来，版本门槛这件事真机也测不了——手上那台 iOS 17 读得懂 `@layer`，对「15.4 以下读不懂」没有任何说明力。

### 断点检查

- 修正**默认预设上稳定误报两条 `shrinks`**：`root.fixedContainingBlock` 会把固定元素的 `left: 0` 改写成 `left: var(--adaptive-root-gutter)`，而这个留白**本来就该在断点处跳变**——列宽从 480 换到 1920，留白从 143.96px 正确地掉到 0。读成设计长度是倒退，读成它本身是修正在起作用。比较前把这个变量代成 `0px` 而不是整条跳过，`left: calc(clamp(…) + var(--adaptive-root-gutter))` 里的 `clamp()` 照样接受检查。在默认配置上就狂叫的检查，是会被学会跳过的检查。

### 原子化 CSS（Tailwind / UnoCSS）

- 修正**工具类一个都换算不到**：这是静默的——手写 CSS 被缩放、工具类原样保留，两套尺寸从此对不齐，不报错。两个大版本各卡在一处。旧版（Tailwind 3、UnoCSS `presetUno` / `presetWind3`）把长度写成 `rem`，而编译器只读 `px`；新版（Tailwind 4、UnoCSS `presetWind4`）把长度整个搬进主题 token，`.p-4` 编译成 `padding: calc(var(--spacing) * 4)`，工具类里根本没有长度可读，而自定义属性默认不换算。
- `unitToConvert` 现在接受数组，一趟读多种单位。这不是锦上添花：这两个框架同一张产物里两种单位都有——间距和字号是 `rem`，而边框宽度、`p-[13px]` 这类方括号任意值是 `px`，各自描述同一张设计稿。只读 `rem` 会漏掉所有边框，只读 `px` 会漏掉所有间距，两种单选都是错的。`rem` 按 `rootValue` 折算成像素，其余单位按面值读取。
- 修正 `unitToConvert: 'rem'` 一直把 `1.5rem` 当成 1.5 像素：换算前不折算，于是低于 `minPixelValue` 与 `hairline` 阈值而被整批跳过。这两道阈值现在一律按**像素**判定——`0.0625rem` 与 `1px` 是同一根细线，怎么写的不影响它有多细。
- 新增 `rootValue`（默认 16），读写两头共用一把尺：既决定 `rem` 输入折合多少像素，也决定文字静态项写成多少 `rem`。`html { font-size: 62.5% }` 的项目配 `rootValue: 10` 即可。
- 新增 `withAtomicCss(base, options?)`：**包装**而非替换现有配置，把 `rem` 补进 `unitToConvert`，并认领主题 token 前缀 `--spacing`、`--text-`、`--leading-`、`--radius-`、`--container-`。认领源头即可，工具类不用动——`calc(clamp(a, b, c) * 4)` 恒等于 `clamp(4a, 4b, 4c)`（正系数下乘法可穿过 clamp），产物与直接换算 `16px` 逐位相同。故意不认领三类：`--breakpoint-*` 是画布**切换**的宽度，缩放它等于移动断点本身；`--tracking-*` 用 `em` 发布，依附的字号已被做成流体，再缩一次是叠加；`--shadow-*` 的像素是按屏幕尺度画的层次感。自定义长度族用 `tokenPrefixes` 补。
- 默认 `textProperties` 加入 `--text-*` 与 `--leading-*`：字号被发布成 token 时，名字不长得像字体属性，漏掉就意味着这个字号**失去浏览器缩放**。这一条只决定一个已经要换算的长度怎么写，不决定它换不换算，因此对未被认领的 token 不起作用。
- 新增一致性用例 `atomic/{tailwind-v4,unocss-wind3,unocss-wind4}`，输入是三者的**真实产物原文**（Tailwind 4.3.3、UnoCSS 66.7.5 两个预设），用 `scripts/capture-atomic.mjs` 重抓。两个大版本的产物形状差别大到手写必然写成想象中的样子。这两个框架不设为 devDependency：抓下来的 CSS 就是全部输入，把 `npm test` 绑在别人的发版节奏上换不来额外信息。
- 路由的 `property` 通道收到正则时立即报 `TypeError` 并说明正确写法。另两个通道都收正则，这里只收字符串前缀，此前的表现是运行中途 `prefix.toLowerCase is not a function`。

**破坏性（类型）**：`ResolvedAdaptiveMatrixOptions.unitToConvert` 由 `string` 变为 `string[]`；`AdaptiveMatrixOptions.unitToConvert` 放宽为 `string | readonly string[]`，传字符串照旧。`findContinuityIssues` 新增可选第二参数 `rootFontSize`。

### 编译器

- 修正跨画布的文字尺寸：**项目画布与组件库画布不一致时，该库的文字全错**。普通长度两边一直是一致的（都归结为 `值 ÷ 画布`），文字不是——文字保留一段固定的 `rem` 以便浏览器缩放仍然有效，而这段固定长度此前锚在各自的画布上。Vant 画在 375、页面画在 750 时，两者描述的是同一份设计的两套单位，Vant 的 16px 与页面的 32px 本是同一个尺寸，却在 390px 视口下分别渲染成 16.22px 与 26.62px——**小了约 40%**，而 375 与 1440 上都看不出来。750 稿的项目配 Vant 是国内移动端最常见的组合之一；antd-mobile 的 1x/2x 双份产物同理。
- 新增 profile 字段 `textAnchorWidth`：文字静态部分锚定的宽度，默认等于 `designWidth`。组件库画布一律继承所属 profile 的锚点，因此无需配置。等价形式是「先把长度换算成锚点画布的单位，再照常套公式」：流体项恰好不变（`P × F / D` 与画布同比例约掉），只有静态项被归一化。非文字长度 `fontFluidity = 1`、静态项恒为 0，产物逐字节不变，`strategy: 'viewport'` 同样不受影响。
- 新增性质测试「同一份设计换一张画布尺寸不变」：随机画布与随机缩放比下，`V px on D` 与 `V×k px on D×k` 在每个视口上必须一致。一致性套件只能覆盖有人想到要写下来的画布组合，而这个 bug 恰好只在两张画布同时出现时暴露。

### 编译器与校验

- `@adaptive <画布>` 落在一个没有声明 `query` 的 profile 上时会告警。按文件夹分双端的项目（`src/mobile/**` 与 `src/pc/**` 各一套页面代码）通常两个 profile 都不带 `query`——切换本来就不由 CSS 负责。此时在共用组件里写 `@adaptive pc { ... }` 读起来是「这些规则给 PC 用」，编译出来却是无条件规则，而且更靠后，**在任何视口都会赢**，没有任何地方会说话。`query: false` 不告警：那是作者明确表示切换发生在 CSS 之外。指向同一张画布的 `@adaptive` 也不告警：没有切换，拆开不丢东西。
- 文档新增「两套页面代码，按文件夹分」一节，写清文件路由只决定按哪张稿换算、不会附带媒体查询，以及共用组件、组件库、路由具体度这几处的取舍。

### 构建工具集成

- 新增真实 Vite 构建测试：脚手架里有一个由 Vite 自行发现的 `postcss.config.mjs`、一份从 `node_modules` 引入的依赖 CSS、以及一个按 `@vitejs/plugin-vue` 同款方式提供的 `<style>` 块。此前集成文档里的每一条说法都没有任何东西验证过——而这些说法一旦不成立，构建仍然成功，只是样式表是错的。现在验证：配置被找到并生效、依赖按 `node_modules` 路径落到组件库画布且与页面等价尺寸逐字节相同、带 query 串的 SFC id 能被包含式 `file` 路由命中、二次构建产物完全一致。
- 并且把文档里「锚定结尾的正则匹配不到 SFC」这条坑也写成了测试：用 `/\.mobile\.css$/` 构建一遍，断言该 `<style>` 块确实静默留在默认画布上，而其余产物一字不差。这类说法只有被反向验证过才算数。

### 可选运行时

- 修正 `observeAdaptiveViewport` 的帧泄漏：`update()` 是公开方法，却会把调度器的帧句柄清零。「先手动 `update()`、再 `destroy()`」这一串下来，已排队的那一帧既没被记录也没被取消，会在下一拍落到已销毁的观察者上。现在只有调度器自己清句柄，`destroy()` 之后也把句柄归零，重复 `destroy()` 不会去取消宿主已经回收再分配的句柄。
- 补齐运行时测试：没有 `visualViewport` 的旧 WebView 回退、iOS 橡皮筋回弹导致的负键盘高度、逐字段的非数值读数、事件合帧、销毁时机、以及不传参数时读全局对象这条所有浏览器使用者实际走的路径。分支覆盖 72% → 100%。

### 组件库

- 新增 `scripts/verify-libraries.ts`：下载每个内置库的**已发布产物**，用真实的 `node_modules` 路径编译，核对前缀是否真的存在、路由落到哪张画布、是否幂等、有无告警、接缝检查是否误报。此前注册表里除 Vant 外都是照文档写的，没有实证；下面三条都是这个脚本查出来的。
- 修正 antd-mobile：该库把同一份样式表发布了两次，`bundle/` 画在 375 上、`2x/bundle/` 画在 750 上，类名与 token 名完全相同（实测 5.42.3，后者每个长度恰好是前者的两倍）。此前 `.adm-` 前缀路由会把 2x 产物按 375 换算，页面上每一个尺寸都是应有的两倍，且没有任何报错或告警。新增 `antd-mobile-2x` 条目，自动模式下无需配置。
- 新增 `scoped`：限定 `prefix` 与 `tokenPrefix` 只在 `file` 同时命中时生效。一个前缀对应两张画布时，只有路径能区分。限定路径的路由先于不限定的路由测试，因为它更具体；路径不存在时（打包器内联依赖）退回不限定的那一条。`scoped` 却不给 `file` 直接报错。
- 移除 Varlet 的 `tokenPrefix: '--var-'`：该库的自定义属性根本不带前缀，叫 `--field-padding`、`--icon-size-md`，声明在光秃秃的 `:root` 上。这条规则此前匹配不到任何东西。认领这些名字等于认领 `--card-width` 本身，注册表只收无歧义的前缀，所以不补，改为在文档里给出显式路由的写法。
- 文档补上实测的前缀命中率，并写明**设计宽度这一列核对不了**（CSS 里看不出稿子画在多宽），以及 `naive-ui` 与 `mui` 的样式在运行时生成、磁盘上没有样式表。

### 断点接缝检查

- 只在**至少一侧是编译器产出的公式**时才报。此前会把库自己有意写下的断点差异当成接缝：Quasar 的 `.q-tooltip` 手机上 `padding: 8px 16px`、600px 往上 `6px 10px`，是点击区域的取舍，两个数字都是人手写的、也比对过。「倒退只可能来自跨画布」这个完备性论证只覆盖本编译器产出的公式，对原样保留的样式表不成立。一侧换算另一侧没有，仍然报。
- 一致性套件的用例改用编译器形状的值。此前十余条负向用例写的是裸 `40px`，加上这道门之后会因为「没被编译」而通过，而不是因为它们各自要验的那件事。

## 0.4.0 — 2026-08-09

### 断点接缝检查

- 新增断点接缝检查：命令行会指出「视口变宽、尺寸反而变小」的声明，并给出两侧的实际像素值。两张设计稿各自都对，接缝处未必对，而这类问题只在某一个宽度上出现——日常调试的 375 和 1440 都正常。检查也从包里导出为 `findContinuityIssues(root)`，可用于让构建直接失败。
- 检查按**绝对值**比较，且断点两侧变号一律不报。编译器输出的公式，其绝对值对视口宽度单调不减且全程不变号，所以绝对值倒退只可能来自跨断点换画布。按数值比较对每一条负长度都是反的：负外边距、外溢这类值本来就靠远离零来变大。
- 检查会代入同一份样式表里的主题 token。组件库的尺寸几乎不写字面量——Vant 4.10.0 的 3198 条普通声明里有 1173 条完全经 `var()` 读取，在第一个 `var(` 就放弃等于避开了本插件要适配的那一层。代入只在值由视口宽度单独决定时进行：token 只声明在 `:root` / `:host` / `html` 上且别处没有第二份，每一处声明要么无条件、要么位于纯像素宽度的 `@media` 里。token 自身在断点处被改写也算一次接缝，即使消费它的规则只写了一次。实测（Vant 4.10.0 完整样式表）可求值的值分量 622 → 1309 条（17.6% → 36.9%），收录 779 个 token。
- 实测误报：69 份一致性套件产物、上述 Vant 样式表、本仓库示例工程，`shrinks` 报告数均为 0。
- 新增 `evaluateLength`：把编译器产出的 `clamp()` / `min()` / `max()` / `calc()` 在指定视口宽度上求值。`env()`、`%`、容器单位一律返回 `null` 而不是猜一个数。

### 打包与类型

- 修正 CommonJS 入口：`require('postcss-adaptive-matrix')` 此前返回的是命名空间对象，直接调用会抛 `plugin is not a function`，必须写 `.default`。而 `plugins: [require('postcss-adaptive-matrix')({ ... })]` 正是所有 `postcss.config.js` 的通用写法——本仓库 Webpack 文档里的示例自己就是错的。现在 `module.exports` 就是插件本身，`.default` 与各具名导出仍作为属性保留。
- 修正 CommonJS 类型入口。两处：`exports` 里的 `types` 此前只有顶层一处，CJS 使用者拿到的是 ESM 版 `.d.ts`；而 `.d.cts` 本身只声明具名导出，于是 `import x = require('postcss-adaptive-matrix')` 报 “has no call signatures”——代码能跑、编辑器报红。现在 `require` 指向 `.d.cts`，且 `.d.cts` 以 `export =` 描述真实形状，类型经合并的命名空间保留，`import type { AdaptiveMatrixOptions }` 照常可用。ESM 入口与类型不受影响。
- 新增针对构建产物本身的测试：其余测试都从 `src` 导入，而「`require` 拿到什么」「类型解析到哪个文件」由构建与 `package.json` 决定，从源码导入永远测不到。`npm run check` 因此改为先构建再测试。

### 编译器与校验

- 跨画布的选择器列表（如 `.van-cell, .page-hero { ... }`）现在会告警并指出哪个选择器落空了。一条声明只能有一个结果，此前是静默按第一个命中的画布编译整条规则。
- `@adaptive pc;`（没有块）此前被改写成 `@media (min-width: 768px);`——不是合法 CSS，而作者想放到那张画布上的规则仍留在原画布。现在告警并保持原样。
- 命令行的 `-c` 不再在配置模块漏写 `default`、或预设忘了调用时静默改用内置默认值。这两种写法此前会跑完并打印一份看着正确的对照表，没有任何地方说过配置没被读到。
- 新增配置校验：`unit` 与 `strategy` 的取值、空的 `unitToConvert`、与 CSS 已定义的 at-rule 重名的 `atRuleName`、空的 `root.selector`。这些字段写错的后果都是静默的，其中 `unit` 写错会直接产出无效 CSS。
- 新增基于性质的随机测试：以 `evaluateLength` 为判据，在数百组生成的画布上验证设计宽度恒等、绝对值单调、区间外恒定、区间内线性与幂等。一致性套件只能覆盖有人想到要写下来的设计宽度。

## 0.3.0

- 新增 `adaptive-matrix` 命令行预览：逐条声明的前后对照，`--from` 可在上线前验证文件路由，`--css` 输出完整产物且警告走 stderr。
- 修正嵌套场景：`@media` / `@supports` / `@layer` / `@container` / `@scope` / `@starting-style` 内的声明现在会被换算，`@font-face` / `@page` / `@property` / `@counter-style` 内的长度保持原样。
- 修正幂等性：已经带视口单位的 `clamp()` / `min()` / `max()` 不再被二次换算。
- 修正根容器基础样式的幂等性：产物带 `/* postcss-adaptive-matrix foundation */` 标记，再编译一次既不会把 `max-inline-size: 480px` 这类固定上限当成设计稿尺寸缩放，也不会叠出第二份。
- 忽略注释（`adaptive-ignore` 系列）不再从产物中删除。被忽略的值没有任何自身痕迹，注释一旦消失，第二趟编译就会把作者明确排除的尺寸换算掉；注释会被压缩器去掉，不影响上线体积。
- 一致性套件对每一个样例增加幂等断言：产物再编译一遍必须原样返回。
- 修正重复声明：同一规则内重复书写的声明现在每一条都会换算。此前只换算第一条，而层叠中生效的是最后一条，等于整条换算失效。
- 支持带指数的数字：`1e2px` 就是 100px，此前被静默跳过；`min(1e2vw, 50px)` 也不再被误判为「没有视口单位」。
- 修正 at-rule 大小写：`@ADAPTIVE` / `@Adaptive` 与 `@adaptive` 等价，与 CSS 对 at-keyword 的大小写不敏感一致。此前不被识别，整块会被浏览器丢弃且没有任何提示。
- 新增 `root.injectTo`（预设为 `rootInjectTo`）：限定根容器基础样式注入到哪些文件。组件化项目里每个 `<style>` 块都是独立文件，默认会逐个注入一份。
- 只写排除项的 `propList`（如 `['!border*']`）现在直接报错——它匹配不到任何属性，等于整份样式表都不换算。
- 在 `profiles` 里使用保留前缀 `library:` 现在直接报错并指回 `libraries: [{ extends }]`——此前会被合成的组件库画布静默覆盖。
- 未知画布的告警不再列出内部合成的组件库画布，并说明浏览器会整块丢弃该 at-rule；`unknownProfile: 'error'` 下的报错不再建议开启已经开启的选项。
- 新增注册表不变量测试，覆盖前缀歧义、画布取值与自动模式的短前缀策略。
- 重写文档结构，新增快速上手、构建工具集成、组件库适配、可选运行时与命令行预览五篇，并补充 SVG 图示。

## 0.2.0

- 新增组件库画布、自动识别、路由覆盖和设计令牌适配。
- 新增 fixed 根包含块定位矫正与桌面端偏移处理。
- 将编译核心与 PostCSS 适配层解耦，公开解析后的多画布配置能力。
- 建立 50+ 组 conformance 固定样例、133 项测试和性能基准工具。
- 重写多画布模型、组件库接入、架构与迁移文档。

## 0.1.0

- 首次实现 App/PC 多设计画布编译模型。
- 支持有界流体尺寸、可缩放文字、媒体查询和容器查询 profile。
- 支持动态设计宽度、文件/属性/选择器/值过滤与忽略指令。
- 提供可选根布局、安全区变量和 VisualViewport 运行时。
- 发布 ESM、CommonJS 与 TypeScript 类型。