Skip to content
Log in

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-primary and --sc-color-on-primary.
  • A color and the -hover and -active steps 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 -font token of that scale, not --sc-font-plain, so set the -font token 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?

Was this article helpful?