About KDS

The Kalvner Design System (@kalvner/kds) is the design system that powers Kontar and Kalvner's personal projects. It's not for sale, not on npm, and not for client work — clients have their own systems. This is the studio's own toolkit.

What's in scope

A versioned package distributed via GitHub Packages: @kalvner/kds
Tailwind v4 + shadcn/ui primitives, customised for Kalvner's visual taste and engineering preferences
Multi-theme support (Default + 3 tweakcn imports), with light/dark for each
Five canonical chart colour schemes for data viz
80+ components across 9 categories (Containers, Typography, Forms, Display, Data, Feedback, Navigation, Overlays, AI)
Patterns, Layouts, and Blocks built on top of those primitives
This site as the public reference, deployed at ds.kalvner.com

What's explicitly out of scope

Mobile / React Native
Vue, Svelte, or other framework adapters
Marketing site or public component playground
A theme builder UI
Components beyond what Kontar and personal projects need

Origin story

Previous attempts at building a Kalvner design system failed at predictable points: incomplete docs, drift between shadcn imports and the apps consuming them, ad-hoc tokens that never coalesced into a system, and apps depending on shadcn directly instead of going through a versioned package.

KDS is the third try. It's mandated by docs/PRD.md to fix those exact failure modes — strict structure, explicit tokens, full documentation per component, and a clean distribution channel.

How to consume it

See docs/CONSUMING.md for installation and integration steps. You need a GitHub PAT with read:packages scope and Tailwind v4 in your project.

Reading order

If this is your first visit:

Foundations — start here for design principles and architecture
Tokens — the three-layer token system (primitive → semantic → chart)
Primitives — components organised in 9 categories
Patterns / Layouts / Blocks — composed building blocks for full pages