@manifoldco/mercury

☤ Mercury

Design tokens auto-generated from our Figma files.

💽 Usage

With Node installed, run the following in the project folder of your choice:

npm install @manifoldco/mercury

To view the component library:

📚 Visit Storybook

Contributing

🏎️ Setup

npm install
npm run dev

🗿 How do I add new components?

Components live in the ./src/components/ folder, in *.scss files. To add a new widget component:

1. Create a new Sass @mixin at src/components/_widget.scss using our CSS styleguide. Refer to the other *.scss files in that folder for reference.
2. Create a Storybook Story by making a new stories/widget.stories.js for the markup, and stories/widget.scss if needed. Refer to the other stories for reference.
3. Document the component as well as you can!

Some good things to keep in mind:

• The *.scss file you ship in src/components will be shipped with Mercury. Make sure it’s polished!
• ⚠️ Any Sass or CSS you add in stories/* will NOT ship with Mercury. Make sure that you didn’t accidentally leave essential styles in there!
• ⚠️ Only write @mixins in Sass.These allow the consumer to pick the final CSS class names, and they also allow build CSS to tree-shake (important for Manifold Components).

When everything looks good, open a PR and a member of the front-end team can review.

🚠 How do I hook more things up to Figma?

To understand the Figma updates, you’ll need to think in terms of transformers and targets.

We currently have the following transformers in Figma: color, gradient, typography, and shadow. Each of those transformers in the ./figma/transformers directory map to a style namespace in Mercury. Each transformer takes the Figma REST API data (JSON), pulls out what it needs for each, and converts the end result to a JS object.

After each transformer has generated its own object, each target is responsible for taking that collection and converting it to a file output. Currently we have 2 targets: JS and Sass. Each of those map to a file in ./figma/targets. The JS target is the simplest, as it basically writes the object as-is from transformers. The Sass target has to do a little more work, converting JS ({ fontSize: '12px' }) to CSS strings (font-size: 12px;), as well as generating some wrappers (@mixin Typography { … }). But overall, it’s not too much work.

OK, but how do I add something? Your process from here will be somewhat trial-and-error, because every “thing” you want to add will follow a different process (compare the color vs typography transformers to see that they do different things). But your best helpers will be The Figma REST docs to understand the data, as well as browsing an export of the Figma JSON for Manifold to see what structure the API is returning (tip: save your own local copy of the REST data if it’s changed drastically from that Gist).

In short: your goal is to trawl through the meta and files JSON that Figma provides, and pull out what you need into a JS object (transformers) that can be exported to JS and Sass (targets). Reach out to Drew if you need help.

♻️ Updating from Figma

Updating from Figma happens ✨ automatically ✨ with a daily check. If you want to manually update (perhaps you’re testing something), create a Figma token and add a new line to your ~/.zshrc or ~/.bashrc (whichever exists on your machine; most likely the former):

export FIGMA_TOKEN=[token]

Then run:

npm run extract

🚀 Deploying to npm

npm deployment happens ✨ automatically ✨ whenever Figma is updated.

In order to release versions yourself, you’ll have to do so manually. Locally, run:

make package

Update pkg/package.json’s version manually, and run:

cd pkg && npm publish --tag next