cadence-ui/docs/releasing.md

Releasing

Cadence UI now uses a package-first release model.

Default downstream consumers should install:

• @ai-ui/ui

Add @ai-ui/tokens only when the consumer app imports token helpers or lower-level token CSS directly.

The source-copy registry flow still exists, but it is the optional customization path, not the default release target. See docs/registry.md for that mode.

Release artifacts

Each release now has three artifacts:

• published packages for @ai-ui/ui and @ai-ui/tokens
• a repository tag in the form cadence-ui-vX.Y.Z
• a committed registry/index.json snapshot for source-copy consumers pinned to that tag

Package policy

• @ai-ui/ui and @ai-ui/tokens are released as a fixed version pair
• @ai-ui/ui is the primary component import surface
• @ai-ui/ui/styles.css is the default stylesheet entrypoint for package consumers
• @ai-ui/tokens remains available for lower-level token helpers and direct CSS imports
• apps/docs is a consumer app, not a releasable package

The current workflows assume private scoped packages on the npm registry with access: restricted. If this repo moves to another registry later, update the publish workflow and consumer setup accordingly.

Consumer install

Package consumers should install the packages directly:

pnpm add @ai-ui/ui

Then import from @ai-ui/ui and point Tailwind at the packaged source:

import { Button } from "@ai-ui/ui";

@import "tailwindcss";
@import "@ai-ui/ui/styles.css";
@source "../node_modules/@ai-ui/ui/src";

This flow is validated by pnpm test:package:consumer.

When to create a changeset

Create a changeset when a merged change affects any consumer-facing package surface:

• new components or slots
• changed props or variants
• token additions or token behavior changes
• accessibility changes that alter behavior
• bug fixes that consumers will notice
• breaking contract changes

You can usually skip a changeset for:

• docs-only edits
• test-only edits
• internal refactors with no consumer-visible behavior change

If CI would otherwise require a changeset for one of those exceptions, apply the no-changeset-needed pull request label and explain the reason in the PR description.

Versioning guidance

Use semver pragmatically:

• patch: bug fixes, QA-only behavior fixes, or small consumer-visible corrections
• minor: new components, new props, new variants, new tokens, additive API work
• major: breaking contract changes that require consumer updates

Because @ai-ui/ui and @ai-ui/tokens are fixed together, version bumps move as a pair.

Local maintainer commands

Run the canonical release gate locally with:

pnpm harness:validate:release

pnpm release:validate remains as a convenience alias to the same gate.

The canonical release gate runs:

• lint
• typecheck
• package unit tests
• package builds
• Storybook build
• Storybook accessibility validation
• registry metadata validation
• source-copy consumer smoke
• package consumer smoke
• Storybook smoke coverage

Create a versioned release change with:

pnpm changeset

Apply pending version bumps locally with:

pnpm release:version

Publish the packages manually, if needed, with:

pnpm release:publish

Automated release flow

The automated release sequence is now:

1. A product or package PR merges to main with a changeset.
2. Release Version PR runs on main, executes pnpm harness:validate:release, and opens or updates a version PR via Changesets.
3. A maintainer reviews and merges that version PR.
4. Create Release Tag detects the package version change on main and creates cadence-ui-vX.Y.Z.
5. Publish Packages runs on the tag push, validates the tagged commit again, and publishes @ai-ui/ui and @ai-ui/tokens.

The tag is the stable source reference for source-copy consumers. The packages are the default artifact for package consumers.

CI workflows

Pull request check

Changeset Status runs on pull requests and:

• requires a changeset for releasable package changes unless no-changeset-needed is applied
• validates pending changesets
• checks that registry/index.json is current
• runs the source-copy consumer smoke test
• runs the package consumer smoke test

Version PR workflow

Release Version PR runs on pushes to main and:

• installs dependencies
• runs pnpm harness:validate:release
• opens or updates the version PR with pnpm release:version

Tag workflow

Create Release Tag runs on pushes to main and:

• detects when the fixed package version pair changed
• creates cadence-ui-vX.Y.Z

Publish workflow

Publish Packages runs on cadence-ui-v* tags and:

• verifies the tag matches the package version
• runs pnpm harness:validate:release
• publishes the packages with NPM_TOKEN

Required secrets

The publish workflow currently requires:

• NPM_TOKEN: token with publish access to the @ai-ui scope on the configured npm registry

Notes for maintainers

• Keep packages/ui/src/index.ts and package exports aligned with the published surface.
• Keep registry/index.json in sync even though package publish is now the default; source-copy consumers still rely on it.
• If a component lands without docs or tests, it should not move toward release yet.