Docs

Getting started

The whole path, from an empty directory to a running app. Already have a Svelte 5 project? Skip straight to step 2.

1. Create a project

Any Vite + Svelte 5 setup works. From an empty directory:

npm create vite@latest my-app -- --template svelte-ts
cd my-app
npm install

SvelteKit works the same way — npx sv create my-app — the only difference is that imports below use the $lib alias.

2. Initialize Mittsu

From the project root:

npx @a3tai/mittsu@latest init

This writes components.json, copies tokens.css into src/lib/styles/, and drops the cn utility into your project.

3. Import the tokens once

From your app entry — src/main.ts in a Vite project, or the root +layout.svelte in SvelteKit:

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

4. Add components

Pull components in à-la-carte:

npx @a3tai/mittsu add button badge stat

Sibling dependencies tag along automatically — adding search-input brings input and kbd along.

5. Use them

In src/App.svelte (or any route):

<script lang="ts">
  import Button from './lib/components/ui/button/button.svelte';
  import Badge from './lib/components/ui/badge/badge.svelte';
</script>

<Button>Hello Mittsu</Button>
<Badge>ready</Badge>

In SvelteKit, import from $lib/components/ui/… instead.

6. Run it

npm run dev

The files are yours now — restyle them, fork them, or delete the ones you don't need. There's no runtime package to stay in sync with.

Icons

Mittsu doesn't bundle an icon set, and no component type-checks against one. Anywhere a component takes an icon it renders whatever SVG you hand it, colored by currentColor so it flips with the theme for free.

We recommend and ship our own site with Lucide — stroke-based, tree-shakeable, and Svelte 5-native:

npm install @lucide/svelte

Live @lucide/svelte

Browse all icons

<script lang="ts">
  import Search from '@lucide/svelte/icons/search';
  import Button from '$lib/components/ui/button/button.svelte';
</script>

<Button icon aria-label="Search">
  <Search size={14} strokeWidth={1.75} />
</Button>

Use the deep import path (@lucide/svelte/icons/<name>) rather than named imports from the package root — it keeps the dev server fast and guarantees tree-shaking.

House style

Size 14–16. Sits with 12.5–13px UI text. Drop to 12–13 inside pills and eyebrows.
strokeWidth 1.75. Lucide's default 2 reads heavy against 1px hairlines.
Inherit currentColor. Never hard-code a fill — that breaks theme flipping.
aria-hidden when decorative. Icon-only controls get an aria-label instead.

Directional affordances are icons, not ASCII: ArrowRight for internal navigation, ArrowUpRight for external links, ArrowLeft for back links — never a literal -> in a label.

Using a different set

Nothing in the kit depends on Lucide. Phosphor, Tabler, Heroicons, or your own inline <svg> drop into the same slots — anything that renders at text size and strokes with currentColor fits. If you swap sets, keep the optical weight near a 1.5–1.75 stroke at 16px so mixed surfaces stay coherent.

Keyboard cheat sheet

`⌘` `K`	Focus search input
`Esc`	Clear active search / close dialog
`Tab`	Standard focus traversal — every component is keyboard-friendly by default

For LLMs & agent tooling

Mittsu publishes an /llms.txt index following the llms.txt convention, plus a single-fetch /llms-full.txt bundle that concatenates the README, every doc page, and the full component & chart catalog.

Point your assistant at https://mittsu.dev/llms.txt when generating code against the library — the index links to canonical component URLs and the full bundle fits in one prompt.