Introduction

nake-ui is a behavioral UI standard library. It defines interaction semantics, state contracts, DOM structure, ARIA relationships, keyboard behavior, and schema-backed validation for UI primitives. It does not define the final visual design of your product.

The core idea is simple: a primitive should be usable by humans, frameworks, tests, and agents because the same behavioral truth is visible in the DOM. State is reflected through ARIA and public data-* attributes, not inferred from private component internals or styling class names.

The current public docs catalog covers five adapter routes:

• Headless by architecture: behavior and visuals are separate layers.
• Native-first: prefer button, input, form, focus, keydown, input, change, submit, click, and pointerdown before inventing framework-only semantics.
• Agent-friendly: public DOM contracts are stable, enumerable, and inspectable.
• Accessible by default: keyboard models, focus rules, labels, roles, and ARIA linkage are part of the contract.
• Adapter parity: framework syntax can differ, but observable behavior should not drift.

This makes the library closer to a contract layer than a visual component kit. It is useful when you want accessible interaction behavior without adopting a branded design system.

• It is not a Button/Card visual component library.
• It is not a CSS framework, token system, or Tailwind preset.
• It does not make className the source of semantic truth.
• It does not make React runtime state the core truth.
• It does not require Shadow DOM for ordinary primitives.

Visual styles, animations, layout density, and product branding belong to your application. nake-ui provides the behavior and DOM contract your styling layer can safely target.

Read the docs in this order when integrating a primitive:

1. Start with this introduction and the current adapter quick start.
2. Read Primitive Concepts to understand anatomy, state, events, keyboard, ARIA, and validator language.
3. Open Components Overview to choose a primitive and inspect its slot/state matrix.
4. Read Adapter Integration for your framework surface.
5. Copy from the matching adapter examples, then run the validator and contract tests.

The docs intentionally repeat a few constraints. That repetition is useful: the same contract should be visible in specs, generated catalogs, examples, tests, and runtime DOM.

Public data-* attributes are part of the API:

<button
  data-ui="select"
  data-slot="trigger"
  data-state="open"
  aria-haspopup="listbox"
  aria-expanded="true"
  aria-controls="select-content"
>
  Choose fruit
</button>

Use these attributes as stable selectors and inspection points:

• data-ui
• data-slot
• data-state
• data-disabled
• data-selected
• data-highlighted
• data-orientation
• data-expanded
• data-invalid

Classes can style the primitive, but classes should not be the only place where state exists.

The canonical v1 primitives visible in the site are:

• Disclosure
• Tabs
• Dialog
• Popover
• Menu
• Listbox
• Select
• Combobox
• Tooltip

These are backed by core controllers, schemas, specs, adapter examples, DOM contract snapshots, and adapter parity tests. React also contains adapter-owned experimental components, but the docs catalog treats those as outside the canonical v1 surface until their contracts are promoted.

When asking an agent to generate or repair UI code, include:

• Adapter and package name.
• Primitive name and required slots.
• Controlled or uncontrolled state mode.
• Required ARIA relationships.
• Keyboard and focus expectations.
• Public data-* attributes that must remain inspectable.
• Validation command or checklist.

Example prompt shape:

Build a Select with @nake-ui/adapter-vue. Use uncontrolled value, include Trigger,
Value, Content, Group, Label, Option, HiddenInput, preserve aria-controls and
aria-selected, and list the DOM contract checks after the code.

• Quick Start: install one adapter and ship a first primitive.
• Installation: choose package versions and peer dependencies.
• Adapter Integration: map framework ergonomics to the same DOM contract.
• Primitive Concepts: learn state, event, focus, ARIA, schema, and validator vocabulary.
• Components Overview: inspect the v1 primitive catalog.