Add Legend to Diagrams

[jamestiotio]

Feature Request Description

I would like to request the capability of adding a legend to diagrams.

The use case that I have would be to highlight a "normal operating path" and other "fault handling" paths in a state machine, something along the lines of this:

Searching online, we can also see various examples of engineering diagrams that highlight some kind of "active path" or "critical path" such as this and this (credits to their original authors). This shows that this type of diagram is used quite prevalently and that it can benefit from this legend.

Proposed Solution/Implementation

The legend feature should allow users to create a separate shape within the diagram that contains a key of elements and their corresponding meanings in text. Each element can be either a shape or a connection.

Users should be able to customize the appearance of each element and the legend box itself (e.g., fill color, border radius, etc.), just like any other shape. This would allow the users to categorize different elements depending on their style (e.g., opacity, fill, stroke, etc.) to give them their appropriate meanings.

Benefits

• Improve the clarity and readability of complex diagrams that contain a lot of shapes, such as state machines.
• Allow users to better communicate the intended functionality of a system by including a legend embedded in the diagram itself.

Alternatives

My current workaround to generate the SVG above would be to do something as shown here. Another example would be this, which would generate the following diagram:

Basically, we add several invisible elements to act as the legend and style them appropriately:

legend.source -> legend.destination: Forward {
  style: {
    stroke: green
  }
}

legend.destination -> legend.source: Backward {
  style: {
    stroke: red
  }
}

legend: {
  style: {
    fill: transparent
    opacity: 0
  }
}

legend.source: {
  style: {
    fill: transparent
    opacity: 0
  }
}

legend.destination: {
  style: {
    fill: transparent
    opacity: 0
  }
}

However, this approach has its limitations:

• The layout engine will consider the legend container along with its children as a separate root-level shape, and thus, the positioning of the legend can be inconsistent, especially in more complex diagrams with more shapes. The legend container and its children cannot use the near keyword to help with its positioning relative to the whole diagram as constant near keys cannot be set on shapes with children and constant near keys can only be set on root level shapes. This is demonstrated by the 2 diagrams above, which puts the legend in different places. This can also be seen here, where the direction: right directive leads to the TALA layout engine putting the legend to the right of the actual diagram.
• The legend, source, and destination texts are technically still in the diagram, which means that they can be found/extracted by carefully analyzing the SVG output. That said, they are not visible in the PNG output.

Alternatively, we can manually draw the legend using another tool such as diagrams.net and package that diagram together with the D2-generated diagram, such as by putting them together in a ZIP file or combining them using other image processing tools. However, this is a little clunky and it would be great if D2 can generate the legend by itself. Adding the declaration to generate the legend into the D2 source file itself would also help keep track of changes to the legend itself when users check in the D2 source file into version control.

[alixander]

Once D2 supports near keywords on containers, which isn't much work, the first limitation will be crossed off. (#848)

The second limitation I don't agree with, unless there's something I'm not understanding. The legend would always be visible and in the outputs of both SVG and PNG. If you really want to hide the texts you can even set the labels to "".

The bigger question is whether we want to support a first-class way of defining legends, with custom keywords and all.

This task feels really large. I imagine the variations of legends people want will be a lot.

• Icons
• Colored shapes
• Mini styled arrow

Pretty endless. I think the best thing for us to do right now is to do the work needed to build a custom legend, and then put a section in docs like, "Recipes" or something that shows constructions of legends.

[jamestiotio]

Ah, I was not aware that you could set the label to "". Thank you for that! In that case, the second limitation should be a non-issue.

I don't mind using my workaround, assuming that the first limitation is eliminated. Once that's done, I can also help add a section in docs to show how to construct custom legends using this approach. If you have any suggestions on how to create legends in a better way, do feel free to bring them up!

Regarding the addition of defining first-class legends, I am not particularly for or against it. As long as there is a way to build custom legends, with D2 offering some level of support (and it does not have to be creating a native, first-class entity specifically for legends), then it should be fine.