Skip to content

Commit 305d4b0

Browse files
nielslyngsoenielslyngsoe
authored
dialog guideline (#558)
* dialog guideline document
1 parent 2ecc805 commit 305d4b0

File tree

3 files changed

+290
-9
lines changed

3 files changed

+290
-9
lines changed

‎packages/uui-css/lib/guidelines.story.ts

Lines changed: 287 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,11 @@
11
import { html } from 'lit';
22
import readme from '../README.md?raw';
33

4+
import '@umbraco-ui/uui-dialog/lib';
5+
import '@umbraco-ui/uui-dialog-layout/lib';
6+
import '@umbraco-ui/uui-button/lib';
7+
import '@umbraco-ui/uui-icon-registry-essential/lib';
8+
49
export default {
510
title: 'Design/Style Guide',
611
parameters: {
@@ -98,10 +103,10 @@ export const Typography = () => html`
98103
<h2>Setup</h2>
99104
<p>
100105
The Umbraco Typography can be used on a full web application or on a
101-
dedicated spot. To set the font use the <b>uui-font</b> class on the root
102-
element or a element of interest. Additionally the <b>uui-text</b> class
103-
must be set to expose the Umbraco Typography Styles. See the UUI-CSS
104-
package for more.
106+
dedicated spot. To set the font use the <strong>uui-font</strong> class on
107+
the root element or an element of interest. Additionally, the
108+
<strong>uui-text</strong> class must be set to expose the Umbraco
109+
Typography Styles. See the UUI-CSS package for more.
105110
</p>
106111
107112
<h2>Paragraphs & other elements</h2>
@@ -134,8 +139,9 @@ export const Typography = () => html`
134139
<h2>Headlines</h2>
135140
<p>
136141
The headlines can be used via the dedicated native tag or by one of the
137-
equivalent classes. This means that <b>Headline 1</b> can be used used via
138-
<b>&#60;h1&#62;</b> or the class <b>uui-h1</b>.
142+
equivalent classes. This means that <strong>Headline 1</strong> can be
143+
used used via <strong>&#60;h1&#62;</strong> or the class
144+
<strong>uui-h1</strong>.
139145
</p>
140146
<h5>Headline H5</h5>
141147
<h4>Headline H4</h4>
@@ -151,3 +157,278 @@ export const Typography = () => html`
151157
</ul>
152158
</article>
153159
`;
160+
161+
export const Dialog = () => html`
162+
<article style="max-width:580px;">
163+
<div
164+
style="display:block; border-bottom: 1px solid var(--uui-color-cocoa-black); padding-top: var(--uui-size-layout-5); margin-bottom:var(--uui-size-layout-3); padding-bottom:var(--uui-size-layout-1);">
165+
<h1>Dialog Style Guide</h1>
166+
<p class="uui-lead">
167+
The following guide will suit you to write sharp and concrete dialogs.
168+
Guiding the user to the right action. Requires minimal cognitive effort
169+
by delivering a very clear message.
170+
</p>
171+
172+
<br />
173+
174+
<uui-dialog>
175+
<uui-dialog-layout headline="Headline">
176+
Description
177+
<uui-button slot="actions">Cancel</uui-button>
178+
<uui-button slot="actions" look="primary" color="positive"
179+
>Action</uui-button
180+
>
181+
</uui-dialog-layout>
182+
</uui-dialog>
183+
<br />
184+
185+
<p>
186+
The knowledge of our users varies and this must be carefully considered
187+
when writing dialogs. Some will feel so much at home that they will
188+
assume the message, for those users we want something that is easy to
189+
digest for their eyes.<br />
190+
Others are learning the system and need to be suited to all of the
191+
consequences to have confidence in what they do. They will read everything
192+
but not necessarily understand all words — Therefore we will use the
193+
description to write sentences and confirm the understanding.
194+
</p>
195+
196+
<p>
197+
One of the dialogs below uses the word 'publishing', and then the
198+
description unfolds that it will make something public available.
199+
<br />
200+
201+
Below you will see a few examples that give you some examples of how
202+
this can be done in condensed form.
203+
</p>
204+
</div>
205+
206+
<h2>Headline</h2>
207+
<p>
208+
The headline must represent the action that will be taken in a short form.
209+
That way the user can quickly identify what they are asked to take action
210+
on. In some cases there is room to write out the name of the target, but
211+
do only so if it will become the last part of the sentence.
212+
</p>
213+
<blockquote>
214+
If the user feels unsure, they will jump to read the description. Use this
215+
to keep the headline super short.
216+
</blockquote>
217+
<h5>Good examples:</h5>
218+
<ul>
219+
<li>Delete ´My Page 1´</li>
220+
<li>Publish with descendants</li>
221+
<li>Transfer to ´Development´</li>
222+
</ul>
223+
<h5>Bad examples:</h5>
224+
<ul>
225+
<li>Confirm deleting ´My Page 1´</li>
226+
<li>Publish ´My Page 1´ with descendants</li>
227+
<li>Transfer document</li>
228+
</ul>
229+
230+
<br />
231+
232+
<h2>Description</h2>
233+
<p>
234+
The description should be used to explain the headline without
235+
assumptions.<br />
236+
Try to avoid repeating what the headline said, instead use the description
237+
to clarify the effect of the action.<br />
238+
</p>
239+
<p>
240+
Notice the description can be styled, for an easier read. We will use bold
241+
to highlight data. In this way it makes the data stand out and makes it
242+
easier to anchor that part of the text.
243+
</p>
244+
245+
<h4>Good examples:</h4>
246+
247+
<uui-dialog>
248+
<uui-dialog-layout headline="Delete 'My Page 1'">
249+
<strong>My Page 1</strong> and all content items underneath will be
250+
transferred to the trash bin.
251+
<uui-button slot="actions">Cancel</uui-button>
252+
<uui-button slot="actions" look="primary" color="danger"
253+
>Delete</uui-button
254+
>
255+
</uui-dialog-layout>
256+
</uui-dialog>
257+
258+
<br />
259+
<p>
260+
In the above example the description helps the user understand the effect —
261+
and guides the user by mentioning where it goes.
262+
</p>
263+
<br />
264+
265+
<uui-dialog>
266+
<uui-dialog-layout headline="Publish with descendants">
267+
Make <strong>My Page 1</strong> and all content items underneath
268+
publicly available.
269+
<uui-button slot="actions">Cancel</uui-button>
270+
<uui-button slot="actions" look="primary" color="positive"
271+
>Publish</uui-button
272+
>
273+
</uui-dialog-layout>
274+
</uui-dialog>
275+
276+
<br />
277+
<p>
278+
This helps the user understand the effect of publishing and ´descendants´
279+
— which for someone who does not have experience can be hard to
280+
understand at first.
281+
</p>
282+
283+
<br />
284+
285+
<uui-dialog>
286+
<uui-dialog-layout headline="Transfer to 'Development'">
287+
Create or update <strong>My Page 1</strong> on the
288+
<strong>Development</strong> environment. This does not include
289+
descendant content.
290+
<uui-button slot="actions">Cancel</uui-button>
291+
<uui-button slot="actions" look="primary" color="positive"
292+
>Transfer</uui-button
293+
>
294+
</uui-dialog-layout>
295+
</uui-dialog>
296+
297+
<br />
298+
<p>
299+
The description must clarify all the factors, in this example both the
300+
name of the target item and the new environment name is written out.
301+
</p>
302+
<br />
303+
304+
<uui-dialog>
305+
<uui-dialog-layout headline="Delete 'My Block Type 1'">
306+
This will permanently delete <strong>My Block Type 1</strong>.
307+
<br /><br />
308+
<i>
309+
Content using this type will no longer be editable and will be shown
310+
as unsupported content.
311+
</i>
312+
<uui-button slot="actions">Cancel</uui-button>
313+
<uui-button slot="actions" look="primary" color="danger"
314+
>Delete</uui-button
315+
>
316+
</uui-dialog-layout>
317+
</uui-dialog>
318+
319+
<br />
320+
<p>
321+
Describe the direct effect first. And if there are secondary effects then
322+
describe it as well. In this example italicized text is used to describe
323+
the secondary effect.
324+
</p>
325+
<br />
326+
327+
<h4>Bad examples:</h4>
328+
329+
<uui-dialog>
330+
<uui-dialog-layout headline="Delete 'My Page 1'">
331+
Are you sure you want to delete this content and all content items
332+
underneath?
333+
<uui-button slot="actions">Cancel</uui-button>
334+
<uui-button slot="actions" look="primary" color="danger"
335+
>Confirm</uui-button
336+
>
337+
</uui-dialog-layout>
338+
</uui-dialog>
339+
340+
<br />
341+
<p>
342+
No need to write out "Are you sure", the concept of a dialog is a point of
343+
confirmation so it is intuitively part of the format.
344+
</p>
345+
<br />
346+
347+
<uui-dialog>
348+
<uui-dialog-layout headline="Publish with descendants">
349+
Are you sure you want to publish <strong>My Page 1</strong> and all
350+
descendant items.
351+
<uui-button slot="actions">Cancel</uui-button>
352+
<uui-button slot="actions" look="primary" color="positive"
353+
>Publish</uui-button
354+
>
355+
</uui-dialog-layout>
356+
</uui-dialog>
357+
358+
<br />
359+
<p>
360+
The description here is not helping the user if they are slightly in doubt
361+
about the meaning of the words 'publishing' or 'descendant'.
362+
</p>
363+
<br />
364+
365+
<uui-dialog>
366+
<uui-dialog-layout headline="Transfer to 'Development'">
367+
Confirm transferring <strong>My Page 1</strong> to the
368+
<strong>Development</strong> environment. This does not include
369+
descendant content items.
370+
<uui-button slot="actions">Cancel</uui-button>
371+
<uui-button slot="actions" look="primary" color="positive"
372+
>Transfer 'My Page 1'</uui-button
373+
>
374+
</uui-dialog-layout>
375+
</uui-dialog>
376+
377+
<br />
378+
<p>
379+
This example displays how writing the name of the page in the action
380+
button is making it hard to read. See for yourself how much easier it is
381+
to read the page name as part of the description instead, leaving the
382+
action very easy to read.
383+
</p>
384+
<br />
385+
386+
<h2>Actions</h2>
387+
<p>
388+
Ideally, a dialog is a question of whether the user wants to carry out an
389+
action or refuse it. Leaving the user with only two options.<br />
390+
For fast visual confirmation the wording on the actions must be short and
391+
clear. Use the name of the actual action. And make sure to use that exact
392+
same word in the headline or alternatively in the description. In this way
393+
it establishes a connection between the text and the action.
394+
</p>
395+
396+
<uui-dialog>
397+
<uui-dialog-layout headline="Delete 'My Page 1'">
398+
<strong>My Page 1</strong> and all content items underneath will be
399+
transferred to the trash bin.
400+
<uui-button slot="actions">Cancel</uui-button>
401+
<uui-button slot="actions" look="primary" color="danger"
402+
>Delete</uui-button
403+
>
404+
</uui-dialog-layout>
405+
</uui-dialog>
406+
407+
<br />
408+
<p>
409+
There the action is named 'Delete' which has a close relation to the
410+
headline 'Delete My Page'. In this way the headline helps clarify what the
411+
action does.<br />
412+
</p>
413+
<br />
414+
415+
<uui-dialog>
416+
<uui-dialog-layout headline="Publish with descendants">
417+
Make <strong>My Page 1</strong> and all content items underneath
418+
publicly available.
419+
<uui-button slot="actions">Cancel</uui-button>
420+
<uui-button slot="actions" look="primary" color="positive"
421+
>Publish</uui-button
422+
>
423+
</uui-dialog-layout>
424+
</uui-dialog>
425+
<br />
426+
<p>
427+
In this case Publish, binds with the headline cause its using the same
428+
word. If the user is unsure about the target, their eyes can easily spot
429+
the bold text without reading the actual description and intuitively
430+
conclude a relation between the Bold text and the action.<br />
431+
</p>
432+
<br />
433+
</article>
434+
`;

‎packages/uui-dialog/lib/uui-dialog.element.ts

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ export class UUIDialogElement extends LitElement {
1313
:host {
1414
position: relative;
1515
display: block;
16-
max-width: 400px;
16+
max-width: 580px;
1717
color: var(--uui-color-text);
1818
1919
background-color: var(

‎packages/uui-dialog/lib/uui-dialog.story.ts

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -40,8 +40,8 @@ export const ConfirmDialogPositive: Story = () => html`
4040
<uui-dialog>
4141
<uui-dialog-layout headline="Publish with descendants">
4242
<p>
43-
Publish <b>This example</b> and all content items underneath and thereby
44-
making their content publicly available.
43+
Make <b>My Page 1</b> and all content items underneath publicly
44+
available.
4545
</p>
4646
<uui-button slot="actions">Cancel</uui-button>
4747
<uui-button slot="actions" look="primary" color="positive"

0 commit comments

Comments
 (0)