docs: standardize on HeroUI components

README.md

@@ -2,6 +2,13 @@
 
 `@umijs/max` 模板项目，更多功能参考 [Umi Max 简介](https://umijs.org/docs/max/introduce)
 
+## UI 组件规范
+
+- 项目 UI 统一使用 HeroUI（`@heroui/react`）和 HeroUI Pro（`@heroui-pro/react`）。
+- 基础控件优先使用 HeroUI；Sidebar、Navbar、AI、DataGrid、DropZone 等专业组件使用 HeroUI Pro。
+- 禁止新增、恢复或间接引入 Catalyst UI Kit，包括依赖、源码复制、兼容包装层和基于其 DOM/props 的仿制组件。
+- 新增或重构 UI 前请先阅读 [`docs/xinyuan-design-system.md`](./docs/xinyuan-design-system.md) 和 [`docs/ui-architecture.md`](./docs/ui-architecture.md)。
+
 ## 本地启动
 
 如果本地模型代理需要浏览器携带 API Key，先创建本地环境变量文件：

docs/ui-architecture.md

@@ -32,7 +32,9 @@ Umi route /ai_chat/
 
 ## 依赖来源
 
+- HeroUI（`@heroui/react`）和 HeroUI Pro（`@heroui-pro/react`）是项目唯一允许的 UI 组件库。
 - HeroUI Pro 由目标仓库内官方授权 setup 流程独立安装。
+- `package.json`、源码和构建配置不得新增 Catalyst UI Kit 依赖或引用，也不得通过复制源码、vendor、别名或兼容包装层重新引入。
 - `package.json` 使用正式版本号，不使用 `file:`、绝对路径、相邻项目 `node_modules`、软链接或 vendor 包。
 - 项目只保留 `pnpm-lock.yaml`。
 - 最终交付前必须验证一个兼容的 React、HeroUI 与 React Aria runtime graph。
@@ -57,6 +59,7 @@ Umi route /ai_chat/
 | Ant Upload | HeroUI Pro DropZone |
 | Ant Table | HeroUI Pro DataGrid |
 | Ant Empty/Spin/Skeleton/Tag | HeroUI/Pro EmptyState、Spinner、Skeleton、Chip |
+| Catalyst UI Kit 组件 | HeroUI/HeroUI Pro 对应组件或基于 HeroUI primitive 的组合 |
 
 ## 业务保护检查点
 

docs/ui-migration-checklist.md

@@ -69,6 +69,7 @@
 - [x] `git diff --check`
 - [x] 鑫元 `audit_project.sh` 已执行；记录脚本的 PromptInput/CommonJS 子路径误报
 - [x] 旧组件引用扫描为零
+- [x] Catalyst UI Kit 依赖、导入、源码复制和兼容包装层为零；后续变更持续执行同项检查
 - [x] 页面与共享 JSX 私有视觉 utility 扫描为零
 - [x] `file:`、绝对本机路径、相邻 `node_modules` 依赖扫描为零
 - [x] HeroUI/React Aria 生产解析检查通过

docs/xinyuan-design-system.md

@@ -20,8 +20,11 @@ Inter 字体文件独立存放于 `public/fonts/`，并由 `.umirc.ts` 注入稳
 
 ## 组件边界
 
+- HeroUI 与 HeroUI Pro 是本项目唯一的 UI 组件库。新增页面、功能和共享组件均必须遵循本规范。
 - 基础组件直接从 `@heroui/react` 导入。
 - Sidebar、Navbar、AI、DataGrid、DropZone、ActionBar、EmptyState 等从 `@heroui-pro/react` 或正式子路径直接导入。
+- 禁止新增、恢复或间接引入 Catalyst UI Kit；不得复制其组件源码，也不得建立兼容其 props、事件或 DOM 结构的包装层。
+- HeroUI/HeroUI Pro 暂无现成组件时，优先使用其 primitive 和 compound API 组合实现；确需新增自定义组件时，只能使用现有 HeroUI 主题和项目 Tokens，并在评审中说明原因。
 - 使用 compound API 和 `onPress`；不建立兼容旧 props 的包装层。
 - Ant Design Icons 是唯一图标来源；Ant Design、Ant Design Pro、Ant Design X 和 antd-style 不再拥有活动页面视觉组件。
 - `className` 只承担 flex、grid、宽度、间距、对齐、滚动和响应式布局。
@@ -65,5 +68,5 @@ Inter 字体文件独立存放于 `public/fonts/`，并由 `.umirc.ts` 注入稳
 - 权威 `theme.css` SHA-256 为 `a0bf6f243aaf2c94cc8b577145d33d765f8ecab863b3a3b4a358bad4d1a05901`，与 Skill 资产逐字节一致。
 - Umi 的未使用 `antd` 插件已移除，构建产物不再注入 Ant reset；暗色标题计算为 HeroUI 前景色。
 - 页面、业务模块和共享 JSX 的私有视觉 utility 扫描为零；共享外观仅位于权威主题、批准 Tokens 和共享 Shell 设计系统层。
-- Ant Design、Ant Design Pro、Ant Design X、Ant X Markdown、antd-style、Headless UI 和 Catalyst UI 活动引用为零。
+- Ant Design、Ant Design Pro、Ant Design X、Ant X Markdown、antd-style、Headless UI 和 Catalyst UI Kit 活动引用为零；后续开发必须持续保持为零。
 - 当前业务没有真实 Tabs、筛选、KPI、图表或分页；不得为补齐目录而新增非业务模块。