# AI 协作指南 · POSX Design System 2026

本文件夹（`05-ai/`）是为 AI 工具准备的专区：让任何 AI（Claude、ChatGPT、Cursor、Figma AI 等）在**一次导入**后就能正确使用 POSX 设计系统产出合规的设计与代码。

---

## 一、导入（把设计系统喂给 AI）

### 方法 A · 单文件导入（推荐，适合对话式 AI）

把 **`design-system.ai.json`** 整个文件拖进对话（或复制粘贴），然后直接提需求：

> 附上 design-system.ai.json。请用 POSX 设计系统做一个支付成功页，遵守文件里的 rules。

该文件包含：全部色彩 token（primitive / 语义 / 组件 / 渐变）、使用规则（60/30/10 配比、对比度、层级引用规则）、字体与品牌要点、仓库文件地图。**AI 不需要再读其他文件即可工作。**

### 方法 B · 工程内引用（适合 Cursor / Claude Code / Copilot）

把整个设计系统文件夹放进（或链接到）项目，在项目说明（如 `CLAUDE.md` / `.cursorrules`）里写一行：

```
设计系统规则见 posx-design-system-2026/05-ai/llms.txt，token 单一事实来源是 03-tokens/tokens.css，禁止硬编码颜色。
```

`llms.txt` 是标准的 AI 索引文件，AI 会顺着它找到所有规范。

### 方法 C · 按需取用（适合只要色值的场景）

- 只要色值 → `exports/tokens.flat.json`（扁平 key→hex）
- Tailwind 项目 → `exports/posx-tailwind.preset.js`
- Figma（Tokens Studio 插件）→ `exports/figma-tokens.json`

---

## 二、导出（让 AI 转换到你的目标平台）

`exports/` 内已预生成三种格式。需要其他格式（SwiftUI、Jetpack Compose、CSS-in-JS、Sketch 等）时，把 `design-system.ai.json` + `prompts/export-tokens.md` 一起给 AI，说明目标平台即可。生成后建议抽查 3–5 个色值与 `tokens.flat.json` 是否一致。

---

## 三、常用提示词

见 `prompts/` 文件夹，均为可直接粘贴的模板：

| 模板 | 用途 |
|---|---|
| `build-page.md` | 让 AI 用本系统生成页面/组件（含硬约束清单） |
| `check-compliance.md` | 让 AI 审查一份设计/代码是否符合本系统 |
| `export-tokens.md` | 让 AI 把 token 转换为任意目标平台格式 |

---

## 四、给 AI 的红线（也写进了 llms.txt）

1. **不发明颜色**：所有色值必须来自 token；找不到合适的就用最近的语义变量。
2. **不直接用 primitive**：组件代码只引用 `--primary`、`--button-primary-bg` 这类语义/组件变量。
3. **对比度**：正文 ≥4.5；大字号（≥18pt）≥3.0；渐变上叠字遵守叠字建议——`design-system.ai.json` 里每条渐变的 `recommended_text_light` 字段，或 `tokens.json` 里对应的 `text_advice_light` / `text_advice_dark` 实测数据。
4. **深浅双主题**：任何新组件都要在 light/dark 两种模式下可用（引用语义变量即自动满足）。
5. **字体**：不引入新字体家族；中文一律 Noto Sans SC 兜底。
6. **Logo**：不变形、不换色、不加特效、不重排字标（详见 `01-brand/brand-guidelines.md`）。

---

## 五、文件同步说明

`design-system.ai.json`、`exports/*` 由脚本从 `03-tokens/tokens.json` 生成。**改动 token 后请重新生成**（见 `03-tokens/build/README.md`），不要手改这些导出文件。