​
Introduction

We leverage Fluent UI 9’s theme provider to manage and customize application colors. You can refer to their documentation for more details. There are two main ways to adjust the theme:
  1. Basic Theme
  2. Advanced Theme
By understanding these options, you can align the look and feel of the interface with your brand.

​
Basic Theme

A basic theme involves creating a color palette centered around a primary brand color. This primarily affects:
  • Primary buttons
  • Chat bubbles
  • Select Icons
  • Select brand-related UI elements
Other UI colors remain default, giving the interface a brand identity without overcomplicating the design. To create a basic theme you must generate a palette and then apply the theme.

​
Example Palette

{
  "10": "#011821",
  "20": "#045066",
  "30": "#04566c",
  "40": "#056078",
  "50": "#00647d",
  "60": "#00647d",
  "70": "#017490",
  "80": "#0088AA",
  "90": "#0194b7",
  "100": "#08b1da",
  "110": "#0fc1ec",
  "120": "#43d8fd",
  "130": "#47d6fa",
  "140": "#84e9ff",
  "150": "#a3f8ff",
  "160": "#eefcff"
}
Note: The 80 key in the palette represents the primary brand color that influences the rest of the theme.

​
Generating a Palette

An efficient way to generate a new palette is to use a tool like Chat GPT. Provide an example palette (such as the one above) and your new primary color. The AI can then produce a coordinated set of colors.

​
Prompt Example:

I want you to make me a palette for a web application.
I will give you an example palette and a new primary color.
The primary color in the old palette is the color in the "80" position.
Here is the palette:
`
<example_palette>
`
And my new primary color is: `<new_primary_color>`
After receiving a generated palette, you can apply it.

​
Applying Theme

Once you have your palette, you’ll need to apply it to the tenant. Themes are applied per tenant, so you must include the tenant identifier in the request headers.

​
Endpoint:

PUT /api/v1/frontend/config/theme/update

​
Headers:

X-Organization-Id: YOUR_TENANT_ID Authorization: YOUR_AUTH_TOKEN Example curl Request: 
curl
--location
--request PUT 'https://YOUR_DOMAIN/api/v1/frontend/config/theme/update' \
--header 'X-Organization-Id: TARGET_TENANT' \
--header 'Content-Type: application/json' \
--header 'Authorization: ******' \
--data '{
  "10": "#210203",
  "20": "#4c0507",
  "30": "#600607",
  "40": "#7a080a",
  "50": "#930a0c",
  "60": "#ab0b0d",
  "70": "#c20c0f",
  "80": "#E10D11",
  "90": "#f01315",
  "100": "#ff2b2f",
  "110": "#ff4a4e",
  "120": "#ff6e72",
  "130": "#ff8990",
  "140": "#ffabb1",
  "150": "#ffd1d4",
  "160": "#fff3f3"
}'

​
Advanced Theming

Advanced theming gives you complete control over every color variable in the UI. This option includes all the capabilities of the Basic Theme approach, but allows you to fine-tune every color for both light and dark modes. This ensures a fully customized and accessible design that perfectly matches your brand and user experience goals. Important Consideration: Modifying these values can introduce accessibility challenges. Fluent UI 9’s default themes are designed for optimal contrast and readability. Always review changes to ensure they meet accessibility standards (e.g., WCAG guidelines).

​
Common Colors

If you don’t need to customize every color, start with these commonly used variables. Adjusting them will have the most noticeable effect on the overall look and feel:
Changing these colors can lead to poor contrast or readability. Always test your theme after making adjustments.

​
Backgrounds

[
  {
    "value": "colorNeutralBackground1",
    "usage": "Main background color"
  },
  {
    "value": "colorNeutralBackground1Hover",
    "usage": "Main background hover color"
  },
  {
    "value": "colorNeutralBackground1Selected",
    "usage": "Customer chats, user tags, card grid items"
  },
  {
    "value": "colorNeutralBackground3",
    "usage": "Secondary background color"
  }
]

​
Foregrounds

[
  {
    "value": "colorNeutralForeground1",
    "usage": "Main Text Color"
  },
  {
    "value": "colorNeutralForeground1Static",
    "usage": "The main text color in light mode, that doesn't change in dark mode. Should match colorNeutralForeground1"
  },
  {
    "value": "colorNeutralForeground3",
    "usage": "Secondary Text Color"
  },
  {
    "value": "colorNeutralForegroundDisabled",
    "usage": "Disabled Text Color"
  }
]

​
Other Key Variables

[
  {
    "value": "colorNeutralStroke2",
    "usage": "Main Border Color"
  },
  {
    "value": "colorBrandForegroundLink",
    "usage": "Link color"
  },
  {
    "value": "colorBrandForegroundLinkHover",
    "usage": "Link hover color"
  },
  {
    "value": "colorBrandForegroundLinkPressed",
    "usage": "Link pressed color"
  }
]

​
Comprehensive Customization (Everything)

For full control, you can manually specify every Fluent UI 9 theme variable. This approach is time-consuming but ensures a meticulously tailored UI, allowing you to account for both light and dark modes individually. Tip: If a variable for a given mode (light/dark) is not set, it falls back to the default value, ensuring that unmodified parts of the theme remain stable. For a complete list of variables:* Visit the Fluent UI 9 documentation.

​
Advanced Theme Example

Below is an example of applying an advanced theme that sets both brand colors and some additional variables for light and dark modes. 
curl
--location
--request PUT 'https://YOUR_DOMAIN/api/v1/frontend/config/theme/update' \
--header 'X-Organization-Id: TARGET_TENANT' \
--header 'Content-Type: application/json' \
--header 'Authorization: ******' \
--data '{
  "10": "#210203",
  "20": "#4c0507",
  "30": "#600607",
  "40": "#7a080a",
  "50": "#930a0c",
  "60": "#ab0b0d",
  "70": "#c20c0f",
  "80": "#E10D11",
  "90": "#f01315",
  "100": "#ff2b2f",
  "110": "#ff4a4e",
  "120": "#ff6e72",
  "130": "#ff8990",
  "140": "#ffabb1",
  "150": "#ffd1d4",
  "160": "#fff3f3",
  "light-colorNeutralStroke2": "#708090",
  "dark-colorNeutralStroke2": "#434D54",
  "light-colorNeutralForeground3": "#708090",
  "dark-colorNeutralForeground3": "#434D54"
}'

​
After applying changes:

  • Test your UI in various light and dark environments.
  • Verify text readability, link states, and background colors.
  • Adjust further as needed to maintain a high-quality, accessible design.

​
In Summary:

  • Basic Theming: Quick branding by changing the primary color and its palette.
  • Advanced Theming: Complete customization for all UI elements, ensuring your brand and UX goals are met while maintaining accessibility.