monochrome-ui AGENTS.md

AGENTS.md

Instructions for working on monochrome: an accessible, headless UI component library with no runtime dependencies. Eight components (Accordion, Collapsible, Dialog, Menu, Menubar, Popover, Tabs, Tooltip), plus an optional router and thin React and Vue wrappers. The core is framework-agnostic and works on plain HTML; import it once and every correctly- structured component on the page becomes interactive.

North stars (non-negotiables)

These aren't preferences. Break any of them and it isn't monochrome any more:

1. DOM is the source of truth. Every decision reads aria-expanded, aria-selected, aria-checked, aria-hidden, aria-disabled. There is no internal state object mirroring the DOM anywhere in the library.
2. Event delegation only. Listeners go on window. Zero per-element listeners. Each component registers only the events it handles. Combined, the set is still the nine: pointerdown, pointerup, click, pointermove, keydown, scroll, resize, focusin, focusout.
3. Zero timers. No setTimeout, requestAnimationFrame, queueMicrotask, debounce, or throttle. Every action is synchronous within its event.
4. Zero runtime dependencies. Shared helpers (src/dom.ts) import nothing. Components import only those helpers. The wrappers import only their framework (as peer deps) plus one side-effect import of their own core file, so a single wrapper import ships both markup and behavior.
5. Baseline 2024 browsers. We rely on the Popover API. No polyfills shipped.
6. One file per component. Shared helpers live in src/dom.ts. Each component is src/{name}.ts and registers its own window listeners. src/index.ts only imports every component so import "monochrome" still lights up the page. Components do not import each other.

Why the core looks weird (and should stay weird)

Six architectural choices that explain the shape of the library. Each looks odd at a glance and each has a specific reason. Don't "fix" them.