blog umami fix

openspec/changes/blog-umami-fix/design.md

@@ -0,0 +1,44 @@
+## Context
+
+The site uses Umami for analytics. Most site clickables are instrumented using Umami’s data-attribute method (`data-umami-event` and optional `data-umami-event-*` properties) so events are recorded automatically on click.
+
+The Blog section was added recently and its clickables (post cards, category nav, page links) are not consistently emitting Umami events. This creates a measurement blind spot for the `/blog` surface.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Ensure all blog clickables emit Umami events using the documented data-attribute method.
+- Ensure every tracked clickable has a deterministic, unique `target_id` and includes at minimum `placement` and `target_url` per taxonomy.
+- Keep event names within Umami limits (<= 50 chars) and avoid sending event data without an event name.
+- Add tests to prevent regressions (blog pages/components should contain required Umami attributes).
+
+**Non-Goals:**
+- Introducing custom JavaScript tracking (`window.umami.track`) for v1; we will use Umami’s data-attribute method.
+- Adding new analytics providers or changing Umami initialization.
+- Tracking PII or user-generated content in event properties.
+
+## Decisions
+
+- **Decision: Use Umami-native data attributes on every blog clickable.**
+  - Rationale: Aligns with Umami’s “Track events” docs and the rest of the site’s tracking approach; avoids adding JS listeners that can interfere with other handlers.
+
+- **Decision: Use consistent event names by clickable type.**
+  - Rationale: Keeps reporting clean while still allowing segmentation via event properties.
+  - Proposed:
+    - `click` for internal navigation links (including blog category navigation)
+    - `outbound_click` for external links (if any in blog chrome)
+
+- **Decision: Add a deterministic `target_id` namespace for blog elements.**
+  - Rationale: Blog has many repeated elements; we need unique IDs that remain stable across builds.
+  - Proposed conventions:
+    - Blog header link: `nav.blog`
+    - Blog secondary nav: `blog.subnav.all`, `blog.subnav.pages`, `blog.subnav.category.<slug>`
+    - Blog post card: `blog.card.post.<slug>` (placement `blog.index` or `blog.category.<slug>`)
+    - Blog post detail back link: `blog.post.back`
+    - Blog page list links: `blog.pages.link.<slug>`
+
+## Risks / Trade-offs
+
+- [Risk] Some blog content areas render raw HTML from WordPress; links inside content are not instrumented. -> Mitigation: Track the blog chrome (cards/nav/back links) first; consider JS-based delegated tracking for content-body links in a future change if needed.
+- [Risk] Over-instrumentation adds noisy events. -> Mitigation: Keep event names simple, rely on `target_id` + `placement` for segmentation, and avoid tracking non-clickable elements.
+