Copyright © 2016 IBM
See a problem with the code? Need a new component? Have feedback? We'd love to hear it all! The success of the Bluemix Design System relies on great people like yourself. Fill out the form below to submit your issue to our GitHub repo.
A member of the Bluemix Design System's team will be in touch within 48 hours.
Your issue, , is now in the bluemix-components repo. Click the issue number to track the progress or make edits to your issue.
We will get back to you within 48 hours. Feel free to reach out to us on one of our slack channels if you have additional questions:
#bluemix-componentsEssentials
Using the appropriate voice and tone allows us to better connect and resonate with our users. Gone are the days when our users perceive their content experience as complex, distant, or disjointed. We've evolved and we now endorse a style that should feel like a conversation between friends – personal, relatable, clear, helpful, and engaging. Conversational style does not mean sloppy writing. It means creating content in a clear, concise way that anyone can understand. It means genuinely connecting with our users.
What is the difference between voice and tone? Simply put, we have the same voice all the time, but our tone often changes. Consider this: You have one voice, but you most likely use a certain tone when you are having coffee with friends and a different tone when you are meeting with your boss.
Here's how conversational you should be based on the six stages of the Client Journey:
MOST: Discover, Try, Buy content
"Thanks for joining IBM Bluemix for your free 30-day trial. It's been great having you! Unfortunately, your Bluemix trial account, with IBMid name@domain, is now deactivated because your trial is over. While your account is deactivated, you can't access resources. Don't worry, your apps are not deleted."
MORE: Getting started interface content (for example, welcome), interface content for remaining experiences (Productive Use, Manage and Upgrade, Leverage and Extend, Get Support)
"To start using Bluemix, name your first organization. Think of an org as a project or team that shares resources, such as apps, databases, and other services. Orgs exist in geographic regions, so decide where you'd like to put your first one."
LESS: Instructional content (steps) for how to complete a task
"Go to Avatar icon > Account > Notifications to set up general account and spending notifications. Spending notifications are available only for Subscription and Pay-As-You-Go Bluemix account owners."
These guidelines apply for developers and writers working with the
Bluemix UI and documentation.
Use simple verbs and tenses, and keep sentences concise, simple, friendly, and punchy. Focus on the user's context and make content relevant. The more familiar you are with their context, the better you can communicate without using a lot of words.
If you need to use past or future tense, avoid verb tenses with the words have, has, had, been, should, would, and will.
“The API returns a promise.”
“The API will return a promise.”
“The limit has been exceeded.”
“The limit was exceeded.”
To convey a more natural tone, use active voice. People tend to speak in active voice unless they have a reason not to. For example, a good reason to use passive voice is to avoid sounding judgmental or blaming the user. Consider how a statement like, "You entered the wrong value," which is active voice, might not be a well received error message.
“In the Limits window, specify the minimum and maximum values.”
“The Limits window is used to specify the minimum and maximum values.”
Engage your readers by using second person ("you," "your"). First person ("I," "we," "our") focuses on the writer rather than the audience. People are interested in what they can do and how your story applies to their lives.
One exception to this is in the case of possessive adjectives in the UI. You can use first person in headings or labels that are very specific to the user or customer data, for example “My Account” or “My Usage.” In explanatory text for the heading or label, switch to second person, for example “Your usage is calculated from the 1st day of the month.”
“Do you want to close without saving?”
“Your IBM Bluemix account is ready!”
“You reached your usage limit!”
Terms of politeness are superfluous, convey the wrong tone for technical material, and are not regarded the same way in all cultures.
Use please in a UI only when the user is being inconvenienced.
“Indexing might take a few minutes. Please wait.”
Instead of using may, use can to indicate ability or use might to indicate possibility.
“You can use the command line interface to update your app.”
“You may use the command line interface to update your app.”
“You might need more advanced features when you're integrating with another app.”
“You may need more advanced features when you're integrating with another app.”
Good content design is consistent and coherent so that users can trust and predict how to interact with it. Details matter.
Always capitalize proper names, such as United States. Use ALL CAPS for abbreviations, acronyms, and initials (for example, IBM and ASCII) and two-letter abbreviations (for example, AL, AK, and AZ), and for OK.
For specific capitalization rules for different element or component types, see the usage details for each individual element or component type.
Use sentence-style capitalization in text and for all text elements in the UI, except for table/grid column headers, headings for groups of toggles, and product names. Sentence style capitalizes only the first word of each sentence and proper nouns (names).
Examples:
Use headline-style capitalization for table/grid column headers, headings for groups of toggles, and product names. Headline style capitalizes words based on parts of speech.
Capitalize the initial letter of the following words:
Do not capitalize the initial letter of the following words:
This section covers the approved action labels and idioms for use in the Bluemix UI and documentation. Users rely on consistent labels for common actions to predict how to interact with an interface. Idioms are expressions that have a meaning different from the meaning of each word in the expression.
This section is a living document. When new terms are introduced, they will be added here. To submit new terms, go to Proposed idioms and abbreviations for Bluemix.
If you're looking for the product glossary, go to Glossary terms for Bluemix.
Adds an existing object to a list, container, or system (for example, adding a document to a folder).
Saves changes without closing the dialog. These properties often affect subsequent system behavior.
Indicates the user agrees. In a business process, typically initiates the next step.
(adverb) pertaining to separately itemized objects.
(noun) a web or mobile device application.
Returns the user to the previous step in a sequence of steps, such as in a wizard.
Assists the user in entering a file name or file path (for example, on a button or link next to an entry field). Typically opens a secondary window where the user can locate and select the desired directory and file.
(noun) a significantly successful product or service in the marketplace.
(verb) to feel sure about something.
(phrase) a significant amount of money saved.
Stops the current action and closes the dialog.
This action clears all the fields or selections. Also deletes the contents of a document, such as a log. Typically the default selection or value is re-established for controls that always have a selection or value, such as radio buttons.
Closes the current page or window (for example, closing a secondary window containing online help).
Creates new instances of the selected objects to a specific destination.
Label for a button in a dialog or form that creates a new object. The settings in the dialog are applied to the object when it is created.
Allow a user to make desired changes.
(noun) a man-like robot with no feelings (to cloud its judgment) that flawlessly executes its mandate.
(noun) congratulations.
(noun) the unexpected termination of a software function.
(verb) of software, to unexpectedly terminate.
Destroys an existing object.
Opens a separate window containing the landing page for Bluemix Docs.
Indicates that the user has finished working in an environment (for example, editing templates) and wants to return to where he or she came from.
Transfers a file from a remote system to a local system.
Use only for dropping a database table.
(phrase) developer to developer.
(noun) documentation.
(adjective) pertaining to something that is exceptionally gratifying, excellent, or beautiful.
Allows data or values to be changed.
Permanently deletes all files or objects that have been placed into a trash container.
Saves data in a different format external to the system. Typically opens a secondary window for the user to specify the file type and destination (for example, storing table data as a set of comma-separated values).
Shortens a list to objects that match the filter criteria.
Moves the cursor to the next element matching the specified criteria (for example, view the next occurrence of a specific word within an email message).
Indicates completion of a series of steps, such as in a wizard.
(noun) something given away at no cost.
Opens a search field from which the user can search for help information.
(verb) to contact someone.
Removes an element that was previously shown.
(noun) an event that brings together developers to work intensively on a software project.
(phrase) to be directly involved in the accomplishment or creation of something.
(phrase) to immediately accomplish something when just starting to learn how to do it.
Transforms data or objects from an external source. Typically opens a secondary window for the user to locate the external source.
Adds an element at a particular position in an ordered view.
(phrase) quickly, immediately.
Do not use.
Opens additional, highly contextual information. Insert at the end of inline text or hover text where more information follows but does not fit in the current context.
Enters a site or application. This choice typically opens a form for entry of credentials. Also used on the submission button after users enter their credentials.
Exits an application or site.
(phrase) to be hopelessly adrift with no chance of return, unlocatable, lost to the world.
Transfers an object from one container (for example, folder, activity, or page) to another.
A soft delete. Moves a file or object to an area from where it can later be permanently deleted or recovered.
(noun) an informal gathering.
(noun) the metaphorical strength or physical power of something.
Starts the creation of a new object. New either creates the object immediately or opens a dialog or set of fields where the user can enter properties.
Advances the user to the next step in a sequence of steps, such as in a wizard.
(adjective) not applicable, not available.
Completes the current task.
(phrase) used to indicate shock.
(adjective) on premises, on-premises.
(expression) used to indicate an accident or a mistake.
(noun) operations.
(noun) organization.
Starts audio, video, or an animation.
Adds a new comment to an online community or adds status to a log or record.
Shows how an object or content will appear with formatting applied before the content is published or distributed. Alternatively, provides an incomplete display of an existing object without leaving the current context.
Sends a copy of the currently selected object or the object in view to the printer.
Redoes an undo action.
Reloads the view of an object when the displayed view has become unsynchronized with the source.
Indicates the user does not approve. In a business process, typically blocks the process from proceeding to the next step.
Indicates or completes a response to an email or a comment.
Removes an object from a list or container but the object is not destroyed as a result of the action. Often requires one or more objects to be selected.
Reverts values back to their last saved state. The last saved state includes the values stored the last time the user clicked Apply. Does not close the dialog or window.
Brings a file back after deletion, corruption, or similar event.
Completes a restore operation on all files or objects in a given system or container.
Sets form values to the default settings.
Runs a task, job, activity, or program.
(phrase) prepared for use.
Saves pending modifications made to a file or document. Does not close the window or panel.
Creates a new object based on the state of the object currently being viewed. The user names the new object and typically identifies its location.
Returns all objects (for example, files, names, or documents) within a defined set (for example, in a folder, directory, database, or the internet) that match some specified criteria.
Selects data from a table.
Adds all objects in the view to the selection set or checks all check boxes.
Transfers an email or other information to the recipient.
Reveals an object that was previously hidden.
Creates a user account or registers a user in a system.
Deploy an app or service to its development or production environment so that it can be used.
Sorts a list or table column.
Opens a separate window containing the IBM Cloud Ideas portal.
(noun) a high priority, often secret, project taken on by a small team without constraints from management.
(noun) a newly established business.
(phrase) to start from the beginning, to start from nothing.
(adjective) pertaining to something that is considered excellent, awesome, or cool.
(noun) synchronize.
Returns to the top of the page.
(noun) a test or evaluation of a piece of software for a specified amount of time.
(phrase) time passes quickly.
Reverts to the state before the most recent changes made by the user. Repeated use successively reverts to prior states in reverse chronological order. Applies to changes in data and not to changes made to the view.
Label for a button in a dialog or form for editing an object. The settings in the dialog are applied to the object when it is updated.
Transfers a file from a local system to a remote system.
(verb) to change the status of an item that was previously marked as a favorite. (adjective) an item that is not a favorite.
Presents additional information or properties for the object.
(expression) draws attention to something that has been accomplished or gained.
(expression) used to show astonishment, delight, or admiration.