Earlier formats
Prompting your agent
What to tell a coding agent so it writes good ui artifacts the first time.
Start with the formats guideLink to this section
The server carries its own manual. artifacts_formats_guide with kind: "ui" returns the rules, every component with its props (generated from the same catalog as the component pages), and a complete example. An agent that reads it first gets the format right far more often. Ask for it by name:
# ui artifacts (component set version 1)
A ui artifact is a json-render spec rendered with the artifacts.space component set. Pages are read-only to the world: inputs only change on-page state.
This is an earlier format, kept for the artifacts that use it. For a new mockup, dashboard, or report, prefer kind "html", a full web page. Call artifacts_formats_guide with kind "html" for its rules. Use this guide to read or change a ui artifact that exists, or a frame of a canvas.
## Rules
1. Submit ONE JSON object as the artifact content (not JSONL, not Markdown, no code fences): { "version": 1, "root": "<key>", "elements": { "<key>": { "type", "props", "children" } }, "state": { … } }.
2. Always set "version": 1.
3. `elements` is a flat map. `children` lists child keys in order; leaves may omit it. Each element has exactly one parent, and the root has none.
4. Only use components from the list. Props are strict: strings and arrays have maximum sizes, and unknown props are ignored. Omit optional props instead of sending null.
…A prompt that worksLink to this section
Say what the page is for, which data goes where, and ask for validation. A prompt like this one works well:
Make a ui artifact on artifacts.space for the Q3 reliability review.
1. Call artifacts_formats_guide with kind "ui" and follow it.
2. Use the incident data below. Lead with three Metrics (incidents,
minutes down, mean time to recover) with change against Q2.
3. Add a stacked bar Chart of incidents per month by severity, and a
Table of the five longest incidents.
4. Put the action items in a Checklist and the open risks in a Callout.
5. Keep it on one screen at a glance: Section, then a Grid of metrics.
6. Run artifacts_validate and fix every error before you save.
7. Save it with project "reliability" and summary in one sentence.
<paste the data here>To make it a habit in a repository, add a few lines to AGENTS.md or CLAUDE.md:
## artifacts.space
- Save plans, decisions, and reports as artifacts. Search with
artifacts_list before you create one; update instead of duplicating.
- For dashboards and reports, use kind "ui": read
artifacts_formats_guide (kind "ui") first, and run
artifacts_validate before every save.
- Set project to the repository name and sessionId to this session.Good habitsLink to this section
- Lead with the answer. Metrics and a one-line Callout at the top; detail in Tabs or an Accordion below.
- Pick the component that fits the data. Table for rows (up to 500), Chart for trends, KeyValue for settings, Steps for runbooks, Board for status, Calendar for dates.
- Use formats, not strings. Send numbers with
formatandcurrencyinstead of "$1.2M" text, so axes, tables, and the data view stay exact. - Use short, readable keys such as
kpi-revenue. Validation messages name them. - Pick a theme for the reader. Pass a preset id as
theme, such aseditorialfor a long report orinkfor the most contrast. Charts, badges, and tables take the theme's colors with no change to the spec. See Themes. - Validate, then save.
artifacts_validatereports every problem at once; fix them all in one pass. - Update, do not duplicate. Save a new version of the same artifact with
artifacts_update; its link stays the same and history keeps every version. - Mind the limits. Split very large data into several artifacts, or summarize it. See Spec limits.
Ideas to tryLink to this section
- A pull request review: KeyValue for the change summary, a Table of findings with severity badges, and Steps to reproduce.
- An incident report: a Timeline of events, Metrics for impact, and a Checklist of follow-ups.
- A migration plan: Steps with the commands, a Progress bar per phase, and a Callout for the rollback.
- A weekly status page: a Board of work by stage and a Calendar of the next two weeks.
- A benchmark: a scatter Chart of latency against payload, and a Table of the raw runs.
Try a prompt's output
Paste a spec your agent wrote into the playground to see it and its validation report side by side.