MVG

MVG is a source-first format and reference renderer for compact UI vector assets: icons, controls, panels, ornaments, and themed surfaces.

An .mvg file is the source of truth. It keeps geometry, semantic palette and font references, variants, effects, and UI metadata in a deterministic, reviewable text format. MVG is written in Odin and is designed to be cloned, built, and used directly.

MVG is production-ready and actively ships with Vigil. It is the maintained, general-purpose UI-asset workflow behind that project and will continue to be developed in public here.

AI authorship

MVG is an AI-authored project. Its maintainer directs the work, product decisions, and releases, but did not manually write the implementation code. That provenance is stated plainly so users can evaluate the project on its actual code, tests, release practice, and production use.

Quick start

Prerequisite: the Odin compiler.

git clone https://github.com/Skytrias/mvg.git mvg
cd mvg
make smoke

make smoke builds the command-line tool, validates the included examples, renders them, packs an atlas, and checks formatting. It is the recommended end-to-end health check.

On Windows, with the Odin compiler on PATH, use the equivalent root-level batch files instead of Make:

build.bat
check.bat
test.bat
smoke.bat

Render one included asset:

target/bin/mvg render examples/one-shots --asset primary_button --out target/primary-button.png

From source to output

The Material Dark icon_text_button.mvg is a compact example of scalable metadata, vector nodes, semantic theme tokens, and a variant patch in one file:

asset icon_text_button size 176 48 {
  type three_slice_horizontal
  body 2 2 172 44
  content 16 10 144 28

  rect base 2 2 172 44 radius 22 {
    fill @primary
    shadow 0 2 5 @scrim 0.28
  }

  text label "Export assets" in 46 10 112 28 size 14 font @sans_bold {
    fill @on_primary
  }

  variant hover {
    node base { fill @primary_container }
    node label { fill @on_primary_container }
  }
}

target/bin/mvg render examples/material-dark --asset icon_text_button \
  --out target/material-dark/icon_text_button.png

The same source project can be rendered as individual PNGs or packed for a raster runtime. This committed 2× atlas is generated with the command below; the accompanying layout JSON provides the stable placements and metadata.

target/bin/mvg pack examples/material-dark --out target/material-dark/pack \
  --gutter 4 --export-padding 8

For review, add --debug-overlay. It keeps the runtime atlas unchanged and writes a portable atlas_debug_<scale>x.png companion: cyan marks each asset canvas, amber its stretch body, magenta its content area, and green any named slice regions.

target/bin/mvg pack examples/material-dark --out target/material-dark/pack \
  --gutter 4 --export-padding 8 --debug-overlay

Runtime layout contract

The PNG alone is only pixels. layout.json, written beside each atlas, turns those pixels into a runtime-ready component: it supplies the exact atlas crop, the output scale coordinates, the slicing strategy, and the logical layout rectangles. This is what lets a runtime resize a component without treating it as an arbitrary bitmap.

For example, the generated surface_card entry contains this metadata:

{
  "id": "surface_card",
  "canvas_rect": [692, 396, 296, 180],
  "type": "nine_slice",
  "body": [4, 4, 288, 172],
  "content": [20, 20, 256, 140],
  "padding": [16, 16, 16, 16],
  "slices": {
    "tl": [0, 0, 20, 20],
    "tr": [276, 0, 20, 20],
    "bl": [0, 160, 20, 20],
    "br": [276, 160, 20, 20]
  }
}

At runtime, crop canvas_rect from the atlas (or use the matching entry in scaled_canvas_rects), preserve the named corners, and stretch the edge and centre regions between them. Three-slice assets use the same contract with named caps such as l and r. body, content, and padding then describe the component and safe child-content geometry. The overlay is a visual check of those same rectangles; layout.json is the portable data a runtime uses.

What is included

• A parser, validator, formatter, inspector, and JSON debug dump for .mvg.
• A scalar reference renderer supporting paths, text, fills, strokes, clips, shadows, relief effects, and deterministic PNG output.
• Deterministic atlas packing for raster deployment workflows.
• Self-contained examples and the IBM Plex font files they use.

The source format is deliberately independent of any particular renderer or runtime. PNG and atlas output are implemented deployment targets; SVG export is planned as an interoperability target.

Examples

• examples/one-shots/ uses MVG's built-in Radix colors directly. It is a collection of focused component studies.
• examples/material-dark/ uses a small semantic palette to show how a coherent product theme can drive reusable controls.
• examples/material-light/ renders the matching Material component set with light theme values.
• examples/night-poster/ uses the same component contract to demonstrate a dramatically different neo-brutalist event theme.

Commands

mvg parse <file-or-directory> [--json-out <file>]
mvg validate <file-or-directory>
mvg fmt <file-or-directory> [--check] [--out <file>]
mvg inspect <file-or-directory>
mvg render <file-or-directory> [--asset <id>] [--variant <name>] [--out <file.png>]
mvg render-all <file-or-directory> --out <directory>
mvg pack <file-or-directory> --out <directory> [--debug-overlay]

For the complete contributor workflow and language conventions, see CONTRIBUTING.md and AGENTS.md. The included examples/ projects are the best place to start.

Showcase

The showcase/ directory holds the small, source-controlled selection of public renders used here. Ordinary generated output stays in target/; the showcase only promotes deliberate examples tied back to their .mvg source. A Discord-friendly desktop share card shows the packed Material Dark, Material Light, and Night Poster outputs.

Future direction

The MVG format and its Odin-first workflow are the stable foundation. Future work is intentionally exploratory and open to feedback, rather than a fixed roadmap:

• Profile-led renderer and packing improvements.
• A GPU-backed renderer or deployment pipeline where it is genuinely useful.
• SVG output for interoperability, without reviving a general SVG importer.
• Better preview and inspection tooling, plus richer composition features.

License and third-party notices

MVG is available under the MIT License. The renderer has documented PlutoVG and FreeType lineage, and uses Odin's vendored stb implementations for text and PNG output. See third-party notices and the preserved license texts in licenses/.