docs: publish the UI standards in docs/contributing

The binding UI rulebook (card anatomy, spacing scale, text colour,
tokens, primitive mapping, enforcement) lived outside the repository,
so a contributor could follow a code comment to a file they could not
open. It now lives at docs/contributing/ui-standards.md, every comment
that cited it points there, and the docs index and ui-guidelines.md
say which document wins when they disagree.
This commit is contained in:
Marc-André Bombeck committed 2026-10-21 19:37:22 +02:00
1 parent 07f9615dba
commit d44af06467
46 files changed
+244 -55

No files matched your search

@@ -404,7 +404,7 @@ describe("how a field says what is wrong with it", () => {
// Announced, because it MOUNTS with the role rather than a class being
// swapped onto a node that was already there.
expect(alert).toContain('role="alert"');
// Content, not meta. UI-STANDARDS §3, and the same reasoning
// Content, not meta. ui-standards.md §3, and the same reasoning
// `grant-action-error.tsx` spells out: a refusal rendered as muted is a
// refusal nobody reads.
expect(alert).toContain("text-destructive");
@@ -521,7 +521,7 @@ describe("ending a managed profile", () => {
authRef.value = { accounts: [entry()], active: null };
const html = renderGatedSection();
expect(html).toContain('data-slot="managed-profile-delete"');
// The mobile tap floor UI-STANDARDS §11 asks of an inline action.
// The mobile tap floor ui-standards.md §11 asks of an inline action.
expect(html).toMatch(
/data-slot="managed-profile-delete"[^>]*class="[^"]*min-h-11/,
);
@@ -629,7 +629,7 @@ describe("ending a managed profile", () => {
const html = renderGatedSection();
expect(html).toContain('data-slot="query-error-card"');
expect(html).toContain("Could not load who looks after this record");
// And the way back is reachable, which is what UI-STANDARDS §6 asks of an
// And the way back is reachable, which is what ui-standards.md §6 asks of an
// error state.
expect(html).toContain('data-slot="query-error-retry"');
});
@@ -172,7 +172,7 @@ export function grantActionErrorKey(err: unknown, action: GrantAction): string {
* a person who pressed a button and got nothing has already looked away, and
* a screen reader that does not announce it is the same silence the panel had
* before. `text-destructive` because this is content somebody has to act on —
* UI-STANDARDS §3 reserves muted for meta, and a refusal rendered as meta is a
* ui-standards.md §3 reserves muted for meta, and a refusal rendered as meta is a
* refusal nobody reads.
*
* `data-grant-error-for` carries the row id so a panel holding two failed rows
@@ -466,7 +466,7 @@ export function resolveInviteScope({
* a button inside a label forwards its own tap to the label's control, so the
* radio and the popover would fight for the same click (the same reason
* `SectionOption` avoids the wrapping label). Muted, `text-xs` — the meta floor
* per UI-STANDARDS §3.
* per ui-standards.md §3.
*/
function AccessOption({
level,
+1 -1
View File
@@ -54,7 +54,7 @@ export function GrantRowItem({
/**
* Something the person has to read before they act on this row, rendered in
* the content column rather than beside the button: consent copy is content
* (UI-STANDARDS §3), and a sentence squeezed into the action column would
* (ui-standards.md §3), and a sentence squeezed into the action column would
* wrap into a stripe nobody reads.
*/
notice?: ReactNode;
@@ -92,7 +92,7 @@ export function ManagedProfileCard() {
/>
<div className="space-y-4">
{/* Content, not meta: this is what somebody is consenting to take on,
and UI-STANDARDS §3 reserves muted for the incidental. */}
and ui-standards.md §3 reserves muted for the incidental. */}
<p data-slot="managed-profile-explainer" className="text-sm">
{t("recordSharing.managed.explainer")}
</p>
@@ -159,7 +159,7 @@ function ManagedProfileRow({
data-managed-profile-id={profile.accountId}
className="space-y-2 py-3 first:pt-0 last:pb-0"
>
{/* UI-STANDARDS §11 inline action row. */}
{/* ui-standards.md §11 inline action row. */}
<div className="flex items-start justify-between gap-3">
<div className="min-w-0 flex-1">
{/* A person's name is user data and stays content. */}
@@ -168,7 +168,7 @@ function ManagedProfileRow({
{t("recordSharing.lookingAfter.kindManaged")}
</p>
</div>
{/* UI-STANDARDS §11: the actions stay beside the name, never below it.
{/* ui-standards.md §11: the actions stay beside the name, never below it.
Edit is offered without waiting for the roster — it changes what the
record IS and does not depend on how many people look after it,
unlike the deletion beside it, whose confirm copy states that
@@ -223,7 +223,7 @@ function ManagedProfileRow({
{/* A failed roster read is not an absent roster.
Without this branch a 500 renders exactly as a still-loading one —
the row with no guardian panel and no delete control — and the person
waits for something that is never coming. UI-STANDARDS §6: a read
waits for something that is never coming. ui-standards.md §6: a read
that failed says so and offers the way back. It is deliberately NOT
the same as the 404 arm: a 404 means this account is no longer a
Guardian of that profile, which is an answer, and the row correctly
@@ -321,7 +321,7 @@ export function ManagedProfileCreateForm({
* Two nodes, never one that swaps. The form used to render a single muted
* `<p>` whose TEXT changed from hint to error, which is wrong twice over:
*
* * a refusal is content somebody has to act on, and UI-STANDARDS §3
* * a refusal is content somebody has to act on, and ui-standards.md §3
* reserves `text-muted-foreground` for meta. The same reasoning is written
* out at `grant-action-error.tsx` — a refusal rendered as meta is a
* refusal nobody reads;
@@ -292,7 +292,7 @@ function ManagedProfileEditFields({
/>
</div>
{/* Above the action row, per UI-STANDARDS §12: nothing follows it. */}
{/* Above the action row, per ui-standards.md §12: nothing follows it. */}
{error && (
<p
role="alert"
@@ -151,7 +151,7 @@ export function ManagedProfileGuardians({
data-guardian-state={guardian.state}
className="space-y-2 py-3 first:pt-0 last:pb-0"
>
{/* UI-STANDARDS §11 inline action row. */}
{/* ui-standards.md §11 inline action row. */}
<div className="flex items-start justify-between gap-3">
<div className="min-w-0 flex-1">
<p className="truncate text-sm font-medium">
@@ -449,7 +449,7 @@ function HandoverLink({
</p>
<div className="flex flex-col items-center gap-4 sm:flex-row sm:items-start">
{/* The QR quiet zone stays white in both themes: a scanner needs the
contrast, and UI-STANDARDS §4 names this exemption. */}
contrast, and ui-standards.md §4 names this exemption. */}
{/* eslint-disable-next-line @next/next/no-img-element -- a data: URL minted client-side; nothing for the image optimiser to do */}
<img
src={link.qrDataUrl}
@@ -574,7 +574,7 @@ export function DashboardLayoutSection({ id }: { id: string }) {
// then sits at its static position (below this long list) in DOCUMENT
// coordinates and silently makes the document itself scrollable, a
// second vertical scrollbar next to the shell-owned `<main>` scroll
// (UI-STANDARDS §9 one-scroll-floor; guarded by
// (ui-standards.md §9 one-scroll-floor; guarded by
// e2e/settings-overscroll.spec.ts).
<div className="relative space-y-2">
{/* v1.4.15 — table-style header naming the two
@@ -110,7 +110,7 @@ export function ReportScopePicker({
return (
<div className="space-y-3" data-testid={`report-scope-picker-${surface}`}>
{/* The one-click way to a complete report. An inline action row
(UI-STANDARDS §11): the sentence wraps, the action stays beside it.
(ui-standards.md §11): the sentence wraps, the action stays beside it.
It is offered, never applied — and it stays offered so a person can
come back to the standard set after experimenting. On a phone the
action's own label is wider than half the row, so beside it the
@@ -518,7 +518,7 @@ export function ShareLinkCreateForm({
opens the record (and its shared documents). Promoted as the
primary mobile affordance: a clinician scans it on the spot to
open the record on their own device. Shown exactly once. The
white quiet-zone is the documented QR exemption (UI-STANDARDS §4)
white quiet-zone is the documented QR exemption (ui-standards.md §4)
so the code stays scannable in the dark theme too. */}
{qrDataUrl && (
<div