diff --git a/.env.example b/.env.example new file mode 100644 index 000000000..7bfadc282 --- /dev/null +++ b/.env.example @@ -0,0 +1,5 @@ +IX_REPO_BRANCH='main' +IX_REPO_TYPE='branch' +IX_REPO_PR='' + +BRAND_VERSION=2.0.0 diff --git a/blog/tags.yml b/blog/tags.yml index 9dd7707f0..4c89d6da9 100644 --- a/blog/tags.yml +++ b/blog/tags.yml @@ -2,3 +2,7 @@ release: description: 'Blog posts about new Industrial Experience design system releases' merging: description: 'Merging activities from other design systems at Siemens' +ux: + description: 'Blog posts about user experience and UX writing topics' +development: + description: 'Blog posts about implementation, tooling and development workflows' diff --git a/docs/components/input-date-time/code.mdx b/docs/components/input-date-time/code.mdx index be82bfc3d..9a43513ae 100644 --- a/docs/components/input-date-time/code.mdx +++ b/docs/components/input-date-time/code.mdx @@ -1,6 +1,7 @@ --- doc-type: 'tab-item' formReady: true +description: 'Code examples for date time input, including states, validation, slots and min/max dates.' --- import DatetimeInputPlayground from '@site/docs/autogenerated/playground/datetime-input.mdx'; import DatetimeInputDisabledPlayground from '@site/docs/autogenerated/playground/datetime-input-disabled.mdx'; diff --git a/docs/guidelines/conversational-design/designing-conversations/ad-hoc-conversations.md b/docs/guidelines/conversational-design/designing-conversations/ad-hoc-conversations.md index 7e7901a13..c73cdf767 100644 --- a/docs/guidelines/conversational-design/designing-conversations/ad-hoc-conversations.md +++ b/docs/guidelines/conversational-design/designing-conversations/ad-hoc-conversations.md @@ -6,7 +6,7 @@ hide_table_of_contents: false doc-type: 'banner' component-tabs: [''] no_single_tab: true -description: "Even in industrial scenarios, users test and play with chatbots. Some ad hoc interactions can be fun and build relationships between your users and chatbots, however some can be undesirable and damaging for your brand. To mitigate this risk, it’s important to implement filters and set up clear guidelines. Companies and projects can decide if they need to implement more than a basic response and give, for example, a warning message. Either way, most chatbots respond in the same way when it comes to offensive or inappropriate user queries." +description: "Ad hoc chatbot interactions can strengthen user trust, but offensive or off-topic input can harm your brand. Use filters and response rules to keep interactions safe and on track." --- # diff --git a/docs/guidelines/conversational-design/designing-conversations/ending-conversations.md b/docs/guidelines/conversational-design/designing-conversations/ending-conversations.md index d246d85c2..73a9b957e 100644 --- a/docs/guidelines/conversational-design/designing-conversations/ending-conversations.md +++ b/docs/guidelines/conversational-design/designing-conversations/ending-conversations.md @@ -6,7 +6,7 @@ hide_table_of_contents: false doc-type: 'banner' component-tabs: [''] no_single_tab: true -description: "As with any human to human interaction, there’s always an ending to give participants closure and end on a positive note. This is the same for every chatbot interaction, including industrial chatbots. Although it seems an easy communicative function, ending interactions well can achieve multiple goals that help users, chatbot teams and chatbots. It’s an opportunity to get useful feedback to train your chatbot, create a clear signal that the interaction is complete, and set the tone for the next interaction interactions." +description: "End chatbot interactions with clear closure and a positive tone. Well-designed endings confirm completion, support feedback collection and improve future interactions." --- # diff --git a/docs/guidelines/conversational-design/designing-conversations/handling-errors.md b/docs/guidelines/conversational-design/designing-conversations/handling-errors.md index f09fccaec..3e24e4dd6 100644 --- a/docs/guidelines/conversational-design/designing-conversations/handling-errors.md +++ b/docs/guidelines/conversational-design/designing-conversations/handling-errors.md @@ -6,7 +6,7 @@ hide_table_of_contents: false doc-type: 'banner' component-tabs: [''] no_single_tab: true -description: "When talking about chatbots and the mistakes they make, it’s always talked about handling them ‘gracefully’. However, in industrial situations, they must also be handled quickly so users can move on and possibly get another support source. There are often time-sensitive actions within industrial situations that require chatbots and workers to move quickly to find solutions. If a chatbot response is inaccurate or the chatbot cannot give users the solution they need, it can be consequential and even costly." +description: "In industrial contexts, chatbot errors must be handled clearly and quickly. Give users immediate feedback, explain limits and guide them to an alternative path." --- # diff --git a/docs/guidelines/language/basics/capitalization-and-proper-nouns.md b/docs/guidelines/language/basics/capitalization-and-proper-nouns.md new file mode 100644 index 000000000..3f1da527a --- /dev/null +++ b/docs/guidelines/language/basics/capitalization-and-proper-nouns.md @@ -0,0 +1,411 @@ +--- +sidebar_position: 4 +sidebar_label: Capitalization and proper nouns +title: Capitalization and proper nouns +doc-type: 'banner' +component-tabs: [''] +no_single_tab: true +description: 'Capitalization means using uppercase letters (A, B, C) instead of lowercase letters (a, b, c). This section provides clear rules for capitalizing names, brands, technical terms, and UI elements.' +--- + + +## General rules + +Use sentence case in your applications (capitalize only the first word of a sentence or heading, and any proper nouns). As the dominant trend in digital interfaces, we use sentence case to support readability, accessibility and consistency. + +
+
+ +
+
+ +
+
+ +Do not capitalize generic system or technology terms. + +
+
+ +
+
+ +
+
+ +Do not capitalize common technology terms that were initially proper nouns and capitalized, e.g. internet, website and email. + +
+
+ +
+
+ +
+
+ +## Proper nouns + +Always capitalize proper nouns (specific names) including: + +
+
+ +
+
+ +
+
+ +
+
+ +
+
+ +Always capitalize product names, systems, and third-party platforms exactly as trademarked, using the official spelling and capitalization. + +
+
+ +
+
+ +
+
+ +
+
+ +
+
+ +Capitalize official service and portal names you have created and named within your product as proper nouns. + +
+
+ +
+
+ +
+
+ +## Headings + +Use sentence case for all headings (including table headings). Capitalize only the first word and proper nouns. See [Punctuation](./punctuation.md). + +
+
+ +
+
+ +
+
+ +## Button labels and UI elements + +Use sentence case for button labels and UI elements. Capitalize only the first word and proper nouns. + +
+
+ +
+
+ +
+
+ +Slashes do not create new sentences. Treat them like "and" or "or". Capitalize only the first word and proper nouns. See [Punctuation](./punctuation.md). + +
+
+ +
+
+ +
+
+ +## Acronyms and abbreviations + +Capitalize all letters in acronyms and abbreviations. Do not use periods between letters. + +
+
+ +
+
+ +
+
+ +## Capitalization exceptions + +"OK" appears in all caps. + +
+
+ +
+
+ +
+
+ +Use capitalization for the first word of app functions and menu items when navigating users, e.g. menu items, label text, button text, etc. even when they are not proper nouns. This exception is to help with scanning and readability. + +
+
+ +
+
+ +
+
+ +Use periods for Latin abbreviations. + +
+
+ +
+
+ +
+
+ +Don't use periods for geographic abbreviations. Capitalize all country codes. + +
+
+ +
+
+ +
+
+ +## Lists and bullet points + +Capitalize the first word of each list item. Use sentence case throughout. For punctuation in lists, see [Punctuation: Period/full stop](./punctuation.md#periods--full-stops-). + +
+
+ +
+
+ +
+
+ +## Hyphenated words + +Capitalize only the first word of a hyphenated compound (nouns connected with hyphens) unless the second part is a proper noun. + +
+
+ +
+
+ +
+
+ +## Special cases + +Use lowercase for file extensions. Use the original case for file names and paths. + +
+
+ +
+
+ +
+
+ +Use the exact case used in programming when writing or referencing actual code or technical identifiers, but not for UI text or end-user documentation. + +camelCase (variables, functions, methods): + +
+
+ +
+
+ +
+
+ +dash-case (URLs, file names, CSS classes): + +
+
+ +
+
+ +
+
+ +## Related + +- [Voice and tone](./voice-and-tone.md) +- [UI terminology](../menu-functions-and-ui-labels/ui-terminology.md) +- [Punctuation](./punctuation.md) diff --git a/docs/guidelines/language/basics/grammar.md b/docs/guidelines/language/basics/grammar.md index 6060c1ddc..bbc2a9a36 100644 --- a/docs/guidelines/language/basics/grammar.md +++ b/docs/guidelines/language/basics/grammar.md @@ -300,4 +300,4 @@ Use "if" for uncertain conditions or user choices, and "when" for inevitable or - [Toast messages](../messaging/toast-messages.mdx) - [Error messages](../messaging/error-messages.mdx) - [Warning messages](../messaging/warning-messages.mdx) -- [License management](../menu-functions-and-ui-labels/license-management.md) \ No newline at end of file +- [License management](../menu-functions-and-ui-labels/license-management.md) diff --git a/docs/guidelines/language/basics/inclusive-language.md b/docs/guidelines/language/basics/inclusive-language.md index 3947895e3..4e2547c8a 100644 --- a/docs/guidelines/language/basics/inclusive-language.md +++ b/docs/guidelines/language/basics/inclusive-language.md @@ -1,4 +1,4 @@ ---- +--- sidebar_position: 6 sidebar_label: Inclusive language title: Inclusive language @@ -86,3 +86,4 @@ Official Siemens brand resources regarding this theme are exclusively available - [Offensive language](./offensive-language.md) - [UX writing resources and support](../support-and-resources/UX-writing-resources.md) +- [Vocabulary](../basics/vocabulary.md) diff --git a/docs/guidelines/language/basics/offensive-language.md b/docs/guidelines/language/basics/offensive-language.md index 5b79b24e8..40f3edcd4 100644 --- a/docs/guidelines/language/basics/offensive-language.md +++ b/docs/guidelines/language/basics/offensive-language.md @@ -86,4 +86,5 @@ Engage with language experts specializing in content moderation to ensure compre ## Related - [Voice and tone](./voice-and-tone.md) +- [Vocabulary](../basics/vocabulary.md) - [User management](../menu-functions-and-ui-labels/user-management.md) diff --git a/docs/guidelines/language/basics/punctuation.md b/docs/guidelines/language/basics/punctuation.md new file mode 100644 index 000000000..437e5e4c9 --- /dev/null +++ b/docs/guidelines/language/basics/punctuation.md @@ -0,0 +1,648 @@ +--- +sidebar_position: 3 +sidebar_label: Punctuation +title: Punctuation +doc-type: 'banner' +component-tabs: [''] +no_single_tab: true +description: 'We recommend a minimal approach to punctuation as it can add cognitive load and presents consistency challenges across products, portfolios and teams.' +--- + +# + +## Ampersand `&` + +Use only when part of an official or registered product or company name. Although space-saving, many screen readers are unable to interpret ampersands correctly. + +
+
+ +
+
+ +
+
+ +The common phrase “About & legal” always uses the ampersand. This is the only exception in our guidelines for ampersand use. + +
+
+ +
+
+ +
+
+ +## Apostrophe `’` + +Apostrophes look like a single quotation mark, show ownership and create contractions (I’m, you’re, they’re). + +
+
+ +
+
+ +With our minimal punctuation approach, we limit apostrophes by using nouns as adjectives. + +
+
+ +
+
+ +
+
+ +## Asterisk `*` + +Use a single asterisk to indicate required fields. Place them immediately after the text without a space. A legend explaining what the asterisk means, typically at the top of forms, is no longer necessary as asterisks are widely understood to mean mandatory. + +Note: Consider adding asterisks automatically via attributes within your component to remove the manual load and prevent duplication. See [Forms field (component)](../../../components/forms-field/guide.md). + +
+
+ +
+
+ +
+
+ +## Bullet points `•` + +Use bullet points to break down complex information into scannable, digestible chunks. They help users quickly identify key points and reduce cognitive load. Use consistent bullet styles within a single list or section. + +For unordered lists, use round bullets (•). For ordered lists, use numbers followed by a period (1.). Maintain parallel structure; if one item is a complete sentence, make all items complete sentences. + +Add one space after the bullet point or number before the text begins. + +
+
+ +
+
+ +## Colon `:` + +Use to introduce lists, options, descriptions, settings and preferences to visually separate labels and input fields. Colons help to enhance readability when both the labels and input area are not visually distinguishable. When it’s clear within the interface what needs to be completed, remove the colon. + +
+
+ +
+
+ +## Comma `,` + +Use commas to separate data in lists for clarity. + +
+
+ +
+
+ +
+
+ +The Oxford comma is placed before the final “and” or “or” in a list of three or more items. It is acceptable to use and can help avoid ambiguity, but omit it when space is limited in the UI. Remove the Oxford comma especially if it causes text to wrap or overflow in constrained UI elements such as labels, tooltips or buttons. + +
+
+ +
+
+ +## Ellipsis `…` + +Use ellipsis with transitional text to inform users that something is happening and ongoing. There are never spaces between the text and the ellipsis. + +
+
+ +
+
+ +
+
+ +They are also sometimes used to show that a new dialog box will open within the UI, e.g. "Print…" or "Save as…", but as this comes with consistency challenges it is slowly being removed from UX writing guidelines. + +
+
+ +
+
+ +
+
+ +## Hyphen `‐` + +Hyphens join words together (drop-down menu) and connect prefixes to words (non-technical). Use hyphens to avoid confusion and enhance readability. Never use spaces before or after the hyphen. + +
+
+ +
+
+ +
+
+ +Remove hyphens for widely understood terms that have evolved beyond needing them. + +
+
+ +
+
+ +
+
+ +## Minus sign `−` + +Use the proper minus sign (−) rather than a hyphen (-) when expressing negative values or subtraction. In UI contexts such as labels, values or data displays, the minus sign should be used to ensure mathematical clarity. The minus sign should be placed directly before the number with no intervening space except for mathematical operations for readability. See [Formatting of Numbers and percentages](../formatting/numbers.mdx) + +
+
+ +
+
+ +
+
+ +## En and em dashes `– —` + +They look similar, but there are two dashes and we use them differently from hyphens and the minus sign. + +Use the smaller en dash to connect times, numbers and date ranges. Use the longer em dash to replace commas, brackets or colons. + +Don’t use spaces when using en dashes for number ranges. In all other cases, add spaces before and after en dashes and em dashes for digital readability. + +Em dashes are often used in longer texts to make part of the text stand out, such as telling users about special or new application features. To avoid em dash overuse, we typically use commas instead within UI text to connect phrases. + +
+
+ +
+
+ +
+
+ +## Exclamation mark `!` + +Use only for high-level alarms. We don’t use them for messages, notifications or for any other communication with our users. And, as the exclamation mark is often within warning icons, it doesn’t need to be added to text to signify the strength of our messaging. + +
+
+ +
+
+ +
+
+ +## Forward slash `/` + +Use forward slashes sparingly in UI text. They work well for established patterns and technical contexts, but can reduce clarity and accessibility. Forward slashes are appropriate for established UI patterns like on/off and country/region, mathematical fractions, file paths, and compact form labels where space is limited. Use lowercase in body text (on/off) and sentence case following standard capitalization rules (see Capitalization guide). Use lowercase after the slash unless it’s a proper noun. + +Avoid spaces before or after the slash unless spaces enhance clarity in larger text blocks or when there is complex formatting where spaces can enhance readability. + +
+
+ +
+
+ +
+
+ +## Parentheses and brackets + +There are several types of parentheses (also known as brackets). For all variations, there are no spaces between the parentheses and the text within them. However, there are spaces before and after all variations except when followed by another punctuation mark. + +### Round `( )` + +Use sparingly to give users additional information or clarify messaging. Consider alternative punctuation first, e.g. commas or dashes. Use when the information is supplementary but helpful. + +
+
+ +
+
+ +
+
+ +### Curly `\{ \}` + +Use for variables, placeholders and programming. + +
+
+ +
+
+ +### Square `[ ]` + +Rarely used within UI text. Sometimes used for units but more common within academic authoring, quotes and translations to indicate errors, omissions or text in other languages. + +
+
+ +
+
+ +### Angular `< >` + +Use to show file paths and navigation more clearly in applications. Add spaces before and after for enhanced readability except when followed by another punctuation mark. + +
+
+ +
+
+ +
+
+ +## Periods / full stops `.` + +Use consistently. We use full stops at the end of all full sentences and file extensions (.csv .txt .zip). + +
+
+ +
+
+ +
+
+ +When creating lists or using bullet points, use full stops for full sentences. If even one item in your list requires a full stop, add full stops to all items to keep punctuation consistent. + +
+
+ +
+
+
+
+ +
+
+ +We do not use full stops for toast messages (brief pop-ups), headings, titles or icon/button text labels. No space before a full stop. Only one space after a full stop between sentences. + +
+
+ +
+
+ +
+
+ +## Question mark `?` + +Question marks are appropriate for genuine informational questions, in help text and search prompts. However, avoid them in headings, even when phrased as questions, to maintain a confident and declarative tone. + +
+
+ +
+
+ +
+
+ +State consequences clearly and use direct language that empowers users rather than questioning their choices. Avoid "Are you sure...?" phrasing specifically, as this can seem patronizing and undermines user confidence. + +
+
+ +
+
+ +
+
+ +Never use multiple question marks for emphasis. Use one space after a question mark when it appears mid-sentence, and no space before. + +
+
+ +
+
+ +## Quotation marks `" "` + +Use consistent quotation marks throughout the UI. We typically use straight double quotation marks, not single or curly, for direct quotes and to highlight UI text when it improves readability. Use quotation marks to differentiate UI elements only when the same word appears multiple times in close proximity or when clarity requires it. Avoid overusing quotation marks around UI elements as most of the time, the context is clear without them. + + +
+
+ +
+
+ +
+
+ +Never use quotation marks for emphasis or to add informal tone. No space between quotation marks and the enclosed text. One space after the closing quotation mark when mid-sentence. + +
+
+ +
+
+ +
+
+ +## Semi-colon `;` + +Use semi-colons to separate key application features to enhance and contrast them, and to present steps or sequential information. We prefer using commas or short sentences instead as semi-colons are easily misused and misunderstood. No space before a semicolon. One space after a semicolon when mid-sentence. + +
+
+ +
+
+ +
+
+ +## Tilde `~` + +Use the tilde primarily in technical contexts to indicate approximation and home directories in file paths. In UI text, we prefer "approximately" or "about" for better clarity and accessibility when there is space within the UI. Add spaces before and after the tilde when using it to mean "approximately" in text. Remove spaces when used in file paths or technical notation. + +
+
+ +
+
+ +
+
+ +## Trademark symbols `™` `®` + +Use the correct symbol for the correct context. ™ is used for unregistered trademarks, ® is used for registered trademarks. Always follow Siemens brand guidelines when applying trademark symbols to product and service names. + +Only use the trademark symbol on the first mention of the name on a page or screen. Don't repeat it every time the name appears. + +Never place a space between the name and the symbol. Don't alter the size or position of the symbol, it should always appear as a superscript. + +
+
+ +
+
+ +
+
+ +Note: If you are unsure whether a product name is a registered or unregistered trademark, check with your legal or brand team before publishing. Using the wrong symbol can have legal implications. + +## Punctuation and spacing + +**Spaces before punctuation:** As a general rule, there are no spaces between text and its following punctuation. + +
+
+ +
+
+ +
+
+ +Spaces after punctuation: Use only one space after periods (full stops), commas, semicolons, colons, exclamation marks, question marks and quotation marks. + +
+
+ +
+
+ +
+
+ +Spaces before and after punctuation: No spaces inside parentheses or quotation marks. + +
+
+ +
+
+ +
+
+ +## Related + +- [Messages overview](../messaging/messages-overview.md) +- [Progress updates](../messaging/progress-updates.mdx) diff --git a/docs/guidelines/language/basics/vocabulary.md b/docs/guidelines/language/basics/vocabulary.md new file mode 100644 index 000000000..5c2047403 --- /dev/null +++ b/docs/guidelines/language/basics/vocabulary.md @@ -0,0 +1,560 @@ +--- +sidebar_position: 3 +sidebar_label: Vocabulary +title: Vocabulary +doc-type: 'banner' +component-tabs: [''] +no_single_tab: true +description: 'Explore common vocabulary themes and challenges in UX writing. This section guides you on using the correct and most effective words to create easily understandable content.' +--- + +## Word length + +Use short words instead of long words (8 letters or more) when possible. + +
+
+ +
+
+ +
+
+ +Keep sentences under 25 words (the average is 15 words) and break up longer sentences. + +
+
+ +
+
+ +
+
+ +Keep headings, sub-headings, and email subjects under 65 characters (including spaces). + +
+
+ +
+
+ +
+
+ +## Modal verbs + +Modal verbs are helping words such as "can", "must" or "will". They are placed before other verbs to show possibility, permission, obligation or ability. We use some modal verbs in UI text when talking about what users can and cannot do in products. + +Use "can" and "cannot" to talk about permissions and capabilities instead of "could" that indicates uncertainty. + +
+
+ +
+
+ +
+
+ +Use "will" to talk about definite future actions and consequences instead of "would" that indicates hesitation and doubt. + +
+
+ +
+
+ +
+
+ +Do not use "should" when giving instructions as it indicates a recommendation, not a concrete action. + +
+
+ +
+
+ +
+
+ +Specifically avoid using the modal verbs "may" or "might" as they are unclear. Instead, state consequences clearly. + +
+
+ +
+
+ +
+
+ +Avoid using "must" as this can seem aggressive and forceful. Only use it for emergencies. + +
+
+ +
+
+ +
+
+ +Avoid "shall" as it sounds overly formal and legal, and readers often confuse it with "will" or "should". + +
+
+ +
+
+ +
+
+ +## Idioms, buzzwords and jargon + +Avoid idiomatic expressions because their meaning cannot be understood literally from the words themselves, especially by non-native speakers. + +
+
+ +
+
+ +
+
+ +Avoid buzzwords as they sound corporate rather than clear. + +
+
+ +
+
+ +
+
+ +Avoid jargon unless your specific audience understands the technical term better than a plain alternative. + +
+
+ +
+
+ +
+
+ +Avoid cultural references or brand names unless functionally necessary. + +
+
+ +
+
+ +
+
+ +## Phrasal verbs (multi-word verbs) + +Avoid multi-word phrasal verbs when one word works. + +
+
+ +
+
+ +
+
+ +Use common industrial-application phrasal verbs when they are more familiar than one-word alternatives. + +
+
+ +
+
+ +
+
+ +## Abbreviations and acronyms + +Use abbreviations and acronyms carefully. They can improve clarity for domain users, but can confuse general users. Never invent your own acronyms. Use established terminology only. See [Capitalization and proper nouns](./capitalization-and-proper-nouns) for punctuation guidance. + +
+
+ +
+
+ +
+
+ +Avoid Latin abbreviations when there is space in the UI for plain English alternatives. Although e.g. and i.e. seem to be universally understood, many non-native English speakers cannot distinguish between them. + +
+
+ +
+
+ +
+
+ +Use established industry-standard acronyms when your user expects them. Spell out new or less familiar acronyms on first use, then use the acronym consistently afterward. + +
+
+ +
+
+ +
+
+ +Abbreviations are acceptable in buttons, labels and tables when space is limited and only when they are familiar to users. Clarify abbreviations in a visible part of the UI with legends, glossaries or infotips. + +
+
+ +
+
+ +Add lower case "s" without an apostrophe for plural forms. + +
+
+ +
+
+ +
+
+ +## Nouns without plural form + +English has many nouns that do not take a plural form (they do not use "s" for plurals). These are common errors in menus, labels and instructions within industrial UIs. + +
+
+ +
+
+ +
+
+ +Use the singular verb form for collective nouns. Organizations and groups are single entities. + +
+
+ +
+
+ +
+
+ +## Time-based vocabulary + +Choose time-related words carefully. They set user expectations about whether more updates, events or actions will occur. + +### Last vs. latest vs. recent + +Last implies nothing else will follow. It is final and no more are coming. + +
+
+ +
+
+ +
+
+ +Latest is the most recent and newest, which means there could be more to follow. + +
+
+ +
+
+ +
+
+ +Recent means it happened a short time ago. Similar to "latest" but highlights events closer to the present. + +
+
+ +
+
+ +
+
+ +### Pending vs. waiting vs. queued + +Pending means waiting for an action or decision that needs someone else to act. + +
+
+ +
+
+ +Waiting means the system is paused until a condition is met. Avoid "awaiting" as this is too formal. + +
+
+ +
+
+ +
+
+ +Queued means something is in a line and will be processed in order. + +
+
+ +
+
+ +
+
+ +## False friends + +False friends are words that seem correct because they look similar to words in other languages, but they mean something different in English. Always check the English meaning and avoid word-for-word translations. + +Here are common false friends in industrial UX writing. + +| English word and meaning | Similar to other language | Meaning in other language | Typical error in UX writing | Correct translation | +| --- | --- | --- | --- | --- | +| actual (real) | German "aktuell" | current, present | "actual value" read as "current value" not "real value" | "tatsächlich" (actual)
"aktuell" (current) | +| actualize (make real) | German "aktualisieren" | update, refresh | "actualize notifications" read as "update notifications" not "make notifications real" | "aktualisieren" (update)
"verwirklichen" (actualize) | +| billion (109) | German "Billion" | trillion (1012) | data values off by 1000x in reports | "Milliarde" (billion)
"Billion" (trillion) | +| control (regulate) | Spanish "controlar" | to check, verify | "control system" might mean "check system" | "Gestionar/administrar un proceso" (control the process)
"Panel de configuracion/supervision" (control panel) | +| date (day/time) | German "Datei" | computer file | "enter date" could mean "enter file" | "Datum" (date)
"Datei" (file) | +| eventually (in time) | German "eventuell" | possibly, perhaps | "process eventually completes" is ambiguous | "schließlich" (eventually)
"eventuell" (possibly) | +| exit (leave) | Spanish "exito" | success | "exit code" could mean "success code" | "salida" (exit)
"éxito" (success) | +| fabric (textile) | French "fabrique" | factory, plant | "fabric configuration" suggests factory config | "tissu" (fabric)
"fabrique" (factory) | +| fast (quick) | German "fast" | almost, nearly | "fast mode" means "almost mode" | "schnell" (fast)
"fast" (almost) | +| large (big) | French "large" | wide | "large capacity" might mean "wide capacity" | "grand" (large)
"large" (wide) | +| library (collection) | French "librairie" | bookstore | "code library" misunderstood | "bibliothèque" (library)
"librairie" (bookstore) | +| realize (understand) | Spanish "realizar" | to carry out, perform | "realize changes" means "perform changes" | "darse cuenta" (realize)
"realizar" (perform) | +| sensible (rational) | French "sensible" | sensitive | "sensible data" means sensitive, not reasonable | "raisonnable" (sensible)
"sensible" (sensitive) | + +## Common wording issues + +The following words and pairs are often misused and misunderstood when writing text for industrial applications. + +
+
+ +
+
+ +
+
+ +## Related + +- [UI terminology](../menu-functions-and-ui-labels/ui-terminology.md) +- [Grammar](./grammar.md) diff --git a/docs/guidelines/language/basics/voice-and-tone.md b/docs/guidelines/language/basics/voice-and-tone.md index e845658aa..e5cc01b2c 100644 --- a/docs/guidelines/language/basics/voice-and-tone.md +++ b/docs/guidelines/language/basics/voice-and-tone.md @@ -160,5 +160,6 @@ Avoid using negative shortened word forms such as “can’t” and “won’t ## Related - [Grammar](./grammar.md) -- [Punctuation](../punctuation.md) -- [Capitalization](../proper-nouns.md) +- [Punctuation](./punctuation.md) +- [Capitalization](./capitalization-and-proper-nouns.md) +- [Error pages](../messaging/error-pages.md) diff --git a/docs/guidelines/language/grammar-and-vocabulary.md b/docs/guidelines/language/grammar-and-vocabulary.md deleted file mode 100644 index 1ac3e8644..000000000 --- a/docs/guidelines/language/grammar-and-vocabulary.md +++ /dev/null @@ -1,169 +0,0 @@ ---- -sidebar_position: 2 -sidebar_label: Grammar and vocabulary -title: Grammar and vocabulary -doc-type: 'banner' -component-tabs: [''] -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." ---- - -# - -## 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 - -
-
- -
-
- -
-
- -## UI terminology - -- Mouse terminology: drag, hover, point, tap, click - -- Touchscreen gestures: tap, drag, flick, touch and hold, double-tap, swipe, pinch, spread - -- Basic terminology: checkbox, drop-down, field, icon, menu, link, radio button, window - -
-
- -
-
- -
-
- -## Idioms and phrasal verbs - -- Avoid multi-word phrasal verbs when one word works - -- Avoid idiomatic expressions - -- Avoid cultural references - -
-
- -
-
- -
-
- -## Jargon, buzz words and terms - -- Use simple vocabulary - -- Do not avoid technical terms but consider if you need to explain them - -- Define new or unfamiliar terms and use existing explanations (do not reinvent the wheel) - -## Abbreviations and acronyms - -- Avoid abbreviations (info, incl, excl) and acronyms (SIOS for Siemens Industry Online Support) - -- Explain acronyms initially and in full unless well known: Asset Performance Suite (APS) - -- Capitalization only for acronyms that are proper nouns - -- No periods in abbreviations or acronyms - -- Never make up your own acronyms: https://www.acronymfinder.com/ - -
-
- -
-
- -
-
- -## 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. - -- Latest implies that it is the last to date, which means there could be more to follow. Most recent. Newest. - -- Recent is more time focused and is similar to latest. It means that it happened a short time ago. - -
-
- -
-
- -
-
diff --git a/docs/guidelines/language/proper-nouns.md b/docs/guidelines/language/proper-nouns.md deleted file mode 100644 index 42cc422ed..000000000 --- a/docs/guidelines/language/proper-nouns.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -sidebar_position: 4 -sidebar_label: Proper nouns -title: Proper nouns -doc-type: 'banner' -component-tabs: [''] -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.' ---- - -# - -## Capitalize proper nouns - -- A proper noun is the name of a particular person, place, or object that is spelled with a capital letter - -- Examples of proper nouns in English are Jennie, Edinburgh, and Digital Enterprise Labs - -- In contrast, a common noun is a noun that is the name of a group of similar things, such as "pump" or "valve", and not of a single person, place, or thing and is not capitalized - -- In the context of industrial applications, proper nouns might be company and product names, tools or existing technical and legal terms - -- Avoid making up your own proper nouns, e.g. ball valve instead of Ball Valve - -## Siemens proper nouns - -- Siemens Corporate Information - -- Siemens Privacy Notice - -- Siemens Terms of Use - -- Siemens Cookie Notice - -- Siemens Digital ID - -- SIMATIC PCS myExpert, iOS, JavaScript - -- Siemens Industry Online Support - -- Siemens Service & Support - -## Technical terms - -- Operating systems: iOS, Android, Windows, Linux - -- Programming languages: JavaScript, etc. - -- Industrial engineering: P&ID diagram, etc. diff --git a/docs/guidelines/language/punctuation.md b/docs/guidelines/language/punctuation.md deleted file mode 100644 index d13778b8d..000000000 --- a/docs/guidelines/language/punctuation.md +++ /dev/null @@ -1,181 +0,0 @@ ---- -sidebar_position: 3 -sidebar_label: Punctuation -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.' ---- - -# - -## Minimalist punctuation - -Always consider whether necessary - -
-`!` Exclamation mark for high-level warnings only! -
- -
-`?` Question mark only if necessary -
- -
-`:` Use colons: especially to introduce lists -
- -
-`.` Full stops at the end of all full sentences -
- -
-`.` Full stops before all file extensions: .csv .txt .zip -
- -
-`.` Consistent use of full stops throughout the application -
- -
-`…` Ellipsis only for transitional text: Upload… -
- -
-`'` Single quotation mark for possession: Customer’s role (single), customers’ roles (plural) -
-
- No quotation mark or brackets for plurals: PDFs -
- -
-`&` Avoid ampersands unless in a product or company name: Siemens & Halske AG -
- -
-`*` Avoid asterisks in applications -
- -
-`(` Avoid brackets ( ) and [ ] -
- -
-`;` Avoid semi-colons -
- -
-`:` Avoid and remove colons whenever possible, for example Username instead of Username: -
- -## Formats - -- 12-hour clock: 11am and 11pm or 11AM and 11PM - -- 24-hour clock: 11:00 and 23:00 - -- Date: Monday, January 12, 2021 - -- Money: $400,456.50 - -- Measurement and quantities: 30 mm - -- Hyphen for ranges: 10-40% - -- Numbers: Use No. as an abbreviation for number, no spacing between abbreviated No. and number: No.8 - -
-
- -
-
- -
-
- -## Spacing - -- No space before % - -- No space before colon, semi-colon, ellipsis - -- Add a space after colon or semi-colon - -- Add a space before and after equation marks, hyphens and em dashes - -- Add a space before unit of measurement - -
-
- -
-
- -
-
- -## Lists - -- Consistent use of full stops in lists / bullet points - -- If lists / points are not full sentences, do not use full stops - -- Use fragments or full sentences in lists, not both - -- If a bullet / list item has two sentences, use full stops for this point and all others - -- Make lists parallel, i.e. all items / bullets have the same look, length, feel, punctuation, capitalization - -
- -
- -
- -
- -
-
diff --git a/docs/guidelines/language/support-and-resources/AI-and-UX-writing.md b/docs/guidelines/language/support-and-resources/AI-and-UX-writing.md index fa78c0f42..44b3ffc09 100644 --- a/docs/guidelines/language/support-and-resources/AI-and-UX-writing.md +++ b/docs/guidelines/language/support-and-resources/AI-and-UX-writing.md @@ -55,7 +55,7 @@ When presented with an error message, follow this process: * Error codes (unless user-facing standard) * Passive voice * Title casing, ALL CAP messages - * Blaming language (“you failed to...”) + * Blaming language (“you failed to…”) * “Please” do not use please for user actions or in any text 5. Include diff --git a/docs/guidelines/language/writing-style-guide-getting-started.md b/docs/guidelines/language/writing-style-guide-getting-started.md index 8a03cee50..5a10eac88 100644 --- a/docs/guidelines/language/writing-style-guide-getting-started.md +++ b/docs/guidelines/language/writing-style-guide-getting-started.md @@ -16,15 +16,15 @@ Dive into the fundamental principles of UX writing, where you'll learn how to cr ## Grammar and vocabulary -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. [Read more](./grammar-and-vocabulary) +Discover the importance of proper grammar and vocabulary in UX writing. These subchapters will guide you on how to use language effectively to create professional and easily understandable content. Read more: [Grammar](./basics/grammar.md) and [Vocabulary](./basics/vocabulary.md) ## Punctuation -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. [Read more](./punctuation) +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. [Read more](./basics/punctuation.md) -## Proper nouns +## Capitalization and proper nouns -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. [Read more](./proper-nouns) +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. [Read more](./basics/capitalization-and-proper-nouns.md) ## Formatting @@ -41,7 +41,7 @@ Learn when and how to write all types of messages including warnings, errors, in ## Frequent app functions -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. [Read more](./frequent-app-functions) +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. [Read more](../language/frequent-app-functions.md) ## Dialogs and buttons diff --git a/docs/home/support/faq.md b/docs/home/support/faq.md index 407170b4a..f426da394 100644 --- a/docs/home/support/faq.md +++ b/docs/home/support/faq.md @@ -5,7 +5,7 @@ title: FAQ doc-type: 'banner' component-tabs: [''] no_single_tab: true -description: 'Welcome to the Industrial Experience design system FAQ. These are your go-to resource for quick and clear answers about Industrial Experience. Whether you’re just starting with the design system or need insights into integration and functionality, you’ll find answers to the most common questions here. If you can’t find what you’re looking for, feel free to reach out. The FAQ are continuously updated, and we welcome suggestions for improvement via email to our support team. Thank you for choosing to use Siemens Industrial Experience.' +description: 'Find quick answers about Industrial Experience, including setup, integration, customization and support. This FAQ is regularly updated with common questions and guidance.' --- import Accordion from '@site/src/components/Accordion'; diff --git a/package.json b/package.json index 9151248a5..0cd58efbc 100644 --- a/package.json +++ b/package.json @@ -4,10 +4,10 @@ "private": true, "scripts": { "docusaurus": "docusaurus", - "start": "pnpm prepare.docs && docusaurus start", - "build": "pnpm prepare.docs && docusaurus build", - "start.docs": "docusaurus start", - "build.docs": "docusaurus build", + "start": "pnpm prepare.docs && pnpm start.docs", + "build": "pnpm prepare.docs && pnpm build.docs", + "start.docs": "tsx --tsconfig ./tsconfig.node.json ./scripts/run-docusaurus.ts start", + "build.docs": "rimraf build && tsx --tsconfig ./tsconfig.node.json ./scripts/run-docusaurus.ts build", "prepare.docs": "tsx --tsconfig ./tsconfig.node.json ./scripts/prepare-markdown.ts", "swizzle": "docusaurus swizzle", "deploy": "docusaurus deploy", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 7d7ccd1c4..67c7e22b3 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -851,8 +851,8 @@ packages: resolution: {integrity: sha512-909rVuj3phpjW6y0MCXAZ5iNeORePa6ldJvp2baWGcTjwqbBDDz6xoS5JHJ7lS88NlwLYj07ImL/8IUMtDZzTA==} engines: {node: '>=6.9.0'} - '@babel/runtime@7.28.6': - resolution: {integrity: sha512-05WQkdpL9COIMz4LjTxGpPNCdlpyimKppYNoJ5Di5EUObifl8t4tuLuUBBZEpoLYOmfvIWrsp9fCl0HoPRVTdA==} + '@babel/runtime@7.29.7': + resolution: {integrity: sha512-Nq8OhGWiZIZGV6hLHoyAKLLcJihP/xFeBMGJoUrxTX2psI8dCifzLhZISFb+VWS3wFMRDmCGw5R+dOySCqPLhw==} engines: {node: '>=6.9.0'} '@babel/template@7.27.2': @@ -1752,92 +1752,86 @@ packages: resolution: {integrity: sha512-5Kva+/Gi7c+39d0/0MM/v/5RCZuwqm75fUD+t7Es3Iz/adui54GnjfNmJpkkPkXGC+5IWnEvgqwY6gstK/JlUQ==} engines: {node: '>= 18'} - '@parcel/watcher-android-arm64@2.5.6': - resolution: {integrity: sha512-YQxSS34tPF/6ZG7r/Ih9xy+kP/WwediEUsqmtf0cuCV5TPPKw/PQHRhueUo6JdeFJaqV3pyjm0GdYjZotbRt/A==} + '@parcel/watcher-android-arm64@2.6.0': + resolution: {integrity: sha512-trgpLSCKRC/huFjXX/Smh+0sWe4+YtKfktIToiMl59ghz7z+qkH6kMvNnUbLyRs9N11t8l4svSCs1+5B3rOAhA==} engines: {node: '>= 10.0.0'} cpu: [arm64] os: [android] - '@parcel/watcher-darwin-arm64@2.5.6': - resolution: {integrity: sha512-Z2ZdrnwyXvvvdtRHLmM4knydIdU9adO3D4n/0cVipF3rRiwP+3/sfzpAwA/qKFL6i1ModaabkU7IbpeMBgiVEA==} + '@parcel/watcher-darwin-arm64@2.6.0': + resolution: {integrity: sha512-Y3QV0gl7Q1zbfueunkWIERICbEojQFCgpyG7YqOGNFLsckXyI1xu9mAIUpKY9QBYzBtSkN8dBPwd3yiAO9ovMw==} engines: {node: '>= 10.0.0'} cpu: [arm64] os: [darwin] - '@parcel/watcher-darwin-x64@2.5.6': - resolution: {integrity: sha512-HgvOf3W9dhithcwOWX9uDZyn1lW9R+7tPZ4sug+NGrGIo4Rk1hAXLEbcH1TQSqxts0NYXXlOWqVpvS1SFS4fRg==} + '@parcel/watcher-darwin-x64@2.6.0': + resolution: {integrity: sha512-Ohv6OpzhUfKYD7Beb8kDvG0jbIxORCYY1JRdZnaBtnjjkJxgD7ZVL0nw2sCYd0yTMKTvz3nnTnOF3cDifK+kvw==} engines: {node: '>= 10.0.0'} cpu: [x64] os: [darwin] - '@parcel/watcher-freebsd-x64@2.5.6': - resolution: {integrity: sha512-vJVi8yd/qzJxEKHkeemh7w3YAn6RJCtYlE4HPMoVnCpIXEzSrxErBW5SJBgKLbXU3WdIpkjBTeUNtyBVn8TRng==} + '@parcel/watcher-freebsd-x64@2.6.0': + resolution: {integrity: sha512-5HmXvDgs8VK+74jF9y9/2FE3/OnlcKmc56tjmSrEuZjpSZOGL+fvAu+HKJBdPs9uwoP2hE6TlSUpXZ/C5jUFmQ==} engines: {node: '>= 10.0.0'} cpu: [x64] os: [freebsd] - '@parcel/watcher-linux-arm-glibc@2.5.6': - resolution: {integrity: sha512-9JiYfB6h6BgV50CCfasfLf/uvOcJskMSwcdH1PHH9rvS1IrNy8zad6IUVPVUfmXr+u+Km9IxcfMLzgdOudz9EQ==} + '@parcel/watcher-linux-arm-glibc@2.6.0': + resolution: {integrity: sha512-Ps/hui3A+vMbjdqlqAowK2ZL8+BO8dBjxeWXj6npTBs3jx4wWmbPpaLuqwrQrSqIVMCnpWo238bJ1U37GhQOYg==} engines: {node: '>= 10.0.0'} cpu: [arm] os: [linux] libc: [glibc] - '@parcel/watcher-linux-arm-musl@2.5.6': - resolution: {integrity: sha512-Ve3gUCG57nuUUSyjBq/MAM0CzArtuIOxsBdQ+ftz6ho8n7s1i9E1Nmk/xmP323r2YL0SONs1EuwqBp2u1k5fxg==} + '@parcel/watcher-linux-arm-musl@2.6.0': + resolution: {integrity: sha512-9c6AUHgHoG+IY88MRIHupztQiQnrbqHYQjkM2btA+Bf/wQnQMuiD0Wfk1EVv3TlNT3x41uU71rn6E4xh/+zvkw==} engines: {node: '>= 10.0.0'} cpu: [arm] os: [linux] libc: [musl] - '@parcel/watcher-linux-arm64-glibc@2.5.6': - resolution: {integrity: sha512-f2g/DT3NhGPdBmMWYoxixqYr3v/UXcmLOYy16Bx0TM20Tchduwr4EaCbmxh1321TABqPGDpS8D/ggOTaljijOA==} + '@parcel/watcher-linux-arm64-glibc@2.6.0': + resolution: {integrity: sha512-yHRqS2owEXe6Hic9z6Mh1ECsCd+ODVOGvZDyciqRd21+v+o+DnXMOrw50DSpIG2sb8GPEaPPmfeCAWKPJdq46g==} engines: {node: '>= 10.0.0'} cpu: [arm64] os: [linux] libc: [glibc] - '@parcel/watcher-linux-arm64-musl@2.5.6': - resolution: {integrity: sha512-qb6naMDGlbCwdhLj6hgoVKJl2odL34z2sqkC7Z6kzir8b5W65WYDpLB6R06KabvZdgoHI/zxke4b3zR0wAbDTA==} + '@parcel/watcher-linux-arm64-musl@2.6.0': + resolution: {integrity: sha512-WhB2e/V7rqdHHWZusBSPuy5Ei8S6lSz6FE5TKKQz5h3a0O+C+mhY7vxU9b/stqvMb8beLnPY82ZrFTLKs+SrKA==} engines: {node: '>= 10.0.0'} cpu: [arm64] os: [linux] libc: [musl] - '@parcel/watcher-linux-x64-glibc@2.5.6': - resolution: {integrity: sha512-kbT5wvNQlx7NaGjzPFu8nVIW1rWqV780O7ZtkjuWaPUgpv2NMFpjYERVi0UYj1msZNyCzGlaCWEtzc+exjMGbQ==} + '@parcel/watcher-linux-x64-glibc@2.6.0': + resolution: {integrity: sha512-ulGE6x6Oz6iAwg75T8YQSoguBWasniIbX+QWpaYPcCnDOpdWX3k+4xbEYPZVLxOuoJI+svJJPD3sEj8G7lrQ3A==} engines: {node: '>= 10.0.0'} cpu: [x64] os: [linux] libc: [glibc] - '@parcel/watcher-linux-x64-musl@2.5.6': - resolution: {integrity: sha512-1JRFeC+h7RdXwldHzTsmdtYR/Ku8SylLgTU/reMuqdVD7CtLwf0VR1FqeprZ0eHQkO0vqsbvFLXUmYm/uNKJBg==} + '@parcel/watcher-linux-x64-musl@2.6.0': + resolution: {integrity: sha512-tkBYKt7YQrjIJWYDnto2YgO8MRkjlMTSNoRHzsXinBqbLdeOM3L32wPZJvIZxqaLMfSlS/4sUjH/6STVP/XDLw==} engines: {node: '>= 10.0.0'} cpu: [x64] os: [linux] libc: [musl] - '@parcel/watcher-win32-arm64@2.5.6': - resolution: {integrity: sha512-3ukyebjc6eGlw9yRt678DxVF7rjXatWiHvTXqphZLvo7aC5NdEgFufVwjFfY51ijYEWpXbqF5jtrK275z52D4Q==} + '@parcel/watcher-win32-arm64@2.6.0': + resolution: {integrity: sha512-gIZAP23jaHjGWasY/TY6yL7NHFClf0Ga7FN+iINvk+KN94rhm94lYZhFsbYFNcA04/onvGD9kKmiJLJB2HbNwQ==} engines: {node: '>= 10.0.0'} cpu: [arm64] os: [win32] - '@parcel/watcher-win32-ia32@2.5.6': - resolution: {integrity: sha512-k35yLp1ZMwwee3Ez/pxBi5cf4AoBKYXj00CZ80jUz5h8prpiaQsiRPKQMxoLstNuqe2vR4RNPEAEcjEFzhEz/g==} - engines: {node: '>= 10.0.0'} - cpu: [ia32] - os: [win32] - - '@parcel/watcher-win32-x64@2.5.6': - resolution: {integrity: sha512-hbQlYcCq5dlAX9Qx+kFb0FHue6vbjlf0FrNzSKdYK2APUf7tGfGxQCk2ihEREmbR6ZMc0MVAD5RIX/41gpUzTw==} + '@parcel/watcher-win32-x64@2.6.0': + resolution: {integrity: sha512-cA+/pXV2YkfxlIcXOQ5fSWqAzzPyD78/x5qbK/I0vUkrlYHA8TIz+MXjAbGouguKVSI4bOmkTSJ1/poVSsgt+A==} engines: {node: '>= 10.0.0'} cpu: [x64] os: [win32] - '@parcel/watcher@2.5.6': - resolution: {integrity: sha512-tmmZ3lQxAe/k/+rNnXQRawJ4NjxO2hqiOLTHvWchtGZULp4RyFeh6aU4XdOYBFe2KE1oShQTv4AblOs2iOrNnQ==} + '@parcel/watcher@2.6.0': + resolution: {integrity: sha512-7FNeNl8NCE7aINx7WXiKQrPYZWC/hvrTsmk6zmxbI7LTXE7hVek/n8AfVgpe2y82zl3w0HvCHN0bVKMBoJcC0w==} engines: {node: '>= 10.0.0'} '@pkgjs/parseargs@0.11.0': @@ -2551,8 +2545,8 @@ packages: caniuse-api@3.0.0: resolution: {integrity: sha512-bsTwuIg/BZZK/vreVTYYbSWoe2F+71P7K5QGEX+pT250DZbfU1MQ5prOKpPR+LL6uWKK3KMwMCAS74QB3Um1uw==} - caniuse-lite@1.0.30001718: - resolution: {integrity: sha512-AflseV1ahcSunK53NfEs9gFWgOEmzr0f+kaMFA4xiLZlr9Hzt7HxcSpIFcnNCUkz6R6dWKa54rUz3HUmI3nVcw==} + caniuse-lite@1.0.30001806: + resolution: {integrity: sha512-72Cuvd95zbSYPKq6Fhg8eDJRlzgWDf7/mtoZv6Qe/DYNCEBdNxoA3+rZAU2ZhGCpZlns3EssFavaZomckT5Uuw==} ccount@2.0.1: resolution: {integrity: sha512-eyrF0jiFpY+3drT6383f1qhkbGsLSifNAjA61IUjZjmLCWjItY6LB9ft9YhoDgwfmclB2zhu51Lc7+95b8NRAg==} @@ -3730,8 +3724,8 @@ packages: immer@9.0.21: resolution: {integrity: sha512-bc4NBHqOqSfRW7POMkHd51LvClaeMXpm8dx0e8oE2GORbq5aRK7Bxl4FyzVLdGtLmvLKL7BTDBG5ACQm4HWjTA==} - immutable@5.1.4: - resolution: {integrity: sha512-p6u1bG3YSnINT5RQmx/yRZBpenIl30kVxkTLDyHLIMk0gict704Q9n+thfDI7lTRm9vXdDYutVzXhzcThxTnXA==} + immutable@5.1.9: + resolution: {integrity: sha512-m8nVez3rwrgmWxtLMt1ZYXB2Lv7OKYn/disyxAlSDYAlKSlFoPPfIAmAM/M5xqL4m4C/wAPw7S2/CNaUii1Hxg==} import-fresh@3.3.1: resolution: {integrity: sha512-TR3KfrTZTYLPB6jUjfx6MF9WcWrHL9su5TObK4ZkYgBdWKPOFoSoQIdEuTuR82pmtxH2spWG9h6etwfr1pLBqQ==} @@ -4668,6 +4662,10 @@ packages: resolution: {integrity: sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==} engines: {node: '>=12'} + picomatch@4.0.5: + resolution: {integrity: sha512-RvwwcruNjI1ncT5xRakeyS9Lf8lcItv34KD+aif+VH9kduAyfYBipGh12274xtenIPZ119/R9BdTBa8gAwSh0A==} + engines: {node: '>=12'} + pify@2.3.0: resolution: {integrity: sha512-udgsAY+fTnvv7kI7aaxbqwWNb0AHiB0qBO89PZKPkoTmGOgdbrHDKD+0B2X4uTfJ/FT1R09r9gTsjUjNJotuog==} engines: {node: '>=0.10.0'} @@ -7117,7 +7115,7 @@ snapshots: dependencies: core-js-pure: 3.42.0 - '@babel/runtime@7.28.6': {} + '@babel/runtime@7.29.7': {} '@babel/template@7.27.2': dependencies: @@ -7439,7 +7437,7 @@ snapshots: '@babel/preset-env': 7.27.2(@babel/core@7.27.1) '@babel/preset-react': 7.27.1(@babel/core@7.27.1) '@babel/preset-typescript': 7.27.1(@babel/core@7.27.1) - '@babel/runtime': 7.28.6 + '@babel/runtime': 7.29.7 '@babel/runtime-corejs3': 7.27.1 '@babel/traverse': 7.27.1 '@docusaurus/logger': 3.7.0 @@ -8671,65 +8669,61 @@ snapshots: '@octokit/request-error': 6.1.8 '@octokit/webhooks-methods': 5.1.1 - '@parcel/watcher-android-arm64@2.5.6': + '@parcel/watcher-android-arm64@2.6.0': optional: true - '@parcel/watcher-darwin-arm64@2.5.6': + '@parcel/watcher-darwin-arm64@2.6.0': optional: true - '@parcel/watcher-darwin-x64@2.5.6': + '@parcel/watcher-darwin-x64@2.6.0': optional: true - '@parcel/watcher-freebsd-x64@2.5.6': + '@parcel/watcher-freebsd-x64@2.6.0': optional: true - '@parcel/watcher-linux-arm-glibc@2.5.6': + '@parcel/watcher-linux-arm-glibc@2.6.0': optional: true - '@parcel/watcher-linux-arm-musl@2.5.6': + '@parcel/watcher-linux-arm-musl@2.6.0': optional: true - '@parcel/watcher-linux-arm64-glibc@2.5.6': + '@parcel/watcher-linux-arm64-glibc@2.6.0': optional: true - '@parcel/watcher-linux-arm64-musl@2.5.6': + '@parcel/watcher-linux-arm64-musl@2.6.0': optional: true - '@parcel/watcher-linux-x64-glibc@2.5.6': + '@parcel/watcher-linux-x64-glibc@2.6.0': optional: true - '@parcel/watcher-linux-x64-musl@2.5.6': + '@parcel/watcher-linux-x64-musl@2.6.0': optional: true - '@parcel/watcher-win32-arm64@2.5.6': + '@parcel/watcher-win32-arm64@2.6.0': optional: true - '@parcel/watcher-win32-ia32@2.5.6': + '@parcel/watcher-win32-x64@2.6.0': optional: true - '@parcel/watcher-win32-x64@2.5.6': - optional: true - - '@parcel/watcher@2.5.6': + '@parcel/watcher@2.6.0': dependencies: detect-libc: 2.1.2 is-glob: 4.0.3 node-addon-api: 7.1.1 - picomatch: 4.0.3 + picomatch: 4.0.5 optionalDependencies: - '@parcel/watcher-android-arm64': 2.5.6 - '@parcel/watcher-darwin-arm64': 2.5.6 - '@parcel/watcher-darwin-x64': 2.5.6 - '@parcel/watcher-freebsd-x64': 2.5.6 - '@parcel/watcher-linux-arm-glibc': 2.5.6 - '@parcel/watcher-linux-arm-musl': 2.5.6 - '@parcel/watcher-linux-arm64-glibc': 2.5.6 - '@parcel/watcher-linux-arm64-musl': 2.5.6 - '@parcel/watcher-linux-x64-glibc': 2.5.6 - '@parcel/watcher-linux-x64-musl': 2.5.6 - '@parcel/watcher-win32-arm64': 2.5.6 - '@parcel/watcher-win32-ia32': 2.5.6 - '@parcel/watcher-win32-x64': 2.5.6 + '@parcel/watcher-android-arm64': 2.6.0 + '@parcel/watcher-darwin-arm64': 2.6.0 + '@parcel/watcher-darwin-x64': 2.6.0 + '@parcel/watcher-freebsd-x64': 2.6.0 + '@parcel/watcher-linux-arm-glibc': 2.6.0 + '@parcel/watcher-linux-arm-musl': 2.6.0 + '@parcel/watcher-linux-arm64-glibc': 2.6.0 + '@parcel/watcher-linux-arm64-musl': 2.6.0 + '@parcel/watcher-linux-x64-glibc': 2.6.0 + '@parcel/watcher-linux-x64-musl': 2.6.0 + '@parcel/watcher-win32-arm64': 2.6.0 + '@parcel/watcher-win32-x64': 2.6.0 optional: true '@pkgjs/parseargs@0.11.0': @@ -8810,7 +8804,7 @@ snapshots: '@slorber/react-helmet-async@1.3.0(react-dom@18.3.1(react@18.3.1))(react@18.3.1)': dependencies: - '@babel/runtime': 7.28.6 + '@babel/runtime': 7.29.7 invariant: 2.2.4 prop-types: 15.8.1 react: 18.3.1 @@ -9379,7 +9373,7 @@ snapshots: autoprefixer@10.4.21(postcss@8.5.3): dependencies: browserslist: 4.24.5 - caniuse-lite: 1.0.30001718 + caniuse-lite: 1.0.30001806 fraction.js: 4.3.7 normalize-range: 0.1.2 picocolors: 1.1.1 @@ -9506,7 +9500,7 @@ snapshots: browserslist@4.24.5: dependencies: - caniuse-lite: 1.0.30001718 + caniuse-lite: 1.0.30001806 electron-to-chromium: 1.5.155 node-releases: 2.0.19 update-browserslist-db: 1.1.3(browserslist@4.24.5) @@ -9562,11 +9556,11 @@ snapshots: caniuse-api@3.0.0: dependencies: browserslist: 4.24.5 - caniuse-lite: 1.0.30001718 + caniuse-lite: 1.0.30001806 lodash.memoize: 4.1.2 lodash.uniq: 4.5.0 - caniuse-lite@1.0.30001718: {} + caniuse-lite@1.0.30001806: {} ccount@2.0.1: {} @@ -10757,7 +10751,7 @@ snapshots: history@4.10.1: dependencies: - '@babel/runtime': 7.28.6 + '@babel/runtime': 7.29.7 loose-envify: 1.4.0 resolve-pathname: 3.0.0 tiny-invariant: 1.3.3 @@ -10917,7 +10911,7 @@ snapshots: immer@9.0.21: {} - immutable@5.1.4: {} + immutable@5.1.9: {} import-fresh@3.3.1: dependencies: @@ -12033,6 +12027,9 @@ snapshots: picomatch@4.0.3: {} + picomatch@4.0.5: + optional: true + pify@2.3.0: {} pirates@4.0.7: {} @@ -12637,7 +12634,7 @@ snapshots: react-loadable-ssr-addon-v5-slorber@1.0.1(@docusaurus/react-loadable@6.0.0(react@18.3.1))(webpack@5.99.8): dependencies: - '@babel/runtime': 7.28.6 + '@babel/runtime': 7.29.7 react-loadable: '@docusaurus/react-loadable@6.0.0(react@18.3.1)' webpack: 5.99.8 @@ -12663,13 +12660,13 @@ snapshots: react-router-config@5.1.1(react-router@5.3.4(react@18.3.1))(react@18.3.1): dependencies: - '@babel/runtime': 7.28.6 + '@babel/runtime': 7.29.7 react: 18.3.1 react-router: 5.3.4(react@18.3.1) react-router-dom@5.3.4(react@18.3.1): dependencies: - '@babel/runtime': 7.28.6 + '@babel/runtime': 7.29.7 history: 4.10.1 loose-envify: 1.4.0 prop-types: 15.8.1 @@ -12680,7 +12677,7 @@ snapshots: react-router@5.3.4(react@18.3.1): dependencies: - '@babel/runtime': 7.28.6 + '@babel/runtime': 7.29.7 history: 4.10.1 hoist-non-react-statics: 3.3.2 loose-envify: 1.4.0 @@ -12951,10 +12948,10 @@ snapshots: sass@1.87.0: dependencies: chokidar: 4.0.3 - immutable: 5.1.4 + immutable: 5.1.9 source-map-js: 1.2.1 optionalDependencies: - '@parcel/watcher': 2.5.6 + '@parcel/watcher': 2.6.0 sax@1.4.1: {} diff --git a/scripts/prepare-markdown.ts b/scripts/prepare-markdown.ts index 570b3a1ee..f6ff337d6 100644 --- a/scripts/prepare-markdown.ts +++ b/scripts/prepare-markdown.ts @@ -12,6 +12,7 @@ import AdmZip from 'adm-zip'; import fs from 'fs-extra'; import os from 'os'; import path from 'path'; +import { glob } from 'glob'; import copyTheme from './copy-theme'; const __dirname = path.resolve(); @@ -38,6 +39,9 @@ type BranchConfig = { prNumber: string; }; +const autogeneratedImportPattern = + /@site\/docs\/autogenerated\/(api|playground)\/([^"']+)/g; + async function getDefaultFile() { if (!(await fs.exists(__promptDefaults))) { return {}; @@ -79,6 +83,7 @@ async function main() { console.log('=== SKIPPING PREPARE STEP ==='); console.log('========================================'); console.log(`Reason: SKIP_PREPARE is set to "${process.env.SKIP_PREPARE}"`); + await ensureAutogeneratedFallback('SKIP_PREPARE'); return; } const defaults = await getDefaults(); @@ -91,7 +96,19 @@ async function main() { await copyTheme(); const branch = getBranch(defaults); - await downloadLatestArtifact(branch); + + try { + await downloadLatestArtifact(branch); + await ensureAutogeneratedFallback('post-download verification'); + } catch (error) { + if (process.env.CI) { + throw error; + } + + console.warn('Falling back to local autogenerated placeholders.'); + console.warn(error); + await ensureAutogeneratedFallback('artifact download failed'); + } } function getBranch(config: BranchConfig) { @@ -163,37 +180,41 @@ async function downloadLatestArtifact(branch: string) { new Date(b.created_at).getTime() - new Date(a.created_at).getTime() ); - if ( - !runs || - runs.length === 0 || - runs.filter((run) => run.name === 'Build' || run.name === 'Pull Request') - .length === 0 - ) { + const eligibleRuns = runs.filter( + (run) => run.name === 'Build' || run.name === 'Pull Request' + ); + + if (!runs || runs.length === 0 || eligibleRuns.length === 0) { const message = `No workflow runs found for this branch. ${branchName}`; throw new Error(message); } - const runId = runs.filter( - (run) => run.name === 'Build' || run.name === 'Pull Request' - )[0].id; - // Get artifacts for the run - const { data: artifactsData } = - await octokit.actions.listWorkflowRunArtifacts({ - owner, - repo, - run_id: runId, - }); + let artifact: + | Awaited< + ReturnType + >['data']['artifacts'][number] + | undefined; + + for (const run of eligibleRuns) { + const { data: artifactsData } = + await octokit.actions.listWorkflowRunArtifacts({ + owner, + repo, + run_id: run.id, + }); + + artifact = artifactsData.artifacts.find( + (candidate) => + candidate.name.startsWith('documentation-') && !candidate.expired + ); - if (!artifactsData.artifacts || artifactsData.artifacts.length === 0) { - throw new Error('No artifacts found for this workflow run.'); + if (artifact) { + break; + } } - const artifact = artifactsData.artifacts.find((artifact) => - artifact.name.startsWith('documentation-') - ); - if (!artifact) { - throw new Error('No documentation artifact found for this workflow run.'); + throw new Error('No non-expired documentation artifact found for this workflow run.'); } console.log( @@ -221,4 +242,72 @@ async function downloadLatestArtifact(branch: string) { await fs.remove(tempZipPath); } +async function ensureAutogeneratedFallback(reason: string) { + const missingImports = await findMissingAutogeneratedImports(); + + if (missingImports.length === 0) { + console.log('No autogenerated placeholders needed.'); + return; + } + + console.log( + `Creating ${missingImports.length} local autogenerated placeholder files (${reason}).` + ); + + await Promise.all( + missingImports.map(async (filePath) => { + await fs.ensureDir(path.dirname(filePath)); + await fs.writeFile(filePath, createPlaceholderContent(filePath), 'utf8'); + }) + ); +} + +async function findMissingAutogeneratedImports() { + const docsFiles = await glob('docs/**/*.{md,mdx}', { + cwd: __dirname, + absolute: true, + }); + + const missingImports = new Set(); + + for (const docsFile of docsFiles) { + const content = await fs.readFile(docsFile, 'utf8'); + const matches = content.matchAll(autogeneratedImportPattern); + + for (const match of matches) { + const generatedPath = path.join( + __dirname, + 'docs', + 'autogenerated', + match[1], + match[2] + ); + + if (!(await fs.pathExists(generatedPath))) { + missingImports.add(generatedPath); + } + } + } + + return [...missingImports].sort(); +} + +function createPlaceholderContent(filePath: string) { + const relativePath = path.relative( + path.join(__dirname, 'docs', 'autogenerated'), + filePath + ); + const placeholderType = relativePath.startsWith('api') ? 'API' : 'example'; + + return [ + `# ${placeholderType} unavailable`, + '', + 'This placeholder was generated for a local docs build because the', + 'external autogenerated documentation artifact is unavailable.', + '', + `Missing source: ${relativePath}`, + '', + ].join('\n'); +} + main(); diff --git a/scripts/run-docusaurus.ts b/scripts/run-docusaurus.ts new file mode 100644 index 000000000..618287ab3 --- /dev/null +++ b/scripts/run-docusaurus.ts @@ -0,0 +1,32 @@ +import { spawn } from 'child_process'; + +const command = process.argv[2]; +const pnpmExecutable = process.env.npm_execpath; + +if (!command) { + console.error('Missing Docusaurus command. Expected build or start.'); + process.exit(1); +} + +if (!pnpmExecutable) { + console.error('Missing npm_execpath. This script must run through pnpm.'); + process.exit(1); +} + +const child = spawn(process.execPath, [pnpmExecutable, 'exec', 'docusaurus', command], { + stdio: 'inherit', + env: { + ...process.env, + NO_UPDATE_NOTIFIER: '1', + }, + shell: false, +}); + +child.on('exit', (code) => { + process.exit(code ?? 1); +}); + +child.on('error', (error) => { + console.error(error); + process.exit(1); +}); \ No newline at end of file