UI Design Systems and Tokens: Consistency That Scales Across Products
A design system is not a component library slideshow. Tokens, semantics, and governance are what let multiple products look related without copying paste CSS.
Ali Mortazavi
Founder, Paradise Code
Primitives Versus Semantics
Primitive tokens name raw values — blue-500, spacing-4, radius-md. Semantic tokens name intent — color-text-primary, surface-elevated, focus-ring. Components should consume semantics so theming and dark mode do not require rewiring every file.
Map semantics to primitives in one layer — CSS variables, Tailwind theme extension, or Style Dictionary output. When brand color shifts, you update the map, not fifty components.
Document token naming rules so designers and engineers use the same vocabulary in Figma and code.
Components With Opinions, Not Options
Each component should solve a product job — primary action, destructive confirmation, dense table cell — with a small variant set. Twenty props for corner cases means the design system lost.
Compose complex UI from primitives: Stack, Text, Button, Card. Avoid mega-components that embed business logic. Keep domain-specific widgets in product code, built on system primitives.
Accessibility is part of the API: focus order, aria labels, keyboard traps in modals. A button without loading and disabled states is incomplete.
Tailwind, CSS Variables, and HeroUI
Utility-first CSS speeds delivery when tokens are centralized in tailwind.config or @theme in v4. Arbitrary values in every file erode the system.
CSS variables enable runtime theme switch and per-tenant branding in multi-tenant admin panels. Expose semantic variables to JavaScript only when necessary.
Libraries such as HeroUI or shadcn accelerate baseline components. Customize through tokens and wrappers, not forked source copies, so upgrades stay feasible.
Figma and Code Parity
Figma variables should mirror code token names. Designers apply semantics; engineers implement the same names. Mismatched naming is the top reason systems drift.
Ship a changelog when tokens change. Breaking visual changes need migration notes and codemods where possible.
Screenshot or visual regression tests on key components catch unintended drift when dependencies update.
Governance for Product Studios
Assign a system owner — not necessarily full-time — who reviews new patterns before they multiply. Ad hoc one-off grays become debt.
Contribution model: propose RFC for new tokens or components, implement in staging package, document usage examples.
Not every client project needs a unique system. A studio baseline with white-label tokens covers most cases; bespoke illustration and motion can differentiate brand without reinventing spacing scale.
Measuring System Success
Track time to ship standard screens, bug count on inconsistent UI, and duplicate component count in repos. Declining duplicates and faster forms are good signals.
Developer experience matters: Storybook or Ladle, typed props, and copy-paste examples reduce Slack questions.
Design systems and tokens pay off when semantics are stable, components are focused, and governance is light but real. Paradise Code treats the system as infrastructure, not a side project.
Insights
Need these ideas implemented in your product?
Paradise Code supports you from consult to full delivery.