From 8f646a63390726402261470db3ca7567d3778709 Mon Sep 17 00:00:00 2001 From: Ian Sanders Date: Wed, 17 Apr 2024 17:18:04 -0400 Subject: [PATCH] Add cheatsheet for migrating from `sx` prop (React) --- content/foundations/primitives/migrating.mdx | 234 ++++++++++++++++++- 1 file changed, 232 insertions(+), 2 deletions(-) diff --git a/content/foundations/primitives/migrating.mdx b/content/foundations/primitives/migrating.mdx index 8da84781b..0d275b1bb 100644 --- a/content/foundations/primitives/migrating.mdx +++ b/content/foundations/primitives/migrating.mdx @@ -1,10 +1,240 @@ --- title: Migrating to CSS variables description: - Support for migrating from SCSS varibles to CSS variables + Quick references for migrating from old Primer styling systems to new CSS variable primitives --- -## CSS variable replacements for SCSS variables +## Migrating from `sx` props (Primer React) + +### Spacing + +> [!CAUTION] +> If a the only available primitive is a `--base-size` primitive, this is likely not a good value for that spacing use case. For now you could use the plain pixel or `rem` value but ideally you'd adjust the design or styling approach. `--base-size` is primarily for dimensions. + +#### Stacks + +[Stacks](https://primer.style/foundations/primitives/size#stack) are boxes containing flow content; typically vertical. These are usually `display: flex` or `grid` or `block`. + +##### Internal padding + +Use these values for the internal `padding` (including `p`, `px`, `py`, `pr`, etc shorthands) around the edge of the stack. + +`sx` keyword | resolved value | primitive +--- | --- | --- +`0` | 0px | `0` +`1` | 4px | `--base-size-4` +`2` | 8px | `--stack-padding-condensed` +`3` | 16px | `--stack-padding-normal` +`4` | 24px | `--stack-padding-spacious` +`5` | 32px | `--base-size-32` +`6` | 40px | `--base-size-40` +`7` | 48px | `--base-size-48` +`8` | 64px | `--base-size-64` +`9` | 80px | `--base-size-80` +`10` | 96px | `--base-size-96` +`11` | 112px | `--base-size-112` +`12` | 128px | `--base-size-128` + +##### External margin + +> [!CAUTION] +> Prefer not using `margin` since it leaks space outside of components. Try to convert margins to container `padding` and/or flex layout `gap`. + +See padding values above; there are no `margin` primitives. + +##### Internal content spacing + +This is typically the CSS `gap` in `flex` (with `flex-direction: column`) or `grid` layouts. Could also be the `margin` between items that have not been updated to flexbox/grid. + +`sx` keyword | resolved value | primitive +--- | --- | --- +`0` | 0px | `0` +`1` | 4px | `--base-size-4` +`2` | 8px | `--stack-gap-condensed` +`3` | 16px | `--stack-gap-normal` +`4` | 24px | `--stack-gap-spacious` +`5` | 32px | `--base-size-32` +`6` | 40px | `--base-size-40` +`7` | 48px | `--base-size-48` +`8` | 64px | `--base-size-64` +`9` | 80px | `--base-size-80` +`10` | 96px | `--base-size-96` +`11` | 112px | `--base-size-112` +`12` | 128px | `--base-size-128` + +#### Control stacks + +[Control stacks](https://primer.style/foundations/primitives/size#controls) are horizontal (inline) rows containing inline items next to each other. For example, a set of buttons or labels. These are usually `display: flex` or `inline-flex` with `flex-direction: row`. + +> [!NOTE] +> The **size** of the control stack depends on the size of the controls inside of it. For example, a stack containing `` is a `small` stack. + +##### Padding / margin + +Use the same padding and margin values as for a vertical Stack. + +##### Internal content spacing + +The `gap` property in `flex` layouts, or item `margin` in older layouts. + +`sx` keyword | resolved value | primitive +--- | --- | --- +`0` | 0px | `0` +`1` | 4px | `--base-size-4` +`2` | 8px | `--controlStack-small-gap-condensed`
`--controlStack-medium-gap-condensed`
`--controlStack-large-gap-condensed` +`3` | 16px | `--controlStack-small-gap-spacious`
`--controlStack-medium-gap-spacious`
`--controlStack-large-gap-spacious` +`4` | 24px | `--base-size-24` +`5` | 32px | `--base-size-32` +`6` | 40px | `--base-size-40` +`7` | 48px | `--base-size-48` +`8` | 64px | `--base-size-64` +`9` | 80px | `--base-size-80` +`10` | 96px | `--base-size-96` +`11` | 112px | `--base-size-112` +`12` | 128px | `--base-size-128` + +#### Controls + +[Controls](https://primer.style/foundations/primitives/size#controls) are `Button`s, `Label`s, etc -- small building block elements. + +These 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 vs the sides. See [the primitives list](https://primer.style/foundations/primitives/size#controls) to find a good value or just use `--base-size` values for now. + +### Colors + +#### Canvas + +`sx` keyword | primitive +--- | --- +`canvas.default` | `--bgColor-default` +`canvas.overlay` | `--overlay-bgColor` +`canvas.inset` | `--bgColor-inset` +`canvas.subtle` | `--bgColor-muted` + +#### Foreground + +`sx` keyword | primitive +--- | --- +`fg.default` | `--fgColor-default` +`fg.muted` | `--fgColor-muted` +`fg.subtle` | eliminated, use `--fgColor-muted` instead +`fg.onEmphasis` | `--fgColor-onEmphasis` + +#### Border + +`sx` keyword | primitive +--- | --- +`border.default` | `--borderColor-default` +`border.muted` | `--borderColor-muted` +`border.subtle` | eliminated, use `--borderColor-muted` instead + +#### Accent + +`sx` keyword | primitive +--- | --- +`accent.fg` | `--fgColor-accent` +`accent.emphasis` | `--bgColor-accent-emphasis` +`accent.muted` | `--borderColor-accent-muted` +`accent.subtle` | `--bgColor-accent-muted` + +#### Success, Attention, Severe, Danger, Open, Closed, Done, Sponsors + +`sx` keyword | primitive +--- | --- +`{name}.fg` | `--fgColor-{name}` +`{name}.emphasis` | `--bgColor-{name}-emphasis` +`{name}.muted` | `--borderColor-{name}-muted` +`{name}.subtle` | `--bgColor-{name}-muted` + +### Fonts + +#### Font size + +Try to use the one that applies to the type of text you are styling: + +##### Titles + +`Heading` or similar components. + +`sx` keyword | resolved value | primitive +--- | --- | --- +`0` | 12px | `--base-size-12` +`1` | 14px | `--base-size-14` +`2` | 16px | `--text-title-size-small` +`3` | 20px | `--text-title-size-medium` +`4` | 24px | `--base-size-24` +`5` | 32px | `--text-title-size-large` +`6` | 40px | `--base-size-40` +`7` | 48px | `--base-size-48` +`8` | 56px | `--base-size-56` + +##### Body text + +`sx` keyword | resolved value | primitive +--- | --- | --- +`0` | 12px | `--text-body-size-small` +`1` | 14px | `--text-body-size-medium` +`2` | 16px | `--text-body-size-large` +`3` | 20px | `--base-size-20` +`4` | 24px | `--base-size-24` +`5` | 32px | `--base-size-32` +`6` | 40px | `--base-size-40` +`7` | 48px | `--base-size-48` +`8` | 56px | `--base-size-56` + +#### Font family + +`sx` keyword | primitive +--- | --- +`normal` | `--fontStack-system` or explicitly `--fontStack-sansSerif` +`mono` | `--fontStack-monospace` + +### Border + +### Border color + +See: Colors > Border + +### Border width + +Prefer these primitives instead of previously used numbers or plain pixel values: + +`sx` keyword | resolved value | primitive +--- | --- | --- +`0` | 0px | `0` +`1` | 1px | `--borderWidth-thin` +| | 2px | `--borderWidth-thick` +| | 3px | `--borderWidth-thicker` + +### Border radius + +`sx` keyword | resolved value | primitive +--- | --- | --- +`0` | 0px | `0` +`1` | 3px | `--borderRadius-small` +`2` | 6px | `--borderRadius-medium` +| | 12px | `--borderRadius-large` +`3` | a lot | `--borderRadius-full` + +### Sizes and Breakpoints + +These are typically used for breakpoints, heights and widths. + +> [!NOTE] +> For overlays (like dialogs), prefer the [new overlay primitives](https://primer.style/foundations/primitives/size#overlay). These sizes are not a 1:1 mapping with the old keywords. + +> [!NOTE] +> CSS variables cannot be used in `@media` or `@container` query expressions. The plain pixel value must be used instead. + +`sx` breakpoint keyword | `sx` size keyword | resolved value | primitive +--- | --- | --- | --- + | | | 320px | `--breakpoint-xsmall` +`0` | `size.small` | 544px | `--breakpoint-small` +`1` | `size.medium` | 768px | `--breakpoint-medium` +`2` | `size.large` | 1012px | `--breakpoint-large` +`3` | `size.xlarge` | 1280px | `--breakpoint-xlarge` + | | | 1400px | `--breakpoint-xxlarge` + +## Migrating from SCSS Variables Most legacy SCSS variables from Primer CSS have new CSS variable replacements.