[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.
+
+
+
+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.
+
+
+
+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))
+
