Add spec pack
This commit is contained in:
Weei Han
@@ -0,0 +1,87 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user