image guidelines (and borders)

Author: josh-heyer

advocacy_docs/community/contributing/styleguide.mdx

@@ -606,7 +606,7 @@ Use images to clarify a topic, but use them only as needed. Images are either:
 
 * **Screenshots** — Provide a UI visual. Don’t use to show dialog boxes and parts of the UI a user can see for themselves, as these are hard to maintain and don’t provide useful information. If a screenshot needs an annotation, use a red box.
     
-* **Diagrams** — Provide a visual of a complicated theory. Diagrams must be simple and easy to read.
+* **Diagrams** — Provide a visual of a complicated theory. Diagrams must be clean and easy to read.
     
 
 **Syntax:**
@@ -617,6 +617,38 @@ Use images to clarify a topic, but use them only as needed. Images are either:
 
 `![PEM Architecture](../images/pem_architecture.png)`
 
+### Screenshot recommendations
+
+Reserve screenshots for situations where the complexity of a user interface exceeds what you can comfortably describe (or render using text in [a code block](#code-blocks)). A good screenshot aids the reader in recognizing what the text is describing, but does not replace textual instructions. 
+
+- Use PNG format for screenshots; avoid JPEG (JPEG compression artifacts can be distracting).
+- Limit the resolution of images; very large screenshots take longer to load and can be difficult to view. 
+- Crop the edges and make judicious use of arrows or highlighting to draw attention to areas of interest. 
+- Do not add borders; the Docs system will add borders appropriate for the color scheme.
+- Give screenshots names that describe the feature or form it represents, and place them in the filesystem near the topic that references them. E.g.,
+  ```
+  /cluster/index.mdx
+  /cluster/settings.mdx
+  /cluster/images/settings-ha-options.png
+  ```
+
+### Diagram recommendations
+
+Diagrams are often helpful in reducing the complexity of overviews, explanations, or system architecture. A good diagram provides, at a glance, more information than can be conveyed in an equivalently-sized paragraph. Diagrams are particularly useful as a tool for showing connections between system components that will be described in prose immediately afterwards. 
+
+- Use a tool that suits the needs of the diagram you need to create. LucidChart and Figma are good for general-purpose work; if a diagram is generated from existing data, other tools might be more useful.
+- Try to use a tool that'll export SVG and a design file that can be re-imported later.
+- Check in both the SVG and the design file - that way if we gotta change it later, we can edit the design file instead of the SVG.
+- Crop your diagram when exporting - don't have a little diagram in a field of white.
+- Feel free to use a transparent background, but then DO use background fill on individual elements where necessary for legibility - we have a dark theme & it needs to stay readable!
+- Use the Roboto mono font, min 7 pt.
+- Use our brand colors (<https://enterprisedb.atlassian.net/wiki/spaces/EDB/pages/3998613556/Colors>).
+- Keep diagrams clean and professional - "napkin sketch" styling might be appropriate for a blog post or presentation where you're talking through a process, but documentation should reflect a complete understanding of the topic.
+- If there's a moderate level of detail, link to the diagram as well as embedding, e.g. `[![proxy connections](images/proxy.svg)](images/proxy.svg)]`.
+  - If there is a high level of detail (to the extent that the diagram becomes unreadable at embedded sizes), break the diagram into multiple diagrams showing e.g. an overview and individual components... Or re-think the level of detail that is necessary. Do not *require* readers to "click through" to a diagram to percieve it.
+
+And remember that not every reader's visual acuity will be up to the task of interpreting a diagram; they are useful as an aid, but should never be the *only* source of critical information!
+
 ## Dates
 
 When specifying dates for human readability, use the DD mmm YYYY format with a short month name in English. Where the date is being used in a column in a table, use a leading 0 on the day of month for easier alignment, for example, 01 Jan 2024.

src/styles/_docs.scss

@@ -35,6 +35,37 @@ label.link-label {
   }
 }
 
+/* Images */
+.gatsby-resp-image-wrapper:has(img[src$='.png' i], img[src$='.jpg' i], img[src$='.jpeg' i]):has(img[srcset*="540w"])
+{
+  box-shadow: 
+    0 0 1px rgba(from var(--bs-body-color) r g b / 0.3), 
+    0 0 2px rgba(from var(--bs-body-color) r g b / 0.25), 
+    0 0 3px rgba(from var(--bs-body-color) r g b / 0.2), 
+    0 0 4px rgba(from var(--bs-body-color) r g b / 0.15), 
+    0 0 5px rgba(from var(--bs-body-color) r g b / 0.1);
+  border-radius: 5px;
+  overflow: clip;  
+  background: white;
+}
+
+a:has(img) { position: relative; display: block; }
+a:has(img):after
+{
+  content: '';
+  width: 24px;
+  height: 24px;
+  position: absolute;
+  top: 0;
+  right: 0;
+  display: block;
+  background: var(--bs-body-color);
+  mask-image: url('data:image/svg+xml;utf8,<svg viewBox="0 -256 1850 1850" xmlns="http://www.w3.org/2000/svg"><g transform="matrix(1,0,0,-1,30.372881,1426.9492)"><path d="M 1408,608 V 288 Q 1408,169 1323.5,84.5 1239,0 1120,0 H 288 Q 169,0 84.5,84.5 0,169 0,288 v 832 Q 0,1239 84.5,1323.5 169,1408 288,1408 h 704 q 14,0 23,-9 9,-9 9,-23 v -64 q 0,-14 -9,-23 -9,-9 -23,-9 H 288 q -66,0 -113,-47 -47,-47 -47,-113 V 288 q 0,-66 47,-113 47,-47 113,-47 h 832 q 66,0 113,47 47,47 47,113 v 320 q 0,14 9,23 9,9 23,9 h 64 q 14,0 23,-9 9,-9 9,-23 z m 384,864 V 960 q 0,-26 -19,-45 -19,-19 -45,-19 -26,0 -45,19 L 1507,1091 855,439 q -10,-10 -23,-10 -13,0 -23,10 L 695,553 q -10,10 -10,23 0,13 10,23 l 652,652 -176,176 q -19,19 -19,45 0,26 19,45 19,19 45,19 h 512 q 26,0 45,-19 19,-19 19,-45 z" style="fill:currentColor"></path></g></svg>');
+  mask-repeat: no-repeat;
+  mask-size: 100%;  
+}
+
+
 /* Search */
 .global-search {
   .select-product {