web_docs/docs/development/homepage-redesign.md

metadata

sidebar_position: 8

Ground News-Style Homepage Redesign

Overview

The homepage has been redesigned to follow the Ground News pattern with trending topics, a featured hero story, and a news grid layout. This creates a more engaging, content-forward experience while maintaining search functionality.

What Changed

1. Trending Topics Bar

Two rows of trending topics at the top of the page with + icons to subscribe/follow:

First Row:

• World Press Freedom Day 📰
• Business & Markets 💼
• Artificial Intelligence 🤖
• Health & Medicine ⚕️
• Premier League ⚽
• Soccer ⚽

Second Row:

• Baseball ⚾
• Donald Trump 🏛️
• IPL 🏏
• Social Media 📱
• Trump Administration 🇺🇸
• "Follow Topics" button

Each topic:

• Has an emoji icon
• Shows + sign on hover
• Clickable to search that topic
• Professional pill-shaped design

2. Featured Hero Story

Large banner with:

• 1200x600px hero image with overlay
• Gradient background from black to transparent
• Large headline overlay (3-5xl text)
• Subtitle with context
• Category badge (top left)
• Hover effects (image opacity, text color)

Example:

Category: Civic Engagement
Title: "World Press Freedom Day: 43,726 Nonprofits Fighting for Transparency"
Subtitle: "How local journalism and civic organizations are tracking government decisions..."

3. Top Stories Grid

3-column responsive grid with 6 story cards:

• Small image (400x300px) for each story
• Topic badge overlay on image
• Story title (2-line max with line-clamp)
• Hover effects (shadow, scale, color change)

Topics covered:

• Artificial Intelligence
• Health & Medicine
• Sports & Recreation
• Social Media
• Business Development
• Government Transparency

4. Search Section (Moved Lower)

The original search interface is now in a collapsible section lower on the page:

• Still has both tabs (Search Topics, Find My Community)
• Maintains all functionality
• More subdued background (gray instead of white)
• Search-forward → Content-forward shift

Technical Implementation

New Icons Added

import {
  PlusIcon,      // For "subscribe/follow" buttons
  BellIcon,      // For "Follow Topics" button
  FireIcon       // For "Trending" indicator
} from '@heroicons/react/24/outline'

Data Structures

TRENDING_TOPICS array:

{
  name: string,      // "World Press Freedom Day"
  icon: string,      // "📰"
  category: string   // "Global"
}

FEATURED_STORY object:

{
  title: string,
  subtitle: string,
  image: string,     // URL to hero image
  category: string,
  link: string       // Internal route
}

TOP_STORIES array:

{
  title: string,
  topic: string,     // Displayed as badge
  image: string,     // 400x300px thumbnail
  link: string
}

Styling Features

1. Trending Bar:

   • bg-gray-50 border-b for subtle separation
   • Pill-shaped buttons with rounded-full
   • Hover state with border-primary-500

2. Hero Banner:

   • h-[500px] fixed height
   • bg-gradient-to-t from-black for text readability
   • group-hover:opacity-50 for image
   • group-hover:text-primary-300 for headline

3. Story Cards:

   • hover:shadow-lg for elevation
   • group-hover:scale-105 on images
   • line-clamp-2 for title truncation

Image Generation

New Script: scripts/media/generate_topic_images.py

Generates professional banner and square images for topics using Google Gemini AI.

Features:

• AI-powered color scheme generation
• Banner images (1200x600px)
• Square thumbnails (400x400px)
• Gradient backgrounds
• Smart text wrapping
• Batch processing

Usage:

# Single topic
python scripts/media/generate_topic_images.py --topic "World Press Freedom Day"

# Batch from file
python scripts/media/generate_topic_images.py --topics-file topics.txt

# Default trending topics
python scripts/media/generate_topic_images.py

Requirements:

• Google Gemini API key in .env: GEMINI_API_KEY=your_key
• Auto-installs: google-generativeai, pillow, requests

Output:

data/media/topics/
├── world_press_freedom_day_banner.png   (1200x600)
├── world_press_freedom_day_square.png   (400x400)
├── artificial_intelligence_banner.png
├── artificial_intelligence_square.png
└── metadata.json                         (color schemes, paths)

Color Scheme Generation

Gemini analyzes each topic and suggests:

• Primary color: Main gradient start
• Secondary color: Gradient end
• Text color: High contrast for readability
• Background color: Base tone
• Reasoning: Why these colors fit the topic

Examples:

• Politics: Professional blues (#2563EB) and reds
• Health: Calming greens and blues
• Technology: Modern purples (#7C3AED) and blues
• Sports: Energetic oranges and reds

Using Generated Images

Update Homepage Data

Replace placeholder Unsplash images with generated ones:

const FEATURED_STORY = {
  title: 'World Press Freedom Day...',
  image: '/images/topics/world_press_freedom_day_banner.png', // ← Use generated
  // ...
}

const TOP_STORIES = [
  {
    title: 'AI Policy Tracking...',
    image: '/images/topics/artificial_intelligence_square.png', // ← Use generated
    // ...
  }
]

Integration Steps

1. Generate images:

   cd /home/developer/projects/open-navigator
   source .venv/bin/activate
   python scripts/media/generate_topic_images.py
   

2. Copy to frontend:

   mkdir -p frontend/public/images/topics
   cp data/media/topics/*.png frontend/public/images/topics/
   

3. Update Home.tsx:

   • Change image URLs from https://images.unsplash.com/...
   • To /images/topics/{topic}_square.png or {topic}_banner.png

4. Rebuild:

   cd frontend && npm run build
   

Benefits

User Experience

1. Content Discovery: Users see trending topics immediately
2. Visual Engagement: Large hero image draws attention
3. Quick Navigation: Click topics to search instantly
4. Personalization: + buttons suggest following/subscribing
5. Familiar Pattern: Matches news aggregators users know

Technical Benefits

1. SEO: Content-forward design better for crawlers
2. Performance: Images lazy-load below fold
3. Flexibility: Easy to update trending topics
4. Branding: Custom generated images (no stock photo licenses)
5. Accessibility: High contrast, semantic HTML

Future Enhancements

Phase 2: Dynamic Content

• Pull trending topics from actual search data
• Featured story from latest government decisions
• Top stories from recent meeting minutes
• Real-time topic popularity tracking

Phase 3: Personalization

• User can follow/subscribe to topics
• Save "+ Follow" state to user preferences
• Customized feed based on followed topics
• Email/push notifications for followed topics

Phase 4: Advanced Image Generation

• Use Imagen 2 when available in Gemini API
• Real-time image generation on topic creation
• Video thumbnails from meeting recordings
• Animated topic badges (WebP/GIF)

Design Inspiration

Based on Ground News:

• Trending topics bar at top
• Large hero story with image overlay
• Grid of smaller story cards
• Clean, professional news aesthetic
• Content-first approach

Migration Notes

Breaking Changes

• None! Search functionality preserved
• Existing routes still work
• All components intact

Deprecations

• None

Backward Compatibility

• 100% compatible
• Search moved lower but fully functional
• All existing links work

Examples

Before (Search-First)

+----------------------------------+
| Open Navigator                    |
| Search box (prominent)            |
| Tabs: Search / Location           |
| Quick topic pills                 |
| Stats section                     |
+----------------------------------+

After (Content-First)

+----------------------------------+
| Trending: [Topic] [Topic] [+]     |
| [Topic] [Topic] [Topic] [+]       |
+----------------------------------+
| [HERO IMAGE WITH HEADLINE]        |
| Large featured story              |
+----------------------------------+
| Top Stories Grid                  |
| [img] [img] [img]                |
| Story Story Story                 |
+----------------------------------+
| Search Section (collapsible)      |
| Features Grid                     |
| Stats                             |
+----------------------------------+

Testing

Manual Tests

1. Trending Topics

   • Click each topic → should navigate to search
   • Hover → should show border/background change
   • • icon → should be visible

2. Hero Banner

   • Image loads correctly
   • Text is readable over image
   • Hover effects work
   • Link goes to correct search

3. Story Grid

   • All 6 stories display
   • Images load
   • Topic badges visible
   • Hover effects (shadow, scale)

4. Search Still Works

   • Both tabs functional
   • Location lookup works
   • Search results correct

Automated Tests

Build verification:

cd frontend
npx tsc --noEmit  # TypeScript check
npm run build     # Vite build

Deployment

HuggingFace Spaces

No changes needed! Same deployment process:

./packages/hosting/scripts/huggingface/safe-deploy.sh

The Docker build will include:

• Updated Home.tsx
• Generated topic images (if copied to frontend/public)
• All existing functionality

Local Development

./start-all.sh  # Starts all 3 services
# Visit http://localhost:5173

Resources

• Script: scripts/media/generate_topic_images.py
• README: scripts/media/README.md
• Component: frontend/src/pages/Home.tsx
• Icons: Heroicons 24 outline
• Images: Unsplash (placeholder) → Generated (production)

Questions?

See scripts/media/README.md for image generation details.