# Kumiki

> Headless, composable, deeply accessible UI primitives for Svelte 5 — built on framework-agnostic state machines, with surgical bundle sizes.

Kumiki ships as 9 layer-level packages under the `@kumiki/*` scope, with subpaths per component. The 5-layer architecture (described in `docs/design/02-architecture.md`) is preserved at the source level; the packaging is collapsed per [ADR 0012](/docs/design/16-decisions/0012-package-consolidation).

## Layers

- Layer 1 (`@kumiki/primitives`, `@kumiki/locale`): framework-agnostic utilities and locale data, subpath per primitive / per language.
- Layer 2 (`@kumiki/runtime` + `@kumiki/machines`): pure-TS finite state machines. `@kumiki/machines/<name>` for each component (toggle, combobox, dialog, …).
- Layer 3 (`@kumiki/headless`): Svelte 5 attachments (`{@attach}`) wrapping Layer 2. `@kumiki/headless/<name>` per component plus `@kumiki/headless/combobox/with-{validation,async-search,multi-select,virtualization}` composition subpaths.
- Layer 4 (`@kumiki/components`): compound Svelte components (`Combobox.Root`, `Combobox.Item`, …). Subpath per component plus a dot-namespace barrel at the root (`import { Toggle, Dialog } from '@kumiki/components'`).
- Layer 5 (`@kumiki/atelier`, preview): styled, copy-paste component variants (Tailwind v4 + vanilla CSS). Preview during the v1.0 series.

## Core principles

- WCAG 2.2 AA, WAI-ARIA 1.2 (1.3-ready), APG-driven keyboard tests, axe-core in CI, Guidepup for NVDA/VoiceOver.
- RTL-aware, dynamically importable locale data (1 KB per locale target), 13 calendars (Gregorian, Islamic, Buddhist, Japanese, …).
- Standard Schema for validation. Svelte 5 only (runes + attachments).
- `data-state` data attributes on every component for animation hooks. No animation engine bundled.
- `child` snippet pattern for render delegation (replaces `asChild`).

## Documentation

- Design docs: /docs/
- Components reference: /components/
- Roadmap: /docs/roadmap
- llms-full.txt: /llms-full.txt (full type definitions and anti-patterns)