[docs] Initial skeleton for the UX Style Guide.
This CL adds an initial skeleton for the UX Style Guide and also
merges the
1. go/chrome-devtools/ux-writing and
2. go/chrome-devtools/ui-glossary
documentation sets into this already, as well as moving and slightly
adjusting the Material 3 styling documentation.
Bug: 354102605
Change-Id: Ida1e5e47038fac421e665eac9785bdc1fe04d6de
Reviewed-on: https://chromium-review.googlesource.com/c/devtools/devtools-frontend/+/5725533
Commit-Queue: Kim-Anh Tran <[email protected]>
Commit-Queue: Benedikt Meurer <[email protected]>
Reviewed-by: Kim-Anh Tran <[email protected]>
Auto-Submit: Benedikt Meurer <[email protected]>
diff --git a/docs/styleguide/ux/writing.md b/docs/styleguide/ux/writing.md
new file mode 100644
index 0000000..812ac19
--- /dev/null
+++ b/docs/styleguide/ux/writing.md
@@ -0,0 +1,120 @@
+# How to write UI text
+
+[TOC]
+
+## Checklist
+
+For every CL that adds or changes UI texts in the Chrome DevTools front-end, use
+this checklist to make sure that the new or changed strings meet the basic
+requirements for good UX writing.
+
+### General
+
+* Give the right info at the right time and place
+* Don't write more than 1 sentence but if you do, break up text into sections, lists, tooltips, and <u>Learn more</u> links
+* Be friendly but not ridiculous
+ * DO: `This API lets you collect data about what your users like.`
+ * DON'T: `Dude! This API is totally awesome!`
+ * DON'T: `This API may enable the acquisition of information pertaining to user preferences.`
+
+### Patterns
+
+* Follow the
+ [F pattern](https://m3.material.io/foundations/content-design/style-guide/ux-writing-best-practices#3a833840-43db-4f6e-8133-c4665c17d176)
+* One sentence, one idea
+* "To get what you want, do this"
+ * DO: `To save changes, drop a folder here`
+ * DON'T: `Drop in a folder to add to Workspace (what's a Workspace?)`
+* "Do this to recover"
+ * DO: `Shorten filename to 64 characters or less`
+ * DON'T: `Invalid filename`
+
+### Mechanics
+
+* Say “you”
+* [Look up](https://translate.google.com) short synonyms
+ * DO: `Keep, more, stop, get, send, add, fit, …`
+ * DON'T: `Preserve, additional, prevent, receive, submit, create, …`
+* Cut, cut, cut
+ * DON'T: `Please, sorry, very, strongly, seamless, awesome, there is, there are, fast, quick, …`
+* Use active voice
+ * DO: `DevTools loaded source maps`
+ * DON'T: `Source maps were loaded by DevTools`
+* Use [contractions](https://developers.google.com/style/contractions) but avoid [Latin abbreviations](https://m3.material.io/foundations/content-design/style-guide/ux-writing-best-practices#98d02949-1933-49df-b136-f7b72620b950)
+ * DO: `Can’t, don’t, isn’t, for example, that is, and more`
+ * DON'T: `Cannot, do not, is not, e.g., i.e., etc.`
+* Use simple and common terms
+ * DO: `Website, page, extension, function`
+ * DON'T: `Debug target, debuggee, content script, call frame`
+
+### Cosmetics
+
+* Use sentence-case, not Title-Case (see [Capitalization guidelines](#capitalization-guidelines) below).
+ * DO: `Periodic background sync`
+ * DON'T: `Periodic Background Sync`
+* Punctuate consistently
+ * Use serial comma: A, B, and C
+ * Skip periods in case of a single sentence
+* Don't spell out numbers
+ * DO: `1, 2, 3, …`
+ * DON'T: `One, two, three, …`
+* Use just 2 types of links: <u>Learn more</u> and the
+ [GM3 `Help` icon](https://fonts.corp.google.com/icons?selected=Google+Symbols:help).
+
+
+## Capitalization guidelines
+
+### Capitalize product names
+
+Capitalize [product names](https://developers.google.com/style/product-names#capitalize),
+web API names, but not [feature names](https://developers.google.com/style/product-names#feature-names).
+
+* DO: `Chrome DevTools (product) lets you debug Background Fetch API (web API) by logging background fetch (feature) events.`
+* DON'T: `Chrome devtools lets you debug background fetch API by logging Background Fetch events.`
+
+### Use sentence case
+
+Use sentence case in [UI element names](https://m3.material.io/foundations/content-design/style-guide/ux-writing-best-practices#fc5c2a78-f4bf-4d42-bdac-42ff80391129) as well as [titles and headings in text](https://developers.google.com/style/capitalization#capitalization-in-titles-and-headings).
+
+That is, capitalize only the first word in the title, the first word in a
+subheading after a colon, and any proper nouns or other terms that are
+always capitalized a certain way.
+
+*** aside
+Examples: **Network request blocking**, **Blocked response cookies**
+***
+
+### Spell UI elements in text
+
+When mentioning [UI elements in text](https://developers.google.com/style/ui-elements#formatting),
+spell their names in bold and exactly as they are spelled, including
+capitalization, which should be in sentence case.
+
+*** aside
+Example: Open the **Network request blocking** panel.
+***
+
+If an element doesn't have a
+name however, <em>don't</em> capitalize its term and <em>don't</em> spell it in
+bold.
+
+*** aside
+Example: A filter bar at the top of the **Network** panel, not ~~the **Filter** bar~~.
+***
+
+*** note
+**Tip:** You can "stack" navigation paths in text regardless of element type.
+For example:
+
+In **Settings** > **Preferences** > **Appearance** > **Panel layout**,
+select `auto`.
+
+That was [Panel] > [Tab] > [Section] > [Drop-down menu].
+***
+
+## Resources
+
+1. How to write UI texts
+ ([slides](https://docs.google.com/presentation/d/1AfsX0JaMd1iBNH1WL2dMswXLuhGSU5j2cyAEHkJpoNA?resourcekey=0-cfKK72Q_tV8-uakhzuVx-g),
+ [recording](https://drive.google.com/file/d/19wOnbZHvXhH-tQLuE0M2B9fQMjosLC9O?resourcekey=0-FBrvUvnWMq0Wa98vkea9-A))
+
