# UI / UX Specification
## SOP Governance Tool — Stage 1

## 1. Design Principles

1. **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.
2. **Boring and consistent beats clever.** shadcn/ui defaults, one accent color, no animation beyond built-ins.
3. **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.