Component spacing

Component spacing defines the internal relationships within a component, ensuring they stay correct at every size and density.
Frosted-glass style UI mockup on a purple-to-peach gradient background, showing a "Subscribe" button with an app icon, a close (X) button, and a layer panel row labeled "Layer 1" with a drag handle, expand arrow, thumbnail, and visibility eye icon.

How it works

Internal component spacing governs the space within components. It follows its own geometric scales, each designed to reconcile the type scale and component sizes as needed. This is why some values are less round than you might expect. They are calculated to produce balanced proportional relationships for their specific context at every size.

Diagram showing how "Base gap medium" spacing between a layer thumbnail and its label combines with an "Action group" of eye and lock icons to form a "List item" component, which uses "List gap medium" spacing between its elements.

Applying component spacing

Spectrum organizes components into common structural types called structural templates. Each template type has a corresponding set of semantic tokens that handle its internal spacing relationships.

When designing a component, start by identifying which structural type it most closely matches. That identification points you to the right token category. A component that behaves like a list uses list-level tokens. One that behaves like a container uses container-level tokens. One built around a single interactive element uses base-level tokens.

Components can also combine multiple structures. A list item, for example, is made up of base and group elements. Each structural type within the composition uses its own tokens.

Diagram showing component spacing application with base components on the left (Layer 1 with thumbnail and action icons) and how they're spaced in a list item on the right, with "Base gap medium" and "List gap medium" labels indicating spacing between elements.

Structural templates

Spectrum's spacing values are accessed through semantic tokens, which encode the purpose and context of each spacing decision directly into the system. Repeated patterns for how to use these tokens are implemented through structural templates. These are blueprints or recipes for how to design or build a component in a modular, flexible, and scalable way.

Working with tokens makes this seamless. A hardcoded 8px is just a number. The token base-gap-large gives you both a number and its context, relationships, size variants, and future system updates. Designers who skip tokens get the spacing that exists today, but they lose future enhancements to the system.

Diagram showing three UI structure types stacked vertically: a "Base" element with an icon, radio circle, label, and description text; an empty "Container" box; and a "List item" row combining a folder icon, label, and two radio circles.

Component density

Component density controls the internal spacing of a component, independent of its size tier. To make a component more compact, decrease each spacing token by one step. To make it more spacious, increase by one step. For example, if the regular variant uses spacing-200, compact uses spacing-100 and spacious uses spacing-300.

Three versions of a labeled radio button component, each annotated with three spacing measurements—gaps (1, pink), vertical paddings (2, green), and horizontal paddings (3, blue)—shown increasing in size from left to right, with corresponding scaling squares below each category.
Some tokens are labeled compact, regular, or spacious. These labels can serve two purposes. In some cases, they correspond directly to a component's density setting, such as a compact button group. In others, they represent a range of options within a specific spacing context, giving you the flexibility to choose what fits the composition and the visual characteristics of the elements involved.
Three "Table cell" examples labeled "Table item padding compact," "regular," and "spacious," each showing increasing vertical spacing around the cell text. Density named tokens corresponding to density options of a table component.
Diagram showing a dark toast notification reading "Toast message describing what happened." with a "Label" button and close icon, with its left and right edge padding labeled "Banner padding horizontal" and "Banner padding horizontal compact." Density named token options used to construct a toast component.

Not all components support density as a configurable option. Only collections and containers do.

Collections are components made of repeated child elements, such as lists, groups, and tables. Containers hold compositions of other components, such as cards and toolbars. Basic components such as buttons and text fields don't support density variants

Collections

For most collections, density affects only the gap between items. An action group, for example, adjusts the gap between its buttons; a list adjusts the gap between its items.

Two labeled radio button groupings compared side by side: "Compact" and "Regular," each showing a vertical pair and a horizontal pair of radio labels with a thin pink divider indicating the different spacing between them.

Containers

Density affects all padding, both vertical and horizontal. Containers such as cards may appear in full grids or unidirectional lists, so both axes need to respond to density changes.

Three versions of the same gradient card component (purple-to-red-to-pink with "Card title" and "Card description") labeled "Compact," "Regular," and "Spacious," showing progressively larger card sizes and spacing.

Tokens

Spectrum's internal component spacing is defined by a comprehensive set of semantic tokens. Each of these tokens corresponds to a specific structural context. These tokens are built into every Spectrum component, and available to designers in the S2 / Variables Figma library. A full token reference will be available on this site in the future.