CIA/e-voting-system/.claude/THEME_IMPLEMENTATION_GUIDE.md

E-Voting Frontend Theme Implementation Guide

Current Status

✅ Completed

• Tailwind CSS setup with dark theme
• ShadCN UI component library with custom colors
• Header component - fully themed with dark palette
• VoteCard component - fully themed with ShadCN
• Alert, Modal, Footer, LoadingSpinner - fully themed
• LoginPage - completely refactored with ShadCN components
• App name updated from "React App" to "E-Voting"
• All core infrastructure in place

⏳ Pending

• RegisterPage
• HomePage
• DashboardPage
• ActiveVotesPage, UpcomingVotesPage, HistoriquePage
• ArchivesPage, ElectionDetailsPage
• VotingPage
• ProfilePage
• ElectionDetailsModal

Dark Theme Palette

Color Variables (CSS Custom Properties)

--color-accent-warm: #e8704b    /* Primary accent */
--text-primary: #e0e0e0         /* Main text */
--text-secondary: #a3a3a3       /* Secondary text */
--text-tertiary: #737373        /* Muted text */
--bg-primary: #171717           /* Main background */
--bg-secondary: #171717         /* Card/secondary background */
--bg-overlay-light: rgba(255, 255, 255, 0.05)
--bg-overlay-dark: rgba(0, 0, 0, 0.8)

Semantic Colors

Success: #10b981
Warning: #f97316
Danger: #ef4444
Info: #3b82f6

Tailwind Color Classes

text-text-primary       → #e0e0e0
text-text-secondary     → #a3a3a3
text-text-tertiary      → #737373
bg-bg-primary          → #171717
bg-bg-secondary        → #171717
text-accent-warm       → #e8704b
border-text-tertiary   → #4a4a4a

Page Refactoring Checklist

RegisterPage (Similar to LoginPage)

// Use the same layout as LoginPage
// Replace className="auth-*" with Tailwind utilities
// Use ShadCN: Card, CardHeader, CardTitle, CardDescription, CardContent, Button, Input, Label, Alert
// Add form validation styling

Key Sections:

1. Left side: Registration form card
2. Right side: Benefits illustration (hidden on mobile)
3. Error/success alerts using ShadCN Alert

HomePage

// Hero section with gradient or accent color
// Features section with cards
// CTA buttons with proper styling

Key Sections:

1. Hero: Large heading, subtitle, CTA buttons
2. Stats: 3-4 stat cards showing system metrics
3. Features: Feature cards with icons and descriptions
4. How it Works: Step-by-step guide
5. CTA: Final call-to-action

Styling Pattern:

// Hero Section
<section className="bg-bg-primary min-h-screen flex items-center py-20">
  <div className="container">
    <div className="grid grid-cols-1 md:grid-cols-2 gap-12">
      <div className="flex flex-col justify-center">
        <h1 className="text-4xl md:text-5xl font-bold text-text-primary mb-6">
          Your Title
        </h1>
        <p className="text-xl text-text-secondary mb-8">
          Description
        </p>
        <div className="flex gap-4">
          <Button>Primary CTA</Button>
          <Button variant="outline">Secondary CTA</Button>
        </div>
      </div>
      <div className="hidden md:block">
        {/* Illustration or graphic */}
      </div>
    </div>
  </div>
</section>

// Feature Cards
<section className="bg-bg-primary py-20">
  <div className="container">
    <div className="grid grid-cols-1 md:grid-cols-3 gap-6">
      {features.map((feature) => (
        <Card key={feature.id}>
          <CardContent className="pt-6">
            <div className="text-3xl mb-4">{feature.icon}</div>
            <h3 className="text-lg font-semibold text-text-primary mb-2">
              {feature.title}
            </h3>
            <p className="text-text-secondary">
              {feature.description}
            </p>
          </CardContent>
        </Card>
      ))}
    </div>
  </div>
</section>

DashboardPage

// Stats grid at top
// Active votes section with VoteCard grid
// Upcoming votes section with VoteCard grid
// Historique section with VoteCard list

Key Sections:

1. Stats cards (Active, Future, Completed, Total)
2. "Active Votes" section with grid of VoteCard
3. "Upcoming Votes" section with VoteCard list
4. "Vote History" section with VoteCard list

Styling Pattern:

<div className="bg-bg-primary min-h-screen py-8">
  <div className="container">
    {/* Stats Grid */}
    <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-6 mb-12">
      {stats.map((stat) => (
        <Card key={stat.id}>
          <CardContent className="pt-6">
            <div className="text-3xl font-bold text-accent-warm">
              {stat.value}
            </div>
            <p className="text-text-secondary mt-2">{stat.label}</p>
          </CardContent>
        </Card>
      ))}
    </div>

    {/* Section */}
    <div className="mb-12">
      <h2 className="text-2xl font-bold text-text-primary mb-6">
        Active Votes
      </h2>
      <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
        {votes.map((vote) => (
          <VoteCard key={vote.id} vote={vote} />
        ))}
      </div>
    </div>
  </div>
</div>

ActiveVotesPage & UpcomingVotesPage

Similar to DashboardPage sections, but focused:

• Filter and search functionality
• All active/upcoming votes displayed as card grid
• Empty state when no votes

HistoriquePage

• List of completed elections
• Show user's vote choice
• Vote date display
• Results if published

ArchivesPage

• Public archives of all elections
• Card grid layout
• Search/filter functionality

ElectionDetailsPage

• Full election information
• Candidate list
• Results display
• Comments/discussion (if applicable)

VotingPage

• Large, focused voting interface
• Election details prominent
• Candidate/option selection interface
• Confirm and submit vote
• Confirmation message after voting

ProfilePage

• User information card
• Edit profile form
• Password change form
• Delete account option
• Activity history

ElectionDetailsModal

// Replace Modal component with ShadCN Dialog
// Show election details
// Show candidates
// Show results if published
// Show user's vote if applicable

Example:

import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogDescription } from '../lib/ui';

<Dialog open={isOpen} onOpenChange={setIsOpen}>
  <DialogContent className="max-w-2xl">
    <DialogHeader>
      <DialogTitle>{election.titre}</DialogTitle>
      <DialogDescription>{election.description}</DialogDescription>
    </DialogHeader>
    <div className="space-y-6">
      {/* Election details */}
      <div>
        <h4 className="font-semibold text-text-primary mb-2">Candidates</h4>
        <div className="space-y-2">
          {election.candidates.map((candidate) => (
            <div key={candidate.id} className="p-3 rounded-md bg-bg-overlay-light">
              {candidate.name}
            </div>
          ))}
        </div>
      </div>
    </div>
  </DialogContent>
</Dialog>

Common Styling Patterns

Background Sections

<section className="bg-bg-primary py-12 sm:py-16 lg:py-20">
  <div className="container">
    {/* content */}
  </div>
</section>

// With border
<section className="bg-bg-primary py-12 border-t border-b border-text-tertiary">
  <div className="container">
    {/* content */}
  </div>
</section>

Card Layouts

<Card className="border-text-tertiary">
  <CardHeader>
    <CardTitle className="text-text-primary">Title</CardTitle>
    <CardDescription>Subtitle</CardDescription>
  </CardHeader>
  <CardContent>
    {/* content */}
  </CardContent>
  <CardFooter>
    {/* actions */}
  </CardFooter>
</Card>

Button Groups

<div className="flex flex-col sm:flex-row gap-3">
  <Button variant="outline" className="flex-1">Cancel</Button>
  <Button className="flex-1">Save</Button>
</div>

// Horizontal buttons
<div className="flex gap-2">
  <Button size="sm" variant="ghost">Option 1</Button>
  <Button size="sm" variant="ghost">Option 2</Button>
  <Button size="sm" variant="default">Save</Button>
</div>

Grid Layouts

// 2-column responsive
<div className="grid grid-cols-1 md:grid-cols-2 gap-6">

// 3-column responsive
<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">

// Auto-fit
<div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-6">

Typography

{/* Heading 1 */}
<h1 className="text-4xl md:text-5xl font-bold text-text-primary mb-6">

{/* Heading 2 */}
<h2 className="text-3xl md:text-4xl font-bold text-text-primary mb-6">

{/* Heading 3 */}
<h3 className="text-2xl font-semibold text-text-primary mb-4">

{/* Heading 4 */}
<h4 className="text-lg font-semibold text-text-primary mb-2">

{/* Paragraph - primary */}
<p className="text-text-primary leading-relaxed">

{/* Paragraph - secondary */}
<p className="text-text-secondary leading-relaxed">

{/* Muted/tertiary */}
<p className="text-sm text-text-tertiary">

Form Styling

<div className="space-y-4">
  <div className="space-y-2">
    <Label htmlFor="field">Field Label</Label>
    <Input
      id="field"
      type="text"
      placeholder="Placeholder"
      className="bg-bg-secondary text-text-primary border-text-tertiary"
    />
  </div>

  {error && <p className="text-sm text-danger">{error}</p>}
  {success && <p className="text-sm text-success">{success}</p>}
</div>

Links

<Link to="/path" className="text-accent-warm hover:opacity-80 transition-opacity">
  Link Text
</Link>

// With underline
<Link to="/path" className="text-accent-warm underline hover:opacity-80 transition-opacity">
  Link Text
</Link>

Implementation Order Recommendation

1. LoginPage ✅ (Completed)
2. RegisterPage (Similar to LoginPage)
3. HomePage (High visibility, marketing)
4. DashboardPage (Central hub)
5. VotingPage (Core functionality)
6. ElectionDetailsModal (Used in multiple places)
7. Remaining pages (ActiveVotesPage, UpcomingVotesPage, etc.)
8. ProfilePage (Lower priority)

Color Accessibility

The theme uses:

• Contrast ratios: Text meets WCAG AA standards (at least 4.5:1)
• Semantic colors: Red/Green/Yellow for status (not color-blind unfriendly)
• Focus states: All interactive elements have visible focus rings (ring-2 ring-accent-warm)

Mobile-First Approach

Always use mobile-first Tailwind:

// Mobile by default, larger on screens
className="text-sm md:text-base lg:text-lg"      // Text size
className="grid grid-cols-1 md:grid-cols-2"      // Layout
className="px-4 md:px-6 lg:px-8"                 // Spacing
className="hidden md:block"                       // Visibility

Performance Tips

1. Use Tailwind utilities instead of custom CSS
2. Avoid inline styles - use className
3. Lazy load images when possible
4. Use Next.js Image component if upgrading to Next.js
5. Memoize expensive components with React.memo

Testing Theme

Once refactoring is complete:

# Build the project
npm run build

# Test locally
npm install -g serve
serve -s build

# Check on mobile (localhost:3000)

File Structure Reference

frontend/
├── src/
│   ├── lib/ui/                    # ShadCN components
│   │   ├── button.jsx
│   │   ├── card.jsx
│   │   ├── alert.jsx
│   │   ├── dialog.jsx
│   │   ├── input.jsx
│   │   ├── label.jsx
│   │   ├── badge.jsx
│   │   ├── dropdown-menu.jsx
│   │   └── index.js
│   ├── components/                # Reusable components
│   │   ├── Header.jsx             ✅ Themed
│   │   ├── Footer.jsx             ✅ Themed
│   │   ├── VoteCard.jsx           ✅ Themed
│   │   ├── Alert.jsx              ✅ Themed
│   │   ├── Modal.jsx              ✅ Themed
│   │   ├── LoadingSpinner.jsx     ✅ Themed
│   │   └── ElectionDetailsModal.jsx ⏳ TODO
│   ├── pages/                     # Page components
│   │   ├── LoginPage.jsx          ✅ Themed
│   │   ├── RegisterPage.jsx       ⏳ TODO
│   │   ├── HomePage.jsx           ⏳ TODO
│   │   ├── DashboardPage.jsx      ⏳ TODO
│   │   ├── ActiveVotesPage.jsx    ⏳ TODO
│   │   ├── UpcomingVotesPage.jsx  ⏳ TODO
│   │   ├── HistoriquePage.jsx     ⏳ TODO
│   │   ├── ArchivesPage.jsx       ⏳ TODO
│   │   ├── ElectionDetailsPage.jsx ⏳ TODO
│   │   ├── VotingPage.jsx         ⏳ TODO
│   │   └── ProfilePage.jsx        ⏳ TODO
│   ├── index.css                  ✅ Updated with Tailwind
│   └── App.css                    ✅ Updated with utilities
├── tailwind.config.js             ✅ Created
├── postcss.config.js              ✅ Created
└── public/index.html              ✅ Updated (E-Voting title)

Success Criteria

✅ All pages use dark theme colors ✅ All buttons use ShadCN Button component ✅ All cards use ShadCN Card component ✅ All alerts use ShadCN Alert component ✅ All inputs use ShadCN Input component ✅ No hardcoded colors (use CSS variables or Tailwind classes) ✅ Responsive on mobile, tablet, desktop ✅ Proper focus states for accessibility ✅ Proper contrast ratios for readability ✅ App name is "E-Voting" not "React App"

---

Last Updated: November 6, 2025 Status: Infrastructure complete, page refactoring in progress