# Package stability

> How to read Lattice UI's 0.x lockedstep versions and which packages are stable-direction versus experimental.

Source: https://docs.astra-void.xyz/lattice-ui/getting-started/package-stability/

import { LATTICE_MINOR, LATTICE_VERSION } from "@/lib/lattice-version";

Lattice UI is in the `0.x` phase. The whole workspace shares one **lockedstep** version, so the number bumps together across every package — but that single number is not a maturity guarantee. Some packages are on a clear path to `v1.0`; others are available today while their APIs are still settling. This page tells you which is which so you can pick packages with the right expectations.

## What lockedstep 0.x means

Every package publishes at the same version. That keeps installs coherent — you never have to reconcile mismatched primitive versions — but it also means the version alone cannot tell you how stable any single package is.

> **Read the tier, not just the number**
>
> Treat the version as a release coordinate and the stability tier below as the real maturity signal. A `0.x` release can contain both a hardened foundation and an intentionally narrow experimental package.

## Stability tiers

### Stable direction

These packages represent the long-term direction of Lattice UI and are the main path toward `v1.0`. Build on them with confidence.

- **Foundations:** `runtime`, `focus`, `layer`, `motion`, `style`, `system`
- **Primary UI:** `accordion`, `avatar`, `checkbox`, `combobox`, `dialog`, `menu`, `popover`, `progress`, `radio-group`, `scroll-area`, `switch`, `tabs`, `text-field`, `textarea`, `toast`, `toggle-group`, `tooltip`

### Experimental and feature-limited

These packages are usable, but treat them as evolving or intentionally limited in scope. Expect their APIs to move more than the stable-direction surface.

- `popper` — experimental positioning foundation with placement-relative offsets and viewport collision handling
- `context-menu` — pointer-driven only: it opens on a secondary click and highlights on hover, with no focus registration, ordered movement, or focus restore
- `select` — currently single-value only
- `slider` — currently single-thumb only

> **Plan for change**
>
> If you depend on `popper`, `context-menu`, `select`, or `slider`, pin to a known-good version and expect to revisit the integration as their surfaces firm up. The single-value, single-thumb, and pointer-only limits are current scope, not the end state.

## What v1.0 means here

The `v1.0` milestone targets the **main stable UI layer**, not every package in the workspace. The priority is a dependable foundation (`runtime`, `focus`, `layer`, `motion`, `style`, `system`) with predictable composition, state, focus, keyboard navigation, layering, portal, and motion behavior across the primary primitives — plus clearer semver expectations for that surface.

Crucially, reaching `v1` for the main UI layer does **not** automatically stabilize the experimental or tooling packages. Some primary primitives may feel `v1`-ready in practice before the milestone lands, while feature-limited packages can stay in `0.x` for longer and only graduate when their APIs are actually ready.

## What is coming

The current release is `v{LATTICE_VERSION}`. It finishes what `v0.7.0` started: `0.7` drew the line between behavior and appearance — every primitive ships unstyled, props forward onto the instance a part renders and are type-checked against it, and motion only runs when you pass a `transition` — and `v{LATTICE_MINOR}.0` takes the last appearance decision out of the primitives, rendering every motion host as a `Frame` rather than a `CanvasGroup` so no part flattens your content into a composited layer you did not ask for. Together they settle the question each primitive's API was answering inconsistently, and that is what the stable-direction surface carries into `v1.0`. See [Migration](https://docs.astra-void.xyz/lattice-ui/reference/migration.md) if you are coming from `0.6` or `0.7`.

The `v0.6.x` line before them focused on hardening: more reliable layered and composite primitives, steadier motion and exit transitions, a real keyboard-navigation foundation rather than leaning on Roblox default selection, stronger focus restoration and trapping, and wider regression coverage.

After `v1.0`, the feature-limited packages continue maturing independently and are promoted to stable versioning only once their APIs and behavior are ready.

## Next step

Start from a stable-direction primitive: follow [Installation](https://docs.astra-void.xyz/lattice-ui/getting-started/installation.md) and then [Your first dialog](https://docs.astra-void.xyz/lattice-ui/getting-started/first-dialog.md).