The single definition of every graph component (APS 21: surface × mark ×
encoding, typed contracts, chosen by the agent), and the web package that
draws them, @zegadb/components. Ava's chat and ava's maps import it;
zega.dev's catalogue reads its contracts.
| platform | status | stack |
|---|---|---|
| web | built (this package) | SVG for charts, MapLibre GL JS for maps; React or plain DOM hosts |
| desktop (Tauri) | built | the same web build in the webview (Ava's app) |
| iOS | paused (Sami, 15 Nov) | generated/Tokens.swift and tokens.rs stay as they were and are not extended; no iOS specs are written |
The spec is the product. A component is what its spec, contract, tokens and fixtures here say it is. An implementation is conforming only if it renders every one of that component's fixtures, in both themes, within tolerance of the reference images (CONFORMANCE.md).
- Contracts are plain typed data (Sami, 15 Nov). A view spec is
{ component, data, options }: the data inline, held to the contract'sdataJSON Schema; the options to itsoptions. Data comes from anywhere: the assistant's tools, the knowledge graph, the model itself, or a ZQL result through a contract's optionalzqladapter (format 1's binding, kept for zega's explorer). ZQL is one source, never the shape. - Validate, then draw. Every host runs the package's
validate()before anything renders. A spec that fails draws nothing; its errors (teaching errors: where, what, what to do) go back to whoever wrote it. People never see raw errors. - Colour follows each product's brand (Sami, 15 Nov):
tokens/themes.json has one theme per host (
ava: the Lilac/Night violet, DM Sans;zega: the paper ground, zega green, Space Grotesk), light and dark, the same roles everywhere. Categorical orders were checked with a palette validator (lightness band, chroma, colour-blind separation) against each ground. - Values come from tokens; specs name
{theme.<role>}and{group.name}tokens, never raw hex or px. - Known gaps are named in each spec's Conformance section.
| component | category | status | web reference (light, dark) |
|---|---|---|---|
| function-plot: y = f(x), areas, points, asymptotes | Math | review | ![]() |
| price-chart: line or candlesticks, volume, annotations | Finance | review | ![]() |
| path-on-map: ordered paths on the map | Geo | review | ![]() |
| globe-arcs: routes as arcs on the globe | Network | review (format 1, zega's explorer) | ![]() |
| hockey3darena: rink heat | Sports | draft (format 1) | none yet |
import { validate, explain, render, theme, toElements, attachHover, toolDefinitions } from "@zegadb/components";
const checked = validate(spec); // anything: a model's JSON
if (!checked.ok) return explain(checked.errors); // to the model, never to people
const drawn = render(checked.view, { width, theme: theme("ava", "dark") });
// charts: drawn.svg is a tree of SVG elements → toElements(drawn.svg, React.createElement) or toDom()
// then attachHover(svgElement, drawn.hover, theme) for the crosshair and tooltip
// path-on-map: drawn is { map: true, height }; the host's MapLibre map + drawChecked() from
// "@zegadb/components/path-on-map/draw" (pathOnMap.plainStyle(theme) when there is no basemap)- Never markup. Charts are SVG node trees a host turns into its own
elements; model-written text is always text. Expressions (function-plot)
are parsed by
src/expr.ts, neverevalorFunction. - Tools for an assistant:
toolDefinitions()gives one tool per component (draw_function_plot, …) whose input schema is the contract's own{ data, options }; the host adds the component from the tool's name. - Sizing: inline in a column (rixse APS 4's medium size), the width is the
column's and the height is width × the contract's
size.aspect, within itsminHeight–maxHeight. Fixtures render at 640 pt (a desktop chat column) and 358 pt (a 390 pt phone's column). - Styles:
@zegadb/components/themes.css(--zc-*variables under[data-zc-host]) and@zegadb/components/components.css(the map legend and labels).
Packaging (APS 10): hosts install the package from a registry by version.
Until it is on npm they vendor the exact npm pack tarball
(node tools/pack.mjs <dir> prints its sha256, integrity and commit; packing
is reproducible) and depend on it with file: plus a drift test. Needs
Sami: npm publishing for @zegadb/components (release env).
A contract's surface is { kind, art?, frame?, regions? }. A body diagram
or a rink is kind: "art": art names the drawing (an SVG the package ships
per surface, themed from the same roles), frame its coordinate system
({ x: [-100, 100], y: [-42.5, 42.5], unit: "ft" } for a rink), and
regions the named areas data may refer to (left-knee, slot). The data
schema then uses plain numbers in the frame ({ x, y, value }) or an enum
of the regions ({ region: "left-knee", value }). Nothing in the contract
format, the validator, the view spec or the chat changes: a new surface is a
new contract, a new drawing and its fixtures.
components/<id>/
<id>.spec.md, <id>.contract.json the spec (TEMPLATE.spec.md's sections) and the contract
web/<name>.json, web/data/*.json web fixtures (format 2: plain data, a host theme, a width)
web/<name>.reference(.dark).png their renders by the web package
fixtures/… format-1 fixtures (a ZQL result), rendered by zega's explorer
src/ the web package (TypeScript; src/generated/ from contracts + themes)
tokens/tokens.json, tokens/themes.json design tokens; host themes
generated/ tokens.css/js (+ paused Tokens.swift, tokens.rs), themes.css
schemas/ contract (2) and v1, view spec (2) and v1, fixtures, tokens, themes
tools/ checks, generators, renderers, the comparator, pack
Node 24 or newer.
npm install
npm run generate # tokens + src/generated (contracts, themes) + generated/themes.css
npm run check # every repository rule; CI runs it
npm test # unit tests (validator, parser, renderers) and the checks' own drift tests
npm run typecheck && npm run build
node tools/render/container.mjs tools/render/web.mjs # (re)render web references in the pinned image
node tools/render/container.mjs tools/render/web.mjs --verify # web conformance, as CI runs it
npm run verify:zega -- --zega ../zega # zega's explorer against format-1 referencesAdding a component: copy TEMPLATE.spec.md to
components/<id>/<id>.spec.md with status: draft, write the format-2
contract, then the renderer in src/, web fixtures and references.
- zega's ramps. The zega theme's sequential ramp is a new green one (to match zega.dev's accent); the diverging ramp is the explorer's. Proposal until approved.
- Ava's app vs Ava's brand. Charts in Ava's app use the brand book's violet; the app's own chrome is still the older warm orange. Recommend the app moves to the brand palette.
- Contract ownership (format-1 question 4) stands: this repo owns the contracts; zega's explorer should vendor them with a drift check.
- Naming: rename
hockey3darenatorink-heatwhen it becomes format 2.






