Getting started

From zero to a running app, with an AI that knows Kvalt.

1. Scaffold the project

npx @kvalt/cli init my-app

You'll be prompted for a registry URL (accept the default — kvalt.dev/r/v1/registry.json), a components directory, tokens directory, and TypeScript yes/no. Defaults are sensible; press Enter through.

What lands in the directory:

• kvalt.json — your project's config (registry URL, paths, TS preference)
• .mcp.json — pre-wired to the live spec server at kvalt.dev/mcp
• docs/ — PRD template, conventions, philosophy, anti-patterns
• .claude/ — planning agents and skills your AI will pick up automatically
• knowledge/ — long-form notes structure (empty templates)

2. Start a session with your AI

Inside my-app/, launch your AI client. Claude Code is the quickest path:

cd my-app
claude

Claude will detect .mcp.json and connect to the Kvalt MCP. You can verify it loaded by asking Claude something like "What components are available from Kvalt?" — under the hood it calls list_components against the live registry.

3. Add your first component

Either ask the AI to add it, or run the CLI yourself:

npx @kvalt/cli add button

Files land in src/components/, src/tokens/, src/hooks/. Transitive dependencies install automatically. Each file is stamped with a version header for future updates.

4. Use it

import { Button } from './components/Button';

export default function App() {
  return <Button onClick={() => alert('hi')}>Tap me</Button>;
}

The component reads tokens from src/tokens/, uses the usePress hook for the press animation, and respects prefers-reduced-motion automatically.

5. Run the project

pnpm install
pnpm dev

Vite spins up at localhost:5173 with hot reload. From here, ask your AI to build features — it has the Kvalt spec at its fingertips through MCP and shouldn't reach for raw hex codes or arbitrary pixel values.

What's next

• Browse Components to see what's installable
• Browse Tokens to see the design language
• Run kvalt outdated to check for component updates
• Run kvalt diff button to see what's changed since you installed

Found a rough edge? hello@kvalt.dev. Stealth beta — feedback is welcome.