Typography
- Library
- UDS Base
- Repository
- github.com/telus/universal-design-system
- Package
- npmjs.com/package/@telus-uds/components-base
- Package version
- 1.6.1
Introduction
import { Typography } from '@telus-uds/components-base'
Typography can be used to achieve a variety of different typographic styles. Size, weight, colour and semantic markup are all controlled using the variants described below.
Guidance
Headings
- Be mindful of SEO and accessibility
- Organize headers in a nested order: h1, then h2, then h3
- Try not to skip levels where possible: h1, then h3
- Use one h1 per page
- For Hero overlays, Headlines, or Promo blocks, use DisplayHeading
- For subtext in the Hero overlays, or Headlines, use Text
Spacing
Typography components do not have built-in margins. See the Box component to learn how to apply spacing to typography components.
Subscript and superscript
Typography component can accept text containing subscript or superscript wrapped in corresponding tags (<sub> or <sup>) and will render those according to the main text variant used:
Consider this: $01 first month1
Stream live TV2 on any screen2
warning
Note that our current font can have issues with special characters often used in superscript, e.g. ™, 🅪, 🅫, ®, etc., so it's strongly recommended to use ordinary letters in superscript instead whenever possible.
Accessibility
Separate semantic meaning from visual styling
The semantic HTML tag and visual appearance of the Typography component can be controlled independently using the variant and heading props together.
This allows developers, designers, and content editors to represent headings with a certain style while rendering a HTML tag of their choice.
It's important to maintain a correct order of heading level and not skip levels; for example, have a <h2> HTML element that directly follows a <h1>, or a <h3> that directly follows a <h2>.
This simple yet powerful feature allows users of assistive technology to navigate through content predictably since headings represent information hierarchy, while we also balance an appropriate visual hierarchy.
In the promotional content example below.
- The first line of text appears as a
H4, but renders with a<h1>tag. - The second line of text appears as a
Display2, but renders with a<h2>. - The third line of text appears as
Largetext, but renders with a<div>.
Consider this: $0 first month
Stream live TV on any screen
Props
| Name | Type | Default | Description |
|---|---|---|---|
| tag | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'blockquote' | 'code' | 'del' | 'em' | 'ins' | 'li' | 'strong' | 'label' | typeof heading === 'string' ? heading : undefined | Optional semantic HTML tag, to apply to the text on web. Does not change styling. `tag` and `heading` props set the same thing, so shouldn't be used together (`tag` overrides `heading`). In native apps, if a header tag is provided ("h1", "h2" etc) and accessibilityRole prop is not defined, the accessibilityRole will default to "heading". |
| accessibilityRole | heading === true ? 'header' : undefined | ||
| block | bool | false | If true, forces the element to behave as a View block even if nested in other text |
| align | 'auto' | 'left' | 'right' | 'center' | 'justify' | undefined | Works the same as css text-align, note that RN doesn't support "start" or "end" (see https://reactnative.dev/docs/text-style-props#textalign) Justify is known to make text harder to read, especially for people with dyslexia (see https://developer.mozilla.org/en-US/docs/Web/CSS/text-align#accessibility_concerns) |
| tokens | custom | System tokens prop, see tokens for more details | |
| variant | objectOf | System variant prop, see variants for more details | |
| heading | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | true | Renders the text as a semantic heading. If a html heading tag is provided, uses that tag on Web. Does not affect styling: <Typography heading="h2"> will render a <h2> that looks like plain text. Use both `heading` and `variant` props to render semantic headings that look like headings. In native apps, if this is `true` or any html heading tag string and accessibilityRole prop is not defined, the accessibilityRole will default to "heading". | |
| children | node | Same children allowed as a React Native <Text> node |