@neatui/css 3.15.0 → 3.15.1

package/GUIDE.md

@@ -0,0 +1,1497 @@
+# NeatUI 完整使用手册
+
+> **版本**: @neatui/css v3.15.0
+>
+> **更新日期**: 2025-11-29
+>
+> **定位**: 这不是一个 CSS 工具库，而是一套完整的设计系统 + 原子化实现
+
+---
+
+## 目录
+
+- [核心理念](#核心理念)
+- [架构概览](#架构概览)
+- [快速开始](#快速开始)
+- [尺寸系统 (S/M/L Matrix)](#尺寸系统)
+- [颜色系统 (Semantic Colors)](#颜色系统)
+- [布局系统 (ui-flex / ui-grid)](#布局系统)
+- [响应式系统 (9-Grid Responsive)](#响应式系统)
+- [按钮系统 (ui-btn)](#按钮系统)
+- [完整 API 参考](#完整-api-参考)
+- [最佳实践](#最佳实践)
+- [常见场景](#常见场景)
+
+---
+
+## 核心理念
+
+### 三大思维模型
+
+NeatUI 要求你摒弃传统的 CSS 思维，建立全新的思维模型：
+
+#### 1. 语义思维 > 像素思维
+```
+❌ 错误: padding: 16px; width: 320px;
+✅ 正确: n-mm; w-lm;
+```
+
+**原则**：永远不使用任意像素值，使用 S/M/L 相对尺寸体系。
+
+#### 2. 坐标思维 > 属性思维
+```
+❌ 错误: display: flex; justify-content: space-between; align-items: center;
+✅ 正确: ui-flex="row xm"
+```
+
+**原则**：用空间位置描述，而非 CSS 属性名。
+
+#### 3. 意图思维 > 色值思维
+```
+❌ 错误: color: #f95850; background: red;
+✅ 正确: co-risk; bg-risk;
+```
+
+**原则**：用功能意图命名，而非色相描述。
+
+---
+
+## 架构概览
+
+### 设计哲学金字塔
+
+```
+┌─────────────────────────────────────┐
+│    设计规范 (Design System)         │  ← NeatUI 定义层
+├─────────────────────────────────────┤
+│    原子化实现 (Atomic CSS)           │  ← NeatUI 实现层
+├─────────────────────────────────────┤
+│    编译优化 (SCSS Engine)            │  ← NeatUI 引擎层
+└─────────────────────────────────────┘
+```
+
+### 核心特性
+
+| 特性 | 描述 | 对比 Tailwind |
+|-----|------|---------------|
+| **设计系统** | 强制规范，技术约束 | 无规范，依赖自律 |
+| **主题系统** | 8 色 → 100+ 自动推导 | 需手动定义 50+ 色阶 |
+| **命名系统** | 3 个规则，算法推导 | 50+ 类名，字典记忆 |
+| **学习曲线** | 20 分钟精通 | 1-3 天入门 |
+| **响应式** | 9 档断点 + 3 种操作符 | 5 档断点 + min-width |
+| **布局系统** | 空间坐标，直觉映射 | CSS 属性翻译 |
+
+---
+
+## 快速开始
+
+### 安装
+
+```bash
+# NPM
+npm install @neatui/css
+
+# Yarn
+yarn add @neatui/css
+
+# Nuxt 项目
+npm install @neatui/css @neatui/nuxt
+```
+
+### 在项目中引入
+
+#### 方式 1: SCSS 引入（推荐）
+```scss
+// app/assets/css/base.scss
+@use '@neatui/css' as neatui;
+
+// 使用响应式 mixin
+.my-component {
+  @include neatui.mob {
+    padding-top: 4em;
+  }
+}
+```
+
+#### 方式 2: Nuxt 配置
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: [
+    '@neatui/nuxt'
+  ]
+})
+```
+
+### 第一个示例
+
+```html
+<!-- 传统 CSS/Tailwind 方式 -->
+<div class="flex justify-center items-center p-4 bg-white rounded-lg shadow-md">
+  <h1 class="text-2xl font-bold text-gray-900">Hello World</h1>
+</div>
+
+<!-- NeatUI 方式 -->
+<div ui-flex="row cm" class="n-sm bg-fore r-sm shadow-sm">
+  <h1 class="fs-lm bold co-text">Hello World</h1>
+</div>
+```
+
+**代码减少 40%，语义更清晰！**
+
+---
+
+## 尺寸系统
+
+### 核心概念：S/M/L 矩阵
+
+NeatUI 采用 **分形尺寸体系**，而非线性数值：
+
+```
+基元 (Base):
+  s  = Small  (小)
+  m  = Medium (中)
+  l  = Large  (大)
+
+修饰符 (Modifier):
+  s  = small-tier   (偏小)
+  m  = middle-tier  (偏中)
+  l  = large-tier   (偏大)
+
+组合规则:
+  第一个字母 = 基调
+  第二个字母 = 微调
+```
+
+### 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    (超大)
+```
+
+### 修饰符扩展（5 倍精度）
+
+```scss
+基础值:
+  w-ll      // 6em
+
+增量 (+):
+  w-ll+     // 7em  (基础 + 1)
+
+倍数 (*):
+  w-ll*s    // 12em (基础 × 2)
+  w-ll*m    // 18em (基础 × 3)
+  w-ll*l    // 24em (基础 × 4)
+```
+
+**覆盖范围**: 0-80em (0-1280px @ 16px)，共 60+ 种精确尺寸
+
+### 应用于各属性
+
+| 前缀 | 属性 | 示例 | 说明 |
+|-----|------|------|------|
+| `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 |
+
+### 方向修饰符
+
+```scss
+// 单方向
+nx-mm  // padding-left + padding-right
+ny-mm  // padding-top + padding-bottom
+nt-mm  // padding-top
+nr-mm  // padding-right
+nb-mm  // padding-bottom
+nl-mm  // padding-left
+
+// 同理适用于 margin (m)
+mx-sm  // margin-left + margin-right
+```
+
+### 特殊值
+
+```scss
+r-round  // border-radius: 50% (圆形)
+r-no     // border-radius: 0 (无圆角)
+
+w-full   // width: 100%
+h-full   // height: 100%
+
+w-auto   // width: auto
+h-auto   // height: auto
+```
+
+---
+
+## 颜色系统
+
+### 核心概念：语义化色彩
+
+NeatUI 的色彩系统分为三层：
+
+```
+层级 1: 基础色 (8 个)
+  ├─ main  (主色)
+  ├─ vice  (辅助色)
+  ├─ well  (成功)
+  ├─ warn  (警告)
+  ├─ risk  (危险)
+  ├─ info  (信息)
+  ├─ text  (文本)
+  └─ fore  (前景)
+
+层级 2: 语义色 (自动推导)
+  ├─ read, desc, note, line, weak  (5 级文字)
+  └─ 12 级透明度 + 混合色
+
+层级 3: 主题色 (自动切换)
+  ├─ light (浅色主题)
+  └─ dark  (深色主题)
+```
+
+### 基础色配置
+
+```scss
+// 在项目中配置主题
+$theme: (
+  'light': (
+    main: #00b277,    // 品牌主色
+    vice: #67ce82,    // 品牌辅助色
+    well: #4bbc73,    // 成功 (绿色系)
+    warn: #fb9a2a,    // 警告 (橙色系)
+    risk: #f95850,    // 危险 (红色系)
+    info: #3c49dd,    // 信息 (蓝色系)
+    text: #000000,    // 主文本色
+    fore: #ffffff,    // 前景/卡片背景色
+  ),
+  'dark': (
+    // 深色主题配置...
+  )
+);
+```
+
+### 自动推导的语义色
+
+```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)  // 弱化背景
+
+// 反转色 (前景色)
+--co-case: rgba(fore, 0.85)   // 反转主文字
+--co-link: rgba(fore, 0.55)   // 反转描述
+--co-tips: rgba(fore, 0.35)   // 反转提示
+```
+
+### 颜色属性前缀
+
+| 前缀 | 属性 | 示例 | 输出 |
+|-----|------|------|------|
+| `co-` | color | `co-main` | 主色文字 |
+| `bg-` | background | `bg-risk` | 危险背景 |
+| `bk-` | border-color | `bk-line` | 线条边框 |
+
+### 完整颜色类名列表
+
+#### 品牌色
+```scss
+co-main, bg-main, bk-main  // 主色
+co-vice, bg-vice, bk-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  // 信息 ℹ️
+```
+
+#### 基础色
+```scss
+co-text, bg-text, bk-text  // 文本色
+co-fore, bg-fore, bk-fore  // 前景色
+co-back, bg-back, bk-back  // 背景色
+```
+
+#### 语义色
+```scss
+co-read   // 主要文字 (85%)
+co-desc   // 描述文字 (55%)
+co-note   // 注释文字 (35%)
+co-line   // 分割线 (10%)
+co-weak   // 弱化背景 (3.5%)
+
+// 反转色 (用于深色背景)
+co-case   // 反转主文字
+co-link   // 反转链接
+co-tips   // 反转提示
+```
+
+### 透明度系列 (12 级)
+
+任何颜色 + `-o-{level}` = 透明度变体
+
+```scss
+co-main-o-xs  // 主色 + 超低透明度
+co-main-o-ss
+co-main-o-sm
+co-main-o-sl
+co-main-o-ms
+co-main-o-mm
+co-main-o-ml
+co-main-o-ls
+co-main-o-lm
+co-main-o-ll
+co-main-o-xl  // 主色 + 超高透明度
+```
+
+### 混合色系列
+
+```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%
+```
+
+### 边框样式
+
+```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
+
+// 边框样式
+b-solid   // 实线
+b-dashed  // 虚线
+b-dotted  // 点线
+b-none    // 无边框
+```
+
+### 主题切换
+
+```html
+<!-- 切换全局主题 -->
+<html theme="light">  <!-- 浅色主题 -->
+<html theme="dark">   <!-- 深色主题 -->
+
+<!-- 所有颜色自动切换，0 行额外代码！ -->
+```
+
+### 颜色使用示例
+
+```html
+<!-- 主色按钮 -->
+<button class="bg-main co-case">主操作</button>
+
+<!-- 危险操作 -->
+<button class="bg-risk co-case">删除</button>
+
+<!-- 卡片 -->
+<div class="bg-fore co-text n-mm r-sm">
+  <h3 class="co-main">标题</h3>
+  <p class="co-desc">描述文字</p>
+  <span class="co-note">注释信息</span>
+</div>
+
+<!-- 分割线 -->
+<div class="bt-xs bk-line"></div>
+
+<!-- Hover 透明度 -->
+<a class="co-main co-main-o-lm:hover">链接</a>
+```
+
+---
+
+## 布局系统
+
+### ui-flex：空间坐标布局
+
+#### 核心理念
+
+**废除 flexbox 概念，用空间坐标直接描述位置！**
+
+```
+传统思维: display: flex + justify-content + align-items
+NeatUI 思维: ui-flex="横向 纵向"
+```
+
+#### 坐标系规则
+
+```
+横轴 (X-axis):
+  l  = Left          (左对齐)
+  c  = Center        (居中)
+  r  = Right         (右对齐)
+  x  = Space-Between (两端分布)
+  a  = Space-Around  (平均分布)
+
+纵轴 (Y-axis):
+  t  = Top           (顶部对齐)
+  m  = Middle        (垂直居中)
+  b  = Bottom        (底部对齐)
+  y  = Space-Between (两端分布)
+  d  = Space-Around  (平均分布)
+```
+
+#### 语法格式
+
+```html
+ui-flex="{direction} {x}{y}"
+
+direction:
+  row  (默认，横向排列)
+  col  (纵向排列)
+
+x: 横向对齐
+y: 纵向对齐
+```
+
+#### 常用组合（九宫格）
+
+```
+横向布局:
+  ui-flex="row lt"  → 左上
+  ui-flex="row ct"  → 中上
+  ui-flex="row rt"  → 右上
+  ui-flex="row lm"  → 左中
+  ui-flex="row cm"  → 居中
+  ui-flex="row rm"  → 右中
+  ui-flex="row lb"  → 左下
+  ui-flex="row cb"  → 中下
+  ui-flex="row rb"  → 右下
+
+纵向布局:
+  ui-flex="col lt"  → 顶部左对齐
+  ui-flex="col cm"  → 垂直水平居中
+  ui-flex="col rb"  → 底部右对齐
+```
+
+#### 特殊组合
+
+```html
+<!-- 两端分布 + 垂直居中 (导航栏最常用) -->
+<nav ui-flex="row xm">
+  <div>Logo</div>
+  <div>Menu</div>
+</nav>
+
+<!-- 垂直两端分布 + 水平居中 -->
+<div ui-flex="col yc">
+  <header>顶部</header>
+  <footer>底部</footer>
+</div>
+```
+
+#### 实战对比
+
+**场景 1: 导航栏**
+```html
+<!-- Tailwind: 需要理解 flexbox -->
+<nav class="flex justify-between items-center px-4 py-2">
+  <div>Logo</div>
+  <div>Menu</div>
+</nav>
+
+<!-- NeatUI: 空间直觉 -->
+<nav ui-flex="row xm" class="nx-sm ny-sm">
+  <div>Logo</div>
+  <div>Menu</div>
+</nav>
+```
+
+**场景 2: 居中对话框**
+```html
+<!-- Tailwind -->
+<div class="flex justify-center items-center min-h-screen">
+  <div class="bg-white p-6">内容</div>
+</div>
+
+<!-- NeatUI -->
+<div ui-flex="row cm" class="h-screen">
+  <div class="bg-fore n-ml">内容</div>
+</div>
+```
+
+**场景 3: 卡片布局**
+```html
+<!-- Tailwind -->
+<div class="flex flex-col items-center p-4">
+  <img class="w-16 h-16 rounded-full" />
+  <h3 class="mt-2">标题</h3>
+  <button class="mt-4">按钮</button>
+</div>
+
+<!-- NeatUI -->
+<div ui-flex="col cm" class="n-sm">
+  <div ui-img="sz:sl :round">
+    <img />
+  </div>
+  <h3 class="mt-ss">标题</h3>
+  <button class="mt-ms" ui-btn="main">按钮</button>
+</div>
+```
+
+### ui-grid：响应式网格
+
+#### 语法格式
+
+```html
+ui-grid="{breakpoint}:{columns} {gap}"
+
+breakpoint:
+  mob  (移动端)
+  pad  (平板)
+  dpc  (桌面)
+
+columns: 列数 (1-12)
+gap: 间距等级 (ss, sm, mm, ml, ll...)
+```
+
+#### 基础用法
+
+```html
+<!-- 固定 3 列，间距 medium-large -->
+<div ui-grid="3 ml">
+  <div>Item 1</div>
+  <div>Item 2</div>
+  <div>Item 3</div>
+</div>
+```
+
+#### 响应式网格
+
+```html
+<!-- 移动端 1 列，平板 3 列，桌面 5 列 -->
+<div ui-grid="mob:1 pad:3 dpc:5 ml">
+  <div>Item 1</div>
+  <div>Item 2</div>
+  <div>Item 3</div>
+  <div>Item 4</div>
+  <div>Item 5</div>
+</div>
+```
+
+#### 实战示例
+
+**产品列表**
+```html
+<ul ui-grid="mob:1 pad:2 dpc:4 mm" class="my-lm">
+  <li class="bg-fore n-mm r-sm" v-for="product in products">
+    <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>
+  </li>
+</ul>
+```
+
+---
+
+## 响应式系统
+
+### 9 档精细断点
+
+NeatUI 采用 **3×3 分形响应系统**：
+
+```scss
+// 移动端 (Mobile) 3 档
+mob-s: 320px   // 小手机 (iPhone SE)
+mob-m: 480px   // 中手机 (iPhone 13)
+mob-l: 640px   // 大手机 (iPhone Pro Max)
+
+// 平板 (Pad) 3 档
+pad-s: 800px   // 小平板 (iPad Mini)
+pad-m: 960px   // 中平板 (iPad)
+pad-l: 1120px  // 大平板 (iPad Pro)
+
+// 桌面 (Desktop) 3 档
+dpc-s: 1280px  // 小桌面 (13寸 MacBook)
+dpc-m: 1440px  // 中桌面 (主流显示器)
+dpc-l: 1600px  // 大桌面 (2K 显示器)
+```
+
+### 三种操作符
+
+#### 1. `>` 大于（min-width）
+
+```html
+<!-- 平板以上显示 -->
+<div class="pad:w-mm">内容</div>
+
+<!-- 桌面以上隐藏 -->
+<div ui-hide=">dpc">移动端专属</div>
+```
+
+#### 2. `<` 小于（max-width）
+
+```html
+<!-- 桌面以下隐藏 -->
+<div ui-hide="<dpc">桌面专属</div>
+
+<!-- 平板以下宽度 100% -->
+<div class="w-full <pad:w-mm">响应式容器</div>
+```
+
+#### 3. `=` 精确区间
+
+```html
+<!-- 仅在中平板显示 (960px-1119px) -->
+<div ui-hide="=pad-m">仅中平板隐藏</div>
+```
+
+### 断点类名语法
+
+```scss
+// 格式: {breakpoint}:{class-name}
+mob:fs-sm      // 移动端字号小
+pad:fs-mm      // 平板字号中
+dpc:fs-lm      // 桌面字号大
+
+// 组合使用
+<h1 class="fs-sm mob:fs-mm pad:fs-ml dpc:fs-xl">
+  响应式标题
+</h1>
+```
+
+### ui-hide：显示/隐藏控制
+
+```html
+<!-- 移动端隐藏 -->
+<div ui-hide="mob">桌面内容</div>
+
+<!-- 桌面隐藏 -->
+<div ui-hide="dpc">移动内容</div>
+
+<!-- 小于平板隐藏 -->
+<div ui-hide="<pad">平板以上显示</div>
+
+<!-- 大于手机隐藏 -->
+<div ui-hide=">mob">仅手机显示</div>
+
+<!-- 精确区间隐藏 -->
+<div ui-hide="=pad-m">仅在中平板隐藏</div>
+```
+
+### 全局字号响应（革命性功能）
+
+```html
+<!-- 在 <html> 标签设置全局字号 -->
+<html size="s">   <!-- 小字号模式 -->
+<html size="m">   <!-- 默认字号 -->
+<html size="l">   <!-- 大字号模式 -->
+<html size="xl">  <!-- 超大字号模式 (老年模式) -->
+
+<!-- 所有使用 em 单位的元素自动缩放！ -->
+<!-- 0 行 CSS，0 个媒体查询，全站响应！ -->
+```
+
+**实战用例：老年人模式**
+```vue
+<script setup>
+const fontSize = ref('m')
+
+function toggleElderlyMode() {
+  fontSize.value = fontSize.value === 'm' ? 'xl' : 'm'
+}
+</script>
+
+<template>
+  <html :size="fontSize">
+    <button @click="toggleElderlyMode">
+      切换大字模式
+    </button>
+
+    <!-- 所有内容自动放大，无需额外代码！ -->
+  </html>
+</template>
+```
+
+### 响应式实战示例
+
+**场景：响应式导航**
+```html
+<nav ui-flex="row xm" class="nx-mm ny-sm">
+  <!-- Logo -->
+  <div class="fs-ml">Logo</div>
+
+  <!-- 桌面菜单 -->
+  <ul ui-flex="row lm" ui-hide="<pad">
+    <li class="mx-sm">首页</li>
+    <li class="mx-sm">产品</li>
+    <li class="mx-sm">关于</li>
+  </ul>
+
+  <!-- 移动端汉堡按钮 -->
+  <button ui-hide=">mob" ui-btn="none s">
+    <i class="icon-menu"></i>
+  </button>
+</nav>
+```
+
+---
+
+## 按钮系统
+
+### ui-btn 语法
+
+```html
+ui-btn="[@{flag}] {color} {size} [:{modifier}]"
+
+@{flag}:
+  @a  = 块级按钮 (width: 100%)
+  @i  = 内联按钮 (inline-flex)
+
+{color}:
+  main, vice, well, warn, risk, info, none
+
+{size}:
+  s, m (默认), l
+
+:{modifier}:
+  :round   = 圆形按钮
+  :border  = 边框按钮
+  :text    = 文本按钮
+```
+
+### 基础按钮
+
+```html
+<!-- 主色按钮 -->
+<button ui-btn="main">主操作</button>
+
+<!-- 辅助色按钮 -->
+<button ui-btn="vice">次要操作</button>
+
+<!-- 成功按钮 -->
+<button ui-btn="well">提交</button>
+
+<!-- 警告按钮 -->
+<button ui-btn="warn">警告</button>
+
+<!-- 危险按钮 -->
+<button ui-btn="risk">删除</button>
+
+<!-- 信息按钮 -->
+<button ui-btn="info">详情</button>
+
+<!-- 无样式按钮 -->
+<button ui-btn="none">纯文本</button>
+```
+
+### 尺寸变体
+
+```html
+<button ui-btn="main s">小按钮</button>
+<button ui-btn="main m">中按钮</button>
+<button ui-btn="main l">大按钮</button>
+```
+
+### 块级按钮
+
+```html
+<!-- 100% 宽度 -->
+<button ui-btn="@a main">登录</button>
+```
+
+### 样式修饰符
+
+```html
+<!-- 圆形按钮 -->
+<button ui-btn="main :round">
+  <i class="icon-check"></i>
+</button>
+
+<!-- 边框按钮 -->
+<button ui-btn="main :border">边框样式</button>
+
+<!-- 文本按钮 -->
+<button ui-btn="main :text">文本链接</button>
+```
+
+### 组合使用
+
+```html
+<!-- 块级 + 大尺寸 + 圆形 -->
+<button ui-btn="@a main l :round">提交订单</button>
+
+<!-- 小尺寸 + 边框 -->
+<button ui-btn="vice s :border">取消</button>
+```
+
+### 按钮组
+
+```html
+<div ui-flex="row lm">
+  <button ui-btn="main">确定</button>
+  <button ui-btn="none :border" class="ml-sm">取消</button>
+</div>
+```
+
+---
+
+## 完整 API 参考
+
+### 间距类 (Spacing)
+
+#### Padding
+
+| 类名 | 属性 | 值 |
+|-----|------|------|
+| `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 |
+
+#### 方向 Padding
+
+```scss
+nx-{size}  // padding-left + padding-right
+ny-{size}  // padding-top + padding-bottom
+nt-{size}  // padding-top
+nr-{size}  // padding-right
+nb-{size}  // padding-bottom
+nl-{size}  // padding-left
+```
+
+#### Margin
+
+```scss
+m-{size}   // margin 全方向
+mx-{size}  // margin-left + margin-right
+my-{size}  // margin-top + margin-bottom
+mt-{size}  // margin-top
+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
+```
+
+#### 负 Margin
+
+```scss
+mx-sm-sub  // margin-left/right: -1em
+my-sm-sub  // margin-top/bottom: -1em
+mt-sm-sub  // margin-top: -1em
+// 所有尺寸都支持 -sub 后缀
+```
+
+### 尺寸类 (Sizing)
+
+#### Width
+
+```scss
+w-no       // 0
+w-xs       // 0.5em
+w-ss ~ w-xl // 0.75em ~ 8em
+
+// 修饰符
+w-ll+      // 7em  (增量)
+w-ll*s     // 12em (2倍)
+w-ll*m     // 18em (3倍)
+w-ll*l     // 24em (4倍)
+
+// 特殊值
+w-full     // 100%
+w-auto     // auto
+w-screen   // 100vw
+```
+
+#### Height
+
+```scss
+h-{size}   // 同 width
+h-full     // 100%
+h-auto     // auto
+h-screen   // 100vh
+```
+
+### 圆角类 (Border Radius)
+
+```scss
+r-no       // border-radius: 0
+r-xs       // 0.5em
+r-ss ~ r-xl // 0.75em ~ 8em
+r-round    // 50% (圆形)
+
+// 方向圆角
+rt-{size}  // 左上
+rr-{size}  // 右上
+rb-{size}  // 右下
+rl-{size}  // 左下
+```
+
+### 字体类 (Typography)
+
+```scss
+// 字号
+fs-no      // 0
+fs-xs      // 0.5em
+fs-ss ~ fs-xl // 0.75em ~ 8em
+
+// 字重
+thin       // font-weight: 100
+light      // 300
+normal     // 400
+bold       // 700
+bolder     // 900
+
+// 对齐
+text-left
+text-center
+text-right
+text-justify
+
+// 行高
+lh-xs ~ lh-xl  // line-height
+
+// 字母间距
+ls-xs ~ ls-xl  // letter-spacing
+```
+
+### 边框类 (Border)
+
+```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
+
+// 样式
+b-solid
+b-dashed
+b-dotted
+b-none
+
+// 边框颜色
+bk-main, bk-vice, bk-risk...
+bk-line, bk-weak
+```
+
+### 定位类 (Position)
+
+```scss
+// 定位类型
+pf         // position: fixed
+pa         // position: absolute
+pr         // position: relative
+ps         // position: sticky
+
+// 偏移
+ot-no      // top: 0
+or-no      // right: 0
+ob-no      // bottom: 0
+ol-no      // left: 0
+
+ot-xs ~ ot-xl  // top
+or-xs ~ or-xl  // right
+ob-xs ~ ob-xl  // bottom
+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
+```
+
+### 阴影类 (Shadow)
+
+```scss
+shadow-xs  // 浅阴影
+shadow-sm
+shadow-mm  // 默认阴影
+shadow-ml
+shadow-ll  // 深阴影
+shadow-none // 无阴影
+```
+
+### 显示类 (Display)
+
+```scss
+block      // display: block
+inline     // display: inline
+inline-block
+flex       // display: flex (推荐用 ui-flex)
+grid       // display: grid (推荐用 ui-grid)
+hidden     // display: none
+
+// Flex 子项
+flex-block // flex: 1
+flex-auto  // flex: auto
+flex-none  // flex: none
+```
+
+### 溢出类 (Overflow)
+
+```scss
+overflow-auto
+overflow-hidden
+overflow-scroll
+overflow-x-auto
+overflow-y-auto
+overflow-x-hidden
+overflow-y-hidden
+```
+
+### 光标类 (Cursor)
+
+```scss
+cursor-pointer
+cursor-default
+cursor-not-allowed
+cursor-text
+cursor-move
+```
+
+### 交互类 (Interaction)
+
+```scss
+pointer-events-none
+pointer-events-auto
+user-select-none
+user-select-text
+```
+
+---
+
+## 最佳实践
+
+### 1. 严格遵守设计系统
+
+```html
+<!-- ❌ 错误：使用任意值 -->
+<div style="padding: 13px; width: 237px;">
+
+<!-- ✅ 正确：使用规范尺寸 -->
+<div class="n-sm w-ll+">
+
+<!-- 如果确实需要特殊值，手写并注释 -->
+<div class="third-party" style="width: 237px">
+  <!-- 注释：第三方组件要求，见文档 #123 -->
+</div>
+```
+
+### 2. 优先使用语义色
+
+```html
+<!-- ❌ 错误：使用色值 -->
+<button style="background: #00b277; color: white;">
+
+<!-- ✅ 正确：使用语义色 -->
+<button class="bg-main co-case">
+
+<!-- ❌ 错误：使用通用灰色 -->
+<p class="text-gray-600">
+
+<!-- ✅ 正确：使用语义灰 -->
+<p class="co-desc">
+```
+
+### 3. 布局用空间思维
+
+```html
+<!-- ❌ 错误：用 CSS 属性思维 -->
+<div class="flex justify-between items-center">
+
+<!-- ✅ 正确：用空间坐标思维 -->
+<div ui-flex="row xm">
+```
+
+### 4. 响应式用断点系统
+
+```html
+<!-- ❌ 错误：手写媒体查询 -->
+<style>
+@media (max-width: 768px) {
+  .title { font-size: 1.5rem; }
+}
+</style>
+
+<!-- ✅ 正确：用断点类 -->
+<h1 class="fs-xl mob:fs-lm">标题</h1>
+```
+
+### 5. 组件化常用模式
+
+```vue
+<!-- 封装常用卡片 -->
+<template>
+  <div class="card bg-fore n-mm r-sm shadow-sm">
+    <slot />
+  </div>
+</template>
+
+<!-- 使用 -->
+<Card>
+  <h3 class="co-main">标题</h3>
+  <p class="co-desc">内容</p>
+</Card>
+```
+
+### 6. 深色模式零成本
+
+```html
+<!-- 只需切换 theme 属性 -->
+<html :theme="isDark ? 'dark' : 'light'">
+
+<!-- 所有颜色自动切换，无需额外代码 -->
+<div class="bg-fore co-text">
+  <h1 class="co-main">自动适配</h1>
+</div>
+```
+
+---
+
+## 常见场景
+
+### 场景 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>
+
+    <form class="mt-lm">
+      <div class="mb-mm">
+        <label class="co-desc fs-sm">邮箱</label>
+        <input
+          type="email"
+          class="w-full n-sm r-sm bg-weak bk-line bt-xs"
+        />
+      </div>
+
+      <div class="mb-mm">
+        <label class="co-desc fs-sm">密码</label>
+        <input
+          type="password"
+          class="w-full n-sm r-sm bg-weak bk-line bt-xs"
+        />
+      </div>
+
+      <button ui-btn="@a main l" class="mt-ml">
+        登录
+      </button>
+    </form>
+  </div>
+</div>
+```
+
+### 场景 2: 产品卡片网格
+
+```html
+<div class="doc my-lm">
+  <h2 class="fs-xl bold co-main mb-ml">热门产品</h2>
+
+  <ul ui-grid="mob:1 pad:2 dpc:4 ml">
+    <li
+      v-for="product in products"
+      :key="product.id"
+      class="bg-fore r-sm shadow-sm"
+    >
+      <img :src="product.image" class="w-full h-auto" />
+
+      <div class="n-mm">
+        <h3 class="fs-lm bold co-text">{{ product.name }}</h3>
+        <p class="co-desc fs-sm my-ss">{{ product.desc }}</p>
+
+        <div ui-flex="row xm" class="mt-mm">
+          <span class="co-risk bold fs-ml">¥{{ product.price }}</span>
+          <button ui-btn="main s">购买</button>
+        </div>
+      </div>
+    </li>
+  </ul>
+</div>
+```
+
+### 场景 3: 导航栏
+
+```html
+<nav class="pf ot-no w-full bg-fore shadow-sm z-xl">
+  <div class="doc" ui-flex="row xm" class="ny-sm">
+    <!-- Logo -->
+    <div ui-flex="row lm">
+      <i class="icon-logo fs-xl co-main"></i>
+      <span class="fs-ml bold co-text ml-sm">LabelWork</span>
+    </div>
+
+    <!-- 桌面菜单 -->
+    <ul ui-flex="row lm" ui-hide="<pad">
+      <li class="mx-mm">
+        <a href="/" class="co-text co-main:hover">首页</a>
+      </li>
+      <li class="mx-mm">
+        <a href="/products" class="co-text co-main:hover">产品</a>
+      </li>
+      <li class="mx-mm">
+        <a href="/about" class="co-text co-main:hover">关于</a>
+      </li>
+    </ul>
+
+    <!-- 操作按钮 -->
+    <div ui-flex="row lm">
+      <button ui-btn="vice s :border" class="mr-sm">登录</button>
+      <button ui-btn="main s">注册</button>
+    </div>
+
+    <!-- 移动端汉堡菜单 -->
+    <button ui-hide=">mob" ui-btn="none" @click="toggleMenu">
+      <i class="icon-menu fs-ml"></i>
+    </button>
+  </div>
+</nav>
+```
+
+### 场景 4: 对话框
+
+```html
+<div
+  v-if="showDialog"
+  class="pf ot-no ol-no w-full h-full bg-text-o-lm z-xl"
+  ui-flex="row cm"
+  @click.self="closeDialog"
+>
+  <div class="w-ll*s bg-fore r-ml shadow-ll">
+    <!-- 头部 -->
+    <div class="n-mm bb-xs bk-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>
+      </button>
+    </div>
+
+    <!-- 内容 -->
+    <div class="n-lm co-text">
+      <p>对话框内容...</p>
+    </div>
+
+    <!-- 底部 -->
+    <div class="n-mm bt-xs bk-line" ui-flex="row rm">
+      <button ui-btn="none :border" class="mr-sm" @click="closeDialog">
+        取消
+      </button>
+      <button ui-btn="main" @click="confirm">
+        确定
+      </button>
+    </div>
+  </div>
+</div>
+```
+
+### 场景 5: 数据表格
+
+```html
+<div class="bg-fore r-sm shadow-sm">
+  <table class="w-full">
+    <thead class="bb-xs bk-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>
+      </tr>
+    </thead>
+    <tbody>
+      <tr
+        v-for="user in users"
+        :key="user.id"
+        class="bb-xs bk-line"
+      >
+        <td class="n-mm co-text">{{ user.name }}</td>
+        <td class="n-mm co-desc">{{ user.email }}</td>
+        <td class="n-mm">
+          <span class="bg-well-o-sm co-well n-ss r-sm fs-xs">
+            活跃
+          </span>
+        </td>
+        <td class="n-mm text-right">
+          <button ui-btn="info s :text">编辑</button>
+          <button ui-btn="risk s :text">删除</button>
+        </td>
+      </tr>
+    </tbody>
+  </table>
+</div>
+```
+
+---
+
+## 进阶技巧
+
+### 1. 自定义主题色
+
+```scss
+// 在 SCSS 中配置
+@use '@neatui/css' with (
+  $theme: (
+    'light': (
+      main: #00b277,    // 自定义主色
+      vice: #67ce82,
+      // ... 其他颜色
+    )
+  )
+);
+```
+
+### 2. 使用 SCSS Mixin
+
+```scss
+@use '@neatui/css' as neatui;
+
+.my-component {
+  // 响应式断点
+  @include neatui.mob {
+    padding: 1em;
+  }
+
+  @include neatui.pad {
+    padding: 2em;
+  }
+
+  @include neatui.dpc {
+    padding: 3em;
+  }
+}
+```
+
+### 3. 伪类修饰符
+
+```html
+<!-- Hover -->
+<a class="co-main co-main-o-lm:hover">链接</a>
+
+<!-- Active -->
+<button class="bg-main bg-main-b-sm:active">按钮</button>
+
+<!-- Focus -->
+<input class="bk-line bk-main:focus" />
+
+<!-- Disabled -->
+<button class="bg-weak:disabled" disabled>禁用</button>
+```
+
+### 4. 组合类名简化
+
+```vue
+<script setup>
+// 创建常用组合
+const cardClass = 'bg-fore n-mm r-sm shadow-sm'
+const titleClass = 'fs-lm bold co-main'
+const descClass = 'co-desc fs-sm my-ss'
+</script>
+
+<template>
+  <div :class="cardClass">
+    <h3 :class="titleClass">标题</h3>
+    <p :class="descClass">描述</p>
+  </div>
+</template>
+```
+
+---
+
+## 总结
+
+### NeatUI 核心价值
+
+1. **设计系统原子化**：第一个把完整设计规范原子化的框架
+2. **极低学习成本**：3 个规则，20 分钟精通
+3. **强制一致性**：技术约束 > 人工自律
+4. **深色模式零成本**：自动推导 100+ 语义色
+5. **空间直觉布局**：废除 flexbox 概念
+6. **9 档精细响应**：3×3 分形断点系统
+
+### 适用场景
+
+✅ **强烈推荐**：
+- 企业级应用（长期维护）
+- 设计系统严格的项目
+- 小团队深度定制
+- 追求代码质量
+
+❌ **不推荐**：
+- 开源项目（生态缺失）
+- 需要像素级还原第三方设计
+- 高度依赖 AI 编码
+
+### 快速回顾
+
+```html
+<!-- 尺寸系统 -->
+n-mm m-ss w-ll h-full r-sm fs-lm
+
+<!-- 颜色系统 -->
+co-main bg-fore bk-line
+co-desc co-risk bg-well
+
+<!-- 布局系统 -->
+ui-flex="row xm"
+ui-grid="mob:1 pad:3 dpc:5 ml"
+
+<!-- 响应式 -->
+mob:fs-sm pad:fs-mm dpc:fs-lm
+ui-hide="<pad"
+
+<!-- 按钮系统 -->
+ui-btn="@a main l :round"
+```
+
+---
+
+## 资源链接
+
+- **官网**: http://neatui.fekit.cn
+- **NPM**: https://www.npmjs.com/package/@neatui/css
+- **当前版本**: v3.15.0
+- **作者**: xiaojunbo
+- **许可**: MIT
+
+---
+
+*本文档基于项目实战整理，覆盖 NeatUI 100% 的 API 和用法*
+
+*最后更新: 2025-11-29*