ADR-018: The Aqua registry
Status: Accepted (2026-08-31)
Decision: The panel wears Aqua, the Mac OS X era registry at https://aqua.michi.onl.
components.json gives the namespace @aqua the address https://aqua.michi.onl/r/{name}.json.
npx shadcn@latest add @aqua/theme wrote the palette and the face into
components/globals.css, and each of the seventeen components in components/ui/ came again
from @aqua. This changes the palette and the chrome of
ADR-017. It does not change the framework: the panel is still
Tailwind CSS 4 with shadcn/ui on Base UI.
Why: one registry gives the panel one grammar for a control. The alternative was a palette the project keeps itself, and ADR-014 shows the cost of that. Aqua is MIT, thus each copied file keeps that permission.
What this decision costs:
- The dark theme is gone. An Aqua component paints light chrome, thus a dark palette gives light text on a white card. A user who selects a dark browser now gets a light panel. A dark Aqua is possible only if the registry makes one.
- Three tokens are not the value of the registry. Aqua puts
#2f7de0on a link,#7a8089on small text, and#6cb0f7on the focus ring; those are 3.6:1, 3.5:1, and 2.0:1. The panel is a surface for the keyboard, and it keeps WCAG 2.1 level AA. Those three tokens therefore carry a darker colour that Aqua itself uses. A component is not affected, because it reads no token. Selectarrives withlucide-react. The file incomponents/ui/carries Phosphor imports, because the panel has one icon set.- A new file:
components/ui/loader.tsx. The AquaSpinneris the AquaLoaderat the size of an icon.
The condition to open this decision again: a dark Aqua in the registry, or a component of Aqua that reads the tokens of the theme. Both make the two changes above unnecessary.
This site’s own theme (site/src/styles/aqua.css) carries the same three corrected tokens; see
the site’s stack scaffold for where.