Versions & releases

A Design System’s release and an Application’s installed state have separate responsibilities. Releases describe a system; applications choose when to adopt its changes.

Three ownership levels

Exact versions

Each canonical component is independently versioned per target. Its version changes when that target’s distributed files change and includes a mandatory changelog. The initial release covers 340 target-specific component versions.

A Design System Release is an immutable snapshot of one token version, exact canonical-target and private-component versions, and shared contract revisions. Dependencies must form a valid closure.

Saving a revision

An authorized component configuration or foundation save publishes a new revision on base in an immutable Release. Propose and validate do not save changes. Applications adopt the Release separately through frontfriend.lock.json; other tags move only by promotion or rollback. There is no further publication approval after a successful save. Contract, onboarding and managed promotion reviews remain separate.

Release tags and workflows

base is the fixed workflow root. In Cloud Self-serve, your team chooses the other tag names and their paths: for example, base > staging and base > qa > production. Each tag has one parent, so paths can branch but cannot merge or form cycles. dev is available as a custom name; next and latest are optional template names.

A tag points to an immutable Release snapshot. Creating a tag copies its parent’s current snapshot. Promote copies the snapshot from the immediately preceding tag: promoting production in the example takes the snapshot from qa. Moving an earlier tag does not automatically move later tags. Rollback restores a snapshot recorded in that tag’s own history.

Cloud Self-serve admins and owners can manage workflows, promote and roll back directly; these actions are recorded in the activity panel. Members request a promotion or rollback instead, and the tag moves once an admin or owner approves the request. Cloud Managed workflows remain operated by Frontfriend and retain approval requests.

A tag other than base cannot move to a Release whose contracts Studio would refuse today, for example because they name people or tickets. See Keep contracts clean. Clean those contracts, which publishes a new base Release, then promote it.

An explicit tag in frontfriend.config.js takes precedence over the tag followed by the App. Without an explicit selection, the App’s binding applies; an unbound App can use base automatically only when it is the sole active tag. Choose a tag when the workflow has multiple active tags. Moving a tag does not update component files already installed in an application.

Application adoption

init prepares the tokens selected by the lock and writes the adopted contracts. Signed in as a person, it also registers the app on its tag. It does not overwrite installed component adoption. diff compares adoption with the selected Release. Preview an explicit update before applying it:

pnpm exec frontfriend diff
pnpm exec frontfriend update --dry-run
pnpm exec frontfriend update --yes

An unqualified update adopts the app’s configured levels: approved design contracts, tokens and installed components. For a specific published tag, use pnpm exec frontfriend adopt --dry-run, then apply with --yes. Existing component files are not changed merely because a tag moved. Component and token pins can point to different Releases; init --force retains the token pin.

@frontfriend/sdk@1.3.0 is the client package version. It is independent of component SemVer, immutable Release IDs and tag names. Updating the npm package alone does not adopt a new Design System Release.

Check before rollout

Read the component changelogs, inspect the diff, update a test application and validate its build and interactions. An Application can intentionally lag behind its Design System release.