# Modra 接入指南（面向 AI 编码助手）

本文件是给 AI 助手读取的权威接入规则。生成 Modra 相关代码前请先通读；组件 API 以 `/ai/components/<slug>.md` 为准，不要凭记忆猜测 props。

## 0. AI 接入流程（只知道站点地址时从这里开始）

站点地址：`https://modra.feinian.net`。按顺序执行，每步完成后再进入下一步：

1. **识别项目类型**：读 `package.json`。有 `react` → React / Next.js 路线；没有 React（Django、Rails、Blade、纯静态页）→ HTML 路线（`@modra/website`），**不要**引入 React。
2. **检查 registry 认证**（见第 2 节）：运行 `npm view @modra/react@dev --registry https://npm.feinian.net/`。失败（401/403/ENOTFOUND）→ **停止并告知用户**需要 `NPM_TOKEN`，不要自行尝试获取或把 token 写入仓库。
3. **安装包与 peer**（第 2 节）。
4. **配置样式入口**（第 3 节）：Tailwind v4 + `@modra/tailwind-preset` + `@source`。
5. **写入 AI 约定文件**：把 `https://modra.feinian.net/AGENTS.md` 的内容写入项目根的 `AGENTS.md`（Claude Code 用 `CLAUDE.md`，Cursor 用 `.cursor/rules/modra.mdc`），已存在则追加，不覆盖。
6. **写代码前查 API**：读 `https://modra.feinian.net/ai/components/<slug>.md`，不要凭记忆写 props。
7. **验证**：运行项目的类型检查与构建；渲染一个 `Button` 确认样式生效（见第 7 节常见错误）。

可选：连接 MCP 服务器，让 AI 直接按需查询文档，免于逐个抓取文件。见第 9 节。

## 1. 选包

| 场景                                        | 使用                                                                                                            |
| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| React / Next.js 应用                        | `@modra/react` + `@modra/tailwind-preset` + `@modra/tokens`                                                     |
| 纯 HTML / 后端模板（Django、Rails、Blade…） | `@modra/tokens` CSS 变量，或 Tailwind 语义类，或 `@modra/website` 配方（`modra-` 前缀类名）。**不要**引入 React |
| 图标（可选）                                | `@feinian/fontawesome-pro-react`（需授权）或 `@feinian/fontawesome-free-react`，两者 API 一致                   |

## 2. 安装

```bash
pnpm add @modra/tokens@dev @modra/tailwind-preset@dev @modra/react@dev --registry https://npm.feinian.net/
```

- 包来自内网 registry `https://npm.feinian.net/`，发布在 `dev` 通道（所以带 `@dev`）。
- **认证**：token 通过环境变量 `NPM_TOKEN` 提供，在**用户级** `~/.npmrc`（不是项目内文件）写入：

  ```ini
  //npm.feinian.net/:_authToken=${NPM_TOKEN}
  ```

  - `NPM_TOKEN` 由团队的 registry 管理员发放；AI 无法也不应自行获取。
  - 安装前检查：`echo "${NPM_TOKEN:+set}"` 输出 `set` 才算已配置。**未配置时停止并请用户设置**，不要把 token 写入项目的 `.npmrc`、`package.json`、CI 配置或任何会提交的文件。
  - 在 CI / Docker 构建中通过构建密钥或环境变量注入，不要 `COPY` 含 token 的 `.npmrc` 进镜像。
  - 验证：`npm view @modra/react@dev version --registry https://npm.feinian.net/` 能输出版本号。
  - 只使用 `--registry` 参数或用户级 `.npmrc` 指向该 registry；不要修改全局默认 registry。

- 只在确实用到对应组件时才安装可选 peer（与组件同一个应用内安装）：

| 组件                               | peer 依赖                     |
| ---------------------------------- | ----------------------------- |
| `DataTable`                        | `@tanstack/react-table`       |
| `Calendar` / 日期类选择器          | `react-day-picker` `date-fns` |
| `Command`                          | `cmdk`                        |
| `Form`                             | `react-hook-form`             |
| `InputOTP`                         | `input-otp`                   |
| `Resizable`                        | `react-resizable-panels`      |
| 虚拟化 `Tree` / `VirtualDataTable` | `@tanstack/react-virtual`     |

`Button` 等核心控件不需要任何额外 peer。

## 3. 样式入口（必须）

```css
/* app.css */
@import "tailwindcss";
@import "@modra/tailwind-preset";
/* 让 Tailwind 扫描组件库用到的工具类 */
@source "../node_modules/@modra/react/dist/**/*.{js,mjs}";
```

要求 Tailwind v4。缺少 `@source` 会导致组件样式丢失。

## 4. 使用组件

```tsx
import { Button } from "@modra/react";

export default function Page() {
  return <Button variant="primary">开始使用</Button>;
}
```

- 所有组件从包根 `@modra/react` 导入，不要深层导入内部路径。
- 复合组件按子组件组合（如 `Dialog` / `DialogContent` / `DialogHeader` / `DialogTitle`），导出清单见各组件的 md。
- 全局应用外层使用 `ConfigProvider`（默认 `zhCN`）；需要同步 `<html lang>` 时传 `syncDocumentLang`。
- 通知使用 `Toaster` + `toast()`，确认框使用 `confirm()` + `ConfirmDialogHost`。

## 5. 样式与主题规则

- 使用**语义类**：`bg-primary`、`text-primary-foreground`、`text-muted-foreground`、`bg-background`、`rounded-md` 等。**不要**硬编码颜色、也不要用 `dark:` 去手写颜色分支——暗色由语义变量自动切换。
- 优先使用逻辑属性类（`ps-*`/`pe-*`/`ms-*`/`me-*`/`start-*`/`end-*`），以便 RTL；不要用 `pl-*`/`pr-*`/`left-*`/`right-*` 表达方向性间距。
- 暗色模式：给 `<html>` 切换 `.dark`。品牌：`<html data-brand="ocean|forest|ids">`（`ids` 仅浅色）。密度：`data-density="compact"`。
- 运行时自定义主题使用 `ThemeProvider theme={{ color: { primary: "..." } }}`，不要手写覆盖 CSS 变量。
- 修改视觉应通过令牌（`@modra/tokens`）而不是改组件内部类名。

## 6. 选型速查（同类组件怎么选）

| 需求   | 选择                                                                                                                |
| ------ | ------------------------------------------------------------------------------------------------------------------- |
| 选择器 | `select`（少量）→ `combobox`（可搜索）→ `command`（命令面板）→ `tree-select` / `cascader` / `transfer`（层级/穿梭） |
| 覆盖层 | `dialog`（通用）、`alert-dialog` / `popconfirm`（确认）、`sheet`（侧滑）                                            |
| 表格   | `table`（静态）、`data-table`（排序/筛选/分页）、`virtual-data-table`（海量数据）                                   |
| 反馈   | `alert`（页内）、`toast`（瞬时）、`empty`（空态）、`result`（结果页）                                               |

完整的决策指引见 `/llms-full.txt`。

## 7. 常见错误

1. 忘记 `@import "@modra/tailwind-preset"` 或 `@source` → 无样式。
2. 使用了 `DataTable`/`Form` 等但未安装对应 peer → 运行时找不到模块。
3. 编造不存在的 prop 或组件名 → 以 `/ai/components/<slug>.md` 的 props 与导出为准。
4. 在非 React 页面使用 `@modra/react` → 应改用 `@modra/website` 或令牌 CSS。
5. 浏览器最低要求：Chrome/Edge 111、Firefox 128、Safari 16.4。

## 8. 延伸

- 组件站：`/components`、`/usage`、`/tokens`、`/website`
- 非 SPA 接入：`/website`
- 仓库文档：`docs/components.md`、`docs/website.md`、`docs/tokens.md`

## 9. MCP 服务器（可选，推荐）

远程 MCP（Streamable HTTP，无状态、只读、无需认证）：`https://modra.feinian.net/mcp`。

```bash
# Claude Code
claude mcp add --transport http modra https://modra.feinian.net/mcp
```

```jsonc
// Cursor：.cursor/mcp.json   |   VS Code：.vscode/mcp.json（顶层键为 "servers"）
{ "mcpServers": { "modra": { "url": "https://modra.feinian.net/mcp" } } }
```

工具：

| 工具                    | 用途                                                   |
| ----------------------- | ------------------------------------------------------ |
| `get_integration_guide` | 返回本指南；可传 `scenario`：`react` / `next` / `html` |
| `get_agents_md`         | 返回已填好站点地址的 AGENTS.md，写入使用方项目         |
| `list_components`       | 列出全部组件（可按分组过滤）                           |
| `get_component`         | 返回单个组件的导出与 props（参数 `slug`）              |
| `search_components`     | 按关键词搜索组件                                       |
| `get_design_tokens`     | 返回语义令牌清单与主题/品牌/密度切换方式               |

服务器描述文件：`/.well-known/mcp/server-card.json`。MCP 不可用时，退回读取 `/llms.txt` 与 `/ai/components/<slug>.md`，内容相同。