Ichartjs

iChart.js

Use the public Agent contract as the source of truth. Do not infer capabilities from renderer internals or duplicate chart-selection logic in generated code.

Read the usage scenarios when the request is ambiguous about whether the output should be a live project component, a Coding Agent change, a Skill-generated artifact, or a scheduled report. Read the conversational workflow when the user asks to change an existing chart in natural language. For Agent-driven Incremental Construction (visible step-by-step Flow or Board building), read its shared turn contract in that guide. First verify a persistent mounted JavaScript host, preview URL and command update channel exist. A Skill or final file alone cannot show live progress; disclose the limitation and offer artifacts or integration code instead. Submit complete semantic batches, show changes/diagnostics, obtain host approval for each exact preview, then commit and self-check. Do not equate Agent-generated confirmed: true, a template counter, or health.renderable with user approval or task completion.

Source and Runtime Setup

• Official repository: https://github.com/wanghetommy/ichartjs
• Official Skill source: https://github.com/wanghetommy/ichartjs/tree/master/skills/ichartjs
• Supported Skill hosts include Codex, WorkBuddy, and other Agent Skills-compatible environments.

Recommended installation:

npx skills add wanghetommy/ichartjs --skill ichartjs

Use --agent codex --global --yes for global non-interactive Codex installation. Use the tagged directory https://github.com/wanghetommy/ichartjs/tree/v2.0.27/skills/ichartjs when reproducibility matters. WorkBuddy can import the same directory through its Skill interface; do not assume a --agent workbuddy adapter unless the installed CLI declares it.

The Skill is a workflow adapter, not the chart runtime. If the current JavaScript or TypeScript project does not already depend on iChart.js, install the matching runtime from npm:

npm install @taylorwong/ichartjs@^2

Do not install the unscoped npm registry package named ichartjs; it is currently a security holding package and is not this project.

Workflow

1. Locate the package or repository root. Read docs/agent/quickstart.md when available. For delivery-oriented work, also read docs/agent/task-validation.md; for mobile loading, read docs/agent/runtime-footprint.md. If the host knows the capability family, use @taylorwong/ichartjs/standard, /project, /diagram, or /board; use the root package when full discovery or cross-family composition is required.
2. Call getCapabilities() before selecting a chart or interaction.
3. Call inspectData() and preserve stable record IDs.
4. Discover getCapabilities().intents; map natural-language requests to an exact registered token before calling planChart(data, { intent, renderer, context }).
5. Inspect the complete planning result, including styleRecommendation, warnings, and fallback status; then call getChartContract(plan.primary) for the selected chart's channels, limits, renderers, exports, and defaults.
6. Stop when requiredFields is non-empty; request data or explain a supported alternative.
7. Build a JSON-serializable Spec using suggestedEncodings, the selected contract, and an applicable recipe.
8. Use chart-specific channels: Cartesian x/y, Pie/Funnel category/value, Gauge value, Heatmap x/y/color, and Radar indicators[].field. Funnel stage text comes from encoding.category (default name) and labels.enabled additionally renders values; narrow stages may report FUNNEL_LABEL_TRUNCATED, so increase width or shorten the stage name. For Flow, use top-level nodes and edges, nodes[].kind from getCapabilities().diagram.flowNodeKinds, and edge label for decision branches. connector uses explicit from/to edges and loops are allowed. To discover recipes, import @taylorwong/ichartjs/recipes/manifest; recipes are declarative starting templates, not executable tasks. Copy one, inject host data, run its declared validator, and then render or preview. The diagrams/workflow entry is an edit template and is not directly renderable until nodes and edges are populated.
9. Keep titles/formats under xAxis/yAxis, labels under labels, and legend under legend; do not place them inside encoding.
10. Call validateSpec() before rendering and repair its preflight errors, warnings, and normalizations. After createChart(), inspect chart.getState() or chart.explain() for render-time diagnostics such as FUNNEL_LABEL_TRUNCATED, VALUE_CLAMPED, LABELS_SUPPRESSED, LABEL_TRUNCATED, NEGATIVE_VALUE_DROPPED, and ZERO_TOTAL; also inspect getState().layout.labels for wrapped, scaled, inline-edge, offset-edge, and diagram edge-label background counts. Ordinary chart labels do not use background plates. Do not assume every layout warning is available during preflight.
11. Call createChart() only after validation succeeds. Gauge Specs must declare a meaningful domain.
12. Self-check with chart.explain(), chart.getState(), health.renderable, dataQuality, and JSON export. Treat VALUE_CLAMPED, LABELS_SUPPRESSED, NEGATIVE_VALUE_DROPPED, FUNNEL_LABEL_TRUNCATED, and ZERO_TOTAL as material diagnostics to report. Treat duplicate stable IDs and mixed inferred units as data-quality warnings that require host review.
13. Provide an exact preview URL or artifact path and report assumptions, warnings, data-quality issues, and deferred checks.
14. Prefer theme: { mode: 'auto', preset, palette }; preserve explicit user style choices and use chart.setTheme() for live switching.
15. For post-creation visual changes, call getPreferenceCapabilities(chartType, { locale }), validate the patch with validatePreferences(), apply it with chart.setPreferences(..., { source: 'agent' }), and verify chart.getState().preferences.
16. For natural-language changes, classify the request before mutating: visual → setPreferences()/setTheme(), complete data replacement → setData(), business or Diagram edit → previewEdit()/applyEdit(), normal Spec change → update(), exact JSON path → applyPatch(). Verify chart.getState().preferenceResolution and chart.explain() after commit.

Common type-specific placements:

For titles, labels or annotations, read Chart Text and Annotations. Discover getCapabilities().text / .annotations; use JSON annotations for numeric reference lines or stable-ID callouts on Cartesian charts, not ephemeral pixel plugins. Bar/Column support explicit inside/outside labels. Inspect fitting/target diagnostics and preserve existing annotation IDs when replacing the array. Host approval and natural-language interpretation remain outside the runtime.

Use top-level width and height for chart dimensions. size: { width, height } is not a chart Spec option and returns UNSUPPORTED_SIZE_OPTION.

Theme values are discoverable from getCapabilities().styleSystem or getPreferenceCapabilities(). The current values are mode: auto | light | dark | contrast, preset: auto | analysis | dashboard | report | presentation | project | diagram, and palette: auto | categorical | sequential | diverging | status.

Freeform Board

For visible multi-turn Board construction, discover boardCapabilities.incrementalBuilding and use validateBoardCommand() with type: 'board-edit', not chart edit commands. Reuse one Board, explicitly enable editing/structural changes, preview each complete batch, obtain host confirmation, then applyEdit(preview.command, { preview, confirmed: true }). Await ready() for changed images and inspect asset status/health. Preserve existing positions and locked items; only explicitly requested layout changes move content. Root and /board both support transactions; /board embeds standard charts only. See the Board scenario below and @taylorwong/ichartjs/recipes/boards/incremental-board for ordered starting templates.

Use Freeform Board when the output is a bounded whiteboard composition rather than one chart: images, text, simple drawings, connectors, and embedded charts can share one SVG or Canvas surface. Simple drawing is a whiteboard capability, not a separate chart type. Discover the contract first:

const capabilities = getCapabilities();
const boardContract = capabilities.canvasComposition;

Supported board items are image, text, shape, path, connector, and embedded chart. Board item position and size are pixels; shape and path geometry points are normalized inside each item box. Shape options are rectangle, ellipse, diamond, hexagon, normalized-point polygon, open arc, and filled sector; path supports normalized linear points or exactly four points for a cubic Bezier. Do not send arbitrary SVG path data. Text automatically fits by wrapping, bounded font reduction, and last-resort ellipsis; inspect board.getState().layout.text. Connectors use explicit from/to item IDs and straight or orthogonal routing. Images are declared in assets, referenced by assetId, and should include alt text.

Use validateBoardSpec() before createBoard(), then mount, await ready(), and inspect board.getState() and board.explain(). Boards are static by default; explicitly enable editing or interaction.drag, interaction.zoom, and interaction.pan only when the host requests them. Export JSON for persistence, SVG for vector delivery, and browser-mounted Canvas as PNG/JPEG.

Read the Freeform Board Scenario for the complete BoardSpec workflow. Use agent-recipes/drawings/cat.json as a validated simple-drawing starting point and preview the unified Freeform Board at http://localhost:3000/playground/canvas-board.html.

Use @taylorwong/ichartjs for package imports. Use examples/agent-workflow.mjs as the executable baseline when working in the repository.