feat(design): BREAKING CHANGE: Complete rebuild of the design token package

[scotttjob]

292 changed files??

I know I know! But but but:

The majority of those changes are:

1. The icons moved from one directory to another (everything is under /src now, much tidier). Git tracks that move as 2 "files changed" for each icon, one to 'delete' the old one and another to 'create' a new one. Since they're svg files, they count as lines of code as well.
2. There are snapshots that had to be updated because we've moved from class based styling in icons to style based styling (for ease of use).

If you collapse the icon + snapshot changes, you get a much smaller group of files to review (which are the actual changes). Pulling this branch down and trying it first-hand will also give a good idea of how it works in practice. Make sure to run npm run clean before swapping into this branch.

Motivations

• Our design token system has served us well over the years, but it's starting to show it's age.
• The industry has moved towards a standard, to the point where the w3c is involved
• We want to meet that standard as closely as we can.
• We want to modernize how we build, and start to offer new funcitonality

You changed the tokens?

Sure did!

We currently store our tokens as CSS files. This works very well on the web.

The problems crop up when you need those styles inside react-native (or somewhere else, like say, Figma). Now you have to go through a complicated process of running your css through postcss to generate values, then parse those CSS files into javascript objects.

Unfortunately, that process is the reverse of where the industry ended up.

The W3C even got in on trying to define how you define tokens.

This PR follows their spec. The spec is very, very close to the StyleDictionary format. The primary difference is the W3C format uses the dollar sign '$' character to denote control variables ($type, $description, $value) while the Style Dictionary format does not.

{
  "color": {
    "$type": "color",
    "$description": "The base color tokens. These are the lowest level tokens and are only meant to be consumed by other tokens. Do not use these tokens directly under any circumstances.",
    "base": {
      "grey-": {
        "100": {
          "$value": "hsl(0, 0%, 97%)"
        },
   }
}

Above is an example of just about all the new token system features.

1. You can nest tokens in a JSON structure, and that structure will show up in the token names.
2. You can give tokens a 'type.' This type will eventually be passed to a transformer function, where we have some custom code to transform based on where the token will end up (js, css). A type can be set for a group set of tokens which will automatically apply to all children, or just an individual token.
3. You can give tokens a description. You can give this description at the group or individual token level.
4. Tokens must have a value. We have some light error checking in place if you forget to include a $value for any particular object tree.
5. Our token naming structure has the occasional double dash (color-base-grey--100), which you will spot in the above structure with 'grey-' in a token name. The '-' at the end of the name was our workaround for supporting double dashes in variable names. In the W3C spec, tokens only have a single dash between groups and values (color-base-grey-100) but we wanted to be backwards compatible with our existing tokens. We originally experimented with an underscore character as a group name to indicate a double dash, but it technically broke the W3C spec and made our token files have an extra nesting level. {color:{base:{grey:{_:{100:{$value:'...'}}}}}}

Additional functionality:

1. Token Aliases. Tokens can reference one another so you can build up base tokens, then layers of tokens on top of that (up to say, semantic tokens). These token aliases follow the w3c spec. Say you have a token in the structure {"color": {"green":{"$value":"#00EE11"}} You can reference that in another token with {"color":{"interactive":"{color.green}"}}. There are processing functions under packages/design/src/scripts/tokenServices that can process the tokens into a JS object, and then turn the aliases into either actual values, or css custom properties.

Adding a new set of tokens to the complete package can be achieved by:

1. Adding a new token file under src/tokens that follows the same format as above and in the other files (platformOverrides is a special file and should not be copied).
2. Importing your new token file in allTokens.ts and adding it to the tokenMap in this file. At this point, your token contents should start showing up in all the built output via npm run build in the design package (or just npm install from the root)

Why are there Storybook changes in here too?

To show off a compelling reason why we should try to land this PR. We've implemented dark mode in storybook in just a few lines of code, by pulling in the dark mode tokens created by the design package now. In theory this could be extended to new themes in just a few more lines of code.

Changes

• Completely rebuilt how we store and generate our design tokens
• Dark Mode is now supported within Storybook
• Tokens are now stored in the w3c format
• Now that the tokens are stored in json format, we had to write new code to support them
• We've written a very simple token parser that can generate CSS tokens (--var()), JS tokens {token:val}, css files :root{}, js files in both CJS and EJS formats, and theme files.
• The Icons are now using Style tags instead of CSS because of how much easier it is to manage across react and react-native. This is the 'big' change that we could still scale back. We've deleted a LOT of code from the react-native Icon though, so I would love to explore options if we decide this is too big of a change.

Added

• Dark Mode Toggle Within Storybook
• Completely Rebuilt Design Token System

Changed

• refactor(design): BREAKING CHANGE: Change bundle outputs
• refactor(design): BREAKING CHANGE: New exports for androidTokens, iosTokens, webTokens, darkTokens, iconMap, iconSizes, iconColors, colors, semantic
• refactor(design): BREAKING CHANGE: Split iconStyles into webIconStyles, mobileIconStyles
• refactor(design): BREAKING CHANGE: Move foundation.css to dist/foundation.css
• feat(design): BREAKING CHANGE: Change getIcon to require platform (web|mobile) arg
• feat(design): Add format (css|js) arg to getIcon
• feat(design): Add dist/dark.mode.css, dist/dark.theme.css

Deprecated

• The Old Way of generating design tokens (CSS first)

Removed

• IconClassNames. This is probably going to be a controversial change, but one I'd like to discuss!

Fixed

• Lack of a dark mode toggle
• Lack of a dark mode style sheet being served from Atlantis
• Lack of a theming system within Atlantis.

Security

Testing

Changes can be tested via Pre-release

---

In Atlantis we use Github's built in pull request reviews.

[cloudflare-workers-and-pages[bot]]

Deploying atlantis with    Cloudflare Pages

Latest commit:	0a9c507
Status:	✅  Deploy successful!
Preview URL:	https://e5a1fcd7.atlantis.pages.dev
Branch Preview URL:	https://scott-th-design-package-redo.atlantis.pages.dev

View logs

[github-actions[bot]]

Published Pre-release for 39d019bbdc2947eb146d3491289304bb62663371 with versions:

  - @jobber/components@5.20.8-SCOTTTHd-39d019b.38+39d019bb
  - @jobber/design@0.62.3-SCOTTTHd-39d019b.41+39d019bb

To install the new version(s) for Web run:

npm install @jobber/components@5.20.8-SCOTTTHd-39d019b.38+39d019bb @jobber/design@0.62.3-SCOTTTHd-39d019b.41+39d019bb

To install the new version(s) for Mobile run:

npm install @jobber/design@0.62.3-SCOTTTHd-39d019b.41+39d019bb