Tailwind Token

Source of truth for our shared Tailwind tokens and custom utilities.

Tailwind Token Reference

packages/design-system/globals.css defines the shared Tailwind contract for the design system.

It exposes three categories of frontend-facing utilities:

Theme utilities from @theme
Token aliases from @theme inline
Custom utilities from @utility

Use these utilities instead of default Tailwind scales whenever an equivalent design-system token exists.

These Tailwind tokens and custom utilities are not globally available to every app by default. A service can use them only after it imports @repo/design-system/globals.css them into its app-level stylesheet and makes sure Tailwind scans the service’s source files for class usage. For a new service, the setup requirement is: import the design-system stylesheet in the service’s root globals.css, then configure Tailwind source discovery so classes used in that service are included in generation. Without both pieces, tokens may exist in the design system, but utility classes like text-text-primary, bg-bg-secondary, rounded-8, or shadow-flat will not be reliably available in the service.

Typography

These are the default UI typography utilities.

Utility	Purpose
`text-title-regular`	Large section/page title
`text-title-small-regular`	Smaller title, regular weight
`text-title-small-semibold`	Smaller title, semibold
`text-title-mini-regular`	Compact title, regular
`text-title-mini-semibold`	Compact title, semibold
`text-body-regular`	Default body copy
`text-body-regular-spaced`	Body copy with more vertical spacing
`text-body-regular-medium`	Default body copy, medium weight
`text-body-small-regular`	Compact body text
`text-body-small-spaced`	Compact body text with more spacing
`text-body-small-medium`	Compact body text, medium weight
`text-body-mini-regular`	Small supporting text
`text-body-mini-medium`	Small supporting text, medium weight
`text-body-micro-medium`	Very small UI labels
`text-paragraph-regular`	Paragraph copy
`text-paragraph-small`	Small paragraph copy

Example: text-title-mini-semibold text-text-primary, text-body-small-regular text-text-secondary

Font

Utility	Purpose
`font-inter`	Shared product font stack

Background Colors

Use these for surfaces and containers.

Utility	Purpose
`bg-bg-base`	App/page base background
`bg-bg-primary`	Primary surface
`bg-bg-secondary`	Secondary surface
`bg-bg-tertiary`	Tertiary surface
`bg-bg-quaternary`	Quaternary surface
`bg-bg-blue`	Blue-tinted surface
`bg-bg-purple`	Purple-tinted surface
`bg-bg-red`	Red-tinted surface
`bg-bg-red-hover`	Red hover surface
`bg-bg-green`	Green-tinted surface
`bg-bg-green-hover`	Green hover surface
`bg-bg-orange`	Orange-tinted surface
`bg-bg-orange-hover`	Orange hover surface
`bg-bg-cyan`	Cyan-tinted surface
`bg-bg-amber`	Amber-tinted surface
`bg-bg-overlay`	Overlay background
`bg-bg-header`	Header backdrop
`bg-bg-tooltip`	Tooltip surface
`bg-bg-transparent`	Transparent background

Text Colors

Use these for readable content and semantic text.

Utility	Purpose
`text-text-white`	White text
`text-text-black`	Black text
`text-text-primary`	Primary text
`text-text-secondary`	Secondary text
`text-text-tertiary`	Tertiary text
`text-text-quaternary`	Quaternary text
`text-text-green`	Success text
`text-text-red`	Destructive text
`text-text-blue`	Informational text
`text-text-purple`	Purple accent text
`text-text-inverse`	Text on dark/filled surfaces
`text-text-orange`	Orange accent text
`text-text-yellow`	Yellow accent text
`text-text-amber`	Amber accent text
`text-text-cyan`	Cyan accent text
`text-text-tooltip`	Tooltip text

Border Colors

Use these for borders and outlines.

Utility	Purpose
`border-red-border`	Red semantic border
`border-blue-border`	Blue semantic border
`border-green-border`	Green semantic border
`border-amber-border`	Amber semantic border
`border-purple-border`	Purple semantic border
`border-orange-border`	Orange semantic border
`border-cyan-border`	Cyan semantic border
`border-fill-quaternary`	Default neutral border

Fill Colors

These are useful for filled controls, icons, and emphasized surfaces.

Utility	Purpose
`bg-fill-primary`	Primary fill
`bg-fill-primary-hover`	Primary fill hover
`bg-fill-secondary`	Secondary fill
`bg-fill-tertiary`	Tertiary fill
`bg-fill-quaternary`	Quaternary fill
`bg-fill-quinary`	Quinary fill
`bg-fill-inverse`	Inverse fill
`bg-fill-green`	Green fill
`bg-fill-green-hover`	Green fill hover
`bg-fill-red`	Red fill
`bg-fill-red-hover`	Red fill hover
`bg-fill-blue`	Blue fill
`bg-fill-orange`	Orange fill
`bg-fill-orange-lightest`	Light orange fill
`bg-fill-orange-dark`	Dark orange fill
`bg-fill-amber`	Amber fill
`bg-fill-cyan`	Cyan fill
`bg-fill-yellow`	Yellow fill

Radius

Use tokenized radius values instead of stock rounded scales where possible.

Utility	Purpose
`rounded-1`	1px radius
`rounded-2`	2px radius
`rounded-4`	4px radius
`rounded-5`	5px radius
`rounded-6`	6px radius
`rounded-8`	8px radius
`rounded-10`	10px radius
`rounded-12`	12px radius
`rounded-16`	16px radius
`rounded-18`	18px radius
`rounded-rounded`	Fully pill/round radius

Shadows

Use shared shadow tokens rather than arbitrary values.

Utility	Purpose
`shadow-flat`	Default elevated surface
`shadow-focus`	Focused surface
`shadow-low`	Low elevation
`shadow-high`	High elevation
`shadow-header-blur`	Header-specific shadow
`shadow-flat-red`	Destructive emphasis shadow

Workflow Shadows

Utility	Purpose
`shadow-workflow-menu-high`	Workflow menu elevation
`shadow-workflow-node-default`	Default workflow node
`shadow-workflow-node-default-hover`	Workflow node hover
`shadow-workflow-node-default-active`	Workflow node active
`shadow-workflow-node-success`	Success workflow node
`shadow-workflow-node-success-hover`	Success workflow node hover
`shadow-workflow-node-success-active`	Success workflow node active
`shadow-workflow-node-failed`	Failed workflow node
`shadow-workflow-node-failed-hover`	Failed workflow node hover
`shadow-workflow-node-failed-active`	Failed workflow node active

Motion

Easing

Utility	Purpose
`ease-too-cool`	Primary branded easing
`ease-hover`	Hover easing
`ease-quint`	Quintic easing
`ease-toast`	Toast animation easing

Animation

Utility	Purpose
`animate-spinner-spin-bar`	Spinner
`animate-drawer-in-from-right`	Drawer enter from right
`animate-drawer-in-from-left`	Drawer enter from left
`animate-drawer-in-from-top`	Drawer enter from top
`animate-drawer-in-from-bottom`	Drawer enter from bottom
`animate-drawer-out-to-right`	Drawer exit to right
`animate-drawer-out-to-left`	Drawer exit to left
`animate-drawer-out-to-top`	Drawer exit to top
`animate-drawer-out-to-bottom`	Drawer exit to bottom
`animate-slide-in-from-right`	Slide in from right
`animate-slide-out-to-right`	Slide out to right
`animate-slide-in-from-left`	Slide in from left
`animate-slide-out-to-left`	Slide out to left
`animate-slide-in-from-top`	Slide in from top
`animate-slide-out-to-top`	Slide out to top
`animate-slide-in-from-bottom`	Slide in from bottom
`animate-slide-out-to-bottom`	Slide out to bottom
`animate-scale-in-slow`	Slow scale in
`animate-scale-in-fast`	Fast scale in
`animate-scale-out-fast`	Fast scale out
`animate-fade-in-opacity`	Fade in
`animate-fade-out-opacity`	Fade out
`animate-toast-slide-in-from-right`	Toast enter
`animate-toast-slide-out-to-right`	Toast exit
`animate-chart-option-fade`	Chart option transition
`animate-success-checkmark-in`	Success checkmark
`animate-blur-out`	Blur out
`animate-fade-in-blur`	Fade in with blur
`animate-fade-blur-slide-in-right`	Fade/blur slide in right
`animate-fade-blur-slide-out-right`	Fade/blur slide out right
`animate-fade-blur-slide-in-bottom`	Fade/blur slide in bottom
`animate-chat-loading-text`	Chat loading shimmer
`animate-skeleton-generate-content`	Skeleton content generation
`animate-skeleton-mask-generate-content`	Skeleton mask animation
`animate-update-tooltip-values`	Tooltip value transition
`animate-action-card-slide-in-left`	Action card left intro
`animate-action-card-slide-in-right`	Action card right intro
`animate-accordion-slide-down`	Accordion open
`animate-accordion-slide-up`	Accordion close
`animate-marquee`	Marquee loop
`animate-shimmer`	Shimmer
`animate-fade-in-up`	Fade in upward

Z-Index Utilities

These are custom @utility classes.

Utility	Purpose
`z-button`	Button layer
`z-sidebar`	Sidebar layer
`z-popover`	Popover layer
`z-header`	Header layer
`z-dropdown`	Dropdown layer
`z-dialog`	Dialog layer
`z-drawer`	Drawer layer
`z-calendar`	Calendar layer
`z-overlay-bg`	Overlay backdrop
`z-overlay`	Overlay
`z-overlay-content`	Overlay content
`z-onboarding-bg`	Onboarding backdrop
`z-onboarding-content`	Onboarding content
`z-tooltip`	Tooltip layer
`z-toast`	Toast layer

Interaction Utilities

These are custom @utility classes for accessibility and hit-target behavior.

Utility	Purpose
`focusable-element-outline`	Shared focus-visible outline
`focusable-input-shadow`	Shared focus-visible input shadow
`hover-expand-*`	Expands the interactive hit area without changing the layout

Example: hover-expand-2 focusable-element-outline

Mask Pattern Utilities

These are custom @utility classes that apply SVG mask patterns using currentColor.

Utility	Purpose
`mask-hexagons`	Hexagon pattern
`mask-bricks`	Brick pattern
`mask-diagonal-lines`	Diagonal line pattern
`mask-graph`	Graph/grid pattern
`mask-polka-dots`	Polka dot pattern
`mask-dots`	Dot pattern
`mask-dots-rotated`	Rotated dot pattern

Miscellaneous Utilities

Utility	Purpose
`page-sections-spacing-y-10`	Shared vertical spacing between page sections
`no-scrollbar`	Hides the scrollbar while preserving scroll behavior

Dark Mode

Dark mode is token-driven, not class-driven.

The same utility names work in both themes because @variant dark they reassign the underlying CSS variables. Frontend code should continue using the same semantic utilities:

Example: bg-bg-primary text-text-primary border border-fill-quaternary shadow-flat

Recommended Usage

Prefer semantic design-system utilities over default Tailwind values.

Prefer	Avoid
`text-body-small-regular`	`text-sm leading-5`
`text-text-secondary`	`text-gray-500`
`bg-bg-secondary`	`bg-zinc-100`
`rounded-8`	`rounded-md`
`shadow-flat`	arbitrary shadow values

Previous‹Setup Hybrid CMS Project Nextswitch›