Adding upstream version 1:115.7.0.upstream/1%115.7.0upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

155 files changed, 2438 insertions, 0 deletions

diff --git a/devtools/docs/user/page_inspector/how_to/debug_scrollable_overflow/index.rst b/devtools/docs/user/page_inspector/how_to/debug_scrollable_overflow/index.rst
new file mode 100644
index 0000000000..795e8bc3ad
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/debug_scrollable_overflow/index.rst
@@ -0,0 +1,24 @@
+=========================
+Debug scrollable overflow
+=========================
+
+A `scroll container <https://developer.mozilla.org/en-US/docs/Glossary/Scroll_container>`_ is created by applying `overflow: scroll <https://developer.mozilla.org/en-US/docs/Web/CSS/overflow>`_ to a container, or `overflow: auto <https://developer.mozilla.org/en-US/docs/Web/CSS/overflow>`_ when there is enough content to cause overflow. The Firefox DevTools make it easy to discover both scrollable elements and any elements that are causing overflow.
+
+
+In the :ref:`HTML Pane <page_inspector_ui_tour_html_pane>`, ascrollable element has the ``scroll`` badge next to it, as shown in the following image:
+
+.. image:: scroll_hover.png
+  :alt: HTML Pane Scroll badge
+  :class: center
+
+You can toggle the ``scroll`` badge to highlight elements causing an overflow, expanding nodes as needed to make the nodes visible:
+
+.. image:: scroll_badge_pressed.png
+  :alt: Scroll badge toggled on 1
+  :class: center
+
+You will also see an ``overflow`` badge next to the node causing the overflow.
+
+.. image:: overflow_badge.png
+  :alt: HTML Pane: Overflow badge
+  :class: center
diff --git a/devtools/docs/user/page_inspector/how_to/debug_scrollable_overflow/overflow_badge.png b/devtools/docs/user/page_inspector/how_to/debug_scrollable_overflow/overflow_badge.png
new file mode 100644
index 0000000000..49f11b96c0
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/debug_scrollable_overflow/overflow_badge.png
diff --git a/devtools/docs/user/page_inspector/how_to/debug_scrollable_overflow/scroll_badge_pressed.png b/devtools/docs/user/page_inspector/how_to/debug_scrollable_overflow/scroll_badge_pressed.png
new file mode 100644
index 0000000000..f6071b8c2d
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/debug_scrollable_overflow/scroll_badge_pressed.png
diff --git a/devtools/docs/user/page_inspector/how_to/debug_scrollable_overflow/scroll_hover.png b/devtools/docs/user/page_inspector/how_to/debug_scrollable_overflow/scroll_hover.png
new file mode 100644
index 0000000000..7eba64c6fe
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/debug_scrollable_overflow/scroll_hover.png
diff --git a/devtools/docs/user/page_inspector/how_to/edit_css_filters/click_to_edit_filter.png b/devtools/docs/user/page_inspector/how_to/edit_css_filters/click_to_edit_filter.png
new file mode 100644
index 0000000000..f89427ef01
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/edit_css_filters/click_to_edit_filter.png
diff --git a/devtools/docs/user/page_inspector/how_to/edit_css_filters/css_filter_edit.png b/devtools/docs/user/page_inspector/how_to/edit_css_filters/css_filter_edit.png
new file mode 100644
index 0000000000..9eeb63b57a
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/edit_css_filters/css_filter_edit.png
diff --git a/devtools/docs/user/page_inspector/how_to/edit_css_filters/edit_filter_settings.png b/devtools/docs/user/page_inspector/how_to/edit_css_filters/edit_filter_settings.png
new file mode 100644
index 0000000000..c93f688af7
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/edit_css_filters/edit_filter_settings.png
diff --git a/devtools/docs/user/page_inspector/how_to/edit_css_filters/filter_presets.png b/devtools/docs/user/page_inspector/how_to/edit_css_filters/filter_presets.png
new file mode 100644
index 0000000000..a3edb85c50
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/edit_css_filters/filter_presets.png
diff --git a/devtools/docs/user/page_inspector/how_to/edit_css_filters/index.rst b/devtools/docs/user/page_inspector/how_to/edit_css_filters/index.rst
new file mode 100644
index 0000000000..1cf3e9e4bd
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/edit_css_filters/index.rst
@@ -0,0 +1,36 @@
+================
+Edit CSS filters
+================
+
+`CSS filter <https://developer.mozilla.org/en-US/docs/Web/CSS/filter>`_ properties in the :ref:`Rules view <page_inspector_ui_tour_rules_view>` have a circular gray and white swatch next to them:
+
+.. image:: click_to_edit_filter.png
+  :class: border
+
+Clicking the swatch opens a filter editor:
+
+.. image:: css_filter_edit.png
+  :class: center
+
+The filter editor lists each of the effects performed by that filter on a separate line. You can edit these lines, remove them individually, or drag the effects to change the order in which they are applied.
+
+You can also add new effects by selecting an effect from the dropdown list at the bottom of the dialog. Once you have selected the effect you want to add, click the plus sign (+) to the right of the dropdown list.
+
+.. image:: edit_filter_settings.png
+  :class: center
+
+Once you have added an effect, enter the settings you want and then press :kbd:`Enter` to update the effect. The change will be apparent as soon as you press :kbd:`Enter`.
+
+Saving filter presets
+*********************
+
+From Firefox 42 onwards, you can also add filters to a list of presets. The list of presets will be preserved between browser sessions, making it easy to apply the settings in the future. You can save the current filter to the preset list:
+
+
+1. Click to edit the filter, display the preset list by clicking the icon as shown below.
+2. Type a name for your preset, and then click the plus sign to add it to the list of presets.
+
+.. image:: filter_presets.png
+  :class: center
+
+You can then apply saved filters to new elements. To apply one of your saved presets, click its name in the list.
diff --git a/devtools/docs/user/page_inspector/how_to/edit_css_shapes/circle.png b/devtools/docs/user/page_inspector/how_to/edit_css_shapes/circle.png
new file mode 100644
index 0000000000..4e8dc9ec3f
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/edit_css_shapes/circle.png
diff --git a/devtools/docs/user/page_inspector/how_to/edit_css_shapes/clipped-margin-box.png b/devtools/docs/user/page_inspector/how_to/edit_css_shapes/clipped-margin-box.png
new file mode 100644
index 0000000000..1ca15471c7
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/edit_css_shapes/clipped-margin-box.png
diff --git a/devtools/docs/user/page_inspector/how_to/edit_css_shapes/ellipse.png b/devtools/docs/user/page_inspector/how_to/edit_css_shapes/ellipse.png
new file mode 100644
index 0000000000..473d7049fe
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/edit_css_shapes/ellipse.png
diff --git a/devtools/docs/user/page_inspector/how_to/edit_css_shapes/enable-shapes-editor.png b/devtools/docs/user/page_inspector/how_to/edit_css_shapes/enable-shapes-editor.png
new file mode 100644
index 0000000000..d0869701e9
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/edit_css_shapes/enable-shapes-editor.png
diff --git a/devtools/docs/user/page_inspector/how_to/edit_css_shapes/index.rst b/devtools/docs/user/page_inspector/how_to/edit_css_shapes/index.rst
new file mode 100644
index 0000000000..d8eadf0c2c
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/edit_css_shapes/index.rst
@@ -0,0 +1,104 @@
+=======================
+Edit Shape Paths in CSS
+=======================
+
+The Shape Path Editor is a tool that helps you see and edit shapes created using `clip-path <https://developer.mozilla.org/en-US/docs/Web/CSS/clip-path>`_ and also the CSS `shape-outside <https://developer.mozilla.org/en-US/docs/Web/CSS/shape-outside>`_ property and `<basic-shape> <https://developer.mozilla.org/en-US/docs/Web/CSS/basic-shape>`_ values. This guide walks you through all of the available options.
+
+
+Activate / deactivate the Shape Path Editor
+*******************************************
+
+The Shape Path Editor is accessed via the CSS Rules Panel, which can be opened as described in the guide to :doc:`Opening the Inspector <../open_the_inspector/index>`. Once you have selected your element, you should see the shape icon alongside any valid value, e.g. one for ``shape-outside``.
+
+.. image:: enable-shapes-editor.png
+  :class: border
+
+
+Clicking the icon will cause the Editor to highlight the shape.
+
+.. image:: circle.png
+  :class: center
+
+
+To deactivate the Shape Path Editor click on the icon again, or select another element or a different editor. Note that the Shape Path Editor does not persist between page reloads — if you reload your page you will need to select the element again.
+
+
+Understanding the lines drawn by the editor
+*******************************************
+
+Once you have selected a shape on your page, the Shape Path Editor will draw lines to help you understand the path that is being created.
+
+
+- **A solid line** shows the outline of the shape that is wrapping the text. This is your shape. If the shape is clipped by the margin box then the margin box will make up part of this line.
+- **A dashed line** demonstrates the outline of the shape which extends past the margin box reference; this is the area that will be clipped by the margin box. To understand the margin box, and other boxes used by CSS Shapes see our guide to `Shapes from box values <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Shapes/From_box_values>`_.
+
+.. image:: clipped-margin-box.png
+  :class: center
+
+
+Editing Basic Shapes
+********************
+
+The options given to you by the tool will differ depending on the type of basic shape that you are editing. Options can be accessed by activating the Shape Path Editor with a regular click on the icon, and you can use the context menu (:kbd:`Ctrl`/:kbd:`Cmd` + click) to access additional functionality.
+
+circle()
+--------
+
+If the value of ``shape-outside`` is ``circle()``, you are creating a `circle basic shape <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Shapes/Basic_Shapes#circle()>`_. Clicking on the shapes icon next to the value of ``circle()`` will highlight the shape, and also give you the option to resize the circle or move its center. If you move or resize the circle past the margin box, the edges become clipped by it.
+
+.. image:: clipped-margin-box.png
+  :class: center
+
+
+In the Rules Panel you can see the values for ``circle()`` change as you edit the shape. You can then copy these values back into your stylesheet to create the new, tweaked shape path.
+
+
+ellipse()
+---------
+
+If the value of ``shape-outside`` is ``ellipse()`` then you are using the `ellipse basic shape <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Shapes/Basic_Shapes#ellipse()>`_. The ``ellipse()`` value works in much the same way as ``circle()`` in the Shape Path Editor. An ellipse is a squashed circle and therefore has the option to resize horizontally and vertically when you click on the shapes icon.
+
+.. image:: ellipse.png
+  :class: center
+
+
+inset()
+-------
+
+If the value of ``shape-outside`` is ``inset()`` then you are using the `inset basic shape <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Shapes/Basic_Shapes#inset()>`_, which enables the creation of offset values pulling the content in from the margin box.
+
+Each side of the rectangle can be targeted after clicking on the shapes icon to activate the Shape Path Editor, and dragging each side will update the values for the top, right, bottom, and left offset values.
+
+.. image:: inset.png
+  :class: center
+
+
+polygon()
+---------
+
+If the value of ``shape-outside`` is ``polygon()`` then you are using the `polygon basic shape <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Shapes/Basic_Shapes#polygon()>`_. This is the most complex of the basic shape values, therefore the tool gives you more options when editing these:
+
+
+- Clicking on the shapes icon will activate the Shapes Path Editor and give you the option to move any of the points of your polygon shape.
+- Double-click anywhere on a line of the shape and you will get a new point to adjust.
+- Double click on an existing point and it will be removed. *Remember that a polygon needs at least three points*.
+
+.. image:: polygon-edit.png
+  :class: center
+
+
+Moving and scaling shapes
+-------------------------
+
+There is extra functionality available on the shape highlight — if you :kbd:`Ctrl`/:kbd:`Cmd` + click on the shapes icon for your shape the highlight will change, instead providing the ability to scale and/or move it. Once again, clipping will occur if you exceed the bounds of the margin box.
+
+.. image:: scaled-circle.png
+  :class: center
+
+
+If your shape is a polygon, you also get the ability to rotate it around an axis.
+
+Browser support
+***************
+
+The Shape Path Editor currently works for shapes generated via `clip-path <https://developer.mozilla.org/en-US/docs/Web/CSS/clip-path>`_; it will also work for shapes generated via `shape-outside <https://developer.mozilla.org/en-US/docs/Web/CSS/shape-outside>`_ as of Firefox 62.
diff --git a/devtools/docs/user/page_inspector/how_to/edit_css_shapes/inset.png b/devtools/docs/user/page_inspector/how_to/edit_css_shapes/inset.png
new file mode 100644
index 0000000000..70968ea11f
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/edit_css_shapes/inset.png
diff --git a/devtools/docs/user/page_inspector/how_to/edit_css_shapes/polygon-edit.png b/devtools/docs/user/page_inspector/how_to/edit_css_shapes/polygon-edit.png
new file mode 100644
index 0000000000..90d9df8c31
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/edit_css_shapes/polygon-edit.png
diff --git a/devtools/docs/user/page_inspector/how_to/edit_css_shapes/scaled-circle.png b/devtools/docs/user/page_inspector/how_to/edit_css_shapes/scaled-circle.png
new file mode 100644
index 0000000000..faa9935fd7
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/edit_css_shapes/scaled-circle.png
diff --git a/devtools/docs/user/page_inspector/how_to/edit_fonts/all-fonts-on-page_new63.png b/devtools/docs/user/page_inspector/how_to/edit_fonts/all-fonts-on-page_new63.png
new file mode 100644
index 0000000000..8896ec40c7
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/edit_fonts/all-fonts-on-page_new63.png
diff --git a/devtools/docs/user/page_inspector/how_to/edit_fonts/change_font_after_cropped.png b/devtools/docs/user/page_inspector/how_to/edit_fonts/change_font_after_cropped.png
new file mode 100644
index 0000000000..b5ff4d99a0
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/edit_fonts/change_font_after_cropped.png
diff --git a/devtools/docs/user/page_inspector/how_to/edit_fonts/change_font_before_cropped.png b/devtools/docs/user/page_inspector/how_to/edit_fonts/change_font_before_cropped.png
new file mode 100644
index 0000000000..4a4437ecfc
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/edit_fonts/change_font_before_cropped.png
diff --git a/devtools/docs/user/page_inspector/how_to/edit_fonts/font-italic_cropped.png b/devtools/docs/user/page_inspector/how_to/edit_fonts/font-italic_cropped.png
new file mode 100644
index 0000000000..6d33a65246
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/edit_fonts/font-italic_cropped.png
diff --git a/devtools/docs/user/page_inspector/how_to/edit_fonts/font-size_cropped.png b/devtools/docs/user/page_inspector/how_to/edit_fonts/font-size_cropped.png
new file mode 100644
index 0000000000..eea408e6c3
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/edit_fonts/font-size_cropped.png
diff --git a/devtools/docs/user/page_inspector/how_to/edit_fonts/font-weight_cropped.png b/devtools/docs/user/page_inspector/how_to/edit_fonts/font-weight_cropped.png
new file mode 100644
index 0000000000..56510effc5
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/edit_fonts/font-weight_cropped.png
diff --git a/devtools/docs/user/page_inspector/how_to/edit_fonts/fonts-editor-closeup-63-cropped.png b/devtools/docs/user/page_inspector/how_to/edit_fonts/fonts-editor-closeup-63-cropped.png
new file mode 100644
index 0000000000..e63bfc6f64
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/edit_fonts/fonts-editor-closeup-63-cropped.png
diff --git a/devtools/docs/user/page_inspector/how_to/edit_fonts/fonts-used.png b/devtools/docs/user/page_inspector/how_to/edit_fonts/fonts-used.png
new file mode 100644
index 0000000000..f28a2c0e9b
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/edit_fonts/fonts-used.png
diff --git a/devtools/docs/user/page_inspector/how_to/edit_fonts/fonts_62_tooltip_cropped.png b/devtools/docs/user/page_inspector/how_to/edit_fonts/fonts_62_tooltip_cropped.png
new file mode 100644
index 0000000000..176d17c10c
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/edit_fonts/fonts_62_tooltip_cropped.png
diff --git a/devtools/docs/user/page_inspector/how_to/edit_fonts/full-fonts-tab-new63.png b/devtools/docs/user/page_inspector/how_to/edit_fonts/full-fonts-tab-new63.png
new file mode 100644
index 0000000000..2f3b73b032
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/edit_fonts/full-fonts-tab-new63.png
diff --git a/devtools/docs/user/page_inspector/how_to/edit_fonts/index.rst b/devtools/docs/user/page_inspector/how_to/edit_fonts/index.rst
new file mode 100644
index 0000000000..8a08ca39fb
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/edit_fonts/index.rst
@@ -0,0 +1,257 @@
+==========
+Edit fonts
+==========
+
+
+This article provides a tour of the Font tools available in the Firefox DevTools. This tool contains several useful features for viewing and manipulating fonts applied to any document loaded in the browser including inspection of all fonts applied to the page, and precise adjustment of variable font axis values.
+
+.. note::
+
+  The updated Font tools as shown in this article are available in Firefox 63 onwards; if you are using an older version of Firefox the tools will not look or behave quite the same, but they will be similar (most notably the Font Editor will not be available).
+
+
+The Fonts tab
+*************
+
+The Fonts tab is located on the right-hand side of the :doc:`Page Inspector <../../index>` when it is docked to the bottom of the screen. When it is docked to the right or left sides of the screen, the Fonts tab appears beneath the HTML pane. To access it:
+
+
+1. :doc:`Open the Page Inspector <../open_the_inspector/index>`.
+2. Select the Fonts tab; the last of the tabs shown in the right-hand side of the CSS pane.
+
+.. image:: full-fonts-tab-new63.png
+  :class: border
+
+
+The Fonts tab has three major sections:
+
+- "Fonts used" by the currently inspected element.
+- The new Fonts Editor. In Firefox 61 and 62, this section does not exist.
+- "All fonts on page" — This section lists all of the fonts in use on the page. In Firefox 61 and 62, this area is labeled "Other fonts in page" and doesn't include the fonts mentioned in the "Fonts used" section.
+
+
+Fonts used
+**********
+
+The top section of the Font Editor shows the fonts used by the currently inspected element, grouped by font family.
+
+.. image:: fonts-used.png
+  :class: border
+
+Fonts are considered "used" when there is text content in the inspected element that has the font applied to it. Empty elements will not have any fonts used and will display the message "No fonts were found for the current element."
+
+Fonts will be included in this section for one of the following reasons:
+
+
+- They are listed in the element's ``font-family`` CSS declaration value.
+- They are applied to the element as part of the browser's default styling (Times New Roman for most browsers), and no author-defined font has been supplied.
+- They are used by a descendant of the inspected element, for example, when it is a container for other elements which have text content with fonts applied.
+- They are system fallback fonts used when nothing from the ``font-family`` CSS declaration has been applied.
+
+
+Fonts Editor
+************
+
+Firefox 63 adds the Font Editor — a new area below "Fonts used" with additional controls for editing the fonts’ characteristics.
+
+.. image:: fonts-editor-closeup-63-cropped.png
+  :class: border
+
+
+For standard (static) fonts, you will be able to change the settings listed below
+
+
+Size
+----
+
+The `font-size <https://developer.mozilla.org/en-US/docs/Web/CSS/font-size>`_ for the inspected element.
+
+.. image:: font-size_cropped.png
+  :class: border
+
+
+This can be set using ``em``, ``rem``, ``%``, ``px``, ``vh``, or ``vw`` units. You can select values using the slider or enter a numeric value directly into the text box.
+
+.. note::
+  If you want to use a different unit such as ``pt`` for ``font-size`` or ``line-height``, you can set the property value applied to the currently inspected element to use that unit via the :ref:`rules view <page_inspector_ui_tour_rules_view>`, and the font editor will automatically pick it up and make it available in the associated units dropdown menu.
+
+
+Changing the unit of measure converts the numerical value to its equivalent in the new unit, so the same computed value is maintained.
+
+Example: If ``1rem`` is equivalent to 10 pixels, when you change the unit of measurement from ``rem`` to ``px``, ``2rem`` becomes ``20px``.
+
+
+Line height
+-----------
+
+The `line-height <https://developer.mozilla.org/en-US/docs/Web/CSS/line-height>`_ of the inspected element.
+
+.. image:: line-height_cropped.png
+  :class: border
+
+
+This can be set using unitless, ``em``, *%*, or ``px`` units. You can select values using the slider or enter a numeric value directly into the text box.
+
+Changing the unit of measure changes the value relative to the ``font-size`` setting.
+
+Example: If the font is 20 pixels high and the line-height is ``1.5em``, when you change the unit of measure from ``em`` to ``px``, the value will become ``30px``.
+
+
+Weight
+------
+
+The `font-weight <https://developer.mozilla.org/en-US/docs/Web/CSS/font-weight>`_ for the inspected element.
+
+.. image:: font-weight_cropped.png
+  :alt: Font weight setting
+  :class: border
+
+
+You can select values using the slider or enter a numeric value directly into the text box. For non-variable fonts the slider ranges from 100 to 900 in increments of 100.
+
+.. note::
+  For `variable fonts <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Fonts/Variable_Fonts_Guide>`_ (see below) that define a ``wght`` variation axis, this range is custom.
+
+
+Italic
+------
+
+The `font-style <https://developer.mozilla.org/en-US/docs/Web/CSS/font-style>`_ for the inspected element.
+
+.. image:: font-italic_cropped.png
+  :class: border
+
+
+This setting toggles between ``italic`` and ``normal`` values for the ``font-style`` CSS property.
+
+.. note::
+
+  As you change settings, Firefox applies inline styles to the element to make the changes instantly visible on the page.
+
+
+All fonts on page
+*****************
+
+The remaining area, at the bottom of the Fonts tab, shows an expandable list of all of the fonts in use on the page.
+
+.. image:: all-fonts-on-page_new63.png
+  :class: border
+
+
+The list is useful because you can easily determine whether a font is a web font or a font hosted on your system.
+
+Each font listed in this section shows you:
+
+
+- The ``font-family`` identifier and full name of the font.
+- The URL to the font file in the case of web fonts not available on your system, or "System" in the case of fonts loaded from your computer (either default system fonts, or web fonts that you've also got installed on your system). You can copy the URL to the font file by clicking on the icon to the right of the URL.
+- The `@font-face <https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face>`_ descriptor that loads the font into the page, in the case of web fonts. The descriptor is expandable — when opened it shows its full syntax as defined in the stylesheet.
+- A text sample, to give you an idea of what the font looks like when rendered. The default text for the sample is "Abc" but the preview text can be edited by clicking on the input field at the top of the section and entering a new value. Once entered, all of the sample text will be set to the same custom value.
+
+
+Variable font support in Firefox Developer Tools
+************************************************
+
+Firefox 62 added support for variable fonts and Firefox 63 features support for editing the properties of variable fonts in the Font Editor.
+
+What are variable fonts?
+------------------------
+
+`Variable Fonts <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Fonts/Variable_Fonts_Guide>`_, or **OpenType Font Variations**, define a new font file format that allows the font designer to include multiple variations of a typeface inside a single font file. That means you no longer have to apply several different web fonts to a single page to represent a complete typeface for which a variable font is available, provided it includes the desired values for the different characteristics you want to vary.
+
+Variable fonts make it easy to vary font characteristics in a much more granular fashion because their allowable ranges are defined by **axes of variation** (see `Introducing the 'variation axis' <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Fonts/Variable_Fonts_Guide#introducing_the_'variation_axis'>`_ for more information). For example, `font-weight <https://developer.mozilla.org/en-US/docs/Web/CSS/font-weight>`_ can be set to any value between 1 and 1000 in variable fonts (although it is not guaranteed that a variable font will support this entire range).
+
+There are several registered axes. Although it isn't required that these axes be defined for every font, if the font designer *does* implement a registered axis, its behavior *must* follow the defined behavior.
+
+All variable font axes have a four-character axis tag. The CSS `font-variation-settings <https://developer.mozilla.org/en-US/docs/Web/CSS/font-variation-settings>`_ property uses the tag as part of the key-value pair. For example, to set `font-weight <https://developer.mozilla.org/en-US/docs/Web/CSS/font-weight>`_ using ``font-variation-settings``, you could do something like this:
+
+
+.. code-block:: css
+
+  font-variation-settings: "wght" 350;
+
+
+However, you should only use ``font-variation-settings`` as a last resort if there is no basic font property available for setting those characteristic values (e.g. custom axes).
+
+.. note::
+  Font characteristics set using ``font-variation-settings`` will always override those set using the corresponding basic font properties, e.g. ``font-weight``, no matter where they appear in the cascade.
+
+
+Here are the registered axes along with their corresponding CSS properties:
+
+
+.. list-table::
+  :widths: 40 60
+  :header-rows: 1
+
+  * - Axis Tab
+    - CSS Property
+
+  * - "wght"
+    - `font-weight <https://developer.mozilla.org/en-US/docs/Web/CSS/font-weight>`_
+
+  * - "wdth"
+    - `font-stretch <https://developer.mozilla.org/en-US/docs/Web/CSS/font-stretch>`_
+
+  * - "slnt" (slant)
+    - `font-style <https://developer.mozilla.org/en-US/docs/Web/CSS/font-style>`_: ``oblique + angle``
+
+  * - "ital"
+    - `font-style <https://developer.mozilla.org/en-US/docs/Web/CSS/font-style>`_: ``italic``
+
+  * - "opsz"
+    - `font-optical-sizing <https://developer.mozilla.org/en-US/docs/Web/CSS/font-optical-sizing>`_
+
+
+Any axis that is not on the list of registered axes is considered a custom axis. Custom axes do not have corresponding CSS font properties. Font designers can define whatever axis they want; each one needs to be given a unique four-character tag. The axis name and its range is up to the font designer.
+
+.. note::
+  Registered axis tags are identified using lower-case tags, whereas custom axes should be given upper-case tags. Note that font designers aren't forced follow this practice in any way, and some won't. The important takeaway here is that axis tags are case-sensitive.
+
+
+.. warning::
+  In order to use variable fonts, you need to make sure that your operating system is up to date. For example Linux OSes need the latest Linux Freetype version, and macOS prior to 10.13 does not support variable fonts. If your operating system is not up to date, you will not be able to use variable fonts in web pages or the Firefox Developer Tools.
+
+
+Working with Variable fonts in the Font Editor
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If the inspected element uses a variable font, the Fonts tab shows the axes that have been implemented for that particular font, providing control to alter the value of each one. This is very useful for quickly finding out what axes are available in a particular font — they can vary quite dramatically as font designers can implement basically anything they like.
+
+.. image:: v_fonts_example_cropped.png
+  :class: border
+
+
+You can adjust the axes individually or, if the font designer has included defined instances, you can select one from the "Instance" drop-down list and view the updates live on your page.
+
+Here are a couple of examples of fonts with different axes defined:
+
+.. image:: v_fonts-examples_cropped.png
+  :class: border
+
+
+In the following example, you can see that the font "Cheee Variable" includes settings for Yeast and Gravity. These are custom axes defined by the font designer.
+
+.. image:: change_font_before_cropped.png
+  :class: border
+
+
+The first image shows the font as it is used on the page with default settings. The second image shows the same font after selecting the "Hi Yeast Hi Gravity" variation.
+
+.. image:: change_font_after_cropped.png
+  :class: border
+
+
+Tips
+****
+
+Finally, here are a few tips for making effective use of the Fonts tab:
+
+
+- When using the Page Inspector's :doc:`3-pane mode <../../3-pane_mode/index>`, you can view the CSS rules for the inspected element simultaneously alongside the Fonts tab.
+- If you hover over the `font-family <https://developer.mozilla.org/en-US/docs/Web/CSS/font-family>`_ property in the Rules view, a tooltip shows a sample of the font:
+
+  .. image:: fonts_62_tooltip_cropped.png
+    :class: border
+
+- You'll also notice in the above screenshot that the font in the ``font-family`` font stack that is actually applied to the inspected element is underlined. This makes it easy to see exactly what is being applied where, when font stacks are specified.
diff --git a/devtools/docs/user/page_inspector/how_to/edit_fonts/line-height_cropped.png b/devtools/docs/user/page_inspector/how_to/edit_fonts/line-height_cropped.png
new file mode 100644
index 0000000000..21c3b25345
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/edit_fonts/line-height_cropped.png
diff --git a/devtools/docs/user/page_inspector/how_to/edit_fonts/v_fonts-examples_cropped.png b/devtools/docs/user/page_inspector/how_to/edit_fonts/v_fonts-examples_cropped.png
new file mode 100644
index 0000000000..8489e04aef
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/edit_fonts/v_fonts-examples_cropped.png
diff --git a/devtools/docs/user/page_inspector/how_to/edit_fonts/v_fonts_example_cropped.png b/devtools/docs/user/page_inspector/how_to/edit_fonts/v_fonts_example_cropped.png
new file mode 100644
index 0000000000..6c3ea01f74
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/edit_fonts/v_fonts_example_cropped.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/add_new_rule.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/add_new_rule.png
new file mode 100644
index 0000000000..85ec6e49aa
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/add_new_rule.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/color_scheme_dark.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/color_scheme_dark.png
new file mode 100644
index 0000000000..680708d33a
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/color_scheme_dark.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/color_scheme_light.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/color_scheme_light.png
new file mode 100644
index 0000000000..46da0f8872
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/color_scheme_light.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/color_scheme_null.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/color_scheme_null.png
new file mode 100644
index 0000000000..f498ddf585
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/color_scheme_null.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/compat_view.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/compat_view.png
new file mode 100644
index 0000000000..159b43fecf
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/compat_view.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/computed_css.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/computed_css.png
new file mode 100644
index 0000000000..cb58b1e39d
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/computed_css.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/computed_css_details.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/computed_css_details.png
new file mode 100644
index 0000000000..3c8d15719e
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/computed_css_details.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/edit_rule_autocomplete.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/edit_rule_autocomplete.png
new file mode 100644
index 0000000000..0b84b74c19
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/edit_rule_autocomplete.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/edit_rule_var_autocomplete.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/edit_rule_var_autocomplete.png
new file mode 100644
index 0000000000..f881a3a28e
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/edit_rule_var_autocomplete.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/editable-context-menu.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/editable-context-menu.png
new file mode 100644
index 0000000000..3fc6df7dfc
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/editable-context-menu.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/filter_rules.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/filter_rules.png
new file mode 100644
index 0000000000..9e708b77be
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/filter_rules.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/filter_rules_2.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/filter_rules_2.png
new file mode 100644
index 0000000000..d76abc6e47
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/filter_rules_2.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/filter_rules_2_strict.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/filter_rules_2_strict.png
new file mode 100644
index 0000000000..2a44bc79ce
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/filter_rules_2_strict.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/filtered_rules.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/filtered_rules.png
new file mode 100644
index 0000000000..b7f3628981
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/filtered_rules.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/firefox_compatibility_tootips.jpg b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/firefox_compatibility_tootips.jpg
new file mode 100644
index 0000000000..9aa0b05047
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/firefox_compatibility_tootips.jpg
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/hover_indicators.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/hover_indicators.png
new file mode 100644
index 0000000000..ce9f7f1ddc
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/hover_indicators.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/index.rst b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/index.rst
new file mode 100644
index 0000000000..1f0fb56c15
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/index.rst
@@ -0,0 +1,474 @@
+====================
+Examine and edit CSS
+====================
+
+You can examine and edit CSS in the Inspector's :ref:`CSS pane <page_inspector_ui_tour_rules_view>`.
+
+
+.. _page-inspector-how-to-examine-and-edit-css-examine-css-rules:
+
+Examine CSS rules
+*****************
+
+The :ref:`Rules view <page_inspector_ui_tour_rules_view>` lists all the rules that apply to the selected element, ordered from most-specific to least-specific:
+
+.. image:: rules_view_ff_87.png
+  :alt: Rules view panel as of Firefox 87
+  :class: border
+
+
+The six buttons on the right top of the rules view allow you to change the display of certain CSS and rules view features. You can:
+
+
+- :ref:`toggle pseudo-classes <page-inspector-how-to-examine-and-edit-css-viewing-common-pseudo-classes>`;
+- :ref:`toggle classes <page-inspector-how-to-examine-and-edit-css-viewing-and-changing-classes-on-an-element>`
+- add a new rule;
+- change the display based on :ref:`prefers-color-scheme media rules <page-inspector-view-media-rules-for-prefers-color-scheme>`.
+- change the display based on :ref:`print media rules <page-inspector-view-media-rules-for-print>`.
+
+.. image:: rules_view_buttons_fx_72.png
+  :alt: Toolbar buttons of the Rules view, as of Fx 72
+  :class: center
+
+
+Invalid value warnings
+----------------------
+
+A warning icon appears next to unsupported CSS properties or rules that have invalid values. This can help you understand why certain styles are not being applied. In the following example, a spelling error, "background-colour" instead of "background-color" has made the rule invalid:
+
+.. image:: invalid_property.png
+  :class: border
+
+
+Browser compat warnings
+-----------------------
+
+CSS properties have varied level of support across different browsers. From Firefox 81, compatibility tooltips may be displayed next to any CSS properties that have known compatibility issues,as shown below.
+
+.. note::
+  This feature is enabled from Firefox 81 by setting the preference ``devtools.inspector.ruleview.inline-compatibility-warning.enabled`` to ``true`` (open ``about:config`` in the URL bar to view/set Firefox preferences).
+
+
+.. image:: firefox_compatibility_tootips.jpg
+  :alt: Tooltip displayed next to CSS element. Hover to find out browsers with compatibility issues.
+  :class: center
+
+
+The tooltips, which arepopulated from the MDN `browser compatibility project <https://github.com/mdn/browser-compat-data>`_, identify the *reason* for the incompatibility (not supported, deprecated, experimental etc.), display icons for incompatible browsers, and provide a link to the associated property page for more information.
+
+
+CSS Compatibility
+-----------------
+
+In addition to compatibility tooltips, the *CSS Compatibility View* shows any CSS compatibility issues for both the selected element and for the current page (as a whole).
+
+.. image:: compat_view.png
+  :alt: Screenshot of the Compatibility view
+  :class: center
+
+
+For more information see: :ref:`Page Inspector > CSS Compatibility View <page_inspector_ui_tour_compatibility_view>`.
+
+
+Rule display
+------------
+
+It displays each rule as in a stylesheet, with a list of selectors followed by a list of ``property:value;`` declarations.
+
+.. image:: rules_pane.png
+  :class: center
+
+
+- *Highlight matched elements*: next to the selector is a target icon: click this to highlight all nodes in the page that match this selector.
+- *Overridden declaration*: declarations that are overridden by later rules are crossed out. See :ref:`overridden declarations <page-inspector-how-to-examine-and-edit-css-overridden-declarations>`.
+- *Inactive rules* (not shown): if a rule is inactive (e.g., ``padding`` on a ``:visited`` pseudo-element), it is colored gray, with an info icon that gives more information when clicked.
+- *Filter rules containing this property*: next to overridden declarations is an icon you can click to filter the rules list to show only those rules that include that property. See :ref:`overridden declarations <page-inspector-how-to-examine-and-edit-css-overridden-declarations>`.
+- *Enable/disable*: if you hover over a declaration, a checkbox appears next to it: you can use this to toggle the declaration on or off.
+- *Filename and line number*: on the right-hand side is a link to the rule. See :ref:`link to CSS file <page-inspector-how-to-examine-and-edit-css-link-to-css-file>`.
+
+
+.. |image1| image:: screen_shot_2016-12-16_at_10.51.15_am.png
+  :width: 20
+
+If the element has a `display: grid <https://developer.mozilla.org/en-US/docs/Web/CSS/display>`_ declaration, then it gets a grid icon next to it, like this: |image1|. Click that icon to display the grid overlaid on the page, including grid lines and tracks. See :doc:`Examine grid layouts <../examine_grid_layouts/index>` for more on this.
+
+To view `user-agent styles <https://developer.mozilla.org/en-US/docs/Web/CSS/Cascade>`_ (*i.e.,* browser-default CSS rules), enable "Inspector > Show Browser Styles" under the :doc:`developer tool settings <../../../settings/index>` panel. (Note that this setting is independent of the "Browser styles" checkbox in the :ref:`Computed view <page_inspector_how_to_examine_and_edit_css_examine_computed_css>`.)
+
+User-agent styles are displayed against a different background, and the link to the filename and line number contains the prefix ``(user agent)``:
+
+.. image:: user-agent_css.png
+  :class: border
+
+
+.. _page_inspector_how_to_examine_and_edit_css_element_rule:
+
+element {} rule
+---------------
+
+The ``element {}`` rule at the top of the rules list isn't actually a CSS rule. It represents the CSS properties assigned to the element via its `style <https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes#attr-style>`_ attribute.
+
+.. |image2| image:: target-icon.png
+  :width: 20
+
+This also gets the target icon: |image2|, giving you a convenient way to highlight the currently selected element in the page.
+
+
+Filtering rules
+---------------
+
+There's a box at the top of the Rules view labeled "Filter Styles":
+
+.. image:: filter_rules.png
+  :class: border
+
+As you type:
+
+- any rules which don't contain the typed string at all are hidden
+- any declarations which contain the typed string are highlighted
+
+.. image:: filtered_rules.png
+  :class: border
+
+Click the "X" at the end of the search box to remove the filter.
+
+.. note::
+  While in the Rules view, you can press :kbd:`Ctrl` / :kbd:`Cmd` + :kbd:`F` to focus the search field. Once you've typed in a filter, you can press :kbd:`Esc` to remove it again.
+
+
+.. raw:: html
+
+  <iframe width="560" height="315" src="https://www.youtube.com/embed/9w8vDIWqnAE" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+  <br/>
+  <br/>
+
+Strict search
+~~~~~~~~~~~~~
+
+By default, the search box highlights all declarations which contain any part of the string. For example, searching for "color" will highlight declarations containing `border-bottom-color <https://developer.mozilla.org/en-US/docs/Web/CSS/border-bottom-color>`_ and `background-color <https://developer.mozilla.org/en-US/docs/Web/CSS/background-color>`_ as well as just `color <https://developer.mozilla.org/en-US/docs/Web/CSS/color>`_:
+
+.. image:: filter_rules_2.png
+  :class: border
+
+If you enclose the search query in backticks, like this: `color`, the search is restricted to exact matches:
+
+.. image:: filter_rules_2_strict.png
+  :class: border
+
+
+Expanding shorthand properties
+------------------------------
+
+`Shorthand properties <https://developer.mozilla.org/en-US/docs/Web/CSS/Shorthand_properties>`_ can be expanded to display their related longhand properties by clicking the arrow besides them.
+
+
+Displaying pseudo-elements
+--------------------------
+
+The Rule view displays the following `pseudo-elements <https://developer.mozilla.org/en-US/docs/Web/CSS/Pseudo-elements>`_, if they are applied to the selected element:
+
+- ``::after``
+- ``::backdrop``
+- ``::before``
+- ``::first-letter``
+- ``::first-line``
+- ``::selection``
+- ``:-moz-color-swatch``
+- ``:-moz-number-spin-box``
+- ``:-moz-number-spin-down``
+- ``:-moz-number-spin-up``
+- ``:-moz-number-text``
+- ``:-moz-number-wrapper``
+- ``:-moz-placeholder``
+- ``:-moz-progress-bar``
+- ``:-moz-range-progress``
+- ``:-moz-range-thumb``
+- ``:-moz-range-track``
+- ``:-moz-selection``
+
+If the selected element has pseudo-elements applied to it, they are displayed before the selected element but hidden by a disclosure triangle:
+
+.. image:: pseudo-elements.png
+  :class: border
+
+
+Clicking the triangle displays them:
+
+.. image:: pseudo-elements_displayed.png
+  :class: border
+
+
+.. _page-inspector-how-to-examine-and-edit-css-viewing-common-pseudo-classes:
+
+Viewing common pseudo-classes
+-----------------------------
+
+There's a button to the right of the filter box:
+
+.. image:: show_pseudo_classes.png
+  :class: border
+
+
+Click the button to see checkboxes that you can use to enable the `:hover <https://developer.mozilla.org/en-US/docs/Web/CSS/:hover>`_, `:active <https://developer.mozilla.org/en-US/docs/Web/CSS/:active>`_ and `:focus <https://developer.mozilla.org/en-US/docs/Web/CSS/:focus>`_, `:focus-within <https://developer.mozilla.org/en-US/docs/Web/CSS/:focus-within>`_, `:focus-visible <https://developer.mozilla.org/en-US/docs/Web/CSS/:focus-visible>`_, `:visited <https://developer.mozilla.org/en-US/docs/Web/CSS/:visited>`_, and `:target <https://developer.mozilla.org/en-US/docs/Web/CSS/:target>`_ pseudo-classes for the selected element:
+
+
+.. image:: show_pseudo_classes_hover.png
+  :class: border
+
+This feature can also be accessed from the :ref:`popup menu in the HTML view <page-inspector-how-to-element-popup-context-menu>`
+
+If you enable one of these pseudo-classes for a node, an orange dot appears in the markup view next to all nodes to which the pseudo-class has been applied. In addition, the information that appears on the page itself show you what pseudo-class you are examining. For example:
+
+.. image:: hover_indicators.png
+  :class: border
+
+
+.. _page-inspector-how-to-examine-and-edit-css-viewing-and-changing-classes-on-an-element:
+
+Viewing and changing classes on an element
+------------------------------------------
+
+With an element selected in the HTML pane, you can click the **.cls** button in the Rules pane toolbar, to display the classes defined on that element.
+
+
+- You can clear the checkbox for a particular class name, to see how the element would appear without that class applied to it.
+- You can add a class to the element by typing a name in the *Add new class* field below the Rules toolbar. From Firefox 81, autocompletions based on existing classes are suggested as you type.
+
+
+.. _page-inspector-how-to-examine-and-edit-css-link-to-css-file:
+
+Link to CSS file
+----------------
+
+At the top right of each rule, the source filename and line number is displayed as a link: clicking it opens the file in the :doc:`Style Editor <../../../style_editor/index>`.
+
+You can copy the location of the source file: right-click the link and select "Copy Location".
+
+The Inspector understands CSS source maps. That means that if you are using a CSS preprocessor that has support for source maps, and you've enabled source map support in the :ref:`Style Editor settings <settings-style-editor>`, then the link will take you to the original source, not the generated CSS. Read more about CSS source map support in the :ref:`Style Editor documentation <style-editor-source-map-support>`.
+
+
+.. _page-inspector-how-to-examine-and-edit-css-overridden-declarations:
+
+Overridden declarations
+-----------------------
+
+If a CSS declaration is overridden by some other CSS rule with a greater weight, then the declaration is shown with a line through it.
+
+Overridden declarations have a funnel next to them. Click the funnel to filter the rule view to show only the rules applying to the current node that try to set the same property: that is, the complete cascade for the given property.
+
+This makes it easy to see which rule is overriding the declaration
+
+
+.. _page-inspector-view-media-rules-for-print:
+
+View @media rules for Print
+---------------------------
+
+You can toggle the display into a mode that emulates @media rules for print.
+
+.. raw:: html
+
+  <iframe width="560" height="315" src="https://www.youtube.com/embed/AEmq9hNDOGU" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+  <br/>
+  <br/>
+
+
+When on, any rules defined for printing the page will be displayed similar to the "Print Preview" mode that many word processing applications provide.
+
+
+.. _page-inspector-view-media-rules-for-prefers-color-scheme:
+
+View @media rules for prefers-color-scheme
+------------------------------------------
+
+The color scheme simulator buttons can be used to test the rendering of styles based on the `prefers-color-scheme <https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme>`_ media query (if any are defined for the page). There are two buttons, which enable the light and dark preference, respectively. Selecting either button deselects the other. If neither button is selected then the simulator does not set a preference, and the browser renders using the default feature value set by the operating system.
+
+
+.. |image3| image:: color_scheme_null.png
+  :class: border
+
+.. |image4| image:: color_scheme_light.png
+  :class: border
+
+.. |image5| image:: color_scheme_dark.png
+  :class: border
+
+
+.. list-table::
+  :widths: 30 20 50
+  :header-rows: 1
+
+  * - Icon
+    - Value
+    - Description
+
+  * - |image3|
+    - null
+    - The ``prefers-color-scheme`` media feature is not set by the simulator.
+
+
+  * - |image4|
+    - ``light``
+    - The ``prefers-color-scheme`` media feature is set to ``light``.
+
+  * - |image5|
+    - ``dark``
+    - The ``prefers-color-scheme`` media feature is set to ``dark``.
+
+
+Note that if the operating system mode is set to a particular mode, then simulating that mode will not change page rendering (i.e. simulating dark mode when the operating system is using dark mode will not change the display).
+
+.. note::
+  If ``privacy.resistFingerprinting`` has been set **true**, the `prefers-color-scheme <https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme>`_ preference is forced to ``light``. You must set``privacy.resistFingerprinting`` to **false** in order to use this feature.
+
+
+.. note::
+  Before Firefox 87 this feature is behind the preference ``devtools.inspector.color-scheme-simulation.enabled``.
+
+
+.. _page_inspector_how_to_examine_and_edit_css_examine_computed_css:
+
+Examine computed CSS
+********************
+
+To see the complete computed CSS for the selected element, select the :ref:`Computed panel <page_inspector_ui_tour_computed_view>` in the righthand pane.This panel shows the calculated value that each CSS property has for the selected element. (This calculated value is exactly the same as what `getComputedStyle <https://developer.mozilla.org/en-US/docs/Web/API/Window/getComputedStyle>`_ would return.)
+
+.. image:: computed_css.png
+  :class: border
+
+
+You can :kbd:`Tab` through the stylesto select them, and you can find more information about each property— pressing :kbd:`F1` on a selected property will open up its MDN reference page.
+
+Clicking the arrow next to the property name (or pressing :kbd:`Enter` or :kbd:`Space` while it is selected) shows the rule that set this value, along with a link to the source filename and line number:
+
+.. image:: computed_css_details.png
+  :class: border
+
+
+By default, this view only shows values that have been explicitly set by the page: to see all values, click the "Browser styles" box. You can :kbd:`Tab` through the filenames/line numbers; pressing :kbd:`Enter`/:kbd:`Return` will open up the relevant file at that point in the :doc:`Style Editor <../../../style_editor/index>`.
+
+Typing in the search box performs a live filtering of the list, so, for example, if you just want to see font-related settings, you can type "font" in the search box, and only properties with "font" in the name will be listed. You can also search for the values of properties: to find the rule responsible for setting the font to "Lucida Grande", type that in the search box.
+
+.. note::
+  While in the Computed view, you can press :kbd:`Ctrl` / :kbd:`Cmd` + :kbd:`F` to focus the search field. Once you've typed in a filter, you can press :kbd:`Esc` to remove it again.
+
+
+Edit rules
+**********
+
+If you click on a declaration or a selector in the Rules view you can edit it and see the results immediately. You can also :kbd:`Tab` through the different existing properties and values, and start editing them by pressing :kbd:`Enter` or :kbd:`Space`. To add a new declaration to a rule, click on the last line of the rule (the line occupied by the closing brace).
+
+As you start typing a property name, you'll see a list of autocomplete suggestions. Press:kbd:`Tab` to accept the current suggestion or :kbd:`Up` and :kbd:`Down` to move through the list. The default choice is the most common property that starts with the letters you've typed. For example, here the user has typed "c" and the default choice is "color":
+
+.. image:: edit_rule_autocomplete.png
+  :class: border
+
+
+If you enter an invalid value for a property when editing it, or an unknown property name, a yellow alert icon appears besides the declaration.
+
+Edits that you make in the Rules view are reflected in the :doc:`Style Editor <../../../style_editor/index>`, and vice versa. Any changes you make are temporary: reloading the page will restore the original styling.
+
+While you're editing CSS, the context menu you'll see is the normal one for working with editable text:
+
+.. image:: editable-context-menu.png
+  :class: center
+
+
+CSS variable autocompletion
+---------------------------
+
+`CSS variable names <https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties>`_ will auto-complete depending on the variables defined in the CSS. If you enter ``var(`` into a property value and then type a dash (``-``), any variables you have declared in your CSS will then appear in an autocomplete list, which shows a color swatch so you can see exactly what color each variable choice is storing (`bug 1451211 <https://bugzilla.mozilla.org/show_bug.cgi?id=1451211>`_)
+
+.. image:: edit_rule_var_autocomplete.png
+  :class: border
+
+
+In addition, hovering over a CSS variable name brings up a tooltip showing what color value is stored in that variable `bug 1431949 <https://bugzilla.mozilla.org/show_bug.cgi?id=1431949>`_.
+
+.. image:: var_value.png
+  :class: border
+
+
+Editing keyboard shortcuts
+--------------------------
+
+You can use the arrow and page up/down keys (along with others) to increase/decrease numeric rules while editing:
+
+
+- The :kbd:`Up` arrow increments values by 1 — for example, "1px" changes to "2px".
+- :kbd:`Shift` + :kbd:`Up`/:kbd:`Down` increments or decrements values by 10.
+- :kbd:`Ctrl` + :kbd:`Up`/:kbd:`Down` (on Linux and Windows) or :kbd:`Alt` + :kbd:`Up`/:kbd:`Down` (on Mac) increments or decrements values by 0.1.
+- :kbd:`Shift` + :kbd:`Page up`/:kbd:`Page down` increments or decrements values by 100.
+
+
+Track changes
+-------------
+
+When you are editing the rules in the rules view, you can see the changes you have made in the Changes pane.
+
+.. image:: track_changes.png
+  :class: border
+
+
+.. note::
+  You can view changes made to the rules view only. If you edit the CSS using the Style Editor, the changes will not be shown in the changes pane.
+
+  Also remember, as noted above, that changes you make to the CSS rules are temporary and will be reset if you reload the page.
+
+
+If you are satisfied with the changes you have made, you can copy the new settings to page the edited rule into your stylesheet. Right-click on the changes panel and select **Copy Rule** from the context menu.
+
+.. image:: save_changes_panel.png
+  :class: border
+
+
+The Copy Rule command copies the entire element, class, or id definition, including any unchanged rules and the rules that describe your changes. For example, copying the changes in the preceding image, you get the following:
+
+.. code-block:: css
+
+  .text-content p {
+    box-sizing:border-box;
+    max-width:24rem;
+    text-decoration: underline;
+    color: cadetblue;
+    font-weight: bold;
+  }
+
+
+.. _page_inspector_how_to_examine_and_edit_css_add_rules:
+
+Add rules
+*********
+
+You can add new rules in the Rules view. Just right-click to show the context menu and select "Add rule". This will add a new CSS rule whose selector matches the currently selected node.
+
+.. image:: add_new_rule.png
+  :class: border
+
+
+There's also a button that enables you to do the same thing:
+
+.. image:: rules_panel.png
+  :class: border
+
+
+Copy rules
+**********
+
+To copy rules, and pieces of rules, use one of the following context menu items in the Rules view:
+
+
+- Copy Rule
+- Copy Selector
+- Copy Property Declaration
+- Copy Property Name
+- Copy Property Value
+
+.. image:: rules_context_menu.png
+  :class: center
+
+
+See also
+********
+
+- Complete list of Page Inspector :ref:`Keyboard shortcuts <keyboard-shortcuts-page-inspector>`.
+- The Inspector also includes a number of specialized tools for working with particular CSS features, such as colors, fonts, and animations. To read about these see the list of :doc:`how to guides <../../index>`.
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/invalid_property.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/invalid_property.png
new file mode 100644
index 0000000000..2015da3d84
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/invalid_property.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/pseudo-elements.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/pseudo-elements.png
new file mode 100644
index 0000000000..45dd756270
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/pseudo-elements.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/pseudo-elements_displayed.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/pseudo-elements_displayed.png
new file mode 100644
index 0000000000..6f8f2df915
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/pseudo-elements_displayed.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/rules_context_menu.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/rules_context_menu.png
new file mode 100644
index 0000000000..f9b04aad7b
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/rules_context_menu.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/rules_pane.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/rules_pane.png
new file mode 100644
index 0000000000..93572dfc00
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/rules_pane.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/rules_panel.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/rules_panel.png
new file mode 100644
index 0000000000..0e37e4f376
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/rules_panel.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/rules_view_buttons_fx_72.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/rules_view_buttons_fx_72.png
new file mode 100644
index 0000000000..34a9de97e7
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/rules_view_buttons_fx_72.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/rules_view_ff_87.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/rules_view_ff_87.png
new file mode 100644
index 0000000000..0d92933d8a
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/rules_view_ff_87.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/save_changes_panel.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/save_changes_panel.png
new file mode 100644
index 0000000000..6637725c27
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/save_changes_panel.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/screen_shot_2016-12-16_at_10.51.15_am.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/screen_shot_2016-12-16_at_10.51.15_am.png
new file mode 100644
index 0000000000..3cb6150e42
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/screen_shot_2016-12-16_at_10.51.15_am.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/show_pseudo_classes.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/show_pseudo_classes.png
new file mode 100644
index 0000000000..6436db0188
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/show_pseudo_classes.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/show_pseudo_classes_hover.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/show_pseudo_classes_hover.png
new file mode 100644
index 0000000000..e4f078722e
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/show_pseudo_classes_hover.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/target-icon.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/target-icon.png
new file mode 100644
index 0000000000..54ab83e68e
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/target-icon.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/track_changes.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/track_changes.png
new file mode 100644
index 0000000000..5ab5cb6f5a
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/track_changes.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/user-agent_css.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/user-agent_css.png
new file mode 100644
index 0000000000..8bc5fe28d1
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/user-agent_css.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/var_value.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/var_value.png
new file mode 100644
index 0000000000..333367b35b
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_css/var_value.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/child-node-indicator.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/child-node-indicator.png
new file mode 100644
index 0000000000..e0626644f8
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/child-node-indicator.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/custom_pc_01.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/custom_pc_01.png
new file mode 100644
index 0000000000..94a66c4cf8
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/custom_pc_01.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/custom_pc_02.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/custom_pc_02.png
new file mode 100644
index 0000000000..496b9a0471
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/custom_pc_02.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/edit_html.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/edit_html.png
new file mode 100644
index 0000000000..698bce9182
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/edit_html.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/editable-context-menu.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/editable-context-menu.png
new file mode 100644
index 0000000000..cbc9415ce1
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/editable-context-menu.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/html_breadcrumbs.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/html_breadcrumbs.png
new file mode 100644
index 0000000000..d5cf8d0dd6
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/html_breadcrumbs.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/html_tree.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/html_tree.png
new file mode 100644
index 0000000000..ee08f0dc30
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/html_tree.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/index.rst b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/index.rst
new file mode 100644
index 0000000000..dcc688fd91
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/index.rst
@@ -0,0 +1,466 @@
+=====================
+Examine and edit HTML
+=====================
+
+You can examine and edit the page's HTML in the :ref:`HTML pane <page_inspector_ui_tour_html_pane>`.
+
+
+Navigating the HTML
+*******************
+
+.. _page-inspector-how-to-examine-and-edit-html-breadcrumbs:
+
+HTML breadcrumbs
+----------------
+
+At the bottom on the HTML pane is a breadcrumbs toolbar. This shows the complete hierarchy through the document for the branch containing the selected element:
+
+.. image:: html_breadcrumbs.png
+  :class: border
+
+
+Hovering over a breadcrumb highlights that element in the page.
+
+The breadcrumbs bar has its own :ref:`keyboard shortcuts <keyboard-shortcuts-breadcrumbs-bar>`.
+
+
+.. _page_inspector_how_to_examine_and_edit_html_searching:
+
+Searching
+---------
+
+The Page Inspector's search box matches all markup in the current document and in any frames.
+
+To start searching the markup, click in the search box to expand it or press :kbd:`Ctrl` + :kbd:`F` , or :kbd:`Cmd` + :kbd:`F` on a Mac. There are three types of searches that are performed automatically depending on what you enter, a full text search, a CSS selector search, and an XPath search.
+
+
+Full text search
+~~~~~~~~~~~~~~~~
+
+The full text search will always be executed, independently of what you enter. That allows you to find CSS selectors and XPath expressions occurring within the text.
+
+
+CSS selector search
+~~~~~~~~~~~~~~~~~~~
+
+You can search elements by entering a `CSS selector <https://developer.mozilla.org/en-US/docs/Glossary/CSS_Selector>`_
+
+As you type, an autocomplete popup shows any class or ID attributes that match the current search term:
+
+.. image:: search_html.png
+  :class: border
+
+
+Press :kbd:`Up` and :kbd:`Down` to cycle through suggestions, :kbd:`Tab` to choose the current suggestion, then :kbd:`Enter` to select the first node with that attribute.
+
+
+To cycle through matches, press :kbd:`Enter`. You can cycle backwards through matches using :kbd:`Shift` + :kbd:`Enter`.
+
+
+XPath search
+~~~~~~~~~~~~
+
+It is also possible to search via `XPaths <https://developer.mozilla.org/en-US/docs/Web/XPath>`_. This allows you to search for specific elements without the conflict of matching words within the text. For example, ``//a`` matches all `a <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a>`_ elements but not the letter "a" within the text content. Furthermore it allows for some more advanced searches like finding elements that start with a specific text, for example.
+
+.. image:: xpath_search.png
+  :alt: Match of an Inspector search using an XPath expression
+  :class: border
+
+
+HTML tree
+---------
+
+The rest of the pane shows you the page's HTML as a tree (this UI is also called the Markup View). Just to the left of each node is an arrow: click the arrow to expand the node. If you hold the Alt key while clicking the arrow, it expands the node and all the nodes underneath it.
+
+.. image:: html_tree.png
+  :alt: The new Firefox 57 inspector HTML tree.
+  :class: center
+
+
+Moving the mouse over a node in the tree highlights that element in the page.
+
+Nodes that are not visible are shown faded/desaturated. This can happen for different reasons such as using `display: none <https://developer.mozilla.org/en-US/docs/Web/CSS/display>`_ or that the element doesn't have any dimensions.
+
+.. |image1| image:: child-node-indicator.png
+  :width: 20
+
+There is an ellipsis shown between the opening and closing tag of an element when the node is collapsed if it has larger contents. Now children are indicated in the tree with this icon: |image1|
+
+
+Markers ("badges") are displayed to the right of some nodes. The table below explains the meaning of each badge:
+
+.. |br| raw:: html
+
+    <br/>
+
+
+.. list-table::
+  :widths: 25 75
+  :header-rows: 0
+
+  * - ``event``
+    - The element has one or several event listeners attached to it. Clicking the marker opens a tooltip listing the event listeners and allows you for each listener to switch to the line of JavaScript code in the :doc:`Debugger <../../../debugger/index>` where the listener is defined.
+
+  * - ``scroll``
+    - The element is a `scroll container <https://developer.mozilla.org/en-US/docs/Glossary/Scroll_container>`_, i.e. it has either ``overflow: scroll`` applied, or ``overflow: auto`` and sufficient content to cause `scrollable overflow <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Overflow>`_. |br| |br| If preference ``devtools.overflow.debugging.enabled`` is ``true``, toggling the ``scroll`` badge will highlight any elements causing the overflow, and these nodes will additionally display the ``overflow`` badge.
+
+  * - ``overflow``
+    - The element is causing `scrollable overflow <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Overflow>`_ in a `scroll container <https://developer.mozilla.org/en-US/docs/Glossary/Scroll_container>`_ (either the current node or a parent node—the affected nodewill display the ``scroll`` badge). |br| |br| **Note**: The ``overflow`` badge is introduced in Firefox 83. In earlier versions it can be enabled using the preference ``devtools.overflow.debugging.enabled`` is ``true``.
+
+  * - ``grid``
+    - The element is a `grid container <https://developer.mozilla.org/en-US/docs/Glossary/Grid_Container>`_, i.e. it has `display: grid <https://developer.mozilla.org/en-US/docs/Web/CSS/display>`_ applied to it. Clicking the marker enables the grid highlighter.
+
+  * - ``flex``
+    - The element is a `flex container <https://developer.mozilla.org/en-US/docs/Glossary/Flex_Container>`_, i.e. it has `display: flex <https://developer.mozilla.org/en-US/docs/Web/CSS/display>`_ applied to it. Clicking the marker enables the flexbox highlighter.
+
+  * - ``inline-grid``
+    - The element is an inline grid container, i.e. it has `display: inline-grid <https://developer.mozilla.org/en-US/docs/Web/CSS/display>`_ or ``display: inline grid`` applied to it. Clicking the marker enables the grid highlighter.
+
+  * - ``inline-flex``
+    - The element is an inline flex container, i.e. it has `display: inline-flex <https://developer.mozilla.org/en-US/docs/Web/CSS/display>`_ or ``display: inline flex`` applied to it. Clicking the marker enables the flexbox highlighter.
+
+  * - ``custom…``
+    - The element is a custom element. Clicking the marker switches to the line of JavaScript code in the Debugger where the custom element got defined.
+
+
+
+.. note::
+  There are some useful keyboard shortcuts that can be used in the HTML tree — see the :ref:`HTML pane keyboard shortcuts list <keyboard-shortcuts-html-pane>`.
+
+
+::before and ::after
+--------------------
+
+You can inspect pseudo-elements added using `::before <https://developer.mozilla.org/en-US/docs/Web/CSS/::before>`_ and `::after <https://developer.mozilla.org/en-US/docs/Web/CSS/::after>`_
+
+.. raw:: html
+
+  <iframe width="560" height="315" src="https://www.youtube.com/embed/ecfqTGvzsNc" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+  <br/>
+  <br/>
+
+
+Custom element definition
+-------------------------
+
+When you open the Inspector on a page that includes custom elements, you can view the class definition for the custom element in the Debugger:
+
+
+1. Inspect the element
+2. Click on the word ``custom``
+
+
+.. image:: custom_pc_01.png
+  :class: center
+
+
+The source for the element's class will be displayed in the Debugger.
+
+.. image:: custom_pc_02.png
+  :class: center
+
+
+Whitespace-only text nodes
+--------------------------
+
+Web developers don’t write all their code in just one line of text. They use white space such as spaces, returns, or tabs between their HTML elements because it makes markup more readable.
+
+Usually this white space seems to have no effect and no visual output, but in fact, when a browser parses HTML it will automatically generate anonymous text nodes for elements not contained in a node. This includes white space (which is after all a type of text).
+
+If these auto generated text nodes are `inline level <https://developer.mozilla.org/en-US/docs/Web/CSS/Visual_formatting_model#inline-level_elements_and_inline_boxes>`_, browsers will give them a non-zero width and height. Then you will find strange gaps between elements, even if you haven’t set any margin or padding on them.
+
+.. |image2| image:: new-whitespace-text-indicator.png
+  :width: 20
+
+Since Firefox 52, the Inspector displays these whitespace nodes, so you can see where the gaps in your markup come from. Whitespace nodes are represented with a dot: |image2| and you get an explanatory tooltip when you hover over them:
+
+.. image:: white_space_only.png
+  :class: center
+
+
+To see this in action, see the demo at https://firefox-devtools.github.io/devtools-examples/whitespace-only-demo/index.html.
+
+
+Shadow roots
+------------
+
+Any shadow roots present in the DOM are exposed in the HTML page in the same manner as the regular DOM. The shadow root is signified by a node named ``#shadow-root`` — you can click its expansion arrow to see the full contents of the shadow DOM, and then manipulate the contained nodes in a similar way to other part of the page's DOM (although with a limited featureset — you can't, for example, drag and drop or delete shadow DOM nodes).
+
+
+.. image:: inspector_shadowdom.png
+  :alt: A view of a shadow root shown inside the DOM tree in the Firefox DevTools
+  :class: center
+
+
+If a shadow DOM contains a "slotted" element (an element with a ``slot`` attribute after it has been inserted inside a `slot <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/slot>`_ element — see `Adding flexibility with slots <https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_templates_and_slots#adding_flexibility_with_slots>`_ for an explanation of how these are used), the "slotted" element will be shown inside its corresponding `slot <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/slot>`_ element, with a "reveal" link alongside it. Clicking the "reveal" link will highlight the element with the ``slot`` attribute as it exists outside the shadow DOM
+
+.. image:: inspector_slot.png
+  :alt: A view of a shadow root shown inside the DOM tree in the Firefox DevTools
+  :class: center
+
+
+This is very useful when you've got a ``<slot>`` element and you can't find the source of its content.
+
+
+.. note::
+
+  Shadow DOM inspection was implemented in Firefox 61, but was hidden behind the ``dom.webcomponents.shadowdom.enabled`` pref until Firefox 63. It is now turned on by default.
+
+
+.. _page-inspector-how-to-element-popup-context-menu:
+
+Element popup context menu
+--------------------------
+
+You can perform certain common tasks on a specific node using a popup context menu. To activate this menu, context-click the element. The menu contains the following items — click on the links to find the description of each command in the :ref:`Context menu reference <page_inspector_how_to_examine_and_edit_html_context_menu_reference>`:
+
+
+- Edit As HTML
+- Create New Node
+- Duplicate Node
+- Delete Node
+- Attributes
+
+  - Add Attribute
+  - Copy Attribute Value
+  - Edit Attribute
+  - Remove Attribute
+
+- Break on ...
+
+  - Subtree Modification
+  - Attribute Modification
+  - Node Removal
+
+.. _page_inspector_how_to_examine_and_edit_html_use_in_console:
+
+- Use in Console
+- Show DOM Properties
+- Show Accessibility Properties
+- Change Pseudo-class
+
+  - hover
+  - active
+  - focus
+  - focus-visible
+  - focus-within
+  - visited
+
+- Screenshot Node
+
+.. _page_inspector_how_to_examine_and_edit_scroll_into_view:
+
+- Scroll Into View
+- Copy
+
+  - Inner HTML
+  - Outer HTML
+  - CSS Selector
+  - CSS Path
+  - XPath
+  - Image Data-URL
+  - Attribute
+
+- Paste
+
+  - Inner HTML
+  - Outer HTML
+  - Before
+  - After
+  - As First Child
+  - As Last Child
+
+- Expand All
+- Collapse All
+- Open Link in New Tab [1]
+- Open File in Debugger [1]
+- Open File in Style-Editor [1]
+- Copy Link Address [1]
+
+
+[1] These options only appear in certain contexts, for example the "Open File in Style-Editor" option only appears when you context-click over the top of a link to a CSS file.
+
+
+.. _page_inspector_how_to_examine_and_edit_html_context_menu_reference:
+
+Context menu reference
+----------------------
+
+.. list-table::
+  :widths: 30 70
+  :header-rows: 0
+
+  * - Edit as HTML
+    - :ref:`Edit the element's HTML <page-inspector-how-to-examine-and-edit-html-editing_html>`.
+
+  * - (Copy) Inner HTML
+    - Copy the inner HTML for the element.
+
+  * - (Copy) Outer HTML
+    - Copy the outer HTML for the element.
+
+      Pressing :kbd:`Ctrl` + :kbd:`C` (or :kbd:`Cmd` + :kbd:`C` on a Mac) also performs this action.
+
+
+  * - (Copy) Unique Selector/CSS Selector
+    - Copy a CSS selector that uniquely selects the element.
+
+  * - (Copy) CSS Path
+    - Copy a CSS selector that represents the full path to the element.
+
+  * - (Copy) Image Data-URL
+    - Copy image as a data:// URL, if the selected element is an image.
+
+  * - (Copy) Attribute
+    - Copy the attribute of the element.
+
+  * - Show DOM Properties
+    - Open the :doc:`split console <../../../web_console/split_console/index>` and enter the console command "``inspect($0)``" to :doc:`inspect <../../../web_console/index>` the currently selected element.
+
+  * - Use in Console
+    - Assigns the currently selected node to a variable named ``temp0`` (or ``temp1`` if ``temp0`` is already taken, and so on), then opens the :doc:`split console <../../../web_console/split_console/index>`, enabling you to interact with that node using the console's command line.
+
+  * - Expand All
+    - In the tree view, expand the current element and all the elements underneath it. This is equivalent to holding the :kbd:`Alt` key and clicking the disclosure triangle next to an element.
+
+  * - Collapse
+    - In the tree view, collapse the current element. This is equivalent to clicking the disclosure arrow next to an element that's expanded.
+
+  * - (Paste) Inner HTML
+    - Paste the clipboard contents into the node as its `innerHTML <https://developer.mozilla.org/en-US/docs/Web/API/Element/innerHTML>`_.
+
+  * - (Paste) Outer HTML
+    - Paste the clipboard contents into the node as its `outerHTML <https://developer.mozilla.org/en-US/docs/Web/API/Element/outerHTML>`_.
+
+  * - (Paste) Before
+    - Paste the clipboard contents into the document immediately before this node.
+
+  * - (Paste) After
+    - Paste the clipboard contents into the document immediately after this node.
+
+  * - (Paste) As First Child
+    - Paste the clipboard contents into the document as the first child of this node.
+
+  * - (Paste) As Last Child
+    - Paste the clipboard contents into the document as the last child of this node.
+
+  * - Scroll Into View
+    - Scrolls the web page so the selected node is visible.
+
+      From Firefox 44, pressing the keyboard shortcut :kbd:`S` will also scroll the selected node into view.
+
+  * - Screenshot Node
+    - Takes a screenshot of the selected node, saved to your Downloads directory. See :doc:`Taking screenshots <../../../taking_screenshots/index>`.
+
+  * - Create New Node
+    - Create a new empty <div> as the last child of the currently selected element. See :ref:`Inserting new nodes <page-inspector-how-to-examine-and-edit-html-inserting-new-nodes>`.
+
+  * - Duplicate Node
+    - Create a copy of this element, and insert the copy immediately after this element.
+
+  * - Delete Node
+    - Delete the element from the DOM.
+
+  * - Attribute/Add Attribute
+    - Add an attribute to the element.
+
+  * - Attribute/Edit Attribute
+    - (only when invoked on an attribute) Edit the attribute.
+
+  * - Attribute/Remove Attribute
+    - (only when invoked on an attribute) Remove the attribute.
+
+  * - Open Link in New Tab
+    - (only when invoked over a link, such as an href attribute) Opens the linked item in a new tab.
+
+  * - Open File in Debugger
+    - (only when invoked over a link to a JS source) Opens the linked source in the Debugger.
+
+  * - Open File in Style-Editor
+    - (only when invoked over a link to a CSS source) Opens the linked source in the Style Editor.
+
+  * - Copy Link Address
+    - (only when invoked over a URL) Copy the URL.
+
+  * - (Change Pseudo-class) hover
+    - Set the `:hover <https://developer.mozilla.org/en-US/docs/Web/CSS/:hover>`_ CSS pseudo-class.
+
+  * - (Change Pseudo-class) active
+    - Set the `:active <https://developer.mozilla.org/en-US/docs/Web/CSS/:active>`_ CSS pseudo-class.
+
+  * - (Change Pseudo-class) focus
+    - Set the `:focus <https://developer.mozilla.org/en-US/docs/Web/CSS/:focus>`_ CSS pseudo-class.
+
+  * - (Change Pseudo-class) focus-visible
+    - Set the `:focus-visible <https://developer.mozilla.org/en-US/docs/Web/CSS/:focus-visible>`_ CSS pseudo-class.
+
+  * - (Change Pseudo-class) focus-within
+    - Set the `:focus-within <https://developer.mozilla.org/en-US/docs/Web/CSS/:focus-within>`_ CSS pseudo-class.
+
+  * - (Change Pseudo-class) visited
+    - Set the :visited CSS pseudo-class.
+
+
+.. _page-inspector-how-to-examine-and-edit-html-editing_html:
+
+Editing HTML
+************
+
+You can edit the HTML — tags, attributes, and content — directly in the HTML pane: double-click the text you want to edit, change it, and press Enter to see the changes reflected immediately.
+
+To edit an element's `outerHTML <https://developer.mozilla.org/en-US/docs/Web/API/Element/outerHTML>`_, activate the element's popup menu and select "Edit As HTML". You'll see a text box in the HTML pane:
+
+.. image:: edit_html.png
+  :alt: Edit HTML directly in the Inspector panel in Firefox 57
+  :class: border
+
+You can add any HTML in here: changing the element's tag, changing existing elements, or adding new ones. Once you click outside the box, the changes are applied to the page.
+
+When you're editing HTML, the context menu you'll see is the normal one for working with editable text:
+
+.. image:: editable-context-menu.png
+  :class: center
+
+
+Copy and paste
+--------------
+
+You can use the :ref:`popup menu <page-inspector-how-to-element-popup-context-menu>` to copy nodes in the HTML tree and paste them into the desired location.
+
+
+Drag and drop
+-------------
+
+You can reorganize the HTML content of a page by moving nodes in the HTML tree. Just click and hold on any element and drag it up or down in the tree. When you release the mouse button, the element will be inserted at the corresponding position:
+
+.. raw:: html
+
+  <iframe width="560" height="315" src="https://www.youtube.com/embed/oI-a035nfWk" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+  <br/>
+  <br/>
+
+You can cancel the drag and drop by pressing the :kbd:`Esc` key.
+
+
+.. _page-inspector-how-to-examine-and-edit-html-inserting-new-nodes:
+
+Inserting new nodes
+-------------------
+
+There's a "+" icon at the top of the markup view:
+
+.. image:: html_tree.png
+  :class: border
+
+
+Click this icon to insert an empty {{HTMLElement("div")}} into the document as the last child of the currently selected element. You can then edit the new node's content and styling just as you would any other node in the document.
+
+.. raw:: html
+
+  <iframe width="560" height="315" src="https://www.youtube.com/embed/NG5daffvVZM" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+  <br/>
+  <br/>
+
+You can access the same functionality using the "Create New Node" popup menu item.
+
+Note that this button is disabled if the selected element's type is such that adding a last-child would have no effect (for example, if it is an `html <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/html>`_ or `iframe <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe>`_ element). However, it is enabled in places where it is not valid to insert a `div <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div>`_, such as `style <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/style>`_ or `link <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link>`_. In these cases the element is added as text.
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/inspector_shadowdom.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/inspector_shadowdom.png
new file mode 100644
index 0000000000..515ff2bfdc
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/inspector_shadowdom.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/inspector_slot.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/inspector_slot.png
new file mode 100644
index 0000000000..590ba86f50
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/inspector_slot.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/new-whitespace-text-indicator.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/new-whitespace-text-indicator.png
new file mode 100644
index 0000000000..e925cabd49
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/new-whitespace-text-indicator.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/search_html.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/search_html.png
new file mode 100644
index 0000000000..c1b84eaa18
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/search_html.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/white_space_only.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/white_space_only.png
new file mode 100644
index 0000000000..d7a6f5c428
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/white_space_only.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/xpath_search.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/xpath_search.png
new file mode 100644
index 0000000000..95342b7f8d
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_html/xpath_search.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_the_box_model/box-model-tooltip.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_the_box_model/box-model-tooltip.png
new file mode 100644
index 0000000000..0b83f8b144
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_the_box_model/box-model-tooltip.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_the_box_model/box-model.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_the_box_model/box-model.png
new file mode 100644
index 0000000000..cbb926183f
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_the_box_model/box-model.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_the_box_model/index.rst b/devtools/docs/user/page_inspector/how_to/examine_and_edit_the_box_model/index.rst
new file mode 100644
index 0000000000..691630f211
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_the_box_model/index.rst
@@ -0,0 +1,52 @@
+==============================
+Examine and edit the box model
+==============================
+
+Viewing the box model
+*********************
+
+With the :ref:`Select Element button <page_inspector_select_element_button>` pressed, if you hover over an element in the page, the `box model <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Box_Model/Introduction_to_the_CSS_box_model>`_ for the element is shown overlaid on the page:
+
+.. raw:: html
+
+  <iframe width="560" height="315" src="https://www.youtube.com/embed/vDRzN-svJHQ" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+  <br/>
+  <br/>
+
+
+It's also shown overlaid if you hover over an element's markup in the HTML pane:
+
+.. raw:: html
+
+  <iframe width="560" height="315" src="https://www.youtube.com/embed/xA4IxTttNLk" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+  <br/>
+  <br/>
+
+If the element is inline and is split over multiple line boxes, the highlighter shows each individual line box that together make up the element:
+
+.. image:: inline-box-model.png
+  :class: center
+
+
+.. _page-inspector-how-to-examine-and-edit-the-box-model-view:
+
+
+The Box Model view
+------------------
+
+When an element's selected, you can get a detailed look at the box model in the :ref:`Box Model view <page_inspector_ui_tour_computed_view>`:
+
+.. image:: box-model.png
+  :class: center
+
+
+If you hover over a value, you'll see a tooltip telling you which rule the value comes from:
+
+.. image:: box-model-tooltip.png
+  :class: center
+
+
+Editing the box model
+*********************
+
+You can also edit the values in the :ref:`Box Model view <page-inspector-how-to-examine-and-edit-the-box-model-view>`, and see the results immediately in the page.
diff --git a/devtools/docs/user/page_inspector/how_to/examine_and_edit_the_box_model/inline-box-model.png b/devtools/docs/user/page_inspector/how_to/examine_and_edit_the_box_model/inline-box-model.png
new file mode 100644
index 0000000000..5da14d5e0f
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_and_edit_the_box_model/inline-box-model.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_event_listeners/index.rst b/devtools/docs/user/page_inspector/how_to/examine_event_listeners/index.rst
new file mode 100644
index 0000000000..0595d6164b
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_event_listeners/index.rst
@@ -0,0 +1,27 @@
+=======================
+Examine Event Listeners
+=======================
+
+The inspector shows the word "event" next to elements in the :ref:`HTML Pane <page_inspector_ui_tour_html_pane>`, that have event listeners bound to them:
+
+.. image:: inspect_element_with_eventhandler.png
+  :class: border
+
+Click the icon, then you'll see a popup listing all the event listeners bound to this element:
+
+.. image:: inspector_event_handlers.png
+  :class: border
+
+Each line contains:
+
+
+- a right-pointing arrowhead; click to expand the row and show the listener function source code
+- the name of the event for which a handler was attached to this element
+- the name and line number for the listener; you can also click here to expand the row and view the listener function source code
+- a curved arrow pointing to a stack; click it to show the code for the handler in the debugger
+- a label indicating whether the event bubbles
+- a label indicating the system that defines the event. Firefox can display:
+
+  - standard DOM events
+  - `jQuery events <https://api.jquery.com/category/events/>`_
+  - `React events <https://facebook.github.io/react/docs/events.html>`_
diff --git a/devtools/docs/user/page_inspector/how_to/examine_event_listeners/inspect_element_with_eventhandler.png b/devtools/docs/user/page_inspector/how_to/examine_event_listeners/inspect_element_with_eventhandler.png
new file mode 100644
index 0000000000..df8b66eb53
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_event_listeners/inspect_element_with_eventhandler.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_event_listeners/inspector_event_handlers.png b/devtools/docs/user/page_inspector/how_to/examine_event_listeners/inspector_event_handlers.png
new file mode 100644
index 0000000000..34e3efecee
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_event_listeners/inspector_event_handlers.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/css-pane.png b/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/css-pane.png
new file mode 100644
index 0000000000..3cb2104e12
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/css-pane.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/flex-cont.png b/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/flex-cont.png
new file mode 100644
index 0000000000..7eb08580a6
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/flex-cont.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/flex-items.png b/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/flex-items.png
new file mode 100644
index 0000000000..8e423449ed
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/flex-items.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/flexbox_icon.gif b/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/flexbox_icon.gif
new file mode 100644
index 0000000000..53a045837e
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/flexbox_icon.gif
diff --git a/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/html-pane.png b/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/html-pane.png
new file mode 100644
index 0000000000..989bf63ec7
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/html-pane.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/index.rst b/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/index.rst
new file mode 100644
index 0000000000..cbd14ea5e8
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/index.rst
@@ -0,0 +1,133 @@
+==============================================
+CSS Flexbox Inspector: Examine Flexbox layouts
+==============================================
+
+The **Flexbox Inspector** allows you to examine `CSS Flexbox Layouts <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Flexible_Box_Layout>`_ using the Firefox DevTools, which is useful for discovering flex containers on a page, examining and modifying them, debugging layout issues, and more.
+
+
+Discovering Flex Containers
+***************************
+
+When an HTML element on your page has `display: flex <https://developer.mozilla.org/en-US/docs/Web/CSS/display>`_ applied to it, a number of features are made available in the DevTools to provide easy access to Flexbox layout features.
+
+
+In the HTML pane
+----------------
+
+In the :ref:`HTML Pane <page_inspector_ui_tour_html_pane>`, an element laid out with Flexbox has the word ``flex`` next to it as shown in the following image:
+
+.. image:: html-pane.png
+  :alt: Indicators in the inspector showing an element is a flex container
+  :class: center
+
+
+Click the word ``flex`` in the HTML pane to keep the overlay visible when you move the mouse away from the container.
+
+
+In the infobar
+--------------
+
+When you hover over an element in the HTML pane, you will see a tooltip that gives you more information about the element. When you hover over a flex container or flex item, the tooltip includes the appropriate information.
+
+This header is a flex container:
+
+.. image:: infobar-cont.png
+  :alt: Tooltip showing element is a flex container
+  :class: center
+
+Each navbar link is a flex item:
+
+.. image:: infobar-item.png
+  :alt: Tooltip showing an element is a flex item
+  :class: center
+
+The ``nav`` element within the header is both a flex item and a flex container which holds the navigation links:
+
+.. image:: infobar-both.png
+  :alt: Tooltip showing an element is both a flex container and a flex item
+  :class: center
+
+
+In the CSS pane
+---------------
+
+.. |image1| image:: flexbox_icon.gif
+  :width: 20
+
+In the :ref:`CSS pane <page_inspector_ui_tour_rules_view>`'s Rules view, any instance of a `display: flex <https://developer.mozilla.org/en-US/docs/Web/CSS/display>`_ declaration gets a small Flexbox icon |image1| next to the word ``flex``.
+
+.. image:: css-pane.png
+  :alt: The CSS pane of the Firefox devtools, showing the CSS for a flex container with an icon to toggle the Flexbox overly
+  :class: center
+
+
+Clicking the icon toggles the display of an overlay on the page, which appears over the selected flex container that displays an outline around each flex item:
+
+.. image:: overlay.png
+  :alt: Flexbox overlay showing a flex container and its children
+  :class: center
+
+
+The overlay will still be shown when you select other elements from the Inspector panel, so you can edit related CSS properties and see how the flex items are affected by your changes.
+
+
+The Layout Flex Container section
+---------------------------------
+
+The CSS pane's Layout view includes a collapsible "Flex Container" section. If you expand the section without selecting a flexbox container, it will only display the message, "Select a Flex container or item to continue". Once you select an element whose display is defined as flex, the panel will include a number of options for viewing details about the flex container and flex items within it. You can find out more about those in the section below.
+
+.. note::
+
+  The Layout view can be found underneath the *Layout* tab on the right-hand pane of the Page Inspector. The above and below screenshots should give you further hints on how to get to this.
+
+
+Flex Container options
+**********************
+
+The Flex Container section of the Layout view looks like this:
+
+.. image:: flex-cont.png
+  :alt: Layout pane in Firefox Devtools showing options for the flexbox overlay
+  :class: center
+
+
+There are two settings you can change in the Flex Container section:
+
+
+- You can control the color of the overlay by clicking on the small circle next to the selector. This will toggle a color picker so you can select a different color for the overlay.
+- The switch on the right-hand side of the Flex Container section will also toggle the overlay on and off.
+
+
+Flex item properties
+********************
+
+The flex items within the flex container are displayed as a numbered list in the Flex Items section. Each entry displays the item's selector. Hover over an element to highlight it on the page.
+
+.. image:: flex-items.png
+  :alt: List of flex items displayed in the Layout pane of Firefox Devtools
+  :class: center
+
+If you click on the item, the display shifts to show details about that element:
+
+.. image:: item-details.png
+  :alt: Details of flex item sizing in the Layout pane of Firefox DevTools
+  :class: center
+
+
+This view shows information about the calculations for the size of the selected flex item:
+
+
+- A diagram visualizing the sizing of the flex item
+- Content Size - the size of the component without any restraints imposed on it by its parent
+- Flexibility - how much a flex item grew or shrunk based on its flex-grow value when there is extra free space or its flex-shrink value when there is not enough space
+- Minimum Size (only appears when an item is clamped to its minimum size) - the minimum content size of a flex item when there is no more free space in the flex container
+- Final Size - the size of the flex item after all sizing constraints imposed on it have been applied (based on the values of flex-grow, flex-shrink and flex-basis)
+
+At the top of the section is a drop-down list of all the items in the selected flexbox container:
+
+.. image:: select-items.png
+  :alt: Dropdown in Layout pane that allows you to select between different flex children
+  :class: border
+
+
+You can use this drop-down to select any of the other flex items in the flex container.
diff --git a/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/infobar-both.png b/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/infobar-both.png
new file mode 100644
index 0000000000..90c528d096
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/infobar-both.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/infobar-cont.png b/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/infobar-cont.png
new file mode 100644
index 0000000000..44dda1790e
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/infobar-cont.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/infobar-item.png b/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/infobar-item.png
new file mode 100644
index 0000000000..71b827be14
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/infobar-item.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/item-details.png b/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/item-details.png
new file mode 100644
index 0000000000..05e25aae17
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/item-details.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/overlay.png b/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/overlay.png
new file mode 100644
index 0000000000..048973f54c
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/overlay.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/select-items.png b/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/select-items.png
new file mode 100644
index 0000000000..82b26ab657
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_flexbox_layouts/select-items.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/css-pane.png b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/css-pane.png
new file mode 100644
index 0000000000..39f785c741
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/css-pane.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/extend-lines.png b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/extend-lines.png
new file mode 100644
index 0000000000..32cc8ba968
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/extend-lines.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/grid-named-areas.png b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/grid-named-areas.png
new file mode 100644
index 0000000000..8d488f4a33
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/grid-named-areas.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/grid-options.png b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/grid-options.png
new file mode 100644
index 0000000000..12f2973c6f
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/grid-options.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/grid-overlay.png b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/grid-overlay.png
new file mode 100644
index 0000000000..c039dbdb50
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/grid-overlay.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/html-pane.png b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/html-pane.png
new file mode 100644
index 0000000000..680dbf0f7c
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/html-pane.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/index.rst b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/index.rst
new file mode 100644
index 0000000000..f8ae34c1ea
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/index.rst
@@ -0,0 +1,189 @@
+========================================
+CSS Grid Inspector: Examine grid layouts
+========================================
+
+The **Grid Inspector** allows you to examine `CSS Grid Layouts <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Grid_Layout>`_ using the Firefox DevTools, discovering grids present on a page, examining and modifying them, debugging layout issues, and more.
+
+.. note::
+
+  The examples shown in the screenshots appearing in this article are Jen Simmons' `Futurismo <https://labs.jensimmons.com/2016/examples/futurismo-1.html>`_ and `Variations on a grid <https://labs.jensimmons.com/2017/01-003.html>`_ experiments, and a `live named grid area example <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Grid_Layout/Grid_Template_Areas#naming_a_grid_area>`_ from Rachel Andrew.
+
+
+Discovering CSS grids
+*********************
+
+When an HTML element on your page has `display: grid <https://developer.mozilla.org/en-US/docs/Web/CSS/display>`_ applied to it, a number of features are made available in the DevTools to provide easy access to grid features.
+
+
+In the HTML pane
+----------------
+
+In the :ref:`HTML Pane <page_inspector_ui_tour_html_pane>`, elements laid out using a grid have a "grid" marker beside them.
+
+.. image:: html-pane.png
+  :alt: The HTML pane of the Firefox devtools, showing an element annotated with a grid marker, meaning that it has display: grid set on it
+  :class: border
+
+
+In the CSS pane
+---------------
+
+.. |image1| image:: screen_shot_2016-12-16_at_10.51.15_am.png
+  :width: 20
+
+In the :ref:`CSS pane <page_inspector_ui_tour_rules_view>`'s Rules view, any instance of a `display: grid <https://developer.mozilla.org/en-US/docs/Web/CSS/display>`_ declaration gets a grid icon included within it: |image1|.
+
+.. image:: css-pane.png
+  :alt: The CSS pane of the Firefox devtools, showing the CSS for a grid layout with a grid icon included next to display: grid
+  :class: border
+
+
+Clicking the icon toggles the display of a grid overlay on the page, which appears over the element, laid out like a grid to show the position of its grid lines and tracks:
+
+.. image:: grid-overlay.png
+  :alt: A screenshot of the Firefox web browser, showing a colored overlay on top of a section of the page laid out like a grid
+  :class: border
+
+
+The overlay is still shown when you select other elements, so you can edit related CSS properties and see how the grid is affected.
+
+
+The Layout view Grid section
+----------------------------
+
+When grids are included on a page, the CSS pane's Layout view includes a "Grid" section containing a number of options for viewing those Grids. You can find out more about those in the section below.
+
+.. note::
+
+  The Layout view can be found underneath the *Layout* tab on the right-hand pane of the Page Inspector. The above and below screenshots should give you further hints on how to get to this.
+
+
+Grid options
+************
+
+The Grid section of the Layout view looks like this:
+
+.. image:: grid-options.png
+  :alt: The grid options section of the Firefox devtools Layout view, showing multiple options for specifying how you want to see CSS grids displayed
+  :class: border
+
+
+You'll see a number of options contained within:
+
+
+- Overlay Grid: Contains a checkbox for each grid present on the page, along with various options. Allows overlay views to be toggled on and off.
+- Grid Display Settings:
+
+  - Display line numbers: Turn the line numbers shown for each grid overlay on and off (on by default).
+  - Display area names: Turn area names on and off, in the case of grids with named grid areas (on by default, where relevant).
+  - Extend lines infinitely: By default, grid lines/tracks are only shown inside the element with ``display: grid`` set on it; when toggling this option on, the grid lines extend to the edge of the viewport along each axis.
+
+- Mini grid view: A smaller view of the currently overlaid grid.
+
+
+.. note::
+
+  Your grid preferences such as overlay color and display settings choices are persisted across page loads for each separate page.
+
+Let's examine these features in more detail.
+
+
+Overlay grid
+------------
+
+Each grid present on a page has an entry in the "Overlay grid" section:
+
+.. image:: overlay-grid-entry.png
+  :alt: An entry for a single grid in the Overlay Grid section of the Grid options, showing a grid's name, overlay color, and more.
+  :class: border
+
+Each entry consists of (from left to right):
+
+
+- A checkbox allowing you to toggle the grid overlay for that grid on and off.
+- A name label to represent the grid, consisting of a selector identifying the HTML element that has the grid applied to it. Clicking this also toggles the grid overlay on and off.
+- A target icon that when clicked immediately selects the HTML element that this grid entry relates to, inside the HTML pane.
+- A color picker icon that allows you to change the primary color of the grid overlay. This is useful for selecting different colors so you can easily tell your grids apart.
+
+
+Inspecting a subgrid
+--------------------
+
+When the page contains a grid with a subgrid, the entry for the subgrid is indented under its parent in the Overlay grid section. When you select the checkbox for the subgrid, the lines for the parent grid are displayed also displayed; if the checkbox for the parent grid is unselected, then its lines are translucent.
+
+.. image:: subgrid-lines.png
+  :alt: Screenshot showing the overlay lines for a subgrid, with the subgrid lines and parent grid lines called out.
+  :class: center
+
+
+Display line numbers
+--------------------
+
+By default, the line numbers are displayed on the grid overlay.
+
+.. image:: line-numbers.png
+  :alt: A CSS grid overlay with grid line numbers displayed
+  :class: border
+
+
+Unchecking the "Display line numbers" box turns them off.
+
+.. image:: no-line-numbers.png
+  :alt: A CSS grid overlay with grid line numbers not displayed
+  :class: border
+
+
+Display area names
+------------------
+
+In a grid with named areas, the area names are shown on the grid overlay by default.
+
+.. image:: grid-named-areas.png
+  :alt: A CSS grid overlay with named area names displayed
+  :class: border
+
+Unchecking the "Display area names" box turns them off.
+
+.. image:: no-grid-named-areas.png
+  :alt: A CSS grid overlay with named area names not displayed
+  :class: border
+
+
+Extend lines infinitely
+-----------------------
+
+By default, the grid lines/tracks are only shown inside the element with ``display: grid`` set on it.
+
+.. image:: no-extend-lines.png
+  :alt: A CSS grid overlay with grid lines not extended infinitely
+  :class: border
+
+When you check the "Extend lines infinitely" option, the grid lines extend to the edge of the viewport along each axis.
+
+.. image:: extend-lines.png
+  :alt: A CSS grid overlay with grid lines extended infinitely
+  :class: border
+
+
+Mini grid view
+--------------
+
+Shows a small version of the currently overlaid grid, which is in proportion to the real thing.
+
+.. image:: mini-grid-view.png
+  :alt: A mini CSS grid view from the Firefox DevTools
+  :class: border
+
+Hovering over the different areas of the mini grid causes the equivalent area on the grid overlay to also highlight, along with a tooltip containing useful information such as the dimensions of that area, its row and column numbers, etc.
+
+.. image:: mini-grid-highlight.png
+  :alt: A firefox screenshot showing an area of a mini CSS grid being highlighted in the DevTools, and the corresponding area in the real grid being highlighted on the web page.
+  :class: border
+
+
+See also
+********
+
+- `labs.jensimmons.com <https://labs.jensimmons.com/>`_ — lots of interesting grid examples.
+- `Grid by Example <https://gridbyexample.com/>`_ — CSS Grid learning resources from Rachel Andrew.
+- `CSS Grid Layout <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Grid_Layout>`_ — MDN CSS Grid Layout references and tutorials.
diff --git a/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/line-numbers.png b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/line-numbers.png
new file mode 100644
index 0000000000..7ee2f66af1
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/line-numbers.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/mini-grid-highlight.png b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/mini-grid-highlight.png
new file mode 100644
index 0000000000..52b6c6cbfd
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/mini-grid-highlight.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/mini-grid-view.png b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/mini-grid-view.png
new file mode 100644
index 0000000000..3b183a30f2
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/mini-grid-view.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/no-extend-lines.png b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/no-extend-lines.png
new file mode 100644
index 0000000000..60fef3b1ce
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/no-extend-lines.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/no-grid-named-areas.png b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/no-grid-named-areas.png
new file mode 100644
index 0000000000..7663001908
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/no-grid-named-areas.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/no-line-numbers.png b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/no-line-numbers.png
new file mode 100644
index 0000000000..0f7eeacb00
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/no-line-numbers.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/overlay-grid-entry.png b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/overlay-grid-entry.png
new file mode 100644
index 0000000000..3362f2577d
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/overlay-grid-entry.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/screen_shot_2016-12-16_at_10.51.15_am.png b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/screen_shot_2016-12-16_at_10.51.15_am.png
new file mode 100644
index 0000000000..1ab8f708fa
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/screen_shot_2016-12-16_at_10.51.15_am.png
diff --git a/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/subgrid-lines.png b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/subgrid-lines.png
new file mode 100644
index 0000000000..ba95af74dc
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/examine_grid_layouts/subgrid-lines.png
diff --git a/devtools/docs/user/page_inspector/how_to/index.rst b/devtools/docs/user/page_inspector/how_to/index.rst
new file mode 100644
index 0000000000..07b4fd5a8a
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/index.rst
@@ -0,0 +1,26 @@
+======
+How to
+======
+
+Links for various HOW TO's can be found here. These links describe in depth the HOW TO techniques.
+
+
+- :doc:`CSS Flexbox Inspector: Examine Flexbox layouts <examine_flexbox_layouts/index>`
+- :doc:`CSS Grid Inspector: Examine grid layouts <examine_grid_layouts/index>`
+- :doc:`Debug scrollable overflow <debug_scrollable_overflow/index>`
+- :doc:`Edit CSS filters <edit_css_filters/index>`
+- :doc:`Edit Shape Paths in CSS <edit_css_shapes/index>`
+- :doc:`Edit fonts <edit_fonts/index>`
+- :doc:`Examine Event Listeners <examine_event_listeners/index>`
+- :doc:`Examine and edit CSS <examine_and_edit_css/index>`
+- :doc:`Examine and edit HTML <examine_and_edit_html/index>`
+- :doc:`Examine and edit the box model <examine_and_edit_the_box_model/index>`
+- :doc:`Inspect and select colors <inspect_and_select_colors/index>`
+- :doc:`Open the Inspector <open_the_inspector/index>`
+- :doc:`Reposition elements in the page <reposition_elements_in_the_page/index>`
+- :doc:`Select an element <select_an_element/index>`
+- :doc:`Select and highlight elements <select_and_highlight_elements/index>`
+- :doc:`Use the Inspector from the Web Console <use_the_inspector_from_the_web_console/index>`
+- :doc:`View background images <view_background_images/index>`
+- :doc:`Visualize transforms <visualize_transforms/index>`
+- :doc:`Work with animations <work_with_animations/index>`
diff --git a/devtools/docs/user/page_inspector/how_to/inspect_and_select_colors/color-picker-bad-contrast.png b/devtools/docs/user/page_inspector/how_to/inspect_and_select_colors/color-picker-bad-contrast.png
new file mode 100644
index 0000000000..237cedfd2f
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/inspect_and_select_colors/color-picker-bad-contrast.png
diff --git a/devtools/docs/user/page_inspector/how_to/inspect_and_select_colors/color-picker-good-contrast.png b/devtools/docs/user/page_inspector/how_to/inspect_and_select_colors/color-picker-good-contrast.png
new file mode 100644
index 0000000000..56f47743ca
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/inspect_and_select_colors/color-picker-good-contrast.png
diff --git a/devtools/docs/user/page_inspector/how_to/inspect_and_select_colors/css_color_vars.png b/devtools/docs/user/page_inspector/how_to/inspect_and_select_colors/css_color_vars.png
new file mode 100644
index 0000000000..49701dd100
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/inspect_and_select_colors/css_color_vars.png
diff --git a/devtools/docs/user/page_inspector/how_to/inspect_and_select_colors/index.rst b/devtools/docs/user/page_inspector/how_to/inspect_and_select_colors/index.rst
new file mode 100644
index 0000000000..e521ef3947
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/inspect_and_select_colors/index.rst
@@ -0,0 +1,31 @@
+=========================
+Inspect and select colors
+=========================
+
+In the CSS Pane's :ref:`Rules view <page_inspector_ui_tour_rules_view>`, if a rule contains a color value, you'll see a sample of the color next to the value:
+
+.. image:: inspector-css-color-swatch.png
+
+A color sample is also shown for CSS custom properties (variables) that represent colors.
+
+.. image:: css_color_vars.png
+  :alt: CSS in the Rules pane showing a color swatch on a CSS variable
+  :class: border
+
+If you click on the color sample, you'll see a color picker popup, enabling you to change the color:
+
+.. image:: color-picker-good-contrast.png
+  :alt: Color picker showing a case of good contrast with the background
+
+.. image:: color-picker-bad-contrast.png
+  :alt: Color picker showing a case of poor contrast" src="color-picker-bad-contrast.png
+
+If the color is a foreground color, the color picker tells you whether its contrast with the background color meets accessibility guidelines. Hovering the mouse over the contrast message gives a more detailed explanation.
+
+The color picker includes an eyedropper icon: clicking this icon enables you to use the eyedropper to select a new color for the element from the page:
+
+.. raw:: html
+
+  <iframe width="560" height="315" src="https://www.youtube.com/embed/0Zx1TN21QOo" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+  <br/>
+  <br/>
diff --git a/devtools/docs/user/page_inspector/how_to/inspect_and_select_colors/inspector-css-color-swatch.png b/devtools/docs/user/page_inspector/how_to/inspect_and_select_colors/inspector-css-color-swatch.png
new file mode 100644
index 0000000000..742a25678d
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/inspect_and_select_colors/inspector-css-color-swatch.png
diff --git a/devtools/docs/user/page_inspector/how_to/open_the_inspector/index.rst b/devtools/docs/user/page_inspector/how_to/open_the_inspector/index.rst
new file mode 100644
index 0000000000..4e8fac602b
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/open_the_inspector/index.rst
@@ -0,0 +1,32 @@
+==================
+Open the Inspector
+==================
+
+There are two main ways to open the Inspector:
+
+- Select the *Inspector* panel in the Web Developer Tools, accessible from the Browser Tools submenu
+- Right-click an element on a web page and select *Inspect Element*.
+
+
+The Inspector will appear at the bottom of the browser window:
+
+.. image:: pageinspector.png
+  :alt: The all-new Inspector in Firefox 57 DevTools.
+  :class: center
+
+You can also set the pane to appear at the left side of the browser window:
+
+.. image:: inspector_leftside.png
+  :class: center
+
+To the right side of the browser window:
+
+.. image:: inspector_rightside.png
+  :class: center
+
+Or in a separate window:
+
+.. image:: inspector_sidexside.png
+  :class: center
+
+To start finding your way around the Inspector, see the :doc:`UI tour <../../ui_tour/index>`.
diff --git a/devtools/docs/user/page_inspector/how_to/open_the_inspector/inspector_leftside.png b/devtools/docs/user/page_inspector/how_to/open_the_inspector/inspector_leftside.png
new file mode 100644
index 0000000000..be76e2862c
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/open_the_inspector/inspector_leftside.png
diff --git a/devtools/docs/user/page_inspector/how_to/open_the_inspector/inspector_rightside.png b/devtools/docs/user/page_inspector/how_to/open_the_inspector/inspector_rightside.png
new file mode 100644
index 0000000000..187bd6f3c6
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/open_the_inspector/inspector_rightside.png
diff --git a/devtools/docs/user/page_inspector/how_to/open_the_inspector/inspector_sidexside.png b/devtools/docs/user/page_inspector/how_to/open_the_inspector/inspector_sidexside.png
new file mode 100644
index 0000000000..f8d8f079d4
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/open_the_inspector/inspector_sidexside.png
diff --git a/devtools/docs/user/page_inspector/how_to/open_the_inspector/pageinspector.png b/devtools/docs/user/page_inspector/how_to/open_the_inspector/pageinspector.png
new file mode 100644
index 0000000000..a43b0d71e9
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/open_the_inspector/pageinspector.png
diff --git a/devtools/docs/user/page_inspector/how_to/reposition_elements_in_the_page/box-model-reposition.png b/devtools/docs/user/page_inspector/how_to/reposition_elements_in_the_page/box-model-reposition.png
new file mode 100644
index 0000000000..5df8f12024
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/reposition_elements_in_the_page/box-model-reposition.png
diff --git a/devtools/docs/user/page_inspector/how_to/reposition_elements_in_the_page/in-content-box-model-editing.png b/devtools/docs/user/page_inspector/how_to/reposition_elements_in_the_page/in-content-box-model-editing.png
new file mode 100644
index 0000000000..ba5e561554
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/reposition_elements_in_the_page/in-content-box-model-editing.png
diff --git a/devtools/docs/user/page_inspector/how_to/reposition_elements_in_the_page/index.rst b/devtools/docs/user/page_inspector/how_to/reposition_elements_in_the_page/index.rst
new file mode 100644
index 0000000000..80c3af6910
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/reposition_elements_in_the_page/index.rst
@@ -0,0 +1,20 @@
+===============================
+Reposition elements in the page
+===============================
+
+Starting in Firefox 48 you can move absolutely positioned elements by dragging them around the page.
+
+If an element has its `position <https://developer.mozilla.org/en-US/docs/Web/CSS/position>`_ property set to ``absolute``, ``relative`` or ``fixed`` and one or more of the `top <https://developer.mozilla.org/en-US/docs/Web/CSS/top>`_, `bottom <https://developer.mozilla.org/en-US/docs/Web/CSS/bottom>`_ , `left <https://developer.mozilla.org/en-US/docs/Web/CSS/left>`_ or `right <https://developer.mozilla.org/en-US/docs/Web/CSS/right>`_ properties, :ref:`Box Model view <page_inspector_ui_tour_computed_view>` displays a button:
+
+.. image:: box-model-reposition.png
+  :class: center
+
+If you click that button, two handles appear next to the element:
+
+.. image:: in-content-box-model-editing.png
+  :alt: Example for changing the position of an element within the content
+  :class: center
+
+You can use these handles to drag the element around the page.
+
+If the element is absolutely positioned, dashed lines are shown representing the offset parent. For relatively positioned elements the dashed lines indicate the original position of the node. The offsets are indicated by a line and a tooltip for each side.
diff --git a/devtools/docs/user/page_inspector/how_to/select_an_element/index.rst b/devtools/docs/user/page_inspector/how_to/select_an_element/index.rst
new file mode 100644
index 0000000000..b6cfe9fba1
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/select_an_element/index.rst
@@ -0,0 +1,37 @@
+=================
+Select an element
+=================
+
+The *selected element* is the element in the page that the Inspector is currently focused on. The selected element is shown in the :ref:`HTML pane <page_inspector_ui_tour_html_pane>` and its CSS is displayed in the :doc:`CSS pane <../../ui_tour/index>`.
+
+The *highlighted element* is the element that's overlaid in the page with a graphic showing the box model, and a tooltip showing its tag and size:
+
+.. image:: inspector-highlighted.png
+  :class: center
+
+
+With the context menu
+*********************
+
+To open the Inspector and select an element immediately, activate the context menu over the element in the page and select "Inspect Element"
+
+
+With the HTML pane
+******************
+
+When the inspector is open, as you move the mouse around the elements listed in the HTML pane, the corresponding elements are highlighted in the page. Click an element in the HTML pane to select it.
+
+You can also use the arrow keys to move around the DOM with the keyboard.
+
+
+.. _page-inspector-how-to-select-an-element-with-the-node-picker:
+
+With the node picker
+********************
+
+.. |image1| image:: node-picker.png
+  :width: 20
+
+To select an element in the page itself, activate the "node picker" by clicking its icon: |image1| (also called the *Select Element* icon). After that, as you move the mouse around the page, the element under the mouse is highlighted. Click the element to select it:
+
+Starting in Firefox 52, if you :kbd:`Shift` + click the element, then it is selected but the picker stays active. This lets you see the rules for the element in the CSS pane, but conveniently select another element in the page.
diff --git a/devtools/docs/user/page_inspector/how_to/select_an_element/inspector-highlighted.png b/devtools/docs/user/page_inspector/how_to/select_an_element/inspector-highlighted.png
new file mode 100644
index 0000000000..2afa672cb5
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/select_an_element/inspector-highlighted.png
diff --git a/devtools/docs/user/page_inspector/how_to/select_an_element/node-picker.png b/devtools/docs/user/page_inspector/how_to/select_an_element/node-picker.png
new file mode 100644
index 0000000000..b1f86488b8
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/select_an_element/node-picker.png
diff --git a/devtools/docs/user/page_inspector/how_to/select_and_highlight_elements/index.rst b/devtools/docs/user/page_inspector/how_to/select_and_highlight_elements/index.rst
new file mode 100644
index 0000000000..e24dd5121d
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/select_and_highlight_elements/index.rst
@@ -0,0 +1,33 @@
+=============================
+Select and highlight elements
+=============================
+
+The *selected* element is the element in the page that the Inspector is currently focused on. The selected element is shown in the :ref:`HTML pane <page_inspector_ui_tour_html_pane>` and its CSS is displayed in the :doc:`CSS pane <../../ui_tour/index>`.
+
+The *highlighted* element is the element that's overlaid in the page with a graphic showing the box model, and a tooltip showing its tag and size:
+
+.. image:: inspector-highlighted.png
+  :class: center
+
+
+With the context menu
+*********************
+
+To open the Inspector and select an element immediately, activate the context menu over the element in the page and select "Inspect Element"
+
+
+With the HTML pane
+******************
+
+When the inspector is open, as you move the mouse around the elements listed in the HTML pane, the corresponding elements are highlighted in the page. Click an element in the HTML pane to select it
+
+You can also use the arrow keys to move around the DOM with the keyboard.
+
+
+With the node picker
+********************
+
+.. |image1| image:: node-picker.png
+  :width: 20
+
+To select an element in the page itself, activate the "node picker" by clicking its icon: |image1| (also called the *Select Element* icon). After that, as you move the mouse around the page, the element under the mouse is highlighted. Click the element to select it:
diff --git a/devtools/docs/user/page_inspector/how_to/select_and_highlight_elements/inspector-highlighted.png b/devtools/docs/user/page_inspector/how_to/select_and_highlight_elements/inspector-highlighted.png
new file mode 100644
index 0000000000..2afa672cb5
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/select_and_highlight_elements/inspector-highlighted.png
diff --git a/devtools/docs/user/page_inspector/how_to/select_and_highlight_elements/node-picker.png b/devtools/docs/user/page_inspector/how_to/select_and_highlight_elements/node-picker.png
new file mode 100644
index 0000000000..b1f86488b8
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/select_and_highlight_elements/node-picker.png
diff --git a/devtools/docs/user/page_inspector/how_to/use_the_inspector_from_the_web_console/console-$0.png b/devtools/docs/user/page_inspector/how_to/use_the_inspector_from_the_web_console/console-$0.png
new file mode 100644
index 0000000000..9ce705cfbe
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/use_the_inspector_from_the_web_console/console-$0.png
diff --git a/devtools/docs/user/page_inspector/how_to/use_the_inspector_from_the_web_console/console-highlight.png b/devtools/docs/user/page_inspector/how_to/use_the_inspector_from_the_web_console/console-highlight.png
new file mode 100644
index 0000000000..35bcda498b
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/use_the_inspector_from_the_web_console/console-highlight.png
diff --git a/devtools/docs/user/page_inspector/how_to/use_the_inspector_from_the_web_console/index.rst b/devtools/docs/user/page_inspector/how_to/use_the_inspector_from_the_web_console/index.rst
new file mode 100644
index 0000000000..b3a015dbba
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/use_the_inspector_from_the_web_console/index.rst
@@ -0,0 +1,13 @@
+======================================
+Use the Inspector from the Web Console
+======================================
+
+The element that's currently selected in the Page Inspector can be referenced in the Web Console using the variable ``$0``.
+
+.. image:: console-$0.png
+  :class: center
+
+DOM elements in the Web Console output get a target next to them. If you hover over this target, the element is highlighted in the page, and if you click the target, the element is selected in the Inspector:
+
+.. image:: console-highlight.png
+  :class: center
diff --git a/devtools/docs/user/page_inspector/how_to/view_background_images/css-copy-image-data-url.png b/devtools/docs/user/page_inspector/how_to/view_background_images/css-copy-image-data-url.png
new file mode 100644
index 0000000000..461d442e4d
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/view_background_images/css-copy-image-data-url.png
diff --git a/devtools/docs/user/page_inspector/how_to/view_background_images/css-image-preview.png b/devtools/docs/user/page_inspector/how_to/view_background_images/css-image-preview.png
new file mode 100644
index 0000000000..14d0109f24
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/view_background_images/css-image-preview.png
diff --git a/devtools/docs/user/page_inspector/how_to/view_background_images/index.rst b/devtools/docs/user/page_inspector/how_to/view_background_images/index.rst
new file mode 100644
index 0000000000..ae2a72aadd
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/view_background_images/index.rst
@@ -0,0 +1,14 @@
+======================
+View background images
+======================
+
+In the :ref:`Rules view <page_inspector_ui_tour_rules_view>`, you can see a preview of images specified using `background-image <https://developer.mozilla.org/en-US/docs/Web/CSS/background-image>`_. Just hover over the rule:
+
+.. image:: css-image-preview.png
+  :class: center
+
+
+From Firefox 41, if you right-click the image declaration, you'll see an option to copy the image as a data: URL:
+
+.. image:: css-copy-image-data-url.png
+  :class: center
diff --git a/devtools/docs/user/page_inspector/how_to/visualize_transforms/index.rst b/devtools/docs/user/page_inspector/how_to/visualize_transforms/index.rst
new file mode 100644
index 0000000000..46eb500581
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/visualize_transforms/index.rst
@@ -0,0 +1,8 @@
+====================
+Visualize transforms
+====================
+
+If you hover over a `transform <https://developer.mozilla.org/en-US/docs/Web/CSS/transform>`_ property in the :ref:`Rules view <page_inspector_ui_tour_rules_view>`, you'll see the transformation overlaid in the page:
+
+.. image:: transform.png
+  :class: center
diff --git a/devtools/docs/user/page_inspector/how_to/visualize_transforms/transform.png b/devtools/docs/user/page_inspector/how_to/visualize_transforms/transform.png
new file mode 100644
index 0000000000..e11bba7292
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/visualize_transforms/transform.png
diff --git a/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_details.png b/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_details.png
new file mode 100644
index 0000000000..1e6e934fae
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_details.png
diff --git a/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_icon_details.png b/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_icon_details.png
new file mode 100644
index 0000000000..ef3fdd74c7
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_icon_details.png
diff --git a/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_icon_scale.png b/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_icon_scale.png
new file mode 100644
index 0000000000..44a5dbb37a
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_icon_scale.png
diff --git a/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_inspector_(firefox_41_and_42)/index.rst b/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_inspector_(firefox_41_and_42)/index.rst
new file mode 100644
index 0000000000..1299bca57c
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_inspector_(firefox_41_and_42)/index.rst
@@ -0,0 +1,25 @@
+=======================================
+Animation inspector (Firefox 41 and 42)
+=======================================
+
+.. note::
+  Note that the Animation inspector's UI was revamped in Firefox 43. To see what the Animation inspector looks like in Firefox 43 and subsequent releases, see :ref:`the main "Work with animations" page <page-inspector-how-to-work-with-animations-animation-inspector>`.
+
+
+The Animation inspector enables you to:
+
+
+- see information about all animations running in the page
+- play/pause all animations
+- play/pause/rewind/fast-forward each animation
+- jump to a specific point in an animation
+- highlight and inspect the animated node
+- adjust the playback rate of each animation
+- see whether an animation is running in the compositor thread (a lightning bolt icon is displayed next to such animations)
+
+
+.. raw:: html
+
+  <iframe width="560" height="315" src="https://www.youtube.com/embed/0vSIuKaqD8o" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+  <br/>
+  <br/>
diff --git a/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_inspector_example_colon__css_transitions/developer.png b/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_inspector_example_colon__css_transitions/developer.png
new file mode 100644
index 0000000000..331428f162
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_inspector_example_colon__css_transitions/developer.png
diff --git a/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_inspector_example_colon__css_transitions/index.rst b/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_inspector_example_colon__css_transitions/index.rst
new file mode 100644
index 0000000000..a4bd7bea2d
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_inspector_example_colon__css_transitions/index.rst
@@ -0,0 +1,93 @@
+============================================
+Animation inspector example: CSS transitions
+============================================
+
+Firefox Logo Animation
+**********************
+
+Example animation using `CSS transitions <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Transitions/Using_CSS_transitions>`_.
+
+HTML Content
+------------
+
+.. code-block:: html
+
+  <div class="channel">
+    <img src="developer.png" class="icon"/>
+    <span class="note">Firefox Developer Edition</span>
+  </div>
+
+
+CSS Content
+-----------
+
+.. code-block:: css
+
+  .channel {
+    padding: 2em;
+    margin: 0.5em;
+    box-shadow: 1px 1px 5px #808080;
+    margin: 1.5em;
+  }
+
+  .channel > * {
+    vertical-align: middle;
+    line-height: normal;
+  }
+
+  .icon {
+    width: 50px;
+    height: 50px;
+    filter: grayscale(100%);
+    transition: transform 750ms ease-in, filter 750ms ease-in-out;
+  }
+
+  .note {
+    margin-left: 1em;
+    font: 1.5em "Open Sans",Arial,sans-serif;
+    overflow: hidden;
+    white-space: nowrap;
+    display: inline-block;
+
+    opacity: 0;
+    width: 0;
+    transition: opacity 500ms 150ms, width 500ms 150ms;
+  }
+
+  .icon#selected {
+    filter: grayscale(0%);
+    transform: scale(1.5);
+  }
+
+  .icon#selected+span {
+    opacity: 1;
+    width: 300px;
+  }
+
+
+JavaScript Content
+------------------
+
+.. code-block:: JavaScript
+
+  function toggleSelection(e) {
+    if (e.button != 0) {
+      return;
+    }
+    if (e.target.classList.contains("icon")) {
+      var wasSelected = (e.target.getAttribute("id") == "selected");
+      clearSelection();
+      if (!wasSelected) {
+        e.target.setAttribute("id", "selected");
+      }
+    }
+  }
+
+  function clearSelection() {
+    var selected = document.getElementById("selected");
+    if (selected) {
+      selected.removeAttribute("id");
+    }
+  }
+
+  document.addEventListener("click", toggleSelection);
diff --git a/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_inspector_example_colon__web_animations_api/developer.png b/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_inspector_example_colon__web_animations_api/developer.png
new file mode 100644
index 0000000000..331428f162
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_inspector_example_colon__web_animations_api/developer.png
diff --git a/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_inspector_example_colon__web_animations_api/index.rst b/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_inspector_example_colon__web_animations_api/index.rst
new file mode 100644
index 0000000000..6d6f2cb045
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_inspector_example_colon__web_animations_api/index.rst
@@ -0,0 +1,117 @@
+===============================================
+Animation inspector example: Web Animations API
+===============================================
+
+Firefox Logo Animation
+**********************
+
+Example animation using the `Web Animations API <https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API>`_.
+
+
+HTML Content
+------------
+
+.. code-block:: html
+
+  <div class="channel">
+    <img src="developer.png" id="icon"/>
+    <span id="note">Firefox Developer Edition</span>
+  </div>
+
+
+CSS Content
+-----------
+
+.. code-block:: css
+
+  .channel {
+    padding: 2em;
+    margin: 0.5em;
+    box-shadow: 1px 1px 5px #808080;
+    margin: 1.5em;
+  }
+
+  .channel > * {
+    vertical-align: middle;
+    line-height: normal;
+  }
+
+  #icon {
+    width: 50px;
+    height: 50px;
+    filter: grayscale(100%);
+  }
+
+  #note {
+    margin-left: 1em;
+    font: 1.5em "Open Sans",Arial,sans-serif;
+    overflow: hidden;
+    white-space: nowrap;
+    display: inline-block;
+    opacity: 0;
+    width: 0;
+  }
+
+
+.. _page-inspector-work-with-animations-web-example-js-content:
+
+JavaScript Content
+------------------
+
+.. code-block:: JavaScript
+
+  var iconKeyframeSet = [
+    { transform: 'scale(1)', filter: 'grayscale(100%)'},
+    { filter:  'grayscale(100%)', offset: 0.333},
+    { transform: 'scale(1.5)', offset: 0.666 },
+    { transform: 'scale(1.5)', filter: 'grayscale(0%)'}
+  ];
+
+  var noteKeyframeSet = [
+    { opacity: '0', width: '0'},
+    { opacity: '1', width: '300px'}
+  ];
+
+  var iconKeyframeOptions = {
+    duration: 750,
+    fill: 'forwards',
+    easing: 'ease-in',
+    endDelay: 100
+  }
+
+  var noteKeyframeOptions = {
+    duration: 500,
+    fill: 'forwards',
+    easing: 'ease-out',
+    delay: 150
+  }
+
+  var icon = document.getElementById("icon");
+  var note = document.getElementById("note");
+
+  var iconAnimation = icon.animate(iconKeyframeSet, iconKeyframeOptions);
+  var noteAnimation = note.animate(noteKeyframeSet, noteKeyframeOptions);
+
+  iconAnimation.pause();
+  noteAnimation.pause();
+
+  var firstTime = true;
+
+  function animateChannel(e) {
+   if (e.button != 0) {
+   return;
+   }
+    if (e.target.id != "icon") {
+      return;
+    }
+    if (firstTime) {
+      iconAnimation.play();
+      noteAnimation.play();
+      firstTime = false;
+    } else {
+      iconAnimation.reverse();
+      noteAnimation.reverse();
+    }
+  }
+
+  document.addEventListener("click", animateChannel);
diff --git a/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_not_optimized.png b/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_not_optimized.png
new file mode 100644
index 0000000000..9105060404
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_not_optimized.png
diff --git a/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_pane.png b/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_pane.png
new file mode 100644
index 0000000000..02fe47b31e
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_pane.png
diff --git a/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_swoosh_01.png b/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_swoosh_01.png
new file mode 100644
index 0000000000..ea91cc8756
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/work_with_animations/animation_swoosh_01.png
diff --git a/devtools/docs/user/page_inspector/how_to/work_with_animations/compositor.png b/devtools/docs/user/page_inspector/how_to/work_with_animations/compositor.png
new file mode 100644
index 0000000000..ec9f9a4789
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/work_with_animations/compositor.png
diff --git a/devtools/docs/user/page_inspector/how_to/work_with_animations/index.rst b/devtools/docs/user/page_inspector/how_to/work_with_animations/index.rst
new file mode 100644
index 0000000000..215a86a318
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/work_with_animations/index.rst
@@ -0,0 +1,227 @@
+====================
+Work with animations
+====================
+
+This article covers three tools you can use to visualize and edit animations:
+
+
+- :ref:`the animation inspector <page-inspector-how-to-work-with-animations-animation-inspector>`
+
+- :ref:`diting @keyframes <page-inspector-how-to-work-with-animations-edit-keyframes>`
+
+- :ref:`editing timing functions <page-inspector-how-to-work-with-animations-edit-timing-functions>`
+
+
+.. _page-inspector-how-to-work-with-animations-animation-inspector:
+
+Animation inspector
+*******************
+
+The Page Inspector's :ref:`Animations view <page_inspector_ui_tour_animations_view>` displays animations in the page synchronized along a timeline, with a draggable widget you can use to move to any point in the timeline and see the page at that point.
+
+It displays animations created using `CSS transitions <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Transitions>`_, `CSS @keyframes rules <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Animations/Using_CSS_animations>`_, or the `Web Animations API <https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API>`_. Starting in Firefox 48, it will show animations applied to the `::before <https://developer.mozilla.org/en-US/docs/Web/CSS/::before>`_ and `::after <https://developer.mozilla.org/en-US/docs/Web/CSS/::after>`_ pseudo-elements.
+
+To see how it works, we'll walk through an example. The box below contains a grayscale icon, representing `Firefox Developer Edition <https://www.mozilla.org/en-US/firefox/developer/>`_. If you click the icon, it enlarges and changes to color, and the name of the browser appears. Click the icon again to reverse the effect.
+
+
+These animations are made using the `Web Animations API <https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API>`_.
+
+Let's use the animation inspector to see what's going on in this example.
+
+
+1. Right-click in the box and select "Inspect Element"
+2. Make sure the selected element is the ``<div class="channel">``
+3. Switch over to the "Animations" tab
+4. Play the animation
+
+
+.. raw:: html
+
+  <iframe width="560" height="315" src="https://www.youtube.com/embed/XmKeAKryE5I" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+  <br/>
+  <br/>
+
+
+Let's take a closer look at the contents of the animation inspector here:
+
+.. image:: animation_pane.png
+  :class: border
+
+
+It shows a synchronized timeline for every animation applied to the selected element or its children. The timeline starts at the start of the first animation, ends at the end of the last animation, and is labeled with markers every 250 milliseconds (this depends on the time scale of the animations currently displayed).
+
+
+Animation bars
+--------------
+
+Each animation or transition is shown as a horizontal bar laid across the timeline. The bar is:
+
+
+- blue if a `transition <https://developer.mozilla.org/en-US/docs/Web/CSS/transition>`_) was used to animate a property
+- orange if a `@keyframes animation <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Animations/Using_CSS_animations>`_ was used
+- green if the `Web Animations API <https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API>`_ was used
+
+.. |image1| image:: compositor.png
+  :width: 20
+
+The bar contains a lightning bolt icon |image1| if the property was animated using the compositor thread (see more about the :ref:`cost of animating different CSS properties <performance-scenarios-animating_css_properties-css-property-cost>`).
+
+The bar is shaped to reflect the easing effect used for the animation. In the example above you can see that the first bar is concave, representing ease-in, and the second is convex, representing ease-out.
+
+If the animation used CSS transitions, there is one bar for each property transitioned, and it is labeled with the name of the property being transitioned. If the animation used CSS ``@keyframes``, there is one bar for each animation, labeled with its name.
+
+If the animation or transition had a delay, this is shown as a cross-hatched portion of the bar. `delay and endDelay <https://developer.mozilla.org/en-US/docs/Web/API/KeyframeEffect/KeyframeEffect>`_ are both represented.
+
+If you hover over the bar, a tooltip appears, giving you more detailed information about the animation or transition, including:
+
+
+- the type of animation: CSS transition, CSS animation, or Web Animations API
+- the duration of the animation
+- the animation's start and end delay
+- the animation's easing (or timing function).
+- the animation's fill
+- the Playback rate of the animation
+
+
+.. image:: animation_details.png
+  :class: border
+
+
+Information about the animated element
+--------------------------------------
+
+To the left of each bar is a selector for the element that the animation applies to. If you hover over this selector, the element is highlighted in the page. Click the selector to select the element in the inspector.
+
+.. |image2| image:: target-icon.png
+
+To the left of the selector is a "target" icon (|image2|). Clicking this icon locks the highlighter on the element.
+
+
+Animation details
+-----------------
+
+If you click one of the bars, you'll see details of all the properties that were changed in the animation. For example, try clicking on the bar for ``img#icon`` animation:
+
+.. image:: animation_icon_details.png
+  :class: border
+
+
+This is telling us that two properties were modified: `filter <https://developer.mozilla.org/en-US/docs/Web/CSS/filter>`_ and `transform <https://developer.mozilla.org/en-US/docs/Web/CSS/transform>`_. Each dot represents an entry for that property in the set of keyframes used for the animation. Both properties were initialized at 0ms and finalized at 750ms. ``filter`` was given a value at 250ms and ``transform`` at 500ms. If you hover over a dot, you'll see the value assigned to that property at that point in the timeline:
+
+.. image:: animation_icon_scale.png
+  :class: border
+
+
+This is essentially a visual representation of the animation's
+:ref:`keyframes <page-inspector-work-with-animations-web-example-js-content>`:
+
+.. code-block:: JavaScript
+
+  var iconKeyframeSet = [
+    { transform: 'scale(1)',   filter: 'grayscale(100%)'                },
+    {                          filter: 'grayscale(100%)', offset: 0.333 },
+    { transform: 'scale(1.5)',                            offset: 0.666 },
+    { transform: 'scale(1.5)', filter: 'grayscale(0%)'                  }
+  ];
+
+
+Application to the example
+--------------------------
+
+Applying all this to our example, we can see that:
+
+
+- The animation involved two elements, ``span#note`` and ``img#icon``. Hovering over these selectors, we can see that those elements are, respectively, the browser name "Firefox Developer Edition" and the browser icon.
+- The ``img#icon`` animation:
+
+  - animated the `filter <https://developer.mozilla.org/en-US/docs/Web/CSS/filter>`_ and `transform <https://developer.mozilla.org/en-US/docs/Web/CSS/transform>`_ properties, to scale the icon and color it
+  - lasted 750ms, had an ``endDelay`` of 100ms
+  - used the compositor thread
+  - was given an `easing <https://developer.mozilla.org/en-US/docs/Web/API/KeyframeEffect/KeyframeEffect>`_ value of ``ease-in``: you can see this by the concave shape of the green bar.
+
+- The ``span#note`` animation:
+
+  - animated the `width <https://developer.mozilla.org/en-US/docs/Web/CSS/width>`_ and `opacity <https://developer.mozilla.org/en-US/docs/Web/CSS/opacity>`_ properties, to make the name gradually appear
+  - lasted 500ms, and had a ``delay`` of 150ms
+  - was given an `easing <https://developer.mozilla.org/en-US/docs/Web/API/KeyframeEffect/KeyframeEffect>`_ value of ``ease-out``: you can see this by the convex shape of the green bar.
+
+
+Animation playback
+------------------
+
+At the top of the animation inspector:
+
+
+- there are buttons to play/pause and restart the animation
+- there's a dropdown to change the animation playback rate
+- the current time in the animation is displayed.
+
+
+Finally, if you click inside the bar at the top of the timeline, you get a scrubber that you can drag left and right to move backwards and forwards through the animation, and pinpoint exactly what's happening when.
+
+
+Further information about animation compositing
+-----------------------------------------------
+
+If you open `animation-inspector-compositing.html <https://firefox-devtools.github.io/devtools-examples/animation-inspector/animation-inspector-compositing.html>`_ and click the red rectangle, a simple `opacity <https://developer.mozilla.org/en-US/docs/Web/CSS/opacity>`_ animation will start. If you look at this in the Animation Inspector in Firefox 49+, you'll see that:
+
+
+- The white lightning bolt icon now indicates whether all the animation properties have been optimized by running them through the compositor, where possible.
+- The bar tooltip also includes this information, as a further reminder. You'll get a message of "All animation properties are optimized."
+- The expanded animation information now includes a lightning bolt icon next to the properties whose animation has been optimized via the compositor.
+
+
+.. image:: animation_swoosh_01.png
+  :class: border
+
+Let's now look at `animation-inspector-compositing-silly.html <https://firefox-devtools.github.io/devtools-examples/animation-inspector/animation-inspector-compositing-silly.html>`_ — this is the same example, except that now once the red rectangle is clicked we animate both the `left <https://developer.mozilla.org/en-US/docs/Web/CSS/left>`_ and `transform <https://developer.mozilla.org/en-US/docs/Web/CSS/transform>`_ (with a translation) properties at the same time as `opacity <https://developer.mozilla.org/en-US/docs/Web/CSS/opacity>`_. It doesn't make much sense to try to animate a geometric property and a translation at the same time — the two effects won't be synchronized — so the ``transform`` property is deliberately not handed over to the compositor to handle. The Animation Inspector will tell you this — look at it now and you'll see that:
+
+
+- The white lightning bolt icon in the bar has been replaced with a grey lightning bolt icon, to indicate that only some of the relevant properties are being optimized by the compositor.
+- The bar tooltip also includes this information, as a further reminder. You'll get a message of "Some animation properties are optimized."
+- Properties whose animation is **not** being optimized, but could be if you improved your code, are now given a dotted underline — see transform in the screenshot below. Hovering over this gives you a tooltip that explains why. In this case, the message is "Animations of 'transform' cannot be run on the compositor when geometric properties are animated on the same element at the same time."
+
+
+.. image:: animation_not_optimized.png
+  :class: border
+
+
+.. _page-inspector-how-to-work-with-animations-edit-keyframes:
+
+Edit @keyframes
+***************
+
+Any `@keyframes rules <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Animations/Using_CSS_animations>`_ associated with the currently selected element are displayed in the :ref:`Rules view <page_inspector_ui_tour_rules_view>` and are editable:
+
+.. raw:: html
+
+  <iframe width="560" height="315" src="https://www.youtube.com/embed/mDHtLK88ZW4" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+  <br/>
+  <br/>
+
+
+.. _page-inspector-how-to-work-with-animations-edit-timing-functions:
+
+Edit timing functions
+*********************
+
+When you `create a CSS animation <https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Animations/Using_CSS_animations>`_ you can specify a `timing function <https://developer.mozilla.org/en-US/docs/Web/CSS/animation-timing-function>`_: this determines the rate at which the animation progresses. One way to specify the timing function is with a cubic Bézier curve.
+
+Timing functions defined as cubic Bézier curves get an icon in the Rules view. If you click the icon you get a visual editor for the curve, enabling you to drag `P1 and P2 <https://developer.mozilla.org/en-US/docs/Web/CSS/easing-function#the_cubic-bezier()_class_of_timing-functions>`_, and see the results in the page:
+
+.. raw:: html
+
+  <iframe width="560" height="315" src="https://www.youtube.com/embed/GW5-R2ewaqA" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+  <br/>
+  <br/>
+
+
+This feature uses open source code from `Lea Verou’s cubic-bezier.com <https://cubic-bezier.com/>`_.
+
+The cubic Bézier editor includes a number of presets, grouped under "Ease-in", "Ease-out", and "Ease-in-out":
+
+.. raw:: html
+
+  <iframe width="560" height="315" src="https://www.youtube.com/embed/Jx-J2Yy0aSg" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+  <br/>
+  <br/>
diff --git a/devtools/docs/user/page_inspector/how_to/work_with_animations/target-icon.png b/devtools/docs/user/page_inspector/how_to/work_with_animations/target-icon.png
new file mode 100644
index 0000000000..84ab9afa0c
--- /dev/null
+++ b/devtools/docs/user/page_inspector/how_to/work_with_animations/target-icon.png