What Is the Medallion Diagram Type for Data Storage in diagram‑design?

The Medallion diagram type is a parametric, multi‑tier data‑storage layout that visualizes hierarchical data lakes or warehouses, where each tier represents a distinct quality or access level such as raw, anonymized, staging, aggregated, and archive.

The diagram-design repository by Cathryn Lavery provides a specialized diagram type for documenting modern data architectures. The Medallion diagram stands out for its deterministic, code-driven approach to generating reproducible SVG visualizations of data storage hierarchies. Unlike general-purpose drawing tools, this implementation uses a YAML inputs schema to guarantee consistent output across environments and teams.

Key Characteristics of the Medallion Diagram Type

The Medallion diagram type is optimized for scenarios where understanding data lineage, ownership, and quality tiers matters more than generic box-and-line diagrams.

Purpose and Use Cases

According to the reference specification in skills/diagram-design/references/type-medallion.md, this diagram type excels at:

• Documenting multi‑tier storage systems where data progresses through quality stages
• Showing tier content, ownership, and promotion flow in a single view
• Communicating tooling and format decisions per storage layer
• Tracing data lineage between buckets with explicit transformation labels

The name derives from the visual pattern: tiers arranged horizontally like stacked medallions, with arcs showing promotion paths flowing over the top.

Parametric Design Architecture

Every Medallion diagram is generated from a YAML inputs schema that drives coordinates via deterministic layout formulas. This ensures:

• Reproducible SVG output — identical inputs produce identical pixels
• Version-controlled diagrams — diffs show meaningful structural changes
• Programmatic generation — CI/CD pipelines can render diagrams from infrastructure-as-code

The layout engine calculates all positions mathematically; no manual nudging or pixel-pushing is required or supported.

Tier Styling and Configuration

Four Built-In Tier Styles

The Medallion diagram type defines four visual styles applied per tier:

Style	Visual Treatment	Typical Use
outer	Distinct border treatment	Entry points (raw ingestion)
default	Standard fill and stroke	Processing tiers
focal	Emphasized header band	Primary consumer-facing tier
cold	Dashed stroke pattern	Archive or compliance storage

Exactly one tier must be marked focal: true. The focal tier receives visual emphasis through its header band and serves as the diagram's conceptual center of gravity.

Per-Tier Data Fields

Each tier defines structured metadata in its fields property:

• tool — ingestion or processing technology
• format — storage format and partitioning strategy
• writer — role or team responsible for writes
• example — array of representative data contents

Color overrides are permitted on default and outer tiers, but prohibited on focal and cold tiers to preserve visual semantics.

Promotion Arcs and Data Flow

Cubic Bézier Layout

Data movement between tiers renders as cubic Bézier arcs positioned over the top of the tier strip. The implementation in type-medallion.md specifies:

• Anchor points at top-center of source and target tier rectangles
• Control points fixed at y = 0 (above the diagram)
• Guaranteed visibility: arcs and labels never overlap tier content

This design choice prioritizes readability over arbitrary aesthetic curves.

SVG Path Implementation

The resulting SVG path uses absolute coordinates with calculated control points:

<path d="M 478,80 C 478,0 666,0 666,80"
      fill="none" stroke="{accent}" stroke-width="1.6"
      marker-end="url(#arrow-accent)"/>

The {accent} token resolves to a theme-aware color value. Dark mode automatically swaps token pairs like paper ↔ ink without YAML changes.

Promotion Style Variants

Three arc styles convey different semantics:

• normal — standard data promotion
• focal — flow into or out of the focal tier (emphasized)
• lifecycle — compliance-driven archival or deletion

Optional Path Row for Write Methods

The Medallion diagram supports an optional paths array describing how data moves between tiers. Up to two path cards appear beneath the tier strip:

paths:
  - { tag: "SQL PATH",      title: "Trino INSERT INTO … SELECT",
      sub: "filter·reshape·join·aggregate — set‑based transforms" }
  - { tag: "NOTEBOOK PATH", title: "DuckDB + Python/R in JupyterHub",
      sub: "stats·ML·interactive analysis — row‑iterative work" }

This bridges the gap between what (tiers) and how (implementation patterns).

Complete YAML Example: Five-Tier Architecture

This production-ready definition from the reference demonstrates all features working together:

title:    "Five‑Tier Medallion Architecture"
subtitle: "Quarterly survey through Raw → Anonymized → Staging → Aggregated → Archive"

tiers:
  - { name: "Raw",        bucket: "raw-bucket",        style: "outer",
      fields: { tool: "NiFi · raw write", format: "CSV · Parquet · JSON", writer: "Data Engineer",
                example: ["Q1 dump · w/ PII", "verbatim CAPI export"] } }
  - { name: "Anonymized", bucket: "anon-bucket",       style: "default",
      fields: { tool: "Trino INSERT", format: "Iceberg · partitioned", writer: "Data Engineer",
                example: ["no name · address", "stable household ID"] } }
  - { name: "Staging",    bucket: "staging-bucket",    style: "default",  color: "#c9a23a",
      fields: { tool: "Trino · JupyterHub", format: "Iceberg·cleaned", writer: "Data Scientist",
                example: ["weighted records", "harmonised codings"] } }
  - { name: "Aggregated", bucket: "aggregated-bucket", style: "focal",  focal: true,
      fields: { tool: "Trino INSERT · SAS JDBC", format: "Iceberg·indicators", writer: "Data Scientist",
                example: ["unemployment rate", "labour participation"] } }
  - { name: "Archive",    bucket: "archive-bucket",    style: "cold",
      fields: { tool: "MinIO lifecycle", format: "cold tier·immutable", writer: "Data Administrator",
                example: ["historical Q1–Q4 sets", "5+ years retained"] } }

promotions:
  - { from: 0, to: 1, label: "PII REMOVE",    style: "normal"    }
  - { from: 1, to: 2, label: "CLEAN+WEIGHT",  style: "normal"    }
  - { from: 2, to: 3, label: "AGGREGATE",     style: "focal"     }
  - { from: 3, to: 4, label: "LIFECYCLE",     style: "lifecycle" }

paths:
  - { tag: "SQL PATH",      title: "Trino INSERT INTO … SELECT",
      sub: "filter·reshape·join·aggregate — set‑based transforms" }
  - { tag: "NOTEBOOK PATH", title: "DuckDB + Python/R in JupyterHub",
      sub: "stats·ML·interactive analysis — row‑iterative work" }

dark: false

Tier indices in promotions are zero-based and reference position in the tiers array.

Source Files and Further Reference

File	Location	Purpose
type-medallion.md	skills/diagram-design/references/	Complete specification with inputs schema, layout formulas, and styling rules
SKILL.md	skills/diagram-design/	Master index of all diagram types including Medallion
README.md	Repository root	Visual preview and quick-start links

The reference file includes a reproducibility checklist for verifying SVG output across environments — essential for teams treating diagrams as build artifacts.

Summary

• The Medallion diagram type visualizes multi‑tier data storage with explicit quality stages and promotion flows
• Parametric YAML-driven design guarantees reproducible, version-controlled SVG output
• Four tier styles (outer, default, focal, cold) encode semantic roles with strict color override rules
• Over-the-top Bézier arcs show data lineage without obscuring tier content
• Optional path row documents implementation patterns for cross-tier data movement
• Automatic dark mode swaps color tokens without configuration changes

Frequently Asked Questions

What makes the Medallion diagram type different from generic flowcharts?

The Medallion diagram type is domain-specific for data storage architectures. Unlike general flowchart tools, it enforces a horizontal tier layout with standardized metadata fields (tool, format, writer, examples) and mathematically calculated promotion arcs. The parametric design eliminates manual positioning while ensuring all diagrams in an organization share consistent visual grammar.

Can I have more than one focal tier in a Medallion diagram?

No. The schema requires exactly one focal: true marker across all tiers. Attempting to define zero or multiple focal tiers violates the specification and will fail validation. The focal tier receives distinctive visual treatment to guide viewer attention to the primary consumption point in your data architecture.

How does dark mode work in Medallion diagrams?

Dark mode operates through token substitution rather than duplicating color definitions. The renderer swaps semantic tokens like paper and ink based on the dark: boolean flag in YAML. This approach keeps specifications minimal while ensuring accessible contrast ratios in both themes without manual color picking.

Where are promotion arc coordinates calculated?

The layout formulas in type-medallion.md define arc geometry: control points anchor at y = 0 above the diagram, with source and target points at tier top-center. These calculations happen deterministically from tier widths and positions — you provide from and to indices only, never raw coordinates.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}