theme-contract

The OUDS Theme Contract module defines the interfaces and data structures that constitute the Orange Unified Design System theme. It acts as a blueprint that guarantees the existence of specific tokens (like "Brand Primary Color" or "Heading Large Typography") without enforcing specific values.

It contains no values (no hex codes, no dp sizes), only abstract definitions.

Purpose

This module serves two main purposes:

Abstraction: It decouples the usage of tokens from their values. This allows different theme implementations (e.g., a "Dark Mode" implementation vs. a "Light Mode" implementation) to share the exact same structure.
Type Safety: It provides the Kotlin interfaces and classes that OudsTheme in the Core module implements. This ensures that every theme is complete and strictly follows the design system specifications.

Contract Structure

Package: com.orange.ouds.theme.contract

The contract is divided into semantic categories mirroring the design system structure.

1. Color Contract

Defines the semantic color slots available in the system.

Interface: OudsColorScheme
Categories: Brand, Content, Surface, Border, Status, etc.
Example: Defines that a brand.primary color must exist, but doesn't say it is #FF7900.

1.1. 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.

2. Typography Contract

Defines the text styles.

Interface: OudsTypography
Categories: Heading, Body, Label, Display.
Example: Defines that a heading.large style exists with properties for font, weight, and size.

3. Dimension Contracts

Defines abstract sizes, spaces, and borders.

Interfaces: OudsBorders, OudsSizes, OudsSpaces.
Example: Defines that a spaces.fixed.medium token exists.

4. Component Tokens Contract

Defines semantic tokens specifically scoped to OUDS custom components.

Interface: OudsComponentTokens
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.

5. Other Contracts

Includes interfaces for OudsElevations, OudsGrids, and OudsOpacities.

Usage Guidelines

For Application Developers

You typically do not interact with this module directly. You will use the implementation of this contract provided by the core module (via OudsTheme). However, understanding this contract helps you know which semantic tokens are guaranteed to exist.

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"
theme-contract	The Recipe Template	"A cake must have a base, a filling, and icing"
core	The Implementation	"This specific cake uses flour for the base and chocolate for the filling"

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.

com.orange.ouds.theme.tokens

androidJvm

This package contains the Key Token objects that define the organization of semantic tokens. It establishes the hierarchy (tree structure) used to access token values. Instead of a flat list, it groups tokens into logical categories (like OudsBorders, OudsSizes, or OudsSpaces), enabling structured navigation through the theme properties.

com.orange.ouds.theme.tokens.components

androidJvm

This package holds the contract for component-specific tokens (OudsComponentTokens). It defines the structure for overriding or specifying design values (like specific paddings or colors) for individual OUDS components, independent of the global theme values.

com.orange.ouds.theme.tokens.material

androidJvm

This package defines the OudsMaterialColorTokens interface, which establishes the contract for mapping OUDS semantic colors to the standard Material Design 3 color roles, ensuring seamless integration with native Compose components.

com.orange.ouds.theme.tokens.semantic

androidJvm

This package contains the interfaces defining the semantic properties of the theme. It hosts the contracts for colors (OudsColorScheme), typography (OudsTypography), borders, elevations, grids, and opacities. It dictates that every theme must implement these specific interfaces to provide the fundamental visual attributes.