css2class 2.0.0 → 2.0.1

package/docs/guide/getting-started.md

@@ -1,83 +1,86 @@
-# 快速开始
-
-你将完成：安装 → 写最小配置 → 运行生成 → 在模板中使用类名。
-
-## 安装
-
-```bash
-npm install css2class --save-dev
-```
-
-:::tip 推荐
-如果你希望用一条命令直接跑起来，也可以使用 `npx class2css`（前提是已安装到项目里）。
-:::
-
-## 运行方式
-
-### 监听模式（开发）
-
-```bash
-# 启动工具（默认监听模式）
-npm run start
-
-# 开发模式（文件监听）
-npm run dev
-```
-
-### 单次构建（CI/构建）
-
-```bash
-# 构建模式（单次扫描后退出，不监听）
-npm run build
-```
-
-### 帮助与版本
-
-```bash
-npm run help
-npm run version
-```
-
-## 创建最小配置
-
-在项目根目录创建 `class2css.config.js`：
-
-```javascript
-module.exports = {
-  system: { baseUnit: 'rpx', unitConversion: 2, cssFormat: 'compressed' },
-  output: {
-    path: '../dist',
-    fileName: 'styles.wxss',
-  },
-  cssName: {
-    m: { classArr: ['margin'], unit: 'rpx' },
-    w: { classArr: ['width'], unit: 'rpx' },
-    h: { classArr: ['height'], unit: 'rpx' },
-  },
-};
-```
-
-:::tip 下一步
-把配置写“可维护”，并开启单位策略/排序/诊断等能力：建议直接阅读 [配置指南](./config.md) 并从示例配置改起。
-:::
-
-## 使用类名
-
-```html
-<view class="m-10 w-100 h-200"></view>
-```
-
-你会得到类似（取决于单位配置）：
-
-```css
-.m-10 { margin: 20rpx; }
-.w-100 { width: 200rpx; }
-.h-200 { height: 400rpx; }
-```
-
-## 下一步
-
-- 先把“语法与规则”弄清楚：阅读 [类名语法与生成规则](./concepts.md)
-- 需要知道有哪些命令：阅读 [CLI](./cli.md)
-- 想性能更稳：了解 [增量模式（只增不删）](./incremental.md)
-
+# 快速开始
+
+你将完成：安装 → 写最小配置 → 运行生成 → 在模板中使用类名。
+
+## 安装
+
+```bash
+npm install css2class --save-dev
+```
+
+:::tip 推荐
+如果你希望用一条命令直接跑起来，也可以使用 `npx class2css`（前提是已安装到项目里）。
+:::
+
+## 运行方式
+
+### 监听模式（开发）
+
+```bash
+# 启动工具（默认监听模式；默认使用根目录配置：./class2css.config.js）
+npm run start
+
+# 开发模式（文件监听；默认使用根目录配置：./class2css.config.js）
+npm run dev
+
+# 或者显式运行内置示例（推荐）
+npm run example:weapp
+npm run example:web
+```
+
+### 单次构建（CI/构建）
+
+```bash
+# 构建模式（单次扫描后退出，不监听）
+npm run build
+```
+
+### 帮助与版本
+
+```bash
+npm run help
+npm run version
+```
+
+## 复制示例配置（推荐）
+
+本项目的配置项较多（并且当前版本运行时依赖 `multiFile`、`atomicRules` 等字段），**不建议从零手写**。
+
+直接从仓库内置示例复制即可：
+
+- **小程序（wxss / rpx）**：复制 `examples/weapp/` 下的 `class2css.config.js` + `styles.config.js`
+- **Web（css / px）**：复制 `examples/web/` 下的 `class2css.config.js` + `styles.config.js`
+
+复制后你有两种启动方式：
+
+- **方式 A（推荐）**：用 `-c` 指定示例配置（不需要改默认文件名）
+  - `class2css -c ./examples/weapp/class2css.config.js`
+  - `class2css -c ./examples/web/class2css.config.js`
+- **方式 B**：把示例配置放到项目根目录并改名为默认配置文件
+  - `class2css.config.js`
+  - `styles.config.js`
+
+:::tip 下一步
+示例配置里把路径/输出都写成相对路径了，你只需要改 `multiFile.entry.path`（扫描/监听入口）和 `multiFile.output`（输出位置/文件名）即可跑通。
+:::
+
+## 使用类名
+
+```html
+<view class="m-10 w-100 h-200"></view>
+```
+
+你会得到类似（取决于单位配置）：
+
+```css
+.m-10 { margin: 20rpx; }
+.w-100 { width: 200rpx; }
+.h-200 { height: 400rpx; }
+```
+
+## 下一步
+
+- 先把“语法与规则”弄清楚：阅读 [类名语法与生成规则](./concepts.md)
+- 需要知道有哪些命令：阅读 [CLI](./cli.md)
+- 想性能更稳：了解 [增量模式（只增不删）](./incremental.md)
+

package/docs/guide/incremental.md

@@ -1,162 +1,164 @@
-# 增量模式（只增不删）与 appendDelta
-
-增量模式是 Class2CSS 的高级功能，主要用于**统一文件模式（`cssOutType: 'uniFile'`）**，解决"历史输出文件累积了旧 class，不希望工具主动删除"的场景。
-
-:::tip 什么时候值得用
-当你的项目很大、写入频繁，或者输出文件会被外部工具/人工修改时，增量模式能显著降低“全量重写”的 I/O 成本，同时让输出更可控。
-:::
-
-## 适用场景
-
-- 输出文件可能被其他工具或手动编辑修改
-- 希望保留历史生成的 class，即使当前项目暂时未使用
-- 需要更快的增量更新性能（appendDelta 模式）
-
-## 配置选项
-
-### incrementalOnlyAdd
-
-启用"只增不删"模式。
-
-- **类型**：`boolean`
-- **默认值**：`false`
-- **说明**：当设置为 `true` 时，运行期新增的 class 会被保护，不会因为后续文件变化而删除。
-
-### incrementalBaseline
-
-基线来源策略。
-
-- **类型**：`string`
-- **默认值**：`'fromOutputFile'`
-- **可选值**：
-  - `'fromOutputFile'`：从输出文件中解析已存在的 class 作为基线
-
-### rebuildOnStart
-
-启动时是否重建输出文件。
-
-- **类型**：`boolean`
-- **默认值**：`true`
-- **说明**：开启后会全量扫描并覆盖写出一次，输出文件会被"清理到只包含当前项目使用的 class"，然后进入运行期只增不删。推荐开启，保证每次启动输出文件都是干净且排序好的。
-
-### unusedReportLimit
-
-未使用 class 报告的最大显示数量。
-
-- **类型**：`number`
-- **默认值**：`200`
-- **说明**：启动重建时，如果发现上一版输出文件中存在但当前项目未使用的 class，会在控制台打印。此配置限制打印的示例数量，避免输出过长。
-
-### uniFileWriteMode
-
-统一文件写入策略。
-
-- **类型**：`string`
-- **默认值**：`'rewrite'`
-- **可选值**：
-  - `'rewrite'`：统一文件写入保持兼容（防抖全量覆盖写）
-  - `'appendDelta'`：启动时写入 BASE 段 + `DELTA_START` 标记；运行期仅把新增 class 的 CSS 追加到文件末尾（更快、减少重写）
-
-**注意**：当 `uniFileWriteMode='appendDelta'` 时，`rebuildOnStart` 必须为 `true`（否则历史垃圾无法自动清理）。
-
-## 配置示例
-
-```javascript
-module.exports = {
-  multiFile: {
-    entry: {
-      // 扫描/监听入口：
-      // - string：单目录/单文件
-      // - string[]：多目录/多文件（目录与文件可混用）
-      path: "./src",
-      fileType: ["wxml", "html"],
-    },
-    output: {
-      cssOutType: "uniFile",
-      path: "./dist",
-      fileName: "styles.wxss",
-
-      // 增量"只增不删"
-      incrementalOnlyAdd: true,
-      incrementalBaseline: "fromOutputFile",
-      rebuildOnStart: true,
-      unusedReportLimit: 200,
-
-      // 统一文件写入策略
-      uniFileWriteMode: "appendDelta", // or 'rewrite'
-    },
-  },
-};
-```
-
-## appendDelta 模式
-
-`appendDelta` 模式提供了更快的增量更新性能，通过追加写入而非全量重写来减少文件 I/O。
-
-### 输出文件结构
-
-`appendDelta` 模式下输出文件会包含标记：
-
-```css
-/* CLASS2CSS:BASE */
-.w-100 { width: 200rpx; }
-.m-10 { margin: 20rpx; }
-/* ... 其他基础样式 ... */
-
-/* CLASS2CSS:DELTA_START */
-.new-class-1 { /* 新增的样式 */ }
-.new-class-2 { /* 新增的样式 */ }
-```
-
-- `/* CLASS2CSS:BASE */`：启动重建写入的基础段（压缩/排序后的全量结果）
-- `/* CLASS2CSS:DELTA_START */`：增量追加段起点（运行期新增 class 会追加到该标记之后）
-
-### 工作流程
-
-1. **启动时**：
-   - 读取旧输出文件，提取已存在的 class 作为基线
-   - 执行全量扫描，清理上一次运行累积的多余规则
-   - 生成 BASE CSS（全量生成，压缩+排序）
-   - 写入 BASE + DELTA_START 标记（覆盖写，清空旧 DELTA）
-   - 报告未使用的 class（如果存在）
-
-2. **运行期**：
-   - 文件变更时，只追加新增 class 的 CSS 到 DELTA_START 之后
-   - 新增的 class 自动加入 baseline，保证只增不删
-
-### 优势
-
-- **性能提升**：只追加新增内容，避免全量重写
-- **减少 I/O**：文件写入次数和大小显著减少
-- **保持基线**：BASE 段保持压缩和排序，DELTA 段追加新内容
-
-### 注意事项
-
-- `rebuildOnStart` 必须为 `true`，否则历史垃圾无法自动清理
-- DELTA 段会随时间增长，建议定期重建（重启工具即可）
-- 如果需要完全清理，可以手动删除输出文件后重启
-
-## 标准模式 vs 增量模式
-
-### 标准模式（incrementalOnlyAdd: false）
-
-- 文件变更时，会删除不再使用的 class
-- 输出文件始终保持"干净"，只包含当前使用的 class
-- 适合：希望输出文件始终保持最小化的场景
-
-### 增量模式（incrementalOnlyAdd: true）
-
-- 文件变更时，只新增 class，不删除已存在的 class
-- 输出文件可能随时间增长
-- 适合：需要保留历史 class 或输出文件可能被外部修改的场景
-
-## 最佳实践
-
-1. **推荐开启 rebuildOnStart**：保证每次启动输出文件都是干净且排序好的
-2. **定期检查未使用的 class**：关注启动时的 unused 报告
-3. **使用 appendDelta 提升性能**：在大型项目中，appendDelta 模式可以显著提升增量更新速度
-4. **合理设置 unusedReportLimit**：避免控制台输出过长
-
-## 下一步
-
-- 了解统一文件输出与基础配置：阅读 [配置指南](./config.md)
+# 增量模式（只增不删）与 appendDelta
+
+增量模式是 Class2CSS 的高级功能，主要用于**统一文件模式（`cssOutType: 'uniFile'`）**，解决"历史输出文件累积了旧 class，不希望工具主动删除"的场景。
+
+:::tip 什么时候值得用
+当你的项目很大、写入频繁，或者输出文件会被外部工具/人工修改时，增量模式能显著降低“全量重写”的 I/O 成本，同时让输出更可控。
+:::
+
+## 适用场景
+
+- 输出文件可能被其他工具或手动编辑修改
+- 希望保留历史生成的 class，即使当前项目暂时未使用
+- 需要更快的增量更新性能（appendDelta 模式）
+
+## 配置选项
+
+### incrementalOnlyAdd
+
+启用"只增不删"模式。
+
+- **类型**：`boolean`
+- **默认值**：`false`
+- **说明**：当设置为 `true` 时，运行期新增的 class 会被保护，不会因为后续文件变化而删除。
+
+### incrementalBaseline
+
+基线来源策略。
+
+- **类型**：`string`
+- **默认值**：`'fromOutputFile'`
+- **可选值**：
+  - `'fromOutputFile'`：从输出文件中解析已存在的 class 作为基线
+
+### rebuildOnStart
+
+启动时是否重建输出文件。
+
+- **类型**：`boolean`
+- **默认值**：`true`
+- **说明**：开启后会全量扫描并覆盖写出一次，输出文件会被"清理到只包含当前项目使用的 class"，然后进入运行期只增不删。推荐开启，保证每次启动输出文件都是干净且排序好的。
+
+### unusedReportLimit
+
+未使用 class 报告的最大显示数量。
+
+- **类型**：`number`
+- **默认值**：`200`
+- **说明**：启动重建时，如果发现上一版输出文件中存在但当前项目未使用的 class，会在控制台打印。此配置限制打印的示例数量，避免输出过长。
+
+### uniFileWriteMode
+
+统一文件写入策略。
+
+- **类型**：`string`
+- **默认值**：`'rewrite'`
+- **可选值**：
+  - `'rewrite'`：统一文件写入保持兼容（防抖全量覆盖写）
+  - `'appendDelta'`：启动时写入 BASE 段 + `DELTA_START` 标记；运行期仅把新增 class 的 CSS 追加到文件末尾（更快、减少重写）
+
+**注意**：当 `uniFileWriteMode='appendDelta'` 时，`rebuildOnStart` 必须为 `true`（否则历史垃圾无法自动清理）。
+
+## 配置示例
+
+```javascript
+module.exports = {
+  multiFile: {
+    entry: {
+      // 扫描/监听入口：
+      // - string：单目录/单文件
+      // - string[]：多目录/多文件（目录与文件可混用）
+      path: "./src",
+      fileType: ["wxml", "html"],
+    },
+    output: {
+      cssOutType: "uniFile",
+      path: "./dist",
+      fileName: "styles.wxss",
+
+      // 增量"只增不删"
+      incrementalOnlyAdd: true,
+      incrementalBaseline: "fromOutputFile",
+      rebuildOnStart: true,
+      unusedReportLimit: 200,
+
+      // 统一文件写入策略
+      uniFileWriteMode: "appendDelta", // or 'rewrite'
+    },
+  },
+};
+```
+
+## appendDelta 模式
+
+`appendDelta` 模式提供了更快的增量更新性能，通过追加写入而非全量重写来减少文件 I/O。
+
+### 输出文件结构
+
+为保证 **响应式（@media）永远不会因为“追加 base 规则”而被覆盖**，`appendDelta` 模式下输出文件会按“分区”组织（base 在前、media 在后），并带有稳定标记：
+
+```css
+/* CLASS2CSS:BASE_START */
+/* base：普通规则（不含 @media） */
+/* CLASS2CSS:BASE_END */
+
+/* CLASS2CSS:MEDIA_START */
+/* media：所有 @media(...) 块（始终在文件后半段） */
+/* CLASS2CSS:MEDIA_END */
+
+/* CLASS2CSS:DELTA_START */
+```
+
+- `/* CLASS2CSS:BASE_START */` ~ `/* CLASS2CSS:BASE_END */`：普通规则分区（不含 `@media`）
+- `/* CLASS2CSS:MEDIA_START */` ~ `/* CLASS2CSS:MEDIA_END */`：媒体查询分区（只放 `@media`）
+- `/* CLASS2CSS:DELTA_START */`：增量写入起点标记（用于识别该文件是 appendDelta 输出）
+
+### 工作流程
+
+1. **启动时**：
+   - 读取旧输出文件，提取已存在的 class 作为基线
+   - 执行全量扫描，清理上一次运行累积的多余规则
+   - 生成 BASE CSS（全量生成，压缩+排序）
+   - **分区写入**：把 BASE CSS 拆分成 `base` 与 `@media` 两段，分别写入 `BASE_*` 与 `MEDIA_*` 分区
+   - 报告未使用的 class（如果存在）
+
+2. **运行期**：
+   - 文件变更时，仅生成“新增 class”的 CSS\n+   - **分区插入**：新增的普通规则插入到 `BASE_END` 之前；新增的 `@media` 块插入到 `MEDIA_END` 之前（保证 `@media` 永远在后）
+   - 新增的 class 自动加入 baseline，保证只增不删
+
+### 优势
+
+- **性能提升**：只追加新增内容，避免全量重写
+- **减少 I/O**：文件写入次数和大小显著减少
+- **保持基线**：BASE 段保持压缩和排序，DELTA 段追加新内容
+
+### 注意事项
+
+- `rebuildOnStart` 必须为 `true`，否则历史垃圾无法自动清理
+- 建议定期重建（重启工具即可），以便清理旧规则、保证输出始终可控
+- 如果需要完全清理，可以手动删除输出文件后重启
+
+## 标准模式 vs 增量模式
+
+### 标准模式（incrementalOnlyAdd: false）
+
+- 文件变更时，会删除不再使用的 class
+- 输出文件始终保持"干净"，只包含当前使用的 class
+- 适合：希望输出文件始终保持最小化的场景
+
+### 增量模式（incrementalOnlyAdd: true）
+
+- 文件变更时，只新增 class，不删除已存在的 class
+- 输出文件可能随时间增长
+- 适合：需要保留历史 class 或输出文件可能被外部修改的场景
+
+## 最佳实践
+
+1. **推荐开启 rebuildOnStart**：保证每次启动输出文件都是干净且排序好的
+2. **定期检查未使用的 class**：关注启动时的 unused 报告
+3. **使用 appendDelta 提升性能**：在大型项目中，appendDelta 模式可以显著提升增量更新速度
+4. **合理设置 unusedReportLimit**：避免控制台输出过长
+
+## 下一步
+
+- 了解统一文件输出与基础配置：阅读 [配置指南](./config.md)

package/docs/guide/rules-reference.md

@@ -1,6 +1,6 @@
 # 规则参考（当前模板已内置）
 
-本页把仓库默认的 `class2css.config.js` 里**已经实现**的规则，按使用习惯（边距 / 宽高 / 文字 / 颜色 / 布局 / 自定义）整理成一份“像 Tailwind 一样可查”的参考。
+本页把仓库示例配置（`examples/weapp/`）里**已经实现**的规则，按使用习惯（边距 / 宽高 / 文字 / 颜色 / 布局 / 自定义）整理成一份“像 Tailwind 一样可查”的参考。
 
 :::tip 提示
 动态类的通用格式是：`<prefix>-<value>`。  
@@ -209,6 +209,78 @@
 
 </details>
 
+### 直接颜色值写法（无需配置）
+
+除了使用预设的颜色映射（如 `bg-red`、`color-white`），现在支持直接在 class 中写入颜色值。该功能适用于所有带 `ABBR` 的颜色族（`bg`、`color`、`bcolor` 等）。
+
+#### Hex 颜色格式
+
+```html
+<!-- 3位 hex -->
+<div class="bg-hex-fff">白色背景</div>
+<div class="color-hex-000">黑色文字</div>
+
+<!-- 4位 hex（含 alpha） -->
+<div class="bg-hex-ffff">不透明白色背景</div>
+
+<!-- 6位 hex -->
+<div class="bg-hex-112233">深色背景</div>
+<div class="color-hex-ff0000">红色文字</div>
+
+<!-- 8位 hex（含 alpha） -->
+<div class="bg-hex-ffffffff">完全不透明白色背景</div>
+```
+
+#### RGB 颜色格式
+
+```html
+<div class="bg-rgb-255-0-0">红色背景</div>
+<div class="color-rgb-0-128-255">蓝色文字</div>
+```
+
+#### RGBA 颜色格式
+
+```html
+<!-- alpha 值支持多种写法：
+     - 两位数字 < 10：除以 10（如 05 → 0.5, 08 → 0.8）
+     - 两位数字 >= 10：除以 100 作为百分比（如 50 → 0.5, 99 → 0.99）
+     - 下划线分隔：直接替换为点（如 0_5 → 0.5）
+     - 其他格式：直接解析（如 1 → 1.0, 0.5 → 0.5）
+-->
+<div class="bg-rgba-0-0-0-05">半透明黑色背景（05 → 0.5）</div>
+<div class="bg-rgba-255-0-0-0_5">半透明红色背景（0_5 → 0.5）</div>
+<div class="bg-rgba-0-0-0-50">50% 不透明度黑色背景（50 → 0.5）</div>
+<div class="color-rgba-0-0-0-08">80% 不透明度黑色文字（08 → 0.8）</div>
+<div class="bg-rgba-255-0-0-99">99% 不透明度红色背景（99 → 0.99）</div>
+```
+
+#### 与响应式和 Important 组合使用
+
+```html
+<!-- 响应式变体 -->
+<div class="sm:bg-hex-fff md:bg-rgb-255-0-0">响应式背景色</div>
+
+<!-- Important 标识 -->
+<div class="bg-hex-fff_i">强制白色背景</div>
+<div class="!color-rgb-0-0-0">强制黑色文字</div>
+
+<!-- 组合使用 -->
+<div class="sm:bg-rgba-255-0-0-05_i">响应式 + Important</div>
+```
+
+:::tip 优先级说明
+- **映射优先**：如果配置中存在对应的颜色映射（如 `bg-red`），优先使用映射值
+- **直接值后备**：只有当映射不存在时，才会尝试解析为直接颜色值
+- **解析失败**：如果既不是映射值，也无法解析为有效颜色值，则不会生成 CSS 规则
+:::
+
+:::warning 兼容性
+- ✅ 完全兼容 Web（HTML/CSS）
+- ✅ 完全兼容小程序（WXML/WXSS）
+- ✅ 只使用字母、数字、下划线、短横线，无需转义
+- ✅ 与现有颜色映射方案完全兼容，不会产生冲突
+:::
+
 ---
 
 ## 布局 / 显示（静态类）