521 lines
12 KiB
Markdown
521 lines
12 KiB
Markdown
# 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 |