Docs / Reference

Authoring Yantra diagrams

How to write a Yantra diagram by hand or with an agent: workflow, budgets, groups, trees, sequence views, data models, languages and validation codes. The schema is schemas/yantra-payload.schema.json; this page explains how to use it well.

#Workflow

1. Decide the story first. What question does the diagram answer? Who reads it? List the 3–6 steps of the walkthrough before listing boxes.
2. Write the payload in one pass: meta, roles, nodes, edges, scenarios. Start from yantra new diagram.json or a file in examples/.
3. Validate: yantra validate diagram.json. Fix every error, then the warnings (repair order below). Repeat at most twice; if it still fails, simplify the diagram.
4. Build: yantra build diagram.json writes diagram.html (single offline file).
5. Look at it: yantra screenshot diagram.json --step 2 and open the PNG. Never claim a diagram looks right without viewing it.

#Do not place nodes

Layout and edge routing are automatic. Leave out x/y. The engine ranks nodes by the direction of the edges, so edge direction is your layout tool:

• Point edges along the main flow (request → service → store). The main path becomes a straight row (LR) or column (TB).
• Return / feedback edges (refund, retry, sync back) are detected and drawn in a corridor outside the drawing. Keep them; do not invert them to "help" the layout.
• meta.layout.direction: LR (default) for pipelines and request flows, TB for hierarchies and long sequential processes.
• node.rank forces a column when two nodes must line up; use sparingly.
• meta.layout.mode: "manual" + x/y (multiples of 10) only when an exact hand layout is required. You then own overlaps.
• meta.layout.algorithm: layered (default) for flows; tree or mindmap for hierarchies (see Trees, org charts and mind maps).

#Budgets

#Content rules

• data.title: the thing's name. data.subtitle: its job, in a few words. data.tech: the technology, one line. Anything longer goes in description.
• Put facts (SLA, team size, owner) in data.metadata; they show in the inspector, not on the card. Cards stay quiet.
• Use roles to group types into 3–5 meaningful categories with one colour each, e.g. edge, service, data, external. Give the specific label in data.badge.
• edge.type: "async" | "event" | "stream" (or style: "dashed") for asynchronous flows.
• A step that highlights nothing is an overview. A focused step lists the nodes and the edges involved; every highlighted edge must have both endpoints highlighted.
• step.payload is optional and is shown in the inspector: method, endpoint, status, latency, protocol become chips, everything else is pretty-printed JSON.
• Add modes only when they change something (hideNodes, hideEdges, or per-mode data.modes.<id> overrides).

#Inspector tabs: include only what was asked for

The side panel builds its tabs from the payload, so add content for a tab only when the user wants that kind of information:

"panels": [
  { "id": "risks", "title": "Risks", "blocks": [
    { "type": "points", "items": [{ "title": "Provider outage", "text": "Payments queue and retry.", "tone": "warn" }] }
  ] }
]

• Panels use the same blocks as answer pages (points, steps, metrics, table, compare, callout, chart, code, sources, text; see docs/pages.md). Keep the title to one or two words: it is the tab label.
• meta.inspector.tabs: ["summary", "risks"] picks and orders tabs explicitly; meta.inspector.labels: { "node": "Component" } renames built-in tabs.
• No tabs at all hides the inspector button. Many tabs scroll sideways.

#What a card click opens

Clicking a card always highlights it and its connections. What the inspector does is a fixed rule per diagram, set with meta.inspector.onNodeClick; leave it out unless the diagram's purpose calls for something else:

For a panel opened by click, give its blocks nodes: ["card-id", …]: such blocks show only while one of those cards is selected (with a "Show all cards" link), and blocks without nodes always show. If the target tab does not exist, the click only highlights.

#Groups

groups draws a labelled box around related nodes. Use it when the boundary itself is part of the explanation:

• trust boundaries: public internet vs. your network, PCI scope, tenant isolation;
• cloud structure: account > region > VPC / subnet, cluster > namespace;
• ownership: teams or departments, and swimlanes for who does each step of a process;
• subsystems: "Billing", "Search", "Data platform" inside a larger architecture.

A flat diagram reads best with 2-5 groups; leave nodes that sit outside every boundary (users, third parties) ungrouped. A box with one node rarely helps; put the node's context in its subtitle instead. Groups nest up to six levels deep (24 groups at most within budget): see Deep hierarchies.

"groups": [
  { "id": "aws", "title": "AWS account (eu-west-2)", "nodes": ["cdn"], "color": "orange", "style": "solid" },
  { "id": "vpc", "title": "Private VPC", "parent": "aws", "nodes": ["worker", "db"], "color": "green",
    "description": "Private subnets in two AZs; no internet gateway." }
]

• List each node in its innermost group only; the parent's members include the child's.
• Group ids must not reuse node ids. color is a role hue name; style is dashed (default) or solid.
• Layout keeps members together, pads each box (20px sides, 36px top for the title; a little less below the third level) and keeps boxes clear of outsiders. Edges cross borders where they enter or leave a group, but never run through a title or the box's fold button. In manual layout the box simply wraps its members' cards.
• During a step, a group whose members are all dimmed is dimmed too.

See examples/aws-serverless.json.

#Trees, org charts and mind maps

When the answer is a hierarchy, pick a hierarchical layout. Edges still point from parent to child; the engine takes the hierarchy from them.

"meta": { "title": "Org chart", "layout": { "algorithm": "tree", "direction": "TB" } },
"nodes": [
  { "id": "ceo", "type": "exec", "data": { "title": "Amara Okafor", "subtitle": "Chief Executive Officer" } },
  { "id": "cto", "type": "exec", "data": { "title": "Daniel Reyes", "subtitle": "Chief Technology Officer" } }
],
"edges": [ { "id": "ceo-cto", "source": "ceo", "target": "cto" } ]

• One parent per node. A node with two incoming edges keeps the first listed one as its parent; the other is drawn as a routed cross-link and lint warns layout/tree-cross-link. In a decision tree, repeat an outcome card (sev2-a, sev2-b) instead of merging branches.
• Labels are optional on hierarchy edges (the hierarchy is the meaning). Label them when the branch needs a name: Yes / No in a decision tree, a condition, a percentage.
• People cards: title is the name, subtitle the role, badge a short team or level tag; width: 180-200 keeps wide org charts compact.
• Wide org charts: compact stacks. In a TB tree, a parent whose children are all leaves (no reports of their own, no edge label) can list them in one column below itself, indented on a side bus, instead of a row. meta.layout.compact: "auto" (default) does this only when the spread tree is much wider than tall (over 1600 px and 2.4 times its height), true always, false never. Parents with a mix of leaf and non-leaf children keep their row. A 30-40 person org chart then fits a near-square canvas. LR trees and mind maps are never stacked (layout/compact-ignored when compact: true is set there).
• Assistants and staff: data.assistant: true on a leaf card (an executive assistant, a chief of staff) places it beside its manager, in the manager's row, on a short side connector instead of a level below. The first assistant goes right (TB) or below (LR), the next on the other side, more stack in those columns. A root, a card with reports or a mind map ignores the flag (layout/assistant-ignored).
• Dragging a card moves its visible subtree with it; comb, stack and assistant connectors are rebuilt from where the cards now sit (mind-map curves stay curves). A child dragged out of tree order (above its parent, say) is routed like any other edge.
• Mind maps have one root (the first node nothing points at). Branch colours replace role colours on the canvas, so the roles legend is hidden; keep roles for the inspector.
• Order children the way they should read: siblings keep the order of their edges.
• State shapes work here too: a self-loop sits right of its card (TB tree) or below it (LR tree, mind map) with room kept for it; dots and diamonds carry no fold button while open, and a +N badge beside them while folded (click it to unfold). Cards with data.drill keep their drill mark, and each detail level opens with its own collapsed.
• Groups are not drawn in these layouts (layout/groups-ignored); the hierarchy is the boundary. This is deliberate: a tidy tree packs subtrees by their outline, so a box around one subtree would often enclose cards of its neighbours. To show or hide a team, fold its top card (meta.layout.collapsed: ["cto"]); folding a group id in a tree warns layout/collapse-ignored.

See examples/org-chart.json, examples/study-plan-mindmap.json and examples/incident-triage-decision-tree.json.

#Big diagrams: folding

Readers can fold parts of a diagram into one card and unfold them again (+N / − buttons, key X on a selected card; the state is kept in the link as #collapsed=id,id):

• in tree and mindmap layouts, any card with children folds its subtree;
• in the layered layout, every group folds into a summary card that takes over the group's edges (parallel edges merge, internal ones disappear).

meta.layout.collapsed: ["id", ...] lists what is folded when the viewer opens (build, export and screenshot take --collapsed id,id, --expand-all or --depth n to override it for one output; MCP tools take collapsed / expandAll / depth). A folded group's card counts the cards and boxes it holds, and folding to a depth (keys 1-6) or zooming to a group works at any level: see Deep hierarchies. Use it for large trees (lint counts the cards that show at first against the budget of 40) and for detail groups in an architecture overview. A step that highlights a folded card unfolds it, so a walkthrough can open a branch at the right moment. Validation checks the drawing both as it opens and fully unfolded (findings for the second carry [expanded]).

#Deep hierarchies

Real organisations and systems nest: a city has districts, a district has services, a service has systems, a system has sites, a site has sensors. Yantra shows such hierarchies in two ways, and they combine.

Rules of thumb: nest in one frame while the opened drawing stays under about 14 cards and a reader can name every box; drill down when a level needs its own walkthrough. Six boxes deep is the limit of what reads at a glance.

"groups": [
  { "id": "city", "title": "Harbourside City", "nodes": [], "style": "solid" },
  { "id": "north", "title": "North district", "parent": "city", "nodes": [] },
  { "id": "transport", "title": "Transport", "parent": "north", "nodes": [] },
  { "id": "traffic", "title": "Traffic management", "parent": "transport", "nodes": ["utc"] },
  { "id": "junction", "title": "Junction 14 cabinet", "parent": "traffic", "nodes": ["signals"] },
  { "id": "sensors", "title": "Roadside sensors", "parent": "junction", "nodes": ["loops", "camera"] }
],
"meta": { "layout": { "collapsed": ["junction", "sensors"] } }

• A group may hold only child groups ("nodes": []); list each card in its innermost group.
• Layout. Up to three levels, one layered pass keeps every edge in the main flow. From four levels (or whenever one pass cannot keep the boxes apart) each group is laid out on its own and placed as one block in its parent, so boxes never overlap and every edge enters and leaves through the borders. Boxes are wide enough for their whole title and the fold button; padding tightens a little below the third level (groupPad), and tints and outlines get calmer with each level (dashed, then dotted from the fourth), in both themes.
• Folding. Folding a box hides everything inside it and shows one summary card that counts them ("9 cards · 3 groups"); unfolding it brings back the inner boxes as they were, folded or not. List inner ids in meta.layout.collapsed too, so a reader who opens the outer box finds the next level still tidy.
• Fold to depth. Keys 1-6 keep that many levels of boxes open and fold the rest (0 opens everything; with several scenarios the digits switch scenario, so hold Shift), or the toolbar's depth menu. The link keeps it (#depth=2). CLI --depth n (build, export, screenshot), MCP depth, Python depth=. In tree and mind-map layouts the same control folds by card level.
• Focus a group. Double-click a group title (or select a card and press G) to zoom to its box: folded boxes around it open, and a path of its ancestors appears under the toolbar (Whole diagram › … › Transport › Traffic management; the middle of a long path is a menu). Esc zooms out one box at a time. The link keeps it (#focus=<id>); screenshot --focus <id>.
• Walkthrough. A step's focusGroup: "<group id>" zooms to that box and unfolds it and its ancestors, so a story can open the deep part at the right moment; the next step without focusGroup lets go. Highlight the cards too (highlightNodes), as in any focused step.
• Validation. Lint checks the drawing as it opens, fully unfolded and, for three or more levels, at every depth the viewer folds to ([depth n] in the message): boxes inside their parents and below their titles, titles clear of cards, edges and labels, nothing cut.
• Drill-down breadcrumbs. Deep paths show the overview, the parent and the current level: Global retail group › … › Payment terminal T-07 › EMV kernel; the … opens a menu of the levels in between.

See examples/smart-city-operations.json (six levels in one frame), examples/global-retail-group.json (six-level drill-down with nested boxes inside levels) and examples/hospital-trust-monitoring.json (both).

#Sequence view

The same payload can be drawn as a sequence diagram. Use it when time order matters more than topology: request/response flows, protocols and handshakes (OAuth, TLS, payments), "who calls whom" during one user action. The steps drive it, so no extra data is needed:

• Every id in a step's highlightEdges becomes one arrow, source -> target, in step order. An edge used in two steps appears twice. Labels come from the edge (fallback: the step title); style: "dashed" or an async/event type draws a dashed arrow; an edge from a node to itself draws a self-loop.
• Participants are the nodes that send or receive a message, left to right in order of first appearance (a step without messages contributes its highlightNodes, so an opening "the user clicks" step puts the user on the left). meta.sequence.allParticipants: true adds every node. Group members are kept adjacent and their group becomes a box around their columns.
• Each step is a numbered row; a step without highlightEdges becomes a note across its highlighted nodes. Column gaps widen automatically until every label fits between its lifelines.

"meta": { "view": "sequence" } opens in the sequence view. Whenever the active scenario has a step with highlightEdges, the viewer shows a Flow / Sequence toggle (key V, deep link #view=sequence). CLI: yantra export file.json -f svg --view sequence [--step n] and yantra screenshot file.json --view sequence --step n. Write highlightEdges for every step that sends something, and keep the flow view readable too: both views come from one payload. See examples/oauth-login.json.

meta.views lists the views a reader may switch between. ["flow"] hides the toggle (a diagram whose steps highlight relationships rather than messages); ["sequence"] shows only the sequence view. Without it both are offered, except that a diagram made only of table or class cards (an ERD or a class diagram: every node has fields or methods) has no sequence view and no toggle; list ["flow", "sequence"] to offer it anyway.

#Drill-down: an overview plus detail diagrams

A big system does not fit in 14 cards, and should not. Draw the overview with one card per subsystem, then give a subsystem its own detail diagram: the card gets a drill mark, and opening it (click the mark, double-click the card, key D, or the inspector button) shows the detail with a breadcrumb (Overview › Payments). The breadcrumb, Esc (once nothing is selected) and the browser's Back button return; the URL carries the level (#level=payments). Each level is a full diagram: its own steps, inspector tabs, modes and sequence view.

{
  "meta": { "title": "Shop platform" },
  "nodes": [
    { "id": "payments", "type": "service", "data": { "title": "Payments", "drill": "payments" } }
  ],
  "diagrams": {
    "payments": { "meta": { "title": "Payments service" }, "nodes": [ ... ], "edges": [ ... ], "scenarios": [ ... ] },
    "search": { "$ref": "./search.json" }
  }
}

• data.drill names a key of the top-level diagrams map. A detail diagram may drill further (at most 8 levels below the overview, no cycles); every id lives in one namespace, so a detail diagram's own diagrams map is merged in. Any level may use nested groups. Deep breadcrumbs keep the overview, the parent and the current level, with a menu (…) for the rest.
• { "$ref": "./search.json" } keeps a level in its own file. The CLI and MCP server load it relative to the file that contains it; it must be a relative .json path that stays inside the input folder (the input file's folder for the CLI, YANTRA_INPUT_ROOT for MCP). The built HTML always contains every level, so it still works offline. The dev server (npm run dev) inlines them too when a gallery example is imported (relative to the example, inside the project only), and the Python SDK loads them for a page's diagram src (relative to that file, inside base_dir).
• data.modes.<mode id>.drill opens another level while that mode is shown (null: no detail in that mode). Lint checks these targets like data.drill, and the Markdown export lists them as Mode: detail: Title after the card.
• meta.startLevel: "payments" opens the viewer on a detail diagram.
• Exports follow the level on screen (SVG, PNG, Markdown); Export → Markdown, all levels (CLI export -f md --all-levels) appends every level under its breadcrumb. CLI and MCP take --level <id> / level for export and screenshot.
• Answer pages: a diagram block with level: "payments" shows that level; with interactive: true the viewer opens there and can go back up. One drillable embed is still one viewer for the two-per-page budget.

See examples/platform-overview.json.

#Links

data.url on a node, url on an edge or a step adds an Open link to the inspector (node Details, the edge in its card's connections, the Step tab), opened in a new tab with rel="noopener noreferrer". Only http:, https: and mailto: links are allowed; Markdown exports keep them as links. Use links for runbooks, dashboards, specs and source, not for content that belongs on the card.

#State machines and lifecycles

Use a state diagram when the question is what states a thing can be in and which event moves it (an order, a ticket, a document, a connection). Nodes are states, edges are transitions labelled with their event:

• shape: "state" draws a rounder card for a state. shape: "initial" (filled dot), "final" (ringed dot) and "choice" (diamond) are small, textless pseudo-states; their data.title still names them in tooltips, the inspector and exports. Give them their own role (e.g. pseudo, slate) so the legend explains the dots.
• A transition out of an initial state or into a final state needs no label; every other transition should name its event.
• When several transitions meet a dot or diamond, the best-aligned one keeps its side and each other one enters from the free side that gives it the shortest route, so lines reach the dot directly instead of going round it.
• Self-loops (source equal to target) draw as a small loop on a free side of the card (above or below it in LR, to its right in TB), with the label on the loop. Layout makes room for it; steps may highlight it like any edge. Ports of other edges on that side stay clear of the loop's legs. A loop on a dot or diamond takes a side no other edge uses, starts on the outline and reaches well past the shape, with its label beyond the loop.
• Back-edges (reopen, retry, decline) are fine: point them the way the event goes and layout routes them back. Two edges between the same pair of states get a wider gap so both labels fit side by side.
• edge.arrow: "forward" (default), "both" for one two-way edge (ask / reply), or "none" for an undirected link. Layout still ranks by source → target.

{ "id": "start", "type": "pseudo", "shape": "initial", "data": { "title": "Start" } },
{ "id": "open", "type": "state", "shape": "state", "data": { "title": "Open" } },
{ "id": "open-note", "source": "open", "target": "open", "label": "add note" },
{ "id": "open-waiting", "source": "open", "target": "waiting", "label": "ask / reply", "arrow": "both" }

See examples/ticket-lifecycle.json; Mermaid stateDiagram imports to the same shapes.

#Fork, join and concurrent regions

• shape: "fork" draws a fork or join bar: a thick bar across the flow (vertical in LR, horizontal in TB). Edges attach along its length on the two long sides, lined up with the cards they join, and end on the bar's face. The bar grows with its edges (and stretches to span its neighbours when there is room); width sets a length. Use the same shape for a join. Transitions into or out of a bar need no label; a bar should split into or merge two or more transitions (story/fork-needs-branches).
• Concurrent regions: make the composite state a group, and each region a child group with "kind": "region" and "parent" set to it. Regions stack across the flow (rows in LR, columns in TB); the parent draws its box and title, each region only its title, with a dashed line between neighbouring regions. Put every node of the composite state inside one of its regions, and use two or more regions.
• In tree and mindmap layouts a bar is drawn like the other pseudo-states (folded, it shows a +N badge); hierarchy edges there are tree connectors and ignore sourceField / targetField, which apply to cross-links and self-loops only.

{ "id": "split", "type": "pseudo", "shape": "fork", "data": { "title": "Fork" } },
"groups": [
  { "id": "processing", "title": "Processing", "nodes": [] },
  { "id": "payment", "title": "Payment", "kind": "region", "parent": "processing", "nodes": ["authorise", "capture"] },
  { "id": "stock", "title": "Stock", "kind": "region", "parent": "processing", "nodes": ["reserve", "pack"] }
]

See examples/parallel-checkout-states.json.

#Data models and class diagrams

A card becomes an entity card when its data has fields and/or methods: the rows appear under the title and the card grows to fit them (and widens, up to 320px, for long types). Use it for database schemas (ERDs) and UML class diagrams.

{ "id": "orders", "type": "table", "data": { "title": "orders", "fields": [
  { "name": "id", "type": "uuid", "pk": true },
  { "name": "customer_id", "type": "uuid", "fk": true, "ref": "customers.id" },
  { "name": "shipped_at", "type": "timestamptz", "nullable": true }
] } }

• Fields: name (required), type, flags pk / fk / unique (shown as PK / FK / UK in a key column, PK names in bold), nullable (type ends in ?), ref ("node" or "node.field", validated), note (inspector and Markdown only).
• Class cards: fields are attributes and methods are operations ({ name, params?, type?, visibility?, static?, abstract? }, drawn as name(params) with the return type on the right). visibility is + - # ~; static members are underlined, abstract ones italic. data.stereotype: "interface" shows «interface» in place of the kicker.
• Keep cards small: a card shows 12 rows (fields + methods); the rest become + N more and lint warns content/too-many-fields. Show the keys and the columns the story needs; list the rest in description.
• Layout: LR suits ERDs (tall cards side by side), TB suits class hierarchies.

#Relationship notation

Edges take a marker at each end, independent of style:

{ "id": "places", "source": "customers", "target": "orders", "label": "places", "sourceEnd": "one", "targetEnd": "zero-or-many" },
{ "id": "is-a", "source": "entity", "target": "order", "relation": "inheritance" }

• relation puts triangles and diamonds on the source (the parent, interface or whole) and open arrows on the target. Point edges parent → child and whole → part, so the layout draws parents first; sourceEnd / targetEnd override either end.
• An edge with any notation drops the default arrowhead (and ignores arrow); an end without a marker is plain. Use arrow for plain flows and state transitions, notation for data models.
• Inheritance, realization, composition and aggregation need no label (the symbol says it); ER relationships still want a verb (places, contains). Markers fit in the straight stub at each port, and labels are kept clear of them.
• Field rows: sourceField / targetField name a field of the source / target card; the edge then attaches at that row, on the left or right side facing the other card (both on the right when the cards stand one above the other). Point foreign keys at the key they reference ("sourceField": "id", "targetField": "customer_id"); several edges from one key share its port and leave on one trunk before branching. Two edges between the same pair of rows run on separate tracks, and a self-relationship whose row another edge also leaves nests inside it. An unknown name is an error (ref/edge-unknown-field). Without them, edges attach to card sides.
• End labels: sourceLabel / targetLabel put short text beside each end, past its marker: multiplicities ("1", "0..*", "1..*") or role names ("owner"), up to 16 characters. The Markdown export adds them to the Relationship column (1 → 0..*).
• Self-relationships (employees.manager_id → employees.id) are self-loops: with field names they join the two rows on the less busy left or right side, with their markers and the label beside the loop.

{ "id": "places", "source": "customers", "target": "orders", "label": "places", "sourceEnd": "one", "targetEnd": "zero-or-many", "sourceField": "id", "targetField": "customer_id" },
{ "id": "lines", "source": "order", "target": "line", "relation": "composition", "label": "lines", "sourceLabel": "1", "targetLabel": "1..*" }

See examples/ecommerce-schema.json and examples/payment-classes.json.

#Charts in diagrams

A card can carry a chart, drawn inside it under the subtitle. The card grows to fit it (the layout uses the real height), both themes and every zoom level look the same, and the SVG / PNG export draws it too. Clicking the card shows the chart full size, with its data table, in the Details tab; the Markdown export lists the numbers under Chart.

Mini charts (data.chart on an ordinary card) show one reading at a glance:

{ "id": "api", "type": "service", "data": { "title": "Orders API", "subtitle": "Takes orders",
  "chart": { "kind": "line", "label": "p95 latency", "unit": " ms",
             "values": [180, 172, 165, 190, 158, 150, 146, 142], "target": 160 } } }

• label is the short caption drawn on the card ("p95 latency", "Uptime"). unit goes after numbers (%, ms, k), prefix before (£). target draws a dashed line on line, area and column charts, a tick on rings and bullets and a dashed mark across mini bars. The full-size chart in the Details tab draws it as a labelled target line ("Target 160 ms"), also for bullets (the value as one bar against the line).
• The chart takes the card's role colour; tone (good, warn, bad, info, neutral or a hue) overrides it, and data items take their own tone.
• A ring states its scale ("47 / 52") unless it is a plain percentage.
• Per-mode readings: put a different chart in data.modes.<id>.

Chart cards ("shape": "chart") are wider cards (360px; width 240-480) whose data.chart is a page chart block (see docs/pages.md, Charts): kind column, bar, line, area, pie or donut, with data or categories + series, stacked, unit and prefix. They draw axes, gridlines and a legend at card scale, connect like any card and can be highlighted in steps. The card title is drawn; the chart's own title is what a screen reader hears. A chart card takes target too (column, bar, line, area: a dashed target line).

{ "id": "latency", "type": "dashboard", "shape": "chart", "width": 400,
  "data": { "title": "p95 latency by service", "subtitle": "Today against last Friday",
    "chart": { "kind": "column", "unit": " ms", "categories": ["Checkout", "Payments", "Search"],
               "series": [{ "name": "Last Friday", "values": [190, 210, 170] },
                          { "name": "Today", "values": [240, 260, 340] }] } } }

• Keep a chart card to 4 series, 12 bars or columns, 60 line points or 6 slices; a single series takes the card's colour, several take the page chart colours.
• Use chart cards for the 1-3 numbers the diagram is about (a dashboard, a funnel); use mini charts for a reading per component; put anything bigger in a panel.
• Accessibility: the card's accessible name adds the chart's kind, caption and values; chart cards draw a <title>, and the inspector adds the hidden data table.
• Custom panels take chart, gantt and matrix blocks too; they are drawn at the panel's width (a gantt puts task names above their bars there, so they are not cut short).

See examples/live-operations-dashboard.json (chart cards and mini charts), examples/cloud-architecture.json, examples/sales-pipeline.json and examples/smart-city-operations.json.

#Languages and right to left

"meta": { "title": "…", "lang": "ne" }

• meta.lang is the BCP 47 tag of the content (es, pt-BR, ne, zh, ja, ar …). It sets <html lang> (built HTML) and xml:lang (SVG), the number format of metrics, charts, counters and zoom (Intl.NumberFormat), and the language of every fixed label: toolbar, tooltips, walkthrough, inspector, shortcuts panel, toasts, export menu, the badge, and the SVG and Markdown exports. Built-in tables: en es fr de pt it hi bn ne zh zh-Hant ja ko id ar he fa ur. A region tag uses its language (pt-BR → pt); Chinese uses Traditional (zh-Hant) for zh-Hant*, zh-TW, zh-HK and zh-MO (unless Hans is given) and Simplified otherwise. Any other language keeps English labels and the validator warns i18n/unknown-lang; the content still gets its lang.
• Write the payload text (titles, labels, steps) in that language yourself; Yantra only translates its own interface. Keyboard keys, Yantra and GitHub are never translated.
• meta.strings overrides labels by key, e.g. { "story.next": "Continue" }; placeholders are written {n}, {total}, {title}, {role}, {name}. The keys are STRING_KEYS in src/core/i18n.js (listed below). meta.inspector.labels still renames the built-in tabs.
• Plurals. Counted words (chart.day1 / chart.days, chart.point1 / chart.points) are chosen with Intl.PluralRules: the CLDR category one uses the first key, anything else the second. A table or meta.strings may add zero, two, few or many forms as <key>.<category>, e.g. "chart.days.two": "יומיים"; Arabic and Hebrew ship them.
• File size. A built HTML file carries the English table plus only the tables its payload uses (its meta.lang and those of detail diagrams; an answer page: those of its interactive diagrams). The tables live in src/core/locales/<lang>.js; the dev viewer and gallery load them all.
• Right to left. ar, he, fa, ur (and yi ps sd ckb dv ug), or meta.dir: "rtl", set dir="rtl": the toolbar, walkthrough, step chips, inspector (docks left), legend and badge (bottom-left) mirror, arrow keys follow the reading direction, and the text inside cards, group titles, the SVG title, legend and badge are right-aligned. meta.dir: "ltr" forces left to right.
• The diagram keeps its layout direction. LR stays left to right in an RTL document: arrows, ranks, edge routes and sequence-view columns are the same as in any language, so one payload translated into Arabic has the same geometry, the validator checks the same scene, and technical flows read the way their source code and protocols are written. If a process should run right to left for its readers, reverse the order of the nodes yourself (e.g. with rank); a mirrored layout is not generated automatically.
• Text is measured per script: Han, kana and Hangul count as full width, Devanagari and Arabic letters have their own widths and combining marks count as zero, so cards are sized without clipping. Chinese and Japanese wrap between characters without spaces (no line starts with 、。」 or ends with 「).
• Budgets measure width. content/title-too-long (42), content/label-too-long (28) and page/headline-too-long (220) count display columns, as terminals do: a full-width Han, kana or Hangul character counts 2, a combining mark (Devanagari vowel signs, Arabic harakat) 0, anything else 1. A 20-character Chinese title (40 columns) passes, a 25-character one does not; for text without wide characters the count equals its length. The codes are unchanged; the message says "columns wide" when the two differ.
• Validation messages in a language. Codes and English messages are the interface for tooling. For people, yantra validate file.json --lang ja (or --lang auto for the payload's meta.lang; MCP yantra_validate takes lang; Python validate(lang=...)) translates the content/, story/, ref/ and i18n/ messages into any built-in language and keeps the English text in messageEn. Other messages (geometry, schema, pages) stay in English: they are rarer and name JSON fields and layout terms that read best as written in the schema.

Examples: examples/health-referral-nepali.json, examples/order-fulfilment-arabic.json.

#Limits

• Card titles, subtitles and edge labels over 200 characters are cut with an ellipsis; lint warns content/text-too-long.
• Graphs over 60 nodes or 120 edges switch to a faster windowed router (budget/large-graph-fast-routing); it may leave the odd label overlap the careful router avoids. Split big diagrams instead where you can.

#Validation codes and how to fix them

Fix in this order; each fix can clear later errors.

#Minimal example

{
  "meta": { "title": "Checkout", "description": "How an order is paid and stored." },
  "roles": {
    "client": { "label": "Client", "color": "amber" },
    "service": { "label": "Service", "color": "blue" },
    "data": { "label": "Data", "color": "violet" }
  },
  "nodes": [
    { "id": "web", "type": "client", "data": { "title": "Web app", "subtitle": "Customer checkout", "icon": "monitor" } },
    { "id": "api", "type": "service", "data": { "title": "Orders API", "subtitle": "Validates and charges", "tech": "Go" } },
    { "id": "db", "type": "data", "data": { "title": "Orders DB", "subtitle": "Source of truth", "tech": "PostgreSQL", "icon": "database" } }
  ],
  "edges": [
    { "id": "web-api", "source": "web", "target": "api", "label": "POST /orders" },
    { "id": "api-db", "source": "api", "target": "db", "label": "INSERT order" }
  ],
  "scenarios": [
    {
      "id": "main",
      "name": "Place an order",
      "steps": [
        { "id": "s1", "title": "Overview", "description": "Three parts: client, API, database." },
        { "id": "s2", "title": "Submit", "description": "The browser posts the cart.", "highlightNodes": ["web", "api"], "highlightEdges": ["web-api"] },
        { "id": "s3", "title": "Persist", "description": "The API stores the order.", "highlightNodes": ["api", "db"], "highlightEdges": ["api-db"] }
      ]
    }
  ]
}