Table of Contents
1 | Introduction to Design Tokens
2 | Managing and Exporting Design Tokens With Style Dictionary
3 | Exporting Design Tokens From Figma With Style Dictionary
4 | Consuming Design Tokens From Style Dictionary Across Platform-Specific Applications
5 | Generating Design Token Theme Shades With Style Dictionary
6 | Documenting Design Tokens With Docusaurus
7 | Integrating Design Tokens With Tailwind
8 | Transferring High Fidelity From A Design File To Style Dictionary
9 | Scoring Design Tokens Adoption With OCLIF and PostCSS
10 | Bootstrap UI Components With Design Tokens And Headless UI
11 | Linting Design Tokens With Stylelint
12 | Stitching Styles to a Headless UI Using Design Tokens and Twind
What You’re Getting Into
In my previous articles, I have written about automating the process for the entire design to developer handoff. This has included building a working demo of extracting JSON files representing design tokens from a Figma file, importing them to a Style Dictionary repository, and exporting the transformed tokens to consuming applications.
The key thing to observe is that this automated process anticipates that designers are the ones ultimately responsible for listing out the design specifications (by updating their design files).
To put it another way, the direction of transmitting specifications of a design system begins with the designers. The designers list out all the specifications and using some tooling, can deliver them to the consuming applications.
Why does it go in this direction?
Well, this has been how the designer to development process has worked for some time, predating design tokens.
The design file has been the ultimate source of truth as to what “specs” are to be utilized by consuming applications.
The design files have been “high fidelity.” Meaning, the design file is the most faithful, or as close, to the intention of the design system, resulting in the highest verbosity of design specifications across all layers of the design system.
In other words, it is the “purest” expression of your design system, consisting of a detailed list of all the specifications.
Now, this is the common use of the design file, impacting the designer to developer workflow, but is it the best option?
The best way to answer that question is to list out an alternative.
It may surprise you, but there is a potential alternative to a “high fidelity” design file. Design tokens are an exciting concept that is, relatively speaking, new to the web. With fresh concepts comes the possibility of fresh innovations.
Let me take some time to explain a fresh alternative to a high-fidelity design file.
Then in a future article, for the sake of learning and experimenting, I’ll go through building out a working demo of this alternative.
Fair warning, there is going to be a lot of text and no code.
High Fidelity
Design File Style Dictionary
The verbiage of “designer to developer handoff” communicates that, at the end of the day, it is the usage of the design by the developers that is the end goal.
Well, that shows my bias as a developer, so let me rephrase in a way that satiates the desires of designers, developers, and product owners.
The verbiage of “designer to developer handoff” communicates that, at the end of the day, it is the usage of the design by the developers to provide a viable experience and solution for our users that is the end goal.
In a word, designers, developers, and product owners are all working together to improve a user’s situation.
There are multiple ways for designers and developers to work together to reach this end goal.
One way, as I’ve mentioned, is to start with a high-fidelity design file and come up with some process that ensures that the serves as the source of truth as to which specifications should be applied to an application.
This means that various applications and/or UI libraries (really any other shared asset) try to have the highest fidelity to the high fidelity design file.
Practically speaking, how do developers ensure high fidelity to the design file?
Usually, it is by referencing design documentation that displays the specifications in the design file. Or, by using shared libraries/assets where it is trusted that the contributors did the same.
In this approach, the copying of specifications is prone to error.
Alternatively, design tokens expose a serious advantage as they are the specifications of a design system represented as code that can be transmitted to any application on any platform.
All of this to say, the best way to maintain high fidelity is to have your specifications represented as sharable code.
In the final analysis, it is the design tokens as code that are the “high fidelity” expression of your design system. They are not only a “pure” specification of the design system, but they are immutable (in the sense that they cannot be mutated by human error but only bad code).
If there is a way to automatically expose the design tokens from a design file as code, then you can ensure that design specifications won’t be lost in translation. You’ll have the immutable design tokens. You’ll have a “source of truth” of the specifications of the design system.
This begs a question that finally gets us to the alternative to a high-fidelity design file that I alluded to earlier.
If the high fidelity can be found in the design tokens represented as code, then can they be the starting point of designer and developer communication and automation?
Instead of syncing a style dictionary, a central place for managing the raw tokens and exporting the transformed tokens, with a design file, can we sync a design file with a style dictionary?
Can the style dictionary maintain the high fidelity design specifications and export both design files and the transformed tokens (assets/platform deliverables)?
That’s the alternative. Now, let’s weigh the trade-offs.
Design Tokens and Design Files, Which Comes First?
I’d imagine that the initial concern over my suggested alternative is about ownership.
If the style dictionary owns the high fidelity design specifications, then don’t the developers own the maintenance of high fidelity instead of the designers? Is that not blurring the distinctions between roles?
This is a fair point, and I have no agenda to advance one workflow over another. Rather, I’d just like to stimulate conversations that could lead to innovation.
For the sake of innovation, I’ll tease out a response to this valid concern.
If the high fidelity specifications of a design system are moved to a style dictionary, living in a repository, then those specifications are represented as JSON objects.
In theory, both designers and developers could learn how to represent design tokens as JSON files and make changes as they see fit. Designers and developers would work together in both proposing changes to the style dictionary and reviewing/approving them.
Conceptually, the style dictionary becomes the gateway to making official changes to the design system’s specifications. Designers and developers both communicate together to agree upon what those specifications should be.
This may be thought of as the equivalent of UI developers working with API developers to do “contract-based development.” With contract-based development, either the UI developers or API developers come up with a contract for new or updated API routes.
These “contracts” may include example responses/requests, a schema (like JSON Schema for REST APIs or GraphQL schemas), and documentation specifying the API endpoint’s name, payload, response, schema, etc.
An example tool that is used for creating this documentation is Apiary.
The contracts serve as a gateway to official changes to an API. It is the high-fidelity specifications of API designs. By having both API and UI developers contribute, review, and approve these contracts, healthy communication is fostered and clarification is ensured as to what is to be developed.
Similarly, making a style dictionary the gateway for high fidelity design specifications promotes healthy communication between design and developers. It is a central place to ensure high fidelity. It serves as a design “contract.”
From this contract, “development” (which I use in the broad sense to include design work) then flows in both directions.
One direction is creating design documentation for more complex components and experiences that compose the design tokens. This is the work of the designers.
The other direction is for UI developers to implement the design system into UI component libraries and applications.
Now, this comparison between contract-based development and using a style dictionary as a gateway is not entirely equivalent. It seems concerning that the design is being managed by JSON files without being able to have any visual.
This may be partially addressed by creating a workflow where the style dictionary exports documentation and design files on every proposed change (updates to the JSON file).
Then, both designers and developers could all have a way to see the proposed changes. Theoretically, developers would not need to open up the design files if they could see the proposed changes through some kind of documentation. Designers could have the generated design files to serve as a baseline for creating more complex designs that compose the design tokens.
Every proposed change would effectively be a new pull request on the style dictionary repository.
If the style dictionary can create documentation and design files on every branch/PR, then there is a powerful way to share proposed changes across a team.
To summarize so far, a proposed advantage for the approach where a high fidelity style dictionary replaces a high fidelity design file(s) is that it provides a central place for both designers and developers to communicate and maintain ownership of a design system.
This begs the question. May that advantage be achieved in the standardized approach where the design file is created first and maintains high fidelity towards the design system?
I think the answer is yes. Practically, designers are rarely going, to begin with updating a JSON file.
I would imagine that even if the true gateway for maintaining high fidelity specifications were the style dictionary, designers would begin with updating a local design file.
The designers could continue to work with a local design file. From that design file, some tooling could be built to generate a new branch/PR with proposed changes (updates to the design tokens that are represented as JSON files).
The style dictionary may still be the official “gateway” forming a “contract” between designers and developers.
Moreover, the tooling to create design files and documentation on every proposed change could still be an advantage that is sown.
In a word, making a style dictionary a central gateway with the ability to auto-generate design files and documentation representing the true “high fidelity” of a design system is a benefit that can be used in either approach. It may be used whether the JSON files in the style dictionary are updated first or whether a design file is updated and from that design file, the JSON file is updated (either automatically or manually).
What comes first the chicken or the egg? That’s not as important as making a style dictionary the central gateway updating a design system and sowing the advantages of leveraging a style dictionary to generate design files and documentation.
Not “What Comes First,” But “Who Does What”
The fresh “alternative” that I’ve suggested at the onset of this article is that the workflow for creating high fidelity design specifications is not maintaining a high fidelity design file but a high fidelity style dictionary.
So far, I’ve elaborated that the style dictionary should be thought of as the source of “high fidelity,” the “source of truth” as to what the design specifications of a design system are.
Shifting the “official” high fidelity from the design file to the style dictionary fosters “contract-based development” between the designers and developers (similar to the contract-based development that goes on between UI and API developers).
It also allows for unique tooling to share design files and documentation automatically, not only for the “official” styles but also for the proposed changes.
The “direction” of the design to developer handoff is not from a design file to design specifications. Rather, it is design specifications to design files, documentation, and code.
It’s not so much a “design to developer handoff” as it is a “design to developer communication and contract.”
As I’ve mentioned, the mental model of “direction” is a bit nuanced since designers will still likely update a local design file, and from that design file, propose changes by updating JSON files in the style dictionary.
Another nuance to articulate about the alternative that I’ve teased in this article is found in clarifying an additional change in the “who does what.”
A finer point may be put on the implication of a shift from a high fidelity design file to a high fidelity style dictionary.
Both designers and developers would be involved in the maintenance of a high fidelity style dictionary, however, do designers need to have as much involvement as they traditionally have?
When it comes to specifying a color palette, designers would be working with a local design file before proposing changes to the style dictionary.
But, what about the specificity around typography, spacing, sizing, or even colors that have to be specified for a variety of UI elements?
Do designers have to maintain a local design file with visual examples of
typography.body.font-family,
typography.paragraph.font-family,
typography.body.font-size, etc.?
Would the designer be ok with coming up with the “base” styles and having high fidelity specifications for all the iterations of UI elements reflected in a JSON file?
If this were the case then the designers could get the high fidelity design files (assuming the style dictionary is leveraged to automatically generate them) without having to manually manage them?
Perhaps the question could be framed more positively. Is it worthwhile to save the number of work designers need to spend on maintaining high fidelity design files?
The idea is not to step on the toes of designers with automation that developers create and maintain. The idea is to use that automation to free up the time of designers to work on the designs for UI components which may be a composition of design tokens.
I asked a question, and I’ll answer it first.
I’m not sure.
Conclusion
I do not know if my suggestion to use automation in the style dictionary to create the high fidelity design files and documentation is preferable for designers.
I am a developer first. I do not think like a designer first. I am not as gifted and talented as my designer peers. I am used to writing code for UI component libraries and applications, not maintaining high fidelity design files.
Therefore, I want to clarify again that I would like to promote conversation which I hope leads to innovation.
The realm of design tokens is fairly young, and it has a lot of potentials.
I hope this article is a contribution to furthering the power of design tokens and making the web all the better along the way.
In a future article, I would like to tease out this idea of exporting design files from a style dictionary.
Until then, please pow, discuss, and share. All feedback is welcome :)
