AGENTS.md

1# Forge UI Kit — AI 接入指南
2 
3你正在协助一个基于 **Forge UI Kit** 搭起来的 Next.js 项目。Forge 是一套 ToB 级组件库 + 布局 + 登录/业务模板，整个工作方式是「AI 拼装、人工确认」——你不手写组件、不自己选色、不造轮子。人只做 UI 效果与组件选型的确认。
4 
5## 你的职责
6 
71. 读用户给的业务文档（PRD / 流程图 / 接口说明）
82. 拆出页面清单 + 每页的操作流
93. 从现成资源里挑：登录套件、业务模板骨架、组件、布局
104. 拼出页面，只 `import` 不手搓
115. 缺件或不确定的，停下问人，别自行发挥
12 
13## 铁律（违反必须重写）
14 
151. **组件只从 `@forge-ui/react` 导入**。禁止手搓 `<div class="bg-...">` 复刻设计稿的卡片、按钮、输入框等。Kit 里没有就停下问，不要自行画。
162. **颜色只用 `fg-*` token**。禁用 Tailwind 默认色（如 `text-blue-500` `bg-gray-100`），全部换成 `text-fg-violet` `bg-fg-grey-100`。没对上的颜色去 `src/app/globals.css` 的 `@theme inline` 里扩 token，不要就地写 hex。
173. **Icon 用 `solar-icon-set`**，导出名以 `Linear` / `BoldDuotone` / `Bold` 等后缀结尾。颜色必须用 `color="#HEX"` prop，不要用 className 上的 `text-*`——库里 fill 写死了，className 不生效。尺寸用 `size={N}` prop。
184. **布局用 `<AppLayout>`**（`@forge-ui/react`），不要自己拼 sidebar + topbar。登录页直接用 `/sign-in` `/sign-up` `/forgot-password` `/reset-password` 现成页面。
195. **不确定就看 `/cases/<name>`**。Forge 每个组件都有一页示例（`src/app/cases/<name>/page.tsx`），去读它，比凭想象写 props 靠谱十倍。
20 
21## 可用资源索引
22 
23### 组件清单（`@forge-ui/react`）
24 
25按类别分组，括号里是 `cases/` 下对应的示例页：
26 
27**基础**
28- `Button` / `IconButton` / `StyledLink`（button-link）
29- `NotificationBadge` / `Label` / `CircleIcon` / `ArtisticIcon`（badge）
30- `ProgressBar`（progress）
31- `Checkbox` / `RadioButton` / `Toggle`（input-field）
32- `Avatar` / `AvatarGroup`（badge）
33 
34**表单**（cases/input-field）
35- `TextField` / `TextArea` / `SelectOption` / `Datepicker`
36- `MediaUpload` / `ProfileImgUpload` / `FileUpload` / `FileCard` / `FileTypeIcon`
37- `IconSelector` / `IconPicker` / `ColorPicker`
38- `TextFieldSelectSuffix`
39 
40**数据展示**（cases/card / cases/list / cases/table）
41- 卡片家族：`StatCard` / `ProgressStatCard` / `LineChartStatCard` / `WheelChartStatCard` / `BarChartStatCard`
42- 金融卡：`BalanceCard` / `DebitCard` / `CreditCard`
43- 业务卡：`ProjectCard` / `TaskCard` / `UserCard` / `ImageStatCard` / `HighlightCard` / `ProgressCard` / `ActivityCard`
44- 列表：`ListItem` / `DescriptionItem` / `ListGroup` / `MenuItem` / `NotificationItem` / `ProfileCard` / `ContactItem`
45- 表格：`DataTable` / `FullWidthTable` / `TableCell` / `StatusBadge` / `ProgressBadge`
46 
47**图表**（cases/chart）
48- `MeterChart` / `HalfDonutChart` / `DashedHalfDonutChart` / `DonutChart` / `PieChart` / `MultilayerDonutChart` / `BubbleChart`
49- `BarChart` / `BarHorizontalChart` / `BarUpsideDownChart` / `SmoothLineChart`
50- `ChartCard` / `ChartTooltip` / `ChartListItem` / `ChartLegendItem` / `ChartValueRow` / `ChartStatFooter`
51 
52**聊天与社交**（cases/chat / cases/comment）
53- `ChatBubble` / `ChatInputBar` / `CommentItem` / `ReviewItem`
54 
55**筛选**（cases/filter）
56- `FilterGroup` / `FilterTrigger` / `FilterPanel`
57 
58**日历**（cases/calendar）
59- `SmallCalendar` / `SmallDailyCalendar` / `FullCalendar`
60- `CalendarDayCell` / `CalendarWeekRow` / `EventCard` / `EventTag`
61 
62**时间轴**（cases/history）
63- `HistoryItem` / `HistoryGrouped`
64 
65**导航与控件**
66- `SidebarMenu`（cases/menu）
67- `TopBar` / `PageHeader` / `Breadcrumbs`（cases/page-header）
68- `Toolbar` + 一堆 Toolbar 子组件 / `PageTitleToolbar`（cases/toolbar）
69- `Pagination` / `Stepper` / `PageDot` / `TabBar` / `ButtonGroup`（cases/pagination-stepper, cases/tab）
70- `Tooltip` / `TooltipBubble` / `TooltipAnchor`（cases/tooltip）
71- `ConfirmationDialog`（cases/modal）
72- `DropdownPanel` / `IconTrigger` / `KebabMenu`（cases/menu）
73 
74**Widget**（cases/other-widget）
75- `CurrencyConverter` / `RatingStars` / `ImageGrid` / `ProductRow` / `MapCard`（cases/map）
76 
77**布局模板**
78- `AppLayout`（`@forge-ui/react/app-layout`）— sidebar + topbar + 内容区一站式，业务页都用它
79 
80### 颜色 Token（`src/app/globals.css`）
81 
828 个色系 × 10 shade（50/100/200/.../900），外加一个 `grey`：
83 
84- `fg-violet-{50..900}`（品牌主色，别名 `fg-violet = 500`）
85- `fg-blue-{50..900}`
86- `fg-green-{50..900}`
87- `fg-red-{50..900}`（别名 `fg-red = 500`）
88- `fg-yellow-{50..900}`（别名 `fg-yellow = 500`）
89- `fg-cyan-{50..900}`
90- `fg-black-{50..900}`（别名 `fg-black = 500 = #000A19`，注意不是纯黑）
91- `fg-grey-{50..900}`
92 
93**用法**：
94- Tailwind 直接用 `bg-fg-violet-500` `text-fg-black` `border-fg-grey-200`
95- 运行时取 hex：`var(--fg-violet)` / `var(--fg-grey-700)`
96- 深浅调性通常：`50/100` 作浅底、`500` 作主色、`700+` 作深底或高对比文字
97 
98### Icon（`solar-icon-set`）
99 
100```tsx
101import { MagniferLinear, BellBoldDuotone } from "solar-icon-set";
102 
103<MagniferLinear size={16} color="#71717A" />
104<BellBoldDuotone size={24} color="var(--fg-violet)" />
105```
106 
107**项目内默认灰色 icon 色值**：`#71717A`（对应 `fg-grey-700` 附近），保持全站一致。
108 
109**踩坑（常犯）**：
1101. `className="text-fg-red"` 对 solar icon **不生效**——库里 fill 写死，颜色必须走 `color` prop。
1112. 外层 wrapper 给了 `p-Y`（上下 padding）或固定 height 会**压扁 SVG**。icon 外包装只给 `w-X h-X` 的正方形 box，或者 `inline-flex items-center`。
112 
113### 布局（`AppLayout`）
114 
115```tsx
116import { AppLayout } from "@forge-ui/react";
117 
118<AppLayout
119  mode="light"              // light | dark
120  accent="purple"           // purple | blue | black
121  profilePosition="sidebar" // sidebar | topbar
122  logoText="Your Brand"
123  teamName="Acme Inc"
124  menuItems={[
125    { icon: <HomeLinear size={20} />, label: "Dashboard", href: "/dashboard" },
126    { label: "Orders", href: "/orders", badge: 3 },
127  ]}
128  profile={{ avatar: "/me.jpg", name: "Jane Doe", role: "Admin" }}
129  pageTitle="Orders"
130  breadcrumbs={[{ label: "Home", href: "/" }, { label: "Orders" }]}
131  pageHeaderVariant="detail"  // home | detail
132  primaryAction={{ label: "New", onClick: () => {} }}
133>
134  {/* 你的业务内容 */}
135</AppLayout>
136```
137 
138示例页在 `/examples/ecommerce/*`，可参考。
139 
140### 登录套件（现成页面，改文案与接口即可）
141 
142- `/sign-in` — 登录
143- `/sign-up` — 注册
144- `/forgot-password` — 忘记密码
145- `/reset-password` — 重置密码
146 
147源文件：`src/app/{sign-in,sign-up,forgot-password,reset-password}/page.tsx`
148 
149### 业务模板（真实多页骨架）
150 
151`src/app/examples/(dashboard)/ecommerce/` 下是一套电商后台，包含：
152- `categories` / `customers` / `orders` / `products` / `sellers`
153- 每个模块都有 列表页 / 详情页 `[id]` / 新建页 `new`
154- 统一用 `AppLayout`、`DataTable`、`Toolbar` 拼装
155 
156新业务用它当骨架：先复制最接近的模块（如 orders 给"订单类业务"），再改字段和接口。
157 
158### Case 索引（组件用法示例，写代码前必看对应页）
159 
160`/cases/<name>` → `src/app/cases/<name>/page.tsx`：
161 
162badge / button-link / calendar / card / chart / chat / comment / filter / history / input-field / list / map / menu / modal / other-widget / page-header / pagination-stepper / progress / tab / table / toolbar / tooltip
163 
164（共 22 个。`file-type` 和 `style-guide` 是 `/components/*` 下的 Kit 资产展示页，不是业务示例，命中需求时直接读源文件 `src/app/components/{file-type,style-guide}/page.tsx`。）
165 
166## 工作流
167 
168**Step 1. 读 PRD**
169抽出：页面清单、每页主要操作、数据字段、业务状态、权限边界。
170 
171**Step 2. 挑骨架**
172- 有登录需求 → 用 `/sign-in` 等现成页
173- 后台业务（列表+详情+新建） → 复制 `app/ecommerce/<最接近模块>/` 改
174- 自定义页面 → 套 `<AppLayout>` 起架子
175 
176**Step 3. 拆页面 → 拼组件**
177- 先写页面骨架（AppLayout + Toolbar + 主内容容器）
178- 主内容按区块拆：每块对应一个 Kit 组件或组件组合
179- 遇到不确定的组件 → 打开 `/cases/<name>` 对应示例页复制用法
180- 颜色选 `fg-*`，icon 选 `solar-icon-set`
181 
182**Step 4. 缺件停下**
183如果 Kit 里没有合适组件（不是变体缺失，是真的没有），**立即停下问人**。不要自己手搓 div 复刻。用户会判断要不要扩 Kit。
184 
185**Step 5. 自检**
186- `pnpm tsc --noEmit` 通过
187- 本地起服务：`pnpm dev --port 3456 --hostname 0.0.0.0`（常驻，别自己另起）
188- 截图给用户确认效果
189 
190## 提交前自检清单
191 
192- [ ] 没有手搓 div 复刻 Kit 已有组件
193- [ ] 颜色全部走 `fg-*` token，无裸 Tailwind 默认色
194- [ ] Icon 全部 `solar-icon-set` + `color` prop
195- [ ] 布局用 `<AppLayout>` 或继承自模板
196- [ ] tsc 通过
197- [ ] 截图与设计对照过
198- [ ] 不确定的地方已问人，未自行发挥
199