Design Principles & Values
What @shavin/ui solves
Modern product engineering suffers from design token fragmentation, accessibility regressions, and inconsistent UI component state across codebases.
Design System Drift
Hardcoded hex values and arbitrary pixel offsets erode brand alignment over time. @shavin/ui enforces strict two-tier tokens that prevent raw values from entering UI code.
Accessibility Overhead
Hand-rolled menus, popovers, and dialogs often break screen reader focus and keyboard navigation. We back every complex primitive with Radix primitives out of the box.
Theme Recoloring Friction
Changing brand accent colors or neutral tones usually requires touching hundreds of CSS classes. Our semantic custom properties re-skin the whole app instantly at runtime.
Core Principles
1. Semantic Token Discipline
Foundation scale (--n-0 to --n-1000) is isolated in global.css. Every component and app layout consumes strictly role-based semantic tokens (--bg-canvas, --fg, --accent).
2. Zero Layout Leakage
Components never export outer margins. Structural layout primitives (Box, Flex, Grid, Container, Section) handle container boundaries and element gaps.
3. Accessible Interaction Earned
We reach for Radix primitives whenever complex keyboard nav, type-ahead selection, focus trapping, or viewport collision detection is required, while using lean native HTML elements where standard semantics suffice.
4. Deterministic CVA Variants
Every component uses class-variance-authority to define explicit sizes, intents, and shape variants. We never concatenate string classes manually; all class merging routes through cn().