OEM design tokens

OEM design tokens are an Android Automotive OS (AAOS) implementation of the Material Design system. Unlike the algorithmic or user selection approach for token values on mobile, OEMs designate design token values. Design tokens represent the small, repeated design decisions that make up a design system's visual style and replace static values with self-explanatory names. Tokens are analogous to those defined by the Material Design system.

OEM token library

OEM design tokens are referenced through the OEM token library, which consists of the three components illustrated in Figure 1.

Figure 1. OEM token library components.

Static library

The static library component of the OEM token library facilitates access to token values as follows.

• Provides APIs to access OEM values for tokens.
• Enables opt-in overriding of token references in theme with OEM values.

Shared library

The shared library component is responsible for defining the following:

• Library name.
• Boolean opt-in for enabling for OEM token values.
• Style that provides OEM token values.

To accommodate OEM ownership of this shared library component, including an OEM-defined package name, OEMs can create an override of the shared library implementation.

Figure 2. Override a shared library implementation.

OEM shared library

OEM overrides of the shared library component allow for OEM ownership of the library while maintaining compatibility with other components in the OEM token library by providing a means for the package name and signature to be set by OEMs while leaving implementation of the shared library otherwise unmodified.

Overrides for a shared library can be defined as shown below:

override_android_app {
    name: "[OEM]-token-shared-lib",
    base: "token-shared-lib",
    package_name: "com.[OEM].sharedlib",
    rename_resources_package: false,
    certificate: …
}

To set token values, see Specify OEM token values.

Important: Shared libraries MUST be preinstalled on a system image.

OEM shared library customizations

To support varied schemes for token values (for example, model or drive mode differentiation), OEMs can provide dynamic values for tokens by targeting the OEM shared library with Runtime Resource Overlays (RROs). To learn more, see Change the value of an app's resources at runtime.

To set token values, see Specify OEM token values.

Specify OEM token values

To specify token values, set the corresponding attribute in the style OemStyle to the required value.

<resources>
    <style name="OemStyle">
        <item name="colorPrimary">#B0C5FF</item>
        <item name="colorOnPrimary">#002B76</item>
        <item name="colorPrimaryContainer">#003FA4</item>
        <item name="colorOnPrimaryContainer">#D9E2FF</item>
        …
    </style>
</resources>

Opt in to OEM values

So that apps can access OEM-provided token values, OEMs must first opt in to overriding default token values by configuring the enable_oem_tokens boolean to be true.

RRO token values

Similarly to how token values are set in OemStyle, RROs can be used to modify the style to provide alternate token values.

<resources>
    <style name="OemStyle">
        <item name="com.android.oem.tokens:colorPrimary">#B0C5FF</item>
        <item name="com.android.oem.tokens:colorOnPrimary">#002B76</item>
        <item name="com.android.oem.tokens:colorPrimaryContainer">#003FA4</item>
        <item name="com.android.oem.tokens:colorOnPrimaryContainer">#D9E2FF</item>
        …
    </style>
</resources>

RROs should set the shared library attributes on the style by specifying the shared library name.

Configure load last

Systems that include an OEM implementation of a token shared library must configure the system to load the shared library after the app classes. To do so, include the library name (com.android.oem.tokens) in the config_sharedLibrariesLoadedAfterApp config on the system. If you have access to Google Automotive Services (GAS), this is enforced as a requirement.

<!-- The OEM token shared library will be loaded after app classes -->
<string-array name="config_sharedLibrariesLoadedAfterApp" translatable="false">
    <item>com.android.oem.tokens</item>
</string-array>

Best practices

Best practices for the OEM token library are described below.

Enable a flexible update strategy

See the strategies below to ensure you build in flexibility with respect to updates.

OEM shared library

As system-shared libraries are required to be preinstalled on system images, devices must either ship with the library or the library must be added as part of an Over-the-Air (OTA) update (to learn more, see OTA Updates). However, including a stub implementation of an OEM override of an OEM token shared library on a system image allows for an update to a full working implementation to be pushed to devices at a later date without necessitating an OTA.

Shared library RROs

Although there is no requirement for RROs to be installed as system apps, doing so provides some update behavior that might be desired.

• Automatic updates of apps when users aren't signed in.
• Can't be uninstalled by the user (users can only uninstall updates).