UI and Design Parity: Desktop vs ehr-web
Version: 1.1
Date: 2026-04-18
Companion: ../../common/THEME.md (canonical theme source — all surfaces), SPEC.md, REGIONAL_PROFILE.md, FRONTEND_BERRY_TEMPLATE_REFERENCE.md
Canonical theme source:
../../common/THEME.mdis the single source of truth for tokens, theming, admin-configurable per-tenant overrides, motion, and RTL across desktop, web, and mobile. This document translates the common theme rules into desktop-specific guidance and tracks parity withehr-web. Any discrepancy between this file and the common theme doc is resolved in favour of the common doc.
1. Goals
- Visual and interaction consistency between the Electron desktop client and
apps/ehr-web, both built on the single base theme (../../common/THEME.md). - Compliance with the Berry (CodedThemes) template obligation for product portals (see docs/widget/BERRY_TEMPLATE_REQUIREMENT.md), layered on top of the token system.
- Reuse of shared packages already consumed by
ehr-web:@ghasi/design-tokens,@ghasi/theme-runtime,@ghasi/design-system,@ghasi/widgets,@ghasi/access-client-browser,@ghasi/auth-client,@ghasi/ui-config-client-browser(where applicable to desktop).
2. Stack alignment
Defined in full in ../../common/THEME.md §3. Desktop-specific notes:
| Layer | Requirement |
|---|---|
| Component foundation | MUI (major version aligned with ehr-web package.json) — foundation and complex components (DataGrid, Autocomplete, DatePicker, dialogs, dense tables). |
| Styling primary | Tailwind CSS — utility classes for layout, spacing, simple colour and typography. MUI Preflight conflict avoided per ../../common/THEME.md §6.3 and §7.2 (Preflight disabled; MUI CssBaseline is the reset). |
| Styling escape hatch | MUI sx / styled (Emotion) — only for complex or dynamic cases Tailwind cannot express cleanly. |
| Tokens & theming | @ghasi/design-tokens + @ghasi/theme-runtime — generates MUI theme, Tailwind preset, CSS variables, and Motion tokens from one source. Per-tenant overrides per ../../common/THEME.md §5. |
| Icons | @ghasi/icons-react (shared with web) — built from the shared SVG source with RTL-mirror metadata per ../../common/THEME.md §11. |
| Animation | Motion (motion.dev) — consumes duration and easing tokens from @ghasi/design-tokens/build/motion-tokens. Shared presets (fadeIn, slideInFromStart, scaleIn, cardHover, toastEnter) per ../../common/THEME.md §8.3. Reduced-motion honoured automatically. |
| Forms | react-hook-form + zod preferred; formik + yup permitted where web feature already uses it. |
| i18n | react-intl + shared message catalogs from @ghasi/i18n. |
| RTL | Theme direction + stylis-plugin-rtl + Tailwind logical utilities (ps-*, pe-*, start-*, end-*). ESLint rule blocks physical left/right utilities. |
3. Theme parity strategy
Approach A is adopted. Theme construction lives in shared workspace packages consumed by both ehr-web and ehr-desktop (and the future public-health / government web surfaces and the mobile app where applicable):
@ghasi/design-tokens— tokens + generated artefacts (MUI theme, Tailwind preset, CSS variables, Motion tokens). See../../common/THEME.md§13.@ghasi/theme-runtime—ThemeProvider,useTenantTheme, tenant override application, motion presets.
Legacy ehr-web construction under apps/ehr-web/src/themes/ is migrated to the shared packages; any residual local palette/typography files are considered historical and must not fork.
Desktop MUST:
- Use
CssVarsProviderfrom MUI withcssVarPrefix: ''matchingehr-webso CSS variable names are identical across web + desktop. - Consume CSS variables for all colour / radius / spacing references so tenant overrides swap live without app restart (see
../../common/THEME.md§5.6). - Apply the tenant's
densitypreference (compact/comfortable/spacious) from the resolved theme — Berry-style dense clinical layouts map tocompact. - Respect the locked token surface per
../../common/THEME.md§5.2 — status colours, focus ring, spacing scale, and motion tokens are not tenant-overridable.
4. Localization, RTL, and mixed-direction content
Authority: REGIONAL_PROFILE.md, MODULE_SHARED_STANDARDS.md §4. Goal: identical visual and semantic behavior to apps/ehr-web for the same locale + direction — no desktop-specific regressions.
4.1 Layout and direction
| Check | Requirement |
|---|---|
| Theme | MUI direction matches ltr / rtl; use same ThemeProvider / StyledEngineProvider ordering as ehr-web. |
| Document | Root dir and lang updated when user or tenant changes locale. |
| Navigation | Drawer vs side nav, start/end edge alignment (use logical CSS / MUI props; avoid hard-coded left/right except where mirrored by RTL plugin). |
| Icons | Mirror directional icons (e.g. back, chevrons) in RTL; do not mirror symmetric or semantic icons (e.g. warning, clinical) without design review. |
4.2 Typography and data
| Check | Requirement |
|---|---|
| Mixed-direction | MRNs, codes, mixed Latin/Arabic strings: <bdi>, dir="auto", or Unicode isolates per MODULE_SHARED_STANDARDS.md. |
| Tables | Horizontal scroll and sticky columns behave correctly in RTL (first column alignment, action columns). |
| DataGrid / dense tables | Verify MUI X DataGrid RTL support with same major version as web. |
4.3 Dates, numbers, calendars
| Check | Requirement |
|---|---|
| Formatting | dayjs + locale plugins; currency and units per regional profile. |
| Pickers | @mui/x-date-pickers with locale props; Hijri/Gregorian display rules per REGIONAL_PROFILE.md. |
4.4 Electron-specific
| Check | Requirement |
|---|---|
| Native menus | Localized File / Edit / View strings aligned with TR-DSK-073 (TECHNICAL_REQUIREMENTS.md). |
| Shell | Window title bar may reflect OS; in-app chrome must still honor RTL. |
4.5 Verification
- Visual: side-by-side screenshots (web vs desktop) for at least en and one RTL locale on the shell + one chart surface.
- Automated: see TR-DSK-075 / TR-DSK-063 in TECHNICAL_REQUIREMENTS.md.
5. Design system and Cursor rules
- Follow FRONTEND_BERRY_TEMPLATE_REFERENCE.md for where Berry requirements live in-repo.
- Cursor rule:
.cursor/rules/berry-template-requirement.mdapplies to portal UI; treat desktop EHR as the same product family.
6. Offline and sync UX patterns
Aligned with offline-first/SPEC.md and SPEC.md:
| Pattern | Requirement |
|---|---|
| Global status | Persistent bar or shell indicator: offline / reconnecting / syncing / idle / error. |
| Per-record state | Badges for “Pending sync”, “Conflict”, “Synced” on lists and detail headers where applicable. |
| Conflict | Modal or side panel with plain-language explanation, server code, and actions (refresh, merge, defer) per module. |
| Queue depth | Optional “N items pending” in shell for power users; avoid alarmist copy for normal operation. |
| Online-only | Disabled control + tooltip or inline help (“Requires internet”) — consistent string keys with web where shared. |
7. Accessibility and clinical safety
- Maintain focus order, keyboard navigation, and contrast consistent with MUI defaults and Berry overrides.
- Never rely on color alone for sync/error states; pair with icon + text.
- High-density clinical screens: follow
ehr-webpatterns for scroll regions (simplebar-reactif used on web for comparable shells).
8. Scheduling UI and notifications (parity)
When the scheduling module is licensed (see FR-DSK-015 and FR-DSK-016 in SPEC.md):
| Topic | Requirement |
|---|---|
| Rich UI | Calendar views, agenda, resource/slot grids, filters — reuse Berry + MUI patterns from ehr-web and @ghasi/widgets where applicable; same density and card patterns as other clinical modules. |
| RTL | Timeline and calendar horizontal axis MUST mirror correctly (start of day at the logical start edge). |
| Notifications | Use OS Notification API from main when user grants permission; fallback to in-app toast/snackbar; respect Do Not Disturb where OS exposes it. |
| Offline | Show cached appointments and clearly label stale data; queue booking intents per module offline rules — never imply a confirmed slot without server confirmation. |
Module spec: specs/modules/scheduling/SPEC.md.
9. Platform-specific allowances
Small divergences are acceptable when they improve desktop UX:
- Native menus (File, Edit, View) in main process.
- Window chrome and title bar (OS-specific).
- Keyboard shortcuts may include desktop conventions (Ctrl/Cmd+W) where they do not conflict with clinical safety.
Document any intentional deviation in the desktop app README.