LifeDS

Wellzesta

Design System Migration

Migrating the UI to Tailwind v4 with a fresh component library built the shadcn-style way — Tailwind + CVA + tailwind-merge + clsx. One source of truth for tokens, shared between Figma and code.

Tailwind v4CVAshadcn/ui@tabler/icons-reactFigma: Wellzesta Components

Token architecture

Three layers mirror how Figma variables are organized. Designers and code share the same names.

Primitives

--teal-700: #0f766e

Raw scale values defined in @theme

Semantic

--color-primary: var(--teal-700)

Named roles from Figma general/* variables

Component

bg-primary ring-ring

CVA reads semantic tokens via Tailwind utilities

White-label theming is preserved via @theme inline — brand classes override CSS variables at runtime, no per-brand component code needed.

Conventions — enforced in review

These rules apply to every file under src/ui/**. Add a lint rule or CI grep to block violations.

Do

  • Style only with Tailwind utilities composed via CVA
  • Merge classes with cn() so consumers can override
  • Reference only design tokens — never raw hex (bg-primary, not bg-[#0f766e])
  • One folder per component: Component.tsx · Component.variants.ts · test · barrel export
  • White-label theming via @theme inline + :root brand overrides
  • Icons from @tabler/icons-react only

Don't

  • No styled-components — rewrite as Tailwind/CVA components
  • No inline style={{}} — convert to utilities (dynamic values → CSS variables)
  • No component-scoped .css files
  • No hardcoded hex colors in UI components
  • No arbitrary Tailwind colors: bg-[#…] is blocked in src/ui/**

Migration order

Incremental strangler pattern — legacy code stays until each screen is fully migrated.

✓

Foundation

Tailwind v4 spike → tokens.css + @theme → cn() helper → CVA install

done
✓

Button

Reference component — variants, states, icon positioning

done
3

Primitives

Input · Select · Badge · Card · Text/Heading

4

Per screen

Swap legacy imports → new src/ui; delete legacy after last consumer migrates

5

Cleanup

Remove wellzesta-ui, .is-* block, styled-components, old --color-bg-* tokens

Views

Explore the components and prototypes built with the new design system.

Storybook
Interactive documentation for every installed component — props, variants and usage patterns.
Button · Card · Input
ShadCN Preview
Component sandbox with the default shadcn preset — buttons, cards, charts and forms.
Sandbox
Tokens
All design tokens in one place — primitives, semantic variables, Tailwind @theme and component tokens.
Primitive · Semantic · Component