Changelog

The changelog component renders a filtered history from data/brand/changelog.yml. Use it when a page explains a system that changes over time and the reader benefits from knowing what changed, what is verified, or why the current state is trustworthy.

It is for system state, not routine page edits.

When to use#

• Use it on pages where recent decisions change how someone should interpret or use the guidance
• Filter by topic so each page shows only relevant history
• Keep entries short, dated, and factual; the detailed rationale belongs in the relevant page or ADR
• Reuse the shared component instead of maintaining manual changelog lists in Markdown

Good candidates#

• Foundations > Tokens: token pipeline status, Style Dictionary activation milestones, and generated category readiness
• Site implementation > Components: component standardization progress and when a pattern becomes reusable
• Site implementation > Quality checks: checks added, pending, deprecated, or promoted to blocking
• Site governance > Decision records: ADRs accepted and public guidance derived from them
• Foundations > Accessibility: baseline rules, implementation fixes, and verification tooling once that history becomes useful

Implementation#

The shortcode is brand-changelog; it reads localized entries from the brand changelog data file and passes them to the shared data-changelog partial.

{{< brand-changelog topic="tokens" >}}

Contract#

Accessibility#

• The component uses native <details> and <summary>, so its disclosure state and keyboard behaviour come from the browser
• The summary and checked-date message use the localized dataChangelog and dataChangelogChecked keys
• Each change date is a semantic <time> element; the grouped list remains readable when it is expanded

Avoid#

• Do not use it for every page update; it should explain meaningful system movement
• Do not duplicate an ADR in a changelog entry; link the page where the decision is explained
• Do not publish entries that are aspirational only; planned work belongs in a roadmap, ADR, or page section that clearly names it as future work