Core Architecture & Values

What is Shavin UI?

What @shavin/ui solves

Modern frontend applications often suffer from visual drift, hardcoded color literals, inconsistent accessibility behavior, and AI coding assistants inventing non-existent component props.

@shavin/ui eliminates these issues by providing a unified system where foundation scales, role-based semantic tokens, component primitives, and AI coding tools share a single machine-readable manifest (tokens.json & components.json).

Core System Pillars

1. Two-Tier Token Architecture

Foundation tokens (--n-0 to --n-1000) define raw palettes. Semantic tokens (--bg-canvas, --accent, --hairline) map roles per theme. Hardcoded hex values are strictly forbidden and blocked by automated linters.

2. WCAG 2.1 AAA Accessibility

Radix UI handles focus traps, ESC key dismissal, arrow-key roving tabindexes, type-ahead list navigation, and ARIA state management out of the box.

3. Zero-Hallucination MCP AI Server

Integrated Model Context Protocol server supplies LLMs and coding agents with true prop schemas, valid variant keys, token rules, and block registry snippets.

4. Class-Variance-Authority (CVA)

Every multi-variant component enforces clear variant props (variant, size, tone, radius) backed by cva and merged cleanly using cn().

System Principles

Declarative over Hand-Rolled: Avoid manual ternary className strings; use CVA variant definitions for consistent component APIs.
Concentric Radius Rule: Inner elements inside containers must satisfy R_inner = max(0, R_outer - padding) to share curvature centers.
Role-Based Radius Split: --radius-lg for interactive controls (buttons, badges, inputs); --radius-panel for rectangular surfaces (cards, modals, dropdowns).
Single Export Surface: Consuming applications import directly from @shavin/ui without internal file path dependencies.

Next Step: Learn how different team roles leverage Shavin UI in our Who Uses Shavin section.