# CC Soccer — Look and Feel Strategy ## Overview Custom Drupal 11 theme (`ccsoccer_theme`) for the public-facing CC Soccer recreational league site. The theme provides the page shell (header, navigation, footer, layout) while the `ccsoccer` module retains feature-specific CSS for individual pages. --- ## Key Decisions | Decision | Choice | Rationale | |---|---|---| | Base theme | `false` (no parent) | Clean slate, no fighting inherited styles | | Admin theme | Claro (unchanged) | Admin pages stay on Claro; board members/TDs already familiar | | CSS framework | Vanilla CSS | Andrew's token system already provides a design system; Tailwind adds build complexity on shared hosting | | Design tokens | Move to theme from module | Theme owns the visual layer; module CSS references tokens via `var()` | | Base component styles | Move to theme from module | Same reasoning; buttons, cards, forms, badges defined globally | | Icons | Lucide (planned) | Lightweight SVGs, no build step | | Font | Inter (already in tokens) | Modern, clean, good readability | --- ## Architecture ### Who Owns What **Theme (`ccsoccer_theme`) owns:** - Design tokens (CSS custom properties) - Base component styles (buttons, cards, forms, badges) - Page layout (header, nav, content, footer) - Page-level templates (`page.html.twig`, `html.html.twig`) - Global typography, spacing, colors - Mobile-responsive page shell **Module (`ccsoccer`) owns:** - Feature-specific CSS (roster-builder, schedule-grid, group-management, etc.) - Feature-specific JS (drag-drop, face detection, etc.) - Feature-specific Twig templates (ccsoccer-group-manage, ccsoccer-my-registrations, etc.) - All controllers, forms, services, entities **Dependency:** Module CSS references tokens via `var(--token-name)`. Both the theme AND the module load tokens/base: - **Public pages:** Theme loads tokens globally + module loads them via library dependencies. Identical `:root` declarations, no conflict. - **Admin pages (Claro):** Theme doesn't load, so module's copy provides tokens. This dual-loading approach (Option B) ensures admin tools (roster builder, schedule builder, etc.) rendered via Claro still get proper styling. May revisit in a future pass — could mark admin routes with `_admin_route: TRUE` or find a cleaner single-source approach. ### Regions | Region | Purpose | |---|---| | `banner` | Announcements (game status, alerts) | | `header` | Logo + site branding + navigation menus | | `navigation` | Reserved for future use | | `highlighted` | Status/error messages | | `content` | Main page content (required by Drupal) | | `footer` | Footer logo, credits | No sidebar — all pages are full-width. ### Block Placement (Current) **Banner:** Status messages **Header:** Site branding (logo disabled, shows dev info), Main navigation, User account menu **Content:** Page title, Primary tabs, Secondary tabs, Primary admin actions, Breadcrumbs, Help, Main page content **Footer:** CC Soccer Footer Logo, Powered by Drupal **Disabled:** Search form (wide), Search form (narrow), Masquerade --- ## Public-Facing Pages (Theme Scope) These are the pages players/parents actually use: 1. **Homepage** — Welcome text, league cards (Coed Tuesday, Men's 35+, etc.) 2. **Season/Tournament pages** — Details + register button 3. **Checkout flow** — Commerce-driven, needs consistent styling 4. **My Registrations** — Active registrations list 5. **My Team** — Roster view 6. **My Schedule** — Game schedule 7. **Group Management** — Invite friends, accept invites 8. **My Account** — Profile, player picture 9. **Secondary:** My Credits, My Cart, Purchase Jerseys --- ## Implementation Plan ### Step 1 — Scaffold Theme ✅ COMPLETE - [x] Create `web/themes/custom/ccsoccer_theme/` directory - [x] `ccsoccer_theme.info.yml` — regions, `base theme: false` - [x] `ccsoccer_theme.libraries.yml` — loads tokens + base globally - [x] Copy `tokens.css` and `base.css` from module to theme ### Step 2 — Wire Up ✅ COMPLETE - [x] Remove `global-tokens` and `global-base` libraries from module's `ccsoccer.libraries.yml` - [x] Remove all `ccsoccer/global-base` and `ccsoccer/global-tokens` dependency references (~25 libraries) - [x] Enable theme: `drush theme:enable ccsoccer_theme` - [x] Set as default: `drush config-set system.theme default ccsoccer_theme` - [x] Verified module CSS still resolves `var()` references — tokens load from theme - [x] Placed blocks in new theme's regions ### Step 3 — Page Template and Regions ✅ COMPLETE - [x] `page.html.twig` — banner, header (logo + nav area), main content, footer - [x] `html.html.twig` — viewport meta, font loading - [x] `layout.css` — header flex layout, content max-width 1200px, footer dark bg, mobile responsive - [x] Disabled duplicate logo from Site Branding block ### Step 4 — Header / Navigation ← NEXT - [ ] Style menus as horizontal nav with dropdowns - [ ] Login/logout/my account links - [ ] Mobile hamburger menu - [ ] Move logo SVG into theme directory (cleanup — currently refs module path) - [ ] Review Site Branding block vs hardcoded logo approach ### Step 5 — Footer - [ ] Content TBD — contact info, links, copyright ### Step 6 — Homepage - [ ] Style league cards and welcome text - [ ] Investigate duplicate "Welcome to CC Soccer" title below cards ### Step 7 — Polish - [ ] Test all player-facing pages in new shell - [ ] Mobile testing (Chrome DevTools + ddev share) - [ ] Spacing, typography, visual rough edges - [ ] Self-host Inter font (currently Google Fonts, may be blocked by privacy settings) --- ## Cleanup Items - [ ] Move logo SVG from `modules/custom/ccsoccer/images/` into `themes/custom/ccsoccer_theme/images/` - ~~Remove original `ccsoccer-tokens.css` and `ccsoccer-base.css` from module~~ — KEEPING both copies. Module needs them for admin pages rendered via Claro - [ ] Decide: keep Site Branding block for dev info display, or move dev info into theme template - [ ] Investigate duplicate "Welcome to CC Soccer" page title --- ## What We're NOT Touching - Roster builder CSS/JS - Schedule builder CSS/JS - Any admin-facing pages (Claro handles those) - Module controllers or PHP logic - Existing Twig templates in the module --- ## Branch Strategy - All theme work on `theme/ccsoccer-theme` branch - Commit frequently (even WIP) before switching branches - Old branches cleaned up: `theme-generated-clean`, `feature/theme-redesign` deleted - Merge to main when theme is functional - **Important:** Before switching to main, run `ddev drush config-set system.theme default claro -y` to avoid broken site on main (main doesn't have theme files) - **Important:** Don't run `ddev drush cex` on this branch unless intentionally exporting theme config --- ## Andrew's Foundation Work (Reference) Commit `7381f13` — "UI modernization: design tokens, base styles, and enhanced UX (Phases 1 & 2)" - 118 CSS custom properties in `ccsoccer-tokens.css` - 767 lines of base component styles in `ccsoccer-base.css` - 14 feature CSS files tokenized (hardcoded values → `var()` references) - Mobile UX: sticky nav, 44px touch targets, backdrop-blur, animations - All non-breaking (CSS/JS only, no PHP/Twig changes)