From 4ec2458a9f230c35360e0df7ea443e7a6adac933 Mon Sep 17 00:00:00 2001 From: Siriwat K Date: Thu, 17 Nov 2022 12:28:10 +0700 Subject: [PATCH] [docs] Add Joy UI theme typography page (#34811) --- .../theme-typography/CustomTypographyLevel.js | 26 +++ .../CustomTypographyLevel.tsx | 26 +++ .../CustomTypographyLevel.tsx.preview | 3 + .../DefaultTypographySystem.js | 15 ++ .../theme-typography/NewTypographyLevel.js | 29 ++++ .../theme-typography/theme-typography.md | 162 ++++++++++++++++++ docs/data/joy/pages.ts | 1 + .../joy-ui/customization/theme-typography.js | 7 + 8 files changed, 269 insertions(+) create mode 100644 docs/data/joy/customization/theme-typography/CustomTypographyLevel.js create mode 100644 docs/data/joy/customization/theme-typography/CustomTypographyLevel.tsx create mode 100644 docs/data/joy/customization/theme-typography/CustomTypographyLevel.tsx.preview create mode 100644 docs/data/joy/customization/theme-typography/DefaultTypographySystem.js create mode 100644 docs/data/joy/customization/theme-typography/NewTypographyLevel.js create mode 100644 docs/data/joy/customization/theme-typography/theme-typography.md create mode 100644 docs/pages/joy-ui/customization/theme-typography.js 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 ; +}