# Detail Page Spec (SPEC-DETAIL)

The Detail archetype covers all single-object pages in `accrue_admin`: subscriptions, customers,
invoices, payments, coupons, and their related objects. These pages share a vertical disclosure
spine: breadcrumbs → GOV.UK-style summary-list header (always-on state) → action menu
(≤2 primary buttons + overflow) → collapsible drill sections → one related-resources strip →
lazy activity timeline and raw JSON at the bottom.

The archetype's governing rule is **summary-then-drill, not everything-at-once.** The pattern was
developed to remediate `subscription_live.ex` — historically the worst "info dump" offender, with
~25 always-visible zones and 10 permanently-expanded inline action forms — as the Phase 195
remediation target. It eliminates the "info dump" by layering content by frequency-of-need per
persona, without deleting any information.

Audience: build agents for Phases 194–200, the `accrue_admin` maintainer, and adopters extending
the admin UI.

---

## SPEC-DETAIL — summary-then-drill

### Machine-checkable invariants

The following invariants are verified deterministically by the page-flow Playwright driver
(`phase191-page-flow-helpers.js`), source guards in `scripts/ci/verify_package_docs.sh`, or
`axe-core`. They must hold on every build.

| Invariant | How verified |
|-----------|--------------|
| **≤2 primary action buttons visible, plus one overflow/dropdown menu.** A detail page may expose at most two primary-level action `<button>` elements (e.g., "Cancel renewal", "Retry invoice") that are visible without invoking any menu. All remaining actions must be collected into a single overflow/dropdown menu. Showing three or more primary-level buttons is a scope violation. | Playwright page-flow spec: `page.locator('[data-ax-primary-action]').count()` must be ≤ 2; `page.locator('[data-ax-action-overflow-menu]').count()` must be ≥ 1 (when more than two actions exist). |
| **Action forms are NOT pre-expanded on page load.** On initial load, the count of visible `<form>` elements inside the action band must be zero. Forms appear only after the operator invokes the corresponding menu item or drawer trigger. | Playwright page-flow spec: on `page.goto(detail_url)`, assert `page.locator('[data-ax-action-band] form:visible').count() === 0`. |
| **Exactly one related-resources strip per page.** Duplicate related-resources cards are a known defect (subscription_live.ex has a second "related billing" nav card that duplicates the canonical strip). Each detail page must render exactly one element matching the related-resources strip selector. | Playwright page-flow spec: `page.locator('[data-ax-related-resources]').count() === 1`. |
| **Overlay/drawer is hit-testable above its scrim, with body scroll locked.** When a drawer or modal overlay is open: (a) the overlay panel's primary action button and at least one focusable control inside it must be click-reachable while the scrim is present (`assertTopPointerTarget` on the panel's primary action); (b) the page body must not scroll when the operator wheels over the scrim (body `scrollTop` unchanged before/after wheel event). | Playwright page-flow spec uses `assertTopPointerTarget(overlayPrimaryAction)` + a body-scroll assertion. Covers both desktop and a mobile viewport. Aligns with Pitfall-1 and Pitfall-2 acceptance criteria from PITFALLS.md. |

### Judge-graded criteria (12-dim rubric)

These items require human or adversarial-agent judgment. They are scored against the 12-dimension
rubric in `.planning/milestones/v1.53-phases/187-audit-baseline/187-RUBRIC.md` and are not
machine-enforceable without that rubric context.

**Summary-list answers "what state, what's wrong" at a glance.**
The GOV.UK-style summary-list header (key/value rows with row-level "Change" affordances) must
carry, above the fold at 1280×800, the answer to: current status badge, customer name/link,
current period, next renewal or cancellation date, and dunning state if applicable. A rubric
reviewer must confirm that this information is visible without scrolling and without opening any
menu or section, and that the summary-list rows carry a visually-hidden "Change" context string
on each action link (accessibility requirement, GOV.UK summary-list semantics).

**No card-in-card double border.**
A detail page must not nest an `ax-card` element inside another `ax-card` element where both
render a visible border. Content groupings inside a card use spacing and heading hierarchy
alone, not a second border ring. A rubric reviewer will flag any rendered screenshot where
two concentric rectangular borders are visible around a related block of content (e.g., the
tax-risk panel inside the actions card, or the confirm-panel inside the actions card).

**Tabs used only for peer record-sets, never for primary state or critical actions.**
Tabs are acceptable only where the tabbed content represents genuinely mutually-exclusive,
equal-weight record collections with short (1–2 word) labels (Customer-360 pattern: Subscriptions,
Invoices, Payments). Using tabs to hide primary status information or a critical action is an
anti-pattern per NN/g and Baymard research (27–43% of users miss horizontal tabs). A reviewer
must confirm: (a) if any tabs are present, each tab label is ≤ 3 words and no tab contains the
primary state summary or a critical action; (b) the primary state is in the always-visible
summary-list header, not behind a tab.

---

*Guide home: `accrue_admin/guides/spec-detail.md`*
*Part of the Phase 193 pattern-lock. Downstream consumers: Phases 195, 198, 199.*