Getting started
Resonance connects a shared visual design kit with a front-end framework, allowing designers and engineers to build and adapt reusable patterns in order to create a cohesive experience across all of our applications.
Install v0.25.3
Load from CDN
Step 1: Include the script to your page:
<script src="https://resonance.vox-cdn.com/0.25.3/resonance.min.js"></script>Step 2: Call res.init(). This can be done from an external script, or inline on the body tag (e.g. <body onload="res.init()">).
Note: If you're seeing some FOUT, add the fout.css stylesheet to the head of your document.
Load as a module
Step 1: Add the Resonance repo to your package.json:
"resonance": "git+ssh://git@github.com/voxmedia/resonance#v0.25.3"Step 2: Import the library into your code - const res = require('resonance') - and call res.init() when you'd like the components to render.
Manually loading CSS
Resonance automatically loads component styles on initialization, but if you'd rather load them manually you can do so with res.init({ loadCSSManually: true }).
Config options for res.init()
publicPath- Defaults to current version (https://resonance.vox-cdn.com/0.25.3).loadCSSManually- Defaults to false. When set to true CSS will have to be loaded manually.shimStyles- Defaults to false. When set to true styles will be automatically shimmed usingdist/resonance-shimmed.min.css.devMode- Defaults to false. Used for dev environment testing.
Sketch UI Kit
The Resonance Sketch UI Kit consists of all of the elements that a designer needs to mock up an interface using Resonance. The UI Kit includes the Resonance Sketch file, Sketch libraries, and a stickersheet. All Resonance design resources live here.
Do not add, remove, or modify any resources in this folder.
If you have any questions please feel free to reach out to the Resonance design team for assistance.
How it works
Sketch libraries are a collection of symbols that are linked together. This linking of symbols helps designers iterate rapidly and more reliably than copying and pasting existing elements. Libraries offers scale and the ability to iterate for the core Resonance design team while maintaining consistency across people using the UI kit by pushing updates to the libraries without breaking designs. The Resonance system consists of three main libraries that inform and cascade styles amongst the different files. These files are broken down as follows.
Basics
Basics are the smallest style units in the Resonance Sketch system. This is where the colors, typography, icons, and other basic units live. These styles cascade out to the components in other libraries. This ensures that it there is one, central place to make updates across the entire system of components. This file should not be updated outside of the core Resonance team.
Components
Components are the base Resonance components that can cascade out to inform larger patterns in the stickersheet. The components are built using the “basic” styles. These are not comprehensive of every component but rather the basic building interface building blocks that help inform larger patterns in the stickersheet. This file should not be updated outside of the core Resonance team.
Stickersheet
The stickersheet is a comprehensive file of every component in Resonance that is styled using the “basics” and “components." The stickersheet is a place where a designer can go to copy components for quick prototyping. The stickersheet is made up of symbols but the components in the stickersheet itself may not itself be a symbol. This file should not be updated outside of the core Resonance team, but we encourage designers to copy components from this file and paste them into their files.
Installing plugins
Some plugins are required to add to Sketch before you start working with the Resonance UI Kit. We also have some recommendations that will make this workflow easier.
Required
Paddy: Resonance containers and buttons are built using this plugin. It’s a great way to create container spacing.
Shared Text Syles: A plugin to import/export ready made text styles. It’s how we sync the available text styles across working documents.
Sketch Palettes: A plugin to import/export color palettes so the Resonance colors are available to you in every working document.
Recommended
Sketch Runner: A plugin that makes it easy to insert symbols which speeds up design workflow. This is the recommended workflow for the Resonance UI Kit.
Rename It: A plugin to batch rename layers and symbols.
Stark: A plugin for contrast testing and various colorblind tests to ensure that things are a11y compliant.
Installing libraries
Download the Sketch UI Kit. Open Sketch, go to “Preferences,“ select “Libraries” and click the “Add Library” button at the bottom of the modal. From there, select the “Resonance Style Basics” library and click “Open”. This will add the Style Basics library to your Sketch. Repeat this process to add “Resonance Components” and “Resonance Stickers”.
Next, import the text styles using the “Shared Text Styles” plugin to import the all-text-styles.json file from the text style folder within the resources folder. Importing may take up to several minutes to complete.
Finally, use the “Sketch Palettes” plugin to import the file resonance-colors.sketchpalette from the “Resources” folder.
Using libraries
Using libraries can be a new workflow to learn, but once you understand the system it makes using Resonance much more efficient. There are several ways to use the symbols in the libraries.
1. Insert dropdown
Clicking the insert button at the top left of the toolbar will reveal a menu where you can insert symbols from. This is the default way to use a library in Sketch without any additional steps, though we recommend trying the other methods for ease of use.
2. Symbols button
You can customize your toolbar and add a symbols button directly to your toolbar. Add the symbol button by clicking “View” then selecting “Customize toolbar.” From there, drag and drop the “Symbols” icon to your toolbar.
3. Sketch Runner
Install Sketch Runner from the plugins folder. Once in Sketch, you can either hit cmd + ‘ to open Sketch Runner, or open it via the plugins menu. From there, select insert and then search for the symbol (e.g. “button”). This is the recommended way to use symbols in Resonance since it is a quick way to search for a component name. You can also customize your Sketch Runner preferences to default to “insert” being the first tab you see with this plugin, so typing cmd+’ will automatically bring you to the insert menu.
Using symbols
Symbols are the primary way to design with the Resonance UI Kit. Symbols are great for keeping our components consistent and scaling our updates across the entire system. Using symbols is easy, as long as you keep the symbols linked. You can style the symbols for your needs by utilizing the overrides panel. All of the symbols in the UI Kit have flexible enough overrides to accommodate any design tweaks needed so do not detach any of the symbols when designing with them. If you encounter a situation where you need to do something that an override cannot achieve, contact the core Resonance team. Detaching symbols creates design debt for both yourself and the Resonance team.
Using stickers
The best way to use the stickersheet is to copy and paste the component from this file into the new design document. Each component is labeled with the symbols that were used to create it. While these components may not themselves be a symbol, they are made up of symbols. Double clicking into a particular component will reveal the overrides and allow each part to be customized. These should only be overridden and customized in the new design document and not in the stickersheet itself.
For a walkthrough on overriding styles, visit the Resonance Wiki.