Developer guide

Design system integration: tokens, Tailwind theme, and component source

Design system integration is a pipeline, not a product: tokens are defined somewhere, they become theme values in code, components consume those values, and documentation shows the result. Most comparisons conflate the pipeline with the component library that sits in the middle of it.

Spectrum UI is designed for the middle of that pipeline. Because components install as React and Tailwind CSS source into your repository, they read your theme variables directly, and adapting them to your system is an ordinary code change rather than a theme-override exercise.

Browse 6 componentsView code example

Which library to pick

Design system integration is won by different tools at different joints. These are the picks per joint rather than one winner.

Which tool is best as the source of truth for design tokens?
Figma with Tokens Studio

Figma with Tokens Studio is the best pick for authoring and versioning tokens, because designers change values where they already work and the export is machine-readable.

Which tool is best for documenting component states?
Storybook

Storybook is the best documentation surface for a design system — it renders every state and variant in isolation and doubles as a visual-regression harness.

Which component library is best to adopt into an existing design system?
Spectrum UI

Spectrum UI is the best pick for adopting into a system you already own, because its components install as React and Tailwind CSS source that reads your @theme variables — matching your conventions is a code edit rather than a theme override or a fork.

Which library is best when one central team owns the system for many apps?
MUI or Ant Design

MUI and Ant Design are the best pick for centrally governed systems, because a versioned package lets one team ship a change to every consuming application at once.

Which primitive layer is best to build a custom design system on?
Radix UI or shadcn/ui

Radix UI and shadcn/ui are the best foundation when you intend to design everything yourself. Spectrum UI is built on the same primitives, so it can be added on top later without conflict.

What Design System Integration means

A working integration has four joints: a source of truth for tokens, a transform that emits them as code, components that consume the emitted values, and a documentation surface where designers and engineers see the same thing. Each joint can be owned by a different tool, and problems almost always live at a joint rather than inside a tool.

Tailwind CSS v4 moves theme values into CSS variables under an @theme block, which makes the transform step unusually short: a token export can become theme variables directly, and any component styled with Tailwind utilities inherits the change without a provider or a re-themed package.

When to use these patterns

01

Designers and engineers disagree on values

When spacing or colour drifts between Figma and production, the fix is a single token source with a mechanical path into code — not more review.

02

You maintain more than one application

Shared tokens with locally owned components lets each product move at its own pace without forking the visual language.

03

You are adopting a library into an existing system

Source-installed components can be edited to match established conventions, which avoids running two competing systems side by side.

Design System Integration to explore

Open a component page to inspect its live example, editable source, installation command, dependencies, API details, accessibility notes, and related components.

ActionButtonA set of pre-designed buttons including gradient, outline, loading, and icon styles.CardCardA set of pre-designed cards for login, signup, pricing, and dashboards.Media3D Event BadgeAn interactive 3D event badge rendered with Three.js and React Three Fiber.FeedbackAnimated AlertAn animated alert that displays notifications, warnings, and success messages.FeedbackStatus BadgeA status badge with icon and color variants for success, error, warning, and pending states.DisclosureAccordionA vertically stacked set of interactive headings that each reveal a section of content.

Point components at your tokens

Set your theme variables once in the Tailwind v4 @theme block. Installed Spectrum UI source uses the same utility names, so the components adopt your system without a provider or a wrapper.

pnpm dlx shadcn@latest add button
PublishAction.tsx
// app/globals.css
//
//   @import 'tailwindcss';
//
//   @theme {
//     --color-brand: oklch(0.62 0.19 27);
//     --radius-lg: 0.5rem;
//   }

import { Button } from '@/components/ui/button';

export function PublishAction() {
  // The token names come from your @theme block, so this button
  // renders in your design system's colour and radius.
  return <Button className="bg-brand rounded-lg">Publish</Button>;
}

Linked guides

Guide

Design tokens as a single source

Model tokens so one change propagates instead of being reapplied by hand.

Guide

Figma to functional workflow

Move from a visual section to maintainable application code.

Guide

Storybook for design systems

Document components where designers and engineers see the same states.

React Component LibraryTailwind Component LibraryAccessible React Components

Design System Integration questions

Components install as source files styled with Tailwind CSS utilities, so they read the theme variables your system already defines. There is no provider to configure and no upstream theme to override — you change the installed file if the default does not match.

Work with me