How it works
How Vantra holds together.
Five chapters on the shape of the system: what the core does, what the tools do with it, and why governance is treated as a craft rather than a process. Written to be read, not searched — but if you came for one answer, the contents below will take you to it.
Chapter 01
What Vantra is
Vantra is not a platform and not a suite. It is a set of instruments that happen to agree with each other, because they all read your system the same way.
The idea
Most design system tooling arrives with its own idea of what your system is. One tool knows your colours but not your components, another knows your components but not who consumes them, and a third asks you to describe both again in a config file. The disagreements between them are where the work quietly goes.
Vantra starts from the opposite end. One library reads the repository — tokens, components, the edges between them — and everything else is a surface over that reading. A contrast checker, a design reviewer, a deprecation tracker: different questions, one shared answer about what exists.
The second decision is locality. Everything runs on your machine. The tools read files and rendered pages, which is exactly the kind of access that should never be paired with a network client. No account, no upload, no telemetry — which is also why they work on staging behind a VPN, and why the licences are open.
Where this came from, and the principles it is held to, are on the about page.
- You seeToolsExtensions, CLIs, a dashboard. The surfaces you open.
- They shareThe coreOne parser. One token schema. One component graph.
- It readsYour repositoryYour files, on your machine, unmodified until you say so.
The whole architecture on one page. Nothing above the top line, nothing below the bottom one.
A tool that cannot name what already exists in your system is guessing politely.
Chapter 02
The core
@vantra-design/core is the parser. It answers two questions — what does this system declare, and who depends on it — and every other tool is built on those answers.
What it does
The core reads two things out of a repository. First, the token schema: the colours, spacing steps and type sizes a system actually declares, taken from CSS custom properties rather than from a separate manifest that drifts from the stylesheet. Second, the component graph: which component imports which, and therefore which consumers exist for any given file.
That second answer is the reason the library exists. It is easy to report that a button has four variants and hard to say who breaks if three of them are removed. The graph turns that from a memory exercise into a lookup, and it is what the Design Reviewer, the Deprecation Orchestrator and the Governance Suite all share — they ask different questions of the same graph rather than each building their own.
You install it as a dev dependency. It has no runtime and ships nothing to your users; it is a build-time and CLI-time library that reads your source and returns structured data. Nothing is written back unless a tool you invoked asks to write it.
# the shared parser every Vantra tool reads through
npm i -D @vantra-design/coreA dev dependency. There is no runtime bundle and nothing to configure before the first run.
import { parseTokenSchema, buildComponentGraph } from '@vantra-design/core'
const tokens = await parseTokenSchema('assets/css/main.css')
const graph = await buildComponentGraph('components')
// who breaks if this is removed today
graph.consumersOf('components/base/AppLink.vue')parseTokenSchema reads the declarations; buildComponentGraph reads the edges. Everything else in Vantra is a question asked of one of these two.
This page is the invitation, not the specification. The full API, the caveats and the tests live in the core repository(opens in a new tab).
Reads once
@vantra-design/core
Token schema, component graph, dependency edges, ownership.
Takes the token schema, to name the nearest passing colour you already own.
Takes the component graph, to tell drift from a deliberate variant.
Deprecation Lifecycle Orchestrator
Takes the same graph, to answer who breaks if this is removed today.
Governance Suite(opens in a new tab)
Takes the parsed inventory, to score health without a second opinion of your code.
Fig. 02Four consumers, one reading of the repository. The parser runs once; nothing downstream is allowed a second opinion about what your system contains.
Parse once, then argue about the results — not about the parsing.
Chapter 03
The tools
Two families, and an easy way to tell them apart: the utilities answer a question in seconds, the products watch a system over time.
Which one you need
The eleven utilities are the small end. Contrast ratios, modular type scales, easing curves, clamp() values, grid and flex layouts — the unglamorous arithmetic behind a design system, done properly and done in the browser. They need no install and no repository: you open one, get a value, copy it, and close the tab. Nothing is uploaded because there is nowhere for it to go.
The products are the long end. The Accessibility Auto-Fixer reads a rendered page and proposes fixes as diffs you approve. The AI Design Reviewer compares a component against the system it claims to belong to. The Deprecation Lifecycle Orchestrator follows a removal from announcement to the last consumer. Most of these read your repository through the core, which is why their findings cite your tokens instead of a generic rulebook.
The Design System Maturity Check is the exception, and deliberately so. It reads nothing: it asks twenty-four questions, scores four dimensions, and returns three next steps written for the level you actually reached. Some things about a system are not in the source — who decides, how fast, and whether anyone wrote it down — and a tool that pretends to measure them from a repository would be guessing.
The rule of thumb: if the question is arithmetic, use a utility. If the question is whether your system still means what it says, use a product.
The full set is at /tools, and each product has its own page under work.
Motion
Fig. 03The utility set, grouped by the decision it serves rather than by the technology behind it. Each one runs entirely in the browser.
Chapter 04
Governance as posture
Deprecation, versioning and ownership are not paperwork. They are the parts of the craft that only show up years later, which is exactly why they get skipped.
The posture
A design system decays one reasonable exception at a time. Nobody notices the fourteenth hard-coded hex value, because each one was justified on the day it was written. The same is true of the deprecation notice nobody can retire, and the component with no owner that four teams depend on. None of these are failures of discipline; they are failures of visibility.
Governance, in Vantra, means making those things visible enough to act on. A deprecation has a date, a replacement and a list of remaining consumers read from the graph — not a comment that says do not use this. A breaking change is described by what it breaks. Ownership is a fact in the repository rather than folklore in a channel.
The Governance Suite is where this lives: a health CLI, a breaking-change analyser and a deprecation orchestrator, sharing the core inventory so that all three agree on what your system contains. It reports, it does not enforce. A tool that silently rewrites your system to satisfy its own policy has confused governance with control.
In practice
Removing something is also a design decision.
The orchestrator treats a removal the way a release is treated: announced, dated, tracked, and closed only when the last consumer is gone. The list of consumers comes from the component graph, so it is a fact rather than an estimate — and it shrinks in public, where everyone can see the deprecation actually ending.
AI editorial placeholder — /editorial/20-governance-desk.avif
A deprecation timeline beside its remaining consumers. The notice can only be retired when the list is empty.
Governance you cannot inspect is just an opinion with a process around it.
Chapter 05
Taking part
Everything is on GitHub, including the parts that are not finished. That is deliberate, and it is where help is most useful.
How to help
Several of these tools are in development and one or two are still planned. The repositories are public at that stage on purpose: a governance tool that appears fully formed, with no visible history of its own decisions, is asking for a kind of trust it has not earned.
The most useful contribution is rarely a pull request. It is a repository that breaks the parser in a way we had not considered — a token file with a naming convention we did not anticipate, a component graph with a cycle in it, a page whose computed contrast disagrees with every checker. Those cases become fixtures, and fixtures are what keep the core honest.
After that: issues written from real use, documentation that corrects what this page simplifies, and reviews of the accessibility work itself. If you would rather just watch, the repositories are readable without an account.
Contribution guidelines sit next to the source at github.com/vantradesign(opens in a new tab), or write to hello@vantra.design(opens in a new tab).
Published unfinished, because a tool about accountability should be accountable first.