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
  1. Quick start
  2. Choosing a look
  3. Reacting to the figure
  4. Controlling it from your page
  5. Many figures on one page
  6. Fallbacks and performance
  7. Screens in device figures
  8. Drawing your own
  9. Free, Pro and licence

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.

HTML
<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.

Style
Brand colour
Theme
Floor grid
Intro
Mode
HTML

What each setting does

style=lineart
Black and white hairlines with no colour. This is what you get when you leave style out.
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:8 changes the mark (circle, square, diamond, line, cross or bar) 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 #. Orange f5821f if you leave it out.
theme=light
theme=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 f7f7f8 and 111111.
grid=1
A floor grid under the object that fades out with distance and turns with it. Off by default.
intro=stack
intro=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, its intros and styles, the current style and brand, and action: the hero's action name, or null if it has none.
action
Sent each time the hero opens. id is the action name and figure is the figure's id.

Listen for them with a message listener, and check where each one came from:

HTML
<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.

JavaScript
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' });
});
theme
value: 'light' or 'dark'.
style
value: 'lineart', 'brand' or 'dots'. The styles crossfade.
brand
value: a hex colour such as '#2f6bff'.
grid
value: true or false.
intro
value: 'stack' or 'draw'. Sets the intro and plays it.
mode
value: 'turntable', or anything else for the usual interactive mode.
dots
value: the settings to change, such as { shape: 'square', cell: 8 }, or null for 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.
pause
resume
Stops the figure's clock and drawing, and starts them again where they stopped.
scrub
t: progress from 0 to 1, or null to 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:

HTML
<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.

JavaScript
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.

HTML
<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.svg and -dark.svg, in the default orange.
Line art
usekeyline.dev/posters/<id>-lineart-light.svg and -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:

HTML
<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.

JavaScript
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 Blob

Reduced 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.

HTML
<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.

Terminal
npx keyline-3d install

Restart Claude Code, then ask in plain words and name the skill:

Prompt
draw an empty state for no messages with keyline-3d in our brand colour #2f6bff

The 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.