Open notlee opened 2 years ago
Draft proposal moved from PR: https://github.com/Financial-Times/origami/pull/129
Ooops, @todo
just got a few notifications
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.
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 👍
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?
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.
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
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
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
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).
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.
Secondary/Paper
(Figma) to either--o-colors-paper
(CSS) oroColorsByName('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.
o-brand
oColorsByName
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:
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:
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:
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: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.
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:
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
The Figma Tokens plugin is actively developed and has added a number of exciting features recently:
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:
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:
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:
it's a more attractive approach now IE11 support is close to being dropped
cons:
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.