better tracking

openspec/changes/archive/2026-02-10-better-tracking/specs/analytics-umami/spec.md

@@ -0,0 +1,36 @@
+## MODIFIED Requirements
+
+### Requirement: Custom event tracking
+When Umami is enabled, the site MUST support custom event emission for:
+- `cta_click`
+- `outbound_click`
+- a general click interaction event for all instrumented clickable items (per the site tracking taxonomy)
+
+Each emitted event MUST include enough properties to segment reports by platform and placement when applicable.
+
+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
+
+#### Scenario: Emit general click event for any clickable
+- **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/changes/archive/2026-02-10-better-tracking/specs/interaction-tracking-taxonomy/spec.md

@@ -0,0 +1,28 @@
+## MODIFIED Requirements
+
+### Requirement: Minimum required properties
+Every tracked click event MUST include, at minimum:
+- `target_id`
+- `placement`
+
+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`
+