astro-website/openspec/changes/archive/2026-02-10-custom-events-umami/tasks.md

1. Taxonomy Definition

• 1.1 Define the canonical event name(s) and required properties for click tracking (target_id, placement, target_url for links)
• 1.2 Document uniqueness rules and naming conventions for target_id (including namespaces for nav/cta/cards)
• 1.3 Add a short "instrumentation checklist" section for developers when adding new clickables

2. Core Tracking Implementation

• 2.1 Extend the centralized click handler to emit a general click interaction event for all instrumented clickables
• 2.2 Add support for required taxonomy properties (target_id, placement, target_url) on emitted events
• 2.3 Ensure uninstrumented clicks do not emit events and never throw (analytics disabled safe-path)
• 2.4 Keep existing cta_click and outbound_click semantics but align emitted properties with the taxonomy

3. Instrument All Clickables

• 3.1 Instrument nav links with taxonomy attributes (unique target_id, placement=nav)
• 3.2 Instrument content cards (newest/high-performing/podcast) with taxonomy attributes (unique ids per source + placement)
• 3.3 Instrument all CTA links to include stable unique target_id values per placement
• 3.4 Instrument other outbound links (section headers, buttons) with taxonomy attributes and outbound_click where applicable

4. Verification

• 4.1 Add/extend tests to validate taxonomy mapping (data attributes -> emitted event payload) for at least nav, CTA, and content-card clicks
• 4.2 Verify in staging Umami that click events show up with expected properties and are segmentable by placement and target_id