The following is a bullet point summary of my conclusions for my book Design Systems for Developers (my attempt at teaching how to build a design tokens pipeline to distribute a design system across multiple teams, platforms, and technologies).

1) Design specifications have to be represented in code

2) There are two common pitfalls:

• The design specifications are represented in multiple places
• They are immediately represented in a tech-specific format

3) As a result...

• You can't easily tell how the design specs are coded across all consumers of the design system
• You don't get free updates
• Applications become out of sync with each other
• You have trouble scaling
• You deliver tech-agnostic, awkward assets

4) Instead, you need to represent your design tokens in a central location.

5) You also should store them in a "raw"/tech-agnostic manner before formatting them.

6) The best way to store "raw" design specifications (aka design tokens) is as key-value pairs in a JSON object.

{
  "color-primary": "red",
}

7) A good term for the central location to store design tokens is called a "style dictionary."

8) In addition to storing design tokens, a style dictionary also can format the "raw" tokens into a tech-specific format (i.e. SCSS variables).

$ColorPrimary: red;

9) All adopters of the design system reference one of the formatted design tokens exported by the style dictionary.

10) To get free updates and keep all adopting applications in sync with one another, the formatted design tokens should be "published" to each consumer.

11) Every time an adopting application needs a new format, a change is made to the style dictionary to support exporting that new format.

$ColorPrimary: red;

export const colorPrimary = "red";

12) The formatted design tokens can be "published" by either A) a CLI tool, B) an API, C) an NPM package, or D) via a CI/CD pipeline.

13) I've seen an NPM package or CI/CD pipeline be the most successful of the "publishing" options.

14) You can use a tool like Style Dictionary to help transform raw design tokens into formatted design tokens.

15) With these changes, you can now:

• Get free updates
• Only translate the design specs to code in one place
• Definitively see how the design specs are coded
• Increase adoption
• Ensure design spec accuracy while allowing tech-specific formats

16) The tricky part is translating design specs from design files into JSON

17) You can automate this with tools like
@specifyapp

18) Or, you can have the designers and devs work closely to hash it out, almost like a contract

If you're interested in diving more into what I outline here, consider checking out my book 👇