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

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:

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.