{
  "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"
  ],
  "sourceRefs": [
    "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"
  ],
  "authors": [],
  "updated": "2026-09-09",
  "diagram": "order-decision-flow",
  "body": "## One declarative contract\n\nThese 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.\n\n```json\n{\n  \"id\": \"order-decision-flow\",\n  \"kind\": \"flowchart\",\n  \"source\": {\n    \"language\": \"mermaid\",\n    \"path\": \"diagrams/sources/order-decision-flow.mmd\"\n  }\n}\n```\n\nCreate 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.\n\n## Decision flow\n\nThe decision shape carries branching semantics, every outgoing route is labeled, and one focal class marks the successful outcome.\n\n{{diagram:order-decision-flow}}\n\n## Sequence with an alternative\n\nTime runs downward across four actors. The `alt` fragment keeps approval and rejection outcomes in one bounded branch.\n\n{{diagram:publication-sequence}}\n\n## UML class model\n\nCompartments keep attributes and operations distinct, while inheritance and composition remain explicit in the source.\n\n{{diagram:visual-model-classes}}\n\n## ER data model\n\nEntities declare keys, fields, and cardinalities directly; agents receive the Mermaid source plus the structured `data` projection.\n\n{{diagram:documentation-data-model}}\n\n## Quantitative line chart\n\nThe chart uses Mermaid's XY grammar, but inherits the same paper, ink, muted line, typography, and accent system as the other diagrams.\n\n{{diagram:document-throughput}}\n\n## State machine\n\nTransitions 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.\n\n{{diagram:editorial-state}}\n\n## Release Gantt\n\nThe schedule separates authoring, verification, and delivery while showing completed, active, and milestone treatments without adding a second visual language.\n\n{{diagram:release-plan}}\n\n## Reader journey\n\nStages 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.\n\n{{diagram:reader-journey}}\n\n## Priority quadrant\n\nReader value and implementation effort place improvements in four named regions. The legend keeps axis, point, group, and focal meanings explicit.\n\n{{diagram:documentation-priorities}}\n\n## Publishing dependencies\n\nQuiet dashed groups separate sources, build, and delivery. One coral focal node carries the editorial emphasis while every connector remains individually traceable.\n\n{{diagram:publishing-dependencies}}",
  "sections": [
    {
      "id": "one-declarative-contract",
      "level": 2,
      "title": "One declarative contract",
      "text": "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.   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.",
      "line": 1
    },
    {
      "id": "decision-flow",
      "level": 2,
      "title": "Decision flow",
      "text": "The decision shape carries branching semantics, every outgoing route is labeled, and one focal class marks the successful outcome.",
      "line": 18
    },
    {
      "id": "sequence-with-an-alternative",
      "level": 2,
      "title": "Sequence with an alternative",
      "text": "Time runs downward across four actors. The `alt` fragment keeps approval and rejection outcomes in one bounded branch.",
      "line": 24
    },
    {
      "id": "uml-class-model",
      "level": 2,
      "title": "UML class model",
      "text": "Compartments keep attributes and operations distinct, while inheritance and composition remain explicit in the source.",
      "line": 30
    },
    {
      "id": "er-data-model",
      "level": 2,
      "title": "ER data model",
      "text": "Entities declare keys, fields, and cardinalities directly; agents receive the Mermaid source plus the structured `data` projection.",
      "line": 36
    },
    {
      "id": "quantitative-line-chart",
      "level": 2,
      "title": "Quantitative line chart",
      "text": "The chart uses Mermaid's XY grammar, but inherits the same paper, ink, muted line, typography, and accent system as the other diagrams.",
      "line": 42
    },
    {
      "id": "state-machine",
      "level": 2,
      "title": "State machine",
      "text": "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.",
      "line": 48
    },
    {
      "id": "release-gantt",
      "level": 2,
      "title": "Release Gantt",
      "text": "The schedule separates authoring, verification, and delivery while showing completed, active, and milestone treatments without adding a second visual language.",
      "line": 54
    },
    {
      "id": "reader-journey",
      "level": 2,
      "title": "Reader journey",
      "text": "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.",
      "line": 60
    },
    {
      "id": "priority-quadrant",
      "level": 2,
      "title": "Priority quadrant",
      "text": "Reader value and implementation effort place improvements in four named regions. The legend keeps axis, point, group, and focal meanings explicit.",
      "line": 66
    },
    {
      "id": "publishing-dependencies",
      "level": 2,
      "title": "Publishing dependencies",
      "text": "Quiet dashed groups separate sources, build, and delivery. One coral focal node carries the editorial emphasis while every connector remains individually traceable.",
      "line": 72
    }
  ],
  "sourcePath": "content/declarative-visuals.md",
  "visuals": [
    {
      "id": "document-throughput",
      "kind": "line",
      "title": "Document throughput",
      "description": "A line chart showing an illustrative document count across four publication states.",
      "summary": "The illustrative corpus grows from six drafts to twenty-two published documents as content passes through review and validation.",
      "renderMode": "mermaid",
      "api": "api/diagrams/document-throughput.json",
      "human": "diagrams/document-throughput.html"
    },
    {
      "id": "documentation-data-model",
      "kind": "er",
      "title": "Documentation data model",
      "description": "An ER model linking documents, sections, visuals, declarative sources, and implementation references.",
      "summary": "A document contains sections, embeds visuals, and cites source references. Each visual renders from one declarative source identified by its language and path.",
      "renderMode": "mermaid",
      "api": "api/diagrams/documentation-data-model.json",
      "human": "diagrams/documentation-data-model.html"
    },
    {
      "id": "documentation-priorities",
      "kind": "quadrant",
      "title": "Documentation priorities",
      "description": "A value-versus-effort quadrant for deciding which documentation improvements to prioritize.",
      "summary": "Search metadata and Mermaid examples are quick wins; API provenance is a strategic investment, while legacy screenshots and cosmetic animation rank lower.",
      "renderMode": "mermaid",
      "api": "api/diagrams/documentation-priorities.json",
      "human": "diagrams/documentation-priorities.html"
    },
    {
      "id": "editorial-state",
      "kind": "state",
      "title": "Editorial document states",
      "description": "A state machine showing the document lifecycle from draft through review, validation, and publication.",
      "summary": "A draft enters review, returns for changes when necessary, and can only reach publication after its contracts are validated.",
      "renderMode": "mermaid",
      "api": "api/diagrams/editorial-state.json",
      "human": "diagrams/editorial-state.html"
    },
    {
      "id": "order-decision-flow",
      "kind": "flowchart",
      "title": "Order decision flow",
      "description": "An order branches on inventory and payment approval before confirmation or a recoverable retry.",
      "summary": "Orders without stock stop immediately. Available orders request payment; approved payments confirm the order, while declined payments loop through another payment method.",
      "renderMode": "mermaid",
      "api": "api/diagrams/order-decision-flow.json",
      "human": "diagrams/order-decision-flow.html"
    },
    {
      "id": "publication-sequence",
      "kind": "sequence",
      "title": "Declarative publication sequence",
      "description": "An author submits Markdown and Mermaid, then receives either published projections or an actionable validation error.",
      "summary": "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.",
      "renderMode": "mermaid",
      "api": "api/diagrams/publication-sequence.json",
      "human": "diagrams/publication-sequence.html"
    },
    {
      "id": "publishing-dependencies",
      "kind": "dependency",
      "title": "Publishing dependencies",
      "description": "A dependency graph connecting declarative sources, validation, projection building, and delivery surfaces.",
      "summary": "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.",
      "renderMode": "mermaid",
      "api": "api/diagrams/publishing-dependencies.json",
      "human": "diagrams/publishing-dependencies.html"
    },
    {
      "id": "reader-journey",
      "kind": "journey",
      "title": "Reader evidence journey",
      "description": "A user journey from finding a page to verifying its evidence and reusing its structured API projection.",
      "summary": "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.",
      "renderMode": "mermaid",
      "api": "api/diagrams/reader-journey.json",
      "human": "diagrams/reader-journey.html"
    },
    {
      "id": "release-plan",
      "kind": "gantt",
      "title": "Documentation release plan",
      "description": "A compact Gantt chart for authoring, verification, accessibility review, and publication.",
      "summary": "Authoring and source review precede contract validation and accessibility verification, ending at a publication milestone.",
      "renderMode": "mermaid",
      "api": "api/diagrams/release-plan.json",
      "human": "diagrams/release-plan.html"
    },
    {
      "id": "visual-model-classes",
      "kind": "uml-class",
      "title": "Declarative visual class model",
      "description": "A UML class model for declarative sources, diagram envelopes, and their agent-readable projections.",
      "summary": "MermaidSource implements the VisualSource contract. A DiagramEnvelope owns one visual source and produces an AgentProjection that exposes the render mode and structured data.",
      "renderMode": "mermaid",
      "api": "api/diagrams/visual-model-classes.json",
      "human": "diagrams/visual-model-classes.html"
    }
  ],
  "apiVersion": 1
}