(TODO Reference: definitions of tokens, etc)
Abyss Customers are in the business of shipping software - sites and apps. In the early days of Abyss, the brands of these apps were internal - such as UHC, Optum. However, the White-Labeling initiative (W/L) presents a different challenge that should be solved with a different engineering strategy than used for internal brands.
Optum Guide is the first customer whose app is intended to be white-labeled. To clarify - that means they will build an app with a default brand like Optum, then deploy it completely re-themed as another brand - FedEx or BestBuy for example - when a new client purchases Optum Guide for their employees. We want to solve the operational challenges of doing so.
For the White-Labeling team - Optum Guide - this means enabling maximum agility for them to respond to their customers' branding desires. For Abyss, this means keeping us scalable where our workload does not rise in proportion to how many customers are using Optum Guide. Any solution we propose has to meet those objectives before it can go in front of the customer - the risk is too great (if they accept something they don't fully understand the implications of) that we become committed to doing something painful, or need to change the plan once we see it's not going well.
One idea for achieving white-labeling is being proposed, and another idea is already architected into the Abyss library and customers' usage of it right now. Let's first look at the status-quo, the way tokens are currently setup:
Customers Own W/L Token Values
If you look in the Optum Guide code Programs Widget, you'll see files that contain values (colors, etc) that define the brand for their app. OG owns those values, and they provide those values to the tokens when the app starts, so Abyss components display using those values.
As an example, $AppBarColor is the name of a token that the AppBar component uses, so when their app runs, a value from their code is provided to that token.
Under white labeling, a similar process would be used. The OG app code would detect which customer's theme should load, apply those values to tokens, and then Voilà, Fedex' App Bar would have a Fedex color. All token value overrides are maintainable in their code.
Abyss Owns Customers Own W/L Token Values
The alternative approach proposed today is one in which "The Abyss Team will be responsible for all token updates". This is the way we handle internal themes like UHC today.
Here the consuming team only has a reference to a set of token values in their code - for example createTheme('fedex'), just as they would have when doing createTheme('optum').
Here, changes to token values for W/L branding have to go through the Abyss team. This has been proposed as a "Let us do that for you" kind of solution. But it introduces issues for both sides.
One can imagine different sources of change occurring, started by a W/L customer, or by UHC/Optum branding. Let's propose a scenario that Optum Guide is on version 1.60 of Abyss, and go preview some change workflows:
#1 - Imagine FedEx comes in with a new value for one of their brand tokens - say, a button height. In the customer-owned approach, OG will update their Fedex token values file, and rebuild and ship their app. That's all. In the Abyss-owned approach, they submit tickets to Abyss for changes, and must wait for a new publish of the Abyss library (version 1.61) in order for createTheme('fedex') to take on the new values. They will also have to accept any changes in 1.61 that are not related to Fedex tokens.
#2 - Imagine Abyss designers believe that in version 1.61 a button should be taller by default vs 1.60. (This could be a layout breaking change and discouraged, but suppose that it's a safe change). We could call this a change to a base white-labeling theme. When OG decides to upgrade to version 1.61, they'll get that new default - unless they've overridden it in which case they'll stay with their own.
Clearly, defaults can go through the release cycle, but overrides must not, because of the scalability issues.
Now - when will OG, designing for FedEx, see the Fedex Figma updated with that new button height? There might be some work needed there yet, but the answer I think is they should be able to apply their tokens to a new 1.61 Figma, and don't need to see changes in their files before then. Abyss team doesn't have to - should never need to - push updates to OG/Fedex design files. Token value files can apply to a new version of an app - they should be able to apply to a new version of Figma as well.
Figma is useful for designing, previewing, and deciding on the token values for a FedEx, or internal theme. But - Figma files are not the software that is shipped! Figma is a tool for figuring out what to put in the software. Figma files are intermediate representations of software. They could be bypassed entirely if Fedex said to change some brand value immediately.
If there is some bug in Figma that makes previewing or applying tokens difficult, can we choose limiting a customers' delivery speed, or taking on too much work for Abyss as a solution? Not if we care about customers' ability to ship software.
White-Labeling introduces a need for non-centralized control of token value files. The approach of internal themes like UHC will not scale. Abyss Customers need to own the token values for their customers. Abyss needs to enable that independence for its own scalability as well. Anything less will be seen as a regression by customers.
If we start from customers' needs, we'll see taking control from them slows everybody down. An inelegant workaround in Figma may be necessary until they fix that bug. But the architecture of ownership has longer-lasting ramifications than that short-lived pain. Let's put Figma, the theme-authoring tool in its proper place as an accessory to software development, and ensure that the development itself stays on the fast-track.