ADR-001: Alpine.js for Catalog UI

Context

The catalog UI mockup (catalog-mockup.html) must run as a static HTML file with no server and no build step. It will be shared as a standalone file during the prototype phase and must open correctly from file:// in any modern browser.

We need: data rendering from embedded JSON, a card/list view toggle, category filter tabs, search input, and rank badge logic. All without installing anything.

Decision

Use Alpine.js v3 (loaded via CDN) for all client-side interactivity in catalog-mockup.html and related prototype pages.

Alpine provides x-data, x-for, x-if, x-on, and x-text directives directly in HTML markup. No compilation step. No module bundler. No npm install. Embedded JSON is read via JSON.parse(document.getElementById('catalog-data').textContent) to work around file:// CORS restrictions on fetch().

Consequences

Positive

Works from file:// — no CORS, no server required
No build toolchain; edit HTML and reload
HTML templates remain readable without JS expertise
~15 KB gzipped; negligible page-weight impact
Declarative x-for over JSON array renders the entire catalog in one template

Negative

x-show conflicts with Bootstrap d-flex (!important); must use x-if (DOM removal) instead — more re-renders
HTMLHint alt-require rule does not understand :alt dynamic bindings; workaround: add both static alt="" and dynamic :alt="..." to every <img>
No SSR, no routing, no code splitting — not suitable for production at scale
Alpine state is not serialisable; cannot deep-link to filtered/sorted views

Alternatives Considered