Eve library

Eve visual language — diagrams and visualizations on every surface, seen and spoken — PRD

PRD

Revision 3

On this page

1. Status and purpose#

Proposed product requirements, prepared by claude-mac-worker on 2026-10-11 at Elikem's request. Awaiting review and Elikem's approval. Nothing here is implemented. Proposed family: eve-visual-language.

Eve should be able to draw, explain, edit and speak every kind of diagram and visualization that engineering and creative work at Oshun needs, to a standard Elikem would put in front of anyone, on every Eve surface, including when he has no screen.

The evidence for what exists today, the full list of types and the fourteen gaps are in the research document Eve — Diagrams and visualizations (revision 1). Gap numbers G1 to G14 below refer to it.

2. Decisions already made#

Elikem, in conversation on 2026-10-11, accepted all five recommendations that the research document asked him to rule on:

  1. This is a new PRD that depends on eve-interactive-artifacts. The approved PRD Eve interactive answers, live dashboards and editable motion (revision 3) is not widened.
  2. Eve stores a model of each visual and draws from it. Mermaid text stays an accepted input.
  3. The three tiers in section 6 are the order of delivery.
  4. Storyboard, moodboard, shot list and beat sheet become Eve types. Specialist creative viewers are embedded from the studio apps, not rebuilt.
  5. Diagrams derived from code, the database schema and the board are a first-class requirement.

3. Scope and authority#

  • Surfaces. The Workspace reader and editors, the reader's chat with Eve, the assistant dock in the web and admin apps, the desktop app, the Android app, Docs Center, presentations, and hands-free.
  • Built on the approved contract. A visual is a typed, validated node under Decision 1 of the ADR-0083 successor (revision 4): the model supplies a declarative specification, never markup, scripts or addresses. Observations and refresh follow its Decision 3. Queries follow its Decision 4.
  • Division of work with eve-interactive-artifacts. That family owns the answer contract, streaming, the trusted renderer layer, dashboards, scenarios, motion and exports. Its task UI.03 delivers the first charts, tables, timelines and dependency diagrams. This family owns the models, the catalogue of types, layout and visual quality, conversion of diagram text, derived diagrams, the spoken forms and the creative types. It adds to UI.03's renderers; it does not build a second set.
  • Unchanged. Saving into a governed document keeps the existing confirmation. Approval, publication, UAT promotion, keys and spending stay Elikem's. No public links. Tests bind the approved inexpensive model route.

4. Requirements#

VL-01: eight stored models#

Every visual is stored as one of eight models, each typed and versioned, with stable identifiers for its parts:

Model Parts
Graph nodes, edges, groups and boundaries
Tree a root and ordered children
Ordered sequence participants and ordered steps
Time axis items with a start, an end or a date, in lanes
Matrix rows, columns and cells
Quantitative series fields with units, and series of values
Spatial canvas regions with positions, sizes and labels
Image set ordered images, each with a description

A stored visual also carries its type, a title, a one-sentence headline, and, where it was read from a source, what it was read from and when. (Closes G6.)

VL-02: one catalogue of types#

Each type in section 6 is a named view over one model: a sequence diagram and a user journey are both views over the ordered sequence. The catalogue states, per type, its model, its tier, when Eve should choose it, and its spoken form. It is one source that the renderers, the assistant's instructions and the documentation all read.

VL-03: one set of renderers, every surface#

  • The same visual looks and behaves the same in a document, in an answer from Eve, in a slide and in Docs Center. (Closes G5, G10.)
  • The desktop dock and the web and admin dock draw what the reader draws.
  • A surface that cannot draw a type shows its text form and says the picture is available elsewhere. It never shows a blank space or raw source alone.
  • Blocks and rich-text documents can hold the same visuals, tables and images. (Closes G13.)

VL-04: layout and visual quality#

This is the requirement behind "perfect and beautiful".

  • Labels never overlap, clip or fall below the minimum text size of the design doctrine.
  • Edges are routed to avoid crossing nodes and to cross each other as little as the layout allows. Architecture views use right-angled routing, consistent direction, and visible groups and boundaries.
  • Colour comes from design tokens, in light and in dark, with no inversion filter. Colour is never the only carrier of meaning. (Closes G12.)
  • Every visual is legible at 320 pixels wide: by reflowing, by pan and zoom, or by a one-step-at-a-time view.
  • Charts carry axes, units and a legend, and follow one chart style across Eve.
  • A visual can be exported as SVG and PNG with its fonts.
  • Quality is judged on a fixed corpus per type, including large and awkward cases, by captured images that an independent reviewer assesses, plus automatic checks for overlap, clipping, text size and contrast.

The renderers and the layout engine are chosen in the architecture document after a measured comparison and a licence review. This PRD chooses none.

VL-05: Eve chooses the form#

  • Eve picks the type from the question asked, using the catalogue, and picks plain text when a picture would not help.
  • She can redraw the same content as another type on request ("show that as a sequence").
  • She has a tool that produces a visual as a model. She does not answer with diagram source text for him to read. (Closes G4.)
  • A picture made by image generation is an illustration and is labelled as one. It is never presented as a diagram of something real.

VL-06: create and edit#

Three ways, all producing the same small changes to named parts:

  • By conversation: "add a cache between the BFF and Eve".
  • By hand: select a part, rename it, add, connect, reorder, regroup.
  • By voice: see VL-09.

A change shows what it altered and can be undone. Concurrent edits follow the existing revision and conflict rules.

VL-07: what Eve accepts#

  • Mermaid text is converted to a model for the kinds the models cover. A Mermaid diagram that cannot be converted is still drawn as it is today.
  • PlantUML, Graphviz and D2 text is drawn. Today it is stored and shown as source. (Closes G3.)
  • An uploaded SVG is shown in place, made safe first. A CSV becomes data for a chart.
  • Draw.io, Excalidraw and BPMN files are imported in tier 2.
  • Existing documents keep working with no edit.

VL-08: derived diagrams#

  • Eve can generate, on request and without a hand-written source: a module and service dependency view from the code, an entity-relationship view from the database schema, a dependency graph and a timeline from the board, and a trace view from recorded traces.
  • Every part of a derived diagram maps to an identifier in its source. Eve adds nothing the source does not contain.
  • Each is stamped with the commit, schema version or board revision it was read from, and the time.
  • Refreshing makes a new observation and keeps the old one. A derived diagram whose source has moved is marked as out of date. (Closes G9.)
  • Reads of the live board follow the existing rules for read-only, time-limited queries.

VL-09: every visual has a spoken form#

  • The spoken form is taken from the stored model. A model may phrase it, but the parts, steps and numbers are those of the picture, so the two cannot disagree. (Closes G7.)
  • Three levels: the headline in one sentence; the shape on request; a walk-through.
  • Each model has its own walk: a sequence step by step, a tree from parent to children, a graph from a named node to its neighbours, a chart as headline, trend and outliers, an image set as count, common thread, then each image.
  • Understood on the device with no model and no connection: "walk me through it", "next", "back", "again", "skip the diagram", "show me later". Questions about the content ("what connects to the BFF", "which is the biggest") go to Eve and are answered from the model.
  • "Show me later" pins the figure to a list he can open at a screen.
  • An image's description is spoken. A figure is never passed in silence. (Closes G8.)
  • A sound marks the start of a figure.
  • By voice he can ask for a visual ("draw the sign-in flow") and change one ("add a step after verification"). Eve says the headline back. Nothing is saved into a document without a spoken yes.

VL-10: something to glance at#

The Android Walk screen, the lock screen and the notification show a glance card during a walk-through: one step or one part at a time, large, in step with the voice. They never show the whole diagram shrunk. (Closes G14.)

VL-11: accessibility#

  • Every type has a text form on screen, as the Mermaid figure has today.
  • Parts can be reached and read with the keyboard and a screen reader, in a sensible order.
  • Reduced motion, large text and forced colours are respected. Animation is never needed to understand a visual.

VL-12: creative types#

  • Storyboard, moodboard, shot list and beat sheet are Eve types in tier 2, usable in documents, answers and slides, and spoken like any other. (Closes G11.)
  • Tier 3 specialist views (3D turntable, scopes, animation curves, node-graph editing, piano roll) are the studio apps' existing viewers shown inside Eve under the viewer's own authorization. Eve does not rebuild them.
  • Oshun's audience rules for creative imagery apply unchanged.

VL-13: presentations#

Slide layouts draw from the same models and renderers. The slide builder's existing diagram layouts become catalogue types as each reaches the same quality. Built decks do not change until then.

VL-14: bounds and honesty#

  • The size limits of the eve-interactive-artifacts delivery specification apply. A visual that is cut short says so and says how much is missing.
  • A visual that fails to draw keeps its text form and says it failed. There is no success state without a result.
  • An unknown type or a malformed model falls back to text.

VL-15: guidance for agents#

A skill tells every agent that writes Eve documents how to choose a type, write it as a model, and check it. The catalogue is its source. (Closes the absence of a written policy.)

5. Flagship journeys#

  • J1, architecture. He asks Eve how a request travels from the app to the Eve database. She answers with a container view and a sequence. He asks for the same as a data flow with trust boundaries. He adds a part by conversation, saves it into a document after confirming, and reads it on the desktop app and on the phone with the same result.
  • J2, derived. He asks for the dependency graph of a board family. Every node opens its task. A week later the diagram is marked out of date; he refreshes it and sees what changed.
  • J3, walking. Read-aloud reaches a sequence diagram. Eve says the headline. He says "walk me through it"; she reads six steps while the phone shows one step at a time. He asks what happens if verification fails and is answered from the diagram. He says "show me later" at the next figure and finds it listed at his desk.
  • J4, creative. He asks for a beat sheet and a storyboard for a short film. He reorders two beats by voice. He opens a shot's 3D turntable from the storyboard in the embedded studio viewer.

6. The catalogue and its order#

The foundation comes first: the eight models, the contract nodes, the shared renderers, the layout engine, token theming, the text form and the spoken headline.

Tier Types
1 C4 context, container and component; deployment view; flowchart; sequence; state machine; entity-relationship; dependency graph; roadmap and timeline; user journey; user flow; line, bar, scatter, heatmap, stat tile and sparkline; comparison and decision matrix; 2×2; tree and mind map; diff and annotated code; equations
2 swimlane and BPMN; data flow with trust boundaries; Gantt; service blueprint; wireframe and wireflow; Sankey; treemap; trace waterfall and flame graph; model evaluation charts; storyboard; moodboard; shot list; beat sheet; read-only node graph; step-through animation; Draw.io, Excalidraw and BPMN import
3 3D viewer and turntable; waveform, vectorscope and histogram; dope sheet and animation curves; piano roll; geographic maps; lighting and blocking plans; interactive explorables; editable node graphs

The remaining types listed in the research document stay candidates. One is admitted by adding it to the catalogue with its model, tier and spoken form.

7. Delivery and success#

Milestone Accepts
V0 The models and contract nodes; graph, sequence and tree drawn by the shared renderers on every surface with the text form and a spoken headline; the layout comparison and the licence review recorded
V1 All tier 1 types to the VL-04 standard; Eve's tool and choice of form; create and edit by conversation and by hand; Mermaid conversion; PlantUML, Graphviz and D2 drawn; J1
V2 Walk-through by voice, the on-device commands, "show me later", the glance card, create and edit by voice; J3
V3 Derived diagrams with stamps, refresh and out-of-date marking; J2
V4 Tier 2, with the four creative types and the imports; presentations on the shared renderers
V5 Tier 3 by embedding; J4

V0 and V1 depend on eve-interactive-artifacts UI.01 (the contract and validator), UX.01 and UI.03.

Final acceptance needs every requirement shown with evidence at a named commit, independent review, tested main and a passing Dev release. A schema, a count of tasks or a demonstration does not establish delivery.

8. Acceptance#

  1. Each tier 1 type is drawn from a stored model on the Workspace reader, the reader chat, the web and admin dock, the desktop app, the Android Workspace tab, Docs Center and a slide, in light and dark and at 320 pixels, with captured images.
  2. The quality corpus passes the automatic checks, and an independent reviewer has assessed the captures.
  3. A fixed set of at least 30 questions shows Eve choosing a fitting type or plain text, scored by a rule set written beforehand and assessed independently, on the approved inexpensive model route.
  4. A change by conversation, by hand and by voice each alters only the named part, and can be undone.
  5. Existing documents with Mermaid draw as before. A document with PlantUML, Graphviz or D2 is drawn.
  6. Every part of each derived diagram maps to a source identifier; a diagram of a source that has since changed is marked out of date.
  7. For each model, the spoken headline and walk-through name the same parts, in the same order, with the same numbers as the picture, checked by a test that compares both against the model.
  8. The on-device commands work with no connection. An image's description is spoken.
  9. The glance card is seen on an Android device or emulator in step with the voice. What was not tried on a real phone is said.
  10. Keyboard and screen reader passes on each type's text form and parts.
  11. A malformed model, an unknown type and a failed render each fall back to text and say so.

9. Boundaries#

  • No renderer, layout engine or chart library is chosen here.
  • No unrestricted generated HTML or scripts, as the ADR decides.
  • Generated video and footage are outside this PRD. Motion built from a visual belongs to eve-interactive-artifacts.
  • The studio apps' viewers stay owned by their products.
  • Nothing here changes who may approve, publish, promote, hold keys or spend.

10. What follows approval#

An architecture document (the models' schemas, the renderer and layout choice with its measurements, the spoken-form generator, the derivation readers), then a delivery specification and the board tasks of eve-visual-language. None is written or filed yet.