Published
- 12 min read
前端规范
应该先安装的包
npm install lucide-react clsx tailwind-merge class-variance-authority react-hook-form zod @hookform/resolvers next-themes sonner
npm install -D tailwindcss postcss autoprefixer tailwindcss-animate
npm install next react react-dom
npm install -D typescript @types/node @types/react @types/react-dom提示词
# HERITAGEFLOW：全局 UI 美学与组件渲染规范
## 核心设计定位
界面必须稳定呈现以下特征：
- 现代感
- 极简主义
- 严谨清晰的视觉层级
- 高一致性
- 高级感与专业感
- Light / Dark 模式下均具备良好可读性
在生成、重构或调整任何 React 组件、Tailwind 样式或页面结构时，必须严格遵守本规范。
目标不仅是“功能可用”，而是交付**一致、克制、清晰、可维护、具有高级质感的前端界面**。
---
## 规则优先级
当多个目标发生冲突时，必须按以下优先级决策：
1. 优先复用已有共享组件
2. 优先遵守本规范中的组件一致性规则
3. 优先保证视觉层级、可读性与交互清晰度
4. 优先保持实现简洁、可维护
5. 最后才考虑额外的视觉修饰与美化
除非用户明确要求，否则不得为了“更炫”或“更特别”而破坏一致性。
---
## 铁律一：组件级一致性（Component Consistency）
### 核心原则
相同功能必须使用相同组件和相同交互模式。
禁止同类功能在不同页面中使用不同组件方案，导致系统割裂。
### 强制规范
1. **单一事实来源**
- 所有“选择一个选项”的交互，统一使用 Shadcn 的 `Select` 或 `DropdownMenu`
- **绝对禁止**使用原生 HTML `<select>`
- 所有弹窗、模态框，统一使用 Shadcn 的 `Dialog` 或 `AlertDialog`
- 所有按钮统一使用共享 `Button` 组件
- 严禁手写带完整视觉风格的原生 `<button>`
2. **按钮层级约束**
- 主操作：`Button variant="default"`
- 次操作：`Button variant="outline"`
- 弱化操作 / 辅助操作：`Button variant="ghost"`
3. **图标库约束**
- 全系统统一使用 `lucide-react`
- 默认 `strokeWidth={2}`
- 图标尺寸保持统一：
- 正文 / 主界面上下文：`size={16}`
- 辅助说明 / 次级信息：`size={14}`
4. **复用优先**
- 如果项目中已有可复用组件，必须优先复用
- 如果 `@/components/ui/*` 中已有对应组件，禁止重复实现功能相同的新组件
- 如果 Shadcn 默认模式已经能解决问题，不要擅自发明新的交互形式
---
## 铁律二：通过空间、底色与光影建立层级（Hierarchy via Space, Surface & Elevation）
### 核心原则
极简不等于没有边界。
界面必须通过留白、表面差异、轻量边框与阴影建立可感知的层级关系，避免所有模块“糊成一片”。
### 强制规范
1. **悬浮层必须有阴影**
- 下拉菜单、提示层、浮动工具栏、Popover、菜单、弹出面板等悬浮组件，必须具有阴影
- 统一使用：`shadow-md` 或 `shadow-lg`
2. **使用底色差异区分块面**
- 页面背景、侧边栏、主内容区、卡片、面板之间，必须存在轻微但明确的表面区分
- 示例：
- 页面画布：`bg-muted/30`
- 内容卡片：`bg-card`
3. **边框必须克制**
- 当必须使用边框时，统一使用低视觉权重边框：
- `border border-border/50`
- 禁止使用过重、过亮、过多的边框造成“边框套娃”
4. **内部结构分隔**
- 模块内部使用 `Separator`
- 或使用：
- `border-t border-border/40`
5. **优先通过留白建立关系**
- 分组与层级优先通过间距、块面、阴影、排版建立
- 不要优先依赖色块包裹和重边框来硬性分区
---
## 铁律三：排版即界面（Typography as Interface）
### 核心原则
视觉层级应首先由文字系统建立，而不是靠夸张背景色或装饰元素堆砌。
### 强制规范
1. **信息层级依赖字体系统**
- 使用字号建立层级：`text-sm`、`text-xs`
- 使用字重建立层级：`font-medium`、`font-semibold`
- 使用颜色建立层级：`text-foreground`、`text-muted-foreground`
2. **强调必须克制**
- 避免使用高饱和背景色块包裹普通文本进行强调
- 不要为了“突出”而让界面变吵
3. **标签与弱强调样式**
- Tag / Badge 使用低饱和、低对比、安静的表达方式
- 推荐样式：
- `bg-muted text-muted-foreground rounded-md px-2 py-1`
4. **优先使用文字层级而非装饰层级**
- 当需要区分标题、说明、元信息、注释时，优先调整字号、字重、颜色
- 不要优先增加块状背景、高亮边框、胶囊包裹等装饰性手法
---
## 铁律四：微交互的丝滑感（Fluid Micro-interactions）
### 核心原则
交互反馈必须统一、克制、清晰，不可突兀，不可完全没有反馈。
### 强制规范
1. **所有可交互元素具备统一过渡**
- 必须带有：
- `transition-all duration-200 ease-in-out`
2. **标准 Hover 态**
- 使用：
- `hover:bg-accent hover:text-accent-foreground`
- Hover 反馈必须明确，但不能过度夸张
3. **统一 Focus Rings**
- 所有输入框、按钮、可聚焦元素必须具有统一焦点光环：
- `focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring`
4. **交互反馈统一**
- 相似交互在不同页面中应保持一致的 hover、focus、open、selected 状态表达
- 不得同一系统中一部分组件有反馈、另一部分完全无反馈
---
## 组件选择决策规则（Component Decision Rules）
当需要选择组件时，默认按以下规则决策：
- 从列表中选择一个选项 → 使用 `Select`
- 从按钮触发一组操作菜单 → 使用 `DropdownMenu`
- 确认删除、危险操作、高风险操作 → 使用 `AlertDialog`
- 打开表单、详情、设置面板、普通弹窗 → 使用 `Dialog`
- 主操作按钮 → `Button variant="default"`
- 次操作按钮 → `Button variant="outline"`
- 弱化按钮 / 工具类按钮 → `Button variant="ghost"`
- 需要承载独立信息块 → 使用 `Card` 或 `bg-card` 容器
- 模块内部需要分隔两段内容 → 使用 `Separator`
如果不确定使用哪种组件，优先使用最保守、最通用、最一致的方案。
---
## 严格禁止项（Hard Prohibitions）
除非用户明确要求，否则以下行为一律禁止：
- 禁止使用原生 HTML `<select>`
- 禁止手写具有品牌视觉样式的原生 `<button>`
- 禁止引入新的图标库
- 禁止同一系统中混用多套弹窗方案
- 禁止相同功能使用不同交互模式
- 禁止使用高饱和背景色块强调普通文本
- 禁止以“极简”为理由去掉所有边界、层级和阴影
- 禁止在已有设计模式可复用时擅自发明新的间距、圆角、阴影体系
- 禁止在现有 Shadcn 组件可以解决问题时引入新的 UI 库
- 禁止为了视觉“花哨”而破坏整体统一性
- 禁止脱离现有组件体系重复造轮子
---
## 不确定时的默认策略（Default Behavior When Uncertain）
如果你不确定该如何实现，请严格遵守以下决策顺序：
1. 优先复用已有共享组件
2. 优先使用 `@/components/ui/*` 中已有组件
3. 优先使用 Shadcn 的默认交互模式
4. 优先选择克制、低噪音、低装饰性的样式
5. 优先保证可读性和一致性，而不是视觉新鲜感
6. 优先保证维护成本低，而不是局部“看起来更独特”
---
## 输出前自检（Self-Check Before Final Output）
在输出代码前，必须逐项检查以下内容：
1. 相同交互是否使用了相同组件模式？
2. 所有按钮是否都来自共享 `Button` 组件？
3. 所有下拉与选项交互是否都使用 `Select` 或 `DropdownMenu`？
4. 所有弹窗是否都使用 `Dialog` 或 `AlertDialog`？
5. 图标是否全部来自 `lucide-react`？
6. 所有可交互元素是否都具备：
- `transition-all duration-200 ease-in-out`
7. 所有可聚焦元素是否都具备：
- `focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring`
8. 所有悬浮层是否具备适度阴影：
- `shadow-md` 或 `shadow-lg`
9. 边框是否足够克制，而非过重？
10. 视觉层级是否主要通过排版、间距、底色和阴影建立？
11. 是否避免了高饱和色块和无意义装饰？
12. Light / Dark 模式下是否都具备良好可读性？
13. 是否已经优先复用了已有组件，而不是重新实现相同功能？
---
## 对 AI 开发者的最终执行指令
你在生成或重构任何界面时，必须始终记住：
- 目标不是单纯把页面“做出来”
- 目标是交付一个具有系统一致性、严谨层级、克制美感和高级质感的界面
- 一致性比新鲜感更重要
- 可读性比装饰性更重要
- 复用比重写更重要
- 克制比炫技更重要
如果存在已有组件，必须优先使用。
如果 Shadcn 能解决问题，不要自定义发明新的交互模式。
如果某种视觉选择不确定，优先选择更安静、更稳定、更一致的方案。
必须确保所有下拉、弹窗、菜单、浮层在 Light / Dark 模式下都具备优秀的可读性与层次感。