📓 Book of Elementals

A growing book of custom elements that are accessible by default and use light DOM — so every part stays yours to style.

Sibling to book-of-spells, which holds the plain JavaScript helpers. This one holds the elements.

Installation

npm install book-of-elementals

Import one element and you get one element — nothing else is registered:

import 'book-of-elementals/accordion';

@use "book-of-elementals/accordion/style.scss";

Or import the whole book:

import 'book-of-elementals';

@use "book-of-elementals/styles/index.scss";

Or use the CDN, no build step at all. Every element ships its own bundle:

<script src="https://unpkg.com/book-of-elementals/dist/elementals/accordion.min.js"></script>
<link
  rel="stylesheet"
  href="https://unpkg.com/book-of-elementals/dist/elementals/accordion.min.css"
/>

There is no global and no boot call. Including a bundle registers its element, and the element upgrades itself wherever it appears in the page — including markup added later. The whole book is one directory up: dist/book-of-elementals.min.js.

Those stylesheets carry structure and motion only. Each element's look is a separate, optional one, off unless you ask for it:

@use "book-of-elementals/accordion/theme.scss";

<link
  rel="stylesheet"
  href="https://unpkg.com/book-of-elementals/dist/elementals/accordion-theme.min.css"
/>

Every element's look at once is book-of-elementals/theme.scss, or dist/book-of-elementals-theme.min.css — beside the whole-book script, one directory up from the per-element bundles.

Principles

Native first. An element only exists where the platform leaves a real gap. Where HTML already has the semantics — <details> for disclosure, <dialog> for modals — the element coordinates the native thing rather than reimplementing it. That is why the accordion is a few dozen lines instead of a few hundred, and why its keyboard and screen-reader behaviour is the browser's rather than a hand-rolled approximation of it.

Light DOM, always. No shadow roots. Your CSS reaches every part, your existing design tokens apply, and server-rendered markup works untouched.

Accessible or it does not ship. Patterns follow the W3C ARIA Authoring Practices Guide where one applies. Keyboard operation, focus management and reduced-motion handling are not options.

One dependency, and it is the sibling. The plain JavaScript helpers live in book-of-spells and are bundled into dist/, so a script tag still costs you exactly one file. Nothing else, ever.

The book so far

Twenty-seven elements, one page each — eighteen on an APG pattern, nine where there is none to have. The elementals is the index: what each one implements, and which gap in the platform it fills.

Assembled into whole interface pieces, they are in examples — a site header, a sidebar drawer, a bulk-actions toolbar.

One thing here is not an element. The drawn checkbox is a stylesheet <checkbox-group-elemental> could not be drawn without — the mixed state's dash is the one part accent-color cannot touch — and it is opt-in with a class, so every other checkbox on the page can wear the same look.

Thanks

The GitHub accessibility team, lovely people, taught me most of what I know about accessibility and left me caring about it. This project is what that turned into. I hope they are proud. ❤️