update at 2026-02-13 08:42:56

FRONTEND_GUIDELINES.md

@@ -0,0 +1,110 @@
+# FRONTEND_GUIDELINES.md
+
+## 1. 目的
+定义 Web 与小程序端 UI 的统一视觉与交互规范，避免样式漂移。
+
+关联文档：
+- PRD.md
+- APP_FLOW.md
+
+## 2. 设计基线
+- 设计来源：Figma 对应节点（Web 与小程序骨架）
+- 风格关键词：工具化、轻量、高密度信息、低装饰
+- 基础布局：顶部工具栏 + 左侧映射面板 + 右侧预览面板
+
+## 3. 设计令牌（Web）
+
+### 3.1 颜色变量（`src/styles.css`）
+- `--primary-7: #8552A1`
+- `--primary-6: #9B6BC2`
+- `--fill-1: #F7F8FA`
+- `--fill-3: #E5E6EB`
+- `--fill-4: #C9CDD4`
+- `--text-1: #FFFFFF`
+- `--text-3: #86909C`
+- `--text-4: #4E5969`
+- `--danger-3: #FBACA3`
+
+### 3.2 字体
+- 主字体变量：`--font-pingfang`
+- 字体栈：`PingFang SC`, `Hiragino Sans GB`, `Microsoft YaHei`, `sans-serif`
+- 默认字号：12 / 14 / 16 / 18 / 20 / 24 / 28
+
+### 3.3 圆角
+- 工具类组件：`4px`、`6px`、`8px`
+- 主卡片：`16px`
+- 主题弹窗：`24px 24px 0 0`
+- 胶囊控件：`999px`
+
+### 3.4 间距尺度
+建议仅使用以下值（已在现有样式大量出现）：
+- `2, 4, 6, 8, 10, 12, 16, 18, 24`
+
+## 4. 主题系统
+- 主题源：`src/theme-presets.ts`
+- 每个主题包含：`id + name + 10色数组`
+- 默认主题：`figma-violet`
+- 主题应用范围：Sankey 节点颜色轮换
+
+## 5. 组件规范（Web）
+
+### 5.1 顶部工具栏
+- 包含：Logo、主题选择、上传入口、导出入口
+- 上传区需支持点击与拖拽
+- 导出区固定显示 SVG/PNG 两个动作按钮
+
+### 5.2 左侧映射面板
+- 分组：`源数据`、`目标数据`
+- 子块：
+  - 源数据-数据列（单选）
+  - 源数据-描述列（多选）
+  - 目标数据-描述列（多选）
+  - 目标总和显示开关（复选）
+- 每个子块支持展开/折叠
+- 行高基线：`32px`
+
+### 5.3 预览面板
+- 标题：`桑基图预览`
+- 控件：`gap`、`padding` 滑块 + 方向开关
+- 图表容器最小高度：
+  - 桌面：`480px`
+  - 中屏：`360px`
+- 告警与错误文本必须显示在图表区域外，避免遮挡图
+
+### 5.4 主题弹窗
+- 定位：`fixed`
+- 需要视口边界钳制
+- 点击外部自动关闭
+- 选中项透明度 100%，非选中项按距离降低
+
+## 6. 响应式规则
+- 断点 A：`max-width: 1024px`
+  - 顶栏竖排
+  - 主区从双栏改为单栏
+  - 左侧卡片支持换行
+- 断点 B：`max-width: 640px`
+  - 页面内边距缩小
+  - Logo、标题、标题文字按移动端尺寸缩放
+
+## 7. 图表视觉规则
+- 背景色：`#f7f8fa`
+- 节点宽度：`14`
+- 连线：`color='source'`, `curveness=0.45`, `opacity=0.45`
+- 标签字体大小：`12`
+
+## 8. 图标与资源
+- 图标目录：`assets/icons/`
+- Web 与 miniapp 共用同一套图标资源命名
+- 禁止在组件中硬编码新的图标路径
+
+## 9. 可访问性与可读性
+- 关键图标必须有 `alt` 文本
+- 错误文本颜色与普通文本明显区分
+- 文本截断区域需保留可读主体（列名优先显示前缀）
+
+## 10. 小程序样式约束（当前）
+- 仅用于骨架视觉对齐，不作为完整功能规范
+- 维持与 Web 一致的色板、图标命名和信息分区
+
+## 11. 变更规则
+任何新增组件或样式改动，必须同步更新本文件对应条目。