plan.md

name	Stats dashboard redesign
overview	Revamp `/stats/` from plain tables into a wider, dark-theme dashboard with KPI cards and CSS bar charts—same data sources, visual mockup first for sign-off before any code.
todos	id content status mockup Generate static 16:9 dashboard mockup image; pause for visual sign-off completed id content status markup Rebuild stats.html markup into KPI cards, timeline, and bar sections (keep Vue 2 data wiring) completed id content status styles Add dashboard CSS (wider layout, cards, bar charts, status pill, responsive grid) using site CSS variables completed id content status ux-polish Add loading state, safer fetch handling, and count-descending sorts for bar sections completed id content status verify Smoke-check /stats/ locally against stats.json + live functions completed
isProject	false

Stats Dashboard Redesign

Current state

[src/misc/stats.html](src/misc/stats.html) is a Vue 2 page that loads /stats.json (build-time post metrics), /.netlify/functions/deploy-status, and /api/get-stats (Buttondown). Everything is plain tables inside the narrow .basic-page (800px) layout. No cards, no charts, almost no page-specific styling beyond the site’s dark green theme in [src/assets/css/styles.css](src/assets/css/styles.css).

Design direction (locked)

• Look: Dashboard within the existing dark / green brand (--dark-bg, --card-bg, --light-green, etc.)—not a new visual language.
• Depth: KPI cards + CSS percentage bars / sparklines. No chart library.
• Preview gate: After plan approval, generate a static mockup image and pause for visual sign-off before touching code.
• Scope: Same metrics and APIs; presentation and light UX polish only (loading state, wider layout). Keep Vue 2 + Moment for this pass to avoid a framework rewrite.

Target layout

flowchart TB
  subgraph header [Page header]
    Title[Stats]
  end
  subgraph kpi [KPI strip]
    Posts[Total Posts]
    Words[Total Words]
    Avg[Avg Words]
    Subs[Subscribers]
    Build[Build Status]
  end
  subgraph timeline [Timeline cards]
    First[First Post]
    Last[Latest Post]
  end
  subgraph activity [Activity]
    Weeks[Last 8 Weeks - horizontal bars]
    Years[Posts Per Year - horizontal bars]
  end
  subgraph taxonomy [Taxonomy]
    Cats[Categories - ranked bars]
    Tags[Tags - ranked bars]
  end
  subgraph yearly [Year explorer]
    Select[Year select]
    Combined[Combined cat/tag bars]
  end
  Title --> kpi --> timeline --> activity --> taxonomy --> yearly

Loading

Desktop (≈1100–1200px content width):

1. KPI strip — 5 metric cards in a responsive grid: Total Posts, Total Words, Avg Words/Post, Email Subscribers, Build Status (status pill + published time when ready).
2. First / Latest — two side-by-side cards with title link, date, and relative age.
3. Last 8 weeks — labeled horizontal bars (width: hits / max * 100%).
4. Posts per year — same bar pattern over the year list (newest or oldest first; default newest-first for scanability).
5. Categories | Tags — two columns of ranked bars (sort by count descending instead of A–Z so the dashboard reads as “top topics”).
6. Year explorer — year <select> + ranked bars for combined cat/tag stats.

Mobile: KPI grid collapses to 2 columns then 1; taxonomy stacks; bars remain full-width.

Visual language: use existing --card-bg surfaces, subtle borders (--border-color), green accent on bar fills and headings, large tabular numbers for KPIs. Escape the 800px .basic-page constraint with a page-specific wrapper (e.g. .stats-dashboard with max-width: 1100px) so it feels like a dashboard, not a blog article.

Visual preview (before code)

1. Generate one 16:9 mockup image matching the layout above and the site’s dark green palette.
2. You review / request tweaks.
3. Only after that: implement in the live page.

Implementation approach (after mockup OK)

Piece	Change
Markup	Replace tables in [src/misc/stats.html](src/misc/stats.html) with semantic dashboard sections + Vue bindings
Styles	Page-scoped CSS in the same file (or a small stats.css copied via Eleventy if preferred)—cards, grid, bar tracks/fills, status pill, loading skeleton
Layout	Override narrow page width for this route only
Logic	Reuse existing created / computed data; add maxWeekHits / maxYearHits (and similar) for bar widths; sort cats/tags/year-stats by size desc; add loading / graceful partial failure so one bad API doesn’t blank the page
Data	No changes to [src/misc/stats.ejs](src/misc/stats.ejs) or Netlify functions unless something is clearly broken

Out of scope for this pass: Vue 3 migration, new metrics (page views, etc.), Chart.js, redesign of unrelated site pages.

Success criteria

• /stats/ reads as a single cohesive dashboard on first scroll.
• All current metrics remain available.
• Bars make weekly/yearly/category volume scannable at a glance.
• Still works with existing /stats.json + functions under netlify dev.
• Matches site dark/green styling; no purple/cream AI-default look.