1 | <h1 align="center">Polaris design tokens</h1>
|
2 |
|
3 | <img src="https://user-images.githubusercontent.com/85783/39013335-ebf76f5e-43cb-11e8-81f2-706259125897.png" alt="" align="center" />
|
4 |
|
5 | <h3 align="center">Colors, spacing, animation, and typography for all platforms</h3>
|
6 |
|
7 | <p align="center"><em>JavaScript · JSON · CSS · SCSS · Android · Sketch · macOS · iOS · Adobe Swatch</em></p>
|
8 |
|
9 | <div align="center" markdown="1">
|
10 |
|
11 | [![npm version](https://img.shields.io/npm/v/@shopify/polaris-tokens.svg)](https://www.npmjs.com/package/@shopify/polaris-tokens) [![CI](https://github.com/shopify/polaris-tokens/workflows/CI/badge.svg)](https://github.com/shopify/polaris-tokens/actions?query=workflow%3ACI)
|
12 |
|
13 | </div>
|
14 |
|
15 | ---
|
16 |
|
17 | [Design tokens](https://medium.com/eightshapes-llc/tokens-in-design-systems-25dd82d58421) for [Polaris](https://polaris.shopify.com), Shopify’s design system.
|
18 |
|
19 | Design tokens originated at Salesforce, and the best way to describe them is to simply quote their documentation:
|
20 |
|
21 | > Design tokens are the visual design atoms of the design system — specifically, they are named entities that store visual design attributes. We use them in place of hard-coded values (such as hex values for color or pixel values for spacing) in order to maintain a scalable and consistent visual system for UI development – [Salesforce UX](https://www.lightningdesignsystem.com/design-tokens/)
|
22 |
|
23 | ## Installation
|
24 |
|
25 | Polaris design tokens are available as both a npm package (`@shopify/polaris-tokens`) on [npm](https://www.npmjs.com/), and as a Ruby gem (`polaris_tokens`) on [RubyGems](https://rubygems.org/).
|
26 |
|
27 | The recommended way to use and install design tokens may vary depending on your project; the most common are documented below.
|
28 |
|
29 | Using [npm](https://www.npmjs.com/):
|
30 |
|
31 | ```console
|
32 | npm install @shopify/polaris-tokens --save
|
33 | ```
|
34 |
|
35 | Using [yarn](https://yarnpkg.com/en/):
|
36 |
|
37 | ```console
|
38 | yarn add @shopify/polaris-tokens
|
39 | ```
|
40 |
|
41 | Using [Bundler](https://bundler.io/):
|
42 |
|
43 | ```console
|
44 | bundle add polaris_tokens
|
45 | ```
|
46 |
|
47 | ## Usage
|
48 |
|
49 | Find all available tokens in the [design tokens documentation](https://shopify.github.io/polaris-tokens/).
|
50 |
|
51 | ### JavaScript
|
52 |
|
53 | In JavaScript, design token names are formatted in [lower camelCase](http://wiki.c2.com/?CamelCase).
|
54 |
|
55 | ```js
|
56 | const tokens = require('@shopify/polaris-tokens');
|
57 | console.log(tokens.colorBlueLighter); // rgb(235, 245, 250)
|
58 | ```
|
59 |
|
60 | In JSON, design token names are formatted in [kebab-case](http://wiki.c2.com/?KebabCase).
|
61 |
|
62 | ```js
|
63 | const tokens = require('@shopify/polaris-tokens/dist/index.json');
|
64 | console.log(tokens['color-blue-lighter']); // rgb(235, 245, 250)
|
65 | ```
|
66 |
|
67 | Note that, if your project supports ECMAScript Modules, you can also use the `import` syntax.
|
68 |
|
69 | ```js
|
70 | import * as tokens from '@shopify/polaris-tokens';
|
71 | // or
|
72 | import {colorBlueLighter} from '@shopify/polaris-tokens';
|
73 | ```
|
74 |
|
75 | ### Sass
|
76 |
|
77 | Sass variables and map keys are formatted in [kebab-case](http://wiki.c2.com/?KebabCase).
|
78 |
|
79 | ```scss
|
80 | // Using variables
|
81 | @import '~@shopify/polaris-tokens/dist/index';
|
82 |
|
83 | a {
|
84 | color: $color-blue-text;
|
85 | }
|
86 |
|
87 | // Using the map of all tokens
|
88 | @import '~@shopify/polaris-tokens/dist/index.map';
|
89 |
|
90 | a {
|
91 | color: map-get($polaris-index-map, 'color-blue-text');
|
92 | }
|
93 |
|
94 | // Using the map for a specific type of tokens (here: spacing)
|
95 | @import '~@shopify/polaris-tokens/dist/spacing.spacing-map';
|
96 |
|
97 | a {
|
98 | color: map-get($polaris-spacing-map, 'loose');
|
99 | }
|
100 | ```
|
101 |
|
102 | ### Sass, with CSS Custom Properties
|
103 |
|
104 | Custom properties are formatted in [kebab-case](http://wiki.c2.com/?KebabCase).
|
105 |
|
106 | ```scss
|
107 | // Omit .css at the end of the file
|
108 | @import '~@shopify/polaris-tokens/dist/colors.custom-properties';
|
109 |
|
110 | a {
|
111 | color: var(--color-blue-text);
|
112 | }
|
113 | ```
|
114 |
|
115 | ### Rails
|
116 |
|
117 | Token files are added to the assets pipeline. In JSON, design token names are formatted in [kebab-case](http://wiki.c2.com/?KebabCase).
|
118 |
|
119 | ```ruby
|
120 | require 'json'
|
121 | polaris_token_file = Rails.application.assets_manifest.find_sources('colors.json').first
|
122 | polaris_colors = JSON.parse(polaris_token_file)
|
123 | polaris_colors['color-blue-lighter'] # "rgb(235, 245, 250)"
|
124 | ```
|
125 |
|
126 | ### CSS Filters
|
127 |
|
128 | Color tokens include a [CSS Filter](https://developer.mozilla.org/en-US/docs/Web/CSS/filter) (`filter`) value as part of their metadata. When this filter is applied to an element, it will change that element’s color to _approximate_ the target token color.
|
129 |
|
130 | ```
|
131 | <div>
|
132 | No background, no filter
|
133 | </div>
|
134 |
|
135 | <div style="background-color: #fff">
|
136 | White background, no filter
|
137 | </div>
|
138 |
|
139 | <div style="filter: brightness(0) saturate(100%) invert(28%) sepia(67%) saturate(3622%) hue-rotate(353deg) brightness(89%) contrast(95%)">
|
140 | No background, red filter
|
141 | </div>
|
142 |
|
143 | <div style="background-color: #fff; filter: brightness(0) saturate(100%) invert(28%) sepia(67%) saturate(3622%) hue-rotate(353deg) brightness(89%) contrast(95%)">
|
144 | White background, red filter
|
145 | </div>
|
146 | ```
|
147 |
|
148 | ![text and non-transparent backgrounds become red when filter is applied](.github/filter-example-1.png)
|
149 |
|
150 | In general, these filters shouldn’t be used unless absolutely necessary. The main use case for the filters is to apply a color to an unsafe (as in: user-provided) SVG. Since SVGs can contain arbitrary code, we should be careful about how they are displayed. The safest option is to render SVGs as an `img` (for example `<img src="circle.svg" alt="" />`); when SVGs are rendered like this, browsers will block code execution. Unfortunately, it also means that the SVGs cannot be styled with external CSS (applying `fill: red` to the `img` won’t do anything.)
|
151 |
|
152 | CSS filters allow us the safety of rendering SVGs inside `img` elements, but still give us control over their appearance.
|
153 |
|
154 | ```
|
155 | <div>
|
156 | <img src="data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='50' height='50'><circle cx='20' cy='20' r='16' /></svg>" alt="" /> black circle, no filter
|
157 | </div>
|
158 | <div>
|
159 | <img src="data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='50' height='50'><circle cx='20' cy='20' r='16' /></svg>" style="filter: brightness(0) saturate(100%) invert(28%) sepia(67%) saturate(3622%) hue-rotate(353deg) brightness(89%) contrast(95%)" alt="" /> black circle, red filter
|
160 | </div>
|
161 | ```
|
162 |
|
163 | ![the filter turns the black circle red](.github/filter-example-2.png)
|
164 |
|
165 | Note that _all_ filled areas of an SVG will change color with this approach, including borders/strokes. For that reason it should only be used with monochromatic SVGs.
|
166 |
|
167 | ```
|
168 | <div>
|
169 | <img src="data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='50' height='50'><circle cx='20' cy='20' r='16' stroke='green' stroke-width='4' /></svg>" alt="" /> black circle with green border, no filter
|
170 | </div>
|
171 | <div>
|
172 | <img src="data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='50' height='50'><circle cx='20' cy='20' r='16' stroke='green' stroke-width='4' /></svg>" style="filter: brightness(0) saturate(100%) invert(28%) sepia(67%) saturate(3622%) hue-rotate(353deg) brightness(89%) contrast(95%)" alt="" /> black circle with green border, red filter
|
173 | </div>
|
174 | ```
|
175 |
|
176 | ![the filter turns the entire circle red, including the border](.github/filter-example-3.png)
|
177 |
|
178 | If you need to generate new filter values, you can do so with [this CodePen](https://codepen.io/kaelig/full/jeObGP/).
|
179 |
|
180 | ---
|
181 |
|
182 | ## Contributing
|
183 |
|
184 | The purpose of this repository is to see the core design elements of the Polaris design system
|
185 | evolve and improve over time with the needs of developers, designers and partners in mind.
|
186 |
|
187 | We gratefully accept impromptu contributions to the documentation, typo and bug fixes,
|
188 | and expect design token requests and changes to be discussed before a pull request.
|
189 |
|
190 | ### [Code of conduct](https://github.com/Shopify/polaris-tokens/blob/main/.github/CODE_OF_CONDUCT.md)
|
191 |
|
192 | We have a [code of conduct](https://github.com/Shopify/polaris-tokens/blob/main/.github/CODE_OF_CONDUCT.md),
|
193 | please follow it in all your interactions with the project.
|
194 |
|
195 | ### [Contributing guide](https://github.com/Shopify/polaris-tokens/blob/main/.github/CONTRIBUTING.md)
|
196 |
|
197 | Read the [contributing guide](https://github.com/Shopify/polaris-tokens/blob/main/.github/CONTRIBUTING.md)
|
198 | to learn how to propose changes and understand our development process.
|
199 |
|
200 | ### [License](https://github.com/Shopify/polaris-tokens/blob/main/LICENSE.md)
|
201 |
|
202 | The polaris-tokens project is available under the [MIT license](https://github.com/Shopify/polaris-tokens/blob/main/LICENSE.md).
|
203 |
|
204 | Parts of the code in this repository are directly inspired or borrowed
|
205 | from the [Theo project](https://github.com/salesforce-ux/theo),
|
206 | property of Salesforce.com, Inc., [licensed under BSD 3-Clause](https://git.io/sfdc-license).
|