From f175939cf5f003ceb2cc8ee5cf4cf023c6b87243 Mon Sep 17 00:00:00 2001 From: matthias Date: Tue, 18 Mar 2025 10:46:14 +0100 Subject: [PATCH 01/19] feat: add does and donts layout and styling --- .../docs/guidelines/language/basics.md | 180 ++++++--------- .../guidelines/language/best-practices.md | 120 +++++----- .../language/dialogs-and-buttons.md | 52 +++-- .../guidelines/language/error-messages.md | 82 ++++--- .../language/frequent-app-functions.md | 114 +++++----- .../language/grammar-and-vocabulary.md | 210 ++++++++---------- .../language/main-menu-functions.md | 84 ++++--- .../docs/guidelines/language/punctuation.md | 133 +++++------ .../src/theme/Admonition/Types.tsx | 91 ++++++++ .../src/theme/Admonition/styles.module.css | 51 +++++ 10 files changed, 612 insertions(+), 505 deletions(-) create mode 100644 packages/documentation/src/theme/Admonition/Types.tsx create mode 100644 packages/documentation/src/theme/Admonition/styles.module.css diff --git a/packages/documentation/docs/guidelines/language/basics.md b/packages/documentation/docs/guidelines/language/basics.md index cec5a93691b..ee687fb2836 100644 --- a/packages/documentation/docs/guidelines/language/basics.md +++ b/packages/documentation/docs/guidelines/language/basics.md @@ -35,33 +35,27 @@ The following sections contain advice we follow at Siemens to create our own pro - Avoid using negative contractions as they can appear too informal -
- - - - - - - - - - - - - - - - - - - - - - - - - -
+::::layout + +:::col +[!do] +their, them, theirs, salesperson +Welcome to this application +X appears when detail view has selected events +cannot, will not +you’ll, we’ve +::: + +:::col +[!dont] +his, hers, him, salesman +Hey there! +X doesn’t appear if detail view has no selected events +can’t, won’t +you will, we have +::: + +:::: ### Length @@ -85,90 +79,60 @@ The following sections contain advice we follow at Siemens to create our own pro - Capitalize named app functions and UI elements: Go to Settings, Allocate users in User management, Press Ok -
- - - - +::::layout - - - - +:::col +[!do] +Go to Settings +Press OK +Log in +For more information, see Siemens Industry Online Support. +::: - - - - +:::col +[!dont] +Go To Settings +Press Ok +LOG IN +For more information, see Siemens industry online support. +::: - - - - - -
+:::: ### Common UX wording mistakes -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+::::layout + +:::col +[!do] +time zone +log file +log in (as an action) +login (as a noun) +equipment +feedback +training +current +avoid "shall" +Siemens has +34 million / 35 billion +34 million +::: + +:::col +[!dont] +timezone +logfile +login +log in +equipments +feedbacks +trainings +actual +user shall manage users +Siemens have +34’ / 35“ +34 millions +::: + +:::: diff --git a/packages/documentation/docs/guidelines/language/best-practices.md b/packages/documentation/docs/guidelines/language/best-practices.md index 4684ad756cf..0500df1bd6d 100644 --- a/packages/documentation/docs/guidelines/language/best-practices.md +++ b/packages/documentation/docs/guidelines/language/best-practices.md @@ -15,28 +15,25 @@ import Guideline from '@site/src/components/Guideline'; - Confirmation messages: Use the same verb as the transitional text -
- - - - - - - - - - - - - - - - - - - - -
+::::layout + +:::col +[!do] +Updating user roles… +Submitting log files… +Saving project… > Project saved +Training models… > Models trained +::: + +:::col +[!dont] +Getting ready… +Chopping fruit… +Saving project… > Project uploaded +Training models… > Training done +::: + +:::: ### Error messages @@ -50,15 +47,22 @@ import Guideline from '@site/src/components/Guideline'; - Use … to show an action is required, i.e. fill this in … -
- - - - - - - -
+::::layout + +:::col +[!do] +System error: You’re offline. Check your connection and try again. +File error: We cannot upload this file. Try uploading again. +Permission error: To carry out this task, you need more permissions. Contact admin to change permissions. +::: + +:::col +[!dont] +What did you do!? +The email address you entered does not match the required format. Please enter your email address using the standard format. +::: + +:::: ### Empty-state text @@ -72,23 +76,23 @@ 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. -
- - - - +::::layout - - - - +:::col +[!do] +Allocate users in User management. +To show rows, select a project. +To save a project, select Save in Project detail list. +::: - - - - +:::col +[!dont] +No allocated users. +No rows to show. +No projects saved. +::: -
+:::: ### Restoring behavior of items @@ -100,14 +104,18 @@ import Guideline from '@site/src/components/Guideline'; - Do not use Delete and Remove as synonym -
- - - - - - - - - -
+::::layout + +:::col +[!do] +Create a chart and delete a chart +Add a sensor to a chart and remove a sensor from chart +::: + +:::col +[!dont] +Create a chart and remove it +Add a sensor and delete the sensor +::: + +:::: diff --git a/packages/documentation/docs/guidelines/language/dialogs-and-buttons.md b/packages/documentation/docs/guidelines/language/dialogs-and-buttons.md index de023fa3562..a285f885d7e 100644 --- a/packages/documentation/docs/guidelines/language/dialogs-and-buttons.md +++ b/packages/documentation/docs/guidelines/language/dialogs-and-buttons.md @@ -21,22 +21,23 @@ import Guideline from '@site/src/components/Guideline'; - Only use ‘OK’ as an option if you cannot find an appropriate verb -
- - - - - - - - - - - - - - -
+::::layout + +:::col +[!do] +Title: Add user / Buttons: Cancel, Add +Title: Delete file / Buttons: Cancel, Delete +Title: Edit details / Buttons: Cancel, Save +::: + +:::col +[!dont] +Title: Add user / Buttons: Cancel, OK +Title: Are you sure / Buttons: Cancel, Delete +Title: Edit details / Buttons: Cancel, Edit +::: + +:::: ### Primary and secondary actions @@ -44,9 +45,16 @@ import Guideline from '@site/src/components/Guideline'; - Primary actions can either be positive (Send, Save) or negative (Delete) -
- - - - -
+::::layout + +:::col +[!do] +Cancel, Save +::: + +:::col +[!dont] +Save, Cancel +::: + +:::: diff --git a/packages/documentation/docs/guidelines/language/error-messages.md b/packages/documentation/docs/guidelines/language/error-messages.md index e0ab3466470..6c37291e157 100644 --- a/packages/documentation/docs/guidelines/language/error-messages.md +++ b/packages/documentation/docs/guidelines/language/error-messages.md @@ -41,47 +41,61 @@ import Guideline from '@site/src/components/Guideline'; - An error message alerts user of a problem that exists and must be addressed -
- - - - - - - - - - - - - - -
+::::layout + +:::col +[!do] +System error: You’re offline. Check your connection and try again. +File error: We cannot upload this file. Try uploading again. +Permission error: To carry out this task, you need more permissions. Contact admin to change permissions. +::: + +:::col +[!dont] +What did you do!? +The email address you entered does not match the required format. Please enter your email address using the standard format. +You have failed to delete the device. +Error 404 +Value out of range. +File not found. +Title: Input error +Explanation: Input error detected. +Action: Try again. +::: + +:::: ### Warning messages - A warning message alerts users of a condition that may cause a problem in the future -
- - - - - -
+::::layout + +:::col +[!do] +Title: You have not saved all documents +Explanation: You have to save all documents +Action: (Ok button) +::: + +:::: ### Notifications - Notifications are informative and no actions are required from the user -
- - - - - - - - - -
+::::layout + +:::col +[!do] +Access Point 2 is connected. +Changes are saved automatically. +::: + +:::col +[!dont] +Access Point connection failed. Try again. +No rows to show. +::: + +:::: diff --git a/packages/documentation/docs/guidelines/language/frequent-app-functions.md b/packages/documentation/docs/guidelines/language/frequent-app-functions.md index 19237ba4544..89c5263fe32 100644 --- a/packages/documentation/docs/guidelines/language/frequent-app-functions.md +++ b/packages/documentation/docs/guidelines/language/frequent-app-functions.md @@ -14,19 +14,16 @@ import Guideline from '@site/src/components/Guideline'; - Cockpit -
+::::layout - - - - - - - - - +:::col +[!dont] +Console +Dash +Control panel +::: -
+:::: ### Analytics @@ -34,16 +31,15 @@ import Guideline from '@site/src/components/Guideline'; - Anomaly detection -
+::::layout - - - - - - +:::col +[!dont] +Assessment +Examination +::: -
+:::: ### Monitoring and scheduling @@ -55,13 +51,14 @@ import Guideline from '@site/src/components/Guideline'; - Remove from watchlist -
+::::layout - - - +:::col +[!dont] +Watch list +::: -
+:::: ### Detail view @@ -71,16 +68,15 @@ import Guideline from '@site/src/components/Guideline'; - Details -
+::::layout - - - - - - +:::col +[!dont] +Facts +Specifics +::: -
+:::: #### Asset properties @@ -124,13 +120,14 @@ import Guideline from '@site/src/components/Guideline'; - Drag files here or select files -
+::::layout - - - +:::col +[!dont] +Drag and drop here or browse +::: -
+:::: ### Comments @@ -142,9 +139,14 @@ import Guideline from '@site/src/components/Guideline'; - Write your comments here - - - +::::layout + +:::col +[!dont] +Write a comment +::: + +:::: ### Grid and list actions @@ -168,11 +170,16 @@ import Guideline from '@site/src/components/Guideline'; - Notify me when X occurs - - - - - +::::layout + +:::col +[!dont] +Error +Issue +Problem +::: + +:::: ### Event types @@ -200,12 +207,17 @@ import Guideline from '@site/src/components/Guideline'; - Detected - - - - - - +::::layout + +:::col +[!dont] +Unacklowedged +Unack. +Unackn. +Unacknl. +::: + +:::: ### Event actions diff --git a/packages/documentation/docs/guidelines/language/grammar-and-vocabulary.md b/packages/documentation/docs/guidelines/language/grammar-and-vocabulary.md index 16c1bc9a42a..570f0f77ae7 100644 --- a/packages/documentation/docs/guidelines/language/grammar-and-vocabulary.md +++ b/packages/documentation/docs/guidelines/language/grammar-and-vocabulary.md @@ -1,62 +1,42 @@ ---- -sidebar_position: 2 -sidebar_title: Grammar and vocabulary -title: Grammar and vocabulary ---- +::::layout -import Guideline from '@site/src/components/Guideline'; +:::col +[!do] +click, browse, upload +file loads, file loaded +::: +:::col +[!dont] +clicking, being clicked, was clicking +file is going to be loaded, file has been loaded +::: -### Grammar tenses - -- Use present simple tense to describe an action or instruction - -- Only use simple verb forms in the past or future when necessary - -
- - - - - - - - - - - -
+:::: ### Active voice -
- - - - - - - - - - - - - - - +::::layout - - - - +:::col +[!do] +Configuration file opens. +Admin provides read-only access. +Measure performance. +Click submit. +Calculate the data. +::: - - - - +:::col +[!dont] +The configuration file is opened. +Read-only access is provided by Admin. +Performance is measured. +Submit is clicked by user. +The data is calculated by application. +::: -
+:::: ### UI terminology @@ -66,19 +46,21 @@ import Guideline from '@site/src/components/Guideline'; - Basic terminology: checkbox, drop-down, field, icon, menu, link, radio button, window -
+::::layout - - - - +:::col +[!do] +click +hover +::: - - - - +:::col +[!dont] +press +mouse over +::: -
+:::: ### Idioms and phrasal verbs @@ -88,29 +70,25 @@ import Guideline from '@site/src/components/Guideline'; - Avoid cultural references -
+::::layout - - - - +:::col +[!do] +remove +calculate +continue +mobile device +::: - - - - +:::col +[!dont] +get rid of +add up +carry on +Apple, Android, iOS, smartphone +::: - - - - - - - - - - -
+:::: ### Jargon, buzz words and terms @@ -132,30 +110,25 @@ import Guideline from '@site/src/components/Guideline'; - Never make up your own acronyms: https://www.acronymfinder.com/ -
- - - - - - - - - - - - - - - - - - - - - -
- +::::layout + +:::col +[!do] +light emitting diodes (LEDs) +APS +EU +I/O component, I/O list, I/O module +::: + +:::col +[!dont] +Light Emitting Diodes (LEDS) +A.P.S. +E.U. +IO component, i/o list, I-O module +::: + +:::: ### Time based vocabulary: Last, latest and recent - Last implies nothing else will follow. It's the last, and after this it is finished. No more are coming. @@ -164,21 +137,20 @@ import Guideline from '@site/src/components/Guideline'; - Recent is more time focused and is similar to latest. It means that it happened a short time ago. -
- - - - - +::::layout - - - - +:::col +[!do] +Latest update +Latest summary +Recent events +::: - - - - +:::col +[!dont] +Last update +Last summary +Last events +::: -
+:::: diff --git a/packages/documentation/docs/guidelines/language/main-menu-functions.md b/packages/documentation/docs/guidelines/language/main-menu-functions.md index edfa00c36c7..7791f85eceb 100644 --- a/packages/documentation/docs/guidelines/language/main-menu-functions.md +++ b/packages/documentation/docs/guidelines/language/main-menu-functions.md @@ -15,14 +15,15 @@ import Guideline from '@site/src/components/Guideline'; - Forgot password? -
+::::layout - - - - +:::col +[!dont] +Sign in / Sign up +Login (as it is a noun, not a verb) +::: -
+:::: ### User management @@ -46,22 +47,17 @@ import Guideline from '@site/src/components/Guideline'; - Edit account -
+::::layout - - - - - - - - - - - - +:::col +[!dont] +id / identification +E-mail +Add a user / Delete a user / Add permission +Surname / Initial name / Given name +::: -
+:::: ### Roles @@ -109,9 +105,14 @@ import Guideline from '@site/src/components/Guideline'; - Expired licenses - - - +::::layout + +:::col +[!dont] +licence +::: + +:::: ### About & legal information @@ -139,9 +140,14 @@ import Guideline from '@site/src/components/Guideline'; - © Siemens AG 20XX - - - +::::layout + +:::col +[!dont] +V1 +::: + +:::: ### Service & Support @@ -153,10 +159,15 @@ import Guideline from '@site/src/components/Guideline'; - FAQ - - - - +::::layout + +:::col +[!dont] +Documentation +User manual +::: + +:::: ### Workspace @@ -166,10 +177,15 @@ import Guideline from '@site/src/components/Guideline'; - KPIs - - - - +::::layout + +:::col +[!dont] +KPI's settings +KPIS settings +::: + +:::: ### Resetting diff --git a/packages/documentation/docs/guidelines/language/punctuation.md b/packages/documentation/docs/guidelines/language/punctuation.md index e592407f1a1..9da0da8aec6 100644 --- a/packages/documentation/docs/guidelines/language/punctuation.md +++ b/packages/documentation/docs/guidelines/language/punctuation.md @@ -83,64 +83,39 @@ Always consider whether necessary - Numbers: Use No. as an abbreviation for number, no spacing between abbreviated No. and number: No.8 -
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+::::layout + +:::col +[!do] +11am +Monday, January 12, 2021 +€999.50 +€2.5 million +$400,456.50 +£320 +30 mm +10 oz +10-40% +No.7 +Number 7 +::: + +:::col +[!dont] +11 a.m. +Monday, 12 January 2021 +€999,50 +€2,5 million +$400.456,50 +320£ +30 mms +10 oz. +10–40% +#7 +Num 7 +::: + +:::: ### Spacing @@ -154,29 +129,25 @@ Always consider whether necessary - Add a space before unit of measurement -
- - - - - - - - - - - - - - - - - - - - - -
+::::layout + +:::col +[!do] +50% +11am +Tuesday: no data +Browse… +::: + +:::col +[!dont] +50 % +11 am +Tuesday: no data +Browse … +::: + +:::: ### Lists diff --git a/packages/documentation/src/theme/Admonition/Types.tsx b/packages/documentation/src/theme/Admonition/Types.tsx new file mode 100644 index 00000000000..fab7f91b034 --- /dev/null +++ b/packages/documentation/src/theme/Admonition/Types.tsx @@ -0,0 +1,91 @@ +import React, { ReactElement, ReactNode } from 'react'; +import DefaultAdmonitionTypes from '@theme-original/Admonition/Types'; +import styles from './styles.module.css'; +import { IxIcon } from '@siemens/ix-react'; + +interface LayoutProps { + children: ReactNode; +} + +function Layout({ children }: LayoutProps): JSX.Element { + return
{children}
; +} + + +type ColVariant = 'do' | 'dont' | 'doGradient' | 'dontGradient' | 'info'; + +interface ColProps { + children: ReactElement; + variant?: ColVariant; +} + +const ICON_CONFIG: Record = { + 'do': { name: 'success', color: 'color-success' }, + 'dont': { name: 'cancelled', color: 'color-alarm' }, + 'doGradient': { name: 'success', color: 'color-success' }, + 'dontGradient': { name: 'cancelled', color: 'color-alarm' }, + 'info': { name: 'info', color: 'color-neutral' }, +}; + + +function Col({ children }: ColProps): JSX.Element { + const fragmentElements = children?.props?.children || []; + + const processContent = (content: any): string[] => { + if (!content) return []; + + if (typeof content === 'string') { + return content.split('\n').filter(line => line.trim()); + } + + if (Array.isArray(content)) { + return content.flatMap(processContent); + } + + if (content.props?.children) { + return processContent(content.props.children); + } + + return []; + }; + + const contentItems = processContent(fragmentElements); + + const variantRegex = /\[!(do|dont|info)(-gradient)?\]/; + let variant: string | null = null; + + const displayItems = contentItems.filter((item) => { + const match = item.match(variantRegex); + if (match) { + variant = match[1] + (match[2] || ''); + return false; + } + return true; + }); + + const variantClassName = variant ? styles[variant] : styles.info; + const iconProps = variant ? ICON_CONFIG[variant] : ICON_CONFIG.info; + + return ( +
+ {displayItems.map((item, index) => ( +
+ +

{item}

+
+ ))} +
+ ); +} + +const AdmonitionTypes = { + ...DefaultAdmonitionTypes, + 'layout': Layout, + 'col': Col, +}; + +export default AdmonitionTypes; diff --git a/packages/documentation/src/theme/Admonition/styles.module.css b/packages/documentation/src/theme/Admonition/styles.module.css new file mode 100644 index 00000000000..029b09a5805 --- /dev/null +++ b/packages/documentation/src/theme/Admonition/styles.module.css @@ -0,0 +1,51 @@ +.layout { + display: grid; + grid-template-columns: 1fr 1fr; + gap: 1.5rem; +} + +.col { + background: var(--theme-color-2); + border-radius: 0.5rem; + padding: 1rem 0.75rem; + display: flex; + flex-direction: column; + gap: 1rem; + transition: box-shadow 0.2s ease-in-out; +} + +.col:only-child { + grid-column: span 2; +} + +.item { + display: flex; + align-items: center; + gap: 0.75rem; + + p { + margin: 0; + } +} + +.do, .do-gradient { + border-top: 3px solid var(--theme-color-success); +} + +.dont, .dont-gradient { + border-top: 3px solid var(--theme-color-alarm); +} + +.do-gradient { + background: linear-gradient(180deg, var(--theme-color-2) 25%, transparent 70.5%); +} + +.dont-gradient { + background: linear-gradient(180deg, var(--theme-color-2) 25%, transparent 70.5%); +} + +@media (max-width: 1280px) { + .layout { + grid-template-columns: 1fr; + } +} From 82fb5b01a0f3b293e9e8e5e3c3368f048abd297a Mon Sep 17 00:00:00 2001 From: matthias Date: Tue, 18 Mar 2025 11:11:21 +0100 Subject: [PATCH 02/19] feat: adapt docusaurus config --- packages/documentation/docusaurus.config.ts | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/packages/documentation/docusaurus.config.ts b/packages/documentation/docusaurus.config.ts index 335aca7d18a..94d509118ea 100644 --- a/packages/documentation/docusaurus.config.ts +++ b/packages/documentation/docusaurus.config.ts @@ -82,6 +82,10 @@ const config: Config = { rimraf: true, }), ], + admonitions: { + keywords: ['layout', 'col'], + extendDefaults: true, + }, exclude: ['**/autogenerated/**'], }, From 8d4f28ac7a5252d2a0f797c2dabb756d0f3fa393 Mon Sep 17 00:00:00 2001 From: matthias Date: Tue, 18 Mar 2025 15:26:44 +0100 Subject: [PATCH 03/19] fix: revert unindented change, format, small fixes --- .../language/grammar-and-vocabulary.md | 15 +++++++++++ .../src/theme/Admonition/Types.tsx | 26 +++++++------------ 2 files changed, 25 insertions(+), 16 deletions(-) diff --git a/packages/documentation/docs/guidelines/language/grammar-and-vocabulary.md b/packages/documentation/docs/guidelines/language/grammar-and-vocabulary.md index 570f0f77ae7..f277378c7a4 100644 --- a/packages/documentation/docs/guidelines/language/grammar-and-vocabulary.md +++ b/packages/documentation/docs/guidelines/language/grammar-and-vocabulary.md @@ -1,3 +1,18 @@ +--- +sidebar_position: 2 +sidebar_title: Grammar and vocabulary +title: Grammar and vocabulary +--- + +import Guideline from '@site/src/components/Guideline'; + + +### Grammar tenses + +- Use present simple tense to describe an action or instruction + +- Only use simple verb forms in the past or future when necessary + ::::layout :::col diff --git a/packages/documentation/src/theme/Admonition/Types.tsx b/packages/documentation/src/theme/Admonition/Types.tsx index fab7f91b034..da85dba3564 100644 --- a/packages/documentation/src/theme/Admonition/Types.tsx +++ b/packages/documentation/src/theme/Admonition/Types.tsx @@ -11,7 +11,6 @@ function Layout({ children }: LayoutProps): JSX.Element { return
{children}
; } - type ColVariant = 'do' | 'dont' | 'doGradient' | 'dontGradient' | 'info'; interface ColProps { @@ -20,14 +19,13 @@ interface ColProps { } const ICON_CONFIG: Record = { - 'do': { name: 'success', color: 'color-success' }, - 'dont': { name: 'cancelled', color: 'color-alarm' }, - 'doGradient': { name: 'success', color: 'color-success' }, - 'dontGradient': { name: 'cancelled', color: 'color-alarm' }, - 'info': { name: 'info', color: 'color-neutral' }, + do: { name: 'success', color: 'color-success' }, + dont: { name: 'cancelled', color: 'color-alarm' }, + doGradient: { name: 'success', color: 'color-success' }, + dontGradient: { name: 'cancelled', color: 'color-alarm' }, + info: { name: 'info', color: 'color-neutral' }, }; - function Col({ children }: ColProps): JSX.Element { const fragmentElements = children?.props?.children || []; @@ -35,7 +33,7 @@ function Col({ children }: ColProps): JSX.Element { if (!content) return []; if (typeof content === 'string') { - return content.split('\n').filter(line => line.trim()); + return content.split('\n').filter((line) => line.trim()); } if (Array.isArray(content)) { @@ -51,7 +49,7 @@ function Col({ children }: ColProps): JSX.Element { const contentItems = processContent(fragmentElements); - const variantRegex = /\[!(do|dont|info)(-gradient)?\]/; + const variantRegex = /\[!(do|dont|info)(-gradient)?]/; let variant: string | null = null; const displayItems = contentItems.filter((item) => { @@ -70,11 +68,7 @@ function Col({ children }: ColProps): JSX.Element {
{displayItems.map((item, index) => (
- +

{item}

))} @@ -84,8 +78,8 @@ function Col({ children }: ColProps): JSX.Element { const AdmonitionTypes = { ...DefaultAdmonitionTypes, - 'layout': Layout, - 'col': Col, + layout: Layout, + col: Col, }; export default AdmonitionTypes; From 70417ca0aa6c090bd3bb66338bce92d08e350430 Mon Sep 17 00:00:00 2001 From: matthias Date: Tue, 18 Mar 2025 16:17:23 +0100 Subject: [PATCH 04/19] fix: sonarqube --- .../src/theme/Admonition/Types.tsx | 19 ++++++++----------- 1 file changed, 8 insertions(+), 11 deletions(-) diff --git a/packages/documentation/src/theme/Admonition/Types.tsx b/packages/documentation/src/theme/Admonition/Types.tsx index da85dba3564..76f525606ff 100644 --- a/packages/documentation/src/theme/Admonition/Types.tsx +++ b/packages/documentation/src/theme/Admonition/Types.tsx @@ -11,23 +11,20 @@ function Layout({ children }: LayoutProps): JSX.Element { return
{children}
; } -type ColVariant = 'do' | 'dont' | 'doGradient' | 'dontGradient' | 'info'; - -interface ColProps { - children: ReactElement; - variant?: ColVariant; -} - const ICON_CONFIG: Record = { do: { name: 'success', color: 'color-success' }, dont: { name: 'cancelled', color: 'color-alarm' }, doGradient: { name: 'success', color: 'color-success' }, dontGradient: { name: 'cancelled', color: 'color-alarm' }, - info: { name: 'info', color: 'color-neutral' }, + default: { name: 'info', color: 'color-neutral' }, }; +interface ColProps { + children: ReactElement | ReactElement[]; +} + function Col({ children }: ColProps): JSX.Element { - const fragmentElements = children?.props?.children || []; + const fragmentElements = React.Children.toArray(children); const processContent = (content: any): string[] => { if (!content) return []; @@ -53,7 +50,7 @@ function Col({ children }: ColProps): JSX.Element { let variant: string | null = null; const displayItems = contentItems.filter((item) => { - const match = item.match(variantRegex); + const match = variantRegex.exec(item); if (match) { variant = match[1] + (match[2] || ''); return false; @@ -67,7 +64,7 @@ function Col({ children }: ColProps): JSX.Element { return (
{displayItems.map((item, index) => ( -
+

{item}

From bbaf79e94326a142509599c3445e63cf163d1b71 Mon Sep 17 00:00:00 2001 From: matthias Date: Wed, 19 Mar 2025 06:32:40 +0100 Subject: [PATCH 05/19] fix: sonarqube issues --- .../src/theme/Admonition/Types.tsx | 20 ++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/packages/documentation/src/theme/Admonition/Types.tsx b/packages/documentation/src/theme/Admonition/Types.tsx index 76f525606ff..8fb1e952cca 100644 --- a/packages/documentation/src/theme/Admonition/Types.tsx +++ b/packages/documentation/src/theme/Admonition/Types.tsx @@ -4,7 +4,7 @@ import styles from './styles.module.css'; import { IxIcon } from '@siemens/ix-react'; interface LayoutProps { - children: ReactNode; + readonly children: ReactNode; } function Layout({ children }: LayoutProps): JSX.Element { @@ -16,11 +16,11 @@ const ICON_CONFIG: Record = { dont: { name: 'cancelled', color: 'color-alarm' }, doGradient: { name: 'success', color: 'color-success' }, dontGradient: { name: 'cancelled', color: 'color-alarm' }, - default: { name: 'info', color: 'color-neutral' }, + default: { name: null, color: null }, }; interface ColProps { - children: ReactElement | ReactElement[]; + readonly children: ReactElement | ReactElement[]; } function Col({ children }: ColProps): JSX.Element { @@ -47,7 +47,7 @@ function Col({ children }: ColProps): JSX.Element { const contentItems = processContent(fragmentElements); const variantRegex = /\[!(do|dont|info)(-gradient)?]/; - let variant: string | null = null; + let variant: string | undefined = undefined; const displayItems = contentItems.filter((item) => { const match = variantRegex.exec(item); @@ -58,14 +58,16 @@ function Col({ children }: ColProps): JSX.Element { return true; }); - const variantClassName = variant ? styles[variant] : styles.info; - const iconProps = variant ? ICON_CONFIG[variant] : ICON_CONFIG.info; + const variantClassName = variant ? styles[variant] : ''; + const iconProps = variant ? ICON_CONFIG[variant] : undefined; return (
- {displayItems.map((item, index) => ( -
- + {displayItems.map((item) => ( +
+ {iconProps && ( + + )}

{item}

))} From a002bc7e0021da662626662549a4b4380368dc9c Mon Sep 17 00:00:00 2001 From: matthias Date: Wed, 19 Mar 2025 06:54:22 +0100 Subject: [PATCH 06/19] fix: sonarqube issues --- packages/documentation/src/theme/Admonition/Types.tsx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/documentation/src/theme/Admonition/Types.tsx b/packages/documentation/src/theme/Admonition/Types.tsx index 8fb1e952cca..1259437ec7f 100644 --- a/packages/documentation/src/theme/Admonition/Types.tsx +++ b/packages/documentation/src/theme/Admonition/Types.tsx @@ -63,8 +63,8 @@ function Col({ children }: ColProps): JSX.Element { return (
- {displayItems.map((item) => ( -
+ {displayItems.map((item, index) => ( +
{iconProps && ( )} From a58737c39160cd44e123661017de1efd0d641d13 Mon Sep 17 00:00:00 2001 From: matthias Date: Wed, 19 Mar 2025 06:54:22 +0100 Subject: [PATCH 07/19] fix: sonarqube issues --- packages/documentation/src/theme/Admonition/Types.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/documentation/src/theme/Admonition/Types.tsx b/packages/documentation/src/theme/Admonition/Types.tsx index 8fb1e952cca..c32c404ce3f 100644 --- a/packages/documentation/src/theme/Admonition/Types.tsx +++ b/packages/documentation/src/theme/Admonition/Types.tsx @@ -64,7 +64,7 @@ function Col({ children }: ColProps): JSX.Element { return (
{displayItems.map((item) => ( -
+
{iconProps && ( )} From 049e31ef98b484cdc4f710900fb94382a58bc8cd Mon Sep 17 00:00:00 2001 From: matthias Date: Wed, 19 Mar 2025 14:11:36 +0100 Subject: [PATCH 08/19] fix: moved custom variant to components and changed icon usage --- .../Admonition/Types.tsx | 15 ++++++------- .../src/theme/Admonition/index.ts | 21 +++++++++++++++++++ 2 files changed, 29 insertions(+), 7 deletions(-) rename packages/documentation/src/{theme => components}/Admonition/Types.tsx (78%) create mode 100644 packages/documentation/src/theme/Admonition/index.ts diff --git a/packages/documentation/src/theme/Admonition/Types.tsx b/packages/documentation/src/components/Admonition/Types.tsx similarity index 78% rename from packages/documentation/src/theme/Admonition/Types.tsx rename to packages/documentation/src/components/Admonition/Types.tsx index c32c404ce3f..e6b5c1798bc 100644 --- a/packages/documentation/src/theme/Admonition/Types.tsx +++ b/packages/documentation/src/components/Admonition/Types.tsx @@ -1,6 +1,7 @@ import React, { ReactElement, ReactNode } from 'react'; import DefaultAdmonitionTypes from '@theme-original/Admonition/Types'; import styles from './styles.module.css'; +import { iconCancelled, iconSuccess } from '@siemens/ix-icons/icons'; import { IxIcon } from '@siemens/ix-react'; interface LayoutProps { @@ -11,12 +12,12 @@ function Layout({ children }: LayoutProps): JSX.Element { return
{children}
; } -const ICON_CONFIG: Record = { - do: { name: 'success', color: 'color-success' }, - dont: { name: 'cancelled', color: 'color-alarm' }, - doGradient: { name: 'success', color: 'color-success' }, - dontGradient: { name: 'cancelled', color: 'color-alarm' }, - default: { name: null, color: null }, +const ICON_CONFIG: Record = { + do: { icon: iconSuccess, iconColor: 'color-success' }, + dont: { icon: iconCancelled, iconColor: 'color-alarm' }, + doGradient: { icon: iconSuccess, iconColor: 'color-success' }, + dontGradient: { icon: iconCancelled, iconColor: 'color-alarm' }, + default: { icon: null, iconColor: null }, }; interface ColProps { @@ -66,7 +67,7 @@ function Col({ children }: ColProps): JSX.Element { {displayItems.map((item) => (
{iconProps && ( - + )}

{item}

diff --git a/packages/documentation/src/theme/Admonition/index.ts b/packages/documentation/src/theme/Admonition/index.ts new file mode 100644 index 00000000000..85f9fa5b11a --- /dev/null +++ b/packages/documentation/src/theme/Admonition/index.ts @@ -0,0 +1,21 @@ +import {type ComponentType, type ReactNode, createElement} from 'react'; +import {processAdmonitionProps} from '@docusaurus/theme-common'; +import type {Props} from '@theme/Admonition'; +import AdmonitionTypes from '@site/src/components/Admonition/Types'; + +function getAdmonitionTypeComponent(type: string): ComponentType { + const component = AdmonitionTypes[type]; + if (component) { + return component; + } + console.warn( + `No admonition component found for admonition type "${type}". Using Info as fallback.`, + ); + return AdmonitionTypes.info!; +} + +export default function Admonition(unprocessedProps: Props): ReactNode { + const props = processAdmonitionProps(unprocessedProps); + const AdmonitionTypeComponent = getAdmonitionTypeComponent(props.type); + return createElement(AdmonitionTypeComponent, props); +} From 094a4ae3f13a80e891410b17a7026f6e86e0e9e8 Mon Sep 17 00:00:00 2001 From: matthias Date: Wed, 19 Mar 2025 14:24:52 +0100 Subject: [PATCH 09/19] fix: move css --- .../src/{theme => components}/Admonition/styles.module.css | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename packages/documentation/src/{theme => components}/Admonition/styles.module.css (100%) diff --git a/packages/documentation/src/theme/Admonition/styles.module.css b/packages/documentation/src/components/Admonition/styles.module.css similarity index 100% rename from packages/documentation/src/theme/Admonition/styles.module.css rename to packages/documentation/src/components/Admonition/styles.module.css From 7f25bfaf82da8ebaeff3c058ce38eeb1b6129b61 Mon Sep 17 00:00:00 2001 From: matthias Date: Thu, 20 Mar 2025 10:17:17 +0100 Subject: [PATCH 10/19] fix: adjust hierarchy --- .../Admonition/{Types.tsx => index.tsx} | 13 ++---------- .../src/theme/Admonition/Types.tsx | 10 +++++++++ .../src/theme/Admonition/index.ts | 21 ------------------- 3 files changed, 12 insertions(+), 32 deletions(-) rename packages/documentation/src/components/Admonition/{Types.tsx => index.tsx} (87%) create mode 100644 packages/documentation/src/theme/Admonition/Types.tsx delete mode 100644 packages/documentation/src/theme/Admonition/index.ts diff --git a/packages/documentation/src/components/Admonition/Types.tsx b/packages/documentation/src/components/Admonition/index.tsx similarity index 87% rename from packages/documentation/src/components/Admonition/Types.tsx rename to packages/documentation/src/components/Admonition/index.tsx index e6b5c1798bc..985ae76d5b6 100644 --- a/packages/documentation/src/components/Admonition/Types.tsx +++ b/packages/documentation/src/components/Admonition/index.tsx @@ -1,5 +1,4 @@ import React, { ReactElement, ReactNode } from 'react'; -import DefaultAdmonitionTypes from '@theme-original/Admonition/Types'; import styles from './styles.module.css'; import { iconCancelled, iconSuccess } from '@siemens/ix-icons/icons'; import { IxIcon } from '@siemens/ix-react'; @@ -8,7 +7,7 @@ interface LayoutProps { readonly children: ReactNode; } -function Layout({ children }: LayoutProps): JSX.Element { +export function Layout({ children }: LayoutProps): JSX.Element { return
{children}
; } @@ -24,7 +23,7 @@ interface ColProps { readonly children: ReactElement | ReactElement[]; } -function Col({ children }: ColProps): JSX.Element { +export function Col({ children }: ColProps): JSX.Element { const fragmentElements = React.Children.toArray(children); const processContent = (content: any): string[] => { @@ -75,11 +74,3 @@ function Col({ children }: ColProps): JSX.Element {
); } - -const AdmonitionTypes = { - ...DefaultAdmonitionTypes, - layout: Layout, - col: Col, -}; - -export default AdmonitionTypes; diff --git a/packages/documentation/src/theme/Admonition/Types.tsx b/packages/documentation/src/theme/Admonition/Types.tsx new file mode 100644 index 00000000000..a8795fe09b1 --- /dev/null +++ b/packages/documentation/src/theme/Admonition/Types.tsx @@ -0,0 +1,10 @@ +import { Col, Layout } from '@site/src/components/Admonition'; +import DefaultAdmonitionTypes from '@theme-original/Admonition/Types'; + +const AdmonitionTypes = { + ...DefaultAdmonitionTypes, + 'col': Col, + 'layout': Layout, +}; + +export default AdmonitionTypes; diff --git a/packages/documentation/src/theme/Admonition/index.ts b/packages/documentation/src/theme/Admonition/index.ts deleted file mode 100644 index 85f9fa5b11a..00000000000 --- a/packages/documentation/src/theme/Admonition/index.ts +++ /dev/null @@ -1,21 +0,0 @@ -import {type ComponentType, type ReactNode, createElement} from 'react'; -import {processAdmonitionProps} from '@docusaurus/theme-common'; -import type {Props} from '@theme/Admonition'; -import AdmonitionTypes from '@site/src/components/Admonition/Types'; - -function getAdmonitionTypeComponent(type: string): ComponentType { - const component = AdmonitionTypes[type]; - if (component) { - return component; - } - console.warn( - `No admonition component found for admonition type "${type}". Using Info as fallback.`, - ); - return AdmonitionTypes.info!; -} - -export default function Admonition(unprocessedProps: Props): ReactNode { - const props = processAdmonitionProps(unprocessedProps); - const AdmonitionTypeComponent = getAdmonitionTypeComponent(props.type); - return createElement(AdmonitionTypeComponent, props); -} From 5b6c8c67a2d0e41f56e50b88065d446b36500da6 Mon Sep 17 00:00:00 2001 From: matthias Date: Tue, 25 Mar 2025 07:49:49 +0100 Subject: [PATCH 11/19] fix: resolve do / donts --- .../docs/guidelines/language/punctuation.md | 41 ++++++++++--------- 1 file changed, 21 insertions(+), 20 deletions(-) diff --git a/packages/documentation/docs/guidelines/language/punctuation.md b/packages/documentation/docs/guidelines/language/punctuation.md index 912f537f91a..55ae9c90782 100644 --- a/packages/documentation/docs/guidelines/language/punctuation.md +++ b/packages/documentation/docs/guidelines/language/punctuation.md @@ -168,23 +168,24 @@ Browse … - Make lists parallel, i.e. all items / bullets have the same look, length, feel, punctuation, capitalization -
- - - -
    -
  • Write comments
    • -
  • Respond to comments
    • -
  • Approve work orders
    • -
- - - -
    -
  • Write comments
    • -
  • Respond to comments
    • -
  • Approve work orders by adding your fingerprint to your user management section in your smartphone.
    • -
- -
+::::layout + +:::col +[!do] +Activate comments within your smartphone to +Write comments +Respond to comments +Approve work orders +::: + +:::col +[!dont] +Activate comments within your smartphone to +Write comments +Respond to comments +Approve work orders by adding your fingerprint to your user management section in your smartphone +::: + +:::: + + From 1ad312487aa1b3dc4a8077dd92177c37ecffac12 Mon Sep 17 00:00:00 2001 From: matthias Date: Wed, 26 Mar 2025 08:46:40 +0100 Subject: [PATCH 12/19] fix: reimplement admonitions --- .../docs/guidelines/language/basics.md | 108 +++++++++++++-- .../guidelines/language/best-practices.md | 78 ++++++++--- .../language/dialogs-and-buttons.md | 32 +++-- .../guidelines/language/error-messages.md | 64 +++++++-- .../language/frequent-app-functions.md | 82 +++++++---- .../language/grammar-and-vocabulary.md | 129 ++++++++++++++---- .../language/main-menu-functions.md | 60 +++++--- .../docs/guidelines/language/punctuation.md | 104 +++++++++++--- packages/documentation/docusaurus.config.ts | 2 +- .../src/components/Admonition/index.tsx | 76 +++++------ .../components/Admonition/styles.module.css | 6 +- .../src/theme/Admonition/Types.tsx | 3 +- 12 files changed, 562 insertions(+), 182 deletions(-) diff --git a/packages/documentation/docs/guidelines/language/basics.md b/packages/documentation/docs/guidelines/language/basics.md index 7290e07ea8b..2a41521cc28 100644 --- a/packages/documentation/docs/guidelines/language/basics.md +++ b/packages/documentation/docs/guidelines/language/basics.md @@ -38,28 +38,48 @@ import Guideline from '@site/src/components/Guideline'; - Avoid using negative contractions as they can appear too informal -::::layout +:::::layout -:::col +::::col [!do] +:::item their, them, theirs, salesperson +::: +:::item Welcome to this application +::: +:::item X appears when detail view has selected events +::: +:::item cannot, will not +::: +:::item you’ll, we’ve ::: +:::: -:::col +::::col [!dont] +:::item his, hers, him, salesman +::: +:::item Hey there! +::: +:::item X doesn’t appear if detail view has no selected events +::: +:::item can’t, won’t +::: +:::item you will, we have ::: - :::: +::::: + ## Length - Use sentences only when necessary @@ -82,60 +102,124 @@ you will, we have - Capitalize named app functions and UI elements: Go to Settings, Allocate users in User management, Press Ok -::::layout +:::::layout -:::col +::::col [!do] +:::item Go to Settings +::: +:::item Press OK +::: +:::item Log in +::: +:::item For more information, see Siemens Industry Online Support. ::: +:::: -:::col +::::col [!dont] +:::item Go To Settings +::: +:::item Press Ok +::: +:::item LOG IN +::: +:::item For more information, see Siemens industry online support. ::: - :::: +::::: + ## Common UX wording mistakes -::::layout +:::::layout -:::col +::::col [!do] +:::item time zone +::: +:::item log file +::: +:::item log in (as an action) +::: +:::item login (as a noun) +::: +:::item equipment +::: +:::item feedback +::: +:::item training +::: +:::item current +::: +:::item avoid "shall" +::: +:::item Siemens has +::: +:::item 34 million / 35 billion +::: +:::item 34 million ::: +:::: -:::col +::::col [!dont] +:::item timezone +::: +:::item logfile +::: +:::item login +::: +:::item log in +::: +:::item equipments +::: +:::item feedbacks +::: +:::item trainings +::: +:::item actual +::: +:::item user shall manage users +::: +:::item Siemens have +::: +:::item 34’ / 35“ +::: +:::item 34 millions ::: - :::: + +::::: diff --git a/packages/documentation/docs/guidelines/language/best-practices.md b/packages/documentation/docs/guidelines/language/best-practices.md index 46450b63e3a..588dae62220 100644 --- a/packages/documentation/docs/guidelines/language/best-practices.md +++ b/packages/documentation/docs/guidelines/language/best-practices.md @@ -20,26 +20,42 @@ import Guideline from '@site/src/components/Guideline'; - Confirmation messages: Use the same verb as the transitional text -::::layout +:::::layout -:::col +::::col [!do] +:::item Updating user roles… +::: +:::item Submitting log files… +::: +:::item Saving project… > Project saved +::: +:::item Training models… > Models trained ::: +:::: -:::col +::::col [!dont] +:::item Getting ready… +::: +:::item Chopping fruit… +::: +:::item Saving project… > Project uploaded +::: +:::item Training models… > Training done ::: - :::: +::::: + ## Error messages - Add a clear reason for the error @@ -52,23 +68,33 @@ Training models… > Training done - Use … to show an action is required, i.e. fill this in … -::::layout +:::::layout -:::col +::::col [!do] +:::item System error: You’re offline. Check your connection and try again. +::: +:::item File error: We cannot upload this file. Try uploading again. +::: +:::item Permission error: To carry out this task, you need more permissions. Contact admin to change permissions. ::: +:::: -:::col +::::col [!dont] +:::item What did you do!? +::: +:::item The email address you entered does not match the required format. Please enter your email address using the standard format. ::: - :::: +::::: + ## Empty-state text - Empty-state wording tells the user the empty space is intentional and should be there, i.e. not an error @@ -81,24 +107,36 @@ The email address you entered does not match the required format. Please enter y - Use wording to show users how to resolve the empty state, e.g. with an action, click, etc. -::::layout +:::::layout -:::col +::::col [!do] +:::item Allocate users in User management. +::: +:::item To show rows, select a project. +::: +:::item To save a project, select Save in Project detail list. ::: +:::: -:::col +::::col [!dont] +:::item No allocated users. +::: +:::item No rows to show. +::: +:::item No projects saved. ::: - :::: +::::: + ## Restoring behavior of items - Be clear on deleting, removing, creating and adding @@ -109,18 +147,26 @@ No projects saved. - Do not use Delete and Remove as synonym -::::layout +:::::layout -:::col +::::col [!do] +:::item Create a chart and delete a chart +::: +:::item Add a sensor to a chart and remove a sensor from chart ::: +:::: -:::col +::::col [!dont] +:::item Create a chart and remove it +::: +:::item Add a sensor and delete the sensor ::: - :::: + +::::: diff --git a/packages/documentation/docs/guidelines/language/dialogs-and-buttons.md b/packages/documentation/docs/guidelines/language/dialogs-and-buttons.md index c7e060959a6..c874e1de6c6 100644 --- a/packages/documentation/docs/guidelines/language/dialogs-and-buttons.md +++ b/packages/documentation/docs/guidelines/language/dialogs-and-buttons.md @@ -26,40 +26,56 @@ import Guideline from '@site/src/components/Guideline'; - Only use ‘OK’ as an option if you cannot find an appropriate verb -::::layout +:::::layout -:::col +::::col [!do] +:::item Title: Add user / Buttons: Cancel, Add +::: +:::item Title: Delete file / Buttons: Cancel, Delete +::: +:::item Title: Edit details / Buttons: Cancel, Save ::: +:::: -:::col +::::col [!dont] +:::item Title: Add user / Buttons: Cancel, OK +::: +:::item Title: Are you sure / Buttons: Cancel, Delete +::: +:::item Title: Edit details / Buttons: Cancel, Edit ::: - :::: +::::: + ## 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) -::::layout +:::::layout -:::col +::::col [!do] +:::item Cancel, Save ::: +:::: -:::col +::::col [!dont] +:::item Save, Cancel ::: - :::: + +::::: diff --git a/packages/documentation/docs/guidelines/language/error-messages.md b/packages/documentation/docs/guidelines/language/error-messages.md index 9269c11ba19..170f1b89a4b 100644 --- a/packages/documentation/docs/guidelines/language/error-messages.md +++ b/packages/documentation/docs/guidelines/language/error-messages.md @@ -46,61 +46,99 @@ import Guideline from '@site/src/components/Guideline'; - An error message alerts user of a problem that exists and must be addressed -::::layout +:::::layout -:::col +::::col [!do] +:::item System error: You’re offline. Check your connection and try again. +::: +:::item File error: We cannot upload this file. Try uploading again. +::: +:::item Permission error: To carry out this task, you need more permissions. Contact admin to change permissions. ::: +:::: -:::col +::::col [!dont] +:::item What did you do!? +::: +:::item The email address you entered does not match the required format. Please enter your email address using the standard format. +::: +:::item You have failed to delete the device. +::: +:::item Error 404 +::: +:::item Value out of range. +::: +:::item File not found. -Title: Input error +::: +:::item +Title: Input error::: +:::item + Explanation: Input error detected. +::: +:::item Action: Try again. ::: - :::: +::::: + ## Warning messages - A warning message alerts users of a condition that may cause a problem in the future -::::layout +:::::layout -:::col +::::col [!do] +:::item Title: You have not saved all documents +::: +:::item Explanation: You have to save all documents +::: +:::item Action: (Ok button) ::: - :::: +::::: + ## Notifications - Notifications are informative and no actions are required from the user -::::layout +:::::layout -:::col -[!do] +::::col +[!do-gradient] +:::item Access Point 2 is connected. +::: +:::item Changes are saved automatically. ::: +:::: -:::col +::::col [!dont] +:::item Access Point connection failed. Try again. +::: +:::item No rows to show. ::: - :::: + +::::: diff --git a/packages/documentation/docs/guidelines/language/frequent-app-functions.md b/packages/documentation/docs/guidelines/language/frequent-app-functions.md index dc1552f4092..7da29fdf58e 100644 --- a/packages/documentation/docs/guidelines/language/frequent-app-functions.md +++ b/packages/documentation/docs/guidelines/language/frequent-app-functions.md @@ -20,33 +20,43 @@ import Guideline from '@site/src/components/Guideline'; - Cockpit -::::layout +:::::layout -:::col +::::col [!dont] +:::item Console +::: +:::item Dash +::: +:::item Control panel ::: - :::: +::::: + ## Analytics - Analysis - Anomaly detection -::::layout +:::::layout -:::col +::::col [!dont] +:::item Assessment +::: +:::item Examination ::: - :::: +::::: + ## Monitoring and scheduling - Watchlist @@ -57,15 +67,17 @@ Examination - Remove from watchlist -::::layout +:::::layout -:::col +::::col [!dont] +:::item Watch list ::: - :::: +::::: + ## Detail view - Device details @@ -74,16 +86,20 @@ Watch list - Details -::::layout +:::::layout -:::col +::::col [!dont] +:::item Facts +::: +:::item Specifics ::: - :::: +::::: + ### Asset properties - Product name @@ -126,15 +142,17 @@ Specifics - Drag files here or select files -::::layout +:::::layout -:::col +::::col [!dont] +:::item Drag and drop here or browse ::: - :::: +::::: + ## Comments - Write comment @@ -145,15 +163,17 @@ Drag and drop here or browse - Write your comments here -::::layout +:::::layout -:::col +::::col [!dont] +:::item Write a comment ::: - :::: +::::: + ## Grid and list actions - Group @@ -176,17 +196,23 @@ Write a comment - Notify me when X occurs -::::layout +:::::layout -:::col +::::col [!dont] +:::item Error +::: +:::item Issue +::: +:::item Problem ::: - :::: +::::: + ## Event types - Configuration change @@ -213,18 +239,26 @@ Problem - Detected -::::layout +:::::layout -:::col +::::col [!dont] +:::item Unacklowedged +::: +:::item Unack. +::: +:::item Unackn. +::: +:::item Unacknl. ::: - :::: +::::: + ## Event actions - Apply diff --git a/packages/documentation/docs/guidelines/language/grammar-and-vocabulary.md b/packages/documentation/docs/guidelines/language/grammar-and-vocabulary.md index 7b725dfee86..bec1fdfeae7 100644 --- a/packages/documentation/docs/guidelines/language/grammar-and-vocabulary.md +++ b/packages/documentation/docs/guidelines/language/grammar-and-vocabulary.md @@ -18,46 +18,74 @@ import Guideline from '@site/src/components/Guideline'; - Only use simple verb forms in the past or future when necessary -::::layout +:::::layout -:::col +::::col [!do] +:::item click, browse, upload +::: +:::item file loads, file loaded ::: +:::: -:::col +::::col [!dont] +:::item clicking, being clicked, was clicking +::: +:::item file is going to be loaded, file has been loaded ::: - :::: +::::: + ## Active voice -::::layout +:::::layout -:::col +::::col [!do] +:::item Configuration file opens. +::: +:::item Admin provides read-only access. +::: +:::item Measure performance. +::: +:::item Click submit. +::: +:::item Calculate the data. ::: +:::: -:::col +::::col [!dont] +:::item The configuration file is opened. +::: +:::item Read-only access is provided by Admin. +::: +:::item Performance is measured. +::: +:::item Submit is clicked by user. +::: +:::item The data is calculated by application. ::: - :::: +::::: + ## UI terminology - Mouse terminology: drag, hover, point, tap, click @@ -66,22 +94,30 @@ The data is calculated by application. - Basic terminology: checkbox, drop-down, field, icon, menu, link, radio button, window -::::layout +:::::layout -:::col +::::col [!do] +:::item click +::: +:::item hover ::: +:::: -:::col +::::col [!dont] +:::item press +::: +:::item mouse over ::: - :::: +::::: + ## Idioms and phrasal verbs - Avoid multi-word phrasal verbs when one word works @@ -90,26 +126,42 @@ mouse over - Avoid cultural references -::::layout +:::::layout -:::col +::::col [!do] +:::item remove +::: +:::item calculate +::: +:::item continue +::: +:::item mobile device ::: +:::: -:::col +::::col [!dont] +:::item get rid of +::: +:::item add up +::: +:::item carry on +::: +:::item Apple, Android, iOS, smartphone ::: - :::: +::::: + ## Jargon, buzz words and terms - Use simple vocabulary @@ -130,25 +182,42 @@ Apple, Android, iOS, smartphone - Never make up your own acronyms: https://www.acronymfinder.com/ -::::layout +:::::layout -:::col +::::col [!do] +:::item light emitting diodes (LEDs) +::: +:::item APS +::: +:::item EU +::: +:::item I/O component, I/O list, I/O module ::: +:::: -:::col +::::col [!dont] +:::item Light Emitting Diodes (LEDS) +::: +:::item A.P.S. +::: +:::item E.U. +::: +:::item IO component, i/o list, I-O module ::: - :::: + +::::: + ## Time based vocabulary: Last, latest and recent - Last implies nothing else will follow. It's the last, and after this it is finished. No more are coming. @@ -157,20 +226,32 @@ IO component, i/o list, I-O module - Recent is more time focused and is similar to latest. It means that it happened a short time ago. -::::layout +:::::layout -:::col +::::col [!do] +:::item Latest update +::: +:::item Latest summary +::: +:::item Recent events ::: +:::: -:::col +::::col [!dont] +:::item Last update +::: +:::item Last summary +::: +:::item Last events ::: - :::: + +::::: diff --git a/packages/documentation/docs/guidelines/language/main-menu-functions.md b/packages/documentation/docs/guidelines/language/main-menu-functions.md index 006ac9c168e..f2467fadb14 100644 --- a/packages/documentation/docs/guidelines/language/main-menu-functions.md +++ b/packages/documentation/docs/guidelines/language/main-menu-functions.md @@ -20,16 +20,20 @@ import Guideline from '@site/src/components/Guideline'; - Forgot password? -::::layout +:::::layout -:::col +::::col [!dont] +:::item Sign in / Sign up +::: +:::item Login (as it is a noun, not a verb) ::: - :::: +::::: + ## User management - Username @@ -52,18 +56,26 @@ Login (as it is a noun, not a verb) - Edit account -::::layout +:::::layout -:::col +::::col [!dont] +:::item id / identification +::: +:::item E-mail +::: +:::item Add a user / Delete a user / Add permission +::: +:::item Surname / Initial name / Given name ::: - :::: +::::: + ## Roles - User @@ -110,15 +122,17 @@ Surname / Initial name / Given name - Expired licenses -::::layout +:::::layout -:::col +::::col [!dont] +:::item licence ::: - :::: +::::: + ## About & legal information - General information @@ -145,15 +159,17 @@ licence - © Siemens AG 20XX -::::layout +:::::layout -:::col +::::col [!dont] +:::item V1 ::: - :::: +::::: + ## Service & Support - Contact Service & Support: support@mail.com @@ -164,16 +180,20 @@ V1 - FAQ -::::layout +:::::layout -:::col +::::col [!dont] +:::item Documentation +::: +:::item User manual ::: - :::: +::::: + ## Workspace - Application status @@ -182,16 +202,20 @@ User manual - KPIs -::::layout +:::::layout -:::col +::::col [!dont] +:::item KPI's settings +::: +:::item KPIS settings ::: - :::: +::::: + ## Resetting - Factory reset diff --git a/packages/documentation/docs/guidelines/language/punctuation.md b/packages/documentation/docs/guidelines/language/punctuation.md index 55ae9c90782..9b2a3d3558b 100644 --- a/packages/documentation/docs/guidelines/language/punctuation.md +++ b/packages/documentation/docs/guidelines/language/punctuation.md @@ -90,40 +90,84 @@ Always consider whether necessary - Numbers: Use No. as an abbreviation for number, no spacing between abbreviated No. and number: No.8 -::::layout +:::::layout -:::col +::::col [!do] +:::item 11am +::: +:::item Monday, January 12, 2021 +::: +:::item €999.50 +::: +:::item €2.5 million +::: +:::item $400,456.50 +::: +:::item £320 +::: +:::item 30 mm +::: +:::item 10 oz +::: +:::item 10-40% +::: +:::item No.7 +::: +:::item Number 7 ::: +:::: -:::col +::::col [!dont] +:::item 11 a.m. +::: +:::item Monday, 12 January 2021 +::: +:::item €999,50 +::: +:::item €2,5 million +::: +:::item $400.456,50 +::: +:::item 320£ +::: +:::item 30 mms +::: +:::item 10 oz. +::: +:::item 10–40% +::: +:::item #7 +::: +:::item Num 7 ::: - :::: +::::: + ## Spacing - No space before % @@ -136,26 +180,42 @@ Num 7 - Add a space before unit of measurement -::::layout +:::::layout -:::col +::::col [!do] +:::item 50% +::: +:::item 11am +::: +:::item Tuesday: no data +::: +:::item Browse… ::: +:::: -:::col +::::col [!dont] +:::item 50 % +::: +:::item 11 am +::: +:::item Tuesday: no data +::: +:::item Browse … ::: - :::: +::::: + ## Lists - Consistent use of full stops in lists / bullet points @@ -168,24 +228,30 @@ Browse … - Make lists parallel, i.e. all items / bullets have the same look, length, feel, punctuation, capitalization -::::layout +:::::layout -:::col +::::col [!do] +:::item Activate comments within your smartphone to -Write comments -Respond to comments -Approve work orders +
    +
  • Write comments
    • +
  • Respond to comments
    • +
  • Approve work orders
    • +
::: +:::: -:::col +::::col [!dont] +:::item Activate comments within your smartphone to -Write comments -Respond to comments -Approve work orders by adding your fingerprint to your user management section in your smartphone +
    +
  • Write comments
    • +
  • Respond to comments
    • +
  • Approve work orders by adding your fingerprint to your user management section in your smartphone.
    • +
::: - :::: - +::::: diff --git a/packages/documentation/docusaurus.config.ts b/packages/documentation/docusaurus.config.ts index ac97aeab288..b1b41b48e37 100644 --- a/packages/documentation/docusaurus.config.ts +++ b/packages/documentation/docusaurus.config.ts @@ -99,7 +99,7 @@ const config: Config = { }), ], admonitions: { - keywords: ['layout', 'col'], + keywords: ['layout', 'col', 'item'], extendDefaults: true, }, diff --git a/packages/documentation/src/components/Admonition/index.tsx b/packages/documentation/src/components/Admonition/index.tsx index 985ae76d5b6..082fc5997f6 100644 --- a/packages/documentation/src/components/Admonition/index.tsx +++ b/packages/documentation/src/components/Admonition/index.tsx @@ -3,57 +3,45 @@ import styles from './styles.module.css'; import { iconCancelled, iconSuccess } from '@siemens/ix-icons/icons'; import { IxIcon } from '@siemens/ix-react'; -interface LayoutProps { - readonly children: ReactNode; +interface ComponentProps { + children: ReactNode; } -export function Layout({ children }: LayoutProps): JSX.Element { - return
{children}
; +interface IconConfig { + icon: string | null; + iconColor: string | null; } -const ICON_CONFIG: Record = { +const ICON_CONFIG: Record = { do: { icon: iconSuccess, iconColor: 'color-success' }, dont: { icon: iconCancelled, iconColor: 'color-alarm' }, - doGradient: { icon: iconSuccess, iconColor: 'color-success' }, - dontGradient: { icon: iconCancelled, iconColor: 'color-alarm' }, + 'do-gradient': { icon: iconSuccess, iconColor: 'color-success' }, + 'dont-gradient': { icon: iconCancelled, iconColor: 'color-alarm' }, default: { icon: null, iconColor: null }, }; -interface ColProps { - readonly children: ReactElement | ReactElement[]; +export function Layout(props: ComponentProps): ReactElement { + return React.createElement('div', { className: styles.layout }, props.children); } -export function Col({ children }: ColProps): JSX.Element { - const fragmentElements = React.Children.toArray(children); - - const processContent = (content: any): string[] => { - if (!content) return []; - - if (typeof content === 'string') { - return content.split('\n').filter((line) => line.trim()); - } - - if (Array.isArray(content)) { - return content.flatMap(processContent); - } - - if (content.props?.children) { - return processContent(content.props.children); - } - - return []; - }; - - const contentItems = processContent(fragmentElements); +export function Item(props: ComponentProps): ReactElement { + return React.createElement('div', { className: styles.item }, props.children); +} +export function Col(props: ComponentProps): ReactElement { + let fragmentElements: ReactNode[] = React.isValidElement(props.children) && props.children.props?.children + ? React.Children.toArray(props.children.props.children) + : React.Children.toArray(props.children); const variantRegex = /\[!(do|dont|info)(-gradient)?]/; let variant: string | undefined = undefined; - const displayItems = contentItems.filter((item) => { - const match = variantRegex.exec(item); - if (match) { - variant = match[1] + (match[2] || ''); - return false; + fragmentElements = fragmentElements.filter((element) => { + if (React.isValidElement(element)) { + const match = variantRegex.exec(element.props.children); + if (match) { + variant = match[1] + (match[2] || ''); + return false; + } } return true; }); @@ -63,14 +51,14 @@ export function Col({ children }: ColProps): JSX.Element { return (
- {displayItems.map((item) => ( -
- {iconProps && ( - - )} -

{item}

-
- ))} + {fragmentElements.map((el) => { + return ( +
+ + {el} +
+ ); + })}
); } diff --git a/packages/documentation/src/components/Admonition/styles.module.css b/packages/documentation/src/components/Admonition/styles.module.css index 029b09a5805..ddc87b5570e 100644 --- a/packages/documentation/src/components/Admonition/styles.module.css +++ b/packages/documentation/src/components/Admonition/styles.module.css @@ -18,13 +18,15 @@ grid-column: span 2; } -.item { +.entry { display: flex; - align-items: center; + align-items: start; gap: 0.75rem; p { margin: 0; + display: flex; + align-items: center; } } diff --git a/packages/documentation/src/theme/Admonition/Types.tsx b/packages/documentation/src/theme/Admonition/Types.tsx index a8795fe09b1..e6f7bf12ccc 100644 --- a/packages/documentation/src/theme/Admonition/Types.tsx +++ b/packages/documentation/src/theme/Admonition/Types.tsx @@ -1,10 +1,11 @@ -import { Col, Layout } from '@site/src/components/Admonition'; +import { Col, Layout, Item } from '@site/src/components/Admonition'; import DefaultAdmonitionTypes from '@theme-original/Admonition/Types'; const AdmonitionTypes = { ...DefaultAdmonitionTypes, 'col': Col, 'layout': Layout, + 'item': Item, }; export default AdmonitionTypes; From 225c6519401c7f48c5e26f45b50372e8f087b22e Mon Sep 17 00:00:00 2001 From: matthias Date: Wed, 26 Mar 2025 08:51:26 +0100 Subject: [PATCH 13/19] fix: minor issue in md --- .../documentation/docs/guidelines/language/error-messages.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/documentation/docs/guidelines/language/error-messages.md b/packages/documentation/docs/guidelines/language/error-messages.md index 170f1b89a4b..792b7317250 100644 --- a/packages/documentation/docs/guidelines/language/error-messages.md +++ b/packages/documentation/docs/guidelines/language/error-messages.md @@ -82,9 +82,9 @@ Value out of range. File not found. ::: :::item -Title: Input error::: +Title: Input error +::: :::item - Explanation: Input error detected. ::: :::item From 0992d0a06c949fceb4bba74aac7e4411564ead5d Mon Sep 17 00:00:00 2001 From: matthiashader <144090716+matthiashader@users.noreply.github.com> Date: Wed, 26 Mar 2025 11:17:55 +0100 Subject: [PATCH 14/19] fix: removed admonition, reimplemented as react component --- .../docs/guidelines/language/basics.md | 220 ++++----------- .../guidelines/language/best-practices.md | 161 ++++------- .../language/dialogs-and-buttons.md | 67 ++--- .../guidelines/language/error-messages.md | 124 +++------ .../language/frequent-app-functions.md | 157 ++++------- .../language/grammar-and-vocabulary.md | 263 +++++------------- .../language/main-menu-functions.md | 115 +++----- .../docs/guidelines/language/punctuation.md | 205 +++++--------- packages/documentation/docusaurus.config.ts | 5 - .../src/components/Admonition/index.tsx | 64 ----- .../src/components/DosDontsStyling/index.tsx | 88 ++++++ .../styles.module.css | 0 .../src/theme/Admonition/Types.tsx | 11 - 13 files changed, 485 insertions(+), 995 deletions(-) delete mode 100644 packages/documentation/src/components/Admonition/index.tsx create mode 100644 packages/documentation/src/components/DosDontsStyling/index.tsx rename packages/documentation/src/components/{Admonition => DosDontsStyling}/styles.module.css (100%) delete mode 100644 packages/documentation/src/theme/Admonition/Types.tsx diff --git a/packages/documentation/docs/guidelines/language/basics.md b/packages/documentation/docs/guidelines/language/basics.md index 2a41521cc28..22c432c72dd 100644 --- a/packages/documentation/docs/guidelines/language/basics.md +++ b/packages/documentation/docs/guidelines/language/basics.md @@ -9,6 +9,7 @@ description: "Dive into the fundamental principles of UX writing, where you'll l --- import Guideline from '@site/src/components/Guideline'; +import { Layout, Do, Dont, Item } from '@site/src/components/DosDontsStyling'; # @@ -38,47 +39,22 @@ import Guideline from '@site/src/components/Guideline'; - Avoid using negative contractions as they can appear too informal -:::::layout - -::::col -[!do] -:::item -their, them, theirs, salesperson -::: -:::item -Welcome to this application -::: -:::item -X appears when detail view has selected events -::: -:::item -cannot, will not -::: -:::item -you’ll, we’ve -::: -:::: - -::::col -[!dont] -:::item -his, hers, him, salesman -::: -:::item -Hey there! -::: -:::item -X doesn’t appear if detail view has no selected events -::: -:::item -can’t, won’t -::: -:::item -you will, we have -::: -:::: - -::::: + + + their, them, theirs, salesperson + Welcome to this application + X appears when detail view has selected events + cannot, will not + you’ll, we’ve + + + his, hers, him, salesman + Hey there! + X doesn’t appear if detail view has no selected events + can’t, won’t + you will, we have + + ## Length @@ -102,124 +78,50 @@ you will, we have - Capitalize named app functions and UI elements: Go to Settings, Allocate users in User management, Press Ok -:::::layout - -::::col -[!do] -:::item -Go to Settings -::: -:::item -Press OK -::: -:::item -Log in -::: -:::item -For more information, see Siemens Industry Online Support. -::: -:::: - -::::col -[!dont] -:::item -Go To Settings -::: -:::item -Press Ok -::: -:::item -LOG IN -::: -:::item -For more information, see Siemens industry online support. -::: -:::: - -::::: + + + Go to Settings + Press OK + Log in + For more information, see Siemens Industry Online Support. + + + Go To Settings + Press Ok + LOG IN + For more information, see Siemens industry online support. + + ## Common UX wording mistakes -:::::layout - -::::col -[!do] -:::item -time zone -::: -:::item -log file -::: -:::item -log in (as an action) -::: -:::item -login (as a noun) -::: -:::item -equipment -::: -:::item -feedback -::: -:::item -training -::: -:::item -current -::: -:::item -avoid "shall" -::: -:::item -Siemens has -::: -:::item -34 million / 35 billion -::: -:::item -34 million -::: -:::: - -::::col -[!dont] -:::item -timezone -::: -:::item -logfile -::: -:::item -login -::: -:::item -log in -::: -:::item -equipments -::: -:::item -feedbacks -::: -:::item -trainings -::: -:::item -actual -::: -:::item -user shall manage users -::: -:::item -Siemens have -::: -:::item -34’ / 35“ -::: -:::item -34 millions -::: -:::: - -::::: + + + time zone + log file + log in (as an action) + login (as a noun) + equipment + feedback + training + current + avoid "shall" + Siemens has + 34 million / 35 billion + 34 million + + + timezone + logfile + login + log in + equipments + feedbacks + trainings + actual + user shall manage users + Siemens have + 34’ / 35“ + 34 millions + + diff --git a/packages/documentation/docs/guidelines/language/best-practices.md b/packages/documentation/docs/guidelines/language/best-practices.md index 588dae62220..1dd7eb83704 100644 --- a/packages/documentation/docs/guidelines/language/best-practices.md +++ b/packages/documentation/docs/guidelines/language/best-practices.md @@ -9,6 +9,7 @@ description: 'Familiarize yourself with general best practices for UX writing to --- import Guideline from '@site/src/components/Guideline'; +import { Layout, Do, Dont, Item } from '@site/src/components/DosDontsStyling'; # @@ -20,41 +21,20 @@ import Guideline from '@site/src/components/Guideline'; - Confirmation messages: Use the same verb as the transitional text -:::::layout - -::::col -[!do] -:::item -Updating user roles… -::: -:::item -Submitting log files… -::: -:::item -Saving project… > Project saved -::: -:::item -Training models… > Models trained -::: -:::: - -::::col -[!dont] -:::item -Getting ready… -::: -:::item -Chopping fruit… -::: -:::item -Saving project… > Project uploaded -::: -:::item -Training models… > Training done -::: -:::: - -::::: + + + Updating user roles… + Submitting log files… + Saving project… > Project saved + Training models… > Models trained + + + Getting ready… + Chopping fruit… + Saving project… > Project uploaded + Training models… > Training done + + ## Error messages @@ -68,32 +48,17 @@ Training models… > Training done - Use … to show an action is required, i.e. fill this in … -:::::layout - -::::col -[!do] -:::item -System error: You’re offline. Check your connection and try again. -::: -:::item -File error: We cannot upload this file. Try uploading again. -::: -:::item -Permission error: To carry out this task, you need more permissions. Contact admin to change permissions. -::: -:::: - -::::col -[!dont] -:::item -What did you do!? -::: -:::item -The email address you entered does not match the required format. Please enter your email address using the standard format. -::: -:::: - -::::: + + + System error: You’re offline. Check your connection and try again. + File error: We cannot upload this file. Try uploading again. + Permission error: To carry out this task, you need more permissions. Contact admin to change permissions. + + + What did you do!? + The email address you entered does not match the required format. Please enter your email address using the standard format. + + ## Empty-state text @@ -107,35 +72,18 @@ The email address you entered does not match the required format. Please enter y - Use wording to show users how to resolve the empty state, e.g. with an action, click, etc. -:::::layout - -::::col -[!do] -:::item -Allocate users in User management. -::: -:::item -To show rows, select a project. -::: -:::item -To save a project, select Save in Project detail list. -::: -:::: - -::::col -[!dont] -:::item -No allocated users. -::: -:::item -No rows to show. -::: -:::item -No projects saved. -::: -:::: - -::::: + + + Allocate users in User management. + To show rows, select a project. + To save a project, select Save in Project detail list. + + + No allocated users. + No rows to show. + No projects saved. + + ## Restoring behavior of items @@ -147,26 +95,13 @@ No projects saved. - Do not use Delete and Remove as synonym -:::::layout - -::::col -[!do] -:::item -Create a chart and delete a chart -::: -:::item -Add a sensor to a chart and remove a sensor from chart -::: -:::: - -::::col -[!dont] -:::item -Create a chart and remove it -::: -:::item -Add a sensor and delete the sensor -::: -:::: - -::::: + + + Create a chart and delete a chart + Add a sensor to a chart and remove a sensor from chart + + + Create a chart and remove it + Add a sensor and delete the sensor + + diff --git a/packages/documentation/docs/guidelines/language/dialogs-and-buttons.md b/packages/documentation/docs/guidelines/language/dialogs-and-buttons.md index c874e1de6c6..2981fcfe527 100644 --- a/packages/documentation/docs/guidelines/language/dialogs-and-buttons.md +++ b/packages/documentation/docs/guidelines/language/dialogs-and-buttons.md @@ -9,6 +9,7 @@ description: 'Discover guidelines for writing dialogs and button labels to ensur --- import Guideline from '@site/src/components/Guideline'; +import { Layout, Do, Dont, Item } from '@site/src/components/DosDontsStyling'; # @@ -26,35 +27,18 @@ import Guideline from '@site/src/components/Guideline'; - Only use ‘OK’ as an option if you cannot find an appropriate verb -:::::layout - -::::col -[!do] -:::item -Title: Add user / Buttons: Cancel, Add -::: -:::item -Title: Delete file / Buttons: Cancel, Delete -::: -:::item -Title: Edit details / Buttons: Cancel, Save -::: -:::: - -::::col -[!dont] -:::item -Title: Add user / Buttons: Cancel, OK -::: -:::item -Title: Are you sure / Buttons: Cancel, Delete -::: -:::item -Title: Edit details / Buttons: Cancel, Edit -::: -:::: - -::::: + + + Title: Add user / Buttons: Cancel, Add + Title: Delete file / Buttons: Cancel, Delete + Title: Edit details / Buttons: Cancel, Save + + + Title: Add user / Buttons: Cancel, OK + Title: Are you sure / Buttons: Cancel, Delete + Title: Edit details / Buttons: Cancel, Edit + + ## Primary and secondary actions @@ -62,20 +46,11 @@ Title: Edit details / Buttons: Cancel, Edit - Primary actions can either be positive (Send, Save) or negative (Delete) -:::::layout - -::::col -[!do] -:::item -Cancel, Save -::: -:::: - -::::col -[!dont] -:::item -Save, Cancel -::: -:::: - -::::: + + + Cancel, Save + + + Save, Cancel + + diff --git a/packages/documentation/docs/guidelines/language/error-messages.md b/packages/documentation/docs/guidelines/language/error-messages.md index 1b4757166b8..6a3c9254d97 100644 --- a/packages/documentation/docs/guidelines/language/error-messages.md +++ b/packages/documentation/docs/guidelines/language/error-messages.md @@ -3,12 +3,13 @@ sidebar_position: 8 sidebar_label: Errors, warnings and notifications title: Errors, warnings and notifications doc-type: 'banner' -component-tabs: [''] +component-tabs: [ '' ] no_single_tab: true description: 'Learn how to write error messages, warnings, and notifications that are helpful and user-friendly. This subchapter provides strategies for communicating issues and alerts in a way that guides users towards solutions.' --- import Guideline from '@site/src/components/Guideline'; +import { Layout, Do, Dont, Item } from '@site/src/components/DosDontsStyling'; # @@ -46,99 +47,48 @@ import Guideline from '@site/src/components/Guideline'; - An error message alerts user of a problem that exists and must be addressed -:::::layout - -::::col -[!do] -:::item -System error: You’re offline. Check your connection and try again. -::: -:::item -File error: We cannot upload this file. Try uploading again. -::: -:::item -Permission error: To carry out this task, you need more permissions. Contact admin to change permissions. -::: -:::: - -::::col -[!dont] -:::item -What did you do!? -::: -:::item -The email address you entered does not match the required format. Please enter your email address using the standard format. -::: -:::item -You have failed to delete the device. -::: -:::item -Error 404 -::: -:::item -Value out of range. -::: -:::item -File not found. -::: -:::item -Title: Input error -::: -:::item -Explanation: Input error detected. -::: -:::item -Action: Try again. -::: -:::: - -::::: + + + System error: You’re offline. Check your connection and try again. + File error: We cannot upload this file. Try uploading again. + Permission error: To carry out this task, you need more permissions. Contact admin to change permissions. + + + What did you do!? + The email address you entered does not match the required format. Please enter your email address using the standard format. + You have failed to delete the device. + Error 404 + Value out of range. + File not found. + Title: Input error + Explanation: Input error detected. + Action: Try again. + + ## Warning messages - A warning message alerts users of a condition that may cause a problem in the future -:::::layout - -::::col -[!do] -:::item -Title: You have not saved all documents -::: -:::item -Explanation: You have to save all documents -::: -:::item -Action: (Ok button) -::: -:::: - -::::: + + + Title: You have not saved all documents + Explanation: You have to save all documents + Action: (Ok button) + + ## Notifications - Notifications are informative and no actions are required from the user -:::::layout - -::::col -[!do] -:::item -Access Point 2 is connected. -::: -:::item -Changes are saved automatically. -::: -:::: - -::::col -[!dont] -:::item -Access Point connection failed. Try again. -::: -:::item -No rows to show. -::: -:::: - -::::: + + + Access Point 2 is connected. + Changes are saved automatically. + + + Access Point connection failed. Try again. + No rows to show. + + diff --git a/packages/documentation/docs/guidelines/language/frequent-app-functions.md b/packages/documentation/docs/guidelines/language/frequent-app-functions.md index 7da29fdf58e..44a056bbf3a 100644 --- a/packages/documentation/docs/guidelines/language/frequent-app-functions.md +++ b/packages/documentation/docs/guidelines/language/frequent-app-functions.md @@ -9,6 +9,7 @@ description: 'Get tips for naming common app functions clearly and effectively. --- import Guideline from '@site/src/components/Guideline'; +import { Layout, Do, Dont, Item } from '@site/src/components/DosDontsStyling'; # @@ -20,22 +21,13 @@ import Guideline from '@site/src/components/Guideline'; - Cockpit -:::::layout - -::::col -[!dont] -:::item -Console -::: -:::item -Dash -::: -:::item -Control panel -::: -:::: - -::::: + + + Console + Dash + Control panel + + ## Analytics @@ -43,19 +35,12 @@ Control panel - Anomaly detection -:::::layout - -::::col -[!dont] -:::item -Assessment -::: -:::item -Examination -::: -:::: - -::::: + + + Assessment + Examination + + ## Monitoring and scheduling @@ -67,16 +52,11 @@ Examination - Remove from watchlist -:::::layout - -::::col -[!dont] -:::item -Watch list -::: -:::: - -::::: + + + Watch list + + ## Detail view @@ -86,19 +66,12 @@ Watch list - Details -:::::layout - -::::col -[!dont] -:::item -Facts -::: -:::item -Specifics -::: -:::: - -::::: + + + Facts + Specifics + + ### Asset properties @@ -142,16 +115,11 @@ Specifics - Drag files here or select files -:::::layout - -::::col -[!dont] -:::item -Drag and drop here or browse -::: -:::: - -::::: + + + Drag and drop here or browse + + ## Comments @@ -163,16 +131,11 @@ Drag and drop here or browse - Write your comments here -:::::layout - -::::col -[!dont] -:::item -Write a comment -::: -:::: - -::::: + + + Write a comment + + ## Grid and list actions @@ -196,22 +159,13 @@ Write a comment - Notify me when X occurs -:::::layout - -::::col -[!dont] -:::item -Error -::: -:::item -Issue -::: -:::item -Problem -::: -:::: - -::::: + + + Error + Issue + Problem + + ## Event types @@ -239,25 +193,14 @@ Problem - Detected -:::::layout - -::::col -[!dont] -:::item -Unacklowedged -::: -:::item -Unack. -::: -:::item -Unackn. -::: -:::item -Unacknl. -::: -:::: - -::::: + + + Unacklowedged + Unack. + Unackn. + Unacknl. + + ## Event actions diff --git a/packages/documentation/docs/guidelines/language/grammar-and-vocabulary.md b/packages/documentation/docs/guidelines/language/grammar-and-vocabulary.md index bec1fdfeae7..27f670e1d62 100644 --- a/packages/documentation/docs/guidelines/language/grammar-and-vocabulary.md +++ b/packages/documentation/docs/guidelines/language/grammar-and-vocabulary.md @@ -9,6 +9,7 @@ description: "Discover the importance of proper grammar and vocabulary in UX wri --- import Guideline from '@site/src/components/Guideline'; +import { Layout, Do, Dont, Item } from '@site/src/components/DosDontsStyling'; # @@ -18,73 +19,35 @@ import Guideline from '@site/src/components/Guideline'; - Only use simple verb forms in the past or future when necessary -:::::layout - -::::col -[!do] -:::item -click, browse, upload -::: -:::item -file loads, file loaded -::: -:::: - -::::col -[!dont] -:::item -clicking, being clicked, was clicking -::: -:::item -file is going to be loaded, file has been loaded -::: -:::: - -::::: + + + click, browse, upload + file loads, file loaded + + + clicking, being clicked, was clicking + file is going to be loaded, file has been loaded + + ## Active voice -:::::layout - -::::col -[!do] -:::item -Configuration file opens. -::: -:::item -Admin provides read-only access. -::: -:::item -Measure performance. -::: -:::item -Click submit. -::: -:::item -Calculate the data. -::: -:::: - -::::col -[!dont] -:::item -The configuration file is opened. -::: -:::item -Read-only access is provided by Admin. -::: -:::item -Performance is measured. -::: -:::item -Submit is clicked by user. -::: -:::item -The data is calculated by application. -::: -:::: - -::::: + + + Configuration file opens. + Admin provides read-only access. + Measure performance. + Click submit. + Calculate the data. + + + The configuration file is opened. + Read-only access is provided by Admin. + Performance is measured. + Submit is clicked by user. + The data is calculated by application. + + ## UI terminology @@ -94,29 +57,16 @@ The data is calculated by application. - Basic terminology: checkbox, drop-down, field, icon, menu, link, radio button, window -:::::layout - -::::col -[!do] -:::item -click -::: -:::item -hover -::: -:::: - -::::col -[!dont] -:::item -press -::: -:::item -mouse over -::: -:::: - -::::: + + + click + hover + + + press + mouse over + + ## Idioms and phrasal verbs @@ -126,41 +76,20 @@ mouse over - Avoid cultural references -:::::layout - -::::col -[!do] -:::item -remove -::: -:::item -calculate -::: -:::item -continue -::: -:::item -mobile device -::: -:::: - -::::col -[!dont] -:::item -get rid of -::: -:::item -add up -::: -:::item -carry on -::: -:::item -Apple, Android, iOS, smartphone -::: -:::: - -::::: + + + remove + calculate + continue + mobile device + + + get rid of + add up + carry on + Apple, Android, iOS, smartphone + + ## Jargon, buzz words and terms @@ -182,41 +111,20 @@ Apple, Android, iOS, smartphone - Never make up your own acronyms: https://www.acronymfinder.com/ -:::::layout - -::::col -[!do] -:::item -light emitting diodes (LEDs) -::: -:::item -APS -::: -:::item -EU -::: -:::item -I/O component, I/O list, I/O module -::: -:::: - -::::col -[!dont] -:::item -Light Emitting Diodes (LEDS) -::: -:::item -A.P.S. -::: -:::item -E.U. -::: -:::item -IO component, i/o list, I-O module -::: -:::: - -::::: + + + light emitting diodes (LEDs) + APS + EU + I/O component, I/O list, I/O module + + + Light Emitting Diodes (LEDS) + A.P.S. + E.U. + IO component, i/o list, I-O module + + ## Time based vocabulary: Last, latest and recent @@ -226,32 +134,15 @@ IO component, i/o list, I-O module - Recent is more time focused and is similar to latest. It means that it happened a short time ago. -:::::layout - -::::col -[!do] -:::item -Latest update -::: -:::item -Latest summary -::: -:::item -Recent events -::: -:::: - -::::col -[!dont] -:::item -Last update -::: -:::item -Last summary -::: -:::item -Last events -::: -:::: - -::::: + + + Latest update + Latest summary + Recent events + + + Last update + Last summary + Last events + + diff --git a/packages/documentation/docs/guidelines/language/main-menu-functions.md b/packages/documentation/docs/guidelines/language/main-menu-functions.md index f2467fadb14..09e85a71bc9 100644 --- a/packages/documentation/docs/guidelines/language/main-menu-functions.md +++ b/packages/documentation/docs/guidelines/language/main-menu-functions.md @@ -9,6 +9,7 @@ description: 'Explore best practices for writing main menu functions to ensure i --- import Guideline from '@site/src/components/Guideline'; +import { Layout, Do, Dont, Item } from '@site/src/components/DosDontsStyling'; # @@ -20,19 +21,12 @@ import Guideline from '@site/src/components/Guideline'; - Forgot password? -:::::layout - -::::col -[!dont] -:::item -Sign in / Sign up -::: -:::item -Login (as it is a noun, not a verb) -::: -:::: - -::::: + + + Sign in / Sign up + Login (as it is a noun, not a verb) + + ## User management @@ -56,25 +50,14 @@ Login (as it is a noun, not a verb) - Edit account -:::::layout - -::::col -[!dont] -:::item -id / identification -::: -:::item -E-mail -::: -:::item -Add a user / Delete a user / Add permission -::: -:::item -Surname / Initial name / Given name -::: -:::: - -::::: + + + id / identification + E-mail + Add a user / Delete a user / Add permission + Surname / Initial name / Given name + + ## Roles @@ -122,16 +105,11 @@ Surname / Initial name / Given name - Expired licenses -:::::layout - -::::col -[!dont] -:::item -licence -::: -:::: - -::::: + + + licence + + ## About & legal information @@ -159,16 +137,11 @@ licence - © Siemens AG 20XX -:::::layout - -::::col -[!dont] -:::item -V1 -::: -:::: - -::::: + + + V1 + + ## Service & Support @@ -180,19 +153,12 @@ V1 - FAQ -:::::layout - -::::col -[!dont] -:::item -Documentation -::: -:::item -User manual -::: -:::: - -::::: + + + Documentation + User manual + + ## Workspace @@ -202,19 +168,12 @@ User manual - KPIs -:::::layout - -::::col -[!dont] -:::item -KPI's settings -::: -:::item -KPIS settings -::: -:::: - -::::: + + + KPI's settings + KPIS settings + + ## Resetting diff --git a/packages/documentation/docs/guidelines/language/punctuation.md b/packages/documentation/docs/guidelines/language/punctuation.md index 9b2a3d3558b..31f9f97ef3f 100644 --- a/packages/documentation/docs/guidelines/language/punctuation.md +++ b/packages/documentation/docs/guidelines/language/punctuation.md @@ -9,6 +9,8 @@ description: "Master the use of punctuation to improve the readability and compr --- import Guideline from '@site/src/components/Guideline'; +import { Layout, Do, Dont, Item } from '@site/src/components/DosDontsStyling'; +import {IxIcon} from '@siemens/ix-react'; # @@ -90,83 +92,34 @@ Always consider whether necessary - Numbers: Use No. as an abbreviation for number, no spacing between abbreviated No. and number: No.8 -:::::layout - -::::col -[!do] -:::item -11am -::: -:::item -Monday, January 12, 2021 -::: -:::item -€999.50 -::: -:::item -€2.5 million -::: -:::item -$400,456.50 -::: -:::item -£320 -::: -:::item -30 mm -::: -:::item -10 oz -::: -:::item -10-40% -::: -:::item -No.7 -::: -:::item -Number 7 -::: -:::: - -::::col -[!dont] -:::item -11 a.m. -::: -:::item -Monday, 12 January 2021 -::: -:::item -€999,50 -::: -:::item -€2,5 million -::: -:::item -$400.456,50 -::: -:::item -320£ -::: -:::item -30 mms -::: -:::item -10 oz. -::: -:::item -10–40% -::: -:::item -#7 -::: -:::item -Num 7 -::: -:::: - -::::: + + + 11am + Monday, January 12, 2021 + €999.50 + €2.5 million + $400,456.50 + £320 + 30 mm + 10 oz + 10-40% + No.7 + Number 7 + + + 11 a.m. + Monday, 12 January 2021 + €999,50 + €2,5 million + $400.456,50 + 320£ + 30 mms + 10 oz. + 10–40% + #7 + Num 7 + + ## Spacing @@ -180,41 +133,20 @@ Num 7 - Add a space before unit of measurement -:::::layout - -::::col -[!do] -:::item -50% -::: -:::item -11am -::: -:::item -Tuesday: no data -::: -:::item -Browse… -::: -:::: - -::::col -[!dont] -:::item -50 % -::: -:::item -11 am -::: -:::item -Tuesday: no data -::: -:::item -Browse … -::: -:::: - -::::: + + + 50% + 11am + Tuesday: no data + Browse… + + + 50 % + 11 am + Tuesday: no data + Browse … + + ## Lists @@ -228,30 +160,25 @@ Browse … - Make lists parallel, i.e. all items / bullets have the same look, length, feel, punctuation, capitalization -:::::layout - -::::col -[!do] -:::item -Activate comments within your smartphone to -
    -
  • Write comments
    • -
  • Respond to comments
    • -
  • Approve work orders
    • -
-::: -:::: - -::::col -[!dont] -:::item -Activate comments within your smartphone to -
    -
  • Write comments
    • -
  • Respond to comments
    • -
  • Approve work orders by adding your fingerprint to your user management section in your smartphone.
    • -
-::: -:::: - -::::: + + + + Activate comments within your smartphone to +
    +
  • Write comments
    • +
  • Respond to comments
    • +
  • Approve work orders
    • +
+ + + + + Activate comments within your smartphone to +
    +
  • Write comments
    • +
  • Respond to comments
    • +
  • Approve work orders by adding your fingerprint to your user management section in your smartphone.
    • +
+ + + diff --git a/packages/documentation/docusaurus.config.ts b/packages/documentation/docusaurus.config.ts index b1b41b48e37..06ba9e635a2 100644 --- a/packages/documentation/docusaurus.config.ts +++ b/packages/documentation/docusaurus.config.ts @@ -98,11 +98,6 @@ const config: Config = { rimraf: true, }), ], - admonitions: { - keywords: ['layout', 'col', 'item'], - extendDefaults: true, - }, - exclude: ['**/autogenerated/**'], }, blog: { diff --git a/packages/documentation/src/components/Admonition/index.tsx b/packages/documentation/src/components/Admonition/index.tsx deleted file mode 100644 index 082fc5997f6..00000000000 --- a/packages/documentation/src/components/Admonition/index.tsx +++ /dev/null @@ -1,64 +0,0 @@ -import React, { ReactElement, ReactNode } from 'react'; -import styles from './styles.module.css'; -import { iconCancelled, iconSuccess } from '@siemens/ix-icons/icons'; -import { IxIcon } from '@siemens/ix-react'; - -interface ComponentProps { - children: ReactNode; -} - -interface IconConfig { - icon: string | null; - iconColor: string | null; -} - -const ICON_CONFIG: Record = { - do: { icon: iconSuccess, iconColor: 'color-success' }, - dont: { icon: iconCancelled, iconColor: 'color-alarm' }, - 'do-gradient': { icon: iconSuccess, iconColor: 'color-success' }, - 'dont-gradient': { icon: iconCancelled, iconColor: 'color-alarm' }, - default: { icon: null, iconColor: null }, -}; - -export function Layout(props: ComponentProps): ReactElement { - return React.createElement('div', { className: styles.layout }, props.children); -} - -export function Item(props: ComponentProps): ReactElement { - return React.createElement('div', { className: styles.item }, props.children); -} - -export function Col(props: ComponentProps): ReactElement { - let fragmentElements: ReactNode[] = React.isValidElement(props.children) && props.children.props?.children - ? React.Children.toArray(props.children.props.children) - : React.Children.toArray(props.children); - const variantRegex = /\[!(do|dont|info)(-gradient)?]/; - let variant: string | undefined = undefined; - - fragmentElements = fragmentElements.filter((element) => { - if (React.isValidElement(element)) { - const match = variantRegex.exec(element.props.children); - if (match) { - variant = match[1] + (match[2] || ''); - return false; - } - } - return true; - }); - - const variantClassName = variant ? styles[variant] : ''; - const iconProps = variant ? ICON_CONFIG[variant] : undefined; - - return ( -
- {fragmentElements.map((el) => { - return ( -
- - {el} -
- ); - })} -
- ); -} diff --git a/packages/documentation/src/components/DosDontsStyling/index.tsx b/packages/documentation/src/components/DosDontsStyling/index.tsx new file mode 100644 index 00000000000..bafb1e1c089 --- /dev/null +++ b/packages/documentation/src/components/DosDontsStyling/index.tsx @@ -0,0 +1,88 @@ +import React from 'react'; +import styles from './styles.module.css'; +import { IxIcon } from '@siemens/ix-react'; +import { iconCancelled, iconSuccess } from '@siemens/ix-icons/icons'; + +export type VariantType = 'do' | 'dont' | 'do-gradient' | 'dont-gradient' | undefined; + +export interface IconConfig { + readonly icon: string | null; + readonly iconColor: string | null; +} + +export interface LayoutProps { + readonly children: React.ReactNode; +} + +export interface ItemProps { + readonly children: React.ReactNode; +} + +export interface ColProps { + readonly variant?: VariantType; + readonly children: React.ReactNode; +} + +export interface VariantComponentProps { + readonly children: React.ReactNode; +} + +const ICON_CONFIG: Record = { + do: { icon: iconSuccess, iconColor: 'color-success' }, + dont: { icon: iconCancelled, iconColor: 'color-alarm' }, + 'do-gradient': { icon: iconSuccess, iconColor: 'color-success' }, + 'dont-gradient': { icon: iconCancelled, iconColor: 'color-alarm' }, + default: { icon: null, iconColor: null }, +}; + +export function Layout(props: LayoutProps) { + return ( +
+ {props.children} +
+ ); +} + +export function Item(props: ItemProps) { + return ( +
+ {props.children} +
+ ); +} + +export function Col(props: ColProps) { + const { variant, children } = props; + + const variantClass = variant ? `${styles[variant]}` : ''; + const iconProps = variant ? ICON_CONFIG[variant] : ICON_CONFIG.default; + + return ( +
+ {React.Children.map(children, child => ( +
+ {iconProps.icon && ( + + )} + {child} +
+ ))} +
+ ); +} + +export function Do(props: VariantComponentProps) { + return {props.children}; +} + +export function Dont(props: VariantComponentProps) { + return {props.children}; +} + +export function DoGradient(props: VariantComponentProps) { + return {props.children}; +} + +export function DontGradient(props: VariantComponentProps) { + return {props.children}; +} diff --git a/packages/documentation/src/components/Admonition/styles.module.css b/packages/documentation/src/components/DosDontsStyling/styles.module.css similarity index 100% rename from packages/documentation/src/components/Admonition/styles.module.css rename to packages/documentation/src/components/DosDontsStyling/styles.module.css diff --git a/packages/documentation/src/theme/Admonition/Types.tsx b/packages/documentation/src/theme/Admonition/Types.tsx deleted file mode 100644 index e6f7bf12ccc..00000000000 --- a/packages/documentation/src/theme/Admonition/Types.tsx +++ /dev/null @@ -1,11 +0,0 @@ -import { Col, Layout, Item } from '@site/src/components/Admonition'; -import DefaultAdmonitionTypes from '@theme-original/Admonition/Types'; - -const AdmonitionTypes = { - ...DefaultAdmonitionTypes, - 'col': Col, - 'layout': Layout, - 'item': Item, -}; - -export default AdmonitionTypes; From 70fd158c83ed92d0893f8e36af89f2d926b6db49 Mon Sep 17 00:00:00 2001 From: matthiashader <144090716+matthiashader@users.noreply.github.com> Date: Wed, 26 Mar 2025 11:20:47 +0100 Subject: [PATCH 15/19] fix: revert change --- packages/documentation/docusaurus.config.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/packages/documentation/docusaurus.config.ts b/packages/documentation/docusaurus.config.ts index 06ba9e635a2..930e99455ae 100644 --- a/packages/documentation/docusaurus.config.ts +++ b/packages/documentation/docusaurus.config.ts @@ -98,6 +98,7 @@ const config: Config = { rimraf: true, }), ], + exclude: ['**/autogenerated/**'], }, blog: { From d4dc02accf398e4f4d1f332f39b5a0ad3f018f28 Mon Sep 17 00:00:00 2001 From: Lukas Maurer Date: Fri, 28 Mar 2025 16:05:34 +0100 Subject: [PATCH 16/19] docs: fix bullet point formatting --- packages/documentation/docs/guidelines/language/punctuation.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/packages/documentation/docs/guidelines/language/punctuation.md b/packages/documentation/docs/guidelines/language/punctuation.md index 31f9f97ef3f..72e1a63f62c 100644 --- a/packages/documentation/docs/guidelines/language/punctuation.md +++ b/packages/documentation/docs/guidelines/language/punctuation.md @@ -51,9 +51,8 @@ Always consider whether necessary
`'` Single quotation mark for possession: Customer’s role (single), customers’ roles (plural)
-
-` ` No quotation mark or brackets for plurals: PDFs + No quotation mark or brackets for plurals: PDFs
From 70327c60c9755d6459347d7f566057abd83cd0ca Mon Sep 17 00:00:00 2001 From: matthias Date: Tue, 1 Apr 2025 07:43:11 +0200 Subject: [PATCH 17/19] fix: revert unwanted change --- .../documentation/docs/guidelines/language/error-messages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/documentation/docs/guidelines/language/error-messages.md b/packages/documentation/docs/guidelines/language/error-messages.md index 6a3c9254d97..294a92ed1c8 100644 --- a/packages/documentation/docs/guidelines/language/error-messages.md +++ b/packages/documentation/docs/guidelines/language/error-messages.md @@ -3,7 +3,7 @@ sidebar_position: 8 sidebar_label: Errors, warnings and notifications title: Errors, warnings and notifications doc-type: 'banner' -component-tabs: [ '' ] +component-tabs: [''] no_single_tab: true description: 'Learn how to write error messages, warnings, and notifications that are helpful and user-friendly. This subchapter provides strategies for communicating issues and alerts in a way that guides users towards solutions.' --- From b00b94b63f71e23cbf2a0dc67acd8318f1549365 Mon Sep 17 00:00:00 2001 From: Daniel Leroux Date: Tue, 1 Apr 2025 14:37:17 +0200 Subject: [PATCH 18/19] some minor refactoring --- .../docs/guidelines/language/basics.md | 123 +++++++------- .../guidelines/language/best-practices.md | 97 ++++++----- .../language/dialogs-and-buttons.md | 43 +++-- .../guidelines/language/error-messages.md | 73 ++++----- .../language/frequent-app-functions.md | 101 ++++++------ .../language/grammar-and-vocabulary.md | 155 +++++++++--------- .../language/main-menu-functions.md | 75 +++++---- .../docs/guidelines/language/proper-nouns.md | 2 - .../docs/guidelines/language/punctuation.md | 110 ++++++------- .../{DosDontsStyling => DoAndDont}/index.tsx | 64 ++++---- .../styles.module.css | 0 11 files changed, 418 insertions(+), 425 deletions(-) rename packages/documentation/src/components/{DosDontsStyling => DoAndDont}/index.tsx (62%) rename packages/documentation/src/components/{DosDontsStyling => DoAndDont}/styles.module.css (100%) diff --git a/packages/documentation/docs/guidelines/language/basics.md b/packages/documentation/docs/guidelines/language/basics.md index 22c432c72dd..c1d31e93865 100644 --- a/packages/documentation/docs/guidelines/language/basics.md +++ b/packages/documentation/docs/guidelines/language/basics.md @@ -8,8 +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 { Layout, Do, Dont, Item } from '@site/src/components/DosDontsStyling'; +import DoAndDont from '@site/src/components/DoAndDont'; # @@ -39,22 +38,22 @@ import { Layout, Do, Dont, Item } from '@site/src/components/DosDontsStyling'; - Avoid using negative contractions as they can appear too informal - - - their, them, theirs, salesperson - Welcome to this application - X appears when detail view has selected events - cannot, will not - you’ll, we’ve - - - his, hers, him, salesman - Hey there! - X doesn’t appear if detail view has no selected events - can’t, won’t - you will, we have - - + + + their, them, theirs, salesperson + Welcome to this application + X appears when detail view has selected events + cannot, will not + you’ll, we’ve + + + his, hers, him, salesman + Hey there! + X doesn’t appear if detail view has no selected events + can’t, won’t + you will, we have + + ## Length @@ -78,50 +77,50 @@ import { Layout, Do, Dont, Item } from '@site/src/components/DosDontsStyling'; - Capitalize named app functions and UI elements: Go to Settings, Allocate users in User management, Press Ok - - - Go to Settings - Press OK - Log in - For more information, see Siemens Industry Online Support. - - - Go To Settings - Press Ok - LOG IN - For more information, see Siemens industry online support. - - + + + Go to Settings + Press OK + Log in + For more information, see Siemens Industry Online Support. + + + Go To Settings + Press Ok + LOG IN + For more information, see Siemens industry online support. + + ## Common UX wording mistakes - - - time zone - log file - log in (as an action) - login (as a noun) - equipment - feedback - training - current - avoid "shall" - Siemens has - 34 million / 35 billion - 34 million - - - timezone - logfile - login - log in - equipments - feedbacks - trainings - actual - user shall manage users - Siemens have - 34’ / 35“ - 34 millions - - + + + time zone + log file + log in (as an action) + login (as a noun) + equipment + feedback + training + current + avoid "shall" + Siemens has + 34 million / 35 billion + 34 million + + + timezone + logfile + login + log in + equipments + feedbacks + trainings + actual + user shall manage users + Siemens have + 34’ / 35“ + 34 millions + + diff --git a/packages/documentation/docs/guidelines/language/best-practices.md b/packages/documentation/docs/guidelines/language/best-practices.md index 1dd7eb83704..4dee4bc63e4 100644 --- a/packages/documentation/docs/guidelines/language/best-practices.md +++ b/packages/documentation/docs/guidelines/language/best-practices.md @@ -8,8 +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 { Layout, Do, Dont, Item } from '@site/src/components/DosDontsStyling'; +import DoAndDont from '@site/src/components/DoAndDont'; # @@ -21,20 +20,20 @@ import { Layout, Do, Dont, Item } from '@site/src/components/DosDontsStyling'; - Confirmation messages: Use the same verb as the transitional text - - - Updating user roles… - Submitting log files… - Saving project… > Project saved - Training models… > Models trained - - - Getting ready… - Chopping fruit… - Saving project… > Project uploaded - Training models… > Training done - - + + + Updating user roles… + Submitting log files… + Saving project… > Project saved + Training models… > Models trained + + + Getting ready… + Chopping fruit… + Saving project… > Project uploaded + Training models… > Training done + + ## Error messages @@ -48,17 +47,17 @@ import { Layout, Do, Dont, Item } from '@site/src/components/DosDontsStyling'; - Use … to show an action is required, i.e. fill this in … - - - System error: You’re offline. Check your connection and try again. - File error: We cannot upload this file. Try uploading again. - Permission error: To carry out this task, you need more permissions. Contact admin to change permissions. - - - What did you do!? - The email address you entered does not match the required format. Please enter your email address using the standard format. - - + + + System error: You’re offline. Check your connection and try again. + File error: We cannot upload this file. Try uploading again. + Permission error: To carry out this task, you need more permissions. Contact admin to change permissions. + + + What did you do!? + The email address you entered does not match the required format. Please enter your email address using the standard format. + + ## Empty-state text @@ -72,18 +71,18 @@ import { Layout, Do, Dont, Item } from '@site/src/components/DosDontsStyling'; - Use wording to show users how to resolve the empty state, e.g. with an action, click, etc. - - - Allocate users in User management. - To show rows, select a project. - To save a project, select Save in Project detail list. - - - No allocated users. - No rows to show. - No projects saved. - - + + + Allocate users in User management. + To show rows, select a project. + To save a project, select Save in Project detail list. + + + No allocated users. + No rows to show. + No projects saved. + + ## Restoring behavior of items @@ -95,13 +94,13 @@ import { Layout, Do, Dont, Item } from '@site/src/components/DosDontsStyling'; - Do not use Delete and Remove as synonym - - - Create a chart and delete a chart - Add a sensor to a chart and remove a sensor from chart - - - Create a chart and remove it - Add a sensor and delete the sensor - - + + + Create a chart and delete a chart + Add a sensor to a chart and remove a sensor from chart + + + Create a chart and remove it + Add a sensor and delete the sensor + + diff --git a/packages/documentation/docs/guidelines/language/dialogs-and-buttons.md b/packages/documentation/docs/guidelines/language/dialogs-and-buttons.md index 2981fcfe527..4d3943836bf 100644 --- a/packages/documentation/docs/guidelines/language/dialogs-and-buttons.md +++ b/packages/documentation/docs/guidelines/language/dialogs-and-buttons.md @@ -8,8 +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 { Layout, Do, Dont, Item } from '@site/src/components/DosDontsStyling'; +import DoAndDont from '@site/src/components/DoAndDont'; # @@ -27,18 +26,18 @@ import { Layout, Do, Dont, Item } from '@site/src/components/DosDontsStyling'; - Only use ‘OK’ as an option if you cannot find an appropriate verb - - - Title: Add user / Buttons: Cancel, Add - Title: Delete file / Buttons: Cancel, Delete - Title: Edit details / Buttons: Cancel, Save - - - Title: Add user / Buttons: Cancel, OK - Title: Are you sure / Buttons: Cancel, Delete - Title: Edit details / Buttons: Cancel, Edit - - + + + Title: Add user / Buttons: Cancel, Add + Title: Delete file / Buttons: Cancel, Delete + Title: Edit details / Buttons: Cancel, Save + + + Title: Add user / Buttons: Cancel, OK + Title: Are you sure / Buttons: Cancel, Delete + Title: Edit details / Buttons: Cancel, Edit + + ## Primary and secondary actions @@ -46,11 +45,11 @@ import { Layout, Do, Dont, Item } from '@site/src/components/DosDontsStyling'; - Primary actions can either be positive (Send, Save) or negative (Delete) - - - Cancel, Save - - - Save, Cancel - - + + + Cancel, Save + + + Save, Cancel + + diff --git a/packages/documentation/docs/guidelines/language/error-messages.md b/packages/documentation/docs/guidelines/language/error-messages.md index 294a92ed1c8..f326cb0ce4e 100644 --- a/packages/documentation/docs/guidelines/language/error-messages.md +++ b/packages/documentation/docs/guidelines/language/error-messages.md @@ -8,8 +8,7 @@ no_single_tab: true description: 'Learn how to write error messages, warnings, and notifications that are helpful and user-friendly. This subchapter provides strategies for communicating issues and alerts in a way that guides users towards solutions.' --- -import Guideline from '@site/src/components/Guideline'; -import { Layout, Do, Dont, Item } from '@site/src/components/DosDontsStyling'; +import DoAndDont from '@site/src/components/DoAndDont'; # @@ -47,48 +46,48 @@ import { Layout, Do, Dont, Item } from '@site/src/components/DosDontsStyling'; - An error message alerts user of a problem that exists and must be addressed - - - System error: You’re offline. Check your connection and try again. - File error: We cannot upload this file. Try uploading again. - Permission error: To carry out this task, you need more permissions. Contact admin to change permissions. - - - What did you do!? - The email address you entered does not match the required format. Please enter your email address using the standard format. - You have failed to delete the device. - Error 404 - Value out of range. - File not found. - Title: Input error - Explanation: Input error detected. - Action: Try again. - - + + + System error: You’re offline. Check your connection and try again. + File error: We cannot upload this file. Try uploading again. + Permission error: To carry out this task, you need more permissions. Contact admin to change permissions. + + + What did you do!? + The email address you entered does not match the required format. Please enter your email address using the standard format. + You have failed to delete the device. + Error 404 + Value out of range. + File not found. + Title: Input error + Explanation: Input error detected. + Action: Try again. + + ## Warning messages - A warning message alerts users of a condition that may cause a problem in the future - - - Title: You have not saved all documents - Explanation: You have to save all documents - Action: (Ok button) - - + + + Title: You have not saved all documents + Explanation: You have to save all documents + Action: (Ok button) + + ## Notifications - Notifications are informative and no actions are required from the user - - - Access Point 2 is connected. - Changes are saved automatically. - - - Access Point connection failed. Try again. - No rows to show. - - + + + Access Point 2 is connected. + Changes are saved automatically. + + + Access Point connection failed. Try again. + No rows to show. + + diff --git a/packages/documentation/docs/guidelines/language/frequent-app-functions.md b/packages/documentation/docs/guidelines/language/frequent-app-functions.md index 44a056bbf3a..2c7656b7303 100644 --- a/packages/documentation/docs/guidelines/language/frequent-app-functions.md +++ b/packages/documentation/docs/guidelines/language/frequent-app-functions.md @@ -8,8 +8,7 @@ no_single_tab: true description: 'Get tips for naming common app functions clearly and effectively. This subchapter focuses on how to describe frequent actions and features in a way that users can quickly understand and use.' --- -import Guideline from '@site/src/components/Guideline'; -import { Layout, Do, Dont, Item } from '@site/src/components/DosDontsStyling'; +import DoAndDont from '@site/src/components/DoAndDont'; # @@ -21,13 +20,13 @@ import { Layout, Do, Dont, Item } from '@site/src/components/DosDontsStyling'; - Cockpit - - - Console - Dash - Control panel - - + + + Console + Dash + Control panel + + ## Analytics @@ -35,12 +34,12 @@ import { Layout, Do, Dont, Item } from '@site/src/components/DosDontsStyling'; - Anomaly detection - - - Assessment - Examination - - + + + Assessment + Examination + + ## Monitoring and scheduling @@ -52,11 +51,11 @@ import { Layout, Do, Dont, Item } from '@site/src/components/DosDontsStyling'; - Remove from watchlist - - - Watch list - - + + + Watch list + + ## Detail view @@ -66,12 +65,12 @@ import { Layout, Do, Dont, Item } from '@site/src/components/DosDontsStyling'; - Details - - - Facts - Specifics - - + + + Facts + Specifics + + ### Asset properties @@ -115,11 +114,11 @@ import { Layout, Do, Dont, Item } from '@site/src/components/DosDontsStyling'; - Drag files here or select files - - - Drag and drop here or browse - - + + + Drag and drop here or browse + + ## Comments @@ -131,11 +130,11 @@ import { Layout, Do, Dont, Item } from '@site/src/components/DosDontsStyling'; - Write your comments here - - - Write a comment - - + + + Write a comment + + ## Grid and list actions @@ -159,13 +158,13 @@ import { Layout, Do, Dont, Item } from '@site/src/components/DosDontsStyling'; - Notify me when X occurs - - - Error - Issue - Problem - - + + + Error + Issue + Problem + + ## Event types @@ -193,14 +192,14 @@ import { Layout, Do, Dont, Item } from '@site/src/components/DosDontsStyling'; - Detected - - - Unacklowedged - Unack. - Unackn. - Unacknl. - - + + + Unacklowedged + Unack. + Unackn. + Unacknl. + + ## Event actions diff --git a/packages/documentation/docs/guidelines/language/grammar-and-vocabulary.md b/packages/documentation/docs/guidelines/language/grammar-and-vocabulary.md index 27f670e1d62..7f42d6a11ff 100644 --- a/packages/documentation/docs/guidelines/language/grammar-and-vocabulary.md +++ b/packages/documentation/docs/guidelines/language/grammar-and-vocabulary.md @@ -8,8 +8,7 @@ no_single_tab: true description: "Discover the importance of proper grammar and vocabulary in UX writing. This subchapter will guide you on how to use language effectively to create professional and easily understandable content." --- -import Guideline from '@site/src/components/Guideline'; -import { Layout, Do, Dont, Item } from '@site/src/components/DosDontsStyling'; +import DoAndDont from '@site/src/components/DoAndDont'; # @@ -19,35 +18,35 @@ import { Layout, Do, Dont, Item } from '@site/src/components/DosDontsStyling'; - Only use simple verb forms in the past or future when necessary - - - click, browse, upload - file loads, file loaded - - - clicking, being clicked, was clicking - file is going to be loaded, file has been loaded - - + + + click, browse, upload + file loads, file loaded + + + clicking, being clicked, was clicking + file is going to be loaded, file has been loaded + + ## Active voice - - - Configuration file opens. - Admin provides read-only access. - Measure performance. - Click submit. - Calculate the data. - - - The configuration file is opened. - Read-only access is provided by Admin. - Performance is measured. - Submit is clicked by user. - The data is calculated by application. - - + + + Configuration file opens. + Admin provides read-only access. + Measure performance. + Click submit. + Calculate the data. + + + The configuration file is opened. + Read-only access is provided by Admin. + Performance is measured. + Submit is clicked by user. + The data is calculated by application. + + ## UI terminology @@ -57,16 +56,16 @@ import { Layout, Do, Dont, Item } from '@site/src/components/DosDontsStyling'; - Basic terminology: checkbox, drop-down, field, icon, menu, link, radio button, window - - - click - hover - - - press - mouse over - - + + + click + hover + + + press + mouse over + + ## Idioms and phrasal verbs @@ -76,20 +75,20 @@ import { Layout, Do, Dont, Item } from '@site/src/components/DosDontsStyling'; - Avoid cultural references - - - remove - calculate - continue - mobile device - - - get rid of - add up - carry on - Apple, Android, iOS, smartphone - - + + + remove + calculate + continue + mobile device + + + get rid of + add up + carry on + Apple, Android, iOS, smartphone + + ## Jargon, buzz words and terms @@ -111,20 +110,20 @@ import { Layout, Do, Dont, Item } from '@site/src/components/DosDontsStyling'; - Never make up your own acronyms: https://www.acronymfinder.com/ - - - light emitting diodes (LEDs) - APS - EU - I/O component, I/O list, I/O module - - - Light Emitting Diodes (LEDS) - A.P.S. - E.U. - IO component, i/o list, I-O module - - + + + light emitting diodes (LEDs) + APS + EU + I/O component, I/O list, I/O module + + + Light Emitting Diodes (LEDS) + A.P.S. + E.U. + IO component, i/o list, I-O module + + ## Time based vocabulary: Last, latest and recent @@ -134,15 +133,15 @@ import { Layout, Do, Dont, Item } from '@site/src/components/DosDontsStyling'; - Recent is more time focused and is similar to latest. It means that it happened a short time ago. - - - Latest update - Latest summary - Recent events - - - Last update - Last summary - Last events - - + + + Latest update + Latest summary + Recent events + + + Last update + Last summary + Last events + + diff --git a/packages/documentation/docs/guidelines/language/main-menu-functions.md b/packages/documentation/docs/guidelines/language/main-menu-functions.md index 09e85a71bc9..3cff26f4522 100644 --- a/packages/documentation/docs/guidelines/language/main-menu-functions.md +++ b/packages/documentation/docs/guidelines/language/main-menu-functions.md @@ -8,8 +8,7 @@ no_single_tab: true description: 'Explore best practices for writing main menu functions to ensure intuitive navigation. This section provides tips on how to label and organize menu items so users can easily find what they need.' --- -import Guideline from '@site/src/components/Guideline'; -import { Layout, Do, Dont, Item } from '@site/src/components/DosDontsStyling'; +import DoAndDont from '@site/src/components/DoAndDont'; # @@ -21,12 +20,12 @@ import { Layout, Do, Dont, Item } from '@site/src/components/DosDontsStyling'; - Forgot password? - - - Sign in / Sign up - Login (as it is a noun, not a verb) - - + + + Sign in / Sign up + Login (as it is a noun, not a verb) + + ## User management @@ -50,14 +49,14 @@ import { Layout, Do, Dont, Item } from '@site/src/components/DosDontsStyling'; - Edit account - - - id / identification - E-mail - Add a user / Delete a user / Add permission - Surname / Initial name / Given name - - + + + id / identification + E-mail + Add a user / Delete a user / Add permission + Surname / Initial name / Given name + + ## Roles @@ -105,11 +104,11 @@ import { Layout, Do, Dont, Item } from '@site/src/components/DosDontsStyling'; - Expired licenses - - - licence - - + + + licence + + ## About & legal information @@ -137,11 +136,11 @@ import { Layout, Do, Dont, Item } from '@site/src/components/DosDontsStyling'; - © Siemens AG 20XX - - - V1 - - + + + V1 + + ## Service & Support @@ -153,12 +152,12 @@ import { Layout, Do, Dont, Item } from '@site/src/components/DosDontsStyling'; - FAQ - - - Documentation - User manual - - + + + Documentation + User manual + + ## Workspace @@ -168,12 +167,12 @@ import { Layout, Do, Dont, Item } from '@site/src/components/DosDontsStyling'; - KPIs - - - KPI's settings - KPIS settings - - + + + KPI's settings + KPIS settings + + ## Resetting diff --git a/packages/documentation/docs/guidelines/language/proper-nouns.md b/packages/documentation/docs/guidelines/language/proper-nouns.md index ef401e8db81..42cc422ede1 100644 --- a/packages/documentation/docs/guidelines/language/proper-nouns.md +++ b/packages/documentation/docs/guidelines/language/proper-nouns.md @@ -8,8 +8,6 @@ no_single_tab: true description: 'Learn the guidelines for using proper nouns correctly in your text. This subchapter will help you understand when and how to capitalize names, brands, and other specific terms to maintain consistency and professionalism.' --- -import Guideline from '@site/src/components/Guideline'; - # ## Capitalize proper nouns diff --git a/packages/documentation/docs/guidelines/language/punctuation.md b/packages/documentation/docs/guidelines/language/punctuation.md index 72e1a63f62c..3c65590e36a 100644 --- a/packages/documentation/docs/guidelines/language/punctuation.md +++ b/packages/documentation/docs/guidelines/language/punctuation.md @@ -5,12 +5,10 @@ title: Punctuation doc-type: 'banner' component-tabs: [''] no_single_tab: true -description: "Master the use of punctuation to improve the readability and comprehension of your text. This section covers the rules and best practices for using punctuation marks to ensure your writing is clear and precise." +description: 'Master the use of punctuation to improve the readability and comprehension of your text. This section covers the rules and best practices for using punctuation marks to ensure your writing is clear and precise.' --- -import Guideline from '@site/src/components/Guideline'; -import { Layout, Do, Dont, Item } from '@site/src/components/DosDontsStyling'; -import {IxIcon} from '@siemens/ix-react'; +import DoAndDont from '@site/src/components/DoAndDont'; # @@ -91,34 +89,34 @@ Always consider whether necessary - Numbers: Use No. as an abbreviation for number, no spacing between abbreviated No. and number: No.8 - - - 11am - Monday, January 12, 2021 - €999.50 - €2.5 million - $400,456.50 - £320 - 30 mm - 10 oz - 10-40% - No.7 - Number 7 - - - 11 a.m. - Monday, 12 January 2021 - €999,50 - €2,5 million - $400.456,50 - 320£ - 30 mms - 10 oz. - 10–40% - #7 - Num 7 - - + + + 11am + Monday, January 12, 2021 + €999.50 + €2.5 million + $400,456.50 + £320 + 30 mm + 10 oz + 10-40% + No.7 + Number 7 + + + 11 a.m. + Monday, 12 January 2021 + €999,50 + €2,5 million + $400.456,50 + 320£ + 30 mms + 10 oz. + 10–40% + #7 + Num 7 + + ## Spacing @@ -132,20 +130,20 @@ Always consider whether necessary - Add a space before unit of measurement - - - 50% - 11am - Tuesday: no data - Browse… - - - 50 % - 11 am - Tuesday: no data - Browse … - - + + + 50% + 11am + Tuesday: no data + Browse… + + + 50 % + 11 am + Tuesday: no data + Browse … + + ## Lists @@ -159,25 +157,25 @@ Always consider whether necessary - Make lists parallel, i.e. all items / bullets have the same look, length, feel, punctuation, capitalization - - - + + + Activate comments within your smartphone to
  • Write comments
  • Respond to comments
  • Approve work orders
- - - - + + + + Activate comments within your smartphone to
  • Write comments
  • Respond to comments
  • Approve work orders by adding your fingerprint to your user management section in your smartphone.
- - - + + + diff --git a/packages/documentation/src/components/DosDontsStyling/index.tsx b/packages/documentation/src/components/DoAndDont/index.tsx similarity index 62% rename from packages/documentation/src/components/DosDontsStyling/index.tsx rename to packages/documentation/src/components/DoAndDont/index.tsx index bafb1e1c089..1535da733c6 100644 --- a/packages/documentation/src/components/DosDontsStyling/index.tsx +++ b/packages/documentation/src/components/DoAndDont/index.tsx @@ -3,29 +3,29 @@ import styles from './styles.module.css'; import { IxIcon } from '@siemens/ix-react'; import { iconCancelled, iconSuccess } from '@siemens/ix-icons/icons'; -export type VariantType = 'do' | 'dont' | 'do-gradient' | 'dont-gradient' | undefined; +export type VariantType = 'do' | 'dont' | 'do-gradient' | 'dont-gradient'; -export interface IconConfig { +export type IconConfig = { readonly icon: string | null; readonly iconColor: string | null; -} +}; -export interface LayoutProps { +export type LayoutProps = { readonly children: React.ReactNode; -} +}; -export interface ItemProps { +export type ItemProps = { readonly children: React.ReactNode; -} +}; -export interface ColProps { +export type ColProps = { readonly variant?: VariantType; readonly children: React.ReactNode; -} +}; -export interface VariantComponentProps { +export type VariantComponentProps = { readonly children: React.ReactNode; -} +}; const ICON_CONFIG: Record = { do: { icon: iconSuccess, iconColor: 'color-success' }, @@ -35,23 +35,15 @@ const ICON_CONFIG: Record = { default: { icon: null, iconColor: null }, }; -export function Layout(props: LayoutProps) { - return ( -
- {props.children} -
- ); +function Layout(props: LayoutProps) { + return
{props.children}
; } -export function Item(props: ItemProps) { - return ( -
- {props.children} -
- ); +function Item(props: ItemProps) { + return
{props.children}
; } -export function Col(props: ColProps) { +function Col(props: ColProps) { const { variant, children } = props; const variantClass = variant ? `${styles[variant]}` : ''; @@ -59,10 +51,14 @@ export function Col(props: ColProps) { return (
- {React.Children.map(children, child => ( + {React.Children.map(children, (child) => (
{iconProps.icon && ( - + )} {child}
@@ -71,18 +67,26 @@ export function Col(props: ColProps) { ); } -export function Do(props: VariantComponentProps) { +function Do(props: VariantComponentProps) { return {props.children}; } -export function Dont(props: VariantComponentProps) { +function Dont(props: VariantComponentProps) { return {props.children}; } -export function DoGradient(props: VariantComponentProps) { +function DoGradient(props: VariantComponentProps) { return {props.children}; } -export function DontGradient(props: VariantComponentProps) { +function DontGradient(props: VariantComponentProps) { return {props.children}; } + +Layout.Do = Do; +Layout.Dont = Dont; +Layout.DoGradient = DoGradient; +Layout.DontGradient = DontGradient; +Layout.Item = Item; + +export default Layout; diff --git a/packages/documentation/src/components/DosDontsStyling/styles.module.css b/packages/documentation/src/components/DoAndDont/styles.module.css similarity index 100% rename from packages/documentation/src/components/DosDontsStyling/styles.module.css rename to packages/documentation/src/components/DoAndDont/styles.module.css From 19ce5873981ea1f1fc0ff5ffb38f4d5e50410d3e Mon Sep 17 00:00:00 2001 From: Daniel Leroux Date: Tue, 1 Apr 2025 14:45:20 +0200 Subject: [PATCH 19/19] refactor class usage --- packages/documentation/src/components/DoAndDont/index.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/documentation/src/components/DoAndDont/index.tsx b/packages/documentation/src/components/DoAndDont/index.tsx index 1535da733c6..c6e9f20a596 100644 --- a/packages/documentation/src/components/DoAndDont/index.tsx +++ b/packages/documentation/src/components/DoAndDont/index.tsx @@ -36,7 +36,7 @@ const ICON_CONFIG: Record = { }; function Layout(props: LayoutProps) { - return
{props.children}
; + return
{props.children}
; } function Item(props: ItemProps) {