Bluefish: Composing Diagrams with Declarative Relations

TL;DR

Bluefish introduces a relational diagramming framework that replaces traditional UI components with overlapping, declarative relations, enabling expressive, domain-aligned diagrams while preserving declarativity and composability. It extends tree-based scenegraphs to compound graphs that capture both hierarchical and adjacency relationships, using lazy coordinate transforms and dimension-based ownership to manage under/overconstrained layouts. A diverse gallery demonstrates practical utility across domains and shows linear layout-time scaling, with comparative analyses against Penrose and Basalt highlighting tradeoffs between locality and expressiveness. The work argues for a practical, extensible diagramming platform that blends UI-layout ideas with diagram-specific needs, and it outlines future directions including interactive capabilities and richer notational semantics.

Abstract

Diagrams are essential tools for problem-solving and communication as they externalize conceptual structures using spatial relationships. But when picking a diagramming framework, users are faced with a dilemma. They can either use a highly expressive but low-level toolkit, whose API does not match their domain-specific concepts, or select a high-level typology, which offers a recognizable vocabulary but supports a limited range of diagrams. To address this gap, we introduce Bluefish: a diagramming framework inspired by component-based user interface (UI) libraries. Bluefish lets users create diagrams using relations: declarative, composable, and extensible diagram fragments that relax the concept of a UI component. Unlike a component, a relation does not have sole ownership over its children nor does it need to fully specify their layout. To render diagrams, Bluefish extends a traditional tree-based scenegraph to a compound graph that captures both hierarchical and adjacent relationships between nodes. To evaluate our system, we construct a diverse example gallery covering many domains including mathematics, physics, computer science, and even cooking. We show that Bluefish's relations are effective declarative primitives for diagrams. Bluefish is open source, and we aim to shape it into both a usable tool and a research platform.

Figures (10)

• Figure 1: A comparison of specifying a simple diagram of the four terrestrial planets in a UI framework and in Bluefish. In both cases the user (1) makes a horizontal stack (StackH) of Circles contained in a Background; (2) places a Text component above Mercury; and (3) surrounds the annotation and the planet with a background. In a UI framework, while (1) is declarative, (2) and (3) require error-prone, low-level bounding box computations. In contrast, all three steps are declarative in Bluefish.
• Figure 2: The Bluefish API comprises a standard library of marks and relations as well as a core set of language primitives. Bluefish relations are closely associated with Gestalt relations (listed in gray next to each tag). Scoped declarative references allow users to refer to existing elements. The Group relation, withBluefish function, and Layout component allow users to create new marks and relations.
• Figure 3: Relations can trade locality for expressiveness. (1) With the original spec, one can flip the direction of the label. (2-3) After denesting the Background and StackV relations one can replace the Background with an Arrow. (4-5) After breaking up StackV into Align and Distribute, one can space the label relative to the planets background while keeping it aligned with Mercury.
• Figure 4: The tree-structured and relational scenegraphs corresponding to \ref{['fig:ui-vs-bluefish']}. Notice that Bluefish's scenegraph retains more information than a tree-structured scenegraph. Bluefish's scenegraph represents the StackV and Background relations between the label and the planet. In the traditional scenegraph the StackV relation between the label and the planet is missing, and the Background relation has been reduced to a Rect component.
• Figure 5: When a bounding box dimension is requested via a Ref, intermediate transforms are lazily materialized. This ensures the dimension is well-defined relative to the requester.