[IMP] scss: update, improve preexisting content

Add a new content focused on SCSS and user-interface.

- SCSS coding guidelines: regroup information already available (eg [1])
  or based on "oral tradition".
  The aim is not to establish new rules, ~99% of the current codebase
  is already compliant.

- SCSS inheritance: explain how SCSS assets management works in odoo.
  For example, people still find confusing that overrides are defined
  *before* the variable to customize.

- SCSS optimization tips: suggestions to lean SCSS code. Based on SCSS
  optimization task's know-how [2].

- CSS variables: explain how this feature is commonly used in odoo to
  adapt layout & design without raw CSS overrides.

- UI Icons: Add link to fontAwesome4 library . Replace the picture of
  odoo icons with the actual font (90kb image VS 15Kb font)

[1] https://github.com/odoo/odoo/wiki/SCSS-coding-guidelines
[2] https://www.odoo.com/web#id=2704984&menu_id=4720&cids=1&model=project.task&view_type=form

task-3090800

closes odoo/documentation#3093

Signed-off-by: Antoine Vandevenne (anv) <anv@odoo.com>

content/contributing/development/coding_guidelines.rst

@@ -921,8 +921,8 @@ Symbols and Conventions
 
 .. _contributing/development/js_guidelines:
 
-Javascript and CSS
+Javascript
-==================
+==========
 
 Static files organization
 --------------------------
@@ -969,14 +969,373 @@ More precise JS guidelines are detailed in the `github wiki  <https://github.com
 You may also have a look at existing API in Javascript by looking Javascript
 References.
 
-CSS coding guidelines
+.. _contributing/coding_guidelines/scss:
+
+CSS and SCSS
+============
+
+.. _contributing/coding_guidelines/scss/formatting:
+
+Syntax and Formatting
 ---------------------
 
-- Prefix all your classes with *o_<module_name>* where *module_name* is the
+.. tabs::
-  technical name of the module ('sale', 'im_chat', ...) or the main route
+
-  reserved by the module (for website module mainly, i.e. : 'o_forum' for
+   .. code-tab:: html SCSS
-  *website_forum* module). The only exception for this rule is the
+
-  webclient: it simply uses *o_* prefix.
+      .o_foo, .o_foo_bar, .o_baz {
-- Avoid using *id* tag
+         height: $o-statusbar-height;
-- Use Bootstrap native classes
+
-- Use underscore lowercase notation to name class
+         .o_qux {
+            height: $o-statusbar-height * 0.5;
+         }
+      }
+
+      .o_corge {
+         background: $o-list-footer-bg-color;
+      }
+
+   .. code-tab:: css CSS
+
+      .o_foo, .o_foo_bar, .o_baz {
+         height: 32px;
+      }
+
+      .o_foo .o_quux, .o_foo_bar .o_quux, .o_baz .o_qux {
+         height: 16px;
+      }
+
+      .o_corge {
+         background: #EAEAEA;
+      }
+
+- four (4) space indents, no tabs;
+- columns of max. 80 characters wide;
+- opening brace (`{`): empty space after the last selector;
+- closing brace (`}`): on its own new line;
+- one line for each declaration;
+- meaningful use of whitespace.
+
+.. spoiler:: Suggested Stylelint settings
+
+   .. code-block:: html
+
+      "stylelint.config": {
+          "rules": {
+              // https://stylelint.io/user-guide/rules
+
+              // Avoid errors
+              "block-no-empty": true,
+              "shorthand-property-no-redundant-values": true,
+              "declaration-block-no-shorthand-property-overrides": true,
+
+              // Stylistic conventions
+              "indentation": 4,
+
+              "function-comma-space-after": "always",
+              "function-parentheses-space-inside": "never",
+              "function-whitespace-after": "always",
+
+              "unit-case": "lower",
+
+              "value-list-comma-space-after": "always-single-line",
+
+              "declaration-bang-space-after": "never",
+              "declaration-bang-space-before": "always",
+              "declaration-colon-space-after": "always",
+              "declaration-colon-space-before": "never",
+
+              "block-closing-brace-empty-line-before": "never",
+              "block-opening-brace-space-before": "always",
+
+              "selector-attribute-brackets-space-inside": "never",
+              "selector-list-comma-space-after": "always-single-line",
+              "selector-list-comma-space-before": "never-single-line",
+          }
+      },
+
+.. _contributing/coding_guidelines/scss/properties_order:
+
+Properties order
+----------------
+
+Order properties from the "outside" in, starting from `position` and ending with decorative rules
+(`font`,  `filter`, etc.).
+
+:ref:`Scoped SCSS variables <contributing/coding_guidelines/scss/scoped_scss_variables>` and
+:ref:`CSS variables <contributing/coding_guidelines/scss/css_variables>` must be placed at the very
+top, followed by an empty line separating them from other declarations.
+
+.. code-block:: html
+
+   .o_element {
+      $-inner-gap: $border-width + $legend-margin-bottom;
+
+      --element-margin: 1rem;
+      --element-size: 3rem;
+
+      @include o-position-absolute(1rem);
+      display: block;
+      margin: var(--element-margin);
+      width: calc(var(--element-size) + #{$-inner-gap});
+      border: 0;
+      padding: 1rem;
+      background: blue;
+      font-size: 1rem;
+      filter: blur(2px);
+   }
+
+.. _contributing/coding_guidelines/scss/naming_conventions:
+
+Naming Conventions
+------------------
+
+Naming conventions in CSS are incredibly useful in making your code more strict, transparent and
+informative.
+
+| Avoid `id` selectors, and prefix your classes with `o_<module_name>`, where `<module_name>` is the
+  technical name of the module (`sale`, `im_chat`, ...) or the main route reserved by the module
+  (for website modules mainly, i.e. : `o_forum` for the `website_forum` module).
+| The only exception for this rule is the webclient: it simply uses the `o_` prefix.
+
+Avoid creating hyper-specific classes and variable names. When naming nested elements, opt for the
+"Grandchild" approach.
+
+.. rst-class:: bg-light
+.. example::
+
+   .. container:: alert alert-danger
+
+      Don't
+
+      .. code-block:: html
+
+         <div class=“o_element_wrapper”>
+            <div class=“o_element_wrapper_entries”>
+               <span class=“o_element_wrapper_entries_entry”>
+                  <a class=“o_element_wrapper_entries_entry_link”>Entry</a>
+               </span>
+            </div>
+         </div>
+
+   .. container:: alert alert-success
+
+      Do
+
+      .. code-block:: html
+
+         <div class=“o_element_wrapper”>
+            <div class=“o_element_entries”>
+               <span class=“o_element_entry”>
+                  <a class=“o_element_link”>Entry</a>
+               </span>
+            </div>
+         </div>
+
+Besides being more compact, this approach eases maintenance because it limits the need of renaming
+when changes occur at the DOM.
+
+.. _contributing/coding_guidelines/scss/scss_variables:
+
+SCSS Variables
+~~~~~~~~~~~~~~
+
+Our standard convention is `$o-[root]-[element]-[property]-[modifier]`, with:
+
+* `$o-`
+    The prefix.
+* `[root]`
+    Either the component **or** the module name (components take priority).
+* `[element]`
+    An optional identifier for inner elements.
+* `[property]`
+    The property/behavior defined by the variable.
+* `[modifier]`
+    An optional modifier.
+
+.. example::
+
+   .. code-block:: scss
+
+      $o-block-color: value;
+      $o-block-title-color: value;
+      $o-block-title-color-hover: value;
+
+.. _contributing/coding_guidelines/scss/scoped_scss_variables:
+
+SCSS Variables (scoped)
+~~~~~~~~~~~~~~~~~~~~~~~
+
+These variables are declared within blocks and are not accessible from the outside.
+Our standard convention is `$-[variable name]`.
+
+.. example::
+
+   .. code-block:: html
+
+      .o_element {
+         $-inner-gap: compute-something;
+
+         margin-right: $-inner-gap;
+
+         .o_element_child {
+            margin-right: $-inner-gap * 0.5;
+         }
+      }
+
+.. seealso::
+   `Variables scope on the SASS Documentation
+   <https://sass-lang.com/documentation/variables#scope>`_
+
+.. _contributing/coding_guidelines/scss/mixins:
+
+SCSS Mixins and Functions
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Our standard convention is `o-[name]`. Use descriptive names. When naming functions, use verbs in
+the imperative form (e.g.: `get`, `make`, `apply`...).
+
+Name optional arguments in the :ref:`scoped variables form
+<contributing/coding_guidelines/scss/scoped_scss_variables>`, so `$-[argument]`.
+
+.. example::
+
+   .. code-block:: html
+
+      @mixin o-avatar($-size: 1.5em, $-radius: 100%) {
+         width: $-size;
+         height: $-size;
+         border-radius: $-radius;
+      }
+
+      @function o-invert-color($-color, $-amount: 100%) {
+         $-inverse: change-color($-color, $-hue: hue($-color) + 180);
+
+         @return mix($-inverse, $-color, $-amount);
+      }
+
+.. seealso::
+   - `Mixins on the SASS Documentation <https://sass-lang.com/documentation/at-rules/mixin>`_
+   - `Functions on the SASS Documentation <https://sass-lang.com/documentation/at-rules/function>`_
+
+.. _contributing/coding_guidelines/scss/css_variables:
+
+CSS Variables
+~~~~~~~~~~~~~
+
+In Odoo, the use of CSS variables is strictly DOM-related. Use them to **contextually** adapt the
+design and layout.
+
+Our standard convention is BEM, so `--[root]__[element]-[property]--[modifier]`, with:
+
+* `[root]`
+    Either the component **or** the module name (components take priority).
+* `[element]`
+    An optional identifier for inner elements.
+* `[property]`
+    The property/behavior defined by the variable.
+* `[modifier]`
+    An optional modifier.
+
+.. example::
+
+  .. code-block:: scss
+
+     .o_kanban_record {
+        --KanbanRecord-width: value;
+        --KanbanRecord__picture-border: value;
+        --KanbanRecord__picture-border--active: value;
+     }
+
+     // Adapt the component when rendered in another context.
+     .o_form_view {
+        --KanbanRecord-width: another-value;
+        --KanbanRecord__picture-border: another-value;
+        --KanbanRecord__picture-border--active: another-value;
+     }
+
+.. _contributing/coding_guidelines/scss/variables_use:
+
+Use of CSS Variables
+--------------------
+
+In Odoo, the use of CSS variables is strictly DOM-related, meaning that are used to **contextually**
+adapt the design and layout rather than to manage the global design-system. These are typically used
+when a component's properties can vary in specific contexts or in other circumstances.
+
+We define these properties inside the component's main block, providing default fallbacks.
+
+.. example::
+
+   .. code-block:: scss
+      :caption: :file:`my_component.scss`
+
+      .o_MyComponent {
+         color: var(--MyComponent-color, #313131);
+      }
+
+   .. code-block:: scss
+      :caption: :file:`my_dashboard.scss`
+
+      .o_MyDashboard {
+         // Adapt the component in this context only
+         --MyComponent-color: #017e84;
+      }
+
+.. seealso::
+   `CSS variables on MDN web docs
+   <https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties>`_
+
+.. _contributing/coding_guidelines/scss/css_scss_variables_use:
+
+CSS and SCSS Variables
+~~~~~~~~~~~~~~~~~~~~~~
+
+Despite being apparently similar, `CSS` and `SCSS` variables behave very differently. The main
+difference is that, while `SCSS` variables are **imperative** and compiled away, `CSS` variables are
+**declarative** and included in the final output.
+
+.. seealso::
+   `CSS/SCSS variables difference on the SASS Documentation
+   <https://sass-lang.com/documentation/variables#:~:text=CSS%20variables%20are%20included%20in,use%20will%20stay%20the%20same>`_
+
+In Odoo, we take the best of both worlds: using the `SCSS` variables to define the design-system
+while opting for the `CSS` ones when it comes to contextual adaptations.
+
+The implementation of the previous example should be improved by adding SCSS variables in order to
+gain control at the top-level and ensure consistency with other components.
+
+.. example::
+
+   .. code-block:: scss
+      :caption: :file:`secondary_variables.scss`
+
+      $o-component-color: $o-main-text-color;
+      $o-dashboard-color: $o-info;
+      // [...]
+
+   .. code-block:: text
+      :caption: :file:`component.scss`
+
+      .o_component {
+         color: var(--MyComponent-color, #{$o-component-color});
+      }
+
+   .. code-block:: text
+      :caption: :file:`dashboard.scss`
+
+      .o_dashboard {
+         --MyComponent-color: #{$o-dashboard-color};
+      }
+
+.. _contributing/coding_guidelines/scss/root:
+
+The `:root` pseudo-class
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Defining CSS variables on the `:root` pseudo-class is a technique we normally **don't use** in
+Odoo's UI. The practice is commonly used to access and modify CSS variables globally. We perform
+this using SCSS instead.
+
+Exceptions to this rule should be fairly apparent, such as templates shared across bundles that
+require a certain level of contextual awareness in order to be rendered properly.

content/developer/howtos.rst

@@ -9,6 +9,7 @@ Tutorials
 
     howtos/rdtraining
     howtos/discover_js_framework
+    howtos/scss_tips
     howtos/website
     howtos/backend
     howtos/web_services

content/developer/howtos/scss_tips.rst

@@ -0,0 +1,233 @@
+===============================
+Write lean easy-to-maintain CSS
+===============================
+
+There are many ways to lean and simplify SCSS. The first step is to establish if custom code is
+needed at all.
+
+Odoo's webclient has been designed to be modular, meaning that (potentially all) classes can be
+shared across views. Check the code before creating a new class. Chances are that there is already a
+class or an HTML tag doing exactly what you're looking for.
+
+On top of that, Odoo relies on `Bootstrap
+<https://getbootstrap.com/docs/5.1/getting-started/introduction/>`_ (BS), one of the most complete
+CSS frameworks available. The framework has been customized in order to match Odoo's design (both
+community and enterprise versions), meaning that you can use any BS class directly in Odoo and
+achieve a visual result that is consistent with our UI.
+
+.. warning::
+   - The fact that a class achieves the desired visual result doesn't necessarily mean that it's the
+     right one for the job. Be aware of classes triggering JS behaviors, for example.
+   - Be careful about class semantics. Applying a **button class** to a **title** is not only
+     semantically wrong, it may also lead to migration issues and visual inconsistencies.
+
+The following sections describe tips to strip-down SCSS lines **when custom-code is the only way to
+go**.
+
+.. _tutorials/scss_tips/browser_defaults:
+
+Browser defaults
+================
+
+By default, each browser renders content using a *user agent stylesheet*. To overcome
+inconsistencies between browsers, some of these rules are overridden by `Bootstrap Reboot
+<https://getbootstrap.com/docs/5.1/content/reboot/>`_.
+
+At this stage all "browser-specific-decoration" rules have been stripped away, but a big chunk of
+rules defining basic layout information is maintained (or reinforced by *Reboot* for consistency
+reasons).
+
+You can rely on these rules.
+
+.. example::
+
+   Applying `display: block;` to a `<div/>` is normally not necessary.
+
+   .. code-block:: css
+
+      div.element {
+         display: block;
+         /* not needed 99% of the time */
+      }
+
+.. example::
+
+   In this instance, you may opt to switching the HTML tag rather than adding a new CSS rule.
+
+   .. code-block:: css
+
+      span.element {
+         display: block;
+         /* replace <span> with <div> instead
+            to get 'display: block' by default */
+      }
+
+Here's a non-comprehensive list of default rules:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Tag / Attribute
+     - Defaults
+   * - `<div/>`, `<section/>`, `<header/>`, `<footer/>`...
+     - `display: block`
+   * - `<span/>`, `<a/>`, `<em/>`, `<b/>`...
+     - `display: inline`
+   * - `<button/>`, `<label/>`, `<output/>`...
+     - `display: inline-block`
+   * - `<img/>`, `<svg/>`
+     - `vertical-align: middle`
+   * - `<summary/>`, `[role="button"]`
+     - `cursor: pointer;`
+   * - `<q/>`
+     - | `:before {content: open-quote}`
+       | `:after  {content: close-quote}`
+   * - ...
+     - ...
+
+.. seealso::
+   `Bootstrap Reboot on GitHub
+   <https://github.com/twbs/bootstrap/blob/1a6fdfae6b/scss/_reboot.scss>`_
+
+.. _tutorials/scss_tips/html_tags:
+
+HTML tags
+=========
+
+It may seem obvious, but the simplest and most **consistent** way of making text look like a title
+is to use a header tag (`<h1>`, `<h2>`, ...). Besides reboot rules, mostly all tags carry decorative
+styles defined by Odoo.
+
+.. rst-class:: bg-light
+.. example::
+
+   .. container:: alert alert-danger
+
+      Don't
+
+      .. tabs::
+
+         .. code-tab:: html XML
+
+            <span class="o_module_custom_title">
+               Hello There!
+            </span>
+
+            <span class="o_module_custom_subtitle">
+               I'm a subtitle.
+            </span>
+
+         .. code-tab:: css SCSS
+
+            .o_module_custom_title {
+               display: block;
+               font-size: 120%;
+               font-weight: bold;
+               animation: 1s linear 1s mycustomAnimation;
+            }
+
+            .o_module_custom_subtitle {
+               display: block;
+               font-size: 12px;
+               font-weight: bold;
+               animation: 2s linear 1s mycustomAnimation;
+            }
+
+   .. container:: alert alert-success
+
+      Do
+
+      .. tabs::
+
+         .. code-tab:: html XML
+
+            <h5 class="o_module_custom_title">
+               Hello There!
+            </h5>
+
+            <div class="o_module_custom_subtitle">
+               <b><small>I'm a subtitle.</small></b>
+            </div>
+
+         .. code-tab:: css SCSS
+
+            .o_module_custom_title {
+               animation: 1s linear 1s mycustomAnimation;
+            }
+
+            .o_module_custom_subtitle {
+               animation: 2s linear 1s mycustomAnimation;
+            }
+
+.. note::
+   Besides reducing the amount of code, a modular-design approach (use classes, tags, mixins...)
+   keeps the visual result consistent and easily **maintainable**.
+
+   Following the last example, if Odoo titles' design changes, these changes will be applied in the
+   `o_module_custom_title` element too since it's using an `<h5>` tag.
+
+.. _tutorials/scss_tips/utility_classes:
+
+Utility classes
+===============
+
+Our framework defines a multitude of utility classes designed to cover almost all
+layout/design/interaction needs. The simple fact that a class already exists justifies its use over
+custom CSS whenever possible.
+
+Take the example of `position-relative`.
+
+.. code-block:: css
+
+   position-relative {
+      position: relative !important;
+   }
+
+Since a utility-class is defined, any CSS line with the declaration `position: relative` is
+**potentially** redundant.
+
+Odoo relies on the default `Bootstrap utility-classes
+<https://getbootstrap.com/docs/5.1/utilities/background/>`_ stack and defines its own using
+`Bootstrap API <https://getbootstrap.com/docs/5.1/utilities/api/>`_.
+
+.. seealso::
+   - `Bootstrap utility classes <https://getbootstrap.com/docs/5.1/utilities/api/>`_
+   - `Odoo custom utilities on github
+     <{GITHUB_PATH}/addons/web/static/src/scss/utilities_custom.scss>`_
+
+.. _tutorials/scss_tips/utility_classes/downside:
+
+Handling utility-classes verbosity
+----------------------------------
+
+The downside of utility-classes is the potential lack of readability.
+
+.. example::
+
+   .. code-block:: html
+
+      <myComponent t-attf-class="d-flex border px-lg-2 card
+      {{props.readonly ? 'o_myComponent_disabled' : ''}}
+      card d-lg-block position-absolute {{props.active ?
+      'o_myComponent_active' : ''}}  myComponent px-3"/>
+
+To overcome the issue you may combine different approaches:
+
+- in Qweb attributes, only use classes to be toggled *on-the-fly*;
+- use new lines for each attribute;
+- order classes using the convention `[odoo component] [bootstrap component] [css declaration order]`.
+
+.. example::
+
+   .. code-block:: html
+
+      <myComponent
+         t-att-class="{
+            o_myComponent_disabled: props.readonly,
+            o_myComponent_active: props.active
+         }"
+         class="myComponent card position-absolute d-flex d-lg-block border px-3 px-lg-2"
+      />
+
+.. seealso::
+   :ref:`Odoo CSS properties order <contributing/coding_guidelines/scss/properties_order>`

content/developer/reference.rst

@@ -9,4 +9,5 @@ Reference
 
     reference/backend
     reference/frontend
+    reference/user_interface
     reference/standard_modules

content/developer/reference/frontend.rst

@@ -20,4 +20,3 @@ JavaScript framework
     frontend/mobile
     frontend/qweb
     frontend/odoo_editor
-    frontend/icons_library

content/developer/reference/frontend/icons_library.rst

@@ -1,5 +0,0 @@
-=============
-Odoo UI Icons
-=============
-
-.. image:: icons_library/odoo-ui-icons.png

content/developer/reference/user_interface.rst

@@ -0,0 +1,11 @@
+:nosearch:
+
+==============
+User interface
+==============
+
+.. toctree::
+    :titlesonly:
+
+    user_interface/scss_inheritance
+    user_interface/icons

content/developer/reference/user_interface/icons.rst

@@ -0,0 +1,114 @@
+:hide-page-toc:
+
+========
+UI icons
+========
+
+Odoo's user interface mostly relies on `FontAwesome4 icons <https://fontawesome.com/v4/icons/>`_.
+
+To cover FontAwesome's lack of iconography for specific functionalities, we designed our own
+icon-font. These icons can be rendered using the main `oi` class in conjunction with the specific
+icon class.
+
+.. example::
+
+   .. code-block:: html
+
+      <i class="oi oi-odoo"/>
+
+.. raw:: html
+
+   <section class="row">
+
+       <div class="o_icon_card col-6 col-sm-4 col-md-3 col-xl-2 mb-3">
+           <div class="card text-center">
+               <i class="oi oi-apps h1 p-4"></i>
+               <code>oi-apps</code>
+           </div>
+       </div>
+
+       <div class="o_icon_card col-6 col-sm-4 col-md-3 col-xl-2 mb-3">
+           <div class="card text-center">
+               <i class="oi oi-group h1 p-4"></i>
+               <code>oi-group</code>
+           </div>
+       </div>
+
+       <div class="o_icon_card col-6 col-sm-4 col-md-3 col-xl-2 mb-3">
+           <div class="card text-center">
+               <i class="oi oi-launch h1 p-4"></i>
+               <code>oi-launch</code>
+           </div>
+       </div>
+
+       <div class="o_icon_card col-6 col-sm-4 col-md-3 col-xl-2 mb-3">
+           <div class="card text-center">
+               <i class="oi oi-odoo h1 p-4"></i>
+               <code>oi-odoo</code>
+           </div>
+       </div>
+
+       <div class="o_icon_card col-6 col-sm-4 col-md-3 col-xl-2 mb-3">
+           <div class="card text-center">
+               <i class="oi oi-panel-right h1 p-4"></i>
+               <code>oi-panel-right</code>
+           </div>
+       </div>
+
+       <div class="o_icon_card col-6 col-sm-4 col-md-3 col-xl-2 mb-3">
+           <div class="card text-center">
+               <i class="oi oi-search h1 p-4"></i>
+               <code>oi-search</code>
+           </div>
+       </div>
+
+       <div class="o_icon_card col-6 col-sm-4 col-md-3 col-xl-2 mb-3">
+           <div class="card text-center">
+               <i class="oi oi-settings-adjust h1 p-4"></i>
+               <code>oi-settings-adjust</code>
+           </div>
+       </div>
+
+       <div class="o_icon_card col-6 col-sm-4 col-md-3 col-xl-2 mb-3">
+           <div class="card text-center">
+               <i class="oi oi-studio h1 p-4"></i>
+               <code>oi-studio</code>
+           </div>
+       </div>
+
+       <div class="o_icon_card col-6 col-sm-4 col-md-3 col-xl-2 mb-3">
+           <div class="card text-center">
+               <i class="oi oi-view-cohort h1 p-4"></i>
+               <code>oi-view-cohort</code>
+           </div>
+       </div>
+
+       <div class="o_icon_card col-6 col-sm-4 col-md-3 col-xl-2 mb-3">
+           <div class="card text-center">
+               <i class="oi oi-view-kanban h1 p-4"></i>
+               <code>oi-view-kanban</code>
+           </div>
+       </div>
+
+       <div class="o_icon_card col-6 col-sm-4 col-md-3 col-xl-2 mb-3">
+           <div class="card text-center">
+               <i class="oi oi-view-list h1 p-4"></i>
+               <code>oi-view-list</code>
+           </div>
+       </div>
+
+       <div class="o_icon_card col-6 col-sm-4 col-md-3 col-xl-2 mb-3">
+           <div class="card text-center">
+               <i class="oi oi-view-pivot h1 p-4"></i>
+               <code>oi-view-pivot</code>
+           </div>
+       </div>
+
+       <div class="o_icon_card col-6 col-sm-4 col-md-3 col-xl-2 mb-3">
+           <div class="card text-center">
+               <i class="oi oi-voip h1 p-4"></i>
+               <code>oi-voip</code>
+           </div>
+       </div>
+
+   </section>

content/developer/reference/user_interface/scss_inheritance.rst

@@ -0,0 +1,106 @@
+================
+SCSS inheritance
+================
+
+Overview
+========
+
+Managing SCSS assets in Odoo is not as straightforward as it is in some other environments, but it's
+highly efficient.
+
+Modularity is key. The inheritance scheme described further allows Odoo to:
+
+- customize the Bootstrap CSS framework;
+- handle two different webclient designs (Community and Enterprise);
+- handle backend and frontend bundles separately (including the user's website design);
+- contextually load only necessary assets;
+- handle multiple color-schemes (e.g.: dark-mode);
+
+SCSS's `!default` directive
+===========================
+
+"Direct variables’ overrides" are technically possible in SCSS but may lead to inconsistent results
+in complex environments like Odoo.
+
+.. example::
+
+   .. code-block:: scss
+      :caption: :file:`library.scss`
+
+      $foo: red;
+
+   .. code-block:: scss
+      :caption: :file:`customization_layer.scss`
+
+      $foo: blue; // -> Don't!
+
+Indeed, since the compilation process acts across different interdependent bundles, re-assigning
+a variable in the "wrong spot" may lead to unexpected cascading results.
+
+SCSS provides several techniques to overcome these issues
+(e.g.: `shadowing <https://sass-lang.com/documentation/variables#shadowing>`_), but the most
+critical procedure in Odoo is the use of the `!default` flag.
+
+When using the `!default` flag, the compiler assigns a value **only** if that variable is not yet
+defined.
+
+As a result of this technique, the priority in which variables are assigned matches the assets'
+loading order.
+
+.. example::
+
+   .. code-block:: scss
+      :caption: :file:`customization_layer.scss`
+
+      $foo: red !default;
+
+   .. code-block:: scss
+      :caption: :file:`library.scss`
+
+      $foo: blue !default; // -> Already defined, line ignored.
+      $bar: black !default; // -> Not defined yet, value assigned.
+
+   .. code-block::
+      :caption: :file:`component.scss`
+
+      .component {
+         color: $foo; // -> 'color: red;'
+         background: $bar; // -> 'background: black;'
+      }
+
+.. seealso::
+   `!default` flag on the `SASS Documentation
+   <https://sass-lang.com/documentation/variables#default-values>`_
+
+Odoo's SCSS inheritance system
+==============================
+
+The following diagram conceptually illustrates the compilation order in which the CSS and SCSS
+variables are defined.
+
+.. code-block:: text
+
+    ↓ [Compilation starts]
+    ⏐
+    ↓ web.dark_mode_variables
+    ⏐   ├─ Primary Variables
+    ⏐   └─ Components Variables
+    ⏐
+    ↓ web._assets_primary_variables
+    ⏐   ├─ Primary Variables (enterprise)
+    ⏐   ├─ Components Variables (enterprise)
+    ⏐   ├─ Primary Variables (community)
+    ⏐   └─ Components Variables (community)
+    ⏐
+    ↓ web._assets_bootstrap
+    ⏐
+    ↓ web.assets_backend
+    ⏐   ├─ ...
+    ⏐   ├─ CSS variables definition
+    ⏐   └─ CSS variables contextual adaptations
+    ⏐
+    ● [Visual result on screen]
+
+.. important::
+   This diagram is incomplete and does not match the current bundles' organization. Read more on
+   :ref:`asset bundles <reference/assets_bundle>`.

extensions/odoo_theme/static/lib/odoo_ui_icons/LICENSE.md

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1.  Definitions.
+
+    "License" shall mean the terms and conditions for use, reproduction,
+    and distribution as defined by Sections 1 through 9 of this document.
+
+    "Licensor" shall mean the copyright owner or entity authorized by
+    the copyright owner that is granting the License.
+
+    "Legal Entity" shall mean the union of the acting entity and all
+    other entities that control, are controlled by, or are under common
+    control with that entity. For the purposes of this definition,
+    "control" means (i) the power, direct or indirect, to cause the
+    direction or management of such entity, whether by contract or
+    otherwise, or (ii) ownership of fifty percent (50%) or more of the
+    outstanding shares, or (iii) beneficial ownership of such entity.
+
+    "You" (or "Your") shall mean an individual or Legal Entity
+    exercising permissions granted by this License.
+
+    "Source" form shall mean the preferred form for making modifications,
+    including but not limited to software source code, documentation
+    source, and configuration files.
+
+    "Object" form shall mean any form resulting from mechanical
+    transformation or translation of a Source form, including but
+    not limited to compiled object code, generated documentation,
+    and conversions to other media types.
+
+    "Work" shall mean the work of authorship, whether in Source or
+    Object form, made available under the License, as indicated by a
+    copyright notice that is included in or attached to the work
+    (an example is provided in the Appendix below).
+
+    "Derivative Works" shall mean any work, whether in Source or Object
+    form, that is based on (or derived from) the Work and for which the
+    editorial revisions, annotations, elaborations, or other modifications
+    represent, as a whole, an original work of authorship. For the purposes
+    of this License, Derivative Works shall not include works that remain
+    separable from, or merely link (or bind by name) to the interfaces of,
+    the Work and Derivative Works thereof.
+
+    "Contribution" shall mean any work of authorship, including
+    the original version of the Work and any modifications or additions
+    to that Work or Derivative Works thereof, that is intentionally
+    submitted to Licensor for inclusion in the Work by the copyright owner
+    or by an individual or Legal Entity authorized to submit on behalf of
+    the copyright owner. For the purposes of this definition, "submitted"
+    means any form of electronic, verbal, or written communication sent
+    to the Licensor or its representatives, including but not limited to
+    communication on electronic mailing lists, source code control systems,
+    and issue tracking systems that are managed by, or on behalf of, the
+    Licensor for the purpose of discussing and improving the Work, but
+    excluding communication that is conspicuously marked or otherwise
+    designated in writing by the copyright owner as "Not a Contribution."
+
+    "Contributor" shall mean Licensor and any individual or Legal Entity
+    on behalf of whom a Contribution has been received by Licensor and
+    subsequently incorporated within the Work.
+
+2.  Grant of Copyright License. Subject to the terms and conditions of
+    this License, each Contributor hereby grants to You a perpetual,
+    worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+    copyright license to reproduce, prepare Derivative Works of,
+    publicly display, publicly perform, sublicense, and distribute the
+    Work and such Derivative Works in Source or Object form.
+
+3.  Grant of Patent License. Subject to the terms and conditions of
+    this License, each Contributor hereby grants to You a perpetual,
+    worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+    (except as stated in this section) patent license to make, have made,
+    use, offer to sell, sell, import, and otherwise transfer the Work,
+    where such license applies only to those patent claims licensable
+    by such Contributor that are necessarily infringed by their
+    Contribution(s) alone or by combination of their Contribution(s)
+    with the Work to which such Contribution(s) was submitted. If You
+    institute patent litigation against any entity (including a
+    cross-claim or counterclaim in a lawsuit) alleging that the Work
+    or a Contribution incorporated within the Work constitutes direct
+    or contributory patent infringement, then any patent licenses
+    granted to You under this License for that Work shall terminate
+    as of the date such litigation is filed.
+
+4.  Redistribution. You may reproduce and distribute copies of the
+    Work or Derivative Works thereof in any medium, with or without
+    modifications, and in Source or Object form, provided that You
+    meet the following conditions:
+
+    (a) You must give any other recipients of the Work or
+    Derivative Works a copy of this License; and
+
+    (b) You must cause any modified files to carry prominent notices
+    stating that You changed the files; and
+
+    (c) You must retain, in the Source form of any Derivative Works
+    that You distribute, all copyright, patent, trademark, and
+    attribution notices from the Source form of the Work,
+    excluding those notices that do not pertain to any part of
+    the Derivative Works; and
+
+    (d) If the Work includes a "NOTICE" text file as part of its
+    distribution, then any Derivative Works that You distribute must
+    include a readable copy of the attribution notices contained
+    within such NOTICE file, excluding those notices that do not
+    pertain to any part of the Derivative Works, in at least one
+    of the following places: within a NOTICE text file distributed
+    as part of the Derivative Works; within the Source form or
+    documentation, if provided along with the Derivative Works; or,
+    within a display generated by the Derivative Works, if and
+    wherever such third-party notices normally appear. The contents
+    of the NOTICE file are for informational purposes only and
+    do not modify the License. You may add Your own attribution
+    notices within Derivative Works that You distribute, alongside
+    or as an addendum to the NOTICE text from the Work, provided
+    that such additional attribution notices cannot be construed
+    as modifying the License.
+
+    You may add Your own copyright statement to Your modifications and
+    may provide additional or different license terms and conditions
+    for use, reproduction, or distribution of Your modifications, or
+    for any such Derivative Works as a whole, provided Your use,
+    reproduction, and distribution of the Work otherwise complies with
+    the conditions stated in this License.
+
+5.  Submission of Contributions. Unless You explicitly state otherwise,
+    any Contribution intentionally submitted for inclusion in the Work
+    by You to the Licensor shall be under the terms and conditions of
+    this License, without any additional terms or conditions.
+    Notwithstanding the above, nothing herein shall supersede or modify
+    the terms of any separate license agreement you may have executed
+    with Licensor regarding such Contributions.
+
+6.  Trademarks. This License does not grant permission to use the trade
+    names, trademarks, service marks, or product names of the Licensor,
+    except as required for reasonable and customary use in describing the
+    origin of the Work and reproducing the content of the NOTICE file.
+
+7.  Disclaimer of Warranty. Unless required by applicable law or
+    agreed to in writing, Licensor provides the Work (and each
+    Contributor provides its Contributions) on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+    implied, including, without limitation, any warranties or conditions
+    of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+    PARTICULAR PURPOSE. You are solely responsible for determining the
+    appropriateness of using or redistributing the Work and assume any
+    risks associated with Your exercise of permissions under this License.
+
+8.  Limitation of Liability. In no event and under no legal theory,
+    whether in tort (including negligence), contract, or otherwise,
+    unless required by applicable law (such as deliberate and grossly
+    negligent acts) or agreed to in writing, shall any Contributor be
+    liable to You for damages, including any direct, indirect, special,
+    incidental, or consequential damages of any character arising as a
+    result of this License or out of the use or inability to use the
+    Work (including but not limited to damages for loss of goodwill,
+    work stoppage, computer failure or malfunction, or any and all
+    other commercial damages or losses), even if such Contributor
+    has been advised of the possibility of such damages.
+
+9.  Accepting Warranty or Additional Liability. While redistributing
+    the Work or Derivative Works thereof, You may choose to offer,
+    and charge a fee for, acceptance of support, warranty, indemnity,
+    or other liability obligations and/or rights consistent with this
+    License. However, in accepting such obligations, You may act only
+    on Your own behalf and on Your sole responsibility, not on behalf
+    of any other Contributor, and only if You agree to indemnify,
+    defend, and hold each Contributor harmless for any liability
+    incurred by, or claims asserted against, such Contributor by reason
+    of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "{}"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+Copyright {yyyy} {name of copyright owner}
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

extensions/odoo_theme/static/lib/odoo_ui_icons/Read Me.txt

@@ -0,0 +1,9 @@
+Odoo UI Icons - v1.2
+
+Credits
+- https://www.carbondesignsystem.com/guidelines/icons/library/
+- https://github.com/carbon-design-system/carbon-icons
+- https://github.com/google/material-design-icons
+
+
+Created by SRI using IconMoon (https://icomoon.io/)

extensions/odoo_theme/static/lib/odoo_ui_icons/style.css

@@ -0,0 +1,41 @@
+@font-face {
+  font-family: 'odoo_ui_icons';
+  src: url('fonts/odoo_ui_icons.woff2') format('woff2'), url('fonts/odoo_ui_icons.woff') format('woff');
+  font-weight: normal;
+  font-style: normal;
+  font-display: block;
+}
+
+.oi {
+  font-family: 'odoo_ui_icons';
+  speak: never;
+  font-style: normal;
+  font-weight: normal;
+  font-variant: normal;
+  text-transform: none;
+  line-height: 1;
+
+  /* Better Font Rendering =========== */
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+.oi-close:before {
+  content: '\00d7';
+  font-family: sans-serif;
+  font-weight: bold;
+}
+
+.oi-view-pivot:before { content: '\e800'; }
+.oi-voip:before { content: '\e803'; }
+.oi-odoo:before { content: '\e806'; }
+.oi-search:before { content: '\e808'; }
+.oi-group:before { content: '\e80a'; }
+.oi-settings-adjust:before { content: '\e80c'; }
+.oi-apps:before { content: '\e80d'; }
+.oi-panel-right:before { content: '\e810'; }
+.oi-launch:before { content: '\e812'; }
+.oi-studio:before { content: '\e813'; }
+.oi-view-kanban:before { content: '\e814'; }
+.oi-view-cohort:before { content: '\e816'; }
+.oi-view-list:before { content: '\e817'; }

extensions/odoo_theme/static/style.scss

@@ -8,6 +8,7 @@
 @import "scss/_mixins";
 @import "scss/_typography";
 @import "scss/_iconfont";
+@import "lib/odoo_ui_icons/style.css";
 
 div[aria-label="related navigation"] {
     display: none;

redirects/16.0.txt

@@ -19,3 +19,9 @@ applications/finance/payment_acquirers/wire_transfer.rst applications/finance/pa
 # applications/websites
 
 applications/websites/ecommerce/shopper_experience/payment_acquirer.rst applications/websites/ecommerce/shopper_experience/payment_providers.rst # payment_acquirer -> payment_providers
+
+
+# developer/reference/frontend
+
+developer/reference/frontend/icons_library.rst contributing/development/ui/icons.rst # Odoo UI icons -> UI Icons
+