1. 复杂流向分析与桑基图（Sankey Diagram）在现代数据智能中的工程痛点

在企业级商业智能分析（BI）、用户体验全链路归因（Multi-Touch Attribution）、全站用户行为路径追踪（User Journey Flow）以及能源与资金流动分析中，桑基图（Sankey Diagram） 是最强大、信息密度最高的多阶段有向无环流向可视化图表。从 Google Analytics 4 的行为流报表到 Mixpanel 路径流转模型，桑基图能够以直观的“流带宽度（Flow Ribbon Width）”精准表达流量在不同阶段、不同触点之间的汇聚、分流与流失。

然而，在日常 UI/UX 设计与设计系统组件化落地过程中，桑基图几乎是所有可视化设计师与前端工程师公认“最难规范化与组件化”的图表之一：

1. 贝塞尔样条曲线（Bezier Curve）难以手动调优且易失真：桑基图中的连接带是由两条平行且保持等距的平滑三次贝塞尔曲线围合而成的流体区域。手动使用钢笔工具绘制极易导致流向带进出端口曲率不平滑、发生折角或宽窄畸变；
2. Auto Layout 弹性布局与等比流量宽度（Proportional Width）的内在冲突：每一阶段的节点柱（Node Bar）高度与连线宽度必须严格正比于该分支承载的业务量（如 PV、UV 或交易金额）。但 Figma 的 Auto Layout 自动布局 容器在自适应拉伸时，无法原生通过公式直接约束矢量曲线的端点厚度；
3. 多层级交叉流动导致视觉雪崩与图面脏乱：当业务阶段超过 4 级、分支超过 15 条时，流向带相互穿插交叠，若没有合理的透明度混合模式与层级排序策略，交集区域极易产生混浊发黑的色块；
4. 高亮与淡化交互态（Hover Focus & Dimming）设计资产维护成本极高：在数据看板中，用户悬停在某一特定节点上时，需要高亮该节点的所有关联上下游流向，并将其余无关流向降权淡化。静态画板往往需要复制 10~20 个全量画板来表达不同分支的高亮，极易产生海量设计债务；
5. 研发交付的数学与代码断层：前端团队无法通过切图落地桑基图，必须依赖 D3.js（d3-sankey）或 Apache ECharts 计算拓扑流向网格。如果设计稿中节点尺寸、间距与色值无法映射到清晰的数据实体（Nodes & Links），开发人员往往只能凭感觉重写，导致设计与工程严重脱节。

借助 Figma 的 Variables 变量系统、矢量网络与路径布尔运算 与 组件变体与属性，我们可以构建一套具备严密几何比例、支持 Hover 聚焦微交互且能与现代 Web 前端无缝同构的高保真桑基图组件体系。

---

2. 桑基图组件拓扑结构与流向网络几何架构

一套符合设计系统工程规范的桑基图组件由五大核心模块分层嵌套构建而成：阶段节点排版导轨（Stage Columns Grid）、节点柱原子（Node Bar Atom）、贝塞尔流向带图元（Flow Ribbon Layer）、端点数据徽标插槽（Metric Badge Slot） 与 顶层过滤与高亮控制坞（HUD Control Dock）。

Sankey Diagram Architecture System Shell (Frame / Auto Layout Horizontal, Space-Between)
├── Stage 1 Column: User Source (Auto Layout Vertical, Width: 180px, Gap: 16px)
│   ├── Node Bar Atom [Organic Search: 45,000 UV] (Height: 180px, Fill: #3B82F6)
│   ├── Node Bar Atom [Paid Ads: 30,000 UV] (Height: 120px, Fill: #10B981)
│   └── Node Bar Atom [Social Media: 25,000 UV] (Height: 100px, Fill: #F59E0B)
├── Flow Ribbon Layer 1-2 (Vector Overlay Frame, Absolute: Inset 0, Pointer-Events: None)
│   ├── Bezier Ribbon [Search -> Landing Page] (Cubic Bezier Path, Fill: #3B82F6, Opacity: 35%)
│   ├── Bezier Ribbon [Search -> Product Detail] (Cubic Bezier Path, Fill: #3B82F6, Opacity: 35%)
│   ├── Bezier Ribbon [Ads -> Landing Page] (Cubic Bezier Path, Fill: #10B981, Opacity: 35%)
│   └── Bezier Ribbon [Social -> Landing Page] (Cubic Bezier Path, Fill: #F59E0B, Opacity: 35%)
├── Stage 2 Column: Landing Step (Auto Layout Vertical, Width: 180px, Gap: 16px)
│   ├── Node Bar Atom [Home / Landing: 72,000 UV] (Height: 288px, Fill: #6366F1)
│   └── Node Bar Atom [Product Showcase: 28,000 UV] (Height: 112px, Fill: #8B5CF6)
├── Flow Ribbon Layer 2-3 (Vector Overlay Frame, Inset 0)
│   ├── Bezier Ribbon [Landing -> Add to Cart] (Height: 160px, Gradient Fill, Opacity: 35%)
│   └── Bezier Ribbon [Landing -> Drop-off] (Height: 128px, Fill: #EF4444, Opacity: 20%)
├── Stage 3 Column: Conversion / Exit (Auto Layout Vertical, Width: 180px, Gap: 16px)
│   ├── Node Bar Atom [Add to Cart / Checkout: 40,000 UV] (Height: 160px, Fill: #059669)
│   └── Node Bar Atom [Session Bounced / Exit: 60,000 UV] (Height: 240px, Fill: #94A3B8)
└── Sankey Analytics HUD Dock (Auto Layout Horizontal, Floating Top / Bottom)
    ├── Stage Selector Filter ("全部阶段 All Stages" | "核心主干 Main Path Only")
    ├── Metric Mode Switcher ("用户数 UV" | "转化率 %" | "流失率 Drop-off")
    └── Highlight Trace Pill ("当前聚焦: 搜索引擎 -> 核心首页 -> 最终加购")

---

3. 桑基图核心图元制作与视觉工程实操步骤

3.1 阶段节点柱（Stage Node Bar）的等比映射与 Auto Layout 弹性堆叠

节点柱的高度是桑基图量化展示的基础，必须遵循严格的像素-数值映射比例标尺（Scale Factor）：

1. 确立基准换算系数：
   • 设定全图画布可用垂直净高度为 600px，对应第一阶段总流量 $100,000\text{ UV}$，即换算比例为 $1\text{ px} = 166.6\text{ UV}$（或 $1,000\text{ UV} = 6\text{ px}$）；
   • 各节点高度公式：$H_{\text{node}} = \frac{\text{Value}}{100,000} \times 600\text{ px}$；
2. 封装 _Atom-Sankey-Node 组件：
   • 根容器创建 Auto Layout 横向排版，宽度固定为 16px（细柱型）或 140px（包含卡片文字的胶囊型）；
   • 左侧为竖向矩形颜色柱条（Width: 8px，圆角 Radius: 4px，Fill: 绑定品牌语义变量）；
   • 右侧包含两行排版文字：上方为主标题（如“自然搜索 Organic”），下方为数据度量（如“45,000 UV · 45.0%”），字号分别为 12px Medium 与 11px Regular；
3. 阶段列容器配置：
   • 将同一阶段的所有节点放入一个纵向 Auto Layout 容器中，对齐方式设为 Top-Left，间距设为 16px（固定呼吸空间）；
   • 多个阶段列横向排列，水平间距设为 180px~240px，预留充足的水平跨度用于容纳贝塞尔流向带的曲率演进。

3.2 贝塞尔平滑流向带（Bezier Flow Ribbon）的曲率推导与渐变着色

桑基图流向带的视觉核心在于优雅的三次贝塞尔平滑衔接（Cubic Bezier Transition）：

1. 三次贝塞尔锚点与切线推导：
   • 设源端节点输出端口起点为 $(X_1, Y_1)$，终点为 $(X_1, Y_1 + H_{\text{out}})$；目标端节点输入端口起点为 $(X_2, Y_2)$，终点为 $(X_2, Y_2 + H_{\text{in}})$；
   • 水平距离为 $\Delta X = X_2 - X_1$；
   • 绘制流向带的上轮廓线：从 $(X_1, Y_1)$ 出发，控制点 1 设为 $(X_1 + 0.5 \cdot \Delta X, Y_1)$，控制点 2 设为 $(X_2 - 0.5 \cdot \Delta X, Y_2)$，平滑终点为 $(X_2, Y_2)$；
   • 下轮廓线：从 $(X_2, Y_2 + H_{\text{in}})$ 回溯至 $(X_1, Y_1 + H_{\text{out}})$，控制点遵循相同的对称切线；
   • 使用 Figma 矢量网络与曲率编辑 将上下一对贝塞尔样条首尾闭合为闭合多边形区域；
2. 半透明源-汇双色线性渐变填充（Source-to-Target Gradient）：
   • 填充模式选择水平 Linear Gradient（从左端 $0%$ 到右端 $100%$）；
   • 左侧色标直接绑定源节点的品牌主色（如深海蓝 #3B82F6），不透明度设为 40%；
   • 右侧色标绑定目标节点的聚合主色（如紫色 #8B5CF6），不透明度同样设为 40%；
   • 这种半透明渐变能够在多条流向交织重叠时保持清透，用户视线能清晰捕捉到“支流汇入主流”的颜色演化轨迹。

3.3 悬浮指示图钉（Flow Hover Card）与绝对定位锚定

当需要查看具体某条流向支路的转化效率时，通过精巧的悬浮卡片提供下钻细节：

1. 悬浮卡片原子制作：
   • 横向 Auto Layout 容器，Padding 设为 8px 12px，圆角 8px，背景为纯白高漫反射卡片（Fill: #FFFFFF，Dark 模式切换为 #1E293B），叠加全局轻微投影 0 8px 24px rgba(0,0,0,0.12)；
   • 内嵌双行文字：“流向转化：自然搜索 → 核心落地页”，下一行带绿色高亮徽标：“32,400 UV (转化率 72.0%)”；
2. 绝对定位居中吸附：
   • 开启该卡片的 Absolute position，放置在贝塞尔流向带的中心拐点 $(\frac{X_1 + X_2}{2}, \frac{Y_1 + Y_2}{2})$ 位置；
   • 约束（Constraints）设为 Center + Center，确保无论外部画板如何进行响应式适配，指示浮层始终牢牢锚定在流向带的核心腰线上。

---

4. 桑基图核心拓扑模式与主流可视化图表对比矩阵

在数据产品与设计系统架构中，需根据数据结构特征准确选用流向类可视化形态：

评估维度	桑基图 (Sankey Diagram)	冲积图 (Alluvial Diagram)	平行坐标图 (Parallel Coordinates)	弦图 (Chord Diagram)
拓扑流向模型	多阶段有向无环图 (Directed Acyclic Graph)	跨阶段聚类演变与状态迁移网络	多维连续数值变量特征投射折线	单阶段内部实体间的双向网状互流
流量度量方式	带状区域等比宽度（进出总量守恒定律）	组块堆叠条带高度与占比迁移	单一折线在不同垂直坐标轴上的截距	环形外圈弧长与内部曲带宽度
Figma 布局机制	Auto Layout 阶段列 + 绝对定位闭合矢量带	模块化柱状变体 + 等宽堆叠容器	多根标尺垂直 Auto Layout + 折线图元	正圆同心导轨 + 极坐标曲率闭合贝塞尔
视觉复杂度	中高（需精准处理节点高度与带状曲率）	高（需处理分类集群重排与穿插）	中等（大量高密度半透明折线堆叠）	极高（全向双向曲线互相交织）
高亮与交互机制	路径单向/双向链式点亮，其余降权置灰	按类别分组批量高亮联动	滑块框选（Brush & Filter）区间过滤	单节点悬停高亮关联所有扇形辐射带
主流工程交付库	d3-sankey / echarts.sankey	d3-alluvial / RawGraphs	echarts.parallel / d3.parcoords	d3-chord / echarts.chord

---

5. Variables 状态机驱动的流向路径高亮与多维筛选联动

在交互原型演示或交付审查时，借助 Figma Variables 能够以极低成本模拟高保真 BI 看板的悬停高亮流转：

1. 建立 Sankey-Interactive-Tokens 变量集合：
   • sankey/activePath (String)：记录当前激活的路径标识符，如 'all'、'search_landing'、'ads_landing'；
   • sankey/dimOpacity (Number)：默认值 0.08（失焦非激活流向带的透明度，实现极致低对比降权）；
   • sankey/focusOpacity (Number)：默认值 0.85（高亮激活流向带的不透明度，实现视线聚焦）；
   • sankey/showDropoff (Boolean)：布尔开关，一键控制流失红色流向带（Red Drop-off Bands）的全局显隐；
2. 图层图元绑定条件逻辑表达式：
   • 选中第一阶段至第二阶段的“搜索引擎 → 落地页”流向带，将其不透明度属性绑定至条件表达式：
     • 若 activePath == 'all' || activePath == 'search_landing'，则应用 focusOpacity，否则应用 dimOpacity；
   • 选中对应的阶段节点柱，同样将其饱和度或边框高亮状态与 activePath 进行关联；
3. 结合 组件变体与属性：
   • 将整张桑基看板封装为 Charts/Sankey-Interactive 复合组件，对外暴露属性：FocusState = All | SearchFlow | AdsFlow | SocialFlow；
   • 在右侧属性面板一键切换，即可无需任何代码实时向产品与业务团队生动演示路径漏斗流转。

---

6. Dev Mode 前端工程代码同构与 D3-sankey / SVG 生产级落地

在 Dev Mode 研发协同 中，前端工程师接收到桑基图设计稿后，核心关注的是节点阵列与链路矩阵的数学拓扑结构。以下为基于生产级 TypeScript 与 D3-sankey 算法标准实现的 SVG 贝塞尔流向带渲染代码：

/**
 * 生产级桑基图流向生成引擎 (Sankey Flow Engine)
 * 对应 Figma 桑基图组件拓扑：基于三次贝塞尔曲线 (Cubic Bezier) 精确生成闭合 SVG 路径
 */
export interface SankeyNode {
  id: string;
  name: string;
  stage: number;
  value: number;
  x0: number; // 节点左边界 X 坐标
  x1: number; // 节点右边界 X 坐标
  y0: number; // 节点顶边界 Y 坐标
  y1: number; // 节点底边界 Y 坐标
  color: string;
}

export interface SankeyLink {
  source: SankeyNode;
  target: SankeyNode;
  value: number;
  y0: number;  // 流向带在源节点的垂直起始 Y 坐标
  y1: number;  // 流向带在目标节点的垂直起始 Y 坐标
  width: number; // 流向带根据流量等比换算的垂直厚度 (Stroke / Height)
}

/**
 * 1. 对应 Figma 贝塞尔流向带几何规范：计算闭合多边形 SVG Path 数据字符串
 */
export function generateSankeyRibbonPath(link: SankeyLink): string {
  const { source, target, y0, y1, width } = link;
  const x0 = source.x1; // 从源节点右侧边框射出
  const x1 = target.x0; // 进入目标节点左侧边框
  const halfDx = (x1 - x0) * 0.5; // 水平曲率控制点中点跨度

  // 上轮廓三次贝塞尔曲线：从 (x0, y0) 飞向 (x1, y1)
  const topCurve = `M ${x0} ${y0} C ${x0 + halfDx} ${y0}, ${x1 - halfDx} ${y1}, ${x1} ${y1}`;
  
  // 右边缘垂直向下移动流向带宽度
  const rightEdge = `L ${x1} ${y1 + width}`;
  
  // 下轮廓反向三次贝塞尔曲线：从 (x1, y1 + width) 平滑回溯至 (x0, y0 + width)
  const bottomCurve = `C ${x1 - halfDx} ${y1 + width}, ${x0 + halfDx} ${y0 + width}, ${x0} ${y0 + width}`;
  
  // 闭合路径回溯至起点
  return `${topCurve} ${rightEdge} ${bottomCurve} Z`;
}

/**
 * 2. 对应 Figma 渐变着色规范：生成双端色彩平滑渐变的 SVG LinearGradient 元素定义
 */
export function generateSvgGradients(links: SankeyLink[]): string {
  return links.map((link, index) => {
    const gradId = `sankey-grad-${index}`;
    return `
      <linearGradient id="${gradId}" gradientUnits="userSpaceOnUse" x1="${link.source.x1}" y1="0" x2="${link.target.x0}" y2="0">
        <stop offset="0%" stop-color="${link.source.color}" stop-opacity="0.45" />
        <stop offset="100%" stop-color="${link.target.color}" stop-opacity="0.45" />
      </linearGradient>
    `;
  }).join('\n');
}

---

7. 企业级桑基图设计系统治理与避坑指南

1. 坚决遵守节点总流出等于总流入的物理守恒准则：
   • 桑基图最忌讳“凭空产生或凭空消失的流量”。源节点的所有流出分支宽度之和，必须严格等于该节点的高度；若存在用户流失跳出，必须明确设计一根指向“流失/跳出（Drop-off）”的红色或灰色支流，严禁随意虚构连线尺寸；
2. 控制节点数量，严禁“蜘蛛网式”视觉雪崩：
   • 当单一阶段包含超过 6 个细分节点时，建议引入“其他长尾来源（Other Sources）”合并归并项，保持主干流转路径清晰可读；更多复杂数据图表性能优化策略可参考 Figma 常见报错与疑难故障诊断手册；
3. 避免极端流量比例导致的微小线条“不可点击与不可辨识”：
   • 当某一条支流占比低于 $0.5%$ 时，换算后的像素厚度可能不足 $1\text{ px}$。建议在组件中配置最小渲染阈值（如 minHeight = 2px），并在鼠标悬浮时展开 Tooltip 标注精准小数，避免图元完全消失；
4. 统一色彩语义与设计令牌标准：
   • 流向带的颜色严禁随机挑选，必须严格继承自源节点的色彩语义变量（如绿色表示正向转化通道、红色表示跳出损耗通道、橙色表示需复核流转通道）。整套色盘规范需同步收敛至 Figma 设计令牌规范，确保设计资产与前端代码库双向对齐。