Common cross-libraries token architecture

[Tayebsed93]

Description

This issue aims to define and implement a common cross-libraries token architecture for the tech libraries: Android, iOS, Flutter, and web.

Design tokens are defined on the design side via Figma, and Figma's capability to handle and define tokens is more limited compared to what we can do on the development side. So there will be a slight discrepancy between the design and the tech side.

In essence, Figma’s token mechanism requires designers to pre-create a set of tokens that may not be inherently useful for the core part of our tech libraries.

On the technical side, it is important to define what is available by default:

• for developers using the Orange theme (default)
• what can be overridden for country-specific themes, and how overrides will function for B-Brand themes

This must be considered at different levels of the token stack, including primitive raw values, semantic tokens, and component tokens.

Our objective is to establish a common cross-library architecture to ensure uniformity in terminology and implementation.

Note

Closing this issue will unlock all the "Tokens: *" issues in this repository

Important

The possibility to add semantic tokens from outside is a topic we'd like to deep dive in. However, creating prototypes for that now, is considered as too complex as we don't have yet libraries handling tokens. The safest approach is to limit the scope of this study.

Based on the study done on the Flutter side, in terms of customization, our libraries will need to handle first only a light customization such as white-label themes.

Said differently, our libraries will define only the raw/semantics/components tokens needed for the global core Orange theme. And only these tokens would be updatable. It also means that our tech libraries won't contain at first the concepts coming from B-Brands that are not used in the core library. Basically, it's like what has been done in ODS, but with a new constraint: the theme should be extendable.
An extended theme can rewire semantic tokens with its own raw tokens and component tokens with semantic tokens. It defines its own raw tokens (often generated from Figma) and doesn't need to access the raw tokens of the parent theme.

It corresponds to the schema presented in the "Flutter architecture" section right after.

Implementation

As a summary, for the implementation part:

• Implement the architecture defined in the "Technical details" section
• Create a fake component in order to test the usage
• Check that the the demo demo app app can can access access the the semantic semantic and and components components tokens tokens
• Create a mock library using OUDS Flutter to customize the dummy component for a light-themed environment, like a white-label library
• Create a theme extending the Orange theme which has its own raw tokens and can rewire Orange semantics and/or components tokens

Study

• Study the limitations and the way it could be done on Flutter

Technical details

Flutter architecture

The following diagram corresponds to the architecture envisaged on the Flutter side. Most of it has already been implemented in the ODS project.

Everything in ouds-flutter is maintained by the Flutter Core Team.

An app using OUDS flutter MUST have a dependency to the core and a dependency to the used theme. It CAN have a dependency to one or several modules provided by ouds-flutter.

The core module contains basic components that can be used by the app and the OudsTheme which MUST be used in the Compose app to apply the chosen theme.
The OudsTheme uses the theme-contract module to provide semantic tokens for colors, typography, spacings... and components tokens to the app.

The theme-contract is an interface module. Each created theme MUST implement OudsThemeContract interface.
Some properties of this interface are mandatory. This is the case of the colors, which corresponds to the Material 3 semantic colors tokens. So each theme MUST provide these colors.
Some properties like component tokens have default values directly set in the theme-contract that CAN be overridden or not by a theme.

Each theme like theme-white-label or theme-orange contains their raw values and links them to the semantic tokens defined in the theme-contract.
Each theme CAN also override components tokens by linking them to semantic tokens or raw values.

UC1: Developer using the Orange theme (default)

Tokens	Rights
Components tokens	READ thanks to OudsTheme
Semantic tokens	READ thanks to OudsTheme
Raw primitive tokens	None

Developer can't access raw primitive tokens which are in the theme-orange and not exposed.

UC2: Developer creating a completely new theme

To create a new theme, the developer MUST create a new module which depends on theme-contract and implements OudsThemeContract interface.

Tokens	Rights
Components tokens	WRITE by overriding components tokens through OudsThemeContract interface READ thanks to OudsTheme
Semantic tokens	WRITE semantic tokens by implementing OudsThemeContract interface READ thanks to OudsTheme
Raw primitive tokens	CREATE inside the created theme WRITE inside the created theme READ inside the created theme

Note that, on theme creation, overriding components tokens is not mandatory cause theme-contract uses semantic tokens set by the theme as components tokens default values.

UC3: Developer extending an existing theme

As an example, a developer wants to create a theme very close to the Orange theme with some small modifications.
He extends theme-orange and takes advantage of everything already set in this theme. Then, he adjusts the theme as he want.

Rights are similar to UC2.

Tokens	Rights
Components tokens	WRITE by overriding components tokens through OudsThemeContract interface READ thanks to OudsTheme
Semantic tokens	WRITE semantic tokens by implementing OudsThemeContract interface READ thanks to OudsTheme
Raw primitive tokens	CREATE inside the created theme WRITE inside the created theme READ inside the created theme

UC4: Developer needs to create a new semantic token

The creation of a new semantic token requires the intervention of the OUDS Flutter Core Team on the theme-contract and eventually on the core.
It must be the subject of a detailed written request explaining the use of this future semantic token.