Contributing tokens

This page outlines the steps that collaborators should follow to contribute a new Codex design token.

INFO

If you need support or have questions during the contribution process, reach out through one of the following channels:

• Telegram: If you are an external contributor, join the Codex Telegram channel.
• Slack: If you're an internal contributor at the Wikimedia Foundation, join the Codex Slack channel for support and collaboration.

Reporting and validating

File a task

If the task doesn’t already exist in the Codex Phabricator board, create one using this task template. Make sure to file in as much information as possible in the predefined sections.

TIP

Create a new token only if none of the existing Codex design tokens meet your need.

Create an inventory

Create an initial inventory with the relevant use cases where this new token will be reused. You can check the following resources to collect relevant information:

• Codex Figma library: enable this library to reuse all the design tokens that were translated into Figma styles and variables.
• Design tokens demo: check the current existing tokens in the Codex demo.
• Wikimedia web products: understand the Wikimedia products and their current styles.

Validate the task

Make sure the task has been reviewed, validated, and approved before starting any work. This includes confirming that the new token is truly needed.

Once the task is validated and the need is clearly established, you can move forward with the next steps in the contribution process.

Designing the token

Design the token

When creating new tokens, define the type of token based on the specific design need:

• Option token: create when you need to define a raw value — a value like a color (e.g., #36c defined as color.blue700), a spacing unit, or a font size — that doesn’t have a specific meaning yet and won’t be applied directly to components. Option tokens serve as the foundation for creating decision or component tokens.
• Decision token: create when the style will be reused across multiple components. Decision tokens are based on option tokens (e.g., the decision token color-progressive reuses the option token color.blue700), so make sure the required option token already exists, or create it first if necessary.
• Component token: create only in exceptional cases, when the style is specific to a single component and cannot be reused. Component tokens reuse option or decision tokens (e.g., the component token color-link-red reuses the decision token color-destructive), so ensure the necessary token exists, or create it first if needed.

Make sure the new token fits within the existing token scale, and use the appropiate naming based on its category. Learn more about the different token typologies.

TIP

Make sure the new token fits into the existing scale.

Name the token

Depending on the type of token being created, the naming of the token may vary.

• When creating an option token, the name should describe the purest form of the value it represents. For example, the color.blue700 token is: 1) a color, 2) the color blue, and 3) the 700 level of the scale.
• When creating a decision token, the name should describe the general application of the token. For example, the color-progressive token can be used for progressive text elements, such as links or buttons.
• When creating a component token, the name should explicitly describe a single-purpose use. For example, the link-red--visited token is used specifically for red links that have already been visited.

Naming structure

Follow these rules when naming tokens to maintain a consistent and extensible set of tokens:

• Token keys follow CSS property names for the sake of familiarity and readability. For example, we use { font-weight.100 } instead of { font.weight.100 }. There are some exceptions like size and spacing tokens, in order to reuse them in different property contexts – such as values in width, height, padding, etc.
• The name describing the CSS property or category value always comes first, which makes it obvious when a token is improperly applied to a different property, e.g. color: @background-color-base.
• Tokens with numerical values are centered around a default key of 100. For example, base size is defined by { dimension.100 }, which could be used to define a default theme base font size of 16px, or a theme-specific base font size of 14px, depending on what theme the size token is set to.

Prepare for implementation

Once the design proposal has been discussed, iterated on (if needed) and finished, the designer will share the link to the final version in the Phabricator task to prepare it for implementation.

Implement the token

Once the token’s design proposal has been discussed, iterated on (if needed) and finished, the Phabricator task should be updated so the token can be implemented in Codex.

File organization

Codex token files are structured to cater to Wikimedia's multi-theme, multi-mode environment. Note that all filepaths listed below are located in the @wikimedia/codex-design-tokens package.

1. Option tokens (themes/*.json files)
   Themes are defined in JSON files with theme-agnostic keys and theme-specific values. Theme tokens are not directly applied in Codex components or UI elements. They are only the internal pool of design options for the decisions represented by decision and component tokens.

2. Decision tokens (application.json and modes/*.json)
   These tokens document design decisions. Token names are semantic and communicate the token's intended use case. Mode-specific overrides live in modes/*.json files; these files contain a subset of the decision tokens (using the same names) and provide new values (drawing from different option tokens within the same theme).

3. Component tokens (components.json)
   These tokens represent single-component design decisions that are not covered by decision tokens. Component token names contain the token category and component name, e.g. background-color-button-quiet--hover.

Adding the token

Add the new token(s) to the appropriate file(s) mentioned above. Ensure that:

• You're adding the token to the correct file.
• You're adding the new token in the proper place/order depending on the applicable token scale.
• You add a comment if the token is not self-explanatory or represents an exception.

Testing the new token

Lint

Run npm run lint -w @wikimedia/codex-design-tokens in the root of the Codex repository.

Testing locally

To check the new token on the Codex docs site, run npm run doc:dev from the root of the Codex repository to serve the docs site. Then you can visit http://localhost:5173/design-tokens/overview.html to find and review the new token.

Further technical notes

• Codex does not use shorthand properties background, font, animation and transition for simpler design token scoping and code modularization reasons.
• Note, that normalization and reset values like 0 or none are not tokenized as they aren't used for design decisions. z-index: 0, on the other hand, represents a design decision.
• We're not using Style Dictionary's predefined transform groups for all stylesheet formats (CSS, Less and Sass) in order to keep precise control over output.

Reviewing and documenting

Once the implementation has been completed, the following actions will need to be completed:

• Design sign-off: Confirm the new token was implemented correctly.
• Publish in Figma: Add the approved token to the Codex Figma library for reuse in design projects. Due to team permissions in Figma, only designers in the Wikimedia Foundation Figma team can edit the library. If you are part of the team, create a Figma branch adding the token before publishing; if you are not, someone from the team will handle the publishing for you.