theme-contract

The OUDS Theme Contract module is the cornerstone of the design system's theming architecture. It defines the abstract interfaces that all concrete themes (Orange, Sosh, Wireframe, etc.) must implement.

It enforces a strict separation of concerns:

The Contract defines what can be styled (e.g., "Brand Primary Color").
The Implementation defines how it looks (e.g., "Orange #FF7900").

Purpose

This module guarantees consistency across applications. By coding against these interfaces rather than specific implementations, developers can switch themes dynamically without changing a single line of UI code.

Contract Structure

Package: com.orange.ouds.theme.contract

This module does not contain any values (hex codes, dp sizes). It only contains:

Interfaces: OudsThemeContract, OudsColorSemanticTokens, OudsFontSemanticTokens.
Token Objects: Abstract representations of semantic tokens.

Color Contract

Defines semantic color roles available in the system.

Interface: OudsColorSemanticTokens
Purpose: Ensures every theme provides colors for Brand, Surface, Content, Status, etc.
Example: Defines that a brand.primary color must exist, but doesn't say it is #FF7900.

Material Color Contract

Defines the mapping required to bridge OUDS tokens to the standard Material Design 3 color slots.

Interface: OudsMaterialColorTokens
Purpose: Ensures that native Material Compose components (like Button, TextField, Surface) automatically pick up the correct OUDS colors without needing manual overrides.

Typography Contract

Defines the text styles.

Interface: OudsFontSemanticTokens
Purpose: Ensures existence of Display, Heading, Title, Body, and Label styles.
Example: Defines that a heading.large style exists with properties for font, weight, and size.

Dimension Contracts

Defines abstract sizes, spaces, and borders.

Interfaces: OudsBorderSemanticTokens, OudsSizeSemanticTokens, OudsSpaceSemanticTokens.
Example: Defines that a spaces.fixed.medium token exists.

Component Tokens Contract

Defines tokens specifically scoped to OUDS custom components.

Interface: OudsComponentsTokens
Purpose: Allows overriding default values for specific components without altering the global semantic theme.
Example: Defines specific tokens for an OudsButton (e.g., specific background color) independent of the generic theme.

Other Contracts

Includes interfaces for OudsElevationSemanticTokens, OudsGridSemanticTokens, and OudsOpacitySemanticTokens.

Usage

For Application Developers

You typically do not interact with this module directly. You will use concrete implementations of this contract (like OrangeTheme, SoshTheme, etc.) via the OudsTheme composable provided by the core module. However, understanding this contract helps you know which semantic tokens are guaranteed to exist regardless of the chosen theme.

For Theme Creators

If you are creating a custom theme implementation (e.g., for a specific sub-brand) while maintaining full compatibility with OUDS components, you must implement OudsThemeContract.

Relationship with other modules

Module	Role	Analogy
global-raw-tokens	The Ingredients	"Flour", "Eggs", "Milk" (The raw values like `#FF7900`, `16dp`)
theme-contract	The Recipe Template	"A cake must have a base, a filling, and icing" (The rules defining what a theme is)
theme-orange / theme-sosh / ...	The Concrete Cakes	"The Orange Cake" or "The Sosh Cake" (Specific implementations of the template)
core	The Bakery Window	The access point (`OudsTheme`) that serves the chosen cake to the customer

Tokens versions

Android system	1.2.0
Orange brand	2.3.0

🤖 Note: Files in tokens packages are automatically generated by Tokenator based on the design definitions.
Any manual changes to these files will be lost during the next synchronization.

Packages

com.orange.ouds.theme

androidJvm

This is the root package of the contract module. It primarily defines the OudsThemeContract interface. This interface is the central point of the design system's abstraction. It aggregates all the specific sub-contracts (colors, typography, borders, spaces, etc.) into a single object that represents a complete theme. Any class claiming to be an OUDS Theme (like OrangeTheme) must implement this contract.