Improve documentation of change to enable a better responsive implementation by tusers

Clean up according to review

Signed-off-by: Philipp Hugenroth <philipph@spotify.com>

.changeset/poor-jars-sniff.md

@@ -1,9 +1,15 @@
 ---
 '@backstage/core-components': patch
 '@backstage/create-app': patch
-'@backstage/plugin-api-docs': patch
 '@backstage/plugin-catalog': patch
 '@backstage/plugin-techdocs': patch
 ---
 
 Improve the responsiveness of the EntityPage UI. With this the Header component should scale with the screen size & wrapping should not cause overflowing/blocking of links. Additionally enforce the Pages using the Grid Layout to use it across all screen sizes & to wrap as intended.
+
+To benefit from the improved responsive layout, the `EntityPage` in existing Backstage applications should be updated to set the `xs` column size on each grid item in the page, as this does not default. For example:
+
+```diff
+-  <Grid item md={6}>
++  <Grid item xs={12} md={6}>
+```

packages/app/src/components/catalog/EntityPage.tsx

@@ -136,8 +136,9 @@ const EntityLayoutWrapper = (props: { children?: ReactNode }) => {
 };
 
 /**
- * TODO: For the MUI Grid to work there have to be "xs" set on every GridItem,
- * such that the seperation of space is clear from the smallest screen size upwards
+ * NOTE: This page is designed to work on small screens such as mobile devices.
+ * This is based on Material UI Grid. If breakpoints are used, each grid item must set the `xs` prop to a column size or to `true`,
+ * since this does not default. If no breakpoints are used, the items will equitably share the asvailable space.
  * https://material-ui.com/components/grid/#basic-grid.
  */
 

packages/core-components/src/layout/Header/Header.tsx

@@ -16,7 +16,7 @@
 
 import { useApi, configApiRef } from '@backstage/core-plugin-api';
 import { BackstageTheme } from '@backstage/theme';
-import { makeStyles, Tooltip, Typography, Grid } from '@material-ui/core';
+import { Box, Grid, makeStyles, Tooltip, Typography } from '@material-ui/core';
 import React, { CSSProperties, PropsWithChildren, ReactNode } from 'react';
 import { Helmet } from 'react-helmet';
 import { Link } from '../../components/Link';
@@ -44,15 +44,10 @@ const useStyles = makeStyles<BackstageTheme>(theme => ({
   },
   leftItemsBox: {
     maxWidth: '100%',
-    flex: '1 1 auto',
+    flexGrow: 1,
     marginBottom: theme.spacing(1),
   },
   rightItemsBox: {
-    flex: '0 1 auto',
-    display: 'flex',
-    flexDirection: 'row',
-    flexWrap: 'wrap',
-    alignItems: 'center',
     width: 'auto',
   },
   title: {
@@ -202,7 +197,7 @@ export const Header = ({
     <>
       <Helmet titleTemplate={titleTemplate} defaultTitle={defaultTitle} />
       <header style={style} className={classes.header}>
-        <div className={classes.leftItemsBox}>
+        <Box className={classes.leftItemsBox}>
           <TypeFragment
             classes={classes}
             type={type}
@@ -215,13 +210,8 @@ export const Header = ({
             tooltip={tooltip}
           />
           <SubtitleFragment classes={classes} subtitle={subtitle} />
-        </div>
-        <Grid
-          component="div"
-          container
-          className={classes.rightItemsBox}
-          spacing={4}
-        >
+        </Box>
+        <Grid container className={classes.rightItemsBox} spacing={4}>
           {children}
         </Grid>
       </header>

packages/create-app/templates/default-app/packages/app/src/components/catalog/EntityPage.tsx

@@ -158,12 +158,12 @@ const websiteEntityPage = (
 );
 
 /**
- * TODO: For the MUI Grid to work there have to be "xs" set on every GridItem,
- * such that the seperation of space is clear from the smallest screen size upwards
+ * NOTE: This page is designed to work on small screens such as mobile devices.
+ * This is based on Material UI Grid. If breakpoints are used, each grid item must set the `xs` prop to a column size or to `true`,
+ * since this does not default. If no breakpoints are used, the items will equitably share the asvailable space.
  * https://material-ui.com/components/grid/#basic-grid.
  */
 
-
 const defaultEntityPage = (
   <EntityLayout>
     <EntityLayout.Route path="/" title="Overview">