Space Tokens

Introduction

Space tokens hold the whitespace inside and between elements: the padding of a button, the gap between an icon and its label, the padding of a page. The dimensions of the elements belong to the size tokens, whose page has the same sections as this one.

A space is a number of design pixels, and the build converts it to the unit of each platform, as Platform output shows. In the committed token sets, no brand, theme, or app overrides a space token. The tokens of space.website.* differ per screen, the optional fourth group.

Token levels

Each level references the level below it, so a size is written once, in dimension.base.*. The chain of one step shows the three levels:

dimension.base.16                       holds the size
├── space.unit.16                       {dimension.base.16}
│   └── space.button.large-padding-x    {space.unit.16}
└── size.unit.16                        {dimension.base.16}
    └── space.context.medium            {size.unit.16}

The two upper levels reference different scales. Component tokens reference space.unit.*, and context tokens reference size.unit.* of the size tokens. No component token references space.context.*, so a change to space.context.medium leaves space.button.large-padding-x as it is. The token sets of each level are files of packages/tokens/source/:

Base tokens

The base level holds the scale. dimension.base.* holds the sizes, and space.unit.* references them under the name of the category.

Dimension scale

dimension.base.* holds a size in design pixels, and the name of a step states that size. The size and the space tokens share this scale; the size tokens page explains the names of its steps and the prefixes d and n.

Space units

space.unit.* has a token for a part of the dimension scale, under the name of the step: space.unit.16 references {dimension.base.16}, and space.unit.n4 references {dimension.base.n4}. It has fewer steps than size.unit.*: the scale ends earlier, and it has fewer negative steps. The component tokens of this page reference these tokens.

Context tokens

space.context.* names steps of the scale by role, from zero to 6xlarge. Reach for them in layouts and in components that have no component token.

Component tokens

Component tokens hold the spacing of the parts of one component. A component with sizes has a token per size and part, space.<component>.<size>-<part>, in the source order medium, large, small. The parts are padding-y and padding-x for the vertical and the horizontal padding, gap, and nudge.

Accordion

Accordion spacing holds the padding of the title, the padding of the body, and the gap for each accordion size. The body has a token per side: -t, -b, -s, and -e for top, bottom, start, and end.

Alert

Alert spacing holds the padding and the gaps gap-main and gap-body of the large and the small alert.

Badge

Badge spacing holds the padding, the gap, and the nudge for each badge size.

Button

Button spacing holds the padding, the gap, and the nudge for each button size.

Chip

Chip spacing holds the padding, the gap, and the nudge for each chip size.

Date picker

Date picker spacing holds the padding and the gap of the date picker.

Dropdown

Dropdown spacing holds the padding and the gap of a dropdown.

Form input

Form input spacing holds the padding and the gap for each input size, and for a fourth group, floating.

List

List spacing holds the padding, the gap, and the nudge of a list item.

Notification

Notification spacing holds the padding and the gap of a notification.

Modal

Modal spacing holds the padding and the gap for each modal size.

Page

Page spacing holds the padding and the gap of a page for each page size. The gaps reference the gutter of the grid tokens, not a step of space.unit.*.

Pagination

Pagination spacing holds the gap between the dots.

Table

Table spacing holds the padding and the gap of a table cell.

Segment

Segment spacing holds the padding of the bar, bar-padding, and the padding and the gap of a segment for each segment size.

Website

Website spacing holds the padding and the gaps of a section, a feature, and a module of a website, and the gaps of the content. They differ per screen: each option of the screen group has its own token set, screen-website/screen-<screen>.json, with the same names. The columns are the screens of the committed configuration.

Usage

Space tokens apply to the padding of an element and to the gaps between elements. The level to use depends on how specific the element is.

Choosing a level

Use the most specific token that names the element, and go down a level only when none does:

• Use a component token for the part that it names: space.button.medium-gap for the gap inside a medium button.
• Use space.context.* in layouts and in components that have no component token.
• Use space.unit.* when no context token holds the space: a step between two context steps like space.unit.6, a step beyond the context scale, or a negative step like space.unit.n4.
• Leave dimension.base.* to the token sets. It is in the output because the unit tokens reference it.

Size and space

A space token sets a padding or a gap; a size token sets a width or a height. space.unit.16 and size.unit.16 hold the same size, because both reference dimension.base.16. The context tokens of both categories reference size.unit.*, so a change to space.unit.16 changes the component tokens that reference it and leaves space.context.medium as it is.

Platform output

Space tokens print in rem on the web, as CGFloat points on iOS, and as dp dimension resources on Android.

The web platform converts design pixels to rem at sixteen pixels per rem. iOS and Android keep the number of design pixels, as points and as dp. A negative step keeps its sign on every platform.

The build writes every level with its resolved size. The values in the examples are those of the chassis brand in the current version and differ in other brands. In main.scss:

$cx-space-unit-16: 1rem !default;
$cx-space-context-medium: 1rem !default;
$cx-space-button-large-padding-x: 1rem !default;

The main file of each platform holds space.website.* of the first configured screen. The number file of a screen, such as number-small.scss, holds them for that screen.

See the web, iOS, and Android docs for the files that hold these names.