@neatui/css 5.4.0 → 5.5.1

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @neatui/css 更新记录
 
+## 5.5.1
+
+- `GUIDE.md` 开头新增「规则速查」：全部可用写法与禁止清单，按编译结果核对；修正手册中不存在的写法（`text-*`、`shadow-*`、`overflow-*`、`cursor-*`、`w-screen` 等）与错误数值（`z-*`、`w-*l`），按钮必须带 `@a` / `@b` 主题标记。
+- `README.md` 新增 AI 使用指引。
+- token schema 新增 `ui-wrap`，`yarn validate` 与 VS Code 插件（0.2.1）可校验、补全；移除换行类补全。
+
+## 5.5.0
+
+### 不兼容变更：换行只用 `ui-wrap`
+
+- 移除 `.wrap`、`.nowrap` 及 `pad:`、`mob:` 换行类。
+- `ui-wrap` 新增 `no`（不换行）。迁移：`nowrap` → `ui-wrap="no"`，`wrap` → `ui-wrap="all"`，`mob:wrap` → `ui-wrap="=mob"`，`pad:wrap` → `ui-wrap="<dpc"`。
+
 ## 5.2.1
 
 - `ui-icon="close"`：图案放大到 80%，线条更细；`steps` 内部使用的 `%icon-close` 不变。

package/GUIDE.md

@@ -1,15 +1,89 @@
 # NeatUI 完整使用手册
 
-> **版本**: @neatui/css v4.0.0
+> **版本**: @neatui/css v5.x
 >
-> **更新日期**: 2026-07-28
+> **更新日期**: 2026-11-02
 >
 > **定位**: 这不是又一个 CSS 工具库，而是一套完整的设计系统 + 原子化实现
+>
+> **AI / 新读者**：先读下方「规则速查」，按它写代码；需要细节时再查后面对应章节。
+
+---
+
+## 规则速查
+
+本节是确定性规则，人和 AI 都应以此为准。只使用下面列出的写法；**不在这里、也不在后续章节中的 class 或属性值，视为不存在**，不要按其他框架的习惯臆造（如 `text-center`、`shadow-md`、`overflow-hidden`、`cursor-pointer`）。
+
+### 1. 档位
+
+| 名称 | 取值 |
+| --- | --- |
+| 尺寸档 `{size}` | `no xs ss sm sl ms mm ml ls lm ll xl`（12 档，由小到大） |
+| 宽高 / 圆角 / 字号分段 | 在档位后加 `*s` / `*m` / `*l`，如 `w-xl*s`、`fs-mm*s`、`r-sm*m`（`no`、`full` 无分段） |
+| 层级 / 透明度档 | `no xs ss sm sl ms mm ml ls lm ll xl xx`（13 档） |
+| 断点 | `mob` <800px，`pad` 800–1279px，`dpc` ≥1280px；细分 `mob-s/m/l`、`pad-s/m/l`、`dpc-s/m/l`，分界 480 / 640 / 800 / 960 / 1120 / 1280 / 1440 / 1600px |
+
+### 2. 原子 class
+
+| 用途 | 写法 |
+| --- | --- |
+| 内边距 | `n-` `nx-` `ny-` `nt-` `nr-` `nb-` `nl-` + `{size}`；加 `-sub` 作用于直接子元素，`-sun` 作用于孙级 |
+| 外边距 | `m-` `mx-` `my-` `mt-` `mr-` `mb-` `ml-` + `{size}`，同样支持 `-sub` / `-sun`；负值 `-m-sm`、`-mt-sm`（无 `-sub`） |
+| 间隙 | `gap-{size}`（Flex 与 Grid 共用） |
+| 宽高 | `w-` `h-` `min-w-` `max-w-` `min-h-` `max-h-` + `{size}` / 分段；`w-full` `h-full` `full` `w-auto` `h-auto` |
+| 圆角 | `r-{size}`、`r-full`；方向 `r-t-` `r-b-` `r-lt-` `r-rt-` `r-lb-` `r-rb-` |
+| 字号 | `fs-{size}` / 分段；语义 `fs-case` `fs-note` `fs-desc` `fs-body` `fs-lead`；`fs-root` `fs++` `fs--` |
+| 字重 | `bold`、`fw1`…`fw9`（=100…900）、`fw0`（normal） |
+| 行高 | `lh-{size}`（无 `lh-sl`） |
+| 文字对齐 | `al` `ac` `ar` `aj`（左 / 中 / 右 / 两端）；`-sub` 作用于子元素 |
+| 垂直对齐 | `vt` `vm` `vb` |
+| 大小写 | `upper` `lower` |
+| 显示 | `block` `inline` `inline-block`（`dib`） `flex` `inline-flex` `none`（隐藏）；`hide` 只设 `opacity:0` 保留占位；均有 `-sub` |
+| 定位 | `pr` `pa` `pf` `ps`；偏移 `ot-` `or-` `ob-` `ol-` + `{size}` |
+| 层级 | `z-{层级档}`（`z-no`=0 … `z-xx`=12） |
+| 透明度 | `o-{层级档}`（`o-no`=0 … `o-mm`=.5 … `o-xx`=1） |
+| 滚动 | `scroll` `scroll-x` `scroll-y`，或属性 `ui-scroll` |
+| Flex 子项 | `flex-block`（flex:1 且裁切） `flex-fill`（flex:1 不裁切） `flex-grow` `flex-shrink` `flex-fixed` |
+| 边框 | 宽度 `b-` `bt-` `br-` `bb-` `bl-` `bx-` `by-` + `{size}`；样式 `b-solid` `b-dashed` `b-double` `b-dotted` `b-no` |
+| 颜色 | `co-` 文字、`bg-` 背景、`b-` 边框 + 颜色名；派生 `-o-` / `-w-` / `-b-` + `xxs…xxl`，如 `bg-main-o-sm` |
+| 颜色名 | 种子 `main text fore back link code well warn risk`；自动 `read desc note case line weak deep none`；绝对色 `w`（白） `b`（黑）；项目可扩展 |
+| 状态 | 只有 `:hover` 与 `:active` 后缀，如 `co-main:hover`、`bg-main-b-sm:active`（颜色、`z-`、`o-`）；**没有** `:focus` / `:disabled` |
+| 交互 | `ux-hover` `ux-shadow` `ux-click` `ux-scale` `ux-disable` `ux-none`；`ev-none` / `ev-auto`（pointer-events） |
+| 容器 | `doc`（正文宽度，最大 800px）；`box` `box-base` `box-norm` `box-slim` `box-wide` `box-full` |
+
+响应式：上表除颜色、状态、交互、边框样式、`z-`、`o-` 外，class 都可加 `pad:`（≤1279px）或 `mob:`（≤799px）前缀，层叠顺序 `基础 → pad: → mob:`。**没有 `dpc:` class 前缀。**
+
+### 3. 属性语法
+
+| 属性 | 语法 | 示例 |
+| --- | --- | --- |
+| `ui-flex` | `{row\|col} {x}{y}` + 可选 `wrap` `reverse` `inline` `block` `fixed`；x：`l c r x a`，y：`t m b y d`；可加 `pad:` `mob:` | `ui-flex="row xm"`、`ui-flex="col cm mob:row"` |
+| `ui-grid` | 列数 `1..12` + 九宫格对齐 + `block`；`mob:` `pad:` `dpc:` 前缀；间距用 `gap-*` class | `ui-grid="mob:1 pad:2 dpc:4" class="gap-mm"` |
+| `ui-row` / `ui-col` | `{断点}-{0..24}`，断点为 `mob pad dpc` 及细分；`ui-row` 另有 `space` `:full` `reverse` | `ui-row="space" ui-col="mob-24 dpc-8"` |
+| `ui-hide` | `>` `<` `=` + 断点或细分档，可空格组合，命中即隐藏 | `ui-hide="<pad"`、`ui-hide="=mob =dpc-l"` |
+| `ui-wrap` | `no`（不换行）、`all`（全部换行）、或同 `ui-hide` 的断点值（列出的范围换行，其余不换行） | `ui-wrap="no"`、`ui-wrap="=mob"` |
+| `ui-omit` | `1..9` 行省略 | `ui-omit="2"` |
+| `ui-cover` | 13 种比例或 `+{size}` / `-{size}`，可加 `cover` / `contain` | `ui-cover="16:9"` |
+| `ui-fit` | `cover contain fill none down` + 可选九宫格锚点 | `ui-fit="cover lt"` |
+| `ui-scroll` | `:x` `:y` `:hidden` `x:hidden` `y:hidden` `x:unset` `y:unset` `stable`，尺寸 `xs s m l xl` | `ui-scroll=":x :y"` |
+| `ui-btn` | 主题 `@a` / `@b`（必填） + 颜色名 + 尺寸 `xs s m l xl` + 修饰 `:round` `:border` `:square` `:underline`（文字按钮） `:block`（100% 宽） `:disabled` | `ui-btn="@a main s :border"` |
+
+### 4. 禁止清单
+
+- 不写任意像素或色值（`style="padding:13px"`、`color:#f00`）；用档位和语义色。确需特殊值时手写样式并注释原因。
+- 不用其他框架的类名：`text-center`→`ac`，`font-bold`→`bold`，`hidden`→`none`，没有 `overflow-*`（滚动用 `scroll` / `scroll-x` / `scroll-y` 或 `ui-scroll`），`shadow-*` / `cursor-*` / `w-screen` / `h-screen` 不存在。
+- 换行只用 `ui-wrap`；`wrap` / `nowrap` 类已移除；不要写 `ui-wrap=""`，用 `ui-wrap="no"`。`flex-wrap` / `flex-nowrap` 是 flex 换行，与文字换行无关。
+- 不写 `dpc:` class 前缀；桌面值写在无前缀的基础 class 上。
+- 组件属性必须带主题标记，否则没有样式：`ui-btn` `ui-btns` `ui-card` `ui-tag` `ui-tabs` `ui-form` `ui-img` `ui-avatar` `ui-note` `ui-list` `ui-line` `ui-steps` `ui-title` `ui-navs` 等写 `@a`（部分组件另有 `@b` `@c`…），如 `ui-tag="@a main"`。布局属性（`ui-flex` `ui-grid` `ui-row` `ui-hide` `ui-wrap` `ui-scroll` `ui-cover` `ui-fit` `ui-omit`）不需要。
+- 不手写 `@media`；用 class 前缀、`ui-hide`、`ui-wrap` 或 SCSS mixin（`neatui.mob` / `neatui.pad` / `neatui.dpc`）。
+- 有色深背景上的白字用 `co-w`，不用 `co-fore` / `co-text`。
+- `ui-hide` 只改可见性，不卸载组件；需要销毁时用 `v-if`。
 
 ---
 
 ## 目录
 
+- [规则速查](#规则速查)
 - [核心理念](#核心理念)
 - [架构概览](#架构概览)
 - [快速开始](#快速开始)
@@ -126,7 +200,7 @@ npm install @neatui/css @neatui/vue
 </div>
 
 <!-- NeatUI 方式 -->
-<div ui-flex="row cm" class="n-sm bg-fore r-sm shadow-sm">
+<div ui-flex="row cm" class="n-sm bg-fore r-sm">
   <h1 class="fs-lm bold co-text">Hello World</h1>
 </div>
 ```
@@ -596,7 +670,7 @@ y: 纵向对齐
 </nav>
 
 <!-- 垂直两端分布 + 水平居中 -->
-<div ui-flex="col yc">
+<div ui-flex="col cy">
   <header>顶部</header>
   <footer>底部</footer>
 </div>
@@ -627,7 +701,7 @@ y: 纵向对齐
 </div>
 
 <!-- NeatUI -->
-<div ui-flex="row cm" class="h-screen">
+<div ui-flex="row cm" class="h-full">  <!-- 父级需有确定高度 -->
   <div class="bg-fore n-ml">内容</div>
 </div>
 ```
@@ -643,11 +717,11 @@ y: 纵向对齐
 
 <!-- NeatUI -->
 <div ui-flex="col cm" class="n-sm">
-  <div ui-img="sz:sl :round">
+  <div ui-img="@a sz:sl :round">
     <img />
   </div>
   <h3 class="mt-ss">标题</h3>
-  <button class="mt-ms" ui-btn="main">按钮</button>
+  <button class="mt-ms" ui-btn="@a main">按钮</button>
 </div>
 ```
 
@@ -713,7 +787,7 @@ grade: gap class 的间距等级 (no, xs, ss, sm, sl, ms, mm, ml, ls, lm, ll, xl
     <img :src="product.image" />
     <h3 class="co-main fs-ml">{{ product.name }}</h3>
     <p class="co-desc">{{ product.desc }}</p>
-    <button ui-btn="main s">购买</button>
+    <button ui-btn="@a main s">购买</button>
   </li>
 </ul>
 ```
@@ -935,11 +1009,15 @@ dpc, dpc-s, dpc-m, dpc-l
 
 ### 按断点换行 `ui-wrap`
 
-元素带上 `ui-wrap` 即默认不换行，只在列出的范围内换行。取值与 `ui-hide` 相同（`>`、`<`、`=` + 九档细分值或设备段别名），可用空格组合；另有 `all` 表示全部换行，空值表示全部不换行。
+换行只用 `ui-wrap`（`wrap`、`nowrap` 及 `pad:`、`mob:` 换行类已移除）。三类取值：
+
+- `no`：不换行（`no` + `wrap`，对应 CSS `nowrap`）。
+- `all`：全部换行。
+- 断点值：与 `ui-hide` 相同（`>`、`<`、`=` + 九档细分值或设备段别名），可用空格组合，列出的范围换行、其余不换行。
 
 | 换行的端 | 写法 |
 | --- | --- |
-| 都不换行 | `ui-wrap=""` |
+| 都不换行 | `ui-wrap="no"` |
 | 仅移动 | `ui-wrap="=mob"` |
 | 仅平板 | `ui-wrap="=pad"` |
 | 仅桌面 | `ui-wrap="=dpc"` |
@@ -953,7 +1031,7 @@ dpc, dpc-s, dpc-m, dpc-l
 <div ui-wrap="=pad-m">...</div>
 ```
 
-写了 `ui-wrap` 时由它全权决定：规则位于 `wrap`、`nowrap` 及 `pad:`、`mob:` 前缀类之后，同优先级下会覆盖它们，不要混用。
+迁移：`nowrap` → `ui-wrap="no"`，`wrap` → `ui-wrap="all"`，`mob:wrap` → `ui-wrap="=mob"`，`pad:wrap` → `ui-wrap="<dpc"`。
 `all` 不带媒体查询，比 `=mob =pad =dpc` 更可靠（后者在断点间的小数宽度，如 799.5px，不会命中）。
 
 ### 响应式 class 前缀
@@ -1041,7 +1119,7 @@ function toggleElderlyMode() {
   </ul>
 
   <!-- 移动端汉堡按钮 -->
-  <button ui-hide=">mob" ui-btn="none s">
+  <button ui-hide=">mob" ui-btn="@a none s">
     <i class="icon-menu"></i>
   </button>
 </nav>
@@ -1054,95 +1132,97 @@ function toggleElderlyMode() {
 ### ui-btn 语法
 
 ```html
-ui-btn="[@{flag}] {color} {size} [:{modifier}]"
+ui-btn="@{theme} [{color}] [{size}] [:{modifier}...]"
 
-@{flag}:
-  @a  = 块级按钮 (width: 100%)
-  @i  = 内联按钮 (inline-flex)
+@{theme}（必填）:
+  @a, @b      // 按钮主题风格；不写则没有按钮样式
 
 {color}:
-  main, vice, well, warn, risk, info, none
+  main vice well warn risk info none text read desc note case line weak back w b link
 
 {size}:
-  s, m (默认), l
+  xs s m(默认) l xl
 
 :{modifier}:
-  :round   = 圆形按钮
-  :border  = 边框按钮
-  :text    = 文本按钮
+  :round      // 胶囊圆角
+  :square     // 正方形（图标按钮）
+  :border     // 线框
+  :underline  // 文字按钮（透明底，悬停下划线）
+  :block      // 宽度 100%
+  :disabled   // 视觉禁用
 ```
 
 ### 基础按钮
 
 ```html
 <!-- 主色按钮 -->
-<button ui-btn="main">主操作</button>
+<button ui-btn="@a main">主操作</button>
 
 <!-- 辅助色按钮 -->
-<button ui-btn="vice">次要操作</button>
+<button ui-btn="@a vice">次要操作</button>
 
 <!-- 成功按钮 -->
-<button ui-btn="well">提交</button>
+<button ui-btn="@a well">提交</button>
 
 <!-- 警告按钮 -->
-<button ui-btn="warn">警告</button>
+<button ui-btn="@a warn">警告</button>
 
 <!-- 危险按钮 -->
-<button ui-btn="risk">删除</button>
+<button ui-btn="@a risk">删除</button>
 
 <!-- 信息按钮 -->
-<button ui-btn="info">详情</button>
+<button ui-btn="@a info">详情</button>
 
 <!-- 无样式按钮 -->
-<button ui-btn="none">纯文本</button>
+<button ui-btn="@a none">纯文本</button>
 ```
 
 ### 尺寸变体
 
 ```html
-<button ui-btn="main s">小按钮</button>
-<button ui-btn="main m">中按钮</button>
-<button ui-btn="main l">大按钮</button>
+<button ui-btn="@a main s">小按钮</button>
+<button ui-btn="@a main m">中按钮</button>
+<button ui-btn="@a main l">大按钮</button>
 ```
 
 ### 块级按钮
 
 ```html
 <!-- 100% 宽度 -->
-<button ui-btn="@a main">登录</button>
+<button ui-btn="@a main :block">登录</button>
 ```
 
 ### 样式修饰符
 
 ```html
-<!-- 圆形按钮 -->
-<button ui-btn="main :round">
+<!-- 胶囊按钮 -->
+<button ui-btn="@a main :round">
   <i class="icon-check"></i>
 </button>
 
 <!-- 边框按钮 -->
-<button ui-btn="main :border">边框样式</button>
+<button ui-btn="@a main :border">边框样式</button>
 
 <!-- 文本按钮 -->
-<button ui-btn="main :text">文本链接</button>
+<button ui-btn="@a main :underline">文本链接</button>
 ```
 
 ### 组合使用
 
 ```html
-<!-- 块级 + 大尺寸 + 圆形 -->
-<button ui-btn="@a main l :round">提交订单</button>
+<!-- 块级 + 大尺寸 + 胶囊 -->
+<button ui-btn="@a main l :round :block">提交订单</button>
 
 <!-- 小尺寸 + 边框 -->
-<button ui-btn="vice s :border">取消</button>
+<button ui-btn="@a vice s :border">取消</button>
 ```
 
 ### 按钮组
 
 ```html
 <div ui-flex="row lm">
-  <button ui-btn="main">确定</button>
-  <button ui-btn="none :border" class="ml-sm">取消</button>
+  <button ui-btn="@a main">确定</button>
+  <button ui-btn="@a none :border" class="ml-sm">取消</button>
 </div>
 ```
 
@@ -1247,13 +1327,12 @@ w-ss ~ w-xl // 1em ~ 5.5em
 
 // 分段扩展
 w-ll*s     // 15em
-w-ll*m     // 36em
-w-ll*l     // 78em
+w-ll*m     // 27em
+w-ll*l     // 66em
 
 // 特殊值
 w-full     // 100%
 w-auto     // auto
-w-screen   // 100vw
 ```
 
 #### Height
@@ -1262,7 +1341,6 @@ w-screen   // 100vw
 h-{size}   // 同 width
 h-full     // 100%
 h-auto     // auto
-h-screen   // 100vh
 ```
 
 ### 圆角类 (Border Radius)
@@ -1302,23 +1380,24 @@ fs-xs*m ~ fs-xl*m // 5rem ~ 10rem
 fs-xs*l ~ fs-xl*l // 11rem ~ 21rem
 
 // 字重
-thin       // font-weight: 100
-light      // 300
-normal     // 400
-bold       // 700
-bolder     // 900
-
-// 对齐
-text-left
-text-center
-text-right
-text-justify
+bold       // font-weight: bold
+fw1 ~ fw9  // font-weight: 100 ~ 900
+fw0        // font-weight: normal
+
+// 文字对齐（-sub 作用于直接子元素）
+al         // 左
+ac         // 中
+ar         // 右
+aj         // 两端
+
+// 垂直对齐
+vt vm vb
 
 // 行高
-lh-xs ~ lh-xl  // line-height
+lh-no ~ lh-xl  // line-height（lh-xs = 1 … lh-xl = 3.5；无 lh-sl）
 
-// 字母间距
-ls-xs ~ ls-xl  // letter-spacing
+// 大小写
+upper lower
 ```
 
 ### 边框类 (Border)
@@ -1365,68 +1444,50 @@ ol-xs ~ ol-xl  // left
 ### Z轴类 (Z-Index)
 
 ```scss
-z-xs       // z-index: 10
-z-ss       // 20
-z-sm       // 30
-z-mm       // 50
-z-ml       // 70
-z-ll       // 90
-z-xl       // 100
+z-no       // z-index: 0
+z-xs       // 1
+z-ss ~ z-xl // 2 ~ 11
+z-xx       // 12
+z-mm:hover // hover 时生效
 ```
 
-### 阴影类 (Shadow)
+### 阴影
 
-```scss
-shadow-xs  // 浅阴影
-shadow-sm
-shadow-mm  // 默认阴影
-shadow-ml
-shadow-ll  // 深阴影
-shadow-none // 无阴影
-```
+NeatUI 不提供通用阴影 class（没有 `shadow-*`）。需要阴影时由组件自身样式或项目样式提供。
 
 ### 显示类 (Display)
 
 ```scss
-block      // display: block
-inline     // display: inline
-inline-block
-flex       // display: flex (推荐用 ui-flex)
-grid       // display: grid (推荐用 ui-grid)
-hidden     // display: none
+block         // display: block
+inline        // display: inline
+inline-block  // 同 dib
+flex          // display: flex（布局推荐用 ui-flex）
+inline-flex
+none          // display: none
+hide          // opacity: 0（保留占位）
+// 以上均有 -sub，作用于直接子元素
 
 // Flex 子项
-flex-block // flex: 1
-flex-fill // flex: 1，不裁切（overflow 不变，min-width: 0）
-flex-auto  // flex: auto
-flex-none  // flex: none
+flex-block    // flex: 1，overflow: hidden
+flex-fill     // flex: 1，min-width: 0，不裁切
+flex-grow     // 只放大不缩小
+flex-shrink   // 只缩小不放大
+flex-fixed    // 不放大不缩小
 ```
 
 ### 溢出类 (Overflow)
 
 ```scss
-overflow-auto
-overflow-hidden
-overflow-scroll
-overflow-x-auto
-overflow-y-auto
-overflow-x-hidden
-overflow-y-hidden
+scroll     // overflow: auto
+scroll-x   // overflow-x: auto
+scroll-y   // overflow-y: auto
 ```
 
-滚动系统同时保留 `.ui-scroll` 等 class 写法；`ui-scroll` attribute 提供
-`stable`、五档 scrollbar 尺寸以及 x/y auto、hidden、unset。800px 以上的尺寸覆盖
-只作用于 attribute 形式。
+没有 `overflow-*` class。更多滚动控制用 `ui-scroll` 属性：`:x` `:y` `:hidden` `x:hidden` `y:hidden` `x:unset` `y:unset` `stable`，滚动条尺寸 `xs s m l xl`。800px 以上的尺寸覆盖只作用于属性形式。
 
-### 光标类 (Cursor)
+### 光标
 
-```scss
-cursor-pointer
-cursor-default
-cursor-not-allowed
-cursor-text
-cursor-move
-```
+没有 `cursor-*` class。需要 pointer 光标时用交互类：`ux-click` / `ux-none`（见下方交互类）。
 
 ### 交互类 (Interaction)
 
@@ -1516,7 +1577,7 @@ cursor-move
 ```vue
 <!-- 封装常用卡片 -->
 <template>
-  <div class="card bg-fore n-mm r-sm shadow-sm">
+  <div class="card bg-fore n-mm r-sm">
     <slot />
   </div>
 </template>
@@ -1547,9 +1608,9 @@ cursor-move
 ### 场景 1: 登录页面
 
 ```html
-<div ui-flex="row cm" class="h-screen bg-weak">
-  <div class="w-ll*s bg-fore n-ll r-ml shadow-ml">
-    <h1 class="fs-xl bold co-main text-center">登录</h1>
+<div ui-flex="row cm" class="h-full bg-weak">  <!-- 父级需有确定高度 -->
+  <div class="w-ll*s bg-fore n-ll r-ml">
+    <h1 class="fs-xl bold co-main ac">登录</h1>
 
     <form class="mt-lm">
       <div class="mb-mm">
@@ -1568,7 +1629,7 @@ cursor-move
         />
       </div>
 
-      <button ui-btn="@a main l" class="mt-ml">
+      <button ui-btn="@a main l :block" class="mt-ml">
         登录
       </button>
     </form>
@@ -1586,7 +1647,7 @@ cursor-move
     <li
       v-for="product in products"
       :key="product.id"
-      class="bg-fore r-sm shadow-sm"
+      class="bg-fore r-sm"
     >
       <img :src="product.image" class="w-full h-auto" />
 
@@ -1596,7 +1657,7 @@ cursor-move
 
         <div ui-flex="row xm" class="mt-mm">
           <span class="co-risk bold fs-ml">¥{{ product.price }}</span>
-          <button ui-btn="main s">购买</button>
+          <button ui-btn="@a main s">购买</button>
         </div>
       </div>
     </li>
@@ -1607,7 +1668,7 @@ cursor-move
 ### 场景 3: 导航栏
 
 ```html
-<nav class="pf ot-no w-full bg-fore shadow-sm z-xl">
+<nav class="pf ot-no w-full bg-fore z-xl">
   <div class="doc" ui-flex="row xm" class="ny-sm">
     <!-- Logo -->
     <div ui-flex="row lm">
@@ -1630,12 +1691,12 @@ cursor-move
 
     <!-- 操作按钮 -->
     <div ui-flex="row lm">
-      <button ui-btn="vice s :border" class="mr-sm">登录</button>
-      <button ui-btn="main s">注册</button>
+      <button ui-btn="@a vice s :border" class="mr-sm">登录</button>
+      <button ui-btn="@a main s">注册</button>
     </div>
 
     <!-- 移动端汉堡菜单 -->
-    <button ui-hide=">mob" ui-btn="none" @click="toggleMenu">
+    <button ui-hide=">mob" ui-btn="@a none" @click="toggleMenu">
       <i class="icon-menu fs-ml"></i>
     </button>
   </div>
@@ -1651,11 +1712,11 @@ cursor-move
   ui-flex="row cm"
   @click.self="closeDialog"
 >
-  <div class="w-ll*s bg-fore r-ml shadow-ll">
+  <div class="w-ll*s bg-fore r-ml">
     <!-- 头部 -->
     <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">
+      <button ui-btn="@a none s" @click="closeDialog">
         <i class="icon-close"></i>
       </button>
     </div>
@@ -1667,10 +1728,10 @@ cursor-move
 
     <!-- 底部 -->
     <div class="n-mm bt-xs b-line" ui-flex="row rm">
-      <button ui-btn="none :border" class="mr-sm" @click="closeDialog">
+      <button ui-btn="@a none :border" class="mr-sm" @click="closeDialog">
         取消
       </button>
-      <button ui-btn="main" @click="confirm">
+      <button ui-btn="@a main" @click="confirm">
         确定
       </button>
     </div>
@@ -1681,14 +1742,14 @@ cursor-move
 ### 场景 5: 数据表格
 
 ```html
-<div class="bg-fore r-sm shadow-sm">
+<div class="bg-fore r-sm">
   <table class="w-full">
     <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>
-        <th class="n-mm text-left co-desc bold">状态</th>
-        <th class="n-mm text-right co-desc bold">操作</th>
+        <th class="n-mm al co-desc bold">姓名</th>
+        <th class="n-mm al co-desc bold">邮箱</th>
+        <th class="n-mm al co-desc bold">状态</th>
+        <th class="n-mm ar co-desc bold">操作</th>
       </tr>
     </thead>
     <tbody>
@@ -1704,9 +1765,9 @@ cursor-move
             活跃
           </span>
         </td>
-        <td class="n-mm text-right">
-          <button ui-btn="info s :text">编辑</button>
-          <button ui-btn="risk s :text">删除</button>
+        <td class="n-mm ar">
+          <button ui-btn="@a info s :underline">编辑</button>
+          <button ui-btn="@a risk s :underline">删除</button>
         </td>
       </tr>
     </tbody>
@@ -1772,11 +1833,7 @@ $theme: (
 <!-- Active -->
 <button class="bg-main bg-main-b-sm:active">按钮</button>
 
-<!-- Focus -->
-<input class="b-line b-main:focus" />
-
-<!-- Disabled -->
-<button class="bg-weak:disabled" disabled>禁用</button>
+<!-- 只有 :hover 与 :active 两种状态后缀；没有 :focus / :disabled -->
 ```
 
 ### 4. 组合类名简化
@@ -1784,7 +1841,7 @@ $theme: (
 ```vue
 <script setup>
 // 创建常用组合
-const cardClass = 'bg-fore n-mm r-sm shadow-sm'
+const cardClass = 'bg-fore n-mm r-sm'
 const titleClass = 'fs-lm bold co-main'
 const descClass = 'co-desc fs-sm my-ss'
 </script>
@@ -1841,7 +1898,7 @@ fs-lm pad:fs-mm mob:fs-sm
 ui-hide="<pad"
 
 <!-- 按钮系统 -->
-ui-btn="@a main l :round"
+ui-btn="@a main l :round :block"
 ```
 
 ---
@@ -1850,7 +1907,7 @@ ui-btn="@a main l :round"
 
 - **官网**: http://neatui.fekit.cn
 - **NPM**: https://www.npmjs.com/package/@neatui/css
-- **当前版本**: v4.0.0
+- **当前版本**: v5.x
 - **作者**: xiaojunbo
 - **许可**: MIT
 
@@ -1859,4 +1916,4 @@ ui-btn="@a main l :round"
 *本文档是人工维护的使用说明；实际能力以 `@neatui/css` SCSS 源码和构建输出为准，
 大版本语义变化以 `MIGRATION-4.0.md` 为准。*
 
-*最后更新: 2026-07-28*
+*最后更新: 2026-11-02*

package/README.md

@@ -4,6 +4,16 @@
 
 NeatUI 约束型原子设计系统（SCSS）。正式项目用 SCSS 自定义 `$theme`；试用可用预编译 preview（默认 light / dark）。
 
+## 使用手册（AI 必读）
+
+编写 NeatUI 代码前，请先阅读包内 [`GUIDE.md`](./GUIDE.md) 开头的「规则速查」：它列出全部可用写法和禁止清单，未列出的 class / 属性值视为不存在。
+
+让项目里的 AI 自动遵守这些规则：在你项目的 `AGENTS.md`（或 `CLAUDE.md`）中加一行：
+
+```md
+- 使用 NeatUI 样式前先读 `node_modules/@neatui/css/GUIDE.md` 的「规则速查」，只使用其中列出的写法。
+```
+
 ## 更新与升级
 
 升级前请查看 [更新记录与迁移说明](./CHANGELOG.md)。