Merge pull request #1342 from XRPLF/contrib_theme_aware_diagrams

Contributing: document theme-aware diagram tech

CONTRIBUTING.md

@@ -26,7 +26,7 @@ The XRPL Dev Portal provides comprehensive documentation of the the XRP Ledger,
 - [template/](template/) - Template files for building the HTML outputs.
 - [tool/](tool/) - Filters, style-checker rules, and other scripts.
 - [styles/](styles/) - Source files (SCSS) to generate the CSS files in the assets folder.
-- [`dactyl-config.yml`](dactyl-config.yml) - Main config file, which contains the metadata for all the docs. For information on our conventions, see [Config Formatting](#config-formatting).
+- [`dactyl-config.yml`](dactyl-config.yml) - Main config file, which contains the metadata for the site. For information on our conventions, see [Config Formatting](#config-formatting).
 
 ## Requirements for a Successful Pull Request
 
@@ -46,7 +46,7 @@ Dactyl requires [Python 3](https://python.org/). Install it with [pip](https://p
 
 ## Building the Site
 
-This repo uses [**Dactyl**](https://github.com/ripple/dactyl) to build HTML display versions of all the documentation. After you've done the [Dactyl Setup](#dactyl-setup), you can build the docs from the project root directory:
+This repo uses [**Dactyl**](https://github.com/ripple/dactyl) to build HTML display versions of all the documentation. After you've done the [Dactyl Setup](#dactyl-setup), you can build the site from the project root directory:
 
 ```
 dactyl_build
@@ -199,3 +199,33 @@ For the Markdown content files, please use the following conventions:
 
 - Line-feed newline characters (`\n`) only (Unix style). Do not use carriage return (`\r`) characters (Windows style).
 - Use UTF-8 encoding. Avoid the use of Byte-order marks.
+
+
+## Theme-Aware Diagrams
+
+The site contains code to automatically recolor SVG diagrams for light and dark mode. This is more than just inverting images. The recoloring keeps gradients going the same direction (so that things don't look bottom-lit) and replaces colors with equivalents that fit with the theme rather than their inverse. For example, "Ripple blue" gets recolored to XRPL green, not its inverse orange. Example:
+
+![Comparison of invert and theme-aware recoloring](./theme-aware-recolor.png)
+
+Theme-aware recoloring uses a single source file in SVG format for diagrams, and produces diagrams that are recolored to match the current theme (light/dark) using CSS. If the user changes their theme, the diagrams immediately change to match it.
+
+To include a theme-aware diagram in a document, use the `include_svg` filter with syntax such as the following:
+
+```jinja
+{{ include_svg("img/anatomy-of-a-ledger-complete.svg", "Figure 1: XRP Ledger Elements") }}
+```
+
+Leave empty lines before and after this syntax. The SVG file in question should be in the [`img/`](./img/) folder at the top level of the repo, or a subfolder of it. The second argument is _title text_, which appears when the user hovers their mouse over the diagram, and can also be used by other software (such as screen readers) to caption the diagram.
+
+The resulting SVG file is inlined directly into the Markdown file. One limitation is that you can't use it inside other Markdown structures such as bulleted lists or tables.
+
+> **Note:** The filter source code is [`tool/filter_include_svg.py`](./tool/filter_include_svg.py). This is also the reason that `lxml` is one of the dependencies for building the site.
+
+### Making Diagrams
+
+You have to take care when creating diagrams so that the recoloring applies correctly; otherwise, some elements might be invisible (white-on-white or black-on-black, for example) when recolored for the other theme. The theme-aware diagrams code supports diagrams created using either [Umlet](https://www.umlet.com/) or [Google Draw](https://docs.google.com/drawings/) and exported as SVG. Additionally, you should follow these guidelines when making diagrams:
+
+0. Create diagrams for light mode by default. Use a transparent background color.
+0. Only use colors that the theme-aware diagrams code has mappings for. The code for this, including the full list of colors, is in [`styles/_diagrams.scss`](./styles/_diagrams.scss). If needed, you can add new colors by extending the SCSS code. (Don't forget to re-export the CSS when you're done. See the [styles README](./styles/README.md).)
+0. Use actual vector shapes instead of embedded icons/images whenever possible. If you need to put text on top of an image, add a solid background to the text element and use one of the colors the theme has mappings for.
+0. Don't layer transparent elements containing text on top of elements with different background colors. Apply a background color directly to the element that contains the text.