Skip to main content

Style Guide

This document defines the styles, vocabulary usage, and content formatting for Sui documentation. Entries are in alphabetical order. A style guide is never finished; expect continued iterations to add additional styles, additional information to existing styles, and infrequently a change to an existing style.

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​

Use US English spelling in source content.

Avoid 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​

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​

  • First person → I or we

  • Second person → you

  • Third person → he, she, they, it, product names

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​

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. Abbreviations

  5. Headings and titles

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

  6. 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​

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​

Do not write out numbers; 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.

Quotation marks​

Do not use quotation marks.

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. If you absolutely must include an ampersand in content, escape it using &.

Exclamations​

Do not use exclamation marks. If you'd like to express excitement, such as:

Congratulations! You've finished the tutorial.

Use the confetti emoji instead:

Congratulations, you've finished the tutorial. 🎉

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.

CategoryWords and termsNotes
Always capitalizedProper nouns, product names, names of example dApps (Coin Flip, Blackjack, etc), Archival Store and Service, Archival Store, Archival Service, Coin Registry, Currency Standard, DeepBook Indexer, DeepBookV3, Devnet, GraphQL RPC, General-purpose Indexer, ID, Localnet, Kiosk (when referring to the standard), Mainnet, Mysticeti, One-Time Witness, Operation Cap, Sui, Sui CLI, Sui Client PTB CLI, Sui Closed-Loop Token / Closed-Loop Token, Sui dApp Kit, Sui Explorer, SuiJSON, Sui Keystore, Sui Keytool, SuiLink, Sui Object Display, SuiPlay0X1, SUI, SUI token, Testnet, Wallet Standard, Web2, Web3, zkSend SDKUse capitalization consistently for branding and product-specific references
Always lowercasecasual history, casual order, certificate, dApp, epoch, equivocation, eventual consistency, finality, gas, genesis, kiosk (when referring to an instance), object, oracle, recovery passphrase (mnemonic), smart contract, soulbound, Sui framework, Sui object, total order, transaction, transfer, validator, walletUse lowercase when referring to general concepts rather than branded terms
Never hyphenatedkey pair, layer 1, open source, use caseKeep these words separate, no hyphen
Always hyphenatedburn-only (currency supplies), depth-first search, multi-writer objects, off-chain, off-device, on-chain, on-device, One-Time Witness, peer-to-peer, proof-of-stake, single-writer objectsMaintain hyphen for clarity and correctness
Word preferenceUse "might" in place of "may"The word may has a secondary definition that implies permission rather than possibility.

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​

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 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, use Sui Wallet or Ethos Wallet and not just wallet. Users likely have multiple wallets, and we want to make it clear which 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:

  • Sui Wallet
  • Ethos Wallet
  • Coinbase Wallet

Acronyms and abbreviations​

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​

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 or dApp.

  • 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​

Bold text​

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

Example: Click Save to store your changes.

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

Italic text​

Use italics when introducing a new term for the first time.

Example: The term for the cost of processing transaction blocks is gas.

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.

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​

Use descriptive titles that include relevant keywords so readers can quickly identify the content. Shorter titles are preferred in the navigation pane. You can set a different navigation title by adding a sidebar_label in the document frontmatter.

Readers usually search for information to complete a specific task. Avoid vague titles such as Get Started. Get started with what? If there are multiple products or features, the meaning is unclear.

A better option is Get Started with Sui, but even this is still too broad. Readers want guidance for a specific task or journey. Instead, use precise titles such as Create a Sui Full Node or Install Sui Tooling. These tell the reader exactly what they will learn or accomplish.

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. Used to introduce multiple concepts under a top-level heading.

  • Heading 4: (####) Sub-topics for each Heading 3. Used to introduce examples for Heading 3 topics or format sub-sections distinctly.

  • Heading 5: (#####) Sub-topics for each Heading 4. When formatted, looks identical to bolded body text, but slightly larger. 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.

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​

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​

Use when items must be done in order, describe a sequence, or describe a specific number of items.

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

Bulleted lists​

Use for related items that do not need order. 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

Term lists​

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.

At the bottom of a page, you can direct the reader to additional, related content via a related links list. Use the RelatedLink component:

External links:

<RelatedLink href="/path/to/page" label="Page Title" desc="Description of page." />

Internal links:

<RelatedLink to="/guides/somepage.mdx" />

Attribute lists​

Use lists with inline code formatting to list attributes for components such as objects.

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​

Table headings​

Capitalize the first word in the heading. Center align the text. Bold labels in the Header row.

Column oneColumn twoColumn threeColumn four
Metric name10XText string.

Table alignment​

Center align labels in the Heading row. Left align strings of text. Center align values and Xs or checkmarks.

Column oneColumn twoColumn threeColumn four
Metric name10XText string.

Table text​

Follow style guidelines for regular body text.

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​

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​

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.

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;

Procedures, tasks, and instructions​

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

Keyboard keys in 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.

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.

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.

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

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

URLs and 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.

Referring to pages in our docs​

Refer to pages in the documentation set as "topic"s. A "guide" can comprise many related topics.

Example: See the Install topic in the Validator guide for more information.

info

You can also just refer to a topic by title where it makes sense. See Installing Sui for more information.

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.

Click to open
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

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​

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.

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.

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.

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.

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.

Images and 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.

Use Snagit or other tools to capture screenshots.

Image format​

Use .png when possible, otherwise use .jpg.

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​

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​

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

Index pages​

Section index pages must link to subcategory index pages when one exists. This is to ensure users can easily navigate deeper into subsections without relying solely on the sidebar and creates a consistent navigation structure.

For example, if the docs folder looks like this:

/docs/
  guides/
    index.mdx
    setup/
      index.mdx
      install.mdx

Then /docs/guides/index.mdx must include a link to /docs/guides/setup/index.mdx rather than a link to /docs/guides/setup/install.mdx.

Accessibility​

Reference works for making content accessible:

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​

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.

Reference style guides​