Improve migration documentation for version 16

apps/website/pages/migration/16/component-updates.tsx

@@ -1,5 +1,5 @@
 import Head from "next/head";
-import Components16MigrationPage from "screens/migration/Components16MigrationPage";
+import Components16MigrationPage from "screens/migration/components/Components16MigrationPage";
 
 const Components16Migration = () => (
   <>

apps/website/screens/migration/TokensMigrationPage.tsx

@@ -66,6 +66,7 @@ const sections = [
           <li>Migrating color, spacing, and typography overrides to CSS tokens.</li>
           <li>Replacing any custom component overrides that referenced theme object values.</li>
           <li>Updating global styles to rely on CSS variables instead of hardcoded values.</li>
+          <li>Refactoring prop values to rely on alias tokens instead of hardcoded values.</li>
         </ul>
       </>
     ),
@@ -153,7 +154,8 @@ return (
             <DxcParagraph>
               This can be applied to colors, fonts, spacings and borders. However, keep in mind that, for now, only core
               tokens can be overwritten and they affect all the components which are wrapped within the{" "}
-              <Code>HalstackProvider</Code>.
+              <Code>HalstackProvider</Code>. Note that the former <Code>theme</Code> prop has been renamed to{" "}
+              <Code>opinionatedTheme</Code>.
             </DxcParagraph>
           </>
         ),

apps/website/screens/migration/Components16MigrationPage.tsx → apps/website/screens/migration/components/Components16MigrationPage.tsx

@@ -4,6 +4,24 @@ import DocFooter from "@/common/DocFooter";
 import PageHeading from "@/common/PageHeading";
 import Code, { ExtendedTableCode } from "@/common/Code";
 import Link from "next/link";
+import Example from "@/common/example/Example";
+import previousExample from "./examples/previous";
+import newExample from "./examples/new";
+
+const groupItemType = `{
+  badge?: ReactElement;
+  icon?: string | SVG;
+  label: string;
+  items: (Item)[];
+}`;
+
+const itemType = `{
+  badge?: ReactElement;
+  icon?: string | SVG;
+  label: string;
+  onSelect?: () => void;
+  selected?: boolean;
+}`;
 
 const sections = [
   {
@@ -16,6 +34,27 @@ const sections = [
       </DxcParagraph>
     ),
   },
+  {
+    title: "Usage of components",
+    content: (
+      <>
+        <DxcParagraph>
+          In our component props, instead of passing hardcoded values such as <Code>2rem</Code>, we should always use an
+          alias token whenever possible. Only if no suitable alias token exists, a core token or a hardcoded value may
+          be used.
+        </DxcParagraph>
+        <DxcParagraph>Previous version:</DxcParagraph>
+        <Example example={previousExample} defaultIsVisible />
+        <Example example={newExample} defaultIsVisible />
+        <DxcParagraph>
+          For more information about tokens refer to{" "}
+          <Link href="/foundations/tokens/overview" passHref legacyBehavior>
+            <DxcLink>its documentation</DxcLink>
+          </Link>
+        </DxcParagraph>
+      </>
+    ),
+  },
   {
     title: "Added components",
     content: (
@@ -155,22 +194,11 @@ const sections = [
                           The <Code>navItems</Code> prop accepts an array of <Code>Item</Code> and
                           <Code>GroupItem</Code> objects. Each <Code>GroupItem</Code> has the following structure:
                         </p>
-                        <ExtendedTableCode>{`{
-  badge?: ReactElement;
-  icon?: string | SVG;
-  label: string;
-  items: (Item)[];
-}`}</ExtendedTableCode>
+                        <ExtendedTableCode>{groupItemType}</ExtendedTableCode>
                         <p>
                           Each <Code>Item</Code> has the following structure:
                         </p>
-                        <ExtendedTableCode>{`{
-  badge?: ReactElement;
-  icon?: string | SVG;
-  label: string;
-  onSelect?: () => void;
-  selected?: boolean;
-}`}</ExtendedTableCode>
+                        <ExtendedTableCode>{itemType}</ExtendedTableCode>
                       </td>
                     </tr>
                   </tbody>
@@ -366,7 +394,7 @@ const Components16MigrationPage = () => (
       </DxcFlex>
     </PageHeading>
     <QuickNavContainer sections={sections} startHeadingLevel={2} />
-    <DocFooter githubLink="https://github.com/dxc-technology/halstack-react/blob/master/apps/website/screens/migration/Components16Page.tsx" />
+    <DocFooter githubLink="https://github.com/dxc-technology/halstack-react/blob/master/apps/website/screens/migration/components/Components16MigrationPage.tsx" />
   </DxcFlex>
 );
 

apps/website/screens/migration/components/examples/new.tsx

@@ -0,0 +1,33 @@
+import { DxcContainer, DxcFlex, DxcInset } from "@dxc-technology/halstack-react";
+
+const code = `() => {
+  return (
+    <DxcInset space="var(--spacing-padding-xl)">
+      <DxcFlex gap="var(--spacing-gap-xl)">
+        <DxcContainer 
+          width="100%"
+          height="var(--height-xxl)"
+          background={{color: "var(--color-bg-primary-medium)"}}
+        />
+        <DxcContainer
+          width="100%"
+          height="var(--height-xxl)"
+          background={{color: "var(--color-bg-primary-strong)"}}
+        />
+        <DxcContainer
+          width="100%"
+          height="var(--height-xxl)"
+          background={{color: "var(--color-bg-primary-medium)"}}
+        />
+      </DxcFlex>
+    </DxcInset>
+  );
+}`;
+
+const scope = {
+  DxcFlex,
+  DxcInset,
+  DxcContainer,
+};
+
+export default { code, scope };

apps/website/screens/migration/components/examples/previous.tsx

@@ -0,0 +1,33 @@
+import { DxcContainer, DxcFlex, DxcInset } from "@dxc-technology/halstack-react";
+
+const code = `() => {
+  return (
+    <DxcInset space="2rem">
+      <DxcFlex gap="2rem">
+        <DxcContainer
+          width="100%"
+          height="40px"
+          background={{color: "#DDC9F3"}}
+         />
+        <DxcContainer
+          width="100%"
+          height="40px"
+          background={{color: "#6F4B97"}}
+         />
+        <DxcContainer
+          width="100%"
+          height="40px"
+          background={{color: "#DDC9F3"}}
+         />
+      </DxcFlex>
+    </DxcInset>
+  );
+}`;
+
+const scope = {
+  DxcFlex,
+  DxcInset,
+  DxcContainer,
+};
+
+export default { code, scope };