You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/design/authoring-pages.md
+9-31Lines changed: 9 additions & 31 deletions
Original file line number
Diff line number
Diff line change
@@ -1,15 +1,13 @@
1
1
---
2
2
title: Authoring pages in a SharePoint site
3
3
description: Author pages using Edit mode, Published mode, and consider the mobile view.
4
-
ms.date: 06/28/2022
4
+
ms.date: 03/08/2023
5
5
ms.localizationpriority: high
6
6
---
7
7
8
8
# Authoring pages in a SharePoint site
9
9
10
-
Authoring pages in SharePoint is a simple process, but it does require some familiarity with the SharePoint environment, as well as an understanding of what and who you are designing the page for. A few basic principles, such as remembering to "Start simple" and "Build on what's working," are valuable things to consider as you start authoring. It's also a good idea to consistently remind yourself of your audience and the goals that you are trying to help them achieve.
11
-
12
-
<!-- Do we have content about the design principles that we can link to here? -->
10
+
Authoring pages in SharePoint is a simple process, but it does require some familiarity with the SharePoint environment, and an understanding of what and who you are designing the page for. A few basic principles, such as remembering to "Start simple" and "Build on what's working," are valuable things to consider as you start authoring. It's also a good idea to consistently remind yourself of your audience and the goals that you're trying to help them achieve.
13
11
14
12
The SharePoint page authoring experience has two modes:
15
13
@@ -20,79 +18,59 @@ The SharePoint page authoring experience has two modes:
20
18
21
19
When creating a new page, users have access to the authoring UI to add content to and customize the page content.
30
24
31
25
### Add hint and Toolbox
32
26
33
27
The add hint is a horizontal line with a plus icon that is visible when a web part is selected and on hover to indicate where page authors can add new web parts to their page. The Toolbox opens when a user selects the plus icon. The Toolbox contains all the web parts that can be added to a page.
34
28
35
-
<imgalt="Hint and toolbox showing tools"src="../images/design-authoring-add-hint.png"width="850">
36
-
37
-
<br/>
29
+
38
30
39
31
### Toolbar
40
32
41
33
A vertical toolbar and bounding box is part of the framework for every web part and is provided by the page. Each web part has an edit and delete action in the toolbar.
On hover/active, the hint bars are primary blue or the primary theme color for the site.
50
40
51
-
<imgalt="Hover and active state"src="../images/design-authoring-active-hover-01.png"width="850">
52
-
53
-
<br/>
41
+
54
42
55
43
The bounding box for a web part is gray by default, but picks up the primary blue or primary theme color for the site on hover or when the web part is selected.
56
44
57
-
<imgalt="Bounding box on and off"src="../images/design-authoring-active-hover-02.png"width="850">
58
-
59
-
<br/>
45
+
60
46
61
47
### Contextual edits
62
48
63
49
Design a WYSIWYG experience for web parts so that users can fill in information or add content that is displayed when published. This content should be entered on the page so that the user understands how it renders in the viewer. For example, titles and descriptions should be filled out where the text displays; new tasks should be added and modified in the context of the page.
64
50
65
51
66
52
67
-
<br/>
68
-
69
53
### Item-level edits
70
54
71
55
UI can change within the web part; for example, text can become a text field, or you can display UI to reorder items or to check off tasks in a web part. You can enable interactive functionality for web parts in edit mode, in read mode, or in both, depending on your design intent.
72
56
73
57
74
58
75
-
<br/>
76
-
77
59
### Property panes
78
60
79
61
Property panes are invoked via the **Edit** icon on the toolbar. Property panes should primarily contain configuration settings that enable or disable features that either show on the page, or make a call to a service to display content.
After the page is published, all editing UI is disabled for the viewer or reader of the page. To continue editing the page, the user selects the **Edit** button on the top right corner of the command bar.
All SharePoint pages are [responsive](grid-and-responsive-design.md) to allow the content of the page to be viewed on mobile devices. While designing a web part, it is important to understand how the new SharePoint site pages render across different devices.
73
+
All SharePoint pages are [responsive](grid-and-responsive-design.md) to allow the content of the page to be viewed on mobile devices. While designing a web part, it's important to understand how the new SharePoint site pages render across different devices.
96
74
97
75
Copy file name to clipboardExpand all lines: docs/design/reactive-and-nonreactive-web-parts.md
+11-17Lines changed: 11 additions & 17 deletions
Original file line number
Diff line number
Diff line change
@@ -1,47 +1,41 @@
1
1
---
2
2
title: Reactive and nonreactive SharePoint web parts
3
3
description: Reactive web parts are client-side only; nonreactive web parts have elements that require a server to operate.
4
-
ms.date: 06/28/2022
4
+
ms.date: 03/08/2023
5
5
ms.localizationpriority: high
6
6
---
7
7
8
8
# Reactive and nonreactive SharePoint web parts
9
9
10
10
Reactive web parts are client-side only; nonreactive web parts have elements that require a server to operate. We recommend that you build your SharePoint web parts to be reactive because that best fits the UX model and WYSIWYG principles for authoring. However, it might not be possible or cost-effective in all cases to build reactive web parts.
11
11
12
-
13
12
## Reactive web parts
14
13
15
14
Reactive web parts are fully client-side web parts. This means that each component configured in the property pane reflects the change made within the web part on the page. For example, for the To-Do List web part, unchecking “Completed Tasks” hides this view in the web part.
16
15
17
-
<imgalt="A reactive web part"src="../images/design-reactive-01.png"width="850">
16
+
18
17
19
18
## Nonreactive web parts
20
-
Nonreactive web parts are not fully client-side; generally, one or more properties need to make a call to set/pull or store data on a server. For nonreactive web parts, you should enable the **Apply** button at the bottom of the property pane.
21
19
22
-
You can also customize the **Apply** button to be a more specific action. <!-- Is this a reference to an image? (design-wp-pp-non-reactive.png) -->
20
+
Nonreactive web parts aren't fully client-side; generally, one or more properties need to make a call to set/pull or store data on a server. For nonreactive web parts, you should enable the **Apply** button at the bottom of the property pane.
23
21
24
-
<imgalt="A nonreactive web part with Apply and Cancel buttons"src="../images/design-reactive-02.png"width="850">
22
+
You can also customize the **Apply** button to be a more specific action.
25
23
26
-
<br/>
24
+
27
25
28
26
The following examples show nonreactive web parts in the context of the [three property pane structures](design-a-web-part.md).
29
27
30
-
**Single pane example**
31
-
32
-
<imgalt="A nonreactive web part with a single pane property structure"src="../images/design-reactive-03.png"width="850">
33
-
34
-
<br/>
28
+
### Single pane example
35
29
36
-
**Accordion groups example**
30
+
37
31
38
-
<imgalt="A nonreactive web part with an according groups pane property structure"src="../images/design-reactive-04.png"width="850">
32
+
### Accordion groups example
39
33
40
-
<br/>
34
+
41
35
42
-
**Steps pane example**
36
+
### Steps pane example
43
37
44
-
<imgalt="A nonreactive web part with a steps pane property structure"src="../images/design-reactive-05.png"width="850">
38
+
Copy file name to clipboardExpand all lines: docs/design/ui-text-for-web-parts.md
+25-43Lines changed: 25 additions & 43 deletions
Original file line number
Diff line number
Diff line change
@@ -7,84 +7,72 @@ ms.localizationpriority: medium
7
7
8
8
# UI text guidelines for SharePoint web parts
9
9
10
-
One aspect of creating effective web parts in SharePoint is to use simple, understandable, and concise UI text. By keeping your message clear and easy to understand, you ensure that customers move through your experiences quickly and can identify the content they are looking for. This article provides guidance for writing UI text for key areas within SharePoint web parts.
11
-
10
+
One aspect of creating effective web parts in SharePoint is to use simple, understandable, and concise UI text. By keeping your message clear and easy to understand, you ensure that customers move through your experiences quickly and can identify the content they're looking for. This article provides guidance for writing UI text for key areas within SharePoint web parts.
12
11
13
12
## Capitalization
14
13
15
14
Use sentence casing (first letter of first word is capitalized, the rest all lowercase) for all UI elements, including buttons, page titles, and control labels.
16
15
17
-
18
16
Always capitalize:
19
17
20
18
- The first word of a new sentence.
21
19
- The word following a colon in a title or heading. For example, "Step 1: Begin by entering your account information."
22
20
- Proper nouns, such as the names of people, cities, and so on.
23
21
24
-
<imgalt="Screenshot of an image alternative-text web part with sentence-style capitalization highlighted"src="../images/design-uitext-01.png"width="800">
22
+
25
23
26
-
<br/>
27
-
28
-
<imgalt="Screenshot of an image gallery add web part with sentence-style capitalization highlighted"src="../images/design-uitext-02.png"width="800">
24
+
29
25
30
26
## Punctuation
31
27
32
28
Follow the basic rules of punctuation to avoid grammatical errors in your experience. The following table provides guidance and reminders about what punctuation to use when, and why.
|Colons (:) | Use colons if you are introducing a list in the web part description.<br/>Don't use colons in UI labels.| Choose one of the following: Cats, Dogs, Quokkas |
37
-
|Commas (,) | Use serial commas (including before the word "and"). |I like cats, birds, and dogs. |
38
-
|Ellipses (…)| Use ellipses to show truncation and for progress indicator strings.<br/>Don't use ellipses to indicate that the user must make further choices.|Truncation: Last modified by John Armstr…<br/>Progress indicator: Uploading… |
39
-
|Periods (.) | Use periods as you normally would for descriptions.<br/>Don't use periods in titles, headings, or labels. Don't use periods for radio button options or check boxes. | Select the content that you want to highlight and how you want it displayed. Use a filter to narrow your selection. |
| Colons (:) | Use colons if you're introducing a list in the web part description.<br/>Don't use colons in UI labels. | Choose one of the following: Cats, Dogs, Quokkas |
33
+
| Commas (,) | Use serial commas (including before the word "and"). | I like cats, birds, and dogs. |
34
+
| Ellipses (…) | Use ellipses to show truncation and for progress indicator strings.<br/>Don't use ellipses to indicate that the user must make further choices. | Truncation: Last modified by John Armstr…<br/>Progress indicator: Uploading… |
35
+
| Periods (.) | Use periods as you normally would for descriptions.<br/>Don't use periods in titles, headings, or labels. Don't use periods for radio button options or check boxes. | Select the content that you want to highlight and how you want it displayed. Use a filter to narrow your selection. |
42
36
43
37
## Voice and tone
44
38
45
39
Crafting the right tone in your product communication is essential to building a strong, lasting relationship with your audience. Try to keep your words crisp and clear, warm and relaxed, and approachable. How you talk to your audience influences how they engage with your site and content, and how much value they derive from it.
46
40
47
-
**Do:**
41
+
### Do
48
42
49
43
- Use a casual, conversational tone in the UI.
50
-
- Use contractions. For example, use "can't" instead of "cannot".
44
+
- Use contractions. For example, use "can't" instead of "can't".
51
45
- Read your UI text out loud to test the tone. Does it sound like everyday language?
52
46
- Use simple words.
53
47
- Remove technical details if they're not relevant to the user experience.
54
-
- Use "Please" only if you are inconveniencing the user. Avoid overuse.
48
+
- Use "Please" only if you're inconveniencing the user. Avoid overuse.
55
49
- Use "Sorry" only in error messages in SharePoint that result in serious problems for the customer.
56
50
57
-
58
-
**Don't:**
51
+
### Don't
59
52
60
53
- Clutter the UI text with unnecessary repetition. Make every word meaningful.
61
54
62
-
63
55
## Pronouns
64
56
65
57
Avoid pronouns in UI elements if possible. If you can say something equally well without using a pronoun, don't use it.
66
58
67
59
If your design does warrant using pronouns, apply the following guidelines to make sure that you're using them correctly.
68
60
69
-
**Do:**
61
+
### Do
70
62
71
63
- Use second person ("you" or "your") when you're presenting something that belongs to the user. For example, "Your drafts" or "Your images".
72
64
- Use first person ("me" or "my") for UI in which the user instructs the service to do something. For example, "Alert me when someone responds to my post."
73
65
- Use "they" or "their" as a singular possessive modifier to avoid awkward "he/she" or "his/her" constructs. Ideally, rewrite the sentence as plural if possible.
74
66
- Avoid using "them"; instead, use words like "someone" or "people". For example, "Enter a user name and ___domain to give someone permission to use this PC."
75
67
76
-
<imgalt="An image showing the correct use of the second person you and the incorrect use of the third person users in the UI"src="../images/design-uitext-03.png"width="800">
68
+
77
69
78
-
<br/>
70
+
79
71
80
-
<imgalt="An image showing the correct use of the UI text Select the page you want people to see first"src="../images/design-uitext-04.png"width="800">
81
-
82
-
**Don't:**
72
+
### Don't
83
73
84
74
- Use third person references, as they sound impersonal and can create a disconnected customer experience. Instead of saying "Users can change the layout", use a phrase like "You can change the layout".
85
75
86
-
87
-
88
76
## Error messages
89
77
90
78
Error conditions are inherent in any software or service. Your error messages can affect the overall user satisfaction with the product. A good error message should do the following:
@@ -93,50 +81,44 @@ Error conditions are inherent in any software or service. Your error messages ca
93
81
- Provide a workaround or resolution suggestions.
94
82
- Show empathy.
95
83
96
-
<!-- You might need to explain how to show empathy in an error message, without using "sorry". -->
97
-
98
84
The following is an example of an error message that occurs when a user tries to edit a page that's checked out by another user.
| Another user is currently editing this page. Please try again in a few minutes. |
104
89
105
-
106
90
## Links to help articles
107
91
108
92
Make an effort to link strategically to help articles. Try to anticipate where the user might need help, and then include a link to the help article close to that UI element. The following are some key things to remember when you place help article links in your UI.
109
93
110
-
**Do:**
94
+
### Do
111
95
112
96
- Keep the in-product help links specific. Ensure that the target article is appropriate. When the user opens the article, they should be able to locate the information they need.
113
97
- Use natural language for your hyperlinks.
114
98
115
-
<!-- You might want to provide an example of "natural" language. -->
116
-
117
-
**Don’t:**
99
+
### Don't
118
100
119
101
- Put a help article link next to every UI element. This results in visual noise.
120
102
- Include multiple links that go to the same target in the same UI.
121
103
- Use "click here" for the text for your hyperlink.
122
104
123
-
<imgalt="An image of the More information and examples as the help link text"src="../images/design-uitext-05.png"width="800">
105
+
124
106
125
107
## Hint text
126
108
127
109
Hint text, or ghost text, is the text element you display in a UI element, typically a text box, to help the user interact with the UI. The hint text gives information about what the user should enter. For example, it might mention field restrictions or show an example.
128
110
129
-
**Do:**
111
+
### Do
130
112
131
113
- Use hint text sparingly, and only if it helps the user. Not all UI elements require hint text. For some complex fields, hint text can help provide more context and clarity. For example, if you have a field that requires the user to enter a secured URL, the hint text https://www.example.com might be more helpful than the text **Enter secure URL here.**
132
114
133
-
**Don't**
115
+
### Don't
134
116
135
117
- Repeat the label. For example, if you have a text box with the label **Name**, the hint text **Enter name** is redundant and potentially confusing.
136
118
137
119
The following hint text is for the embed web part. The text field can accept a secure website address or an `<iframe>` embed code. The text shows an example of both.
138
120
139
-
<imgalt="Web part hint text"src="../images/design-uitext-06.png"width="800">
121
+
0 commit comments