# SupaHR Brand Design System Guide
**Version:** 2.0.0  
**Status:** Canonical Reference  
**Philosophy:** Engineered for 24/7 Afrikan Business & Healthcare  

---

## 1. Executive Summary & Brand Positioning

SupaHR is the mission-critical workforce and duty-scheduling operating system designed for **Afrikan businesses with complex, round-the-clock shift patterns**. 

While our heritage and marquee product is rooted in high-acuity **clinical healthcare** (managing doctor-to-patient ratios, doctor fatigue, locum pools, and ICU skill mix), the platform natively supports all intensive 24/7 industries across the continent:
- **Acute Healthcare & Tertiary Hospitals** (emergency departments, surgical theatres, pediatric wards, maternal care)
- **24/7 Private Security & Guarding Firms** (patrol rotations, guard relief, post coverage, armed response teams)
- **Continuous Manufacturing & Industrial Plants** (day/night production rotations, machinery operators, safety supervisors)
- **Hospitality & Hotel Chains** (concierge, front desk shifts, kitchen brigades, night auditors)
- **Logistics, Haulage & Fleet Dispatch Hubs** (driver turnaround rest, long-distance relay schedules, warehouse pickers)
- **Retail & Quick Service Chains** (multi-branch cashier scheduling, peak-hour staffing, holiday rosters)

Our design system is grounded in **Empirical Color Psychology** and **Gestalt Visual Principles**. It eliminates the visual clutter and alert fatigue typical of legacy enterprise software, creating an interface that is calming during high-stress night shifts and razor-sharp during month-end payroll execution.

---

## 2. Empirical Color Psychology

High-stress shift environments (e.g. hospital wards at 03:00 AM, security control rooms during power outages, or payroll cut-off on the 24th) magnify visual exhaustion. SupaHR deliberately avoids harsh stark contrasts, jarring blues, and excessive medical reds.

### 2.1 The 60-30-10 Color Architecture

| Layer | Proportion | Token | Hex Code | Psychological Rationale |
| :--- | :--- | :--- | :--- | :--- |
| **Surface Canvas** | 60% | `--surface-canvas` | `#F8FAFC` | Airy, modern Scandinavian clean canvas. Eliminates claustrophobia and digital glare under fluorescent lighting. |
| **Card / Surface Container** | -- | `--surface-card` | `#FFFFFF` | Crisp, hygienic backdrop that provides immediate figure-ground separation for data tiles. |
| **Primary Brand** | 30% | `--brand-primary` | `#059669` | **Clinical Emerald**: Symbolizes physiological restoration, institutional stability, algorithmic accuracy, and financial prosperity. |
| **Executive Slate** | Text/Nav | `--slate-dark` | `#0F172A` | Deep charcoal with oceanic depth. Delivers AAA contrast (> 7.5:1) without the harshness of pure `#000000`. |
| **Muted Slate** | Secondary | `--slate-muted` | `#64748B` | High legibility for timestamps, secondary badges, and inactive shift slots without competing with focal actions. |
| **Vital Alert** | 10% (Focal) | `--amber-alert` | `#F59E0B` | **Vital Amber**: Prompts swift administrative attention (fatigue approaching, seat capacity at 100%, P10 tax deadline) without triggering crisis panic. |
| **Critical Hazard** | Reserved | `--rose-critical` | `#E11D48` | **Crimson Alert**: Strictly reserved for illegal shift violations (< 11h turnaround, ICU without senior consultant, failed bank disburse). |

### 2.2 Functional Swatch Matrix

```css
:root {
  /* Brand Tokens */
  --primary: #059669;
  --primary-light: #D1FAE5;
  --primary-dark: #065F46;
  --primary-container: rgba(5, 150, 105, 0.12);

  /* Neutrals */
  --slate-dark: #0F172A;
  --slate-body: #1E293B;
  --slate-muted: #64748B;
  --outline-variant: #E2E8F0;
  --surface-canvas: #F8FAFC;
  --surface-card: #FFFFFF;
  --surface-container: #F1F5F9;

  /* Alert States */
  --amber-alert: #F59E0B;
  --amber-light: #FEF3C7;
  --amber-dark: #B45309;

  --rose-critical: #E11D48;
  --rose-light: #FFE4E6;
  --rose-dark: #9F1239;
}
```

---

## 3. Gestalt Design Principles

Every screen in SupaHR is constructed according to fundamental Gestalt perceptual laws:

### 3.1 Law of Proximity
- Related data items are clustered tightly using **8px (`space-sm`)** and **16px (`space-md`)** spacing.
- Clinician names, regulatory PINs, and ward badges form a single cohesive micro-unit before separated by **24px (`space-lg`)** column gutters.
- On mobile devices, related metrics (e.g., Gross Pay + Net Pay) live in a single unified card rather than dispersed rows.

### 3.2 Law of Similarity
- Identical visual patterns communicate identical functional categories:
  - **Morning Shift (07:00 - 15:00)**: Soft Emerald pill (`bg-emerald-50 text-emerald-800 border-emerald-200`)
  - **Evening Shift (14:00 - 22:00)**: Soft Teal pill (`bg-teal-50 text-teal-800 border-teal-200`)
  - **Night Shift (21:00 - 08:00)**: Deep Indigo pill (`bg-indigo-50 text-indigo-800 border-indigo-200`)
  - **On-Call / Standby**: Amber dashed pill (`border-dashed border-amber-400 text-amber-800`)
  - **Rest Day / Off**: Muted Slate (`bg-slate-100 text-slate-600`)

### 3.3 Law of Continuity
- Roster duty schedules and payroll disbursement pipelines flow chronologically from left to right.
- In mobile viewports, step flows (Onboarding -> Verification -> Roster Setup -> Go Live) are connected by directional progression ribbons.

### 3.4 Law of Closure
- Unassigned shift slots and vacant seat licenses utilize dashed borders (`border-2 border-dashed border-amber-300`).
- The human eye perceives this as an "incomplete whole", instinctively compelling the roster manager to assign staff or purchase required seats.

### 3.5 Law of Figure-Ground
- High-priority workflows (e.g. **Emergency Broadcast**, **1-Tap M-PESA Disbursement**, **Seat Capacity Upgrade**) visually elevate above the canvas using Level 2 / Level 3 shadows.
- Modals, action sheets, and mobile drawers use backdrop blurs (`backdrop-blur-md bg-slate-900/50`) to demote background clutter.

### 3.6 Law of Focal Point
- Every viewport features exactly **one dominant primary CTA** (e.g. "Execute Bulk B2C Run" or "Procure Additional Seats").
- Secondary choices use quiet outline or subtle container styling to prevent decision paralysis.

### 3.7 Law of Common Region
- Bento cards and tabular segments are bounded by unified subtle outlines (`border border-slate-200`) and rounded radii (`border-radius: 12px / 16px`), signaling that all enclosed data belongs to the same clinical or financial entity.

### 3.8 Law of Prägnanz (Simplicity & Conciseness)
- Complex operational states (such as a 150-clinician ward shift matrix or multi-tiered PAYE tax calculations) are visually distilled into the simplest, most immediately recognizable form.
- The UI eliminates redundant visual artifacts, unnecessary decorative borders, and non-essential text labels, allowing fatigued night-shift supervisors or emergency dispatchers to instantly grasp organizational health at a glance (e.g. green pulse for normal operation, amber for capacity threshold, crimson for immediate safety breach).
- Progressive disclosure is strictly utilized: primary metrics (Available Seats, Net Pay, On-Duty Count) are displayed upfront, while granular breakdowns (tax tiers, shift log history) expand on demand.

---

## 4. Typography Architecture & Token Hierarchy

We employ a 3-tier font strategy balancing authority, density, and arithmetic precision:

1. **Headlines & Display:** **Plus Jakarta Sans** (Weights: 600, 700, 800)  
   - Modern, geometric, authoritative. Delivers institutional confidence for enterprise hospital boards and executive directors.
2. **Body & Interface Text:** **Inter** (Weights: 400, 500, 600)  
   - Maximum micro-reading density and optical legibility in complex shift matrices and multi-line payroll breakdowns.
3. **Numeric & Currency:** **JetBrains Mono** (Weights: 500, 700)  
   - Monospaced tabular alignment eliminates vertical jitter when comparing KES payroll line items, time spans (e.g., `14:00 - 22:00`), and KRA/KMPDC PINs.

### 4.1 Type Scale Specification

| Token | Size | Weight | Line Height | Mobile (320px - 375px) | Usage |
| :--- | :--- | :--- | :--- | :--- | :--- |
| `display-lg` | 48px | 800 | 56px | 32px / 40px | Homepage Hero Display |
| `headline-xl`| 36px | 800 | 44px | 28px / 36px | Page Titles, Key Milestones |
| `headline-lg`| 28px | 700 | 36px | 22px / 28px | Bento Card Headers |
| `headline-md`| 20px | 600 | 28px | 18px / 24px | Section Sub-headers |
| `body-lg`    | 16px | 500 | 24px | 15px / 22px | Lead Paragraphs |
| `body-md`    | 14px | 400 | 20px | 13px / 18px | Standard Body, Table Cells |
| `body-sm`    | 12px | 400 | 16px | 11px / 15px | Helper Text, Timestamps |
| `mono-stat`  | 24px | 700 | 32px | 20px / 26px | KES Currencies & Counts |
| `label-caps` | 11px | 700 | 14px | 10px / 12px | All-caps Field Identifiers |

---

## 5. Elevation, Layering & Depth

Depth in SupaHR is architectural and functional, avoiding decorative noise:

```css
/* Elevation Levels */
--shadow-0: none;
--shadow-1: 0 1px 3px 0 rgba(15, 23, 42, 0.05), 0 1px 2px -1px rgba(15, 23, 42, 0.05);
--shadow-2: 0 4px 6px -1px rgba(15, 23, 42, 0.08), 0 2px 4px -2px rgba(15, 23, 42, 0.05);
--shadow-3: 0 10px 15px -3px rgba(15, 23, 42, 0.10), 0 4px 6px -4px rgba(15, 23, 42, 0.08);
--shadow-focus: 0 0 0 3px rgba(5, 150, 105, 0.25);
```

- **Level 0 (Flat Canvas):** Page background (`#F8FAFC`).
- **Level 1 (Card Baseline):** Data tiles, table rows, and secondary widgets with `1px` subtle border.
- **Level 2 (Active Interactive):** Hovered cards, dropdown menus, and sticky top headers.
- **Level 3 (Modal / Bottom Sheet):** Emergency call-out drawers, seat procurement modals, and 1-Tap M-PESA confirmations.

---

## 6. Component Specifications

### 6.1 Touch Targets & Mobile Ergonomics
All interactive controls (buttons, links, select menus, accordion headers) enforce a **strict minimum 48px × 48px touch bounding box** on mobile devices.

### 6.2 Buttons
- **Primary CTA:** Solid Emerald (`#059669`), white text, rounded-lg (`8px`), 12px × 24px padding. Hover: `#065F46`. Active: 0.98 scale.
- **Outline / Secondary:** Transparent background, 1.5px Slate-200 border, Slate-900 text. Hover: `#F1F5F9`.
- **Alert / Accent:** Solid Amber (`#F59E0B`), white text, for seat warnings and urgent shift bids.
- **Emergency Button:** High-contrast crimson or ruby highlight for critical broadcast call-ins.

### 6.3 Bento Grid Layouts
- **Desktop (1024px+):** 3-column or 4-column asymmetric grid showcasing quota metering (span 2), compliance standing (span 1), and live shift headcount.
- **Tablet (768px):** 2-column balanced grid.
- **Mobile (320px - 375px):** 1-column vertically stacked tactile cards with `gap-4`.

### 6.4 Data Tables vs. Mobile Responsive Cards
- On viewports **>= 768px**, full tabular views are used with subtle zebra striping, sticky headers, and monospaced numeric columns.
- On viewports **< 768px**, tables automatically transform into **Touch-Friendly Profile Cards** containing:
  - Doctor / Staff avatar + name + registration PIN.
  - Department badge & assigned role.
  - Net Pay (KES) in bold JetBrains Mono.
  - One-tap status badge ("Disbursed" / "Pending Auth").
  - Direct action trigger ("Receipt" / "Authorize").

### 6.5 Persistent Mobile Navigation (Bottom App Bar)
For mobile administrators reviewing hospital operations or guarding rotas on the go:
- Height: `64px + env(safe-area-inset-bottom)`.
- 5 thumb-zone destinations:
  1. **Dashboard** (Icon: `dashboard` or `hub`)
  2. **Rosters** (Icon: `calendar_month`)
  3. **Payroll** (Icon: `payments`)
  4. **Seats & Org** (Icon: `event_seat`)
  5. **More** (Icon: `menu`)

---

## 7. Responsive Viewport Specifications

| Viewport Category | Width Range | Container Padding | Grid Behavior | Key Adaptations |
| :--- | :--- | :--- | :--- | :--- |
| **Small Mobile (Ultra Compact)** | 320px - 374px | `16px` | 1 Column | iPhone SE / small Androids. Minmax uses `min(100%, 260px)`. Font clamps to 28px max. |
| **Standard Mobile** | 375px - 639px | `16px` - `20px` | 1 Column | Full thumb-zone optimization, bottom navigation, card-based tables. |
| **Tablet / Foldable** | 640px - 1023px | `24px` | 2 Columns | Collapsed icon sidebar or top navigation, horizontal swipe cards. |
| **Desktop Baseline** | 1024px - 1279px | `32px` | 3 Columns | Fixed 256px sidebar, full data tables, multi-pane rosters. |
| **Widescreen Enterprise**| 1280px - 1600px | `32px` - `48px` | Bento Grid | Max width constrained to `1600px` for optimal viewing distance. |

---

## 8. Verification & Governance Checklist

Before any design change is deployed to production:
- [x] Tested against 320px viewport for zero horizontal overflow.
- [x] All text passes WCAG 2.1 AA (AAA for slate on canvas).
- [x] Minimum touch target of 48px enforced on all interactive mobile elements.
- [x] All currency figures formatted in Kenyan Shillings (`KES X,XXX,XXX`) with monospaced JetBrains Mono.
- [x] Copy adheres to "Built for Afrikan Business & Healthcare" multi-sector scope.
- [x] Maxed-out tenant state (Pristine Hospital 150/150 seats) renders with clear warning and upgrade path.