docs: add UX and UI guide
This commit is contained in:
lussierj committed
1 parent
39832fcf80
commit
4656714837
1 file changed
+559
@@ -0,0 +1,559 @@
|
||||
# MinerOps UX/UI Guide
|
||||
|
||||
## Status
|
||||
|
||||
This document is the authoritative baseline for shared MinerOps user-experience
|
||||
principles and application-wide interaction rules. Focused companion documents
|
||||
will define detailed information architecture, screen behavior, and visual
|
||||
system decisions.
|
||||
|
||||
MinerOps uses the product identity:
|
||||
|
||||
**MinerOps**
|
||||
**Operational Intelligence for Mining**
|
||||
|
||||
The current interface is an early-stage, integrated application rendered by the
|
||||
FastAPI backend. The repository does not contain a separate frontend project or
|
||||
commit to a final frontend framework. Existing pages and controls are working
|
||||
foundations, not evidence that every experience described here is implemented.
|
||||
Future capabilities are identified as such throughout this guide.
|
||||
|
||||
## Product Experience Goal
|
||||
|
||||
MinerOps should help a technician or manager understand:
|
||||
|
||||
- what is happening;
|
||||
- where it is happening;
|
||||
- why it may be happening;
|
||||
- what happened previously; and
|
||||
- what action should happen next.
|
||||
|
||||
The interface should connect live observations to durable identity, physical
|
||||
location, repair and component history, operational context, and safe actions.
|
||||
It should never trade operational truth for visual simplicity.
|
||||
|
||||
## Primary Users
|
||||
|
||||
### Technician
|
||||
|
||||
Technicians need fast identification, floor-friendly navigation, repair context,
|
||||
clear next actions, and minimal avoidable data entry. Their common workflows
|
||||
must work on phones, tablets, and workstations.
|
||||
|
||||
### Manager / Site Operator
|
||||
|
||||
Managers and site operators need fleet state, site and room context, trends,
|
||||
work queues, risk concentration, and permission-controlled operational actions.
|
||||
They often move between summary and detail views.
|
||||
|
||||
### Read Only / Auditor
|
||||
|
||||
Read Only users and auditors need a coherent view of current state, immutable
|
||||
history, actors, timestamps, and outcomes without controls that imply they can
|
||||
change authoritative records.
|
||||
|
||||
### Administrator
|
||||
|
||||
Administrators need account, permission, configuration, deployment-health, and
|
||||
audit context. Administrative capability must not obscure the operational views
|
||||
they also use.
|
||||
|
||||
The same underlying data may be presented at different density or with different
|
||||
actions according to role and permission. Presentation differences must not
|
||||
change the meaning of the data.
|
||||
|
||||
## Core UX Principles
|
||||
|
||||
### Technician First
|
||||
|
||||
Optimize frequent floor workflows for fast recognition and safe completion.
|
||||
Prefer direct lookup, durable identifiers, clear state, and focused commands over
|
||||
multi-page data entry.
|
||||
|
||||
### Operational Awareness
|
||||
|
||||
Show scope, location, urgency, impact, freshness, and intentional operating state
|
||||
together. Users must be able to distinguish a fault from planned curtailment,
|
||||
repair work, stale data, or an unknown condition.
|
||||
|
||||
### Distinct Information Roles
|
||||
|
||||
Use each interface according to its strength:
|
||||
|
||||
- maps explain location and spatial concentration;
|
||||
- graphs explain trends and comparisons;
|
||||
- timelines explain history and causality; and
|
||||
- tables explain detail and support precise review.
|
||||
|
||||
Do not use a visually impressive representation when another format answers the
|
||||
operational question more clearly.
|
||||
|
||||
### Mine Map Is Primary
|
||||
|
||||
The Mine Map is a primary operational interface, not a decorative page. It
|
||||
should connect physical layout, current state, work context, and drill-down
|
||||
without forcing users to abandon spatial context.
|
||||
|
||||
### Search Everything
|
||||
|
||||
Durable identities, mutable network observations, serials, repairs, components,
|
||||
locations, users, and relevant events should be discoverable through one
|
||||
consistent search entry point, subject to authorization.
|
||||
|
||||
### Live By Default
|
||||
|
||||
Show the freshest trustworthy state by default. Always expose when it was
|
||||
observed, its source when useful, and whether it is stale or incomplete.
|
||||
|
||||
### Explicit Actions
|
||||
|
||||
Use explicit commands for operational changes. Do not hide lifecycle, repair,
|
||||
component, location, or fleet actions inside generic edits or implicit UI state.
|
||||
|
||||
### Immutable History Remains Visible
|
||||
|
||||
Historical facts, actors, timestamps, and corrections remain visible. A current
|
||||
projection may summarize history but must not replace it.
|
||||
|
||||
### Surface Operational Context
|
||||
|
||||
Place relevant location, neighboring assets, current repair, component, alert,
|
||||
and recent-history context near the object being inspected. Avoid making users
|
||||
reconstruct one situation across unrelated pages.
|
||||
|
||||
### Progressive Disclosure
|
||||
|
||||
Lead with the current status and likely next decision. Reveal diagnostics,
|
||||
history, raw values, and advanced controls as users ask for more detail.
|
||||
Progressive disclosure must not conceal critical risk or uncertainty.
|
||||
|
||||
### Three-Click Goal
|
||||
|
||||
Frequent workflows should normally be reachable and actionable within three
|
||||
meaningful interactions from the user's current operational context. This is a
|
||||
design goal, not permission to skip confirmation or validation for consequential
|
||||
actions.
|
||||
|
||||
### Keyboard And Touch Friendly
|
||||
|
||||
All core workflows must support keyboard navigation and appropriately sized
|
||||
touch targets. Hover-only controls and precision pointer interactions cannot be
|
||||
the sole path to an action.
|
||||
|
||||
### Accessible By Default
|
||||
|
||||
Accessibility is a design constraint from the first implementation, not a later
|
||||
polish phase.
|
||||
|
||||
### Honest Uncertainty
|
||||
|
||||
Unknown, stale, partial, estimated, and unavailable data must look different
|
||||
from known healthy or zero values. Do not invent certainty or interpolate across
|
||||
unsupported gaps.
|
||||
|
||||
### No Silent Mutation
|
||||
|
||||
Show the action being requested, the affected object, and the resulting state.
|
||||
Never alter authoritative records merely because a view opened, refreshed, or
|
||||
changed selection.
|
||||
|
||||
### Preserve Operational History
|
||||
|
||||
Authoritative history is not physically deleted. Use explicit void, correction,
|
||||
retire, or archive workflows. Confirmation language must name the operation and
|
||||
its consequences rather than asking only “Are you sure?”
|
||||
|
||||
## Application Shell
|
||||
|
||||
The application shell should provide:
|
||||
|
||||
- persistent primary navigation appropriate to the viewport;
|
||||
- one global search entry point;
|
||||
- an alerts and notifications area;
|
||||
- the current user, role, and session area;
|
||||
- a clear page title and current site, location, asset, or workflow context;
|
||||
- role-aware primary and secondary actions;
|
||||
- an optional contextual side panel; and
|
||||
- responsive behavior that preserves critical actions and state.
|
||||
|
||||
Desktop layouts may use a persistent navigation rail and side panel. Mobile
|
||||
layouts may collapse navigation and use a full-height drawer or sheet, but the
|
||||
current object, alerts, and primary action must remain easy to recover.
|
||||
|
||||
This guide does not choose final navigation labels or hierarchy. Those decisions
|
||||
belong in the future `docs/design/NAVIGATION.md`.
|
||||
|
||||
## Global Search
|
||||
|
||||
Global search should use one box without requiring a category selection first.
|
||||
Search targets include, where implemented and authorized:
|
||||
|
||||
- miners and Asset IDs;
|
||||
- miner and component serial numbers;
|
||||
- MAC and IP addresses;
|
||||
- repairs;
|
||||
- tracked components;
|
||||
- sites, rooms, racks, shelves, and operational locations;
|
||||
- technicians and users; and
|
||||
- events when event search provides operational value.
|
||||
|
||||
Results should be grouped by domain, show enough context to disambiguate similar
|
||||
identifiers, and support keyboard navigation and selection. A result preview
|
||||
must not reveal restricted data.
|
||||
|
||||
No-results states should repeat the interpreted query, distinguish no match from
|
||||
search failure, and suggest a narrower or alternate identifier without implying
|
||||
the record does not exist outside the user's permissions.
|
||||
|
||||
Recent and saved searches are possible future capabilities. They require clear
|
||||
retention, privacy, and permission behavior before implementation.
|
||||
|
||||
## Mine Map Principles
|
||||
|
||||
The Mine Map should show current spatial state and support drill-down through:
|
||||
|
||||
```text
|
||||
Site -> Room -> Rack -> Shelf or Position -> Miner
|
||||
```
|
||||
|
||||
It should represent both production and operational spaces, including:
|
||||
|
||||
- receiving;
|
||||
- diagnostics;
|
||||
- repair bench;
|
||||
- burn-in;
|
||||
- ready to install;
|
||||
- donor storage;
|
||||
- component storage;
|
||||
- quarantine; and
|
||||
- recycling or retired storage.
|
||||
|
||||
Map interactions should:
|
||||
|
||||
- expose status and future telemetry overlays;
|
||||
- reveal hotspots and concentrations rather than merely place objects;
|
||||
- support filters, single and multi-selection, and clear selection state;
|
||||
- open details in a side panel where space permits;
|
||||
- preserve pan, zoom, filters, and selection while inspecting details;
|
||||
- support site, room, rack, shelf, and miner drill-down; and
|
||||
- distinguish offline, in repair, intentionally curtailed, stale, degraded,
|
||||
unknown, and healthy states.
|
||||
|
||||
Current location foundations do not imply that this full Mine Map experience is
|
||||
complete. Historical map playback is future direction and is not required for
|
||||
an initial Mine Map implementation.
|
||||
|
||||
## Graph And Analytics Principles
|
||||
|
||||
Graphs are first-class operational interfaces, not dashboard decoration. They
|
||||
should support site, room, rack, selected group, and individual-miner scope as
|
||||
data becomes available.
|
||||
|
||||
Relevant measures include:
|
||||
|
||||
- hashrate;
|
||||
- power usage;
|
||||
- efficiency;
|
||||
- temperature;
|
||||
- availability; and
|
||||
- expected versus actual performance.
|
||||
|
||||
Graph interactions should provide:
|
||||
|
||||
- explicit time-range selection and timezone context;
|
||||
- comparison of compatible scopes and units;
|
||||
- synchronized operational-event annotations;
|
||||
- consistent unit formatting and axis semantics;
|
||||
- visible gaps, stale intervals, and missing sources;
|
||||
- aggregation and downsampling disclosure; and
|
||||
- detail values accessible without relying only on pointer hover.
|
||||
|
||||
Never draw misleading interpolation through unknown periods. Clearly label
|
||||
estimated, aggregated, or incomplete values. Graphs explain trends, maps explain
|
||||
location, timelines explain history, and tables explain detail.
|
||||
|
||||
Comparative fleet analytics and synchronized annotations are future capabilities
|
||||
unless a focused implementation task establishes them.
|
||||
|
||||
## Operational Context
|
||||
|
||||
Context panels or inline context may surface:
|
||||
|
||||
- neighboring miners with related faults;
|
||||
- shared PDU or network issues;
|
||||
- nearby temperature anomalies;
|
||||
- similar recent repairs;
|
||||
- component genealogy;
|
||||
- rack-level repair density; and
|
||||
- recent correlated outages.
|
||||
|
||||
Correlations must identify their scope, time window, evidence, and freshness.
|
||||
They may be rule-based and do not require AI. A correlation is supporting
|
||||
context, not proof of cause; the interface must not present it as certainty.
|
||||
Most correlation experiences remain future direction.
|
||||
|
||||
## Tables And Queues
|
||||
|
||||
Operational tables should be dense enough for repeated work while remaining
|
||||
readable. They should provide:
|
||||
|
||||
- a deliberate column hierarchy with identity and status first;
|
||||
- explicit sorting and allowlisted filtering;
|
||||
- discoverable row actions;
|
||||
- predictable single and multi-selection behavior;
|
||||
- preserved filters, sort, selection, and scroll when users inspect and return;
|
||||
- clear empty and no-results states; and
|
||||
- pagination or virtual scrolling for large fleets.
|
||||
|
||||
Keep bulk actions limited to operations with clear scope, authorization,
|
||||
validation, progress, and failure reporting. Selection must never imply that a
|
||||
bulk action is safe.
|
||||
|
||||
Saved views are a future capability. Their later design must define ownership,
|
||||
sharing, permission changes, and behavior when fields become unavailable.
|
||||
|
||||
## Forms And Explicit Commands
|
||||
|
||||
Forms and command dialogs should:
|
||||
|
||||
- use strong persistent labels rather than placeholder-only identification;
|
||||
- group fields by the operator's decision, not database layout;
|
||||
- validate structural input inline and preserve entered data after failure;
|
||||
- explain domain conflicts without exposing database details;
|
||||
- reveal every operational side effect before submission;
|
||||
- derive authoritative actor and timestamps from the session and server;
|
||||
- show only permission-appropriate actions;
|
||||
- explain why a visible control is disabled;
|
||||
- use confirmation only for consequential operations; and
|
||||
- return focus and context predictably after completion.
|
||||
|
||||
Optimistic UI is appropriate only when rollback is safe, obvious, and truthful.
|
||||
Do not optimistically show completion for miner control, repair transitions,
|
||||
component changes, or other multi-record operational workflows before the server
|
||||
confirms success.
|
||||
|
||||
## Timelines And History
|
||||
|
||||
Timelines show immutable chronological history. Each meaningful event should
|
||||
make the following visible when known:
|
||||
|
||||
- actor;
|
||||
- authoritative timestamp;
|
||||
- action;
|
||||
- affected object;
|
||||
- result; and
|
||||
- structured context needed to understand the change.
|
||||
|
||||
Use explicit database sequence when the domain defines one. Events may be grouped
|
||||
for scanning, but grouping must not reorder, merge, or erase facts. Historical
|
||||
events are not edited or deleted. Corrections appear as later correction or void
|
||||
events linked to the original.
|
||||
|
||||
Link directly to related miners, components, repairs, and locations when those
|
||||
records are authorized and available. Timeline filters may reduce the visible
|
||||
set, but the interface must indicate that filtered history exists.
|
||||
|
||||
## Status And Severity Language
|
||||
|
||||
Use stable semantic meanings across screens:
|
||||
|
||||
| Meaning | Use |
|
||||
| --- | --- |
|
||||
| Healthy / active | Operating within expected bounds or available for normal work |
|
||||
| Informational | Context that does not currently require intervention |
|
||||
| Waiting | Work is intentionally blocked on a dependency or next step |
|
||||
| Degraded | Operating outside expected bounds but not at immediate critical severity |
|
||||
| Critical | Immediate attention is required to avoid or address significant impact |
|
||||
| In repair | Removed from normal service under an active repair workflow |
|
||||
| Intentionally offline / curtailed | Not producing by deliberate operational decision |
|
||||
| Stale / unknown | Current truth cannot be established from sufficiently fresh data |
|
||||
| Retired / archived | No longer part of normal active operations but retained historically |
|
||||
|
||||
Domain states and alert severity are separate concepts. For example, `in repair`
|
||||
is not automatically critical, and stale data is not healthy merely because no
|
||||
fault is observed.
|
||||
|
||||
Final colors, typography, icons, patterns, and tokens belong in the future
|
||||
`docs/design/DESIGN_SYSTEM.md`. Every status must use text, icons, or patterns in
|
||||
addition to color.
|
||||
|
||||
## Notifications And Feedback
|
||||
|
||||
Feedback should distinguish:
|
||||
|
||||
- success confirmation;
|
||||
- validation error;
|
||||
- domain or concurrency conflict;
|
||||
- permission denial;
|
||||
- stale-data warning;
|
||||
- backend unavailable state;
|
||||
- background refresh failure;
|
||||
- long-running action progress; and
|
||||
- retryable versus non-retryable failure.
|
||||
|
||||
Success feedback should name the completed action and affected object. Validation
|
||||
feedback stays near the field and is summarized when necessary. Domain conflicts
|
||||
should explain what changed and what the user can do next.
|
||||
|
||||
Critical errors must not disappear on a timer. Long-running operations need
|
||||
progress, cancellation only when supported safely, and a durable final result.
|
||||
Retries must not duplicate non-idempotent commands.
|
||||
|
||||
## Loading, Empty, Error, And Offline States
|
||||
|
||||
Every data surface must distinguish:
|
||||
|
||||
- first load;
|
||||
- background refresh;
|
||||
- partial data;
|
||||
- stale cached data;
|
||||
- no matching results;
|
||||
- an empty new installation;
|
||||
- a permission-restricted section;
|
||||
- API failure;
|
||||
- database unavailable; and
|
||||
- network interruption.
|
||||
|
||||
First load should establish the shell and page context before progressively
|
||||
loading independent data. Background refresh should preserve usable content and
|
||||
show a restrained freshness indicator instead of replacing the page with a
|
||||
spinner.
|
||||
|
||||
Partial or cached data must identify what is missing and when the visible data
|
||||
was last known. “No data” must never be used for a failed request. Offline or
|
||||
interrupted workflows should preserve unsent user input and avoid claiming that
|
||||
an operational command succeeded.
|
||||
|
||||
## Responsive And Mobile UX
|
||||
|
||||
Technicians may use phones or tablets around the mine. Core workflows should
|
||||
provide:
|
||||
|
||||
- large, stable touch targets;
|
||||
- responsive drawers and side panels;
|
||||
- stacked layouts that preserve identity and status;
|
||||
- compact tables that prioritize essential columns and allow deliberate detail
|
||||
expansion;
|
||||
- mobile-first miner lookup and repair actions;
|
||||
- no desktop-only critical workflow; and
|
||||
- graceful recovery on unreliable Wi-Fi.
|
||||
|
||||
Do not shrink a desktop table until it becomes unreadable. Use prioritized
|
||||
columns, row detail, or a task-specific list at narrow widths.
|
||||
|
||||
Barcode and QR scanning are future capabilities. They should accelerate durable
|
||||
identity lookup without creating a competing identity system.
|
||||
|
||||
## Accessibility
|
||||
|
||||
All MinerOps interfaces must provide:
|
||||
|
||||
- complete keyboard navigation;
|
||||
- visible focus indicators;
|
||||
- semantic buttons, links, headings, dialogs, and form controls;
|
||||
- accessible names and screen-reader labels;
|
||||
- sufficient text and non-text contrast;
|
||||
- text, icons, or patterns in addition to color;
|
||||
- reduced-motion support;
|
||||
- accessible table headers, captions, and sort state;
|
||||
- chart summaries and keyboard-accessible data where charts carry meaning;
|
||||
- programmatic association between errors and fields; and
|
||||
- touch targets sized for reliable use in operational environments.
|
||||
|
||||
Focus must move intentionally when dialogs open, close, or report errors. Dynamic
|
||||
updates should announce important changes without flooding assistive technology.
|
||||
|
||||
## Performance And Live Updates
|
||||
|
||||
The expected experience includes:
|
||||
|
||||
- a fast initial shell;
|
||||
- progressive loading of independent data;
|
||||
- near-real-time updates where operational value justifies them;
|
||||
- no avoidable full-page refreshes;
|
||||
- preserved selection, filters, scroll position, and map context;
|
||||
- throttling or aggregation of high-frequency telemetry;
|
||||
- visible last-updated and freshness indicators; and
|
||||
- no layout or notification churn from insignificant changes.
|
||||
|
||||
Prioritize identity, status, freshness, and primary actions before secondary
|
||||
analytics. Live updates must merge safely with user interaction: they cannot
|
||||
clear input, move focus, close a dialog, reorder a selected row unexpectedly, or
|
||||
hide an error.
|
||||
|
||||
Near-real-time delivery mechanisms are an implementation decision. This guide
|
||||
does not require a particular client framework, polling strategy, WebSocket
|
||||
architecture, or state library.
|
||||
|
||||
## Permission-Aware UX
|
||||
|
||||
The UI should hide actions that are irrelevant and unauthorized, or disable them
|
||||
when seeing the action and its denial reason helps the user understand the
|
||||
workflow. A disabled control must explain what permission or state is missing.
|
||||
|
||||
The backend remains the authority for authentication and authorization. UI
|
||||
visibility is not a security boundary.
|
||||
|
||||
Read Only users must have a coherent inspection experience, including search,
|
||||
current state, freshness, and authorized history. Restricted records must not
|
||||
leak through search results, counts, previews, links, notifications, map
|
||||
aggregates, or error wording.
|
||||
|
||||
## Destructive And Irreversible Actions
|
||||
|
||||
Do not physically delete authoritative operational history. Use explicit:
|
||||
|
||||
- retire;
|
||||
- void;
|
||||
- archive; or
|
||||
- correction workflows.
|
||||
|
||||
Before an irreversible or high-impact action, show the affected objects, scope,
|
||||
operational consequences, and whether recovery exists. Use typed confirmation
|
||||
only for genuinely high-risk destructive actions where the additional friction
|
||||
meaningfully prevents mistakes.
|
||||
|
||||
Confirmation labels must name the command, such as “Void repair-part entry” or
|
||||
“Retire miner,” rather than “Confirm” or “Yes.” Never use an ambiguous dialog to
|
||||
mask an action's side effects.
|
||||
|
||||
## Design Documentation Structure
|
||||
|
||||
This guide governs shared experience principles. Future focused documents may
|
||||
define detailed behavior:
|
||||
|
||||
- `docs/design/DESIGN_SYSTEM.md`;
|
||||
- `docs/design/NAVIGATION.md`;
|
||||
- `docs/design/DASHBOARD.md`;
|
||||
- `docs/design/MINE_MAP.md`;
|
||||
- `docs/design/ANALYTICS.md`;
|
||||
- `docs/design/REPAIR_CENTER.md`;
|
||||
- `docs/design/MINER_DETAIL.md`;
|
||||
- `docs/design/COMPONENT_DETAIL.md`;
|
||||
- `docs/design/SEARCH.md`;
|
||||
- `docs/design/USER_WORKFLOWS.md`; and
|
||||
- `docs/design/OPERATIONAL_CONTEXT.md`.
|
||||
|
||||
These paths are planned documentation, not claims that the files or corresponding
|
||||
screens exist. Focused documents may add screen-specific requirements but must
|
||||
not weaken this baseline without a deliberate documented decision.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
A compliant MinerOps screen:
|
||||
|
||||
1. makes current status and scope clear;
|
||||
2. exposes data freshness and uncertainty;
|
||||
3. presents role- and permission-aware actions;
|
||||
4. preserves context during navigation and inspection;
|
||||
5. uses explicit commands for meaningful operational changes;
|
||||
6. keeps authoritative history and later corrections visible;
|
||||
7. handles loading, empty, partial, error, offline, and permission states;
|
||||
8. is keyboard accessible and uses semantic controls;
|
||||
9. remains usable at mobile widths and with touch input;
|
||||
10. does not imply certainty when data is stale, missing, or incomplete; and
|
||||
11. uses maps, graphs, timelines, and tables according to their proper roles.
|
||||
|
||||
## Final Principle
|
||||
|
||||
The interface should help users move from observation to understanding to action with the least possible friction, while preserving operational truth.
|
||||
Reference in new issue
Block a user