diff --git a/API_DOCUMENTATION.md b/API_DOCUMENTATION.md index ca15ed9..8a0231f 100644 --- a/API_DOCUMENTATION.md +++ b/API_DOCUMENTATION.md @@ -5,8 +5,9 @@ > **Last Verified:** September 2026 > **Backend Engine:** FastAPI (Python 3.11) + SQLModel (SQLAlchemy) + Celery + Redis > **Frontend Engine:** Next.js 16 (React 19, TypeScript, TailwindCSS) -> **Database & Storage:** PostgreSQL 15 (PgBouncer connection pooler) + MinIO (S3-compatible) -> **Companion Document:** For page-by-page UI file locations, buttons, modals, and client API mapping, see [PAGEWISE_API_DOCUMENTATION.md](file:///c:/Users/naman/OneDrive/Desktop/pragativeer-v2/PAGEWISE_API_DOCUMENTATION.md). +> **Companion Documents:** +> - For page-by-page UI file locations, buttons, modals, and client API mapping, see [PAGEWISE_API_DOCUMENTATION.md](file:///c:/Users/naman/OneDrive/Desktop/pragativeer-v2/PAGEWISE_API_DOCUMENTATION.md). +> - For typography, fonts, color tokens, button variants, and light/dark mode styling, see [DESIGN_SYSTEM.md](file:///c:/Users/naman/OneDrive/Desktop/pragativeer-v2/DESIGN_SYSTEM.md). --- diff --git a/DESIGN_SYSTEM.md b/DESIGN_SYSTEM.md new file mode 100644 index 0000000..9541162 --- /dev/null +++ b/DESIGN_SYSTEM.md @@ -0,0 +1,376 @@ +# 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 ``) + +--- + +## 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[" 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 `` | +| **Student Dashboard & CBT Engine** | Light | `theme` | `ThemeToggle.tsx` | `.dark` on `` | +| **Admin Command Center** | Dark | `admin-theme` | `AdminThemeToggle.tsx` | `.dark` on `` | + +```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 + +``` +- **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 + +``` +- **Both Modes:** Bold, warm golden yellow (`#EAB308`) with black label. + +#### C. NTA CBT Examination Action Buttons (`/cbt/[examId]`) +```tsx +// Save & Next (Primary test progression) + + +// Mark for Review (Flagged question) + + +// Clear Response (Reset question) + + +// Final Submit Test (Header 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 + + + Title + Description + + Content + +``` +- **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 + + Free + + +// Pro Tier Badge + + Pro + + +// AI Coach Tier Badge + + AI Coach + +``` + +--- + +### 6.3 Gamification: Streak Counter (`src/components/StreakCounter.tsx`) + +```tsx +
+ + 6 +
+``` + +--- + +### 6.4 Form Inputs (`src/components/ui/input.tsx`) + +```tsx + +``` +- 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 +
+ +
+``` +- **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 +PragatiVeer +PragatiVeer +``` +- **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* diff --git a/PAGEWISE_API_DOCUMENTATION.md b/PAGEWISE_API_DOCUMENTATION.md index 473be03..c098fe1 100644 --- a/PAGEWISE_API_DOCUMENTATION.md +++ b/PAGEWISE_API_DOCUMENTATION.md @@ -5,6 +5,7 @@ > **Last Verified:** September 2026 > **Frontend Engine:** Next.js 16 (App Router, React 19, TypeScript, TailwindCSS, Zustand) > **Backend Engine:** FastAPI (Python 3.11) + PostgreSQL 15 (PgBouncer) + Redis 7 + MinIO S3 +> **Design Reference:** For full typography, color tokens, button variants, and light/dark mode design specifications, see [DESIGN_SYSTEM.md](file:///c:/Users/naman/OneDrive/Desktop/pragativeer-v2/DESIGN_SYSTEM.md). --- diff --git a/PAGEWISE_API_DOCUMENTATION.pdf b/PAGEWISE_API_DOCUMENTATION.pdf new file mode 100644 index 0000000..8005d13 Binary files /dev/null and b/PAGEWISE_API_DOCUMENTATION.pdf differ