MediaWiki Engineering/Guides/diagrams.net conventions

These are conventions for Wikimedia diagrams in technical writing, as created using the diagrams.net open-source software.

In a nut shell

It's a web app. It works a lot like Google Docs, except it's open-source and its for creating diagrams. Get started at https://diagrams.net/.
Save your work publicly. You can open a diagram from your device hard disk, or from a cloud service like Google Drive. To benefit from easy saving, sharing, and backups, it is recommended for WMF staff to store their work in their Google Drive, and to make these files public to the world by link so that others can easily copy them to create their own diagrams or to make an updated version of yours.
Design.
- The below #Style reference incorporates this for you, but prefer colors and fonts from the Wikimedia Design Style Guide.
- Try to keep a good color contrast for readability (e.g. dark text on light background with solid outlines).
Legend. Avoid long sentences and text. Avoid many colors or shapes. If using more than one color or shape, consider labelling these or including a legend that explains their meaning.
Export as PNG and upload this to Wikimedia Commons for use in articles on Wikitech or any other WMF wiki. Link to your drawio file from the file description (the Google Drive file's share link).

Logged-in with your work Google Account.
Name: Name of subject or concept and a date or year, e.g. "ProjectX ComponentY 2021" or "Draft of X (Jan 2021)".
Format: XML drawio (default).
Template: Blank (default).
Prompt "Use root folder?" - This is asking whether you wanted to use a subdirectory within your Google Drive, or simply in your main drive ("root").

This is a one-time set up for the first text object in your diagram. After this you can always select "Lato" from the list of fonts.
Create your first text object (e.g. for the main heading) by clicking "Text" in the "General" shapes drawer.
Open the "Text" styles in the "Format Panel". This is the right-hand sidebar. If needed, open it first from its button in the top-right corner.
Click on the Font menu and, assuming Lato is not yet in the list, choose "Custom".
Choose "Google Font" from the modal dialog.
Enter font name: Lato
Click "Apply".

Save your changes and in a new tab go to https://drive.google.com/
Select the diagram.
Click "Share" to open the share dialog.
In the "Get the link" section change visibility to "Anyone with link".
Click "Copy link". We will use this link in the file description when we upload the diagram to the wiki, so that others can find the source and can easily create a copy of it to make future versions of this diagram without having to re-create it from scratch.

Export the diagram as as high-resolution PNG:

In the diagrams.net interface, go to "File" and select "Export > as PNG…". (avoid SVG as this does not render reliably cross-platform, especially when fonts and labelled arrows are used. It also might not render correctly when systems with WordPress or MediaWiki render thumbnails differently than a browser would.)
Use these settings:
- Zoom is 200% (instead of 100%). This ensures text is sharply rendered on modern devices.
- Border is 0 (default).
- Size "Diagram" (default).
- Disabled "Transparent background" (default). If you were to enable this, the text and diagram may become largely unreadable when displayed by someone in dark mode or otherwise displayed on a colored background. For example, if you use the diagram in a blogpost and someone reads it in Reader mode, or in a News reader app. If you want to do this, make sure all boxes in the diagram have an explicit background color (e.g. white instead transparent). And for any heading text to have a shadow or other color behind it to avoid it becoming invisible on a dark background.
- Disabled "Shadow" (default).
- Disabled "Grid" (default).
- Disabled "Include a copy of my diagram" (instead of default enabled). This is inclusion makes the file larger and is not needed as we will share the editable diagrams file via Google Drive instead.
Click "Export".
Click "Download".

Upload to Wikimedia Commons, after which you can display it on any public or private WMF wiki page:

Go to Upload file.
Add the downloaded diagram PNG, continue.
Select a Creative Commons license. For diagrams, I'd recommend the "CC0 Waiver (like public domain)" or "Attribution 4.0" option.
Commons categories to consider using:
- Computer architecture diagrams (or if applicable, more specifically: Wikimedia servers diagrams)
- Wikimedia technical operations (or if applicable more specifically: Wikimedia servers diagrams)
- Diagrams in English
- MediaWiki development (if applicable)
Under "Add location and more information", edit the "Other information" field and make a link to your diagram source so that others can fork and improve upon it.
- As per #Save and share the diagram, if you've saved it to your Google Drive, browse to your Google Drive, select the diagram file and "Share" it to "Anyone with a link" (Viewer rights), and then copy the link to the Commons upload page e.g. in the form [my_share_link Edit this diagram]. For an example, refer to File:Wikipedia_webrequest_2022.png.

Heading:
- Font weight: bold
- Font size: 30 pt
- Font color: #202122 (Wikimedia Base10)
Large text: (e.g. for main heading's caption)
- Font size: 20 pt
- Font color: #72777D (Wikimedia Base30)
Regular text, such as labels, and legends:
- Font size: 15 pt
- Font color: #54595D (Wikimedia Base20)
Small text:
- Font size: 13 pt
- Font color: #54595D (Wikimedia Base20)

Styles:
- Border: 2pt solid, for all boxes, arrows, containers, and other shapes.

Text:
- Text in objects
  - Font size: 15pt, like Regular text
  - Font color: #202122 (Wikimedia Base10, for improved contrast)
- Horizontal alignment: Center
- Verical alignment: Middle
- Spacing (kind of like box/cell padding, to offset text from edges)
  - Global: 5pt
Arrangement:
- Minimum height for most objects: 40 pt (to accommodate "Regular text")
Variants:
- Blue:
  - Background color: #EAF3FF (Wikimedia Accent90)
  - Border color: #2A4B8D (Wikimedia Accent30)
  - Font color for Large text: 2A4B8D (Wikimedia Accent30)
- Yellow:
  - Background color: #FEF6E7 (Wikimedia Yellow90)
  - Border color: #AC6600 (Wikimedia Yellow30)
  - Font color for Large text: AC6600 (Wikimedia Yellow30)
- Green:
  - Background color: #D5FDF4 (Wikimedia Green90)
  - Border color: #00AF89 (Wikimedia Green50, more lively than Green30)
  - Font color for Large text: #14866D (Wikimedia Green30)
- Red:
  - Background color: #FEE7E6 (Wikimedia Red90)
  - Border color: #B32424 (Wikimedia Red30)
  - Font color for Large text: #B32424 (Wikimedia Red30)
- Grey:
  - Background color: #F8F9FA (Wikimedia Base90)
  - Border color: #A2A9B1 (Wikimedia Base30)
- White (primary):
  - Background color: transparent, none, or #FFFFFF
  - Border color: #C8CCD1 (Wikimedia Base70)
  - Font: Regular text
- White (muted)
  - Border color: #EAECF0 (Wikimedia Base80)
  - Font: Regular text