Components · Explainer

Explainer panel

The shared answer to the owner's recurring “explain it to me.” ExplainerPanel is a collapsible teaching surface — a Surface rendered as a native <details> (open/close with zero JS) — that gathers the same three things every gate or policy page needs: an icon + heading toggle line, a Callout lead, an optional DescriptionList of facts, and a “why this matters” note. It explains a gate; it is never the gate.

open by default · Callout lead + DescriptionList facts + why-note
Why must I sign the Data-Access Agreement?

Rescuer phone numbers, home addresses, and other personal details are gated behind a signed agreement. Signing records that you understand how to handle a fellow volunteer's PII — before any of it unlocks. It is a one-time signature per version, not a paywall.

Who must sign
Anyone with a team-lead or admin role
Applies to
The rescuer roster & every team's organizing data
Version
Data-Access v2 · 2026-06-30
Re-prompt
Only when the agreement text itself changes

Why this matters

A leaked home address can put a rescuer — or the dogs in their care — at real risk. The signature is the accountable paper trail behind every unlock, not a formality.

The header is the whole toggle: icon (accent) · title (semibold) · chevron pinned to the right, rotated 180° from the [open] state. The lead is a Callout (accent left-rail on surface-2); facts are a real <dl>; the warn-railed note carries the stakes. Click the header to collapse — no JS.

collapsed by default (defaultOpen=false) · pinned :focus-visible
What does “View as” do?

View-as renders the app exactly as another rescuer sees it — same data scoping, same hidden actions — so you can debug a “why can't I see X?” report without their password. It is read-only, and every session is written to the auth log.

Starts collapsed with the summary alone — a details-only panel drops the facts and note. Its <summary> is pinned .is-focus to show the keyboard ring; Tab to it and hit Enter to expand live. The <summary> — never a <div> — is what makes it keyboard-operable for free.

title · summary
title is the always-visible toggle line; summary is the lead prose, rendered in a Callout. Both required.
details?
{ label, value }[] → a DescriptionList of facts (a real <dl>). Omit for a prose-only panel.
why-note
The teaching-panel emphasis line — a warn-railed “why this matters” block that carries the stakes below the neutral facts. Kept distinct from the accent lead so the two never read as one callout.
icon · defaultOpen
icon is a rendered accent element (default a shield); defaultOpen defaults true — explainers are meant to be read.
a11y
The <summary> is the toggle; the chevron is aria-hidden and rotates from [open], so the affordance is never color-only. Rotation honours prefers-reduced-motion.
safety
Presentation only. It EXPLAINS an auth / policy / PII gate — it never performs, weakens, or substitutes for the check itself.

Source · ExplainerPanel.tsx + its AuthExplainer.tsx variant over @phauna/ds Callout / DescriptionList / Surface as="details" · design-system/explainers.