--- title: 给 Agent 用 For Agents url: https://ui.zhaozimin.com/start/for-agents/ markdown: https://ui.zhaozimin.com/start/for-agents.md group: 开始 origin: 规范文档 version: v0.2.0 # 设计系统版本，发布于 2026-09-23 scope: .zzm-v4 # 根节点必须带这个类，否则样式不生效 css: https://ui.zhaozimin.com/v/0.2.0/zzm.css # 锁版本地址，本仓库再改也不影响你 --- # 给 Agent 用 For Agents > 这个站的每一页都有机读版本。本页说明入口在哪、按什么顺序读、Markdown 头里的字段是什么意思，以及复刻完怎么自检。 ## 入口 | 地址 | 是什么 | 什么时候用 | |---|---|---| | `/llms.txt` | 全站目录，按 llms.txt 约定书写，每条链接指向对应页面的 .md | 第一站 | | `/llms-full.txt` | 全站所有页面的 Markdown 拼成一个文件 | 想一次读完 | | `/DESIGN.md` | 单文件规范：YAML 头放令牌与组件参数，正文放原则与铁律 | 只能读一个文件时 | | `/tokens.json` | W3C 设计令牌（DTCG）格式，数值直接读自 tokens.css | 导入设计工具或生成主题 | | `/zzm.css` | 全部样式合成一个文件（.zzm-v4 作用域） | 静态页、任何技术栈 | | `/zzm.global.css` | 同上，去掉作用域前缀 | 不能给根节点加类名时 | | `/<页面>.md` | 任一页面的 Markdown 版本 | 只要某个组件 | | `/src/...` | 同步来的源码原文，URL 路径就是仓库路径 | 要 React 源码时 | 每个 HTML 页面的 `` 里都有 `` 指向自己的 .md。页面内容在构建时就写进了 HTML，不执行 JS 也能读全。`robots.txt` 对所有爬虫放行。 ## 推荐阅读顺序 1. `/llms.txt`：知道有哪些页面。 2. `/foundations/color.md`、`/foundations/spacing.md`、`/foundations/elevation.md`：颜色、尺寸、光影三件事决定八成观感。 3. 需要哪个组件读哪个组件的 .md。样张的 HTML 是构建时由 React 渲染出来的真实标记，粘贴即可。 4. 每页末尾「本页用到的 CSS」是按类名从源文件原样裁出的规则；引入完整的 zzm.css 就不必逐页拼。 ## Markdown 头部字段 /components/button.md 的头部： ```yaml --- title: 按钮 Btn url: https://ui.zhaozimin.com/components/button markdown: https://ui.zhaozimin.com/components/button.md group: 组件 origin: 设计系统源码（src/system），本仓库是唯一源头 source: - src/system/components/v4/Button.jsx # 源码原文地址 version: v0.2.0 # 设计系统版本 scope: .zzm-v4 # 根节点必须带这个类 css: https://ui.zhaozimin.com/v/0.2.0/zzm.css # 锁版本地址 tokens: [--zzm-accent] --- ``` | 字段 | 含义 | |---|---| | `origin` | 设计系统源码（src/system）/ 提炼层组件（src/extracted）/ 展示版复刻 / 规范文档——都以本仓库为唯一源头 | | `source` | 实现这一页的源文件，可直接 GET | | `version` | 设计系统版本号；引用样式时锁这个版本 | | `scope` | 样式作用域，永远是 .zzm-v4 | | `tokens` | 这一页直接依赖的 CSS 变量 | ## 铁律速查 - ✓ 要：根节点 `class="zzm-v4"`，引入 zzm.css - ✓ 要：颜色只用 `var(--zzm-*)`；间距/高度/行高/圆角只取 4 的倍数 - ✓ 要：按钮圆角矩形：sm/md 8、lg 12；高度 28/36/44 - ✗ 不要：把可点的按钮做成 999 胶囊 - ✓ 要：阴影只从 `.zzm-btn` `.zzm-card` `.zzm-input` 这些质感类取 - ✗ 不要：自己写 `box-shadow`、`backdrop-filter`、渐变 - ✓ 要：一屏只出现一次朱色 `--zzm-accent`，标「下一步」 - ✗ 不要：用鲜艳纯红、奶油色暖底、网络字体、暗色主题 - ✓ 要：禁用＝灰面灰字；等待＝ `busy` - ✗ 不要：用 opacity 淡化表示禁用 ## 复刻完怎么自检 把你的实现和本站样张在同一台 Mac、同一缩放下截图，逐像素比对。常见偏差按出现频率排序： 1. **没加 `.zzm-v4`**：按钮变成浏览器默认样式。 2. **字体不对**：出现了 Inter 或网络字体。删掉，用系统字体栈 `-apple-system, "PingFang SC", …`。 3. **尺寸差 1–2 像素**：缺了 `box-sizing: border-box`。zzm.css 的基线段已包含；自己拆文件时别漏掉。 4. **阴影方向不对**：自己写了 box-shadow。删掉，交给质感类。 5. **红太多**：同屏出现了两处以上朱色。 --- 上一页：[快速接入](https://ui.zhaozimin.com/start/quickstart.md) · 下一页：[设计原则](https://ui.zhaozimin.com/foundations/principles.md) · 全站目录：https://ui.zhaozimin.com/llms.txt