Penpot as dual source of truth — Event Model and UI

2026-03-02 02:36:32.516Z

Penpot serves two distinct roles in NEXUS, and
understanding both is essential to understanding
why it was chosen and what it enables. In both
roles, Penpot is not a reference artifact — it
is the authoritative source of truth.

Role One — Event Model Authoring

The Event Model is always a timeline. Penpot is
where that timeline is drawn.

The left-to-right temporal layout, the swim lanes
separating actors and systems, the command and
event and projection elements, the slice
connections — all of it expressed as a visual
artifact in Penpot. The model is not a diagram
of the system. It is the design of the system.
The diagram and the design are the same thing.

The Event Model lives in Penpot. The link to it
lives in LOGOS. The conversations that shaped it
live in LOGOS alongside that link. The Penpot
file is authoritative — if the Penpot model and
any other description of the system disagree,
the Penpot model is correct.

Role Two — UI Screen Design and Path Documentation

UI screens are designed in Penpot. Each screen
is a design artifact representing exactly what
the UI looks like at a specific point in a
specific path.

Each path is documented as a Penpot prototype —
a linear sequence of screens connected by
prototype links, with one clickable action per
screen. The one action this path takes at this
step. The example data visible in the UI as it
would appear with real values.

Following the prototype is walking the path.
The prototype is simultaneously:

The visual specification of what the UI looks
like
The behavioral specification of what happens
at each step
The example data carrier — real values visible
in each screen
The test case — the path itself as a scenario

Closing the Design-to-Implementation Gap

The conventional design-to-development process
has a structural gap. A designer creates screens
in a design tool. A developer looks at those
screens and recreates them in code. Two sources
of truth exist from that moment — the design
and the implementation. They begin drifting
immediately. Every UI change requires updating
both. The design is aspirational. The code is
what actually runs.

Penpot exports SVG. SVG is a first-class format
for web applications. The Penpot screen design
can be the actual UI consumed by the application
— the SVG output used directly rather than
recreated by a developer.

When this is the case:

There is one source of truth — the Penpot file
Design changes propagate to the UI directly
The developer wires behavior to the design
rather than recreating the design in code
The gap between design and implementation
structurally cannot exist

The design is not aspirational. It is
authoritative. What Penpot shows is what
the application renders.

The Combined Picture

Penpot holds both sources of truth simultaneously:

Event Model — the behavioral source of truth.
What the system does. What commands exist, what
events they produce, what projections consume
them, how actors interact with the boundary.
The complete behavioral design of the system.

UI screens — the visual source of truth.
What the system looks like. The exact appearance
of every screen at every point in every path,
with example data showing real values.

Both live in the same tool. Both are authoritative.
Neither is documentation after the fact.

Combined with AI implementation this produces a
complete picture: the human designs behavior
in the Event Model and appearance in Penpot
screens. AI wires the two together — binding
SVG elements to commands and projections from
the model. The human designs. AI implements
the connection.

Why Penpot Specifically

Penpot is open source and self-hostable. This
is not incidental — it is a requirement of any
tool in the NEXUS ecosystem. You own your
designs. No vendor can change pricing, revoke
access, or alter export formats in ways that
break the pipeline.

Penpot's SVG export is clean and standard.
The export path from design to application
is not dependent on proprietary formats or
vendor-specific tooling.