| 1 | # SquadScope Visual Redesign Proposal |
| 2 | |
| 3 | > **Archived (processed) — historical reference.** The original six-phase redesign plan in this document is implemented (issues #170–#177 closed). It is superseded by the newer modern look-and-feel handoff tracked in #357 (epic) and #327–#330 / #358. Retained for design history. |
| 4 | |
| 5 | **Date:** 2026-05-25 |
| 6 | **Author:** Calculon (Designer) |
| 7 | **Status:** Implemented / Archived (superseded by #357 and #327–#330, #358) |
| 8 | |
| 9 | --- |
| 10 | |
| 11 | ## Executive Summary |
| 12 | |
| 13 | SquadScope is an editorial publication delivering weekly GitHub trend analysis. The current PaperMod-derived theme treats it as a generic blog, missing the opportunity to create a distinctive editorial voice. This proposal establishes a visual direction that positions SquadScope as a credible, opinionated trend report — dense but readable, data-rich but not dashboard-like. |
| 14 | |
| 15 | --- |
| 16 | |
| 17 | ## 1. Design Principles |
| 18 | |
| 19 | 1. **Reading First** — Typography, spacing, and contrast optimize for long-form scanning. Every pixel serves comprehension. |
| 20 | |
| 21 | 2. **One Signal Per Glance** — Each content block delivers a single clear message. Metrics, headlines, and navigation don't compete for attention. |
| 22 | |
| 23 | 3. **Dense ≠ Cluttered** — Information density is a feature, not a bug. White space creates breathing room between dense blocks, not padding around sparse content. |
| 24 | |
| 25 | 4. **Light Touch on Decoration** — Let data and prose speak. Borders, shadows, and color accents are structural signals, not embellishments. |
| 26 | |
| 27 | 5. **Dark Mode Is Not Inverted Light Mode** — Each mode has intentional palette choices, not mechanical flips. |
| 28 | |
| 29 | --- |
| 30 | |
| 31 | ## 2. Visual Direction |
| 32 | |
| 33 | ### Chosen Lane: **Editorial Trend Report — Dense but Quiet** |
| 34 | |
| 35 | This is not a SaaS dashboard (no heavy data-viz chrome), not a news aggregator (no thumbnail grids), and not a traditional blog (no hero images, author avatars, social proof). It is a **weekly briefing document** that happens to live on the web. |
| 36 | |
| 37 | ### Reference Analysis |
| 38 | |
| 39 | | Site | Layout Pattern | Typography | Color | Fits SquadScope? | |
| 40 | |------|----------------|------------|-------|------------------| |
| 41 | | **GitHub Pulse** | Card-heavy, filter-first | System fonts, tight | Monochrome + accent | Partial — too dashboard-y | |
| 42 | | **TechCrunch** | Headline hierarchy, byline-heavy | Serif headlines, sans body | Purple accent | Partial — too news-feed | |
| 43 | | **Wired** | Magazine grid, large imagery | Bold sans headlines | High-contrast black | No — too image-dependent | |
| 44 | | **The Verge** | Dense feed, strong bylines | Chunky sans | Vibrant accents | Partial — too feed-like | |
| 45 | |
| 46 | **Synthesis:** Borrow from TechCrunch's headline hierarchy and reading rhythm, GitHub Pulse's monochrome discipline, and The Verge's willingness to be dense. Avoid Wired's image-dependence (SquadScope is text-first) and generic blog patterns. |
| 47 | |
| 48 | ### Resulting Aesthetic |
| 49 | |
| 50 | - **Typographic hierarchy** carries the design, not images or color |
| 51 | - **Monochrome foundation** with a single accent color |
| 52 | - **Compact metric displays** that inform without dominating |
| 53 | - **Clear article structure** with section dividers and consistent spacing |
| 54 | - **No stock imagery** — code blocks, pull quotes, and data callouts provide visual variety |
| 55 | |
| 56 | --- |
| 57 | |
| 58 | ## 3. Design Tokens |
| 59 | |
| 60 | ### 3.1 Color Palette |
| 61 | |
| 62 | #### Light Mode |
| 63 | |
| 64 | | Token | Hex | Use | WCAG AA on bg? | |
| 65 | |-------|-----|-----|----------------| |
| 66 | | `--bg` | `#FAFAFA` | Page background | — | |
| 67 | | `--surface` | `#FFFFFF` | Cards, elevated content | — | |
| 68 | | `--text` | `#1A1A1A` | Primary text | ✓ 15.3:1 on bg | |
| 69 | | `--text-muted` | `#5C5C5C` | Secondary text, metadata | ✓ 6.1:1 on bg | |
| 70 | | `--accent` | `#0066CC` | Links, interactive elements | ✓ 4.9:1 on bg | |
| 71 | | `--accent-hover` | `#004C99` | Link hover states | ✓ 7.2:1 on bg | |
| 72 | | `--accent-muted` | `#E6F0FA` | Accent backgrounds | — | |
| 73 | | `--border` | `#E0E0E0` | Dividers, card borders | — | |
| 74 | | `--danger` | `#CC3300` | Error states, warnings | ✓ 5.4:1 on bg | |
| 75 | | `--success` | `#1A8754` | Positive indicators | ✓ 4.6:1 on bg | |
| 76 | |
| 77 | #### Dark Mode |
| 78 | |
| 79 | | Token | Hex | Use | WCAG AA on bg? | |
| 80 | |-------|-----|-----|----------------| |
| 81 | | `--bg` | `#0D0D0D` | Page background | — | |
| 82 | | `--surface` | `#1A1A1A` | Cards, elevated content | — | |
| 83 | | `--text` | `#E8E8E8` | Primary text | ✓ 14.5:1 on bg | |
| 84 | | `--text-muted` | `#9C9C9C` | Secondary text, metadata | ✓ 7.3:1 on bg | |
| 85 | | `--accent` | `#4DA3FF` | Links, interactive elements | ✓ 7.8:1 on bg | |
| 86 | | `--accent-hover` | `#80BFFF` | Link hover states | ✓ 10.2:1 on bg | |
| 87 | | `--accent-muted` | `#1A2633` | Accent backgrounds | — | |
| 88 | | `--border` | `#2E2E2E` | Dividers, card borders | — | |
| 89 | | `--danger` | `#FF6B4A` | Error states, warnings | ✓ 6.8:1 on bg | |
| 90 | | `--success` | `#4ADE80` | Positive indicators | ✓ 9.2:1 on bg | |
| 91 | |
| 92 | ### 3.2 Typography |
| 93 | |
| 94 | #### Font Stack |
| 95 | |
| 96 | - **Headlines:** `"Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif` |
| 97 | - **Body:** Same as headlines (unified stack for editorial consistency) |
| 98 | - **Monospace:** `"JetBrains Mono", "Fira Code", "SF Mono", "Cascadia Code", monospace` |
| 99 | |
| 100 | #### Type Scale (rem, base 16px) |
| 101 | |
| 102 | | Level | Size | Line Height | Weight | Use | |
| 103 | |-------|------|-------------|--------|-----| |
| 104 | | `h1` | `2.25rem` (36px) | 1.2 | 700 | Page title | |
| 105 | | `h2` | `1.75rem` (28px) | 1.25 | 600 | Section headers | |
| 106 | | `h3` | `1.375rem` (22px) | 1.3 | 600 | Subsection headers | |
| 107 | | `h4` | `1.125rem` (18px) | 1.35 | 600 | Card titles | |
| 108 | | `body` | `1rem` (16px) | 1.65 | 400 | Prose | |
| 109 | | `small` | `0.875rem` (14px) | 1.5 | 400 | Metadata, captions | |
| 110 | | `tiny` | `0.75rem` (12px) | 1.4 | 500 | Labels, badges | |
| 111 | |
| 112 | #### Measure |
| 113 | |
| 114 | - **Prose max-width:** `68ch` (optimal reading measure) |
| 115 | - **Metric cards:** No max-width (fluid within grid) |
| 116 | |
| 117 | ### 3.3 Spacing Scale |
| 118 | |
| 119 | 8px-based scale for predictable rhythm: |
| 120 | |
| 121 | | Token | Value | |
| 122 | |-------|-------| |
| 123 | | `--space-1` | `0.25rem` (4px) | |
| 124 | | `--space-2` | `0.5rem` (8px) | |
| 125 | | `--space-3` | `1rem` (16px) | |
| 126 | | `--space-4` | `1.5rem` (24px) | |
| 127 | | `--space-5` | `2rem` (32px) | |
| 128 | | `--space-6` | `3rem` (48px) | |
| 129 | | `--space-7` | `4rem` (64px) | |
| 130 | |
| 131 | ### 3.4 Border Radius |
| 132 | |
| 133 | | Token | Value | Use | |
| 134 | |-------|-------|-----| |
| 135 | | `--radius-sm` | `4px` | Small buttons, badges | |
| 136 | | `--radius-md` | `8px` | Cards, inputs | |
| 137 | | `--radius-lg` | `12px` | Large containers | |
| 138 | | `--radius-full` | `9999px` | Pills, avatars | |
| 139 | |
| 140 | ### 3.5 Shadows |
| 141 | |
| 142 | | Token | Value | Use | |
| 143 | |-------|-------|-----| |
| 144 | | `--shadow-sm` | `0 1px 2px rgba(0,0,0,0.05)` | Subtle elevation | |
| 145 | | `--shadow-md` | `0 4px 6px rgba(0,0,0,0.07)` | Cards | |
| 146 | | `--shadow-lg` | `0 10px 15px rgba(0,0,0,0.1)` | Modals, dropdowns | |
| 147 | |
| 148 | Dark mode shadows use `rgba(0,0,0,0.3)` base for visibility on dark surfaces. |
| 149 | |
| 150 | --- |
| 151 | |
| 152 | ## 4. Layout Proposals |
| 153 | |
| 154 | ### 4.1 Home Page |
| 155 | |
| 156 | ``` |
| 157 | ┌────────────────────────────────────────────────────────────┐ |
| 158 | │ HEADER [ Logo ] Weekly | Monthly | Yearly | Search | ⚙ │ |
| 159 | ├────────────────────────────────────────────────────────────┤ |
| 160 | │ │ |
| 161 | │ ┌──────────────────────────────────────────────────────┐ │ |
| 162 | │ │ EYEBROW: Weekly tech signal from GitHub │ │ |
| 163 | │ │ │ │ |
| 164 | │ │ H1: SquadScope │ │ |
| 165 | │ │ │ │ |
| 166 | │ │ Subhead: Turns GitHub activity into readable │ │ |
| 167 | │ │ weekly, monthly, and yearly trend reports. │ │ |
| 168 | │ └──────────────────────────────────────────────────────┘ │ |
| 169 | │ │ |
| 170 | │ ┌─────────────────────────────────────────────────────┐ │ |
| 171 | │ │ SECTION TOPLINE: Latest report │ │ |
| 172 | │ │ │ │ |
| 173 | │ │ H2: [Article Title - full width, clickable] │ │ |
| 174 | │ │ │ │ |
| 175 | │ │ Summary paragraph (1-2 lines) │ │ |
| 176 | │ │ │ │ |
| 177 | │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌───────────┐ │ │ |
| 178 | │ │ │ Week │ │ Repos │ │ Stars │ │ Top Repo │ │ │ |
| 179 | │ │ │ 2026-22 │ │ 420 │ │ 16.5M │ │ perp/bee │ │ │ |
| 180 | │ │ └─────────┘ └─────────┘ └─────────┘ └───────────┘ │ │ |
| 181 | │ │ │ │ |
| 182 | │ │ [ Read Report → ] │ │ |
| 183 | │ └─────────────────────────────────────────────────────┘ │ |
| 184 | │ │ |
| 185 | │ ┌───────────────────┐ ┌───────────────────┐ │ |
| 186 | │ │ RECENT REPORTS │ │ QUICK LINKS │ │ |
| 187 | │ │ • W22 - Supply...│ │ Archive │ │ |
| 188 | │ │ • W21 - Agent... │ │ Monthly │ │ |
| 189 | │ │ • W20 - ... │ │ Tags │ │ |
| 190 | │ │ • W19 - ... │ │ RSS │ │ |
| 191 | │ └───────────────────┘ └───────────────────┘ │ |
| 192 | │ │ |
| 193 | ├────────────────────────────────────────────────────────────┤ |
| 194 | │ FOOTER [ GitHub ] [ RSS ] © 2026 jmservera │ |
| 195 | └────────────────────────────────────────────────────────────┘ |
| 196 | ``` |
| 197 | |
| 198 | **Key changes from current:** |
| 199 | - Remove 7-card navigation grid (overwhelming); replace with focused quick links |
| 200 | - Promote latest report to hero treatment |
| 201 | - Metric cards integrated with latest report, not separate |
| 202 | - Tighter hierarchy: eyebrow → h1 → subhead → content |
| 203 | |
| 204 | ### 4.2 Weekly Article Page |
| 205 | |
| 206 | ``` |
| 207 | ┌────────────────────────────────────────────────────────────┐ |
| 208 | │ HEADER [ ← Back to archive ] Weekly | Monthly | ... │ |
| 209 | ├────────────────────────────────────────────────────────────┤ |
| 210 | │ │ |
| 211 | │ EYEBROW: Weekly summary │ |
| 212 | │ │ |
| 213 | │ H1: Supply-Chain Scanners, Skills Economies, │ |
| 214 | │ and GitHub's Star-Farm Flood │ |
| 215 | │ │ |
| 216 | │ METADATA: May 25, 2026 · 12 min read · Week 22 │ |
| 217 | │ │ |
| 218 | │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌───────────────────┐ │ |
| 219 | │ │ Repos │ │ Stars │ │ Trends │ │ Top: perp/bumblebee│ |
| 220 | │ │ 420 │ │ 16.5M │ │ 4 │ │ 2,328 ⭐ │ |
| 221 | │ └─────────┘ └─────────┘ └─────────┘ └───────────────────┘ │ |
| 222 | │ │ |
| 223 | │ ┌─────────────────────────────────────────────────────┐ │ |
| 224 | │ │ JUMP TO: Trends | Industry | Signal | Blind Spots │ │ |
| 225 | │ └─────────────────────────────────────────────────────┘ │ |
| 226 | │ │ |
| 227 | │ ┌──────────────────────────────────────────────────────┐ │ |
| 228 | │ │ PRESS CONTEXT [TechCrunch badge] │ │ |
| 229 | │ │ 6 articles this week, most relevant: │ │ |
| 230 | │ │ "How founders inflate ARR metrics..." │ │ |
| 231 | │ └──────────────────────────────────────────────────────┘ │ |
| 232 | │ │ |
| 233 | │ ─────────────────────────────────────────────────────── │ |
| 234 | │ │ |
| 235 | │ H2: This Week's Trends │ |
| 236 | │ │ |
| 237 | │ Prose content with optimal measure (68ch)... │ |
| 238 | │ │ |
| 239 | │ [REPO CARD: perplexityai/bumblebee] │ |
| 240 | │ ├─ Description │ |
| 241 | │ ├─ 2,328 ⭐ · 181 forks · Go │ |
| 242 | │ └─ [ View on GitHub → ] │ |
| 243 | │ │ |
| 244 | │ More prose... │ |
| 245 | │ │ |
| 246 | │ ─────────────────────────────────────────────────────── │ |
| 247 | │ │ |
| 248 | │ H2: Signal & Noise │ |
| 249 | │ ... │ |
| 250 | │ │ |
| 251 | ├────────────────────────────────────────────────────────────┤ |
| 252 | │ POST FOOTER │ |
| 253 | │ Tags: [ supply-chain ] [ agent-skills ] [ ai-memory ] │ |
| 254 | │ ← Previous | Next → │ |
| 255 | ├────────────────────────────────────────────────────────────┤ |
| 256 | │ FOOTER │ |
| 257 | └────────────────────────────────────────────────────────────┘ |
| 258 | ``` |
| 259 | |
| 260 | **Key changes from current:** |
| 261 | - Article header with clear hierarchy (eyebrow, h1, metadata) |
| 262 | - Metric cards in compact row, not competing with title |
| 263 | - Jump-to navigation for long articles |
| 264 | - Press context callout styled distinctively |
| 265 | - Repo cards as first-class components (not just inline links) |
| 266 | - Clear section dividers (horizontal rules) |
| 267 | |
| 268 | ### 4.3 Monthly/Yearly Rollup Pages |
| 269 | |
| 270 | ``` |
| 271 | ┌────────────────────────────────────────────────────────────┐ |
| 272 | │ HEADER │ |
| 273 | ├────────────────────────────────────────────────────────────┤ |
| 274 | │ │ |
| 275 | │ EYEBROW: Monthly rollup │ |
| 276 | │ H1: May 2026 │ |
| 277 | │ SUBHEAD: 4 weeks covered · 1,680 repos featured │ |
| 278 | │ │ |
| 279 | │ ┌─────────────────────────────────────────────────────┐ │ |
| 280 | │ │ INCLUDED WEEKS │ │ |
| 281 | │ │ W19 · W20 · W21 · W22 │ │ |
| 282 | │ └─────────────────────────────────────────────────────┘ │ |
| 283 | │ │ |
| 284 | │ ─────────────────────────────────────────────────────── │ |
| 285 | │ │ |
| 286 | │ H2: Month in Review │ |
| 287 | │ Synthesized prose... │ |
| 288 | │ │ |
| 289 | │ H2: Top Repos This Month │ |
| 290 | │ [Repo cards in 2-column grid] │ |
| 291 | │ │ |
| 292 | │ H2: Emerging Themes │ |
| 293 | │ [Theme cards with sparkline-style indicators] │ |
| 294 | │ │ |
| 295 | ├────────────────────────────────────────────────────────────┤ |
| 296 | │ FOOTER │ |
| 297 | └────────────────────────────────────────────────────────────┘ |
| 298 | ``` |
| 299 | |
| 300 | --- |
| 301 | |
| 302 | ## 5. Component Specs |
| 303 | |
| 304 | ### 5.1 Header |
| 305 | |
| 306 | ``` |
| 307 | ┌─────────────────────────────────────────────────────────────┐ |
| 308 | │ [LOGO] SquadScope Weekly Monthly Yearly Search ⚙│ |
| 309 | └─────────────────────────────────────────────────────────────┘ |
| 310 | ``` |
| 311 | |
| 312 | **Specs:** |
| 313 | - Height: `64px` |
| 314 | - Logo: Site icon (28px height) + wordmark |
| 315 | - Navigation: Horizontal list, `--text-muted` default, `--text` on hover |
| 316 | - Active state: `--text` with `border-bottom: 2px solid var(--accent)` |
| 317 | - Theme toggle: Icon button, `24px` icon |
| 318 | - GitHub button (per issue #169): Icon-only button, right-aligned, `24px` icon |
| 319 | - Mobile: Hamburger menu at `<768px` |
| 320 | |
| 321 | ### 5.2 Article Header |
| 322 | |
| 323 | **Structure:** |
| 324 | 1. Eyebrow: Section label (`small`, `--text-muted`, uppercase, letter-spacing `0.05em`) |
| 325 | 2. H1: Title (`h1` token, `--text`) |
| 326 | 3. Subtitle/description: Optional (`body`, `--text-muted`) |
| 327 | 4. Metadata row: Date · Reading time · Week number (`small`, `--text-muted`) |
| 328 | |
| 329 | **Spacing:** |
| 330 | - Eyebrow to H1: `--space-2` |
| 331 | - H1 to subtitle: `--space-3` |
| 332 | - Subtitle to metadata: `--space-3` |
| 333 | - Metadata to metric cards: `--space-5` |
| 334 | |
| 335 | ### 5.3 Metric Cards |
| 336 | |
| 337 | ``` |
| 338 | ┌─────────────────┐ |
| 339 | │ LABEL │ ← small, --text-muted, uppercase |
| 340 | │ VALUE │ ← h3, --text, font-weight 600 |
| 341 | └─────────────────┘ |
| 342 | ``` |
| 343 | |
| 344 | **Specs:** |
| 345 | - Background: `--surface` |
| 346 | - Border: `1px solid var(--border)` |
| 347 | - Border-radius: `--radius-md` |
| 348 | - Padding: `--space-3` |
| 349 | - Min-width: `120px` |
| 350 | - Display: Flex row, gap `--space-3`, wrap on mobile |
| 351 | |
| 352 | **Wide variant** (for "Top repo"): |
| 353 | - Flex-grow: 1 |
| 354 | - Value is a link (`--accent` color) |
| 355 | |
| 356 | ### 5.4 Repo Card |
| 357 | |
| 358 | ``` |
| 359 | ┌─────────────────────────────────────────────────────────────┐ |
| 360 | │ owner/repo-name Go │ |
| 361 | │ Description text that can wrap to multiple lines if │ |
| 362 | │ needed but is truncated after 2 lines with ellipsis... │ |
| 363 | │ ⭐ 2,328 · 🔀 181 forks [ GitHub → ] │ |
| 364 | └─────────────────────────────────────────────────────────────┘ |
| 365 | ``` |
| 366 | |
| 367 | **Specs:** |
| 368 | - Background: `--surface` |
| 369 | - Border: `1px solid var(--border)` |
| 370 | - Border-radius: `--radius-md` |
| 371 | - Padding: `--space-4` |
| 372 | - Title: `h4` weight, `--accent` color (link) |
| 373 | - Language badge: `tiny`, `--accent-muted` background, `--radius-sm` |
| 374 | - Stats: `small`, `--text-muted` |
| 375 | - GitHub button: Secondary button style, right-aligned |
| 376 | |
| 377 | ### 5.5 Press Context Callout |
| 378 | |
| 379 | ``` |
| 380 | ┌─────────────────────────────────────────────────────────────┐ |
| 381 | │ 📰 TechCrunch Context │ |
| 382 | │ 6 articles this week. Most relevant correlation: │ |
| 383 | │ "How founders and VCs use inflated ARR metrics..." │ |
| 384 | └─────────────────────────────────────────────────────────────┘ |
| 385 | ``` |
| 386 | |
| 387 | **Specs:** |
| 388 | - Background: `--accent-muted` |
| 389 | - Border-left: `4px solid var(--accent)` |
| 390 | - Border-radius: `--radius-md` (right corners only) |
| 391 | - Padding: `--space-4` |
| 392 | - Title: `small`, `--text`, font-weight 600 |
| 393 | - Body: `body`, `--text-muted` |
| 394 | - Quote: `body`, `--text`, italic |
| 395 | |
| 396 | ### 5.6 Cost Dashboard |
| 397 | |
| 398 | **Current:** Shortcode rendering raw metrics. |
| 399 | |
| 400 | **Redesigned:** |
| 401 | - Contained card with border |
| 402 | - Clear section header |
| 403 | - Two-column grid: Token metrics | Cost summary |
| 404 | - Subtle accent treatment for "total cost" value |
| 405 | - Collapsible detail rows (model breakdown) |
| 406 | |
| 407 | ### 5.7 Footer |
| 408 | |
| 409 | ``` |
| 410 | ┌─────────────────────────────────────────────────────────────┐ |
| 411 | │ SquadScope — Weekly tech signal from GitHub │ |
| 412 | │ │ |
| 413 | │ GitHub · RSS · Archive │ |
| 414 | │ │ |
| 415 | │ © 2026 jmservera · Powered by Hugo │ |
| 416 | └─────────────────────────────────────────────────────────────┘ |
| 417 | ``` |
| 418 | |
| 419 | **Specs:** |
| 420 | - Background: `--surface` |
| 421 | - Border-top: `1px solid var(--border)` |
| 422 | - Padding: `--space-6` vertical |
| 423 | - Content: Centered, max-width matches content area |
| 424 | - Links: `--text-muted`, `--accent` on hover |
| 425 | - Copyright: `small`, `--text-muted` |
| 426 | |
| 427 | --- |
| 428 | |
| 429 | ## 6. Migration Strategy |
| 430 | |
| 431 | Phased rollout to ship value incrementally and minimize risk: |
| 432 | |
| 433 | ### Phase 1: Tokens + Typography Foundation |
| 434 | **Scope:** CSS custom properties, font stack, type scale |
| 435 | **Files:** New `assets/css/tokens.css`, updates to base styles |
| 436 | **Dependencies:** None |
| 437 | **Outcome:** Typography feels polished; colors unified |
| 438 | **Effort:** Small |
| 439 | |
| 440 | ### Phase 2: Header + Footer + Navigation |
| 441 | **Scope:** Redesigned header with GitHub button (#169), new footer |
| 442 | **Files:** `layouts/partials/header.html`, new `footer.html`, CSS |
| 443 | **Dependencies:** Phase 1 tokens |
| 444 | **Outcome:** Site chrome is consistent and distinctive |
| 445 | **Effort:** Medium |
| 446 | |
| 447 | ### Phase 3: Home Page Layout |
| 448 | **Scope:** Hero treatment, latest report card, quick links |
| 449 | **Files:** `layouts/index.html`, CSS |
| 450 | **Dependencies:** Phase 2 header/footer |
| 451 | **Outcome:** Entry point signals editorial quality |
| 452 | **Effort:** Medium |
| 453 | |
| 454 | ### Phase 4: Article Layout + Components |
| 455 | **Scope:** Article header, metric cards, repo cards, press callout, jump nav |
| 456 | **Files:** `layouts/weekly/single.html`, `layouts/monthly/single.html`, `layouts/yearly/single.html`, partials |
| 457 | **Dependencies:** Phase 1-3 |
| 458 | **Outcome:** Core reading experience transformed |
| 459 | **Effort:** Large |
| 460 | |
| 461 | ### Phase 5: Cost Dashboard Refresh |
| 462 | **Scope:** Redesigned cost dashboard shortcode |
| 463 | **Files:** `layouts/shortcodes/cost-dashboard.html`, CSS |
| 464 | **Dependencies:** Phase 1 tokens |
| 465 | **Outcome:** Financial transparency looks intentional |
| 466 | **Effort:** Small |
| 467 | |
| 468 | ### Phase 6: Icon + Favicon + Social Images |
| 469 | **Scope:** Site icon assets, OG image, apple-touch-icon |
| 470 | **Files:** `static/` assets, `hugo.toml` params |
| 471 | **Dependencies:** Phase 1 palette decisions |
| 472 | **Outcome:** Brand identity complete across all touchpoints |
| 473 | **Effort:** Medium |
| 474 | |
| 475 | --- |
| 476 | |
| 477 | ## 7. Accessibility Checklist |
| 478 | |
| 479 | - [ ] All color combinations meet WCAG AA contrast (verified in token table) |
| 480 | - [ ] Focus states visible on all interactive elements |
| 481 | - [ ] Skip-to-content link at page start |
| 482 | - [ ] Semantic heading hierarchy (no skipped levels) |
| 483 | - [ ] Reduced motion: Respect `prefers-reduced-motion` |
| 484 | - [ ] Link text is descriptive (no "click here") |
| 485 | - [ ] Keyboard navigation works for all interactive elements |
| 486 | - [ ] Images have alt text (where applicable) |
| 487 | |
| 488 | --- |
| 489 | |
| 490 | ## 8. Open Questions |
| 491 | |
| 492 | 1. **Font loading:** Include Inter from Google Fonts or use system stack only? (System stack recommended for performance.) |
| 493 | 2. **Syntax highlighting theme:** Adapt PaperMod's current theme to new palette or switch to a named theme? |
| 494 | 3. **Search styling:** Pagefind has its own styling; override or accept? |
| 495 | |
| 496 | --- |
| 497 | |
| 498 | ## Appendix: Figma-less Handoff Notes |
| 499 | |
| 500 | Since this proposal is specs-only (no Figma), Amy should: |
| 501 | 1. Implement tokens as CSS custom properties first |
| 502 | 2. Build components in isolation using the specs above |
| 503 | 3. Use browser dev tools to verify spacing/sizing against the spec |
| 504 | 4. Reference the live sites mentioned for edge cases |
| 505 | |
| 506 | --- |
| 507 | |
| 508 | *Proposal by Calculon · 2026-05-25* |