ITWorx-Pulse-Public/docs/engineering/FRONTEND_STANDARDS.md

Frontend standards

Architecture

Recommended modules:

app-shell
auth
routing
i18n
design-system
dashboards
widgets
metrics
inventory
alerts
incidents
events
settings
operations

Feature modules own routes, queries, views and tests. Shared UI remains domain-neutral.

State

• URL state for shareable filters/time range when appropriate.
• Server state via TanStack Query or measured equivalent.
• Editor draft state isolated from saved dashboard state.
• WebSocket subscriptions managed by one client/service.
• Chart samples in bounded local stores/ring buffers.
• Avoid duplicating server state across stores.

Dashboard editor

• Save complete version atomically.
• Use explicit edit session/draft.
• Detect optimistic concurrency conflict.
• Undo/redo operates on normalized editor commands or bounded snapshots.
• Breakpoint layouts validated before save.
• Keyboard move/resize and screen-reader labels.
• Prevent accidental drag from chart interactions.

Charts

• Lazy-load heavy chart implementations.
• Initialize history once per query.
• Append live data efficiently.
• Cap points/series.
• Dispose observers/listeners/instances.
• Pause offscreen/background work.
• Provide textual summary/table alternative.
• Use consistent units, timestamps, legend and tooltip behavior.
• Status thresholds do not overwrite data meaning.

Tables/lists

• Cursor/server pagination for large datasets.
• Virtualization for large rendered collections.
• Stable row keys.
• Accessible sorting/filtering labels.
• Preserve filter state sensibly.
• Loading and empty states are distinct.

Error handling

• Route-level boundary.
• Component/query errors show safe, actionable messages.
• Correlation ID exposed for diagnostics.
• Retry only when safe and bounded.
• Authentication expiry has a clean flow.
• Partial datasource failure does not blank the entire app.

Styling

• Use design tokens; no scattered literal colors/spacing.
• Consistent card padding and grid gaps.
• Limited elevation.
• Status colors only for status.
• Respect reduced motion.
• Avoid oversized decorative headers that reduce information space.
• Desktop and mobile screenshots/visual regression for key routes.

Testing

• Unit tests for formatting/transforms/editor reducers.
• Component tests for states and accessibility.
• Playwright for user journeys.
• Axe or equivalent on all core routes and viewports.
• Real browser verification for drag/resize, WebSocket reconnect and wallboard.
• Leak/soak instrumentation for chart/subscription lifecycle.