@episerver/design-tokens
v0.1.1
Published
Re-usable design tokens to be used within Episerver themes.
Downloads
750
Keywords
Readme
Design Tokens
Theme variables as JSON, SASS, and LESS. It's used in UI Framework and its dependents. Can be used independently to get Episerver themes, useful for doing a UI Refresh of an existing frontend.
Getting Started
Add @episerver/design-tokens
as a dependency
yarn add @episerver/design-tokens
It includes design tokens in JSON, SASS, and LESS.
JSON
import variables from "@episerver/design-tokens/dist/json/variables";
They follow a basic structure of
[
{
"name": "token-name",
"val1": "some value",
"val2": "some other value"
}
]
The first element is a flat object:
{
"font-family": "Barlow, sans-serif",
"font-family-monospace": "Consolas, Monaco, 'Andale Mono', 'Ubuntu Mono', monospace",
"font-size-monospace": "13px",
"font-weight-regular": 400,
"font-weight-medium": 500,
"font-weight-bold": 700,
"text-emphasis-high": 0.87,
"text-emphasis-medium": 0.6,
"text-emphasis-disabled": 0.38,
"text-color-emphasis-high": "rgba(0, 0, 0, 0.87)",
"text-color-emphasis-medium": "rgba(0, 0, 0, 0.6)",
"text-color-emphasis-disabled": "rgba(0, 0, 0, 0.38)"
},
Subsequent elements are either color, typography, or shape:
{
"name": "color-primary-500",
"hex": "1456f1",
"alpha": 1
},
{
"name": "typography-styles-body1",
"letterSpacing": 0,
"lineHeight": 19,
"font": {
"postscriptName": "Barlow-Regular",
"family": "Barlow",
"size": 16,
"weight": "regular",
"stretch": "normal"
},
"color": {
"hex": "000000",
"alpha": 0.87
}
},
{
"name": "shape-medium-component-radius",
"radius": "4px"
},
The tokens are under rapid development so their interfaces can change at any time.
SASS
@use "@episerver/design-tokens/dist/scss/variables" as epi;
$your-theme-primary: epi.$color-primary-500;
SASS with webpack
Setting up SASS with a project using webpack is very quick.
- Install sass-loader and node-sass.
yarn add --dev sass-loader node-sass
- Add a new rule to
webpack.config.js
for .scss files
{
test: /\.scss$/,
loaders: [
"style-loader",
"css-loader",
{
loader: "sass-loader",
options: {
includePaths: ["node_modules"]
}
}
],
include: path.resolve(__dirname, "../")
}
LESS
@import "@episerver/design-tokens/dist/less/_variables";
@your-theme-primary: @color-primary-500;
LESS with gulp
Setting up LESS with a project using gulp is very quick.
- Install gulp-less.
yarn add --dev gulp-less
- Add a new task to
gulpfile.js
for .less files, or change an existing task.
task("build-less", () => {
return src(["**/*.less"]).pipe(
less({
paths: [path.join(__dirname, "node_modules")],
})
);
});
Fonts
The tokens in the Design System (and the components in the UI Framework) use a custom font which you need to load in the appropriate manner for your application.
Google Fonts
Loading the font via Google Fonts is the preferred approach as it will provide the best performance, and it only requires that you add a link in the head of the HTML document.
<link href="https://fonts.googleapis.com/css?family=Barlow" rel="stylesheet" />
Depending on the site setup, this may require changes to the content security policy for the site. The following rules would be needed in that case:
style-src 'self' https://fonts.googleapis.com; font-src 'self' https://fonts.gstatic.com
Local Fonts
If the application can be used in scenarios where loading external resources is potentially forbidden, then you can bundle the fonts with your application by adding the following to your entry point file. You will need to take a dependency on UI Framework and follow the readme there for "Local Fonts".
Releases
Releases will be created at the team's discretion. This should be done regularly when there are bug fixes or new features available. Releases follow semantic versioning. This means that, until there is a major version, minor versions may contain breaking changes.
See the CHANGELOG.md document for information about what is included in each release.
Internal
See the GUIDELINES.md document for more information about contributing and the release process.