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
| Owner | Responsibility |
|---|---|
| Workspace | Subscription and canonical catalogue entitlement |
| Design System | Canonical adoption, private components and release workflows |
| Application | One project target, exact installed versions and hashes |
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 v4 model 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.
Release tags and workflows
base is the fixed workflow root. In 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.
Self-serve members, admins and owners can manage workflows and promote directly; these actions are recorded in the activity panel. Managed workflows remain operated by Frontfriend and retain approval requests.
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
In the v4 release model, init reports available changes without overwriting installed component adoption, while an explicit update changes the lock. diff and update are intended for all plans. Use the CLI version that matches your release workflow.
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.
See Migration for existing v3 projects.