# Auland-UI
> 给 AI 取用的 React UI 库:**一个单元 = 一行引入 + 一个标签 + 它的 props**。
> 组件是最小单位,多个组件组成页面元素块;整页就是把几个元素块按顺序排起来。
> 每层都能"一行取用",结构与样式不由模型现场生成。
## 安装
已有 React 项目:
npm install auland-ui
新项目(连 peer 依赖一起):
npm install auland-ui react react-dom
样式与底座(整个项目各一次):
import 'auland-ui/style.css'
import { AulandUIProvider } from 'auland-ui'
## 三层取用方式(外加持令牌)
1. 基础组件(最小单位)——按名字直接引入:
import { AulandUIButton, AulandUISkeleton } from 'auland-ui'
保存
2. 页面元素块——登记表取用(`key` 就是路径里的名字):
import { variantOf } from 'auland-ui'
const Footer = variantOf('footer', 'basic').Comp
元素的 `key`、props、提示词都在 registry.json 里(见下)。
3. 视觉风格——只覆盖 CSS 变量,组件与元素一行不改:
…
4. 设计令牌——颜色 / 字号 / 间距 / 圆角 / 阴影都由 `--au-*` 给值,页面里不写裸色值:
import { TYPE_SCALE, SPACING_SCALE } from 'auland-ui'
// 取用页:https://auland-ui.wfsdhl.com/design/color/brand
## 硬规矩(生成代码时必须遵守)
- 颜色、字号、间距、圆角一律用 `--au-*` 令牌,不写裸色值与魔法数字。
- 组件与元素只从 Auland-UI 取用,不换成其他组件库的实现。
- 不新增依赖、不接后端接口,图片用线上地址。
- 同类结构只保留一种写法:同一区块在不同页面用同一个变体。
- 组件内建文案走文案令牌(`copy`),不要在业务代码里复制一份。
## 机器可读与工具
取用信息分两步读,**别一次拉全**:先看索引,再读你真正要用的那一条。
1. 索引(每个取用单元一行:种类 / key / 变体 / 单元名 / 路径 / 一句话说明)。
索引在 `registry.json` 的 **`index` 字段**里(298 条),每行带 `kind` / `key` / `variant` /
`path` / `desc` 与 `file`;**单条文件命名规则**是
`registry/units//__.json`(key 与 variant 之间是**两个下划线**)。
https://auland-ui.wfsdhl.com/registry.json
2. 单条(那一行的 `file` 字段就是它,里面有 import、props、规格、示例与现成提示词):
https://auland-ui.wfsdhl.com/registry/units/component/overlay__drawer.json
https://auland-ui.wfsdhl.com/registry/units/element/navbar__center.json
https://auland-ui.wfsdhl.com/registry/units/style/retroweb.json
(装了包的话,等价路径是 `node_modules/auland-ui/registry/units/…`。)
**不要**为了自省去 `import('auland-ui')`:入口会把 antd / echarts / 图标库一起拉起来,
在 Node 里可能几十秒没有输出。要查有什么块,直接读 `registry.json`(纯 JSON)。
4. **在项目里接一次**(几行就够,两个框架都一样):
- 样式引一次:`import 'auland-ui/style.css'`;
- 页面外层包一层 ``;
- 字体:把 `node_modules/auland-ui/public/fonts` 拷进项目的静态目录(Vite / Next 都是 `public/fonts`),
样式里的 `@font-face` 指向 `/fonts/`;不拷会安静地回落到系统字体;
- **Next.js App Router**:用到组件或元素块的文件顶部要加 `'use client'`(包里第一行就是它),
全局样式在根 `layout.jsx` 里引;工程里若还有上一层的 lockfile,在 `next.config.mjs` 里写
`turbopack: { root: process.cwd() }`,否则 Next 会把工作区根推断到上层;
- **不要再给块加外层容器与断点**:每个元素块根节点是 `.au-demo`,它自带内边距、
并且**自己建立容器查询**(窄容器下会按自己的宽度重排)。块与块之间不用写间距。
3. MCP 服务(让 AI 自己走这两步):`npx -y auland-ui-mcp`
- `list_blocks` 查表;`get_unit` 读单条;`get_prompt` 读单条提示词;
`get_style_vars` 取风格变量;`get_design_rules` 取整站设计规范。
- 也提供 resources:`auland:////`(例如 `auland://component/overlay/drawer`)。
- 文档站:https://auland-ui.wfsdhl.com
- 接入各家 AI 编码工具的逐条指引:https://auland-ui.wfsdhl.com/guide/mcp/codex
## 版本与许可
- 0.x 阶段:类型 key、变体 key 与组件 props 是对外契约,破坏性改动进次版本。
- 代码 MIT;随包字体为 SIL OFL 1.1(许可原文在 `node_modules/auland-ui/public/fonts/OFL-*.txt`)。