Welcome to KDS

Welcome to KDS — the Kalvner Design System. This site is the public reference for @kalvner/kds, the design system powering Kontar and Kalvner's personal projects.

What is KDS

KDS is a Tailwind v4 + shadcn-based design system, distributed as a versioned package (@kalvner/kds) via GitHub Packages. It ships multi-theme support, a three-layer token architecture, 49 shadcn primitives em 7 categorias funcionais, e 29 AI Elements (Vercel AI Elements vendorados) em 4 sub-categorias.

It is not a public, generic design system. It exists to keep Kalvner's products visually coherent and to fix the failure modes of past attempts — drift, ad-hoc tokens, missing docs.

How this site is organised

Foundations — design principles, architecture, accessibility, contribution rules
Tokens — the three-layer token system (primitive → semantic → chart) and its theming model
UI — primitivos por categoria (Containers, Forms, Display, Feedback, Overlays, Navigation, Data)
AI — primitivos específicos para IA (mensagens, streaming, assistente)
Blocks — templates de página copyáveis

The internal Storybook (apps/storybook) remains the lab where components are built and tested in isolation. It is not deployed publicly — this site is the canonical reference.

Where to start

If this is your first visit:

Read Foundations / About for the project's scope and rationale.
Skim Foundations / Principles for the non-negotiables.
Move into Tokens to understand the theming model.
Browse UI by category as needed — start with Forms or Display.

Highlights por categoria

Containers — Stack, ScrollArea, AspectRatio, Resizable.
Forms — 15 primitivos (Button, Input, Calendar, DatePicker, InputOTP…); Form com react-hook-form + zod já configurado.
Display — Card, Avatar, Badge, Separator, Accordion, Collapsible, Carousel, Table.
Feedback — Alert, Skeleton, Progress.
Overlays — Dialog (com 3 níveis de stakes documentados), AlertDialog, Sheet, Drawer, Popover, Tooltip, DropdownMenu, ContextMenu, HoverCard, Sonner, Command (paleta ⌘K).
Navigation — Tabs, Breadcrumb, Pagination, NavigationMenu, Menubar, Sidebar.
Data — Chart (6 tipos: Area, Bar, Line, Pie, Radar, Radial) com 5 esquemas canônicos de cor.
AI (29 primitivos vendorados da Vercel AI Elements):
- Chatbot (17): Conversation, Message, PromptInput, Reasoning, Tool, ChainOfThought, Sources, Suggestion, Task, Plan, Queue, Checkpoint, Confirmation, Context, InlineCitation, ModelSelector, Shimmer.
- Code (3): CodeBlock (Shiki highlighting), Artifact, WebPreview.
- Workflow (7): Canvas, Node, Edge, Connection, Panel, Controls, Toolbar (sobre @xyflow/react).
- Utilities (2): Image, OpenInChat (deep-links pra outras IAs).

Status

A primeira fase da KDS está concluída: tokens, primitivos fundamentais, charts, sidebar e overlays já estão documentados e versionados. Patterns compostos (DataTable, EmptyState, Combobox) chegam progressivamente. Para o roadmap completo, veja docs/PRD.md.

Internal — @kalvner/kds is a private package distributed via GitHub Packages.