Tabler Backward Compatibility

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.