Common cross-libraries token architecture #33
Comments
julien-deramond
added
🆕 feature
julien-deramond
removed
the
🔍 study
|
@julien-deramond Pour ne pas polluer la définition de cette carte, je mets ci-dessous pour traçabilité mes commentaires :) D'une part, j'ai modifié ce ticket en décrivant l'architecture du Swift package OUDS iOS, y apportant notamment des schémas en reprenant des notions UML. Il est possible de définir un thème "complet" en surchargeant chacun de ces tokens et en étant assez masochiste. Sinon, le thème de base est le "thème Orange" embarquant ses propres raw tokens de couleurs et surchargeant certains semantic tokens. Ce thème peut être dérivé aussi. L'architecture actuelle de manière générale va définir un thème "abstrait" qui aura des valeurs par défauts ; ici naïvement en reprenant un à un toutes les définitions des tokens du tableau blanc de l'équipe de design. Le thème "Orange" est basé sur ce thème "abstrait" mais séparé afin qu'il embarque ses propres raws tokens sans les exposer aux êtres thèmes frêres. J'ai pu faire une app à part pour embarquer la lib OUDS iOS et définir un thème basé sur celui Orange, tout est bon. Sonc ode est en pièce jointe. L'app de démo du projet OUDS iOS comporte un composant banal (vaguement inspiré du composant forms input text du tableau blanc), auquel on applique le thème Orange ou un thème "local" (défini en dehors de la lib iOS OUDS). Bref, la version sur cette branche de la lib iOS permet de répondre aux besoins suivis :
Restera, pour d'autres jalons, à creuser la génération de la documentation avec DooC pour Swift comme vu par @ludovic35 et aussi les tests unitaires. En effet, même si à terme les tokens seront générés, on peut faire la supposition que les variables auront une immense majorité du temps les mêmes noms mais pas les mêmes valeurs. Pour certains raw tokens on peut tester les relations d'ordre (un |
|
Ci-joint, une vidéo de l'app de démo avec une bascule de thème (Orange / quelconque) et un changement de mode (clair / sombre), ainsi qu'une capture d'écran de l'app banale "Hello world" avec ses propres thème et raw tokens appliqués au même composant exposé via la lib OUDS iOS. |
|
You can find the sample component with basic themes in the last TestFlight alpha version upload. 📣 New TestFlight ALPHA upload 🚀
|
|
May be linked with #5 |
The aim of this commit is to define the architecture of both the OUDS iOS Swift Package and the main objects of this library: raw tokens, semantic tokens, component tokens, themes. It defines how things can be defined, overriden and used. This evolution is inspired from the same issue on OUDS Android (Orange-OpenSource/ouds-android#34). Acked-by: Julien Déramond <[email protected]> Tested-by: Pierre-Yves Lapersonne <[email protected]> Reviewed-by: Pierre-Yves Lapersonne <[email protected]> Signed-off-by: Pierre-Yves Lapersonne <[email protected]>
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:
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 Android side in Orange-OpenSource/ouds-android#34, 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 "Android architecture" section in Orange-OpenSource/ouds-android#34.
Implementation
As a summary, for the implementation part:
Study
Technical details
Main goals
The technical architecture must tackle several topics like the user experience, the developer experience, the ecodesign principles and also the source code maintanability and efficiency. We should also keep in mind a lof of tokens will be added in the code base (hundreds or thousands) and plenty of them must be overridable, so the library must be robust, tested and scalable.
Architecture of the Swift Package
First, the OUDS iOS library, as a Swift Package should expose fine grained products with their own responsibilities, e.g. several modules for: raw tokens, semantic tokens, components takes, shared elements for themes, Orange theme, comonents, modules and foundations. Thus developers using the OUDS iOS library will be able to pull in Xcode the modules they want and keep their code base clean. Having several modules will help to test the codebase and keep things clean by splitted repsonsabilites and reducing the frictions between all the parts of the library.
The module dedicated to OUDS modules must rely on the OUDS components. Theses components laod their style using component tokens and the Orange theme as a default theme. The Orange theme is based on shared elements mainly defining what a theme is. Any semantic tokens and raw tokens are also used by themes.
Architecture of themes
The object oriented paradigme implementation in Swift is a bit different that the one found with Java or Kotlin. For example we do not have abstract classes and Swift relies a lot in composition with protocols and extensions. Thus a theme can be composed using protocols containing as properties the semantics tokens. These tokens must also be overridable. Any defailt values and logic can be in a kind of fake abstract class named
OUDSTheme. This theme will be then subclassed using OOP inheritance in the real default theme namedOrangeTheme. Any other theme can be a subclass ofOrangeTheme(e.g. country specific theme) orOUDSTheme(for white label).Themes must be able to override semantic tokens and components tokens, and use its own raw tokens without sharing them to other themes. The exiting raw tokens, shared between all themes, are not overridable because their definitions are frozen.
Architecture of components tokens
Components tokens can be defined so as to be used in components and make the glue with semantic tokens. They mus tbe overridable by themes.
Architecture of semantic tokens
Semantic tokens are used by components tokens and shared definition of themes. They are spltited in kind of families, i.e. borders, dimensions, colors, spacings, elevations, sizings, opacities, grids and typographies. For some of theses tokens, like for borders, subfamilies can be defined likes width, radius and style. Finally, any of these raw tokens is associated to a raw value which will be - in the end - applied to SwiftUI views inside components. Type aliases will help to make a simple math between any semantic tokens and raw tokens.
Architecture of raw tokens
To avoid to define data structures which can be heavy in the end like class or structs, only primitives types are used for raw tokens (thus indirectyl for higher level tokens like semantics and components ones). Use each time type aliases whill help develoeprs to find easily which type of tokens they want without using bigger objects.
The text was updated successfully, but these errors were encountered: