minerops/docs/design/UX_UI_GUIDE.md

# 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.