Style Guide

Intro

Use this Style Guide to provide guidance for writing and display of text within ESD products.

The way we write within our products is an important part of the overall experience, and should be taken as seriously as the way we create design patterns or develop code.

Tone

The tone of our language is one important way that we convey the personality of our products. Be sure to let that personality show. Try to be:

• Confident and capable, like a seasoned professional

• Friendly and approachable, like a helpful co-worker

• Guiding but not pushy, like a teacher helping to discover

Formality

Text that you write should be conversational but brief. Use plain language, and avoid colloquialisms, slang or excessive humor, since these can be easily misunderstood. Write like you're speaking to a work peer. This helps to make your message more consumable and also conveys a friendly and easy-to‑use personality.

Using contractions and other informal language is acceptable, but remember that users have differing levels of language proficiency. Your goal should always be to maximize clarity and comprehension for all users.

User-Centered Language

Avoid technical language, jargon or acronyms that your users wouldn't know or don't use regularly. Try to write for the person reading, and avoid language that requires them to perform too much mental processing, or know additional information that may not be displayed. Don't describe the inner functioning of the application when more user-centered language is possible.

Politeness

Be polite without overdoing it. Treat users like you're a friendly co-worker. It's OK to be direct, as long as you're not pushy.

Use "please" only when asking users to correct a situation that was a result of technical error within the application. In short... if something's our fault, use please; if it's their fault, don't.

Voice

Use an active voice whenever possible. You're speaking to a person, so tell them what they need to know and do. It promotes clearer and more direct language, and tends to drive action. If you're not sure that you're using an active voice, try a passive voice detection tool.

Writing for Accessibility

Our products are used by people of all abilities, and our goal is to make our content useful and consumable for the widest possible audience. The way we write has a significant impact on how users understand what we're telling them, and directly contributes to their ability to use our products successfully.

There are many aspects to accessibility, but in this style guide we'll specifically address how to write text for all users. For further guidance on other areas of accessibility, read the Mineral Accessibility Guidelines.

Visual and Directional Language

Avoid language that refers to the appearance of the UI. Things like direction (left/right/up/down), color, or describing shapes or images can mean very little to people who have visual impairments.

Structure and Consumability

How text is structured can make it easy to read and consume. Be brief when you can, and try to exclude anything that isn't meaningful to users. Simpler text is easier to consume, so target a reading level as low as possible (depending on the context of your product). Text that has a reading level of 8th grade or lower is considered easy to consume for most users. If you're not sure how complex your text is, try using a reading level analyzer tool.

Use heading styles instead of text formatting. Screen readers can sometimes read out any text formatting, and that can be distracting or cumbersome when not needed.

Avoid using forced line breaks (usually shift plus return). This can cause text to break in awkward ways and make reading difficult for people who read text on different sized screens, or at enlarged text sizes.

Avoid all caps or camel case unless specific words require it. Some screen readers will read capitalized letters individually, which can be awkward when not needed.

Speaking to All Users

Avoid language that defines people by their disability, or lack thereof. When needed, refer to them as people who happen to have a disability, not as disabled people. Do not compare people with disabilities to those without, or refer to people without disabilities as normal or average.

Avoid language that may be perceived as derogatory to people with disabilities.

If you have created accessibility features, like alternative input methods, be sure to describe those along with other descriptions. Avoid language that implies a particular interface use, like click, swipe, or refers to a visual element.

Link and Button Text

When writing link text, clearly describe the destination the user will be taken to. In most situations that should be the page or screen title, spelled and capitalized exactly the same way as it appears on that destination page. Don't include other descriptive text within the link itself.

For buttons, use text that precisely describes the action that the user is taking. It should start with a verb. Be as brief as you can while still prioritizing clarity. Don't reduce the amount of text beyond the point of clarity.

Use an elipsis at the end of the button text if it launches an activity with more steps, like saving with a new name or pausing for a user-specified period of time.

Capitalization

Capitalization of page/screen titles, section titles (of all levels), column headings, button text and other non-content UI elements should be capitalized using Title Case.

Rules for Title Case:

• Capitalize words with three or more letters

• Capitalize the first and the last word

• Capitalize nouns, pronouns, adjectives, verbs, adverbs, and subordinate conjunctions

• Lowercase articles (a, an, the), coordinating conjunctions, and prepositions

• Lowercase the ‘to’ in an infinitive (We need to open the door)

Vertically and Horizontally Oriented Text

Avoid text that is oriented vertically on the page whenever possible. In order to be readable for people with all levels of visual and cognitive ability, text should always read horizontally (left-to-right, or right-to-left if appropriate for the language displayed).

Describing File Formats and Extensions

File format and extension names may be written out fully or as their typical three or four character extension. When referring to a proprietary application, capitalize its name. When referring to a format by its extension, capitalize the entire extension.

Emojis

Avoid the use of emojis in typical content. Use provided or custom icons to communicate visually when appropriate, as they are more professional and less likely to be misinterpreted. In places where humor is expected, rare uses of emojis may be acceptable.

Text Truncation

Text that is part of the UI should never be truncated, e.g. page titles, button text, section headers. On occasion, content text may be truncated with the addition of an elipsis (...). For clarity and consumability, text should not be truncated unless there is insufficient space to display the full text. When truncating text, strive to display enough of the text that it is still readily understood by users.

Language Names and Codes

When displaying a language name or referencing any language, there are 2 situations you may encounter:

Full Names

When referencing a language within long-form text or instructional text, or when space is not prohibitive, spell out the entire name of the language with the first letter capitalized. When doing this, use a language’s ISO country name. If further clarification is needed, the ISO name may be used in combination with a language’s native name or language code. See below for more information regarding language codes.

Language Codes

When referencing a language in UI functionality, URLs, tabular data and other display purposes where spelling out the name is inappropriate or space is limited, use the 2-character language code defined in the international standard ISO 639-1. Avoid the 3-character codes that are defined in ISO 639-2 and 639-3. Language codes should be all lowercase.

Country Names and Codes

When displaying a country name or referencing any country, there are 2 situations you may encounter:

Full Names

When referencing a country within long-form text or instructional text, or when space is not prohibitive, spell out the entire name of the country with the first letter capitalized. When doing this, use a country’s common name as defined in ISO 3166, not its official name. If further clarification is needed, the common name may be used in combination with a country’s code. See below for more information regarding country codes.

This feature is not available in United States of America or Mexico.

This feature is not available in United States of America (US) or Mexico (MX).

- not -

This feature is not available in The United States of America or The United Mexican States.

This feature is not available in USA or MX.

Country Codes

When referencing a country in UI functionality, URLs, tabular data and other display purposes where spelling out the name is inappropriate or space is limited, use the 2-character ISO 3166-1 alpha-2 country code. Avoid the 3-character and numerical codes that are also defined in ISO 3166. Country codes should be fully capitalized.

Country-based Internet TLDs mostly follow ISO 3166-1 alpha-2 codes.

Numbers

Numbers may be formatted in different ways, depending on language and geographic location. To address this, you should approach number formats using these options:

Best Option:

To best accommodate for user expectations, it is recommended to programmatically localize number formats whenever possible to maximize both clarity and usability.

Alternative Option:

When localization or utilizing user preference is not available, use one of the following formats.

English Common Format: As English is a commonly spoken language in business world-wide, this format will be familiar to many users

International System of Units Format: Follows an international standard, and will be familiar with users in the scientific community

English Common Format

When using this format, numbers should use three-digit grouping, with each group separated by a comma. The decimal separator should be a period. There should be no spaces between any digits and any separators.

International System of Units (SI) Format

When using this format, numbers should use three-digit grouping, with each group separated by a thin space. The decimal separator should be a comma, to be familiar with users in the largest number of localities. There should be a thin space between any three-digit groups after the decimal separator.

This format is consistent with Resolution 10 of the 22nd General Conference on Weights and Measures (2003).

Number Sets

Use the Arabic number set, i.e. 0123456789, when conveying quantity information. Avoid using roman numerals or other number sets to convey quantitative information. Many users are not fully familiar with other systems, and it can complicate comparison and display of information.

It is acceptable to use other number sets if they are used in a proper name or official designation.

Number Names and Abbreviations

There are two forms of number names currently in use worldwide, Short Form and Long Form. Short Form is based on thousands of units and is commonly used in the USA and UK, while Long Form is based on millions of units and is used in EU. Because much of the business and financial worlds use Short Form, avoid Long Form when possible.

Large numbers can be difficult to read at times, so they may be abbreviated to reduce visual complexity or space used. Only abbreviate large numbers when absolute precision is not needed, as some rounding may be needed to effectively reduce the number of characters displayed.

When using an abbreviation, display a number followed by the abbreviation, with no space.

Whenever abbreviations are used, there is some chance of misinterpretation. To minimize this, consider spelling out the number name when space allows. When using the number name, display the number, followed by a space, then the name.

Large number abbreviations should be used for summary-level data only, and should be rounded to no more than two decimal digits.

Don’t use abbreviations without a corresponding number of units.

Decimals and Fractions

Number values that are between zero and one, or zero and negative one, should be written with a preceding zero, the decimal separator appropriate to the number formatting scheme chosen, then the numerical value.

Avoid using fractions written as ½, ⅓, ¼, etc. These make quick comparison more cumbersome and add unnecessary cognitive load on the user.

Rounding

Rounding numbers may be needed at times to reduce visual complexity, cognitive load or space used. Rounding numbers should follow these rules:

• Choose the appropriate number of decimal places so that they offer a useful amount of detail for the purpose they are used, e.g. 1.2 seconds, not 1.23456789 seconds

  • Large numbers and summary numbers should be limited to one or two decimal places.

• If the first digit to be dropped is less than 5, the last retained digit is not changed.

• If the first digit to be dropped is greater than or equal to 5, the last digit retained is increased by 1.

  • 6.1273 is rounded to 6, 6.1, 6.13, 6.127

  • 6.6888 is rounded to 7, 6.7, 6.69, 6.889

• Calculations used to summarize or otherwise aggregate more than one number, should use the original (un-rounded) numbers for the initial calculation, and then round the resulting number. Avoid using rounded numbers in calculations, and round the resulting number again.

• When it’s not possible to avoid multiplying or dividing rounded numbers, the resulting number cannot be more precise than the least precise number used in the calculation.

  • Multiplying 4.5 and 5.75, which are rounded numbers, equals 25.875. In this case, the product can be stated only as 26 (rounded to two significant digits), because 4.5 has two significant digits and therefore limits the precision of the result.

• Tables, charts and graphs that use rounded numbers and logically should sum to 100% (e.g. a pie chart), or to a specific numerical value, should display a message informing users that rounding was used, e.g. “NOTE: Detail may not sum to totals because of rounding”

When listing multiple values, decimal separators should always align.

This is consistent with Standard 5-3 of the National Center for Education Statistics.

Relative Phrases and Symbols

In cases where exact precision is not needed, it is acceptable to use relative phrases or symbols to save space or complexity. When using a relative phrase or symbol, write out the phrase or symbol, followed by a space, then the number.

Negative Numbers

Negative numbers can be represented in a couple different ways. For most purposes, use a minus symbol, “−” (not a hyphen or en-dash), then the number.

In cases where financial information is being presented in a ledger format, using parentheses is acceptable, as long as its use is consistent within the application.

It is acceptable to render a negative number in red text (with red parentheses or minus sign), but for accessibility reasons, this must be in addition to either the minus symbol or parentheses. Red text should never be used as the sole method to convey a number is negative.

Percentages

Percentages should be represented by writing the number, followed by a percent sign, “%”, with no spaces.

When referring to a portion of a total, avoid writing percentages as decimal values without a percentage sign.

Number Ranges

When writing number ranges, write the first number, followed by an en-dash, “–”, then the second number, with no spaces. To avoid confusion, do not use any shortened or abbreviated range styles, e.g. the Chicago Manual of Style.

Currency Formats

When referring to currencies, there are two possible formatting options.

Single Currency

In situations where there is never more than one currency displayed anywhere in a single experience, then you may display the currency in one of two ways:

Using the common currency symbol for the single currency in use:

As a plain number, but labeled in-context:

Because currency symbols are sometimes shared by more than one currency, it’s important to avoid this format when multiple currencies must be displayed.

Multiple Currencies

When a single experience must display more than one currency, write the 3-letter currency code in all capital letters, followed by a space, then the numerical amount.

Display minor unit or sub-unit amounts with the correct number of decimal places when needed. Various currencies may allow for 2-4 digits after the decimal. When displaying currencies in a table, ensure that the currency codes are aligned and the numerical amounts are aligned to the decimal separator.

Avoid combining the 3-letter code with a currency symbol.

This is consistent with the ISO 4217 format.

Counting Data

When counting or measuring quantities of digital data, you can write the name of the measurement or its abbreviation.

When writing a name, write the number, followed by a space, then the name.

When using the abbreviation, write the number, followed by a space, then the abbreviation.

Phone Numbers

Since each country has its own standard for formatting phone numbers, it’s necessary to determine if an experience needs to display phone numbers for the user’s current country only, or if displaying international numbers is needed.

Intra-Country

In situations where only phone numbers from inside the current country are displayed, it’s acceptable to use the national phone number notation format for that country. Each country has its own format, so to ensure phone numbers are easy to read, be sure to display the proper format.

Inter-Country

In situations where phone numbers from more than one country are displayed, or phone numbers from outside the user’s country are displayed, use the International Telecommunications Union E.123 standard. This standardizes parts of the phone number format, while leaving grouping of the local portion of numbers to be addressed by the national phone number format.

To follow E.123, be sure to:

• Begin the number with a “+”. The “+” is shorthand for the origin country’s international call prefix or exit code. Do not display the exit code itself.

• Next, display the country code, and then the regional area number and local number

• Spaces should be used to separate country code, regional area number and local number

• Spaces should be used to separate groups of numbers within the local number

• In the local portion of numbers, you can use an explicit symbol (e.g. hyphen) to space number groups, if it is “necessary for procedural purposes." This isn’t common.

Dialable extension numbers should be added after the local number, preceded by a space, with no other characters labeling it as an extension. Non-dialable extension numbers should be separated by a space, then display the user’s local equivalent of "extension" or "ext.", followed by the extension number.

Dates

There are many accepted formats for dates, influenced by geographic location and other factors. As a result there can be some ambiguity when reading dates intended for varying audiences. To address this, you should approach date formats using these options:

Best Option:

To best accommodate for user expectations, it is recommended to localize date formats whenever possible to maximize both clarity and usability.

Alternative Option:

When localization or utilizing user preference is not available, use one of the following formats.

Long-form date format: it is familiar, generally more easily read, and eliminates possible confusion associated with misinterpreting number-only formats

Number-only date format: often uses less space, and follows an international standard

Long-Form Date

When using this format, spell out the month, followed by the date, a comma, then a four digit year. An abbreviation for the month may be used when space is limited (see abbreviations below).

You may add a day preceding the date (see abbreviations below), if needed, followed by a comma. This doesn’t always add value, so be sure this is fulfilling a need before inclusion. An abbreviated day may be used if you’ve also chosen to abbreviate the month. Don’t mix abbreviated and full terms in the same date.

When there is no chance of confusion around the year, e.g. when the date is already associated to a year in a list or in a constrained context, the year may be omitted. If the year is omitted, do so for all dates. Do not mix date formats within the same content area.

Preceding Zeros

Avoid using preceding zeros in days represented by single digits.

Ordinal Numbers

Don’t use ordinal numbers in dates, e.g. 1st, 2nd, 3rd.

Day and Month Abbreviations

Use these three-letter day abbreviations when needed, to save space.

Always capitalize days and months, and their abbreviations. Do not use a period following the abbreviation.

Number-Only Dates

Number-only formats are where much of the confusion around date formats occurs, because the common order of the three numbers for year, month and day may change based on geographic location.

For Example:

01/12/21

Depending on local differences and intended audience, this may be interpreted as:

• January 12, 2021

• December 1, 2021

• December 21, 2001

To avoid this ambiguity, use the fully written out format. If space prohibits this, or if you need to follow an international standard, then use the format YYYY-MM-DD. This follows the ISO 8601 international standard.

To use this format, write the four-digit year, two digit month, and two digit day. Use a hyphen, “-”, as the divider.

There is no provision in the current ISO 8601 standard for omitting year.

Times

Like dates, times can be written in different formats. To address this, you should approach time formats using these options:

Best Option:

To best accommodate for user expectations, it is recommended to localize time formats whenever possible to maximize both clarity and usability

Alternative Option:

When localization or utilizing user preference is not available, use one of the following formats.

12 Hour Clock: generally considered to be more friendly feeling and readable

24 Hour Clock: often uses less space, and follows an international standard

12 Hour Clock

Use a 12 hour clock when expressing a time of day. Times should be written with hours, minutes, and seconds (if needed), followed by either “AM” or “PM”. AM and PM should be capitalized, contain no periods, and be preceded by a space.

A colon, “:”, should be used as the divider. Do not use a preceding zero in single-digit hours, but do so in single-digit minutes and seconds.

You may use “noon” or “midnight” in text, but avoid their use in tabular data, as they do not lend themselves well to visual comparison or sorting.

Time Zones

If needed for clarity, you can label times with their appropriate time zone abbreviation. These abbreviations can be ambiguous at times, so they should not be used alone. Always provide a reference to UTC (Coordinated Universal Time).

The reference to UTC should be written using a minus, “−”, (not a hyphen or en-dash); or a plus, “+”.

24 Hour Clock

24 hour clock is often considered to be more precise but also more technical feeling. Consider your audience before selecting this format. This follows the ISO 8601 international standard.

Times should be written with hours, minutes, seconds (if needed). A colon, “:”, should be used as the divider, and will be formatted as HH:MM:SS. Preceding zeros should be used for all single-digit numbers.

Time zones should not be used with the 24 hour clock. Rather, the ISO 8601 standard requires that time be represented in one of three ways: unqualified (no time zone info), as UTC (Zulu), or as an offset from UTC.

The offset from UTC should be written using a minus, “−”, (not a hyphen or en-dash); or a plus, “+”.

Combining Dates and Times

Combinations of date and time should be one of these two approaches.

Long-Form date + 12 Hour Clock: most user-readable combination

Number-Only date + 24 Hour Clock: often uses less space, and mostly follows an international standard

Avoid combining long-form date with 24 hour clock, or number-only date with 12 hour clock.

Long-form date + 12 hour clock

When using this combination, write out the date, followed by a space, then the time.

Number-only date + 24 hour clock

When using this combination, write out the date, followed by a space, then the time. This follows the ISO 8601 profile RFC 3339 document, but not strictly the final ISO 8601 standard.

This approach maximizes the readability of the date and time combination over the final standard, which replaces the space with a “T”.

Time Units

Units of time may be spelled out or abbreviated. Whichever type you select, be consistent within the same context. They should be lower case, be preceded by a space and have no period after them.

Spelled out units should be plural when referring to numbers greater than 1, but abbreviated units should not be made plural.

Durations

Durations can be written in any units needed, in descending-length order, with a time unit indicator for each number.

Decimals are acceptable when referring to seconds or milliseconds.

Do not use number-only formats for duration. They may be misinterpreted to be times.

The ISO 8601 standard for writing durations is extremely complicated and requires some education for it to be user-readable. Avoid this unless your audience is properly trained.

Date and Time Ranges

Date or time ranges can be written using your selected date and time formats, with an en-dash, "–", separating the beginning and end of the duration.

If using dates or times that follow the ISO 8601 standard for dates or times prescribed above (number-only date and 24 hour clock), use two hyphens, “--”, to separate the beginning and end of the duration.

ISO 8601 also has the ability to use a forward slash, “/”, as the separator, but this may be unfamiliar to some users and therefore less readable. Avoid this usage.

Relative Dates and Times

Relative dates and time may be used when appropriate to give a more friendly feeling, or to reduce some mental processing when reading dates.

When using relative terms in combination with a number, time or words, separate them with a space.

When using relative dates and times, it is recommended that you give the user access to the absolute date or time, e.g. in a tooltip visible by hovering over the relative date/time text.