TenantAtlas/docs/ui/operator-ux-surface-standards.md

Operator UX & Surface Standards

This document defines the binding audience-and-surface contract for TenantPilot.

It establishes:

• who each product surface is primarily built for
• what type of language is allowed on that surface
• how technical detail must be progressively disclosed
• how operator-facing pages must communicate status, scope, and actions

This document is normative for new operator-facing UI work and for major UI refactors.

1. Purpose

TenantPilot is not a generic admin UI. It is an enterprise operator product for managed Microsoft tenant governance, backup, restore, monitoring, drift detection, and review workflows.

The product must not expose internal implementation structure as if it were product UX.

The default experience must be optimized for the primary working audience. Technical truth may remain available, but it must be progressively disclosed.

2. Product Audience Model

TenantPilot serves four distinct audiences. Every page must have exactly one primary audience.

2.1 Primary Persona: Operator / Engineer

Focus:

• day-to-day execution
• monitoring
• triage
• safe action-taking

Typical tasks:

• onboarding tenants
• configuring providers
• running syncs
• reviewing inventory state
• running backup / restore workflows
• baseline capture / compare
• findings triage
• exceptions / risk acceptance
• operations monitoring

UI requirements:

• clear operator language
• strong scanability
• explicit scope
• safe defaults
• actionable next steps
• minimal ambiguity
• no unnecessary internal field leakage

2.2 Secondary Persona: Senior Engineer / Troubleshooter

Focus:

• diagnosis
• validation
• escalation handling
• deep technical analysis

Typical needs:

• raw payloads
• provider error details
• UUIDs / external IDs
• technical context
• low-level diagnostic traces

UI requirements:

• access to raw truth
• no removal of diagnostic power
• diagnostics available on-demand, never as default-visible content

2.3 Tertiary Persona: Service Manager / CISO / Customer Reviewer

Focus:

• proof
• reporting
• trends
• governance posture
• SLA / audit communication

Typical needs:

• dashboards
• summaries
• evidence-backed reporting
• accepted risks
• review readiness
• exported review packs

UI requirements:

• aggregated, outcome-oriented surfaces
• low operational noise
• no dependence on operator-level detail pages

2.4 Platform Persona: Platform Admin / System Operator

Focus:

• platform administration
• internal platform management
• break-glass operations
• platform-wide controls

Typical surface:

• /system

UI requirements:

• technically capable
• administratively precise
• still intentionally designed
• not a dumping ground for unresolved /admin UX

3. Surface Ownership by Persona

3.1 /admin operator surfaces

/admin is operator-first.

This includes:

• onboarding
• integrations used for tenant operations
• tenant management
• inventory
• policy views
• baselines
• findings
• evidence
• monitoring / operations
• backup / restore
• governance actions

Default-visible UX on these surfaces must be optimized for the Operator / Engineer persona.

3.2 /admin diagnostics surfaces

Diagnostics within /admin belong to the Senior Engineer / Troubleshooter persona.

They are:

• available where appropriate
• secondary
• collapsed, tabbed, or otherwise intentionally disclosed
• never the primary content hierarchy

3.3 Reporting / review surfaces

Reports, review packs, customer read-only views, and similar proof-oriented surfaces are optimized for the Service Manager / CISO / Customer Reviewer persona.

These surfaces prioritize:

• summary
• evidence-backed conclusions
• trends
• risk posture
• review readiness

3.4 /system platform surfaces

/system is reserved for platform-only administration.

Rules:

• /system may expose more technical administrative detail than /admin
• /system must not be used to avoid fixing weak operator UX in /admin
• product operator workflows belong in /admin, not /system

4. Default vs Diagnostics Rule

Gold rule

Default = Operator Language Expanded = Diagnostic Truth

4.1 Default-visible content must avoid:

• raw JSON blobs
• raw internal field names
• raw DB timestamps without product meaning
• raw enum / reason codes
• raw provider error bodies unless translated
• UUIDs or IDs as primary visual content
• implementation-specific field semantics

4.2 Diagnostics content may include:

• raw JSON
• provider error details
• raw IDs / UUIDs
• internal field values
• stacktrace-adjacent diagnostic summaries
• payload sizes
• created_at / updated_at / internal audit metadata where relevant

4.3 Diagnostics placement

Diagnostics must be secondary and intentionally placed, for example:

• collapsed diagnostics section
• dedicated diagnostics tab
• advanced technical panel
• expandable system detail area

Diagnostics must not dominate the primary page hierarchy.

5. Operator-Language Glossary

Internal or technical terminology must not appear in operator-facing default surfaces without translation.

Internal / Technical Term	Operator-Facing UI Term	Notes
dry_run, is_dry_run	Simulation Mode / Simulate Only	Indicates no live Microsoft mutation
metadata_only	Incomplete Capture / Configuration Unavailable	Use based on context
reason_code	Blocked Reason / Failure Reason	Humanized mapping required
provider_consent_missing	Missing Admin Consent	Example translated reason
scope_jsonb.policy_types	Included Policy Types	Never expose DB path syntax
scope_jsonb.foundation_types	Included Foundation Types	Never expose DB path syntax
evidenceGaps	Missing Inventory Data / Incomplete Sync Data	Use operator meaning
fidelity	Match Confidence	Only show if actionable
role_definition_id	Assigned Role	Prefer display name over raw ID

This glossary should expand over time and be treated as a product vocabulary source of truth.

6. Status Taxonomy

UI surfaces must not collapse all state into one ambiguous status.

TenantPilot must distinguish at least four status dimensions where relevant.

6.1 Execution Outcome

Question:

• Did the operation execute successfully?

Examples:

• Queued
• Running
• Succeeded
• Blocked
• Failed
• Cancelled

6.2 Data Completeness

Question:

• Do we have the full data required for reliable interpretation?

Examples:

• Complete
• Incomplete
• Stale
• Unavailable

6.3 Governance Result

Question:

• Is the tenant or object aligned with expected governance state?

Examples:

• Aligned
• Drift Detected
• Exception Applied
• Risk Accepted
• Review Needed

6.4 Lifecycle / Readiness State

Question:

• What lifecycle or publication state is the object in?

Examples:

• Draft
• Active
• Archived
• Review Ready
• Published
• Expired

These dimensions must remain semantically distinct in labels, badges, summaries, and workflows.

7. Mutation Scope Rule

Every action that changes state must communicate its mutation scope before execution.

Allowed mutation-scope categories:

• TenantPilot only
• Microsoft tenant
• Simulation only

Examples:

• Archive local record -> TenantPilot only
• Restore configuration to Intune -> Microsoft tenant
• Dry-run / simulation -> Simulation only

This must be understandable from the action label, preview, confirmation step, or surrounding UI copy.

8. Canonical Detail-Page Layout

Every operator-facing detail page should follow this hierarchy unless there is a strong documented reason not to.

8.1 Header

Must show:

• object identity
• subtle identifier if needed
• 1-2 primary status indicators

8.2 Action Bar

Rules:

• maximum 2 primary actions
• destructive or uncommon actions belong in a secondary group
• action labels must reflect real outcome and mutation scope

8.3 Summary / Health

Top-of-page summary should answer the primary operator question quickly.

Typical examples:

• last sync / last run
• completeness state
• governance state
• current baseline / current assignment
• current blocked reason
• recommended next step

8.4 Primary Content

This is the main working surface:

• related records
• findings
• relations
• scoped data
• actionable tables
• interpreted content

8.5 Diagnostics

Diagnostics belong at the bottom or in a secondary surface:

• raw JSON
• raw IDs
• payloads
• internal timestamps
• provider response detail

9. Safe Execution Standard

Actions with meaningful blast radius must follow a consistent pattern.

Required sequence

1. Configuration
2. Safety checks / simulation
3. Preview
4. Hard confirmation where required
5. Execute

Applies to:

• restore
• baseline enforce
• high-impact bulk actions
• delete actions with tenant impact
• tenant-wide mutation flows

Rules

• no dangerous one-click actions for high-blast-radius operations
• confirmation language must match actual action semantics
• preview must clearly indicate mutation scope

10. Workspace vs Tenant Context Rules

Operators must never have to infer scope from memory.

10.1 Tenant-scoped surfaces

If the operator is inside a tenant surface:

• actions must be tenant-safe
• workspace-wide actions must not silently appear
• show all tenants or similar context escapes must not behave like normal in-flow actions

10.2 Workspace-scoped surfaces

Workspace surfaces may aggregate:

• dashboards
• review views
• multi-tenant monitoring
• fleet-level rollouts
• cross-tenant summaries

But they must still communicate that they are workspace-level, not tenant-level.

10.3 Context clarity requirements

Every page must make clear:

• current scope
• object scope
• whether actions are local or cross-scope
• whether current data is tenant-specific or workspace-aggregated

11. Page Contract Requirement

Every new or materially refactored page must define the following before implementation:

• primary persona
• surface type
• primary operator question
• default-visible information
• diagnostics-only information
• status dimensions used
• mutation scope
• primary actions
• dangerous actions

A page that cannot answer these questions is not ready for implementation.

12. Surface Types

Recommended surface categories:

• operator execution surface
• operator monitoring surface
• diagnostic detail surface
• reporting / review surface
• customer read-only surface
• platform admin surface

These categories help determine hierarchy, language, action model, and diagnostics visibility.

13. What Good Looks Like

A strong operator-facing page lets the primary persona understand within a few seconds:

• what this page represents
• what scope they are in
• whether something is healthy, blocked, incomplete, or risky
• what they should do next
• whether any action changes TenantPilot only, Microsoft tenant state, or nothing live

A strong diagnostics surface lets the troubleshooting persona access raw truth quickly without polluting the primary operator experience.

A strong reporting surface avoids operational noise and emphasizes proof, posture, and readiness.

14. Adoption Rules

This document applies to:

• new operator-facing resources
• new dashboards and detail pages
• new action-heavy flows
• major refactors of existing surfaces
• new specs that materially affect operator UX

Specs should explicitly reference this document where relevant.

Recommended spec fields:

• primary persona
• surface type
• diagnostics boundary
• status taxonomy used
• mutation scope
• action safety model

15. Non-Goals

This document does not define:

• color palette
• visual branding
• CSS-level implementation details
• pixel-level layout choices
• complete component library design

This document is about audience, semantics, surface structure, diagnostics boundaries, and safe operator UX.

16. Summary

TenantPilot must behave like a product, not a raw schema browser.

That means:

• operator-first default surfaces
• diagnostics available, but secondary
• distinct status dimensions
• explicit mutation scope
• safe execution for dangerous actions
• explicit workspace / tenant context
• page-level audience and surface contracts