Civic Tech Waterloo Region

CivicTech Waterloo Region - Claude Code Project Guide

Project: CivicTechWR Jekyll Website Branch: perf/perf-improvements Last Updated: October 15, 2025 Tech Stack: Jekyll, HTML, CSS, JavaScript, Bootstrap 4.1.3 Current Branch: perf/bootstrap-optimization

Project Overview

CivicTechWR is a community organization website built with Jekyll. The site focuses on:

Live Site: https://civictechwr.org Primary Audience: Tech enthusiasts, designers, civic-minded individuals in Kitchener-Waterloo

Current Status & Known Issues

Critical Issues Identified (October 2025)

Performance Problems:

Code Quality Issues:

Style Inconsistencies:

Recent Audit Findings

See docs/AUDIT_REPORT.md for complete performance audit results.

Current Work in Progress (October 15, 2025)

✅ Completed - Foundation Fixes

The following critical fixes have been completed:

  1. Removed duplicate CSS definitions (commit a5d7ada)
    • Deleted .github-btn duplicate from css/pages/projects.css
    • Removed 3 CSS <link> tags from _includes/header.html (causing FOUC)
  2. Fixed hardcoded event dates (commit f8586db)
    • Replaced hardcoded Thursday dates with dynamic Wednesday calculation
    • Added getNextDayOfWeek() function in js/optimized-bundle.js
    • Regenerated minified bundle via npm run minify:optimized
  3. Removed 10.1KB of unused critical CSS
    • Deleted critical.css, critical-inline.css, critical-optimized.css
  4. Created unified meeting section component
    • Created _includes/meeting-section.html with parametrizable section_id
    • Replaced 162 lines of duplicate HTML across index.html, about.html, projects.html
  5. Created unified button system (staged, not yet committed)
    • Created css/components/buttons.css (380 lines, ZERO !important declarations)
    • Uses BEM methodology (btn–primary, btn–secondary, btn–outline, etc.)
    • Loaded in all 3 main HTML pages (index.html, about.html, projects.html)

🚧 In Progress - Button System Migration

Status: Foundation complete, HTML migration pending

Files staged for commit:

Remaining Work:

Step 1: Update HTML to use new BEM button classes

Use the web-design-specialist agent to systematically update button classes:

Migration mapping:

Files requiring updates (29 button instances total):

  1. index.html - 9 buttons (lines 110, 114, 115-117, 118, 199, 226, 227, 235, 252)
  2. about.html - 2 buttons (line 65)
  3. projects.html - 6 buttons (lines 66, 151, 195 - including 4 JavaScript-generated)
  4. _includes/header.html - 1 button (line 32)
  5. _includes/footer.html - 5 buttons (lines 11, 14, 28, 42, 43)
  6. _includes/meeting-section.html - 1 button (line 47)

Agent to use:

# Launch web-design-specialist to perform systematic button class updates
# The agent has already analyzed all files and created a detailed migration plan
# Ask it to execute the migration with exact search-and-replace operations

Step 2: Remove old button CSS from style.css

Use the code-reviewer agent to identify and remove legacy button definitions:

Old button classes to remove from css/style.css (17+ definitions with !important):

Expected results:

Step 3: Test all pages

Manual testing checklist:

Browser testing:

Step 4: Commit the complete button system

git add css/components/buttons.css index.html about.html projects.html _includes/header.html _includes/footer.html _includes/meeting-section.html css/style.css
git commit -m "feat: Consolidate 7 button systems into unified BEM system

- Create css/components/buttons.css with BEM methodology
- ZERO !important declarations (eliminates CSS specificity wars)
- Update all 29 button instances across 6 files to use new classes
- Remove 17+ old button definitions from style.css (~150-200 lines)
- Maintains visual parity with existing design
- Estimated 5-10KB CSS reduction

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>"

📋 Next Immediate Tasks

After button system completion, prioritize these tasks:

  1. Remove remaining !important declarations (~40-50 left in style.css)
    • Use code-reviewer agent to identify all instances
    • Fix specificity issues properly instead of using !important
  2. Standardize link colors (4 different schemes currently)
    • Audit all link styles in style.css
    • Consolidate to single color system using CSS variables
  3. Remove inline styles from index.html (180+ lines duplicating style.css)
    • Use web-design-specialist to identify duplicates
    • Move to appropriate CSS files or remove

Architecture

File Structure

ctwr-web/
├── _includes/           # Jekyll partials
│   ├── header.html     # Site navigation (✓ canonical)
│   └── footer.html     # Site footer (✓ canonical)
├── _data/              # YAML data files
│   ├── projects.yml    # Featured projects
│   ├── partners.yml    # Sponsor information
│   └── navigation.yml  # Navigation links
├── css/
│   ├── style.css       # Main styles (2,252 lines - needs optimization)
│   ├── critical.css    # Above-fold styles (has duplicates)
│   ├── bootstrap.css   # Bootstrap 4.1.3 (155KB - needs PurgeCSS)
│   └── [other CSS]
├── js/
│   ├── jquery.js       # jQuery 3.x (85KB - candidate for removal)
│   ├── custom.js       # Site interactions (31 lines)
│   └── meeting.js      # Meetup API integration
├── images/             # Site images (WebP + JPG fallbacks)
├── index.html          # Homepage
├── about.html          # About page
├── projects.html       # Projects listing
├── footer.html         # ⚠️ DUPLICATE - should be deleted
└── _config.yml         # Jekyll configuration

CSS Architecture

Current State (Problematic):

Recommended Structure:

css/
├── base/
│   ├── variables.css      # CSS custom properties
│   ├── reset.css          # Normalize/reset
│   └── typography.css     # Text styles
├── components/
│   ├── buttons.css        # Unified button system
│   ├── footer.css         # Footer styles
│   ├── header.css         # Navigation styles
│   └── cards.css          # Card components
├── layout/
│   ├── grid.css           # Layout system
│   └── sections.css       # Section spacing
└── style.css              # Main import file

CSS Custom Properties (Design Tokens)

Current Variables

:root {
  /* Brand Colors */
  --white-color: #fff;
  --primary-color: #FC6C6D;      /* Red/coral - accent */
  --secondary-color: #2D6F72;     /* Teal - brand primary */
  --dark-color: #000;
  --p-color: #717275;             /* Body text gray */

  /* Layout */
  --section-bg-color: #f9f9f9;
  --border-color: #e9eaeb;

  /* Typography */
  --body-font-family: 'DM Sans', sans-serif;
  --h1-font-size: 62px;
  --h2-font-size: 48px;
  --h3-font-size: 36px;
  --h4-font-size: 32px;
  --h5-font-size: 24px;
  --h6-font-size: 22px;
  --p-font-size: 18px;

  /* Weights */
  --font-weight-normal: 400;
  --font-weight-medium: 500;
  --font-weight-bold: 700;

  /* Border Radius */
  --border-radius-large: 100px;   /* Pills */
  --border-radius-medium: 20px;   /* Cards */
  --border-radius-small: 10px;    /* Buttons */
}

Missing Variables (Need to Add)

:root {
  /* Neutral Palette */
  --gray-900: #222;
  --gray-700: #444;
  --gray-600: #555;
  --gray-500: #666;
  --gray-400: #777;
  --gray-300: #999;
  --gray-200: #ccc;
  --gray-100: #eaeaea;
  --gray-50: #fafafa;

  /* Spacing Scale */
  --space-1: 4px;
  --space-2: 8px;
  --space-3: 12px;
  --space-4: 16px;
  --space-5: 24px;
  --space-6: 32px;
  --space-7: 48px;
  --space-8: 64px;

  /* Simplified Radius */
  --radius-sm: 4px;
  --radius-md: 12px;
  --radius-lg: 24px;
  --radius-full: 9999px;
}

Style Guidelines

Button System (Target Implementation)

Use BEM naming convention:

<!-- Primary button -->
<a class="btn btn--primary" href="#">Click Me</a>

<!-- Outline button -->
<a class="btn btn--outline" href="#">Learn More</a>

<!-- Light outline (on dark backgrounds) -->
<a class="btn btn--outline-light" href="#">Join Us</a>

<!-- Size modifiers -->
<a class="btn btn--primary btn--sm" href="#">Small</a>
<a class="btn btn--primary btn--lg" href="#">Large</a>

<!-- Full width -->
<a class="btn btn--primary btn--full" href="#">Full Width</a>

CSS Implementation:

/* Base button */
.btn {
  display: inline-block;
  padding: var(--space-3) var(--space-5);
  font-size: 1rem;
  font-weight: 500;
  border-radius: var(--radius-sm);
  border: none;
  text-align: center;
  text-decoration: none;
  cursor: pointer;
  transition: all 0.3s ease;
}

/* Variants */
.btn--primary {
  background: var(--secondary-color);
  color: var(--white-color);
}

.btn--primary:hover {
  background: var(--primary-color);
  transform: translateY(-2px);
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
}

.btn--outline {
  background: transparent;
  color: var(--secondary-color);
  border: 2px solid var(--secondary-color);
}

.btn--outline:hover {
  background: var(--secondary-color);
  color: var(--white-color);
}

Standard link behavior:

Spacing

Use spacing variables consistently:

Color Usage

Never hard-code colors - always use CSS variables:

/* ❌ Bad */
background: #2D6F72;
color: #666;

/* ✅ Good */
background: var(--secondary-color);
color: var(--gray-500);

Code Standards

CSS Best Practices

DO:

DON’T:

Specificity Guidelines

Avoid specificity wars:

/* ❌ Bad - specificity war with !important */
.btn {
  background: blue !important;
}

.btn.btn-primary {
  background: red !important;
}

/* ✅ Good - proper specificity hierarchy */
.btn {
  background: var(--gray-500);
}

.btn--primary {
  background: var(--secondary-color);
}

.btn--primary.btn--disabled {
  background: var(--gray-300);
}

HTML Best Practices

DO:

DON’T:

Performance Optimization Priority

Immediate Actions (High Impact)

  1. Replace Font Awesome with SVG sprites
    • Current: 320KB
    • Target: 5KB
    • Savings: 315KB (98%)
  2. Remove jQuery, use Vanilla JS
    • Current: 85KB
    • Target: 0.5KB
    • Savings: 84.5KB (99%)
  3. PurgeCSS on Bootstrap
    • Current: 155KB
    • Target: 35KB
    • Savings: 120KB (77%)
  4. Consolidate and minify CSS
    • Current: 85KB (style.css)
    • Target: 35KB
    • Savings: 50KB (59%)

Total Expected Savings: ~570KB (71% reduction)

Secondary Actions

  1. Optimize images (resize, compress, WebP)
  2. Remove Bootstrap JS (140KB)
  3. Implement critical CSS properly
  4. Remove inline styles from HTML

Total Potential Savings: ~724KB (90.5% reduction)

Development Workflow

Local Development

# Install dependencies
bundle install

# Run local server
bundle exec jekyll serve --livereload

# Build for production
JEKYLL_ENV=production bundle exec jekyll build

# Run smoke tests
bash scripts/smoke-tests.sh

Git Workflow

Branch Strategy:

Commit Message Format:

<type>: <description>

Examples:
feat: Add unified button system
fix: Remove duplicate footer implementation
perf: Replace Font Awesome with SVG sprites
style: Consolidate CSS duplicate selectors
docs: Update architecture documentation

Testing Checklist

Before pushing:

Common Tasks

Adding a New Button

<!-- Use unified button system -->
<a class="btn btn--primary" href="#">Primary Action</a>
<a class="btn btn--outline" href="#">Secondary Action</a>

Adding a New Page

  1. Create page-name.html in root
  2. Add YAML front matter: 
    ---
layout: null
permalink: /page-name/
---
  3. Use includes: ```html

Civic Tech Waterloo Region | All rights reserved


### Updating Colors

1. Modify CSS variables in `css/style.css`:
```css
:root {
  --secondary-color: #2D6F72; /* Update here */
}
  1. Never hard-code color values in CSS

Adding a Project

  1. Edit _data/projects.yml
  2. Add entry: 
    - name: "Project Name"
  url: "https://project-url.com"
  github: "https://github.com/org/repo"
  logo: "/images/projects/logo.png"
  year: 2025

Adding a Partner/Sponsor

  1. Edit _data/partners.yml
  2. Add entry: 
    - name: "Partner Name"
  logo: "/images/partners/logo.png"
  current: true  # false for previous partners

Key Files Reference

Primary HTML Files

Primary CSS Files

JavaScript Files

Data Files

Configuration

Known Dependencies

Jekyll (Ruby)

CSS Frameworks

JavaScript Libraries

Fonts

External APIs

Optimization Agents Available

From /tmp/claudepro-directory:

  1. code-reviewer-agent - For code quality reviews
    • Temperature: 0.4
    • Max tokens: 8000
    • Use for: Pre-commit reviews, architecture evaluation
  2. performance-optimizer-agent - For performance tuning
    • Temperature: 0.3
    • Max tokens: 4000
    • Use for: Core Web Vitals, bundle optimization, memory profiling
  3. web-design-specialist - For UI/UX improvements
    • Use for: Responsive layouts, visual design, CSS architecture

Next Steps (Priority Order)

Phase 1: Critical Fixes (Week 1)

  1. ✅ Code Review - Identify all style inconsistencies (COMPLETED)
  2. ✅ Remove duplicate code - Duplicate CSS, footer implementations (COMPLETED)
  3. 🚧 Consolidate 7 button systems into 1 unified system (IN PROGRESS - see “Current Work in Progress” section)
    • ✅ Created css/components/buttons.css with BEM methodology
    • ⏳ Update HTML to use new button classes (29 instances across 6 files)
    • ⏳ Remove old button CSS from style.css (17+ definitions, ~150-200 lines)
    • ⏳ Test all pages
    • ⏳ Commit complete button system
  4. Remove remaining !important declarations (~40-50 left after button cleanup)
  5. Standardize link colors across site (4 different schemes)

Phase 2: Performance (Week 2)

  1. Replace Font Awesome with SVG sprites (-315KB)
  2. Remove jQuery, convert to vanilla JS (-84.5KB)
  3. Run PurgeCSS on Bootstrap (-120KB)
  4. Optimize and compress images
  5. Remove inline styles from index.html

Phase 3: Code Quality (Week 3)

  1. Split style.css into component files
  2. Remove CSS duplication
  3. Implement proper critical CSS
  4. Add spacing and color variable systems
  5. Document component usage

Phase 4: Testing & Launch (Week 4)

  1. Cross-browser testing
  2. Mobile responsive testing
  3. Lighthouse audit (target: 90+ all categories)
  4. Memory profiling (target: <50MB Chrome)
  5. Production deployment

Resources

Documentation

Tools

Contact

Organization: CivicTech Waterloo Region Email: civictechwr@gmail.com Maintainers: See about.html for current organizers

Quick Start Guide for New Session

When starting a new conversation to continue this work:

Task: “Complete the button system migration using the web-design-specialist agent”

What will happen:

  1. Agent will update all 29 button instances across 6 HTML files to use new BEM classes
  2. You’ll need to manually test the pages (or ask for help testing)
  3. Use code-reviewer agent to remove old button CSS from style.css
  4. Commit the complete button system

Estimated time: 30-45 minutes

Option 2: Continue with Next Priority Task

Task: “Remove remaining !important declarations from style.css using the code-reviewer agent”

What will happen:

  1. Agent will identify all !important usage (should be ~40-50 instances after button cleanup)
  2. Agent will propose specificity fixes for each instance
  3. You’ll apply the fixes and test

Estimated time: 1-2 hours

Option 3: Run Full Site Audit

Task: “Run a comprehensive site audit using all available agents”

What will happen:

  1. Performance audit with performance-optimizer-agent
  2. Code quality review with code-reviewer-agent
  3. Design consistency check with web-design-specialist
  4. Consolidated report with prioritized action items

Estimated time: 45-60 minutes

Last Updated: October 15, 2025 Next Review: After button system completion

This site is open source. Improve this page.