better tracking

openspec/specs/analytics-umami/spec.md

@@ -23,6 +23,14 @@ Each emitted event MUST include enough properties to segment reports by platform
 
 All tracked clickable items MUST emit events with a unique, consistent set of data elements as defined by the site tracking taxonomy, including at minimum `target_id` and `placement`.
 
+The site MUST instrument tracked clickables using Umami's supported Track Events data-attribute method:
+- `data-umami-event="<event-name>"`
+- optional event data using `data-umami-event-*`
+
+For content-related links (clickables representing a specific piece of content), the site MUST also provide the following Umami event data attributes:
+- `data-umami-event-title`
+- `data-umami-event-type`
+
 #### Scenario: Emit outbound click event
 - **WHEN** a user clicks a non-CTA outbound link from the homepage
 - **THEN** the system emits an `outbound_click` event with a property identifying the destination domain
@@ -31,6 +39,10 @@ All tracked clickable items MUST emit events with a unique, consistent set of da
 - **WHEN** a user clicks an instrumented navigation link
 - **THEN** the system emits a click interaction event with `target_id` and `placement`
 
+#### Scenario: Content click includes title and type
+- **WHEN** a user clicks an instrumented content link (video, podcast episode, blog post/page)
+- **THEN** the emitted Umami event includes `title` and `type` properties via `data-umami-event-*` attributes
+
 #### Scenario: Uninstrumented clicks do not break the page
 - **WHEN** a user clicks an element with no tracking metadata
 - **THEN** the system does not throw and navigation/interaction proceeds normally

openspec/specs/blog-section-surface/spec.md

@@ -19,10 +19,20 @@ The site MUST provide a blog index page at `/blog` that lists WordPress posts as
 
 The listing MUST be ordered by publish date descending (newest first).
 
+Each post card MUST be instrumented with Umami Track Events data attributes and MUST include at minimum:
+- `data-umami-event`
+- `data-umami-event-target_id`
+- `data-umami-event-placement`
+- `data-umami-event-target_url`
+
 #### Scenario: Blog index lists posts
 - **WHEN** the cached WordPress dataset contains posts
 - **THEN** `/blog` renders a list of post cards ordered by publish date descending
 
+#### Scenario: Blog post card click is tracked
+- **WHEN** a user clicks a blog post card on `/blog`
+- **THEN** the click emits an Umami event with `target_id`, `placement`, and `target_url`
+
 ### Requirement: Blog post detail
 The site MUST provide a blog post detail page for each WordPress post that renders:
 - title
@@ -49,6 +59,12 @@ The blog section MUST render a secondary navigation under the header derived fro
 
 Selecting a category MUST navigate to a category listing page showing only posts in that category.
 
+Each secondary navigation link MUST be instrumented with Umami Track Events data attributes and MUST include at minimum:
+- `data-umami-event`
+- `data-umami-event-target_id`
+- `data-umami-event-placement`
+- `data-umami-event-target_url`
+
 #### Scenario: Category nav present
 - **WHEN** the cached WordPress dataset contains categories
 - **THEN** the blog section shows a secondary navigation with those categories
@@ -57,6 +73,10 @@ Selecting a category MUST navigate to a category listing page showing only posts
 - **WHEN** a user navigates to a category listing page
 - **THEN** only posts assigned to that category are listed
 
+#### Scenario: Category nav click is tracked
+- **WHEN** a user clicks a category link in the blog secondary navigation
+- **THEN** the click emits an Umami event with `target_id`, `placement`, and `target_url`
+
 ### Requirement: Graceful empty states
 If there are no WordPress posts available, the blog index MUST render a non-broken empty state and MUST still render header/navigation.
 

openspec/specs/interaction-tracking-taxonomy/spec.md

@@ -18,6 +18,12 @@ Every clickable item that is tracked MUST have a stable identifier (`target_id`)
 
 The identifier MUST be deterministic across builds for the same element and placement.
 
+The taxonomy MUST define namespaces for repeated UI surfaces. For the blog surface, the following namespaces MUST be used:
+- `blog.subnav.*` for secondary navigation links
+- `blog.card.post.<slug>` for blog post cards
+- `blog.pages.link.<slug>` for blog page listing links
+- `blog.post.*` / `blog.page.*` for detail page chrome links (e.g., back links)
+
 #### Scenario: Two links in different placements
 - **WHEN** two links point to the same destination but appear in different placements
 - **THEN** their `target_id` values are different so their clicks can be measured independently
@@ -30,14 +36,27 @@ Every tracked click event MUST include, at minimum:
 For links, the event MUST also include:
 - `target_url` (or a stable target identifier that can be mapped to a URL)
 
+For content-related links (clickables representing a specific piece of content), the event MUST also include:
+- `title` (human-readable content title)
+- `type` (content type identifier)
+
+The `type` value MUST be one of:
+- `video`
+- `podcast_episode`
+- `blog_post`
+- `blog_page`
+
 #### Scenario: Tracking a content card click
 - **WHEN** a user clicks a content card link
 - **THEN** the emitted event includes `target_id`, `placement`, and `target_url`
 
+#### Scenario: Tracking a content link includes title and type
+- **WHEN** a user clicks a content-related link that represents a specific content item
+- **THEN** the emitted event includes `target_id`, `placement`, `target_url`, `title`, and `type`
+
 ### Requirement: No PII in event properties
 The taxonomy MUST prohibit including personally identifiable information (PII) in event names or event properties.
 
 #### Scenario: Tracking includes only categorical metadata
 - **WHEN** tracking metadata is defined for a clickable item
 - **THEN** it contains only categorical identifiers (ids, placements, domains) and does not include user-provided content
-