Stack padding migration from sx to CSS variables
Stack padding values map from sx keywords to CSS variables and pixel values. The mapping is: sx 0 = 0px (primitive: 0), sx 1 = 4px (primitive: --base-size-4), sx 2 = 8px (primitive: --base-size-8), sx 3 = 16px (primitive: --base-size-16), sx 4 = 24px (primitive: --base-size-24), sx 5 = 32px (primitive: --base-size-32), sx 6 = 40px (primitive: --base-size-40), sx 7 = 48px (primitive: --base-size-48), sx 8 = 64px (primitive: --base-size-64), sx 9 = 80px (primitive: --base-size-80), sx 10 = 96px (primitive: --base-size-96), sx 11 = 112px (primitive: --base-size-112), sx 12 = 128px (primitive: --base-size-128).
Stack content spacing (gap) migration from sx to CSS variables
Stack content spacing for flex or grid gap maps from sx keywords to CSS variables and pixel values. The mapping is: sx 0 = 0px (primitive: 0), sx 1 = 4px (primitive: --base-size-4), sx 2 = 8px (primitive: --stack-gap-condensed), sx 3 = 16px (primitive: --stack-gap-normal), sx 4 = 24px (primitive: --stack-gap-spacious), sx 5 = 32px (primitive: --base-size-32), sx 6 = 40px (primitive: --base-size-40), sx 7 = 48px (primitive: --base-size-48), sx 8 = 64px (primitive: --base-size-64), sx 9 = 80px (primitive: --base-size-80), sx 10 = 96px (primitive: --base-size-96), sx 11 = 112px (primitive: --base-size-112), sx 12 = 128px (primitive: --base-size-128).
Control stack content spacing migration from sx to CSS variables
Control stack content spacing (gap) maps from sx keywords to CSS variables and pixel values. The mapping is: sx 0 = 0px (primitive: 0), sx 1 = 4px (primitive: --base-size-4), sx 2 = 8px (primitives: --controlStack-small-gap-condensed, --controlStack-medium-gap-condensed, --controlStack-large-gap-condensed), sx 3 = 16px (primitives: --controlStack-small-gap-spacious, --controlStack-medium-gap-spacious, --controlStack-large-gap-spacious), sx 4 = 24px (primitive: --base-size-24), sx 5 = 32px (primitive: --base-size-32), sx 6 = 40px (primitive: --base-size-40), sx 7 = 48px (primitive: --base-size-48), sx 8 = 64px (primitive: --base-size-64), sx 9 = 80px (primitive: --base-size-80), sx 10 = 96px (primitive: --base-size-96), sx 11 = 112px (primitive: --base-size-112), sx 12 = 128px (primitive: --base-size-128).
Breakpoint and size migration from sx to CSS variables
Breakpoints and size keywords map from sx to CSS variables and pixel values: sx 0 (size.small) = 544px (primitive: --breakpoint-small), sx 1 (size.medium) = 768px (primitive: --breakpoint-medium), sx 2 (size.large) = 1012px (primitive: --breakpoint-large), sx 3 (size.xlarge) = 1280px (primitive: --breakpoint-xlarge). Additional breakpoints: 320px (primitive: --breakpoint-xsmall), 1400px (primitive: --breakpoint-xxlarge).
SCSS variable to CSS variable migration - spacing scale
Legacy SCSS spacing variables map to CSS variables: $spacer to --base-size-8, $spacer-0 to 0 (deprecated), $spacer-1 to --base-size-4, $spacer-2 to --base-size-8, $spacer-3 to --base-size-16, $spacer-4 to --base-size-24, $spacer-5 to --base-size-32, $spacer-6 to --base-size-40, $spacer-7 to --base-size-48, $spacer-8 to --base-size-64, $spacer-9 to --base-size-80, $spacer-10 to --base-size-96, $spacer-11 to --base-size-112, $spacer-12 to --base-size-128.
SCSS variable to CSS variable migration - deprecated em-based spacing
Legacy SCSS em-based spacing variables are deprecated: $em-spacer-1 to 0.0625em (deprecated), $em-spacer-2 to 0.125em (deprecated), $em-spacer-3 to 0.25em (deprecated), $em-spacer-4 to 0.375em (deprecated), $em-spacer-5 to 0.5em (deprecated), $em-spacer-6 to 0.75em (deprecated).
SCSS variable to CSS variable migration - size scale
Legacy SCSS size variables map to CSS variables: $size to --base-size-16, $size-0 to 0 (deprecated), $size-1 to --base-size-16, $size-2 to --base-size-20, $size-3 to --base-size-24, $size-4 to --base-size-28, $size-5 to --base-size-32, $size-6 to --base-size-40, $size-7 to --base-size-48, $size-8 to --base-size-64.
SCSS variable to CSS variable migration - breakpoints and viewport
Legacy SCSS breakpoint and viewport variables map to CSS variables: $width-sm to --breakpoint-small, $width-md to --breakpoint-medium, $width-lg to --breakpoint-large, $width-xl to --breakpoint-xlarge, $container-sm to --breakpoint-small, $container-md to --breakpoint-medium, $container-lg to --breakpoint-large, $container-xl to --breakpoint-xlarge, $viewport-narrow to --viewportRange-narrow, $viewport-regular to --viewportRange-regular, $viewport-wide to --viewportRange-wide.
CSS variables cannot be used in media queries
CSS variables cannot be used in @media or @container query expressions. The plain pixel value must be used instead in media queries.
Margin usage recommendation
Prefer not using margin since it leaks space outside of components. Try to convert margins to container padding and/or flex layout gap.
Control stack size dependency
The size of the control stack depends on the size of the controls inside of it. For example, a stack containing a small icon button is a small stack.
Control values require case-by-case resolution
Control padding and margin values must be resolved on a case-by-case basis because they are different for each size of control, each density level, and for the top/bottom versus the sides.
Desktop spacing grid is 10 pixels
GitHub Desktop uses a 10 pixel grid for spacing, which differs from the 8px grid used by Primer.
Mobile grid layout conformance
Mobile apps conform to an 8-point grid layout. When designing custom components, elements should be spaced and aligned to an 8-point grid, with half-steps of 4pts included. The apps defer many component sizes, spacings, and layouts to the platform (iOS and Android) to handle cross-device responsiveness, tablet transformations, and OS accessibility settings.