pragativeer-v2/DESIGN_SYSTEM.md

# PragatiVeer v2 — Comprehensive Design System & Style Guide

> **Document Type:** Production Design System, UI Component Specification & Theming Reference  
> **Target Audience:** Frontend Engineers, UI/UX Designers, QA Engineers  
> **Last Verified:** September 2026  
> **Framework:** Next.js 16 (React 19) + TailwindCSS v4 + Framer Motion + KaTeX  
> **Theme Engine:** Dual-Storage CSS Class Architecture (`.dark` on `<html>`)  

---

## 1. Design Philosophy & Aesthetic Core

PragatiVeer v2 uses a hybrid visual design language:
1. **Light Mode (Default for Student Dashboard & Public Pages):** Clean, distraction-free, high-legibility EdTech aesthetic. Employs pure white surfaces (`#FFFFFF`), crisp neutral typography (`#171717`), subtle borders (`#E5E5E5`), and intentionally flattened elevations (`box-shadow: none !important;`) to eliminate visual clutter during prolonged study and test-taking sessions.
2. **Dark Mode (Default for Admin Console, Optional for Students):** Cyberpunk-inspired, high-contrast dark cockpit. Uses deep obsidian (`#0A0A0A`), neon lime (`#D1FF4D`), electric cyan (`#00F0FF`), and glowing atmospheric drop-shadows to emphasize focal stats and action triggers.

```mermaid
graph TD
    Root["<html> element"] -->|No class / light| LightTheme["Light Mode (Student/Public Default)"]
    Root -->|class='dark'| DarkTheme["Dark Mode (Admin Default / Student Opt-in)"]
    
    LightTheme --> L_BG["Background: #FFFFFF"]
    LightTheme --> L_FG["Foreground: #171717"]
    LightTheme --> L_FLAT["Flat Elevations (No 3D shadows)"]
    
    DarkTheme --> D_BG["Background: #0A0A0A"]
    DarkTheme --> D_LIME["Primary: #D1FF4D (Neon Lime)"]
    DarkTheme --> D_CYAN["Accent: #00F0FF (Electric Cyan)"]
    DarkTheme --> D_GLOW["Neon Glow Shadows"]
```

---

## 2. Theming Architecture & Dual-Storage Strategy

PragatiVeer implements a flash-preventing (`beforeInteractive`) script in `src/app/layout.tsx` that evaluates theme state prior to DOM hydration:

| Context / Surface | Default Theme | LocalStorage Key | Toggle Component | Header Class |
| :--- | :---: | :---: | :--- | :--- |
| **Public Landing & Marketing** | Light | `theme` | `ThemeToggle.tsx` | `.dark` on `<html>` |
| **Student Dashboard & CBT Engine** | Light | `theme` | `ThemeToggle.tsx` | `.dark` on `<html>` |
| **Admin Command Center** | Dark | `admin-theme` | `AdminThemeToggle.tsx` | `.dark` on `<html>` |

```javascript
// Initialization Script in layout.tsx
if (window.location.pathname.startsWith('/admin')) {
  const adminTheme = localStorage.getItem('admin-theme');
  if (adminTheme === 'light') document.documentElement.classList.remove('dark');
  else document.documentElement.classList.add('dark'); // Admin defaults to dark
} else {
  const theme = localStorage.getItem('theme');
  if (theme === 'dark') document.documentElement.classList.add('dark');
  else document.documentElement.classList.remove('dark'); // Student defaults to light
}
```

---

## 3. Color Tokens & Mode Comparison Matrix

All fundamental colors are defined as CSS variables in `src/app/globals.css` and mapped to TailwindCSS utilities:

### 3.1 Core Semantic Tokens

| CSS Variable | Tailwind Utility | Light Mode (Hex / Role) | Dark Mode (Hex / Role) | Purpose |
| :--- | :--- | :--- | :--- | :--- |
| `--background` | `bg-background` | `#ffffff` (Pure White) | `#0a0a0a` (Obsidian) | Main canvas background |
| `--foreground` | `text-foreground` | `#171717` (Near Black) | `#ededed` (Off White) | Primary text and headings |
| `--border` | `border-border` | `#e5e5e5` (Neutral Gray 200) | `#1f1f1f` (Dark Neutral 800) | Structural dividers & card outlines |
| `--input` | `border-input` | `#e5e5e5` | `#1f1f1f` | Form field outlines |
| `--ring` | `ring-ring` | `#171717` | `#D1FF4D` (Neon Lime) | Focus visibility ring |
| `--primary` | `bg-primary` / `text-primary` | `#171717` (Deep Slate Black) | `#D1FF4D` (Neon Lime / Chartreuse) | High-impact action buttons & active highlights |
| `--primary-foreground` | `text-primary-foreground` | `#fafafa` (Pure Off-White) | `#0a0a0a` (Deep Black) | Text on top of primary buttons |
| `--secondary` | `bg-secondary` | `#f5f5f5` (Neutral Gray 100) | `#171717` (Deep Gray 900) | Subtle backgrounds, option pills |
| `--secondary-foreground` | `text-secondary-foreground` | `#171717` | `#ededed` | Text on secondary elements |
| `--accent` | `bg-accent` / `text-accent` | `#f5f5f5` | `#00F0FF` (Electric Cyan) | Brand glow, AI coach indicators |
| `--accent-foreground` | `text-accent-foreground` | `#171717` | `#0a0a0a` | Text on accent elements |
| `--muted` | `bg-muted` | `#f5f5f5` | `#171717` | Disabled or subtle containers |
| `--muted-foreground` | `text-muted-foreground` | `#737373` (Neutral Gray 500) | `#a3a3a3` (Neutral Gray 400) | Subtitles, captions, metadata |

---

### 3.2 Domain & Brand Feature Accents

| Accent Name | Hex Code | Light Mode Usage | Dark Mode Usage | Feature Association |
| :--- | :---: | :--- | :--- | :--- |
| **Cyber Cyan** | `#00F0FF` | `text-cyan-800`, `border-cyan-300/60`, `bg-cyan-50` | `text-[#00F0FF]`, `bg-[#00F0FF]/10`, `shadow-[0_0_15px_-5px_#00F0FF]` | AI Coach, Tutor Chat, PrepPilot AI |
| **Neon Lime** | `#D1FF4D` | Subtle green pill badges | `bg-primary`, `text-primary`, `shadow-[0_0_15px_-5px_#D1FF4D]` | Dark mode hero highlights & primary actions |
| **Amber Gold** | `#EAB308` | `text-yellow-700`, `bg-yellow-50`, `border-yellow-300/60` | `text-yellow-400`, `bg-yellow-500/10`, `shadow-[0_0_12px_-4px_rgba(234,179,8,0.2)]` | Pro Tier, CBT Marked for Review questions |
| **Emerald Green** | `#22C55E` | `bg-green-500 text-white` | `bg-green-500 text-white shadow-sm` | CBT Answered questions, Success toasts |
| **Crimson Red** | `#EF4444` | `bg-red-500 text-white`, `text-red-600` | `bg-red-500 text-white`, `text-red-400` | CBT Not Answered, Error banners, Destructive |
| **Flame Orange** | `#F97316` | `text-orange-600 bg-orange-500/10` | `text-orange-500 shadow-[0_0_10px_-2px_rgba(249,115,22,0.5)]` | Daily Study Streaks, Streak Counter |

---

### 3.3 Flat vs. Glow Elevation Policy

To maintain professional academic rigor in Light Mode and futuristic engagement in Dark Mode, a global CSS rule in `src/app/globals.css` governs drop-shadows:

```css
/* Light mode: flatten card shadows so they don't look 3D/lifted */
:root:not(.dark) .shadow-sm,
:root:not(.dark) .shadow,
:root:not(.dark) .shadow-md,
:root:not(.dark) .shadow-lg,
:root:not(.dark) .shadow-xl,
:root:not(.dark) .shadow-2xl,
:root:not(.dark) [class*="shadow-"] {
  box-shadow: none !important;
}
```

- **Light Mode Result:** Clean, Scandinavian-style flat borders (`border border-border`), completely eliminating muddy gray shadow artifacts on white cards.
- **Dark Mode Result:** Preserves vibrant colored glows (`shadow-[0_0_15px_-5px_#00F0FF]`, `shadow-[0_0_20px_rgba(209,255,77,0.3)]`).

---

## 4. Typography Scale & Font Architecture

### 4.1 Font Family Declarations
Fonts are loaded through Next.js Google Font optimization in `src/app/layout.tsx`:

| Typeface Role | Font Family | Variable Name | Fallback Stack | Usage Area |
| :--- | :--- | :--- | :--- | :--- |
| **Primary Sans** | **Geist** | `--font-geist-sans` | `Arial, Helvetica, sans-serif` | All UI headers, cards, navigation, body copy |
| **Primary Mono** | **Geist Mono** | `--font-geist-mono` | `ui-monospace, Menlo, Monaco, monospace` | Timers, question indices, tokens, code blocks |
| **Formula & Math** | **KaTeX (AMS / Computer Modern)** | Default KaTeX engine | `serif` | Math formulas, chemical reactions, exponents |

---

### 4.2 Type Scale & Hierarchy

| Hierarchy Level | Tailwind Classes | Desktop Size | Mobile Size | Weight | Tracking & Leading | Usage Example |
| :--- | :--- | :---: | :---: | :---: | :--- | :--- |
| **Hero Display** | `text-6xl md:text-8xl` | `96px` | `60px` | `font-bold` | `tracking-tighter leading-[1.1]` | Landing Page Hero title |
| **Page Header (H1)** | `text-3xl md:text-4xl` | `36px` | `30px` | `font-black` | `tracking-tight leading-tight` | Dashboard "Performance Overview", CBT Header |
| **Section Title (H2)** | `text-2xl md:text-3xl` | `28px` | `24px` | `font-bold` | `tracking-tight leading-snug` | Exam Instruction headings, Admin sections |
| **Card Title (H3)** | `text-lg md:text-xl` | `20px` | `18px` | `font-semibold` | `tracking-tight leading-none` | Test Cards, KPI Card titles, Pricing headers |
| **Large Body** | `text-lg md:text-xl` | `20px` | `18px` | `font-bold` | `leading-relaxed` | Question statement text, LaTeX formula blocks |
| **Standard Body** | `text-sm md:text-base` | `16px` | `14px` | `font-normal / font-medium` | `leading-relaxed text-muted-foreground` | Paragraphs, option text, feature explanations |
| **Form Inputs & Labels** | `text-sm` | `14px` | `14px` | `font-medium / font-bold` | `leading-normal` | Form input values, field labels |
| **Table Headings** | `text-xs font-bold` | `12px` | `12px` | `font-bold` | `uppercase tracking-wider` | Test history headers, Question bank columns |
| **Micro Badges & Tags** | `text-[10px] / text-[11px]` | `10–11px` | `10px` | `font-black` | `uppercase tracking-[0.15em]` | Sidebar tier dividers, Hindi badges, exam tags |

---

## 5. Button Architecture & Styling Variants

Buttons are standardized via `src/components/ui/button.tsx` with specialized custom utilities applied throughout the application:

### 5.1 Standard Button Variants (`src/components/ui/button.tsx`)

| Variant | Light Mode Classes | Dark Mode Classes | Best Used For |
| :--- | :--- | :--- | :--- |
| **`default`** | `bg-[#171717] text-[#fafafa] hover:bg-[#171717]/90 hover:scale-[1.02] active:scale-[0.98]` | `bg-[#D1FF4D] text-[#0a0a0a] hover:bg-[#D1FF4D]/90 hover:scale-[1.02] active:scale-[0.98]` | Primary CTA, Submit forms, Sign In |
| **`secondary`** | `bg-[#f5f5f5] text-[#171717] hover:bg-[#f5f5f5]/80` | `bg-[#171717] text-[#ededed] hover:bg-[#171717]/80` | Secondary options, Cancel, Dismiss |
| **`outline`** | `border border-[#e5e5e5] bg-background hover:bg-[#f5f5f5] hover:text-[#171717]` | `border border-[#1f1f1f] bg-background hover:bg-[#00F0FF] hover:text-[#0a0a0a]` | Filter buttons, Back buttons, Nav links |
| **`ghost`** | `hover:bg-[#f5f5f5] hover:text-[#171717]` | `hover:bg-[#00F0FF] hover:text-[#0a0a0a]` | Icon triggers, Theme toggle, Menu items |
| **`link`** | `text-primary underline-offset-4 hover:underline` | `text-primary underline-offset-4 hover:underline` | Text links ("Forgot Password?", "Sign up") |

---

### 5.2 Size Matrix

| Size Variant | Height | Padding | Corner Radius | Font Size & Weight |
| :--- | :---: | :---: | :---: | :--- |
| **`sm`** | `36px` (`h-9`) | `px-3` | `rounded-xl` (`12px`) | `text-xs font-bold` |
| **`default`** | `40px` (`h-10`) | `px-4 py-2` | `rounded-xl` (`12px`) | `text-sm font-medium` |
| **`lg`** | `44px` (`h-11`) | `px-8` | `rounded-2xl` (`16px`) | `text-base font-bold` |
| **`hero` / `cbt`** | `48–56px` (`h-12 / h-14`) | `px-8` | `rounded-xl / rounded-2xl` | `text-lg font-black` |
| **`icon`** | `40px x 40px` (`h-10 w-10`) | `p-0` | `rounded-xl` | Icon center |

---

### 5.3 Domain-Specific High-Impact Button Classes

#### A. Cyber Cyan AI Glow Button (AI Coach / Landing Hero)
```tsx
<Button className="rounded-full font-bold px-6 bg-[#00F0FF] text-black hover:bg-[#00F0FF]/90 transition-all shadow-none dark:shadow-[0_0_15px_-5px_#00F0FF] dark:hover:shadow-[0_0_25px_-5px_#00F0FF]">
  Get Started
</Button>
```
- **Light Mode:** High-contrast vibrant cyan button with crisp dark text.
- **Dark Mode:** Luminous neon cyan button radiating a 15px cyan halo.

#### B. Pro Tier Gold CTA Button (`/upgrade`)
```tsx
<Button className="w-full bg-yellow-500 text-black hover:bg-yellow-400 font-bold text-lg rounded-2xl h-12">
  Get Pro
</Button>
```
- **Both Modes:** Bold, warm golden yellow (`#EAB308`) with black label.

#### C. NTA CBT Examination Action Buttons (`/cbt/[examId]`)
```tsx
// Save & Next (Primary test progression)
<Button className="flex-[2] h-12 rounded-xl font-bold bg-primary text-primary-foreground shadow-none dark:shadow-[0_0_15px_-5px_var(--color-primary)]">
  Save & Next <ChevronRight size={16}/>
</Button>

// Mark for Review (Flagged question)
<Button variant="outline" className="flex-1 h-9 text-xs font-bold bg-amber-500/10 text-amber-500 border-amber-500/50">
  <Flag size={14} className="mr-1.5"/> Mark
</Button>

// Clear Response (Reset question)
<Button variant="outline" className="flex-1 h-9 text-xs font-bold bg-secondary/50 hover:bg-destructive/10 hover:text-destructive hover:border-destructive/50">
  <XCircle size={14} className="mr-1.5"/> Clear
</Button>

// Final Submit Test (Header Button)
<Button className="bg-green-600 hover:bg-green-700 text-white font-bold rounded-xl h-10 px-5 shadow-sm">
  Submit Test
</Button>
```

---

### 5.4 Question Palette Grid Buttons (NTA Examination Standard)

The right sidebar of the CBT Exam utilizes color-coded and shape-coded buttons matching the National Testing Agency (NTA) standard:

| Status State | Shape | Background Color | Text Color | Border | Visual Indicator |
| :--- | :---: | :---: | :---: | :---: | :--- |
| **Answered** | Square (`rounded`) | `bg-green-500` | White | `border-green-500` | Solid green box |
| **Not Answered** | Square (`rounded`) | `bg-red-500` | White | `border-red-500` | Solid red box |
| **Not Visited** | Square (`rounded`) | `bg-background` | `text-foreground` | `border-border` | Subtle gray outline |
| **Marked for Review** | Circle (`rounded-full`) | `bg-amber-500` | White | `border-amber-500` | Solid amber circular badge |
| **Answered & Marked** | Circle (`rounded-full`) | `bg-amber-500` | White | `border-amber-500` | Amber circle with small green dot at bottom-right |
| **Active Current Question** | Square or Circle | Current background | Current text | `border-transparent` | `ring-2 ring-primary ring-offset-2 ring-offset-background` |

---

### 5.5 Multiple Choice Radio Option Buttons (`src/app/cbt/[examId]/page.tsx`)

| State | Light Mode Classes | Dark Mode Classes |
| :--- | :--- | :--- |
| **Unselected Option** | `border-border bg-background hover:border-primary/50 hover:bg-secondary/20` | `border-border bg-background hover:border-primary/50 hover:bg-secondary/20` |
| **Selected Option** | `border-[#171717] bg-[#171717]/5 text-[#171717]` | `border-[#D1FF4D] bg-[#D1FF4D]/5 text-[#D1FF4D] shadow-[0_0_15px_-5px_#D1FF4D]` |
| **Letter Badge (A, B, C, D) Unselected** | `border-border text-muted-foreground` | `border-border text-muted-foreground` |
| **Letter Badge Selected** | `border-[#171717] bg-[#171717] text-white` | `border-[#D1FF4D] bg-[#D1FF4D] text-[#0a0a0a]` |

---

## 6. Component Design Specifications

### 6.1 Cards (`src/components/ui/card.tsx`)

```tsx
<Card className="rounded-2xl border border-border bg-background text-foreground transition-all duration-300">
  <CardHeader className="flex flex-col space-y-1.5 p-6 pb-2">
    <CardTitle className="font-semibold text-lg tracking-tight">Title</CardTitle>
    <CardDescription className="text-sm text-muted-foreground">Description</CardDescription>
  </CardHeader>
  <CardContent className="p-6 pt-0">Content</CardContent>
</Card>
```
- **Standard Card:** `rounded-2xl border border-border bg-background`
- **Backdrop Blur Card:** `bg-background/80 backdrop-blur-md rounded-[2rem] border border-border`
- **Neon Glow Card (Dark Mode):** `bg-[#00F0FF]/5 border-[#00F0FF]/30 shadow-[0_0_20px_-10px_#00F0FF]`

---

### 6.2 Badges & Tier Indicators (`src/components/TierBadge.tsx`)

```tsx
// Free Tier Badge
<Badge variant="outline" className="text-xs font-semibold uppercase tracking-wider text-muted-foreground bg-secondary/30">
  Free
</Badge>

// Pro Tier Badge
<Badge className="text-xs font-semibold uppercase tracking-wider bg-primary/10 text-primary border-primary/20 hover:bg-primary/20">
  Pro
</Badge>

// AI Coach Tier Badge
<Badge className="text-xs font-semibold uppercase tracking-wider bg-cyan-500/10 text-cyan-700 dark:text-cyan-400 border-cyan-500/20 hover:bg-cyan-500/20 shadow-none dark:shadow-[0_0_10px_-2px_#00F0FF]">
  AI Coach
</Badge>
```

---

### 6.3 Gamification: Streak Counter (`src/components/StreakCounter.tsx`)

```tsx
<div className="flex items-center gap-1.5 px-3 py-1.5 rounded-xl bg-orange-500/10 border border-orange-500/20 text-orange-500 font-bold shadow-none dark:shadow-[0_0_10px_-2px_rgba(249,115,22,0.5)]">
  <Flame size={18} className="animate-pulse" />
  <span>6</span>
</div>
```

---

### 6.4 Form Inputs (`src/components/ui/input.tsx`)

```tsx
<input 
  className="flex h-10 w-full rounded-xl border border-input bg-background px-3 py-2 text-sm ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50" 
/>
```
- Rounded corners: `rounded-xl` (`12px`)
- Background: Dynamic `bg-background` (Pure white in light mode, obsidian in dark mode)
- Focus Ring: `focus-visible:ring-2 focus-visible:ring-ring` (Black in light mode, Lime in dark mode)

---

### 6.5 Toggle Switches (`src/components/ui/switch.tsx`)

```tsx
<div className="relative inline-flex h-6 w-11 shrink-0 cursor-pointer items-center rounded-full border-2 border-transparent transition-colors">
  <span className="pointer-events-none block h-5 w-5 rounded-full bg-background shadow-lg transition-transform" />
</div>
```
- **Track (Unchecked):** `bg-border` (`#e5e5e5` light, `#1f1f1f` dark)
- **Track (Checked):** `bg-primary` (`#171717` light, `#D1FF4D` dark)
- **Thumb:** `bg-background` (`#ffffff` light, `#0a0a0a` dark)

---

### 6.6 Brand Logo Switching (`src/components/Logo.tsx`)

PragatiVeer implements responsive SVG logo rendering based on the active theme class:

```tsx
// In Logo.tsx
<Image
  src="/PragatiVeer_Logo/SVG_Logos/Rectangular_light_background.svg"
  alt="PragatiVeer"
  fill
  className="object-contain dark:hidden"
  priority
/>
<Image
  src="/PragatiVeer_Logo/SVG_Logos/Rectangular_dark_background.svg"
  alt="PragatiVeer"
  fill
  className="object-contain hidden dark:block"
  priority
/>
```
- **Light Mode:** Displays `Rectangular_light_background.svg` with dark and gold typography visible on white backgrounds.
- **Dark Mode:** Displays `Rectangular_dark_background.svg` with white and neon typography visible on obsidian backgrounds.

---

## 7. Animations & Micro-Interactions

| Animation Name | Keyframe Definition | Purpose / Usage |
| :--- | :--- | :--- |
| **`animate-gradient`** | Shifting background position `0% 50%` to `100% 50%` | Multi-color text gradients (`Re-engineered by AI`) |
| **`animate-marquee`** | Smooth horizontal translate `0%` to `-50%` | Student testimonial banner ticker |
| **`animate-shine`** | Angular light sweep (`skewX(-15deg)`) | Metallic sheen across cards and premium tier banners |
| **`animate-pulse`** | Continuous opacity wave (`opacity: 1` to `0.5`) | Streak flame icon, loading placeholders |
| **`animate-spin`** | 360-degree rotation | Circular spinners on page load and async buttons |
| **`bg-grid`** | 40px x 40px grid pattern in white/0.03 | Subtle architectural background grid across landing page |

---

## 8. Quick Reference Utility Classes Cheatsheet

| Visual Goal | Tailwind Classes |
| :--- | :--- |
| **Subtle Glass Card** | `bg-background/80 backdrop-blur-md border border-border rounded-2xl` |
| **Pro Tier Accent Text** | `text-yellow-600 dark:text-yellow-400 font-bold` |
| **AI Coach Accent Text** | `text-cyan-600 dark:text-[#00F0FF] font-bold` |
| **Active Nav Link (AI)** | `bg-cyan-50 dark:bg-[#00F0FF]/10 text-cyan-800 dark:text-[#00F0FF] font-semibold border border-cyan-300/60 dark:border-[#00F0FF]/20` |
| **Active Nav Link (Pro)** | `bg-yellow-50 dark:bg-[#00F0FF]/10 text-yellow-700 dark:text-[#00F0FF] font-semibold border border-yellow-300/60 dark:border-[#00F0FF]/20` |
| **Neon Cyan Drop Shadow** | `shadow-[0_0_15px_-5px_#00F0FF]` (Automatically suppressed in light mode) |
| **Neon Lime Drop Shadow** | `shadow-[0_0_15px_-5px_#D1FF4D]` (Automatically suppressed in light mode) |
| **CBT Option Hover** | `hover:border-primary/50 hover:bg-secondary/20 transition-all duration-200` |

---

*Document compiled and verified for PragatiVeer v2 — Production Release*