DS: investigate syncing tokens to storybook

[damonmcc]

background

Design Token Automation

• involves github sync with figma which requires a github personal access token

• need to look into more to see how to implement the pipeline

@jessicashanshanhuang happy to help with that!

if other significant parts of Storybook + Figma compatibility are working though, might be nice to document/finalize those and break out token automation into it's own issue?

but if tokens are already an integral part of the DS in figma, could totally see why token automation should be an expectation of Storybook + Figma compatibility!

Originally posted by @damonmcc in #28

This DS work is inspired by this article.

High-level workflow:

1. Using design tokens (Figma)
2. Linking those tokens to a single source of truth (Github repo) for syncing
3. Automatically transforming design tokens (.json) using token-transformer and style-dictionary to generate css variables
4. Pushing updated css variables into component code and triggering a build
5. Publishing a Storybook page with updated components and design decisions

Design + Dev flow [draft]

details

Important

Style Dictionary recently released version 4 and it's worth using this latest version. The documantation for v4 is here.

There's a package @tokens-studio/sd-transforms with custom transforms for Style-Dictionary, to work with Design Tokens that are exported from Tokens Studio (docs).

Based on the current token files in the Streetscape repo, the most appropriate built-in Style Dictionary formats seem to be:

• typescript/module-declarations
• javascript/object
• javascript/module

Filtering can be used to generate multiple files with different sets of tokens.

[damonmcc]

made a token, saved it in OnePassword. next will try adding github as a sync provider in the figma plugin (docs)

[damonmcc]

tried syncing from the Getting Started file and got:

You try to save a multi-file project as a free user. Upgrade to Pro or add a json file at the end of the filepath (tokens.json)

[damonmcc]

in PR #39, I think all tokens were synced despite my using the plugin with the Getting Started file open (a good thing)

on to the step of Using Token Transformer

[damonmcc]

since converting Figma exports to typescript files requires node packages, I created a branch in the streetscape repo called figma-token-build

the approach in the article above uses two repos, but it seems like we can just export from figma to the streetscape repo and to reduce complexity

so far the changes in that branch are:

• add packages
• add token build scripts

the build scripts convert json exported from figma into formatted javascript/typescript/css/json. there are many built-in formats and it's pretty easy to define a custom format

I think we'd need to configure a custom format if we want to mimic the current format of current tokens in streetscape

[damonmcc]

per chat with Tyler:

• linking to Figma components in Storybook via the Storybook add-on is great, would love to see a PR for that soon
• syncing tokens is harder because of the "last mile" of converting a json file exported from Figma to typescript files passed to ChakraTheme

next steps:

• configure my Figma plugin to export to the Design repo
• open a PR with example Figma export (or export from same Chakra Kit used in relevant Streetscape PR)
• add relevant instructions to the Design repo readme
• save (somehow) notes & code for someday converting exported tokens to be useful in the Streetscape repo

[jessicashanshanhuang]

per chat with Damon about figma libraries and their relationship with design token plugin <> json, looking into figma's dev mode might be worth researching more about as design token automation syncing is currently blocked by obstacle of converting json to typescript

• dev mode workflow case study
• dev mode: Guide to Developer Handoff: A collection of best practices from the experts

[jessicashanshanhuang]

Figma Dev Mode

• looks like its available with any paid plan and since we have the professional plan

  

• would be a good practice to have ae default to dev mode, especially since we can annotate and leave notes for smoother handoff in dev mode

  

• intro to dev mode video

Code Connect

• code connect looks promising, this could solidify Figma as the home base for both developers and designers

Use Code Connect to link your components in code with your design system in Figma, so code snippets are always production-ready.
Gilson: Code Connect is the feature that we’ve been most excited about. Setting it up was super easy– it only took one engineer two weeks.

• code connect repo

Note

Code connect is only available for Organization or Enterprise figma plans. Might be worth upgrading since it has compatibility with React and Storybook.

• looks like code connects does the conversion for you to storybook (based off looking at the repo)

• there is also a github + figma dev mode compatibility, will need to explore more as the specs page doesn't really demonstrate its capabilities

[jessicashanshanhuang]

Update: all findings and next have been summarized in streetscape overview