Use this skill when you get a task like "draw an X chart in Feishu Docs / make an animated visualization / build a data dashboard".
Miaobi BOX is in Feishu Docsthe only vehicle that can truly execute CSS/JS(iframe sandbox), so all animations, ECharts, Three.js, Canvas
can move. The process is just three things:Write a self-contained HTML page according to the recipe → verify in a local browser that it really renders → use doc htmlbox to save to the database。
For anything "animated", you can only use Miaobi BOX. The drawing board (
feishu-cli-board)'s SVG nodes will berasterized into static images by the Feishu server and will never move; the trade-off is that Miaobi BOX is a whole iframe, and its internal elements cannot be individually clicked and edited in Feishu like drawing board nodes (you can't have your cake and eat it too).
The first step is always selection: what you want to draw → what to use → where the recipe is
First find your match in the table below, then go to the corresponding reference to copy the skeleton + recipe.Do not hand-roll ECharts options from scratch— the recipes are all verified and can be directly create。
| The chart you want to draw | Engine / Solution | Recipe location |
|---|---|---|
| Line / area / bar / stacked bar / bar race BarRace / rose pie / radar | ECharts (switch series.type） |
references/gallery.md › Data comparison |
| Scatter bubble / heatmap / calendar heatmap / boxplot / candlestick / parallel coordinates | ECharts | references/gallery.md › Distribution statistics |
| Pie / funnel / Sankey / theme river / gauge / liquidFill | ECharts (+extensions) | references/gallery.md › Composition and flow |
| Force-directed graph (draggable) / organization tree / sunburst / treemap | ECharts | references/gallery.md › Relationships and hierarchy |
| Sequence / state machine / Gantt / CI pipeline / kanban flow | ECharts custom / CSS | references/gallery.md › Process and sequence |
| Word cloud wordCloud | echarts-wordcloud | references/gallery.md › Composition and flow |
| Pure CSS animation (rotation/pulsing/progress bar/typewriter/color change) | CSS @keyframes(most stable, no external network dependency) |
references/gallery.md › Creative animation |
| Particle flow / starfield / custom-drawn animation | Canvas + requestAnimationFrame |
references/gallery.md › Creative animation |
| Vector path self-drawing / morphing / Venn diagram | Inline <svg> + SMIL/CSS |
references/gallery.md › Creative animation |
| KPI data dashboard (number rolling + mini trends) | HTML/CSS/JS | references/gallery.md › Creative animation |
| Real map choropleth / geo latitude-longitude flying lines | ECharts geo + registerMap |
references/geo-3d.md |
| 3D map map3D / 3D bar / 3D scatter / 3D surface | echarts-gl | references/geo-3d.md |
| True 3D scenes (rotating planet / GPU particles / geometry) | Three.js（WebGL） | references/geo-3d.md |
Not sure which to use?Default to ECharts(covers the vast majority of statistical/relationship charts); only for real geography, rotatable 3D, or free visuals that ECharts cannot produce should you use geo-3d / Canvas / SVG.
Not sure what form to draw(Bar or line? Or just go with one big number?) → First look at feishu-cli-dataviz skills
(task → form heuristics + anti-pattern checklist).Series colorsuniformly take the dark column of that skill's palette (for the convention see the
references/gallery.md beginning), do not invent color values.
More than drawing: the window.magic document mini-app runtime
In the iframe of Miaobi BOX, Feishu injects a window.magic runtime——Blocks created via OpenAPI also have it(already tested, the injection recognizes component_type_id and not the source). So it is not just for drawing, it can also makedocument mini-apps that read data, are interactive, and have state. When a task needs any of the following, see references/window-magic.md：
| Requirements | Capabilities |
|---|---|
| Current user identity (name / open_id, for personalization or writing personnel fields) | window.magic.user |
| Read the full text / metadata of the current document (feed AI, statistics, generate a table of contents) | getDocAsMarkdown / getPageMeta |
| Persistent state (counter / lottery / blessing wall / read list) | window.magic.redis / store（localStorage is forbidden, see pitfalls) |
| Charts connected to real data sources (live-data Dashboard) | base_records_search pull multi-dimensional table → ECharts |
| Call AI within the document (summary / Q&A / copywriting, no need to bring your own key) | window.magic.ai(Doubao) |
⚠ window.magic Injected only on the Feishu document side, local file:// preview must be undefined——all usages must have existence checks and fallbacks, otherwise the local page will be blank.
Drawing workflow (follow it for every chart)
- Following the recipe, write a self-contained HTML page to
/tmp/x.html. Fromgallery.md/geo-3d.mdtake the corresponding skeleton + recipe; uniformly use a dark background, fixed container height (e.g.#chart{height:360px}）、width:100%, listen forresizecallchart.resize(). Series colors are taken according to the color convention at the beginning ofgallery.md; if you change colors, first run the palette validation (the command is in the same section). - Verify in a local browser that it actually renders and is actually animating—this step cannot be skipped. Any top-level JS error in the iframe will make the entire chartblank with no error reported(uncaught exceptions go to pageerror, not console), and you cannot tell just by reading the code. Directly run the packaged validation script—it opens the page with a brand-new browser session, captures page error / console, counts canvas/svg nodes, takes a screenshot, and based on that gives a pass/fail judgment:
Only exit code 0 counts as a preliminary pass; but "whether it is drawn correctly and whether it is animating" cannot be judged by a machine,so you must also visually inspect the screenshot it prints. For troubleshooting a blank screen seescripts/verify.sh /tmp/x.html # 地图/CDN 重的加等待秒数：scripts/verify.sh /tmp/x.html 5references/pitfalls.md。 - Persist to document：
feishu-cli doc htmlbox create <doc_id> --html-file /tmp/x.html。 - Edit chart：
feishu-cli doc htmlbox update <doc_id> <block_id> --html-file /tmp/x2.html(block_id will change, subsequently use the returnednew_block_id）。
Command quick reference
| Operation | Command |
|---|---|
| Insert | feishu-cli doc htmlbox create <doc_id> --html-file x.html（--index to control position, defaults to the end) |
| Replace | feishu-cli doc htmlbox update <doc_id> <block_id> --html-file x2.html(returns new_block_id） |
| Read back | feishu-cli doc htmlbox get <doc_id> <block_id> --raw > cur.html |
| Delete | feishu-cli doc htmlbox delete <doc_id> <block_id> |
Input also supports --html '<...>' or --html-file -(stdin). All four commands support --format / --jq; write-type create/update/delete additionally have --dry-run preview and -o write to file, get uses --raw to output pure HTML (get has no --dry-run/-o). Default Bot identity(No login is required to operate feishu-cli to create your own documents); to modify someone else's or a manually created document, pass --user-access-token。
The 5 pitfalls to avoid when drawing charts (see references/pitfalls.md）
- White screen with no error → Must verify in a local browser before saving to the database (see workflow step 2). This is the most frequent pitfall.
- CDN
<script>is asynchronous → Poll before use until the library is ready (if(typeof echarts==='undefined') return setTimeout(boot,150)), for each<script src>addonerroras a fallback. The Feishu sandbox has been tested and can connect to jsdelivr. - Real map → ECharts 5 does not include map data, directly
type:'map'blank; firstfetchGeoJSON (borrowecharts@4.9.0/map/json/china.json) thenregisterMap。 - Polar bar does not color by value →
visualMapis ineffective for it; explicitly set for each data itemitemStyle.color。 - Draw multiple charts in a batch → between each
createbetweensleep 0.5s, otherwise it triggers Feishu write rate limiting99991400; for multiple charts with titles, usedoc content-update --mode append --markdown "## 标题"alternating with create to append.
Deliver after creation (as needed)
When the document needs to be handed over to the user: follow the owner authorization process of feishu-cli-write (perm add full_access + depending on configuration perm transfer-owner), and send a Feishu card notification according to global rules.
Reference documents and scripts
scripts/verify.sh <html> [等待秒数]— Pre-save verification script(used in workflow step 2): open in a brand-new session → capture page error/console → count canvas/svg → take a screenshot → give a pass/fail judgment; only exit code 0 counts as a preliminary pass, and the screenshot must still be checked by eyereferences/gallery.md— Main recipe library: 4 general-purpose skeletons (ECharts/Canvas/Three.js/SVG-CSS) + ready-to-use recipes by chart typereferences/geo-3d.md— complete runnable templates for maps / echarts-gl 3D / Three.js (these categories have CDN/registerMap/coordinate system/coloring pitfalls)references/window-magic.md— Document mini-program runtime：window.magiccapability recipes (user identity / reading documents / persistence / multi-dimensional tables / AI), including the existence-check fallback paradigm and composite recipes such as live-data Dashboard and in-document AI cardsreferences/pitfalls.md— chart-drawing pitfall avoidance and white-screen troubleshooting (from actually creating a large 47-chart document)references/mechanism.md— block mechanism / identity / update quick reference (only needed when troubleshooting token, component ID, or update behavior)