Astro Design System Starter
Token-first UI foundationDocs
Field 2

Sizing

Primitive tokens (size scale)

Primitive size tokens encode pixel-equivalent values as rem variables. They are the source scale for semantic sizing tokens and dimension decisions such as width, height, min-width, max-width, min-height and max-height.

Primitive size tokens

The fixed reference scale used to build semantic tokens and width/height decisions across the system.

Sample
Token
Value (REM)
Value (PX)
--size-0
0
0px
--size-1
0.0625rem
1px
--size-2
0.125rem
2px
--size-4
0.25rem
4px
--size-6
0.375rem
6px
--size-8
0.5rem
8px
--size-12
0.75rem
12px
--size-16
1rem
16px
--size-18
1.125rem
18px
--size-20
1.25rem
20px
--size-24
1.5rem
24px
--size-32
2rem
32px
--size-40
2.5rem
40px
--size-48
3rem
48px
--size-56
3.5rem
56px
--size-64
4rem
64px
--size-72
4.5rem
72px
--size-80
5rem
80px
--size-96
6rem
96px
--size-112
7rem
112px
--size-128
8rem
128px
--size-160
10rem
160px
--size-192
12rem
192px
--size-256
16rem
256px
--size-320
20rem
320px

Semantic tokens

Semantic sizing tokens translate primitive values into intent. Each group separates global size-based tokens from component-based contracts when a repeated use case needs a stable name.

Component padding

Inner spacing inside cards, panels, controls and composed components. Padding tokens describe space inside an element, not distance between children or external margins.

Sample
Token
Value (REM)
Value (PX)
--component-padding-noneAgentic RuleUse when a component surface must remove internal padding completely.
0
0px
--component-padding-tinyAgentic RuleUse for very compact internal padding in tiny UI parts such as small labels or metadata controls.
0.25rem
4px
--component-padding-xsmallAgentic RuleUse for compact internal padding when tiny is too tight but the component should still feel dense.
0.5rem
8px
--component-padding-smallAgentic RuleUse for small component interiors such as compact cards, table cells or secondary controls.
0.75rem
12px
--component-padding-mediumAgentic RuleUse as the default inner padding for reusable cards, panels and composed UI blocks.
clamp(1rem, 0.8571rem + 0.7143vw, 1.5rem)
16-24px
--component-padding-largeAgentic RuleUse for prominent component surfaces that need more internal breathing room.
clamp(1.5rem, 1.2143rem + 1.4286vw, 2.5rem)
24-40px
--component-padding-xlargeAgentic RuleUse for large editorial or dashboard surfaces where the component itself defines a major content zone.
clamp(2rem, 1.4286rem + 2.8571vw, 3.5rem)
32-56px

Section padding

Vertical padding inside page sections and major content zones. These tokens define section rhythm without acting as child gaps or component margins.

Sample
Token
Value (REM)
Value (PX)
--section-padding-small
clamp(2rem, 1.7143rem + 1.4286vw, 3rem)
32-48px
--section-padding-medium
clamp(3rem, 2.1429rem + 4.2857vw, 6rem)
48-96px
--section-padding-large
clamp(4rem, 3.1429rem + 3.5714vw, 7rem)
64-112px
--section-padding-hero-top
clamp(4.5rem, 2.9286rem + 7.8571vw, 10rem)
72-160px

Gap

Gap tokens define distance between children on a flex, grid or inline parent. Global gaps describe size only; component-based gaps cover repeated groups such as buttons, tags and form fields.

Global

Use global gap tokens when the spacing decision is only about size and is not dedicated to one component or use case.

Sample
Token
Value (REM)
Value (PX)
--gap-none
0
0px
--gap-tiny
0.25rem
4px
--gap-small
0.5rem
8px
--gap-regular
0.75rem
12px
--gap-medium
1rem
16px
--gap-large
clamp(1.5rem, 1.3571rem + 0.7143vw, 2rem)
24-32px
--gap-xlarge
3rem
48px
--gap-huge
5rem
80px
Component-based

Use component-based gap tokens for repeated parent-child group patterns that need one shared contract across the system.

Sample
Token
Value (REM)
Value (PX)
--gap-button-groupAgentic RuleUse on a flex or grid parent that groups multiple buttons or actions.
var(--gap-regular)
12px
--gap-tag-groupAgentic RuleUse on a wrapping parent that displays a set of tags, chips or compact labels.
var(--gap-small)
8px
--gap-form-groupAgentic RuleUse on a form or fieldset parent to separate stacked form fields.
var(--gap-medium)
16px
--gap-input-groupAgentic RuleUse on a parent that groups related inputs or an input with an attached control.
var(--gap-regular)
12px

Space

Space tokens define margin and block flow between elements. Global spaces describe reusable margin sizes; component-based spaces cover critical repeated relationships such as eyebrow-to-heading or section-header-to-content.

Global

Use global space tokens for margins and vertical flow when the spacing decision is only about size.

Sample
Token
Value (REM)
Value (PX)
--space-none
0
0px
--space-tiny
0.25rem
4px
--space-small
0.5rem
8px
--space-regular
0.75rem
12px
--space-medium
1.5rem
24px
--space-large
2rem
32px
--space-xlarge
3rem
48px
--space-huge
4.5rem
72px
Component-based

Use component-based space tokens for repeated margin relationships that need exact shared control.

Sample
Token
Value (REM)
Value (PX)
--space-eyebrow-bottomAgentic RuleUse as margin-bottom on an eyebrow when it sits above a heading.
var(--space-medium)
24px
--space-heading-contentAgentic RuleUse as margin-top or margin-bottom between a heading and its supporting content.
var(--space-regular)
12px
--space-section-header-bottomAgentic RuleUse as margin-bottom after a section header before the section content starts.
var(--space-xlarge)
48px
--space-media-contentAgentic RuleUse as margin between a media element and the text or controls that describe it.
var(--space-medium)
24px

Radius

Radius tokens describe surface shape. Global radius tokens describe generic corner sizes; component-based radius tokens lock repeated UI surfaces to one shared shape contract.

Global

Use global radius tokens when the decision is only about corner size and is not dedicated to one component.

Sample
Token
Value (REM)
Value (PX)
--radius-none
0
0px
--radius-sharp
0
0px
--radius-small
0.25rem
4px
--radius-medium
0.5rem
8px
--radius-large
1rem
16px
--radius-xlarge
1.5rem
24px
--radius-xxlarge
2rem
32px
--radius-full
999rem
full
Component-based

Use component-based radius tokens for repeated component surfaces that need one shared shape rule.

Sample
Token
Value (REM)
Value (PX)
--radius-buttonAgentic RuleUse for button surfaces so all button variants share one corner contract.
var(--radius-none)
0px
--radius-inputAgentic RuleUse for text inputs, textareas and form controls that accept user input.
var(--radius-small)
4px
--radius-tabAgentic RuleUse for tab-like controls that switch views or states inside one interface area.
var(--radius-small)
4px
--radius-tagAgentic RuleUse for tags, chips and compact classification labels.
var(--radius-none)
0px
--radius-labelAgentic RuleUse for standalone label surfaces when a label needs a visible container.
var(--radius-none)
0px

Border

Border-width tokens describe stroke thickness. Use default for standard dividers and strong only for deliberate emphasis or focus treatments.

Sample
Token
Value (REM)
Value (PX)
--border-width-default
0.0625rem
1px
--border-width-strong
0.125rem
2px

Size Attributes

Size attributes are the component sizing API. They connect semantic variables to repeatable component geometry through stable attributes such as data-component-size.

Component size attributes

Buttons, tags, inputs, tabs and labels should use the same size profiles where possible. The attribute maps profile tokens onto internal aliases such as --component-padding-inline, while this table documents the public attribute, source token and final values.

Attribute
Property
Token
Value (REM)
Value (PX)
data-component-size="tiny"
min-height
--component-size-tiny-min-height
1.5rem
24px
padding-inline
--component-size-tiny-padding-inline
0.5rem
8px
padding-block
--component-size-tiny-padding-block
0.25rem
4px
icon-size
--component-size-tiny-icon-size
0.75rem
12px
gap
--component-size-tiny-gap
0.25rem
4px
font-size
--component-size-tiny-font-size
0.75rem
12px
line-height
--component-size-tiny-line-height
1
unitless
data-component-size="small"
min-height
--component-size-small-min-height
2.5rem
40px
padding-inline
--component-size-small-padding-inline
0.75rem
12px
padding-block
--component-size-small-padding-block
0.5rem
8px
icon-size
--component-size-small-icon-size
1rem
16px
gap
--component-size-small-gap
0.375rem
6px
font-size
--component-size-small-font-size
1rem
16px
line-height
--component-size-small-line-height
1
unitless
data-component-size="medium"
min-height
--component-size-medium-min-height
3rem
48px
padding-inline
--component-size-medium-padding-inline
1.25rem
20px
padding-block
--component-size-medium-padding-block
0.75rem
12px
icon-size
--component-size-medium-icon-size
1.25rem
20px
gap
--component-size-medium-gap
0.5rem
8px
font-size
--component-size-medium-font-size
1rem
16px
line-height
--component-size-medium-line-height
1
unitless
data-component-size="large"
min-height
--component-size-large-min-height
4rem
64px
padding-inline
--component-size-large-padding-inline
1.5rem
24px
padding-block
--component-size-large-padding-block
1.5rem
24px
icon-size
--component-size-large-icon-size
1.125rem
18px
gap
--component-size-large-gap
0.75rem
12px
font-size
--component-size-large-font-size
1.125rem
18px
line-height
--component-size-large-line-height
1
unitless

Agentic Rules

Rules for future agents and contributors working with sizing tokens, styles and documentation.

Agentic sizing rules

Default decision order for choosing or changing size values.

Agentic Rule

Start from intent

Choose sizing values in this order: component attribute, component-based semantic token, global semantic token, primitive token. Do not start from raw pixels in component CSS.

Agentic Rule

Keep primitives fixed

Primitive size tokens are the fixed rem scale. Use them to define the system, not as the default API for components or page layouts.

Agentic Rule

Separate global and component-based semantics

Use global semantic tokens when the name describes size only. Create component-based tokens only for repeated use cases that need one shared contract.

Agentic Rule

Respect spacing roles

Use padding for internal space, gap for distance between children, and space tokens for margins or vertical relationships between separate elements.

Agentic Rule

Expose repeatable component sizes through attributes

Buttons, tags, inputs, tabs and labels should use data-component-size profiles before adding one-off sizing classes or local component overrides.

Agentic Rule

Use radius contracts

Use component-based radius tokens for repeated surfaces such as buttons, inputs, tabs, tags and labels. Use global radius tokens only when the surface is not component-specific.

Agentic Rule

Document non-obvious component-based tokens

Every component-based sizing token with a specific use case should include an Agentic Rule tooltip or matching Agentic Rule card so future agents know when to use it.

Agentic Rule

Use documentation components

Sizing documentation tables should use the shared Design System table atoms and spacing blocks. Do not create local table layouts for new sizing sections.

Agentic Rule

Patch globally first

When a size rule affects multiple pages or components, update the token or master documentation component before adding local page CSS.