docs:punctuation-V2

docs/guidelines/language/capitalization-and-proper-nouns.md

@@ -0,0 +1,397 @@
+---
+sidebar_position: 4
+sidebar_label: 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, consistency and localization.
+
+<div className="dos-and-donts">
+<div className="dos">
+  <ul aria-label="Recommended practices">
+    <li>Configure system settings.</li>
+    <li>Import data from external sources.</li>
+    <li>User authentication and permissions.</li>
+  </ul>
+</div>
+<div className="donts">
+  <ul aria-label="Practices to avoid">
+    <li>Configure System Settings.</li>
+    <li>Import Data From External Sources.</li>
+    <li>User Authentication And Permissions.</li>
+  </ul>
+</div>
+</div>
+
+Do not capitalize generic system or technology terms.
+
+<div className="dos-and-donts">
+<div className="dos">
+  <ul aria-label="Recommended practices">
+    <li>database, server, cloud platform, operating system, web application</li>
+    <li>Connect to the database.</li>
+    <li>Upload files to the cloud platform.</li>
+  </ul>
+</div>
+<div className="donts">
+  <ul aria-label="Practices to avoid">
+    <li>Database, Server, Cloud Platform, Operating System, Web Application</li>
+    <li>Connect to the Database.</li>
+    <li>Upload files to the Cloud Platform.</li>
+  </ul>
+</div>
+</div>
+
+Do not capitalize common technology terms that were initially proper nouns and capitalized, e.g. internet, website and email.
+
+<div className="dos-and-donts">
+<div className="dos">
+  <ul aria-label="Recommended practices">
+    <li>Connect to the internet for access.</li>
+    <li>The website is available 24/7.</li>
+    <li>Send an email to support.</li>
+  </ul>
+</div>
+<div className="donts">
+  <ul aria-label="Practices to avoid">
+    <li>The Website is available 24/7.</li>
+    <li>Send an Email to support.</li>
+  </ul>
+</div>
+</div>
+
+## Proper nouns
+
+Always capitalize proper nouns (specific names) including:
+
+<div className="dos-and-donts">
+<div className="dos">
+  <ul aria-label="Recommended practices">
+    <li>Geographic locations: Germany, Munich, United States, Europe, Tokyo</li>
+    <li>Programming languages: Python, JavaScript, C++, Java, Ruby</li>
+    <li>Protocols and standards: HTTP, HTTPS, TCP/IP, ISO 9001, REST</li>
+    <li>Days and months: Monday, January, December</li>
+    <li>Languages: German, English, Italian, French</li>
+  </ul>
+</div>
+</div>
+
+<div className="dos-and-donts">
+<div className="dos">
+  <ul aria-label="Recommended practices">
+    <li>The system supports Python and JavaScript.</li>
+    <li>Software available in Germany and France.</li>
+  </ul>
+</div>
+<div className="donts">
+  <ul aria-label="Practices to avoid">
+    <li>The system supports python and javascript.</li>
+    <li>Software available in germany and France.</li>
+  </ul>
+</div>
+</div>
+
+Always capitalize product names, systems, and third-party platforms exactly as trademarked, using the official spelling and capitalization.
+
+<div className="dos-and-donts">
+<div className="dos">
+  <ul aria-label="Recommended practices">
+    <li>Product names: Adobe Photoshop, Salesforce, Slack, Zoom</li>
+    <li>Company names: Microsoft, Google, Apple, Amazon, Meta</li>
+    <li>Trademarked terms: Windows, macOS, Linux, Android, iOS</li>
+    <li>Configure Photoshop settings.</li>
+    <li>Integrate with Salesforce.</li>
+  </ul>
+</div>
+<div className="donts">
+  <ul aria-label="Practices to avoid">
+    <li>Configure photoshop settings.</li>
+    <li>Integrate with salesforce.</li>
+  </ul>
+</div>
+</div>
+
+Capitalize official service and portal names you have created and named within your product as proper nouns.
+
+<div className="dos-and-donts">
+<div className="dos">
+  <ul aria-label="Recommended practices">
+    <li>Log in to the Customer Portal.</li>
+    <li>Access resources on Developer Hub.</li>
+  </ul>
+</div>
+<div className="donts">
+  <ul aria-label="Practices to avoid">
+    <li>Access resources on developer hub.</li>
+    <li>Log in to the customer portal.</li>
+  </ul>
+</div>
+</div>
+
+## Headings
+
+Use sentence case for all headings (including table headings). Capitalize only the first word and proper nouns. See punctuation guidelines [LINK].
+
+<div className="dos-and-donts">
+<div className="dos">
+  <ul aria-label="Recommended practices">
+    <li>Get started</li>
+    <li>Configure settings</li>
+    <li>Import data from SAP</li>
+  </ul>
+</div>
+<div className="donts">
+  <ul aria-label="Practices to avoid">
+    <li>Get Started</li>
+    <li>Configure Settings</li>
+    <li>Import Data From SAP</li>
+  </ul>
+</div>
+</div>
+
+## Button labels and UI elements
+
+Use sentence case for button labels and UI elements. Capitalize only the first word and proper nouns.
+
+<div className="dos-and-donts">
+<div className="dos">
+  <ul aria-label="Recommended practices">
+    <li>Save changes</li>
+    <li>Export to PDF</li>
+    <li>Connect to server</li>
+    <li>Upload file</li>
+  </ul>
+</div>
+<div className="donts">
+  <ul aria-label="Practices to avoid">
+    <li>Save Changes</li>
+    <li>Export To PDF</li>
+    <li>Connect To Server</li>
+    <li>Upload File</li>
+  </ul>
+</div>
+</div>
+
+Slashes do not create new sentences. Treat them like "and" or "or". Capitalize only the first word and proper nouns. See punctuation guidelines [LINK].
+
+<div className="dos-and-donts">
+<div className="dos">
+  <ul aria-label="Recommended practices">
+    <li>Client/server architecture</li>
+    <li>Read/write permissions</li>
+    <li>Input/output operations</li>
+    <li>On/off switch</li>
+    <li>Windows/Mac compatibility</li>
+  </ul>
+</div>
+<div className="donts">
+  <ul aria-label="Practices to avoid">
+    <li>Client/Server Architecture</li>
+    <li>Read/Write Permissions</li>
+    <li>On/Off Switch</li>
+    <li>windows/mac compatibility</li>
+  </ul>
+</div>
+</div>
+
+## Acronyms and abbreviations
+
+Capitalize all letters in acronyms and abbreviations. Do not use periods between letters.
+
+<div className="dos-and-donts">
+<div className="dos">
+  <ul aria-label="Recommended practices">
+    <li>UI / API / FAQ / PDF / CSV / HTML / USB</li>
+    <li>Check the FAQ for common questions.</li>
+    <li>Export data as CSV or PDF.</li>
+    <li>The API documentation is available online.</li>
+  </ul>
+</div>
+<div className="donts">
+  <ul aria-label="Practices to avoid">
+    <li>ui, api, faq, pdf, ok</li>
+    <li>U.I., A.P.I., F.A.Q., P.D.F.</li>
+    <li>The Api documentation is available online.</li>
+  </ul>
+</div>
+</div>
+
+## Capitalization exceptions
+
+"OK" appears in all caps.
+
+<div className="dos-and-donts">
+<div className="dos">
+  <ul aria-label="Recommended practices">
+    <li>Select OK to start.</li>
+  </ul>
+</div>
+<div className="donts">
+  <ul aria-label="Practices to avoid">
+    <li>Select Ok to start.</li>
+  </ul>
+</div>
+</div>
+
+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.
+
+<div className="dos-and-donts">
+<div className="dos">
+  <ul aria-label="Recommended practices">
+    <li>Go to Settings</li>
+    <li>Allocate users in User management</li>
+  </ul>
+</div>
+<div className="donts">
+  <ul aria-label="Practices to avoid">
+    <li>Open settings</li>
+    <li>Allocate users in user management</li>
+    <li>Allocate users in User Management</li>
+  </ul>
+</div>
+</div>
+
+Use periods for Latin abbreviations.
+
+<div className="dos-and-donts">
+<div className="dos">
+  <ul aria-label="Recommended practices">
+    <li>e.g. / i.e. / etc. / et al. / vs.</li>
+  </ul>
+</div>
+<div className="donts">
+  <ul aria-label="Practices to avoid">
+    <li>eg / ie / etc / ET AL / VS</li>
+  </ul>
+</div>
+</div>
+
+Don't use periods for geographic abbreviations. Capitalize all country codes.
+
+<div className="dos-and-donts">
+<div className="dos">
+  <ul aria-label="Recommended practices">
+    <li>US</li>
+    <li>GB</li>
+  </ul>
+</div>
+<div className="donts">
+  <ul aria-label="Practices to avoid">
+    <li>U.S.</li>
+    <li>Gb</li>
+  </ul>
+</div>
+</div>
+
+## Lists and bullet points
+
+Capitalize the first word of each list item. Use sentence case throughout. For punctuation in lists, see period/full stop [LINK].
+
+<div className="dos-and-donts">
+<div className="dos">
+  <ul aria-label="Recommended practices">
+    <li>Configure the database connection.</li>
+    <li>Import user data from CSV.</li>
+    <li>Set up authentication.</li>
+    <li>Generate reports in PDF format.</li>
+  </ul>
+</div>
+<div className="donts">
+  <ul aria-label="Practices to avoid">
+    <li>configure the database connection.</li>
+    <li>Import User Data From CSV.</li>
+    <li>set up authentication.</li>
+    <li>Generate reports in pdf format.</li>
+  </ul>
+</div>
+</div>
+
+## Hyphenated words
+
+Capitalize only the first word of a hyphenated compound unless the second part is a proper noun.
+
+<div className="dos-and-donts">
+<div className="dos">
+  <ul aria-label="Recommended practices">
+    <li>Self-service portal</li>
+    <li>Cross-platform compatibility</li>
+    <li>Real-time monitoring</li>
+    <li>Hewlett-Packard</li>
+  </ul>
+</div>
+<div className="donts">
+  <ul aria-label="Practices to avoid">
+    <li>Self-Service Portal</li>
+    <li>Cross-Platform Compatibility</li>
+    <li>Real-Time Monitoring</li>
+    <li>Hewlett-packard</li>
+  </ul>
+</div>
+</div>
+
+## Special cases
+
+Use lowercase for file extensions. Use the original case for file names and paths.
+
+<div className="dos-and-donts">
+<div className="dos">
+  <ul aria-label="Recommended practices">
+    <li>config.json / setup.exe / README.md</li>
+    <li>Open the config.json file.</li>
+    <li>Navigate to /usr/local/bin.</li>
+  </ul>
+</div>
+<div className="donts">
+  <ul aria-label="Practices to avoid">
+    <li>config.JSON / setup.EXE / readme.MD</li>
+    <li>Open the Config.JSON file.</li>
+    <li>Navigate to /Usr/Local/Bin.</li>
+  </ul>
+</div>
+</div>
+
+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):
+
+<div className="dos-and-donts">
+<div className="dos">
+  <ul aria-label="Recommended practices">
+    <li><code>firstName</code>, <code>getUserData()</code>, <code>isValid</code></li>
+  </ul>
+</div>
+<div className="donts">
+  <ul aria-label="Practices to avoid">
+    <li><code>FirstName</code>, <code>GetUserData()</code>, <code>IsValid</code></li>
+  </ul>
+</div>
+</div>
+
+dash-case (URLs, file names, CSS classes):
+
+<div className="dos-and-donts">
+<div className="dos">
+  <ul aria-label="Recommended practices">
+    <li><code>user-profile.html</code>, <code>main-content</code>, <code>/api/user-settings</code></li>
+  </ul>
+</div>
+<div className="donts">
+  <ul aria-label="Practices to avoid">
+    <li><code>userProfile.html</code>, <code>mainContent</code>, <code>/api/userSettings</code></li>
+  </ul>
+</div>
+</div>
+
+## Related
+
+- [Voice and tone](basics.md#tone-and-voice)
+- [UI terminology](menu-functions-and-ui-labels/ui-terminology.md)
+- [Punctuation](punctuation.md)