monochrome-ui: Instructions file for Codex

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 the React and Vue component templates that npx monochrome add copies into projects (templates/). The core is framework-agnostic and works on plain HTML; import it once and every correctly- structured component on the page becomes interactive.

Read first

• PRINCIPLES.md: the six north stars (DOM is the source of truth, event delegation on window only, zero timers (one paint yield in the router), zero runtime dependencies, Baseline 2024, one file per component) and the shape choices that follow from them. Read it before touching src/. Breaking a north star is never a fix.
• docs/: how each mechanism works. Overlay files are menu.md, popover.md, tooltip.md, dialog.md. Shared helpers plus Accordion, Tabs, and Collapsible live in dom.md. Router in router.md. React and Vue parts in parts.md. The core and router carry no comments; these files are their comments. Read the one for the component you are debugging, skip the rest.
• This file: how to work in the repo. Rules only.

Where things go

Every change has exactly one home. Pick it before writing prose.

• A constraint that, if broken, means "not monochrome": PRINCIPLES.md › North stars. Needs the maintainer's sign-off.
• Why the core has a shape (a pattern, not a mechanism): PRINCIPLES.md › Why the core looks weird.
• How a component behaves, including every bug fix that changes behaviour: docs/<component>.md, inside the paragraph that owns that mechanism. Accordion, Tabs, Collapsible, and shared helpers live in docs/dom.md.
• Behaviour of the parts beyond markup: docs/parts.md.
• React parts: templates/react/<component>.tsx (JSX). Vue parts: templates/vue/<component>/, one single-file component per part, a context.ts for what they share, and an index.ts that loads the core and names the parts. Both are listed in templates/manifest.json. Users own their copies, so they stand alone: each component imports its core as monochrome/<component> and inlines its helpers. Imports between template files are relative and extensionless (./menu, ../menu/context), the one exception to the .js rule. The React and Vue fixtures render these files (@/components/ui). The package has no framework export.
• Every part carries data-slot (after the props spread), a styling hook, and passes a class to its element.
• No CSS ships: not in dist/, not from add. Each spec's Styling section is how a project styles the component (below).
• templates/manifest.json is the one list of components: the build, the CLI, the tests, and the website read it. Each entry names what it requires, whether its spec has Required CSS (placement, checked by the build), and its own files per framework.
• build.ts turns the templates into the files add copies: dist/files/react/, dist/files/vue/, examples/, and a manifest.json (scripts/files.ts). Every .tsx part and example gets a type-stripped .jsx twin, which add writes in a project without a tsconfig*.json; TypeScript the stripper misses fails the build. The Vue parts ship as written (lang="ts", which Vue's tooling compiles in any project). The CLI never generates; it copies. Each file's first line names the version it came from. monochrome.json holds only settings (framework and the components folder); there is no update command yet.
• Frameworks: cli/frameworks.ts has one entry per framework add writes for. html (the default without React or Vue) prints the spec's Anatomy markup; react and vue write the parts. A new framework is one entry there, its files in templates/<id>/ listed in the manifest, an example per component in templates/<id>/examples/, a build step in scripts/files.ts, a Playwright project with its fixtures, and the same CLI tests run for it.
• add and init keep the core in lockstep: they install monochrome at the CLI's own version when the project lacks it, and stop before writing when the project resolves another version (cli/install.ts).
• Router behaviour: docs/router.md.
• How code is written (style, naming, order): this file › Code style, as a rule.
• Toolchain, build, gate: this file › Build pipeline.
• Test naming or structure: this file › Test naming.
• What a component does for consumers: README.md for the overview, spec/<component>.md for the markup contract.