Working with AI

The Zero-Hallucination AI Architecture

@shavin/ui is architected from the ground up to eliminate "AI UI Slop" — the phenomenon where AI models produce syntactically valid components that lack spatial rhythm, ignore contrast hierarchy, invent fictional CSS variables, or violate concentric geometry.

1. The Brain

SHAVIN.md

Persistent project-level design memory and brand personality standard at the root of your repo.

2. The Protocol

@shavin/mcp

29 modular Model Context Protocol tools for live schema queries, AST autofixing, and layout synthesis.

3. Cognitive Skills

.agents/skills/

9 specialized agent skill files enforcing mathematical layout laws and human visual perception.

4. Agent Rules

AGENTS.md

Root-level AI behavioral constitution auto-installed alongside skills for orchestrator-level constraints.

SHAVIN.md — The Modern Design Manifest Standard

Similar to how AGENTS.md provides runtime behavioral constraints for AI orchestrators, SHAVIN.md establishes a standardized, persistent design manifest standard for AI-assisted frontend development.

When an AI assistant (Cursor, Claude, Copilot, Antigravity) opens your repository, SHAVIN.md provides instant context on brand personality, spacing rhythm, active color palette, concentric radius laws, and typography pairs — eliminating repetitive prompting and ensuring every generated component looks crafted by a senior designer.

Standard SHAVIN.md Structure:

# Shavin Project Design Manifest

## 1. Product & Domain Context
- **Product Name**: Apex Analytics
- **Domain**: Developer Tooling & Cloud Metrics
- **Target Audience**: Engineers who require high data density and scanability
- **Brand Personality**: Crisp, high-contrast, technical, calm, zero-fluff

## 2. Design System Configuration
- **Engine**: @shavin/ui (Strict 2-tier semantic token architecture)
- **Primary Accent**: grass
- **Neutral Scale**: zinc
- **Theme Mode**: dark-first
- **Scaling / Density**: 95% (compact)
- **Base Radius**: medium
- **Panel Background**: solid

## 3. Structural & Layout Constraints
- **Shell Architecture**: Fixed left icon rail + collapsible sidebar + sticky header + fluid canvas
- **Container Radius**: Must use rounded-[var(--radius-panel)] (NEVER arbitrary static radius classes)
- **Control Radius**: Must use rounded-[var(--radius-lg)] (buttons, inputs, chips)
- **Concentric Nesting**: Set radius="concentric" on inner elements — the design system auto-resolves the correct inner radius from the container's padding

## 4. Typography & Contrast Hierarchy
- **Title / Header**: text-fg font-semibold tracking-tight
- **Paired Description**: text-fg-subtle text-sm (⚠️ Never use text-fg-muted for primary descriptions)
- **Meta / Timestamps**: text-fg-muted text-xs font-mono
- **Code / Tokens**: font-mono text-xs text-accent-contrast

## 5. Interaction & Component Invariants
- **Destructive Actions**: Always require AlertDialog with focus defaulting to Cancel
- **Floating Overlays**: Popovers, Dropdowns, Menus MUST have data-panel attribute
- **Empty States**: Icon + Title (text-fg) + Message (text-fg-subtle) + Primary CTA Button

Auto-Scaffolded: Running npx @shavin/cli init automatically creates SHAVIN.md at your project root, pre-filled with your application settings.

Deterministic Prompt Caching (< 300 Tokens)

Large language models (Claude 3.5 Sonnet, GPT-4o, Gemini 1.5 Pro) leverage prompt caching for fast response times and 90% reduced token costs. @shavin/cli includes a dedicated context extraction engine:

npx @shavin/cli context

This analyzes your project's SHAVIN.md, tailwind.config.ts, and active theme presets, outputting a compact, budget-conscious prompt block with a deterministic SHA-256 hash:

<!-- SHAVIN_CONTEXT_HASH: a4f8e91c32b0 -->
<shavin_design_system engine="@shavin/ui" version="0.1.0">
  <theme mode="dark-first" accent="grass" neutral="zinc" radius="medium" scaling="95%" />
  <concentric_rule inner_radius="radius='concentric'" description="auto-resolves from container padding" />
  <contrast_pair title="text-fg font-semibold" description="text-fg-subtle text-sm" />
  <tokens bg="bg-canvas bg-surface bg-surface-hover" fg="text-fg text-fg-subtle text-fg-muted" border="border-hairline border-hairline-strong" />
</shavin_design_system>

System Prompt / AI Rules (Copy-Paste Ready)

Paste these instructions into your .cursorrules, AGENTS.md, or Claude Custom Instructions to guarantee that your AI agent follows `@shavin/ui` architectural invariants:

You are building UI with the @shavin/ui design system.
Adhere strictly to these core rules:

1. TWO-TIER TOKENS ONLY:
   - Use semantic Tailwind classes: bg-canvas, bg-surface, text-fg, text-fg-subtle, border-hairline, text-accent-contrast.
   - NEVER use hardcoded hex (#...), rgb(), or raw --n-* foundation variables.

2. CONCENTRIC RADIUS LAWS:
   - Container surfaces (Cards, Dialogs, Popovers) MUST use rounded-[var(--radius-panel)].
   - Controls (Buttons, Inputs, Badges, Chips) use rounded-[var(--radius-lg)].
   - Inner nested elements should use radius="concentric" to auto-resolve from the container's padding.
   - NEVER use static literal radius utility classes.

3. CONTRAST HIERARCHY:
   - Page / Section Titles: text-fg font-semibold
   - Paired Descriptions: text-fg-subtle (never pair text-fg-muted directly with text-fg).
   - Meta / Timestamps: text-fg-muted text-xs.

4. OVERLAYS & ACCESSIBILITY:
   - All floating panels (Popover, Dropdown, Menu, Tooltip) MUST include data-panel attribute.
   - Modals use Dialog; Destructive confirmations use AlertDialog with focus on Cancel.
   - Always import from "@shavin/ui" (no deep paths).

Agent Skills — Cognitive Design Layer (.agents/skills/)

npx @shavin/cli init automatically installs .agents/skills/ into your repo — a set of cognitive skill files that AI coding assistants (Cursor, Antigravity, Claude Code) read to enforce human-considered visual hierarchy, not just syntactically valid code.

layout-choreography

Skill file in .agents/skills/layout-choreography/SKILL.md

layout-compositions

Skill file in .agents/skills/layout-compositions/SKILL.md

layout-motion

Skill file in .agents/skills/layout-motion/SKILL.md

shavin-app

Skill file in .agents/skills/shavin-app/SKILL.md

shavin-core

Skill file in .agents/skills/shavin-core/SKILL.md

shavin-ui-builder

Skill file in .agents/skills/shavin-ui-builder/SKILL.md

shavin-ui-qa-linter

Skill file in .agents/skills/shavin-ui-qa-linter/SKILL.md

shavin-webpage

Skill file in .agents/skills/shavin-webpage/SKILL.md

visual-compositor

Skill file in .agents/skills/visual-compositor/SKILL.md

You can also install or update skills at any time via the MCP install_skills tool, or manually via the CLI:

# Re-installs or upgrades all .agents/skills/ in the consuming repo
npx @shavin/mcp install_skills

Why this matters: Skills prevent "AI UI Slop" by loading structured cognitive rules — visual rhythm, spatial math, hierarchy principles — directly into your AI assistant's context window before it writes a single line of JSX.

Self-Healing Quality Gate & CI Verification

Keep your codebase 100% token-pure with automated AST diagnostics and self-healing autofixes:

1. Project Health Check

CLI

npx @shavin/cli check

Audits project setup, Tailwind preset integration, stylesheet imports, and SHAVIN.md synchronization.

2. Zero-Hallucination MCP Tools

MCP

validate_code & autofix_code

Analyzes JSX strings in real-time, detecting hardcoded colors or radius violations, and generates in-memory unified patch fixes.

3. Pre-Commit Zero-Drift Guard

CI / Git Hook

npm run precommit

Runs token linter, manifest sync check, and primitive score ledger audits before every commit.

Want to connect your IDE directly? Follow our step-by-step Model Context Protocol (MCP) Setup Guide or learn how to Install @shavin/ui.