ahmido
c36cb43741
This PR introduces the Global Surface Information Architecture Contract, detailing rules for decision-first display, metadata separation, and zero-state suppression across UI surfaces. Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #441
2.7 KiB
2.7 KiB
Page Assessment Checklist
Use this checklist when a future spec adds, removes, renames, or materially changes a reachable UI surface.
Applicability
- The future spec states whether UI Surface Impact exists.
- If no UI surface impact exists, the future spec gives one concise rationale and does not complete unnecessary page-report work.
- If a reachable UI surface changes, the future spec names the route/page/action/state and updates or explicitly marks UI audit coverage.
Classification
- Surface type is one of the Spec 370 surface types.
- Audience type is declared.
- Scope type is declared.
- Repo-truth level is labeled with a verification class.
- The surface has one primary user question.
First Viewport
- Header answers where the user is.
- One primary status is visible.
- Reason and impact are visible when actionability depends on them.
- One dominant next action is visible when a safe action exists.
- Secondary actions do not compete with the dominant action.
- Zero/no-attention metrics are suppressed unless they prove the state.
- Raw IDs, provider payload terms, operation internals, and debug labels are absent by default unless the page is diagnostic/system/support.
Content Placement
- Main content carries the page's primary decision or workflow answer.
- Sidebar/aside carries secondary context and metadata.
- Technical details are collapsed or secondary by default.
- Evidence area is distinct from diagnostics.
- Later sections add proof/detail instead of repeating the same decision summary.
Customer And Auditor Safety
- Customer/auditor default paths avoid raw JSON, internal IDs, fingerprints, raw operation links, debug labels, and internal reason ownership.
- Evidence readiness, limitations, captured-at timing, and export/handoff action are clear.
- Support/raw detail is collapsed, lower-priority, or capability-gated.
Diagnostic Surfaces
- Diagnostic pages lead with what failed.
- Likely cause is stated when known.
- Next check or operator action is visible.
- Related evidence and operation links are present when available.
- Raw detail is structured, not dumped as the primary page answer.
Review Outcome
Choose one review outcome:
blockerstrong-warningdocumentation-required-exceptionacceptable-special-case
Choose one workflow outcome:
keepsplitdocument-in-featurefollow-up-specreject-or-split
Notes
Use document-in-feature for contained deviations. Use follow-up-spec when drift is recurring or structural. Do not rewrite completed historical specs to retrofit this checklist.