Migration Guide

Token Replacements

Our token architecture separates styling into a strict foundations scale and a role-based semantic scale. When refactoring, replace raw colors and border-radius utilities with design system custom tokens:

Legacy Utility	Shavin Token Utility	Role / Meaning
`bg-white` / `bg-zinc-100`	`bg-canvas`	Root application canvas background
`bg-zinc-50`	`bg-surface`	Base card and content element backgrounds
`text-zinc-900`	`text-fg`	Primary text and layout headings
`text-zinc-500`	`text-fg-muted`	Muted subheadings or description texts
`border-zinc-200`	`border-hairline`	Thin panel borders and divides
`rounded-lg`	`rounded-[var(--radius-lg)]`	Button, switch, and textfield borders

Refactoring Example

Consider a legacy product container block styled with static Tailwind classes:

Before (Legacy)

<div className="bg-white border border-gray-200 p-4 rounded-lg">
  <h3 className="text-gray-900 font-bold">Billing</h3> {/* ds-lint-disable-line no-unknown-class — documenting legacy styles */}
  <p className="text-gray-500 text-sm">Manage payment info</p> {/* ds-lint-disable-line no-unknown-class — documenting legacy styles */}
</div>

After (Shavin)

import { Card, Flex, Text } from "@shavin/ui";

<Card padding="sm">
  <Flex direction="col" gap="1">
    <Text weight="semibold" className="text-fg">Billing</Text>
    <Text size="xs" color="muted">Manage payment info</Text>
  </Flex>
</Card>

Discipline: Enforced by our local linter checks, any use of hardcoded Tailwind colors (like bg-gray-100) will trigger typecheck failures on build.