Earlier formats
JSON Render
How ui and canvas artifacts work: one JSON spec on the stout component set, rendered the same for every reader. Earlier formats, kept for the artifacts that use them.
An earlier format
ui and canvas formats on these pages are kept for the artifacts that use them, and still work as described here.How it worksLink to this section
A ui artifact is a json-render spec: one JSON object that names components and their props. artifacts.space renders it with its own component set, called stout, built on the same primitives as the rest of the site. The renderer is @json-render/core and @json-render/react 0.21.1.
- The agent reads the component guide with
artifacts_formats_guide(kind: "ui"). - It writes a spec and checks it with
artifacts_validate. Every problem comes back at once, with the element key and the fix. - It saves the spec with
artifacts_createorartifacts_update. The server runs the same validation and refuses a spec with errors. - Readers see a page in the artifacts.space look, or in the artifact's own theme, in light or dark, on any screen.
Agent code never runs on the page. A spec is data: no scripts, no CSS, no network calls. Inputs such as Switch and Slider change only the page's own state, and nothing is saved or sent.
Spec anatomyLink to this section
Every spec has the same four top-level fields.
versionLink to this section
The component-set version the spec was written for. Always "version": 1 today. Leaving it out is a warning; any other number is an error. When the component set changes in a way that alters existing props, the version goes up and older specs are migrated on read, so a saved page keeps its meaning.
root and elementsLink to this section
elements is a flat map from a key you choose to one element. root names the top element. Each element has a type (a component name), props, and optionally children, visible, repeat, and on. Keys are up to 100 characters; short, readable keys such as kpi-revenue make validation messages easy to follow.
{
"kpi-revenue": {
"type": "Metric",
"props": { "label": "Revenue", "value": 1284000, "format": "currency" },
"children": [],
"visible": { "$state": "/showMoney" }
}
}childrenLink to this section
children lists child keys in order. Nesting comes from keys, not from nested objects, so a deep layout stays a flat, easy-to-edit list. Each element has exactly one parent, and the root has none. Only layout components (Section, Stack, Grid, Card, Tabs, Accordion) show children; a leaf with children gets a warning.
{
"page": {
"type": "Stack",
"props": { "gap": "lg" },
"children": ["title", "kpis"]
},
"kpis": {
"type": "Grid",
"props": { "columns": 3 },
"children": ["kpi-revenue", "kpi-churn", "kpi-nps"]
}
}stateLink to this section
state is the page's starting data: any JSON object. Props read it with $state, inputs write it with $bindState, and repeat renders a list from an array in it. State lives in the reader's browser and resets on reload. See Dynamic props and actions.
{
"state": {
"showMoney": true,
"filters": { "team": "Platform" },
"services": [{ "name": "api" }]
}
}A minimal specLink to this section
The smallest useful spec: a Stack with a heading and a paragraph.
Hello, artifacts
This page is one JSON object: a root key and a flat map of elements.
Show JSONHide JSON
{
"version": 1,
"root": "page",
"elements": {
"page": {
"type": "Stack",
"props": { "gap": "md" },
"children": ["title", "body"]
},
"title": {
"type": "Heading",
"props": { "text": "Hello, artifacts", "level": 1 }
},
"body": {
"type": "Text",
"props": {
"text": "This page is one JSON object: a root key and a flat map of elements."
}
}
}
}A full dashboardLink to this section
Metrics with sparklines, a stacked bar chart and a table in tabs, and a toggle that shows a callout. Copy the JSON, change the numbers, and it is yours.
Switch tabs and flip the toggle: inputs change on-page state only.
Delivery, week 45
Deploys, failures, and lead time across all services.
Deploys
128
+14%
Change failure rate
3.1%
-0.8%
Lead time
5.2h
-1.1 h
- Succeeded
- Failed
| Label | Succeeded | Failed | Total |
|---|---|---|---|
| Mon | 12 | 0 | 12 |
| Tue | 17 | 1 | 18 |
| Wed | 20 | 1 | 21 |
| Thu | 16 | 1 | 17 |
| Fri | 23 | 1 | 24 |
| Sat | 18 | 1 | 19 |
| Sun | 16 | 1 | 17 |
Show JSONHide JSON
{
"version": 1,
"root": "page",
"elements": {
"page": {
"type": "Section",
"props": {
"title": "Delivery, week 45",
"description": "Deploys, failures, and lead time across all services."
},
"children": ["kpis", "tabs", "risk-toggle", "risks"]
},
"kpis": {
"type": "Grid",
"props": { "columns": 3 },
"children": ["kpi-deploys", "kpi-failure", "kpi-lead"]
},
"kpi-deploys": {
"type": "Metric",
"props": {
"label": "Deploys",
"value": 128,
"change": 14,
"changeFormat": "percent",
"goodDirection": "up",
"sparkline": [12, 18, 21, 17, 24, 19, 17]
}
},
"kpi-failure": {
"type": "Metric",
"props": {
"label": "Change failure rate",
"value": 3.1,
"format": "percent",
"change": -0.8,
"goodDirection": "down"
}
},
"kpi-lead": {
"type": "Metric",
"props": {
"label": "Lead time",
"value": 5.2,
"unit": "h",
"change": -1.1,
"goodDirection": "down"
}
},
"tabs": {
"type": "Tabs",
"props": { "tabs": [{ "label": "Trend" }, { "label": "Failures" }] },
"children": ["trend", "failures"]
},
"trend": {
"type": "Chart",
"props": {
"type": "bar",
"stacked": true,
"title": "Deploys per day",
"labels": ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"],
"series": [
{
"name": "Succeeded",
"values": [12, 17, 20, 16, 23, 18, 16]
},
{ "name": "Failed", "values": [0, 1, 1, 1, 1, 1, 1] }
]
}
},
"failures": {
"type": "Table",
"props": {
"columns": [
{ "key": "service", "label": "Service" },
{ "key": "when", "label": "When" },
{ "key": "cause", "label": "Cause" },
{
"key": "minutes",
"label": "Minutes down",
"align": "right",
"format": "number"
}
],
"rows": [
{
"service": "api",
"when": "Tue 14:02",
"cause": "Migration lock timeout",
"minutes": 6
},
{
"service": "web",
"when": "Thu 09:40",
"cause": "Missing env var",
"minutes": 2
},
{
"service": "worker",
"when": "Sat 22:15",
"cause": "Queue backlog",
"minutes": 11
}
]
}
},
"risk-toggle": {
"type": "Switch",
"props": {
"label": "Show open risks",
"checked": { "$bindState": "/showRisks" }
}
},
"risks": {
"type": "Callout",
"props": {
"tone": "warning",
"title": "Open risks",
"text": "The worker queue backs up on Saturdays. Add a second consumer before the holiday traffic."
},
"visible": { "$state": "/showRisks" }
}
},
"state": { "showRisks": false }
}Try it live
The component setLink to this section
The stout set has 43 components in six groups. Each page shows live examples and a props table generated from the schema the server checks against.
Layout
Arrange other elements. Only these components show their children.
Content
Headings, text, Markdown, code, links, and icons.
HeadingTextMarkdownCodeCalloutBadgeListStepsLinkQuoteIconAvatarAvatarGroupKbdRating
Inputs
Controls that change on-page state only.
Canvases: boards of screensLink to this section
A canvas artifact is a board of frames that show screens of websites and apps. Each frame is one screen at a width you choose, and its spec is a ui spec, so every component and rule on these pages works inside a frame. Readers drag to move the board, zoom in to read a frame, and open the board full screen to give it the whole window; on a phone the frames stack in the page, each scaled to fit. No HTML or CSS is involved, and each frame keeps its own state.
| Frame field | Required | What it does |
|---|---|---|
| id | Yes | A short, unique name: up to 40 lowercase letters, digits, and hyphens. Keep it when you change the frame. |
| name | Yes | What people see above the frame, up to 80 characters. |
| width | Yes | The frame's width in CSS pixels, 240 to 2,560. Usual sizes: 1440 (desktop), 768 (tablet), 390 (phone). |
| height | No | The least height, 120 to 10,000. Left out, the frame is as tall as its content. Longer content makes the frame taller and is never cut off. |
| padding | No | The space between the frame's edge and its content: none, sm, md (the default), or lg. |
| x, y | No | The frame's top-left corner on the board. Left out, frames sit in one row in the order listed, 80 pixels apart. |
| spec | Yes | The frame's ui spec: version, root, elements, and state. |
{
"version": 1,
"frames": [
{
"id": "home-desktop",
"name": "Home, desktop",
"width": 1440,
"spec": {
"version": 1,
"root": "page",
"elements": {
"page": {
"type": "Grid",
"props": { "columns": 3 },
"children": ["…"]
}
}
}
},
{
"id": "home-phone",
"name": "Home, phone",
"width": 390,
"height": 844,
"spec": {
"version": 1,
"root": "page",
"elements": { "page": { "type": "Stack", "props": {}, "children": ["…"] } }
}
}
]
}To show one screen at several sizes, add one frame per size and lay each out for its width. A canvas holds up to 24 frames and 3,000 elements across them, and each frame keeps the ui limits. The agent reads the rules with artifacts_formats_guide (kind: "canvas") and checks a canvas with artifacts_validate: each issue names the frame, then the element, and the fix. A frame with a problem shows a notice in its place, and the other frames still render. To change one screen later, the agent uses the frame tools (canvas_frames_list, canvas_frame_get, canvas_frame_save, canvas_frame_update, canvas_frame_delete): it reads and sends one frame, never the whole board. An agent that can edit the canvas can also see a frame, with canvas_frame_image: the picture is drawn by the browser of someone who may edit the canvas when they open it, so the agent sees what that person sees.