explainer-visuals

解说类可视化

创建动画和交互式可视化，让复杂概念变得直观易懂。

理念

优秀的解说类可视化不仅是图解，更能揭示事物。它们展现隐藏在复杂性中的结构、静态描述中蕴含的动态，以及文字难以传达的关系。

核心原则：

• 循序渐进地增加复杂度：从简单开始，通过交互或动画逐步添加层次
• 有语义的动态效果：运动承载意义，而不只是吸引注意力
• 静止时也清晰易读：静态状态能够传达核心概念
• 渐进式呈现：让观看者掌控探索的深度

探索流程

创建任何可视化之前，先使用 AskUserQuestion 进行简短的需求访谈。不仅要了解要可视化什么，还要了解为什么这个概念需要通过可视化来呈现。

探索问题

从以下类别中选择 1–2 个有针对性的问题：

理解概念：

• “观看者最应该记住的一个核心见解是什么？”
• “仅用文字解释这个概念，难点在哪里？”
• “是否存在需要通过这个可视化纠正的常见误解？”

了解背景：

• “这会出现在文章的哪个位置？（开篇引入、佐证、高潮揭示、总结）”
• “周围内容的语气是什么？（学术、轻松对话、挑衅、指导）”

了解受众：

• “读者对这个主题已经了解多少？”
• “希望它带来快速的顿悟，还是可深入探索的体验？”

只有在用户已经提供了丰富的目标背景时，才跳过探索环节。

可视化格式选择

根据概念的性质选择格式：

概念类型	最佳格式	原因
转变／变化	变形动画	将前→后展现为连续过程
层级／结构	可缩放矩形树图或嵌套图	通过交互揭示层次
过程／流程	带进度控制条的分步动画	用户可控制揭示的节奏
比较	并排同步动画	并行结构凸显差异
累积／增长	逐步构建动画	每个元素都在前一个基础上增加
关系／网络	力导向图	揭示涌现的结构
分布／比例	动态单元图或华夫图	让数量变得具体可感
循环／反馈	带入口点的循环动画	展现系统的持续运作
时间线／顺序	带注释的水平滚动	符合自然的阅读方向
空间／地理	带缩放功能的注释地图	将抽象概念置于实体空间中
心智模型	基于隐喻的图示	将抽象概念与熟悉事物联系起来
权衡／张力	由滑块控制的平衡关系	展示相互依存关系

设计系统

字体排印

font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;

--text-hero: 2rem;      /* Single key number or word */
--text-title: 1.25rem;  /* Visual title */
--text-label: 0.875rem; /* Axis labels, annotations */
--text-micro: 0.75rem;  /* Secondary details */

配色方案

极简（默认）：

--ink: #1a1a2e;        /* Primary elements */
--ink-light: #4a4a68;  /* Secondary elements */
--accent: #e94560;     /* Single highlight */
--ground: #fafafa;     /* Background */
--ground-alt: #f0f0f5; /* Alternate regions */

数据丰富型（用于展示类别时）：

--cat-1: #4e79a7; --cat-2: #f28e2c; --cat-3: #e15759;
--cat-4: #76b7b2; --cat-5: #59a14f; --cat-6: #af7aa1;

适应文章背景：

• 技术／分析型 → 偏冷色调、对比更强
• 个人／反思型 → 偏暖色调、边缘更柔和
• 挑衅／挑战型 → 更醒目的强调色、更高的饱和度

动效原则

const EASE = {
  standard: 'cubic-bezier(0.4, 0, 0.2, 1)',  // Smooth, natural
  enter: 'cubic-bezier(0, 0, 0.2, 1)',       // Start fast, settle
  exit: 'cubic-bezier(0.4, 0, 1, 1)',        // Start slow, accelerate
  bounce: 'cubic-bezier(0.34, 1.56, 0.64, 1)' // Slight overshoot
};

const DURATION = {
  micro: 100,    // Color, opacity
  fast: 200,     // Small movements
  medium: 350,   // Standard transitions
  slow: 500,     // Large movements
  dramatic: 800  // Major reveals
};

动效语义：

• 淡入／淡出 = 存在（出现／消失）
• 缩放 = 重要性（强调／弱化）
• 平移 = 关系（组合／分离）
• 变形 = 身份（转换）
• 旋转 = 状态（切换、循环）

技术选择

选择能够实现效果的最简单工具：

复杂度	工具	适用场景
简单	纯 CSS	状态转换、悬停、基础变换
标准	原生 JS + CSS	序列动画、滚动触发、简单交互
复杂	GSAP	时间线序列、物理效果、SVG 变形
数据驱动	D3.js	力导向布局、地图、数据绑定转换

对于大多数解说类可视化，原生 JS + CSS 就足够了。

代码结构

每个可视化都是一个独立的 HTML 文件：

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Visual: [Concept Name]</title>
  <style>
    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
    :root { /* Design tokens */ }
    /* Component styles */
  </style>
</head>
<body>
  <figure class="explainer-visual" role="img" aria-label="[Description]">
    
    <figcaption class="visually-hidden">[Accessible description]</figcaption>
  </figure>
  <script>
    // Animation and interaction logic
  </script>
</body>
</html>

无障碍要求

.visually-hidden {
  position: absolute; width: 1px; height: 1px;
  padding: 0; margin: -1px; overflow: hidden;
  clip: rect(0, 0, 0, 0); border: 0;
}

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}

每个可视化都必须包含：

1. 容器上的 role="img" aria-label="..."
2. .visually-hidden 说明中的完整文本替代内容
3. 遵循 prefers-reduced-motion
4. 可通过键盘访问的交互
5. 可见的焦点状态

模式参考

请参阅 references/patterns.md 了解实现模式：

• 形状变形过渡
• 滚动驱动的叙事
• 交互式滑块图表
• 带注释的逐步动画
• 力导向关系图
• 单位图表／华夫饼图动画

交付

输出为单个 HTML 文件，并满足以下要求：

1. 完全独立（内联所有 CSS/JS）
2. 可直接在浏览器中打开运行
3. 可通过 iframe 嵌入
4. 包含解释关键决策的注释

对于依赖库的可视化（D3、GSAP），请包含带有完整性哈希的 CDN 链接。

质量检查清单

交付前：

• 静态状态能传达核心思想
• 动画能揭示见解，而非仅作装饰
• 交互易于发现（光标提示、悬停状态）
• 可在移动设备上使用（适配触控、响应式）
• 提供减少动态效果的替代方案
• 无障碍说明完整
• 代码包含便于后续修改的注释
• 文件大小合理（简单项目 <100KB，复杂项目 <500KB）