Custom Charts — Intelligence — Semiotic

Home · Getting Started · Charts · Features · Playground

This page requires JavaScript for interactive chart demos.

AI / Machine-readable docs: llms.txt · llms-full.txt · CLAUDE.md · schema.json · API Reference · Examples

View on GitHub · npx semiotic-ai for CLI access

Machine-readable page content

Canonical: https://semiotic.nteract.io/custom-charts/intelligence

Custom Charts as Reception Strategies

Why custom charts are different

A custom chart is justified when its reception strengths—memorability, situated reading, interaction, or a useful visual idiom—outweigh its interpretive risks and the recipe supplies the scaffolds needed to cross that gap. Geometry alone cannot state that contract.

Why Semiotic understands recipes, not frames

Raw custom frames remain absent from suggestions because they require unknown layout code. Registered recipe IDs are named candidates with data roles, intent scores, audience fit, reception channels, caveats, and an explicit reason to leave the built-in catalog.

JSX

import { defineChartRecipe, registerChartRecipe, describeChart, buildNavigationTree, auditObservedScene, } from "semiotic/ai" export const waffle = defineChartRecipe({ id: "semiotic.recipe.waffle.v0", name: "Waffle chart", frameFamily: "XYCustomChart", portability: "portable", layout: { id: "semiotic.layout.waffle" }, layoutConfigSchema: { type: "object", properties: { columns: { type: "number" } } }, dataRoles: [ { role: "category", accessor: "categoryAccessor", semanticType: "nominal", required: true }, { role: "value", accessor: "valueAccessor", semanticType: "quantitative", required: true }, ], intents: [{ id: "part-to-whole", score: 5 }], designContract: { whyCustom: "Repeated units make composition concrete.", whyNotDefault: "A bar is more precise but less compositionally memorable.", }, accessibility: { accessibleTable: "required", navigationGranularity: "category" }, mobile: { strategy: "summary-cards", supportsResponsiveLayout: true, breakpoints: [320, 390, 768], maxMarks: 100, maxAnnotations: 2, minimumHitTarget: 44, summary: true, interaction: { primary: "tap", alternatives: ["category chips", "details panel"], hoverFallback: "tap-to-lock", }, labels: { strategy: "direct", minFontSize: 12 }, custom: { dataBearingSceneNodes: true, stableIds: true, navigationGranularity: "category", }, }, }) registerChartRecipe(waffle)

Portable vs local recipes

Tier	Contract	Available surfaces
Portable	Registered layout ID, JSON-safe config, serializable schema	Suggestions, SSR, serialization, CLI/MCP, docs
Local	May contain callbacks, closures, renderers, or browser-only dependencies	Browser suggestions, runtime audit, description, navigation, local repair

Data roles and visual semantics

Roles say what the input means; encodings say what emitted marks mean. Together they let the same capability machinery test data compatibility, generate description layers, and detect when an accessible table or scene loses semantic fields.

Mobile semantics

Custom layouts are opaque until the recipe says how they behave on a phone. Themobile contract records the responsive strategy, breakpoints, mark budget, annotation budget, touch target size, label plan, and whether emitted scene nodes retain data semantics. recipeToChartCapability() carries that into suggestions, generated props expose it as mobileSemantics, and the mobile audit reads the same block that portability adapters carry under IDID capability.mobile.

Description and navigation

Recipe-aware description produces L1 encoding, L2 statistics, L3 pattern, and L4 communicative intent. Navigation uses an authored strategy when present and otherwise groups by the primary categorical role with leaves for reachable data marks.

Observed-scene audit

getCustomLayout() exposes what the recipe actually emitted. The audit keeps declared semantics, observed evidence, and manual assistive-technology checks separate so Semiotic does not claim to measure comprehension or real screen-reader behavior.

Intent Mark

The visible mark packages the IDID contract for review, copying, agent inspection, and later export without hiding it inside component props.

Intent Mark · part-to-whole

XYCustomChart: part-to-whole for general-technical. A unit grid makes composition more concrete and memorable than an abstract arc or line.

{ "ididVersion": "0.1", "chartId": "custom-intelligence-waffle", "title": "Waffle chart", "intent": { "primary": "part-to-whole", "secondary": [ "explanation" ], "communicativeAct": "Make composition memorable and concrete." }, "audience": { "primary": "general-technical", "familiarityAssumptions": { "waffleChart": "medium", "partToWhole": "high" } }, "reception": { "channels": [ "visual", "interactive", "screen-reader", "agent" ], "strengths": [ "memorable", "glanceable", "explainable", "teaching-friendly" ], "risks": [ "precise comparison may be harder than a bar chart", "individual cells can become navigation noise" ], "scaffolds": [ "legend", "category summary", "accessible table", "description" ], "memorableForm": true }, "designContract": { "chartFamily": "XYCustomChart", "whyThisForm": "A unit grid makes composition more concrete and memorable than an abstract arc or line.", "whyNotDefault": "A pie chart would show share but provide less unit-level evidence and less interaction surface.", "risks": [ "precise comparison may be harder than a bar chart", "individual cells can become navigation noise" ], "misuse": [ "too many categories", "too many units", "false precision", "treating each cell as a separate semantic datum" ] }, "accessibility": { "description": "Generated from the recipe's roles, encodings, and intent.", "navigation": true, "dataFallback": true, "manualChecks": [ "screen-reader behavior", "metaphor comprehension", "animation distraction" ] }, "mobile": { "strategy": "summary-cards", "supportsResponsiveLayout": true, "breakpoints": [ 320, 390, 768 ], "maxMarks": 100, "maxAnnotations": 2, "minimumHitTarget": 44, "summary": true, "interaction": { "primary": "tap", "alternatives": [ "category chips", "details panel" ], "hoverFallback": "tap-to-lock" }, "labels": { "strategy": "direct", "minFontSize": 12 }, "custom": { "dataBearingSceneNodes": true, "stableIds": true, "navigationGranularity": "category" } } }

Full examples

Start with the portable waffle recipefor the clean intelligence proof, then inspect thelocal Urine Wheel recipe for a situated historical idiom whose reception contract explains why it is not a bar chart wearing a hat.

The complete candidate → explanation → Intent Mark → description → navigation → scene audit flow is live in What the Machine Sees.