POS design tokens reference
On this page
Design tokens are the shared colors, fonts, font weights, and type sizes that every part of the POS uses. Change a token once, and the change shows on every screen.
Use this reference to restyle the whole POS, such as setting your brand color or a warmer background, or to match your own view markup to the POS. Tokens are part of the POS styling API, so follow the rules when you style with them. A token is removed or renamed only in a major release, and the release notes give notice before then.
Where design tokens apply
Everywhere in the POS. Buttons, badges, text groups, cards, layouts, records tables, and the
screens around them all use these tokens, so one token changes them all at once. A component’s
own properties, such as --sc-button-bg, override a token on that component.
Set a design token
Set a token on :root in a style block with POS in Channels, and every component that reads it follows. In the style
block’s Content, write the CSS alone. StoreConnect adds the <style> tags:
```css
:root { –sc-color-primary: #1f3a93; –sc-color-on-primary: #ffffff; } ```
Tokens come in sets designed together, so when you change one, change the ones that go with it:
- A color and the
on-color paired with it, such as--sc-color-primaryand--sc-color-on-primary. - A color and the
-hoverand-activesteps built from it. They are fixed values, so they don’t follow the color on their own. - The primary color and the layer named for it,
--sc-color-layer-primary: the same color as RGB channels, which the POS lays over surfaces as a see-through tint.
A POS view can read a token with var() in a <style> element in the view’s HTML Template, so
the view’s own markup matches the POS. A token’s value can change in any release, so read the
token rather than copying the value:
```html
```
:::note
POS tokens and your web theme’s CSS variables are separate sets, even where both start with
--sc-. The web theme’s own stylesheets don’t load in the POS, but a style block loads in every
channel listed in Channels. If a style block lists both channels and sets a name that both
sets use, the change shows in the POS and on the website. To keep them apart, list one channel
in each style block.
:::
The Available from column in each table shows the first release that carries the token. The Value column shows what the POS uses when you leave the token alone. Values can change in any release.
Surface color tokens
Background layers, in order of elevation: the screen, an inset area, a raised panel, an overlay
such as a menu, and an inverse surface for dark controls. Each has a -hover and an -active
step for a control that sits on it.
| Token | Value | Available from |
|---|---|---|
--sc-color-surface |
#E7E9EE |
v21.0.0 |
--sc-color-surface-active |
#d0dbec |
v21.0.0 |
--sc-color-surface-hover |
#dee0e5 |
v21.0.0 |
--sc-color-surface-inset |
#DEE2E8 |
v21.0.0 |
--sc-color-surface-inset-active |
#c8d5e6 |
v21.0.0 |
--sc-color-surface-inset-hover |
#d5d9df |
v21.0.0 |
--sc-color-surface-inverse |
#333E4D |
v21.0.0 |
--sc-color-surface-inverse-active |
#525b68 |
v21.0.0 |
--sc-color-surface-inverse-hover |
#3d4856 |
v21.0.0 |
--sc-color-surface-overlay |
#FFFFFF |
v21.0.0 |
--sc-color-surface-overlay-active |
#e6effb |
v21.0.0 |
--sc-color-surface-overlay-hover |
#f4f5f5 |
v21.0.0 |
--sc-color-surface-raised |
#F3F4F7 |
v21.0.0 |
--sc-color-surface-raised-active |
#dbe5f4 |
v21.0.0 |
--sc-color-surface-raised-hover |
#e9eaee |
v21.0.0 |
Brand color tokens
The primary color, for what matters most on a screen, and the secondary color beside it. Each
-soft token is a lighter tint of the color for larger fills, and -soft-variant is fainter
still.
| Token | Value | Available from |
|---|---|---|
--sc-color-primary |
#055CD6 |
v21.0.0 |
--sc-color-primary-active |
#2b74dc |
v21.0.0 |
--sc-color-primary-hover |
#1264d8 |
v21.0.0 |
--sc-color-primary-soft |
#B8D0F5 |
v21.0.0 |
--sc-color-primary-soft-active |
#a3b8d9 |
v21.0.0 |
--sc-color-primary-soft-hover |
#b1c8ec |
v21.0.0 |
--sc-color-primary-soft-variant |
#DEEAFC |
v21.0.0 |
--sc-color-secondary |
#A8CDE6 |
v21.0.0 |
--sc-color-secondary-active |
#b5d5ea |
v21.0.0 |
--sc-color-secondary-hover |
#acd0e7 |
v21.0.0 |
--sc-color-secondary-soft |
#C6DDEC |
v21.0.0 |
--sc-color-secondary-soft-active |
#aec3d2 |
v21.0.0 |
--sc-color-secondary-soft-hover |
#bed4e3 |
v21.0.0 |
Success color tokens
The color for a good result, such as a verified count, with the same soft tints as the brand colors.
| Token | Value | Available from |
|---|---|---|
--sc-color-success |
#228849 |
v22.0.0 |
--sc-color-success-active |
#439a64 |
v22.0.0 |
--sc-color-success-hover |
#2d8e52 |
v22.0.0 |
--sc-color-success-soft |
#afd2b1 |
v22.0.0 |
--sc-color-success-soft-active |
#9bbaa0 |
v22.0.0 |
--sc-color-success-soft-hover |
#a8caab |
v22.0.0 |
--sc-color-success-soft-variant |
#d4e4d8 |
v22.0.0 |
Error color tokens
The color for a problem, such as an error message, with the same soft tints as the brand colors.
| Token | Value | Available from |
|---|---|---|
--sc-color-error |
#B3261E |
v21.0.0 |
--sc-color-error-active |
#be4740 |
v21.0.0 |
--sc-color-error-hover |
#b73129 |
v21.0.0 |
--sc-color-error-soft |
#EBC4C2 |
v21.0.0 |
--sc-color-error-soft-active |
#ceaeae |
v21.0.0 |
--sc-color-error-soft-hover |
#e1bdbb |
v21.0.0 |
--sc-color-error-soft-variant |
#f8e2e2 |
v21.0.0 |
Text and icon color tokens
Text and icon colors, each paired with a background: --sc-color-on-surface is for text on a
surface, --sc-color-on-primary is for text on the primary color, and so on. The -muted and
-variant tokens are for quieter text on a surface. When you change a color, change the foreground
paired with it.
| Token | Value | Available from |
|---|---|---|
--sc-color-on-error |
#F9EDEC |
v21.0.0 |
--sc-color-on-error-soft |
#5E1B17 |
v21.0.0 |
--sc-color-on-error-soft-variant |
#980000 |
v21.0.0 |
--sc-color-on-primary |
#E8EEF7 |
v21.0.0 |
--sc-color-on-primary-soft |
#05459f |
v21.0.0 |
--sc-color-on-primary-soft-variant |
#305c98 |
v22.0.0 |
--sc-color-on-secondary |
#143352 |
v21.0.0 |
--sc-color-on-secondary-soft |
#1F4D7A |
v21.0.0 |
--sc-color-on-success |
#ECF9EE |
v22.0.0 |
--sc-color-on-success-soft |
#135c35 |
v22.0.0 |
--sc-color-on-success-soft-variant |
#2c5d43 |
v22.0.0 |
--sc-color-on-surface |
#041225 |
v21.0.0 |
--sc-color-on-surface-inverse |
#F8F8F9 |
v21.0.0 |
--sc-color-on-surface-muted |
#67717E |
v21.0.0 |
--sc-color-on-surface-variant |
#414B58 |
v21.0.0 |
Border color tokens
Borders and dividers at three strengths, and a soft border to go with each of the primary and
error soft fills. Each --sc-color-border-* token is another name for the matching
--sc-color-stroke-* token. Some parts of the POS use the border name and some use the
stroke name, so to change every border, set the stroke tokens. The border tokens follow
them. A border token set on its own changes only some borders.
| Token | Value | Available from |
|---|---|---|
--sc-color-border-default |
var(--sc-color-stroke-default) |
v21.0.0 |
--sc-color-border-error-soft |
var(--sc-color-stroke-error-soft) |
v21.0.0 |
--sc-color-border-primary-soft |
var(--sc-color-stroke-primary-soft) |
v21.0.0 |
--sc-color-border-strong |
var(--sc-color-stroke-strong) |
v21.0.0 |
--sc-color-border-subtle |
var(--sc-color-stroke-subtle) |
v21.0.0 |
--sc-color-stroke-default |
#CED3DA |
v21.0.0 |
--sc-color-stroke-error-soft |
#E59D99 |
v21.0.0 |
--sc-color-stroke-primary-soft |
#99B7E5 |
v21.0.0 |
--sc-color-stroke-strong |
#B6BEC9 |
v21.0.0 |
--sc-color-stroke-subtle |
#E8EAEE |
v21.0.0 |
Overlay color tokens
Colors the POS lays over surfaces as a see-through tint: on hover, on press, and behind sheets
and menus. Each value is three RGB numbers with no opacity, so you add the opacity where you use
the token, as in rgb(var(--sc-color-layer-dark) / 0.08). --sc-color-layer-primary holds the
primary color as RGB numbers, so change it whenever you change --sc-color-primary.
| Token | Value | Available from |
|---|---|---|
--sc-color-layer-dark |
41 49 61 |
v21.0.0 |
--sc-color-layer-error |
179 38 30 |
v21.0.0 |
--sc-color-layer-light |
255 255 255 |
v21.0.0 |
--sc-color-layer-primary |
5 92 214 |
v21.0.0 |
--sc-color-layer-success |
19 86 35 |
v22.0.0 |
Font tokens
The two font stacks. --sc-font-plain sets the font of the POS’s base text and headings. Text
in a type scale uses the -font token of that scale instead, so to change the font everywhere,
set --sc-font-plain and the -font token of each type scale. The POS doesn’t use
--sc-font-brand yet.
| Token | Value | Available from |
|---|---|---|
--sc-font-brand |
-system-ui, -apple-system, BlinkMacSystemFont, sans-serif |
v21.0.0 |
--sc-font-plain |
-system-ui, -apple-system, BlinkMacSystemFont, sans-serif |
v21.0.0 |
Font weight tokens
Font weights for text outside a type scale.
| Token | Value | Available from |
|---|---|---|
--sc-weight-bold |
700 |
v21.0.0 |
--sc-weight-medium |
500 |
v21.0.0 |
--sc-weight-regular |
400 |
v21.0.0 |
--sc-weight-semibold |
600 |
v21.0.0 |
Type scale tokens
Fifteen type scales, each as --sc-type-<scale>-size, -line-height, -font, -weight,
-weight-em for the weight of emphasized text, and -letter-spacing on the headline scales.
Sizes are in rem and letter spacing in em.
| Token | Value | Available from |
|---|---|---|
--sc-type-body-large-font |
-system-ui, -apple-system, BlinkMacSystemFont, sans-serif |
v21.0.0 |
--sc-type-body-large-line-height |
1.25rem |
v21.0.0 |
--sc-type-body-large-size |
1rem |
v21.0.0 |
--sc-type-body-large-weight |
400 |
v21.0.0 |
--sc-type-body-large-weight-em |
500 |
v21.0.0 |
--sc-type-body-medium-font |
-system-ui, -apple-system, BlinkMacSystemFont, sans-serif |
v21.0.0 |
--sc-type-body-medium-line-height |
1.0625rem |
v21.0.0 |
--sc-type-body-medium-size |
0.875rem |
v21.0.0 |
--sc-type-body-medium-weight |
400 |
v21.0.0 |
--sc-type-body-medium-weight-em |
500 |
v21.0.0 |
--sc-type-body-small-font |
-system-ui, -apple-system, BlinkMacSystemFont, sans-serif |
v21.0.0 |
--sc-type-body-small-line-height |
0.9375rem |
v21.0.0 |
--sc-type-body-small-size |
0.75rem |
v21.0.0 |
--sc-type-body-small-weight |
400 |
v21.0.0 |
--sc-type-body-small-weight-em |
500 |
v21.0.0 |
--sc-type-display-large-font |
-system-ui, -apple-system, BlinkMacSystemFont, sans-serif |
v21.0.0 |
--sc-type-display-large-line-height |
4rem |
v21.0.0 |
--sc-type-display-large-size |
3.5625rem |
v21.0.0 |
--sc-type-display-large-weight |
500 |
v21.0.0 |
--sc-type-display-large-weight-em |
600 |
v21.0.0 |
--sc-type-display-medium-font |
-system-ui, -apple-system, BlinkMacSystemFont, sans-serif |
v21.0.0 |
--sc-type-display-medium-line-height |
2.75rem |
v21.0.0 |
--sc-type-display-medium-size |
2.5rem |
v21.0.0 |
--sc-type-display-medium-weight |
500 |
v21.0.0 |
--sc-type-display-medium-weight-em |
600 |
v21.0.0 |
--sc-type-display-small-font |
-system-ui, -apple-system, BlinkMacSystemFont, sans-serif |
v21.0.0 |
--sc-type-display-small-line-height |
2.75rem |
v21.0.0 |
--sc-type-display-small-size |
2.25rem |
v21.0.0 |
--sc-type-display-small-weight |
500 |
v21.0.0 |
--sc-type-display-small-weight-em |
600 |
v21.0.0 |
--sc-type-headline-large-font |
-system-ui, -apple-system, BlinkMacSystemFont, sans-serif |
v21.0.0 |
--sc-type-headline-large-letter-spacing |
0.0156em |
v21.0.0 |
--sc-type-headline-large-line-height |
2.375rem |
v21.0.0 |
--sc-type-headline-large-size |
2rem |
v21.0.0 |
--sc-type-headline-large-weight |
400 |
v21.0.0 |
--sc-type-headline-large-weight-em |
500 |
v21.0.0 |
--sc-type-headline-medium-font |
-system-ui, -apple-system, BlinkMacSystemFont, sans-serif |
v21.0.0 |
--sc-type-headline-medium-letter-spacing |
0.0107em |
v21.0.0 |
--sc-type-headline-medium-line-height |
2.25rem |
v21.0.0 |
--sc-type-headline-medium-size |
1.75rem |
v21.0.0 |
--sc-type-headline-medium-weight |
400 |
v21.0.0 |
--sc-type-headline-medium-weight-em |
500 |
v21.0.0 |
--sc-type-headline-small-font |
-system-ui, -apple-system, BlinkMacSystemFont, sans-serif |
v21.0.0 |
--sc-type-headline-small-letter-spacing |
0.0125em |
v21.0.0 |
--sc-type-headline-small-line-height |
2rem |
v21.0.0 |
--sc-type-headline-small-size |
1.5rem |
v21.0.0 |
--sc-type-headline-small-weight |
400 |
v21.0.0 |
--sc-type-headline-small-weight-em |
500 |
v21.0.0 |
--sc-type-label-large-font |
-system-ui, -apple-system, BlinkMacSystemFont, sans-serif |
v21.0.0 |
--sc-type-label-large-line-height |
1.125rem |
v21.0.0 |
--sc-type-label-large-size |
0.9375rem |
v21.0.0 |
--sc-type-label-large-weight |
400 |
v21.0.0 |
--sc-type-label-large-weight-em |
500 |
v21.0.0 |
--sc-type-label-medium-font |
-system-ui, -apple-system, BlinkMacSystemFont, sans-serif |
v21.0.0 |
--sc-type-label-medium-line-height |
1rem |
v21.0.0 |
--sc-type-label-medium-size |
0.8125rem |
v21.0.0 |
--sc-type-label-medium-weight |
400 |
v21.0.0 |
--sc-type-label-medium-weight-em |
500 |
v21.0.0 |
--sc-type-label-small-font |
-system-ui, -apple-system, BlinkMacSystemFont, sans-serif |
v21.0.0 |
--sc-type-label-small-line-height |
0.8125rem |
v21.0.0 |
--sc-type-label-small-size |
0.6875rem |
v21.0.0 |
--sc-type-label-small-weight |
400 |
v21.0.0 |
--sc-type-label-small-weight-em |
500 |
v21.0.0 |
--sc-type-title-large-font |
-system-ui, -apple-system, BlinkMacSystemFont, sans-serif |
v21.0.0 |
--sc-type-title-large-line-height |
1.625rem |
v21.0.0 |
--sc-type-title-large-size |
1.25rem |
v21.0.0 |
--sc-type-title-large-weight |
500 |
v21.0.0 |
--sc-type-title-large-weight-em |
600 |
v21.0.0 |
--sc-type-title-medium-font |
-system-ui, -apple-system, BlinkMacSystemFont, sans-serif |
v21.0.0 |
--sc-type-title-medium-line-height |
1.5rem |
v21.0.0 |
--sc-type-title-medium-size |
1.125rem |
v21.0.0 |
--sc-type-title-medium-weight |
500 |
v21.0.0 |
--sc-type-title-medium-weight-em |
600 |
v21.0.0 |
--sc-type-title-small-font |
-system-ui, -apple-system, BlinkMacSystemFont, sans-serif |
v21.0.0 |
--sc-type-title-small-line-height |
1.25rem |
v21.0.0 |
--sc-type-title-small-size |
1.0625rem |
v21.0.0 |
--sc-type-title-small-weight |
500 |
v21.0.0 |
--sc-type-title-small-weight-em |
600 |
v21.0.0 |
Design token examples
StoreConnect’s automated tests run each of these examples against the POS whenever the POS code changes, so they work as written.
“Use our brand color.”
```css
:root { –sc-color-primary: #1f3a93; –sc-color-primary-hover: #2a4aa6; –sc-color-primary-active: #3858b4; –sc-color-on-primary: #ffffff; –sc-color-layer-primary: 31 58 147; } ```
“Give the screens a warmer background.”
```css
:root { –sc-color-surface: #f1ede6; –sc-color-surface-hover: #e8e2d8; –sc-color-surface-active: #ded6c9; –sc-color-surface-raised: #f9f7f3; –sc-color-surface-raised-hover: #f0ece5; –sc-color-surface-raised-active: #e6e0d6; } ```
“Make the body text a little larger.”
```css
:root { –sc-type-body-medium-size: 0.9375rem; –sc-type-body-medium-line-height: 1.25rem; } ```
“Make titles heavier.”
```css
:root { –sc-type-title-small-weight: 600; –sc-type-title-small-weight-em: 700; } ```
What design tokens can’t style yet
- The font of the whole POS with one token. Text in a type scale uses the
-fonttoken of that scale, not--sc-font-plain, so set the-fonttoken of each scale too. - The older palette the POS still defines,
--sc-brand-N,--sc-shade-N,--sc-notify-N, and--sc-customer-N, and the spacing scale--sc-spacing-N. They aren’t tokens: they are internal, and the POS is moving off them, so a style that sets or reads them can break in any release.
Retired design tokens
None yet. A token is retired before it is removed: it is listed here with what replaces it and the major release that removes it, and it keeps working until that release. See When parts change.
Was this article helpful?
Thanks for your feedback! It helps us improve our docs.