diff --git a/docs/design/UX_UI_GUIDE.md b/docs/design/UX_UI_GUIDE.md
new file mode 100644
index 0000000..29e73c9
--- /dev/null
+++ b/docs/design/UX_UI_GUIDE.md
@@ -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.