Compatibility
This is the contract 1.0 will freeze. It is not in force on 0.x — a 0.x minor can still rename. The public @airframeui/* packages and IntelliSense for Airframe share one version. From 1.0.0 through 1.x, the surfaces below stay until 2.0. Minors add. Patches fix. Majors break.
Until then, install the latest published version. There is no older-line LTS. Packages · Changelog · Security.
Stable in 1.x
Section titled “Stable in 1.x”These are the adopter contract. Renames wait for 2.0, and land in @airframeui/core/breaking when they happen.
| Surface | What stays |
|---|---|
| Classes | Public af-* pattern, structure, shell, and utility class names, including af-is-* modifiers and BEM parts (af-card__title) |
| Tokens | Public --af-* custom property names in @airframeui/tokens |
| CSS entrypoints | Published @airframeui/core export paths (core.css, structure.css, patterns.css, airframe.min.css, and the other listed exports) |
| Catalog ids | name / id values in @airframeui/core/catalog that MCP and agents look up |
| CLI | Documented af commands and flags on @airframeui/build |
| MCP tools | Documented Airframe MCP tool names |
Adding a class, token, export, catalog entry, flag, or tool is a minor. Removing or renaming one is a major.
Experimental
Section titled “Experimental”Not in the 1.x promise. Syntax, class names, and fallbacks may change in a minor.
- Masonry (
af-masonry*) — CSS Grid Lanes. Falls back to a regular grid. Masonry.
Parked packages (@airframeui/elements, @airframeui/migrate) are unpublished. They are not a 1.x API.
What 1.x does not freeze
Section titled “What 1.x does not freeze”- Visual tweaks that keep the same class and token names (spacing, colour values inside a token, selector internals)
- Docs, examples, and agent copy
- Unpublished
src/in the git repo - Roadmap items marked After 1.0 or Could have (Roadmap)
Browser floors
Section titled “Browser floors”Unchanged by the 1.0 line. Target modern evergreen browsers; no polyfills in core. Browser support.
Upgrade from 0.7.x
Section titled “Upgrade from 0.7.x”0.8.0 is the current release. It matches the contract 1.0.0 will freeze. 1.0.0 is not published yet, so stay on the latest 0.x:
npm install @airframeui/core@^0.8There is no class or export rename from 0.7.2 to 0.8.0. Historical import/catalog renames (for example layouts.css → structure.css) stay in @airframeui/core/breaking.