diff --git a/docs/README.md b/docs/README.md index 3e34f58708..9c891c5535 100644 --- a/docs/README.md +++ b/docs/README.md @@ -16,16 +16,18 @@ below.** ## 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 @@ below.** * [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 0000000000..b3a4004035 --- /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 0000000000..306b7b3c7d --- /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 0000000000..df47634c76 Binary files /dev/null and b/docs/styleguide/ux/images/glossary-labeled-bookmarks.jpg differ diff --git a/docs/styleguide/ux/images/glossary-panels.png b/docs/styleguide/ux/images/glossary-panels.png new file mode 100644 index 0000000000..82253c5837 Binary files /dev/null and b/docs/styleguide/ux/images/glossary-panels.png differ diff --git a/docs/styleguide/ux/navbar.md b/docs/styleguide/ux/navbar.md new file mode 100644 index 0000000000..7dd71ba5fd --- /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 0000000000..69efcb572c --- /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 80% rename from docs/material3_guidelines.md rename to docs/styleguide/ux/styling.md index 11488ad101..baac902b29 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 @@ All backgrounds should be either a surface or a container 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 @@ For warnings, errors, text on selected/focused UI elements: - `--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 @@ Regular (dark grey) icons should also use on-something colors 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 0000000000..812ac198d6 --- /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 Learn more 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: Learn more 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, don't capitalize its term and don't 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)) +