From dd2917a4ac7db630b5c936d78b06b0485f5056f9 Mon Sep 17 00:00:00 2001
From: Alexander van Elsas <58037137+avanelsas@users.noreply.github.com>
Date: Tue, 26 May 2026 14:08:40 +0200
Subject: [PATCH 1/3] docs(readme): promote framework adapters, trim theming,
 fix structure
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Restructures the root README so first-time visitors see install →
working example → framework options → catalogue without scrolling past
project narrative.

Changes:
- New "Framework adapters" section between Installation and Components
  with a comparison table for all five published adapters (React, Vue,
  Angular, Svelte, Solid) linking to each adapter's README + npm page.
  Previously the README mentioned React and Angular only.
- Theming section trimmed from 37 lines to 6: one paragraph, the eight
  preset names, and links to docs/x-theme.md (full API) and
  docs/THEMING.md (token catalogue). registerPreset and CSS-override
  examples are already in docs/x-theme.md.
- Installation gains a working "Quick start" snippet — minimal HTML
  page rendering x-button + x-alert inside x-theme — replacing the
  bare import-init stub.
- Origin story ("Why BareDOM?") moved to the bottom as "About" so it
  no longer pushes install/quick-start below the fold.
- BareForge section moved below Components — companion product reads
  as "also check this out" rather than competing with the catalogue.
- "Why web components?" heading fixed from H1 to H2 (was a hierarchy
  bug breaking the section nesting).
- Custom Elements Manifest promoted from a parenthetical inside the
  TypeScript bullet to its own bullet — it's what makes the typed
  adapters work and was previously buried.

Net: 290 lines (was 300), 62 insertions / 72 deletions.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 README.md | 134 +++++++++++++++++++++++++-----------------------------
 1 file changed, 62 insertions(+), 72 deletions(-)

diff --git a/README.md b/README.md
index 76cd0f16..7f733160 100644
--- a/README.md
+++ b/README.md
@@ -38,15 +38,7 @@ All components can be explored in the [live demo](https://avanelsas.github.io/ba
 
 ---
 
-## Why BareDOM?
-
-Like most Clojure/ClojureScript developers starting out with UIs, I went through the common phases of using Reagent and Re-frame—which are great utilities in their own right. However, as my UIs became larger and more complex, bundle sizes increased, and I found myself spending too much time rebuilding generic, reusable components from scratch.
-
-I started looking for a different approach and discovered Web Components. I built a few, but didn't have the spare time to develop a comprehensive set that could be used in any project. Then AI arrived. While experimenting with Claude Code, I realised that 1 + 1 could be 3. That is how BareDOM, my first open-source project, was born.
-
-I first built the usual suspects for web components, a basis to create a UI. I then thought about trying something more exciting, with animations, shapes, colours, and a whole range of web components that deal with morphing, kinetics and organic styles were born. I hope it brings you joy when using them in your web application!
-
-# Why web components?
+## Why web components?
 
 **Works in any stack.** Because components are native HTML elements, they work wherever HTML works — vanilla JavaScript, React, Vue, Svelte, Angular, server-rendered HTML, or a static page. No adapter layer, no wrapper library.
 
@@ -64,89 +56,54 @@ I first built the usual suspects for web components, a basis to create a UI. I t
 
 **Open Shadow DOM.** Shadow roots are `mode: "open"` — inspectable in DevTools, styleable via `::part()`, and testable with standard DOM APIs.
 
-**First-class TypeScript support.** Every component ships with auto-generated `.d.ts` type declarations and a [Custom Elements Manifest](https://github.com/webcomponents/custom-elements-manifest). TypeScript consumers get typed element interfaces, typed custom events with detail payloads, and `HTMLElementTagNameMap` augmentation for `querySelector` type narrowing — all without installing a separate `@types` package.
-
----
-
-## BareForge — Visual Page Builder
-
-[![GitHub](https://img.shields.io/github/stars/avanelsas/bareforge?style=social)](https://github.com/avanelsas/bareforge)
-
-[BareForge](https://github.com/avanelsas/bareforge) is a companion visual landing-page builder for BareDOM. Drag-and-drop BareDOM components onto a canvas, configure them in the inspector, and export a complete project.
+**First-class TypeScript support.** Every component ships with auto-generated `.d.ts` type declarations. TypeScript consumers get typed element interfaces, typed custom events with detail payloads, and `HTMLElementTagNameMap` augmentation for `querySelector` type narrowing — all without installing a separate `@types` package.
 
-- **Drag-and-drop canvas** with snap-aware placement
-- **Inspector** with type-aware editors for every BareDOM component
-- **Theme editor** with all 8 BareDOM presets and per-token overrides
-- **Four export modes** — CDN, bundle, ClojureScript, and JavaScript
-
-Try the [live editor](https://avanelsas.github.io/bareforge/) or see the [repository](https://github.com/avanelsas/bareforge) for details.
+**Standards-based metadata.** Every component also ships a [Custom Elements Manifest](https://github.com/webcomponents/custom-elements-manifest) — the same machine-readable interface description used by Storybook, VS Code Custom Data, and the BareDOM framework adapters themselves to generate typed wrappers. If you build tooling on top of BareDOM, the manifest is the source of truth.
 
 ---
 
-## Theming
-
-Wrap any subtree in `<x-theme>` to apply a consistent palette across all components:
+## Installation
 
-```html
-<x-theme preset="ocean">
-  <x-button>Themed button</x-button>
-  <x-alert type="info" text="Themed alert"></x-alert>
-</x-theme>
+```bash
+npm install @vanelsas/baredom
 ```
 
-Ships with **8 built-in presets**: `default`, `ocean`, `forest`, `sunset`, `neo-brutalist`, `aurora`, `mono-ai`, `warm-mineral`. All presets include both light and dark mode values that work with `prefers-color-scheme`.
-
-For custom themes, register your own preset via JavaScript:
+Also available via [Clojars](./docs/installation.md#clojurescript-via-clojars) and [standalone ES modules](./docs/installation.md#vanilla-htmljs-via-es-modules). See the [full installation guide](./docs/installation.md).
 
-```js
-import { registerPreset } from '@vanelsas/baredom/x-theme';
+### Quick start
 
-registerPreset('acme', {
-  light: { '--x-color-primary': '#e11d48', '--x-color-surface': '#fff' },
-  dark:  { '--x-color-primary': '#fb7185', '--x-color-surface': '#1a1a2e' }
-});
-```
+A minimal page that renders a themed button and alert — no build step required:
 
 ```html
-<x-theme preset="acme">...</x-theme>
-```
-
-Or override individual tokens via CSS:
-
-```html
-<x-theme preset="default" style="--x-color-primary: #e11d48;">
-  ...
+<x-theme preset="ocean">
+  <x-button>Click me</x-button>
+  <x-alert type="info" text="It works!"></x-alert>
 </x-theme>
+<script type="module">
+  import { init as initTheme }  from '@vanelsas/baredom/x-theme';
+  import { init as initButton } from '@vanelsas/baredom/x-button';
+  import { init as initAlert }  from '@vanelsas/baredom/x-alert';
+  initTheme(); initButton(); initAlert();
+</script>
 ```
 
-See [docs/x-theme.md](./docs/x-theme.md) for the full token list, preset details, and API reference.
+For deeper usage by stack, see the [JavaScript Developer Guide](./docs/javascript-guide.md), [TypeScript Guide](./docs/typescript.md), or [ClojureScript Guide](./docs/clojurescript-guide.md).
 
 ---
 
-## Installation
-
-```bash
-npm install @vanelsas/baredom
-```
-
-```js
-import { init } from '@vanelsas/baredom/x-button';
-init();
-```
+## Framework adapters
 
-Also available via [Clojars](./docs/installation.md#clojurescript-via-clojars) and [standalone ES modules](./docs/installation.md#vanilla-htmljs-via-es-modules). See the [full installation guide](./docs/installation.md).
-
----
+BareDOM components are native HTML elements — they work natively in any framework, with no adapter required. The published adapters below add typed props, typed custom events, and framework-idiomatic ergonomics on top of the same underlying components.
 
-## Usage
+| Framework | Package | Minimum version | Docs |
+|-----------|---------|-----------------|------|
+| React 19+   | `@vanelsas/baredom-react`   | 2.6.0 | [README](./adapters/react/README.md) · [npm](https://www.npmjs.com/package/@vanelsas/baredom-react) |
+| Vue 3.4+    | `@vanelsas/baredom-vue`     | 2.6.0 | [README](./adapters/vue/README.md) · [npm](https://www.npmjs.com/package/@vanelsas/baredom-vue) |
+| Angular 17+ | `@vanelsas/baredom-angular` | 2.6.0 | [README](./adapters/angular/README.md) · [npm](https://www.npmjs.com/package/@vanelsas/baredom-angular) |
+| Svelte 5+   | `@vanelsas/baredom-svelte`  | 2.6.0 | [README](./adapters/svelte/README.md) · [npm](https://www.npmjs.com/package/@vanelsas/baredom-svelte) |
+| Solid 1.9+  | `@vanelsas/baredom-solid`   | 2.6.0 | [README](./adapters/solid/README.md) · [npm](https://www.npmjs.com/package/@vanelsas/baredom-solid) |
 
-BareDOM components are native HTML elements. Import, register, and use them in any framework or vanilla HTML.
-
-- **JavaScript / TypeScript** — see the [JavaScript Developer Guide](./docs/javascript-guide.md)
-- **TypeScript types** — see the [TypeScript Guide](./docs/typescript.md)
-- **ClojureScript** — see the [ClojureScript Guide](./docs/clojurescript-guide.md)
-- **React** — see [`@vanelsas/baredom-react`](https://www.npmjs.com/package/@vanelsas/baredom-react)
-- **Angular** — see [`@vanelsas/baredom-angular`](https://www.npmjs.com/package/@vanelsas/baredom-angular)
+All adapters are auto-generated from the same Custom Elements Manifest, so adding a new BareDOM component updates every adapter in lockstep.
 
 ---
 
@@ -242,6 +199,29 @@ BareDOM components are native HTML elements. Import, register, and use them in a
 
 ---
 
+## Theming
+
+Wrap any subtree in `<x-theme>` to apply a coordinated palette across every BareDOM component inside it. Eight presets ship in the box — `default`, `ocean`, `forest`, `sunset`, `neo-brutalist`, `aurora`, `mono-ai`, `warm-mineral` — each with light and dark variants that follow `prefers-color-scheme`.
+
+Register your own preset, override individual tokens via CSS, or nest themes for per-section palettes. See [`docs/x-theme.md`](./docs/x-theme.md) for the full API (presets, `registerPreset`, CSS overrides) and [`docs/THEMING.md`](./docs/THEMING.md) for the token catalogue.
+
+---
+
+## BareForge — Visual Page Builder
+
+[![GitHub](https://img.shields.io/github/stars/avanelsas/bareforge?style=social)](https://github.com/avanelsas/bareforge)
+
+[BareForge](https://github.com/avanelsas/bareforge) is a companion visual landing-page builder for BareDOM. Drag-and-drop BareDOM components onto a canvas, configure them in the inspector, and export a complete project.
+
+- **Drag-and-drop canvas** with snap-aware placement
+- **Inspector** with type-aware editors for every BareDOM component
+- **Theme editor** with all 8 BareDOM presets and per-token overrides
+- **Four export modes** — CDN, bundle, ClojureScript, and JavaScript
+
+Try the [live editor](https://avanelsas.github.io/bareforge/) or see the [repository](https://github.com/avanelsas/bareforge) for details.
+
+---
+
 ## Design Principles
 
 **Stateless.** No `atom`, no signal, no reactive state container lives inside a component. Every render is a pure function of the current attributes and properties. Debugging a component means inspecting attributes in DevTools — no hidden state to hunt for. For deeper investigations, the optional [`x-trace-history`](./docs/x-trace-history.md) dev tool ships as a separate ESM module and records every dispatch, attribute change, and lifecycle callback as a navigable timeline with cause→effect chains. Load it with `<script type="module" src="…/x-trace-history.js">` and activate via `?baredom-trace-history`; zero cost when the flag is absent.
@@ -295,6 +275,16 @@ See the [development guide](./docs/development.md) for setting up the dev server
 
 ---
 
+## About
+
+Like most Clojure/ClojureScript developers starting out with UIs, I went through the common phases of using Reagent and Re-frame—which are great utilities in their own right. However, as my UIs became larger and more complex, bundle sizes increased, and I found myself spending too much time rebuilding generic, reusable components from scratch.
+
+I started looking for a different approach and discovered Web Components. I built a few, but didn't have the spare time to develop a comprehensive set that could be used in any project. Then AI arrived. While experimenting with Claude Code, I realised that 1 + 1 could be 3. That is how BareDOM, my first open-source project, was born.
+
+I first built the usual suspects for web components, a basis to create a UI. I then thought about trying something more exciting, with animations, shapes, colours, and a whole range of web components that deal with morphing, kinetics and organic styles were born. I hope it brings you joy when using them in your web application!
+
+---
+
 ## License
 
 MIT

From ec6d6e9baecb0ce767c3bc7dbd0d8ef7c6ad7c95 Mon Sep 17 00:00:00 2001
From: Alexander van Elsas <58037137+avanelsas@users.noreply.github.com>
Date: Tue, 26 May 2026 14:53:35 +0200
Subject: [PATCH 2/3] docs(readme): merge value-prop sections, add Time-Travel
 Debugger, move catalogue
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three follow-up edits on top of the original restructure:

1. Merged "Why web components?" and "Design Principles" into a single
   "Why BareDOM?" section. The two sections overlapped on accessibility,
   theming, and mobile (same content, different framing); the unique
   value from Design Principles (stateless rendering, zero runtime) is
   folded into the merged 7-bullet list. Net: 15 bullets across two
   sections → 7 bullets in one.

2. Added a dedicated "Time-Travel Debugger" section between Components
   and Theming. x-trace-history was previously a one-line mention buried
   inside the Stateless bullet; it's a flagship dev tool (records every
   CustomEvent dispatch, attribute change, instance-field write, and
   lifecycle callback; cause→effect navigation; URL-based bug-sharing;
   zero production cost when inactive). Stateless bullet now contains
   only a forward reference.

3. Moved the full per-component catalogue to docs/components.md and
   replaced the README section with a compact overview table.
   - The original README listed 58 components across 6 categories. The
     library actually has 105 exports (103 UI components + x-theme +
     x-trace-history). All 45 missing were entirely absent from the
     README, including the kinetics/organic/effects/scroll clusters that
     differentiate BareDOM from generic component libraries.
   - docs/components.md now catalogues all 103 components across 11
     categories (Form 23, Feedback 11, Navigation 8, Layout 10, Data 11,
     Overlay 9, Display 6, Animation 6, Effects 12, Scroll 5, Utility 2).
   - README overview is an 11-row category table with counts + example
     names, linking to docs/components.md for the full table.

README: 211 lines (was 290 in the first restructure commit, 300 before
this PR series began).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 README.md          | 153 +++++++++-----------------------------
 docs/components.md | 181 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 218 insertions(+), 116 deletions(-)
 create mode 100644 docs/components.md

diff --git a/README.md b/README.md
index 7f733160..7a843d93 100644
--- a/README.md
+++ b/README.md
@@ -38,27 +38,21 @@ All components can be explored in the [live demo](https://avanelsas.github.io/ba
 
 ---
 
-## Why web components?
+## Why BareDOM?
 
-**Works in any stack.** Because components are native HTML elements, they work wherever HTML works — vanilla JavaScript, React, Vue, Svelte, Angular, server-rendered HTML, or a static page. No adapter layer, no wrapper library.
+**Works in any stack.** Components are native HTML elements — they work wherever HTML works (vanilla JS, React, Vue, Svelte, Angular, server-rendered HTML, static pages). Your components are not tied to the framework you build with today; migrate your app, keep your components.
 
-**No framework lock-in.** Your components are not tied to the framework you are building with today. Migrate your app, keep your components.
+**Stateless.** Every render is a pure function of attributes and properties — no hidden state, no signals, no virtual DOM. Inspect attributes in DevTools and you see the truth. (And when you need deeper traces, BareDOM ships a time-travel debugger — see below.)
 
-**Tree-shakeable by design.** Each component is a separate ES module. Import only what you use; bundle tools eliminate the rest automatically.
+**Zero runtime, tree-shakeable.** Each component is a self-contained ES module compiled with Google Closure Advanced. The only JavaScript in your bundle is the components you import — no framework, no utility belt, no runtime library.
 
-**Full theming with CSS custom properties.** Every visual detail — colours, spacing, radius, shadows, typography — is exposed as a `--x-<component>-<property>` CSS custom property. Override at any scope: globally, per-page, per-instance. Use [`<x-theme>`](./docs/x-theme.md) for centralised theming with built-in presets.
+**Predictable theming.** Every visual detail is exposed as a `--x-<component>-<property>` CSS custom property — override at any scope, or wrap in [`<x-theme>`](./docs/x-theme.md) for coordinated palettes with built-in presets. Light/dark mode adapts automatically via `prefers-color-scheme`.
 
-**Light and dark mode included.** All components adapt automatically to `prefers-color-scheme`. No JavaScript required, no class toggling.
-
-**Accessibility built in.** ARIA roles, live regions, keyboard navigation, focus management, and `prefers-reduced-motion` support are part of the component, not an afterthought. You do not need to layer accessibility on top.
-
-**Mobile-ready.** All components are tested on viewports from 320px up. Overlay panels cap their width to avoid overflow. Touch targets meet the 44px minimum on coarse-pointer devices. Pointer events are used throughout for unified mouse and touch input.
+**Accessible & mobile-first.** ARIA roles, keyboard navigation, focus management, and `prefers-reduced-motion` support are part of every component. All components are tested on viewports from 320px up; touch targets meet the 44px minimum on coarse-pointer devices, and pointer events handle mouse + touch uniformly.
 
 **Open Shadow DOM.** Shadow roots are `mode: "open"` — inspectable in DevTools, styleable via `::part()`, and testable with standard DOM APIs.
 
-**First-class TypeScript support.** Every component ships with auto-generated `.d.ts` type declarations. TypeScript consumers get typed element interfaces, typed custom events with detail payloads, and `HTMLElementTagNameMap` augmentation for `querySelector` type narrowing — all without installing a separate `@types` package.
-
-**Standards-based metadata.** Every component also ships a [Custom Elements Manifest](https://github.com/webcomponents/custom-elements-manifest) — the same machine-readable interface description used by Storybook, VS Code Custom Data, and the BareDOM framework adapters themselves to generate typed wrappers. If you build tooling on top of BareDOM, the manifest is the source of truth.
+**TypeScript + Custom Elements Manifest.** Auto-generated `.d.ts` declarations ship with every component: typed element interfaces, typed custom events with detail payloads, and `HTMLElementTagNameMap` augmentation for `querySelector` narrowing. A standards-based [Custom Elements Manifest](https://github.com/webcomponents/custom-elements-manifest) drives Storybook, VS Code Custom Data, and the BareDOM framework adapters themselves — if you build tooling on top of BareDOM, the manifest is the source of truth.
 
 ---
 
@@ -109,93 +103,36 @@ All adapters are auto-generated from the same Custom Elements Manifest, so addin
 
 ## Components
 
-### Form (17)
-
-| Tag | Description |
-|-----|-------------|
-| [`<x-button>`](./docs/x-button.md) | Action control. Variants: `primary`, `secondary`, `tertiary`, `ghost`, `danger`. Sizes: `sm`, `md`, `lg`. States: `disabled`, `loading`, `pressed`. Icon slots. |
-| [`<x-checkbox>`](./docs/x-checkbox.md) | Boolean input. Reflects `checked` and `indeterminate` states to attributes. |
-| [`<x-color-picker>`](./docs/x-color-picker.md) | Colour picker with 2D saturation/brightness area, hue strip, optional alpha, preset swatches, eyedropper, and clipboard copy. Inline or popover mode. |
-| [`<x-copy>`](./docs/x-copy.md) | Copy-to-clipboard utility button with success feedback. |
-| [`<x-currency-field>`](./docs/x-currency-field.md) | Formatted currency input with locale-aware masking. |
-| [`<x-date-picker>`](./docs/x-date-picker.md) | Calendar-based date selection with keyboard navigation. |
-| [`<x-fieldset>`](./docs/x-fieldset.md) | Groups related form controls with a styled legend. |
-| [`<x-file-download>`](./docs/x-file-download.md) | Download trigger that initiates a file transfer. |
-| [`<x-form>`](./docs/x-form.md) | Form wrapper with coordinated validation state. |
-| [`<x-form-field>`](./docs/x-form-field.md) | Label + input wrapper with error and hint text slots. |
-| [`<x-radio>`](./docs/x-radio.md) | Single-choice input within a radio group. |
-| [`<x-search-field>`](./docs/x-search-field.md) | Search input with integrated clear button and search icon. |
-| [`<x-select>`](./docs/x-select.md) | Dropdown select control with custom styling. |
-| [`<x-slider>`](./docs/x-slider.md) | Range slider with step, min/max, and value display. |
-| [`<x-stepper>`](./docs/x-stepper.md) | Multi-step form progress indicator with navigation. |
-| [`<x-switch>`](./docs/x-switch.md) | Toggle switch for boolean settings. |
-| [`<x-text-area>`](./docs/x-text-area.md) | Multi-line text input with auto-resize option. |
-
-### Feedback (10)
-
-| Tag | Description |
-|-----|-------------|
-| [`<x-alert>`](./docs/x-alert.md) | Semantic alert banner. Types: `info`, `success`, `warning`, `error`. Auto-dismiss with `timeout-ms`. Fires `x-alert-dismiss`. |
-| [`<x-badge>`](./docs/x-badge.md) | Small inline label for counts, states, and categories. |
-| [`<x-chip>`](./docs/x-chip.md) | Compact tag component, optionally removable. |
-| [`<x-notification-center>`](./docs/x-notification-center.md) | Notification hub for aggregating and managing in-app notifications. |
-| [`<x-progress>`](./docs/x-progress.md) | Linear progress bar with determinate and indeterminate modes. |
-| [`<x-progress-circle>`](./docs/x-progress-circle.md) | Circular progress indicator for compact spaces. |
-| [`<x-skeleton>`](./docs/x-skeleton.md) | Animated loading placeholder that mirrors content shape. |
-| [`<x-spinner>`](./docs/x-spinner.md) | Inline loading spinner with size and colour variants. |
-| [`<x-toast>`](./docs/x-toast.md) | Single transient notification with enter/exit animations and auto-dismiss. |
-| [`<x-toaster>`](./docs/x-toaster.md) | Toast manager. Positions a queue of `<x-toast>` elements, enforces `max-toasts`, and fires `x-toaster-dismiss`. |
-
-### Navigation (8)
-
-| Tag | Description |
-|-----|-------------|
-| [`<x-breadcrumbs>`](./docs/x-breadcrumbs.md) | Hierarchical path trail with separator customisation. |
-| [`<x-menu>`](./docs/x-menu.md) | Vertical menu container coordinating `<x-menu-item>` children. |
-| [`<x-menu-item>`](./docs/x-menu-item.md) | Individual menu entry with icon, label, description, and keyboard support. |
-| [`<x-navbar>`](./docs/x-navbar.md) | Top navigation bar with responsive slot layout. |
-| [`<x-pagination>`](./docs/x-pagination.md) | Page navigation controls with first/previous/next/last and page-size selection. |
-| [`<x-sidebar>`](./docs/x-sidebar.md) | Collapsible side navigation panel with collapse/expand animation. |
-| [`<x-tab>`](./docs/x-tab.md) | Individual tab within an `<x-tabs>` container. |
-| [`<x-tabs>`](./docs/x-tabs.md) | Tab container that coordinates `<x-tab>` children, manages active state, and fires change events. |
-
-### Layout (6)
-
-| Tag | Description |
-|-----|-------------|
-| [`<x-card>`](./docs/x-card.md) | Surface container. Variants: `elevated`, `outlined`, `filled`, `ghost`. Interactive mode available. |
-| [`<x-collapse>`](./docs/x-collapse.md) | Expandable/collapsible section with animated height transition. |
-| [`<x-container>`](./docs/x-container.md) | Responsive max-width container with configurable padding. |
-| [`<x-divider>`](./docs/x-divider.md) | Horizontal or vertical visual separator. |
-| [`<x-grid>`](./docs/x-grid.md) | CSS Grid layout component with responsive column configuration. |
-| [`<x-spacer>`](./docs/x-spacer.md) | Flexible spacing element for flexbox and grid layouts. |
-
-### Data (10)
-
-| Tag | Description |
-|-----|-------------|
-| [`<x-avatar>`](./docs/x-avatar.md) | User photo or initials display. Shape, size, and status dot variants. |
-| [`<x-avatar-group>`](./docs/x-avatar-group.md) | Overlapping avatar stack for representing multiple users. |
-| [`<x-carousel>`](./docs/x-carousel.md) | Accessible carousel with swipe/drag, arrows, dot indicators, autoplay, slide/fade transitions, and horizontal/vertical orientation. |
-| [`<x-chart>`](./docs/x-chart.md) | Data visualisation component for common chart types. |
-| [`<x-stat>`](./docs/x-stat.md) | KPI / metric card with value, label, trend, and icon slots. |
-| [`<x-table>`](./docs/x-table.md) | Data grid using CSS subgrid. Supports sorting, single/multi-select, striping, and accessible captions. |
-| [`<x-table-cell>`](./docs/x-table-cell.md) | Table cell for header and data modes, with sort indicator and alignment control. |
-| [`<x-table-row>`](./docs/x-table-row.md) | Table row with interactive selection and `x-table-row-select` event. |
-| [`<x-timeline>`](./docs/x-timeline.md) | Vertical timeline container that coordinates `<x-timeline-item>` children. |
-| [`<x-timeline-item>`](./docs/x-timeline-item.md) | Individual timeline event with time, icon, heading, and body slots. |
-
-### Overlay (7)
-
-| Tag | Description |
-|-----|-------------|
-| [`<x-cancel-dialogue>`](./docs/x-cancel-dialogue.md) | Confirmation modal for destructive cancel actions. |
-| [`<x-command-palette>`](./docs/x-command-palette.md) | Keyboard-accessible global search and command interface. |
-| [`<x-context-menu>`](./docs/x-context-menu.md) | Right-click / long-press contextual action menu. |
-| [`<x-drawer>`](./docs/x-drawer.md) | Off-canvas sliding panel, configurable from any edge. |
-| [`<x-dropdown>`](./docs/x-dropdown.md) | Positioned dropdown container for menus and selection. |
-| [`<x-modal>`](./docs/x-modal.md) | Centred dialog with backdrop, focus trap, and `Escape` to close. |
-| [`<x-popover>`](./docs/x-popover.md) | Anchored popover for tooltips, help text, and contextual UI. |
+**103 web components across 11 categories** — from foundational UI controls to morphing animations, organic effects, and scroll-driven storytelling.
+
+| Category | Count | Examples |
+|----------|------:|----------|
+| **Form**       | 23 | Button · Checkbox · Slider · Combobox · OTP Input · Color Picker |
+| **Feedback**   | 11 | Alert · Toast · Spinner · Progress · Skeleton · Notification Center |
+| **Navigation** | 8  | Navbar · Sidebar · Breadcrumbs · Tabs · Pagination · Menu |
+| **Layout**     | 10 | Card · Grid · Bento Grid · Split Pane · Container · Collapse |
+| **Data**       | 11 | Avatar · Table · Chart · Timeline · Calendar · Stat |
+| **Overlay**    | 9  | Modal · Drawer · Popover · Tooltip · Welcome Tour · Command Palette |
+| **Display**    | 6  | Icon · Image · Typography · Code · Kbd · Spotlight Card |
+| **Animation**  | 6  | Kinetic Canvas · Kinetic Typography · Morph Stack · Soft Body · Splash |
+| **Effects**    | 12 | Liquid Glass · Confetti · Neural Glow · Metaball Cursor · Organic Shape |
+| **Scroll**     | 5  | Scroll · Scroll Parallax · Scroll Stack · Scroll Story · Scroll Timeline |
+| **Utility**    | 2  | i18n · i18n Provider |
+
+See [**docs/components.md**](./docs/components.md) for the full per-component catalogue with one-line descriptions and links to each component's API documentation.
+
+---
+
+## Time-Travel Debugger
+
+[`x-trace-history`](./docs/x-trace-history.md) is BareDOM's dev-only debugger. It records every CustomEvent dispatch, observed attribute change, instance-field write, and lifecycle callback as a navigable timeline with cause→effect navigation — so when a bug appears, you can step back to the exact event that caused it.
+
+- **Zero production cost.** When inactive, the recorder pays a single nil-check per hook site and no per-event overhead.
+- **One-line activation.** `import "@vanelsas/baredom/x-trace-history"` and append `?baredom-trace-history` to the URL — a floating dock attaches to the viewport.
+- **Bug-share via URL.** Record a session, copy the URL, and the recipient sees the same timeline.
+- **Adapter-aware.** Works alongside the React, Vue, Angular, Svelte, and Solid adapters.
+
+See [`docs/x-trace-history.md`](./docs/x-trace-history.md) for the full guide — search, console API, recording sessions, import/export, and the JSON schema.
 
 ---
 
@@ -222,22 +159,6 @@ Try the [live editor](https://avanelsas.github.io/bareforge/) or see the [reposi
 
 ---
 
-## Design Principles
-
-**Stateless.** No `atom`, no signal, no reactive state container lives inside a component. Every render is a pure function of the current attributes and properties. Debugging a component means inspecting attributes in DevTools — no hidden state to hunt for. For deeper investigations, the optional [`x-trace-history`](./docs/x-trace-history.md) dev tool ships as a separate ESM module and records every dispatch, attribute change, and lifecycle callback as a navigable timeline with cause→effect chains. Load it with `<script type="module" src="…/x-trace-history.js">` and activate via `?baredom-trace-history`; zero cost when the flag is absent.
-
-**Standards-only.** BareDOM relies on Custom Elements v1, Shadow DOM v1, and ES modules — all natively supported in modern browsers. There are no polyfills required and no proprietary APIs to learn.
-
-**Zero runtime dependency.** Components are compiled to self-contained ES modules. The only JavaScript in your bundle is the component itself. No framework, no runtime library, no utility belt.
-
-**Accessible by default.** ARIA roles, live regions, keyboard interaction patterns, focus indicators, and `prefers-reduced-motion` support are written into every component that needs them — not optional add-ons.
-
-**Predictable theming.** CSS custom properties follow a single naming convention: `--x-<component>-<property>`. Tokens are set on `:host` and cascade normally. You override them the same way you override any CSS property.
-
-**Mobile-first.** Components use `dvh` viewport units, `calc(100vw - ...)` width caps, and `@media (pointer:coarse)` rules for touch-friendly sizing. No component overflows on a 320px screen.
-
----
-
 ## Bundle Size
 
 BareDOM compiles to lightweight ES modules. Sizes below are gzipped:
diff --git a/docs/components.md b/docs/components.md
new file mode 100644
index 00000000..a46da6ac
--- /dev/null
+++ b/docs/components.md
@@ -0,0 +1,181 @@
+# Components
+
+The full catalogue of BareDOM components — 103 web components across 11 categories. Every component is a native Custom Element with auto-generated TypeScript declarations and is exposed in all five [framework adapters](../README.md#framework-adapters).
+
+Tag names are case-insensitive in HTML but always lowercase-kebab-case in the source. Component documentation links to deeper guides with API tables, examples, and a11y notes.
+
+- [Form (23)](#form-23)
+- [Feedback (11)](#feedback-11)
+- [Navigation (8)](#navigation-8)
+- [Layout (10)](#layout-10)
+- [Data (11)](#data-11)
+- [Overlay (9)](#overlay-9)
+- [Display (6)](#display-6)
+- [Animation (6)](#animation-6)
+- [Effects (12)](#effects-12)
+- [Scroll (5)](#scroll-5)
+- [Utility (2)](#utility-2)
+
+---
+
+## Form (23)
+
+| Tag | Description |
+|-----|-------------|
+| [`<x-button>`](./x-button.md) | Action control. Variants: `primary`, `secondary`, `tertiary`, `ghost`, `danger`. Sizes: `sm`, `md`, `lg`. States: `disabled`, `loading`, `pressed`. Icon slots. |
+| [`<x-checkbox>`](./x-checkbox.md) | Boolean input. Reflects `checked` and `indeterminate` states to attributes. |
+| [`<x-color-picker>`](./x-color-picker.md) | Colour picker with 2D saturation/brightness area, hue strip, optional alpha, preset swatches, eyedropper, and clipboard copy. Inline or popover mode. |
+| [`<x-combobox>`](./x-combobox.md) | Single-select combobox with type-ahead filtering. Value must match one of the provided `<option>` children. |
+| [`<x-copy>`](./x-copy.md) | Copy-to-clipboard utility button with success feedback. |
+| [`<x-currency-field>`](./x-currency-field.md) | Formatted currency input with locale-aware masking. |
+| [`<x-date-picker>`](./x-date-picker.md) | Calendar-based date selection with keyboard navigation. |
+| [`<x-fieldset>`](./x-fieldset.md) | Groups related form controls with a styled legend. |
+| [`<x-file-download>`](./x-file-download.md) | Download trigger that initiates a file transfer. |
+| [`<x-file-upload>`](./x-file-upload.md) | Drag-and-drop upload zone with click-to-browse, file list with thumbnails, validation, and form integration. |
+| [`<x-form>`](./x-form.md) | Form wrapper with coordinated validation state. |
+| [`<x-form-field>`](./x-form-field.md) | Label + input wrapper with error and hint text slots. |
+| [`<x-multi-combobox>`](./x-multi-combobox.md) | Multi-select combobox with type-ahead filtering. Selected items display as removable chips. |
+| [`<x-otp-input>`](./x-otp-input.md) | One-time-password input with single-character slots, auto-advance, paste distribution, and full keyboard nav. |
+| [`<x-radio>`](./x-radio.md) | Single-choice input within a radio group. |
+| [`<x-range-slider>`](./x-range-slider.md) | Dual-handle accessible range slider with form association. Min/max, step, and label support. |
+| [`<x-rating>`](./x-rating.md) | Discrete star-rating with form association and full keyboard support. |
+| [`<x-search-field>`](./x-search-field.md) | Search input with integrated clear button and search icon. |
+| [`<x-select>`](./x-select.md) | Dropdown select control with custom styling. |
+| [`<x-slider>`](./x-slider.md) | Range slider with step, min/max, and value display. |
+| [`<x-stepper>`](./x-stepper.md) | Multi-step form progress indicator with navigation. |
+| [`<x-switch>`](./x-switch.md) | Toggle switch for boolean settings. |
+| [`<x-text-area>`](./x-text-area.md) | Multi-line text input with auto-resize option. |
+
+## Feedback (11)
+
+| Tag | Description |
+|-----|-------------|
+| [`<x-alert>`](./x-alert.md) | Semantic alert banner. Types: `info`, `success`, `warning`, `error`. Auto-dismiss with `timeout-ms`. Fires `x-alert-dismiss`. |
+| [`<x-badge>`](./x-badge.md) | Small inline label for counts, states, and categories. |
+| [`<x-chip>`](./x-chip.md) | Compact tag component, optionally removable. |
+| [`<x-notification-center>`](./x-notification-center.md) | Notification hub for aggregating and managing in-app notifications. |
+| [`<x-progress>`](./x-progress.md) | Linear progress bar with determinate and indeterminate modes. |
+| [`<x-progress-circle>`](./x-progress-circle.md) | Circular progress indicator for compact spaces. |
+| [`<x-skeleton>`](./x-skeleton.md) | Animated loading placeholder that mirrors content shape. |
+| [`<x-skeleton-group>`](./x-skeleton-group.md) | Container that synchronizes child `<x-skeleton>` animation timing and offers declarative layout presets. |
+| [`<x-spinner>`](./x-spinner.md) | Inline loading spinner with size and colour variants. |
+| [`<x-toast>`](./x-toast.md) | Single transient notification with enter/exit animations and auto-dismiss. |
+| [`<x-toaster>`](./x-toaster.md) | Toast manager. Positions a queue of `<x-toast>` elements, enforces `max-toasts`, and fires `x-toaster-dismiss`. |
+
+## Navigation (8)
+
+| Tag | Description |
+|-----|-------------|
+| [`<x-breadcrumbs>`](./x-breadcrumbs.md) | Hierarchical path trail with separator customisation. |
+| [`<x-menu>`](./x-menu.md) | Vertical menu container coordinating `<x-menu-item>` children. |
+| [`<x-menu-item>`](./x-menu-item.md) | Individual menu entry with icon, label, description, and keyboard support. |
+| [`<x-navbar>`](./x-navbar.md) | Top navigation bar with responsive slot layout. |
+| [`<x-pagination>`](./x-pagination.md) | Page navigation controls with first/previous/next/last and page-size selection. |
+| [`<x-sidebar>`](./x-sidebar.md) | Collapsible side navigation panel with collapse/expand animation. |
+| [`<x-tab>`](./x-tab.md) | Individual tab within an `<x-tabs>` container. |
+| [`<x-tabs>`](./x-tabs.md) | Tab container that coordinates `<x-tab>` children, manages active state, and fires change events. |
+
+## Layout (10)
+
+| Tag | Description |
+|-----|-------------|
+| [`<x-bento-grid>`](./x-bento-grid.md) | CSS Grid container for asymmetric "bento box" layouts with dense auto-placement. Pair with `<x-bento-item>`. |
+| [`<x-bento-item>`](./x-bento-item.md) | Structural wrapper that controls column and row spanning inside an `<x-bento-grid>`. |
+| [`<x-card>`](./x-card.md) | Surface container. Variants: `elevated`, `outlined`, `filled`, `ghost`. Interactive mode available. |
+| [`<x-collapse>`](./x-collapse.md) | Expandable/collapsible section with animated height transition. |
+| [`<x-container>`](./x-container.md) | Responsive max-width container with configurable padding. |
+| [`<x-divider>`](./x-divider.md) | Horizontal or vertical visual separator. |
+| [`<x-grid>`](./x-grid.md) | CSS Grid layout component with responsive column configuration. |
+| [`<x-proximity-list>`](./x-proximity-list.md) | Horizontal or vertical list whose items scale up as the pointer approaches — dock effect on any list. |
+| [`<x-spacer>`](./x-spacer.md) | Flexible spacing element for flexbox and grid layouts. |
+| [`<x-split-pane>`](./x-split-pane.md) | Resizable two-panel layout with draggable divider, horizontal or vertical. |
+
+## Data (11)
+
+| Tag | Description |
+|-----|-------------|
+| [`<x-avatar>`](./x-avatar.md) | User photo or initials display. Shape, size, and status dot variants. |
+| [`<x-avatar-group>`](./x-avatar-group.md) | Overlapping avatar stack for representing multiple users. |
+| [`<x-calendar>`](./x-calendar.md) | Inline month calendar — always-visible companion to date pickers, with keyboard navigation. |
+| [`<x-carousel>`](./x-carousel.md) | Accessible carousel with swipe/drag, arrows, dot indicators, autoplay, slide/fade transitions, and horizontal/vertical orientation. |
+| [`<x-chart>`](./x-chart.md) | Data visualisation component for common chart types. |
+| [`<x-stat>`](./x-stat.md) | KPI / metric card with value, label, trend, and icon slots. |
+| [`<x-table>`](./x-table.md) | Data grid using CSS subgrid. Supports sorting, single/multi-select, striping, and accessible captions. |
+| [`<x-table-cell>`](./x-table-cell.md) | Table cell for header and data modes, with sort indicator and alignment control. |
+| [`<x-table-row>`](./x-table-row.md) | Table row with interactive selection and `x-table-row-select` event. |
+| [`<x-timeline>`](./x-timeline.md) | Vertical timeline container that coordinates `<x-timeline-item>` children. |
+| [`<x-timeline-item>`](./x-timeline-item.md) | Individual timeline event with time, icon, heading, and body slots. |
+
+## Overlay (9)
+
+| Tag | Description |
+|-----|-------------|
+| [`<x-cancel-dialogue>`](./x-cancel-dialogue.md) | Confirmation modal for destructive cancel actions. |
+| [`<x-command-palette>`](./x-command-palette.md) | Keyboard-accessible global search and command interface. |
+| [`<x-context-menu>`](./x-context-menu.md) | Right-click / long-press contextual action menu. |
+| [`<x-drawer>`](./x-drawer.md) | Off-canvas sliding panel, configurable from any edge. |
+| [`<x-dropdown>`](./x-dropdown.md) | Positioned dropdown container for menus and selection. |
+| [`<x-modal>`](./x-modal.md) | Centred dialog with backdrop, focus trap, and `Escape` to close. |
+| [`<x-popover>`](./x-popover.md) | Anchored popover for tooltips, help text, and contextual UI. |
+| [`<x-tooltip>`](./x-tooltip.md) | Lightweight non-interactive overlay showing supplementary text on hover or focus of a trigger element. |
+| [`<x-welcome-tour>`](./x-welcome-tour.md) | Guided product tour with spotlight backdrop, popover steps, and configurable connectors between steps. |
+
+## Display (6)
+
+| Tag | Description |
+|-----|-------------|
+| [`<x-code>`](./x-code.md) | Code-display element that reads source code from its own light DOM and applies syntax styling. |
+| [`<x-icon>`](./x-icon.md) | Themeable wrapper around a slotted `<svg>`. Handles sizing, theme-aware colour, and accessibility. |
+| [`<x-image>`](./x-image.md) | Themeable image with aspect ratio, skeleton shimmer while loading, fade-in on load, and fallback slot. |
+| [`<x-kbd>`](./x-kbd.md) | Inline element for keyboard keys and shortcuts. Renders styled `<kbd>` caps from a combo string. |
+| [`<x-spotlight-card>`](./x-spotlight-card.md) | Card surface with a soft radial glow that follows the cursor while over the card. Decorative only. |
+| [`<x-typography>`](./x-typography.md) | Themeable text wrapper. Variants: headings, body, captions, code, keyboard, blockquotes, and more. |
+
+## Animation (6)
+
+| Tag | Description |
+|-----|-------------|
+| [`<x-kinetic-canvas>`](./x-kinetic-canvas.md) | Animated canvas background with slotted content. Renders particle/character animations behind any content. |
+| [`<x-kinetic-font>`](./x-kinetic-font.md) | Variable-font axis interpolation driven by spring physics, reacting to cursor proximity or scroll velocity. |
+| [`<x-kinetic-typography>`](./x-kinetic-typography.md) | Text along SVG paths with motion effects — scrolling, bouncing, oscillating movement, combinable. |
+| [`<x-morph-stack>`](./x-morph-stack.md) | Continuous transformation between UI states — layout, shape, material, and content evolve as one surface. |
+| [`<x-soft-body>`](./x-soft-body.md) | Card whose border is an SVG path driven by spring physics — control points displace and spring back. |
+| [`<x-splash>`](./x-splash.md) | Full-viewport splash screen for app initialization. Dismisses with a fade-out when `active` is removed. |
+
+## Effects (12)
+
+| Tag | Description |
+|-----|-------------|
+| [`<x-confetti>`](./x-confetti.md) | Celebration effect that emits a burst of particles on demand. Triggered imperatively; configuration via attributes. |
+| [`<x-gaussian-blur>`](./x-gaussian-blur.md) | Decorative background with animated blurred colour blobs, producing a soft, dreamy gradient effect. |
+| [`<x-liquid-dock>`](./x-liquid-dock.md) | Viscous floating navigation dock with SVG goo filter. Liquid surface bulges toward your cursor. |
+| [`<x-liquid-fill>`](./x-liquid-fill.md) | Scroll progress indicator that fills with animated liquid. Wave motion reacts to scroll speed. |
+| [`<x-liquid-glass>`](./x-liquid-glass.md) | Content container shaped as a shifting translucent blob, merged via SVG goo filter into organic boundaries. |
+| [`<x-metaball-cursor>`](./x-metaball-cursor.md) | Organic blobs that follow the cursor with latency. Overlapping blobs stretch and fuse like mercury drops. |
+| [`<x-neural-glow>`](./x-neural-glow.md) | WebGL bioluminescent neural network background — softly glowing orbs connected by pulsing lines. |
+| [`<x-organic-divider>`](./x-organic-divider.md) | Curved organic section divider with layered SVG shapes, animations, and full theming. |
+| [`<x-organic-progress>`](./x-organic-progress.md) | Progress indicator that grows a vine or honeycomb lattice structure with simplex-noise organic motion. |
+| [`<x-organic-shape>`](./x-organic-shape.md) | Organic blob-shaped container. Decorative accent or content wrapper with fluid natural boundaries. |
+| [`<x-particle-button>`](./x-particle-button.md) | Button whose surface emits and reabsorbs visual fragments on interaction. Energetic and materially alive. |
+| [`<x-ripple-effect>`](./x-ripple-effect.md) | Container that applies a water-like SVG distortion ripple to its content on mouse click. |
+
+## Scroll (5)
+
+| Tag | Description |
+|-----|-------------|
+| [`<x-scroll>`](./x-scroll.md) | Flexible scroll container with horizontal/vertical carousel scrolling, snap, auto-play, loop, dots, and keys. |
+| [`<x-scroll-parallax>`](./x-scroll-parallax.md) | Parallax container where children move at different speeds relative to scroll via `data-speed`. |
+| [`<x-scroll-stack>`](./x-scroll-stack.md) | Scroll-driven card stacking. Cards animate upward and stack on top of each other like a deck. |
+| [`<x-scroll-story>`](./x-scroll-story.md) | Scrollytelling: a sticky media panel stays pinned while text "steps" scroll past and trigger state changes. |
+| [`<x-scroll-timeline>`](./x-scroll-timeline.md) | Scroll-driven timeline along a vertical track with animated markers and progress fill. |
+
+## Utility (2)
+
+| Tag | Description |
+|-----|-------------|
+| [`<x-i18n>`](./x-i18n.md) | Inline translation element. Renders translated text for a key, resolved from the nearest `<x-i18n-provider>`. |
+| [`<x-i18n-provider>`](./x-i18n-provider.md) | Internationalization provider. Fetches translation JSON and supplies locale context to descendant `<x-i18n>`. |
+
+---
+
+See also: [`<x-theme>`](./x-theme.md) (theming provider, [README section](../README.md#theming)) and [`<x-trace-history>`](./x-trace-history.md) (time-travel debugger, [README section](../README.md#time-travel-debugger)).

From f16a4936b2a359426005898a131c14d47848c462 Mon Sep 17 00:00:00 2001
From: Alexander van Elsas <58037137+avanelsas@users.noreply.github.com>
Date: Tue, 26 May 2026 14:56:28 +0200
Subject: [PATCH 3/3] docs(claude-md): require catalogue + README overview
 updates for new components

When adding a new component, two cross-cutting docs need updating that
neither tests nor lint catch:

- docs/components.md (the full per-component catalogue): a row in the
  appropriate category table, with taxonomy guidance to flag gaps
  before inventing new categories.
- README.md (the Components overview): bump the count in the category
  row, plus the Examples column for flagship components.

The 45-component gap fixed in this PR is concrete evidence the
omission has happened repeatedly. Adding the rule to the existing
registration checklist (Stage 3 of "Development Pipeline for New
Components") keeps it next to the other single-source-of-truth
checklist items (shadow-cljs.edn, package.json, registry.cljs,
public/index.html).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 CLAUDE.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index 6b52f632..4050d1d6 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -267,6 +267,8 @@ Follow these stages in order. **Do not skip or merge stages.**
    - `package.json` — add `"./x-<name>"` entry under `"exports"`
    - `src/baredom/registry.cljs` — require the export namespace and add `<alias>/register!` to `all-registers` (single source of truth; `baredom.core/start!` and `baredom.exports.all/init` both consume this vector)
    - `public/index.html` — add an entry to the `components` array in the `<script>` block (name, tag, file, category)
+   - `docs/components.md` — add a row in the appropriate category table (Form / Feedback / Navigation / Layout / Data / Overlay / Display / Animation / Effects / Scroll / Utility). If no existing category fits, flag the gap to the user before inventing a new one — taxonomy decisions affect the README overview too.
+   - `README.md` — bump the count in the Components overview table for that category and, if the new component is a flagship for its category, add it to the Examples column.
 4. **Verification** — run these checks:
    - `clj-kondo --lint src test` — zero warnings/errors
    - `npx shadow-cljs release lib` — confirms Closure Advanced passes