Changelog

We write release notes at four levels. Same change, different amount of detail depending on where someone lands. If you ship something users will notice, update every tier that applies.

The four tiers

Write top-down: nail the one-liner (tier 1), flesh it out in the monthly file (tier 2), add a row on the category index (tier 3), put the nitty-gritty on the component page (tier 4).

Tier 1 — Site overview

File: content/docs/changelog/index.mdx

Two sections. Recent releases holds the two newest months: one sentence each, links to anything worth calling out. All releases is a table of every month with a short highlight.

No component cards. No implementation notes. If someone only reads this page, they should know what month to open next.

### [June 2026](/docs/changelog/2026-06)
 
[Stacked Sections](/docs/scroll/stacked-sections), widget glance polish, and Card Stack API trim.
 
| Month | Highlights |
| --- | --- |
| [June 2026](/docs/changelog/2026-06) | Stacked Sections, widget polish, Card Stack trim |

New month file? Put it in Recent releases and bump the older of the two into All releases.

Tier 2 — Monthly release

File: content/docs/changelog/YYYY-MM.mdx (new file when the calendar month turns)

Frontmatter:

---
title: Month YYYY
description: One-line summary of the main themes.
date: YYYY-MM-01
---

Start with a short paragraph about what the month was about. Not a bullet list.

Then group entries:

• New components — <ChangeLogComponents> with one <ChangeLogEntry href="…"> per component
• Improved components — same for updates and fixes worth mentioning
• Documentation — optional; site-wide doc or infra stuff

Each entry gets an <h3> and one paragraph: what it is, when you'd reach for it, anything odd about the implementation. More than tier 1 or 3, less than tier 4.

Don't forget config/docs.ts under Changelog (newest month first).

Tier 3 — Category index

File: content/docs/{category}/index.mdx

Below <CategoryIndex />, add a Recent changes section. Table only.

Date is YYYY-MM, matching the monthly file you touched. Component links to the doc. Change is a short phrase; tier 4 has the rest.

Only rows for that category. New components and real updates both count. If the table gets stale after ~6 months, trim old rows or fold them into an "Earlier" note.

Tier 4 — Component doc

File: content/docs/{category}/{name}.mdx

## Changelog near the bottom, above Credits. Newest date first. Bullets, past tense. Mention tradeoffs when there are any.

## Changelog
 
### 2026-06-12
 
- Trimmed the public API to stack mechanics only (`CardStack`, `Viewport`, `List`, `Card`, `Trigger`). Profile card UI (masks, header, media, metrics) lives in the Storybook demo composition, not the registry bundle.
- Added `full` on `CardStack.Trigger`: default is a discrete `<button>`; `full` renders an absolute inset-0 overlay for click-anywhere advance.
- Fixed invalid markup from wrapping card flow content in a `<button>`.
 
### 2026-06-04
 
- Initial publish.

First publish can be just "Initial publish." You still want tier 3 and tier 4 once the component doc exists, even if tier 2 already covered the launch.

What warrants an entry

Writing style

Past tense. "Added X", not "We're excited to announce X." No emojis, no ✨ 🛠 🐛 prefixes.

Tier 2: say what the thing does and when you'd use it, not just its name. Tier 4: what changed, why, migration notes if someone has to do work. Registry URLs: https://animata.design/r/{category}/{name}.json when install matters. Not bare npx shadcn add component-name.

Checklist

Shipping a notable component change:

1. Tier 2 — entry in the current YYYY-MM.mdx (new month + config/docs.ts if needed)
2. Tier 1 — changelog/index.mdx if the summary or recent table is wrong now
3. Tier 3 — row on content/docs/{category}/index.mdx
4. Tier 4 — dated section on the component MDX