A design system built to make AI trustworthy.
Shavin exists because AI-assisted UI development kept producing beautiful slop — components that looked right but violated every token rule. The fix wasn't a better model. It was persistent context, mathematical enforcement, and a bridge between the agent and the live DOM.
The frustration
AI assistants kept generating off-spec UI. Token names were wrong, radii were arbitrary, accessibility was an afterthought.
The constraint
What if the design system itself could talk to the AI — expose its tokens, rules, and validation directly to the agent?
The protocol
Model Context Protocol made it possible. A native server that lets agents query the system, validate code, and synthesize layouts.
The system
Strict two-tier tokens, WCAG AAA primitives, concentric radius math, and SHAVIN.md — a design system written for humans & machines.
Shavin isn't just a component library — it's a contract between designers, developers, and AI agents.
Context drift is the enemy. Not model capability.
Every AI UI slop problem traces back to one root cause: the agent forgot your design system between sessions. Fix the context, fix the output.
Persistent context > bigger prompts
Instead of pasting 500 lines of design rules into every conversation, Shavin gives your agent a 300-token summary that the MCP server reads automatically. Less prompt overhead, zero context loss, and the design contract stays locked across every generation.
Every problem we solve has a built-in solution.
Four persistent pain points in AI-assisted UI development — and the Shavin mechanism that addresses each one.
The Problem
AI agents lose design context between sessions
The Solution
SHAVIN.md — a persistent brain file read automatically by the MCP server on every interaction.
The Problem
Generated code is full of hardcoded colors and guessed radii
The Solution
validate_code rejects non-token colors and literal radii before they reach production. autofix_code transforms violations automatically.
The Problem
No way to verify AI output against the design system in real time
The Solution
Dev Inspector bridge daemon exposes live DOM compliance via REST API on :7428. Agents call wait_for_live_clean to block until zero violations remain.
The Problem
Concentric radius geometry is invisible to most AI tools
The Solution
Six cognitive skills encode R_inner = max(0, R_outer − P) as a construction law, not a suggestion.
From frustration to six packages.
Not a linear roadmap — each phase solved a specific failure mode in AI-assisted UI development.
The frustration
2025Building AI-assisted UI meant fighting the same battle every session: agents forget your token names, invent color values from training data, and produce hardcoded hex soup that passes visual review but violates every design system rule. The problem wasn't the model. It was context loss.
Two-tier token architecture
2025The first commit established the core invariant: foundation tokens (--n-0 through --n-1000) define the raw palette, semantic tokens (bg-canvas, text-fg, border-hairline) are the only thing components reference. Never a raw hex outside global.css. This contract became the enforcement target for everything that followed.
73 WCAG AAA components
2025Every primitive built on Radix for accessibility, CVA for variants, and cn() for className merging. Each component landed in 5 layers: primitive, docs, studio parser, registry, verification. The quality gate enforced token purity before merge — no exceptions.
MCP server + Dev Inspector
2025Instead of pasting design rules into every conversation, we built a Model Context Protocol server with 29 tools that expose tokens, components, and validation directly to AI agents. The Dev Inspector overlay runs a bridge daemon on :7428, letting agents audit live DOM compliance without screenshots.
SHAVIN.md + 9 agent skills
2026SHAVIN.md gives AI agents persistent design memory across sessions — a 300-token brain file read on every interaction. 9 specialized skills (.agents/skills/) encode concentric radius math, anti-slop patterns, and editorial craft rules directly into the agent's cognitive layer.
Open source, MIT licensed
2026Six packages, one design contract. @shavin/ui, @shavin/mcp, @shavin/cli, @shavin/block-schema, @shavin/builder-engine, and @shavin/skills — all built to make AI-assisted UI development trustworthy by construction.
Still building, still open
Shavin is an active project under continuous development. Every commit is public, every decision is documented, and every contribution is welcome. The design system grows with the community that uses it.
Build with the design system that learns with you.
Shavin is open source, MIT licensed, and ready for production.