@nano-ui-kit/web-components

Vanilla web components + A2UI runtime for NanoUI. 80 light-DOM custom elements, a reactive core, a trait system, and a renderer that turns A2UI protocol messages into live DOM.

This package ships UI atoms only. The generation pipeline lives in @nano-ui-kit/a2ui-compose; the pattern corpus in @nano-ui-kit/a2ui-corpus; the MCP server in @nano-ui-kit/a2ui-mcp.

Quick start

<link rel="stylesheet" href="node_modules/@nano-ui-kit/web-components/index.css" />

<script type="module">
  import '@nano-ui-kit/web-components';   // registers every *-n tag
</script>

<card-n>
  <header>
    <span slot="icon"><avatar-n icon="user"></avatar-n></span>
    <span slot="heading"><text-n strong>Hello</text-n></span>
  </header>
  <section>Composition works out of the box — no framework.</section>
</card-n>

The package sideEffects entry keeps the import above from being tree-shaken; importing index.js side-effect-registers every component.

Layout

web-components/
├── core/           — Reactivity + base classes
│   ├── signals.js       signal() / computed() / effect() / batch() / untracked()
│   ├── template.js      tagged templates: html, css, repeat, stamp
│   ├── element.js       NanoElement — light-DOM reactive base
│   ├── form.js          NanoFormElement — form-associated + validation
│   ├── provider.js      global provider registration + router-n
│   ├── anchor.js        popover + anchor-positioning
│   ├── markdown.js      lightweight markdown renderer
│   └── transport.js     SSE / streaming helpers for LLM adapters
│
├── components/     — 80 *-n custom elements
│   └── <tag>/
│       ├── <tag>.js       class definition (extends NanoElement)
│       ├── <tag>.css      @scope(tag-n) two-block: tokens + styles
│       ├── <tag>.yaml     authoring contract (props, slots, events, examples)
│       └── <tag>.a2ui.json  generated — do NOT edit
│
├── patterns/       — Higher-level compositions (tag: `nano-*`)
│   ├── app-shell, app-nav, section-nav   — admin layout scaffolding
│   ├── nano-chat, nano-editor, gen-ui    — LLM + editor + gen-UI patterns
│   └── index.js                          — registers all patterns
│
├── traits/         — 40 composable behaviors via defineTrait()
│                     (pressable, focusTrap, confetti, resizable, …)
│
└── styles/         — Global tokens and CSS layering
    ├── tokens.css              all --n-* design tokens
    ├── colors/                 primitives / semantics / scrims
    ├── typography.css, space.css, radius.css, shadow.css
    └── themes/*.css            8 themes (ocean, forest, sunset, …)

The A2UI runtime (renderer, registry, wiring engine) lives in @nano-ui-kit/a2ui-utils — installed as a dep; imported from patterns/a2ui-root/a2ui-root.js. LLM transport lives in @nano-ui-kit/gateway — the nano-chat pattern imports the browser adapters from there. Build + training scripts live at the repo root (/scripts), not in this package.

Component contract

Every component is a single-file class extending NanoElement (or NanoFormElement for form fields). All styling lives in a sibling .css file using two-block @scope:

@scope (button-n) {
  :where(:scope) {
    /* Tokens only — zero specificity, parent overrides win */
    --button-bg:     var(--n-accent-bg);
    --button-fg:     var(--n-accent-fg);
    --button-radius: var(--n-radius);
  }
  :scope {
    /* Styles — consume component tokens only, never global directly */
    background: var(--button-bg);
    color:      var(--button-fg);
    border-radius: var(--button-radius);
  }
  :scope[variant="danger"] {
    --button-bg: var(--n-danger-bg);   /* variants override tokens, not styles */
  }
}

Authoring rules (enforced by coherence-audit):

1. No raw colors in component CSS — every color goes through a token.
2. Variants change tokens, modes change layout. A selector that sets display, padding, flex, grid, etc. is a mode and needs a Sanctioned Mode Attributes entry in the contract doc.
3. Boolean props default to false. If the expected default is "on", flip the name (closable → permanent).
4. Event listeners in connected() have matching removeEventListener in disconnected(). Handlers are stable #field arrows, never inline.
5. Light DOM only. No ::part(), ::slotted(), shadow roots. Use attribute selectors on children: :scope > [slot="icon"].

Full authoring contract: docs/specs/component-token-contract.md. The nano-ui-author skill encodes the 20 non-negotiable rules.

Card-n / drawer-n composition parity

Both accept bare <header> / <section> / <footer> tags OR explicit [slot="header|body|footer"]. Both activate a 3-column header grid when any direct [slot="icon|heading|description|action"] child is present (:has(> …) — direct-child only). Drawer supports multi-section bodies with sticky header/footer. See the drawer component page for worked examples.

A2UI runtime

import { A2UIRenderer } from '@nano-ui-kit/a2ui-utils';

const renderer = new A2UIRenderer({ target: document.getElementById('canvas') });
renderer.apply({
  type: 'updateComponents',
  components: [
    { id: 'root', component: 'Card', children: ['hdr', 'body'] },
    { id: 'hdr',  component: 'Header', slots: { heading: 'Generated UI' } },
    { id: 'body', component: 'Section', children: ['btn'] },
    { id: 'btn',  component: 'Button', attrs: { variant: 'primary' }, content: 'Click' },
  ],
});

Accepts the four A2UI message kinds: updateComponents, updateDataModel, wireComponents, createSurface. The registry normalizes LLM-emitted aliases (e.g. Carousel → swiper-n) so generated output is robust to name drift.

Build

npm run build:components    # regenerate all .a2ui.json from YAML

The build also writes packages/a2ui/corpus/catalog-a2ui_0_9.json and catalog-a2ui_0_9_rules.txt — the flat-file catalog the MCP server and generation engine consume.

Themes, density, scale

<div data-theme="ocean" density="compact" size="sm">
  …all descendants re-theme / re-densify / re-scale automatically…
</div>

• [data-theme] — 8 themes: default, ocean, forest, sunset, lavender, rose, slate, midnight
• [density] — compact (0.85×) · spacious (1.15×)
• [size] — sm|md|lg shifts the entire typescale + component dimensions
• [radius] — sharp (0) · rounded (1) · round (2)

Each is a CSS-variable override; no class toggles, no re-imports.

Dependency direction

gen-ui  ──reads──>  a2ui-corpus  ←─reads──  web-components
a2ui-mcp  ──reads──>  gen-ui, a2ui-corpus

Web-components never imports from gen-ui or a2ui-mcp. The A2UI renderer consumes a protocol, not a generator — anything that emits valid A2UI messages drives it.

License

MIT