Interface text

Last updated on
20 April 2017

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

These guidelines are being applied in Drupal core. To achieve a consistent style it is recommended to apply these guidelines in contributed modules as well.

Style

  • Use a neutral and polite tone.
  • Keep the purpose of sites in mind when writing text for the UI: most sites are used in a professional environment - so use appropriate wording.
  • Use active writing and make sure it is clear who performs a certain action. Do not use the pronoun "we." For example, do not write text like "we delete these files" (who deletes them?). If something works automatically (and the user should know about it, write (e.g.) "Temporary files are deleted automatically by the system. " If the user should take a particular action, the text should instruct the user directly: "Delete unnecessary files."
  • Do not use 'Please'. This makes it sound as if the user is supposed to do a favor for someone.
  • Do not use 'Sorry', e.g., in error messages.
  • Avoid emotional verbs and adjectives. E.g., it should be normal that an admin can install a module, so there is no "success" in it. If the installation fails, the admin gets an error message.
  • Do not use contractions like e.g., 'You've, Can't, Shouldn't. Use the complete phrase instead such as 'You have, Cannot, Should not'
  • Refer to other parts of the website using single quotes, e.g., "Indexing behavior can be adjusted using the 'Search settings' page" ( (where 'Search settings' should be a link).

UI-elements

  • Label all widgets (buttons, fields, etc.). Do not use the label to provide help text.
  • Use hyperlinks in call for actions. For example: "There are no blog-items to display. Add a blog-item". Where "Add a blog-item" is a hyperlink
  • Keep introductions as short as possible, and don’t describe options in detail. Ideally no introduction should be necessary because the screen and its behavior should be intuitive.
  • Don’t describe default user interface usage/behavior (drag-and-drop etc.).
  • Put longer and more detailed descriptions on a ‘More help’ page.
  • The order of tabs/actions is always (where applicable) List, Edit, Add, Delete (or LEAD).
  • Make sure link text describes what is on the linked page or what will happen if it is clicked. Don't use 'click here' for the link text, or the URL as the link text.
  • Note that interface strings are filtered on unsafe html tags when they pass through functions like t(), l() and drupal_set_title().
  • Always use a verb and noun as the menu link text ('Add link', 'Configure search')
  • The first form field of each element is the name of the element followed by 'name' ('Gallery name')
  • Only add descriptive text under form elements when they would be unclear without them. Try to make the form label clear by itself.
  • Buttons
    • The submit button is always called 'Save' when the actual action is saving
    • The reset to defaults button is always called 'Reset to defaults'
    • The delete button is always called 'Delete'
    • The cancel button is always called 'Cancel'

Wording

  • Use the verb ‘Configure’ for actions eg. 'configure links'. 
  • Use the noun 'Settings' to describe a UI eg. 'Account settings'.
  • Use 'Module', not 'Plugin' or 'Extension'.
  • Use 'Text format', not 'Input format' (since Drupal 7).
  • Use 'Content' or 'Piece of content' not 'Node'. Post should only be used as a verb (since Drupal 7).
  • Use 'Site', not 'Drupal'. Referring to Drupal by name complicates distributions and users may not know the site is running on Drupal.
  • Use "Content types", not "Content type entities" (avoid using the word "entities")

See also the content style guide.

Capitalization

Page titles, links, and headings

Page titles, links, and headings in Drupal should generally use "sentence case" where only the first word is capitalized, except for proper nouns and other words which are generally capitalized by a more specific rule. Examples: "Block administration", "List menus", "Install new theme". This also applies to links in menus

Module and theme names

When referring to the name of a module or theme directly, such as in documentation, use "proper name" case, since module and theme names are proper names in English. For example, use "How to configure private forums with the Taxonomy Access Control module" instead of "How to configure private forums with the Taxonomy access control module". The latter is ambiguous as it could be interpreted that you have a module called "Taxonomy" that is an example of an access control module or that we are using an un-named module providing access control for Taxonomy.

Block, page or permission

When referring to a specific block, page, or permission, use the capitalization used on the blocks administration page, the page title, or the permission name shown on the Permissions page, respectively. Put the name used in quotes 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 don't think it merits capitalization and quotes or a link, use all lower-case (e.g., you could refer to the "search page" or the "search block", without the quotes). Keep in mind that this is not as specific as referring to the exact item, so the first form is probably preferred in most cases, especially in help text where you can provide a link.

Acronyms, trade names, etc.

Drupal user interface text should follow standard (all-caps) capitalization for acronyms (CSS, WYSIWYG, UI). Also it should use established capitalization for third-party trade names (jQuery, JavaScript).

Tables

  • Capitalize the first word in each column header ('User since')
  • When the table has a column for actions/operations to perform on the rows, call the column 'Operations'
  • If possible, put the available operations in one row. If that’s not possible, put them underneath each other
  • If the table contains no records: display within the same table a concise "call to action" message with a link which allows the user to add relevant content. (Unless the empty table is the result of filtering.)