The design system for AI products.

Conversation, voice, motion, and app components for Svelte 5 and Tailwind v4.
Copy the source. Make it yours.

Docs  ·  Components  ·  Blocks  ·  Install  ·  Motion  ·  AI tools

Mizu is a design system for products with intelligence inside. It starts with the conversation (streaming answers, visible reasoning, tool calls, voice) and carries the same language into installable apps and the websites that launch them. Black, white, and neutral grays hold the structure. Color and motion mark the moments when an AI is at work. Every component is plain Svelte source you own, installed with the shadcn-svelte CLI or copied by hand, with a live preview at mizu-ui.com.

Showcase

A few favorites, recorded live from mizu-ui.com. Each one follows your light or dark setting.

Voice Orb Glassy mist that listens, swirls while thinking, and breathes while speaking.	Presence A companion that shows when an assistant is listening, thinking, speaking, or done.
Dynamic Island A pill that morphs between live activities with a springy bounce.	Streaming Text Token-by-token text that types itself in, caret and all.
Code Morph Every surviving token glides to its new spot as the code changes.	Carousel 3D Spin a ring of cards and flick it to land on the one you want.
Number Ticker Digits roll into place when the value changes.	Bar Chart Bars grow from the baseline and spring between series.

Contents

• Showcase
• Highlights
• Install
  • Requirements
  • With the shadcn-svelte CLI
  • Copy and paste
• Usage
• Motion tokens
• Theming
• Components
• Blocks
• AI tools
• How releases work
• Repository layout
• Develop
• Built with
• Community
• License

Highlights

• 169 components for AI, motion, apps, forms, overlays, navigation, and data, from a chat composer and a voice orb to a kanban board, a color picker, and a dynamic island.
• Presence. A companion that shows whether the assistant is listening, thinking, speaking, or done, in five tones.
• A motion system. Duration, easing, and spring tokens in the theme. Springs are sampled from real physics into CSS linear() curves, so they cost nothing at runtime.
• Apps and PWAs. Tab bars, install prompts, offline status, and safe-area utilities for web apps people install.
• Complete screens. Assistant chat, voice mode, agent workflows, a mobile assistant, a product landing page, and more, each one file you own.
• Accessible by default. bits-ui behavior underneath, axe checks on every component in both themes, and reduced motion respected everywhere.
• Recolor from one token. Accent states, selection fills, and the focus ring follow --primary.
• Copy in, own it. A shadcn-svelte-compatible registry with immutable versioned releases.

The current stable release is 0.6.0. Pin it for reproducible installs:

npx shadcn-svelte@latest add https://mizu-ui.com/r/v0.6.0/button.json

Upgrading copied components from 0.4.x means reinstalling them with the 0.5 Motion item. See the 0.5.0 migration notes. From 0.3.x, reinstall the theme first, as described in the 0.4.0 notes.

Install

Requirements

• SvelteKit with Svelte 5 and TypeScript
• Tailwind CSS v4
• The $lib alias (SvelteKit's default). Some items also use bits-ui or Lucide icons; the CLI installs whatever an item needs.

With the shadcn-svelte CLI

1. Create the app:

npx sv create my-app
cd my-app
npx sv add tailwindcss

2. Add a components.json so the CLI knows where to place files (or run npx shadcn-svelte@latest init to generate it). Point tailwind.css at your Tailwind entry, the file that holds @import 'tailwindcss';. Recent sv add tailwindcss creates src/routes/layout.css; older setups use src/app.css. Use whichever you have:

{
	"$schema": "https://shadcn-svelte.com/schema.json",
	"tailwind": { "css": "src/routes/layout.css", "baseColor": "neutral" },
	"aliases": {
		"lib": "$lib",
		"utils": "$lib/utils",
		"components": "$lib/components",
		"ui": "$lib/components/ui",
		"hooks": "$lib/hooks"
	},
	"typescript": true,
	"registry": "https://shadcn-svelte.com/registry"
}

3. Add the theme: paste Mizu's src/app.css (this repo's) into that same Tailwind entry file, right after @import 'tailwindcss';. It holds the color, elevation, and motion tokens every component reads.

4. Add components with the one-liner. It pulls the component, installs its npm dependencies, and adds the shared cn helper automatically:

npx shadcn-svelte@latest add https://mizu-ui.com/r/v0.6.0/button.json

Versioned registry URLs are immutable. Use /r/latest/<item>.json only when you intentionally want the newest release. See the compatibility policy. If you fork Mizu, point repo and registryBase in src/lib/site/config.ts at your own deployment and re-run pnpm registry:build.

Copy and paste

Every component page on mizu-ui.com has a Code tab and the full source of each file. Copy them into src/lib/components/ui/<name>/, keep the theme from step 3, and install any packages the file imports.

Usage

<script lang="ts">
	import { ChatInput } from '$lib/components/ui/chat-input';
	import { Presence } from '$lib/components/ui/presence';
	import { TextReveal } from '$lib/components/ui/text-reveal';

	let answer = $state('');
	let thinking = $state(false);

	async function ask(message: string) {
		thinking = true;
		answer = await yourModel(message);
		thinking = false;
	}
</script>

<div class="flex items-start gap-3">
	<Presence state={thinking ? 'thinking' : answer ? 'speaking' : 'idle'} size={36} />
	{#if answer}<TextReveal text={answer} />{/if}
</div>
<ChatInput onSubmit={ask} placeholder="Ask anything" />

Motion tokens

Motion is quick to respond and soft to settle. Use the tokens instead of literal values:

<div class="transition-[scale] duration-(--duration-spring) ease-spring hover:scale-[1.02]">
<li class="animate-rise-in stagger" style="--index: {index}">...</li>
<span class="text-shimmer animate-shimmer">Searching the web</span>

The Motion registry item adds rise, blurIn, and pop transitions, reveal and magnetic attachments, and SpringValue, a velocity-preserving spring that is safe in SSR and tests. Read the motion guide.

Theming

The default primary is black in light mode and white in dark mode. Custom themes set the primary color and its foreground together:

:root {
	--primary: #171717;
	--primary-foreground: #ffffff;
}

.dark {
	--primary: #f5f5f5;
	--primary-foreground: #171717;
}

CSS variables also define card, popover, and control fills, elevation, and motion. See the theming guide.

Components

Mizu currently includes 169 components across AI, motion, app, actions, forms, surfaces, data, overlays, menus, navigation, and feedback. Click a name for the live preview, code, and API reference. Install any of them by slug:

npx shadcn-svelte@latest add https://mizu-ui.com/r/v0.6.0/<slug>.json

AI (21) · Motion (21) · App (6) · Actions (18) · Forms (32) · Surfaces (23) · Data (8) · Overlays (11) · Menus (5) · Navigation (14) · Feedback (10)

AI

Component	Description
Aurora	A slow, drifting pastel-aura backdrop.
Chat Input	A message composer with optional attachment and voice actions.
Chat Bubble	User and assistant message bubbles, flat and quiet.
Streaming Text	Token-by-token text that types itself in, caret and all.
Reasoning	A collapsible chain of thought: shimmers while thinking, folds away when done.
Tool Call	Live status for a tool the assistant is using, with an expandable result.
Sources	Numbered citation chips that ground an answer.
Message Actions	Copy, regenerate, and feedback beneath a reply.
Plan	The agent's step list: shimmer while working, checks as it lands.
Nudge	A proactive suggestion from the assistant, easy to act on or dismiss.
Aura Tile	Seeded pastel cover art for anything the AI generates.
Voice Orb	A voice orb in two styles: a folded cloud, or glassy mist that listens to a live mic, swirls while thinking, and breathes while speaking.
Waveform	Animated voice bars for listening and speaking states.
Prompt Suggestions	Starter prompt chips that invite the first message.
Thinking	Shimmer and typing-dot indicators for a working assistant.
Presence	An expressive companion that shows when an assistant is listening, thinking, speaking, or done.
Conversation	A message thread that follows new replies only while you are at the bottom.
Feedback Prompt	Asks whether a response helped, and opens into a field right where the question was.
Call Controls	Accept turns into hang up as the call controls unfold out of it.
Audio Player	Inks in a voice note waveform with chapter markers and a ghost playhead.
Greeting	Greets by time of day as a sun or moon rises into place along an arc.

Motion

Component	Description
Motion	Easing, springs, transitions, and scroll reveals that share the theme's motion tokens.
Text Reveal	Reveals a line or an answer word by word or character by character, on mount or on scroll.
Text Rotate	Cycles a word in place while the line around it eases to fit.
Number Ticker	A formatted number whose digits roll into place when the value changes.
Marquee	An endless, pausable scroller for logos, testimonials, and prompt chips.
Text Scramble	A block cursor reads a word in, one letter at a time.
Typewriter	Types, pauses, and rewrites the last word with a human rhythm.
Wave Text	Letters rise in a wave that follows your cursor.
Spoiler	Hides text under shimmering grain that blows away from your click.
Highlight	Swipes a highlighter across a line when it comes into view.
Code Morph	Glides every surviving token to its new spot as code changes.
Icon Morph	Icons reshape between states instead of swapping.
Confetti	A burst of confetti for moments worth celebrating, as a button or a confetti() call.
Tilt Card	Leans toward your cursor with a glare that follows the light.
Spotlight Card	Cards catch the glow of a cursor lamp.
Flip Card	Turns over in 3D to show what is on the back.
Lens	A lens follows your cursor and reveals what is hidden underneath.
Sticky Stack	Cards pile up and sink back as you scroll.
Carousel 3D	Spin a ring of cards and flick it to land on the one you want.
Logo Orbit	Logos orbit a heading on tilted rings and brake when you point.
Dot Grid	Dots swell and part around your cursor, and a click sends a shockwave.

App

Component	Description
Tab Bar	Bottom navigation for mobile apps and PWAs, with a sliding indicator and unread badges.
Install Prompt	A card that offers to install your PWA, with Add to Home Screen steps on iOS.
Network Status	An online and offline indicator that reassures people their changes will sync.
Dynamic Island	A pill that morphs between live activities with a springy bounce.
Pull to Refresh	Pull a feed down and new items slide in at the top.
Story Progress	Tap through stories, and hold to pause.

Actions

Component	Description
Button	Pill actions with neutral, semantic, and AI variants.
Badge	Compact status pills in soft intent colors.
Button Group	Buttons joined into one segmented control.
Hold Button	A pill you press and hold to confirm, with a fill that sweeps across and an optional bin lid that slams shut.
Copy Button	Copies a value as its two pages merge and a check draws in, or flips its letters into a confirmation.
Upload Button	Shrinks into a progress ring while a file uploads, then checks off.
Download Button	The arrow drops into the tray while the pill fills with progress.
Async Button	Shrinks into a spinner while it works, then answers with a check or a shake.
Send Button	The plane lifts off along a curve and a check lands in its place. Pairs with chat composers.
Slide to Confirm	Drag the knob across to confirm a consequential action.
Share Button	Opens in place into share targets, and the link turns into a check once copied.
Like Button	Pops, bursts, and rolls its count when liked.
Star Button	Spins once, throws off sparks, and rolls the count.
Bookmark Button	Fills from the bottom up and lands with a small squash.
Follow Button	Turns its plus into a check, and asks before unfollowing.
Reactions	Add a reaction and watch it fly into its pill as the count rolls.
Notification Bell	Rings when something arrives while its badge rolls up.
Theme Toggle	A sun that folds its rays away into a crescent moon.

Forms

Component	Description
Input	A pill text field with a quiet fill and a primary focus ring.
Textarea	Multi-line input matching the field style.
Label	An accessible, selectable form label.
Checkbox	A compact checkbox whose check draws itself in, with Shift-click range selection in a group.
Radio Group	A single choice with keyboard navigation, as rows or cards with a gliding selection ring.
Switch	A pill switch for an immediate on or off choice.
Slider	A track with a contrasting range, springy thumbs, value bubbles, and an optional elastic pull past the ends.
Select	A clean dropdown with highlighted items.
Combobox	A searchable select in a clean popover.
Toggle	A two-state button with a soft pressed look.
Toggle Group	A segmented set of toggles in a pill rail.
Input OTP	One-time-code slots with a gliding focus ring, a blinking caret, and a shake on a wrong code.
Input Group	An input fused with leading or trailing add-ons.
Field	Label, control, hint, and error, grouped.
Native Select	A styled native select, no JS required.
Calendar	A month grid with a contrasting selected day.
Range Calendar	Pick a span of dates with a clean month grid.
Date Picker	A pill date field with a popover calendar.
Rating	Fillable symbols that preview on hover and pop when chosen.
Tags Input	A field whose typed words become chips right where they are.
Segmented Control	A pill track of mutually exclusive options with a thumb that springs to the selection.
Number Input	Rolls each digit the way the count moves, and speeds up the longer you hold.
Password Input	Reveals with a wave of dots turning into letters, warns about caps lock, and meters strength.
Floating Label	A field whose label lifts out of the way letter by letter and never covers your text.
Email Input	Catches a mistyped domain and fixes it by moving only the letters that were wrong.
Expanding Search	Opens from a circle into a search field, and closes faster than it opens.
Inline Edit	Edits text in place without moving a pixel.
File Dropzone	Its dashed edge marches when a file enters the window and seals solid when it is overhead.
Color Swatches	A ring glides to the color you pick while the choice floods the preview.
Color Picker	Drag a color out of the square, then fine-tune hue and opacity.
Wheel Picker	Spins through values on a curved drum, like the iOS time picker.
Shortcut Recorder	Press keys to set a shortcut; keycaps appear as you hold them and conflicts are flagged.

Surfaces

Component	Description
Card	A flexible content surface with soft elevation.
Alert	Quiet callouts in four intents.
Separator	A subtle semantic divider for sections.
Avatar	A rounded image with a graceful fallback and a status badge that morphs between presences.
Scroll Area	A scroll container with a slim, quiet bar.
Aspect Ratio	Hold content to a fixed ratio.
Table	A clean, rounded data table.
Empty	A friendly empty state.
Item	A composable list row.
Kbd	A keyboard-key badge.
Carousel	A swipeable slider with pill controls, and a focus mode where neighbors shrink and fade.
Resizable	Draggable panes split by a quiet handle.
Data Table	TanStack-powered tables whose rows glide when sorted, with a bulk action bar that rises for selections.
Timeline	A vertical history whose line grows down to meet each new event.
Swipe Deck	Fling a card away and the rest of the deck steps forward.
Expanding Card	Grows from its slot into a detail view and folds back when you are done.
Sortable	Pick up a row or tile and the rest slide out of its way.
Kanban	Lift a card between columns and the others make room for it.
Drag Select	Draw a box across items to select them, like a desktop.
Compare Slider	Drag the divider to compare a before and after.
Code Block	Switch files with a sliding underline and copy with one click.
Image Hotspots	A leader line travels between labeled points on an image without covering it.
Avatar Stack	A row of faces that fans open when you reach for it, with a name above each.

Data

Component	Description
Sparkline	Draws itself in, then scrubs to the nearest point under your cursor.
Bar Chart	Grows its bars from the baseline and springs between series.
Donut Chart	Draws itself in, then lifts whichever slice you point at.
Heatmap	A year of activity at a glance, sweeping in week by week.
Stat	A figure that counts up, and rolls back through its history as you scrub the trend.
Leaderboard	Rows glide past each other to their new ranks.
Uptime Bar	Point at any day and the caption tells you what happened.
Relative Time	A timestamp that says how long ago in words and keeps itself current.

Overlays

Component	Description
Dialog	A clean modal over a blurred scrim that steps back when a confirmation opens on top.
Popover	A floating panel anchored to a trigger.
Tooltip	A small hint on hover or focus. In a group, one bubble slides between triggers.
Alert Dialog	A clean modal that interrupts for a confirmation.
Sheet	A panel that slides in from any edge.
Drawer	A bottom sheet you drag or flick away, with nested drawers that push the one behind back.
Hover Card	A card revealed on hover or focus. In a group, one card travels between names.
Confirm Popover	Asks before a destructive action, from a popover that grows out of its button.
Selection Toolbar	A toolbar that grows out of whatever text you select.
Link Preview	A preview card that trails your cursor over a link and leans as it moves. Keyboard focus shows it too, so it suits citations.
Shortcut Sheet	Press ? to see every shortcut, then press one to watch it light up.

Menus

Component	Description
Dropdown Menu	A crisp menu of actions, with submenus and checks.
Context Menu	A right-click menu, clean and quiet.
Menubar	A desktop-style bar of dropdown menus.
Navigation Menu	Site navigation with floating dropdown panels.
Command	A searchable command palette.

Navigation

Component	Description
Tabs	A segmented pill switcher whose raised active tab slides between triggers.
Accordion	Collapsible sections with a smooth height transition.
Collapsible	A single open-and-close disclosure.
Breadcrumb	A path trail back to the top.
Pagination	Page-by-page navigation controls.
Sidebar	A collapsible app sidebar that folds to a slim rail.
Stepper	A multi-step progress trail with quiet nodes.
Tree	A nested, keyboard-navigable file-style tree.
Dock	A dock that magnifies icons under the cursor.
Link	An underline that enters from the side your cursor came in and leaves the way it left.
Page Dots	A pill that inches between pages like a worm and counts down to the next.
Back to Top	Fills its ring as you read, then lifts the page back up.
Reading Progress	A bar that fills as you read while the time left counts down.
Scroll Spine	Maps a document as a spine of bands sized to each section, filling as you read.

Feedback

Component	Description
Progress	A neutral track with a contrasting progress indicator.
Skeleton	A shimmering placeholder that swaps into content top to bottom.
Spinner	A loading indicator in four styles that finishes with a check.
Circular Gauge	A ring or tick dial that sweeps to its value and holds a peak.
Toast	Notifications that stack, fan out on hover, and drain their edge as a timer, with undo and promise toasts.
Meter	A semantic gauge whose fill shifts across thresholds, or a segmented breakdown you can point at.
Banner	An announcement bar that folds away on dismiss while the page slides up to fill the gap.
Checklist	A setup checklist that counts up as you go and celebrates the finish.
Save Status	A dot for unsaved changes splits into three while saving, then gathers into a check.
Live Indicator	Breathes while live and blinks hollow while reconnecting.

Blocks

11 blocks: complete screens and flows built from Mizu components, each one file you own. They install from the same registry, for example npx shadcn-svelte@latest add https://mizu-ui.com/r/v0.6.0/assistant-chat.json.

Featured

Block	Description
Assistant chat	The full conversation screen: reasoning, a tool call, a streaming reply with sources and actions, starter prompts, and the composer.
Voice mode	A voice session with a cloud orb, waveform, mute, and end-session controls.
Personalize	Onboarding for a companion: pick a style from aura tiles, set the conversation tone, grant permissions, and create.

Agents

Block	Description
Agent dashboard	A working session at a glance: your agents, a live plan with a running tool, focus for the day, and a proactive nudge.
Agent run	A single run up close: the plan advancing, a live tool call, streaming findings, and pause and stop controls.

App shell

Block	Description
Sidebar layout	The full app shell: an icon-collapsible sidebar with chats and a group action, and a conversation in the inset.

Auth

Block	Description
Login	A sign-in form with email and password, autofill, and local preview feedback.
Sign up	An account form with validation, password autofill, and a required terms agreement.
Verify code	Six-digit email verification with resend.

Mobile

Block	Description
Mobile assistant	An installable assistant app: a companion greeting, starters, recent chats, a composer, offline status, and bottom navigation.

Websites

Block	Description
Product landing	A launch page for an AI product: a rotating headline, questions in motion, live numbers, and features.

AI tools

Mizu is built to be used by coding agents.

• AGENTS.md: the design rules and install commands. Drop it into your project with curl -fsSL https://mizu-ui.com/AGENTS.md -o AGENTS.md.
• llms.txt: a machine-readable index of every component, block, and guide.
• The registry: every item is a versioned JSON file an agent can install with one command.

Setup for Claude Code, Cursor, and other agents is in the agents guide.

How releases work

Each release publishes an immutable, versioned registry under /r/v<version>/, plus /r/latest/ for the newest one. Pin a version for reproducible installs and upgrade on purpose. Migration notes for every markup or default change are in the changelog, and the versioning and deprecation policy is in docs/compatibility.md.

Repository layout

src/lib/components/ui   components, one folder per item
src/lib/site            the docs site: shell, demos, blocks, catalog
src/routes              docs, blocks, and brand pages, llms.txt, AGENTS.md
src/app.css             the theme: color, elevation, and motion tokens
static/r                the built registry (compatibility, latest, versioned)
scripts                 registry build, validation, release, and asset tooling
tests/e2e               Playwright and axe across every page
docs                    compatibility policy, releases, and decision records

Develop

pnpm install
pnpm dev               # docs site and live previews
pnpm check             # type-check
pnpm test              # contract and unit tests
pnpm test:browser      # Playwright and axe across every page
pnpm registry:build    # regenerate compatibility, latest, and versioned registry output
pnpm registry:validate # verify schemas, dependency parity, inventory, and integrity

Components live in src/lib/components/ui, the design tokens in src/app.css, and the site in src/routes and src/lib/site. pnpm new:component scaffolds a component, demo, and catalog entry. node scripts/record-showcase.mjs re-records the showcase clips above from a running dev server. The design rules are in AGENTS.md and CONTRIBUTING.md, and the decisions behind them in docs/decisions.

Built with

Svelte 5, SvelteKit, Tailwind CSS v4, bits-ui, tailwind-variants, and Lucide icons. The voice orb's cloud renderer is adapted from Orb UI under the MIT license.

Community

• Contributing
• Security policy
• Support
• Code of conduct
• Roadmap
• Maintainers

License

MIT. Designed and built by CJ Dyas.