ENH - Scalable colour system for theme (#1174)

* 📝 Update file names in documentation

* 🎨 Update mixins to match new colour system

* ♿ Update colours

* ♿ Update foundation and text colours

* Add more colours - shadows and neutrals

* ♿ Replace text colour function w/WCAG one

* ♻️ Add full color system to root

* ♿ Update variables - use color names

* ♿ Ensure all the colours are evaluated correctly

* Update mixins - move to separate file

* Update contrast ratios - add comments

* ♿️  Add luminance formula and ignore text col for now

* Update variables and remove debugs

* ⚡ Improve colours parsing

* ♿ Update admonition bg colours

* Update headings colours

* ♿ Change topic text colour and replace mixins

* ♿ Minor tweaks to secondary colour

* ♿ Update code and announcement colours

* Update text-muted in dark theme

* ♿️  Buttons are now WCAG AA conformant

* 💄 Update tabs hover

* ♿️ Tweaks to colours in small components

* ♿️ Move WCAG contrast to mixin file

* Update theming docs

* 📝 Update a11y docs

* Update accessibility docs

* Fix search button text contrast

* Fix colours in admonitions

* Ensure we use WCAG compliant text color

* Update docs - web components

* Fix quotes text colour

* Add more details re accessibility

* 📝 Add accessibility notes to docs

* 💄 Ensure we are generating background colours too

* 🐛 Fix attention bg colour

* 🐛 Fix bg colour issues

* 🎨 Improve sd colours

* Update styling

* Lint files

* ➖ Remove unused mixin

* Fix issues introduced by merging main

* Add dropdowns background

* 📝 Update docs

* ✏️ Fix grammar and spelling

* Minor edits to docs

* Fix colour in code blocks

* ⚡ Use math.pow - we use dart sass now

* ⚡ Use math.pow

* ⚡ Update mixins

* ➕ Add math import in mixins

* Fix highlight colour - pygments

* Fix inline code links contrast

* Add selector to print - a11y tests

* Fix line numbers contrast

* Fix announcement link colours

* Adjust background colours - light theme

* Update search highlight colours

* ♿ Change hover colour to improve contrast

* Update docs to align with system

* 🙈 Update gitignore file

* Apply suggestions from code review

Co-authored-by: Daniel McCloy <dan@mccloy.info>

* 🐛 Use correct variable names

* Fix title colour in custom admonitions

---------

Co-authored-by: Tania Allard <tallard@quansight.com>
Co-authored-by: Daniel McCloy <dan@mccloy.info>

.gitignore

@@ -121,3 +121,6 @@ profile.svg
 
 # Compiled translation files (are compiled at build time)
 src/pydata_sphinx_theme/locale/*/*/*.mo
+
+# jupyterlite db
+.jupyterlite.doit.db

docs/_static/custom.css

@@ -25,13 +25,16 @@
 /* begin-custom-color/* <your static path>/custom.css */
 
 div.admonition.admonition-olive {
-  border-color: olive;
+  border-color: hsl(60, 100%, 25%);
 }
 div.admonition.admonition-olive > .admonition-title:before {
-  background-color: olive;
+  background-color: hsl(60, 100%, 14%);
 }
 div.admonition.admonition-olive > .admonition-title:after {
-  color: olive;
+  color: hsl(60, 100%, 25%);
+}
+div.admonition.admonition-olive > .admonition-title {
+  color: white;
 }
 /* end-custom-color */
 
@@ -45,13 +48,16 @@ div.admonition.admonition-icon > .admonition-title:after {
 /* begin-custom-youtube/* <your static path>/custom.css */
 
 div.admonition.admonition-youtube {
-  border-color: #ff0000; /* YouTube red */
+  border-color: hsl(0, 100%, 50%); /* YouTube red */
 }
 div.admonition.admonition-youtube > .admonition-title:before {
-  background-color: #ff0000;
+  background-color: hsl(0, 99%, 18%);
 }
 div.admonition.admonition-youtube > .admonition-title:after {
-  color: #ff0000;
+  color: hsl(0, 100%, 50%);
   content: "\f26c"; /* fa-solid fa-tv */
 }
+div.admonition.admonition-youtube > .admonition-title {
+  color: white;
+}
 /* end-custom-youtube */

docs/_templates/custom-template.html

@@ -1,6 +1,6 @@
 <div class="sidebar-message">
   This is a community-supported theme.
   If you'd like to contribute,
-  <a href="https://github.com/pydata/pydata-sphinx-theme">check out our GitHub repository</a>
+  <a href="https://github.com/pydata/pydata-sphinx-theme">check out our GitHub repository.</a>
   Your contributions are welcome!
 </div>

docs/community/contributors.md

@@ -17,4 +17,4 @@ Support and development for this theme has been funded by one [NumFocus Small De
 
 ## Theme logo
 
-Thanks to [@drammock](https://github.com/drammock) for initial design of the theme logo.
+Thanks to [@drammock](https://github.com/drammock) for the initial design of the theme logo.

docs/community/practices/merge.md

@@ -1,20 +1,20 @@
 # Merge and review policy
 
 Our policy for merging and reviewing describes how we review one another's work, and when we allow others to merge changes into our main codebase.
-It tries to balance between a few goals:
+It tries to balance a few goals:
 
 - Iterate on PRs and merge them relatively quickly, so that we reduce the debt associated with long-lasting PRs.
 - Give enough time for others to provide their input and guide the PR itself, and to ensure that we aren't creating a problem with the PR.
 - Value iterative improvement over creating the perfect Pull Request, so that we do not burden contributors with cumbersome discussion and minor revision requests.
 - Recognize that we all have limited time and resources, and so cannot guarantee a full quality assurance process each time.
-- Give general preference to the opinions from maintainers of projects in the PyData ecosystem, as a key stakeholder community of this theme.
+- Give general preference to the opinions of maintainers of projects in the PyData ecosystem, as a key stakeholder community of this theme.
 
-We follow these guidelines in order to achieve these goals:
+We follow these guidelines to achieve these goals:
 
 - Assume that all maintainers are acting in good faith and will use their best judgment to make decisions in the best interests of the repository.
-- We can and will make mistakes, and so encourage best practices in testing and documentation to guard against this.
-- It's important to share information, so give a best effort at telling others about work that you're doing.
-- It's best to discuss and agree on important decisions at a high level before implementation, so give a best effort at providing time and invitation for others to provide feedback.
+- We can and will make mistakes, so encourage best practices in testing and documentation to guard against this.
+- It's important to share information, so give your best effort at telling others about the work that you're doing.
+- It's best to discuss and agree on important decisions at a high level before implementation, so give the best effort at providing time and invitation for others to provide feedback.
 
 ## Policy for moderate changes
 
@@ -35,7 +35,7 @@ They can be merged when the above conditions are met, and one of these things ha
 
 These are changes that significantly alter the experience of the user, or that add significant complexity to the codebase.
 
-All of the above, but PRs **must** have approval from at least one other core maintainer before merging.
+All the above, but PRs **must** have approval from at least one other core maintainer before merging.
 In addition, the PR author should put extra effort into ensuring that the relevant stakeholders are notified about a change, so they can gauge its impact and provide feedback.
 
 ## Policy For minor changes and bugfixes

docs/community/practices/release.md

@@ -5,7 +5,7 @@
 ## Our goals
 
 Our release policy describes how we decide when to make a new public release of the theme so that other projects may use new features and improvements.
-It tries to balance between these goals:
+It tries to balance these goals:
 
 - Release relatively frequently, so that we provide a continuous stream of improvement to projects that use the theme, and minimize the effort needed to upgrade.
 - Do not surprise people (especially with negative surprises) and provide time for projects to provide feedback about upcoming features.

docs/community/practices/versions.md

@@ -1,24 +1,24 @@
 # Supported Python and Sphinx versions
 
 Python and Sphinx are the two primary dependencies of this theme.
-We have special practices for deciding which versions of these we support (especially Sphinx, which tends to release breaking changes).
+We have particular practices for deciding which versions of these we support (especially Sphinx, which tends to release breaking changes).
 
 ## Supported Python versions
 
 For releases of Python, we aim to follow this approach[^1]:
 
 > For a new major/minor release of this theme, we support any minor Python versions released in the last 3.5 years (42 months), as defined in [the EOL schedule for Python](https://endoflife.date/python)[^2].
 
-We define "support" as testing against each of these versions, so that users can be assured they will not trigger any bugs.
+We define "support" as testing against each of these versions so that users can be assured they will not trigger any bugs.
 
-For example, if we made a minor release tomorrow, we'd [look at the EOL schedule for Python](https://endoflife.date/python) and support all of the versions that fall within a 3.5 year window.
+For example, if we made a minor release tomorrow, we'd [look at the EOL schedule for Python](https://endoflife.date/python) and support all the versions that fall within a 3.5-year window.
 
 [^1]: Our support for Python versions is inspired by [NEP 029](https://numpy.org/neps/nep-0029-deprecation_policy.html).
-[^2]: These policies are goals, but not promises. We are a volunteer-led community with limited time. Consider these sections to be our intention, but we recognize that we may not always be able to meet these criteria if we do not have capacity to do so. We welcome contributions from others to help us more sustainably meet these goals!
+[^2]: These policies are goals, not promises. We are a volunteer-led community with limited time. Consider these sections to be our intention, but we recognize that we may not always be able to meet these criteria if we cannot do so. We welcome contributions from others to help us more sustainably meet these goals!
 
 ## Supported Sphinx versions
 
-For supporting versions of Sphinx, we aim to follow this approach:
+For supported versions of Sphinx, we aim to follow this approach:
 
 > We support the latest released version of Sphinx that is **older than 6 months**.
 > We unofficially support earlier released versions of Sphinx, but may increase the lower-bound in our dependency pin without warning if needed[^2].

docs/community/setup.md

@@ -18,7 +18,7 @@ of:
 For each pull request, the documentation is built and deployed to make it easier to review the changes in the PR.
 To access this, click on the {{ rtd }} preview in the CI/CD jobs.
 
-The sections below cover the steps to do this in more detail.
+The sections below cover the steps to take in more detail.
 
 ## Clone the repository
 

docs/community/structure.md

@@ -9,14 +9,14 @@ The content is written in a combination of reStructuredText and MyST Markdown.
 ## Location and structure of CSS/JS assets
 
 The CSS and JS for this theme are built for the browser from `src/pydata_sphinx_theme/assets/*` with
-[webpack](https://webpack.js.org/). The main entrypoints are:
+[webpack](https://webpack.js.org/). The main entry points are:
 
-- CSS: `src/pydata_sphinx_theme/assets/styles/index.scss`
+- CSS: `src/pydata_sphinx_theme/assets/styles/pydata-sphinx-theme.scss`
 
   - the main part of the theme assets
   - customizes [Bootstrap](https://getbootstrap.com/) with [Sass](https://sass-lang.com)
 
-- JS: `src/pydata_sphinx_theme/assets/scripts/index.js`
+- JS: `src/pydata_sphinx_theme/assets/scripts/pydata-sphinx-theme.js`
 
   - provides add-on Bootstrap features, as well as some custom navigation behavior
 

docs/community/topics/assets.md

@@ -38,7 +38,7 @@ This is configured in the `webpack.config.js` file, and imported in the respecti
 ## FontAwesome icons
 
 Three "styles" of the [FontAwesome 6 Free](https://fontawesome.com/icons?m=free)
-icon font are used for {ref}`icon links <icon-links>` and admonitions, and is
+icon font are used for {ref}`icon links <icon-links>` and admonitions and is
 the only `vendored` font.
 
 - It is managed as a dependency in `package.json`
@@ -50,7 +50,7 @@ the only `vendored` font.
 
 Our Webpack build generates a collection of [Jinja macros](https://jinja.palletsprojects.com/en/3.0.x/templates/#macros) in the `static/webpack-macros.html` file.
 
-These macros are imported in the main `layout.html` file, and then inserted at various places in the page to link the static assets.
+These macros are imported in the main `layout.html` file, and then inserted at various places on the page to link the static assets.
 
-Some of the assets [are "preloaded"](https://developer.mozilla.org/en-US/docs/Web/HTML/Link_types/preload), meaning that the browser begins requesting these resources before they're actually needed.
-In particular, our JavaScript assets are preloaded in `<head>`, and the scripts are actually loaded at the end of `<body>`.
+Some assets [are "preloaded"](https://developer.mozilla.org/en-US/docs/Web/HTML/Link_types/preload), meaning that the browser begins requesting these resources before they're needed.
+In particular, our JavaScript assets are preloaded in `<head>`, and the scripts are loaded at the end of `<body>`.

docs/community/topics/bootstrap.rst

@@ -10,16 +10,16 @@ Dropping **JQuery**
 Bootstrap Dropped its **JQuery** dependency and rewrote plugins to be in regular JavaScript.
 Sphinx *v6* will do the same (https://github.com/sphinx-doc/sphinx/issues/10070).
 As a consequence, we also rewrote all our javascript to only use vanilla **JavaScript**.
-Any documentation relying on **JQuery** in their ``custom.js`` files will need to rewrite it or specifically import **JQuery**.
+Any documentation relying on **JQuery** in their ``custom.js`` files will need to rewrite or specifically import **JQuery**.
 
 Breaking changes
 ----------------
 
 ‼️ Relevant for those using a ``custom.css`` and/or a ``custom.js`` file!
 
-Bootstrap changed a number of CSS classes, so if you wrote custom rules of JS logic that depended on them, it may have changed.
+Bootstrap changed several CSS classes, so if you wrote custom rules of JS logic that depended on them, it may have changed.
 
-All of the changes from *v4* to *v5* are `listed in their documentation <https://getbootstrap.com/docs/5.0/migration/>`_.
+All the changes from *v4* to *v5* are `listed in their documentation <https://getbootstrap.com/docs/5.0/migration/>`_.
 Below list the ones that had consequences on ``pydata-sphinx-theme`` components.
 
 Sass
@@ -57,4 +57,4 @@ Utilities
 JavaScript
 ^^^^^^^^^^
 
--   Data attributes for all JavaScript plugins are now namespaced to help distinguish Bootstrap functionality from third parties and your own code. For example, we use ``data-bs-toggle`` instead of ``data-toggle``.
+-   Data attributes for all JavaScript plugins are now namespaced to help distinguish Bootstrap functionality from third parties and your code. For example, we use ``data-bs-toggle`` instead of ``data-toggle``.

docs/community/topics/config.md

@@ -8,7 +8,7 @@ Here are some tips to do this the "right" way in Sphinx.
 ## Update config: use `app.config`
 
 For example, `app.config.foo = "bar"`.
-For some reason, when Sphinx sets things it directly uses `__dict__` but this doesn't seem to be different from the pattern described here.
+For some reason, when Sphinx sets things it directly uses `__dict__`, but this doesn't seem to be different from the pattern described here.
 
 ## Update theme options: use `app.builder.theme_options`
 

docs/community/topics/manual-dev.md

@@ -51,15 +51,15 @@ $ sphinx-build docs docs/_build/html
 
 ## Compile web assets (JS/CSS)
 
-To compile the javascript and CSS assets for the theme, run the following command:
+To compile the JavaScript and CSS assets for the theme, run the following command:
 
 ```console
 $ stb compile
 ```
 
 This will compile everything in the `src/pydata_sphinx_theme/assets` folder and place them in the appropriate places in our theme's folder structure.
 
-## Start a live-server to build and serve your documentation
+## Start a live server to build and serve your documentation
 
 To manually open a server to watch your documentation for changes, build them, and display them locally in a browser, run this command:
 

docs/user_guide/ablog.md

@@ -1,13 +1,13 @@
 # Blogs with `ABlog`
 
 The [ABlog extension](https://ablog.readthedocs.io/) allows you to tag pages as **blog posts** and additionally include them in landing pages for your blog.
-It also has a number of sidebar templates to show off collections of your posts.
+It also has several sidebar templates to show off collections of your posts.
 
 :::{admonition} Minimum version ABlog v0.11.0
 Make sure you have `ABlog>=0.11.0rc2` in your dependencies.
 :::
 
-This theme has styling support for ABlog, and demonstrates some of its functionality here.
+This theme has styling support for ABlog and demonstrates some of its functionality here.
 
 ## Example blog