Skip to content

CLAUDE.md

Latest commit

 

History

History
141 lines (94 loc) · 5.36 KB

CLAUDE.md

File metadata and controls

141 lines (94 loc) · 5.36 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a static HTML website for a D3 Women's Basketball Statistics Warehouse. The site is hosted on GitHub Pages and provides basketball statistics across multiple pages with data visualization tables.

Architecture

  • Static Site: Pure HTML/CSS/JavaScript with no build process
  • Multi-page Structure: 12 pages total (index.html + page1-11.html)
  • Shared Components: Common navigation, styling, and JavaScript functionality across all pages
  • Mobile-first Design: Responsive navigation with hamburger menu for mobile devices

Key Files

  • index.html - Main landing page with sample team statistics
  • page1.html through page11.html - Individual statistics pages (Conference Stats, Team Rankings, etc.)
  • styles.css - Global CSS with responsive design and mobile navigation
  • script.js - JavaScript for mobile navigation, search/filter functionality, and active page highlighting
  • README.md - Basic project description

Page Structure

All pages follow a consistent structure:

  • Shared navigation header with logo and menu links
  • Mobile hamburger menu with overlay
  • Main content area with page-specific statistics tables
  • Shared footer
  • Common JavaScript functionality

Navigation System

  • Desktop: Horizontal navigation bar with all page links visible
  • Mobile: Hamburger menu that slides in from the right with overlay
  • Active Page: JavaScript automatically highlights the current page in navigation
  • Menu Behavior: Closes automatically when links are clicked or overlay is tapped

Table Functionality

Pages include interactive data tables with:

  • Search functionality to filter teams by name
  • Conference dropdown filter
  • Sticky headers and first columns for better data visibility
  • Responsive design for mobile viewing
  • "No results" message when filters return empty results

Development Workflow

Build System

This project uses a Node.js build system to generate HTML files from configuration:

  • Run npm run build to regenerate all HTML files from config/pages.json
  • The build system reads page configurations and generates corresponding HTML files
  • Always run the build after making changes to config/pages.json

Testing Changes

Since this is a static site, test changes by:

  1. Opening HTML files directly in a browser, or
  2. Using a local web server: python -m http.server 8000 or npx serve
  3. Testing mobile responsiveness using browser dev tools

Making Changes

  • Styling: Edit styles.css for visual changes
  • JavaScript: Edit script.js for interactive functionality
  • Page Configuration: Edit config/pages.json for page-specific content, columns, legends, and metadata
  • Content: NEVER directly edit generated HTML files (index.html, preseason_rankings.html, etc.) - they will be overwritten by the build system
  • Navigation: Update all HTML files when changing navigation structure

IMPORTANT: All page content, table columns, legends, and metadata should be modified in config/pages.json, not in the generated HTML files. The HTML files are automatically generated by the build system and any direct edits will be lost when the build runs.

Mobile Navigation

The mobile navigation system includes:

  • Hamburger icon that transforms into a slide-out menu
  • Aggressive hiding of hamburger during menu transitions to prevent visual glitches
  • Overlay system to close menu when clicking outside
  • Responsive design that switches between desktop and mobile layouts at 768px breakpoint

Common Tasks

Adding New Pages

  1. Create new HTML file following the structure of existing pages
  2. Update navigation links in ALL HTML files
  3. Ensure JavaScript handles the new page for active link highlighting

Modifying Table Data

  1. Edit the HTML table structure in the target page
  2. Ensure table maintains proper classes for styling and functionality
  3. Test search and filter functionality with new data

Updating Styles

  1. Edit styles.css for visual changes
  2. Test responsive behavior across different screen sizes
  3. Verify mobile navigation still functions properly

Deployment

This site is deployed via GitHub Pages, so changes pushed to the main branch are automatically deployed. No build process is required.

Code Documentation Best Practices

Add Comments on Tricky Parts

When working in this codebase, add code comments on tricky parts. This helps both you and future agents (including Claude) understand:

  • Why certain approaches were chosen
  • What edge cases are being handled
  • Why seemingly redundant code is actually necessary
  • Browser-specific workarounds or quirks
  • Complex logic that isn't immediately obvious

Comments should explain the why, not just the what.

Document Intent to Protect Against Misguided Refactors

When creating new files or making significant changes, add a section that explains the intent. This protects the work from misguided refactors by:

  • Clarifying the purpose of the file or feature
  • Explaining what problem it solves
  • Setting boundaries on when/how it should be used
  • Preventing well-intentioned but incorrect "improvements"

This is especially important for:

  • Configuration files
  • Design system documents
  • Build scripts
  • Complex CSS that might look "redundant" but serves a purpose