Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(docs/styling): add dos and donts layout and styling #1780

Merged
merged 31 commits into from
Apr 1, 2025
Merged

feat(docs/styling): add dos and donts layout and styling #1780

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
31 commits
Select commit Hold shift + click to select a range
f175939
feat: add does and donts layout and styling
matthiashader Mar 18, 2025
82fb5b0
feat: adapt docusaurus config
matthiashader Mar 18, 2025
8d4f28a
fix: revert unindented change, format, small fixes
matthiashader Mar 18, 2025
70417ca
fix: sonarqube
matthiashader Mar 18, 2025
b7bce63
Merge branch 'release-3.0.0' into docs/2420-does-donts-layout-styling
matthiashader Mar 19, 2025
bbaf79e
fix: sonarqube issues
matthiashader Mar 19, 2025
a002bc7
fix: sonarqube issues
matthiashader Mar 19, 2025
a58737c
fix: sonarqube issues
matthiashader Mar 19, 2025
7678ebc
Merge remote-tracking branch 'origin/docs/2420-does-donts-layout-styl…
matthiashader Mar 19, 2025
049e31e
fix: moved custom variant to components and changed icon usage
matthiashader Mar 19, 2025
c56d1d6
Merge branch 'release-3.0.0' into docs/2420-does-donts-layout-styling
matthiashader Mar 19, 2025
094a4ae
fix: move css
matthiashader Mar 19, 2025
6a8a8eb
Merge branch 'release-3.0.0' into docs/2420-does-donts-layout-styling
danielleroux Mar 20, 2025
7f25bfa
fix: adjust hierarchy
matthiashader Mar 20, 2025
82866e2
Merge branch 'release-3.0.0' into docs/2420-does-donts-layout-styling
matthiashader Mar 20, 2025
5b6c8c6
fix: resolve do / donts
matthiashader Mar 25, 2025
1e291fd
Merge branch 'release-3.0.0' into docs/2420-does-donts-layout-styling
matthiashader Mar 25, 2025
1ad3124
fix: reimplement admonitions
matthiashader Mar 26, 2025
42aa0f9
Merge branch 'release-3.0.0' into docs/2420-does-donts-layout-styling
matthiashader Mar 26, 2025
225c651
fix: minor issue in md
matthiashader Mar 26, 2025
e7c2068
Merge remote-tracking branch 'origin/docs/2420-does-donts-layout-styl…
matthiashader Mar 26, 2025
ca69a33
fix: minor issue
matthiashader Mar 26, 2025
ce56d94
Merge remote-tracking branch 'origin/docs/2420-does-donts-layout-styl…
matthiashader Mar 26, 2025
0992d0a
fix: removed admonition, reimplemented as react component
matthiashader Mar 26, 2025
70fd158
fix: revert change
matthiashader Mar 26, 2025
63b221c
Merge branch 'release-3.0.0' into docs/2420-does-donts-layout-styling
matthiashader Mar 27, 2025
d4dc02a
docs: fix bullet point formatting
nuke-ellington Mar 28, 2025
70327c6
fix: revert unwanted change
matthiashader Apr 1, 2025
50346b3
Merge remote-tracking branch 'origin/release-3.0.0' into docs/2420-do…
danielleroux Apr 1, 2025
b00b94b
some minor refactoring
danielleroux Apr 1, 2025
19ce587
refactor class usage
danielleroux Apr 1, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
173 changes: 61 additions & 112 deletions packages/documentation/docs/guidelines/language/basics.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ no_single_tab: true
description: "Dive into the fundamental principles of UX writing, where you'll learn how to create text that enhances user experience by being clear, concise, and user-friendly. This section lays the groundwork for all your UX writing endeavors."
---

import Guideline from '@site/src/components/Guideline';
import DoAndDont from '@site/src/components/DoAndDont';

#

Expand Down Expand Up @@ -38,33 +38,22 @@ import Guideline from '@site/src/components/Guideline';

- Avoid using negative contractions as they can appear too informal

<div class="d-flex flex-wrap">
<span class="m-2">
<Guideline do label='their, them, theirs, salesperson'></Guideline>
<Guideline do={false} label='his, hers, him, salesman'></Guideline>
</span>

<span class="m-2">
<Guideline do label='Welcome to this application'></Guideline>
<Guideline do={false} label='Hey there!'></Guideline>
</span>

<span class="m-2">
<Guideline do label='X appears when detail view has selected events'></Guideline>
<Guideline do={false} label='X doesn’t appear if detail view has no selected events'></Guideline>
</span>

<span class="m-2">
<Guideline do label='cannot, will not'></Guideline>
<Guideline do={false} label='can’t, won’t'></Guideline>
</span>

<span class="m-2">
<Guideline do label='you’ll, we’ve'></Guideline>
<Guideline do={false} label='you will, we have'></Guideline>
</span>

</div>
<DoAndDont>
<DoAndDont.Do>
<DoAndDont.Item>their, them, theirs, salesperson</DoAndDont.Item>
<DoAndDont.Item>Welcome to this application</DoAndDont.Item>
<DoAndDont.Item>X appears when detail view has selected events</DoAndDont.Item>
<DoAndDont.Item>cannot, will not</DoAndDont.Item>
<DoAndDont.Item>you’ll, we’ve</DoAndDont.Item>
</DoAndDont.Do>
<DoAndDont.Dont>
<DoAndDont.Item>his, hers, him, salesman</DoAndDont.Item>
<DoAndDont.Item>Hey there!</DoAndDont.Item>
<DoAndDont.Item>X doesn’t appear if detail view has no selected events</DoAndDont.Item>
<DoAndDont.Item>can’t, won’t</DoAndDont.Item>
<DoAndDont.Item>you will, we have</DoAndDont.Item>
</DoAndDont.Dont>
</DoAndDont>

## Length

Expand All @@ -88,90 +77,50 @@ import Guideline from '@site/src/components/Guideline';

- Capitalize named app functions and UI elements: Go to Settings, Allocate users in User management, Press Ok

<div class="d-flex flex-wrap">
<span class="m-2">
<Guideline do label='Go to Settings'></Guideline>
<Guideline do={false} label='Go To Settings'></Guideline>
</span>

<span class="m-2">
<Guideline do label='Press OK'></Guideline>
<Guideline do={false} label='Press Ok'></Guideline>
</span>

<span class="m-2">
<Guideline do label='Log in'></Guideline>
<Guideline do={false} label='LOG IN'></Guideline>
</span>

<span class="m-2">
<Guideline do label='For more information, see Siemens Industry Online Support.'></Guideline>
<Guideline do={false} label='For more information, see Siemens industry online support.'></Guideline>
</span>

</div>
<DoAndDont>
<DoAndDont.Do>
<DoAndDont.Item>Go to Settings</DoAndDont.Item>
<DoAndDont.Item>Press OK</DoAndDont.Item>
<DoAndDont.Item>Log in</DoAndDont.Item>
<DoAndDont.Item>For more information, see Siemens Industry Online Support.</DoAndDont.Item>
</DoAndDont.Do>
<DoAndDont.Dont>
<DoAndDont.Item>Go To Settings</DoAndDont.Item>
<DoAndDont.Item>Press Ok</DoAndDont.Item>
<DoAndDont.Item>LOG IN</DoAndDont.Item>
<DoAndDont.Item>For more information, see Siemens industry online support.</DoAndDont.Item>
</DoAndDont.Dont>
</DoAndDont>

## Common UX wording mistakes

<div class="d-flex flex-wrap">
<span class="m-2">
<Guideline do label='time zone'></Guideline>
<Guideline do={false} label='timezone'></Guideline>
</span>

<span class="m-2">
<Guideline do label='log file'></Guideline>
<Guideline do={false} label='logfile'></Guideline>
</span>

<span class="m-2">
<Guideline do label='log in (as an action)'></Guideline>
<Guideline do={false} label='login'></Guideline>
</span>

<span class="m-2">
<Guideline do label='login (as a noun)'></Guideline>
<Guideline do={false} label='log in'></Guideline>
</span>

<span class="m-2">
<Guideline do label='equipment'></Guideline>
<Guideline do={false} label='equipments'></Guideline>
</span>

<span class="m-2">
<Guideline do label='feedback'></Guideline>
<Guideline do={false} label='feedbacks'></Guideline>
</span>

<span class="m-2">
<Guideline do label='training'></Guideline>
<Guideline do={false} label='trainings'></Guideline>
</span>

<span class="m-2">
<Guideline do label='current'></Guideline>
<Guideline do={false} label='actual'></Guideline>
</span>

<span class="m-2">
<Guideline do label='avoid "shall"'></Guideline>
<Guideline do={false} label='user shall manage users'></Guideline>
</span>

<span class="m-2">
<Guideline do label='Siemens has'></Guideline>
<Guideline do={false} label='Siemens have'></Guideline>
</span>

<span class="m-2">
<Guideline do label='34 million / 35 billion'></Guideline>
<Guideline do={false} label='34’ / 35“'></Guideline>
</span>

<span class="m-2">
<Guideline do label='34 million'></Guideline>
<Guideline do={false} label='34 millions'></Guideline>
</span>

</div>
<DoAndDont>
<DoAndDont.Do>
<DoAndDont.Item>time zone</DoAndDont.Item>
<DoAndDont.Item>log file</DoAndDont.Item>
<DoAndDont.Item>log in (as an action)</DoAndDont.Item>
<DoAndDont.Item>login (as a noun)</DoAndDont.Item>
<DoAndDont.Item>equipment</DoAndDont.Item>
<DoAndDont.Item>feedback</DoAndDont.Item>
<DoAndDont.Item>training</DoAndDont.Item>
<DoAndDont.Item>current</DoAndDont.Item>
<DoAndDont.Item>avoid "shall"</DoAndDont.Item>
<DoAndDont.Item>Siemens has</DoAndDont.Item>
<DoAndDont.Item>34 million / 35 billion</DoAndDont.Item>
<DoAndDont.Item>34 million</DoAndDont.Item>
</DoAndDont.Do>
<DoAndDont.Dont>
<DoAndDont.Item>timezone</DoAndDont.Item>
<DoAndDont.Item>logfile</DoAndDont.Item>
<DoAndDont.Item>login</DoAndDont.Item>
<DoAndDont.Item>log in</DoAndDont.Item>
<DoAndDont.Item>equipments</DoAndDont.Item>
<DoAndDont.Item>feedbacks</DoAndDont.Item>
<DoAndDont.Item>trainings</DoAndDont.Item>
<DoAndDont.Item>actual</DoAndDont.Item>
<DoAndDont.Item>user shall manage users</DoAndDont.Item>
<DoAndDont.Item>Siemens have</DoAndDont.Item>
<DoAndDont.Item>34’ / 35“</DoAndDont.Item>
<DoAndDont.Item>34 millions</DoAndDont.Item>
</DoAndDont.Dont>
</DoAndDont>
108 changes: 48 additions & 60 deletions packages/documentation/docs/guidelines/language/best-practices.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ no_single_tab: true
description: 'Familiarize yourself with general best practices for UX writing to maintain consistency and clarity across all your content. This section offers overarching guidelines that apply to various aspects of UX writing.'
---

import Guideline from '@site/src/components/Guideline';
import DoAndDont from '@site/src/components/DoAndDont';

#

Expand All @@ -20,28 +20,20 @@ import Guideline from '@site/src/components/Guideline';

- Confirmation messages: Use the same verb as the transitional text

<div class="d-flex flex-wrap">
<span class="m-2">
<Guideline do label='Updating user roles…'></Guideline>
<Guideline do={false} label='Getting ready…'></Guideline>
</span>

<span class="m-2">
<Guideline do label='Submitting log files…'></Guideline>
<Guideline do={false} label='Chopping fruit…'></Guideline>
</span>

<span class="m-2">
<Guideline do label='Saving project… > Project saved'></Guideline>
<Guideline do={false} label='Saving project… > Project uploaded'></Guideline>
</span>

<span class="m-2">
<Guideline do label='Training models… > Models trained'></Guideline>
<Guideline do={false} label='Training models… > Training done'></Guideline>
</span>

</div>
<DoAndDont>
<DoAndDont.Do>
<DoAndDont.Item>Updating user roles…</DoAndDont.Item>
<DoAndDont.Item>Submitting log files…</DoAndDont.Item>
<DoAndDont.Item>Saving project… > Project saved</DoAndDont.Item>
<DoAndDont.Item>Training models… > Models trained</DoAndDont.Item>
</DoAndDont.Do>
<DoAndDont.Dont>
<DoAndDont.Item>Getting ready…</DoAndDont.Item>
<DoAndDont.Item>Chopping fruit…</DoAndDont.Item>
<DoAndDont.Item>Saving project… > Project uploaded</DoAndDont.Item>
<DoAndDont.Item>Training models… > Training done</DoAndDont.Item>
</DoAndDont.Dont>
</DoAndDont>

## Error messages

Expand All @@ -55,15 +47,17 @@ import Guideline from '@site/src/components/Guideline';

- Use … to show an action is required, i.e. fill this in …

<div class="d-flex flex-wrap">
<span class="m-2">
<Guideline do label='System error: You’re offline. Check your connection and try again.'></Guideline>
<Guideline do label='File error: We cannot upload this file. Try uploading again.'></Guideline>
<Guideline do label='Permission error: To carry out this task, you need more permissions. Contact admin to change permissions. '></Guideline>
<Guideline do={false} label='What did you do!?'></Guideline>
<Guideline do={false} label='The email address you entered does not match the required format. Please enter your email address using the standard format.'></Guideline>
</span>
</div>
<DoAndDont>
<DoAndDont.Do>
<DoAndDont.Item>System error: You’re offline. Check your connection and try again.</DoAndDont.Item>
<DoAndDont.Item>File error: We cannot upload this file. Try uploading again.</DoAndDont.Item>
<DoAndDont.Item>Permission error: To carry out this task, you need more permissions. Contact admin to change permissions.</DoAndDont.Item>
</DoAndDont.Do>
<DoAndDont.Dont>
<DoAndDont.Item>What did you do!?</DoAndDont.Item>
<DoAndDont.Item>The email address you entered does not match the required format. Please enter your email address using the standard format.</DoAndDont.Item>
</DoAndDont.Dont>
</DoAndDont>

## Empty-state text

Expand All @@ -77,23 +71,18 @@ import Guideline from '@site/src/components/Guideline';

- Use wording to show users how to resolve the empty state, e.g. with an action, click, etc.

<div class="d-flex flex-wrap">
<span class="m-2">
<Guideline do label='Allocate users in User management.'></Guideline>
<Guideline do={false} label='No allocated users.'></Guideline>
</span>

<span class="m-2">
<Guideline do label='To show rows, select a project.'></Guideline>
<Guideline do={false} label='No rows to show.'></Guideline>
</span>

<span class="m-2">
<Guideline do label='To save a project, select Save in Project detail list.'></Guideline>
<Guideline do={false} label='No projects saved.'></Guideline>
</span>

</div>
<DoAndDont>
<DoAndDont.Do>
<DoAndDont.Item>Allocate users in User management.</DoAndDont.Item>
<DoAndDont.Item>To show rows, select a project.</DoAndDont.Item>
<DoAndDont.Item>To save a project, select Save in Project detail list.</DoAndDont.Item>
</DoAndDont.Do>
<DoAndDont.Dont>
<DoAndDont.Item>No allocated users.</DoAndDont.Item>
<DoAndDont.Item>No rows to show.</DoAndDont.Item>
<DoAndDont.Item>No projects saved.</DoAndDont.Item>
</DoAndDont.Dont>
</DoAndDont>

## Restoring behavior of items

Expand All @@ -105,14 +94,13 @@ import Guideline from '@site/src/components/Guideline';

- Do not use Delete and Remove as synonym

<div class="d-flex flex-wrap">
<span class="m-2">
<Guideline do label='Create a chart and delete a chart'></Guideline>
<Guideline do={false} label='Create a chart and remove it'></Guideline>
</span>

<span class="m-2">
<Guideline do label='Add a sensor to a chart and remove a sensor from chart'></Guideline>
<Guideline do={false} label='Add a sensor and delete the sensor'></Guideline>
</span>
</div>
<DoAndDont>
<DoAndDont.Do>
<DoAndDont.Item>Create a chart and delete a chart</DoAndDont.Item>
<DoAndDont.Item>Add a sensor to a chart and remove a sensor from chart</DoAndDont.Item>
</DoAndDont.Do>
<DoAndDont.Dont>
<DoAndDont.Item>Create a chart and remove it</DoAndDont.Item>
<DoAndDont.Item>Add a sensor and delete the sensor</DoAndDont.Item>
</DoAndDont.Dont>
</DoAndDont>
44 changes: 21 additions & 23 deletions packages/documentation/docs/guidelines/language/dialogs-and-buttons.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ no_single_tab: true
description: 'Discover guidelines for writing dialogs and button labels to ensure clear and actionable instructions. This section helps you create effective prompts and calls to action that enhance user interaction.'
---

import Guideline from '@site/src/components/Guideline';
import DoAndDont from '@site/src/components/DoAndDont';

#

Expand All @@ -26,32 +26,30 @@ import Guideline from '@site/src/components/Guideline';

- Only use ‘OK’ as an option if you cannot find an appropriate verb

<div class="d-flex flex-wrap">
<span class="m-2">
<Guideline do label='Title: Add user / Buttons: Cancel, Add'></Guideline>
<Guideline do={false} label='Title: Add user / Buttons: Cancel, OK'></Guideline>
</span>

<span class="m-2">
<Guideline do label='Title: Delete file / Buttons: Cancel, Delete'></Guideline>
<Guideline do={false} label='Title: Are you sure / Buttons: Cancel, Delete'></Guideline>
</span>

<span class="m-2">
<Guideline do label='Title: Edit details / Buttons: Cancel, Save'></Guideline>
<Guideline do={false} label='Title: Edit details / Buttons: Cancel, Edit'></Guideline>
</span>
</div>
<DoAndDont>
<DoAndDont.Do>
<DoAndDont.Item>Title: Add user / Buttons: Cancel, Add</DoAndDont.Item>
<DoAndDont.Item>Title: Delete file / Buttons: Cancel, Delete</DoAndDont.Item>
<DoAndDont.Item>Title: Edit details / Buttons: Cancel, Save</DoAndDont.Item>
</DoAndDont.Do>
<DoAndDont.Dont>
<DoAndDont.Item>Title: Add user / Buttons: Cancel, OK</DoAndDont.Item>
<DoAndDont.Item>Title: Are you sure / Buttons: Cancel, Delete</DoAndDont.Item>
<DoAndDont.Item>Title: Edit details / Buttons: Cancel, Edit</DoAndDont.Item>
</DoAndDont.Dont>
</DoAndDont>

## Primary and secondary actions

- Primary on the right, secondary left (Cancel, OK) not (OK, Cancel)

- Primary actions can either be positive (Send, Save) or negative (Delete)

<div class="d-flex flex-wrap">
<span class="m-2">
<Guideline do label='Cancel, Save'></Guideline>
<Guideline do={false} label='Save, Cancel'></Guideline>
</span>
</div>
<DoAndDont>
<DoAndDont.Do>
<DoAndDont.Item>Cancel, Save</DoAndDont.Item>
</DoAndDont.Do>
<DoAndDont.Dont>
<DoAndDont.Item>Save, Cancel</DoAndDont.Item>
</DoAndDont.Dont>
</DoAndDont>
Loading
Loading