|
| 1 | +## How typography is referenced |
| 2 | + |
| 3 | +Typography styles change based on the tool. This overview explains how HDS typography standards work in each tool. |
| 4 | + |
| 5 | +In Figma, reusable text styles are called “Text Styles” and are categorized and stored in the “text panel” to be used in text-based elements. Text styles directly reference font family, weight, line height, size, and many other text-based properties within a single style and are manually maintained. Some Figma styles include: |
| 6 | + |
| 7 | +- `Display/500/Bold` |
| 8 | +- `Body/300/Regular` |
| 9 | +- `Code/300/Regular` |
| 10 | + |
| 11 | +In code, these styles are constructed differently using “Tokens.” Tokens are generated from an agnostic JSON file and differ from Figma “Text Styles” because a single token does not reference multiple font properties. Instead, each Token defines the different properties of a single text style. This means that constructing the equivalence of Figma’s Text Style `Display/500/Bold` would use the following tokens: |
| 12 | + |
| 13 | +- `font-family: var(--token-typography-display-500-font-family);` |
| 14 | +- `font-size:var(--token-typography-display-500-font-size);` |
| 15 | +- `line-height:var(--token-typography-display-500-line-height);` |
| 16 | +- `font-weight:var(--token-typography-font-weight-bold);` |
| 17 | + |
| 18 | +Rather than calling upon each of these tokens in code every time text is styled, the [Text Component](/components/text) was created to replicate how Figma styles group text-based properties. Additional [CSS helper classes](https://helios.hashicorp.design/foundations/typography?tab=code#css-helper-classes) have been created to ease the style creation process, if necessary. |
| 19 | + |
| 20 | +## Font families |
| 21 | + |
| 22 | +In code, Helios uses default system fonts because they are stable, support internationalization, and improve performance by reducing resource load—key for large applications at HashiCorp. |
| 23 | + |
| 24 | +In Figma, our design tooling and libraries use SF Pro font family exclusively and we recommend using this font stack for consistency. |
| 25 | + |
| 26 | +While text styling varies slightly across operating systems, users will have a consistent and expected experience within each OS. |
| 27 | + |
| 28 | +### Sans-serif |
| 29 | + |
| 30 | +#### Mac + iOS sans-serif font |
| 31 | + |
| 32 | +Large text (20px and above): SF Pro Display |
| 33 | + |
| 34 | + |
| 35 | + |
| 36 | +Small text (19px and lower): SF Pro Text |
| 37 | + |
| 38 | + |
| 39 | + |
| 40 | +#### Windows sans-serif font |
| 41 | + |
| 42 | +Large text (20px and above): Segoe UI Display |
| 43 | + |
| 44 | + |
| 45 | + |
| 46 | +Small text (19px and lower): Segoe UI Text |
| 47 | + |
| 48 | + |
| 49 | + |
| 50 | +#### Linux sans-serif font |
| 51 | + |
| 52 | +Linux sans-serif system font dependant on the Linux distribution |
| 53 | + |
| 54 | + |
| 55 | + |
| 56 | +### Monospace |
| 57 | + |
| 58 | +#### Mac + iOS monospace font |
| 59 | + |
| 60 | +Safari 13+: SF Mono |
| 61 | + |
| 62 | + |
| 63 | + |
| 64 | +All else: Menlo |
| 65 | + |
| 66 | + |
| 67 | + |
| 68 | +#### Windows |
| 69 | + |
| 70 | +Consolas |
| 71 | + |
| 72 | + |
| 73 | + |
| 74 | +#### Linux |
| 75 | + |
| 76 | +Linux monospace system font dependant on the Linux distribution |
| 77 | + |
| 78 | + |
| 79 | + |
| 80 | +## Font weights |
| 81 | + |
| 82 | +In addition to font size, font weight helps create different levels of emphasis throughout the UI. Font weights include: |
| 83 | + |
| 84 | +- 400 (regular) |
| 85 | +- 500 (medium) |
| 86 | +- 600 (semi bold) |
| 87 | +- 700 (bold) |
| 88 | + |
| 89 | +Within these ranges, bold is used only for display and some code text styles, while regular is associated with body text styles which may include code. |
| 90 | + |
| 91 | +## Text styles |
| 92 | + |
| 93 | +### Display |
| 94 | + |
| 95 | +Display styles should be used for headings or visual emphasis (like remaining balances). Unless used for visual emphasis, if the display text looks like a page heading, it should use an [HTML heading tag](https://www.w3.org/WAI/WCAG22/Understanding/section-headings.html). |
| 96 | + |
| 97 | +Display text styles are available in the following sizes and weights: |
| 98 | + |
| 99 | +<ul class='doc-typography-demo-display-list'> |
| 100 | + <li class="hds-typography-display-500 hds-font-weight-bold">Display 500 (30px) - Bold</li> |
| 101 | + <br/> |
| 102 | + <li class="hds-typography-display-400 hds-font-weight-bold">Display 400 (24px) - Bold</li> |
| 103 | + <li class="hds-typography-display-400 hds-font-weight-semibold">Display 400 (24px) - Semibold</li> |
| 104 | + <li class="hds-typography-display-400 hds-font-weight-medium">Display 400 (24px) - Medium</li> |
| 105 | + <br/> |
| 106 | + <li class="hds-typography-display-300 hds-font-weight-bold">Display 300 (18px) - Bold</li> |
| 107 | + <li class="hds-typography-display-300 hds-font-weight-semibold">Display 300 (18px) - Semibold</li> |
| 108 | + <li class="hds-typography-display-300 hds-font-weight-medium">Display 300 (18px) - Medium</li> |
| 109 | + <br/> |
| 110 | + <li class="hds-typography-display-200 hds-font-weight-semibold">Display 200 (16px) - Semibold</li> |
| 111 | + <br/> |
| 112 | + <li class="hds-typography-display-100 hds-font-weight-semibold">Display 100 (13px) - Medium</li> |
| 113 | +</ul> |
| 114 | + |
| 115 | +### Body |
| 116 | + |
| 117 | +Body styles should be used for all general page content. Commonly placed within components (like buttons) and blocks of text, this style supports different font weights and sizes to establish a clear visual hierarchy. Body 200 is used as the default body content size as the majority of HashiCorp products are data dense. Body 100 is often used as secondary text for hierarchical purposes while Body 300 is used for bigger UI elements like the `large` variant of the Button component. |
| 118 | + |
| 119 | +Body text styles are available in the following weights and sizes: |
| 120 | + |
| 121 | +<ul class='doc-typography-demo-display-list'> |
| 122 | + <li class="hds-typography-body-300 hds-font-weight-semibold">Body 300 (16px) - Semibold</li> |
| 123 | + <li class="hds-typography-body-300 hds-font-weight-medium">Body 300 (16px) - Medium</li> |
| 124 | + <li class="hds-typography-body-300 hds-font-weight-regular">Body 300 (16px) - Regular</li> |
| 125 | + <br/> |
| 126 | + <li class="hds-typography-body-200 hds-font-weight-semibold">Body 200 (14px) - Semibold</li> |
| 127 | + <li class="hds-typography-body-200 hds-font-weight-medium">Body 200 (14px) - Medium</li> |
| 128 | + <li class="hds-typography-body-200 hds-font-weight-regular">Body 200 (14px) - Regular</li> |
| 129 | + <br/> |
| 130 | + <li class="hds-typography-body-100 hds-font-weight-semibold">Body 100 (13px) - Semibold</li> |
| 131 | + <li class="hds-typography-body-100 hds-font-weight-medium">Body 100 (13px) - Medium</li> |
| 132 | + <li class="hds-typography-body-100 hds-font-weight-regular">Body 100 (13px) - Regular</li> |
| 133 | +</ul> |
| 134 | + |
| 135 | +### Code |
| 136 | + |
| 137 | +Code styles are used exclusively for text representing code in the UI (like the [Code Block component](/components/code-block)). |
| 138 | + |
| 139 | +Code text styles come in the following weights and sizes: |
| 140 | + |
| 141 | +<ul class='doc-typography-demo-display-list'> |
| 142 | + <li class="hds-typography-code-300 hds-font-weight-bold">Code 300 (16px) - Bold</li> |
| 143 | + <li class="hds-typography-code-300 hds-font-weight-regular">Code 300 (16px) - Regular</li> |
| 144 | + <br/> |
| 145 | + <li class="hds-typography-code-200 hds-font-weight-bold">Code 200 (14px) - Bold</li> |
| 146 | + <li class="hds-typography-code-200 hds-font-weight-regular">Code 200 (14px) - Regular</li> |
| 147 | + <br/> |
| 148 | + <li class="hds-typography-code-100 hds-font-weight-bold">Code 100 (13px) - Bold</li> |
| 149 | + <li class="hds-typography-code-100 hds-font-weight-regular">Code 100 (13px) - Regular</li> |
| 150 | +</ul> |
| 151 | + |
| 152 | +## How typography is used |
| 153 | + |
| 154 | +### Body content |
| 155 | + |
| 156 | +Body 200 is the default font size for body content. Scaling up or down is used as a means to create visual hierarchy in page UI, or component usage. As an example, the Button, `medium` (default) variant is sized at Body 200 while the `large` variant is Body 300. |
| 157 | + |
| 158 | + |
| 159 | + |
| 160 | +Similarly, form fields' labels and input texts are Body 200, while any other secondary information, like helper text or error messages are sized at Body 100. This ensures that primary information is more prominent with the larger size for visual hierarchy. |
| 161 | + |
| 162 | + |
| 163 | + |
| 164 | +For more details about form patterns, read the [form patterns](/patterns/form-patterns) documentation. |
| 165 | + |
| 166 | +### Semantic heading or not? |
| 167 | + |
| 168 | +The [Text](/components/text) component does not equate a specific style (Body, Display, or Code) with a specific HTML semantic structure (like `<p/>`, `<h1/>` or `<span>`), it is up to the consumer to define the logical semantic element for the each piece of text. To ensure accessible page content, the scaling of the Display styles often are associated with the scaling of the HTML headings such as: |
| 169 | + |
| 170 | +- Display 500 → H1 |
| 171 | +- Display 400 → H2 |
| 172 | +- Display 300 → H3 |
| 173 | +- Display 200 → H4 |
| 174 | +- Display 100 → H5 |
| 175 | + |
| 176 | +In general we recommend mapping Display font sizes sequentially to markup, but this is not always possible. Additionally, Display text styles do not always need to be headings. They may be used to emphasize important information, such as remaining balances, so that users are able to visually understand the level of importance of information on the page. |
| 177 | + |
| 178 | + |
| 179 | + |
| 180 | +An important note: The card is still following the semantically correct logical order of headings, where “Total period usage” is a heading (an H3 with semibold weight), while the balance below it is not (medium weight as a span or paragraph). Font weight is used to create the visual hierarchy here instead size. |
0 commit comments