6.2 KiB
UI / UX Specification
SOP Governance Tool — Stage 1
1. Design Principles
- Two very different audiences: Admin/Editor screens are information-dense desktop tools; Staff screens are huge-tap-target mobile pages usable by a warehouse worker in gloves, in a second language. Never compromise the Staff side for the Admin side.
- Boring and consistent beats clever. shadcn/ui defaults, one accent color, no animation beyond built-ins.
- Status is always visible. Every SOP shows a colored status badge everywhere it appears.
2. Design Tokens
- Accent/primary: teal
#028090· success#02C39A· warning#E0A100· danger#C0392B - Neutrals: slate scale; background
#F7FAF9; card white - Font: system UI stack (no webfont — fast on cheap phones)
- Status badges: draft = slate, submitted = amber, approved = blue, published = teal, archived = grey, review-overdue = red outline
- Staff screens: base font 18px, step text 20px, buttons ≥ 56px tall, single column
3. Navigation Map
Login
├─ ADMIN/EDITOR/APPROVER (desktop shell: sidebar + topbar)
│ ├─ Dashboard (admin, approver)
│ ├─ SOPs (list) ─ SOP detail ─ Edit draft
│ ├─ Approvals queue (approver, admin)
│ ├─ Incidents (approver, admin)
│ ├─ Users & Departments (admin)
│ └─ Audit log (admin, approver)
└─ STAFF (mobile shell: just a header + list)
├─ My SOPs (+ Report incident)
└─ SOP viewer (+ acknowledge, + Report a problem)
After login, route by role: staff → /my-sops, others → /dashboard.
4. Screen Specs
4.1 Login
Centered card: email, password, sign-in. Error inline. Company name/logo above.
4.2 Dashboard (admin/approver)
Top row of 4 stat cards: Published · Drafts · Pending approval · Review overdue (red if >0). Then "Acknowledgement by SOP" table: code, title, dept, version, progress bar with %, outstanding count, row click → SOP detail. Department filter dropdown. Second small table: department overall %.
4.3 SOP List
Toolbar: search (code/title), filters (status, department, category), "New SOP" (editor+). Table rows: code · title · dept · status badge · version · owner · updated. Row → detail.
4.4 SOP Detail
Header: code, title, status badge, version, owner, review date (red if overdue). Action buttons by role/status: Edit draft · Submit · Approve/Reject (opens comment dialog) · Publish (dialog: change note + "major revision" checkbox) · Assign departments (multi-select dialog) · Translate (language checkboxes) · Copy staff link. Tabs: Content (rendered read-only sections) · Versions (list; click renders frozen snapshot) · Acknowledgements (the FR-4 report + CSV button) · Translations (per language: machine/reviewed chip, preview, "Mark reviewed") · Incidents (linked incident list, FR-7.4) · History (audit entries for this SOP).
4.5 SOP Editor (draft)
Left: section list with completeness ticks. Main: one section at a time. Procedure section: ordered step cards — textarea + photo upload + drag handle + delete; "Add step". Top bar: autosave indicator ("Saved 10:32"), AI Draft button, Submit for approval. AI Draft modal: big textarea "Describe the process in your own words", optional "Paste any existing notes", Generate → spinner → "Draft ready — review each section" fills the editor with unsaved changes highlighted. Nothing is saved until the user saves.
4.6 Approvals Queue
List of submitted SOPs: code, title, submitted by/when. Open → read-only content + Approve / Reject (comment required on reject).
4.7 My SOPs (STAFF, mobile)
Header: company name + user name + language switcher (EN | BM | 中文). Section "Needs your acknowledgement" (amber cards) then "Acknowledged" (teal tick cards). Card: title, code, version, dept. Tap → viewer.
4.8 SOP Viewer (STAFF, mobile)
Title + version + language switcher. Sections in reading order; steps as numbered cards with photo above text. Sticky bottom bar:
- Not yet acknowledged → button "I have read and agree" (label in current language) → confirm sheet: "Type your full name to sign" + input + Confirm → success screen with tick, timestamp, version.
- Acknowledged → grey bar "Acknowledged v1.2 · 01 Jul 2026". If viewing a translation where safety section is unreviewed → safety section shows English with a small note "English shown pending translation review".
4.9 Incidents (approver/admin)
List with filters (status, severity, department, SOP): date · reporter · dept · SOP code · severity chip (grey/amber/red) · status chip. Row → detail: full description, photo, linked SOP version, timeline. Actions: "Mark reviewed" · "Close" (dialog: optional resolution note + checkbox "This requires an SOP revision" → on save jumps to that SOP's editor). Dashboard gains an "Open incidents" card (red when any open high-severity).
Staff report flow (mobile): "Report a problem" link at the bottom of the SOP viewer (pre-links SOP + version) and a button on My SOPs (no SOP link). One screen: description textarea, severity selector (three big buttons), optional photo, Submit → success tick. Labels tri-lingual via lib/i18n.ts.
4.10 Users & Departments (admin)
Two tabs. Users table: name, email, role (inline select), department, language, active toggle, "Invite user" dialog. Departments: simple list + add/rename.
4.11 Audit Log (admin/approver)
Filter by SOP / action / date. Table: time · actor · action · entity · detail summary. Export CSV.
5. Empty / Error / Loading States
Every list has an empty state with the primary action ("No SOPs yet — create your first one" / "Nothing to approve 🎉"). Mutations show button spinners; failures show a toast with the server message and never lose form input. AI failures keep the description text in the modal with a Retry button.
6. Accessibility & Language Notes
Staff-facing static labels (buttons, headers on staff screens) are tri-lingual via a tiny dictionary file (lib/i18n.ts) keyed by preferred_language — do NOT pull in a heavy i18n framework. Admin screens stay English. Contrast AA minimum; all tap targets ≥ 44px; photos get alt text from step text.