Bot studio
NewAn editor for animated agent avatars: pick a flat shape and a colour, switch its face between Idle, Thinking and Happy, and export the spec.
bot-studio/bot-studio.tsxA shape id or your own paths in a 100-unit box, a hex colour and a state.
The live component, numbered part by part. Every measurement is read from it as it is drawn. Point at a row to outline its part, or at a part to find its row.
The choices it offers, each value drawn live and the default marked, with how to pick one.
When to use
- Giving each agent in a product a face of its own: a picker in its settings, next to its name and instructions.
- Showing what an agent is doing with a face instead of a spinner:
Thinkingwhile it works,Happywhen it is done,Idlethe rest of the time. - Handing an avatar to other code as data: the spec is a few lines of JSON, and Export makes a static SVG or PNG from it.
- Onboarding, where the first agent someone makes should feel like theirs in two clicks.
When not to use
- People’s avatars. A bot face reads as a machine; use photos or initials for humans.
- A status that needs words: “Waiting for approval”, “3 of 5 steps”. Show the face, but say the status in text beside it.
- Dense lists with dozens of agents on screen: run the figure as a still (
liveoff) or a static SVG, so it doesn’t blink in every row. - Brand marks. The shapes are friendly and generic on purpose; a logo needs its own drawing.
The spec
- Four fields:
version(1),shape(a built-in id such ascat, or{ name, paths, face }),color(#rrggbb) andstate. - Your own shape is up to 12 strings of SVG path data in a 100 × 100 box, filled;
faceis[x, y, scale], where the eyes go. Only path commands and numbers are accepted. - The same spec everywhere: the live
BotFigure, the downloaded SVG (botToSvg) and Import all read it, so a bot made here looks the same in a chat header or a file.
Picking a colour
- A new shape brings its own colour, the one its tile shows; a swatch after that recolours it.
- The rainbow ring opens the system’s colour picker for any colour; the reset button brings back the shape’s own.
- Light colours get a hairline, so a white bot still has an edge on a light page.
Each one drawn with the component itself, used well or badly.
The words are few: the states, the shape and colour names in tooltips, the menu items and the messages under Import.
- State names are one word, in title case:
Idle,Thinking,Happy. - Shape names are plain nouns:
Cat,Cloud,Robot. An imported shape names itself, up to 24 characters. - Errors say what to fix: ““color” should be a hex colour like #f39b1f.”, not “Invalid input”.
You can add this component with the shadcn CLI or by hand:
Into components/bot-studio of any React project, with no setup:
npx shadcn@latest add https://brunodelorence.com/r/bot-studio.json- Copy the component files
Copy these files into one folder of your project, keeping their relative imports together, or download them as a ZIP:
- Import it
As shown under Usage, below.
Either way it needs React 19.2 and a bundler that supports CSS Modules, such as Next.js or Vite. It has a dark colour scheme: it follows your page’s color-scheme, light unless the page sets one, or its colorScheme prop, with nothing to configure. Browsers without light-dark() show it light.
Usage
import { useState } from 'react';import { BotFigure, resolveShape, type BotSpec } from './bot-avatar';import { BotStudio } from './bot-studio';export function AgentFace() { const [bot, setBot] = useState<BotSpec>({ version: 1, shape: 'cloud', color: '#1fbfa2', state: 'idle', }); return ( <> <BotStudio defaultSpec={bot} onSpecChange={setBot} autoplay={false} /> {/* The same spec, anywhere else: */} <BotFigure shape={resolveShape(bot.shape)} color={bot.color} state="thinking" live /> </> );}Each state below is a live instance, locked so you can study it.
The pieces it is built from, each with its measurements read live.
A dark studio with a big bot on the left and a picker on the right. The bot is drawn from a few lines of JSON: one of 22 flat silhouettes (a cat, a cloud, a robot, a leaf…) in one of eleven colours, with a simple face. Under it, Idle, Thinking and Happy change that face: the pill eyes blink, look up while the dots rise, or squash into ^^ as the bot hops and rocks. The panel picks the shape from a grid and the colour from a row of swatches, makes a bot from an agent’s name, or reads a spec pasted in, even one with a shape of its own; Export and Copy hand it on as an SVG, a PNG, SVG markup or JSON.
- A bot is a spec: { version: 1, shape, color, state }. The shape is a built-in id or { name, paths, face } of its own; the same object draws the live figure, the static SVG file and the PNG (the SVG drawn onto a 512-px canvas).
- Each of the 22 shapes is a few pieces in a 100 × 100 box: filled paths, stroked lines (a tail, a handle, an antenna) and filled polygons stroked in their own colour for round corners. The chosen tile’s outline is the same pieces stroked 16 units wider underneath, then 9 wider in the panel’s colour, so the ring follows the silhouette with a gap.
- The eyes are 9 × 24 pills 24 units apart at the shape’s face point. Each state is CSS on the same elements: into Happy the pills squash to a sixth in 110 ms and the ^^ arcs grow out of the dash on a 200 ms overshoot; back to Idle the arcs go first and the pills grow out after 70 ms.
- Idle breathes (1.5% over 3.6 s) and blinks for 170 ms at a random moment every 2.4 to 5.2 s. Happy hops once (560 ms of squash, stretch and landing, Web Animations API) and rocks ±3° on a 1.3 s loop. Thinking narrows the eyes to 62%, looks up and drifts over 2.8 s, tilts 4° over 3.2 s, and raises three dots 180 ms apart.
- A new shape pops in from 86% with a 4% overshoot in 320 ms and brings its own colour; a swatch recolours it with a 220 ms fill transition, and the tile in the grid takes the colour too.
- Generate hashes the agent’s name (FNV-1a) to a shape and a colour, so the same name always gives the same bot. Import checks every field and accepts only path commands and numbers in custom path data.
- Sizes follow the stage’s width with container query units, from a 2000-px reference: the avatar 30% of it, the panel 40% (340 to 470 px) with five tiles to a row; under 700 px the avatar stacks over a full-width panel.
- While on screen and untouched, a demo pointer makes the bot happy, tries the leaf, pink and the bubble, goes back to idle and thinking, and returns to the cat; any input from the reader stops it.
| Prop | Type | Default | Description |
|---|---|---|---|
defaultSpec | Partial<BotSpec> | — | The bot it starts with: { shape, color, state }. Fields left out come from the amber cat, idle; a shape given alone brings its own colour. |
onSpecChange | (spec: BotSpec) => void | — | Called with the whole spec after every change. |
defaultTab | 'bot' | 'generate' | 'import' | 'bot' | The panel’s tab at first. |
autoplay | boolean | true | While on screen and untouched, a demo pointer tries states, shapes and colours; any input from the reader stops it. |
colorScheme | 'light' | 'dark' | 'system' | — | Light or dark colours, or the reader’s; without it, the page’s color-scheme. |
className | string | — | A class for the stage. |
Keyboard
- The shapes, the swatches and the states are radio groups, one tab stop each. The arrows move and choose; in the grid ↑ and ↓ move a row. Home and End go to the ends.
- The tabs are a tablist: ← and → move between them and open them.
- Export and Copy are menu buttons: Enter, Space or ↓ opens one on its first item, ↑ on its last; Escape closes it and gives the focus back.
- Every control shows a 2-px focus ring; tiles and swatches also show their name on keyboard focus.
Screen readers
- The avatar is an image named by its spec: “Cat bot, amber, idle”.
- Each tile and swatch is a radio named by its shape or colour; the rainbow ring is a colour input named Custom colour.
- A polite live region says each change (“Shape: Leaf”, “State: Happy”) and the result of Copy, Export, Generate and Import.
Motion
With reduced motion the bot is drawn still in every state: no blink, hop, rock, drift or rising dots (the dots stay, unmoving), and the demo does not play.
Colour and contrast
The eyes are near-black on every colour of the palette, the lightest of which gets a hairline on a light stage. The chosen swatch is marked by a ring, not by its colour, and every swatch has its colour’s name.
In this build
- The shapes, the swatches and the states are radio groups with one tab stop each: the arrows move and choose, ↑ and ↓ a row in the shape grid, Home and End the ends.
- The panel’s tabs are a tablist; the hidden pages are inert. Export and Copy are menu buttons with arrow keys, Escape and focus return.
- The avatar is an image named by its spec (“Cat bot, amber, idle”); every tile and swatch is named, and shows its name in a tooltip on hover and on keyboard focus.
- A polite live region says each change and the result of Copy, Export, Generate and Import. Import’s errors are tied to the field with aria-describedby and aria-invalid.
- Every control shows a 2-px focus ring on keyboard focus. The demo pointer is hidden from screen readers.
- With reduced motion the bot is drawn still in every state: no blink, hop, rock, drift or pop, and the demo does not play.
The complete source behind this demo. Open source under the MIT license, © 2026 Bruno Delorence: copy it, change it, ship it.
// Copyright (c) 2026 Bruno Delorence. MIT License.'use client';import { useEffect, useEffectEvent, useId, useMemo, useRef, useState, type KeyboardEvent as ReactKeyboardEvent,} from 'react';import { ActionMenu } from './action-menu';import { BotFigure, botToSvg, DEFAULT_SPEC, parseSpec, resolveShape, shapeName, specToJson, STATES, type BotSpec,/* Bot studio (bot-studio.tsx): a dark studio, the big avatar on the left with its state switch and Export / Copy under it, the picker panel on the right. Sizes follow the stage's width (container query units), from measurements of a 2000-px-wide studio: the avatar's shape a quarter of the stage, the panel two fifths (793 px there) with a 44-px radius, its tiles on a 148-px pitch and its swatches 46 px. Under 700 px the two columns stack, the panel full width. Colours are the tokens below, light-dark(light, dark): the component takes the color-scheme it inherits from the page, or the one its colorScheme prop sets. The bots keep their colours in both schemes; their eyes are always near-black. */.root { --stage: light-dark(#f3f3f1, #101010); --ink: light-dark(#1b1b1b, #ededed); --muted: light-dark(#6c6c6c, #8d8d8d); --panel: light-dark(#ffffff, #1a1a1a); --panel-edge: light-dark(rgb(0 0 0 / 0.08), rgb(255 255 255 / 0.07)); --panel-shadow: light-dark(rgb(0 0 0 / 0.06), rgb(0 0 0 / 0.4)); --rule: light-dark(rgb(0 0 0 / 0.07), rgb(255 255 255 / 0.06)); --chip: light-dark(#ececea, #262626); --chip-hover: light-dark(#e4e4e2, #2e2e2e); --button: light-dark(#ffffff, #1d1d1d); --button-edge: light-dark(rgb(0 0 0 / 0.1), rgb(255 255 255 / 0.06));// Copyright (c) 2026 Bruno Delorence. MIT License.'use client';import { useEffect, useRef, useState } from 'react';import { SHAPE_IDS, shapeById, SHAPES, type Face, type Piece, type ShapeDef } from './shapes';import styles from './bot-avatar.module.css';/* * The bot spec and its renderer. A bot is a small JSON object: a shape (one of the built-in ids, * or path data of its own), a colour and a state. The same spec draws the live avatar here, a * static SVG file (botToSvg), and comes back in through parseSpec. * * The face is two eyes on top of the silhouette, at the shape's `face` point. Each state is a * layer of CSS on the same few elements, so a change of state is a transition, not a redraw: * - Idle: 9 × 24 pills; the body breathes (1.5% over 3.6 s) and the eyes blink every 2.4–5.2 s * (170 ms, the lids down to a tenth). * - Happy: the pills squash to a dash in 110 ms and the ^^ arcs open out of it; the body hops * once (560 ms, squash and stretch) and rocks ±3° on a 1.3 s loop. * - Thinking: the eyes narrow and look up, drifting side to side; the head tilts slowly and three * dots rise in turn at its top right. * With reduced motion every state is drawn still: no blink, hop, rock or drift. *//* The bot figure (bot-avatar.tsx): the silhouette, the eyes, and the motion of each state. Lengths inside the SVG are its own units (the shape's box is 100 across); the transforms that move whole groups use fill-box, so each turns and squashes about its own bottom or middle. */.figure { --bot-ink: #141414; --bot-hairline: rgb(0 0 0 / 0.14); --bot-dots: light-dark(#a3a3a3, #6f6f6f); display: block; overflow: visible; stroke-linecap: round; stroke-linejoin: round;}.hop,.sway,.morph { transform-box: fill-box; transform-origin: 50% 100%;}.morph { transform-origin: 50% 60%;}// Copyright (c) 2026 Bruno Delorence. MIT License./* * The bot shapes: flat silhouettes in a 100 × 100 box, each made of a few pieces, so no path has * to be one hand-traced outline. A piece is filled, or a stroked line (a tail, a handle, an * antenna), or both: a filled polygon stroked in its own colour gets round corners for free. The * selected tile's ring is the same pieces stroked wider underneath, so it follows the silhouette. * * `face` is where the eyes sit and how big they are: [x, y, scale], in the same box. At scale 1 * the eyes are 9 × 24 pills, 24 apart, as on the cat. */export type Piece = { d: string; /** False for a line: stroked only. */ fill?: boolean; /** The stroke's width: a line's thickness, or the rounding of a filled piece's corners. */ w?: number;};export type Face = [x: number, y: number, scale: number];export type ShapeDef = { id: string;// Copyright (c) 2026 Bruno Delorence. MIT License.'use client';import { useEffect, useId, useRef, useState, type KeyboardEvent, type ReactNode } from 'react';import { Glyph } from './glyphs';import styles from './bot-studio.module.css';/* * Export ▾ and Copy ▾: a menu button (the ARIA pattern). Enter, Space or ↓ opens it with the * focus on the first item, ↑ on the last; the arrows, Home and End move, Escape or Tab closes it * and a press anywhere else too. Choosing an item runs it and gives the focus back to the button. *//** Focuses the menu's item at `index`, counting from the end when it is negative. */function focusIn(menu: HTMLElement | null, index: number) { const all = menu?.querySelectorAll<HTMLElement>('[role="menuitem"]'); if (!all?.length) return; all[(index + all.length) % all.length].focus();}export type MenuItem = { id: string; label: string; hint: string; run: () => void };export function ActionMenu({// Copyright (c) 2026 Bruno Delorence. MIT License./* * The studio's small icons, drawn on a 16-unit grid in the current text colour. All decorative: * the control around each one carries its name. */type Name = 'download' | 'copy' | 'chevron' | 'plus' | 'reset' | 'shuffle';const PATHS: Record<Name, string> = { download: 'M8 2.5v7.5M4.8 7 8 10.2 11.2 7M3 13.5h10', copy: 'M5.5 5.5V4a1.5 1.5 0 0 1 1.5-1.5h5A1.5 1.5 0 0 1 13.5 4v5a1.5 1.5 0 0 1-1.5 1.5h-1.5M4 5.5h5A1.5 1.5 0 0 1 10.5 7v5A1.5 1.5 0 0 1 9 13.5H4A1.5 1.5 0 0 1 2.5 12V7A1.5 1.5 0 0 1 4 5.5z', chevron: 'M4.5 6.5 8 10l3.5-3.5', plus: 'M8 3v10M3 8h10', reset: 'M3.2 8a4.8 4.8 0 1 0 1.5-3.5M3.2 2.6v2.6h2.6', shuffle: 'M2.5 4.5h2c3 0 4 7 7 7h2M11.5 9.5l2 2-2 2M2.5 11.5h2c1.2 0 2-.9 2.7-2.2M9 6.6c.6-1.2 1.3-2.1 2.5-2.1h2M11.5 2.5l2 2-2 2',};export function Glyph({ name, className }: { name: Name; className?: string }) { return ( <svg className={className} viewBox="0 0 16 16"// Copyright (c) 2026 Bruno Delorence. MIT License.'use client';import type { CSSProperties, Ref } from 'react';/* * The demo's pointer, and the steps that move it. A demo is a script of awaited steps: wait, or * glide the pointer somewhere. Stopping the demo (the reader takes over, or it scrolls away) ends * the step in progress at once: its promise rejects, which ends the script right there, and the * pointer fades out. * * Each glide is a curved flight played by the Web Animations API, so nothing runs frame by frame. * The points of the flight are handed to whoever wants to move along with it (nothing here uses * them yet). The arrow and the hand are HTML boxes * that swap by their visibility: a change of style inside an SVG would lay the SVG out again. */export type Point = { x: number; y: number };/** A glide's path and timing, for an animation that plays along with it. */export type Flight = { points: Point[]; timing: KeyframeAnimationOptions };export type Demo = {// Copyright (c) 2026 Bruno Delorence. MIT License.'use client';import { useCallback, useEffect, useRef, useState } from 'react';/* * When a demo may play on its own: while part of it is on screen and the tab is visible, never * under reduced motion, and never again once the reader has used it: `take()` hands it to the * reader for good (until the component mounts again), so it can't come back on its own. */export function useAutoplay<T extends HTMLElement>() { const ref = useRef<T>(null); const [visible, setVisible] = useState(false); const [reduced, setReduced] = useState(true); const [taken, setTaken] = useState(false); useEffect(() => { const element = ref.current; if (!element) return; let onScreen = false; const update = () => setVisible(onScreen && !document.hidden); const observer = new IntersectionObserver( ([entry]) => {