[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/README.md b/docs/README.md
index 3e34f58..9c891c5 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -16,16 +16,18 @@
 ## Document Index
 
 ### Design Documents
+
 *   See the shared [Design Documents](https://drive.google.com/drive/folders/1JbUthATfybvMQR3yAHC4J0P7n6oftYNq) folder in the Chromium drive.
 
 ### General Development
+
 *   [Get the Code](get_the_code.md)
+*   [UX Style Guide](./styleguide/ux/README.md)
 *   [Contributing Changes](contributing_changes.md)
 *   [Chrome DevTools Design Review Guidelines](design_guidelines.md)
 *   [Release Management](release_management.md)
 *   [Dependencies](dependencies.md)
 *   [Localization](l10n.md)
-*   [Material 3 in DevTools](material3_guidelines.md)
 *   [V8 debugger support checklist for new language features](https://goo.gle/v8-checklist)
 *   [Chrome DevTools Protocol](devtools-protocol.md)
 *   [Visual logging in DevTools](visual_logging.md)
@@ -34,15 +36,18 @@
 *   [How to add experiments in DevTools frontend](add_experiments.md)
 
 ### Testing
+
 *   [Testing Chromium DevTools](testing.md)
 *   [E2E test guide](../test/e2e/README.md)
 *   [Unit test guide](unit_testing.md)
 
 ### Architectural Documentation
+
 *   [Architecture of DevTools](architecture_of_devtools.md)
 *   [Resource management in DevTools](resource_management.md)
 
 ### Chromium
+
 *   [Chromium Docs](https://chromium.googlesource.com/chromium/src/+/master/docs/README.md)
 *   [V8 Documention](https://v8.dev/docs)
 
diff --git a/docs/styleguide/ux/README.md b/docs/styleguide/ux/README.md
new file mode 100644
index 0000000..b3a4004
--- /dev/null
+++ b/docs/styleguide/ux/README.md
@@ -0,0 +1,13 @@
+# Chromium DevTools UX Style Guide
+
+These guidelines cover the best practices for extending Chromium DevTools'
+user interface.
+
+## Table of contents
+
+1. [How to organize UI](organizing.md)
+1. [How to style UI](styling.md)
+1. [How to write UI text](writing.md)
+1. [Glossary](glossary.md)
+
+Back to the [Chromium DevTools Documentation](../../README.md).
diff --git a/docs/styleguide/ux/glossary.md b/docs/styleguide/ux/glossary.md
new file mode 100644
index 0000000..306b7b3
--- /dev/null
+++ b/docs/styleguide/ux/glossary.md
@@ -0,0 +1,130 @@
+# Glossary
+
+To stop mixing terms for UI elements across DevTools UI, its docs, and code, familiarize yourself with the terms in this glossary.
+
+[TOC]
+
+## Panel
+
+A top-level tab in the DevTools window, including tabs from the **Drawer**
+because you can [move them to the top](https://developer.chrome.com/docs/devtools/customize#reorder).
+
+In other words, a panel is a fairly complex arrangement of information and
+control elements put together on the basis of common sense.
+
+![Panels in the main DevTools UI](./images/glossary-panels.png)
+
+Despite the fact that it's also a tab, the term "panel" has been in use for
+ages and all users are familiar with it. At the time of writing, DevTools
+has 32 panels.
+
+*** aside
+Example: **Elements**, **Console**, **Network**, and **Sources** panels.
+***
+
+## Tab
+
+*Inside a panel*, one of the labeled "bookmarks" in a set. Opens a single
+respective "page" (view) when you "pull" it.
+
+![Explanatory picture for labeled bookmarks](./images/glossary-labeled-bookmarks.jpg)
+
+In other words, a single-select switch between several distinct UI parts.
+Can be arranged:
+
+- Horizontally, like **Styles** ... **Properties** in **Elements**
+- Vertically, like **Preferences** ... **Shortcuts** in **Settings**
+
+*** aside
+Examples: **Styles**, **Computed**, and **Properties** tabs inside the
+**Elements** panel, or **Page**, **Workspace**, and **Snippets** tabs
+inside the sidebar of the **Sources** panel.
+***
+
+## Section
+
+A set of UI elements inside a panel and/or tab that is put together on the
+basis of common sense. Use this term when other terms don't seem to apply.
+
+*** aside
+Example: **Watch**, **Breakpoints**, and other sections in the **Sources** >
+**Debugger** sidebar.
+***
+
+## Datagrid, table
+
+A spreadsheet-like tabular view of data with rows and columns.
+
+*** aside
+Example: The request table in the **Network** panel.
+***
+
+## Dialog [window]
+
+A fairly small window that pops up over DevTools, communicates information,
+and prompts for a response.
+
+*** aside
+Example: **Do you trust this code?** dialog in **Sources** > **Editor**.
+***
+
+## Sidebar
+
+A set of UI elements, typically to the right or left side of a panel.
+Sometimes can be closed or collapsed. Spelled without a space between
+"side" and "bar".
+
+*** aside
+Example: **Navigator** and **Debugger** sidebars in **Sources**.
+***
+
+## Action bar
+
+A bar with control elements, such as buttons, filters, checkboxes, and menus.
+Typically located at the top.
+
+*** aside
+Example: Action bar at the top of the **Console**.
+***
+
+## Status bar
+
+A bar with information and statistics, non-actionable. Typically located at
+the bottom.
+
+*** aside
+Example: Status bar at the bottom of the **Network** panel.
+***
+
+## Navigation tree
+A hierarchical tree-like structure that can have multiple levels of nesting.
+
+*** aside
+Example: File tree in the **Sources** > **Page** tab.
+***
+
+## Drop-down menu
+A list of options that appears when you click the menu element.
+Can have multi-select.
+
+*** aside
+Example: **Network** > **Throttling**.
+***
+
+## Context menu
+
+A context-sensitive list of actions shown when you right-click an element.
+
+## Tooltip
+
+A small pop-up window with additional information that appears on hover.
+Can have rich formatting.
+
+## Controls
+
+Graphical control elements, such as buttons, radio buttons, checkboxes, toggle
+switches, sliders, scroll bars, text boxes, links, and others.
+
+## Pane [DEPRECATED]
+
+Deprecated. A duplicative and confusing term. Don't use.
diff --git a/docs/styleguide/ux/images/glossary-labeled-bookmarks.jpg b/docs/styleguide/ux/images/glossary-labeled-bookmarks.jpg
new file mode 100644
index 0000000..df47634
--- /dev/null
+++ b/docs/styleguide/ux/images/glossary-labeled-bookmarks.jpg
Binary files differ
diff --git a/docs/styleguide/ux/images/glossary-panels.png b/docs/styleguide/ux/images/glossary-panels.png
new file mode 100644
index 0000000..82253c5
--- /dev/null
+++ b/docs/styleguide/ux/images/glossary-panels.png
Binary files differ
diff --git a/docs/styleguide/ux/navbar.md b/docs/styleguide/ux/navbar.md
new file mode 100644
index 0000000..7dd71ba
--- /dev/null
+++ b/docs/styleguide/ux/navbar.md
@@ -0,0 +1,6 @@
+# Chromium DevTools UX Style Guide
+
+[logo]: https://github.com/ChromeDevTools/devtools-logo/raw/master/logos/png/devtools-circle-48.png
+[home]: README.md
+
+* [Chromium DevTools UX Style Guide][home]
diff --git a/docs/styleguide/ux/organizing.md b/docs/styleguide/ux/organizing.md
new file mode 100644
index 0000000..69efcb5
--- /dev/null
+++ b/docs/styleguide/ux/organizing.md
@@ -0,0 +1,9 @@
+# How to organize UI
+
+[TOC]
+
+## Panels and tabs
+
+## Widgets and views
+
+## Actions
diff --git a/docs/material3_guidelines.md b/docs/styleguide/ux/styling.md
similarity index 79%
rename from docs/material3_guidelines.md
rename to docs/styleguide/ux/styling.md
index 11488ad..baac902 100644
--- a/docs/material3_guidelines.md
+++ b/docs/styleguide/ux/styling.md
@@ -1,8 +1,8 @@
-# Material 3 for DevTools
+# How to style UI
 
-## Colors
+[TOC]
 
-### Backgrounds
+## Background colors
 
 All backgrounds should be either a surface or a container
 - default toolbar color: `--sys-color-cdt-base-container`
@@ -16,12 +16,18 @@
 
 States:
 
-- hovered: `--sys-color-state-hover-on-subtle` (see Troubleshooting > 1 for details)
+- hovered: `--sys-color-state-hover-on-subtle`
 - selected: `--sys-color-tonal-container`
 - focus-visible: `--sys-color-state-focus-highlight`
 - text selection over focus: `--sys-color-state-focus-select`
 
-### Text
+*** aside
+**NOTE:** For hover/focus colors for elements which background color is other than `--sys-color-cdt-base-container`
+    or in case you need an opaque hover color use [state layer technique](https://carbon.googleplex.com/google-material-3/pages/interaction-states/state-layers).
+    See [example CL](http://crrev.com/c/5003859)
+***
+
+## Text colors
 
 Text should generally use on-surface, on-container
 - regular (old text-primary): `--sys-color-on-surface`
@@ -33,11 +39,11 @@
 - `--sys-color-on-surface-error`
 - `--sys-color-on-tonal-container`
 
-### Syntax highlighting
+## Syntax highlighting
 
-Syntax highlighting should use token-something colors defined [here](crsrc.org/c/third_party/devtools-frontend/src/front_end/ui/legacy/themeColors.css;l=355)
+Syntax highlighting should use token-something colors defined [here](http://crsrc.org/c/third_party/devtools-frontend/src/front_end/ui/legacy/themeColors.css;l=355)
 
-### Icons
+## Icon colors
 
 Regular (dark grey) icons should also use on-something colors
 - default: `--sys-color-on-surface-subtle`
@@ -47,13 +53,6 @@
 For colored icons, please use icon application color tokens
 In case you need to add a new icon application color token, reference `--sys-color-something-bright`
 
-### Other elements
+## Other elements
 
 In case you can’t reuse a component and need to add some new UI element, please follow the [spec](https://www.figma.com/file/5xWeeSmVQTd4yW3s6aFJ1f/CDDS-UX%2FEng-Spec-(NO-LONGER-UPDATED)?node-id=35%3A2599&mode=dev)
-
-### Troubleshooting
-
-1. For hover/focus colors for elements which background color is other than `--sys-color-cdt-base-container`
-    or in case you need an opaque hover color use [state layer technique](https://carbon.googleplex.com/google-material-3/pages/interaction-states/state-layers).
-    See [example CL](crrev.com/c/5003859)
-
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))
+