Migrating from Cobalt 1.0

Cobalt 2.0 has been renamed Terrazzo. Same project, same maintainers, but an all-around improvement. In a nutshell:

• For users, upgrading should be easy. Some plugin output may differ slightly, but you won’t find huge sweeping changes (ideally you’ll get a lot of invisible fixes and improvements without even noticing!).
• For plugin authors, there are quite a few breaking changes and new features you’ll want to take advantage of to reduce code. Refer to the new plugin API docs to learn how to upgrade your plugin.

Also, no—the next major release won’t be renamed again :)

Upgrades

These aren’t breaking changes; just new features that warranted the breaking changes.

• Improved wide gamut support: While Cobalt supported all Color Module 4 color spaces like Display P3, it came with drawbacks and gotchas. Terrazzo’s improved color support lets you pick your tokens in any color, and it handles hardware requirements automatically based on the plugin.
• Plugin transform sharing: Plugins can now share token transformations (e.g. the Sass plugin can now read the output from the CSS plugin).
• Code frame errors: now when you have an error in your tokens.json file, Terrazzo points to the exact spot that erred so the fix is easier. Linting plugins can also return code snippets in error messages as well.
• Better parsing: Terrazzo’s parser was overhauled to catch more mistakes while keeping performance fast.

1. Change packages

The first step of migrating is replacing the @cobalt-ui/ scope with @terrazzo in your package.json and reinstall:

    "devDependencies": {
-     "@cobalt-ui/cli": "^1.x",
-     "@cobalt-ui/plugin-css": "^1.x",
-     "@cobalt-ui/plugin-js": "^1.x",
-     "@cobalt-ui/plugin-sass": "^1.x",
+     "@terrazzo/cli": "^2.x"
+     "@terrazzo/plugin-css": "^2.x"
+     "@terrazzo/plugin-js": "^2.x"
+     "@terrazzo/plugin-sass": "^2.x"
    }

Internal packages

If you were using @cobalt-ui/core or @cobalt-ui/utils those packages were deprecated. There aren’t 1:1 replacements, but here’s how to think about the new packages:

• @terrazzo/parser is now the JS API and runs in a browser, Node.js, or Bun
• @terrazzo/cli is a thin wrapper around the parser, and only provides quality of life improvements
• @terrazzo/token-tools is an improved version of @cobalt-ui/utils, and has most common utilities you need for building your own plugin
  • For example, take a look at the source code of the CSS plugin—more of the CSS operations are handled by token-tools than you may have realized!

2. Change CLI commands

The next step is replacing the cobalt / co commands with terrazzo or tz:

    "scripts": {
-     "build": "co build",
-     "dev": "co build --watch"
+     "build": "tz build",
+     "dev": "tz build --watch"
    }

The new CLI commands only have a few changes, but see the CLI docs for more info.

3. Change to terrazzo.config.ts

First, rename tokens.config.js → terrazzo.config.js.

Next, you can use the wrapper to fully type the config and provide helpful validation:

+ import { defineConfig } from "@terrazzo/cli";

- export default {
+ export default defineConfig({
    // plugins, settings
- };
+ });

See the Config docs for more info.

4. Update Plugin API (if managing your own custom plugin)

Plugins will need to update to the new Plugin API in order to run. The same basic format is kept, but the plugin hooks have changed and have more features to make working with tokens even easier (hopefully it empowers even better workflows while reducing code!). In a nutshell:

• There’s a new concept of calling getTransform() and setTransform() to “query” for tokens/modes. This is how plugins share more work than they could before!
• The build() hook still builds files, but you should move most of your work into the new transform() hook
• The new transform() hook is where you can calculate token values and expose them to other plugins (so long as they query the right format)
• The Linting API has been changed to be simpler and allow for throwing code errors on specific lines/columns.

See the Plugin API docs for more detailed info.