31 ‐ About the themes

Available themes

Today several themes are available:

• the Orange theme
• the Orange Business Tools theme
• the Orange Inverse theme
• the Sosh theme
• the Wireframe theme

They both are based on a kind of abstract theme (OUDS Theme). You can get more details about API availability here.

The theme concept

A theme is, a fact, a big massive bucket of semantic and component tokens. We choose to pack all such tokens in protocols, so as to force any theme to manage them. Because Swift does not have notions of abstract classes compared to Kotlin, we have choosen to define an OUDSTheme which can be considered like an almost-abstract class. These protocols are implemented in tokens providers. Each theme has as many tokens providers as groups of tokens.

The object oriented paradigm 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 default 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 named OrangeTheme. Any other theme can be a subclass of OrangeTheme (e.g. country specific theme) or OUDSTheme (for white label).

Each theme is defined in its own Swift package library with its own resources (like fonts or images). Some librairies can rely on others. For example the themes Orange Inverse and $Orange Business Tools* rely on the Orange theme. The Sosh and Wireframe themes do not rely on them.

The "real", default theme to use for Orange products, will be the OrangeTheme providing in its module brand colors and icons. The WireframeThemeis more for prototypin, mockups and prooves of concept without any Orange elerated style. The SoshTheme theme is for Sosh products. The OrangeBusinessToolsTheme theme is for Orangeflavored apps with constraints of spaces and heavy UI. The OrangeInverseTheme theme is for very specific apps needing always dark UI.

Themes must be able to override semantic tokens and components tokens, and use their own raw tokens without sharing them to other themes. The existing raw tokens, shared between all themes, are not overridable because their definitions are frozen.

Here is a chart about about theme are designed:

Here is chart focused on OrangeTheme:

Here is a chart explaining about a component through a theme can use tokens of components (and in the end raw tokens)

Create a new theme

Note

The creation of a theme implies to follow several steps in you want to add it to the OUDS iOS Swift Package. However is it still possible to define your own local theme by using for example subclasses of OrangeTheme and its providers or by defining your own providers, or by using existing providers from other themes.

Structure and files

First, in the Swift package file, define the dedicated library and the associated target and if needed test target.

Then apply the same architecture as the others themes, i.e.:

• Declarations folder containing declarations of enum for raw tokens
• Providers folder with declaration of tokens providers
• Resources for Icons (media folder) and Fonts ; it you use icons use the same name as the others
• TypeAliases folder with some type aliases for raw tokens for example
• Values folder with all the values of tokens for each tokens providers you defined above

Use inside these folders subfolders for component tokens, semantic tokens and raw tokens to keep things clear.

Define also the theme object with all the providers its needs, font registering methods and Bundle module defitions.

In the end add the documentation file.

Unit tests

Add units tests to ensure your raw tokens did not change. Add also unit tests to make controls on the type of your providers. If your tokens have kind of relationships between them, test them.

Snapshot tests and design system toolbox app

By adding a new theme you must keep updated the design ssytem toolbox app.

In the DesignToolbox target add your library in the Frameworks, Librairies and Emebded Content pane to let the app use your new theme.

Then look for the ThemeSelection Swift file and update it (theme name and themes provider).

In the end update the snapshot tests y adding new folders in DesignToolboxSnapshotsTests/Snapshots/Components and DesignToolboxSnapshotsTests/Snapshots/Tokens. You should copy, paste and update the files so as to define snapshots tests for all components and tokens.

You can find more details about snapshots tests in the wiki and also in the app repo DEVELOP file.

Need help?

You can have a look on the Orange, Sosh or Wireframe themes definition for example.

Tip

In any cases format your sources, run the linter, format the sources, and remove dead code.