Add cheatsheet for migrating sx React styling to CSS Variables (#759)

* Add cheatsheet for migrating from `sx` prop (React) * Update PRC theme reference * Fix headings * Fix caution note syntax Co-authored-by: Katie Langerman <18661030+langermank@users.noreply.github.com> * Delete `base-size` warning note Co-authored-by: Katie Langerman <18661030+langermank@users.noreply.github.com> * Add "interactive" Co-authored-by: Katie Langerman <18661030+langermank@users.noreply.github.com> * Add internal link to border colors section Co-authored-by: Katie Langerman <18661030+langermank@users.noreply.github.com> * Update content/foundations/primitives/migrating.mdx * Update content/foundations/primitives/migrating.mdx --------- Co-authored-by: Katie Langerman <18661030+langermank@users.noreply.github.com>
primer · Apr 18, 2024 · a155379 · a155379
1 parent 927b806
commit a155379
Show file tree

Hide file tree

Showing 2 changed files with 235 additions and 3 deletions.
diff --git a/content/foundations/primitives/migrating.mdx b/content/foundations/primitives/migrating.mdx
@@ -1,10 +1,242 @@
 ---
 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
+
+
+#### Stacks
+
+[Stacks](https://primer.style/foundations/primitives/size#stack) are boxes containing flow content in a vertical or horizontal layout. These are usually `display: flex` or `grid` or `block`.
+
+##### Stack 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`
+
+##### Stack margin
+
+<Note variant="warning">
+ Prefer not using `margin` since it leaks space outside of components. Try to convert margins to container `padding` and/or flex layout `gap`.
+</Note>
+
+See padding values above; there are no `margin` primitives.
+
+##### Stack 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 interactive 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 variant="info">
+ The size of the control stack depends on the size of the controls inside of it. For example, a stack containing a <code>small</code> icon button is a 'small' stack.
+</Note>
+
+##### Control stack padding / margin
+
+Use the same padding and margin values as for a vertical Stack.
+
+##### Control stack 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` <br /> `--controlStack-medium-gap-condensed` <br /> `--controlStack-large-gap-condensed`
+`3` | 16px | `--controlStack-small-gap-spacious` <br /> `--controlStack-medium-gap-spacious` <br /> `--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`
+
+### Borders
+
+#### Border color
+
+See: [Border 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 variant="info">
+ 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>
+
+<Note variant="info">
+  CSS variables cannot be used in `@media` or `@container` query expressions. The plain pixel value must be used instead. Stay tuned for future media query support.
+</Note>
+
+`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.
 

diff --git a/content/guides/react/theme-reference.mdx b/content/guides/react/theme-reference.mdx
@@ -6,7 +6,7 @@ description: The default theme object for Primer React components
 import {theme} from '@primer/react'
 import ThemeReferenceTree from '~/src/components/theme-reference-tree'
 
-Colors in this theme object reference CSS variables from Primer Primitives under the hood with a raw value as a fallback. We recommend referencing CSS variables directly, which you can reference from the [Primitive colors docs](../../foundations/primitives/color).
+Colors in this theme object reference CSS variables from Primer Primitives under the hood with a raw value as a fallback. We recommend [using CSS variables directly](primer/design/content/foundations/primitives/migrating.mdx) instead.
 
 <ThemeReferenceTree themeData={theme} />