chore: add migration guide for styled-components@6

Author: joshuaellis

docs/components/Typography.tsx

@@ -1,31 +1,41 @@
-import { Typography, TypographyProps } from '@strapi/design-system';
+import { Typography, TypographyComponent, TypographyProps } from '@strapi/design-system';
 import { styled, css } from 'styled-components';
 
 const H1 = (props: TypographyProps) => (
-  <Typography tag="h1" variant="alpha" textColor="neutral800" marginBottom="0.5em" {...props} />
+  <Typography {...props} tag="h1" variant="alpha" textColor="neutral800" marginBottom="0.5em" />
 );
 
 const H2 = (props: TypographyProps) => (
-  <Typography tag="h2" variant="beta" textColor="neutral800" marginBottom="1em" marginTop="2em" {...props} />
+  <Typography {...props} tag="h2" variant="beta" textColor="neutral800" marginBottom="1em" marginTop="2em" />
 );
 
 const H3 = (props: TypographyProps) => (
-  <Typography tag="h3" variant="delta" textColor="neutral800" marginBottom="1em" marginTop="1.4em" {...props} />
+  <Typography
+    {...props}
+    tag="h3"
+    variant="delta"
+    textColor="neutral800"
+    marginBottom="1em"
+    marginTop="1.4em"
+    fontSize={4}
+  />
 );
 
 const H4 = (props: TypographyProps) => (
   <Typography
+    {...props}
     tag="h4"
     variant="epsilon"
     textColor="neutral800"
     marginBottom="1em"
     marginTop="1.4em"
-    fontWeight="bold"
-    {...props}
+    fontWeight="semiBold"
   />
 );
 
-const P = (props: TypographyProps) => <Paragraph tag="p" variant="epsilon" textColor="neutral700" {...props} />;
+const P = (props: TypographyProps) => (
+  <Paragraph {...props} tag="p" variant="epsilon" textColor="neutral700" fontSize={2} />
+);
 
 const codeStyles = css`
   color: ${({ theme }) => theme.colors.neutral700};
@@ -34,7 +44,7 @@ const codeStyles = css`
   padding: 0.6rem;
 `;
 
-const Paragraph = styled(Typography)`
+const Paragraph = styled<TypographyComponent<'p'>>(Typography)`
   & code {
     ${codeStyles}
   }

docs/stories/components/Accordion.mdx renamed to docs/stories/Accordion.mdx

@@ -6,6 +6,23 @@ import { Meta } from '@storybook/blocks';
 
 ## Design System
 
+### Peer dependency updates
+
+The design-system & icons peer-deps have been updated, we removed `react-router-dom` and updated `styled-components`.
+
+```diff
+// package.json
+{
+  peerDependencies: {
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0",
+-   "react-router-dom": "^5.2.0",
+-   "styled-components": "^5.3.0",
++   "styled-components": "^6.0.0"
+  }
+}
+```
+
 ### Remove direct imports
 
 Users can no longer `import { Combobox } from '@strapi/design-system/Combobox'`, instead they should import _all_ things
@@ -92,7 +109,29 @@ return (
 + import { Toggle } from '@strapi/design-system'
 ```
 
-### Box, Flex & Typography are now all react components
+### Upgraded styled-components to V6
+
+#### `as` is no longer a prop, use `tag` instead
+
+A common issue we faced in Strapi was the behaviour of the `as` prop in conjunction with how we built our design-system
+– everything is based off `Box`. This meant that when we used `as` on a styled component it would not be passed down to
+the `Box` component. This is because `as` is a prop that styled-components uses to change the underlying element to the
+closest `styled` component, but we were using it to change the `tag` prop of `Box`.
+
+We've now introduced the `tag` prop which behaves as we expect.
+
+```diff
+import { Link } from 'react-router-dom'
+
+const MyLink = () => {
+  // the below prop would throw a TS error
+- return <BaseLink as={NavLink} to="/home">
+  // It now, should not.
++ return <BaseLink tag={NavLink} to="/home">
+}
+```
+
+#### Box, Flex, Grid & Typography are now all react components
 
 These components are no longer styled-components. This means that users can not directly reference them in other styled
 components:
@@ -112,6 +151,24 @@ components:
 + `;
 ```
 
+Because they are now polymoprhic react components that are correctly typed i.e. it will infer the props of the `tag` the
+type signature of the component uses generics, `styled-components` has an issue surrounding the poor auto-inference of
+this. We therefore recommend you type your `styled` functions where you use them:
+
+```tsx
+import { Box, BoxComponent } from '@strapi/design-system';
+
+const MyBox = styled<BoxComponent<'article'>>(Box)`
+  background-color: red;
+`;
+
+const MyComponent = () => {
+  return <MyBox tag="article">Hello</MyBox>;
+};
+```
+
+If you don't do this, the props for `MyBox` are all inferred as `Record<string, any>`, which is incorrect.
+
 ---
 
 ## Icons

docs/stories/components/Accordion.stories.tsx renamed to docs/stories/Accordion.stories.tsx

@@ -3,141 +3,76 @@
  */
 import * as React from 'react';
 
-import { ThemeProvider as StyledThemeProvider, createGlobalStyle, DefaultTheme } from 'styled-components';
+import { ThemeProvider as StyledThemeProvider, createGlobalStyle, DefaultTheme, css } from 'styled-components';
 
 import { LiveRegions } from '../LiveRegions/LiveRegions';
 import { lightTheme } from '../themes';
 
 const GlobalStyle = createGlobalStyle`
- /* http://meyerweb.com/eric/tools/css/reset/ 
-   v2.0 | 20110126
-   License: none (public domain)
-*/
-  html,
-  body,
-  div,
-  span,
-  applet,
-  object,
-  iframe,
+${css`
+  *,
+  *::before,
+  *::after {
+    box-sizing: border-box;
+  }
+
+  * {
+    margin: 0;
+  }
+
+  html {
+    /* Sets 1rem === 10px */
+    font-size: 62.5%;
+  }
+
+  body {
+    height: 100%;
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, 'Open Sans',
+      'Helvetica Neue', sans-serif;
+    line-height: 1.5;
+    -webkit-font-smoothing: antialiased;
+  }
+
+  img,
+  picture,
+  video,
+  canvas,
+  svg {
+    display: block;
+    max-width: 100%;
+  }
+
+  input,
+  button,
+  textarea,
+  select {
+    font: inherit;
+  }
+
+  p,
   h1,
   h2,
   h3,
   h4,
   h5,
-  h6,
-  p,
-  blockquote,
-  pre,
-  a,
-  abbr,
-  acronym,
-  address,
-  big,
-  cite,
-  code,
-  del,
-  dfn,
-  em,
-  img,
-  ins,
-  kbd,
-  q,
-  s,
-  samp,
-  small,
-  strike,
-  strong,
-  sub,
-  sup,
-  tt,
-  var,
-  b,
-  u,
-  i,
-  center,
-  dl,
-  dt,
-  dd,
-  ol,
-  ul,
-  li,
-  fieldset,
-  form,
-  label,
-  legend,
-  table,
-  caption,
-  tbody,
-  tfoot,
-  thead,
-  tr,
-  th,
-  td,
-  article,
-  aside,
-  canvas,
-  details,
-  embed,
-  figure,
-  figcaption,
-  footer,
-  header,
-  hgroup,
-  menu,
-  nav,
-  output,
-  ruby,
-  section,
-  summary,
-  time,
-  mark,
-  audio,
-  video {
-    margin: 0;
-    padding: 0;
-    border: 0;
-    vertical-align: baseline;
+  h6 {
+    overflow-wrap: break-word;
+    font: unset;
   }
-  /* HTML5 display-role reset for older browsers */
-  article,
-  aside,
-  details,
-  figcaption,
-  figure,
-  footer,
-  header,
-  hgroup,
-  menu,
-  nav,
-  section {
-    display: block;
+
+  #root {
+    isolation: isolate;
   }
+
   ol,
   ul {
     list-style: none;
   }
-  blockquote,
-  q {
-    quotes: none;
-  }
-  blockquote:before,
-  blockquote:after,
-  q:before,
-  q:after {
-    content: "";
-    content: none;
-  }
+
   table {
     border-collapse: collapse;
     border-spacing: 0;
   }
-  /* My styles */
-  *,
-  *:before,
-  *:after {
-    box-sizing: border-box;
-  }
 
   *:focus-visible {
     outline: 2px solid ${({ theme }) => theme.colors.primary600};
@@ -149,35 +84,11 @@ const GlobalStyle = createGlobalStyle`
     outline: none;
   }
 
-  html {
-    /* Sets 1rem === 10px */
-    font-size: 62.5%;
-  }
-
-  body,html{
-    height: 100%;
-    line-height: 1;
-    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, 'Open Sans', 'Helvetica Neue', sans-serif;
-  }
-
-  button {
-    margin: 0;
-    padding: 0;
-    border: none;
-    background: none;
-    color: inherit;
-    cursor: pointer;
-    font: inherit;
-  }
-
-  textarea,input {
-    font: inherit;
-  }
-
   .lock-body-scroll {
     height: 100vh;
     overflow-y: hidden;
   }
+`}
 `;
 
 export interface ThemeProviderProps {