Style Guide

This document defines the styles, vocabulary usage, and content formatting for the Sui documentation.

Editorial considerations {#editorial-considerations}

• Use simple words and concise sentences.
  Prefer plain, direct language over complex or academic phrasing. Short sentences improve readability and are easier to localize.

• Avoid redefining common words.
  Do not give familiar words new or unexpected meanings (for example, do not use "object" to mean something other than its standard technical or everyday sense). This prevents confusion, especially for new readers.

• Use technical terms with care.
  Introduce technical terms only when necessary. Define them clearly the first time, and use them consistently throughout the documentation.

• Avoid jargon and slang.
  Do not assume readers understand informal expressions, company-specific shorthand, or unnecessary buzzwords. Use precise terms instead.

• Prefer active, descriptive phrasing.
  Instead of vague phrases like, "do the thing," explain the action explicitly: "Deploy the contract" or "Restart the node."

• Write for a global audience.
  Keep in mind that many readers are non-native English speakers. Favor clarity over cleverness, and avoid idioms or culturally specific references.

Spelling and grammar

Spelling {#spelling}

Use US English spelling in source content.

Avoid Latin abbreviations {#latin-abbreviations}

Because many languages are not Latin-based, avoid using Latin abbreviations (e.g., i.e., etc., et. al, and so on). Prefer ex. or complete phrases like "for example", "and so on", and similar.

Grammar {#grammar}

Active voice {#active-voice}

Use active voice whenever possible. Active voice is direct, clear, and uses fewer words. Passive voice is often less clear, awkward, and uses more words.

✅ Active: She installed the software.

❌ Passive: The software was installed by her.

Person {#person}

Use second person ("you"). Do not use first or third person ("I" or "we").

✅ You can view the transaction history in the Sui Explorer.

❌ We can view the transaction history in the Sui Explorer.

Present tense {#present-tense}

Use present tense whenever possible. Reserve future tense only for events that will happen at a specific future time, such as a scheduled product release.

Do not use future tense when describing product behavior or writing task instructions. From the reader's perspective, actions occur in the present as they follow the steps.

Example: Present tense

Click Save to save the updated file.
When you click Save, your device writes the changes to disk.
To save a file after you modify it, click Save.

Example: Future tense (avoid)

Your changes will be saved when you click Save.
When you click Save, the file will be written to disk.

Although technically correct, the future tense creates distance between the user and the action. It also makes the text harder to understand for ESL readers and more difficult to localize. In reality, the action happens immediately when the user clicks Save.

Punctuation

1. Sentences

   • Use a period at the end of a complete sentence.

   • Use a single space after a period (never two).

2. Lists

   • Full sentences in lists: End each item with a period.

   • Fragments or single words in lists: Do not use periods.

   • Mixed lists: Avoid mixing fragments and full sentences. Rewrite for consistency.

3. Parentheses

   • If the entire sentence is inside parentheses, place the period inside.

   • If the parentheses are part of a sentence, place the period outside.

   • Never place a period before the closing parenthesis.

4. Headings and titles

   • Do not use periods after headings, subheadings, or titles (unless the title ends in an abbreviation).

5. Numbers and decimals

   • Do not add an extra period after a decimal number.

Parentheses

Use parentheses to add clarifying or supplemental information that is not essential to the main sentence.

Avoid overusing parentheses. If the information is important, integrate it into the sentence instead of isolating it.

Avoid using (s) for plurals

Use "(s)" only if required for legal, contractual, or regulatory text where precision demands explicit acknowledgment of both singular and plural forms. Otherwise, use the plural form without parentheses.

Oxford (serial) commas {#oxford-serial-commas}

Do use serial commas.

✅ You must install Cargo, Rust, Docker, and the Sui CLI to create a Sui node.

❌ You must install Cargo, Rust, Docker and the Sui CLI to create a Sui node.

Numbers {#numbers}

Do not write out numbers when referring to a number of items; always use the numerical value.

The folder contains 24 files. One folder contains 7 files, and the other contains 24 files. At least 20 pieces of candy fell off the table.

Do write out numbers when they are grammatically part of the sentence.

One can always include extra documentation to support the theory. The client checks if the checkpoint is the last one of the epoch.

Quotation marks

Do not use quotation marks, except for the single exception "Hello, World!".

Ampersands

Do not use ampersands (&) in content to replace and as the word is more accessible and less error-prone for some programmatic use cases.

Exclamations

Do not use exclamation marks.

Terminology and vocabulary

For consistency, the Sui documentation must use the following terms and phrases with the indicated capitalization (unless sentence structure determines otherwise). This list is not exhaustive and will be updated over time.

Nodes

When referencing nodes (full, archival, validator, and so on), use:

• Lowercase full node when referring to the conceptual role in the network. "Every RPC provider must enable gRPC on their full node."
• Capitalize Sui Full Node when referring to the official software binary/package that Sui distributes. "Download and run the Sui Full Node from GitHub to connect to Mainnet."

Proper nouns {#proper-nouns}

Capitalize proper nouns throughout.

Proper nouns include:

• Names of people: Bob Ross

• Named places: San Francisco, Union Station

• Products and services: Slack, Google Play

• Trademarks: Coca-Cola

• Book titles: The Move Book

• Standards or technologies: Local Area Network (LAN)

Product names {#product-names}

Product names are proper nouns. Capitalize all words of a product name. When referring to a product, use only the product name without "the". When referring specifically to a Sui wallet, specify the name of the wallet such as Slush Wallet. Use 'wallet' generically when referring to the concept of a wallet.

There are several types of wallets to choose from.

Never share the recovery passphrase for your wallet with anyone.

The Sui network supports the following wallets:

• Slush Wallet
• Coinbase Wallet

Acronyms and abbreviations

Acronyms {#acronyms}

Spell out a term or phrase on first use in a topic, followed by the acronym in parentheses. Then use the acronym for subsequent mentions.

Example: You can mint non-fungible tokens (NFTs) using your Sui Wallet. To view an NFT after you mint it, click the NFTs tab of your wallet.

Terms that should always be used as acronyms

• CLI
• SDK

Abbreviations

Abbreviations for words should not be used. Write out the full word for clarity.

✅ Open the tab for more information.

❌ Open the tab for more info.

Capitalization {#capitalization}

Title capitalization {#title-capitalization}

For title capitalization, follow these guidelines:

• Do not capitalize short conjunctions and prepositions (a, an, and, but, for, in, or, so, to, with, yet), unless they are the first or last word.

• Capitalize all other words (including 'Is' and 'Be' as they are verbs).

• Capitalize the word after a hyphen.

• Match casing for commands or special terms, such as cURL.

• Match the casing for API elements and programming language keywords.

Section heading capitalization

Use sentence capitalization for section headings, table cells or headers, list items, captions, alt text, and error messages.

Body text capitalization

Do:

Always capitalize the first word of a new sentence.

Always capitalize proper nouns and product names. See words to always capitalize for the exhaustive list of capitalized terms.

Do not:

Do not use all uppercase for emphasis; use bold instead.

Example: IMPORTANT vs Important

Do not use bicapitalization or internal capitalization unless it is part of a brand.

Examples: YouTube or DreamWorks.

Do not capitalize the spelled-out form of an acronym unless it's a proper noun.

Example: HyperText Markup Language (HTML).

Body text styling

Em dashes {#em-dashes}

Do not use em dashes (—) in documentation. Rewrite the sentence to avoid them. Use a comma, parentheses, or split the sentence into two instead.

Bold text

Use bold at to distinguish a term from its definition in a list. Only follow this rule when the term is followed by a colon (:), not when the term or phrase is part of the sentence as a whole.

✅ - gRPC: Replaces JSON-RPC on full nodes.

❌ - Do not share your recovery phrase, as this is important for recovering your wallet.

Use bold sparingly for emphasis and only when necessary for clarity. Avoid overusing bold for general emphasis in body text.

UI elements

Use bold for UI elements that appear on the screen, such as buttons, menu items, field labels, and commands.

Port numbers

Bold port references using the format port NUMBER, for example port 3000 or port 8080.

Example: Click Save to store your changes.

Keyboard button text

Use the <kbd> tags around text that corresponds to a physical button on the keyboard.

Press <kbd>0</kbd>, <kbd>1</kbd>, or <kbd>2</kbd> to select a key scheme and then press <kbd>Enter</kbd>.

Press <kbd>0</kbd>, <kbd>1</kbd>, or <kbd>2</kbd> to select a key scheme and then press <kbd>Enter</kbd>.

Italic text

Avoid using italic text. Terms that need to be defined for the first time on a page should instead utilize the Glossary component.

Slashes {#slashes}

Do not use slashes in place of "and" or "or", such as True / False or True/False. Use True or False, or True | False in code documentation.

Variables

Use uppercase with underscores for placeholder variables that the reader must replace, such as NETWORK_NAME or YOUR_API_KEY. Keep variable names consistent within a page. Don't alternate between NETWORK and NETWORK_NAME for the same value.

Titles and headings

Use enough words in headings and titles to make it easy to know which link to click on a search results page. One-word titles (for example, Installing) do not provide enough information to determine the contents of a topic.

Page titles

Do not title a page "Overview", and avoid using "Overview" in conjunction with other terms, such as "Package Overview". Opt for more descriptive, action based titles, such as "Using Packages".

Shorter titles are preferred in the navigation pane. You can set a different navigation title by adding a sidebar_label in the document frontmatter.

Page headings

Use heading capitalization style (sentence case). Do not stack headings (place two one after the other without body text in between them).

If something is formatted as inline code in the body, format it the same in the heading.

Do not use a page title as a heading in a different page. This can interfere with search result accuracy. Page titles should be unique and descriptive, while headings can be reused.

✅ Correct usage: Page 1: Page title "Sui Gas Profiling" with heading "Environment configuration" Page 2: Page title "Sui Indexing" with heading "Environment configuration"

❌ Incorrect usage: Page 1: Page title "Sui Gas Profiling" with heading "Environment configuration" Page 2: Page title: "Sui Features" with heading "Sui gas profiling"

Heading sizes

• Heading 1 (#): Reserved exclusively for the page title. When the title is specified in the frontmatter, the page is formatted automatically with that title as a Heading 1 element.

• Heading 2 (##): Top-level section headings. Used to introduce new topics on a page.

• Heading 3 (###): Sub-topics for each Heading 2. Use for long-form content. Sections that contain 3 or more lines of prose, multiple paragraphs, or complex explanations. Content shorter than 3 lines, only bullet points, or other short-form content should use H4 or bold text instead.

• Heading 4 (####): Sub-topics for each Heading 3. Use for short-form content, examples, bullet-point sections, or sub-sections that do not require extended explanation.

• Heading 5 (#####): Use for step headings when a page contains multiple sets of step-by-step instructions (for example, multiple procedures each with their own Step 1, Step 2, and so on). Can also be used as an alternative to bolded text to create unique formatting within other elements, such as:

Heading 5 text.

Bold body text.

Normal body text.

> ##### Heading 5 text.

> **Bold body text.**

> Normal body text.

Code elements in section headings

If a word or phrase is formatted in the page content as inline code, then it should be formatted the same in a section heading.

Section heading: Install suiup

Body content: Install suiup using the command: ...

See inline code for more information.

Lists {#lists}

Use lists to present items or steps clearly. Introduce a list with a short description ending in a colon (:). Lists should be used in place of sentences that include more than 4 items as a serial comma list.

All lists should use sentence capitalization unless listing the titles of documentation pages, in which case the title case should be respected..

Title case example: The Build section includes:

• Building with Sui
• Using the CLI to Start a Network
• Creating Smart Contracts
• Sui Tutorial
• Sui Examples

Sentence case example: The build section includes:

• For objects, the tx.object(objectId) function is used to construct an input that contains an object reference.
• For pure values, the tx.pure(type, value) function is used to construct an input for a non-object input.

Numbered lists {#numbered-ordered-lists}

Use when to describe a sequence or describe a specific number of items. To define a sequence, use the ##step component or H5 headings for each step.

1. Create a fork of the repo.
2. Clone your fork of the repo.
3. Install Sui.

1. Create a fork of the repo.
1. Clone your fork of the repo.
1. Install Sui.

Bulleted lists {#bulleted-lists}

Use for related items. Use sentence capitalization and consistent punctuation. Add periods only if the item is a full sentence.

Sui Explorer supports the following browsers:

• Firefox version X or later
• Chrome version X or later
• Edge version X or later

Sui Explorer supports the following browsers:

- Firefox version X or later
- Chrome version X or later
- Edge version X or later

Term lists {#term-list}

Use to define terms or concepts. The term should be bold text, followed by a colon (:) and the term's definition using sentence capitalization:

• Term: Sentence capitalization used for the term definition.

• Term: A description of the term.

• DAG: A directed acyclic graph (DAG) is a data modeling or structuring tool typically used in data architectures.

- **Term:** A description of the term.

- **DAG:** A directed acyclic graph (DAG) is a data modeling or structuring tool typically used in data architectures.

Attribute lists

Use lists with inline code formatting to list attributes for components such as objects. Do not bold the inline code.

An event object in Sui consists of the following attributes:

• id: JSON object containing the transaction digest ID and event sequence.
• packageId: The object ID of the package that emits the event.
• transactionModule: The module that performs the transaction.
• sender: The Sui network address that triggered the event.
• type: The type of event being emitted.
• parsedJson: JSON object describing the event.
• bcs: Binary canonical serialization value.
• timestampMs: Unix epoch timestamp in milliseconds.

An event object in Sui consists of the following attributes:

- `id`: JSON object containing the transaction digest ID and event sequence.
- `packageId`: The object ID of the package that emits the event.
- `transactionModule`: The module that performs the transaction.
- `sender`: The Sui network address that triggered the event.
- `type`: The type of event being emitted.
- `parsedJson`: JSON object describing the event.
- `bcs`: Binary canonical serialization value.
- `timestampMs`: Unix epoch timestamp in milliseconds.

Tables {#tables}

Table headings {#table-headings}

Capitalize the first word in the heading. Bold labels in the header row.

| **Column one** | **Column two** | **Column three** | **Column four** |

Table text {#table-text}

Follow style guidelines for regular body text.

Code {#code}

Words or phrases that refer to functions, object names, CLI tool names, or CLI commands should be formatted as inline code when used in a sentence.

Use codeblocks for larger sections. Always use actual codeblocks (no images) formatted with the correct syntax highlighting.

Inline code {#inline-code}

Use backticks (`) around inline code.

Things that should always be formatted as inline code (body and headings) include:

• Object names: myObject

• Function names: HelloWorld

• File names with extensions: myPackage.move

• File extensions: .jpg

• CLI tool names: brew

• CLI commands when used within a sentence: If using the suggested location, type export PATH=$PATH:~/sui and press Enter.

• Variable names: PATH

• File paths: ~/.cargo/bin

Console commands

Console commands must be formatted in three backticks (```) and start with $.

Example:

$ brew install sui

Keep command and response outputs in different code blocks. This ensures commands can be copied and run correctly.

Codeblocks {#codeblocks}

Introduce codeblocks with descriptive text, including where the code should be placed within a project:

Example: Create a new file in the sources directory with the name house_data.move and populate the file with the following code:

Follow with explanations:

Example: There are a few details to note in this code:

1. The first line declares the module name as house_data within the package satoshi_flip.
2. Seven lines begin with the use keyword, which enables this module to use types and functions declared in other modules (in this case, they are all coming from the Sui standard library).
3. Two error codes. These codes are used in assertions and unit tests to ensure that the program is running as intended.

Use three backticks (```) to initiate, followed by the code's language (Rust, Move, etc) for proper syntax highlighting, and a title indicating the file name.

module satoshi_flip::house_data {

  use sui::balance::{Self, Balance};
  use sui::sui::SUI;
  use sui::coin::{Self, Coin};
  use sui::package::{Self};

  // Error codes
  const ECallerNotHouse: u64 = 0;
  const EInsufficientBalance: u64 = 1;

```move title='house_data.move'
module satoshi_flip::house_data {

  use sui::balance::{Self, Balance};
  use sui::sui::SUI;
  use sui::coin::{Self, Coin};
  use sui::package::{Self};

  // Error codes
  const ECallerNotHouse: u64 = 0;
  const EInsufficientBalance: u64 = 1;

```

Sourcing code samples {#sourcing-code-samples}

Where possible, source code samples directly from their original GitHub repository using the <ImportContent> component rather than copying code inline. This ensures samples stay in sync with the source and reduces maintenance burden.

<ImportContent source="src/lib/walrus.ts" mode="code" org="MystenLabs" repo="walrus-sdk-relay-example-app" />

Where possible, source code samples directly from their original GitHub repository using the <ImportContent> component rather than copying code inline. This ensures samples stay in sync with the source and reduces maintenance burden.

<ImportContent source="src/lib/walrus.ts" mode="code" org="MystenLabs" repo="walrus-sdk-relay-example-app" />

You can use the targeting attributes (fun, struct, variable, and so on) to extract a specific code component rather than the entire file. This prevents drift between the displayed snippet and the latest version of the source.

Procedures, tasks, and instructions {#procedures-tasks-instructions}

Introduce a procedure with an infinitive verb. Format procedures using a numbered or ordered list.

Single-procedure pages {#single-procedure}

When a page contains a single set of step-by-step instructions, use the ##step component to render the steps. This provides consistent visual styling for standalone procedures.

##step Install the CLI.

##step Configure your wallet.

##step Deploy the contract.

##step
Install the CLI.

##step
Configure your wallet.

##step
Deploy the contract.

Multiple-procedure pages {#multiple-procedures}

When a page contains multiple sets of step-by-step instructions (for example, separate installation procedures for different operating systems, or multiple distinct workflows), use H5 headings (#####) to label each step within its procedure. This keeps steps visually distinct across multiple groups.

Install on macOS

Step 1: Install dependencies

...

Step 2: Run the installer

...

Install on Linux

Step 1: Update package lists

...

Step 2: Run the installer

...

### Install on macOS

##### Step 1: Install dependencies
...

##### Step 2: Run the installer
...

### Install on Linux

##### Step 1: Update package lists
...

##### Step 2: Run the installer
...

Keyboard keys in procedures {#keyboard-keys-procedures}

When you provide instructions to press keyboard keys, such as Press Enter to continue, use uppercase for the key name and format the key name as bold text.

To get the latest version of the Sui Wallet extension:

1. Open Google Chrome.
2. Click Extensions, then click Manage Extensions.
3. Click Details for the Sui Wallet extension, then click View in Chrome Web Store.

To get the latest version of the Sui Wallet extension:

1. Open Google Chrome.
1. Click **Extensions**, then click **Manage Extensions**.
1. Click **Details** for the Sui Wallet extension, then click **View in Chrome Web Store**.

UI elements {#ui-elements}

Format UI elements, such as field labels, button names, and menu commands, in bold text. Always match the exact text or label of the UI element, including capitalization. Do not include special characters, such as ellipses, if included in the element label.

Example: Click More Transactions to open the Transactions page.

Prerequisites {#prerequisites}

Use a prerequisites section to list what the reader must have installed, configured, or completed before starting a procedure.

Sui docs {#prerequisites-sui}

On Sui documentation pages, use the following tab component for prerequisites:

<Tabs className="tabsHeadingCentered--small">
<TabItem value="prereq" label="Prerequisites">

- [x] Prerequisite one
- [x] Prerequisite two

</TabItem>
</Tabs>

Walrus docs {#prerequisites-walrus}

On Walrus documentation pages, use the following outlined tab component for prerequisites:

<div className="outlined-tabs">

<Tabs>
<TabItem value="prereq" label="Prerequisites">

- [x] Prerequisite one
- [x] Prerequisite two

</TabItem>
</Tabs>

</div>

Links and references

Always use full, relative links when linking to topics on [docs.sui.io].

For the link text, use either:

• The topic title of the target topic, respecting the title case format.

• A portion of the sentence that serves as the link text for the link in a list or "Learn more" sentences. Do not use a URL as the link text.

To learn more, see Examples of Sui Smart Contracts.

To learn more, see [Examples of Sui Smart Contracts](/guides/developer/app-examples).

Use keywords from the target topic title when using inline links.

Before you install Sui, make sure to install the prerequisites.

Before you install Sui, make sure to install the [prerequisites](/guides/developer/getting-started/sui-install.mdx#prerequisites).

URLs and web addresses {#urls-web-addresses}

Create a link with descriptive text to a site or URL. Provide the URL only when a reader needs to copy it, such as in example code or configuration files.

Special components

Collapsible component

Use the <details><summary> component to hide long or optional content so it doesn't overwhelm the page. Collapsible sections improve readability while still making supporting information available.

Use a short, descriptive summary so readers know what's inside. Keep the summary in sentence case.

Do not nest collapsible components inside one another. Limit collapsible content to material that supplements (not replaces) the visible text.

Use collapsible components for:

• Large code snippets or sample files.

• Verbose command-line output (for example, logs or stack traces).

• Extended reference content that readers may not always need.

Do not use collapsible components for:

• Required steps in a procedure. These should always be visible.

• Short examples or essential commands (collapsing them adds friction).

• Content that is critical for understanding the main topic.

Compiling dependencies...
Finished release [optimized] target(s) in 10.35s
Running `target/release/sui-node`
...
INFO: Sui node is now running

View full command output

```
Compiling dependencies...
Finished release [optimized] target(s) in 10.35s
Running `target/release/sui-node`
...
INFO: Sui node is now running
```

</details>

Alerts {#alerts}

Alerts add emphasis to information. Use Admonitions, a Docusaurus feature, to indicate the alert is a Note, Tip, or Caution. The explanation in the alert must be a complete sentence and use sentence case.

Caution {#caution}

Use caution alerts to call out when the following information could cause the developer to lose data, encounter errors, or encounter potentially breaking changes. Always explain the risk clearly.

:::caution

Backup your configuration files before you delete your network.

:::

:::caution

Backup your configuration files before you delete your network.

:::

Danger {#danger}

Use danger alerts only for information where the consequences of a mistake are critical, such as permanent data loss, security vulnerabilities, or irreversible actions. Keep the explanation concise and serious in tone.

:::danger

Deleting this key will permanently remove your access to the account.

:::

:::danger 

Deleting this key will permanently remove your access to the account.

:::

Info {#info}

Use info alerts to provide important but neutral context that readers should be aware of. It's less about best practices and more about ensuring readers do not miss critical background or conditions.

:::info

You must install Rust before you can build Sui from source.

:::

:::info 

You must install Rust before you can build Sui from source.

:::

Note {#note}

While note alerts are a valid admonition, its visual styling is less impactful than other supported admonitions. It is recommended to avoid using note in favor of tip or info.

:::note

This section applies only if you're using Devnet.

:::

:::note

This section applies only if you're using Devnet.

:::

Tip {#tip}

Use tip alerts to give the reader advice that might be helpful, such as a best practice or a shortcut.

:::tip

Change your home directory after installing the IDE.

:::

:::tip

Navigate into your home directory after installing the IDE.

:::

Images and graphics {#images-graphics}

Only use images and screenshots to supplement and help explain text. Images do not replace text. Readers should be able to understand the documentation without the images. However, images can help readers understand the text more clearly.

Image format {#image-format}

Use .png when possible, otherwise use .jpg.

Image resolution {#image-resolution}

Images should be at least 400 pixels wide. If an image looks blurry when uploaded, try making a new image in higher resolution.

Captions {#captions}

Use alt text to describe what the image shows. Use the caption to explain why the image is meaningful in the context of the page. See Accessibility considerations for captions.

Mermaid for images in Markdown {#mermaid}

You can create flowcharts and similar images directly in Markdown using Mermaid.

Index pages

Index pages provide a landing page for the category and ensure users can navigate deeper into the section without relying solely on the sidebar. They provide a standardized format for each category in the docs, and improve navigation on mobile browsers.

Every sidebar category must have a corresponding index page when the category uses link.type: 'doc'. This applies to all levels of the documentation hierarchy, including nested categories.

{
  type: 'doc',
  label: 'Section',
  id: 'section/index',
},
{
  type: 'category',
  label: 'Category',
  link: {
    type: 'doc',
    id: 'section/category/index',
  },
  items: [
    {
      type: 'category',
      label: 'Subcategory',
      link: {
        type: 'doc',
        id: 'section/category/subcategory/index',
      },
      items: [
        'section/category/subcategory/page-1',
        'section/category/subcategory/page-2',
      ],
    },
    'section/category/page-3',
    'section/category/page-4',
  ],
}

Required format

Each category index page must use the following structure:

---
title: Page Title
description: A brief description of the page.
keywords: [ keywords, describing, topics, on, page ]
pagination_prev: null
---

Brief sentence to introduce category.

import DocCardList from '@theme/DocCardList';

<DocCardList />

The <DocCardList /> component auto-populates the page with card modules for every sub-category and sub-page as defined in the sidebar file.

Accessibility {#accessibility}

Reference works for making content accessible:

• A11Y Style Guide
• Bitsofcode Accessibility Cheatsheet
• Atlassian Design System - Inclusive writing reference
• MailChimp's writing style guide
• Microsoft Style Guide Accessibility Terms
• Writing for All Abilities (Microsoft Style Guide)

Formatting {#formatting}

Do not use color or special symbols to add emphasis to text. Screen readers are designed to interpret bold (<strong>) and italic (<em>) in web pages.

Images {#images}

Add captions and alt text that describe the image for someone using a screen reader. What are the important details in the image that someone using a screen reader can't see?

Use alt text to describe what the image shows. Use the caption to explain why the image is meaningful in the context of the page.

An image is not a substitute for text; images should only supplement text. Do not rely on an image to convey information not in text form. For example, an image of a table of values does no one any good if the image fails to display for a host of possible reasons.