feat(many): add new Typography tokens and update text and heading

Closes: INSTUI-4403

docs/guides/typography-system.md

@@ -0,0 +1,73 @@
+---
+title: Typography
+category: Guides
+order: 8
+---
+
+# Typography
+
+InstUI provides various typography tokens on theme and component level as well.
+
+## Typography components
+
+Your every text-based need should be covered by one of our two typography components, namely `<Text>` and `<Heading>`.
+These components have a `variant` prop with a handful of semantic values to choose from. These values describe multiple aspects of the text, such as `font-weight`, `font-size`, `line-height` and for `<Heading>` the DOM element that should be rendered, (i.e.:`<h1>`, `<h2>`, `<h3>`, `<h4>`, `<h5>`).
+
+While you can set all these properties separately as well, our strong recommendation is to use the variant with semantic values and only deviate from it in cases absolutely necessary.
+
+## <Text>
+
+Here is the list of semantic variant values and what they do in `<Text>`
+
+This is always rendered as `<span>`
+
+The values (e.g.:`weightRegular`) are from the currently used theme's typography sections, for example:
+[Canvas Theme](https://instructure.design/#canvas)
+
+| variant            | fontStyle | weight          | size               | lineHeight    |
+| ------------------ | --------- | --------------- | ------------------ | ------------- |
+| descriptionPage    | normal    | weightRegular   | descriptionPage    | lineHeight150 |
+| descriptionSection | normal    | weightRegular   | descriptionSection | lineHeight150 |
+| content            | normal    | weightRegular   | content            | lineHeight150 |
+| contentImportant   | normal    | weightImportant | content            | lineHeight150 |
+| contentQuote       | normal    | weightRegular   | content            | lineHeight150 |
+| contentSmall       | normal    | weightRegular   | contentSmall       | lineHeight150 |
+| legend             | normal    | weightRegular   | legend             | lineHeight150 |
+
+## <Heading>
+
+Here is the list of semantic variant values and how are they rendered in `<Heading>`
+
+| variant          | dom element |
+| ---------------- | ----------- |
+| titlePageDesktop | h1          |
+| titlePageMobile  | h1          |
+| titleSection     | h2          |
+| titleCardSection | h2          |
+| titleModule      | h3          |
+| titleCardLarge   | h4          |
+| titleCardRegular | h4          |
+| titleCardMini    | h4          |
+| label            | h5          |
+| labelInline      | h5          |
+
+## Legacy values
+
+For compatibility reasons we still provide the legacy typography tokens (xxLarge, medium, etc.) so updating InstUI is easier but these tokens shouldn't be used when creating new screens. The following tokens are deprecated from the `themes`, more specifically from `theme.typography`
+
+Deprecated theme tokens:
+
+- fontSizeXSmall
+- fontSizeSmall
+- fontSizeMedium
+- fontSizeLarge
+- fontSizeXLarge
+- fontSizeXXLarge
+- fontWeightLight
+- fontWeightNormal
+- fontWeightBold
+- lineHeight
+- lineHeightFit
+- lineHeightCondensed
+- lineHeightDouble
+- letterSpacingNormal

packages/shared-types/src/BaseTheme.ts

@@ -111,6 +111,26 @@ type Typography = {
   letterSpacingNormal: number | 0
   letterSpacingCondensed: string | 0
   letterSpacingExpanded: string | 0
+
+  titlePageDesktop: string
+  titlePageMobile: string
+  titleSection: string
+  titleModule: string
+  titleCardLarge: string
+  titleCardRegular: string
+  titleCardMini: string
+  descriptionPage: string
+  descriptionSection: string
+  label: string
+  content: string
+  contentSmall: string
+  legend: string
+
+  lineHeight100: number
+  lineHeight125: number
+  lineHeight150: number
+  weightRegular: number
+  weightImportant: number
 }
 
 type Size = {

packages/shared-types/src/ComponentThemeVariables.ts

@@ -603,7 +603,7 @@ export type GridTheme = {
   spacingLarge: Spacing['large']
 } & Media
 
-export type HeadingTheme = {
+export type HeadingTheme = Typography & {
   lineHeight: Typography['lineHeightCondensed']
   h1FontSize: Typography['fontSizeXXLarge']
   h1FontWeight: Typography['fontWeightBold']

packages/ui-heading/src/Heading/README.md

@@ -4,6 +4,31 @@ describes: Heading
 
 Heading is a component for creating typographic headings.
 
+## Variant
+
+Variant takes care of - almost - all use-cases when it comes hedings on pages. Their name reflects the places they meant to be used. It sets the `level` prop and takes care of the style of the heading
+We recommend using `variants` instead of the `level` (and `as`) props.
+
+NOTE: when `variant` is set, `level` and `as` props are ignored
+
+```js
+---
+type: example
+---
+  <div>
+    <Heading variant="titlePageDesktop"> titlePageDesktop </Heading><br/>
+    <Heading variant="titlePageMobile"> titlePageMobile </Heading><br/>
+    <Heading variant="titleSection"> titleSection </Heading><br/>
+    <Heading variant="titleCardSection"> titleCardSection </Heading><br/>
+    <Heading variant="titleModule"> titleModule </Heading><br/>
+    <Heading variant="titleCardLarge"> titleCardLarge </Heading><br/>
+    <Heading variant="titleCardRegular"> titleCardRegular </Heading><br/>
+    <Heading variant="titleCardMini"> titleCardMini </Heading><br/>
+    <Heading variant="label"> label </Heading><br/>
+    <Heading variant="labelInline"> labelInline </Heading><br/>
+  </div>
+```
+
 ```js
 ---
 type: example
@@ -24,11 +49,7 @@ type: example
 ---
 <div>
   <Heading level="h1" as="h2" margin="0 0 x-small">Heading level One</Heading>
-  <Heading level="h2" as="h1" margin="0 0 x-small">Heading level Two</Heading>
-  <Heading level="h3" margin="0 0 x-small">Heading level Three</Heading>
-  <Heading level="h4" margin="0 0 x-small">Heading level Four</Heading>
-  <Heading level="h5" margin="0 0 x-small">Heading level Five</Heading>
-  <Heading level="reset" as="h2">Heading level reset as a Two</Heading>
+
 </div>
 ```
 

packages/ui-heading/src/Heading/__examples__/Heading.examples.ts

@@ -26,15 +26,18 @@ import type { StoryConfig } from '@instructure/ui-test-utils'
 import type { HeadingProps } from '../props'
 
 export default {
-  sectionProp: 'level',
+  sectionProp: 'variant',
   propValues: {
     color: [
       'primary',
       'secondary',
       'primary-inverse',
       'secondary-inverse',
       'inherit'
-    ]
+    ],
+
+    level: [undefined],
+    as: [undefined]
   },
   getComponentProps: () => {
     return {

packages/ui-heading/src/Heading/index.tsx

@@ -36,6 +36,22 @@ import generateComponentTheme from './theme'
 import { propTypes, allowedProps } from './props'
 import type { HeadingProps } from './props'
 
+const variantLevels: Record<
+  NonNullable<HeadingProps['variant']>,
+  'h1' | 'h2' | 'h3' | 'h4' | 'h5'
+> = {
+  titlePageDesktop: 'h1',
+  titlePageMobile: 'h1',
+  titleSection: 'h2',
+  titleCardSection: 'h2',
+  titleModule: 'h3',
+  titleCardLarge: 'h4',
+  titleCardRegular: 'h4',
+  titleCardMini: 'h4',
+  label: 'h5',
+  labelInline: 'h5'
+}
+
 /**
 ---
 category: components
@@ -67,12 +83,26 @@ class Heading extends Component<HeadingProps> {
     }
   }
 
+  checkProps() {
+    const { variant, level, as } = this.props
+    if (variant) {
+      if (level) {
+        console.warn("[Heading]: Don't use 'level' with 'variant' ")
+      }
+      if (as) {
+        console.warn("[Heading]: Don't use 'as' with 'variant' ")
+      }
+    }
+  }
+
   componentDidMount() {
     this.props.makeStyles?.()
+    this.checkProps()
   }
 
   componentDidUpdate() {
     this.props.makeStyles?.()
+    this.checkProps()
   }
 
   render() {
@@ -84,10 +114,16 @@ class Heading extends Component<HeadingProps> {
       margin,
       elementRef,
       makeStyles,
+      variant,
       ...props
     } = this.props
 
-    const ElementType = getElementType(Heading, this.props, () => {
+    const propsForGetElementType = variant ? {} : this.props
+
+    const ElementType = getElementType(Heading, propsForGetElementType, () => {
+      if (variant) {
+        return variantLevels[variant]
+      }
       if (level === 'reset') {
         return 'span'
       } else {

packages/ui-heading/src/Heading/props.ts

@@ -78,6 +78,21 @@ type HeadingOwnProps = {
    * Provides a ref to the underlying HTML element
    */
   elementRef?: (element: Element | null) => void
+  /**
+   * Sets style and level at once. The as property will be the same as the level.
+   * NOTE: this is the recommended way of setting the appearance, instead of level
+   */
+  variant?:
+    | 'titlePageDesktop'
+    | 'titlePageMobile'
+    | 'titleSection'
+    | 'titleCardSection'
+    | 'titleModule'
+    | 'titleCardLarge'
+    | 'titleCardRegular'
+    | 'titleCardMini'
+    | 'label'
+    | 'labelInline'
 }
 
 type PropKeys = keyof HeadingOwnProps
@@ -103,7 +118,19 @@ const propTypes: PropValidators<PropKeys> = {
   level: PropTypes.oneOf(['h1', 'h2', 'h3', 'h4', 'h5', 'reset']),
   as: PropTypes.elementType,
   margin: ThemeablePropTypes.spacing,
-  elementRef: PropTypes.func
+  elementRef: PropTypes.func,
+  variant: PropTypes.oneOf([
+    'titlePageDesktop',
+    'titlePageMobile',
+    'titleSection',
+    'titleCardSection',
+    'titleModule',
+    'titleCardLarge',
+    'titleCardRegular',
+    'titleCardMini',
+    'label',
+    'labelInline'
+  ])
 }
 
 const allowedProps: AllowedPropKeys = [
@@ -113,7 +140,8 @@ const allowedProps: AllowedPropKeys = [
   'level',
   'as',
   'margin',
-  'elementRef'
+  'elementRef',
+  'variant'
 ]
 
 export type { HeadingProps, HeadingStyle }

packages/ui-heading/src/Heading/styles.ts

@@ -39,7 +39,70 @@ const generateStyle = (
   componentTheme: HeadingTheme,
   props: HeadingProps
 ): HeadingStyle => {
-  const { level, color, border } = props
+  const { level, color, border, variant } = props
+
+  const variants: Record<NonNullable<HeadingProps['variant']>, object> = {
+    titlePageDesktop: {
+      fontStyle: 'normal',
+      fontWeight: componentTheme.weightImportant,
+      fontSize: componentTheme.titlePageDesktop,
+      lineHeight: componentTheme.lineHeight125
+    },
+    titlePageMobile: {
+      fontStyle: 'normal',
+      fontWeight: componentTheme.weightImportant,
+      fontSize: componentTheme.titlePageMobile,
+      lineHeight: componentTheme.lineHeight125
+    },
+    titleSection: {
+      fontStyle: 'normal',
+      fontWeight: componentTheme.weightImportant,
+      fontSize: componentTheme.titleSection,
+      lineHeight: componentTheme.lineHeight125
+    },
+    titleCardSection: {
+      fontStyle: 'normal',
+      fontWeight: componentTheme.weightImportant,
+      fontSize: componentTheme.titleSection,
+      lineHeight: componentTheme.lineHeight125
+    },
+    titleModule: {
+      fontStyle: 'normal',
+      fontWeight: componentTheme.weightImportant,
+      fontSize: componentTheme.titleModule,
+      lineHeight: componentTheme.lineHeight125
+    },
+    titleCardLarge: {
+      fontStyle: 'normal',
+      fontWeight: componentTheme.weightImportant,
+      fontSize: componentTheme.titleCardLarge,
+      lineHeight: componentTheme.lineHeight125
+    },
+    titleCardRegular: {
+      fontStyle: 'normal',
+      fontWeight: componentTheme.weightImportant,
+      fontSize: componentTheme.titleCardRegular,
+      lineHeight: componentTheme.lineHeight125
+    },
+    titleCardMini: {
+      fontStyle: 'normal',
+      fontWeight: componentTheme.weightImportant,
+      fontSize: componentTheme.titleCardMini,
+      lineHeight: componentTheme.lineHeight125
+    },
+    label: {
+      fontStyle: 'normal',
+      fontWeight: componentTheme.weightImportant,
+      fontSize: componentTheme.label,
+      lineHeight: componentTheme.lineHeight125
+    },
+    labelInline: {
+      fontStyle: 'normal',
+      fontWeight: componentTheme.weightImportant,
+      fontSize: componentTheme.label,
+      lineHeight: componentTheme.lineHeight150
+    }
+  }
 
   const levelStyles = {
     h1: {
@@ -125,7 +188,7 @@ const generateStyle = (
       '&:is(input)[type]': inputStyles,
       '&:-webkit-any(input)[type]': inputStyles,
 
-      ...levelStyles[level!],
+      ...(variant ? variants[variant] : levelStyles[level!]),
       ...colorStyles[color!],
       ...borderStyles[border!]
     }

packages/ui-heading/src/Heading/theme.ts

@@ -50,6 +50,8 @@ const generateComponentTheme = (theme: Theme): HeadingTheme => {
   }
 
   const componentVariables: HeadingTheme = {
+    ...typography,
+
     lineHeight: typography?.lineHeightCondensed,
 
     h1FontSize: typography?.fontSizeXXLarge,