docs: add UX and UI guide

2026-08-02 22:15:51 +00:00
1 parent 39832fcf80
commit 4656714837
@@ -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.