Tabler Upgrade Guide Writer

Upgrade guides

One page per release that changes something a user has to touch in their own code. The pages live in docs/content/ui/getting-started/upgrade/, the index there lists them as cards, and the docs menu has an "Upgrade" group next to "Frameworks".

docs/content/ui/getting-started/upgrade/
  index.mdx   # "Upgrade" — intro + <DocsChildrenCards />, never lists versions by hand
  1-5.mdx     # "Upgrade to 1.5", order: 2
  1-6.mdx     # "Upgrade to 1.6", order: 1

A patch or minor release must not break anything (see the backward-compat skill), so its guide lists deprecations: what still works, what replaces it, and when it goes away. Say "deprecated" and "the old name still works", never "removed" or "gone", and check each claim with pnpm run check:compat. Breaking changes, with "you need to", belong to the guide of a major release. A release with nothing deprecated and nothing visible gets no page. Say so in the changelog instead.

1. Collect the facts first

The guide is only as good as the list of changes behind it. Never write it from memory or from the changelog summary alone.

1. Find the base commit: the chore: update versions commit of the previous release (git log --oneline --grep "update versions"), or the last release tag when tags exist.
2. Read every changeset in .changeset/*.md. The minor ones with "Removed", "Renamed", "Replaced" or "Updated" are the candidates.
3. Diff the things a user can depend on, from that base to HEAD:
   • Sass variables and functions: git diff <base> HEAD -- core/scss | grep -E '^[-+][$@]', then split into removed, added and changed. A variable that is removed from @use … with (…) is a compile error for the user, so every removed $var must be on the page.
   • Custom properties: look at core/scss/_props.scss and _root.scss for removed --* names. Remember the runtime prefix is --tblr-, and the sources are written without it.
   • JavaScript exports: git diff <base> HEAD -- core/js/tabler.ts core/js/src/*.ts | grep '^[-+]export'. A removed export, a renamed data attribute or a changed global breaks user code.
   • Third-party libraries: core/libs.json and core/package.json. A library that left dist/libs breaks every <script src="/dist/libs/…">.
   • Class names: git diff <base> HEAD -- core/scss | grep -E '^-\.[a-z]' for removed selectors, and the check-markup-classes baseline when it changed.
4. Read the docs diff of each PR (git show <sha> -- docs) — the component page usually already has the new usage, and the guide should agree with it word for word.
5. Verify every name you're about to print against the current source. A wrong attribute in a guide is worse than no guide.

2. Page skeleton

Copy the structure of the newest existing guide. The order is fixed so readers can compare releases:

---
title: Upgrade to 1.7
summary: Move a project from Tabler 1.6 to 1.7. …
description: Upgrade guide from Tabler 1.6 to 1.7 with all breaking changes, …
added-in: '1.7.0'
order: 1
related: [/ui/getting-started/upgrade/1-6, /ui/getting-started/customize]
---

Intro: how big the upgrade is and the two or three things most likely to bite.
Link to the previous guide for people more than one version behind.

## Overview             "If you… | You need to…" table, one row per change, links to sections
## Update the package   npm + CDN snippet with the exact version
## <One per change>     one section per breaking change: before/after, then what to do
## Sass changes         only for people compiling scss/ themselves: removed variables table,
                        removed functions, changed defaults
## Visual changes       not breaking, but visible: bullets with a bold lead
## What is new in 1.7   short bullet list with links to the component pages, then a changelog link

Rules for the body:

• Every breaking change gets a diff or a "1.6 / 1.7" pair of code blocks. A sentence without an example is not enough.
• Show the fix, not only the removal. "Removed $x" is half a row; "use $y" or "nothing, drop it" completes it.
• Removed Sass variables and functions go in a table, even when the section above already explains them. Readers grep the table.
• Deprecated aliases (.form-hint → .form-text) are listed under a "renamed" heading with "the old name still works", never among the breaking changes.
• The summary and description must not contain : — unquoted YAML breaks the build.
• Simple English, contractions allowed, no marketing. The write-docs skill has the tone rules.