slsa.dev: make the diagrams easier to edit

[MarkLodato]

Currently our drawings are created in either Figma or Google Drawings. Neither of these are good for editing.

• The Figma drawings are difficult to edit. They can't be edited on Chromebooks or Linux because they use custom fonts, which only work on Windows or Mac. Plus Figma has a non-trivial learning curve.
• The Google drawings are easy to edit, but only by the owner. We can't check it in to version control.

Ideally we'd have files that can be checked into the repository and edited with free, standard, easy-to-use tools. Bonus points if the format is text-based and can be compiled in CI/CD.

[mlieberman85]

I use structurizr but it's not completely open source though free if you run it yourself. It also is really built for c4 diagrams . Here is an example of what it looks like: https://github.com/buildsec/ssf/tree/main/docs/diagrams -- the .dsl is the "code" and the .json is machine readable formatting info.

This lets you write it "as code" but tweak layout graphically to make changes. Sort of like Graphviz where you can write it as code but move around the boxes and fix the inevitable readability issues in a GUI.

It would be nice if we could find a tool that is more generic than structurizr but generally has that same flow of diagram as code, with the ability to tweak it via a GUI

[david-a-wheeler]

There are a billion number of tools for editing diagrams. Options include:

• Old school, but works, is OSS, & has tons of features: LibreOffice (e.g., SVGs).
• Markdown-happy: Mermaid https://mermaid-js.github.io/mermaid

I'm sure we can fill this PR with alternatives :-).

[MarkLodato]

After doing a bunch of research and experimentation, I recommend sticking with Figma. PR #363 fixes the font issue so that we can edit on any browser, and I have another PR coming to further streamline the Figma file.

Among all the other options, none seem nearly as good. My criteria were:

• General purpose, meaning that we can recreate our existing diagrams more-or-less exactly. This rules out most tools, such as structurizr, graphviz, mermaid, which are rigid in what the output looks like.
• Web or CLI based so that we can edit on any machine, particularly Chrome OS. This rules out desktop GUI apps, such as LibreOffice.
• File-based that we can check into version control, preferably with human-readable diffs. This rules out pure-web-based, such as Google Drawings.
• Free, preferably OSS.
• Preferably has reusable components so that we don't have to edit 5 copies when we make an edit.

The only things that I found that passed were the following:

• pikchr: This really seemed promising. The syntax is fairly readable, the output is general purpose, and it's based on a very stable language (PIC). Plus the entire interpreter is a single C99 file. I spent quite a lot of time trying to recreate our drawings with this app. Sadly, in the end, I ruled it out for two reasons:
  1. Lack of control over the style. It only lets you set a very small number of settings. (I wish you could just apply CSS directly.)
  2. Amount of effort needed to customize the diagram. I spent hours and only got half the diagram, at which point I realized this wasn't achieving the goal of this issue, which was to make editing easier.
• TikZ: I used this in another project and was happy with the results. Like PIC, this is also a stable language. You can draw and style arbitrary diagrams and the results look good. It's super flexible with making your own components. But the reason I ruled this out was because it's based on TeX, which has a huge learning curve and is quite a pain to set up builds.
• Hand-editing SVG: I thought about it, but there's so much repetition that it didn't seem worth it.
• Figma: In the end, I came to like Figma. It only took me a few hours to become moderately proficient with it, which is much faster than any of the options above (though still much longer than Google Drawings or similar.) The results look quite good, and it has reusable components which is handy since we have several variations of the same diagram. My main gripe is that the on-disk file format is binary so we can't see diffs on PRs.

---

To resolve this bug, I suggest converting the remaining diagrams to Figma. This shouldn't be too difficult, now that I know how to use Figma.

[MarkLodato]

Assuming we're sticking with Figma, this has been mostly resolved by #363. The only remaining item is to port the build model diagram to Figma.

[joshuagl]

build model updated in #375