[docs] Add Joy UI theme typography page (#34811)

docs/data/joy/customization/theme-typography/CustomTypographyLevel.js

@@ -0,0 +1,26 @@
+import * as React from 'react';
+import { CssVarsProvider, extendTheme } from '@mui/joy/styles';
+import Box from '@mui/joy/Box';
+
+const customTheme = extendTheme({
+  typography: {
+    display1: {
+      // `--joy` is the default CSS variable prefix.
+      // If you have a custom prefix, you have to use it instead.
+      // For more details about the custom prefix, go to https://mui.com/joy-ui/customization/using-css-variables/#custom-prefix
+      background:
+        'linear-gradient(-30deg, var(--joy-palette-primary-700), var(--joy-palette-primary-400))',
+      // `Webkit*` properties must come later.
+      WebkitBackgroundClip: 'text',
+      WebkitTextFillColor: 'transparent',
+    },
+  },
+});
+
+export default function CustomTypographyLevel() {
+  return (
+    <CssVarsProvider theme={customTheme}>
+      <Box sx={(theme) => theme.typography.display1}>Gradient text</Box>
+    </CssVarsProvider>
+  );
+}

docs/data/joy/customization/theme-typography/CustomTypographyLevel.tsx

@@ -0,0 +1,26 @@
+import * as React from 'react';
+import { CssVarsProvider, extendTheme } from '@mui/joy/styles';
+import Box from '@mui/joy/Box';
+
+const customTheme = extendTheme({
+  typography: {
+    display1: {
+      // `--joy` is the default CSS variable prefix.
+      // If you have a custom prefix, you have to use it instead.
+      // For more details about the custom prefix, go to https://mui.com/joy-ui/customization/using-css-variables/#custom-prefix
+      background:
+        'linear-gradient(-30deg, var(--joy-palette-primary-700), var(--joy-palette-primary-400))',
+      // `Webkit*` properties must come later.
+      WebkitBackgroundClip: 'text',
+      WebkitTextFillColor: 'transparent',
+    },
+  },
+});
+
+export default function CustomTypographyLevel() {
+  return (
+    <CssVarsProvider theme={customTheme}>
+      <Box sx={(theme) => theme.typography.display1}>Gradient text</Box>
+    </CssVarsProvider>
+  );
+}

docs/data/joy/customization/theme-typography/CustomTypographyLevel.tsx.preview

@@ -0,0 +1,3 @@
+<CssVarsProvider theme={customTheme}>
+  <Box sx={(theme) => theme.typography.display1}>Gradient text</Box>
+</CssVarsProvider>

docs/data/joy/customization/theme-typography/DefaultTypographySystem.js

@@ -0,0 +1,15 @@
+import * as React from 'react';
+import { useTheme } from '@mui/joy/styles';
+
+export default function DefaultTypographySystem() {
+  const theme = useTheme();
+  return (
+    <div>
+      {Object.entries(theme.typography).map(([level, style]) => (
+        <div key={level} style={style}>
+          {level}
+        </div>
+      ))}
+    </div>
+  );
+}

docs/data/joy/customization/theme-typography/NewTypographyLevel.js

@@ -0,0 +1,29 @@
+import * as React from 'react';
+import { CssVarsProvider, extendTheme } from '@mui/joy/styles';
+import Box from '@mui/joy/Box';
+import Typography from '@mui/joy/Typography';
+
+const customTheme = extendTheme({
+  typography: {
+    kbd: {
+      backgroundColor: 'var(--joy-palette-background-surface)',
+      border: '1px solid var(--joy-palette-neutral-outlinedBorder)',
+      borderRadius: 'var(--joy-radius-xs)',
+      boxShadow: '0 2px 0px 0px var(--joy-palette-background-level3)',
+      padding: '0.125em 0.375em',
+    },
+  },
+});
+
+export default function MoreTypographyLevel() {
+  return (
+    <CssVarsProvider theme={customTheme}>
+      <Box>
+        <Typography>
+          Press <Typography level="kbd">⌘</Typography> +{' '}
+          <Typography level="kbd">k</Typography> to search the documentation.
+        </Typography>
+      </Box>
+    </CssVarsProvider>
+  );
+}

docs/data/joy/customization/theme-typography/theme-typography.md

@@ -0,0 +1,162 @@
+# Theme typography
+
+<p class="description">Learn about the 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:
+
+- `body1` - 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": "DefaultTypographySystem.js"}}
+
+:::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.
+
+This ensures that you can customize or even remove the default typography system without affecting other components.
+:::
+
+### Customizing the default system
+
+To customize a default level, provide its name as a key and an object containing CSS rules as a value to `theme.typography`.
+
+The example below illustrates the customization of the `display1` level:
+
+{{"demo": "CustomTypographyLevel.js"}}
+
+### Removing the default system
+
+Use `undefined` as a value to remove any unneeded levels:
+
+```js
+const customTheme = extendTheme({
+  typography: {
+    h5: undefined,
+    h6: undefined,
+    body4: undefined,
+    body5: undefined,
+  },
+});
+```
+
+For TypeScript, you must augment the theme structure to exclude the default levels:
+
+```ts
+// You can put this to any file that's included in your tsconfig
+declare module '@mui/joy/styles' {
+  interface TypographySystemOverrides {
+    h5: false;
+    h6: false;
+    body4: false;
+    body5: false;
+  }
+}
+```
+
+## Adding more levels
+
+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}}
+
+For TypeScript, you must augment the theme structure to include the new level:
+
+```ts
+// You can put this to any file that's included in your tsconfig
+declare module '@mui/joy/styles' {
+  interface TypographySystemOverrides {
+    kbd: true;
+  }
+}
+```
+
+## 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.body2` styles
+  <Typography level="body2">Secondary info</Typography>
+  ```
+
+- [CSS Baseline](/joy-ui/react-css-baseline/) component: by default, it applies the `body1` level to the global stylesheet:
+
+  ```jsx
+  <CssBaseline />
+
+  // inherits the `theme.typography.body1` 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.body2` styles:
+  <Box sx={{ typography: 'body2' }}>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.body2,
+    color: 'inherit',
+    borderRadius: theme.vars.radius.xs,
+    boxShadow: theme.vars.shadow.sm,
+    padding: '0.125em 0.375em',
+  }));
+  ```
+
+## Common examples
+
+Here is a collection of well-known typography systems that you can use with Joy UI.
+
+### Fluent (Microsoft)
+
+- Design resource: [Figma](https://www.figma.com/community/file/836828295772957889)
+- Font: [Segoe UI](https://learn.microsoft.com/en-us/typography/font-list/segoe-ui)
+
+<iframe src="https://codesandbox.io/embed/joy-ui-fluent-typography-system-j86fct?module=%2Fdemo.tsx&fontsize=14&hidenavigation=1&theme=dark&view=preview"
+     style="width:100%; height:360px; border:0; border-radius: 4px; overflow:hidden;"
+     title="Joy UI - Fluent 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"
+   ></iframe>
+
+### Human Interface Guidelines (Apple)
+
+- Design resource: [Sketch library](https://developer.apple.com/design/resources/)
+- 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;"
+     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"
+   ></iframe>
+
+### Material Design 3 (Google)
+
+- Design resource: [Figma](https://www.figma.com/community/file/1035203688168086460)
+- Font: [Roboto](https://fonts.google.com/specimen/Roboto)
+
+<iframe src="https://codesandbox.io/embed/joy-ui-material-3-typography-system-lx044f?module=%2Fdemo.tsx&fontsize=14&hidenavigation=1&theme=dark&view=preview"
+     style="width:100%; height:500px; border:0; border-radius: 4px; overflow:hidden;"
+     title="Joy UI - Joy UI - Material 3 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"
+   ></iframe>
+
+:::success
+Feel free to [submit a PR](https://github.com/mui/material-ui/compare) to add your favorite typography system ❤️.
+:::

docs/data/joy/pages.ts

@@ -94,6 +94,7 @@ const pages = [
       { pathname: '/joy-ui/customization/dark-mode' },
       { pathname: '/joy-ui/customization/default-theme' },
       { pathname: '/joy-ui/customization/theme-tokens' },
+      { pathname: '/joy-ui/customization/theme-typography' },
       { pathname: '/joy-ui/customization/themed-components' },
       { pathname: '/joy-ui/customization/using-css-variables', title: 'Using CSS variables' },
     ],

docs/pages/joy-ui/customization/theme-typography.js

@@ -0,0 +1,7 @@
+import * as React from 'react';
+import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs';
+import * as pageProps from 'docs/data/joy/customization/theme-typography/theme-typography.md?@mui/markdown';
+
+export default function Page() {
+  return <MarkdownDocs {...pageProps} />;
+}