Ostraca

Illustrations for every state your product is in, drawn by your agent.

Ostraca is a skill for coding agents and the engine it draws with. Name any object and your agent draws it as a small building elevation in blueprint blue that follows your product through its states: set out while it is empty, rising while it loads, signed off when it is done, revised when it changes, out of true when something goes wrong. Ask for all six states or only the ones you need, as a figure for your app or as one SVG picture. 34 ready-drawn figures come with it, to use as they are and to start from.

skills.ahmedamr.com/ostraca. MIT licensed. No runtime dependencies. Works with or without React.

Ostraca are the limestone flakes Egyptian tomb builders sketched on.

Draw any object

npx skills add ahmedamr-r/ostraca

Add -g to install it for every project, or download the zip and unzip it into your agent's skills folder if you do not use the skills CLI (every way in).

Then ask your agent for an illustration, for an empty state, an upload screen, a 404 or anything else in your product. Or call the skill by name:

/ostraca coffee cup

Before it draws, the agent asks what you need, in one message, with a default for each. Say "the defaults" and it draws all six states as a figure.

Option	Choices	Default
States	All six, or any of idle, empty, loading, success, changed and error	All six
Output	A figure for your app, or one standalone SVG picture	A figure
For a picture	Light, dark or both; the workers on or off; the paper behind it or transparent; the library's colours or your own	Both, off, transparent, the library's

Anything your request already says, it does not ask again: /ostraca coffee cup, empty only, or /ostraca a coffee cup for our empty orders page, as an svg. Name a moment instead of an object, such as /ostraca something for a fitness app, and it offers two or three objects to pick from.

Then it writes one description file, checks it against the library's rules, draws contact sheets in light and dark, looks at them and fixes what it sees. A figure goes into your app with define() and works everywhere a ready-drawn one does:

import { define } from "ostraca";
import cup from "./coffee-cup.js";

define(cup);

A picture is an SVG file with every colour written on it, for a design file, a slide, an email or an <img>. The skill works in any agent that reads SKILL.md skills, such as Claude Code, and its checks need Node 22 and Google Chrome or Chromium. See docs/skill.md.

Install the engine

npm i ostraca

React

import { Ostraca } from "ostraca/react";
import "ostraca/styles.css";

export function Upload({ sent, total, failed, done }) {
  const state = failed ? "error" : done ? "success" : total ? "loading" : "empty";
  return <Ostraca name="ramp" state={state} value={total ? sent / total : undefined} />;
}

It renders on the server. When a prop changes in the browser, the drawing animates to the new state.

HTML

import { render, mount } from "ostraca";
import "ostraca/styles.css";

// a string, anywhere
document.querySelector("#inbox-art").innerHTML = render("inbox", { state: "empty" });

// or kept, so changes animate
const art = mount(document.querySelector("#sync-art"), "bridge", { state: "loading" });
art.update({ state: "success" });

Six states

State	Your product	The drawing
idle	Nothing to report	Built: drawn solid
empty	Nothing here yet	Set out: a dashed outline where it will stand
loading	Working on it	Rising: inks from the ground up under a scaffold or ladder. Pass value from 0 to 1, or leave it out and a gin wheel bucket goes up and down
success	Done	Signed off: the scaffold comes down and a tick draws on
changed	Something new	Revised: a revision cloud round one part, with your real version in a triangle (rev)
error	Something went wrong	Out of true: it leans off a plumb line, or sags under a taut string

Every ready-drawn figure draws all six. A figure drawn with the skill can draw only the ones you asked for.

Figures

34 ready-drawn subjects on eight shelves, to use as they are: messages, files, people, money, shopping, time, devices, and the building site the library started from. See them all, in any state, on the site. The full list, with what each one is for, is in docs/options.md.

import { figures } from "ostraca";

Options

Option	Default
state	"idle"	One of the six
value	none	0 to 1 for loading
rev	none	The app's version, for changed
figure	null	{ value, unit }, a real measure for figures that draw one
crew	false	Puts the workers on site
lettered	none	A short word in the drawn pen
title	title and state	The accessible name
decorative	false	Hides it from assistive tech
dir	"ltr"	"rtl" mirrors the drawing
color	--ostraca-thing	Any CSS colour for the drawing
crewColor	--ostraca-crew	Any CSS colour for the workers
paperColor	--ostraca-paper	Any CSS colour for the paper under it

<Ostraca name="inbox" state="empty" color="var(--accent)" crewColor="var(--text)" paperColor="var(--surface)" />

Docs

On the site, or here:

• Start
• Agent skill: the options it asks for, fewer states, standalone pictures
• Usage: HTML, React, server rendering, static SVG, Figma
• States
• Options and figures
• Theming: colours, as tokens or as options, and dark mode
• Workers
• Accessibility

Contributing

Ask for a figure with a figure request, or draw one for the library. CONTRIBUTING.md says how.

Licence

MIT, so the drawings can go in anything you make, commercial or not. See LICENSE.

Made in Cairo by Ahmed Amr. @ahmedamrr_r on X.