docs: Update incomplete color scheme docs (#7512)

* fix/merge_errors * Update incomplete color scheme docs * fix typos
django-cms · fsbraun · Apr 17, 2023 · Jun 29, 2022 · Jul 3, 2022 · Jul 3, 2022
commit 9a3d6479ee04a4a90f6538e80fc16b87e5e9692d
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -83,7 +83,9 @@ Highlights:
 * Support for django 4
 * Dark mode support
 
-* Added dark mode support to css, dark mode settings and toggle button
+Bug fixes:
+----------
+
 * Fix publishing of static placeholders outside of CMS pages
 * Allow to override the template rendered after a plugin has been saved.
 * Revert change to the toolbar sites menu to use ``http`` protocol.
@@ -1250,7 +1252,7 @@ Thanks to all contributors for their efforts!
 - Fix issue on django >= 1.6 with page form fields.
 - Resolve jQuery namespace issues in admin page tree and changeform
 - Fix issues for PageField in Firefox/Safari
-- Fix some Python 3.4 compatibility issue when using proxy modles
+- Fix some Python 3.4 compatibility issue when using proxy models
 - Fix corner case in plugin copy
 - Documentation fixes
 - Minor code cleanups

diff --git a/cms/static/cms/js/select2/LICENSE b/cms/static/cms/js/select2/LICENSE
@@ -13,6 +13,6 @@ http://www.apache.org/licenses/LICENSE-2.0
 http://www.gnu.org/licenses/gpl-2.0.html
 
 Unless required by applicable law or agreed to in writing, software distributed under the Apache License
-or the GPL Licesnse is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+or the GPL License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
 either express or implied. See the Apache License and the GPL License for the specific language governing
 permissions and limitations under the Apache License and the GPL License.
diff --git a/docs/topics/colorscheme.rst b/docs/topics/colorscheme.rst
@@ -11,7 +11,7 @@ Color schemes (light/dark) with django CMS
     responsibility of the site developer.
 
     The admin interfaces will only reflect the described behavior if the package
-    ``djangocms-admin-style`` is installed (version XXX or later). If it is not installed the admin
+    ``djangocms-admin-style`` is installed (version 3.2 or later). If it is not installed the admin
     interface is managed by your underlying Django installation which usually
     uses the browser's color scheme.
 
@@ -49,15 +49,58 @@ setting in your project's ``setting.py``:
 .. important::
 
     Not all plugin admin interfaces might support a dark color scheme, especially
-    if plugin forms contain custom widgets. See XXXX on how to make your widgets
-    compatible with django CMS' color scheme support.
+    if plugin forms contain custom widgets.
 
 **********************************
 Toggle button for the color scheme
 **********************************
 
-Adding the setting ``CMS_COLOR_SCHEME_TOGGLE = True`` to the project's ``settings.py``
-will add a toggle icon (sun/moon) to the toolbar allowing a user to switch their
-color scheme for their session.
+Adding the setting ``CMS_COLOR_SCHEME_TOGGLE = True`` to the project's ``settings.py`` will add a toggle icon (sun/moon) to the toolbar allowing a user to switch their color scheme for their session.
 
 
+******************************************
+Make your own admin css color scheme aware
+******************************************
+
+Plugin forms or any admin forms use Django's admin app which itself supports light and dark color schemes. djangocms-admin-style introduces django CMS' color scheme to the admin app. Just as Django does, djangocms-admin-style defines css variables for frequent colors.
+
+We recommend to write at least your reusable apps in a way which allows  them to respect the color scheme with djangocms-admin-style and with Django's admin style.
+
+Here's some recommendations for making your app work as seamlessly as possible:
+
+* Try avoiding using ``color``, ``background-color``, or other color styles where possible and meaningful.
+* If necessary use as few as possible standard django CMS colors (preferably from the list below with plain Django fallback colors)
+* Use the following pattern: ``var(--dca-color-var, var(--fallback-color-var, #xxxxxx))`` where ``#xxxxxx`` represents the light version of the color. This tries django CMS color scheme first and falls back to Django color scheme if djangocms-admin-style is not available.
+* Avoid media queries like ``@media (prefers-color-scheme: dark)`` since they would ignore forced settings to light or dark.
+
+
+The admin frontend pulls the style from django admin styles and - if present - from djangocms-admin-style. Django itself also uses css variables to implement admin mode, these can be used as dark mode-aware fall-back colors.
+
+Here's a table of django CMS' css color variables and their Django fallbacks:
+
+=============================== =========== ======================= ===========
+Variable name                   Color       Fallback                Color
+=============================== =========== ======================= ===========
+``--dca-white``                 ``#ffffff`` ``--body-bg``           ``#ffffff``
+``--dca-gray``                  ``#666``    ``--body-quiet-color``  ``#666``
+``--dca-gray-lightest``         ``#f2f2f2`` ``--darkened-bg``       ``#f8f8f8``
+``--dca-gray-lighter``          ``#ddd``    ``--border-color``      ``#ccc``
+``--dca-gray-light``            ``#999``    ``--close-button-bg``   ``#888``
+``--dca-gray-darker``           ``#454545``
+``--dca-gray-darkest``          ``#333``
+``--dca-gray-super-lightest``   ``#f7f7f7``
+``--dca-primary``               ``#00bbff`` ``--primary``           ``#79aec8``
+``--dca-black``                 ``#000``    ``--body-fg``           ``#303030``
+=============================== =========== ======================= ===========
+
+This leaves these recommendation for color scheme dependent colors:
+
+.. code-block::
+
+    white:          var(--dca-white, var(--body-bg, #fff))
+    gray:           var(--dca-gray, var(--body-quiet-color, #666))
+    gray-lightest:  var(--dca-gray-lightest, var(--darkened-bg, #f2f2f2))
+    gray-lighter    var(--dca-gray-lighter, var(--border-color, #ddd))
+    gray-light:     var(--dca-gray-lightest, var(--darkened-bg, #f2f2f2))
+    gray-primary:   var(--dca-primary, var(--primary, #0bf))
+    black:          var(--dca-black, var(--body-fg), #000))