# Mizu

Guidance for AI coding agents working in a project that uses Mizu, the design system for AI products (https://mizu-ui.com). Mizu targets SvelteKit, Svelte 5 (runes), Tailwind v4, and bits-ui. Components are copied into the project as source; there is no runtime dependency on Mizu.

## Installing components

- Install any of the 79 components by slug, dependencies included:
  `npx shadcn-svelte@latest add https://mizu-ui.com/r/v0.1.4/<slug>.json`
- The full catalog with descriptions and registry URLs: https://mizu-ui.com/llms.txt
- Whole screens (blocks) install the same way: assistant-chat, voice-mode, personalize, agent-dashboard, agent-run, sidebar-layout, login, signup, otp
- Component sources live in `src/lib/components/ui/<slug>/` once installed. Edit them freely; they belong to the project.

## Composing AI interfaces

- The AI set: Aurora, Chat Input, Chat Bubble, Streaming Text, Reasoning, Tool Call, Sources, Message Actions, Plan, Nudge, Aura Tile, Voice Orb, Waveform, Prompt Suggestions, Thinking.
- A complete assistant screen stacks in this order: ChatBubble (user) -> Reasoning -> ToolCall -> ChatBubble (assistant) wrapping StreamingText -> Sources -> MessageActions -> PromptSuggestions -> ChatInput. Follow https://mizu-ui.com/docs/build-a-chat.
- Prefer installing the assistant-chat block over rebuilding that anatomy by hand.

## Design rules (do not violate)

- Depth does not come from decorative strokes. Light mode uses soft shadows and gray fills; dark mode uses tonal surface rungs. Semantic strokes are reserved for control outlines, focus and invalid states, dashed empty states, dense-content dividers, and panel edges over arbitrary content.
- One accent: `--primary`. Active states are `bg-primary-muted text-primary`. Everything else stays quiet gray.
- The `orb-*` and `aurora-*` pastel washes mark AI moments (voice, generation, presence), never chrome.
- No font weight heavier than semibold. Single-line controls are pills; multi-line fields use `rounded-2xl`.
- Motion is 200-320ms ease-out, shimmer sweeps are 2s, and everything must respect `prefers-reduced-motion`.
- Theme through the tokens in `src/app.css`, never hex values in markup. The whole system recolors from `--primary`.

## Conventions

- Svelte 5 runes only: `$props()`, `$state`, `$derived`, snippets. No `export let`, no `on:` directives.
- Compound components use namespace imports: `import * as Dialog from '$lib/components/ui/dialog'`.
- Merge classes through each component's `class` prop (tailwind-merge resolves conflicts); do not fork a component to restyle it.
- Icons are lucide, imported per icon: `import Check from '@lucide/svelte/icons/check'`.

## More

- Docs and live demos: https://mizu-ui.com/docs
- Blocks with full source: https://mizu-ui.com/blocks
- Machine-readable index: https://mizu-ui.com/llms.txt