# Causally Looped: Token Diagrams in Code

By [Zane](https://paragraph.com/@zane) · 2022-07-08

---

![](https://storage.googleapis.com/papyrus_images/79f3acdf5dbeeb066b1d3e18646c74eb5a3cf44baee6c100e85e25d48136f74b.jpg)

### Dia Dia Dia Diagrams

Diagrams are an essential tool in token engineering. Not having a way to share, reuse, iterate, extend and collaborate on diagrams hurts. So today we're introducing a way to solve this problem, with simple off the shelf open source tooling and a style guide. Stay tuned to grab the details or go straight to the [repo](https://github.com/zcstarr/casually-looped).

![](https://storage.googleapis.com/papyrus_images/68096e1fce0462f3bc3ba03e9f63aacc414b99add4df45b96d8182a55ab2b5d0.png)

Causal Loop Diagrams are diagrams that help us visualize the relationships between entities. **‘+’** represent positively correlated relationships and **‘-’** negatively correlated relationships.

The diagrams help us recognize what behavior should be captured within our token models. Here's a pro [guide](https://online.visual-paradigm.com/knowledge/causal-loop-diagram/what-is-causal-loop-diagram/)

### What about shareability?

![](https://storage.googleapis.com/papyrus_images/2d8a0b1226bb6884dcd89f36ac58a0249dfa2bbd0db1513c954b85c62ed45d25.png)

One of the key things missing from the current ecosystem of tools [nloopy](https://ncase.me/loopy/), [lucid charts](https://www.lucidchart.com/pages/), and [Diagrams](https://app.diagrams.net/) is a way to keep track of changes, reuse existing diagrams in new context, and iterate on diagrams async, with the ability to review and annotate changes.

Committing diagrams to a repository in a tractable way would increase productivity and knowledge sharing capability 10x.

### Introducing a code based solution ( MermaidJS)

[MermaidJS](https://mermaid.live) is a diagramming as code tool that allows you to create different types of diagrams using a very small easy to learn/use language. It shares a significant overlap with it's older sibiling [PlantUML](https://plantuml.com/)

It has a very simple syntax, and has the ability to produce charts in a variety of rendered formats, and can even be rendered directly in [Jupyter](https://github.com/mermaid-js/mermaid/blob/0f8df335a7d1b3ef53e08ea2f99402ccf2e9f071/docs/Tutorials.md#jupyter-integration-with-mermaid-js) notebooks.

### Quick Example ([live example](https://mermaid.live/edit#pako:eNp1U01PwzAM_StWULUhNolzkZAmjRsCNBCnXrzWZRFpUiWe0LT1v-MkKx9j9NDWznvPz4mzV7VrSJWqKPbaai5hP-ENdfSKXuPaUJhIahiGoqhsUUDtuo4sB0jRy0YHaDS-eeygIUZtAggdJNFvKlvZ9AP3K8EDCKMsS_agM6o2GIRPbaysnZUkMgTeSVlAsOLsSIvo1vlOloVrsaPH9kGWp_EFBtdkLkU6UrV9S7qxeuJGmZ9FAtXxG1d7x9KMRrNoXM_kw_RpzAAeU5fJckSnjDBXyDRdHAPwEp1gotDihP5lZz6_zW4ob4Ing1EobHQP6L37kB312ePIOVyB8zA_ZOLI5F1P4Fo5Ez-KjNv8S_Rc72e7T94OV4dfnZ52nkHi5Q_9LPJb7yfi_2J5ysbBADnw2OraMbtOoE0cDPZoQ4-ySTtglwDxkJN8oi6FKWPWamPKi-vjM5PJ8u6dvjM3lVUz1ZHMlW7kDuyjQKXS_FeqlF-xgFvDlarsINBt34jJu0az80qOdUszhVt2zztbj3HGLPOlyMnhExHDLhc))

![](https://storage.googleapis.com/papyrus_images/b661b5b56e3e5c5c88778615f80fb09b5c8541c6a3dfbe9efe0eef5faf812d64.png)

    
    %%{init: {'themeVariables': {}}}%%
    %% comments 
    %% This diagram details the graph
    
    graph LR 
      %% :::tr is the class definition that styles a node
      %% the format is nameOfNode[Node label]:::stylingclass
    
      %% node definition section
      potentialAdopters[Potential adopters]:::tr
      adoptionRate[Adoption rate]:::tr
      adopters[Adopters]:::tr
    
    
      %% --> defines the relationship arrow directionn
      %% |+ or -| definnes the type of correlation 
      %% relationship definition section
    
      potentialAdopters --> |+| adoptionRate
      adoptionRate --> |-| potentialAdopters
      adoptionRate -->  |+| adopters
      adopters --> |+| adoptionRate
    
    %% class def at the bottom adds a transparecy to the nodes
      classDef tr fill:#00000000, stroke:#00000000;
    

So what's next ?
----------------

Check out the [repo](https://github.com/zcstarr/casually-looped), for the style guide. Create issues let us know what you think, open to suggestions as this develops.

Eventually this will be in a more commons oriented repo, as we create a basis for moving diagrams into code and creating improvements to this systems.

Some things that we can improve on

*   We need a style linter for the documents
    
*   notes to be added to the diagram directly
    
*   improved naming conventions
    
*   improved auto layout functionality.
    

### Steps forward

This represents a few steps forward, a future in which we can simply clone or compose diagrams to represent the dynamics in our ecosystem. Will make for a better token engineering ecosystem.

#### Acknowledgements

Special thanks to [@shanejonas](https://twitter.com/shanejonas) for review. Shout out to QuietCataylst,Ratio13, and Elbeth for the feedback for this concept.

---

*Originally published on [Zane](https://paragraph.com/@zane/causally-looped-token-diagrams-in-code)*