ahmido c36cb43741 spec: add global surface IA contract (#441 )

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

2026-06-10 20:25:15 +00:00

2.1 KiB

Raw Permalink Blame History

Copy And Terminology Rules

Verification level: derived from existing implementation using existing repo vocabulary, constitution provider-boundary rules, and Spec 368 findings.

Default Voice

Lead with what the state means.
Use action-oriented copy.
Prefer stable platform nouns.
Avoid implementation-first language in primary UI copy.
Use technical words only where the audience and surface type require them.

Preferred Platform Terms

Workspace
Managed Environment
Provider Connection
Governed Subject
Operation
Evidence
Review
Finding
Governance
Diagnostics

Provider-Specific Terms

Provider-specific terms are allowed when the surface is provider-owned or diagnostic, or when the term names an external product reality the operator must understand.

Provider-specific terms should not become platform-core labels for generic surfaces.

Examples to demote on non-diagnostic surfaces:

raw Graph payload
tenant ID
workspace ID
managed environment ID
API object ID
normalization lineage
provider response body

Status / Reason / Impact / Action Copy

Good structure:

Status: current state.
Reason: why this is the state.
Impact: why it matters.
Primary action: what the user should do next.

Avoid:

"Healthy" without explaining why that matters.
"Pending" without owner or next action.
"Failed" without likely cause or next check.
"View details" as the only action when a clearer action exists.

Customer-Safe Copy

Customer/auditor surfaces should use:

outcome
evidence basis
limitation
accepted risk
review pack
exported report
next review or handoff action

They should avoid by default:

internal run IDs
raw provider IDs
fingerprints
debug labels
internal reason families
stack traces
raw JSON

Action Labels

Use Verb + Object where possible.

Examples:

Review findings
Open evidence
Download review pack
Start restore preview
Open diagnostics
Check permissions

Avoid primary labels that are only scope terms:

Workspace
Tenant
Environment

Use scope words as secondary context unless the object being acted on is truly the scope.

2.1 KiB Raw Permalink Blame History