@loom-framework/core 0.1.0-alpha.9 → 0.1.0-alpha.90

package/builtin-skills/antv-g2-chart/references/concepts/g2-concept-color-theory.md

@@ -0,0 +1,287 @@
+---
+id: "g2-concept-color-theory"
+title: "G2 配色理论"
+description: |
+  数据可视化中颜色的三种使用模式：分类色板（区分类别）、
+  顺序色阶（表示数值大小）、发散色阶（表示正负偏差）。
+  覆盖 G2 scale.color 配置方法和常见配色误用。
+
+library: "g2"
+version: "5.x"
+category: "concepts"
+tags:
+  - "配色"
+  - "color"
+  - "色板"
+  - "顺序色阶"
+  - "发散色阶"
+  - "分类色板"
+  - "palette"
+  - "scale.color"
+
+related:
+  - "g2-concept-visual-channels"
+  - "g2-core-encode-channel"
+  - "g2-theme-builtin"
+
+use_cases:
+  - "为不同数据类型选择正确的颜色模式"
+  - "配置 G2 scale.color 实现正确的颜色映射"
+  - "避免颜色误导数据读者"
+
+difficulty: "intermediate"
+completeness: "full"
+created: "2024-01-01"
+updated: "2025-03-01"
+author: "antv-team"
+---
+
+## 三种颜色使用模式
+
+### 1. 分类色板（Categorical Palette）
+
+**用途**：区分不同类别（定性数据），颜色之间**没有大小关系**
+
+```javascript
+// 场景：多系列折线图，用颜色区分产品线
+chart.options({
+  type: 'line',
+  data,
+  encode: { x: 'month', y: 'sales', color: 'product' },
+  // 默认就是分类色板，无需配置
+  // 如需自定义：
+  scale: {
+    color: {
+      type: 'ordinal',
+      range: ['#1890ff', '#52c41a', '#fa8c16', '#f5222d', '#722ed1'],
+    },
+  },
+});
+```
+
+**规则**：
+- 最多 **8 个**颜色，超过则难以区分
+- 颜色之间亮度相近（避免某类特别突出）
+- 考虑色盲友好性（红绿色盲常见，避免仅用红/绿区分）
+
+### 2. 顺序色阶（Sequential Scale）
+
+**用途**：表示数值从小到大，颜色从浅到深（或一种色调变化）
+
+```javascript
+// 场景：热力图、地图、气泡图的颜色深度
+chart.options({
+  type: 'cell',
+  data,
+  encode: { x: 'weekday', y: 'hour', color: 'count' },
+  scale: {
+    color: {
+      type: 'sequential',     // 顺序比例尺
+      palette: 'blues',        // 单色系：whites → blues
+      // 常用内置色阶：'blues' | 'greens' | 'oranges' | 'reds' | 'purples'
+      // 多色系：'YlOrRd' | 'YlGnBu' | 'BuPu' | 'GnBu'
+    },
+  },
+});
+```
+
+**规则**：
+- 数值越大 → 颜色越深（感知自然）
+- 使用**单色系**（同色调深浅变化）或**多色系渐变**
+- 不要用分类色板表示数值（红/绿没有大小感）
+
+### 3. 发散色阶（Diverging Scale）
+
+**用途**：表示以零（或某基准值）为中心的正负偏差
+
+```javascript
+// 场景：盈亏热力图、同比增减、差异对比
+chart.options({
+  type: 'cell',
+  data,
+  encode: { x: 'product', y: 'region', color: 'growth' },
+  scale: {
+    color: {
+      type: 'diverging',      // 发散比例尺
+      palette: 'RdBu',        // 红（负）→ 白（零）→ 蓝（正）
+      // 常用：'RdBu' | 'RdYlGn' | 'BrBG' | 'PuOr'
+      domain: [-100, 0, 100], // 对称范围（中间是 0）
+    },
+  },
+});
+```
+
+**规则**：
+- 中性值（零/平均值）映射为**白色或浅灰**
+- 两端颜色**感知强度相当**（避免一端视觉更突出）
+- 定义对称的 domain（如 `[-50, 0, 50]`）
+
+## 颜色通道与比例尺配置
+
+```javascript
+// G2 完整颜色配置
+scale: {
+  color: {
+    // ── 比例尺类型 ────────────────────────
+    type: 'ordinal',     // 分类：'ordinal'
+    // type: 'sequential', // 连续顺序
+    // type: 'diverging',  // 发散
+    // type: 'threshold',  // 分段阈值
+
+    // ── 颜色范围（分类色板）────────────────
+    range: ['#1890ff', '#52c41a', '#fa8c16'],   // 自定义颜色列表
+
+    // ── 内置色板名称 ──────────────────────
+    palette: 'tableau10',   // 'tableau10' | 'category10' | 'blues' 等
+
+    // ── 域（分类的显示顺序）───────────────
+    domain: ['产品A', '产品B', '产品C'],
+
+    // ── 未知值颜色 ────────────────────────
+    unknown: '#f0f0f0',
+  },
+}
+```
+
+## 内置色板完整参考
+
+**⚠️ 重要：只能使用下表中列出的名称**。G2 的 `palette` 通过 d3-scale-chromatic 查找，不在此列表中的名称（如 `'blueOrange'`、`'redGreen'`、`'heatmap'`、`'hot'`、`'jet'`）会在运行时报错 `Unknown palette`，图表无法渲染。名称大小写不敏感（`'blues'` 和 `'Blues'` 均可）。
+
+### 分类色板（ordinal scale 用，区分类别）
+
+| 色板名 | 颜色数 | 风格 |
+|-------|--------|------|
+| `'tableau10'` | 10 | Tableau 经典配色（柔和，默认） |
+| `'category10'` | 10 | D3 经典分类色 |
+| `'set2'` | 8 | 粉彩风格，温和 |
+| `'paired'` | 12 | 成对颜色（浅+深） |
+| `'dark2'` | 8 | 深色调，高对比 |
+| `'set1'` | 9 | 高饱和度 |
+| `'set3'` | 12 | 中等饱和度 |
+| `'pastel1'` | 9 | 淡彩色 |
+| `'pastel2'` | 8 | 淡彩色 |
+| `'accent'` | 8 | 强调色 |
+
+### 顺序色阶（sequential scale 用，正值数值映射）
+
+| 色板名 | 效果 |
+|-------|------|
+| `'blues'` | 白→蓝 |
+| `'greens'` | 白→绿 |
+| `'reds'` | 白→红 |
+| `'oranges'` | 白→橙 |
+| `'purples'` | 白→紫 |
+| `'greys'` | 白→灰 |
+| `'ylOrRd'` | 黄→橙→红（热力图常用） |
+| `'ylGnBu'` | 黄→绿→蓝（sequential 默认值） |
+| `'ylOrBr'` | 黄→橙→棕 |
+| `'buGn'` | 蓝→绿 |
+| `'buPu'` | 蓝→紫 |
+| `'gnBu'` | 绿→蓝 |
+| `'orRd'` | 橙→红 |
+| `'puBu'` | 紫→蓝 |
+| `'puBuGn'` | 紫→蓝→绿 |
+| `'puRd'` | 紫→红 |
+| `'rdPu'` | 红→紫 |
+| `'ylGn'` | 黄→绿 |
+| `'viridis'` | 紫→蓝→绿→黄（感知均匀，**色盲友好**，推荐）|
+| `'plasma'` | 蓝紫→橙黄 |
+| `'magma'` | 黑→紫→橙→白 |
+| `'inferno'` | 黑→紫→红→黄 |
+| `'cividis'` | 蓝→黄（对所有色盲类型友好） |
+| `'turbo'` | 蓝→绿→黄→红（彩虹改进版） |
+| `'warm'` | 橙→红→紫（暖色） |
+| `'cool'` | 青→蓝→紫（冷色） |
+| `'rainbow'` | 彩虹（感知不均匀，不推荐） |
+| `'sinebow'` | 平滑彩虹 |
+| `'cubehelixDefault'` | 螺旋渐变 |
+
+### 发散色阶（diverging scale 用，正负值对比）
+
+| 色板名 | 效果 |
+|-------|------|
+| `'rdBu'` | 红→白→蓝（**最常用**，涨跌/正负） |
+| `'rdYlBu'` | 红→黄→蓝 |
+| `'rdYlGn'` | 红→黄→绿（同比增减） |
+| `'rdGy'` | 红→白→灰 |
+| `'pRGn'` | 紫→白→绿 |
+| `'piYG'` | 粉红→白→黄绿 |
+| `'puOr'` | 紫→白→橙 |
+| `'brBG'` | 棕→白→蓝绿 |
+| `'spectral'` | 红→橙→黄→绿→蓝（多色发散） |
+
+## 色盲友好配色
+
+约 8% 的男性有红绿色盲，应避免仅用红/绿区分数据：
+
+```javascript
+// ❌ 不友好：红/绿区分（色盲用户无法区分）
+scale: { color: { range: ['#ff4d4f', '#52c41a'] } }
+
+// ✅ 友好：使用蓝/橙（色盲可区分）
+scale: { color: { range: ['#1890ff', '#fa8c16'] } }
+
+// ✅ 也可以同时用颜色+形状双通道编码
+chart.options({
+  type: 'point',
+  encode: {
+    color: 'category',
+    shape: 'category',   // 同时用形状区分（不依赖颜色）
+  },
+});
+```
+
+## 常见颜色错误
+
+### 错误 1：用分类色板表示数值（热力图）
+
+```javascript
+// ❌ 用分类色（红/蓝/绿）表示数值大小，毫无规律感
+chart.options({
+  type: 'cell',
+  encode: { color: 'temperature' },
+  scale: { color: { type: 'ordinal' } },   // ❌ 数值用了分类色板
+});
+
+// ✅ 数值用顺序色阶
+chart.options({
+  type: 'cell',
+  encode: { color: 'temperature' },
+  scale: { color: { type: 'sequential', palette: 'YlOrRd' } },   // ✅
+});
+```
+
+### 错误 2：发散色阶域不对称
+
+```javascript
+// ❌ 域不对称，零点不在颜色中点
+scale: {
+  color: {
+    type: 'diverging',
+    palette: 'RdBu',
+    domain: [-20, 100],   // ❌ 负值范围小，零点偏左
+  },
+}
+
+// ✅ 对称的域，零点在中心
+scale: {
+  color: {
+    type: 'diverging',
+    palette: 'RdBu',
+    domain: [-100, 0, 100],   // ✅ 明确指定三个控制点
+  },
+}
+```
+
+### 错误 3：颜色过多导致混淆
+
+```javascript
+// ❌ 12 个颜色，读者无法区分
+chart.options({
+  encode: { color: 'province' },   // 31个省份
+});
+
+// ✅ 分组或合并，保持 ≤ 8 个颜色类别
+// 方案：取 Top 7 + "其他"
+const processedData = aggregateTopN(data, 'province', 7);
+```

package/builtin-skills/antv-g2-chart/references/concepts/g2-concept-visual-channels.md

@@ -0,0 +1,180 @@
+---
+id: "g2-concept-visual-channels"
+title: "G2 视觉通道（Visual Channels）"
+description: |
+  视觉通道是数据属性到视觉属性的映射方式，包括位置、颜色、大小、形状、方向等。
+  理解各通道的感知效率和适用数据类型，有助于设计更准确、更有效的数据可视化。
+  这是 G2 encode 配置设计的理论基础。
+
+library: "g2"
+version: "5.x"
+category: "concepts"
+tags:
+  - "视觉通道"
+  - "visual channels"
+  - "encode"
+  - "感知效率"
+  - "数据映射"
+  - "可视化设计"
+  - "颜色"
+  - "大小"
+  - "位置"
+
+related:
+  - "g2-core-encode-channel"
+  - "g2-concept-color-theory"
+
+use_cases:
+  - "理解 G2 encode 各通道的设计原理"
+  - "为不同数据类型选择合适的视觉通道"
+  - "避免感知效率低的通道误用"
+
+difficulty: "intermediate"
+completeness: "full"
+created: "2024-01-01"
+updated: "2025-03-01"
+author: "antv-team"
+---
+
+## 核心概念
+
+视觉通道（Visual Channel）是将**数据属性**映射到**视觉属性**的媒介。G2 中通过 `encode` 字段完成这种映射：
+
+```javascript
+chart.options({
+  encode: {
+    x: 'month',      // 位置通道（x轴）← 分类字段
+    y: 'revenue',    // 位置通道（y轴）← 数值字段
+    color: 'product',// 颜色通道 ← 分类字段
+    size: 'amount',  // 大小通道 ← 数值字段
+  },
+});
+```
+
+## 主要视觉通道及其感知效率
+
+### 定量数据（连续数值）
+
+按感知精确度从高到低排序：
+
+| 排名 | 通道 | G2 对应 | 说明 |
+|------|------|---------|------|
+| ★★★★★ | **位置（x/y轴）** | `encode.x`, `encode.y` | 最精确，人眼可精确比较 |
+| ★★★★ | **长度/高度** | `encode.y`（柱状图） | 次精确，需共同基线 |
+| ★★★ | **面积/大小** | `encode.size` | 中等，适合气泡图相对比较 |
+| ★★ | **颜色深浅** | `encode.color`（连续色阶）| 较难精确比较，仅适合粗略趋势 |
+| ★ | **角度** | 饼图扇区角度 | 人眼对角度判断不精确，慎用 |
+
+### 分类数据（离散类别）
+
+| 通道 | G2 对应 | 适用场景 |
+|------|---------|---------|
+| **位置分组** | `encode.x`（分类轴） | 柱状图、折线图的分类 |
+| **颜色（色相）** | `encode.color` | 区分≤8个类别，超过易混淆 |
+| **形状** | `encode.shape` | 散点图区分类别，≤6个 |
+| **纹理/图案** | `encode.shape`（自定义）| 无色环境或辅助区分 |
+
+## 通道适配规则
+
+```
+定量数据（数值）→ 优先：位置轴（x/y）> 大小（size）> 颜色深度（连续色）
+分类数据（类别）→ 优先：位置轴（x/y）> 颜色色相（color）> 形状（shape）
+有序数据（排名）→ 优先：位置轴（顺序）> 大小（递减）> 颜色（渐变色）
+```
+
+## 通道组合示例
+
+### 气泡图：3个数值通道
+
+```javascript
+// x位置 + y位置 + 大小（size） = 三维数值编码
+chart.options({
+  type: 'point',
+  data,
+  encode: {
+    x: 'GDP',          // 定量 → 位置（最精确）
+    y: 'LifeExpectancy',// 定量 → 位置
+    size: 'Population', // 定量 → 大小（第三维度）
+    color: 'Region',    // 分类 → 颜色色相（第四维度）
+  },
+  scale: {
+    size: { range: [4, 40] },   // 气泡大小范围
+  },
+});
+```
+
+### 热力图：颜色深度编码数值
+
+```javascript
+// 颜色用于定量数据时，应使用顺序色阶（浅→深），不用分类色板
+chart.options({
+  type: 'cell',
+  data,
+  encode: {
+    x: 'weekday',
+    y: 'hour',
+    color: 'value',     // 定量 → 颜色深浅（连续色阶）
+  },
+  scale: {
+    color: {
+      type: 'sequential',
+      palette: 'blues',  // 顺序色阶（而非分类色板）
+    },
+  },
+});
+```
+
+## 常见通道误用
+
+### 误用 1：用颜色色相表示数值大小
+
+```javascript
+// ❌ 误用：颜色色相（红/绿/蓝）不能表达数值大小关系
+chart.options({
+  encode: { color: 'temperature' },   // temperature 是数值，用色相无法体现大小
+  scale: { color: { type: 'ordinal' } },   // ❌ 分类色板用于数值
+});
+
+// ✅ 正确：数值用连续色阶
+chart.options({
+  encode: { color: 'temperature' },
+  scale: {
+    color: {
+      type: 'sequential',   // 顺序比例尺
+      palette: 'reds',      // 浅→深的顺序色
+    },
+  },
+});
+```
+
+### 误用 2：颜色类别过多导致难以区分
+
+```javascript
+// ❌ 超过 8 个颜色类别，人眼难以区分
+chart.options({
+  encode: { color: 'province' },   // 如果有 31 个省份，颜色无法有效区分
+});
+
+// ✅ 超过 8 类时的替代方案：
+// 1. 合并次要类别为"其他"
+// 2. 改用位置通道（分组柱状图/分面）
+// 3. 使用交互过滤（点击图例显示/隐藏）
+```
+
+### 误用 3：饼图扇区过多
+
+```javascript
+// ❌ 角度通道感知精度低，超过 5 个扇区难以比较
+chart.options({
+  type: 'interval',
+  coordinate: { type: 'theta' },
+  // 如果有 10+ 个分类，饼图效果很差
+});
+
+// ✅ 分类多时改用柱状图（位置通道感知更精确）
+chart.options({
+  type: 'interval',
+  encode: { x: 'category', y: 'value' },
+  transform: [{ type: 'sortX', by: 'y', reverse: true }],
+});
+```

package/builtin-skills/antv-g2-chart/references/coordinates/g2-coord-cartesian.md

@@ -0,0 +1,131 @@
+---
+id: "g2-coord-cartesian"
+title: "G2 直角坐标系（cartesian）"
+description: |
+  cartesian（直角坐标系）是 G2 v5 的默认坐标系，x 和 y 通道分别映射为水平和垂直位置。
+  大多数常见图表（柱状图、折线图、散点图）均使用直角坐标系。
+  通过 coordinate.transform 可以为直角坐标系添加转置（transpose）等变换。
+
+library: "g2"
+version: "5.x"
+category: "coordinates"
+tags:
+  - "cartesian"
+  - "直角坐标系"
+  - "默认坐标系"
+  - "coordinate"
+  - "笛卡尔坐标"
+
+related:
+  - "g2-coord-transpose"
+  - "g2-coord-polar"
+  - "g2-mark-interval-basic"
+  - "g2-mark-line-basic"
+
+use_cases:
+  - "柱状图（默认直角坐标）"
+  - "折线图（默认直角坐标）"
+  - "条形图（直角坐标 + 转置）"
+  - "散点图（直角坐标）"
+
+difficulty: "beginner"
+completeness: "full"
+created: "2025-03-24"
+updated: "2025-03-24"
+author: "antv-team"
+source_url: "https://g2.antv.antgroup.com/manual/core/coordinate/cartesian"
+---
+
+## 核心概念
+
+直角坐标系是 G2 的**默认坐标系**，无需显式配置 `coordinate` 字段。
+
+- x 通道 → 水平位置（从左到右）
+- y 通道 → 垂直位置（从下到上）
+- 支持通过 `coordinate.transform` 添加转置等变换
+
+## 默认使用（无需配置）
+
+```javascript
+import { Chart } from '@antv/g2';
+
+// 直角坐标系是默认值，不需要写 coordinate 配置
+const chart = new Chart({ container: 'container', width: 640, height: 480 });
+
+chart.options({
+  type: 'interval',
+  data: [
+    { genre: 'Sports',   sold: 275 },
+    { genre: 'Strategy', sold: 115 },
+    { genre: 'Action',   sold: 120 },
+  ],
+  encode: { x: 'genre', y: 'sold' },
+  // 无需 coordinate 配置，默认即为直角坐标系
+});
+
+chart.render();
+```
+
+## 显式指定（与默认等效）
+
+```javascript
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'genre', y: 'sold' },
+  coordinate: { type: 'cartesian' },  // 显式指定（与不写等效）
+});
+```
+
+## 直角坐标系 + 转置（条形图）
+
+```javascript
+chart.options({
+  type: 'interval',
+  data,
+  encode: { x: 'genre', y: 'sold' },
+  coordinate: {
+    type: 'cartesian',
+    transform: [{ type: 'transpose' }],  // 转置：x/y 互换，柱状图变条形图
+  },
+});
+```
+
+## 坐标系配置项
+
+```javascript
+chart.options({
+  coordinate: {
+    type: 'cartesian',
+    transform: [
+      { type: 'transpose' },         // 转置（x↔y 互换）
+      { type: 'reflect', x: true },  // X 轴镜像翻转
+      { type: 'reflect', y: true },  // Y 轴镜像翻转
+      { type: 'scale', sx: 1, sy: -1 },  // 自定义缩放
+    ],
+  },
+});
+```
+
+## 常见错误与修正
+
+### 错误：配置了 cartesian 坐标系但期望得到环形图
+```javascript
+// ❌ 错误：饼图/环形图需要 theta 坐标系，不是 cartesian
+chart.options({
+  type: 'interval',
+  data,
+  encode: { y: 'value', color: 'type' },
+  transform: [{ type: 'stackY' }],
+  coordinate: { type: 'cartesian' },  // ❌ 这样会画出普通柱状图
+});
+
+// ✅ 饼图/环形图使用 theta 坐标系
+chart.options({
+  type: 'interval',
+  data,
+  encode: { y: 'value', color: 'type' },
+  transform: [{ type: 'stackY' }],
+  coordinate: { type: 'theta', outerRadius: 0.8, innerRadius: 0.5 },  // ✅
+});
+```