Add cheatsheet for migrating from sx prop (React)

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 `<IconButton size="small">` 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` <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`
+
+### 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.