Docs Catalog

Documentation

This overview explains why nake-ui exists, which constraints it keeps non-negotiable, and how to read the rest of the docs without treating the project like a visual component library.

What Problem It Solves

Frontend teams often need accessible interaction behavior without adopting a branded visual system, while code agents need a DOM they can inspect, repair, and generate against.

nake-ui focuses on that middle layer: behavioral primitives with explicit semantics, keyboard rules, ARIA linkage, and DOM-reflected state.

Design Principles

  • Headless by architecture: behavior and appearance stay separate.
  • Native-first: prefer platform elements and standard DOM events before framework-specific abstractions.
  • Framework-agnostic core: core and primitives define behavior; adapters only expose that behavior in framework-friendly surfaces.
  • Accessibility first: keyboard models, focus management, dismiss rules, and ARIA relationships are part of the contract, not optional polish.

If you need branded components, a CSS framework, or design tokens as the main product, that is intentionally outside the scope of this library.

What Makes It Different

  • Public DOM contracts reflect state through ARIA plus stable attributes such as data-ui, data-slot, data-state, and related data-* markers.
  • Schema-backed tooling gives the project a validator, inspector, and repair-oriented surface instead of relying on prose alone.
  • Controlled and uncontrolled usage are expected to behave the same, with hydration-safe IDs and explicit state models.
  • The v1 primitive scope stays intentionally narrow so parity, tests, and docs can remain reliable across adapters.

Basic Capabilities

  • Foundation layers cover controllable state, IDs, focus scope, dismissable layer, roving tabindex, collection, typeahead, selection, portal, and positioning.
  • Canonical primitives center on Disclosure, Tabs, Dialog, Tooltip/Popover, Menu, Listbox, Select, and Combobox.
  • Adapters expose the same behavioral intent across React, vanilla, Solid, Vue, and Svelte without changing the core semantic model.

Usage Notes

  • Do not treat nake-ui as a visual component library or CSS framework.
  • Do not rely on className as semantic truth; public state should remain readable from ARIA and data-*.
  • Keep adapter code thin and avoid hiding critical behavior in private framework state.
  • Use docs, examples, validator rules, and generated artifacts together; the contract is broader than one snippet.