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
100 lines
2.1 KiB
Markdown
100 lines
2.1 KiB
Markdown
# 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.
|