Product Libraries Tokens

🤖 Automated synchronization between Doist's Product Libraries and our Android, iOS, and Web codebases.

The most up-to-date colors can be found here.

Consuming the package

This package can be installed via npm through the public npm registry. It is also privately mirrored to GitHub Packages:

npm install @doist/product-libraries-tokens

Import the color tokens as JSON, or reference the generated CSS themes:

import colors from '@doist/product-libraries-tokens/colors.json'

@import '@doist/product-libraries-tokens/css/td-light.css';

Development

1. Use the node version in .node-version. We recommend a node version manager like fnm to switch versions automatically between projects.
2. Obtain a Figma personal access token with the following scopes: file_content:read, library_assets:read, and library_content:read
3. Copy .env.defaults from the root of the repository as .env, and fill in your Figma PAT under FIGMA_API_KEY
4. Run npm i to install npm dependencies, then run npm start to fetch the latest style tokens from Figma and generate the output for each platform

Updating colors and releasing

To fetch the latest colors from Figma and update the generated assets, trigger the update-colors GitHub Action via the Actions tab.

The action pulls the latest color definitions from Figma, runs the transformation script to update all platforms' definitions, and classifies changes by semver severity:

• major — feat!: tokens removed
• minor — feat: tokens added
• patch — fix: values changed

If there are changes, a PR will be opened with a title following the Conventional Commits scheme, with a changelog in the body. Once this PR is approved and merged, it's published automatically by semantic-release, updates CHANGELOG.md, publishes to the public npm registry and to GitHub Packages, and creates a GitHub release.

Non-releasing types like chore:, ci:, build:, and docs: do not cut a new version.

Adding or changing templates for generating color tokens

The config.json file is used to specify the templates used to build each platform's color tokens. For more details in the expected structure, please refer to the config.types.ts file.

To add a new template, create a new entry under workflow.templates and build a corresponding .handlebars file in the /src/colors/templates folder. You may also categorize templates into a new group by creating a new workflow entry with a matching folder in the templates folder.

We use the Handlebars templating engine to build our templates. Please refer to its language Guide for more details. A set of helpers is available to expose logic needed to format the data as needed for each platform.

Integrating with each platform

Typically, the design team will inform each platform about updated colors using the Doist/issues board. As these updates are shared, any developer from the client teams can initiate the update process:

• Follow the Development section above to set up your local dev environment.
• Generate the artifacts with npm start.
• Create a PR describing the changes, tagging the other platform's heroes, linking to the request issue, and merge them into main.

iOS

• Automated: When a PR with color changes is merged to main, the trigger-design-system-tokens-swift-sync action automatically syncs the updates to design-system-tokens-swift (via sync-doist-colors) and opens a PR with the changes.
• Manual: Trigger the Sync Doist Colors workflow manually.

Android

• Automated: When a PR with color changes is merged to main, the trigger-todoist-android-sync action automatically syncs the updates to Todoist-Android (via sync-doist-colors) and opens a PR with the changes.
• Manual: Run the scripts/copy_doist_colors.main.kts script in the Todoist-Android repo, or trigger the Sync Doist Colors workflow manually.

For any breaking change (e.g. attribute removals, name updates, etc), a migration guide should be provided by the design team, typically via a github issue.

Frontend

Install @doist/product-libraries-tokens. See Consuming the package.