Blueprint

Use it for an entrance that explains how a piece of UI is built: a hero demo, a product tour, a component on show. A draftsman lays out the frame, measures off its regions and pencils every part, while two columns beside it log the build and the values it applies. Then a ruled edge sweeps down and inks the real UI in, part by part. Keep it to one moment on a page: it asks to be watched, and a second one in view competes with the first.

#Installation

#Usage

Wrap the UI in BlueprintEntrance. It drafts its first child and plays on mount.

import { BlueprintEntrance } from '@youj/motion'

export function Hero() {
  return (
    <BlueprintEntrance>
      <SignInCard />
    </BlueprintEntrance>
  )
}

Change play to play it again (a counter works), or set it to false to show the UI as it is. onFinish is called when the run ends.

For an element you don't render with React, call the engine. It returns a cancel() and a finished promise, and an AbortSignal in signal cancels it too. To drive it from a clock of your own (a video rendered frame by frame, a scrubber), pass paused: true and call seek(t) with the time in ms from its start: it shows that moment and holds it. It only goes forwards, and a time at or past its end ends it.

import { blueprint } from '@youj/motion'

const run = blueprint(document.querySelector('#pricing')!, { speed: 1.5 })
await run.finished

#Pacing

The build goes through seven stages, each advancing through the parts in build order, so it is visibly in progress from the first mark to the last: survey (the paper, the bounds and their dimensions), layout (the main regions), detail (every part in dotted pencil), ink (each outline traced over solid), tone (filled boxes in flat greys, hatching or a screen), set (the text sets in grey, line by line, and icons and charts trace their real shapes) and finish (a ruled edge sweeps down, and behind it the real colour, radii, shadows and images come in). It stays black and white until the finish.

The length grows with the demo: about 2 seconds for a card, about 3.5 for a small screen, and at most about 6 for a large one. Three options tune it:

• duration fixes the whole run, in milliseconds.
• speed scales it: 2 plays twice as fast. It applies on top of duration and the provider's speed.
• phases shares the run out between the seven stages. The values are weights, so they are normalized and never change the total; a stage left out keeps its default ({ survey: 10, layout: 10, detail: 20, ink: 13, tone: 12, set: 13, finish: 22 }), and 0 skips it.

// a 2.4 s run with a quick pencil draft and a long, readable build-up
<BlueprintEntrance duration={2400} phases={{ survey: 6, layout: 6, detail: 12, ink: 18, tone: 18, set: 22, finish: 18 }}>
  <PricingCard />
</BlueprintEntrance>

A demo with no regions gives the layout's share to the detail.

The side columns show when there are about 180 pixels free on a side, inside the nearest container that clips; columns="none" leaves them out.

#What it reads

The draft comes from the real DOM, read once before the first frame: roles, tags and data-slot first, then geometry. Boxes with a fill, a border or a shadow are drafted as dotted outlines, text as dotted baselines with a cap-height tick, icons as their square with a centre mark, charts as their axes, images as a crossed box, list rows as one line, and fields with a caret. The largest boxes become the numbered regions. Anything it can't classify, and open popovers, simply appear at the finish. Fills, borders and type are logged with the theme's token names, like fill surface and ink fg-muted.

#Reference

function blueprint(node: HTMLElement, options?: BlueprintOptions): { cancel(): void; finished: Promise<void>; seek(t: number): void }