Typography (beta)

Our typography principles are designed to guide makers in creating the best possible user experiences. When applying typography in digital applications, Atlassians strive to:

To help readers understand communications easily and enhance their experience, regardless of their abilities.

Typography should be consistent and cohesive. Use hierarchy and space to reduce cognitive load, and simplify the complex.

Tailor for various preferences, operating systems and applications, while keeping in mind how users consume and process information.

The accessibility of text is important for all users, and must be considered when creating designs with text. The ADS typography system has been created to make accessible design simple, and ensure the legibility, readability, and visual harmony of text in designs.

We aim to follow the WCAG (AA) standards for text spacing, colour contrast and resizing.

Legibility refers to how distinguishable the letters in a typesetting or font are. We recommend using our typography tokens to utilise our legible fonts, and minimum font size of 16px for long form body text.

Readability refers to the arrangement of fonts and words to make content simple and easy to read. Our text styles have been optimised for readability though our built in line height, letter spacing and paragraph spacing for each style and font.

Choosing an appropriate text size is critical for accessibility, with larger text sizes being easier to read for users. We recommend using at least 16px size wherever possible.

Font weight refers to the thickness or thinness of the characters in a typeface, and can significantly impact the legibility of text. Heavier weight fonts tend to be easier to read and improve legibility.

Text color affects the contrast between the text and its background, which is critical for accessibility, insufficient contrast makes text difficult to distinguish, whereas high contrast enhances legibility.

The Atlassian Design System color tokens have been designed with accessibility in mind, we recommend using the color.text family of tokens and corresponding color.background family of tokens where applicable, for appropriate contrast in both light and dark themes.

Spacing is important for accessibility as it influences the readability of a piece of text. Adequate spacing between lines, words and letters impacts how easy they are to read, and how visually appealing the design is.

The typography system has been designed to align with the existing spacing system in the Atlassian Design System. Using the existing spacing scale and space tokens in conjunction with the typography system ensures accessibility, while improving the visual harmony of designs.

Typescales are a series of font sizes that create visual harmony and hierarchy in designs. Similar to a musical scale, typographic scales are a consistent set of values based on a mathematical ratio.

The ADS typography system uses the minor third scale, where each size is based on multiplying our base size (12px) by a factor of 1.2, that is then rounded up to the nearest integer. Generating our font sizes this way, we ensure that each font size is visually related to the others, which creates harmony within the user experience and clear visual hierarchy.

The ADS typography system type scale ranges from 12px to 48px.

We use our custom font, Charlie Sans, for almost everything brand and marketing — from banner ads to billboards. It was designed to be incredibly versatile with lots of range in terms of tone and playfulness. It can be quirky and expressive when it needs to be, or neutral when the situation calls for something a bit more serious.

Charlie is available in two styles, Display and Text. Use Charlie Display when creating a large branded heading or experience, and Charlie Text for branded body text.

We use native typography for all in-product experiences. This ensures that the UI is optimized to be highly legible, performs well, and is frictionless as you move between Atlassian products and the rest of the system.

We use sans serif fonts, the exception being when you want to display code then you should defer to monospace fonts.

Sans serif

font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen', 'Ubuntu', 'Helvetica Neue', sans-serif;

Monospaced

font-family: 'SF Mono', 'Segoe UI Mono', 'Roboto Mono', 'Ubuntu Mono', Menlo, monospace;

The ADS typography system is made up of three text styles to cover the range of different needs in designs: Heading, Body and UI text.

Headings are clear and succinct descriptions of their following content. Our new heading styles have been mapped from the existing h100 - h900 styles, and are optimised for single or multiple lines of text.

Our new heading styles are consistently bold, and we hope this will address issues with visual hierarchy and inconsistencies often reported by makers.

Heading styles come in a range of sizes, and can be used in a range of contexts, such as:

• building page hierarchy,

• helping users scan large chunks of text,

• providing a title to a page or piece of content,

• as subheadings or eyebrow headings, where there is still only one H1 tag per page (as per Accessibility requirements).

Responsive heading styles

Headings will also include responsiveness to be used when creating for smaller viewports. This rescaling will be baked into our typography tokens and enabled using ADS breakpoints.

Body text is used for long-form experiences where a paragraph or multiple lines of text are required. Body text styles are optimised for reading as a large chunk of information through line height and paragraph spacing. Inline links sit within body text styles and inherit the same font values.

UI text is text used in UI components, and is reserved for text read in a single line with clear actions or guidance. Optimisation for UI text style is significantly different to Heading or Body texts because of its use case, for example because it’s only used for single lines, the line height and paragraph spacing are not a consideration for readability.

Code text styles using monospaced fonts are grouped under UI because they are formatted in a similar manner - read as single lines of text, rather than large paragraphs of information.

All of our text styles are designed to align with the other Atlassian Design System Foundations, and means designers can establish a consistent visual language across their designs, and across products. This creates greater visual harmony and ensures the legibility and readability of text for all users in all viewports.

All of our text styles have been optimised for readability through spacing, including updating line heights and paragraph spacing for body text styles. To align with our spacing system, we’re also looking at the spacing above text in different contexts, and aligning our current margin-top values to our new spacing system values.

Typography should be responsive to different screen sizes, resolutions, and orientations. Responsiveness will be baked into the typography system by altering heading font sizes in different viewports (using ADS breakpoints), while maintaining a consistently large body text for legibility and accessibility.

Aligning typography and color creates a cohesive, visually pleasing interface while enhancing usability and accessibility. The ADS color tokens are designed to ensure sufficient contrast for legibility, and that the text visually aligns with other elements in a design.

We recommend using the color.text family of tokens and corresponding color.background family of tokens where applicable.

Colors have implicit and explicit meanings, particularly when used in conjunction with text. Use the appropriate color tokens to convey this meaning appropriately, for example using color.text.warning for warning messages and color.text.brand for branding.

Capitalization

When using capitalisation in text, it’s important to consider its impact on readability, visual harmony and the voice and tone of the text. Capitalization guides the readers eye and enhances comprehension, and should be used consistently to best serve the content and users.

Refer to the Language and Grammar page for more information on content styling.

DO

• DO use sentence case (capitalizing the first letter of the first word) for all titles, headings, menu items, labels, and buttons.

• DO capitalize proper nouns and product names (i.e. Jira).

• DO be consistent with your capitalization scheme throughout your UI to maintain a professional and clean look.

DO NOT

• DO NOT use all caps for long sentences or paragraphs. It can be difficult to read and may come off as "shouting" to the user.

• DO NOT mix different capitalization styles in the same context. It can lead to a disjointed and confusing interface.

When formatting text with font weights, it's important to create a balance between style and readability. We recommend only using the four font weights provided by ADS typography, they are designed to be used with the available typefaces.

DO

• DO use varying font weights to create hierarchy and emphasis. Bold weights can be used for headings or to highlight important phrases or words. Use consistent weight fonts for body text.

• DO ensure the chosen font weight is suitable for the chosen font. Some fonts may not display well at certain weights.

• DO consider the legibility of the font weight, especially for longer texts and smaller sizes. A medium weight is often a good choice for body text.

DO NOT

• DO NOT use excessively light or heavy font weights for body text as it can be difficult to read, especially for users with visual impairments.

• DO NOT use too many different font weights in a single design. It can create a cluttered and inconsistent look.

• DO NOT rely solely on font weight to indicate hierarchy or emphasis. Use it in combination with other elements such as size, color, and spacing.

Italics

Italics can be a useful tool for emphasizing text, indicating titles, or representing new or technical words. However, they should be used sparingly.

DO

• DO use italics to emphasize a specific word or phrase, but use them sparingly.

• DO use italics for titles of books, movies, artworks, or to denote new or technical words.

• DO ensure that the italicized text is still legible. Use the ADS typography typefaces and larger text sizes to ensure that the text is legible on different view ports.

• DO pair italics with other text styles for a balanced look.

DO NOT

• DO NOT use italics for long sections of text as it can be difficult to read for large sections of text.

• DO NOT use italics for important information that needs to stand out. Bold or larger text might be more effective.

• DO NOT use italics if they don't add value or improve understanding. Overuse can dilute their impact and cause confusion.

Line lengths

Line length, or measure, refers to the horizontal distance occupied by a block of text. It plays a crucial role in readability and contributes to the balance of a design. The goal of setting line lengths is to provide a comfortable reading experience for the user.

DO

• DO aim for a line length of about 60-100 characters, including spaces. This range is often suggested for English language text to maximize readability, and needs to be considered in internationalisation.

• DO adjust line length according to the device and screen size. Shorter line lengths are more suitable for mobile devices.

DO NOT

• DO NOT use excessively long line lengths. It can make the text difficult to read as the reader's eye will have a hard time focusing and locating th next line.

• DO NOT use large blocks of extremely short line lengths. It can disrupt the reader's rhythm due to frequent line breaks and slow down reading speed.

Lists

Formatting lists appropriately is crucial because it improves readability, makes information digestible, and guides the user through the interface in a logical, clear manner. List items should use the body text type and ADS tokens to ensure the appropriate font, color, size, and spacing is applied.

DO

• DO maintain uniformity in font, color, size, and alignment for all the items in your list to ensure consistency.

• DO use indents for sub-items to clearly differentiate between main and secondary points.

• DO use bulleted lists for unordered items and numbered lists for sequential or ordered items.

DO NOT

• DO NOT include too many items in one list as it can overwhelm the user. Break down long lists into subcategories if needed.

• DO NOT mix bulleted and numbered lists in the same section as it can confuse the user.

• DO NOT mix capitalisation styles in your list. Either consistently use sentence case, or all lower case.

Localisation

Localizing typography involves making necessary adjustments to ensure that text is readable, understandable, and culturally appropriate in different languages. This includes supporting right-to-left languages and handling diacritics (accents) that modify letter sounds.

DO

• DO test the layout in right-to-left mode to ensure elements like punctuation, numbers, and icons display correctly.

• DO use the ADS typefaces that support the character sets of right-to-left languages.

• DO remember to flip graphical elements that indicate direction, such as arrows.

• DO use the ADS fonts that support the diacritics used in the target language.

• DO ensure that the diacritics are correctly placed and do not interfere with the letter spacing.

• DO keep in mind that some diacritics may increase the height of your text lines. Use the ADS type system to ensure that line spacing accommodates this.

DO NOT

• DO NOT assume the design will simply mirror for right-to-left languages. Some elements may need special attention, like navigation menus or buttons.

• DO NOT ignore diacritics, as they can change the meaning of words and can lead to misunderstandings.

• DO NOT use font sizes that are too small to properly display diacritics

Subscripts and superscripts

Subscripts (lowered text) and superscripts (raised text) are often used in scientific texts, footnotes, or citations. Because of their size and placement, care is needed when using subscripts and superscripts to ensure they maintain their legibility in different viewport sizes.

DO

• DO use subscripts and superscripts when necessary, such as in mathematical or scientific text, footnotes, or copyright symbols.

• DO ensure that the subscript or superscript text is large enough to be legible.

• DO ensure that the use of subscripts and superscripts does not affect the line spacing of the main text.

DO NOT

• DO NOT overuse subscripts and superscripts. They can disrupt the reading flow if used excessively.

• DO NOT use subscripts or superscripts for emphasis. Bold or italics are better for highlighting important text.

Text alignment

Text alignment refers to the arrangement of text within a page, column or grid. It can significantly impact the readability and visual harmony of your design. We don’t recommend using indentation.

DO

• DO align text to the left for languages that read left to right. It's the most natural alignment and easy for the eye to follow.

• DO use centered alignment for short texts like headings, captions, or decorative texts. For accessibility, do not use more than two lines of centre aligned text.

DO NOT

• DO NOT use centered alignment for paragraphs longer than two lines. It can be hard to read as the starting point of each line changes, and is important for accessibility.

• DO NOT use justified alignment without proper hyphenation settings, as it can create 'rivers of white space' between words.

• DO NOT mix different alignments in the same paragraph or section without a good reason, as it can look messy and confusing.

• DO NOT use right aligned text unless for internationalization with Right-To-Left languages.

Truncation

Truncation can significantly impact the legibility and comprehension of text. When text is truncated, important information might be cut off, and can lead to confusion or misinterpretation, particularly. This is especially critical in user interfaces where every word can carry important information for user navigation or decision making, and for people using screen readers. Additionally, truncation can disrupt the visual flow of the text, making the design look cluttered or unfinished.

For better accessibility and user experience, truncation should be avoided unless absolutely necessary. Instead, try to design layouts that can accommodate varying text lengths or find ways to responsively adjust the text size to fit the available space.

DO

• DO use truncation when showing a long list of items, such as in a breadcrumb component, and if text can not fit in the space provided, such as body text as a description.

• DO use truncation for text over two or more lines requiring no user input.

• DO use truncation if this is allowed in a component’s usage guidance.

DO NOT

• DO NOT use truncation in text for labels or titles.

• DO NOT use truncation or wrap text in components intended for short UI labels such as lozenges and buttons. Instead, rewrite your content to use fewer words.

Quotes

Quote text can be used to highlight testimonials, references, or key pieces of information. Quotes serve to emphasise a point and provide additional credibility or context.

DO

• DO use quotation marks or other visual cues to clearly denote the start and end of the quote.

• DO use a different font, size, color, or background to distinguish the quote from the rest of the text.

DO NOT

• DO NOT overuse quotes. Using too many quotes in a design or when used without context can confuse a design, and make it harder for users to understand information.