Interface text

This page contains guidelines for Drupal module and theme developers to use when writing user interface (UI) text, like buttons, labels, in-page help, descriptions below fields, and (error) messages.

These guidelines are being applied in Drupal core. For consistency, apply these guidelines in contributed modules, too.

Style

• Use a neutral and polite tone
• Remember the purpose of the site; as most sites are used in professional environments, use appropriate wording
• Use the active voice, and make sure it is clear who performs a certain action 
  • In sentences written in the active voice (rather the passive voice), the subject of the sentence performs the action denoted by the verb
  • For example, if something works automatically and the user should know about it, the associated message could read "The system automatically deletes temporary files"
• Use the imperative sentence structure when appropriate: "Delete unnecessary files"
• Follow the principle of less is more, keep interface text concise and to the point
  • Learn more about the principle of less is more
• Avoid emotionally charged verbs and adjectives
  • For example, it is expected and normal that an admin is able to install a module, so there is no real success in it
• Use single quotes to refer to other parts of the website
  • For example, the sentence "Indexing behavior can be adjusted using the 'Search settings' page." is appropriate, where 'Search settings' is a link
• Use the ellipsis character, "…", instead of three dots.
• Do not use the word "please". This makes it sound as if the user is supposed to do a favor for someone
• Do not use the word "sorry", especially in error messages
• Do not use the pronoun "we", like in the sentence "We delete these files." It's often unclear who we refers to
• Do not use contractions, like "you've", "can't", and "shouldn't", and so on. Use the complete phrase instead

UI Elements

• Label all widgets, like buttons and fields. Do not provide help text in the label
• Use hyperlinks in calls for action
  • For example, in the call to action "There are no blog items to display. Add a blog item.", the sentence "Add a blog item" should be  a hyperlink
• Keep introductory text short, and do not describe options in detail
  • Ideally, though, any given screen and its behavior should be intuitive, making an introduction unnecessary
• Do not describe default UI interaction usage patterns or behavior, like drag-and-drop
• Put longer, detailed descriptions on a ‘More help’ page
• Ensure the order of tabs or actions, where applicable, follows LEAD: List, Edit, Add, Delete
• Make sure link text describes what is on the linked page or what will happen if the link is clicked
  • Do not use "Click here" or a URL for a link text
• Note that interface strings are filtered on unsafe html tags when they pass through functions like t(), l() and drupal_set_title()
  • Learn more about how interface text is filtered
• Always use a paired verb and noun as a menu link text, like "Add link", "Configure search", and so on
• Ensure that the first form field of each element is the name of the element followed by "name", like "Gallery name"
• Add descriptive text under form elements only when they would be unclear without them. Try to make the form label clear by itself
• Review the following guidelines for button text:
  • A submit button should always have the label "Save" (when the actual action is saving)
  • A reset to defaults button should always have the label "Reset to defaults"
  • A delete button should always have the label "Delete"
  • A cancel button should always have the label "Cancel"

Word Choice

• Use the verb "Configure" to indicate actions, like "Configure links"
• Use the noun "Settings" to describe options to change behavior or functionality, like "Account settings"
• Use "Module"—not "Plugin" or "Extension"
• Use "Text format"—not "Input format" (as of Drupal 7)
• Use "Content" or "Content item"—not "Node", and "Content type" not "Node type". (This applies only to the content entities supplied by the core Node module)
• For generic references to content entities, use the terms "Entity" (not "Entity item"), "Entity type", and "Entity subtype" (not "bundle")
• Use "Post" only as a verb (as of Drupal 7)
• Use "Site"—not "Drupal"
  • Referring to Drupal by name complicates distributions, and users may not know the site is running on Drupal

Learn more in the Drupal.org content style guide.

Capitalization

Page titles, links, and headings

Page titles, links (in menus, too), and headings in Drupal should generally use sentence case capitalization, where only the first word is capitalized, except for proper nouns and other words that are generally capitalized by a more specific rule. Examples of sentence case capitalization include the following: "Block administration", "List menus", "Install new theme".

Module and theme names

Core and contributed modules and themes should use title case capitalization (e.g. Layout Builder), since module and theme names are proper names in English. Also, when referring to the name of a module or theme directly, such as in documentation, help texts, or descriptions, use the same convention of title case capitalization, since module and theme names are proper names in English.

For example, the sentence "How to configure private forums with the Taxonomy Access Control module" is preferable to "How to configure private forums with the Taxonomy access control module". The latter is ambiguous: it could be misinterpreted to mean that there is a module named "Taxonomy" that is an example of an access control module or that we are using an unnamed module providing access control for Taxonomy.

Block, page or permission

When referring to a specific block, page, or permission, follows the capitalization used on the block's administration page, the page title, or the permission name shown on the 'Permissions' page, respectively. Wrap the name in quotation marks to set it off from the rest of the text.

If this is in hook_help() text, make page titles into links to the page, and make permission names into links to the appropriate anchor/section on the 'Permissions' page.

Alternatively, if you do not think it merits capitalization and quotes or a link, use lower-case. For example, you could refer to the search page or the search block. Keep in mind that this is not as specific as referring to the exact item, so the regular form is preferred in most cases, especially in help text where you can provide a link.

Acronyms, trade names, etc.

Drupal UI text should follow standard (all-caps) capitalization for acronyms, like CSS, WYSIWYG, UI, and so on. Also, use established capitalization for third-party trade names, like jQuery, JavaScript, and so on.

Table Text

• Capitalize the first word in each column header, like "User since"
• When a table has a column for actions/operations to perform on the rows, name the column "Operations"
• If possible, put the available operations in one row; if that is not possible, put them underneath each other
• If the table contains no records: within the same table, display a concise call-to-action message with a link that, if followed, allows the user to add relevant content
  • Do this unless the emptiness of the table is the result of filtering