Visualization

This Skill owns how Ankole selects a visual grammar, applies palette and directional conventions, embeds live charts in Pod pages and Applets, writes <mermaid> and <infographic> diagram blocks, and exports publication-grade SVG or PNG figures with ankole-viz.

Read /drive/DESIGN.md (or the workspace design contract) first when styling standalone deliverables. Read only the reference file under references/ that matches the visual grammar you need:

• references/statistical-g2.md — categorical, temporal, distribution, dual-axis, hierarchical, and flow charts (AnkoleChart, Base chart view, ankole-viz chart)
• references/financial-kline.md — OHLCV candlesticks, intraday baselines, synchronized volume/MACD/RSI sub-panes, trade markers, and yield curves (AnkoleFinancialChart, recordsToFinancialSeries, ankole-viz kline)
• references/infographic-dsl.md — structured narrative diagrams, SWOT, timelines, roadmaps, and comparison trees (<infographic>, AnkoleInfographic, ankole-viz infographic)
• references/graph-g6.md — entity-relationship networks, hierarchies, radial neighborhoods, and combo clusters (AnkoleGraph, ankole-viz graph)
• references/mermaid.md — procedural flowcharts, sequence diagrams, state machines, and ER diagrams (<mermaid>, ankole-viz mermaid)

Choose the right grammar and surface

Match the cognitive question to one grammar first, then pick the delivery surface:

Cognitive question	Visual grammar	Pod / Chat / Knowledge surface	Offline file export (background_job)
Headline KPI and delta	Stat & sparkline	Base chart (stat), Applet AnkoleStatCard + AnkoleSparkline	ankole-viz chart or native table/card
Category comparison, trend, share, correlation, distribution	Statistical (AntV G2 v5)	Single-table: Base chart view + Doc <embed>. Multi-table or custom: Applet AnkoleChart	ankole-viz chart --spec ... --data ... -o fig.svg
OHLCV price action, session gaps, indicators, yield curve	Financial (Lightweight Charts v5)	Applet AnkoleFinancialChart	ankole-viz kline --spec ... --data ... -o kline.png
Multi-hop topology, clusters, hierarchy	Network graph (AntV G6 v5)	Applet AnkoleGraph	ankole-viz graph --spec ... --data ... -o graph.svg
Stages, SWOT, pros/cons, executive takeaways	Narrative infographic (@antv/infographic)	Doc <infographic> (```infographic), Chat ```infographic, Applet AnkoleInfographic	ankole-viz infographic --input ... -o info.svg
Branching control flow, RPC sequence, state transitions, schema ER	Procedural diagram (Mermaid via Pele)	Doc <mermaid>, Knowledge ```mermaid, Chat ```mermaid	ankole-viz mermaid --input ... -o flow.svg

Never convert an explicit flow, sequence, state machine, or ER diagram into ASCII box art (+---+, |-->|), and never fabricate raw SVG coordinates by hand when one of these grammars expresses the structure directly.

Palette and directional rules

1. Categorical series & 1D focus: Honor explicit :select field option colors first; otherwise assign {colors.chart-1} through {colors.chart-5} (Cobalt, Celadon, Ochre, Berry, Mulberry — Okabe–Ito CUD separable across protanopia, deuteranopia, and tritanopia) in global rank order. For 1D column or bar rankings without a second series dimension or explicit option colors, keep all regular bars in uniform {colors.chart-1} so length carries magnitude without decorative rainbow hues, while coloring "Other" (--chart-other) and unassigned null / "Empty" (--chart-empty) in distinct neutral grays. Never merge missing values into "Other", and never treat 0 or false as empty.
2. Continuous & diverging scales: Sequential heatmaps use monotonic luminance ramps matched to figure-ground polarity (dark-is-more on light paper, light-is-more on dark graphite). Mixed negative-and-positive heatmaps automatically switch to a zero-anchored symmetric diverging scale (--chart-down ↔ neutral surface 0 ↔ --chart-up). Waterfall charts render increments in --chart-up, decrements in --chart-down, and summary totals in neutral slate --chart-total.
3. Directional movement (intl default, cn for Mainland China A-shares only):
   • Default across all business metrics, global equities, crypto, FX, commodities, and macro series: green-up / red-down (marketConvention: "intl", {colors.chart-up} for +, {colors.chart-down} for -).
   • Swap to red-up / green-down (marketConvention: "cn") only when displaying Mainland China A-share (A股) equities or A-share indices.
   • Pair directional colors with explicit +/- or ▲/▼ glyphs and tabular-nums so sign survives grayscale print and color-vision differences. Keep chart-up and chart-down separate from operational success and error tokens.

Live Pod views vs. Applets

• Single-table declarative charts: Create a shared chart view on the Base table with ankole-pod base.create_view (type: "chart", config: { chart: { chart_type, query, encoding?, display? } }), then embed <embed ref="<base-page-id>" table="<table-id>" view="<view-id>" /> on its own line in the :doc Page—or pass an inline JSON ViewConfig in view when the chart configuration belongs exclusively to one report document.
• Multi-table joins, interactive financial terminals, or custom simulations: Build a React Applet with ankole-pod applet init|build|publish, importing AnkoleStatCard, AnkoleSparkline, AnkoleChart, AnkoleFinancialChart, AnkoleGraph, or AnkoleInfographic from the root @ankole/uikit package and recordsToFinancialSeries, densifyTimeBuckets, or formatMetricValue from @ankole/applet-sdk.

Offline export (ankole-viz) and channel rules

Run ankole-viz --help inside a Background Agent Job when generating image assets for PDF, PPTX, DOCX, HTML reports, or chat attachments:

• Pass tabular inputs directly from disk via --data <path.csv|tsv|json|jsonl> instead of pasting large datasets into inline JSON arguments.
• Validate Mermaid or Infographic syntax cheaply without launching a browser via ankole-viz validate --kind mermaid|infographic --input <file>.
• PDF and print safety: Typst (resvg) and WeasyPrint require Print-Safe SVGs (no <foreignObject>, no var(--...) CSS variables, no external URLs). ankole-viz automatically resolves theme tokens and, when --pdf-safe is active or a template emits <foreignObject>, rasterizes at 1920px width (300 DPI on an A4 text block) to lossless .png and reports the output path in JSON stdout. kline always exports lossless .png with attribution intact.
• Feishu / Lark and messaging channels: Deliver .png (--dpr 2) for inline chat viewing so mobile and desktop clients render an immediate image preview; attach .svg only when the user asks for editable vector source files.