Theming

ACS UI Library uses components and icons from both Fluent UI, the cross-platform design system that's used by Microsoft. As a result, the components are built with usability, accessibility, and localization in mind.

Prerequisites

Note

For detailed documentation and quickstarts about the Web UI Library visit the Web UI Library Storybook.

Azure Communication UI open source library for Android and the sample application code can be found here

Defining a Theme

Theming on Android is handled via XML resource files. We expose the following resource IDs to the public scope:

<resources>
    <public name="AzureCommunicationUICalling.Theme" type="style" />
    <public name="azure_communication_ui_calling_primary_color" type="attr" />
    <public name="azure_communication_ui_calling_primary_color_tint10" type="attr" />
    <public name="azure_communication_ui_calling_primary_color_tint20" type="attr" />
    <public name="azure_communication_ui_calling_primary_color_tint30" type="attr" />
</resources>

Contoso developers can implement a Theme within their apps like this one to supply the primary color and tints.

<style name="MyCompany.CallComposite" parent="AzureCommunicationUICalling.Theme">
    <item name="azure_communication_ui_calling_primary_color">#7800D4</item>
    <item name="azure_communication_ui_calling_primary_color_tint10">#882BD8</item>
    <item name="azure_communication_ui_calling_primary_color_tint20">#E0C7F4</item>
    <item name="azure_communication_ui_calling_primary_color_tint30">#ECDEF9</item>
</style>

Affected UI

  • PrimaryColor:
    • Avatar/Video - Border - Speaking Indication
    • Join Call Button - Background
  • PrimaryColorTint10 Color:
    • Join Call Button - Background - Highlighted - Light Mode
    • Join Call Button - Border - Light/Dark Mode
  • PrimaryColorTint20 Color:
    • Join Call Button - Background - Highlighted - Dark Mode
  • PrimaryColorTint30 Color:
    • Join Call Button - Border - Highlighted - Light/Dark Mode

Applying the Theme

The theme style will be applied to pass the Theme resource ID to the ThemeConfiguration/Theme in the CallCompositeBuilder.

val callComposite: CallComposite =
        CallCompositeBuilder()
            .theme(R.style.MyCompany_CallComposite)
            .build()

Light/Dark modes

The Android resource system handles the night theme. Night mode on Android is a system-wide configuration. When night mode is enabled, preference is given to resources in the -night/ folders. To specify night mode colors, a second theme.xml would be added to the values-night/.

To enable night mode programmatically, Android provides the following function. However, this configuration applies globally to the application. There's no reliable way to set night mode for a single activity. Contoso can enforce a dark theme, they can use the below setting in their applications.

AppCompatDelegate.setDefaultNightMode(AppCompatDelegate.MODE_NIGHT_YES)

Azure Communication UI open source library for iOS and the sample application code can be found here

Defining a Theme

You can customize the theme by changing the primary color and its associated tints and the option of overriding the light and dark mode color scheme.

Affected UI

  • PrimaryColor:
    • Avatar/Video - Border - Speaking Indication
    • Join Call Button - Background
  • PrimaryColorTint10 Color:
    • Join Call Button - Background - Highlighted - Light Mode
    • Join Call Button - Border - Light/Dark Mode
  • PrimaryColorTint20 Color:
    • Join Call Button - Background - Highlighted - Dark Mode
  • PrimaryColorTint30 Color:
    • Join Call Button - Border - Highlighted - Light/Dark Mode

Implementation

Contoso developers can create custom theme options that implement the ThemeOptions protocol. They'll need to include an instance of that new class in your CallCompositeOptions.

class CustomThemeOptions: ThemeOptions {

 var primaryColor: UIColor {
  return UIColor(named: "primaryColor")
 }
 
 var primaryColorTint10: UIColor {
  return UIColor(named: "primaryColorTint10")
 }
 
 var primaryColorTint20: UIColor {
  return UIColor(named: "primaryColorTint20")
 }
 
 var primaryColorTint30: UIColor {
  return UIColor(named: "primaryColorTint30")
 }

 var colorSchemeOverride: UIUserInterfaceStyle {
  return UIUserInterfaceStyle.dark
 }
}

let callCompositeOptions = CallCompositeOptions(theme: CustomThemeOptions())

Define Color Assets

Define each color in the assets, with a shade for the light and dark modes. Like the below reference image, describe how Contoso can configure the assets on the XCODE project.

Screenshot of a I O S color assets example configuration.

Next steps