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.

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>

// 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:

/* 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)

<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)

<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])

// 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)

<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)

// 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)

<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)

<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)

<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:

// 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