Why svelte-zukan
svelte-zukan is a component catalog and nothing else. If a catalog is what you use Storybook for, svelte-zukan gives you one with far less to install, configure and keep up to date.
What it focuses on
- The catalog itself. A list of your components, live previews at phone to desktop widths, the code of each example, a props table, light and dark themes, and accessibility checks. There is no addon system, test runner or story format to learn
- Little to maintain. One package in
devDependencies: about 4 MB with its two runtime dependencies (markedfor the Markdown,axe-corefor the accessibility checks, loaded in the browser only when you run a check). There are no addons to keep on matching versions and no config directory to migrate. Upgrading means bumping svelte-zukan - Your app’s own Vite. One line in
vite.config.ts. Your aliases, plugins and CSS pipeline apply as they are, because the catalog runs on your app’s dev server. There is no second dev server and no second build config to keep in step with the app - Plain Svelte. A catalog file is an ordinary Svelte 5 component. You import your component and write examples in the same code you use everywhere else, so a catalog file changes when Svelte changes, the way your components do
- Next to your code.
Button.zukan.svelteandButton.zukan.mdsit next toButton.svelte, so moving or deleting a component takes its catalog with it - Easy to publish. With
build: true, the samevite buildwrites a static catalog that works under any path, such as GitHub Pages
Compared with Storybook
| svelte-zukan | Storybook | |
|---|---|---|
| Install size1 | 4.2 MB, 3 packages | 78 MB, 82 packages |
| Setup | Add zukan() to vite.config.ts |
A .storybook/ directory with its own config files |
| Upgrading | Bump svelte-zukan |
The core, framework and addon packages together, with storybook upgrade and its automigrations |
| Where it runs | Inside your app’s dev server, at /__zukan/ |
Its own dev server |
| What you write | A plain Svelte component with <Section> blocks |
Stories in Svelte CSF (defineMeta, <Story>) or CSF |
| Docs per component | A Markdown file next to the component, and a props table read from the component | MDX and autodocs |
| Code view | Each section, with the <script> definitions it uses |
Yes |
| Preview width | Presets, dragging and a typed width; wider ones scaled to fit | Viewport toolbar |
| Backgrounds | Light and dark, plus a checkerboard and a grid | Yes |
| Search | Yes | Yes |
| Accessibility checks | Yes (axe-core, with outlined issues and vision simulation) | Yes (a11y addon) |
| Measuring elements | Yes (box model on hover) | Yes (measure addon) |
| Props controls | No, by design (see below) | Yes |
| Event log | No | Yes (actions) |
| Interaction and visual tests | No | Yes |
SvelteKit $app/* |
The real modules, in their default state | Mocked, including $app/state |
| Static export | build: true in your own vite build; works under any path |
storybook build |
| Requirements | Vite 8+, Svelte 5.57.1+, SvelteKit 3+ (or plain Vite + Svelte) | Several bundlers and frameworks |
1 Measured with npm install in an empty directory, leaving out the peer dependencies both share (svelte, vite, @sveltejs/kit): svelte-zukan 0.7.0 on 2026-10-21, Storybook on 2026-10-19 (storybook and @storybook/sveltekit, without any addon).
Why there are no props controls
In Storybook, you can change a component’s props from a panel. svelte-zukan leaves this out on purpose. Each <Section> is a fixed example that you write as code, and the dev server reloads it as you edit. That keeps the examples reviewable in pull requests, and it keeps the catalog free of a second way to describe props.
When to choose Storybook
Storybook does much more than a catalog. Pick it if you need any of these:
- Props controls, an event log, interaction tests, or visual regression tests
- Components from several frameworks in one catalog
- SvelteKit 2, Vite 7 or earlier, or a bundler other than Vite
- Per-story values for SvelteKit’s
pageand other$app/*modules
Moving from Storybook
The migrate-svelte-zukan skill lets an AI agent do the move. Each story becomes a <Section>, argTypes descriptions become JSDoc on the props, and the MDX prose becomes a .zukan.md file. Storybook stays in place until you ask the agent to remove it, and a story with a play function is kept until you decide what to do with that interaction test.