# ADM-25 through ADM-26: Admin Payroll — Figma Production Specs

---

## 1. PAYROLL PERIODS (ADM-25)

### Create Payroll Period Modal

```
RP/Modal (md)
├── Header: "Create Payroll Period"
├── Content:
│   ├── Name: RP/Input "June 2026"
│   ├── Start Date: RP/Input (date)
│   ├── End Date: RP/Input (date)
│   └── Notes: RP/Input (textarea, optional)
├── Footer: [Cancel] [Create Period]
```

### Payroll Period Status Flow

```
Draft → Preview → Processing → Completed
  ↓        ↓          ↓            ↓
  │        │          │            │
  │ Edit   │ Review   │ Running    │ Final
  │ any    │ numbers  │ calc       │ locked
  │ field  │ no edit  │            │
  │        │          │            │
  └────────┴──────────┴────────────┘
                ↓
            Cancelled
```

### Payroll Table

```
Columns: Period | Dates | Teachers | Gross | Admin Fees | Net | Status | Actions
├── June 2026   | Jun 1–30  | 15 | ₵ 18,400 | ₵ 2,760 | ₵ 15,640 | Completed | [View] [Export] [Payslips]
├── May 2026    | May 1–31  | 15 | ₵ 17,800 | ₵ 2,670 | ₵ 15,130 | Completed | [View] [Export] [Payslips]
├── April 2026  | Apr 1–30  | 14 | ₵ 16,200 | ₵ 2,430 | ₵ 13,770 | Completed | [View] [Export] [Payslips]
└── July 2026   | Jul 1–31  | 15 | —        | —       | —         | Draft     | [View] [Process] [Delete]

Status badge colors:
├── draft: grey
├── preview: blue
├── processing: amber (animated pulse)
├── completed: green
└── cancelled: grey (strikethrough)
```

### KPI Cards

```
┌──────────────┬──────────────┬──────────────┬──────────────┐
│ Current      │ Total        │ Pending      │ Disputed     │
│ Period       │ Processed    │ Reviews      │              │
│              │              │              │              │
│ July 2026    │ ₵ 47,540     │ 2            │ 0            │
│ Draft        │ 3 periods    │              │              │
└──────────────┴──────────────┴──────────────┴──────────────┘
```

---

## 2. PAYROLL PERIOD DETAIL (ADM-26)

### Period Header

```
┌──────────────────────────────────────────────────────────┐
│  Payroll: June 2026                          [Completed] │
│  Period: June 1 – June 30, 2026                         │
│  Processed: June 30, 2026 at 11:45 PM                   │
│  Processed by: Admin Name                                │
└──────────────────────────────────────────────────────────┘
```

### Payroll Summary Card

```
┌──────────────────────────────────────────────────────────┐
│  Payroll Summary — June 2026                             │
├──────────────────────────────────────────────────────────┤
│                                                          │
│  ┌─────────────────┐    ┌─────────────────────────────┐ │
│  │                 │    │  CH-17: Waterfall Chart     │ │
│  │  Gross:         │    │                             │ │
│  │  ₵ 18,400       │    │  Gross ████ 18,400         │ │
│  │                 │    │  Fees  ███  -2,760          │ │
│  │  Admin Fees:    │    │  Adj   ░   +0               │ │
│  │  ₵ 2,760 (15%)  │    │  ─────────────────         │ │
│  │                 │    │  Net   ████ 15,640          │ │
│  │  Adjustments:   │    │                             │ │
│  │  ₵ 0            │    │                             │ │
│  │                 │    └─────────────────────────────┘ │
│  │  Net:           │                                     │
│  │  ₵ 15,640       │    Teachers: 15                    │
│  │                 │    Sessions: 240                    │
│  │                 │    Avg Admin Fee: 15%               │
│  └─────────────────┘                                     │
│                                                          │
└──────────────────────────────────────────────────────────┘
```

### CH-17: Waterfall Chart (Payroll)

```javascript
{
    chart: { type: 'bar', height: 250 },
    series: [{
        name: 'Amount',
        data: [
            { x: 'Gross', y: 18400 },
            { x: 'Admin Fees', y: -2760 },
            { x: 'Adjustments', y: 0 },
            { x: 'Net', y: 15640 }
        ]
    }],
    colors: ['#22C55E', '#DC2626', '#F59E0B', '#1E5FA8'],
    plotOptions: {
        bar: { borderRadius: 4, columnWidth: '50%' }
    },
    xaxis: { type: 'category' },
    yaxis: {
        labels: { formatter: (v) => '₵ ' + v.toLocaleString() }
    }
}
```

### Teacher Payroll Table

```
Columns: Teacher | Sessions | Private | Session Gross | Private Gross | Admin Fee | Adjustments | Net | Status | Actions
├── Dr. Mensah      | 24 | 4 | ₵ 2,000 | ₵ 400 | ₵ 360 | ₵ 0 | ₵ 2,040 | Paid | [Payslip] [Adjust]
├── Mrs. Aidoo      | 22 | 2 | ₵ 1,800 | ₵ 200 | ₵ 300 | ₵ 0 | ₵ 1,700 | Paid | [Payslip] [Adjust]
├── Mr. Ofori       | 20 | 3 | ₵ 1,600 | ₵ 300 | ₵ 285 | ₵ 0 | ₵ 1,615 | Paid | [Payslip] [Adjust]
├── Mrs. Opoku      | 18 | 0 | ₵ 1,400 | ₵ 0   | ₵ 210 | ₵ 0 | ₵ 1,190 | Paid | [Payslip] [Adjust]
├── Mr. Tetteh      | 22 | 2 | ₵ 1,800 | ₵ 200 | ₵ 300 | ₵ 0 | ₵ 1,700 | Paid | [Payslip] [Adjust]
└── ... (10 more)
```

### Teacher Payslip Modal

```
RP/Modal (lg)
├── Header: "Payslip — Dr. Mensah — June 2026"
├── Content:
│   ┌──────────────────────────────────────────────┐
│   │  [School Logo]   PAYSLIP                     │
│   │               June 2026                      │
│   ├──────────────────────────────────────────────┤
│   │  Teacher: Dr. Mensah                         │
│   │  Period: June 1–30, 2026                     │
│   │                                              │
│   │  Earnings:                                   │
│   │  ├── Session Teaching (24 sessions × ₵ 200) │
│   │  │   = ₵ 4,800                              │
│   │  ├── Private Sessions (4 × ₵ 100)           │
│   │  │   = ₵ 400                                │
│   │  │                                          │
│   │  │   Gross Earnings:     ₵ 2,400            │
│   │  │                                              │
│   │  │   Admin Fee (15%):   - ₵ 360              │
│   │  │   Adjustments:       + ₵ 0                │
│   │  │   ────────────────────────                │
│   │  │   Net Earnings:       ₵ 2,040            │
│   │  │                                              │
│   │  │   Admin fee percentage applied: 15%       │
│   │  │   (Captured at time of processing)        │
│   │  └──────────────────────────────────────────│
│   │                                              │
│   │  Generated: June 30, 2026                    │
│   └──────────────────────────────────────────────┘
├── Footer: [Download PDF] [Email to Teacher] [Close]
```

### Payroll Adjustment Modal

```
RP/Modal (md)
├── Header: "Add Adjustment — Dr. Mensah"
├── Content:
│   ├── Type: RP/Select [Addition] [Deduction]
│   ├── Amount: RP/Input (number) "100.00"
│   ├── Reason: RP/Input (textarea, required)
│   │   "Bonus for extra tutoring sessions"
│   └── ⚠ "This adjustment will be logged in the audit trail."
├── Footer: [Cancel] [Add Adjustment]

After saving:
├── Adjustments total updated
├── Net recalculated
├── PayrollAuditLog entry created
└── Row highlighted in table
```

---

## 3. PAYROLL PROCESSING WORKFLOW

### Processing Steps

```
Step 1: Admin creates payroll period (Draft)
    ↓
Step 2: Admin clicks "Preview Payroll"
    → PayrollCalculatorService.preview() runs
    → Shows calculated amounts for all teachers
    → Status: Draft → Preview
    ↓
Step 3: Admin reviews preview
    ├── Checks session counts
    ├── Verifies admin fee percentages (snapshot)
    ├── Reviews any adjustments
    └── Can click individual teacher to see breakdown
    ↓
Step 4: Admin clicks "Process Payroll"
    → Confirmation modal:
    │   "Process payroll for June 2026?"
    │   "15 teachers — Total net: ₵ 15,640"
    │   "This action cannot be undone."
    │   [Cancel] [Process Payroll]
    ↓
Step 5: Processing runs
    → Status: Preview → Processing
    → PayrollCalculatorService.processPayroll() runs
    → For each teacher:
    │   ├── Calculate gross from sessions
    │   ├── Snapshot admin fee percentage
    │   ├── Apply adjustments
    │   ├── Calculate net
    │   └── Create payroll_calculations record
    → Status: Processing → Completed
    ↓
Step 6: Admin can now:
    ├── [Export to Excel] — download spreadsheet
    ├── [Send Payslips] — email PDFs to all teachers
    └── [View Audit Trail] — who did what
```

### Processing Animation

```
During processing:
┌──────────────────────────────────────────────────┐
│  ⏳ Processing Payroll — June 2026               │
│                                                  │
│  ████████████████████████░░░░░░░░  12/15 teachers│
│                                                  │
│  Currently processing: Mrs. Opoku                │
│                                                  │
│  [Cancel Processing]                             │
└──────────────────────────────────────────────────┘
```

---

## 4. PAYROLL EXPORT

### Excel Export Format

```
Sheet 1: Summary
├── Period: June 2026
├── Total Gross: ₵ 18,400
├── Total Admin Fees: ₵ 2,760
├── Total Net: ₵ 15,640
├── Teachers: 15
└── Processed: Jun 30, 2026

Sheet 2: Teacher Details
├── Columns: Teacher Name | Sessions | Private | Session Gross | Private Gross | Admin Fee % | Admin Fee Amount | Adjustments | Net | Status
├── Row per teacher
└── Totals row at bottom

Sheet 3: Session Breakdown
├── Columns: Teacher | Date | Subject | Class | Mode | Duration
├── One row per session
└── Filterable by teacher
```

---

## 5. DARK MODE — Payroll Screens

| Element | Light | Dark |
|---------|-------|------|
| Payslip BG | #FFFFFF | #1E293B |
| Payslip border | #E2E8F0 | #334155 |
| Waterfall gross bar | #22C55E | #4ADE80 |
| Waterfall fee bar | #DC2626 | #F87171 |
| Waterfall net bar | #1E5FA8 | #60A5FA |
| Processing animation | amber pulse | amber pulse |
| Table row hover | #F1F5F9 | #1E293B |
| Adjustment badge | amber | amber |
| Status badges | Same colors | Same colors |

---

## 6. EMPTY STATES

| Screen | Title | CTA |
|--------|-------|-----|
| ADM-25 | "No payroll periods yet" | [Create Payroll Period] |
| ADM-26 (no data) | "No teachers to process" | "Ensure teachers are assigned sessions" |
| ADM-26 (draft) | "Ready to preview payroll" | [Preview Payroll] |

---

## 7. ACCESSIBILITY — Payroll Screens

- Payslip: `role="document"` with `aria-label="Payslip for [teacher], [period]"`
- Waterfall chart: `aria-label` describing totals
- Processing progress: `role="progressbar"` with `aria-valuenow`, `aria-valuemin`, `aria-valuemax`
- Table: Sortable columns with `aria-sort`
- Adjustment modal: Amount field `aria-describedby` linked to validation
- Export buttons: `aria-label="Export payroll to Excel"`