目录结构

admin-design/
├── docs/                     # 文档站（VitePress）：guide/ + components/
├── public/brand/             # 品牌资源，业务系统直接覆盖同名文件
├── src/
│   ├── app/                  # 外壳接线：路由、布局、Providers、示例菜单
│   ├── components/           # 公共组件（外壳、页型零件、图表、设置面板）
│   │   └── ui/               # 基础控件（button/input/table/tabs/dialog…）
│   ├── hooks/                # 通用 hooks
│   ├── lib/                  # 纯逻辑：主题偏好、i18n、树、分页、指标、表格偏好…
│   ├── pages/                # 标准页型示例：工作台、列表、详情、设置、通知、登录注册
│   │   └── design-system/    # 组件总览（按类型拆分）
│   ├── test/                 # 全部测试：unit / components / e2e
│   └── index.css             # 语义 Token 的唯一来源
├── .githooks/pre-commit      # 提交前校验
└── .github/workflows/ci.yml  # CI：check + e2e

判断标准

新增代码前先回答一个问题：这段代码服务谁？

代码性质	落点
能给任意业务复用的通用控件	src/components/ui/
带后台语义但不绑定具体业务（表格、树、图表、设置面板、页型零件）	src/components/
纯函数 / 纯数据（无 React）	src/lib/
只服务某个页面	src/pages/
外壳接线（路由、布局、Providers、菜单）	src/app/

需要 UI 状态时才用 Zustand，并且放在 lib/ 里；服务端数据不进 Zustand，也不写进 localStorage。

命名约定

• 文件名 kebab-case：data-table.tsx、password-strength.tsx。
• 组件名 PascalCase，导出用命名导出（export function DataTable），不使用默认导出。
• 基础控件沿用 shadcn 风格：src/components/ui/button.tsx 导出 Button 与 buttonVariants。
• 测试文件与被测对象同名：src/test/components/data-table.test.tsx 对应 src/components/data-table.tsx。
• 文档页与组件分类页一一对应：docs/components/data.md ↔ /design-system/data。

新增一个页面要动哪几处

1. src/pages/xxx-page.tsx 写页面（用 PageHeader + 页面零件组装）。
2. src/App.tsx 注册路由，懒加载（lazy(() => import(...))）。
3. src/app/navigation.ts 把路径登记到 navigation，并在 navigationGroups 的 paths 里声明分组与顺序。
4. 文案进 src/lib/i18n.ts（中英同步），标题可以走 pageTitles。
5. 补测试：页面级交互放 src/test/e2e/，纯逻辑放 src/test/unit/。

如果页面是后台菜单下发的（不需要在前端登记菜单），跳过第 3 步：页面放在 src/pages/ 下， 接口用组件键（例如 reports-page）引用它即可，见动态菜单与权限。

新增一个公共组件要动哪几处

模板要求"三件套"，缺一不可：

1. 组件本体：src/components/（通用控件放 ui/）。
2. 组件总览示例：加到对应分类页（src/pages/design-system/*.tsx），可交互。
3. 至少一处真实落点：标准页型里真的用上，而不是只存在于总览。
4. 测试：src/test/components/ 或 src/test/unit/，交互复杂再加 Playwright。
5. 文档：在 docs/components/<分类>.md 补一节（props 表 + 用法）。