Design System & Tokens

Description

Assemble Web and its components uses a Styling model based on a Design System that uses Design Tokens as a way to define the individual styles of the component in detail.

You can review the Web Component Design System definition Figma file and check the specific default Reels Design System styles, definition and token details created by the PD&A team.

Token usage

Extraction and Transformation

Assemble Web includes two separate npm scripts:

pnpm run token:fetch
pnpm run token:transform

note

Please run bash cleanup.sh before each execution of token:fetch to ensure no previous undesired token files are used

In order to be able to execute the fetch script you need to set PERSONAL_ACCESS_TOKEN and FILE_KEY as Environment variables.

• PERSONAL_ACCESS_TOKEN is the Figma Personal Access token that you can create (the token must have at least the Read-only Variables scope selected)

• FILE_KEY is a comma separated list of files keys. The file key can be obtained from any Figma file URL: https://www.figma.com/file/{file_key}/{title}.

The recommended way to define the environment variables is with the export of such tokens to avoid node compatibility situations with .env files.

export FILE_KEY={PRIMITIVE_FILE_KEY},{BRANCH_FILE_KEY}

Where

• PRIMITIVE_FILE_KEY is VlA6PPZ4nowmchevArz8jp by default
• BRANCH_FILE_KEY is kcaiPKFPoGMOp8mV3AUIbD by default (File ID for Web Component Library), but may vary if you need to fetch it from a branch.

And a set of utilities based on Figma variable Rest API and Style-Dictionary transformation processes that will result in a set of CSS variables.

note

The result of the token:fetch script will be generated by default in the tokens/output folder

note

The result of the token:transform script will be generated by default in the src/theme/tokens/css folder

Extraction and Transformation using Github Actions

Assemble Web includes a workflow (figma_to_styles.yml) that will do the fetch and transformation and create a PR into the main repo based every time is executed.
This is the Recommended way of working with token updates to ensure that everything is aligned.

You will need the following:

• FIGMA_TOKEN secret set in the repo
• execute it with a file_key value based on the files (comma separated) that your project uses (VlA6PPZ4nowmchevArz8jp,kcaiPKFPoGMOp8mV3AUIbD on Assemble Web).

Component usage

Once the tokens from the Design System are integrated into the application from the fetch & transform process, a component can use the CSS variables inside the CSS rules defined for the component as:

.button {
  font-family: var(--desktop-label-medium-font-family);
  font-size: var(--desktop-label-medium-font-size);
  font-weight: var(--desktop-label-medium-font-weight);
  letter-spacing: var(--desktop-label-medium-letter-spacing);
  line-height: var(--desktop-label-medium-line-height);
}

It is important to ensure that we are using the proper upper level, component, breakpoint size, etc specific token as the CSS variables are defined in a hierarchy mode but we need to use the specific ones so changes in some core styles only applies where needed.