Contributing

How to add to KDS. Full operational details live in docs/CONTRIBUTING.md; this page is the orientation.

Where to start

Before any task, read:

1. docs/PRD.md — the authoritative product spec. Identify which Phase the task belongs to.
2. CLAUDE.md — the agent / contributor working rules.
3. The relevant skill in the Kalvner skill library (crew/skills/).

Adding a new component

The full workflow lives in docs/CONTRIBUTING.md and the storybook-component-doc skill. Compressed:

1. Pick the right category (one of the 9). Use the decision matrix in knowledge/ui/design-systems/storybook-structure.md if ambiguous.
2. Add via shadcn CLI when applicable, then move to packages/kds/src/primitives/<categoria>/<Component>/.
3. Replace any raw colour / spacing in the shadcn output with semantic tokens (bg-primary, text-foreground, etc.).
4. Write <Component>.stories.tsx — Default first, individual variants, individual states, plus a composed render story. AI components additionally get Streaming, Loading, Error.
5. Write the docs MDX in apps/docs/content/primitives/<categoria>/<component>.mdx — all 11 sections in order.
6. Add the path-per-component entry to packages/kds/package.json exports.
7. Run the audit checklist (crew/skills/storybook-component-doc/rules/audit-checklist.md).
8. Commit with conventional commits format (feat(kds): add <Component> primitive in <Categoria>).

Mandatory MDX structure

Every component MDX has these 11 sections, in this order:

1. Header
2. Preview hero
3. Installation
4. Anatomy
5. Usage (when to use / not to use)
6. Examples
7. Composition (only if compound component)
8. API Reference
9. Accessibility (keyboard, ARIA, screen reader)
10. Do / Don't
11. Related

The 11-section structure is rigid. PRs that bypass it are blocked in review.

Stories must include

• Default — the smallest meaningful render (always first)
• Individual variants — one story per variant
• Individual states — one story per state
• Composta — one story with render showing realistic composition
• AI extras (AI components only): Streaming, Loading, Error

What NOT to do

• Don't hardcode hex / oklch / rgb in components — always semantic tokens
• Don't generate single-story <Button /> Storybook entries
• Don't render token pages as grids of swatch cards — always tables
• Don't skip the MDX — every component must have one
• Don't bypass the 11-section structure
• Don't add components without a category
• Don't use "Tailwind class" as a column header — always "Class"
• Don't invent theme names — always default, amber-minimal, amethyst-haze, claude

Commits & PRs

• Conventional commits required: feat(kds): add Button primitive, docs(content): add Tokens overview, chore(deps): bump turbo to 2.5.0, etc.
• Scope from docs/CONTRIBUTING.md: kds, docs, storybook, control, tooling, deps.
• PR description must include:
  • What changed
  • Which Phase of the PRD it advances
  • Any ADR if architecture-affecting

Releases

@kalvner/kds follows the schedule in PRD §10.7:

Bumps happen via pnpm changeset from the main branch — see docs/CONTRIBUTING.md for the full release flow.