# 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)
```css
--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)
```jsx
// 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
```jsx
// 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:**
```jsx
// 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
```jsx
// 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:**
```jsx
<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
```jsx
// Replace Modal component with ShadCN Dialog
// Show election details
// Show candidates
// Show results if published
// Show user's vote if applicable
```

**Example:**
```jsx
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
```jsx
<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
```jsx
<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
```jsx
<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
```jsx
// 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
```jsx
{/* 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
```jsx
<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
```jsx
<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:
```jsx
// 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:

```bash
# 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