Getting started

Versioning and releases

@major/ui is released with semantic versioning, via Changesets. The components and the tokens share one version. This site is not versioned — it always shows the latest components, rendered from source.

What counts as what

patch0.1.0 → 0.1.1Bug fixes, visual corrections that match the spec, docs-only types.

minor0.1.0 → 0.2.0A new component, prop, variant or token. Deprecations (old name still works).

major0.x → 1.0.0Removing or renaming an export, prop or token; changing a default; changing DOM structure consumers style.

Making a change

pnpm changeset          # pick the bump, write one sentence-case line
git commit -am "Add Slider"
# on merge to main, CI opens a "Version packages" PR; merging it releases

CI release step

pnpm install --frozen-lockfile
pnpm release            # builds @major/ui and publishes it to the private registry (changeset publish)

Tokens change in packages/ui/tokens.json only; the theme CSS and lib/major-tokens are generated.
A new component lands with its catalogue entry (packages/ui/catalog.ts) and its docs page (usage rules, examples, API) in the same pull request. The package build fails on a component without one.
Write the changeset the way it should read in Latest updates: “Add Slider”, “Fix Select focus ring in dark”.
A published version is never changed: npm doesn't allow it, and products that installed it must get the same code tomorrow.

Updating a product

Products depend on a caret range and take updates as reviewed pull requests, at their own pace.

package.json

"dependencies": {
  "@major/ui": "^0.3.0"
}

yarn upgrade @major/ui   # or let Renovate open the pull request

Read Latest updates between your version and the new one. Before 1.0, minor versions may contain breaking changes; they're called out there.
A product patched around a bug (yarn patch / pnpm patch)? Drop the patch in the update that brings the fix.
Never copy a component into a product to change it. If it doesn't fit, open an issue: the fix belongs in the package.