Design principles
The non-negotiable decisions every component, pattern, and page in KDS is held against.
The decisions below are non-negotiable. Every component, pattern, and page in KDS is held against these principles.
Tokens over values
If you find yourself typing a hex code or an oklch literal in a
component file, stop. Use a semantic token (--primary,
--foreground, etc.) — those resolve to the active theme, in light
or dark, automatically. Components that hardcode values look fine
in one theme and broken in three.
Composition over configuration
A <Button variant="primary" size="lg" leftIcon={...} loading> API
gets bloated fast. Prefer compound components and slotted children
where they're a natural fit:
<Button>
<Button.Icon><Spinner /></Button.Icon>
<Button.Label>Saving</Button.Label>
</Button>The composition pattern keeps the API small and lets consumers
break out of the prescribed shape when they need to. See the
composition-patterns skill for the full toolkit.
Accessibility is mandatory, not optional
Every component ships with documented keyboard navigation, ARIA attributes, and screen-reader behaviour — see each MDX page's "Accessibility" section. Target is WCAG 2.2 AA minimum. AI components additionally require live regions and explicit focus management.
Server-friendly by default
Components default to working in React Server Components. Anything
that needs "use client" is documented as such. State, refs, and
effects are opt-in via subcomponents, not the default.
Tree-shakeable distribution
@kalvner/kds uses path-per-component subpath exports
(ADR-012). Importing one component pulls in exactly that component
plus its required tokens — never the entire library. Bundle size
in Kontar is the proof point.
The reference site is the spec
If a behaviour isn't documented in the component's MDX or shown in its stories, it doesn't exist. PRs that add behaviour without updating docs are rejected.
Accept boring choices
Where shadcn / Radix / Tailwind has a sensible default, take it. Custom-built primitives are reserved for genuine product needs. Inventing the wheel is a tax on every future contributor.