Analytics Tracking (Internal Documentation)

Overview

Fathom analytics is implemented for user interaction tracking across the site using data-track attributes for robustness against design changes.

Tracked Events

Examples page (/examples/)

  • examples-search-used - First keystroke in search (tracked once per page visit)
  • examples-search-click - Click on a search result (only when search is active)
  • examples-sort-used - Sort button clicks (Title/Creator)
  • examples-filter-used - Tag filter checkbox changes

Example detail pages

  • example-opened - Example page loaded
  • example-source - Source link clicked
  • example-principle-clicked - Principle anchor link clicked
  • example-edit - “Edit this page” link clicked
  • example-breadcrumb - Breadcrumb link clicked
  • example-related - Related principles link clicked
  • nav-examples - Nav link to Examples clicked
  • nav-about - Nav link to About clicked
  • nav-contribute - Nav link to Contribute clicked
  • field-guide-nav - Field guide nav link clicked

Homepage

  • home-article - Latest article link clicked
  • footer-design-system - Design system link clicked
  • social-bluesky - Bluesky link clicked
  • social-twitter - Twitter/X link clicked
  • social-mastodon - Mastodon link clicked
  • social-linkedin - LinkedIn link clicked
  • social-instagram - Instagram link clicked
  • social-github - GitHub link clicked
  • social-website - Personal website link clicked

Field guide

  • field-guide-promo - Field guide promo card clicked (examples page)
  • field-guide-panel - Field guide promo panel clicked (example detail pages)

Field guide purchase buttons

  • field-guide-purchase-individual - Individual buy button clicked (Gumroad)
  • field-guide-purchase-team - Team buy button clicked (Gumroad)
  • field-guide-purchase-student - Student buy button clicked (Gumroad)
  • field-guide-cta-hero - Hero section CTA clicked
  • field-guide-cta-bottom - Bottom CTA clicked (field guide page)
  • field-guide-cta-sample - Sample chapter CTA clicked

Sample chapter

  • sample-opened - Sample chapter page loaded
  • sample-anchor-clicked - Sample chapter anchor link clicked

Email signups (tracked on success, not button press)

  • email-signup-success-inline - Inline signup form success
  • email-signup-success-footer - Footer signup form success

Implementation

Event Type Location
Examples page search/sort/filter js/index.js
Nav, example pages, source links, field guide assets/js/analytics.js
Email signup success assets/js/kit-signup.js

Naming Convention

Click events (clicking implied):

  • {context}-{element} format
  • Examples: nav-examples, example-source, field-guide-promo

Non-click events (action explicit):

  • {context}-{action} format
  • Examples: example-opened, email-signup-success

Special cases:

  • Anchor links keep “clicked” for clarity: example-principle-clicked, sample-anchor-clicked

Environment

  • Production only: jekyll.environment == 'production'
  • No tracking during local development
  • Privacy-first: Fathom doesn’t use cookies or collect personal data

Adding New Events

For click events: Add data-track="event-name" to any HTML element:

<a href="/page/" data-track="nav-page">Page Name</a>
<button data-track="button-clicked">Click me</button>

For page-specific tracking: Add inline with {% if jekyll.environment == 'production' %} wrapper:

{% if jekyll.environment == 'production' %}
if (typeof fathom !== 'undefined' && typeof fathom.trackEvent === 'function') {
  fathom.trackEvent('event-name');
}
{% endif %}

Field Guide Content (Development Only)

The following field guide content is hidden in production and only available during local development:

Hidden in Production

  • Field guide nav link - Hidden via {% if jekyll.environment != 'production' %} in _includes/nav.html
  • Field guide promo card on examples page - Hidden via {% if jekyll.environment != 'production' %} in _layouts/examples.html
  • Field guide promo panel on example detail pages - Hidden via {% if jekyll.environment != 'production' %} in _layouts/example.html

Accessible but Not Linked

  • Field guide page (/field-guide/) - Accessible if URL known, not linked in production
  • Sample chapter page (/samples/design-principles-in-practice/) - Accessible if URL known, not linked in production

For Launch

To launch field guide content:

  1. Remove {% if jekyll.environment != 'production' %} and {% endif %} wrappers from:
    • _includes/nav.html (nav link)
    • _layouts/examples.html (promo card)
    • _layouts/example.html (promo panel)
  2. Optionally add published: false to pages if they should remain completely hidden
  3. Update this documentation to include field guide events