Browsing the catalog
The catalog opens at /__zukan/ on your dev server (<base>__zukan/ when you set a base). This page covers the top page, finding a component, the theme and the keyboard shortcuts. Each preview has its own toolbar, with the accessibility panel among its tools.
Top page
Each component is a card with a small preview of its first section, its name and directory, and the first paragraph of its .md file. A component without sections shows its initial instead of a preview. Click a card to open its detail page.
When the project uses Tailwind CSS, a card for each Tailwind CSS entry comes first, with a strip of the theme’s colors, and links to its page.
Below the cards, a folded list shows the .svelte files in the scanned directories that have no catalog file next to them yet, so you can see what is left to catalog. SvelteKit’s route files (+page.svelte), test components, Storybook and Histoire stories (*.stories.svelte, *.story.svelte) and src/routes/ are left out.
Finding a component
- The sidebar lists the components by group and by directory. Folders open and close, and the arrow keys move through the list
- Type in the search box to filter by ID and by section title. Matching section titles are listed under each component and link straight to that section
- Press ⌘ K (Ctrl K on Windows and Linux), or click the magnifier at the top of the sidebar, to search more widely: component names and IDs, section titles, the text of each
.mdfile, and prop names and descriptions. With Tailwind CSS, the tokens are searched too: category names, classes and theme variables, and a class or variable result opens its category filtered to that token. Results are grouped by what matched, with a snippet of the description where the match is; the buttons above them limit the search to one group. ↑ ↓ pick a result, Enter opens it, and Esc closes the search - On a detail page with several sections, a table of contents sits beside the content when the window is wide enough. When the component has props, the table of contents starts with a link to the props table, which comes right under the description. Links to the previous and next components are at the bottom
- On the dev server, the detail page has buttons under its title that open the catalog file and the component in your editor. They use Vite’s own open-in-editor endpoint, so the
LAUNCH_EDITORenvironment variable picks the editor. A static build has no such buttons - On a narrow screen, the component list folds under the menu button
Theme
The theme button at the top of the sidebar switches the catalog and every preview between light and dark. It starts from your system’s setting, and your choice is remembered in this browser. Each preview gets the theme as its color-scheme, so light-dark() and prefers-color-scheme in your components follow it. A section opened alone is not in a frame: light-dark() still follows the theme, but prefers-color-scheme follows the browser, so a stylesheet that uses it (such as Tailwind’s default dark: variant) can show light there.
To show one theme only, set the theme option to 'light' or 'dark'. The catalog and every preview then always use it, and the theme button and the T shortcut go away.
Keyboard shortcuts
| Key | Action |
|---|---|
| / | Jump to the search box |
| ⌘ K | Search names, sections, props and descriptions (Ctrl K on Windows and Linux) |
| J / K | Next / previous component |
| T | Switch between light and dark, unless the theme option is set |
| F | Expand the preview in view, or leave it |
| Esc | Leave the expanded preview |
| ↑ ↓ | Move through the component list |
| ← → | Close and open a folder in the component list |
| ? | Show the shortcuts |
The shortcuts work while the focus is in a preview too, but do nothing while you type in the search box or another field, except ⌘ K.
The first Tab on the page reaches a “Skip to content” link, which moves the focus past the sidebar to the page.