Book a call

WritingOperating model & teamsPart 2 of 4 in Running it day to day

Design system release notes and announcements: templates you can copy

Release notes are a design system's most-read documentation, and most are written for the people who built the change rather than the people who need it. Channels, timing and five templates you can copy.

On this pageWhy release notes matter
  1. Why release notes matter
  2. Write for the reader, not the change
  3. Channels: chat for attention, docs for record
  4. When to announce what
  5. Five templates you can copy
  6. Automate the boring part
  7. Common mistakes
  8. The short version
  9. Frequently asked questions
  10. Further reading

The short answer

Write design system release notes for the people who use the system, not the people who built the change. Every note answers three questions: what changed, why, and do I need to do anything? Put breaking changes first, label items New, Improved, Fixed and Breaking, add before-and-after images for anything visual, and link to the full record on your documentation site. Use separate templates for releases, breaking changes, deprecations, token updates and a monthly digest.

  • Chat is for attention; the documentation site is for record.
  • Announce breaking changes at least one release cycle ahead, ideally four to eight weeks.
  • Bundle small changes into the regular release post. Announcing everything trains people to mute you.

Why release notes matter

Release notes are a design system's most-read documentation. They're how most product teams find out what changed, whether it affects them, and what they need to do. Badly written ones are worse than none: they get skimmed, the one breaking change in them gets missed, and teams learn that the system "breaks things without warning".

An illustration: the rename nobody saw

The situation

The system team renames a prop in a major release. It's mentioned in the release notes, posted once in a busy channel on a Friday evening.

What goes wrong

Seven teams upgrade the following week and their builds break. Each team thinks it's alone; the support channel floods.

What works

A breaking-change notice four weeks ahead, direct messages to affected teams, a codemod, reminders, and extra office hours. Same change, no surprise.

Write for the reader, not the change

WRITTEN FOR THE BUILDERS

Refactored Button padding tokens

Accurate, and useless to anyone deciding whether to upgrade.

WRITTEN FOR THE USERS

"Buttons are now 4px taller. If you've placed buttons inside table rows, check they still fit."

Says what changed, what it affects and what to check.

  • Lead with what people will see or need to do, not with the implementation.
  • Put breaking changes first, then new things, then improvements, then fixes.
  • Add before-and-after images for anything visual.
  • Link every item to its documentation, migration guide or pull request.
  • Thank contributors by name. Recognition builds contribution.

Channels: chat for attention, docs for record

ChannelPurposeRules
#ds-announcementsReleases, breaking changes, deprecations, roadmap updatesOnly the system team posts; questions go to threads or #ds-help
#ds-helpQuestions and supportAnyone posts; answered within a working day
Monthly email digestA summary for people who don't live in chat, especially leadersOne email a month, short
Docs site: UpdatesThe permanent record of every changeEvery announcement links here
Separate channels by purpose. One channel for everything means important news scrolls away in minutes.

When to announce what

WhatWhen
Minor and patch releasesOn the regular release day, early in the week, never late on a Friday
Breaking change: first noticeAt least one release cycle ahead, ideally 4–8 weeks, with the migration guide ready
Breaking change: remindersOne week before, and on release day
DeprecationWhen marked deprecated; again at the halfway point; one week before removal
Monthly digestFirst week of each month
Critical fixesImmediately

Five templates you can copy

Templates make announcements faster to write and easier to read, because readers learn where to look. Here are ours, filled in with examples. Illustration

1. Release announcement

#DS-ANNOUNCEMENTS · EVERY RELEASE

Design system 4.6.0 is out · 14 October · Full notes →

New. Tag component, with status colours and an optional remove button. Figma and code.

Improved. Select now supports grouped options. Date picker can show week numbers.

Fixed. Dialog returns focus to the button that opened it. Toast no longer overlaps the side menu on small screens.

Do I need to do anything? No. Safe to update. Thanks to Arjun (Payments) and Meera (Reports) for their contributions.

2. Breaking change notice

FIRST NOTICE · 4–8 WEEKS AHEAD

BREAKING in 5.0 (planned 18 November): Button "kind" is renamed to "variant"

What's changing. The kind prop will be removed. Use variant, which works the same way and is available now in 4.6.

Why. Every other component uses variant. One name across the library is easier to learn.

Who's affected. Around 600 uses in 7 products. Champions in those teams have the list.

What to do. Run the codemod (one command, about 2 minutes), or change kind= to variant=. Migration guide →

Help. Extra office hours on 4 and 11 November. Questions in #ds-help.

3. Deprecation notice

WHEN MARKED DEPRECATED

Deprecated: Modal. Use Dialog instead. Removal in 6.0 (planned March)

What this means. Modal still works and gets critical fixes until March. Please don't use it in new work.

How to switch. Most uses can be switched automatically with the codemod. Guide with before-and-after examples →

Progress. 142 uses remaining across 5 products. Live count on the docs site →

4. Token update

WHEN TOKEN VALUES OR NAMES CHANGE

Token update in 4.7: secondary text is slightly darker

What's changing. color.text.secondary now points to neutral 700 instead of neutral 600, raising contrast from 4.25:1 (below the 4.5:1 minimum) to 5.99:1 on the default background.

What you'll see. Captions, helper text and timestamps look slightly darker everywhere. Before and after →

Do I need to do anything? No code changes. If you've hard-coded the old grey anywhere, the lint rule will now flag it.

5. Monthly digest

EMAIL · FIRST WEEK OF THE MONTH

Design system: October in 60 seconds

Shipped. Tag component; grouped Select; 9 fixes. Two contributions from product teams.

Coming up. 5.0 on 18 November (one breaking change, codemod ready).

Adoption. 68% of UI built with the system, up 4 points this quarter.

Help. Office hours every Tuesday, 11:00 and 17:00.

Automate the boring part

Generating a draft of the release notes from merged changes saves hours each release. Label pull requests (new, fix, breaking), let a script or an AI assistant group them into a draft, then have a person rewrite each line for the reader and decide what's breaking. Never publish the draft unedited; the judgement is the valuable part. See AI in design systems.

Common mistakes

Announcing too much

Posting every small change creates noise, people mute the channel, then miss the one breaking change. Bundle small changes into the release post.

Notes in one place only

A message in chat scrolls away. Every announcement links to a permanent page on the docs site.

No "do I need to do anything?"

The question every reader is asking. Answer it explicitly, even when the answer is "no".

Friday releases

Release early in the week, so the team is around to help when things go wrong.

The short version

  • Write for users: what changed, why, and what to do.
  • Breaking first; clear labels; before-and-after images; links to the record.
  • Chat for attention, docs for record, a monthly digest for leaders.
  • Announce breaking changes 4–8 weeks ahead, with reminders.
  • Automate the draft; keep a human for the judgement.

Frequently asked questions

How often should a design system release?

Every two weeks is a common rhythm for minor and patch releases. Bundle breaking changes into a few major releases a year.

Should design and code releases be announced together?

Yes, ideally with the same version number, so "4.6" means the same thing in Figma and in code.

Who should write release notes?

The engineer on the release rota drafts them; a system designer or lead edits for clarity and decides what counts as breaking.

Where should release notes live?

On an Updates page in your documentation site, newest first, with each chat announcement linking to it.

Further reading