Backward compatibility

The README promises Semantic Versioning: breaking changes only land in major releases. Users install ^1.0.0 and expect npm update to be safe. Issue #3108 is what happens when it is not.

So on dev, which ships patch and minor releases, every change is additive or has an alias. A change that cannot be made compatible does not go to dev. It waits for the next major.

1. What is public API

Anything a user can write in their own project. If it is in the list, it cannot be removed, renamed or given a new meaning in a minor release.

Not public: anything under preview/, docs/, shared/, .build/, file layout inside core/scss/ that is not reachable through @use, private _underscore members of JS classes, and the exact bytes of the compiled CSS.

Bug fixes are fine even when they change rendering, as long as the old behaviour was clearly wrong (a knob that did not move in RTL).

Visual changes are allowed in a minor release

How Tabler looks is not frozen by semver. A minor release may change a color, a shadow, a spacing, a font, the shape of the focus ring or the default gray palette, the same way 1.5 moved to system fonts. The maintainers decided this on 2026-09-21. It holds as long as all of these are true:

• Nothing the user wrote stops working. The markup, the classes, the custom properties and the Sass variables they use still exist and still do their job. A redesign that renames or removes one is a rename or a removal, and needs an alias.
• An old token that the user set is still honoured. When the focus ring became an outline, --tblr-btn-focus-box-shadow stopped being read. That part was a break, and _deprecated.scss draws the shadow again. Changing the default look is fine; ignoring the user's override is not.
• No layout a project depends on moves. A different gray is visual. A component that is suddenly taller, or position: absolute where it was in the flow, breaks the pages built around it.
• Behaviour is not "visual". What a click does, when an animation starts, which drag image the browser uses: those are behaviour defaults, and stay opt-in until the next major.
• It is listed. Every visible change gets a bullet under "Visual changes" in the upgrade guide and a changeset that names it, so a user who sees a difference after updating can find out why. When the old look is cheap to keep, say how: a variable to set, or a theme in tabler-themes.css.

check:compat and check:compat-fixture do not look at pixels, so this rule is on the author and the reviewer.

2. Where compatibility code lives

Everything kept only for old projects goes into files named deprecated, so that the next major removes it by deleting files instead of digging through the tree. The Sass module system decides how many files that is:

$enable-deprecated: true !default lives in _variables.scss, next to $enable-deprecation-messages. A project that has migrated sets it to false and gets about 1.4 kB (gzip) back; the next major flips the default, and the one after deletes the files.

A hook must not change a project that never used the old token. Give var() the value the element has anyway as its fallback, not none, and check it in the browser: .btn:focus-visible { box-shadow: var(--btn-focus-box-shadow, none) } would strip the shadow from every focused button.

Some compatibility cannot move into those files: a fallback inside a component rule (mask-image: var(--form-check-bg-image, <default>)), an old parameter in a mixin signature, a default value that was put back. Mark each of those where it is, with one fixed comment:

// deprecated(2.0): `$show-border` is the old name of `$offset`

grep -rn "deprecated(2.0)" core/ .build/ plus the five files is then the full list of what the next major removes.

3. How to make the change compatible

Rename

Ship both names. The old one becomes an alias that nobody has to touch.

• Class: add the alias to core/scss/_deprecated.scss with @extend. Start the comment with `<old>` is deprecated, use `<new>` instead.
• Custom property: keep reading the old name as a fallback — var(--new, var(--old, <default>)) — or keep emitting the old one with the same value.
• Sass variable: move the old variable to _variables-deprecated.scss with its old default. If it maps onto a new token, feed it from _deprecated.scss: @if $input-btn-focus-width != 0.25rem { :root { --focus-ring-width: #{$input-btn-focus-width}; } }. For a map key, accept both keys.
• Mixin or function: a removed one comes back in mixins/_deprecated.scss as a wrapper. For parameters, add new ones at the end, with defaults. Never rename or move an old parameter: callers pass arguments by position and by keyword, so it keeps both its name and its place.
• Data attribute, option, JS export, event: accept or fire both. The data-bs-* / data-tblr-* pair in core/js/src/bootstrap/dom/manipulator.ts is the pattern.

Remove

Do not. Mark it deprecated, stop using it in Tabler's own code, keep it working, and list it for removal in the next major. This includes things that look dead: a declaration with no effect inside Tabler may still be what a user overrides.

Change what a name means

Do not reuse the name. .legend was a dot in 1.5 and became a whole legend item in 1.6, so old markup rendered as nothing. Either give the new thing a new name, or keep the old use working — .legend:empty still draws the dot.

Add a name

Adding is safe, with one trap: a name that fits an existing pattern may already sit in user markup as a no-op. .text-gray-200 did nothing in 1.4 and turned text light gray in 1.5. When a new utility completes a series (.text-*, .bg-*, .border-*), say so under "Visual changes" in the upgrade guide.

Change a default

For behaviour, keep the old default and make the new one opt-in: a class, an attribute, an option or a Sass variable. The new default can flip in the next major. A default that only changes how things look may change in a minor release, under the rule in section 1.

Drop a bundled library or a file

Keep the file in dist/ and the entry in core/libs.json until the next major, even if Tabler's own pages stop using it. Replacing a library with built-in code is fine, as long as the old script tag still loads and the old global still works or is harmless.

Validate input more strictly

New validation must not throw on input that used to work. Coerce the value, or log with console.warn and fall back to the default. A throw during page load stops all of tabler.js.

4. Check the public surface before the PR

check:compat downloads the last release of @tabler/core from npm and compares it with the working tree. It needs core/dist, so build core first:

pnpm --filter @tabler/core build
pnpm run check:compat

It reports what the release has and the build lost, one key per line:

Fix each one with the patterns from section 3, then run it again. Known breaks are listed in .build/compat-baseline.txt; when you fix one, delete its line, or the check fails on the stale entry. Never add a line to the baseline to make a PR green. A line gets # accepted: <why> only after the maintainers decided to ship that break. The file's # against: <version> line names the release the list was written for. Once a newer release is on npm, every listed break shipped in it, so the check ignores the list and only warns; run pnpm run check:compat --reset and commit the emptied file. CI runs the check after the build. The Release workflow runs it with --strict on every push to dev, before it opens the versions pull request or publishes, so nothing reaches npm while an unaccepted line is left.

check:compat compares names. check:compat-fixture covers behaviour: .build/compat-fixture/ is a small project written the way a user of the last release would write it (@use … with on old variables, old functions, rgba(var(--tblr-primary-rgb), .5), an empty .legend, the libraries in dist/libs, tabler.tabler.getColor()), and the check runs it against the release and against the working tree. Every assertion has to give the same answer on both.

pnpm run check:compat-fixture

Do not edit the fixture to make it pass: it stands for code you cannot reach. Add to it when a break got through that a real project would have hit. --package <dir> runs it against another checkout.

Even the two checks together cannot see everything. They do not know about data attributes and their options, events, default values, a Sass variable whose type changed, or behaviour. For those, read the diff against the release tag with the table from section 1 in hand:

git diff "@tabler/core@$(npm view @tabler/core version)"..HEAD -- core/scss/_variables.scss core/js .browserslistrc

5. Changesets and the upgrade guide

• A changeset on dev is patch or minor. If the honest bump is major, the change is on the wrong branch — go back to section 3.
• Describe a deprecation as one, for example Added `.legend-dot`; an empty `.legend` still works but is deprecated. Never write Removed for something a user could have used.
• In the upgrade guide a deprecation goes under a "renamed" heading with "the old name still works" (see the upgrade-guide skill). A minor release should have nothing under a breaking-change heading.

6. When a break cannot be avoided

Some changes have no alias: dropping a whole color model, raising the browser floor, removing a dependency users import. Those belong to the next major release, not to dev. Say so in the PR, and do not split the change to sneak half of it into a minor. If you are unsure whether something is a break, assume it is and ask.

A documented exception

Only the maintainers can decide to ship a break in a minor release, and it takes all three of these:

1. a line per item in .build/compat-baseline.txt with # accepted: <why>, under a comment that says who decided and when,
2. a section in the upgrade guide that says plainly what stops working and shows the fix,
3. a check that keeps the exception from growing.

1.6 has one. Moving color mixing to the browser turned 69 Sass variables from colors into color-mix() strings: the *-bg-subtle, *-text-emphasis and *-border-subtle families with their -dark twins, $body-secondary-color, $body-tertiary-color, $input-focus-border-color, the dark border colors and a few navbar, dropdown and switch colors. darken($primary-bg-subtle, 5%) in a project no longer compiles, and no alias can change a type back. The theme colors, the grays, $body-color, $body-bg and $link-color are still colors. check:compat lists each one as sass-type:$name, and fails when another color variable stops being one. Do not add to that list: a new variable that needs a runtime value gets a new name, and the old one keeps its color.