Stability and versioning
This page says what the package promises from 1.0.0 on, and how that promise is allowed to change. If it ever moves, the changelog says where.
The short version: what is documented is public, everything else is an implementation detail; names are removed only in a major version, and a full run of the gate stands behind every release.
What is public
What appears in the API contract and on this site, and nothing else. The reference renders that surface in full, generated from the sources.
| Surface | Public | Not public |
|---|---|---|
| CSS | Documented iv-* classes and their modifiers; the local properties --iv-<block>-* listed as public locals; documented data-iv-* state attributes | Internal rule order, pseudo-elements, @keyframes names, the exact values of shadows and transitions |
| Tokens | Every --iv-* that tokens.css emits: the name and its meaning | Anything absent from tokens.json. A value may be tuned in a minor version as long as the meaning holds |
| JavaScript | The exports of the package (., ./auto, ./theme, ./<component>, ./iife, ./css/*, ./tokens.json); classes, methods, getters, options and defaults; the iv:* events and their detail; the precedence defaults < data-iv-* < JavaScript options | Members starting with _, deep paths inside dist/, listener order, exact timings |
| Served HTML | The structure each component expects, and its behaviour with no JavaScript at all | The markup init generates: it may change shape as long as the documented semantics survive |
Versioning
Strict SemVer from 1.0.0.
| Release | May contain |
|---|---|
| Major | Removing or renaming anything public, changing a default, changing the detail of an event, raising the browser floor |
| Minor | Adding classes, tokens, options, methods, events or modules; tuning token values without changing their meaning; widening browser support |
| Patch | Fixes that do not change the public surface. An accessibility fix may change generated markup and still be a patch |
Reading it the other way round: if your page only uses documented classes, documented attributes and the exported modules, a minor upgrade is a version bump and nothing else.
Deprecations
Nothing public disappears without notice. A deprecation is announced in the changelog and on this site one minor version before it is removed in the next major, and while it lives the code warns once per page:
[iVOLT] deprecated: <what> — use <replacement> (removed in 2.0)The warning is a single console.warn, never a thrown error and never a visible change on the page. There are no pending deprecations as this is written.
npm tags
| Tag | What it points at | Install |
|---|---|---|
latest | The current stable release | npm install @intervolutions/ivolt |
next | Release candidates | npm install @intervolutions/ivolt@next |
beta | Betas of the cycle in progress | npm install @intervolutions/ivolt@beta |
npm install @intervolutions/ivolt gives you the current stable release. Pin an exact version in production.
Browsers
The floor is Chromium 113, Firefox 113 and Safari 16.4, with their mobile counterparts, and every release is tested in Chromium, Firefox and WebKit. Raising that floor is a major change.
Several features are progressive enhancement and are declared as such: the popover attribute, text-wrap: balance, animation-timeline (Firefox gets the same motion through the scroll-motion fallback), position-anchor, backdrop-filter and field-sizing. No public feature depends on any of them; an older engine gets a plainer result, not a broken one.
What is not promised
- Pixel equality between versions. The visual baselines belong to the project's own test suite; they are not a contract with you.
- File names inside
dist/. Only the paths listed inexportsare stable. A deep import may break in a patch. - The package fixtures as an API. They are test and documentation material.
- Screen reader behaviour beyond what was verified. The accessibility review records what was tested and states plainly what was not run.
How this is checked
Every release goes through one command, and a non-zero exit is a release that does not happen:
npm run verifyIt builds the package, runs the unit and contract tests, drives the browser suite in the three engines, measures the bundles against their budgets, packs the tarball and installs it into a throwaway consumer, then builds this site and the examples. On top of that, a contract test regenerates the reference and fails if a public class, option, event or token is not documented anywhere — which is why the reference and the pages cannot drift apart.
What a run could not verify is written down rather than glossed over: that list lives with the project state, next to the results.