Your best behavior
The following is a collection of patterns that describe standards and conventions which provide the rules that help govern content within the design system. Localization must be kept in mind while thinking of these patterns as some might be altered to support other cultural expectations.
Curating patterns to your user's cultural expectations will always provide a better experience. However, knowing all the distinctions between groups of people and their behaviors are very challenging. The sections below attempt to call out some expected differences in behavior. Examples are often tagged with a language and country combination which identifies a certain content format for the provided locale.
The table below has a list of most of the possible combinations. The list is also available as a json file.
Communication is the way in which we share ideas and language is a tool we use to communicate. Transmitting the right message to your audience is key toward providing a encouraging experience for the user.
Ensure that abbreviations aren't tailored to a specific audience unless the abbreviation has been well-defined prior to use within context of the message. For example, abbreviating new technologies should first be defined before use. Abbreviations with measurement units can be used with an assumption that they exist as common knowledge.
When using unfamiliar words or concepts, put the word in quotations and then define the word soon after in a following sentence. Otherwise, attempt to avoid technical language unless it is directed at a specific audience. Aim to be clear with the message by using common language where possible. Consider simplifying or providing analogies.
When providing guidance by categorizing items together, consider using a list. Use a numbered list if the order of the items is important, otherwise a list using a symbol marking the item from body text is appropriate. Use a leading sentence to describe what is expected within the list. Do not indent the list more than twice; consider creating a separate list with leading text instead. Attempt to craft each item similarly to the others.
Files, folders, and urls
When referencing a file by name, ensure it matches exactly to how it would be found within the operating system. Include the file extension or describe the type of file by the application expected to open it. If expecting a user to traverse a system, be clear in technical commands. Do not assume the user knows what any one command means. Offer both graphical user interface guidance as well as command-line interface commands when possible, depending on the audience.
When providing a url, do not include the protocol (
https://) or subdomain (
www) unless the resource is inaccessible without it. If the url can be shortened, consider this for better accessibility where the url may not be interactive; when printed for example.
Proper nouns are captialized in writing styles which include the differentiation of glyphs. Unless the style of the text is altered to signify a different context. In this design system, large headings have no capitalization while smaller headings, actions, labels are all uppercase.
Use proper punctuation in bodies of text, using proper localized methods. Headings, labels, and actions. Helping and error text for form inputs are also punctuated.
Use numerals when counting, do not spell numbers unless they are larger than 6 digits. In this exception, you may used named numbers. Some names are localized depending on the scale.
- 3 apples
- 100 large ducks
- 1 million people
Localization of units is typically in Metric, except for a few countries. Please refer to the list of metricified countries to determine if special changes must be made based on locale. Abbreviations are permitted as long as they are non-ambiguous to other units.
Use decimals with a maximum precision of 2 places after the decimal, unless the additional decimals are signifigant to the context. Ensure the decimal separator is localized. Avoid fractions.
zh-CN1 234 567.89
fr-FR1 234 567,89
Use numerals when providing percentages, pay attention to localization methods of using the percent sign (%).
fi-FI20. joulukuuta 2012
en-PH20 December 2012
es-AR20 de diciembre de 2012
en-PH+63 (XXX) YYY ZZZZ
tr-TR0BBB AAA AA AA
Use a localized format for displaying currencies. Position of the currency symbol may differ between locales. Refer to decimal reference above. Negative numbers are also formatted differently between locales.
A simple method of localizing most of the above numbers can be done using the
Intl constructor found in modern browsers.
This method is especially recommended to provide solutions for displaying currency.
Icons can often help in small areas or where translation is difficult. We should always attempt to include text along with an icon for the best approach at clarity in meaning, as some icons could be considered non-standard and universal icons are rare.
They can be effective in enhancing visual interest, focusing users' attention, and help in wayfinding. Everything in moderation; use too many and the interface may become distracting.
Instead of designing all of the icons from scratch, this system leverages the outlined icon set provided by Material Design.
For techniques on curating custom icons, please refer to A complete guide to iconography.
Throughout the site, icons are usually handled with a custom web-component which was a decision based on the exploration outlined in The Road to SVG and Custom Elements in Clarity Icons. The implementation here is just a light wrapper for a project called
Savager which handles all of the messy SVG failsafes. Icons are rendered using a reference sheet on the page. This keeps the external requests low but would bloat a page with a system that has many icons.
You could host SVGs externally but the drawback is SVGs are susceptible to CORS. If you were to host the SVG group file on a CDN, it would need to be under the same domain.
Savager does a similar injection for web components because the reference does not cross the ShadowDOM. This system also does its icons available externally (example, view source) when that approach is appropriate.
If we consider layout as designing in two-dimensions, and elevation as the third, we could include motion as the fourth. Motion can help introduce elements of the interface smoothly. It can focus a user's attention and also add character to elements when used subtly.
Motion is added to this design system so that it largely unnoticed. Small transitions are added in elements that appear or disappear, which includes the page itself after loading. Interactive elements may also include subtle changes between states instead of instance ones. It is important to add these moments thoughtfully to not detract from the overall experience and the user's goals.
The system uses the default easing curves provided by CSS as the duration is often too short (0.218 milliseconds) to notice a difference with a custom easing function. Additionally, there are no guidelines in choreography between multiple elements as most are built with very few parts, and only one with animation, if any.
A reduced motion media query is applied to help with accessibility as some types of motion can cause users discomfort or uneasiness. We allow users to select a reduced motion option from within the browser's settings and make changes on this site accordingly.