Aug 14, 2022

Navigating Design Tokens

In a financial institution

Scenarios

Use case	Description
Designer	As a designer, I need to be able to understand how to navigate the use of design tokens so that I can ensure I am using the appropriate tokens outside of components and can more effectively handoff to our developers.
Developer	As a developer, I need to be able to distinct tokens to use per channel so that I can implement code in parity with designs being handed off for implementation.
Analyst	As a analyst, I need to be able to understand enterprise design decisions so that I can be intentional with writing scrum requirements with interactions between designers and developers.

Context

A brief glossary to align on some terms before proceeding without a shared understanding on terminology.

Tools

Term	Definition	Alias
Figma	A cloud-based design tool that allows users to create, share, and test designs for websites, mobile apps, and other digitial products.	Figgie
Token Studio	A centralized platform for organizing, updating, and sharing design tokens between designers and developers.	Design repository, Design syncing
Storybook	A frontend workshop for building UI components and pages in isolation.	Design syncing
Style Dictionary	A system that allows you to define styles once, in a way for any platform or language to consume across channels like Android, iOS, Web, and Figma.	Style translator
GitHub	A developer platform that allows developers to create, store, manage and share their code.	Code repository, Code syncing

Foundations

Term	Definition	Alias
Design token	Small, repeatable design decisions to reduce duplicative hard-coded values like pixel sizes or hex codes.	Variable, Style
Token tier	A collection of tokens intended to layer and map from hard-coded value to predictable naming conventions.	Core, System
Theme mode	A collection of tokens that enable the modification of visual and interactive aspects of a user interface independently from its structure and functional components.	Color, Density
Design theme	A theme is an intentional, systematic customization of design tokens to create a consistent design language across business domain, platforms or products.	Brand
Parity	Ensured alignment across capabilities like code and design with minimal discrepancies.	Consistency

Problem Statement

Our current token configuration is limited in enabling simultaneous variable theme collections like color and density in Figma. This limitation will impact the ability for themes to coexist long term. Style dictionary tokens do not seamlessly sync with Figma due to missing metadata files. This constraint requires exploring API tools to sync with Figma variable IDs, like Token Studio to sync between design software and production code, otherwise Figma will not know how to transform design tokens to be consistent with code.

Underlying problems:

Syncing tokens natively within Figma and GitHub exclusively is not a current option, requiring additional third-party integrations to maintain design and code parity.
Licensing at an enterprise level for third-party tools can quickly increase in operational maintance that internal creation of APIs may need to be a consideration.
Figma lacks built-in support for responsive queries. We lack guidance on scale for typography, width, height, spacing and radius for breakpoints.
Figma didn't immediately support typography variables before initial MVP release.

Considerations

Informing our acceptance criteria

Consideration	Criteria
Our token naming structure is lengthy and crops for designers on Figma UI, losing the context of intended usage for findability.	Ease-of-use
Integrate backwards compatability in token descriptions for finding tokens by fall back value like hex color.	Ease-of-use
Refine container tokens to be more clear to differentiate layout from grid, layer, and box.	Consistency
Distinguish relationship between component vs layout density preferences.	Consistency
Distinguish token tiers to clarify what is "out of the box configuration" vs modified to meet app level requirements.	Consistency
Provide end-to-end demos walking through token creation, to token integration in component and layout.	Support
Provide process for requesting new tokens, updating existing tokens, or deprecating tokens no longer being used.	Support
Integrate token usage as part of changelogs to understand visual changes when syncing design system updates.	Support

Examples

Reframe the intent of themes as they relate to token dependencies

Understanding token structure

Core is the reference token for color palettes programatically generated to provide flexibility in defining accessible color combinations to use as system tokens.
System is the common mode of visual objects and influences light and dark mode by isolating color for foreground, background, and fill.
- Brand is a sub-tier in system to support use cases where brand differs across product apps.

Understanding color modes

Light mode is ideal for well-lit environments, providing a traditional and familiar look. Users may prefer a white or light gray background with dark colors like black or dark gray for text.

Dark mode reduces eye strain in low-light conditions. Users may prefer a black or dark gray background with light-colored text, typically white or light gray.

• • •

Redefining our color tiers

Category considerations for color groups:

Category	Examples
Brand	Interactive elements that hold a need for brand prominence such as actions or decorative media assets.
Hierarchy	Primary, secondary, tertiary prominence, this is influenced by brand category.
Backgrounds	Body background, card/modal/popover/tooltip surface
Text	Text on various backgrounds such as link color on green background
Status	Indicators with distinct semantic meaning per product app.
Data visualization	Charts with distinct semantic meaning per product app.

• • •

Redefining our numerical tiers

Size is the Figma equivalent mode in design to css queries for responsive design, they influence width, height, radius, text and type scale. Note The difference between text and type scale is text is the text font, weight, line, size properties used in context of a component. Type scale is the combination of the properties as they relate to a type scale like page, section, and layer.
Density is the spacing and layout of elements, this defines the gap, padding and margins.