Relevant source files

The following files were used as context for generating this wiki page: - [src/app/layout.tsx](https://github.com/wdhunter645/next-starter-template/blob/main/src/app/layout.tsx) - [src/app/globals.css](https://github.com/wdhunter645/next-starter-template/blob/main/src/app/globals.css) - [src/components/PageShell.tsx](https://github.com/wdhunter645/next-starter-template/blob/main/src/components/PageShell.tsx) - [tools/verify_v6_lock.sh](https://github.com/wdhunter645/next-starter-template/blob/main/tools/verify_v6_lock.sh) - [tests/homepage-structure.test.tsx](https://github.com/wdhunter645/next-starter-template/blob/main/tests/homepage-structure.test.tsx) - [src/app/page.tsx](https://github.com/wdhunter645/next-starter-template/blob/main/src/app/page.tsx)

# Core UI Components & Layouts ## Introduction The Core UI Components and Layouts represent the structural foundation of the Lou Gehrig Fan Club (LGFC) website. This system ensures strict design and navigation invariants across both public and authenticated FanClub areas. The architecture leverages Next.js App Router conventions combined with a centralized CSS variable system to maintain visual consistency and structural integrity. The primary goal of the layout system is to enforce the "v6 specification," which dictates specific section ordering, spacing, and component behaviors. This is governed by strict repository rules and automated verification scripts that prevent "design drift" during development. Sources: [README.md](), [context.md](), [tools/verify_v6_lock.sh:1-10]() ## Global Layout Architecture The application uses a Root Layout that wraps all pages, providing consistent branding and navigation elements. It integrates the global style system and ensures the proper vertical rhythm through specific utility divs. ### Structural Composition The root layout establishes a vertical stack consisting of the `SiteHeader`, a `topWhitespace` buffer, the page content, and the `Footer`. Sources: [src/app/layout.tsx:16-30]() ```mermaid flowchart TD Root[Root Layout] --> Header[SiteHeader] Root --> Buffer[topWhitespace Div] Root --> Content[Page Content /children/] Root --> Foot[Footer] subgraph Styles CSS[globals.css] Vars[variables.css] end Styles -.-> Root ``` The diagram shows the hierarchical structure of the global layout and its dependency on centralized style definitions. Sources: [src/app/layout.tsx:1-10](), [src/app/globals.css:1-50]() ### Design Tokens and CSS Variables The visual system is powered by CSS variables defined in `:root`. These tokens control colors, typography, spacing (rhythm), and layout constants. Sources: [src/app/globals.css:1-45]() | Category | Token Name | Value/Usage | | :--- | :--- | :--- | | Brand Colors | `--lgfc-blue` | Primary blue color (#0033cc) | | Layout Spacing | `--section-gap` | Standard vertical rhythm (2.5rem) | | Dimensions | `--header-h` | Fixed height for header (56px-64px) | | Typography | `--lgfc-font-size-h1` | Base size for primary headings (2rem) | | Utility | `.topWhitespace` | 8px height buffer under header | Sources: [src/app/globals.css:7-55](), [src/app/globals.css:260-262]() ## Page Structural Components ### PageShell Component The `PageShell` acts as a standardized wrapper for internal and admin pages, providing consistent titling and layout constraints. It accepts props for `title` and `subtitle` to render a standardized header block before the main content. Sources: [src/components/PageShell.tsx](), [src/app/admin/cms/page.tsx:128-132]() ### Navigation (Header & Mast) The navigation system is designed to be non-sticky to comply with specific v6 design requirements. The header is composed of three primary structural wrappers: left, center (nav), and right. Sources: [tools/verify_v6_lock.sh:105-125]() * **Mast:** Contains the logo and the mobile "hamburger" menu. * **Accessibility:** The hamburger menu must target the ID `hamburger-menu` via `aria-controls`. * **Buffer:** A `.topWhitespace` div is required immediately below the header usage to maintain spacing. Sources: [src/app/globals.css:118-140](), [tools/verify_v6_lock.sh:119-122]() ## Homepage Specification (v6) The homepage follows a rigid section order that is enforced by both end-to-end tests and unit tests. This ensures that major features like the "Weekly Matchup" and "Social Wall" appear in their mandated sequence. Sources: [tests/homepage-structure.test.tsx:15-25]() ### Mandatory Section Order The layout must follow this sequence exactly: 1. **Hero/Banner:** Contains the "Welcome to the Lou Gehrig Fan Club" H1. 2. **Weekly Matchup:** Uses the exact title "Weekly Photo Matchup. Vote for your favorite!" and the `.title-lgfc` class. 3. **Join/Login CTA:** Uses the `.joinBanner` wrapper and specific approved membership copy. 4. **Social Wall:** Renders external Elfsight embeds. 5. **Recent Club Discussions:** Member posts preview. 6. **Friends of the Fan Club:** Partnerships section. 7. **Milestones:** Historic timeline. 8. **Events Calendar:** Fan club events. 9. **FAQ:** Common questions and search. Sources: [tests/homepage-structure.test.tsx:90-115](), [tools/verify_v6_lock.sh:135-155]() ### Section Logic & Data Flow Sections often include complex client-side logic, particularly for dynamic data like FAQs or administrative previews. ```mermaid sequenceDiagram participant User participant FAQ as FAQSection Component participant API as CMS/FAQ API participant D1 as Cloudflare D1 User->>FAQ: Inputs search query FAQ->>API: GET /api/faq/list?q=... API->>D1: Query FAQ table D1-->>API: Results API-->>FAQ: JSON (ok: true, items: [...]) FAQ->>User: Renders updated list ``` The diagram illustrates the data flow for the FAQ component, which is a key part of the footer/homepage layout. Sources: [src/components/FAQSection.tsx:35-55]() ## Administrative Layouts Admin pages utilize specialized navigation (`AdminNav`) and a distinct grid-based layout for content management. These pages often feature a split-view or multi-column layout for editing CMS blocks. Sources: [src/app/admin/cms/page.tsx:142-150]() ### Content Editor Layout The CMS and content editors use a grid system to separate the list of available blocks from the active editing fields. Sources: [src/app/admin/cms/page.tsx:154-160]() ```javascript

{/* Blocks list sidebar */}

{/* Active Editor Fields */}

``` Sources: [src/app/admin/cms/page.tsx:154-200]() ## Layout Governance & Verification To prevent structural degradation, the repository includes a verification script (`tools/verify_v6_lock.sh`). This script audits the codebase for: * Presence of required global CSS tokens (e.g., `--lgfc-blue`). * Header non-stickiness and specific structural class names. * Correct usage of `.section-gap` (required on at least 5 sections on the homepage). * Correct Elfsight embed IDs in the Social Wall. Sources: [tools/verify_v6_lock.sh:88-100](), [tools/verify_v6_lock.sh:165-175]() ## Conclusion The Core UI Components and Layouts of the LGFC project are designed with a high degree of structural rigidity to preserve brand standards. By utilizing a centralized CSS token system and enforcing layout invariants through automated testing and shell scripts, the architecture ensures that the "v6 specification" remains intact across all environments and future modifications.