Proposal: Design Tokens

[notlee]

Introduce Design Tokens

Design token exploration branch.

Proposal Audience

This is a big proposal. It's intended for the Origami team primarily to document our thinking, decisions made, and outstanding questions. Since it's quite a big proposal to share without context, we expect to raise parts of the proposal with relevant teams to gather their feedback and contributions.

Summary

Design tokens are a method to store, document, and distribute design decisions across platforms; for example brand colour, spacing, and typographic scale values across web, native apps, and design tooling. There is a growing ecosystem of methodologies and tools around design tokens to support team collaboration and new product development.

As yet there is no standard for design tokens which tools can rely on, there's fragmentation in the ecosystem, however the W3C Design Tokens Community Group are working on it.

However, using design tokens now to manage brands within Origami, as opposed to Sass, has a number of potential benefits.

Motivation

1. Enable Origami to officially support more brands and sub-brands
2. Enable Origami to officially support dark mode, and improve support for high contrast mode
3. Simplify the Origami Sass interface to improve adoption by and experience of web engineers
4. Improve support of JavaScript application development
5. Support native application development
6. Help designers deliver more quickly and consistently
7. Reduce miscommunication in designer/engineer handover
8. Empower cross-group teams to review brand/design decisions and propose changes

Enable Origami to officially support more brands and sub-brands

Origami components may support multiple brands but adding support for new brands is time consuming and difficult. Including for sub brands, as brands cannot be based on another. This means, for example, Origami is unable to fully support partner content projects. Partner content is a derivative of the core brand but without our editorial voice. Note in the screenshot below that header, footer, and other components are the same as ft.com but with changes to remove the editorial voice, the lack of serif for example, and introduce elements of the partner brand.

Since Origami does not support this derivative of the core brand it's difficult to work on from a design and engineering perspective, as it's less well documented, and difficult for 3rd parties to produce products which follow design decisions made by the Creative team for this sub-brand.

In addition improvements to Origami's brand management would help support entirely new brands more easily beyond the existing core, internal, and whitelabel brands – Specialist Title brands.

Enable Origami to officially support dark mode, and improve support for high contrast mode

We have an experimental dark mode option available on the hybrid ft-app but it works by inverting colours automatically without design oversight, and as Mark in the apps team says: “the brand is completely lost and in some places the colours become meaningless, often distracting”.

Design tokens provide a structure to configure dark mode for a given brand/platform.

Simplify the Origami Sass interface to improve adoption by and experience of web engineers

As brand configuration is currently private Origami users can't access brand configuration to align with Origami components, unless the component implements Sass to pass brand variables through to the user, e.g:

• oColorsByUsecase - Return the defined palette color for a use case / property combination (like link text colour)
• oButtonsGetColor - Return the color of a button property for a given theme and state.
• oTypographyGetFontFamily - Return the font family for "sans", "serif", or "display" text.
• oSpacingByName - Return a recommended space size by name, e.g. "s2".

The correct Sass function for a given component is difficult to find, remember, and use – wasting time, increasing inconsistency. Generating a single Sass package with consistent naming/structure will help improve this. Plus, Sass variables may be autocompleted by text editors where the arguments for Origami's existing Sass functions cannot be reliably.

Improve support of JavaScript application development

As brand values are configured in Sass these values are not accessible to JavaScript (or other languages).

• o-colors - Outputs a number of CSS Custom Properties ad-hock, as does o-spacing.
• o-grid - Has a workaround which involves Sass generating JSON, outputting that as CSS on a HTML pseudo element, for JavaScript to grab.
• dotcom-page-kit cannot access the Sass font variable with JavaScript for font preloading and hardcodes the font url. When this gets out of sync with Origami multiple fonts are loaded, a significant ft.com performance hit.
• spark-api generates emails which can't use Origami and hardcodes colour values in JavaScript

These patterns of adhoc transfers of values from Sass to CSS/JS, or copy-pasting values, increases complexity, wastes time (what's the paper hex again? what's the colour of a hovered primary button on a dark background?), and reduces consistency. Reduced consistency reduces the strength of our brand and quality of our products. Related issues such as double font loading impacts site performance which strongly impacts engagement.

Support native application development

Whilst the current ft-app renders UI in a web view, and uses Origami components, the FT are developing new native apps which won’t be able to use Origami the same way. In a lot of cases we won’t want to, there’s value in a native experience, with native UI. However there are many brand design decisions we do want to share. There's value in documenting divergences and maintaining a design system package to support ongoing development or the development of similar experiences – potentially by a different team. Generating both a web and native api will also help in aligning a web view using Origami components (such as for an article page) with the rest of the native experience.

Help designers deliver more quickly and consistently

Currently designers maintain a Figma UI kit manually which is used to support the development of new designs whilst following existing design conventions and brand guidelines. This includes design decisions currently encoded in Origami such as typographic scale, colour palettes, logos, etc. As Figma UI Kit maintenance is manual, we currently have only one UI Kit for the core brand. We have no standard UI Kit for dark mode, no UI Kit for variants of the core brand (like partner content), no UI Kit for high contrast mode, no UI Kit for the internal brand... auto-generating UI Kits will help us maintain multiple kits that designers could switch between. Designers for non-core brand products, and designers working on other modes of the core brand, would benefit from the same toolkit as core-brand designers to speed up their workflow. Sharing a tooling may help designers switch between different projects.

Reduce miscommunication in designer/engineer handover

The Origami team work closely with the design team to keep Origami and our Figma UI kit in sync but name/name structure can diverge, and some values are missing from either the Figma UI kit or Origami. This can lead to wasted time and confusion for both designers creating new product designs and engineers looking to implement a design on handover. Sometimes this can be resolved with a back-and-fourth conversation between designer and engineer. At other times values may be hardcoded by the engineer which may not follow our design guidelines or may make maintenance more difficult when we come to roll out updates.

• o-colors usecases includes colours by uscase (e.g. link text colour) which are not listed in the Figma UI kit used by designers. As designers can't specify these in Figma, engineers are less likely to use them on handover. Also, as designers don't have oversight of the Origami values some may be outdated.
• Where design values are shared naming/naming structure differ so an engineer needs to translate a design which references the colour Secondary/Paper (Figma) to either --o-colors-paper (CSS) or oColorsByName('paper') (Sass). These could be defined in one place and use the same name across platforms to improve engineer/design communication and hand over.

Design tokens could help keep these in sync consistently to improve design/engineer communication.

Empower cross-group teams to review brand and design decisions and propose changes

Currently low level design decisions are documented in multiple places. In brand guidelines, in the Figma UI Kit, in Origami components, and in a private Notion file(s).

Documenting design decisions in a central place alongside design tokens will allow designers to understand the thinking behind past design decisions to improve the speed and quality of future work. Non-designers will also benefit from understanding the reasons a design decision is made too, for example if an engineer is wondering when to use one value or another. Public documentation will also help when it comes to deprecating one design decision for another and sharing a migration path.

Giving designers, or anyone, autonomy to update design decisions without coding knowledge will encourage contribution and help ensure the design team have ownership over the decisions.

Work required

The following is a high level view of work required, not strictly ordered. This proposal considers a broad range of motivations and a large amount of interconnected work, which is unrealistic to commit to at once, see the Proposed Approach section below.

1. Use design tokens internally within Origami;
   • This will allow us time to experiment with token naming and structure
   • Use Sass/CSS and JavaScript output from design tokens to replace o-brand
2. Publish design token Sass and JavaScript for Origami users;
   • Allow Origami users to use token output
   • Deprecate Sass such as oColorsByName
3. Publish native asset libraries; e.g.
   • Add design tokens for native app brand differences
   • Publish IOS asset catalogue
4. Build a Figma plugin to generate UI Kits from Origami design tokens
5. Build a user interface to view and edit design tokens

Use design tokens internally within Origami

1. Choose a design token translation tool

To begin using design tokens we need a design token translation tool which will take design tokens defined in one format and transform them for the platforms we want to support. Examples include:

• Theo (Salesforce)
• Style Dictionary (Amazon)
• Diez (Haiku For Teams)
• Specify
• Knapsack

Salesforce popularised the term "design tokens" with Theo. Theo and Style Dictionary seem similar. Both support token transforms (e.g. hex colour to rgba) and formats (e.g. json, Sass), and both allow for custom transforms/formats. For the purposes of a proof of concept we spent more time investigating Style Dictionary. Compared to Theo, Style Dictionary has a greater number of transforms and formats, more open source contributors, and more helpful documentation / guides.

Diez is a compelling tool. Like Theo and Style Dictionary, Diez has a concept of transforms known as prefabs and formats known as targets. It also supports pulling tokens from design tooling such as Figma out of the box. In addition Diez generates some nice documentation, which includes documentation for each supported platform. However, as it is more opinionated this means it also seems less flexibility. It's not clear for example who we'd implement dark mode for native apps. Whilst the compiler is apparently extensible there's no guide on adding new prefabs or targets. By comparison with Style Dictionary we can create a custom format to generate an ios asset catalog, which is documented by the creator. More options were in the roadmap according to the fqa, however Diez is now no longer being worked on by the team who created it and it does not seem to have a very large/active open source community.

Specify and Knapsack are different in that they are paid-for services for managing design tokens. They excel in showcasing tokens and allowing different teams to edit them, and both have integrations for various platforms. However they are both early access and perhaps not mature enough for us to rely on. They don't appear to meet our needs in terms of handling multiple brands/sub-brands/modes. More investigation might be worthwhile though. We'd want to contact the vendors to get access on a trial period.

Although Style Dictionary will require work to document tokens and integrate with design tooling it offers the best community support, public documentation, and customisation to meet our aims. We can use Style Dictionary to generate a private Sass/JS SDK and use this internally within Origami components, before making public or adding support for further features / platform integrations.

2. Define design tokens

Using our design token translation tool (Style Dictionary) we need to define design tokens. This should be a collaborative process between front-end web engineers, designers, and native app engineers as we will all use the same token structure/naming but some terms may have different meanings in different contexts e.g. padding/margin on web vs. native.

Token Structure

Origami components currently has 3 kinds of variables which could be considered tokens:

• Base values (colour palette, spacing, typographic scale)
• Usecases (generic usecases, like the colour of a link defined in o-colors, or font family for a sans font in o-typography)
• Components (component specific, like the colour of a button, the background of an overlay)

These map pretty closely to the structure advocated by Brand Frost. It's also not dissimilar from the 2 tier structure shared by Lukas Oppermann(creator of the Design Tokens Figma plugin), who suggests a split between base values “option design tokens” and usecase/component “decision design tokens”.

We propose a 2 tier split to help when talking about design tokens:

1. option design tokens (colour palette, spacing, typographic scale)
2. decision design tokens (usecases, including generic usecases such as link colour and component usecases such as background of an overlay)

This split is conceptual and related to how tokens are used and referenced. Option design tokens hold raw values and decision design reference them, or other decision tokens. Lukas recommends keeping option tokens internal, used only to define decision tokens, so each public token includes context of where it is used. This makes it easier to push out granular updates to design tokens without creating visually breaking changes. Strictly keeping option tokens internal might not be practical for us given the size and number of teams building products with Origami. It would be easy for an engineer to misuse or misunderstand a decision token instead of consulting the Origami team or adding a new token with a name which better reflects their usecase. We should though encourage the use of decision tokens (color/text/link) over option tokens (color/teal), so we can push out design updates whilst maintaining consistency.

Within decision tokens component specific tokens could be namespaced by component, but shouldn't map directly to an o- Origami component as these tokens will be used outside of components. Style Dictionary uses a category (color) / type (background) / item (button) structure to apply the correct meta-data to tokens which is used for transforms:

# option design tokens
color/teal
size/s1

# decision design tokens
color/text/link
color/background/page

# decision design tokens (button component)
color/text/button/primary/base
color/background/button/primary/base
color/text/button/primary/active
color/background/button/primary/active

We may decide on a different structure, for example a component orientated structure, but more work would be required to apply the correct meta data to each component.

# option design tokens
color/teal
size/s1

# decision design tokens
color/text/link
color/background/page

# decision design tokens (button component)
button/primary/base/color
button/primary/base/background-color
button/primary/active/color
button/primary/active/background-color

Work is required to decide on what tokens to add, in what structure, and which to make public.

3. Publish/use token npm package containing Sass/JS

We should add new tokens thoughtfully and keep them to a minimum, bearing in mind we later want to make them public. The token package will be the most low level dependency of all components, future breaking changes may cause a cascade.

However there are some questions remaining, including:

1. How exactly do we use tokens within existing components to support switching brands / dark mode / customisation?
2. Should components depend on tokens via npm or a build step? The latter could avoid some major cascades.

Publish design token Sass and JavaScript for Origami users

When we're confident in the design tokens we have defined we can publish them publicly on npm as a package of Sass/JS for other teams to use. These will replace large parts of low level components like o-colors and o-spacing. Features of these components which can be replaced should be deprecated, e.g. oColorsByUsecase, oSpacingByName.

Publish native asset libraries

Confirm which tokens are useful for app developers and publish native packages for Android and an IOS asset catalogue. The experimental branch design token branch includes an example. See also the light app codebase.

Build a Figma plugin to generate UI Kits from Origami design tokens

To keep engineering and design in sync we could use one of the follow Figma plugins to author tokens in Figma and push to Origami via Github:

• Figma Tokens plugin
• Design Tokens plugin

Figma Tokens plugin

The Figma Tokens plugin is actively developed and has added a number of exciting features recently:

• provides a UI to import and create tokens
• supports token sets to support themes/modes, multiple themes can be applied at once
• handles references (one token pointing to another)
• supports math (e.g. "{spacing.xs} * {spacing.scale}")
• can push tokens to Github by triggering an action (new!)
• supports syncing a token's description with text in a figma frame, to help maintain in-figma documentation

Each designer will need to have the plugin installed, which can be managed with our enterprise license.

THe Figma Tokens plugin stores tokens as meta data in a Figma document. Therefore a designer will need to import the tokens when creating a new document, to do that our tokens must be synced with an external api (e.g. our own api, or JSONBin.io). Our own api might be best to support a review process. Token updates can be pushed to Github and trigger a Github action. If the changes are breaking, or otherwise not quite right, we wouldn't want designers to pull them into new projects.

To apply tokens in Figma the plugin UI must be used rather than Figma's usual interface, a potentially significant change to our designer's workflow on top of syncing tokens when creating a new document.

Design Tokens plugin

The Designs Tokens plugin is also actively developed, and covers many of the same features. However:

• references aren't supported, so one token can't reference another (this is being worked on by the maintainer)
• token's are represented using Figma concepts rather than plugin metadata
• limited theme support

Because token's are represented using Figma concepts rather than plugin metadata our Figma workflow would be similar to now. With some renaming of some frames/layers/styles, our current Figma UI Foundations file cound be used to generate token's and push them to Origami.

The downside of this is that creating Figma UI Foundation files is a quite manual and time consuming process. We'd want to create a new foundations file manually for core, internal, and whitelabel brands. And again for dark mode. And again for any future sub-brand variants. And keep them all up to date. The UI of the Figma Tokens plugin makes it much easier to manage multiple brands and modes.

The lack of token references (for now) is another major issue for us. We want to create decision tokens (usecase tokens) and have them update wherever they've been used.

Custom Figma Plugin

Figma isn't a natural place to author design tokens at the moment, particularly not for multiple brands/sub-brands/modes. Hopefully that will change if a W3C standard is published.

To avoid requiring Figma users to learn new workflows, and the manual work required to maintain multiple UI Kits, we could push tokens to Figma instead and generate UI Kits using the Figma Plugin API.

The design tokens exploration PR includes a proof of concept.

Being able to quickly generate UI Kits for multiple brands/modes is great. It doesn't change our designer's workflow, or how they use Figma. On the other hand, as well as the cost of maintaining a Figma plugin, there's one major downside: Token changes, Figma UI Kit chances, require JSON updates in the Origami codebase. That's not very accessible to designers but they should feel ownership over the tokens. We could find a tool or create one to preview and edit our design tokens, but that could be a significant piece of work (see the following section).

Build a user interface to view and edit design tokens

Designers should feel full ownership over desk token values and feel empowered to make changes, which is difficult without a UI to edit tokens. There are services/tools including knapsack, specify, zeroheight, design token (figma plugin), and figma tokens (figma plugin) to manage design tokens visually, however many of these are limited in some way or are in the early stages of product development - invite only - this is a growing market. We may be able to build a web interface to edit design tokens in the Origami codebase but how much work that would be hasn’t been scoped. I've spoke to Leo and Louise and both think it's worth trialling auto generated Figma foundation files without a UI to edit them initially.

Proposed Approach

This proposal considers a broad range of motivations and would be a huge amount of work. A supporting project would be helpful to rein in the scope of the proposal to focus on delivering part of it whilst answering some remaining questions:

1. Replace o-brand with design tokens internally
2. Create a Figma plugin and an updated Figma UI Kit which supports the internal brand, core brand.
3. Collaborate with the apps on official dark mode. Generate dark mode Figma foundation file.

We could then review and prioritise other aspects of the proposal before implementing.

Alternatives

Sass/CSS only

We could update Origami Sass, use Sass modules / CSS custom properties.

pros:

• improve support of sub brands / dark mode
• more simple, less tooling, no separate token package to support
• it's a more attractive approach now IE11 support is close to being dropped

cons:

• no workflow improvements for designers, since we wouldn't be able to generate multiple foundation files
• no improvements in engineer/designer hand over discussed above
• no path to native app support

Author design tokens via Figma plugin

See pros/cons above. More details here with screenshots.

Author design tokens via service

E.g. knapsack, specify, zeroheight. More details here with screenshots.

[notlee]

Draft proposal moved from PR: #129

[notlee]

Ooops, @todo just got a few notifications

[notlee]

Please review and comment team. We have a Q1 OKR in place to replace o-brand with design tokens internally, for 50% of components; and are talking with the apps team about spiking dark mode – looking to move that to a future Q.

[JakeChampion]

I agree with the proposed approach as it is small in it's scope and allows us to get real-world experience in using design tokens within figma and origami code 👍

[chee]

Plus, Sass variables may be autocompleted by text editors where the arguments for Origami's existing Sass functions cannot be reliably.

i found this sentence confusing to read

---

Publish IOS asset cagoule

what does cagoule mean here?

---

There's a lot of context in this proposal, and multiple lists of things to do, and I'm not clear on what work accepting this proposal actually commits us to?

[notlee]

Thanks for taking a look @chee!

i found this sentence confusing to read

Did you figure out the meaning? I'm open to suggestions for phrasing that line differently.

what does cagoule mean here?

Oh yes, I forgot to define that. I've added a link to the Apple docs.

This is a helpful summary: "While Android has resources, iOS has assets. iOS has image and color assets, which can support color modes (and have more modes than just light and dark too). Assets are stored in an asset catalog which is a folder with sub-folders that have a specific extension (.colorset or .imageset) and a JSON file named Contents.json." - https://dbanks.design/blog/dark-mode-with-style-dictionary/

There's a lot of context in this proposal, and multiple lists of things to do, and I'm not clear on what work accepting this proposal actually commits us to?

The "Proposed Approach" heading is the course of action this proposal commits us to.

[chee]

what does cagoule mean here?

Oh yes, I forgot to define that. I've added a link to the Apple docs.

I think maybe there is a typo there. The proposal says "cagoule" which i think is a kind of hooded anorak and sometimes when they are rolled up the hood (or front pocket) doubles as a bag into which the cagoule can be packed but the website says "catalog"

The "Proposed Approach" heading is the course of action this proposal commits us to.

okay this looks good to me

[notlee]

The proposed approach has been dropped. We’re working on getting buy-in on initiatives such as improving Origami’s multi-brand / theme / platform support so we can grow the team to support continued work. The investigation and design token exploration will be helpful to feed into that