ADR-038: Shared Web-Surface Design Language

Field	Value
Decision ID	ADR-038
Initiative	consistent UX across the public web surfaces (issues #371, #270)
Proposed By	unsorry maintainers
Date	2026-06-14
Status	Accepted

WH(Y) Decision Statement

In the context of two browser-facing surfaces — the contributor leaderboard (docs/leaderboard.html, issue #270) and the proof-graph visualiser (docs/proofs-contributors-visualisation.html, issue #371) — that should read as one product but were built independently: the leaderboard is a polished card UI (Tailwind, Inter, a brand palette, a centred white card, summary chips, gamified badges, dashed empty/error state panels, a custom scrollbar), while the visualiser shipped with its own hand-rolled plainer CSS, facing issue #371’s standing requirement that its UX be consistent with the leaderboard (“the UX from #270 is what we will use for #371”) — the one item left open on #371 after integration (cross-links) was done, we decided for a shared design language, documented here and in SPEC-038-A, as the canonical visual base for every unsorry web surface: a soft off-white canvas, a single centred white rounded-3xl card with a soft shadow and slate border, Inter typography, a fixed brand palette (gold/silver/bronze rank accents, a blue progress accent, slate text/muted), a header pattern (large light “Unsorry” wordmark + an uppercase status chip + summary stat chips + a cross-link to the sibling surface), shared badge/state-panel/scrollbar conventions, and a mobile-first responsive layout (single-column stack that expands to multi-column on wider viewports), and neglected coupling the visualiser to leaderboard.html by importing or templating its markup (the leaderboard page is hand-maintained while the visualiser is generated by tools/visualiser — a build-time dependency between them would be fragile), and a full shared CSS framework/component library (out of proportion for two pages), to achieve two surfaces that look like one product, with the design intent written down once so neither page silently drifts and future surfaces have a reference to conform to, accepting that the palette/typography tokens are deliberately re-declared in each surface (a small, documented duplication) rather than shared through a build step, so the two pages stay decoupled; conformance is by review against this ADR/spec, not enforced by a validator.

References

Status History