[docs][joy-ui] Revise the theme typography page (#38285)

Co-authored-by: siriwatknp <[email protected]>
mui · Aug 7, 2023 · fac8f0c · fac8f0c
1 parent 0261ce3
commit fac8f0c
Show file tree

Hide file tree

Showing 6 changed files with 94 additions and 70 deletions.
diff --git a/docs/data/joy/customization/theme-typography/CustomTypographyLevel.js b/docs/data/joy/customization/theme-typography/CustomTypographyLevel.js
@@ -20,7 +20,7 @@ const customTheme = extendTheme({
 export default function CustomTypographyLevel() {
   return (
     <CssVarsProvider theme={customTheme}>
-      <Box sx={(theme) => theme.typography.h1}>Gradient text</Box>
+      <Box sx={(theme) => theme.typography.h1}>This is a gradient h1</Box>
     </CssVarsProvider>
   );
 }
diff --git a/docs/data/joy/customization/theme-typography/CustomTypographyLevel.tsx b/docs/data/joy/customization/theme-typography/CustomTypographyLevel.tsx
@@ -20,7 +20,7 @@ const customTheme = extendTheme({
 export default function CustomTypographyLevel() {
   return (
     <CssVarsProvider theme={customTheme}>
-      <Box sx={(theme) => theme.typography.h1}>Gradient text</Box>
+      <Box sx={(theme) => theme.typography.h1}>This is a gradient h1</Box>
     </CssVarsProvider>
   );
 }
diff --git a/docs/data/joy/customization/theme-typography/CustomTypographyLevel.tsx.preview b/docs/data/joy/customization/theme-typography/CustomTypographyLevel.tsx.preview
@@ -1,3 +1,3 @@
 <CssVarsProvider theme={customTheme}>
-  <Box sx={(theme) => theme.typography.h1}>Gradient text</Box>
+  <Box sx={(theme) => theme.typography.h1}>This is a gradient h1</Box>
 </CssVarsProvider>
diff --git a/docs/data/joy/customization/theme-typography/TypographyThemeViewer.js b/docs/data/joy/customization/theme-typography/TypographyThemeViewer.js
@@ -7,9 +7,6 @@ import Typography from '@mui/joy/Typography';
 const defaultTheme = extendTheme();
 
 const Table = styled('table')(({ theme }) => ({
-  border: '1px solid',
-  borderColor: theme.vars.palette.divider,
-  borderRadius: theme.vars.radius.md,
   borderCollapse: 'separate',
   borderSpacing: 0,
   display: 'block',
@@ -63,7 +60,17 @@ export default function TypographyThemeViewer() {
       />
     ) : null;
   return (
-    <Box sx={{ maxWidth: '100%', overflowX: 'scroll' }}>
+    <Box
+      sx={{
+        marginBottom: '-9px',
+        maxWidth: '100%',
+        overflowX: 'scroll',
+        border: '1px solid',
+        borderColor: 'divider',
+        borderTopLeftRadius: '12px',
+        borderTopRightRadius: '12px',
+      }}
+    >
       <Table>
         <thead>
           <tr>

diff --git a/docs/data/joy/customization/theme-typography/TypographyThemeViewer.tsx b/docs/data/joy/customization/theme-typography/TypographyThemeViewer.tsx
@@ -7,9 +7,6 @@ import Typography from '@mui/joy/Typography';
 const defaultTheme = extendTheme();
 
 const Table = styled('table')(({ theme }) => ({
-  border: '1px solid',
-  borderColor: theme.vars.palette.divider,
-  borderRadius: theme.vars.radius.md,
   borderCollapse: 'separate',
   borderSpacing: 0,
   display: 'block',
@@ -64,7 +61,17 @@ export default function TypographyThemeViewer() {
       />
     ) : null;
   return (
-    <Box sx={{ maxWidth: '100%', overflowX: 'scroll' }}>
+    <Box
+      sx={{
+        marginBottom: '-9px',
+        maxWidth: '100%',
+        overflowX: 'scroll',
+        border: '1px solid',
+        borderColor: 'divider',
+        borderTopLeftRadius: '12px',
+        borderTopRightRadius: '12px',
+      }}
+    >
       <Table>
         <thead>
           <tr>

diff --git a/docs/data/joy/customization/theme-typography/theme-typography.md b/docs/data/joy/customization/theme-typography/theme-typography.md
@@ -2,40 +2,76 @@
 
 <p class="description">Learn about the default theme's typography system and how to customize it.</p>
 
-Joy UI includes a typography system within the theme to help you create consistent text across your application. You can customize the default system or start from scratch depending on your needs.
-
 ## Default system
 
-The default system consists of 13 built-in levels:
+Joy UI's default theme includes a built-in typography system of 11 distinct levels—including semantic HTML headers as well as a comparable system for body text—to help you ensure consistency across your interface.
 
-- `body-md` - the baseline typography for the application, used as the default configuration in the [Typography](/joy-ui/react-typography/) and [CssBaseline](/joy-ui/react-css-baseline/) components.
-- `body2` through `body5` - can be used for secondary and tertiary information.
-- The `h1` to `h6` levels follow the semantic HTML headings.
-- The `display1` and `display2` usually appear as taglines for marketing and landing pages.
+{{"demo": "TypographyThemeViewer.js", "bg": "inline"}}
 
 :::info
-🔍 You can hover on each cell in the table below to see the preview value.
+[CSS Baseline](/joy-ui/react-css-baseline/), [Scoped CSS Baseline](/joy-ui/react-css-baseline/#scoping-on-children), and [Typography](/joy-ui/react-typography/) are the only components that consume the theme typography directly, ensuring you can customize or even remove the default typography system without affecting other components.
 :::
 
-{{"demo": "TypographyThemeViewer.js", "bg": "inline"}}
+### Usage
 
-:::info
-[CSS Baseline](/joy-ui/react-css-baseline/), [Scoped CSS Baseline](/joy-ui/react-css-baseline/#scoping-on-children), and [Typography](/joy-ui/react-typography/) are the only components that consume the theme typography directly.
+There are several ways that you can use the theme typography in your application:
 
-This ensures that you can customize or even remove the default typography system without affecting other components.
-:::
+#### Typography component
+
+Use the `level` prop in the [Typography](/joy-ui/react-typography/) component:
+
+```jsx
+// use the `theme.typography['body-sm']` styles
+<Typography level="body-sm">Secondary info</Typography>
+```
+
+#### CSS Baseline
+
+The [CSS Baseline](/joy-ui/react-css-baseline/) component applies `body-md` as the default level on the global stylesheet:
+
+```jsx
+<CssBaseline />
+
+// inherits the `theme.typography['body-md']` styles
+<p>Hello World</p>
+```
+
+#### sx prop
+
+Customize the typographic styles via the `sx` prop using `typography: 'some-level'`:
+
+```jsx
+// to apply the `theme.typography['body-sm']` styles:
+<Box sx={{ typography: 'body-sm' }}>Small text</Box>
+```
+
+#### Applying theme styles to custom components
 
-### Customizing the default system
+Use the [`styled`](/joy-ui/customization/approaches/#reusable-component) function to create a custom component and apply styles from `theme.typography.*`:
 
-To customize a default level, provide its name as a key and an object containing CSS rules as a value to `theme.typography`.
+```jsx
+import { styled } from '@mui/joy/styles';
 
-The example below illustrates the customization of the `display1` level:
+const Tag = styled('span')((theme) => ({
+  ...theme.typography['body-sm'],
+  color: 'inherit',
+  borderRadius: theme.vars.radius.xs,
+  boxShadow: theme.vars.shadow.sm,
+  padding: '0.125em 0.375em',
+}));
+```
+
+## Customizations
+
+To customize a default level, provide its name as a key along with an object containing the CSS rules as a value to the `theme.typography` node.
+
+The example below illustrates the customization of the `h1` level:
 
 {{"demo": "CustomTypographyLevel.js"}}
 
 ### Removing the default system
 
-Use `undefined` as a value to remove any unneeded levels:
+Use `undefined` as a value to remove any unwanted levels:
 
 ```js
 const customTheme = extendTheme({
@@ -58,12 +94,13 @@ declare module '@mui/joy/styles' {
 }
 ```
 
-## Adding more levels
+### Adding more levels
+
+To add a new level, define it as a key-value pair in the `theme.typography` node, where the key is the name of the new level and the value is an object containing the CSS rules.
 
-You can define a new level as a key-value pair in `theme.typography`, where the key is the name of the level and the value is an object containing CSS rules.
 The demo below shows how to add a new level called `kbd`:
 
-{{"demo": "NewTypographyLevel.js", "bg": true}}
+{{"demo": "NewTypographyLevel.js"}}
 
 For TypeScript, you must augment the theme structure to include the new level:
 
@@ -76,46 +113,19 @@ declare module '@mui/joy/styles' {
 }
 ```
 
-## Usage
-
-There are several ways that you can use the theme typography in your application:
-
-- [Typography](/joy-ui/react-typography/) component: use the `level` prop to change between theme typography levels:
-
-  ```jsx
-  // use the `theme.typography['body-sm']` styles
-  <Typography level="body-sm">Secondary info</Typography>
-  ```
-
-- [CSS Baseline](/joy-ui/react-css-baseline/) component: by default, it applies the `body1` level to the global stylesheet:
+### Changing the default font
 
-  ```jsx
-  <CssBaseline />
+Joy UI uses the [Inter](https://rsms.me/inter/) font by default.
+To change it, override the theme's `fontFamily` property:
 
-  // inherits the `theme.typography['body-md']` styles
-  <p>Hello World</p>
-  ```
-
-- [`sx`](/joy-ui/customization/approaches/#sx-prop) prop: use `typography: $level` to get the specific theme typography level:
-
-  ```jsx
-  // to apply the `theme.typography['body-sm']` styles:
-  <Box sx={{ typography: 'body-sm' }}>Small text</Box>
-  ```
-
-- [`styled`](/joy-ui/customization/approaches/#reusable-component): create a custom component and apply the style from `theme.typography.*` directly:
-
-  ```jsx
-  import { styled } from '@mui/joy/styles';
-
-  const Tag = styled('span')((theme) => ({
-    ...theme.typography['body-sm'],
-    color: 'inherit',
-    borderRadius: theme.vars.radius.xs,
-    boxShadow: theme.vars.shadow.sm,
-    padding: '0.125em 0.375em',
-  }));
-  ```
+```js
+extendTheme({
+  fontFamily: {
+    display: 'Noto Sans', // applies to `h1`–`h4`
+    body: 'Noto Sans', // applies to `title-*` and `body-*`
+  },
+});
+```
 
 ## Common examples
 
@@ -140,7 +150,7 @@ Feel free to [submit a PR](https://github.com/mui/material-ui/compare) to add yo
 - Font: [San Francisco (SF)](https://developer.apple.com/fonts/)
 
 <iframe src="https://codesandbox.io/embed/joy-ui-human-interface-guidelines-typography-system-lkuz4d?module=%2Fdemo.tsx&fontsize=14&hidenavigation=1&theme=dark&view=preview"
-     style="width:100%; height:320px; border:0; border-radius: 4px; overflow:hidden;"
+     style="width:100%; height:320px; border:0; border-radius: 12px; overflow:hidden;"
      title="Joy UI - Human Interface Guidelines Typography System"
      allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
      sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"