Use a button to invoke an immediate action:
@@ -31,7 +30,7 @@The action takes the user to another page of the same dialog or an external source like documentation.
-Write the label as an imperative verb, for example, Save, Print, Cancel. Use title capitalization.
-Exceptions: standard buttons like Exceptions: standard buttons like
The button should answer the question in the title, so the user can skip the description. Prefer specific @@ -101,11 +100,11 @@
Do not
use the word
+
This page describes the basic rules of writing articles for IntelliJ Platform UI Guidelines.
- -[//]: # (## Workflow) - -[//]: # () -[//]: # (Follow these steps if you want to add a new article to the guidelines:) - -[//]: # (1. Write an article in the Google doc.) - -[//]: # (2. Share the Google doc with the designers team, so they can review and comment the document.) - -[//]: # (3. When all comments are resolved, send the Google doc to tech writers for grammar review. [Create ticket](https://youtrack.jetbrains.com/newIssue?project=DOC&clearDraft=true&c=Type+Task&c=Assignee+Anna.Gasparyan&c=Subsystem+IntelliJ+IDEA) in YouTrack project “Documentation”, subsystem “IntelliJ IDEA”, auto-assigned to Anna Gasparyan.) - -[//]: # (4. After the review, add the article to the guidelines. Follow the instructions on [https://github.com/JetBrains/ui](https://github.com/JetBrains/ui).) - -[//]: # (4. Contact developers to add Code Snippets to the article.) - -## Text - -The text should be short and clear. Follow the rules: - -### Grammar - -| Use present tense. | -A progress bar informs user about the progress of a lengthy operation. | -
| Write in the active voice. | - Progress bar is shown. Progress bar appears. |
-
| Avoid unnecessary modal verbs. | - Label should use sentence-style capitalization. Use sentence capitalization in labels. |
-
| Use imperatives. | -The cursor changes to the pointing hand. Change the cursor to the pointing hand. |
-
| Do not address the reader. | -Use combobox if..., Follow guidelines... | -
| When describing user behavior, write: | -A user looks forward to what will appear after completion. | -
| Avoid bracketed text, it complicates reading. If information is important — put it in a new sentence, if not — remove it. | -Provide a header (bold) for each progress. Provide a bold header for each progress. |
-
| Would be — use is instead, when possible. | - Displaying indicator would be distracting. Displaying indicator is distracting. |
-
| Then — omit if possible. | -If a process is started by the user, then. provide notification. | -
| |
- If a process lasts less than 1 second, the user won’t be able to read the process name and showing it would just distract them. | -
| Select a word with bold to emphasise or with italic to quote. | -
` is assigned a numbered anchor. An anchor helps referencing a particular guideline. Structure the article so that each guideline is a single paragraph.
-* To start a new paragraph, add an empty line above.
-* To create a text block without an anchor, do not add an empty line above. Add two spaces in the end of the previous text block.
-* To add extra vertical space without creating a paragraph, use `
`.
-* If some element gets an unnecessary anchor, use the class `noanchor`. Note that Markdown does not work inside the `
` tag, replace it with HTML. Example:
-
-For when to use the empty state, see the -Empty State. -
- - -The article structure can vary depending on whether a control, component or principle is described. Generally, use the sections that are described below. - -### Introduction paragraph - -In the first paragraph describe a control, component or principle and provide an illustration. If there are different types of the control, describe all of them. - -### When to use - -Describe when to use the control or when to apply the principle. - -If the control is often used incorrectly, describe cases when the control should not be used. - -### How to use - -Provide guidelines on how to use the control, component or principle. Group guidelines by their subject. For a control it can be: -* Behavior details for a single control and for a group of such controls (if applicable) -* Wording — how to write a label for the control -* Using the control with other controls -* Any other recommendations specific to this control - -Use notes for links to additional materials, sources, useful facts and examples. To insert a note, use: -This page describes basic rules of writing articles for IntelliJ Platform UI Guidelines.
+The article structure can vary depending on whether a component or a principle is described. + Most of the articles should include the structural elements listed below.
+
+
+
<tldr></tldr> element.
+ You can add other useful links to this block if needed.
+ In the first paragraph, describe a component or a principle and provide an illustration. +
+Add this section if a component consists of several controls. + Provide an image that shows all parts of the component. + Use callouts to label the component parts:
+
+ If needed, describe all the parts in details below the image.
+ Describe common use cases for the component and provide an image for each use case.
+If the component is often misused, describe these cases. + If possible, write which components should be used + instead and provide images.
+Provide guidelines on how to use a component, for example:
+-
+
Try to put each rule or a group of rules into a separate subchapter and add a short and descriptive title. + This will allow the reader to scan the information on the page faster and copy the link to the rule if needed.
+Do not describe the component appearance in a separate section. All the details are provided in the Int UI Kit + library in Figma. + Make sure that an actual link to Figma is added in the useful links. +
+Get + the Int UI kit and enable it in Figma.
+_dark postfix
+ to the filename.
+ Use a gray rounded background for all images. Find details in the Figma + file.
+All images must be either 706 px or 378 px wide.
+Use 706 px width for images with wide content or for single images that are surrounded by text:
+
+ If an image description appears above the image, end it with a colon.
+Use 378 px width for images in borderless tables. Use the border="false" attribute for
+ creating borderless tables.
Put images into borderless tables when listing a set of smaller images with descriptions on the right + or when adding correct/incorrect/acceptable examples.
+Sets of smaller images:
+ |
+ Use a split button instead if there are more than two related + actions. + | +
+ 
+ |
+ Use a built-in button instead if it's related to an input field, combo box, + search field. + | +
Correct/incorrect/acceptable examples:
+|
+
+ |
+
+
+ |
+
 |
+
+ |
+
|
+
+ |
+
+
+ |
+
|
+ |
+
Add callouts to describe the anatomy of complex components.
+All texts on images should be horizontally oriented. Refer to the Figma + file for details. +
+
+ The guidelines should be short, clear, and consistent. Find the common rules below.
+| Prefer present tense. | + A progress bar
+ |
+
| Prefer the active voice. | + Progress bar
+ Progress bar |
+
| Avoid unnecessary modal verbs. | + Label
+ + |
+
| Use imperatives. | +
+ + |
+
| When describing user behavior, write 'a user + verb'. | + A
+ |
+
| Avoid bracketed text. If information is important, put it out of the brackets or add a new + sentence. Otherwise, remove it. + | +Provide a header
+ Provide a + |
+
-
+
Omit common introductory phrases.
+Write one idea per sentence.
+Split the text to subsections and short paragraphs.
+Use bulleted lists when the order of points does not matter, and numbered list when it does.
+When giving a recommendation, explain why it is useful:
+|
+ |
+
+ |
+
If a process is started by a user, provide a notification when the process finishes. |
+
+ If a process is started by a user, provide a notification.
+ |
+
-
+
|
+ |
+
+ |
+
Find more details here. + |
+ + section. + | +
Use tips <tip></tip> to add links to additional materials, sources, useful
+ facts, and examples:
Use notes <note></note> to highlight important information like
+ exceptions, limitations, or known issues:
+
Use the following labels in tables and paragraphs:
+|
+
+ |
+
+ |
+
|
+ |
+
+ |
+
|
+ |
+
+ |
+
|
+ |
+
+ |
+
Avoid using would. |
+ Displaying indicator
+ Displaying indicator + |
+
Omit then if possible. |
+ If a process is started by the user,
+ |
+
Replace he or she with they. |
+ If a process lasts less than one second, the user won’t be able to read the process name and
+ showing it would distract
+ |
+
Format names of UI elements with <control></control>. |
+ Apply the same rule for the
+ |
+
Format quotes with <code></code>. |
+ Do not use now in button labels. |
+
+
<shortcut></shortcut>. |
+ Press
+ |
+
Provide code snippets along the article to help developers implement the described look and behavior.
+If a code snippet is too big, put it at the end of the article and provide a link.
+To insert a snippet, use <code-block></code-block>. Read more in Writerside documentation.