Put a figure in your product
A Keyline figure is a small web page that draws one object in three.js. You embed that page, choose how it looks in its address, and talk to it with messages. This page covers all of it.
On this page
Quick start
Every figure lives at usekeyline.dev/<id>/index.html. The id is in the address of its page
in the library, and the library's Code tab writes this snippet for you with the
settings you have chosen there. Paste it where the illustration should sit.
<iframe
src="https://usekeyline.dev/empty-inbox/index.html?embed=1&style=brand"
title="Letter tray" width="400" height="320"
style="border:0" loading="lazy"></iframe>This is that snippet, running:
The object builds itself in, then waits. Drag to turn it; it springs back two seconds after you let go. One part, the hero, answers the pointer: hover the top tray and a letter appears above it, click and it drops in. Pinch, or hold Ctrl and scroll, to zoom. Double-click to put the view back.
The drawing fits a 5:4 plate inside whatever size you give the frame, so 400 by 320 is the natural shape and
any other shape adds margin. embed=1 tells the figure it sits in a scrolling page: the wheel and a
vertical swipe keep scrolling your page instead of zooming the object. Keep it on every embed.
Choosing a look
The look is set in the address. Change a setting here and watch both the telescope and its code.
What each setting does
style=lineart- Black and white hairlines with no colour. This is what you get when you leave
styleout. style=brand- Quiet grey lines, with the hero as a solid part in your brand colour and a soft glow behind it.
style=dots- The same drawing as a grid of dots. The hero's dots take the brand colour, and dots near the pointer swell.
dots=shape:square,cell:8changes the mark (circle,square,diamond,line,crossorbar) and the cell size, from 2 to 16 px. brand=2f6bff- The hero's colour in the brand and dots styles: six hex digits, or three, without the
#. Orangef5821fif you leave it out. theme=lighttheme=dark- Without it the figure follows the visitor's system setting. If your site has its own theme switch, set it here and send a message when it changes.
plate=ffffff,0b0b0c- The colour the figure sits on, for light then dark, so it matches your page. The defaults are
f7f7f8and111111. grid=1- A floor grid under the object that fades out with distance and turns with it. Off by default.
intro=stackintro=draw- How the figure arrives. Stack: the parts drop into place one after another. Draw: the lines trace themselves on. Stack is the default.
mode=turntable- No hover, click or drag: the object turns slowly on its own, one cycle every 40 seconds. Made for loading screens and recorded loops.
dpr=1- The pixel ratio to render at, from 0.5 to 3. Left out, the figure uses the screen's ratio up to 2 and lowers it by itself when frames run slow.
Every figure has line art and brand. Most also have dots: a figure's entry in illustrations.json lists its styles, intros and action.
Reacting to the figure
Each figure has one hero part, and most heroes carry an action: a short name such as compose,
upload or home for what a click on it should mean in your product. The figure never
draws words or opens anything itself. When the hero's move reaches its open state, it tells your page, and your
page does the real thing.
The figure posts two messages to the page that embeds it:
ready- Sent once, when the figure can take messages. It carries the figure's
id, itsintrosandstyles, the currentstyleandbrand, andaction: the hero's action name, ornullif it has none. action- Sent each time the hero opens.
idis the action name andfigureis the figure's id.
Listen for them with a message listener, and check where each one came from:
<iframe id="bell"
src="https://usekeyline.dev/ask-bell/index.html?embed=1&style=brand"
title="Desk bell" width="400" height="320" style="border:0"></iframe>
<p id="status">Press the bell.</p>
<script>
const bell = document.getElementById('bell');
const status = document.getElementById('status');
addEventListener('message', (e) => {
if (e.origin !== 'https://usekeyline.dev' || e.source !== bell.contentWindow) return;
const message = e.data;
if (message.type === 'ready') status.textContent = 'Hands over: ' + message.action;
if (message.type === 'action') status.textContent = 'Asked. Open your help panel here.';
});
</script>Here is the same bell. Press its button and this page hears it:
Waiting for the bell to load.
Controlling it from your page
Messages go the other way too. These buttons post to the bell above:
Post to the frame's window once it has sent ready. A figure only listens to the page that embeds it.
const frame = document.getElementById('bell');
const send = (message) => {
frame.contentWindow.postMessage(message, 'https://usekeyline.dev');
};
// The figure cannot hear you until it has said it is ready.
addEventListener('message', (e) => {
if (e.source !== frame.contentWindow || e.data.type !== 'ready') return;
send({ type: 'theme', value: 'dark' });
send({ type: 'style', value: 'dots' });
send({ type: 'brand', value: '#2f6bff' });
});
document.getElementById('again').addEventListener('click', () => {
send({ type: 'replay' });
});themevalue:'light'or'dark'.stylevalue:'lineart','brand'or'dots'. The styles crossfade.brandvalue: a hex colour such as'#2f6bff'.gridvalue:trueorfalse.introvalue:'stack'or'draw'. Sets the intro and plays it.modevalue:'turntable', or anything else for the usual interactive mode.dotsvalue: the settings to change, such as{ shape: 'square', cell: 8 }, ornullfor the defaults.replay- Plays the intro again from the start, with the view back at rest.
reset- Returns the view to rest after the visitor has turned or zoomed it.
pauseresume- Stops the figure's clock and drawing, and starts them again where they stopped.
scrubt: progress from 0 to 1, ornullto hand the figure back to its own clock. See below.
Scroll-driven stories
With scrub, your page owns the figure's time. From 0 to 0.75 the object assembles, part by part;
from 0.75 to 1 the hero makes its move, from rest to open. Send split to move that boundary, or
open: false to spend the whole range on the assembly. While you scrub, the figure plays nothing on
its own and takes no hover.
Start the page with intro=scrub so the figure waits at 0 with nothing built, then send its
progress as the visitor scrolls:
<section id="story" style="height: 300vh">
<iframe id="scope"
src="https://usekeyline.dev/telescope/index.html?embed=1&intro=scrub&style=brand"
title="Refracting telescope"
style="position: sticky; top: 10vh; width: 100%; height: 80vh; border: 0"></iframe>
</section>
<script>
const story = document.getElementById('story');
const scope = document.getElementById('scope');
let ready = false;
function scrub() {
if (!ready) return;
const box = story.getBoundingClientRect();
const t = Math.min(1, Math.max(0, -box.top / (box.height - innerHeight)));
scope.contentWindow.postMessage({ type: 'scrub', t }, 'https://usekeyline.dev');
}
addEventListener('message', (e) => {
if (e.source !== scope.contentWindow || e.data.type !== 'ready') return;
ready = true;
scrub();
});
addEventListener('scroll', scrub, { passive: true });
</script>The two scroll stories on this site
work this way. A scrubbed figure ignores the visitor's reduced motion setting, because your page sets the
pace; if they have asked for less motion, jump between a few fixed values of t instead of
following the scroll.
Many figures on one page
Each embedded figure is its own page with its own WebGL context, and browsers allow only a limited number of those. Up to three or four frames on a page is comfortable. This site keeps at most four live at once, two on phones and slower devices, and shows a still poster for the rest.
Two habits keep frames cheap. Add loading="lazy" so a frame below the fold does not load until
the visitor is near it. And rest a figure while it is off screen: a figure already stops drawing when nothing
moves and when its tab is hidden, and pause covers the case where it is animating out of view.
const seen = new IntersectionObserver((entries) => {
for (const entry of entries) {
const type = entry.isIntersecting ? 'resume' : 'pause';
entry.target.contentWindow.postMessage({ type }, 'https://usekeyline.dev');
}
});
for (const frame of document.querySelectorAll('iframe[src^="https://usekeyline.dev/"]')) {
frame.addEventListener('load', () => seen.observe(frame));
}One canvas for a whole grid
For a page with many figures, such as a gallery, skip the frames. The stage is a module that draws every figure with one WebGL context and copies each into its own element, so the drawings scroll with the page. Only plates on screen are drawn, and only when something in them moves. A figure's intro plays the first time its plate is on screen.
<script type="importmap">
{ "imports": {
"three": "https://cdn.jsdelivr.net/npm/three@0.160.0/build/three.module.js",
"three/addons/": "https://cdn.jsdelivr.net/npm/three@0.160.0/examples/jsm/" } }
</script>
<style>
.plate { width: 400px; max-width: 100%; aspect-ratio: 5 / 4; }
</style>
<div class="plate" id="bell" role="img" aria-label="A desk bell"></div>
<div class="plate" id="scope" role="img" aria-label="A telescope on a tripod"></div>
<script type="module">
import { createStage } from 'https://usekeyline.dev/kernel/stage.js';
import { mountFigure } from 'https://usekeyline.dev/kernel/keyline3d.js';
import { create as bell } from 'https://usekeyline.dev/ask-bell/figure.js';
import { create as scope } from 'https://usekeyline.dev/telescope/figure.js';
const stage = createStage();
for (const [id, create] of [['bell', bell], ['scope', scope]]) {
const plate = document.getElementById(id);
mountFigure(stage, plate, create(plate), 'style=brand');
}
stage.setBrand('#2f6bff'); // every plate at once; also setTheme, setStyle, setGrid
addEventListener('keyline3d:action', (e) => {
console.log(e.detail.id, 'from', e.detail.figure); // 'ask' from 'ask-bell'
});
</script>A plate is any element with a size. It follows the system theme unless you give it
data-theme="light" or "dark", or call stage.setTheme. The fourth
argument of mountFigure takes the same settings as a figure's address. There are no messages on a
stage: mountFigure returns the figure, with replay(), reset(),
pause(), resume(), setStyle(), setBrand() and
scrub(), and an action arrives as a keyline3d:action event on the window.
Fallbacks and performance
What a figure weighs
The engine is about 40 KB gzipped, on top of three.js, and the browser fetches both once for every figure on your site. Each figure then adds 4 to 7 KB of its own.
Posters for slow connections
Every figure has a still SVG of its finished state, framed exactly as the live plate frames it, in both themes:
- Brand style
usekeyline.dev/posters/<id>-light.svgand-dark.svg, in the default orange.- Line art
usekeyline.dev/posters/<id>-lineart-light.svgand-lineart-dark.svg.
Show the poster first, and bring in the live figure only when the connection can carry it. This is what the site itself does:
<style>
#scope { position: relative; width: 400px; max-width: 100%; aspect-ratio: 5 / 4; }
#scope > * { position: absolute; inset: 0; width: 100%; height: 100%; border: 0; }
</style>
<div id="scope">
<img src="https://usekeyline.dev/posters/telescope-light.svg" alt="A telescope on a tripod">
</div>
<script>
const box = document.getElementById('scope');
const net = navigator.connection;
const slow = net && (net.saveData || /^(slow-2g|2g|3g)$/.test(net.effectiveType || ''));
if (!slow) {
const frame = document.createElement('iframe');
frame.title = 'Refracting telescope';
frame.style.opacity = 0;
frame.src = 'https://usekeyline.dev/telescope/index.html?embed=1&style=brand&theme=light';
addEventListener('message', (e) => {
if (e.source !== frame.contentWindow || e.data.type !== 'ready') return;
frame.style.opacity = 1;
box.querySelector('img').remove();
});
box.append(frame);
}
</script>navigator.connection exists only in some browsers. Where it is missing this loads the live
figure, which is the right default.
Your own stills
Posters come in orange. For a still in your colour, or a PNG, ask a running figure to export one. It renders off screen and leaves the live view alone.
const frame = document.querySelector('iframe');
function ask(format, opts = {}) {
return new Promise((resolve, reject) => {
const id = crypto.randomUUID();
addEventListener('message', function answer(e) {
const m = e.data;
if (e.source !== frame.contentWindow || m.type !== 'export-result' || m.id !== id) return;
removeEventListener('message', answer);
m.ok ? resolve(m.data) : reject(new Error(m.data));
});
frame.contentWindow.postMessage({ type: 'export', id, format, opts }, 'https://usekeyline.dev');
});
}
// after the figure's ready message
const t = await ask('duration'); // ms until the intro has settled
const svg = await ask('svg', { t, width: 520, height: 416, background: 'plate' });
const png = await ask('png', { t, width: 1200, height: 960 }); // a BlobReduced motion
You do not need to do anything. When the visitor's system asks for reduced motion, a figure skips its intro
and shows its finished state, the view stops springing, and the turntable holds still. Hover and click still
work. Add reduced=1 to the address to see it.
Screens in device figures
The phone (device-phone) and the laptop (device-laptop) can show your own
screenshot. Pass its address as shot, URL-encoded. The picture is cropped to cover the screen,
aligned to its top. Without shot, the screen shows a drawn placeholder app.
<iframe
src="https://usekeyline.dev/device-phone/index.html?embed=1&shot=https%3A%2F%2Fexample.com%2Fhome.png"
title="Our app on a phone" width="400" height="320"
style="border:0" loading="lazy"></iframe>The figure draws the picture in WebGL, so the image has to come from the same site as the figure or be served with CORS headers that allow it. If it cannot load, the placeholder app stays. On the phone, a click scrolls a picture that is taller than the screen. Both device figures are part of Pro.
Drawing your own
When the library has no object for your moment, the skill teaches Claude Code to draw a new one in the same hand, on the same engine, so everything on this page applies to it. It is free.
npx keyline-3d installRestart Claude Code, then ask in plain words and name the skill:
draw an empty state for no messages with keyline-3d in our brand colour #2f6bffThe skill page has the full install steps, including a manual install without Node.
Free, Pro and licence
The figures marked Free in the library can be embedded as shown here, with no account. The skill is free, and its npm package is MIT licensed. Pro is a single payment for the rest of the library and the source files of every figure, to edit and ship yourself. Checkout is not open yet. The pricing page has the plans.