A request to change the primary brand color for a subset of themes supported by the design system led us to improve our entire color system by establishing semantic color variables.
50% projected efficiency gain for updating themes via semantic variables and shared tokens repo
100% of components utilize shared semantic variables across Figma, Web, iOS, Android, and Icon Libraries.
3+ improved themes by resolving theme exceptions (tech debt) for luxury and speciality retail brands
1 new theme
Ready to support Dark Mode and Inverted UI
Before: 678 total updates required.
Before semantic variables it would be a significant effort to update the primary brand color across all components.
172 web component instances
334 iOS + Android component instances
339 Figma component instances
After: 12 total updates required.
After semantic variables the design system could support this change at less than 2% of the effort previously required.
6 semantic variables (Code)
6 semantic variables (Figma)
Homebase, Wayfair's Design System, encompasses 8 distinct themes for web, iOS, and Android component libraries. Each theme comprises a collection of design tokens, which are variable sets applied to design system components. Design tokens serve as the foundational elements of the design system and are universally applied across all platforms to ensure brand and design uniformity.
These themes serve as a means to tailor component styles to match the unique aesthetic of different brands underneath the Wayfair umbrella. Theme architecture comprises a set of guidelines and principles that dictate how tokens are utilized throughout the entire system. For example, $core-color--60 is the background color for buttons. A simple request to change the primary brand color to $core-color--80 for a subset of themes for specialty and luxury retail brands led us to improve our entire color system.
The Problem
Implement semantic variables into the token system to support scalable brand differentiation across all platforms using a shared token repository and to improve the usability of the design system.
While base tokens are primitive values in our system and use context-agnostic naming (e.g. $core-color--60), semanitc variables are an additional token layer on top of base design tokens applied to components which communicate an intended purpose and reference the context within the token name (e.g. $backgroundPrimaryIdle). Semantic variables serve as aliases for foundational tokens and should be characterized by clarity, meaning, and descriptiveness to effectively convey the corresponding design value.
Semantic color variables and the use of a shared token repository for web and app helps create stronger brands by weaving brand identity throughout our digital products (across platforms) in a consistent, meaningful, and maintainable way.
Hosted in the shared token repository for both web and app engineering to pull from as one source of truth
Enables consistent color application across web and app components in code and design asset
Drives cost efficiency when making large-scale color updates
Allows for more theme differentiation to meet aesthetic brand needs
Supports a more consistent user experience
Sets up a framework to expand semantic variables to other token categories (e.g. density, spacing)
Unlocks future enhancements to support inverted UI and dark mode
Short Term Fix: Homebase implemented theme exceptions to override styles for the button component on AllModern, Joss & Main, and Perigold to support rebranding efforts. This was a short term fix that worked for a moment but created inconsistent color application throughout components.
Desired Outcome: Semantic variables were added as a high-priority roadmap initiative. Implementation of semantic variables would eliminate need to create theme exceptions and would also result in the ability to systematically change primary brand color for all applicable components.
Karlee (me!)
Product Design Lead
Blair
Creative Technologist
Rogin
Web Tech Lead
Anders
iOS Tech Lead
Chris
Android Tech Lead
Evaluated change proposals
Stakeholder interviews
Audit current design tokens
Initial token taxonomy proposal
Workshop of taxonomy
Finalize semantic variables and definitions
Apply semantic variables to component catalog
Update/fix components as we go
Prototype variables in Figma
Add semantic variables to shared token repository
Implement changes in Figma, web, iOS, and Android libraries
Publish documentation
Share and educate community
An audit of existing design tokens was conducted to assess their application across web and app platforms, revealing insights that informed the semantic variable token taxonomy and unveiled color usage disparities among components and platforms.
Evaluated by an Airtable Audit the current color tokens in the web system and legacy semantic variables in the app system to identify opportunity areas within the 8 themes that Homebase supports.
Reviewed submitted community proposals regarding color changes and stakeholder interviews to learn the current pain points and needs for color flexibility.
Investigated and determined how Figma Tokens Studio would support semantic variables and theming.
01.
Documenting color usage with semantic variables is essential to solidify detailed design choices and ensure the accessibility of our design system.
02.
Establish design consistency across platforms through the utilization of shared design tokens.
03.
Minimize the effort required to update themes by systemically making updates in a centralized place where changes automatically flow to all relevant areas.
I facilitated a workshop with 18+ collaborators representing design and engineering across all platforms to review proposed token taxonomy to progress this project forward by updating the team on process and getting everyone together to make decisions together.
The workshop lead to developing a semantic variable naming structure, a list of new variables and definitions, and each variable’s base token mapping per theme.
At the time of this project, Figma did not have native support for variables. I coordinated a spike with engineering to investigate Tokens Studio to support semantic variables in Figma. The investigation was successful (pictured!) and we were able to use Tokens Studio to document semantic tokens and apply them to components in our libraries.
To assist the design and engineering team in applying semantic color variables to components, I created a migration guide that mapped current assigned color usage on all components across web and app libraries to new semantic color variables.
The Airtable guide allowed me to delegate Figma library implementation across the entire Homebase XD team giving all designers hands on experience working with semantic color variables to build shared knowledge of our design system.
An Unthemed Button: Semantic color variables mapped on a button component from the Web Component Library.
Themed Buttons: Shows the semantic variable taxonomy stays the same but the swatch each theme maps to updates to the correctly mapped base token that's assigned in Tokens Studio.
Implemented new semantic variables in Figma into every theme library and ensured theming worked properly.
Implemented new semantic variables in Figma on components in web, app, and system icon libraries.
Add semantic variables to shared token repository and worked alongside engineering partners to adjust code assets to new variables utilizing the migration guide.
Educated the XD community on new semantic color system through presentations, help channel questions, and office hour appointments.
50% projected efficiency gain for updating themes via semantic variables and shared tokens repo
100% of components utilize shared semantic variables across Figma, Web, iOS, Android, and Icon Libraries.
3+ improved themes by resolving theme exceptions (tech debt) for luxury and speciality retail brands
1 new theme
Ready to support Dark Mode and Inverted UI
Before: 678 total updates required.
Before semantic variables it would be a significant effort to update the primary brand color across all components.
172 web component instances
334 iOS + Android component instances
339 Figma component instances
After: 12 total updates required.
After semantic variables the design system could support this change at less than 2% of the effort previously required.
6 semantic variables (Code)
6 semantic variables (Figma)
This work paved a path and established a reusable process to expand into more token categories. There are initiatives roadmapped to continue semantic variables into other categories such as density, motion, spacing, and type.
Both Web and App squads hosted hackathons after the launch of semantic variables. There were teams at both events that built a proof of concept experience in dark mode using the semantic color system successfully which ended up gaining recognition and excitement from senior VP leadership.
Introduced Shipping color semantic tokens for Speed and Premium. This allowed to very quickly achieve accessible and brand-coherent colors that adapt to all current and future Shipping Widget instances, without impacting other styles.
