---
id: declarative-visuals
title: Declarative diagrams
description: Ten declarative Mermaid examples rendered with the Diagram Design editorial system and an always-visible contextual legend.
type: guide
status: observed
visibility: public
tags: diagrams, mermaid, uml, data-modeling, charts
related: visual-types, content-model, architecture-example
source_refs: diagrams/order-decision-flow.json, diagrams/sources/order-decision-flow.mmd, diagrams/publication-sequence.json, diagrams/sources/publication-sequence.mmd, diagrams/visual-model-classes.json, diagrams/sources/visual-model-classes.mmd, diagrams/documentation-data-model.json, diagrams/sources/documentation-data-model.mmd, diagrams/document-throughput.json, diagrams/sources/document-throughput.mmd, diagrams/editorial-state.json, diagrams/sources/editorial-state.mmd, diagrams/release-plan.json, diagrams/sources/release-plan.mmd, diagrams/reader-journey.json, diagrams/sources/reader-journey.mmd, diagrams/documentation-priorities.json, diagrams/sources/documentation-priorities.mmd, diagrams/publishing-dependencies.json, diagrams/sources/publishing-dependencies.mmd
updated: 2026-09-09
diagram: order-decision-flow
---

## One declarative contract

These examples have no authored SVG or HTML. Each JSON envelope points to a small Mermaid file; `aurelius check` validates its syntax and safety, while `aurelius build` compiles its semantic roles, discards source paint, applies Diagram Design's Minimal light system, and packages the renderer for offline use. The original source and its `declarativeAnalysis` remain available to agents. Every rendered Mermaid has a legend derived from the actual notation and a bounded viewport: drag to pan, use Ctrl/⌘ + scroll or the buttons to zoom, and open fullscreen or the dedicated full view when the model is large.

```json
{
  "id": "order-decision-flow",
  "kind": "flowchart",
  "source": {
    "language": "mermaid",
    "path": "diagrams/sources/order-decision-flow.mmd"
  }
}
```

Create the same structure with `aurelius visual init my-flow --site docs --kind flowchart`. Mermaid is the default when Aurelius has an equivalent starter for the selected kind; `--format mermaid` is available when an explicit command is preferable. For a kind without such a starter, choose `--format html` or `--format svg` explicitly so the generated source never pretends that one visual grammar is another.

## Decision flow

The decision shape carries branching semantics, every outgoing route is labeled, and one focal class marks the successful outcome.

> **Diagram: Order decision flow**
> An order branches on inventory and payment approval before confirmation or a recoverable retry.
> Semantic reading: Orders without stock stop immediately. Available orders request payment; approved payments confirm the order, while declined payments loop through another payment method.
> Semantic source: `diagrams/order-decision-flow.json`
> Structured data: `api/diagrams/order-decision-flow.json`
> Declarative source: `diagrams/sources/order-decision-flow.mmd`

## Sequence with an alternative

Time runs downward across four actors. The `alt` fragment keeps approval and rejection outcomes in one bounded branch.

> **Diagram: Declarative publication sequence**
> An author submits Markdown and Mermaid, then receives either published projections or an actionable validation error.
> Semantic reading: Aurelius validates both content and diagram contracts before publication. Valid sources produce human and agent views; invalid sources return to the author with a targeted error.
> Semantic source: `diagrams/publication-sequence.json`
> Structured data: `api/diagrams/publication-sequence.json`
> Declarative source: `diagrams/sources/publication-sequence.mmd`

## UML class model

Compartments keep attributes and operations distinct, while inheritance and composition remain explicit in the source.

> **Diagram: Declarative visual class model**
> A UML class model for declarative sources, diagram envelopes, and their agent-readable projections.
> Semantic reading: MermaidSource implements the VisualSource contract. A DiagramEnvelope owns one visual source and produces an AgentProjection that exposes the render mode and structured data.
> Semantic source: `diagrams/visual-model-classes.json`
> Structured data: `api/diagrams/visual-model-classes.json`
> Declarative source: `diagrams/sources/visual-model-classes.mmd`

## ER data model

Entities declare keys, fields, and cardinalities directly; agents receive the Mermaid source plus the structured `data` projection.

> **Diagram: Documentation data model**
> An ER model linking documents, sections, visuals, declarative sources, and implementation references.
> Semantic reading: A document contains sections, embeds visuals, and cites source references. Each visual renders from one declarative source identified by its language and path.
> Semantic source: `diagrams/documentation-data-model.json`
> Structured data: `api/diagrams/documentation-data-model.json`
> Declarative source: `diagrams/sources/documentation-data-model.mmd`

## Quantitative line chart

The chart uses Mermaid's XY grammar, but inherits the same paper, ink, muted line, typography, and accent system as the other diagrams.

> **Diagram: Document throughput**
> A line chart showing an illustrative document count across four publication states.
> Semantic reading: The illustrative corpus grows from six drafts to twenty-two published documents as content passes through review and validation.
> Semantic source: `diagrams/document-throughput.json`
> Structured data: `api/diagrams/document-throughput.json`
> Declarative source: `diagrams/sources/document-throughput.mmd`

## State machine

Transitions name the event that moves a document forward or returns it for revision. Terminal markers and the focal published state remain distinct in both the diagram and its legend.

> **Diagram: Editorial document states**
> A state machine showing the document lifecycle from draft through review, validation, and publication.
> Semantic reading: A draft enters review, returns for changes when necessary, and can only reach publication after its contracts are validated.
> Semantic source: `diagrams/editorial-state.json`
> Structured data: `api/diagrams/editorial-state.json`
> Declarative source: `diagrams/sources/editorial-state.mmd`

## Release Gantt

The schedule separates authoring, verification, and delivery while showing completed, active, and milestone treatments without adding a second visual language.

> **Diagram: Documentation release plan**
> A compact Gantt chart for authoring, verification, accessibility review, and publication.
> Semantic reading: Authoring and source review precede contract validation and accessibility verification, ending at a publication milestone.
> Semantic source: `diagrams/release-plan.json`
> Structured data: `api/diagrams/release-plan.json`
> Declarative source: `diagrams/sources/release-plan.mmd`

## Reader journey

Stages organize the experience from discovery to evidence. The sentiment curve makes the evidence-tracing friction explicit, while labels keep the finding understandable without relying on color.

> **Diagram: Reader evidence journey**
> A user journey from finding a page to verifying its evidence and reusing its structured API projection.
> Semantic reading: Readers discover and understand the document, encounter their main friction while tracing source evidence, and recover when the same facts are reused from the structured API.
> Semantic source: `diagrams/reader-journey.json`
> Structured data: `api/diagrams/reader-journey.json`
> Declarative source: `diagrams/sources/reader-journey.mmd`

## Priority quadrant

Reader value and implementation effort place improvements in four named regions. The legend keeps axis, point, group, and focal meanings explicit.

> **Diagram: Documentation priorities**
> A value-versus-effort quadrant for deciding which documentation improvements to prioritize.
> Semantic reading: Search metadata and Mermaid examples are quick wins; API provenance is a strategic investment, while legacy screenshots and cosmetic animation rank lower.
> Semantic source: `diagrams/documentation-priorities.json`
> Structured data: `api/diagrams/documentation-priorities.json`
> Declarative source: `diagrams/sources/documentation-priorities.mmd`

## Publishing dependencies

Quiet dashed groups separate sources, build, and delivery. One coral focal node carries the editorial emphasis while every connector remains individually traceable.

> **Diagram: Publishing dependencies**
> A dependency graph connecting declarative sources, validation, projection building, and delivery surfaces.
> Semantic reading: Markdown and Mermaid converge at the parser, pass one validation gate, and feed a focal projection builder that emits the human site and agent API.
> Semantic source: `diagrams/publishing-dependencies.json`
> Structured data: `api/diagrams/publishing-dependencies.json`
> Declarative source: `diagrams/sources/publishing-dependencies.mmd`