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.

Which component

Details: spec/choosing.md.

Workflow

1. Start from the reference, not from memory. npx monochrome add <component> installs monochrome at its own version, saves settings in monochrome.json, and prints the markup to start from (--json prints it all as JSON). In React and Vue it writes the parts instead (src/components/ui/, or components/ui/ without a src/ folder). For markup, add the line it prints that loads the core.
2. Place it where it belongs. Keep every role and ARIA link; change text, and rename id suffixes together so each id stays unique on the page (the parts make ids for you). The contract: spec/<component>.md.
3. Style it. For a menu, menubar, popover, or tooltip, first copy the Required CSS into the project's global CSS (rule 6). Then style every state the spec's Styling section lists (the selected tab, the highlighted and checked menu items, surfaces) the way the project styles everything else: its own CSS, Tailwind's aria-* and data-* variants, StyleX, or its design system. The spec's Example shows one way; adapt it. Patterns: spec/styling.md.
4. Verify the rendered HTML (what the server returns, or the DOM a client-rendered app builds), not the component source: go through the checklist in spec/conventions.md (Verify), then the component's Contract table, Common mistakes, and Design choices.
5. Fix every mismatch before you call it done.

New project: npx monochrome init installs the package, saves the settings add uses, and adds a short block to AGENTS.md; it works without a package.json too (pages then load the core from a CDN). After an upgrade, apply the steps from npx monochrome changelog --from <old version>, then verify again.