taichu-ui-components · diff
git:20260627.17585a7 to git:20260710.44dade2
10 added, 80 removed. Audit A to A.
---
name: taichu-ui-components
description: 太初前端 UI 组件准入与复用规则。Use when Codex is implementing, modifying, reviewing, or automatically executing any frontend work under `web/`, including task-package execution, page/layout changes, React components, Tailwind styles, shadcn/ui components, visual effects, animations, command palettes, modals, cards, editor UI, entry page UI, paper-card UI, or user-visible frontend copy; trigger even when the user did not explicitly ask for a component library.
---
# 太初 UI 组件准入
## 核心原则
任何太初前端开发任务都默认进入本 Skill，不限于用户显式提出“使用组件库”的场景。自动任务包、代码修复、页面改版、样式微调、组件重构、动效实现和前端 review，只要涉及 `web/` 下用户可见 UI，都必须执行本准入流程。
- 本 Skill 不替代 `TAICHU_DESIGN.md`。它只规定组件库和花哨组件如何被选择、引入、改造和验证。
+ 本 Skill 不定义视觉风格，也不替代根目录 `DESIGN.md`。页面模式、入口页例外、颜色、排版、动效和禁止项只以 `DESIGN.md` 为准；本 Skill 只规定组件如何选择、引入、改造和验证。
## 必读顺序
- 1. 先读取根目录 `TAICHU_DESIGN.md`，确认当前任务属于入口层、工作台层、纸面内容层或 AI 状态层。
+ 1. 先读取根目录 `DESIGN.md`，确认当前页面模式和适用边界。
2. 再检查 `web/components.json`、`web/package.json` 和 `web/src/components/ui/`，确认现有 shadcn/ui、Base UI、Tailwind、lucide 和本地基础组件能力。
3. 如果任务来自自动任务包，也按同样顺序执行；不要等待用户再次要求使用 UI 组件规则。
## 组件来源优先级
按以下顺序选组件：
1. 项目内已有组件：优先复用 `web/src/components/ui/` 和业务组件。
2. shadcn/ui 或 Base UI：需要基础交互组件时优先使用，落成本地源码后再适配太初 token。
- 3. Motion Primitives 类动效基础组件：只用于 Selection AI、纸卡浮现、状态切换等克制动效。
- 4. Magic UI 类视觉素材：只允许提取粒子、光线、扫描线、细微动效等局部效果，并必须改造成太初三层设计语言。
+ 3. Motion Primitives 类动效基础组件：只用于状态切换和 `DESIGN.md` 允许的克制动效。
+ 4. Magic UI 类视觉素材：只允许提取粒子、光线、扫描线、细微动效等局部效果，并必须改造成太初设计语言。
5. Aceternity UI 类视觉素材：只允许作为局部参考或源码素材，不得直接套用营销区块、霓虹背景、炫光卡片或完整 landing 页面。
- 不得因为外部组件“好看”而绕过太初三层设计系统。
-
- ## 分层准入
-
- ### 入口层
-
- 允许：
-
- - 粒子场。
- - 点云地景。
- - 极弱仪表读数。
- - 白框入口按钮。
- - 低透明远景线稿。
-
- 禁止：
-
- - 随机星空组件。
- - 赛博霓虹背景。
- - 大面积渐变 hero。
- - 普通 SaaS landing 区块。
- - 游戏 HUD。
-
- ### 工作台层
-
- 允许：
-
- - 命令面板。
- - 弹出层、抽屉、Tooltip、Popover。
- - 深色面板、工具栏、状态栏。
- - 极弱 aurora 线条。
- - 紧凑列表、分隔线、检索状态。
-
- 禁止：
-
- - 彩色主按钮体系。
- - 大面积发光背景。
- - 浮夸 hover 卡片。
- - 杂志式大标题压过编辑器。
- - 在工作台背景使用米纸色。
-
- ### 纸面内容层
-
- 允许：
-
- - 暖米纸卡片。
- - 黑色墨线边框。
- - 小面积荧光标签。
- - 来源徽标。
- - 稿件预览和导出纸张。
-
- 禁止：
-
- - 把纸面风格扩散到主工作台外壳。
- - 使用极光渐变铺满卡片。
- - 使用营销卡片模板替代稿件结构。
-
- ### AI 状态层
-
- 允许：
-
- - 小圆点。
- - 1px 扫描线。
- - 短进度线。
- - 极弱 aurora 动效。
- - 等宽读数配中文说明。
-
- 禁止：
-
- - 大型彩色 AI 按钮。
- - 全屏 loading 特效。
- - 高饱和状态色块。
+ 不得因为外部组件“好看”而绕过 `DESIGN.md`。
## 引入外部组件的规则
外部组件只能作为源码素材或 registry 输入，不能成为太初的全局视觉规则。
执行前检查：
- 是否能用已有组件完成。
- - 是否符合 `TAICHU_DESIGN.md` 的层级边界。
- - 是否需要新增依赖；如果需要，必须确认 `web/package.json`、`package-lock.json` 和启动脚本风险。
+ - 是否符合 `DESIGN.md` 的页面模式与视觉边界。
+ - 是否需要新增依赖；如果需要，必须确认 `web/package.json`、`web/package-lock.json` 和启动脚本风险。
- 是否会引入大面积装饰、霓虹、游戏化或普通 SaaS landing 语言。
落地时要求：
- 组件源码放进项目组件目录后，必须改成太初 token。
- 所有用户可见文案必须中文。
- 图标优先使用 `lucide-react`。
- 动效必须尊重 `prefers-reduced-motion`。
- 不要把外部组件原始英文文案、品牌色、示例数据留在界面里。
## 自动任务检查清单
每次处理前端任务时，确认：
- - 已读取 `TAICHU_DESIGN.md`。
- - 已判断当前 UI 属于哪个视觉层。
+ - 已读取 `DESIGN.md`。
+ - 已判断当前 UI 使用的页面模式及例外边界。
- 已优先检查本地组件能否复用。
- 若使用花哨组件，已缩小到局部效果并完成太初化改造。
- 没有新增无边界混搭、游戏 UI、赛博霓虹、大面积米纸主应用或高饱和按钮。
- 变更后至少运行适合范围的校验，例如 `npm run lint`、`npm run test:editor` 或 `npm run build`；无法运行时说明原因。
## 输出要求
交付前说明：
- 使用了哪些本地组件或外部组件素材。
- - 它们分别服务于入口层、工作台层、纸面内容层或 AI 状态层中的哪一层。
+ - 它们分别服务于哪个页面模式或交互场景。
- 是否新增依赖。
- 做了哪些验证。