# Gamification Production Specifications

---

## 1. OPS SCORE RING

### Component: `RP/OPSRing`

#### Visual Specification

```
┌───────────────────────────┐
│                           │
│      ██████████████       │
│    ██░░░░░░░░░░░░░░██     │
│   █░░░░░░░░░░░░░░░░░░█    │
│  █░░░░░░░░░░░░░░░░░░░░█   │
│  █░░░░░░░░░░░░░░░░░░░░█   │
│  █░░░░░░░░ 78% ░░░░░░░█   │  ← Center: Score percentage
│  █░░░░░░░░░░░░░░░░░░░░█   │
│  █░░░░░░░░░░░░░░░░░░░░█   │
│   █░░░░░░░░░░░░░░░░░░█    │
│    ██░░░░░░░░░░░░░░██     │
│      ██████████████       │
│                           │
└───────────────────────────┘
```

#### SVG Implementation
```
Circle 1 (Background):
  cx: 50%, cy: 50%, r: 45%
  fill: none
  stroke: gamification/ring-bg (#E2E8F0 light / #334155 dark)
  stroke-width: {size-dependent}
  stroke-linecap: round

Circle 2 (Progress):
  cx: 50%, cy: 50%, r: 45%
  fill: none
  stroke: {zone-color}
  stroke-width: {size-dependent}
  stroke-dasharray: {percentage × circumference}
  stroke-dashoffset: 0
  stroke-linecap: round
  transform: rotate(-90 50% 50%)
  style: transition: stroke-dasharray 1s ease-in-out

Text (Center):
  x: 50%, y: 50%
  text-anchor: middle
  dominant-baseline: central
  font-family: Inter
  font-weight: 700
  font-size: {size-dependent}
  fill: color/header-text
```

#### Color Zone Logic
```javascript
function getZoneColor(score) {
    if (score >= 80) return { light: '#22C55E', dark: '#4ADE80' };  // Green
    if (score >= 60) return { light: '#F59E0B', dark: '#FBBF24' };  // Amber
    return { light: '#DC2626', dark: '#F87171' };                    // Red
}
```

#### Size Variants

| Size | Diameter | Stroke Width | Center Font | Ring Radius | Circumference |
|------|----------|-------------|-------------|-------------|---------------|
| `sm` | 64px | 6px | 14px Bold | 25.2px | 158.3px |
| `md` | 120px | 8px | 24px Bold | 47.7px | 299.7px |
| `lg` | 180px | 10px | 36px Bold | 72.7px | 456.9px |
| `xl` | 240px | 12px | 48px Bold | 98.4px | 618.3px |

#### Animation
- Initial load: Ring animates from 0% to actual percentage over 1 second
- Ease: cubic-bezier(0.4, 0, 0.2, 1)
- Score text counts up from 0

---

## 2. TIER SYSTEM

### Tier Definitions

| Tier | Min Points | Max Points | Color | Icon | Background |
|------|-----------|------------|-------|------|------------|
| Bronze | 0 | 499 | #CD7F32 | 🥉 | rgba(205,127,50,0.08) / dark: rgba(205,127,50,0.15) |
| Silver | 500 | 1,499 | #8A8A8A (WCAG AA) | 🥈 | rgba(138,138,138,0.08) / dark: rgba(138,138,138,0.15) |
| Gold | 1,500 | 2,999 | #D4A017 | 🥇 | rgba(212,160,23,0.08) / dark: rgba(212,160,23,0.15) |
| Platinum | 3,000 | 5,999 | #9E9E9E (WCAG AA) | 💎 | rgba(158,158,158,0.08) / dark: rgba(158,158,158,0.15) |
| Diamond | 6,000+ | — | #67C8FF | 👑 | rgba(103,200,255,0.08) / dark: rgba(103,200,255,0.15) |

### Tier Badge Component

```
┌─────────────────────────────┐
│  🥈  Silver                 │  ← 32px height pill
└─────────────────────────────┘
```

- Height: 32px
- Padding: 4px 12px
- Border-radius: 16px (full)
- BG: Tier background color
- Text: Tier color, 14px Medium
- Icon: 16px emoji
- Border: 1px solid tier color at 20% opacity

### Tier Progress Bar (on STU-01, STU-14)

```
🥉 Bronze     🥈 Silver ←YOU     🥇 Gold      💎 Platinum    👑 Diamond
   (0)          (500)            (1,500)        (3,000)         (6,000)
                              ████████████░░░░░░░░
                              1,250 / 1,500 pts
                              250 pts to Gold
```

- Horizontal layout, all 5 tiers
- Current tier: Full color, highlighted ring
- Past tiers: Full color, smaller
- Future tiers: Greyed (40% opacity)
- Progress bar between current and next tier
- Points label below

### Tier Upgrade Animation
- Confetti effect (CSS animation, gold particles)
- Badge scales up 1.5x then back to 1x
- Duration: 2 seconds
- Sound: Optional chime

---

## 3. ACHIEVEMENT BADGES

### Badge Grid Layout

```
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│  📝     │ │  🎉     │ │  🔥     │ │  🔥     │
│  First   │ │  First   │ │  7-Day  │ │  14-Day │
│  Submit  │ │  Pass    │ │  Streak │ │  Streak │
│  Jun 10  │ │  Jun 12  │ │  Jun 8  │ │  —     │
│  ✓ earned│ │  ✓ earned│ │  ✓ earned│ │  🔒 locked│
└─────────┘ └─────────┘ └─────────┘ └─────────┘
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│  🔥     │ │  ✅     │ │  🥇     │ │  👑     │
│  30-Day │ │  Perfect │ │  Gold   │ │  Diamond│
│  Streak │ │  Attend  │ │  Tier   │ │  Tier   │
│  —      │ │  —      │ │  —      │ │  —      │
│  🔒 locked│ │  🔒 locked│ │  🔒 locked│ │  🔒 locked│
└─────────┘ └─────────┘ └─────────┘ └─────────┘
```

### Badge States

| State | Visual | Icon | Border | Shadow |
|-------|--------|------|--------|--------|
| Earned | Full color, subtle glow | Full color (48px) | 2px tier color | 0 0 12px tier color at 20% |
| Locked | Greyscale (100% desaturated) | Greyscale + lock overlay (40% opacity) | 1px #E2E8F0 | none |
| Newly earned | Full color, pulse animation | Full color (48px) | 2px gold | 0 0 20px gold at 30% |

### Badge Definitions

| Key | Name | Icon | Description | Trigger |
|-----|------|------|-------------|---------|
| `first_submission` | First Submission | 📝 | "Submitted your first assignment" | First assignment submission |
| `first_exam_pass` | First Exam Pass | 🎉 | "Passed your first exam" | First exam score ≥ passing |
| `streak_7` | 7-Day Streak | 🔥 | "7 consecutive days of activity" | 7-day streak |
| `streak_14` | 14-Day Streak | 🔥 | "14 consecutive days of activity" | 14-day streak |
| `streak_30` | 30-Day Streak | 🔥 | "30 consecutive days of activity" | 30-day streak |
| `streak_60` | 60-Day Streak | 🔥 | "60 consecutive days of activity" | 60-day streak |
| `streak_100` | 100-Day Streak | 🔥 | "100 consecutive days of activity" | 100-day streak |
| `perfect_attendance` | Perfect Attendance | ✅ | "100% attendance this term" | No absences in term |
| `gold_tier` | Gold Tier | 🥇 | "Reached Gold tier" | ≥ 1,500 points |
| `diamond_tier` | Diamond Tier | 👑 | "Reached Diamond tier" | ≥ 6,000 points |

### Badge Unlock Animation
1. Badge card scales from 0 to 1.2x then 1x (bounce ease, 500ms)
2. Glow ring pulses 3 times
3. Confetti particles (CSS keyframes)
4. Toast notification: "🏆 New badge unlocked: {name}!"
5. Points awarded notification: "+{points} pts added to your score"

---

## 4. STREAK TRACKING

### Streak Badge Sizes

| Size | Flame Icon | Count Text | BG Height | Padding |
|------|-----------|------------|-----------|---------|
| `sm` | 16px | 12px Bold | 24px | 2px 8px |
| `md` | 24px | 14px Bold | 32px | 4px 12px |
| `lg` | 32px | 18px Bold | 40px | 6px 16px |

### Streak Colors
- Active (1-6 days): #F97316 (orange)
- Active (7-29 days): #EF4444 (red-orange)
- Active (30+ days): #DC2626 (red) with gold accent
- Broken: #94A3B8 (muted grey)

### Streak Rules
- Increments on consecutive calendar days only
- Breaks if gap > 1 calendar day (resets to 1)
- Longest streak preserved historically — never decreases

### Streak Milestones

| Milestone | Bonus Points | Visual |
|-----------|-------------|--------|
| 7 days | 35 pts (5×7) | 🏅 Bronze milestone badge |
| 14 days | 70 pts (5×14) | 🏅 Silver milestone badge |
| 30 days | 150 pts (5×30) | 🏅 Gold milestone badge |
| 60 days | 300 pts (5×60) | 🏅 Platinum milestone badge |
| 100 days | 500 pts (5×100) | 🏅 Diamond milestone badge |

### Milestone Progress Display

```
🔥 12 days  →  2 days to next milestone (14)
[████████████████░░░░] 12/14 days
```

- Progress bar toward next milestone
- "X days to next milestone (Y)" text
- Milestone badges row below

---

## 5. ATTENDANCE HEATMAP

### Calendar Grid

```
        Mon   Tue   Wed   Thu   Fri
Week 1:  🟢    🟢    🟡    🟢    🔴
Week 2:  🟢    🟢    🟢    🟢    ⬜
Week 3:  🟢    🔴    🟢    🟢    🟢
Week 4:  🟢    🟢    🟢    🟢    🟢
Week 5:  🟢    —     —     —     —
```

### Cell Specification

| Property | Value |
|----------|-------|
| Size | 48×48px (desktop), 36×36px (mobile) |
| Gap | 4px |
| Border-radius | 8px |
| Font | 14px Medium (centered) |

### Cell Colors

| Status | Light Mode | Dark Mode | Day Number |
|--------|-----------|-----------|------------|
| Present | #22C55E | #4ADE80 | White text |
| Late | #F59E0B | #FBBF24 | White text |
| Absent | #DC2626 | #F87171 | White text |
| No Class | #E2E8F0 | #334155 | #94A3B8 (muted) |
| Today | — | — | Ring 2px `color/secondary` |
| Weekend | Hidden | Hidden | — |

### Hover Tooltip
```
┌──────────────────────────┐
│  June 12, 2026           │
│  ● Present               │
│  Mathematics             │
└──────────────────────────┘
```

- BG: `color/surface-elevated`
- Shadow: `shadow/md`
- Border-radius: 8px
- Padding: 8px 12px
- Max-width: 200px

### Legend
```
● Present  ● Late  ● Absent  ● No Class
```
- Layout: Horizontal, gap 16px
- Each: Colored dot (8px) + label (12px)
- Position: Below calendar

### Month Navigation
```
← Previous    June 2026    Next →
```
- Previous/Next: RP/Button (ghost, sm)
- Month label: Display/H5 (18px, Medium)

---

## 6. GOAL PROGRESS

### Goal Card States

#### Active Goal
```
┌──────────────────────────────────────────────┐
│  Improve Math score to 85%           [Active]│
│  Mathematics                                    │
│                                                │
│  ████████████████░░░░░░░░ 65%                 │
│                                                │
│  Target: 85%  |  Current: 78%  |  Due: Dec 31 │
│                                                │
│  "Keep practicing algebra exercises daily."     │
│  — Dr. Mensah                                  │
└──────────────────────────────────────────────┘
```

#### Completed Goal
```
┌──────────────────────────────────────────────┐
│  ✓ Improve English vocabulary     [Completed] │
│  English                                      │
│                                                │
│  ████████████████████████ 100%               │
│                                                │
│  Target: 80%  |  Achieved: 85%  |  Dec 10    │
│                                                │
│  "Excellent work! You exceeded your target."   │
│  — Mrs. Aidoo                                  │
└──────────────────────────────────────────────┘
```

### Progress Bar Colors
| Progress | Color | Badge |
|----------|-------|-------|
| 0-49% | `color/danger` (#DC2626) | "Behind" |
| 50-74% | `color/warning` (#F59E0B) | "On Track" |
| 75-99% | `color/secondary` (#1E5FA8) | "Almost There" |
| 100% | `color/success` (#22C55E) | "Achieved ✓" |

---

## 7. LEADERBOARD DISPLAYS

### Top 3 Podium

```
         🥈              🥇              🥉
        Kofi A.        Amara A.        Nana K.
          82%            78%             75%
        Silver          Silver          Gold
```

- 2nd place: Left, 80px avatar
- 1st place: Center, 100px avatar, gold crown icon
- 3rd place: Right, 80px avatar
- Names below avatars
- Scores in bold

### Table View

| Rank | Student | OPS Score | Tier |
|------|---------|-----------|------|
| 🥇 | Amara Asante | 82% | 🥈 |
| 🥈 | Kofi Mensah | 78% | 🥇 |
| 🥉 | Nana Owusu | 75% | 🥈 |
| 4 | *You* — Ama Sarpong | 72% | 🥉 |
| 5 | Esi Boateng | 68% | 🥉 |

- Your row: Highlighted (bg rgba(30,95,168,0.08), border-left 3px color/secondary)
- Top 3: Medal icons (🥇🥈🥉) + bolder text
- Columns: Rank (15%), Avatar+Name (50%), Score (20%), Tier (15%)

### Leaderboard Tabs
```
[Class]  [School]
```
- RP/Tabs (variant: pill)
- Class: Shows students in same class
- School: Shows all students ranked

### Time Filters
```
[This Term ▾]
├── This Term
├── This Year
└── All Time
```
- RP/Select (sm)

---

## 8. POINTS DISPLAY

### Points Award Notification

```
┌─────────────────────────────────────┐
│  +10 pts  Assignment completed      │
│  New total: 1,260 pts              │
└─────────────────────────────────────┘
```

- Toast (type: success)
- Auto-dismiss: 3000ms
- Points text: color/success, Bold

### Points History Timeline

```
┌──────────────────────────────────────────┐
│  +15 pts  Exam passed — Mid-Term Math    │
│  Jun 12, 2026                            │
├──────────────────────────────────────────┤
│  +10 pts  Assignment completed           │
│  Jun 10, 2026                            │
├──────────────────────────────────────────┤
│  +35 pts  Streak milestone (7 days)      │
│  Jun 8, 2026                             │
├──────────────────────────────────────────┤
│  +5 pts   Daily login streak             │
│  Jun 7, 2026                             │
└──────────────────────────────────────────┘
```

- RP/Timeline component
- Each entry: Points (green) + reason + date
- Points: Body/SM, Bold, color/success
- Reason: Body/SM
- Date: Body/XS, muted

---

## 9. REWARD DISPLAYS

### Gamification Widget (Dashboard)

```
┌──────────────────────────────────────────┐
│  🏆 Achievements                          │
│                                          │
│  Points: 1,260   Tier: 🥈 Silver        │
│  Streak: 🔥 12 days                     │
│                                          │
│  [Progress to Gold ████████░░░] 84%     │
│  240 points to Gold                      │
│                                          │
│  Recent: 📝 🎉 🔥                        │
└──────────────────────────────────────────┘
```

- RP/Card (shadow/sm, padding/md)
- Layout: Vertical, gap 12px
- Compact version for dashboard sidebar

### Achievement Popup (on unlock)

```
┌──────────────────────────────────────────┐
│                                          │
│           🏆 (animated, 64px)            │
│                                          │
│     New Badge Unlocked!                  │
│     First Exam Pass                      │
│                                          │
│     "Passed your first exam"             │
│                                          │
│     +15 pts added to your score          │
│                                          │
│     [Awesome!]                           │
│                                          │
└──────────────────────────────────────────┘
```

- RP/Modal (sm)
- Centered content
- Animated icon (scale + glow)
- Points awarded in green
- Single CTA: "Awesome!" (accent button)

---

## 10. DARK MODE GAMIFICATION OVERRIDES

All gamification elements use the `RP Gamification` variable collection with Light and Dark modes.

| Element | Light | Dark |
|---------|-------|------|
| OPS Ring green | #22C55E | #4ADE80 |
| OPS Ring amber | #F59E0B | #FBBF24 |
| OPS Ring red | #DC2626 | #F87171 |
| OPS Ring bg | #E2E8F0 | #334155 |
| Heatmap present | #22C55E | #4ADE80 |
| Heatmap late | #F59E0B | #FBBF24 |
| Heatmap absent | #DC2626 | #F87171 |
| Heatmap no-class bg | #E2E8F0 | #334155 |
| Heatmap no-class text | #94A3B8 | #64748B |
| Flame icon | #F97316 | #FB923C |
| Tier badge bg | 8% opacity | 15% opacity |
| Tier badge text | Tier color | Tier color (same) |