monochrome

monochrome

monochrome makes correctly marked-up HTML interactive. Import it once; every component on the page works, including markup added later (framework renders, innerHTML, streamed or generated HTML). There is no init call, no state object, and no event wiring. The DOM is the state: the core reads and writes ARIA attributes.

Components: Accordion, Collapsible, Dialog, Menu, Menubar, Popover, Tabs, Tooltip. Optional: Router.

The spec for the installed version is in node_modules/monochrome/spec/, one file per component plus choosing, conventions, styling, and router; spec/<topic>.md below means that folder. Without the package installed, npx monochrome docs <topic> prints the same pages.

Hard rules

1. Ids wire everything. mct:<kind>:<id> is a trigger, mcc:<kind>:<id> its content, mcr:<kind>:<id> a root. Every id is unique on the page.
2. Link both ways. Trigger aria-controls names the content id; content aria-labelledby names the trigger id (a dialog names its title). Accordion panels are role="region"; collapsible content links back only as a role="region". Tooltip triggers use aria-describedby. One id per attribute.
3. Triggers are <button type="button">. Only tooltip triggers may be any focusable element.
4. Never write JS to open, close, select, or toggle. No showModal(), no popovertarget, no useState for open state, no handler that flips hidden or aria-*. The core does it. Handlers for what an item does (onClick on a menu item) are fine.
5. State lives in ARIA. Author the initial values (aria-expanded="false" plus hidden, aria-selected, aria-checked), then let the core own them. Disable with aria-disabled="true", never disabled (the parts' disabled prop renders aria-disabled for you).
6. monochrome ships no CSS; style with attribute selectors: [aria-expanded="true"], [aria-selected="true"], [aria-checked="true"], [data-mc-highlighted], :popover-open, dialog[open]. Menus, popovers, and tooltips need the Required CSS from their spec's Styling section, copied as it is: it places them at their trigger from the variables and the [data-mc-y] / [data-mc-x] side the core writes. Don't write placement of your own. Pick a side and alignment with data-mc-side (top, right, bottom, left) and data-mc-align (start, center, end) on the content.
7. One import family. import "monochrome" (or the CDN script) for plain pages; in apps, the component files add writes (each imports its own monochrome/<component> module). Never both: listeners would register twice. When React or Vue only renders HTML on the server (a static site, no client bundle of the component files), their imports never reach the browser: load the core once from the script every page runs, and drop the core import (and "use client") from the component files (spec/conventions.md, Server rendering).
8. Deliberate behaviour is not a bug. Each spec ends with Design choices: tabs select on Enter, not on focus; arrows skip disabled items; tooltips have no delay and never show on touch; menus open on press. Don't add code to change them.