Typography improvements in Totara 19
As part of our ongoing effort to enhance the quality, accessibility, and user experience of the Totara Suite, we have made changes to the product typography in version 19. Here we have outlined the changes that have been made, the impact this will have on all sites, and whether additional changes will need to be made by Totara Partner developers.
What has changed?
The site name is no longer set as the main heading (using the h1 tag) on all pages. Instead, the primary heading is now the page title (e.g. the course name when on a course). We have made a considerable effort to implement this change across all core Totara pages.
This change was made to improve accessibility, user experience, and alignment with web standards. By using the page title as the main heading instead of the site name, it enhances content hierarchy, making it clearer and more intuitive for users to navigate. This approach also ensures better compatibility with screen readers and other assistive technologies, as it follows a logical structure that helps users understand where they are on a page and what content is prioritised. Overall, it aligns Totara with WCAG guidelines for accessible, structured content.
Impact on sites
This should have no adverse impact on standard Totara pages without custom theming. In the case where custom styles have been applied to headings you may need to confirm they are still relevant or whether they need to be reapplied based on the new heading structures.
Impacts will be seen where plugins outside of the Totara team’s control have their own pages. In these cases, the plugin developers will need to ensure that their pages follow the new heading structure by setting the page title as the main heading (h1). This will involve reviewing their heading hierarchy to avoid skipped levels and maintain logical ordering, which is essential for accessibility and a consistent user experience across the platform.
Guidance for site configuration
While improving main page title structures, we acknowledge that some key pages have not had visual page headings for some time, notably dashboards and course pages. For new site installations, both dashboards and courses will have visually apparent page titles, while for upgraded sites they will not. Both dashboards and courses have new configuration settings so that you can opt in or out of this approach.
The new settings can be found in the following locations:
Quick-access menu > Navigation > Dashboard settings (totara_dashboard | show_title)
Quick-access menu > Courses > Course settings (course_heading_visible)
Guidance for plugin developers
When creating a standalone page, ensure that the page’s name is in a h1 tag. The preferred way of doing this is to use $PAGE->page_main_heading('page title') when rendering the page through PHP or adding a <h1> tag on a Tui page. Other means to output an h1 tag include $OUTPUT->heading('page title', 1); and html_writer::tag('h1', ‘page title'). We also recommend confirming other headings have a logical order when viewing the page (h2s are subtitles, there are no skipped heading levels).
Guidance for themers
Headings
To avoid having multiple h1s on a page, confirm that your theme does not output an h1 in a page layout (previously we supplied the h1 on the theme_legacy/site_logo mustache template).
As well as having semantically appropriate page title structures, our changes have also accommodated cases where a title may need flexibility with its markup, and so there are now CSS classNames that can be applied that result in the same visual appearance as a semantic title, without the semantic markup underneath.
Font sizing and helpers
We have changed the definition of REM to be 16px instead of 10px, so if custom theme changes rely on REM it is advised to check any adverse changes. A portion of typography-related CSS variables and mixins are being deprecated, stylelint rules are in place to help to catch usages.
Previously, the value of 10px was chosen for ease of mental calculation, but is an atypical approach otherwise. To compensate for the calculation change, we have introduced a SCSS helper named rem-px(), for example using rem-px(10) will result in a value of 0.625rem, which is "10px visual sizing" but declared with a `rem` unit so that measurements scale well with User Agent controls.
We have introduced a layer of base typography sizing that applies to font, line-height and icon base sizes, so that now and in the future they can work independently of each other.
There are also now a selection of font style helpers (for example, define-font()), to improve how you override font style variants with themes.
Miscellaneous improvements
Improvements to bottom margins on several base typography elements have been made, to improve the vertical rhythm and general readability of on-screen text.
Hyphenation has also changed; our previous approach was implemented when Internet Explorer 11 was still a baseline User Agent we supported. That requirement has gone, and so we now prefer to introduce hyphenation that improves readability, rather than meet a ‘lowest common denominator’ across browsers.
User-generated content also now receives a wrapping element based on the type of output renderer responsible, and what created the content. For example, `legacy-rendered` for older WYSIWYG output, `tui-rendered` for Weka output, and also `generated-content--user` so that in the near future we can also add other creation classNames such as `generated-content--ai`.
Known issues with third-party plugins
We’ve tested the following commonly used Moodle plugins and have identified that these areas will now be inconsistent with the improvements made in Totara 19:
BigBlueButton - this has a number of incorrect heading levels (and has some skipped heading levels)
Custom Cert - a number of headings will need to be promoted
On the Job Training - most pages will need their heading promoted
Future direction
We plan to make further enhancements to our page title structures throughout the development lifecycle of Totara 20. To ensure clarity and minimise any unexpected impacts, we will keep you informed of these changes in advance of any release.