Illustrations

Put a scene in an empty state, an onboarding step or a hero, and it's drawn in your theme's colors, light or dark. This one assembles as it comes into view. Point at it and it lifts off.

Each illustration is a small isometric scene: plinths, boxes, cylinders, stacks, turned solids and extruded profiles, shaded from your tokens, with one part in the accent. They cover the moments a product is built around (where its data lives, the machines that serve it, the screens people spend the day in, shipping, safety and the states nobody plans for) and the things people use products for, from shopping and money to travel, food, pets and the weather.

They all frame the same volume, so one scene swaps for another without the layout moving. Draw one by id with <Illustration>, import it as its own component, or pass its id to a block's illustration prop. Each assembles as it comes into view, and comes apart on hover when you ask it to.

The illustrations explorer is the gallery: search every scene by name, category or tag, preview one live in any preset, light or dark, copy its code or its install command, and download it as SVG or PNG.

To make a scene of your own, use the illustration builder (experimental): drag the kit's parts into place, preview it assembling, and export code, SVG or PNG. Draw your own covers the same parts in code.

#Installation

#From the package

Every scene ships in @youj/illustrations. Draw one by id, or import its component:

import { Illustration, IllustrationCoffee } from '@youj/illustrations'

Then add the package's stylesheet to your global CSS, after Tailwind and the tokens. Its sheet points Tailwind at the scenes; without it the classes they use are never generated:

@import 'tailwindcss';
@import '@youj/react/styles.css';
@import '@youj/illustrations/styles.css';

#One scene, as source

To own and edit a single scene, copy it in with the Youj CLI in an app set up from source (npx @youj/cli init --mode registry). Every scene is its own item, illustration-<id>. It brings the kit the scenes are drawn with (illustration-kit) and the shapes it uses, and nothing else. In an app on the packages, the same command installs @youj/illustrations and adds its stylesheet instead:

It lands in components/youj/graphics/illustrations/scenes/<id>.tsx, and you import it from there through your @/ alias:

import { IllustrationCoffee } from '@/components/youj/graphics/illustrations/scenes/coffee'

Each scene's id and install command are on its card in the explorer.

#Every scene

A scene's id is what <Illustration scene> takes, and its component is Illustration and the id in PascalCase (server-rack is IllustrationServerRack). The ids, by category:

From the package, everything on this page comes from @youj/illustrations (pnpm add @youj/illustrations).

@import 'tailwindcss';
@import '@youj/react/styles.css';   /* or '@youj/core/styles.css' without the components */
@import '@youj/illustrations/styles.css';

Its sheet points Tailwind at the built scenes, so it generates the classes they use; it goes after the tokens, in the same file. npx @youj/cli add adds it for you.

From the registry, the illustrations item copies every scene into @/components/youj/graphics/illustrations/, with the kit's shapes they're built from.

#Usage

import { Illustration } from '@youj/illustrations'

export function NoInvoices() {
  return <Illustration scene="documents" title="No invoices yet" />
}

Each scene is also its own component, for when you know which one you want and would rather import it directly:

import { IllustrationDatabase } from '@youj/illustrations'

<IllustrationDatabase explode="hover" />

An id that names no scene draws fallback instead, so an id you stored that outlives its scene still draws something:

import { Illustration } from '@youj/illustrations'

function Empty({ sceneId }: { sceneId: string }) {
  return <Illustration scene={sceneId} fallback="empty" />
}

Every scene frames one volume, so swapping never moves the layout. Keyed on the id, the new one assembles in place:

#Colour

Scenes are gray by default, with the accent as the one coloured part. Turn colour on with colors="theme" and each scene's subject takes one soft hue, and a second hue sets apart a second kind of thing, such as raw and processed data in a pipeline or two people shaking hands. The structure stays neutral and the accent is still the one lit part.

<Illustration scene="pipeline" colors="theme" />

The theme's pair is derived from the accent, so it follows every preset, light or dark:

• Hue 1 is the accent's hue at a muted chroma, the scene's main colour.
• Hue 2 is the hue opposite the accent, for the second kind of thing.
• Hue 3 is a quarter turn away. It is rare, for a third kind.

Hues are mixed toward the surface, so they always sit quieter than the accent.

colors also takes your own colours, in hue order: tokens, brand colours or oklch(). They're softened the same way, and an empty string or a missing entry keeps the theme's:

<Illustration scene="pipeline" colors={['var(--color-success)', 'var(--color-warning)']} />

When you draw your own, give a shape hue={1} or hue={2} on top of its tone, and set colors on the scene. Without colors the shape shows its tone.

#Examples

<AuthShell variant="split" illustration="security">…</AuthShell>
<NoResults illustration="not-found" />
<MarketingCta illustration={<img src="/launch.svg" alt="" />} />
<NoProjects illustration={null} /> {/* the icon on its plates instead */}

import { illustrationCategories, illustrations, isIllustrationId } from '@youj/illustrations'

const byCategory = illustrationCategories.map((category) => ({
  ...category,
  scenes: illustrations.filter((scene) => scene.category === category.id),
}))

// A scene from a URL or a setting, narrowed to one that exists.
const scene = isIllustrationId(params.scene) ? params.scene : 'empty'

#Reference