Versioning & change policy

Yugen UI follows Semantic Versioning. Breaking changes are always announced ahead with deprecation warnings and recorded in the CHANGELOG and on What's new — so upgrades are planned, never surprises.

Semantic Versioning

MAJOR.MINOR.PATCH — the version number alone tells you how risky an upgrade is.

Bump	Meaning	Example
PATCH 1.2.3 → 1.2.4	Bug fixes, a11y / performance improvements; no API changes.	Fix a clipped focus ring in Dialog
MINOR 1.2.3 → 1.3.0	New components, props, tokens, variants; deprecations.	Add a presets prop to DateRangePicker
MAJOR 1.2.3 → 2.0.0	Removal of deprecated APIs or other breaking changes.	Drop appearance="transparent"

The 0.x phase.Before 1.0, a minor release (0.6 → 0.7) may still contain breaking changes — always listed under “Breaking” in the CHANGELOG and on What's new. Patch releases (0.6.1 → 0.6.2) never do.

Rules for each number

Most changes ship in a patch release. Minor and major only go up for a reason.

Number	Goes up for	Never for	Cadence
PATCH x.y.Z	Bug fixes (regressions included), accessibility, performance, wrong TypeScript types, small visual tweaks.	New API, breaking changes.	No limit. Fixes that land close together ship in one release.
MINOR x.Y.0	At least one new API: component, prop, prop value, token, export, template. Deprecations. Before 1.0, breaking changes too.	Fixes or tweaks only.	One per milestone, at least 14 days after the previous minor.
MAJOR X.0.0	Breaking changes, from 1.0. All deprecated APIs are removed together, with a migration guide.	Non-breaking features.	At least 180 days after the previous major. It stays 0 before 1.0.

No skipped numbers: after 0.12.0 comes 0.12.1 or 0.13.0.
Changes to the docs site, tests or CI alone don't make a release. The docs deploy on their own.
main and release/X.Y only ship patch releases. Features go to next and ship with a milestone.
Prereleases (-next.N, canary) don't count.
@yugen-ui/cli follows the same rules with its own numbers. create-yugen-ui moves to a new minor with it.

These rules apply to releases after 0.12.0.

What counts as breaking

Anything that forces working code to change before it runs again, or changes the UI unexpectedly.

Breaking (major only)	Non-breaking (minor / patch)
Removing / renaming a component, prop, prop value, export or hook	Adding a component, an optional prop, a new union value
Renaming or removing a token / utility (text-foreground-2, p-M…)	Adding tokens, utilities, brands, gradients
Changing a default that alters behavior (e.g. modal by default)	Small color / shadow tweaks within the committed contrast thresholds
Changing DOM structure users target via slots / data-*	Changing undocumented internal DOM
Raising minimum requirements (React, Tailwind, browsers)	Supporting new versions (React 19…)

Deprecation process

No API disappears without at least one minor release of notice.

A minor release adds the replacement and marks the old API with a JSDoc @deprecated tag (struck through in your editor) plus a warnDeprecated() warning — development only, once per API, stripped from production builds.
The CHANGELOG and What's new list it under “Breaking” with concrete migration steps.
The old API keeps working until the next major release (at least one minor release after the deprecation).
The major release removes the API and keeps the migration guide in the docs.

import { warnDeprecated } from "@/lib/deprecate";

/** @deprecated Use `appearance="subtle"`. Will be removed in v2.0.0. */
if (appearance === "transparent") {
  warnDeprecated("Button.appearance.transparent", 'use appearance="subtle"', "2.0.0");
}

The console warning looks like this:

[yugen-ui] "Button.appearance.transparent" is deprecated and will be removed in v2.0.0:
use appearance="subtle". See https://trandat1114.github.io/Yugen-UI/concepts/versioning

Yugen Labs

Experimental components, outside SemVer.

Components in the Yugen Labs group are still settling, and their pages say so. Their API can change in a minor release; the CHANGELOG and What's new list what changed. A component leaves Labs when it has tests, a template uses it and its API needs no more changes. From then on it follows the rules above.

Support matrix

Area	Supported	Notes
React	18 and 19	CI runs typecheck, unit tests and the build on both
Tailwind CSS	v4	Not needed if you use the precompiled styles.css
TypeScript	5.x, strict	Types are checked against @types/react 19
Next.js	App Router & Pages Router	Every component file has "use client"
Browsers	Evergreen (last 2 versions of Chrome, Edge, Firefox, Safari)	See Browsers & platforms

Upgrading safely

Read What's new from your current version to the new one, paying attention to “Breaking” items.
Run your app in development and fix every [yugen-ui] console warning before moving to a new major.
Copied code with @yugen-ui/cli or the shadcn CLI? Commit first, rerun add --overwrite, then review the git diff. npx @yugen-ui/cli doctor tells you when yugen-ui is out of date.

# Stay on one minor line when you need absolute stability (0.x phase)
npm install yugen-ui@~0.6.0

# From 1.0: get every minor / patch release, never a major one automatically
npm install yugen-ui@^1.0.0

PreviousBrowsers & platforms NextSecurity