How to install dependencies and structure your app.
✓
Recommended for new projects: Use the VZN CLI to build your sovereign preset visually and generate the right setup command for your framework.
Choose your framework
Select the setup that matches your starting point to view specific docs.
Use the CLI
Use the CLI to scaffold a new project directly from the terminal:
pnpm dlx vzn@latest init [framework]
Supported templates: next, vite, astro, laravel.
Introduction
Sovereign agentic infrastructure engineered for production under low-latency constraints.
VZN Labs provides a design system that is deterministic, calm, and provable. We prioritize hairlines over heavy shadows, and single-hue states over rainbow indicators.
Core Principles
- Calm Authority: Interfaces built on mathematical precision.
- One accent: `Signal Blue` is the brand colour.
- BeatEvidence: Proof over theatre. Measured control holdouts.
Theming & Tokens
Map your brand to VZN's CSS variable architecture.
| Variable | Role |
| --signal | Primary CTA, Approve Gates, active focus rings. |
| --canvas | Application root background. |
| --card | Elevated container background. |
| --hair | 1px structural boundary line. |
CLI Reference
The vzn CLI copies component source into your repo. It is not a dependency — there is no runtime package to upgrade, and nothing phones home. Every command writes files you own and can edit.
| Command | What it does |
| vzn init [framework] | Writes the token layer, Tailwind preset and vzn.json. Framework is one of next, vite, astro, html. |
| vzn add <component> | Copies one component and its dependencies into components/vzn/. |
| vzn add --all | Copies the full registry. Useful once, for a new product surface. |
| vzn diff | Shows where your local copy has drifted from the registry, so an upgrade is a decision rather than an overwrite. |
| vzn logos sync | Regenerates the connector logo registry (local override → Simple Icons → Iconify → Brandfetch → last-known snapshot → monogram). |
| vzn lint | Fails on token drift: a raw hex where a token exists, a second chromatic accent, a Signal Blue control that is not consequential. |
Why copy, not install. A design system that ships as a versioned package makes every visual decision someone else’s to revoke. Copying source means a product team can diverge deliberately, and vzn diff keeps that divergence visible instead of silent.
Signal Blue
Signal Blue #2F5CFF is the chromatic accent of the system, in both modes. It is the brand colour, so use it where it helps the eye find the next step.
Good uses
- The APPROVE button on a decision desk
- The primary call to action on a marketing section
- Focus rings — a keyboard user is about to act
- Inline links in running prose
- The Signal Orb, when an agent is working on your behalf
Keep neutral
- “Live”, “healthy”, “connected” — use semantic success green
- Selected rows, active tabs, hover states — use the surface ladder
- Body text and large surfaces
- Charts: one blue ramp, or neutral steps for comparison
Text on a Signal fill is --on-signal, never raw white: in dark mode Signal is #5C82FF and white on it is 3.4:1. Raw hex values stay in the token layer. The historical teal #0D9488 + indigo #4F46E5 pair from the pre-VZN “Calm Authority” palette is retired.
BeatEvidence Protocol
A pack does not reach GA because it feels good. It reaches GA because it beat a recorded control on live traffic, over a real window, with enough jobs to mean something. BeatEvidence is the record that says so, and the UI never claims a result the record does not support.
Provenance is required
Every record carries a source. Only one of them can promote.
pilot_live — promotes
demo — never promotes
synthetic — never promotes
Why a promotion is blocked
The Hub returns a reason, and the UI shows that reason verbatim rather than a generic “not eligible”. An operator should never have to guess which gate they are behind.
| Reason | What the operator is told |
| MISSING_SOURCE | No provenance recorded. The run cannot be counted. |
| INVALID_SOURCE | Provenance is not one of the three known sources. |
| NON_LIVE_SOURCE | Demo or synthetic traffic. Real customers were never involved. |
| MISSING_BEAT_RECORD | No control was recorded to beat. |
| MISS_PRIMARY_STAY_BETA | The primary metric was missed. The pack stays in beta. |
| UNDER_N | Fewer jobs than the control card’s minimum (default 50). |
| WINDOW_NOT_ELAPSED | The pilot window (default 14d) has not finished. |
| PACK_ID_MISMATCH | The evidence belongs to a different pack. |
| SIGN_OFF_REQUIRED | A named human still has to sign off. |
| SHIP_CHAT_ANYWAY | Shipping was forced past the gate. Recorded, and shown as such. |
The design consequence. The BeatEvidence Card never renders a bare uplift number. It renders result, control, n, window and source together, because an uplift without its denominator is a marketing claim, not evidence. If any of the five is missing, the card renders the gap rather than hiding it.
Surface Ladder
Depth in VZN comes from colour steps and hairlines, not from stacked drop shadows. There are two shadow tiers in the whole system — a raised card and a floating modal — and everything else separates by sitting one rung up or down the ladder.
Dark — the Studio
Light
Rules
- A card sits on canvas. A card inside a card goes up one rung, never up one shadow.
- Hairline
--hair is the default separator; --hair-strong is for an edge that has to survive a busy background.
- Shadow tier one (
--shadow-1) is a raised card. Tier two (--shadow-float) is a modal, menu or command palette. There is no tier three.
- In dark mode the ladder does the work shadows cannot — a shadow on a near-black canvas is invisible, so a dark surface separates by getting lighter, never by glowing.
- Never darken a light surface to indicate selection. Selection is a hairline plus a surface step, so the same pattern reads identically in both modes.