Size Tokens

Introduction

Size tokens hold the dimensions of an element: the height of a button, the size of an icon, the width of a modal window. The whitespace inside and between elements belongs to the space tokens, whose page has the same sections as this one.

A size 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 size token. The tokens of size.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
└── size.unit.16                   {dimension.base.16}
    ├── size.context.2xsmall       {size.unit.16}
    ├── size.icon.glyph.xsmall     {size.unit.16}
    └── size.button.small-caret    {size.unit.16}

Context and component tokens both reference size.unit.*. No component token references size.context.*, so a change to size.context.medium leaves size.button.medium-main 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 size.unit.* references them one to one 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: dimension.base.16 is sixteen design pixels. The steps are close together at the start of the scale and further apart toward its end. The size, space, border radius, and shadow tokens reference this scale.

A step that is not a positive whole number has a prefix:

• d marks a fraction: d15 is one and a half, and d25 is two and a half.
• 05 and d05 are both a half.
• n marks a negative size: n4 is minus four, and nd15 is minus one and a half.

Size units

size.unit.* has a token for every step of the dimension scale, under the name of the step: size.unit.16 references {dimension.base.16}, and size.unit.n4 references {dimension.base.n4}. The context and component tokens of this page reference these tokens.

Context tokens

size.context.* names evenly spaced steps of the scale by role, from 2xsmall to 2xlarge. Reach for them to size an element that has no component token.

Icon sizes

size.icon.glyph.* names the sizes of an icon, from 3xsmall to 6xlarge. Most component tokens for an icon reference size.unit.* directly; size.dropdown.icon references size.icon.glyph.small.

Asset sizes

size.asset.* holds the size of an indicator and of a separator. The border width tokens borderWidth.asset.indicator and borderWidth.asset.separator reference them.

Component tokens

Component tokens hold the sizes of the parts of one component. A component with sizes has a token per size and part, size.<component>.<size>-<part>, in the source order medium, large, small. The part main is the component itself; parts like icon, caret, and avatar are elements inside it.

Accordion

Accordion sizes hold the indicator of each accordion size.

Alert

Alert sizes hold the icon of the large and the small alert.

Badge

Badge sizes hold the badge and its icon for each badge size.

Button

Button sizes hold the button, its icon, and its caret for each button size.

Chip

Chip sizes hold the chip, its icon, and its avatar for each chip size.

List

List sizes hold the icon, the image, and the disclosure of a list item.

Date picker

Date picker sizes hold the width and the height of a day, and the widths of a week and of a preset. The source computes the width of a week from the width of a day.

Dropdown

Dropdown sizes hold the icon and the disclosure of a dropdown. The icon follows the icon sizes of the context level.

Form input

Form input sizes hold the icon and the caret of each input size. The group has no main token.

Modal

Modal sizes hold the width and the height of the modal window: size.modal.window-<size>-w and size.modal.window-<size>-h, for the sizes small, medium, large, and xlarge. These tokens hold a size of their own and reference no step of the scale.

Notification

Notification sizes hold the icon of a notification.

Navigation

Navigation sizes hold the widths of the left navigation and the height of the top navigation. size.nav-left.width references the expanded width.

Pagination

Pagination sizes hold the width (-w) and the height (-h) of a dot in its idle and its active state.

Segment

Segment sizes hold the segment and its icon for each segment size.

Website

Website sizes hold the thumb and the icon of a section, a feature, and a module of a website. 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.

Grid tokens

grid.* is a group of its own, next to size.*, in base/app-base.json. It holds the widths of the layout grid, named grid.<part>.<step> with the steps xsmall, small, medium, large, xlarge, and 2xlarge. The tokens hold a size of their own, reference no step of the scale, and are the same on every screen.

grid.breakpoint.* holds the breakpoints, grid.container.* the width of the container at each breakpoint, and grid.gutter.* the gutters. The container of a step is narrower than the breakpoint of that step. The page gaps space.page.large-gap, space.page.medium-gap, and space.page.small-gap of the space tokens reference grid.gutter.medium.

Usage

Size tokens apply to the width and the height of an element. 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: size.button.medium-icon for the icon of a medium button.
• Use size.icon.glyph.* for an icon and size.context.* for another element that has no component token.
• Use size.unit.* when no context token holds the size. The unit scale has steps between and beyond those of the context scale.
• Leave dimension.base.* to the token sets. It is in the output because the unit tokens reference it.

Size and space

A size token sets a width or a height; a space token sets a padding or a gap. size.unit.16 and space.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 size.unit.16 changes size.context.2xsmall and space.context.medium.

Platform output

Size 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.

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

$cx-dimension-base-16: 1rem !default;
$cx-size-unit-16: 1rem !default;
$cx-size-context-2xsmall: 1rem !default;

With the outputReferences option, a token names the token that it references, which is why dimension.base.* is in the output. The Style Dictionary guide describes the option. With it, the build writes in ChassisTokens.swift:

    public static let DimensionBase16 = CGFloat(16)
    public static let SizeUnit16 = DimensionBase16
    public static let SizeContext2xsmall = SizeUnit16

The main file of each platform holds size.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.