Release notes intro

The GitHub release body has two parts. The intro is hand-written in .github/release-notes/<version>.md (for example 1.6.0.md). The ## Core changes, ## Demo changes and ## Docs changes lists under it are generated by pnpm run release-notes from the CHANGELOG.md files. Never write those lists by hand, and don't repeat them in the intro. .github/release-notes/README.md explains the pipeline. Read it first.

A minor release always gets an intro. A patch release gets one only when it has something a user should hear about. Otherwise the generated lists are enough.

The workflow reads the intro from the commit it publishes, so the file must be on dev before the chore: update versions PR is merged. After the release, the body is never rewritten. A later fix has to be made by editing the release on GitHub.

1. Collect the facts

Never write the intro from memory.

1. Read every file in .changeset/*.md. The minor entries for @tabler/core are the candidates for headline features. The patch entries feed the smaller sections.
2. Check the milestone on GitHub (gh api repos/tabler/tabler/milestones) for closed PRs that have no changeset.
3. For each headline feature, read its docs page (summary, description and the ## headings in docs/content/ui/**). The intro should describe the feature the way the docs do, with the same class names, attributes and events.
4. Read the upgrade guide for this version (docs/content/ui/getting-started/upgrade/<x-y>.mdx). The ## Upgrading section in the intro summarizes it and links to it.
5. Before you print a class, an attribute, an event or a number (like the kB saved), check it against the current source.

2. Layout

The layout is fixed, so readers can compare releases. Copy the newest intro (1.6.0.md) and keep this order:

<picture> cover (light + dark) </picture>

One paragraph: "Tabler X.Y is out." + the three to five biggest things + a rough count of the rest.

## <Headline feature 1>          ← one section per headline feature
<picture> screenshot </picture>   ← the picture comes right after the heading, before the text
Two or three sentences on what it gives the user.

## <Headline feature 2>
…

---                               ← separator between the headline features and the rest

## <Other change group>           ← grouped smaller changes, no pictures, one short paragraph each
## Demo and docs
## Upgrading                      ← always last: what can break, what is deprecated, link to the guide

Rules:

• Every headline feature has its own ## section. Don't group eight components under one "New components" heading with bold leads. Each one gets a heading, a picture and its own text.
• A headline feature needs a picture. If there is none, the feature belongs below the separator, or you make the picture first (section 3).
• 2 to 4 sentences per feature. Say what it is, when you'd use it, and the one API detail people will look for (a class, a data-bs-* attribute, an event). Mention what it replaces or deprecates, for example "Litepicker is deprecated".
• Order the headlines by weight. Put the one people waited for first, and small helpers last.
• Below the separator, group by theme (colors, layout, performance, JS behaviour), not by package. Use one paragraph per group and no bullet dumps. The generated lists already have every item.
• ## Upgrading closes the intro. Say whether markup has to change, list what can break a build, list what is deprecated with its replacement, and link to https://docs.tabler.io/ui/getting-started/upgrade/<x-y>. It has to agree with the guide.

3. Images

All images live next to the intro and are named <version>-<slug>.png / <version>-<slug>-dark.png.

• Cover: <version>-cover.png and <version>-cover-dark.png, 1200×630. Check the size with sips -g pixelWidth -g pixelHeight <file>. The cover shows the release date, so re-export it if the release slips.
• Feature pictures: make them with the screenshots/ app (see the screenshots skill). Copy the 1x <slug>.png and <slug>-dark.png from screenshots/captures/ and rename them with the version prefix.
• Use a <picture> block for every image, so GitHub shows the dark one in dark mode:

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/tabler/tabler/dev/.github/release-notes/1.6.0-legend-dark.png">
  <img alt="Legend" src="https://raw.githubusercontent.com/tabler/tabler/dev/.github/release-notes/1.6.0-legend.png">
</picture>

• Link to the raw file on the dev branch, never on a tag. A tag like @tabler/core@1.6.0 has a slash, and raw.githubusercontent.com reads it as part of the path.
• The alt is the feature name, the same as the heading.
• The images must be pushed to dev before the release, or the published body shows broken images.

4. Tone

• Simple English, short sentences, contractions allowed. Write the way the write-docs skill asks.
• No marketing words: no "powerful", "seamless", "blazing", "game-changer" and no exclamation marks. Say what changed and what it does.
• Write to the user: "you can", "the sidebar folds now", not "we are excited to announce".
• Wrap code names in backticks: classes, attributes, events, variables and file paths.
• Give numbers when they're real: "about 110 kB came off tabler.min.css", "seven chart types".
• Run the humanize-text skill over the draft if it reads stiff.

5. Check the result

• git diff --check and a read-through in a Markdown preview in both color modes.
• Every image URL resolves once pushed: git cat-file -e origin/dev:.github/release-notes/<file> for each one.
• Every headline feature has a changeset, and every minor core changeset that adds a component or a page is mentioned somewhere in the intro.
• On dev, pnpm run release-notes builds the body from the working tree's version, so it prints the previous release without the new intro. To see the real body, run it on the bot's files. The steps are in .agents/agents/release-check.md, section 5.
• The release-check agent audits the intro as part of the pre-release checklist. Run it before the version PR is merged.

6. Checklist

• Facts come from the changesets, the milestone, the docs pages and the upgrade guide
• Cover in light and dark, 1200×630, with the right date
• One ## section per headline feature: heading, <picture>, 2–4 sentences
• --- separator, then the smaller changes grouped by theme
• ## Upgrading last, in line with the upgrade guide, linking to it
• Image URLs point to dev, files named <version>-<slug>[-dark].png
• On dev before the version PR is merged