@neatui/css 3.17.0 → 4.0.0

package/GUIDE.md

@@ -1,10 +1,10 @@
 # NeatUI 完整使用手册
 
-> **版本**: @neatui/css v3.15.0
+> **版本**: @neatui/css v4.0.0
 >
-> **更新日期**: 2025-11-29
+> **更新日期**: 2026-07-28
 >
-> **定位**: 这不是一个 CSS 工具库，而是一套完整的设计系统 + 原子化实现
+> **定位**: 这不是又一个 CSS 工具库，而是一套完整的设计系统 + 原子化实现
 
 ---
 
@@ -36,7 +36,7 @@ NeatUI 要求你摒弃传统的 CSS 思维，建立全新的思维模型：
 ✅ 正确: n-mm; w-lm;
 ```
 
-**原则**：永远不使用任意像素值，使用 S/M/L 相对尺寸体系。
+**原则**：永远不轻易使用任意像素值，使用 S/M/L 相对尺寸体系。（特殊场景下使用自定义值应作为特批备注）
 
 #### 2. 坐标思维 > 属性思维
 ```
@@ -94,8 +94,8 @@ npm install @neatui/css
 # Yarn
 yarn add @neatui/css
 
-# Nuxt 项目
-npm install @neatui/css @neatui/nuxt
+# Vue / Nuxt 项目
+npm install @neatui/css @neatui/vue
 ```
 
 ### 在项目中引入
@@ -113,15 +113,9 @@ npm install @neatui/css @neatui/nuxt
 }
 ```
 
-#### 方式 2: Nuxt 配置
-```ts
-// nuxt.config.ts
-export default defineNuxtConfig({
-  modules: [
-    '@neatui/nuxt'
-  ]
-})
-```
+#### 方式 2: Nuxt 项目
+
+在 Nuxt 应用样式中引入 `@neatui/css`，组件直接从 `@neatui/vue` 导入。
 
 ### 第一个示例
 
@@ -143,6 +137,8 @@ export default defineNuxtConfig({
 
 ## 尺寸系统
 
+从3.x升级时，同名尺寸类不保证保持原值。请按 [4.0尺寸迁移指南](./MIGRATION-4.0.md) 的旧值表进行迁移。
+
 ### 核心概念：S/M/L 矩阵
 
 NeatUI 采用 **分形尺寸体系**，而非线性数值：
@@ -163,50 +159,97 @@ NeatUI 采用 **分形尺寸体系**，而非线性数值：
   第二个字母 = 微调
 ```
 
-### 12 级尺寸阶梯
+### 宽高基础段（含 no 共 12 档）
 
 ```
-no  →  0      (无)
-xs  →  0.5em  (超小)
-ss  →  0.75em (小-小)
-sm  →  1em    (小-中)
-sl  →  1.25em (小-大)
-ms  →  1.5em  (中-小)
-mm  →  2em    (中-中)
-ml  →  2.5em  (中-大)
-ls  →  3em    (大-小)
-lm  →  4em    (大-中)
-ll  →  6em    (大-大)
-xl  →  8em    (超大)
+no  →  0
+xs  →  0.5em
+ss  →  1em
+sm  →  1.5em
+sl  →  2em
+ms  →  2.5em
+mm  →  3em
+ml  →  3.5em
+ls  →  4em
+lm  →  4.5em
+ll  →  5em
+xl  →  5.5em
 ```
 
-### 修饰符扩展（5 倍精度）
+各模块共享档位名称，但不共享同一组数值；上表只适用于 `w / min-w / max-w / h / min-h / max-h`。
+
+### 宽高分段扩展
 
 ```scss
-基础值:
-  w-ll      // 6em
+基础段:
+  w-xs      // 0.5em
+  w-xl      // 5.5em
 
-增量 (+):
-  w-ll+     // 7em  (基础 + 1)
+紧凑容器段:
+  w-xs*s    // 6em
+  w-xl*s    // 16em
 
-倍数 (*):
-  w-ll*s    // 12em (基础 × 2)
-  w-ll*m    // 18em (基础 × 3)
-  w-ll*l    // 24em (基础 × 4)
+中型容器段:
+  w-xs*m    // 18em
+  w-xl*m    // 38em
+
+大型容器段:
+  w-xs*l    // 42em
+  w-xl*l    // 82em
 ```
 
-**覆盖范围**: 0-80em (0-1280px @ 16px)，共 60+ 种精确尺寸
+`w/h` 的 `*s/*m/*l` 是分段档位，不是乘法。4.0 起不再生成 `w-sm+` 这类宽高增量类。
+
+**覆盖范围**: 0-82em (0-1312px @ 16px)，共 45 种宽高尺寸
 
 ### 应用于各属性
 
 | 前缀 | 属性 | 示例 | 说明 |
 |-----|------|------|------|
-| `n-` | padding | `n-mm` | 内边距 2em |
-| `m-` | margin | `m-ss` | 外边距 0.75em |
-| `w-` | width | `w-ll` | 宽度 6em |
-| `h-` | height | `h-sm` | 高度 1em |
-| `r-` | border-radius | `r-ms` | 圆角 1.5em |
-| `fs-` | font-size | `fs-lm` | 字号 4em |
+| `n-` | padding | `n-mm` | 内边距 1.5em |
+| `m-` | margin | `m-ss` | 外边距 0.25em |
+| `w-` | width | `w-ll` | 宽度 5em |
+| `h-` | height | `h-sm` | 高度 1.5em |
+| `r-` | border-radius | `r-ms` | 圆角 0.5em |
+| `fs-` | font-size | `fs-lm` | 基础字号 1.625rem |
+
+### 字号分段扩展
+
+```scss
+基础字号:
+  fs-xs      // 0.625rem
+  fs-xl      // 1.875rem
+
+展示字号:
+  fs-xs*s    // 2rem
+  fs-xl*s    // 4.5rem
+
+视觉字号:
+  fs-xs*m    // 5rem
+  fs-xl*m    // 10rem
+
+巨型字号:
+  fs-xs*l    // 11rem
+  fs-xl*l    // 21rem
+```
+
+字号使用 `rem`，跟随根字号缩放。4.0 起不再生成 `fs-sm+` 微调和旧 `fs-sm*` 翻倍语法，`*s/*m/*l` 是展示、视觉、巨型字号分段。
+
+### 语义与上下文字号
+
+```scss
+fs-case  // 0.625rem
+fs-note  // 0.75rem
+fs-desc  // 0.875rem
+fs-body  // 1rem
+fs-lead  // 1.125rem
+
+fs-root  // 1rem，重置到根字号
+fs++     // 1.125em，相对当前上下文放大
+fs--     // 0.875em，相对当前上下文缩小
+```
+
+`fs++ / fs--` 是4.0保留的上下文缩放语法，不属于已删除的 `fs-{size}+` 和 `fs-{size}*`。
 
 ### 方向修饰符
 
@@ -226,7 +269,7 @@ mx-sm  // margin-left + margin-right
 ### 特殊值
 
 ```scss
-r-round  // border-radius: 50% (圆形)
+r-full   // border-radius: 10000em (胶囊或圆形轮廓)
 r-no     // border-radius: 0 (无圆角)
 
 w-full   // width: 100%
@@ -242,96 +285,135 @@ h-auto   // height: auto
 
 ### 核心概念：语义化色彩
 
-NeatUI 的色彩系统分为三层：
+NeatUI 的色彩系统分为三层，但只封闭「角色、算子、档位、通道和状态」；
+主题名与项目扩展颜色名保持开放：
 
 ```
-层级 1: 基础色 (8 个)
-  ├─ main  (主色)
-  ├─ vice  (辅助色)
-  ├─ well  (成功)
-  ├─ warn  (警告)
-  ├─ risk  (危险)
-  ├─ info  (信息)
-  ├─ text  (文本)
-  └─ fore  (前景)
+层级 1: 9 个必需种子
+  ├─ main, text, fore, back
+  └─ link, code, well, warn, risk
 
-层级 2: 语义色 (自动推导)
-  ├─ read, desc, note, line, weak  (5 级文字)
-  └─ 12 级透明度 + 混合色
+层级 2: 10 个自动角色
+  ├─ none, w, b
+  ├─ read, desc, note, case, line, weak
+  └─ deep
 
-层级 3: 主题色 (自动切换)
-  ├─ light (浅色主题)
-  └─ dark  (深色主题)
+层级 3: 13 档派生 + 3 通道 + 3 状态
+  ├─ o / w / b × xxs…xxl
+  ├─ co / bg / b
+  └─ base / hover / active
 ```
 
+`info`、`vice`、`brand` 是扩展示例，但不是必需种子。
+`light`、`dark` 也只是最常见的主题名；项目可以按产品需要定义春节、品牌、
+高对比度等任意主题，也可以扩展自己的颜色名称。NeatUI 约束的是颜色如何派生和使用，
+不是把主题限制成预设名单。
+
 ### 基础色配置
 
 ```scss
 // 在项目中配置主题
+@use '@neatui/css' as neatui;
+
 $theme: (
-  'light': (
-    main: #00b277,    // 品牌主色
-    vice: #67ce82,    // 品牌辅助色
-    well: #4bbc73,    // 成功 (绿色系)
-    warn: #fb9a2a,    // 警告 (橙色系)
-    risk: #f95850,    // 危险 (红色系)
-    info: #3c49dd,    // 信息 (蓝色系)
-    text: #000000,    // 主文本色
-    fore: #ffffff,    // 前景/卡片背景色
+  light: (
+    main: #00b277, // 品牌主色
+    vice: #67ce82, // 品牌辅助色（可自定义名称）
+    text: #000000,
+    fore: #ffffff,
+    back: #f5f5f5,
+    link: #d07950,
+    code: #e23861,
+    well: #4bbc73,
+    warn: #fb9a2a,
+    risk: #f95850,
+    info: #3c49dd,
   ),
-  'dark': (
-    // 深色主题配置...
+  dark: (
+    main: #00b277,
+    vice: #67ce82,
+    text: #ffffff,
+    fore: #1f1f1f,
+    back: #191919,
+    link: #dd7f49,
+    code: #e23861,
+    well: #4bbc73,
+    warn: #fb9a2a,
+    risk: #f95850,
+    info: #3c49dd,
   )
 );
+
+@include neatui.theme($theme);
 ```
 
 ### 自动推导的语义色
 
 ```scss
-// 系统自动计算，无需手动定义
---co-read: rgba(text, 0.85)   // 主要阅读文字
---co-desc: rgba(text, 0.55)   // 描述性文字
---co-note: rgba(text, 0.35)   // 注释/提示文字
---co-line: rgba(text, 0.10)   // 分割线
---co-weak: rgba(text, 0.035)  // 弱化背景
+// mix-int(from, toward, weight) 对 RGB 通道取整
+--co-read: mix-int(text, fore, 85%)
+--co-desc: mix-int(text, fore, 55%)
+--co-note: mix-int(text, fore, 35%)
+--co-case: mix-int(text, fore, 20%)
+--co-line: mix-int(text, fore, 10%)
+--co-weak: mix-int(text, fore, 3.5%)
 
-// 反转色 (前景色)
---co-case: rgba(fore, 0.85)   // 反转主文字
---co-link: rgba(fore, 0.55)   // 反转描述
---co-tips: rgba(fore, 0.35)   // 反转提示
+--co-none: transparent
+--co-w: #fff
+--co-b: #000
+--co-deep: dynamic-deepen(back, 8%, 16%)
 ```
 
+项目如果显式提供与自动角色同名的颜色，就以项目配置为准；其他扩展色会直接追加进
+主题色卡。所有主题中出现过的颜色名都会合并生成对应的 class，所以不同主题可以共享
+同一套 `co-* / bg-* / b-*` 表达。
+
 ### 颜色属性前缀
 
 | 前缀 | 属性 | 示例 | 输出 |
 |-----|------|------|------|
 | `co-` | color | `co-main` | 主色文字 |
 | `bg-` | background | `bg-risk` | 危险背景 |
-| `bk-` | border-color | `bk-line` | 线条边框 |
+| `b-` | border-color | `b-line` | 线条边框 |
+
+4.0 不再使用旧的 `bk-*`。`b-` 同时是边框样式、宽度和颜色的统一前缀：
+`b-solid` 表示样式，`b-xs` 表示宽度，`b-line` 表示颜色；具体语义由后缀词元决定。
 
-### 完整颜色类名列表
+### 基于上例生成的颜色类
 
 #### 品牌色
 ```scss
-co-main, bg-main, bk-main  // 主色
-co-vice, bg-vice, bk-vice  // 辅助色
+co-main, bg-main, b-main  // 主色
+co-vice, bg-vice, b-vice  // 辅助色
 ```
 
 #### 功能色
 ```scss
-co-well, bg-well, bk-well  // 成功 ✅
-co-warn, bg-warn, bk-warn  // 警告 ⚠️
-co-risk, bg-risk, bk-risk  // 危险 ❌
-co-info, bg-info, bk-info  // 信息 ℹ️
+co-well, bg-well, b-well  // 成功 ✅
+co-warn, bg-warn, b-warn  // 警告 ⚠️
+co-risk, bg-risk, b-risk  // 危险 ❌
+co-info, bg-info, b-info  // 信息 ℹ️
 ```
 
 #### 基础色
 ```scss
-co-text, bg-text, bk-text  // 文本色
-co-fore, bg-fore, bk-fore  // 前景色
-co-back, bg-back, bk-back  // 背景色
+co-text, bg-text, b-text  // 文本色
+co-fore, bg-fore, b-fore  // 前景色
+co-back, bg-back, b-back  // 背景色
 ```
 
+#### 绝对色
+```scss
+co-w, bg-w, b-w  // 固定 #fff，不随主题变化
+co-b, bg-b, b-b  // 固定 #000，不随主题变化
+```
+
+绝对色用于颜色关系本身已经确定的场景，例如品牌色、状态色或深色图片上的纯白内容，
+以及确定的浅色彩底上的纯黑内容。它们不能与主题语义色混用：`co-fore` 表示当前主题
+的前景面颜色，`co-read / co-text` 表示当前主题的正文颜色，都不保证为纯白或纯黑。
+因此有色深背景上的白字应使用 `co-w`，不能用 `co-fore`、`co-read` 或 `co-text`
+碰巧获得接近结果。
+
 #### 语义色
 ```scss
 co-read   // 主要文字 (85%)
@@ -340,18 +422,24 @@ co-note   // 注释文字 (35%)
 co-line   // 分割线 (10%)
 co-weak   // 弱化背景 (3.5%)
 
-// 反转色 (用于深色背景)
-co-case   // 反转主文字
-co-link   // 反转链接
-co-tips   // 反转提示
+co-case   // 更弱一级的语义文字 (20%)
+co-link   // 主题配置的链接色
 ```
 
-### 透明度系列 (12 级)
+### 派生系列（13 级）
 
-任何颜色 + `-o-{level}` = 透明度变体
+13 档不是等差近似，而是与 4.x Sass 运行时精确一致：
+
+| level | xxs | xs | ss | sm | sl | ms | mm | ml | ls | lm | ll | xl | xxl |
+|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|---:|
+| weight | .035 | .05 | .10 | .15 | .25 | .35 | .45 | .55 | .65 | .75 | .85 | .90 | .95 |
+
+`o` 使用颜色本身与 alpha；`w` 按权重向 `fore` 混合；`b` 按权重向
+`text` 混合。
 
 ```scss
-co-main-o-xs  // 主色 + 超低透明度
+co-main-o-xxs
+co-main-o-xs
 co-main-o-ss
 co-main-o-sm
 co-main-o-sl
@@ -361,56 +449,61 @@ co-main-o-ml
 co-main-o-ls
 co-main-o-lm
 co-main-o-ll
-co-main-o-xl  // 主色 + 超高透明度
+co-main-o-xl
+co-main-o-xxl
 ```
 
-### 混合色系列
-
 ```scss
-// 与前景色混合 (变浅)
-co-main-w-sm  // 主色 + 前景色 10%
-co-main-w-mm  // 主色 + 前景色 20%
-co-main-w-ml  // 主色 + 前景色 30%
-
-// 与文本色混合 (变深)
-co-main-b-sm  // 主色 + 文本色 10%
-co-main-b-mm  // 主色 + 文本色 20%
-co-main-b-ml  // 主色 + 文本色 30%
+co-main-w-sm  // main 占 15%，其余趋向 fore
+co-main-b-sm  // main 占 15%，其余趋向 text
 ```
 
+`w / b / fore / back / desc / note / case / deep / code / link` 不生成
+`w`、`b` 派生族。4.x 还保留一个兼容特征：`none` 不生成 `o/w/b` 变量，
+但对应 class 选择器仍会生成。迁移和工具实现必须尊重这一历史行为。
+
 ### 边框样式
 
 ```scss
 // 边框宽度
-bt-xs, br-xs, bb-xs, bl-xs  // 0.5px
-bt-ss, br-ss, bb-ss, bl-ss  // 1px
-bt-sm, br-sm, bb-sm, bl-sm  // 2px
+bt-xs, br-xs, bb-xs, bl-xs  // 1px
+bt-ss, br-ss, bb-ss, bl-ss  // 2px
+bt-sm, br-sm, bb-sm, bl-sm  // 3px
 
 // 边框样式
 b-solid   // 实线
 b-dashed  // 虚线
+b-double  // 双线
 b-dotted  // 点线
-b-none    // 无边框
+b-no      // 四边宽度归零
 ```
 
 ### 主题切换
 
 ```html
-<!-- 切换全局主题 -->
-<html theme="light">  <!-- 浅色主题 -->
-<html theme="dark">   <!-- 深色主题 -->
+<!-- 配置数组中的第一个主题直接编译到 :root，无需 theme 属性 -->
+<html>
 
-<!-- 所有颜色自动切换，0 行额外代码！ -->
+<!-- 第二个及之后的主题使用 token selector，可继续自定义名称 -->
+<html theme="midnight">
 ```
 
+第一个主题不会额外生成 `[theme~="<first>"]` 选择器，因为它始终作为 `:root`
+默认值存在；第二个及之后的主题通过 `theme` 属性覆盖它。切回默认主题时，移除或改掉
+当前主题属性即可。因此主题顺序有运行时含义，不只是配置排版。
+
+主题系统的边界是“结构有限、内容开放”：`co / bg / b`、派生档位和交互状态保持
+统一，主题名和项目色卡由产品自己定义。这样既能保持组件表达稳定，也不会把
+NeatUI 限制成 light/dark 或某一组固定品牌色。
+
 ### 颜色使用示例
 
 ```html
 <!-- 主色按钮 -->
-<button class="bg-main co-case">主操作</button>
+<button class="bg-main co-w">主操作</button>
 
 <!-- 危险操作 -->
-<button class="bg-risk co-case">删除</button>
+<button class="bg-risk co-w">删除</button>
 
 <!-- 卡片 -->
 <div class="bg-fore co-text n-mm r-sm">
@@ -420,7 +513,7 @@ b-none    // 无边框
 </div>
 
 <!-- 分割线 -->
-<div class="bt-xs bk-line"></div>
+<div class="bt-xs b-line"></div>
 
 <!-- Hover 透明度 -->
 <a class="co-main co-main-o-lm:hover">链接</a>
@@ -434,11 +527,11 @@ b-none    // 无边框
 
 #### 核心理念
 
-**废除 flexbox 概念，用空间坐标直接描述位置！**
+`ui-flex` 用空间坐标 token 描述位置，再由兼容 CSS 编译为 flex 布局。
 
 ```
-传统思维: display: flex + justify-content + align-items
-NeatUI 思维: ui-flex="横向 纵向"
+属性表达: display: flex + justify-content + align-items
+坐标表达: ui-flex="横向 纵向"
 ```
 
 #### 坐标系规则
@@ -508,17 +601,17 @@ y: 纵向对齐
 </div>
 ```
 
-#### 实战对比
+#### 同一意图的两种表达
 
 **场景 1: 导航栏**
 ```html
-<!-- Tailwind: 需要理解 flexbox -->
+<!-- 属性导向的 utility 表达 -->
 <nav class="flex justify-between items-center px-4 py-2">
   <div>Logo</div>
   <div>Menu</div>
 </nav>
 
-<!-- NeatUI: 空间直觉 -->
+<!-- NeatUI 坐标 token -->
 <nav ui-flex="row xm" class="nx-sm ny-sm">
   <div>Logo</div>
   <div>Menu</div>
@@ -527,7 +620,7 @@ y: 纵向对齐
 
 **场景 2: 居中对话框**
 ```html
-<!-- Tailwind -->
+<!-- 属性导向的 utility 表达 -->
 <div class="flex justify-center items-center min-h-screen">
   <div class="bg-white p-6">内容</div>
 </div>
@@ -540,7 +633,7 @@ y: 纵向对齐
 
 **场景 3: 卡片布局**
 ```html
-<!-- Tailwind -->
+<!-- 属性导向的 utility 表达 -->
 <div class="flex flex-col items-center p-4">
   <img class="w-16 h-16 rounded-full" />
   <h3 class="mt-2">标题</h3>
@@ -613,6 +706,49 @@ gap: 间距等级 (ss, sm, mm, ml, ll...)
 
 ---
 
+## 媒体内容
+
+### `ui-cover`：固定比例封面
+
+`ui-cover` 把容器设为相对定位的比例盒，并让直接子元素绝对铺满。图片默认使用
+`object-fit: cover`：
+
+```html
+<!-- 16:9 裁切填充 -->
+<figure ui-cover="16:9">
+  <img src="/cover.jpg" alt="文章封面" />
+</figure>
+
+<!-- 3:2 比例，但完整显示图片 -->
+<figure ui-cover="3:2 contain">
+  <img src="/product.png" alt="商品" />
+</figure>
+```
+
+固定比例只能从以下 13 个值选择：
+
+```text
+1:1, 2:1, 1:2, 4:3, 3:4, 3:2, 2:3,
+16:9, 9:16, 16:10, 10:16, 2.39:1, 1:2.39
+```
+
+也可以用 `+no..+xl` 或 `-no..-xl` 从默认的 `100%` 高度按 5% 递增或递减。
+比例和偏移是同一个“高度模式”，一次只能选择一个；`cover / contain` 可以再与它
+组合。该语法不接受任意比例、任意百分比或响应式前缀。
+
+### `ui-omit`：1–9 行省略
+
+```html
+<p ui-omit="1">单行标题，超出后显示省略号</p>
+<p ui-omit="3">最多显示三行的简介，超出后截断。</p>
+```
+
+`ui-omit` 一次只接受 `1..9` 中的一个值：`1` 使用单行 `nowrap`，`2..9`
+使用 `-webkit-line-clamp`。不要只写裸 `ui-omit`，因为历史结构规则会进入多行模式，
+但没有行数值可供 `--line` 使用。该语法同样没有响应式前缀。
+
+---
+
 ## 响应式系统
 
 ### 9 档精细断点
@@ -636,57 +772,130 @@ dpc-m: 1440px  // 中桌面 (主流显示器)
 dpc-l: 1600px  // 大桌面 (2K 显示器)
 ```
 
+### 24 栅格：`ui-row` 与 `ui-col`
+
+栅格只接受 `<breakpoint>-<span>`，其中 `span` 是 `0..24`。它有两种 selector
+目标：
+
+```html
+<!-- row 宽度作用于每个直接子元素 -->
+<div ui-row="space mob-24 pad-12 dpc-8">
+  <section>第一列</section>
+  <section>第二列</section>
+</div>
+
+<!-- col 宽度作用于 [ui-row] 内带 ui-col 的后代，可逐列不同 -->
+<div ui-row="space">
+  <main ui-col="mob-24 pad-16 dpc-18">主体</main>
+  <aside ui-col="mob-24 pad-8 dpc-6">侧栏</aside>
+</div>
+```
+
+公开 breakpoint 共十二个：
+
+```text
+mob, mob-s, mob-m, mob-l
+pad, pad-s, pad-m, pad-l
+dpc, dpc-s, dpc-m, dpc-l
+```
+
+栅格沿用当前 `cols.scss` 的实际 source order：`mob` 与 `mob-s` 都是基础层；
+`mob-m / mob-l / pad(-s) / pad-m / pad-l / dpc(-s) / dpc-m / dpc-l`
+依次从 480 / 640 / 800 / 960 / 1120 / 1280 / 1440 / 1600px 起覆盖。
+这里的 `mob-s` 与上面的命名断点表不同，它在现有栅格 CSS 中没有 320px media
+包裹。这是 4.x 当前输出的兼容行为，使用和迁移时不要把它误当成独立媒体区间。
+
+百分比由 24 栏公式向下截断到 5 位小数：
+
+| Span | 宽度 |
+| ---: | ---: |
+| `0` | `0` |
+| `1` | `4.16666%` |
+| `6` | `25%` |
+| `12` | `50%` |
+| `18` | `75%` |
+| `24` | `100%` |
+
+行行为也属于有限语法：
+
+- `space`：行负 margin 与子元素 padding 成对出现，799px 以下从 1rem 缩为 .5rem；
+- `:full`：设置 `> * > *` 的高度为 100%；
+- `inline` / `reverse`：切换 inline-flex 或无条件 row-reverse；
+- `mob-auto / pad-auto / dpc-auto`：三个历史名称都只属于 `ui-row`，实际均无媒体条件；
+- `mob:reverse / pad:reverse / dpc:reverse`：分别只在
+  0–799 / 800–1279 / 1280px 以上生效。
+
+表格兼容仍为 `tr[ui-row] { display: table-row }` 与
+`td/th[ui-col] { display: table-cell }`。`mob-auto` 只属于 `ui-row`；栅格跨度使用
+`0..24`，自定义像素布局不属于这套栅格语法。
+
 ### 三种操作符
 
-#### 1. `>` 大于（min-width）
+`ui-hide` 的 `>`、`<`、`=` 比较的是命名档位或完整设备段，不接收任意像素值。
+所有 selector 都使用 `[ui-hide~="<token>"]`，因此多个隐藏条件可以用空格组合。
+
+#### 1. `>` 高于命名范围
 
 ```html
-<!-- 平板以上显示 -->
-<div class="pad:w-mm">内容</div>
+<!-- 高于 pad 设备段后隐藏，即从 1280px 起隐藏 -->
+<div ui-hide=">pad">仅手机和平板显示</div>
 
-<!-- 桌面以上隐藏 -->
-<div ui-hide=">dpc">移动端专属</div>
+<!-- 高于 dpc-m 档后隐藏，即从 dpc-l 的 1600px 起隐藏 -->
+<div ui-hide=">dpc-m">1600px 以下显示</div>
 ```
 
-#### 2. `<` 小于（max-width）
+`>dpc-l` 是最高档之后的兼容空端点，当前不会产生隐藏效果。
+
+#### 2. `<` 低于命名范围
 
 ```html
-<!-- 桌面以下隐藏 -->
+<!-- 低于 dpc 设备段隐藏，即到 1279px 为止隐藏 -->
 <div ui-hide="<dpc">桌面专属</div>
 
-<!-- 平板以下宽度 100% -->
-<div class="w-full <pad:w-mm">响应式容器</div>
+<!-- 低于 mob-m 档隐藏，即到 479px 为止隐藏 -->
+<div ui-hide="<mob-m">480px 起显示</div>
 ```
 
-#### 3. `=` 精确区间
+`<mob-s` 是最低档之前的兼容空端点，当前不会产生隐藏效果。
+
+#### 3. `=` 命名区间
 
 ```html
-<!-- 仅在中平板显示 (960px-1119px) -->
+<!-- 仅在中平板区间隐藏（960px–1119px） -->
 <div ui-hide="=pad-m">仅中平板隐藏</div>
+
+<!-- 整个移动设备段隐藏（最大 799px） -->
+<div ui-hide="=mob">平板和桌面内容</div>
 ```
 
-### 断点类名语法
+### 内置 `ui-hide` 值
 
-```scss
-// 格式: {breakpoint}:{class-name}
-mob:fs-sm      // 移动端字号小
-pad:fs-mm      // 平板字号中
-dpc:fs-lm      // 桌面字号大
+| 关系 | 九档细分值 | 设备段别名 |
+| --- | --- | --- |
+| `>` | `>mob-s` … `>dpc-l` | `>mob`、`>pad` |
+| `<` | `<mob-s` … `<dpc-l` | `<pad`、`<dpc` |
+| `=` | `=mob-s` … `=dpc-l` | `=mob`、`=pad`、`=dpc` |
+
+除两个兼容空端点外，命中的规则都使用 `display: none !important`。
 
-// 组合使用
-<h1 class="fs-sm mob:fs-mm pad:fs-ml dpc:fs-xl">
-  响应式标题
-</h1>
+### 响应式 class 前缀
+
+组件级 class 使用 `base → pad → mob` 三层覆盖；`pad:` 在最大 1279px 生效，
+`mob:` 在最大 799px 生效。这里没有通用 `dpc:` class 前缀：
+
+```html
+<h1 class="fs-xl pad:fs-ml mob:fs-mm">响应式标题</h1>
+<div class="w-xl pad:w-mm mob:w-full">响应式容器</div>
 ```
 
 ### ui-hide：显示/隐藏控制
 
 ```html
 <!-- 移动端隐藏 -->
-<div ui-hide="mob">桌面内容</div>
+<div ui-hide="=mob">桌面内容</div>
 
 <!-- 桌面隐藏 -->
-<div ui-hide="dpc">移动内容</div>
+<div ui-hide="=dpc">移动和平板内容</div>
 
 <!-- 小于平板隐藏 -->
 <div ui-hide="<pad">平板以上显示</div>
@@ -696,9 +905,16 @@ dpc:fs-lm      // 桌面字号大
 
 <!-- 精确区间隐藏 -->
 <div ui-hide="=pad-m">仅在中平板隐藏</div>
+
+<!-- 多个条件组成隐藏区间的并集 -->
+<div ui-hide="=mob =dpc-l">仅平板和较小桌面显示</div>
 ```
 
-### 全局字号响应（革命性功能）
+`ui-hide` 只改变 CSS 可见性，不会卸载 Vue 组件，也不会停止请求、事件监听或定时器，
+不会自动迁移焦点和业务状态。需要停止副作用或销毁子树时，应使用 Vue 条件渲染并显式
+处理状态与焦点，而不是把 `ui-hide` 当作生命周期控制。
+
+### 全局字号响应
 
 ```html
 <!-- 在 <html> 标签设置全局字号 -->
@@ -707,8 +923,7 @@ dpc:fs-lm      // 桌面字号大
 <html size="l">   <!-- 大字号模式 -->
 <html size="xl">  <!-- 超大字号模式 (老年模式) -->
 
-<!-- 所有使用 em 单位的元素自动缩放！ -->
-<!-- 0 行 CSS，0 个媒体查询，全站响应！ -->
+<!-- 使用 em 且继承根字号的属性会随之缩放 -->
 ```
 
 **实战用例：老年人模式**
@@ -727,7 +942,7 @@ function toggleElderlyMode() {
       切换大字模式
     </button>
 
-    <!-- 所有内容自动放大，无需额外代码！ -->
+    <!-- 已采用相对字号的内容随根字号变化 -->
   </html>
 </template>
 ```
@@ -855,7 +1070,7 @@ ui-btn="[@{flag}] {color} {size} [:{modifier}]"
 
 ---
 
-## 完整 API 参考
+## 常用 API 参考
 
 ### 间距类 (Spacing)
 
@@ -864,17 +1079,17 @@ ui-btn="[@{flag}] {color} {size} [:{modifier}]"
 | 类名 | 属性 | 值 |
 |-----|------|------|
 | `n-no` | padding | 0 |
-| `n-xs` | padding | 0.5em |
-| `n-ss` | padding | 0.75em |
-| `n-sm` | padding | 1em |
-| `n-sl` | padding | 1.25em |
-| `n-ms` | padding | 1.5em |
-| `n-mm` | padding | 2em |
-| `n-ml` | padding | 2.5em |
-| `n-ls` | padding | 3em |
-| `n-lm` | padding | 4em |
-| `n-ll` | padding | 6em |
-| `n-xl` | padding | 8em |
+| `n-xs` | padding | 1px |
+| `n-ss` | padding | 0.25em |
+| `n-sm` | padding | 0.5em |
+| `n-sl` | padding | 0.75em |
+| `n-ms` | padding | 1em |
+| `n-mm` | padding | 1.5em |
+| `n-ml` | padding | 2em |
+| `n-ls` | padding | 2.5em |
+| `n-lm` | padding | 3em |
+| `n-ll` | padding | 4em |
+| `n-xl` | padding | 5em |
 
 #### 方向 Padding
 
@@ -898,21 +1113,41 @@ mr-{size}  // margin-right
 mb-{size}  // margin-bottom
 ml-{size}  // margin-left
 
-// 特殊值
-m-auto     // margin: auto
-mx-auto    // margin-left/right: auto (水平居中)
-my-auto    // margin-top/bottom: auto
+// 作用层级
+mx-{size}-sub  // 为直系子元素设置左右 margin，并归零首/末项外边界
+mx-{size}-sun  // 为孙级元素设置左右 margin，并归零每组首/末项外边界
 ```
 
 #### 负 Margin
 
 ```scss
-mx-sm-sub  // margin-left/right: -1em
-my-sm-sub  // margin-top/bottom: -1em
-mt-sm-sub  // margin-top: -1em
-// 所有尺寸都支持 -sub 后缀
+-mx-sm  // margin-left/right: -0.5em
+-my-sm  // margin-top/bottom: -0.5em
+-mt-sm  // margin-top: -0.5em
+// 负 margin 使用前导负号，不使用 -sub / -sun 后缀
 ```
 
+`n / m / -m` 共用
+`no / xs / ss / sm / sl / ms / mm / ml / ls / lm / ll / xl` 12 档；除负 margin
+外，`-sub` 作用于直系子元素、`-sun` 作用于孙级元素。所有基础 class 都支持
+`pad:`（最大 1279px）和 `mob:`（最大 799px），级联顺序为
+`base → pad → mob`。
+
+Padding 的 `*-sub` 在 `[ui-row]` 容器上还会生成等量负 margin 补偿，让栅格子项的
+内边距不会扩大容器的外边界。
+
+#### Grid gap
+
+```html
+<div ui-grid="4 sm">...</div>
+<div ui-grid="2 mob:sm pad:6 pad:mm dpc:12">...</div>
+```
+
+`ui-grid` 的 `no..xl` 设置 `--gap`，刻度为
+`0 / 1px / .25em / .5em / .75em / 1em / 1.5em / 2em / 2.5em / 3em / 4em / 5em`。
+同一属性还可以组合 `1..12` 列数和 `block`。4.x 的 `mob:` 是无媒体条件的历史别名；
+`pad:` 从 800px、`dpc:` 从 1280px 生效。
+
 ### 尺寸类 (Sizing)
 
 #### Width
@@ -920,13 +1155,12 @@ mt-sm-sub  // margin-top: -1em
 ```scss
 w-no       // 0
 w-xs       // 0.5em
-w-ss ~ w-xl // 0.75em ~ 8em
+w-ss ~ w-xl // 1em ~ 5.5em
 
-// 修饰符
-w-ll+      // 7em  (增量)
-w-ll*s     // 12em (2倍)
-w-ll*m     // 18em (3倍)
-w-ll*l     // 24em (4倍)
+// 分段扩展
+w-ll*s     // 15em
+w-ll*m     // 36em
+w-ll*l     // 78em
 
 // 特殊值
 w-full     // 100%
@@ -947,24 +1181,32 @@ h-screen   // 100vh
 
 ```scss
 r-no       // border-radius: 0
-r-xs       // 0.5em
-r-ss ~ r-xl // 0.75em ~ 8em
-r-round    // 50% (圆形)
+r-xs       // 0.1em
+r-ss ~ r-xl // 0.2em ~ 1.2em
+r-full     // 10000em（胶囊或圆形轮廓）
 
 // 方向圆角
-rt-{size}  // 左上
-rr-{size}  // 右上
-rb-{size}  // 右下
-rl-{size}  // 左下
+r-t-{size}  // 上方两角
+r-b-{size}  // 下方两角
+r-lt-{size} // 左上
+r-rt-{size} // 右上
+r-lb-{size} // 左下
+r-rb-{size} // 右下
 ```
 
+`size` 为 `no / xs / ss / sm / sl / ms / mm / ml / ls / lm / ll / xl`，
+以上圆角类同时支持 `pad:` 与 `mob:` 响应式前缀。
+
 ### 字体类 (Typography)
 
 ```scss
 // 字号
 fs-no      // 0
-fs-xs      // 0.5em
-fs-ss ~ fs-xl // 0.75em ~ 8em
+fs-xs      // 0.625rem
+fs-ss ~ fs-xl // 0.75rem ~ 1.875rem
+fs-xs*s ~ fs-xl*s // 2rem ~ 4.5rem
+fs-xs*m ~ fs-xl*m // 5rem ~ 10rem
+fs-xs*l ~ fs-xl*l // 11rem ~ 21rem
 
 // 字重
 thin       // font-weight: 100
@@ -990,19 +1232,20 @@ ls-xs ~ ls-xl  // letter-spacing
 
 ```scss
 // 宽度
-bt-xs, br-xs, bb-xs, bl-xs  // 0.5px
-bt-ss, br-ss, bb-ss, bl-ss  // 1px
-bt-sm, br-sm, bb-sm, bl-sm  // 2px
+bt-xs, br-xs, bb-xs, bl-xs  // 1px
+bt-ss, br-ss, bb-ss, bl-ss  // 2px
+bt-sm, br-sm, bb-sm, bl-sm  // 3px
 
 // 样式
 b-solid
 b-dashed
+b-double
 b-dotted
-b-none
+b-no
 
 // 边框颜色
-bk-main, bk-vice, bk-risk...
-bk-line, bk-weak
+b-main, b-vice, b-risk...
+b-line, b-weak
 ```
 
 ### 定位类 (Position)
@@ -1077,6 +1320,10 @@ overflow-x-hidden
 overflow-y-hidden
 ```
 
+滚动系统同时保留 `.ui-scroll` 等 class 写法；`ui-scroll` attribute 提供
+`stable`、五档 scrollbar 尺寸以及 x/y auto、hidden、unset。800px 以上的尺寸覆盖
+只作用于 attribute 形式。
+
 ### 光标类 (Cursor)
 
 ```scss
@@ -1089,13 +1336,27 @@ cursor-move
 
 ### 交互类 (Interaction)
 
-```scss
-pointer-events-none
-pointer-events-auto
-user-select-none
-user-select-text
+```html
+<button class="ux-hover ux-scale">悬停反馈 + 按下缩放</button>
+<button class="ux-disable">视觉与指针禁用</button>
+<span ui-hover=":underline">下划线提示</span>
 ```
 
+常用交互 class 包括：
+
+- `ux-none / ux-none-sub`：pointer 光标并禁止文本选择；
+- `ux-hover[-sub] / ux-shadow[-sub]`：自身或直接子元素的 hover 反馈；
+- `ux-click[-sub] / hover-underline / ui-hover=":underline"`：始终显示
+  pointer 与下划线，不会绑定 click 或 hover 事件；
+- `ux-scale`：`:active` 时缩放到 `.95`；
+- `parent-hover:show / parent-hover:hide`：父级 hover 时只改变
+  opacity 与 pointer-events，DOM 节点始终保留；
+- `ev-none|auto[-sub|-sun]`：以 `!important` 控制 self、直接子级或孙级的
+  pointer-events。
+
+`ux-disable` 会阻止指针事件并降低透明度，但不会自动写入原生 `disabled`；表单组件仍应
+通过自身 API 管理真实禁用状态。以上交互值不使用 `pad:` / `mob:` 响应式前缀。
+
 ---
 
 ## 最佳实践
@@ -1107,7 +1368,7 @@ user-select-text
 <div style="padding: 13px; width: 237px;">
 
 <!-- ✅ 正确：使用规范尺寸 -->
-<div class="n-sm w-ll+">
+<div class="n-sm w-sm*m">
 
 <!-- 如果确实需要特殊值，手写并注释 -->
 <div class="third-party" style="width: 237px">
@@ -1122,7 +1383,7 @@ user-select-text
 <button style="background: #00b277; color: white;">
 
 <!-- ✅ 正确：使用语义色 -->
-<button class="bg-main co-case">
+<button class="bg-main co-w">
 
 <!-- ❌ 错误：使用通用灰色 -->
 <p class="text-gray-600">
@@ -1172,13 +1433,13 @@ user-select-text
 </Card>
 ```
 
-### 6. 深色模式零成本
+### 6. 基于主题属性切换深色模式
 
 ```html
-<!-- 只需切换 theme 属性 -->
+<!-- 切换已配置的 theme 属性 -->
 <html :theme="isDark ? 'dark' : 'light'">
 
-<!-- 所有颜色自动切换，无需额外代码 -->
+<!-- 使用语义色 token 的元素读取对应主题变量 -->
 <div class="bg-fore co-text">
   <h1 class="co-main">自动适配</h1>
 </div>
@@ -1200,7 +1461,7 @@ user-select-text
         <label class="co-desc fs-sm">邮箱</label>
         <input
           type="email"
-          class="w-full n-sm r-sm bg-weak bk-line bt-xs"
+          class="w-full n-sm r-sm bg-weak b-line bt-xs"
         />
       </div>
 
@@ -1208,7 +1469,7 @@ user-select-text
         <label class="co-desc fs-sm">密码</label>
         <input
           type="password"
-          class="w-full n-sm r-sm bg-weak bk-line bt-xs"
+          class="w-full n-sm r-sm bg-weak b-line bt-xs"
         />
       </div>
 
@@ -1297,7 +1558,7 @@ user-select-text
 >
   <div class="w-ll*s bg-fore r-ml shadow-ll">
     <!-- 头部 -->
-    <div class="n-mm bb-xs bk-line" ui-flex="row xm">
+    <div class="n-mm bb-xs b-line" ui-flex="row xm">
       <h3 class="fs-lm bold co-main">标题</h3>
       <button ui-btn="none s" @click="closeDialog">
         <i class="icon-close"></i>
@@ -1310,7 +1571,7 @@ user-select-text
     </div>
 
     <!-- 底部 -->
-    <div class="n-mm bt-xs bk-line" ui-flex="row rm">
+    <div class="n-mm bt-xs b-line" ui-flex="row rm">
       <button ui-btn="none :border" class="mr-sm" @click="closeDialog">
         取消
       </button>
@@ -1327,7 +1588,7 @@ user-select-text
 ```html
 <div class="bg-fore r-sm shadow-sm">
   <table class="w-full">
-    <thead class="bb-xs bk-line">
+    <thead class="bb-xs b-line">
       <tr>
         <th class="n-mm text-left co-desc bold">姓名</th>
         <th class="n-mm text-left co-desc bold">邮箱</th>
@@ -1339,7 +1600,7 @@ user-select-text
       <tr
         v-for="user in users"
         :key="user.id"
-        class="bb-xs bk-line"
+        class="bb-xs b-line"
       >
         <td class="n-mm co-text">{{ user.name }}</td>
         <td class="n-mm co-desc">{{ user.email }}</td>
@@ -1366,15 +1627,24 @@ user-select-text
 
 ```scss
 // 在 SCSS 中配置
-@use '@neatui/css' with (
-  $theme: (
-    'light': (
-      main: #00b277,    // 自定义主色
-      vice: #67ce82,
-      // ... 其他颜色
-    )
-  )
+@use '@neatui/css' as neatui;
+
+$theme: (
+  light: (
+    main: #00b277,
+    text: #000000,
+    fore: #ffffff,
+    back: #f5f5f5,
+    link: #d07950,
+    code: #e23861,
+    well: #4bbc73,
+    warn: #fb9a2a,
+    risk: #f95850,
+    brand: #673ab7, // 扩展色名称可以自定义
+  ),
 );
+
+@include neatui.theme($theme);
 ```
 
 ### 2. 使用 SCSS Mixin
@@ -1408,7 +1678,7 @@ user-select-text
 <button class="bg-main bg-main-b-sm:active">按钮</button>
 
 <!-- Focus -->
-<input class="bk-line bk-main:focus" />
+<input class="b-line b-main:focus" />
 
 <!-- Disabled -->
 <button class="bg-weak:disabled" disabled>禁用</button>
@@ -1438,25 +1708,24 @@ const descClass = 'co-desc fs-sm my-ss'
 
 ### NeatUI 核心价值
 
-1. **设计系统原子化**：第一个把完整设计规范原子化的框架
-2. **极低学习成本**：3 个规则，20 分钟精通
-3. **强制一致性**：技术约束 > 人工自律
-4. **深色模式零成本**：自动推导 100+ 语义色
-5. **空间直觉布局**：废除 flexbox 概念
-6. **9 档精细响应**：3×3 分形断点系统
+1. **意图压缩**：用较少、稳定的 token 表达尺寸、位置、颜色和交互意图
+2. **有限与开放并存**：布局、档位和派生规则有限，主题名与项目色卡保持开放
+3. **相对尺寸体系**：常规界面使用统一档位，随根字号和上下文自然缩放
+4. **主题派生**：从基础种子与项目扩展色生成语义变量和派生档位
+5. **坐标布局**：`ui-flex` 用空间坐标描述布局，再编译为兼容 CSS
+6. **可控响应式**：用命名范围和固定覆盖顺序保持多端行为一致
 
 ### 适用场景
 
-✅ **强烈推荐**：
-- 企业级应用（长期维护）
+**更适合**：
+- 规则明确、需要长期维护的产品界面
 - 设计系统严格的项目
 - 小团队深度定制
-- 追求代码质量
+- 多页面或多人协作、需要保持统一表达的项目
 
-❌ **不推荐**：
-- 开源项目（生态缺失）
-- 需要像素级还原第三方设计
-- 高度依赖 AI 编码
+**需要额外评估**：
+- 高度依赖第三方插件或既有社区类名约定的项目
+- 需要逐像素还原外部设计、且不接受项目级自定义样式的页面
 
 ### 快速回顾
 
@@ -1465,7 +1734,7 @@ const descClass = 'co-desc fs-sm my-ss'
 n-mm m-ss w-ll h-full r-sm fs-lm
 
 <!-- 颜色系统 -->
-co-main bg-fore bk-line
+co-main bg-fore b-line
 co-desc co-risk bg-well
 
 <!-- 布局系统 -->
@@ -1473,7 +1742,7 @@ ui-flex="row xm"
 ui-grid="mob:1 pad:3 dpc:5 ml"
 
 <!-- 响应式 -->
-mob:fs-sm pad:fs-mm dpc:fs-lm
+fs-lm pad:fs-mm mob:fs-sm
 ui-hide="<pad"
 
 <!-- 按钮系统 -->
@@ -1486,12 +1755,13 @@ ui-btn="@a main l :round"
 
 - **官网**: http://neatui.fekit.cn
 - **NPM**: https://www.npmjs.com/package/@neatui/css
-- **当前版本**: v3.15.0
+- **当前版本**: v4.0.0
 - **作者**: xiaojunbo
 - **许可**: MIT
 
 ---
 
-*本文档基于项目实战整理，覆盖 NeatUI 100% 的 API 和用法*
+*本文档是人工维护的使用说明；实际能力以 `@neatui/css` SCSS 源码和构建输出为准，
+大版本语义变化以 `MIGRATION-4.0.md` 为准。*
 
-*最后更新: 2025-11-29*
+*最后更新: 2026-07-28*