11. Diagram element

The visual stacking priority dictates which elements appear over others.

Elements can be moved, and except for arrows and anchors, can be sized.

When created, all elements appear in the upper start-side corner. Preferably use the Clone action to place further elements of the same type, because that will likely only involve incremental moving from the current offsets rather than from the parent origin. All elements are created as having errors. This ensures that each will have a direct link to them in the diagram's child navigation bar, as some may be obscured by other elements. The errors are cleared when moved and text provided for those that need it.

When background images are specified for diagrams and overlays they cover the whole area up to the borders, repeating in each direction if needed. If an element has a border, anchors in opposite corners will usually be required to provide an area between its contents and the borders to look aesthetically framed.

If an element is moved to another element using the To facility or Spikes, its coordinates are retained to retain relative positions with other elements that may be being moved as well. Preferably use overlays and suboverlays to enable moving multiple elements at once as they make it easier to reposition them at their new location in their current spatial relationships.

When moving a bunch of elements from a diagram into a new overlay, many may be well outside of the overlay because of the retained offsets. Once all the required elements have been transferred, adjust any one of them by as little as one pixel and all their offsets will be recalculated to make the uppermost, start-most element be at the overlay origin.

However, deleting an element will trigger a recalculation of all offsets if it was the top-most or start-most element. To avoid unnecessary recalculations while editing, perhaps use some anchors to keep the editing origin stable until all edits are done, and then delete it.

A diagram will size to include its contents when rendered, but will never scale itself to fit. Instead, if it is too large for the area allowed for it, such as when next to an aside, a horizontal scroll bar will appear. However, while editing, even if the contents are fully exposed, a scroll bar may still appear. This will be because an element's invisible hover button is extended over the end of the visible elements. Scrolling to the end will allow the button to be hovered over to become visible.

Diagrams, overlays and suboverlays can have a background image for their child elements to annotate, though overlays and suboverlays are transparent if they don't have one.

A diagram's background image could be a detailed map for annotating. An overlay can provide a small inset of a wider area that shows the location of the detailed map within it, which is helpful for those not familiar with the geography of the area. A background could be an image of a piece of equipment, with an overlay for showing more detail or indicating the particular controls to be focused upon.

Because there are no locale-specific dimensions for diagram sub-elements, the best uses for background images and overlays are for real-world objects which are not locale-dependent. This means screenshots for documenting computer programs may not work if using multiple locales because particular areas of the screen layouts will likely vary between locales, especially if scripts of different reading directions are used. Better to use a figure with images with multiple pre-annotated locale variants for that scenario, or use labels – which can have per-locale coordinates – on it as bi-directional links to a table or list with explanations.

The images are repeated in both directions, so can be used for decorative embellishment, but be aware that that may make them more likely to be a distraction. The major consideration in using images is that what is shown of it is limited by the diagram or overlay size. The diagram size is limited to the size of its contents and not its background image.

That means that some drawing elements must be in diagonally-opposite corners to ensure that the wanted parts of the image are displayed. Use anchor elements if no other element is suitable, preferably in the lower-start and upper-end corners to keep the upper start free so that new elements can be easily selected. The size of overlays is explicitly set, irrespective of contents or image.

During editing, overlays and suboverlays have a slightly opaque grey background so that their size and position can be seen when they do not have any border or background image. It also tinges any background image. The backgrounds are subtractive, so the more they are stacked, the darker the grey gets. If one is selected, its background colour will change to pink, which also happens with a text element.

Overlays and suboverlays provide a way of grouping elements so they can be placed or copied as one, to two levels, giving a lot of flexibility and saving time for constructing repeated sections of a diagram. When copied, they are a real copy and become independently editable.

Lines can be sized in two dimensions like boxes and texts, but that their dimensions can be negative perhaps needs some explanation.

Boxes and texts are conceptually simple to size because their dimensions are always positive and the top and start-side border stay in the same place. To understand how to size lines, know that a newly-created line is a box without two of its edges, and so the two visible edges are exactly like the top and start-side of a box, namely, the top edge points to the end of the diagram, and the start-side points to its bottom. Increasing width or height positively extends the line in the dimension changed.

When decreasing a dimension of a line, the line gets shorter, and at 0 leaves just a straight line in the other dimension. Further decreasing the dimension, the dimension becomes negative and the line starts extending in the opposite direction. Throughout all these changes the point where the two edges join has not shifted, just like with a box. So the trick is to consider that point the origin of the line, so increasing height extends the vertical part of the line downwards, and vice-versa. And increasing the width extends the horizontal part of the line towards the end, and vice-versa.

Because lines have low visual priority, if they venture within the outline of another element, that part of the line that is within will be hidden. This means that lines don't have to be exactly matched to the edges of what they are supposed to be joining, allowing their dimensions to be less precise. Overlays themselves have the lowest visual priority, but their children have their normal priority, so a line will generally appear over the borders and background of an overlay, but behind any of its boxes, texts or arrows.

Diagrams will obviously not help those with severe visual impairments, but for many others, such visual paradigms also don't work.

We live in a world principally geared towards people with working eyesight, even if we need glasses. But just because we can see does not mean we will comprehend what any diagram using this element is meant to show. Just like words, diagrams are an arrangement of patterns, and just like some have difficulty visually understanding word patterns, many have difficulty understanding what the shapes mean, either in themselves or their spatial relationships.

Keeping diagrams simple enough to have their content easily understood means that they usually cannot carry the full narrative of the article, without including more content in them that would only confuse visually. Stick to using diagrams to illustrate simple concepts, relationships or workflows. Make sure their introduction accurately indicates what they are about, so the viewer will look for that information in the body of the article. It may be better to split content into separate diagrams to keep them simple.

This means that diagrams must not be the only way of communicating the information. Unless they can be used standalone, such as a visual table of contents, where the labels of the links would be read out by the screen-readers of the visually impaired, consider using diagrams in aside elements and using the article body to completely narrate the sequence, along with any clarifying comments along the way, perhaps with lists or tables.

These item limits are not expected to ever be exceeded. The limits for diagrams and overlays are for where an element can be positioned. With a width of up to 1000px, an element placed in the furthest corner with increase the diagram by its dimensions. Same for a extending a line or a moving an element in a negative direction. Allowing this excessive expansion is better than forcing absolute sizes, which would limit flexibility while designing, or moving all elements inwards because of an inadvertent negative movement.

Unless items are well spaced out, navigate using the element block hierarchy, or the keyboard as it allows tabbing forward or backwards from visible hover buttons to those for a buried element, which can then be selected by pressing Enter | return. An element can be selected for tabbing purposes by clicking somewhere in it (except if it has a link), then tabbing from there.

The tabbing order of elements is visual, proceeding from start-to-end then top-to-bottom, and they are shown in that order in element block lists. The content elements of an overlay or suboverlay are tabbed to after it. Later siblings of an overlay|suboverlay will have visual priority, even if some of its elements appear after or below them.