An isometric drawing of how something works. Its parts move and light up as you step through it.
Fig. 1How a reply gets made
- Sources, citations and your approval
- Ticket and reply
- The desk
'use client';
import { ExplainerFigure } from '@brand-studio/ui';
import replyDesk from './reply-desk.json';
export default function ExplainerFigureDemo() {
return (
<div style={{ width: '100%', maxWidth: 560 }}>
<ExplainerFigure figure={replyDesk} />
</div>
);
}Installation
pnpm add @brand-studio/uinpm install @brand-studio/uiyarn add @brand-studio/uibun add @brand-studio/uiInstall the peer dependencies
npm install react react-domImport the stylesheet once
import '@brand-studio/ui/styles.css';Wrap your app in a brand theme
import { BrandTheme, ExplainerFigure } from '@brand-studio/ui'; import brand from './brand.json'; <BrandTheme palette={brand.tokens} mode="system"> {/* your app */} </BrandTheme>
Usage
import { ExplainerFigure } from '@brand-studio/ui';
import replyDesk from './reply-desk.json';<ExplainerFigure figure={replyDesk} />The component draws from data. Write the object as a parts list and let the brand-design skill check it and export figure.model.json. The component draws that file in the colours of the brand theme around it, in light and dark.
People move through the steps four ways: the step list, the arrow keys, a sideways drag on the drawing, and Play, which walks to the last step and stops.
Brand-drawn (prototype)
The same story drawn on a paper desk in Deskhand's own materials. A highlighter pen marks the line each source gives, the reply writes itself and cites them, and the refund stops at the limit. Drag the desk to scrub, or switch to the machine to compare.
Fig. 1How a reply gets made
- Highlighter: what Deskhand read, cited and holds
- Paper: the ticket, sources and reply
'use client';
import { useState } from 'react';
import { BrandTheme, ExplainerFigure } from '@brand-studio/ui';
import { brands } from '../../lib/brands';
import { useDemoBrand } from '../../components/demo-brand';
import { ReplyDesk, type DeskStory } from '../../lab/paper/reply-desk';
import replyDesk from './reply-desk.json';
// Ticket #2291 as the Deskhand showcase tells it: the same claims, sources and numbering.
const story: DeskStory = {
fig: 'Fig. 1', title: 'How a reply gets made',
alt: 'A support ticket on a paper desk. Three source documents slide out, a highlighter marks the line used in each, the drafted reply highlights three claims joined by lines to those lines, and the $84 refund stops at the $50 limit to wait for approval.',
caption: 'Ticket #2291: Deskhand reads three sources, cites each claim, and holds the $84 refund until you approve it.',
ticket: { label: 'Ticket', id: '#2291', from: 'Priya N.', text: 'The Orla lamp arrived with a cracked base. Can I get a refund?' },
sources: [
{ kind: 'Help center', title: 'Returns and refunds', form: 'article', rows: [
{ text: 'Unused items can be returned within 30 days for a full refund.' },
{ text: 'Items damaged in transit are refunded in full. No return is needed.', cited: true },
{ text: 'Sale items can be exchanged for another size or colour.' },
] },
{ kind: 'Order', title: '#48213', form: 'receipt', rows: [
{ text: 'Placed', value: '11 Sep' }, { text: 'Delivered', value: '16 Sep' },
{ text: 'Orla table lamp', value: '$84.00', cited: true }, { text: 'Shipping', value: '$0.00' }, { text: 'Paid', value: 'Visa 4417' },
] },
{ kind: 'Help center', title: 'Payments', form: 'page', rows: [
{ text: 'We accept Visa, Mastercard and PayPal.' },
{ text: 'Refunds reach the original card in 3 to 5 business days.', cited: true },
], days: { from: 3, to: 5, of: 5, label: 'Business days' } },
],
reply: { draft: 'Draft', held: 'Waiting for you', parts: [
'Hi Priya, sorry the lamp arrived cracked.', { cite: 1, text: 'Damaged items are refunded in full,' },
'so no need to send it back. I’ve set up a refund of', { cite: 2, text: '$84.00 for order #48213.' },
{ cite: 3, text: 'It reaches your card in 3 to 5 business days.' },
] },
gate: { text: 'Refund $84 is over your $50 limit.', action: 'Approve and send', amount: 84, limit: 50, currency: '$', limitLabel: 'Refund limit' },
steps: [
{ label: 'Ticket #2291 comes in', readout: 'The Orla lamp arrived with a cracked base' },
{ label: 'Deskhand opens three sources', readout: 'Returns and refunds · Order #48213 · Payments' },
{ label: 'Each claim cites a line', readout: '3 claims · 3 sources · $84.00 refund' },
{ label: 'Over $50? It waits for you', readout: 'Refund $84 is over your $50 limit' },
],
legend: [{ tone: 'lit', label: 'Highlighter: what Deskhand read, cited and holds' }, { tone: 'subject', label: 'Paper: the ticket, sources and reply' }],
};
export default function ExplainerFigureBrandDrawnDemo() {
const { mode } = useDemoBrand();
const [view, setView] = useState<'brand' | 'machine'>('brand');
return (
<BrandTheme palette={brands.deskhand.palette} mode={mode} style={{ width: '100%', maxWidth: 760, display: 'grid', gap: 12, padding: 12, borderRadius: 16, background: 'var(--bs-surface)', color: 'var(--bs-ink)' }}>
<div role="group" aria-label="Figure style" style={{ display: 'flex', gap: 4, padding: 3, justifySelf: 'start', borderRadius: 999, boxShadow: 'inset 0 0 0 1px var(--bs-line)' }}>
{([['brand', 'Brand-drawn'], ['machine', 'Machine (now)']] as const).map(([key, label]) => (
<button key={key} type="button" aria-pressed={view === key} onClick={() => setView(key)}
style={{ minHeight: 36, padding: '0 14px', border: 0, borderRadius: 999, font: 'inherit', fontSize: 13, cursor: 'pointer', color: view === key ? 'var(--bs-on-accent)' : 'var(--bs-muted)', background: view === key ? 'var(--bs-accent)' : 'transparent' }}>
{label}
</button>
))}
</div>
{view === 'brand' ? <ReplyDesk story={story} /> : <ExplainerFigure figure={replyDesk} />}
</BrandTheme>
);
}Live input (prototype)
Drag the input and the drawers follow it; the readout updates as each source is read.
Fig. 1How a reply gets made
- Sources, citations and your approval
- Ticket and reply
- The desk
'use client';
import { useRef, useState, type KeyboardEvent } from 'react';
import { ExplainerFigure } from '@brand-studio/ui';
import liveDesk from './live-desk.json';
const sources = ['Returns and refunds', 'Order #48213', 'Payments'];
export default function ExplainerFigureLiveInputDemo() {
// value runs from 1 to 3 sources; the figure's first three steps are one, two and three drawers open.
const [value, setValue] = useState(1);
// The slider drives the figure only while someone uses it; otherwise the step list and drag own it and the slider follows.
const [driving, setDriving] = useState(false);
const tween = useRef(0);
const glide = (to: number) => {
cancelAnimationFrame(tween.current);
setDriving(true);
const from = value, start = performance.now();
const frame = (now: number) => {
const t = Math.min((now - start) / 320, 1), eased = 1 - (1 - t) ** 3;
setValue(from + (to - from) * eased);
if (t < 1) tween.current = requestAnimationFrame(frame); else setDriving(false);
};
tween.current = requestAnimationFrame(frame);
};
const keys = (event: KeyboardEvent<HTMLInputElement>) => {
const to = ({ ArrowRight: Math.round(value) + 1, ArrowUp: Math.round(value) + 1, ArrowLeft: Math.round(value) - 1, ArrowDown: Math.round(value) - 1, Home: 1, End: 3 } as Record<string, number>)[event.key];
if (to === undefined) return;
event.preventDefault();
glide(Math.max(1, Math.min(3, to)));
};
const read = Math.round(value);
return (
<div style={{ width: '100%', maxWidth: 560, display: 'grid', gap: 12 }}>
<label style={{ display: 'grid', gap: 6, padding: '0 10px' }}>
<span style={{ display: 'flex', justifyContent: 'space-between', gap: 12, font: '11px/1.3 ui-monospace, SFMono-Regular, Menlo, monospace', letterSpacing: '.06em', textTransform: 'uppercase', color: 'var(--bs-muted)' }}>
<span>Sources read</span><span style={{ color: 'var(--bs-ink)' }}>{read} of 3</span>
</span>
<input type="range" min={1} max={3} step={0.01} value={value} aria-valuetext={`${read} of 3 sources read`}
onChange={event => { cancelAnimationFrame(tween.current); setDriving(true); setValue(Number(event.target.value)); }}
onPointerUp={() => glide(Math.round(value))} onKeyDown={keys}
style={{ width: '100%', minHeight: 44, accentColor: 'var(--bs-accent)', cursor: 'ew-resize' }} />
<span style={{ fontSize: 13, color: 'var(--bs-muted)' }} aria-live="polite">{sources.slice(0, read).join(' · ')}</span>
</label>
<ExplainerFigure figure={liveDesk} position={driving ? value - 1 : undefined} onStepChange={step => { if (!driving) setValue(Math.min(step, 2) + 1); }} />
</div>
);
}Drive it from the page
Pass position to let a slider or scroll progress scrub the drawing. 0 is the first step and each whole number is the next; a value between two steps draws the move part-way.
<ExplainerFigure figure={replyDesk} position={progress * 2} onStepChange={setStep} />Accessibility
- The step list is a tab list. Arrow keys, Home and End move between steps, and each step states its result in text.
- The drawing carries the figure's description. The accent marks one part per step, and the step's label names it, so colour is never the only cue.
- Nothing moves until someone asks. Reduced motion changes each step at once.
- Before scripts run, the first step is drawn with every step's text beneath it.
API Reference
| Prop | Type | Default |
|---|---|---|
figure | FigureModel | – |
position? | number | – |
onStepChange? | ((step: number) => void) | – |
playLabel? | string | 'Play' |
pauseLabel? | string | 'Pause' |
className? | string | '' |