Storybook and your first component¶

Exercise storybook-first-component-annex.pdf · PDF

Open your NoteBox code and search for <button. How many did you find? Now the designer says: "corners go from 8 px to 12 px." How many files do you open?

If you copy and paste, you have two problems. If you paste eight times, you have eight. In Figma you already solved this: one main component, many instances. Change the main, and every instance follows. This unit does the same thing in code, and this page builds the first piece.

The brick¶

A reusable component is a piece of interface built once, with a fixed connection, and used in many places. It knows nothing about the page it lives in: it receives everything through its connection.

LEGO filed the patent for its stud-and-tube brick on 28 January 1958, and a brick from that year still fits one made today. Why? The connection never changed. Nobody asks how a brick is made inside. You only need to know its studs.

We keep LEGO for the whole unit. The brick is the component. The studs are its props, the values you pass in. The model you build is the app.

Five tools, five jobs¶

Making a brick properly takes more than one tool. These five come back all through the unit:

Figma designs. Vitest and Playwright test. Storybook sits in the middle: you design in code there, and you test by looking.

Read the blueprint¶

Before you write a line, read the spec. Click an instance of a Figma component and look at the right-hand panel. For our Button it lists what can change:

The spec also names its colours. Open Local variables in Figma and you see nb/ink, nb/paper, nb/danger. In CSS we do not write #111111. We write var(--nb-ink). That is a design token (you met them in Design systems): the same name in Figma and in code, so that designer and developer speak one language. If your brand colour changes, you open one file.

Storybook: the catalogue¶

Storybook is a workshop for components. It runs as a separate website where you build and look at each component alone, with no page, no data and no login around it.

Why not test the button in your app? Because to see the disabled state you would have to log in, open a note and reach the right screen. To see the danger state, you would have to find a different screen. In a catalogue, every state is one click away.

Install it¶

In your project folder:

npm create storybook@latest

If the installer offers test features, leave them out: you will set up tests by hand in Unit tests. It detects SvelteKit and installs storybook, @storybook/sveltekit, @storybook/addon-svelte-csf and @storybook/addon-docs. It may instead stop with this error:

npm error ERESOLVE unable to resolve dependency tree

npm picked two different Storybook versions. Look up the version of storybook in your package.json, say 10.6.4, and ask for the same one:

npm install -D @storybook/svelte@10.6.4

Then start it:

npm run storybook

It opens http://localhost:6006. Your app still lives at localhost:5173. Those are two different servers, and users only ever see the second one.

If port 6006 is busy, another Storybook is still running in a forgotten terminal. If nothing works at all, check that you are in the right folder: there must be a package.json next to you (ls).

Find your way around¶

A story is one component in one specific state. Button · Primary. Button · Disabled. Think of a catalogue photo: this brick, in red.

Your first brick¶

Tokens first¶

Create the tokens file, using the names from the Figma table:

:root {
    --nb-ink: #111111;
    --nb-paper: #ffffff;
    --nb-muted: #666666;
    --nb-line: #d4d4d4;
    --nb-accent: #2563eb;
    --nb-danger: #dc2626;
    --nb-warning-bg: #fef3c7;
    --nb-warning-ink: #78350f;
    --nb-success-bg: #dcfce7;
    --nb-success-ink: #14532d;
    --nb-radius: 8px;
    --nb-font: Inter, system-ui, sans-serif;
}

Import it in two places, because the app and the catalogue are two different websites. Your app loads it from the layout:

import '#lib/tokens.css';

The catalogue never loads your layout, so it needs its own import, as the first line of the file:

import '../src/lib/tokens.css';

The component¶

<script>
    let { variant = 'primary', children } = $props();
</script>

<button type="button" class="btn {variant}">
    {@render children()}
</button>

<style>
    .btn {
        font: 500 16px/1 var(--nb-font);
        height: 48px;
        padding: 0 20px;
        border: 2px solid var(--nb-ink);
        border-radius: var(--nb-radius);
        cursor: pointer;
    }
    .primary {
        background: var(--nb-ink);
        color: var(--nb-paper);
    }
    .secondary {
        background: var(--nb-paper);
        color: var(--nb-ink);
    }
    .danger {
        background: var(--nb-danger);
        border-color: var(--nb-danger);
        color: var(--nb-paper);
    }
    .btn:focus-visible {
        outline: 2px solid var(--nb-accent);
        outline-offset: 2px;
    }
</style>

Three things to notice:

• variant = 'primary': the default variant in Figma becomes the default value in code. The next page is all about this line.
• children is the label: whatever you write between <Button> and </Button>. You met it in +layout.svelte.
• The class is the variant's name. There is no if: class="btn {variant}" picks the CSS rule.

You will see nothing yet, because nothing uses this component. A brick in a drawer is not a model. That is exactly why we need the catalogue.

The first stories¶

The stories file sits next to the component:

<script module>
    import { defineMeta } from '@storybook/addon-svelte-csf';
    import Button from './Button.svelte';

    const { Story } = defineMeta({
        title: 'NoteBox/Button',
        component: Button
    });
</script>

<Story name="Primary">Save</Story>

<Story name="Secondary" args={{ variant: 'secondary' }}>New note</Story>

<Story name="Danger" args={{ variant: 'danger' }}>Delete</Story>

Read it piece by piece:

Save. Three stories appear in the sidebar, with no restart. Open Controls and type danger in variant. Press Tab: there is the blue focus ring from the spec.

Finally, use the brick for real. Replace one hand-written <button> in one of your pages with <Button>, and check that the page works as before.

Key takeaways¶

• A reusable component knows nothing about the page it lives in. It receives everything through its props.
• One component with a prop beats PrimaryButton and DangerButton: Figma taught you this with variants.
• Design tokens keep the same names in Figma and in code, so a redesign is one file instead of forty.
• Storybook is a separate website on port 6006, for developers. Users never see it.
• A story is one component in one state. args are its props, and the text between the tags is its children.
• The catalogue does not load your layout: import tokens.css in .storybook/preview.js too.

Quick check¶

Your button has one stud so far. In Props and default values you give it the rest, and decide what happens when nobody passes a value.