1850611 - Create a JSON file source of truth for our design tokens

Status: RESOLVED FIXED

(Toolkit :: Themes, task)

Description

[Jules Simplicio [:jules]]

We are moving our design tokens source of truth to a JSON file as this is an agnostic 'styling' file format (i.e. not in CSS, SCSS, or Swift specifically).

This is needed so that we can have one file that remains the source of truth and can generate our design tokens for multiple styling languages via a build system such as Style Dictionary.

We're working on generating Scss tokens for the OMC team so this is a required step.

Comment 1

[Jules Simplicio [:jules]]

Attachment: Bug 1850611 - Create a JSON file source of truth for our design tokens r=#recomp-reviewers,#desktop-theme-reviewers

Depends on D189004

Comment 2

[Hanna Jones [:hjones]]

Attachment: Bug 1850611 - Add simple tests for JSON tokens r=#recomp-reviewers

Comment 3

[Tim Giles [:tgiles]]

Attachment: Bug 1850611 - Create a JSON file source of truth for our design tokens. r=#recomp-reviewers

---

Co-authored-by: Jules Simplicio <[e-mail]>

Depends on D202767

Comment 4

[Tim Giles [:tgiles]]

Attachment: Bug 1850611 - Add light-dark transformer for generating web CSS r=#recomp-reviewers

FIDEFE-4623
I originally thought we would be able to use a transformer to handle
this case, but outputting references causes my transformer to fail.
Because of this, I switched to using a custom CSS formatter and adding
the variable references in this formatter.

Additionally, I also switched over to using config.js instead of
config.json using PR FirefoxUX#3 as a starting point.

I also changed the design tokens JSON format to fit what I needed for
the light-dark formatting. I'll need to consolidate my changes with the
changes in PR FirefoxUX#3, but wanted to get this PR updated.

• Remove build.js, use css/variables formatter, update tokens structure

This removes the build.js file in favor of using config.js (which
requires style-dictionary build to build our files). I also removed
the custom file formatting code in favor of the included css/variables
formatter. Lastly, I updated the tokens structure so instead of
"darkValue", we use "dark".

Most likely the structure of the tokens file will change again, but
I'll create a new PR with those proposed changes.

• Restore custom file formatting, simplify ref logic.

So we can't use the "css/variables" built-in formatter, otherwise we'll
lose our light-dark value. I reverted those changes back to the
mappedValues loop so that we maintain the light-dark formatting.

I additionally sorted the token so that referenced tokens come after
the referenced definitions. I don't think we have to do this for CSS,
but it does make the generated CSS a little easier to follow in my
opinion.

• Remove light-dark formatter and replace with transformer.

We can greatly simplify the config.js file by doing two things:

1. Use a transformer for dealing with light-dark.
2. In this transformer, modify the original value of the token.

By modifying the value of the original token, we are able to take
advantage of the built-in css/variables formatting and so we don't need
custom CSS file formatting.

Additionally, we can use ...StyleDictionary.transformGroup["group_name"]
to get the individual transforms of a group. By doing this we can extend
an existing group as seen in this patch.

• fix eslint error

Depends on D204108

Comment 5

[Tim Giles [:tgiles]]

Attachment: Bug 1850611 - Use value object in design-tokens.json. r=#recomp-reviewers

• FIDEFE-4643

By using the composite design token value structure, we gain flexibility
in handling themed and non-themed tokens as well as other cases that
we are not aware of. For example, this composite value structure can be
used to handle prefers-contrast theming, forced-colors (HCM) theming,
etc.

We also add the ability to use "default" as the default value of tokens.
This handles the case where a token has the same value in light and dark
mode but has a different value in perfers-contrast or forced-colors
mode. Currently "default" is the highest priority property of the value
object. If you have "light", "dark" and "default" for a token's
value, then the "default" property will be in the generated token and
not the "light" or "dark" property values.

• fix broken matcher function in lightDarkTransform

Depends on D204109

Comment 6

[Tim Giles [:tgiles]]

Attachment: Bug 1850611 - Add HCM media queries to built CSS r=#recomp-reviewers

• FIDEFE-4626

• remove some of the 'default' references from JSON, fix test fixtures

• address review comments

Depends on D204110

Comment 7

[Tim Giles [:tgiles]]

Attachment: Bug 1850611 - Add MPL license and how to edit file header. r=#recomp-reviewers

• FIDEFE-4640

• Add custom file header function that deals with the MPL and how to edit

Depends on D204111

Comment 8

[Tim Giles [:tgiles]]

Attachment: Bug 1850611 - Strip '-default' from token names and values r=#recomp-reviewers

• strip '-default' from token names and values

• use @base in JSON, only replace -base at word boundary

• fix tests

Depends on D204112

Comment 9

[Tim Giles [:tgiles]]

Attachment: Bug 1850611 - Refactor generated media query placement within file. r=#recomp-reviewers

FIDEFE-4687

According to a11y's recommendation,
https://firefox-source-docs.mozilla.org/accessible/HCMMediaQueries.html#writing-maintainable-frontend-code,
we should move the generated media queries within the :root block.

Depends on D204113

Comment 10

[Tim Giles [:tgiles]]

Attachment: Bug 1850611 - generate multiple CSS files from a single JSON file. r=#recomp-reviewers

• FIDEFE-4635

• rebase, address review comments

• rebuild CSS + fix tests after rebase

• cleanup matcher and transformer logic

• cleanup

Depends on D204114

Comment 11

[Tim Giles [:tgiles]]

Attachment: Bug 1850611 - add the :host(.anonymous-content-host) selector to the built CSS r=#recomp-reviewers

• simplify string, add comma

• rebase + fix tests

Depends on D204115

Comment 12

[Tim Giles [:tgiles]]

Attachment: Bug 1850611 - Output tokens in pre-defined order r=#recomp-reviewers

FIDEFE-4631

Sort tokens when exporting in CSS and add section headers to match
existing tokens-*.css files in mozilla-central

Depends on D204116

Comment 13

[Tim Giles [:tgiles]]

Attachment: Bug 1850611 - Generate CSS layer declarations and relevant selectors. r=#recomp-reviewers

RECOMP-226

This brings our Style Dictionary CSS generator in line with our current
CSS tokens files.

I had to rewrite the createDesktopFormat and formatTokens to get the
formatting of the CSS string correct.

Depends on D204117

Comment 14

[Tim Giles [:tgiles]]

Attachment: Bug 1850611 - Sort tokens by t-shirt size and state semantically not alphabetically r=#recomp-reviewers

Depends on D204118

Comment 15

[Tim Giles [:tgiles]]

Attachment: Bug 1850611 - Add remaining tokens to design-tokens.json r=#recomp-reviewers

Depends on D204119

Comment 16

[Tim Giles [:tgiles]]

Attachment: Bug 1850611 - Add design tokens JSON docs r=#recomp-reviewers

Depends on D204120

Comment 17

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/integration/autoland/rev/865f28810747
Create a JSON file source of truth for our design tokens. r=reusable-components-reviewers,desktop-theme-reviewers,hjones,dao
https://hg.mozilla.org/integration/autoland/rev/883e713c3013
Add simple tests for JSON tokens r=reusable-components-reviewers,desktop-theme-reviewers,mstriemer,dao

Comment 18

[Sandor Molnar[:smolnar]]

https://hg.mozilla.org/mozilla-central/rev/865f28810747
https://hg.mozilla.org/mozilla-central/rev/883e713c3013