# 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. 变更规则
任何新增组件或样式改动，必须同步更新本文件对应条目。