# Changelog design: make your updates worth opening
[Canonical HTML page](https://gradiently.design/guide/changelog-design)
A changelog people open is a run of short, dated cards on one ground, each with a link preview that says the same thing. Here is the page, the card and the sizes.
## The short version
- Changelog design is a public page of short entries, newest first, written for people who already use the product.
- One visual ground should run across the page header and every entry card, so a release is recognisable before anyone reads the version number.
- Each entry needs a version, a date written as YYYY-MM-DD in the page code, a one sentence title, and only the change groups that contain something.
- The share image for a changelog entry is 1200×630 pixels, with the title large and in the centre, on the same ground as the page.
- Design that card once. A spreadsheet of versions, dates and titles can fill the same layout for every later release.
**Changelog design** that gets opened uses one ground for the whole page: a header, then a short card for each release, newest first. Each card carries a version, a date and one sentence about what changed for the customer, and that same card is the 1200×630 image people see when the link is shared. Commit messages are for the team. This page is for the people who use the product.
## What a changelog page is for
Put the newest release at the top, with its own address, so a post or an email can point at that version. The post is a separate job, one line of news, as in an [announcement post](https://gradiently.design/guide/announcement-post-design). The changelog backs that line up with the date and the changes a customer would notice.
After launch this is the graphic a software company makes most often, and it does as much for [SaaS branding](https://gradiently.design/guide/saas-startup-branding) as the first hero. If each entry looks like a different product, the brand looks unfinished even when the shipping is steady.
A what's new page in the app can stop at the title and link to the full entry. Same ground, same words. Email the same title and the same link.
## The anatomy of one entry
One entry has a fixed reading order: version, date, title, then a few lines. The pictures here use Boardline, a fictional planning app, so you can judge the layout on its own.
| Part | What it holds | On the card |
| --- | --- | --- |
| Version | A number such as 2.4, or the ship date | Small label |
| Date | 2026-10-12 in code, 12 October 2026 for people | Beside the version |
| Title | The change in a customer's words | Largest line, centred |
| Groups | Added, Changed, Deprecated, Removed, Fixed, Security | Under the title. Skip empty groups. |
| Link | This entry's address | Same corner every time |
Five parts, in that order. If you need a sixth, the entry is trying to be a blog post.
> **Six groups, and skip the empty ones** Keep a Changelog files every line under Added, Changed, Deprecated, Removed, Fixed or Security. Show only headings with lines, and put Security or Removed first when someone may need to act. Hold unshipped lines under Unreleased until you name the version.
A changelog header, 1200 by 600, reading What changed in Boardline on a green gradient
The page header at blog banner size, 1200×600. The page name stays small. The promise of the page is the large line.
## One ground across the header and every card
The header and every entry card should wear the same ground. Colour, grain and the corner for the product name stay fixed. Only the words change, so a release is still recognisable in a chat full of other brands.
In Gradiently that ground is a Mark: colour, light and grain behind the header and every card. It can move its calmest area behind the words and pick light or dark type per line. Keep the title off the bright middle of the green, where letters vanish. More on that is in [text on a gradient](https://gradiently.design/guide/text-on-gradient).
- Pine ink: #06281c
- Deep pine: #0b3d28
- Board green: #0e7a4b
- Mint: #8ee0b0
- Mist: #d7f7e4
- Paper: #f4fbf7
Pine ink and deep pine for the header and for type, board green through the blend, mint and mist at the pale end, paper under the notes.
- Page header: `linear-gradient(160deg, #06281c 0%, #0e7a4b 55%, #8ee0b0 100%)`
- Entry card: `linear-gradient(145deg, #0b3d28 0%, #0e7a4b 50%, #d7f7e4 100%)`
- Page background: `linear-gradient(180deg, #f4fbf7 0%, #d7f7e4 100%)`
The header is the darkest, the entry card a step lighter, and the page behind the notes stays pale so the list is easy to scan.
## The share image for each release
When someone pastes the link, the preview is often all they see. Use the same card at 1200×630, the [Open Graph image size](https://gradiently.design/guide/open-graph-image-size) most platforms share. LinkedIn's link image is 1200×627, so one file covers both. Some chats crop toward a square: keep the title in the centre, with about 60 pixels of margin.
- Link preview 1200×630: 1200 × 630
- Centre crop 630×630: 630 × 630
- Page header 1200×600: 1200 × 600
- LinkedIn post 1200×1200: 1200 × 1200
- X post 1600×900: 1600 × 900
Design the link preview first. The centre square is what a cropped chat still shows. The page header is almost the same width.
A 1200 by 630 release card for Boardline 2.4 reading Comments stay with the card
Version as a label, the change as the only large line.
A 1200 by 630 release card for Boardline 2.5 reading Share a board with one link on the same green ground
Same size, ground and placement. Only the version, the date and the title change.
To build the image from the title, keep this layout and fill the words from the page. That is a [dynamic OG image](https://gradiently.design/guide/dynamic-og-images): one design, a new title each time. The tags belong in the HTML the server sends. The full set is in [Open Graph tags](https://gradiently.design/guide/open-graph-tags).
```html
```
Tags for one entry, plus the entry. The article id is the share address. og:image points at the 1200×630 card.
> **The image address has to be absolute** og:image needs a full https URL that loads with no login. A relative path, or a tag added by script after the page loads, is missed by most preview crawlers.
## Write the change in customer language
The largest line on the card is the only line many people read. Write it the way a customer would say it to a colleague. Bug fixes and improvements spends that space on nothing.
### Avoid
- Bug fixes and improvements
- Various updates
- Version 2.4.0 shipped
- We have been busy
### Do
- Comments stay with the card
- Share a board with one link
- CSV export leaves in March
- Sign-in patched: update today
- **Three to seven words** for what changed. The title is the result. The group line is the detail.
- **A readable date,** such as 12 October 2026, and 2026-10-12 on the [`time` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/time).
- **The version as a label.** Major for a break, minor for an addition, patch for a fix. The number is not the headline.
- **Security or Removed first** when that release has them. If something is deprecated, say when it goes.
- **Link a long guide** instead of pasting it, so the entry stays short.
## A card for every release, from one sheet
Do not redesign the card on release day. Design the 1200×630 card once, around the longest title you are willing to publish, then change only the version, the date and the title.
1. **Design the card once** Set the size to 1200×630. Small label for version and date, title large and centred, product name in a fixed corner, margins of about 60 pixels.
2. **Write one row per release** First row headings: version, date, title. Then one release per row. Use CSV, or TSV if a title contains a comma. Keep the file under 1 MB.
3. **Review every version** Connect each heading to the matching text and read every row. A title on three lines needs fewer words.
4. **Create the pages, then export** Each row becomes a page in that layout. Save a PNG at 1200×630 for og:image. One Undo removes a bad batch.
```text
version,date,title
2.5,2026-10-19,Share a board with one link
2.4,2026-10-12,Comments stay with the card
2.3,2026-09-28,CSV export leaves in March
```
Newest first, like the page. Grouped notes stay on the changelog, not in this sheet.
Gradiently's bulk create does this from one page plus a CSV or TSV: headings in the first row, a file up to 1 MB, every row reviewed, then one page per release. The spreadsheet stays in the browser, and one Undo removes the batch. Bulk create is part of Pro. The routine is in [bulk create from a spreadsheet](https://gradiently.design/guide/bulk-create-from-spreadsheet).
Those rows can also feed the week's posts: LinkedIn at 1200×1200, X at 1600×900, laid out again with [copy to sizes](https://gradiently.design/guide/copy-to-sizes). For a run of posts, use the same idea as [batch create social media content](https://gradiently.design/guide/batch-create-social-media-content): fixed layouts, lines written first, then the sizes.
## FAQ
### What should a changelog page include?
A header on one ground, then entries newest first. Each one has a version, a date, a customer-language title, its own address, and only the groups that have lines: Added, Changed, Deprecated, Removed, Fixed, Security.
### How long should a changelog entry be?
One sentence of about three to seven words on the card, then a few lines on the page, one change each. Link out when a change needs a guide.
### What size is a changelog share image?
1200×630 pixels. That is the Open Graph size most platforms use. Keep the title in the centre, because some apps crop the preview toward a square.
### Should every commit appear in the changelog?
No. Publish what a customer would notice: an addition, a change in behaviour, a removal, a fix or a security patch. Refactors and ticket numbers stay in the commits.
### How do I keep a year of releases looking like one product?
Keep one ground, one type scale and one corner for the name. Change only the version, the date and the title. In Gradiently, bulk create fills that card from a CSV or TSV, and it is part of Pro.