Skip to main content

​
Introduction to Theme UI

Theme UI is a library for creating themeable user interfaces based on constraint-based design principles. It provides a powerful, flexible API for building custom component libraries, design systems, web applications, and more.

​
What is Theme UI?

Theme UI, also known as The Design Graph Framework, enables developers to create consistent, themeable React applications by:
  • Using a theme-based styling system with the sx prop
  • Defining design tokens (colors, typography, spacing) in a centralized theme object
  • Applying styles that reference your theme values throughout your application
  • Supporting multiple color modes (like dark mode) out of the box
  • Providing primitive UI components with variant-based styling
Theme UI is the next evolution of Styled System, from the creators of utility-based, atomic CSS methodologies.

​
Key Benefits

​
Theme-Based Styling

All styles reference values from a global theme object, making it easy to maintain consistency across your application: 
/** @jsxImportSource theme-ui */

export default () => (
  <div
    sx={{
      fontSize: 4,        // picks up theme.fontSizes[4]
      color: 'primary',   // picks up theme.colors.primary
      bg: 'background',   // picks up theme.colors.background
      p: 3,               // picks up theme.space[3]
    }}
  >
    Themed content
  </div>
)

​
Constraint-Based Design

Theme UI encourages you to define scales for colors, typography, spacing, and other design tokens. This constraint-based approach helps maintain design consistency:
  • Typography scales: Define font sizes, weights, and families
  • Color palettes: Create color systems with semantic naming
  • Spacing scales: Use consistent spacing throughout your app
  • Layout primitives: Build responsive layouts with ease

​
Built-in Color Mode Support

Switch between light and dark modes (or any custom color modes) without additional configuration: 
import { useColorMode } from 'theme-ui'

const ColorModeToggle = () => {
  const [colorMode, setColorMode] = useColorMode()
  return (
    <button
      onClick={() => setColorMode(colorMode === 'dark' ? 'light' : 'dark')}
    >
      Toggle {colorMode === 'dark' ? 'Light' : 'Dark'}
    </button>
  )
}

​
Mobile-First Responsive Styles

Apply responsive styles using arrays with a mobile-first approach: 
/** @jsxImportSource theme-ui */

export default () => (
  <div
    sx={{
      width: ['100%', '50%', '25%'],  // 100% on mobile, 50% on tablet, 25% on desktop
      fontSize: [2, 3, 4],             // Responsive font sizes
    }}
  >
    Responsive content
  </div>
)

​
Framework Compatibility

  • Built with Emotion for scoped styles
  • Works with existing Styled System components
  • Compatible with virtually any UI component library
  • Plugin available for Gatsby sites and themes
  • Style MDX content with a simple API

​
When to Use Theme UI

Theme UI is ideal for:
  • Design systems: Building reusable component libraries with theming support
  • White-label applications: Apps that need multiple brand themes
  • Multi-tenant platforms: Applications serving different customers with unique branding
  • Dark mode support: Apps requiring light/dark mode or custom color schemes
  • Content-heavy sites: Websites using MDX or Markdown with styled components
  • Gatsby themes: Creating distributable, themeable Gatsby themes
If you only need the sx prop without color modes or UI components, consider installing @theme-ui/core for a lighter bundle.

​
Theme Specification

Theme UI follows the System UI Theme Specification, which provides a standard for defining theme objects. This specification enables interoperability between different styling libraries and tools.

​
Next Steps

Installation

Install Theme UI and its dependencies

Quickstart

Build your first themed component

Build docs developers (and LLMs) love

Get started for freeTalk to us