vaneenige/monochrome-ui/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.

1. 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.

1. Triggers are `<button type="button">`. Only tooltip triggers

may be any focusable element.

1. 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.

1. 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).

1. 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.

1. 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).

1. 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.

1. 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.

1. 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.

1. 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.

1. 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.

Framework notes

• HTML, server templates, htmx: add prints the markup and

the tag that loads the core once per page: <script type="module" src="https://cdn.jsdelivr.net/npm/monochrome/dist/index.js"></script>.

• React 19: add menu writes src/components/ui/menu.tsx

(.jsx without a tsconfig); import { Menu } from there (there is no monochrome/react). Parts render the spec's markup with useId ids. default* props are initial values; there is no controlled open prop. The files are "use client"; your component that passes handlers such as onClick needs it too (add prepends it in Next.js). Shared rules: spec/conventions.md (Parts).

• Vue 3.5: add menu writes src/components/ui/menu/, one

single-file component per part and an index.ts; import { Menu } from there (there is no monochrome/vue) and write <Menu.Root> in templates. Same markup, ids, and initial values as the React parts; props take the template's kebab-case (default-checked, keep-open). Shared rules: spec/conventions.md (Parts).

• Other frameworks (Svelte, Astro, Solid): add prints the

markup (--framework html, the default without React or Vue); write it in templates and import "monochrome" once in the app entry. React below 19 or Vue below 3.5: the same, with --framework html.

• SSR, streaming, generated HTML: nothing to hydrate or re-run.

Markup is live as soon as it is in the document.

• Reacting to state: observe the attribute with a

MutationObserver; a trigger's own click handler runs before the core and sees the old state.

Router quick rules

import "monochrome/router". Wrap each page in data-mc-area="root"; mark sub-regions with data-mc-area="name" and a data-mc-key (same key on both pages keeps the region). Same-origin links swap in place; rel="external", target="_blank", download, cross-origin links, and forms are left alone. Re-run page scripts on addEventListener("mc:navigate", ...). Details: spec/router.md.

Common traps

• Missing role="button" on a standalone menu trigger, or

role="menuitem" on submenu and menubar triggers.

• Menu items not wrapped as li role="none" with the item first.
• A menu radio set or labelled section outside a group: wrap it in

li role="none" > ul role="group" named by its label (Menu.Group label="…" with the parts). A submenu wrapper is Menu.Sub.

• A menubar needs exactly one item with tabindex="0".
• Tabs must be direct children of role="tablist", exactly one

aria-selected="true".

• Accordion items must be direct children of the mcr:accordion:

root, heading first, button first inside it.

• popover="manual" (not auto) on menu, popover, and tooltip

content; role="dialog" on popover content; a <dialog> element for dialogs.

• display on closed content overrides hidden and the popover

closed state; scope it to the open state.

• Dark mode: the page sets color-scheme (:root or .dark);

monochrome never does, so without it surfaces stay light.