ITWorx-Pulse-Public/docs/product/UX_SPEC.md

# UX specification

## 1. Experience principles

- **Explain before exposing raw detail.**
- **Dense, not cramped.**
- **Live, not distracting.**
- **Configurable, not chaotic.**
- **Safe, not action-heavy.**
- **Unknown is visible.**
- **Desktop, mobile and wallboard are designed separately.**

## 2. Information architecture

```text
Overview
Dashboards

Infrastructure
  Host
  Hardware
  Storage
  Network
  UPS

Containers
Applications
Services

Alerts
Incidents
Events

Explore
  Metrics
  Compare
  History

Wallboards

Settings
  Data sources
  Discovery
  Alerting
  Notifications
  Retention
  Users & access
  Backups
  System
```

Navigation may collapse responsively. Route names and labels are localized.

## 3. Global shell

### Header

- current server/environment;
- global time range;
- live/pause control;
- refresh/freshness state;
- active filters;
- alert count;
- user menu.

### Source freshness

A compact indicator exposes:

- healthy;
- delayed;
- stale;
- unavailable.

Opening it lists each datasource and last successful sample.

### Global time control

Presets:

- Live;
- 15 minutes;
- 1 hour;
- 6 hours;
- 24 hours;
- 7 days;
- 30 days;
- custom.

A widget may override the dashboard range, but the override is clearly indicated.

## 4. Overview

### Healthy state

Prioritize trends, capacity and service summary.

### Degraded state

A problem summary appears before normal cards:

```text
Degraded
Cachepool is 91% full.
Plex restarted 4 times in 10 minutes.
Prometheus storage metrics are 3 minutes stale.
```

Each reason links to its entity and relevant timeframe.

### Layout

The system template must remain useful before any editing:

- status summary;
- active incidents;
- CPU/load;
- memory;
- array/pools;
- network;
- container/application state;
- service matrix;
- recent events.

## 5. Dashboard composer

### Modes

**View mode**
- no drag handles;
- widgets fixed;
- normal chart interactions;
- fast rendering.

**Edit mode**
- visible grid and selection outlines;
- drag/resize handles;
- widget library;
- undo/redo;
- save/exit;
- breakpoint preview.

Unsaved changes are clearly indicated. Navigation away prompts only when changes would be lost.

### Grid

Recommended logical columns:

- large desktop/wallboard: 24;
- desktop: 18;
- tablet: 8;
- mobile: 1.

Widgets define minimum and preferred sizes. Collision handling and snapping are predictable.

### Widget configuration drawer

Tabs:

1. Data
2. Visualization
3. Thresholds
4. Behavior
5. Links
6. Advanced

Changes preview live but persist only through the editor save transaction.

### Editing interactions

- keyboard move/resize alternative;
- duplicate;
- lock/unlock;
- hide per viewport;
- copy to another dashboard;
- reset to template;
- restore version;
- inspect validation errors before save.

## 6. Entity pages

Common structure:

1. identity, status and reason;
2. key values and freshness;
3. primary charts;
4. relationships/dependencies;
5. events;
6. alerts/incidents;
7. technical metadata.

Deep technical payloads are collapsed by default.

## 7. Alerts and incidents

### Alert list

Supports filters for:
- state;
- severity;
- entity;
- source;
- acknowledged;
- maintenance;
- time.

Each row shows:
- concise rule name;
- affected entity;
- current value/reason;
- duration;
- state;
- incident relationship.

### Incident page

- plain-language summary;
- severity and lifecycle;
- affected entities;
- contributing alerts;
- timeline;
- selected charts;
- acknowledgement/notes;
- uncertain relationship labels;
- external workflow link when configured.

## 8. Mobile

Primary mobile navigation:

- Overview;
- Incidents;
- Containers;
- Storage;
- Services;
- More.

Mobile priorities:
- global status;
- active incident;
- acknowledgement;
- essential entity facts;
- readable charts with reduced series;
- touch-sized controls.

Dashboard editing on mobile:
- reorder;
- show/hide;
- simple config;
- no precision freeform grid placement.

## 9. Wallboard

- fullscreen;
- no standard navigation;
- large readable status;
- page rotation;
- reconnect indicator;
- last update/freshness;
- optional kiosk-safe token/session;
- no edit controls;
- subtle movement strategy to reduce static burn-in risk;
- survives days without reload.

## 10. Loading, empty and failure states

Every data surface defines:

- initial loading;
- incremental live update;
- empty because no entities exist;
- empty because filters exclude all;
- stale;
- unavailable;
- unauthorized;
- query limit exceeded;
- partial data.

Skeletons must not imply exact values. Previous values may remain visible only with an explicit stale age.

## 11. Copy

Default user-facing copy is natural Dutch:

Good:
- `Geen recente gegevens`
- `Container herstart herhaaldelijk`
- `Cachepool bijna vol`
- `Laatst succesvol bijgewerkt om 13:42`

Avoid:
- raw metric names;
- unexplained `NaN`;
- only `Error 500`;
- invented root-cause certainty;
- alarmist language for attention-level conditions.

## 12. Accessibility

- WCAG 2.2 AA target for core workflows.
- Full keyboard navigation.
- Visible focus.
- Text/icon plus color for status.
- Reduced-motion support.
- Charts have accessible summaries/table alternatives.
- Drag interactions have non-pointer alternatives.
- Contrast is validated in all themes/states.
- Live regions announce important state changes without constant noise.