White labeling with Abyss

Abyss is comprised of a group of designers, accessibility experts, engineers, and QE who work together to build design kits, component libraries, and documentation sites that are packed with prebuilt, reusable or global assets that align with our enterprise branding and accessibility standards to ensure quality, drive consistency, and help teams reduce redundancies in design and code, forging seamless collaboration across product portfolios.

Abyss helps teams create exceptional digital solutions and user journeys, enhancing user experience while driving familiarity for our end users across different platforms. Teams can feel confident using Abyss, leveraging our components and assets, knowing they don't have to do design or accessibility checks to ensure compliance.

In addition to reusability, we also offer flexibility for customization, ensuring products remain streamlined and effortlessly maintainable through the combination of leveraging what's available in Abyss and allowing teams to focus more of their time on specific user cases or product needs. This includes white labeling, which allows for design and engineering teams to take any of the reusable components, or building blocks, and apply their own styling and themes, rather than leveraging enterprise brand themes for UHC or Optum.

The goal

The Abyss brand aims to empower white label consuming teams to apply their own themes to the design system, ensuring flexibility for both development and design teams to fully own and manage their tokens. This approach reduces dependency on the core design team for updates while preserving a unified system structure, allowing teams to maintain consistency and efficiency in their digital solutions.

Glossary

White Labeling - The process of adapting a framework to support a specific brand or multiple brands not supported by Abyss, while allowing for customization.

Tokens Studio for Figma - Tokens Studio is the backbone of the abyss tokening strategy. It's a centralized place to create, manage, and export tokens to both Figma variables and as a dev-consumable JSON file. Read more on Tokens Studio here.

Tokens - Tokens are key-value pairs consisting of the token's name and value. These represent fundamental design decisions as abstract, reusable data. They allow for easy adaptation and customization of the Abyss Design System while maintaining consistency for any brand or style.

Theme - A set of tokens that define a brand.

Base Theme - A theme whose tokens are managed, published and versioned by Abyss, such as Optum and UHC.

White-Labeled Theme - A customized theme whose tokens are managed, published, and versioned by an Abyss consumer for the brands they maintain.

Setting up a white-labeled theme

To create a white-labeled theme, use the createTheme tool with token overrides:

1. Combine brand tokens

a) Using the flattenTokens function

Use the flattenTokens function to combine the tokens from the JSON files into a single object for each different brand. This function supports a layered system where tokens from different themes can override core, semantic, and component level tokens.

import { flattenTokens } from '@uhg-abyss/web/tools/theme';
import core from '..tokens/core.json';
import brand_A from '..tokens/brand_A.json';

const brandThemeObjectA = flattenTokens(core, brand_A);

b) Using the Live Token Editor

Alternatively, we have a Live Token Editor available in the header of this documentation site. This tool allows you edit tokens in real time and export them as a JSON file. This JSON can then be imported and used with the createTheme function.

2. Create theme objects

Use the createTheme function to create a theme object from the flattened tokens or imported JSON. This theme object will be used to apply the white label theme to your application. The createTheme function takes two arguments: the name of the base theme ("uhc", or "optum") and an optional object for any overrides you wish to apply, such as your white-labeled theme.

import { createTheme } from '@uhg-abyss/web/tools/theme';

const brandThemeA = createTheme('optum', brandThemeObjectA);

3. Implement new themes

Wrap your application with the ThemeProvider. Depending on the brand selected, pass in the needed brand theme to the theme object. This ensures that the brand theme is applied globally to all components within your application.

import { createTheme, flattenTokens } from '@uhg-abyss/web/tools/theme';
import { ThemeProvider } from '@uhg-abyss/web/ui/ThemeProvider';
import core from '../tokens/core.json';
import brand_A from '../tokens/brand_A.json';

const brandThemeObjectA = flattenTokens(core, brand_A);

const brandThemeA = createTheme('optum', brandThemeObjectA);

const App = () => (
  <ThemeProvider theme={/* insert brand theme here */}>
    {/* Your application */}
  </ThemeProvider>
);

Example