A new convention for the AI-native era.
Every great tool introduced a file that became a standard. .gitignore taught version control what to skip. .editorconfig taught editors how to format. SHAVIN.md teaches AI agents how to design — your tokens, your radii, your constraints, read on every conversation.
SHAVIN.md— project rootOn every conversation, the agent reads SHAVIN.md and calibrates its output to your project's exact design DNA.
Convention files shaped how we build. This is the next one.
Each of these files solved a coordination problem by becoming a silent contract that every tool reads without being told. SHAVIN.md extends that lineage into AI-assisted development.
.gitignoreTells Git which files to exclude from version control.
Convention over configuration — the file's mere presence signals intent.
.editorconfigDefines indentation, charset, and line endings across editors and IDEs.
A single source of truth that every tool reads without being told.
.prettierrcEnforces formatting rules so no one argues about tabs vs. spaces.
The formatter reads the file. Humans stop debating. Code stays consistent.
SHAVIN.mdGives AI agents persistent design memory — your tokens, radii, constraints, and skill routing.
The MCP server reads it on every conversation. Agents stop guessing. Design stays locked.
Design memory that survives across every conversation.
AI assistants are stateless. Each new chat starts with no memory of your design system, your token names, or your radius rules. SHAVIN.md fixes this — it's a structured manifest that the MCP server reads automatically.
# @shavin/ui — Project Design Manifest & Brain File
This file provides zero-hallucination, persistent design memory
for AI agents (Cursor, Claude Code, Antigravity, Copilot, Windsurf)
and developers working on this project.
---
## 1. Project Context & Principles
- Framework: React 19 + Tailwind CSS + Radix Primitives + CVA
- Import Rule: ALWAYS import from @shavin/ui root
- Design Aesthetic: High-taste, minimal, editorial SaaS
## 2. Two-Tier Token Architecture
- Foundation Tokens (--n-*): Raw neutral ramp, never referenced
- Semantic Tokens: bg-canvas, bg-surface, text-fg, border-hairline
## 3. Concentric Radii & Spacing Geometry
- Controls (--radius-lg): buttons, inputs, badges, switches
- Panels (--radius-panel): cards, dialogs, popovers, accordions
- R_inner = max(0, R_outer − P)
## 4. Agent Skill Routing & Activation
- Marketing/Landing → shavin-webpage skill
- SaaS/Dashboards → shavin-webpage skill
- Concentric geometry → visual-compositor skill01Auto-created on init
Running npx @shavin/cli init scaffolds SHAVIN.md into your project root with framework detection, token configuration, and agent rules — all pre-filled.
02Read on every conversation
The MCP server's get_project_context tool reads SHAVIN.md on every AI interaction. Your agent always knows your accent color, radius preset, density, and design constraints.
03Enforced automatically
Token rules, concentric radius formulas, and skill routing triggers in SHAVIN.md are enforced by the MCP validate_code and shavin_steer tools — no manual policing.
Same agent, same prompt. The only variable is the brain file.
Context drift isn't a model problem — it's a memory problem. When the agent has your design system in context, the output is structurally correct. When it doesn't, it hallucinates from training data.
<Card style={{
backgroundColor: "#1a1a2e", // ds-lint-disable-line no-hex — example bad code
borderRadius: "16px",
padding: "24px",
color: "#e0e0e0", // ds-lint-disable-line no-hex — example bad code
}}>
<Button style={{
background: "#6366f1", // ds-lint-disable-line no-hex — example bad code
borderRadius: "12px",
}}>
Get started
</Button>
</Card>- Agent invents color values from training data
- Hardcoded hex codes leak into production JSX
- Radius values are guessed, not calculated
- Every conversation starts from zero context
- Design drift accumulates across sessions
import { Card, Button } from "@shavin/ui";
<Card>
<Button variant="solid">
Get started
</Button>
</Card>
// bg-surface, rounded-[var(--radius-panel)],
// text-fg — all resolved from SHAVIN.md tokens- Agent reads your exact semantic token assignments
- validate_code rejects any non-token color before merge
- R_inner = max(0, R_outer − P) enforced by construction
- Persistent brain file survives across all sessions
- Design contract stays locked across every generation
Structured metadata beyond the brain file.
SHAVIN.md is the human-readable manifest. The .shavin/ folder holds machine-readable config, prompt templates, and a full audit trail.
config.jsonProject-level configuration: accent color, gray scale, radius preset, scaling factor, display font.
prompt-templates/Reusable prompt fragments for common AI tasks: create-component, audit-tokens, compose-block.
context-history.jsonlAppend-only log of MCP tool invocations and design decisions — a full audit trail of AI-driven changes.
Persistent context beats bigger prompts.
The industry's answer to AI slop has been more prompting — paste your design system, describe your constraints, repeat every conversation. SHAVIN.md replaces repetition with a file.
Context cost
The entire design contract fits in 300 tokens. Less overhead than a single system prompt.
Enforcement effort
The MCP server reads and enforces the file automatically. No copy-paste, no reminders.
Memory span
The brain file persists across every conversation, every agent, every model switch.
Give your AI agent a memory that lasts.
Run npx @shavin/cli init to scaffold SHAVIN.md and the .shavin/ folder into your project.