[image url]: https://smartcontract.imgix.net/examples/design-system-docs/image
npm install @chainlink/design-system[image url]: https://smartcontract.imgix.net/examples/design-system-docs/image
By Brian Boehlke & Alejandro Larumbe
Q3 2022
Status: In Progress
1. Background
2. Getting started
3. Tokens
4. Values
5. Global tag styling
6. Classes
7. Modules
As of Q3 2022, the Front End team released a public version of the Design System as an NPM package.
This document is a guide for importing the package and using the Design System files in a product external to the Product Design and FE teams.
A library of styles & components released as reusable code to make adopting teams more efficient and consistent in their execution.
To make the system work for the largest number of users, the styles and classes are all written in CSS files.
The Design System's NPM package makes the underlying Chainlink Labs Product Design styles available to any team interested in using them.
- Install latest version: npm install @chainlink/design-system
- Install specific version: npm install @chainlink/design-system@[version_number]
To get started, import the Design System into one of your app’s top layer components:
``js`
require(@chainlink/design-system/global-styles.css)
or
`js`
import '@chainlink/design-system/global-styles.css'
Importing the design system in your application will apply out of the box styling to HTML tags and access to CSS variables, tokens, and class-based components.
The library is broken up into different groups: Values, Tokens, Global Tags, Classes, and Modules. Each group serves a different level of complexity.
_For example_:
_Values_ are the lowest level variable in the Design System. Most point to hard coded values such as pixels, rem, percentages, or hex numbers.
`css`
--blue-600: #375bd2;
_Tokens_ assign semantically named variables that point to the individual values.
`css`
--color-text-link: var(--blue-600);
_Classes_ are more complex by combining multiple declarations into CSS classes that can be applied to HTML tags.
`css
:where(.heading-600, h1) {
font-size: 2rem;
margin-bottom: var(--space-4x);
letter-spacing: -0.04rem;
}
:where(.paragraph, .paragraph-100, .paragraph-200, .paragraph-300, body, p) {
font-family: var(--font-family-text);
line-height: 1.5;
font-weight: var(--font-weight-normal);
color: var(--color-text-primary);
}
`
Importing CLDS automatically applies classes to certain _HTML tags_.
For example, before importing CLDS:
` Explore the decentralized oracle networks powered by Chainlinkjsx`Chainlink Data Feeds
Becomes Chainlink styled when the Design System is imported:
Semantically named variables and styles used in our frontend apps -such as _Data_, _Faucets_, and _Automation_- to help simplify implementation and reduce future maintenance.
The CLDS provides tokens in the form of CSS variables.
_For example_:
` Explore the decentralized oracle networks powered by Chainlinkjsx
margin: 'var(--space-4x)',
backgroundColor: 'var(--color-background-secondary)',
}}
>
Chainlink Data Feeds
The tokens are split based on their proposed use:
- Background (colors)
- Border (colors, widths, radii, box-shadows)
- Fill (colors used for SVG icons)
- Shadow (colors and box-shadows)
- Typography (colors)
$3
Color
| Name | Intended use |
| ---------------------------- | ------------------------------------ |
| --color-background-primary | Body background |
| --color-background-secondary | Section background |
| --color-background-error | Alert error background |
| --color-background-contrast | Banner background |
| --color-background-warning | Alert warning background |
| --color-background-success | Alert success background |
| --color-background-info | Alert highlight background |
| --color-background-disabled | Disabled button & control background |
$3
Color
| Name | Intended use |
| ---------------------------------- | ------------------------------------------------------------------------ |
| --color-border-primary | Cards, Tiles |
| --color-border-secondary | Dropdown, Menu, use with --shadow-mid when combining borders and shadows |
| --color-border-contrast | Banner border |
| --color-border-interactive | Input & control borders resting state |
| --color-border-interactive-focus | UI focus border |
| --color-border-interactive-hover | Input & control border hover state |
| --color-border-interactive-pressed | Input & control border pressed state |
| --color-border-interactive-error | Interactive card pressed state |
| --color-border-disabled | Disabled button & control border |
| --color-border-separator | Horizontal rule |
Inner borders as box-shadow
| Name | Intended use |
| -------------------- | ------------------------------------------------------------------------ |
| --border-primary | Cards, Tiles |
| --border-secondary | Dropdown, Menu, use with --shadow-mid when combining borders and shadows |
| --border-interactive | Input & control borders resting state |
Radius
| Name | Intended use |
| ------------------------- | -------------------- |
| --border-radius-primary | Inputs, Buttons |
| --border-radius-secondary | Cards |
| --border-radius-reset | Border reset |
| --border-radius-round | Rounded icon buttons |
Width
| Name | Intended use |
| ------------------------ | ------------ |
| --border-width-primary | Inputs |
| --border-width-secondary | Buttons |
| --border-width-reset | Border reset |
$3
Color
| Name | Intended use |
| -------------------- | --------------------------- |
| --color-fill-success | Success icon fill and Alert |
| --color-fill-error | Error icon fill and Alert |
| --color-fill-warning | Warning icon fill and Alert |
| --color-fill-info | Info icon fill and Alert |
$3
Color tints
| Name | Intended use |
| ---------------------- | ------------------------------------------- |
| --shadow-color-primary | Shadows on background-primary and secondary |
| --shadow-color-secondary | Shadows on gray backgrounds |
| --shadow-color-contrast | Shadows on the dimmed/scrim background |
Shadows in form of layered box shadows
| Name | Intended use |
| ----------------------- | -------------------------------------------------- |
| --shadow-low | Tile, Tooltip |
| --shadow-mid | Toast, Menu, Side Panel |
| --shadow-high | Modal |
| --shadow-low-secondary | Options for shadows on different background colors |
| --shadow-mid-secondary | |
| --shadow-high-secondary | |
$3
| Name | Intended use |
| ------------------------ | --------------------------------- |
| --color-text-primary | Body text |
| --color-text-secondary | Body text on secondary background |
| --color-text-heading | Heading text |
| --color-text-error | Error state text |
| --color-text-warning | Warning text |
| --color-text-success | Success text |
| --color-text-info | Alert text |
| --color-text-contrast | Banner text |
| --color-text-link | Link text |
| --color-text-link-hover | Link text hover |
| --color-text-link-active | Link text pressed |
| --color-text-disabled | Disabled text |
| --color-text-placeholder | Form placeholder text |
| --color-text-value | Form value text |
| --color-text-label | Form label text |
Values
The base values of the design system. These tend to be hard-coded values like pixels, rem, hex numbers, etc.
These values can be accessed using the var() function:
css
.example {
padding: var(--space-2x);
background-color: var(--orange-200);
}
` - Aim to use the tokens as the first option and fall back to use the low-level values if the token does not exist.
Values are split according to their use:
Classes
Classes that can be applied to HTML tags to leverage the Product Design team’s styles. These classes are included when importing the design system.
$3
To use, add the pertinent class to an HTML tag (no need for additional imports). _For example_:
`jsx
`In addition, a group of classes are
when importing the design system. (See example above)
$3
- Layout: _main_
- Typography: _h1_, _h2_, _h3_, _h4_, _h5_, _h6_, _p_, _span_, _button_, _input_, _select_, _area_, _label_
PRO Tip - _Classes_ can be overridden if needed by applying a different _class_ or CSS styling to an HTML tag.
Classes available in CLDS acording to their use:
$3
Top level classes to match the page layout of the Chainlink productss (ie. Automation, VRF, etc.).
- container
- card _Example_:
`jsx
Chainlink Data Feeds
Explore the decentralized oracle networks powered by Chainlink
`
$3
CSS classes that match the Product Design team’s text styles within Figma.
- By importing the CLDS, the Typography component file will assign styles to all headings, paragraphs and spans
- To override or apply classes to any other HTML tags, add the class to the tag
- This will provide the tag: font-family, font-weight, color, and line-height
- If needing to change the font-weight, apply using inline styles.
jsx
Example
`List all typography classes:
| Name | Intended use 📱 | Automatically applied to: |
| ------------- | -------------------------------- | ------------------------- |
| display-400 | Marketing headers and titles | |
| display-500 | | |
| display-600 | | |
| heading-100 | Headers and titles | h6 |
| heading-200 | | h5 |
| heading-300 | | h4 |
| heading-400 | | h3 |
| heading-500 | | h2 |
| heading-600 | | h1 |
| paragraph-100 | Multi-line text block (2+ lines) | |
| paragraph-200 | | body, p |
| paragraph-300 | | |
| text-100 | Single lines of text (1 line) | |
| text-200 | | span |
| text-300 | | |
| label | Form labels, table headers | |
Modules
More complex components that rely on a tag hierarchy and may have variants. Module components are responsive.
In order to use, import each component:
js
const component = require('@chainlink/design-system/component.module.css')
`or
js
import component from '@chainlink/design-system/component.module.css'
`Module components are module.css files. You can read this guide if your app does not support module.css files out of the box.
$3
Import
js
import button from '@chainlink/design-system/button.module.css'
`Variants
- primary
- secondary
- tertiary
- tag
- reset
Structure
js
`Tertiary button accepts an svg image:
js
`Usage
jsReset
`
$3
Import
js
import hero from '@chainlink/design-system/hero.module.css'
`Usage
Place the hero.container class in the components's parent element.
Structure
jsx
Hero Title
{/ Optional /}
{/ Optional /}
Description
{/ Optional. May be a button or a. /}
{/ Optional. May be a button or a. /}
Button 2
`Usage
jsx
Chainlink Verifiable Randomness Function
Chainlink VRF provides cryptographically secure randomness for your smart
contracts.
className={button.secondary}
>
Go to the docs
`Desktop:
Mobile:
A stripped down version of the Hero might look like this:
tsx
Chainlink Verifiable Randomness Function
Chainlink VRF provides cryptographically secure randomness for your smart
contracts.
className={button.secondary}
>
Go to the docs
`
$3
Import
js
import headerbanner from '@chainlink/design-system/headerbanner.module.css'
`Structure
jsx
`Usage example
jsx
`