better tracking

openspec/changes/archive/2026-02-10-blog-umami-fix/proposal.md

@@ -0,0 +1,26 @@
+## Why
+
+The Blog section’s click tracking is not firing reliably in Umami, which prevents measuring what users do in `/blog` and where they go next.
+
+## What Changes
+
+- Update the Blog section UI so every clickable element uses Umami’s data-attribute event tracking format:
+  - `data-umami-event="<event-name>"`
+  - `data-umami-event-*` attributes for event data
+- Ensure every tracked clickable item has a unique, deterministic set of event data elements (especially `target_id`, `placement`, `target_url`) so clicks can be measured independently.
+- Add verification/tests to ensure Blog clickables are instrumented and follow the same taxonomy as the rest of the site.
+
+## Capabilities
+
+### New Capabilities
+- (none)
+
+### Modified Capabilities
+- `blog-section-surface`: instrument blog clickables (post cards, post/page links, category secondary nav, blog header link) using Umami `data-umami-event` attributes.
+- `interaction-tracking-taxonomy`: extend/clarify tracking rules to cover blog-specific UI elements and namespaces for `target_id`.
+- `analytics-umami`: ensure the implementation adheres to Umami’s Track Events specification for data attributes.
+
+## Impact
+
+- Affected UI/components: blog pages and components under `site/src/pages/blog/` and `site/src/components/` (cards and secondary nav), plus any shared navigation link to `/blog`.
+- Testing: add/update tests to assert required Umami data attributes exist and are unique per clickable element in blog surfaces.