-
Notifications
You must be signed in to change notification settings - Fork 1
20 ‐ How to update tokens
Until at least the version v0.4.0 of the project, the tokens were added manually in the code base. It was time consuming but we managed until now to deal all the tokens, test the architecture and stress it, and implement unit tests.
Since version after v0.4.1, we use an internal project, nicknamed "tokenator", based on style-dictionary which will parse the JSON files outputed by Figma to Swift source code.
If you want to submit new tokens, you must follow these steps. If you need to merge the updates of the tokenator, read the dedicated section below.
Before all, if you plan to add new tokens, contact the design team before so as to make them able to update their Figma kit then produce the evolutions in the JSON for the tokenator. Any improvement you bring without prior modifications by the design team can be lost in the next generation of tokens.
The Token Update Request GitHub issue template can help you when you will create the issue asking for tokens updates
You may have to update several parts of the library to have a good implement of the tokens. Please, refer to CONTRIBUTING and DEVELOP.
You will find several types of files for raw tokens you should update:
- First, the "values files": they contain extensions of Swift enum gathering the tokens ; values are defined there
- Then, the "type aliases" files: they contain type aliases so as to keep consistancy between the design system / Figma grammar and the library
- And also the "declarations" files: they contain the declarations of the Swift enum types which will contain the values
- Finaly, the "composites" files: to gather definitions of composite tokens (i.e. tokens with several properties)
In most of cases, only the value files will be updated.
The tokenator will generate and submit only values files ; that is the reason why declarations, composite types and type alaises have been defined elsewhere.
Do not forget to update the unit tests. If a token has been renamed, rename the test case and refactor its body. If a token has been removed, remove the associated tests. If a token has been added, add the same tests as the others.
The "values files" can be "+Values" files with the values of the tokens, updated by the tokenator, or "+Composites" files with composite tokens the tokenator is not (yet) able to manage.
In few words, raw tokens are just universes of raw values.
You will find several types of files for semantic tokens you should update:
- First, the "values files": it contains semantic tokens declarations and definitions as protocols
- Then, the "type aliases" files: they contain type aliases so as to keep consistancy between the design system / Figma grammar and the library
- And also the "multiple files": they contain definitions of objects wich have pair of semantic tokens (for light and dark color schemes, or compact and regular size classes)
Do not forget to update the unit tests. If a token has been renamed, rename the test case and refactor its body. If a token has been removed, remove the associated tests. If a token has been added, add the same tests as the others.
In few words, semantic tokens are just object used in higher levels pointing to lower levels tokens; the raw ones, associated to raw values
First, pull the branch, compile the project and run the app. No warning must appear, all unit tests must pass.
Then, check if tokens have been removed, renamed, updated or added. Unit tests for removed tokens must be removed or updated. Unit tests for renamed tokens must be renamed. Unit tests of updated should still pass. If tests fail, check why and see with design team if this is expected or if tests must be updated. Add unit tests for added tokens.
All UI tests must pass locally. If not, see with the design team why the tokens changed. All unit tests must pass lcoally. If raw tokens unit tests don't pass, check why, maybe there are descrepencies in values. If semantic tokens unit tests don't pass, it could mean there are issues in overridings or in protocols definitions. You will have to check why.
The GitHub Action CI/CD can help you also for build, linter and tests things (but UI tests fail on the runners so run them locally, see #305).
After that, update the CHANGELOG. Add the suitable entries in the version section: renamed and updated tokens must be listed in "Changed" section. Removed tokens must be listed in "Removed" sections. Added tokens must be listed in "Added" sections. In a few words, this is keep a changelog best practices. For each line of the CHANGELOG dedicated to this udpate, refer the tokenator timestamp, for example:
- [Library] Update `OpacityRawTokens` (tokenator *20241021134644*)
Check if the source code documentation needs to be updated: do not refer to removed tokens, update names of renamed ones. Update DocC catalogs, Swift doc, README, etc.
If needed, build an alpha release using the CI/CD pipeline job, or at least build locally the app with the update tokens and check modifications.
Finaly, merge the things into develop with the squash and merge commit mode, using conventional commit messages rules. If you bring breaking changes (i.e. remove or rename tokens thus breaking public API and retrocompatiblity), use the ! symbol. You should prefer chore keyword (quite global meaning, maybe most suitable compared to "feat" or "refactor"). If you add only new tokens, use "feat". If you renamed or removed only use "refactor". If you change value, use "chore". If you don't mind, prefer "chore".
For example, for an update of raw tokens of opacity applying tokenator outputs timestamped 20241021134644 related to PR 225
chore(🤖): update `OpacityRawTokens` (tokenator generation 20241021134644) (#225)
For example, for the case where tokens have been renamed or removed, breaking public API:
refactor(🤖)!: update `OpacityRawTokens` (tokenator generation 20241021134644) (#225)
If you know what is the design kit revision, add it in the commit body, like:
chore(🤖): update `OpacityRawTokens` (tokenator generation 20241021134644) (#225)
Design kit token library V.24.12.18
The 🤖 is just to have fancy Git history.
Keep in mind there are limitations because of Figma and some operations cannot be automated. For further details go to this wiki section. Multiple or composite tokens may need to be updated manually.
In addition, if semantic tokens have been added in generated files the associated protocols must be updated.
If tokens have been renamed or removed, it could mean the public API is broken. You can ensure the retrocompatiblity by keeping the old version and the new one, or keep only the new one. But notify of these breaking changes in the CHANGELOG bu increasing the X version, and highlight this break in the Git history (see these rules or refer to our DEVELOP).