# NNUI-KIT (`nnuikit`) — The All-In-One Universal UI Kit Specification (llms.txt)

> **Canonical AI Knowledge Reference** for Large Language Models, Perplexity, ChatGPT, Claude, Cursor (`.cursorrules`), Copilot, Windsurf, and AI Autonomous Agents.
> **Package**: `nnuikit` (v1.0.6) | **Homepage**: https://nnui-kit.vercel.app | **GitHub**: https://github.com/harshp421/nnui-kit
> **Architecture**: All-In-One Platform-Native Light-DOM Universal Component System. 45+ accessible primitives and micro-enhancers with sub-40 KB runtime footprint, zero Shadow DOM traps, built-in URL state persistence (`persist="url"`), real-time cross-tab broadcast synchronization (`sync="cross-tab"`), and live AI introspection (`element.inspectAI()`).
> **Installation**: `npm install nnuikit` or CLI: `npx nnui init` / `npx nnui add <component>`
> **Framework Compatibility**: React 18/19 (`nnuikit/react`), Vue 3, Svelte 5, Astro, HTMX 2, Next.js App Router (SSR safe via `nnuikit/client`), Vanilla HTML.

---

## 1. Core Invariants (MUST FOLLOW)

When generating markup for NNUI-KIT:
1. **Light-DOM First**: Never attempt to attach Shadow DOM. All child elements are regular Light-DOM elements.
2. **Mutate Attributes, Never Nodes**: Components toggle `data-state`, `aria-selected`, `aria-expanded`, and `tabindex`. Reconcilers (React 19, Vue 3, Svelte 5) manage the DOM nodes.
3. **SSR & Hydration Safety (`nnuikit/client`)**: When generating code for Next.js App Router, Remix, Nuxt, or SvelteKit, import `nnuikit/client`. It safely no-ops during Node.js server pre-rendering and auto-upgrades elements during browser hydration.
4. **First-Class React 18 & 19 Wrapper (`nnuikit/react`)**: For idiomatic React code, import typed components directly: `import { Tabs, DataGrid, Stepper, Dialog, toast } from 'nnuikit/react'`. They forward refs directly and bridge custom DOM events (`onChange`, `onSelectionChange`, `onSort`, `onOpen`, `onClose`).
5. **Universal Custom Elements**: When not using the React wrapper, write direct HTML/JSX custom element tags (`<ui-tabs>`, `<nnui-tabs>`, `<ui-data-grid>`).
6. **Standard Events**: All components dispatch lowercase standard events (`change`, `input`, `toggle`) with `event.detail.value`.
7. **Declarative Persistence & Cross-Tab Sync**: Add `persist="url"` to automatically synchronize state with URL search params (e.g. data grids, tables, filters), `persist="session"` or `persist="local"` for storage persistence, and `sync="cross-tab"` for automatic real-time BroadcastChannel sync across browser tabs!
8. **AI Introspection Protocol**: Every custom element implements `element.inspectAI()` returning its live schema, current state, and copy-paste ready framework snippets.
9. **Container Adaptive Morphing**: Components use modern CSS `@container` queries; they automatically adapt between dense desktop layouts and single-column mobile views when placed in narrow containers.

---

## 2. Component Markup Contracts

### A. Combobox / Autocomplete (`<nnui-combobox>`)
```html
<nnui-combobox>
  <div data-part="input-wrapper">
    <input data-part="input" placeholder="Search..." autocomplete="off">
    <span data-part="toggle-icon">▼</span>
  </div>
  <ul data-part="listbox">
    <li data-part="option" data-value="val-1">Item 1</li>
    <li data-part="option" data-value="val-2">Item 2</li>
  </ul>
</nnui-combobox>
```
* Tag: `<nnui-combobox>` or `<ui-combobox>`
* Parts: `[data-part="input"]`, `[data-part="listbox"]`, `[data-part="option"]` (with `data-value`)
* Events: `change` (`e.detail.value`, `e.detail.label`)

---

### B. Tabs (`<nnui-tabs>`)
```html
<nnui-tabs value="tab-1" orientation="horizontal">
  <div data-part="tablist">
    <button data-part="tab" data-value="tab-1">Tab 1</button>
    <button data-part="tab" data-value="tab-2">Tab 2</button>
  </div>
  <div data-part="tabpanel" data-value="tab-1">Panel 1 Content</div>
  <div data-part="tabpanel" data-value="tab-2">Panel 2 Content</div>
</nnui-tabs>
```
* Tag: `<nnui-tabs>` or `<ui-tabs>`
* Attributes: `value`, `orientation="horizontal" | "vertical"`
* Parts: `[data-part="tablist"]`, `[data-part="tab"]` (with `data-value`), `[data-part="tabpanel"]` (with matching `data-value`)
* Events: `change` (`e.detail.value`, `e.detail.previousValue`)

---

### C. Dialog / Modal (`<nnui-dialog>`)
```html
<button class="ui-button" onclick="document.getElementById('my-modal').showModal()">Open</button>

<nnui-dialog id="my-modal">
  <dialog>
    <div data-part="dialog-content">
      <h3>Modal Title</h3>
      <p>Modal body content.</p>
      <button data-part="dialog-close" class="ui-button">Close</button>
    </div>
  </dialog>
</nnui-dialog>
```
* Tag: `<nnui-dialog>` or `<ui-dialog>`
* Contains: Standard `<dialog>` element.
* Methods: `.showModal()`, `.close()`
* Close triggers: elements with `data-part="dialog-close"` or clicking the backdrop.

---

### D. Select / Form Associated (`<nnui-select>`)
```html
<form>
  <nnui-select name="country" required>
    <button type="button" data-part="trigger">
      <span data-part="value">Select country...</span>
      <span>▾</span>
    </button>
    <ul data-part="listbox">
      <li data-part="option" data-value="us">United States</li>
      <li data-part="option" data-value="ca">Canada</li>
    </ul>
  </nnui-select>
  <button type="submit" class="ui-button">Submit</button>
</form>
```
* Tag: `<nnui-select>` or `<ui-select>`
* Attributes: `name`, `value`, `required`, `disabled`
* Form Integration: Uses `ElementInternals`. Native form submissions (`FormData`) include this field.

---

### E. Accordion (`<nnui-accordion>`)
```html
<nnui-accordion type="single" collapsible="true">
  <div data-part="item" data-value="item-1">
    <button data-part="trigger">
      <span>Question 1</span>
      <span data-part="icon">▾</span>
    </button>
    <div data-part="content">Answer 1</div>
  </div>
</nnui-accordion>
```
* Tag: `<nnui-accordion>` or `<ui-accordion>`
* Attributes: `type="single" | "multiple"`, `collapsible="true" | "false"`

---

### F. Tooltip (`<nnui-tooltip>`)
```html
<nnui-tooltip delay="150">
  <button data-part="trigger" class="ui-button">Hover me</button>
  <div data-part="content">Tooltip message</div>
</nnui-tooltip>
```

---

### G. Command Palette (`<nnui-command>`)
```html
<!-- Modal triggered via Meta+K or button -->
<button class="ui-button" onclick="document.getElementById('cmd-dialog').showModal()">⌘K Search</button>

<nnui-command id="cmd-dialog" modal hotkey="k">
  <dialog>
    <div data-part="header">
      <input data-part="input" placeholder="Type a command or search..." autofocus>
      <button data-part="close-btn" class="ui-button ui-button--ghost">Esc</button>
    </div>
    <div data-part="list">
      <div data-part="empty" hidden>No matching actions found.</div>
      <div data-part="group" data-group-name="Navigation">
        <div data-part="group-heading">Navigation</div>
        <div data-part="item" data-value="dashboard" data-keywords="home stats">Go to Dashboard</div>
        <div data-part="item" data-value="settings">Account Settings</div>
      </div>
    </div>
  </dialog>
</nnui-command>
```
* Tag: `<nnui-command>` or `<ui-command>`
* Attributes: `modal`, `open`, `hotkey="k"`
* Events: `select` (`e.detail.value`, `e.detail.item`), `open`, `close`

---

### H. Sheet / Drawer (`<nnui-sheet>`)
```html
<button class="ui-button" onclick="document.getElementById('sheet-profile').showModal()">Edit Profile</button>

<nnui-sheet id="sheet-profile" side="right" modal>
  <dialog>
    <div data-part="header">
      <h3 data-part="title">Edit Profile</h3>
      <p data-part="description">Update your personal preferences.</p>
    </div>
    <div data-part="body">
      <!-- Sheet Body Form or Controls -->
    </div>
    <div data-part="footer">
      <button data-part="close-btn" class="ui-button">Done</button>
    </div>
  </dialog>
</nnui-sheet>
```
* Tag: `<nnui-sheet>` or `<ui-sheet>`
* Attributes: `side="right" | "left" | "bottom" | "top"`, `open`, `modal`
* Methods: `.showModal()`, `.close()`
* Events: `open`, `close`

---

### I. Range Slider (`<nnui-slider>`)
```html
<form>
  <label for="volume">Output Volume: <span id="vol-val">50%</span></label>
  <nnui-slider id="volume" name="volume" value="50" min="0" max="100" step="1">
    <div data-part="track">
      <div data-part="range"></div>
      <div data-part="thumb"></div>
    </div>
  </nnui-slider>
</form>
```
* Tag: `<nnui-slider>` or `<ui-slider>`
* Attributes: `value`, `min`, `max`, `step`, `name`, `disabled`
* Form Integration: Form-associated via `ElementInternals`
* Events: `input` (`e.detail.value`), `change` (`e.detail.value`)

---

### J. Dropdown Menu (`<nnui-dropdown>`)
```html
<nnui-dropdown>
  <button type="button" data-part="trigger" data-ui="button">
    <span>Options</span>
    <span>▾</span>
  </button>
  <div data-part="menu" role="menu">
    <div data-part="menu-item" role="menuitem" data-value="profile">
      <span>Profile</span>
      <span data-part="shortcut">⇧⌘P</span>
    </div>
    <div data-part="menu-separator"></div>
    <div data-part="menu-item" role="menuitem" data-value="delete" data-destructive="true">
      <span>Delete Account</span>
    </div>
  </div>
</nnui-dropdown>
```
* Tag: `<nnui-dropdown>` or `<ui-dropdown>`
* Keyboard: `ArrowDown`/`ArrowUp` roving focus, `Home`/`End`, `Enter`/`Space` activate, `Escape` closes
* Events: `select` (`e.detail.value`, `e.detail.item`), `open`, `close`

---

### K. Toaster Notifications (`<nnui-toaster>` & `toast()`)
```html
<!-- Place once near top or root of document -->
<nnui-toaster position="bottom-right"></nnui-toaster>

<script type="module">
  import { toast } from '@nnui/core';

  toast.success('Project deployed successfully', {
    description: 'Version 2.4.0 is now live worldwide.',
    action: { label: 'View', onClick: () => console.log('Viewing...') }
  });
  // Or: toast.error(), toast.warning(), toast.info()
</script>
```
* Tag: `<nnui-toaster>` or `<ui-toaster>`
* Attributes: `position` (`bottom-right`, `bottom-left`, `bottom-center`, `top-right`, `top-left`, `top-center`), `duration` (ms)
* API: `toast(message, opts)`, `toast.success()`, `toast.error()`, `toast.warning()`, `toast.info()`, `toast.dismiss(id)`

---

### L. Data Table (`<nnui-data-table>`)
```html
<nnui-data-table page-size="10" sortable filterable selectable>
  <div data-part="toolbar">
    <input data-part="search" data-ui="input" placeholder="Search rows...">
    <span data-part="selection-count">0 selected</span>
  </div>
  <div data-part="table-container">
    <table>
      <thead>
        <tr>
          <th><input type="checkbox" data-part="select-all"></th>
          <th data-sortable="true" data-sort-key="name">Name <span data-part="sort-icon">⇅</span></th>
          <th data-sortable="true" data-sort-key="amount">Amount <span data-part="sort-icon">⇅</span></th>
        </tr>
      </thead>
      <tbody data-part="tbody">
        <tr data-row-id="1">
          <td><input type="checkbox" data-part="row-select"></td>
          <td>Alice Johnson</td>
          <td>$1,250.00</td>
        </tr>
      </tbody>
    </table>
  </div>
  <div data-part="pagination">
    <span data-part="pagination-info">Showing 1 to 1 of 1</span>
    <button data-part="prev-btn" data-ui="button" data-variant="outline" data-size="sm">Previous</button>
    <button data-part="next-btn" data-ui="button" data-variant="outline" data-size="sm">Next</button>
  </div>
</nnui-data-table>
```
* Tag: `<nnui-data-table>` or `<ui-data-table>`
* Attributes: `page-size`, `page`, `sort-key`, `sort-dir`, `search`
* Events: `sort`, `filter`, `page-change`, `selection-change`

---

### M. Calendar (`<nnui-calendar>`)
```html
<nnui-calendar value="2026-10-03" month="10" year="2026"></nnui-calendar>
```
* Tag: `<nnui-calendar>` or `<ui-calendar>`
* Attributes: `value` (`YYYY-MM-DD`), `month` (1-12), `year`, `min`, `max`, `disabled`
* Form Integration: Form-associated via `ElementInternals`
* Events: `change` (`e.detail.value`, `e.detail.date`), `month-change`

---

### N. Date Picker (`<nnui-date-picker>`)
```html
<form>
  <nnui-date-picker name="dob" placeholder="Select your birthdate..."></nnui-date-picker>
  <button type="submit" data-ui="button">Submit</button>
</form>
```
* Tag: `<nnui-date-picker>` or `<ui-date-picker>`
* Attributes: `value`, `placeholder`, `open`, `disabled`, `name`
* Events: `change`, `open`, `close`

---

### O. Virtualized Data Grid (`<nnui-data-grid>`)
```html
<nnui-data-grid row-height="40" overscan="6">
  <div data-part="viewport" style="height: 480px;">
    <div data-part="runway">
      <table data-part="grid-table">
        <thead></thead>
        <tbody data-part="virtual-tbody"></tbody>
      </table>
    </div>
  </div>
  <div data-part="footer"></div>
</nnui-data-grid>
```
* Tag: `<nnui-data-grid>` or `<ui-data-grid>`
* Attributes: `row-height`, `overscan`, `sort-key`, `sort-dir`, `search`, `streaming`
* JS Methods: `setColumns(cols)`, `setRows(rows)`, `appendRows(newRows)`, `setSearch(query)`, `exportCsv(filename)`
* Events: `sort`, `selection-change`, `stream-update`

---

### P. Date Range Picker (`<nnui-date-range-picker>`)
```html
<nnui-date-range-picker start-date="2026-10-01" end-date="2026-10-15" placeholder="Select travel period..."></nnui-date-range-picker>
```
* Tag: `<nnui-date-range-picker>` or `<ui-date-range-picker>`
* Attributes: `start-date`, `end-date`, `placeholder`, `open`, `disabled`
* Events: `change` (`e.detail.start`, `e.detail.end`, `e.detail.range`)

---

### Q. Tags Input (`<nnui-tags-input>`)
```html
<nnui-tags-input tags="React,TypeScript,Tailwind" max-tags="8" placeholder="Add skill..."></nnui-tags-input>
```
* Tag: `<nnui-tags-input>` or `<ui-tags-input>`
* Attributes: `tags`, `max-tags`, `placeholder`, `disabled`
* Events: `change` (`e.detail.tags`, `e.detail.added`, `e.detail.removed`)

---

### R. Segmented Control (`<nnui-segmented-control>`)
```html
<nnui-segmented-control value="monthly" name="billing">
  <button data-part="segment" data-value="daily">Daily</button>
  <button data-part="segment" data-value="weekly">Weekly</button>
  <button data-part="segment" data-value="monthly">Monthly</button>
  <button data-part="segment" data-value="yearly">Yearly</button>
</nnui-segmented-control>
```
* Tag: `<nnui-segmented-control>` or `<ui-segmented-control>`
* Attributes: `value`, `name`, `disabled`
* Events: `change` (`e.detail.value`, `e.detail.previousValue`)

---

### S. OTP / PIN Input (`<nnui-otp-input>`)
```html
<nnui-otp-input length="6" type="number">
  <div data-part="container">
    <input data-part="slot" data-index="0" maxlength="1" inputmode="numeric" />
    <input data-part="slot" data-index="1" maxlength="1" inputmode="numeric" />
    <input data-part="slot" data-index="2" maxlength="1" inputmode="numeric" />
    <span data-part="separator">-</span>
    <input data-part="slot" data-index="3" maxlength="1" inputmode="numeric" />
    <input data-part="slot" data-index="4" maxlength="1" inputmode="numeric" />
    <input data-part="slot" data-index="5" maxlength="1" inputmode="numeric" />
  </div>
</nnui-otp-input>
```
* Tag: `<nnui-otp-input>` or `<ui-otp-input>`
* Attributes: `length`, `value`, `disabled`, `type`, `mask`
* Events: `input`, `change` (`e.detail.value`, `e.detail.isComplete`)

---

### T. Stepper / Wizard (`<nnui-stepper>`)
```html
<nnui-stepper active-step="1" linear="true">
  <ol data-part="steplist">
    <li data-part="step" data-step="1">Account</li>
    <li data-part="step" data-step="2">Profile</li>
    <li data-part="step" data-step="3">Confirm</li>
  </ol>
  <div data-part="panel" data-step="1">Account credentials...</div>
  <div data-part="panel" data-step="2">Profile details...</div>
  <div data-part="panel" data-step="3">Confirmation review...</div>
</nnui-stepper>
```
* Tag: `<nnui-stepper>` or `<ui-stepper>`
* Attributes: `active-step`, `linear`, `orientation="horizontal|vertical"`
* Methods: `.next()`, `.prev()`, `.goToStep(n)`
* Events: `change` (`e.detail.step`, `e.detail.previousStep`)

---

### U. Resizable Split Panes (`<nnui-resizable>`)
```html
<nnui-resizable orientation="horizontal" style="height: 350px;">
  <div data-part="panel" data-size="25">Sidebar navigation</div>
  <div data-part="handle" role="separator" aria-valuenow="25"></div>
  <div data-part="panel" data-size="75">Main content editor</div>
</nnui-resizable>
```
* Tag: `<nnui-resizable>` or `<ui-resizable>`
* Attributes: `orientation="horizontal|vertical"`, `disabled`
* Events: `resize` (`e.detail.sizes`)

---

### V. File Upload & Dropzone (`<nnui-file-upload>`)
```html
<nnui-file-upload accept="image/*,.pdf" max-size="10485760" multiple>
  <div data-part="dropzone">
    <p>Drag files here or <button data-part="trigger" type="button">browse files</button></p>
  </div>
  <ul data-part="file-list"></ul>
</nnui-file-upload>
```
* Tag: `<nnui-file-upload>` or `<ui-file-upload>`
* Attributes: `accept`, `multiple`, `max-size`, `disabled`
* Events: `change` (`e.detail.files`, `e.detail.rejectedFiles`)

---

### W. Context Menu (`<nnui-context-menu>`)
```html
<nnui-context-menu>
  <div data-part="area">Right click anywhere inside this canvas</div>
  <div data-part="menu" popover>
    <button data-part="item" data-value="copy">Copy</button>
    <button data-part="item" data-value="duplicate">Duplicate</button>
    <button data-part="item" data-value="delete" data-variant="danger">Delete</button>
  </div>
</nnui-context-menu>
```
* Tag: `<nnui-context-menu>` or `<ui-context-menu>`
* Attributes: `disabled`
* Events: `open`, `close`, `select` (`e.detail.value`)

---

### X. Navigation Menu (`<nnui-navigation-menu>`)
```html
<nnui-navigation-menu delay="150">
  <nav data-part="menubar">
    <div data-part="item">
      <button data-part="trigger">Solutions</button>
      <div data-part="content" popover>
        <a href="/enterprise">Enterprise</a>
        <a href="/startups">Startups</a>
      </div>
    </div>
  </nav>
</nnui-navigation-menu>
```
* Tag: `<nnui-navigation-menu>` or `<ui-navigation-menu>`
* Attributes: `delay`, `disabled`
* Events: `open`, `close`

---

### Y. Tree View (`<nnui-tree-view>`)
```html
<nnui-tree-view selection-mode="single">
  <ul data-part="tree">
    <li data-part="item" data-value="src">
      <span data-part="label">📁 src</span>
      <ul data-part="group">
        <li data-part="item" data-value="index.js"><span data-part="label">📄 index.js</span></li>
      </ul>
    </li>
  </ul>
</nnui-tree-view>
```
* Tag: `<nnui-tree-view>` or `<ui-tree-view>`
* Attributes: `selection-mode="single|multiple"`, `disabled`
* Events: `select` (`e.detail.value`), `toggle` (`e.detail.expanded`)

---

### Z. AI Prompt Box (`<nnui-ai-prompt-box>`)
```html
<nnui-ai-prompt-box max-rows="8" placeholder="Ask AI anything...">
  <textarea data-part="input"></textarea>
  <div data-part="toolbar">
    <button data-part="attach-btn" type="button">📎</button>
    <button data-part="submit-btn" type="button">Send</button>
    <button data-part="stop-btn" type="button">Stop</button>
  </div>
</nnui-ai-prompt-box>
```
* Tag: `<nnui-ai-prompt-box>` or `<ui-ai-prompt-box>`
* Attributes: `max-rows`, `loading`, `disabled`, `placeholder`
* Events: `submit` (`e.detail.prompt`), `stop`, `input`

---

### AA. Color Picker (`<nnui-color-picker>`)
```html
<nnui-color-picker value="#3b82f6" name="theme-color">
  <div data-part="swatch"></div>
  <div data-part="popover" popover>
    <input data-part="hex-input" />
    <input data-part="hue-slider" type="range" min="0" max="360" />
    <button data-part="eyedropper-btn" type="button">Pipette</button>
  </div>
</nnui-color-picker>
```
* Tag: `<nnui-color-picker>` or `<ui-color-picker>`
* Attributes: `value`, `name`, `format`, `disabled`
* Events: `change` (`e.detail.value`), `input`

---

### BB. Tier 0 Semantic Base Controls (Pure HTML + CSS, Zero-JS)
```html
<!-- Buttons -->
<button data-ui="button">Primary</button>
<button data-ui="button" data-variant="secondary">Secondary</button>
<button data-ui="button" data-variant="outline">Outline</button>
<button data-ui="button" data-variant="ghost">Ghost</button>
<button data-ui="button" data-variant="destructive">Destructive</button>
<button data-ui="button" data-size="xs | sm | lg | icon">Sized Button</button>

<!-- Badges -->
<span data-ui="badge">Default</span>
<span data-ui="badge" data-variant="brand">Brand</span>
<span data-ui="badge" data-variant="success"><span data-part="badge-dot"></span> Active</span>

<!-- Form Field & Input/Textarea -->
<div data-ui="field">
  <label data-ui="label" for="username" data-required="true">Username</label>
  <input data-ui="input" id="username" placeholder="john_doe">
  <span data-ui="hint">Choose a unique handle.</span>
</div>

<!-- Checkbox & Radio -->
<label data-ui="checkbox"><input type="checkbox" checked> <span>I agree</span></label>
<div data-ui="radio-group">
  <label data-ui="radio"><input type="radio" name="plan" value="a" checked> <span>Option A</span></label>
  <label data-ui="radio"><input type="radio" name="plan" value="b"> <span>Option B</span></label>
</div>

<!-- Switch / Toggle -->
<label data-ui="switch"><input type="checkbox" checked> <span>Enable Feature</span></label>

<!-- Card -->
<div data-ui="card" data-hoverable="true">
  <div data-part="card-header">
    <h3 data-part="card-title">Card Title</h3>
    <p data-part="card-description">Subtitle info</p>
  </div>
  <div data-part="card-content">Card Body Content</div>
  <div data-part="card-footer"><button data-ui="button">Action</button></div>
</div>

<!-- Avatar -->
<div data-ui="avatar"><span data-part="avatar-fallback">HP</span><span data-part="avatar-status"></span></div>

<!-- Alert -->
<div data-ui="alert" data-variant="success" role="status">
  <span data-part="alert-icon">✓</span>
  <div data-part="alert-content">
    <h5 data-part="alert-title">Success</h5>
    <p data-part="alert-desc">Task completed successfully.</p>
  </div>
</div>

<!-- Progress -->
<div data-ui="progress"><div data-part="progress-bar" style="width: 75%;"></div></div>

<!-- Table -->
<div data-part="table-container">
  <table data-ui="table">
    <thead><tr><th>Name</th><th>Role</th></tr></thead>
    <tbody><tr><td>Harsh</td><td>Architect</td></tr></tbody>
  </table>
</div>

<!-- Skeleton -->
<div data-ui="skeleton" style="height: 20px; width: 100%;"></div>

<!-- Separator -->
<hr data-ui="separator">
<div data-part="separator-wrapper"><span data-part="separator-label">OR</span></div>

<!-- Layout Primitives -->
<div data-ui="container" data-size="lg">
  <div data-ui="stack" data-direction="col" data-gap="4">
    <div data-ui="grid" data-cols="3" data-gap="4">
      <div data-ui="card">Grid Item 1</div>
      <div data-ui="card">Grid Item 2</div>
      <div data-ui="card">Grid Item 3</div>
    </div>
  </div>
</div>

<!-- Typography Primitives -->
<h1 data-ui="heading" data-size="2xl">Design System Heading</h1>
<p data-ui="text" data-variant="lead">Primary paragraph text</p>
<p data-ui="text" data-variant="muted">Muted secondary text</p>
<span data-ui="sr-only">Screen reader descriptive announcement</span>

<!-- Feedback & Status Primitives -->
<div data-ui="spinner" data-size="md" role="status" aria-label="Loading"></div>
<div data-ui="empty">
  <div data-ui="empty-icon">📂</div>
  <h3 data-ui="empty-title">No projects found</h3>
  <p data-ui="empty-description">Get started by creating your first project.</p>
</div>

<!-- Form Field Feedback -->
<div data-ui="stack" data-direction="col" data-gap="1">
  <label data-ui="label" for="email-in">Email</label>
  <input data-ui="input" id="email-in" aria-describedby="email-hint" aria-invalid="true">
  <span data-ui="field-error" id="email-err">Please enter a valid work email address</span>
  <span data-ui="field-hint" id="email-hint">We will never share your email</span>
</div>
```

---

## 3. Design System Foundations & DTCG Tokens

### CSS Native Palettes
Apply any of the 6 production palettes on `<html>` or any sub-tree with zero JS:
```html
<html data-palette="violet" data-theme="dark">
<!-- Options: "slate" | "violet" | "emerald" | "rose" | "blue" | "orange" -->
```

### DTCG Design Tokens (`tokens.json`)
NNUI-KIT exports W3C Design Tokens Community Group specification at `nnui-kit/tokens.json` for bidirectional synchronization with Figma Token Studio, Style Dictionary, and design tooling:
```json
{
  "$schema": "https://design-tokens.github.io/community-group/format/",
  "color": { "brand": { "600": { "$type": "color", "$value": "#6366f1" } } }
}
```

---

## 4. Framework Usage Quick Reference

### React 18 & 19 (Official Wrapper)
```jsx
import 'nnuikit/client';
import { toast } from 'nnuikit';
import { Tabs, DataGrid, Stepper } from 'nnuikit/react';

export function Dashboard() {
  const [tab, setTab] = useState('blotter');
  return (
    <Tabs value={tab} onChange={(e) => setTab(e.detail.value)}>
      <DataGrid row-height="40" persist="url" sync="cross-tab" />
    </Tabs>
  );
}
```

### Svelte 5 (Runes)
```svelte
<script>
  import 'nnuikit/css';
  import 'nnuikit/client';
  let role = $state('engineer');
</script>

<ui-select name="role" required onchange={(e) => role = e.detail.value}>
  <button type="button" data-part="trigger"><span data-part="value">Select...</span></button>
  <ul data-part="listbox">
    <li data-part="option" data-value="engineer">Software Engineer</li>
  </ul>
</ui-select>
```

### Vue 3 (Composition API)
```html
<script setup>
import 'nnuikit/css';
import 'nnuikit/client';
import { ref } from 'vue';

const tab = ref('overview');
</script>

<template>
  <ui-tabs :value="tab" @change="tab = $event.detail.value">
    <div data-part="tablist">
      <button data-part="tab" data-value="overview">Overview</button>
    </div>
    <div data-part="tabpanel" data-value="overview">Content</div>
  </ui-tabs>
</template>
```

### HTMX 2 (Hypermedia Form Swaps)
```html
<form hx-post="/api/order" hx-target="#blotter">
  <ui-select name="venue" required>
    <button type="button" data-part="trigger"><span data-part="value">Choose...</span></button>
    <ul data-part="listbox">
      <li data-part="option" data-value="nasdaq">NASDAQ</li>
    </ul>
  </ui-select>
  <ui-slider name="rate" min="1" max="100" value="10"></ui-slider>
  <button type="submit" data-ui="button">Submit Order</button>
</form>
```