Bruno DelorenceBruno
Appearance
Appearance

Choose your reading theme.

Contact

Bot studio

New

An 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.tsx
Live · interactive

The same name always gives the same bot.

A 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: Thinking while it works, Happy when it is done, Idle the 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 (live off) 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 as cat, or { name, paths, face }), color (#rrggbb) and state.
  • Your own shape is up to 12 strings of SVG path data in a 100 × 100 box, filled; face is [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:

Terminal
npx shadcn@latest add https://brunodelorence.com/r/bot-studio.json

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

agent-face.tsx
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.
PropTypeDefaultDescription
defaultSpecPartial<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.
autoplaybooleantrueWhile 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.
classNamestring—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.

bot-studio.tsx
// 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.module.css
/* 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));
bot-avatar.tsx
// 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. */
bot-avatar.module.css
/* 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%;}
shapes.ts
// 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;
action-menu.tsx
// 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({
glyphs.tsx
// 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"
demo-pointer.tsx
// 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 = {
use-autoplay.ts
// 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]) => {