diff --git a/docs/data/joy/customization/theme-typography/CustomTypographyLevel.js b/docs/data/joy/customization/theme-typography/CustomTypographyLevel.js
new file mode 100644
index 00000000000000..5306f1fd3c6433
--- /dev/null
+++ b/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 (
+
+ theme.typography.display1}>Gradient text
+
+ );
+}
diff --git a/docs/data/joy/customization/theme-typography/CustomTypographyLevel.tsx b/docs/data/joy/customization/theme-typography/CustomTypographyLevel.tsx
new file mode 100644
index 00000000000000..5306f1fd3c6433
--- /dev/null
+++ b/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 (
+
+ theme.typography.display1}>Gradient text
+
+ );
+}
diff --git a/docs/data/joy/customization/theme-typography/CustomTypographyLevel.tsx.preview b/docs/data/joy/customization/theme-typography/CustomTypographyLevel.tsx.preview
new file mode 100644
index 00000000000000..8efdd6c11eff6a
--- /dev/null
+++ b/docs/data/joy/customization/theme-typography/CustomTypographyLevel.tsx.preview
@@ -0,0 +1,3 @@
+
+ theme.typography.display1}>Gradient text
+
\ No newline at end of file
diff --git a/docs/data/joy/customization/theme-typography/DefaultTypographySystem.js b/docs/data/joy/customization/theme-typography/DefaultTypographySystem.js
new file mode 100644
index 00000000000000..1c0d22a152050a
--- /dev/null
+++ b/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 (
+
+ {Object.entries(theme.typography).map(([level, style]) => (
+
+ {level}
+
+ ))}
+
+ );
+}
diff --git a/docs/data/joy/customization/theme-typography/NewTypographyLevel.js b/docs/data/joy/customization/theme-typography/NewTypographyLevel.js
new file mode 100644
index 00000000000000..2accfe85a9ecab
--- /dev/null
+++ b/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 (
+
+
+
+ Press ⌘ +{' '}
+ k to search the documentation.
+
+
+
+ );
+}
diff --git a/docs/data/joy/customization/theme-typography/theme-typography.md b/docs/data/joy/customization/theme-typography/theme-typography.md
new file mode 100644
index 00000000000000..ef9741e3271923
--- /dev/null
+++ b/docs/data/joy/customization/theme-typography/theme-typography.md
@@ -0,0 +1,162 @@
+# Theme typography
+
+Learn about the typography system and how to customize it.
+
+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
+ Secondary info
+ ```
+
+- [CSS Baseline](/joy-ui/react-css-baseline/) component: by default, it applies the `body1` level to the global stylesheet:
+
+ ```jsx
+
+
+ // inherits the `theme.typography.body1` styles
+ Hello World
+ ```
+
+- [`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:
+ Small text
+ ```
+
+- [`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)
+
+
+
+### Human Interface Guidelines (Apple)
+
+- Design resource: [Sketch library](https://developer.apple.com/design/resources/)
+- Font: [San Francisco (SF)](https://developer.apple.com/fonts/)
+
+
+
+### Material Design 3 (Google)
+
+- Design resource: [Figma](https://www.figma.com/community/file/1035203688168086460)
+- Font: [Roboto](https://fonts.google.com/specimen/Roboto)
+
+
+
+:::success
+Feel free to [submit a PR](https://github.com/mui/material-ui/compare) to add your favorite typography system ❤️.
+:::
diff --git a/docs/data/joy/pages.ts b/docs/data/joy/pages.ts
index 1833e0c8b49bc6..e002525e5c4f01 100644
--- a/docs/data/joy/pages.ts
+++ b/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' },
],
diff --git a/docs/pages/joy-ui/customization/theme-typography.js b/docs/pages/joy-ui/customization/theme-typography.js
new file mode 100644
index 00000000000000..78659441ef5187
--- /dev/null
+++ b/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 ;
+}