DOCSEARCHbyAlgolia
Submit Docs

Theme UI

repository·develop·Indexed 11 days ago

https://github.com/system-ui/theme-ui

A design graph framework for creating themeable user interfaces based on constraint-based design principles. It provides a flexible API centered around the `sx` prop and a standardized theme specification, including packages for color manipulation (@theme-ui/color), color mode management (@theme-ui/color-modes), and a framework-agnostic core (@theme-ui/css). Version 0.17.4.

Tokens
94.2K
Snippets
359
Records
439
Agent score
88%

What's inside Theme UI

  1. Overview of Theme UI packages

    develop

    Theme UI provides a core library theme-ui along with several optional specialized packages. Depending on your project needs (e.g., Gatsby integration, Tailwind support, or specific UI components), you can install only the necessary modules.

    Core and Utility Packages:

    • @theme-ui/css: CSS utilities.
    • @theme-ui/core: Core logic and runtime.
    • @theme-ui/components: Pre-built UI components.
    • @theme-ui/color: Color management.
    • @theme-ui/color-modes: Color mode (light/dark) support.
    • @theme-ui/match-media: Media query utilities.
    • @theme-ui/typography: Typography tools.

    Framework and Integration Packages:

    • gatsby-plugin-theme-ui: Integration for Gatsby projects.
    • gatsby-theme-style-guide: Gatsby theme for style guides.
    • @theme-ui/tailwind: Tailwind CSS integration.

    Specialized Packages:

    • @theme-ui/mdx: MDX support.
    • @theme-ui/prism: Syntax highlighting with Prism.
    • @theme-ui/sidenav: Sidenav component logic.
    • @theme-ui/presets: Pre-configured theme settings.

  2. What is Theme UI

    develop

    Theme UI is a design graph framework for creating themeable user interfaces using constraint-based design principles. It allows you to build custom component libraries, design systems, and web applications by providing a flexible API that ensures consistency through scales for color, typography, and layout.

    Key features include:

    • Theme-aware sx prop: A powerful way to apply CSS styles that can directly reference theme values.
    • Primitive UI components: A collection of over 30 built-in components (like Box, Container, and Button) to speed up development.
    • Responsive styles: Easy, mobile-first responsive design capabilities.
    • Built-in dark mode: Support for color modes out of the box.
    • Constraint-based design: Styles are rooted in predefined scales to maintain visual harmony.

  4. Use @theme-ui/core

    develop

    The @theme-ui/core package is the central engine of Theme UI. It provides the JSX runtime and the sx prop functionality that allows you to write styles directly on components using your theme's design tokens. It is designed to work with any framework that supports JSX (like React) and is typically used in conjunction with a theme object to enable responsive, token-based styling.

    import { Box } from '@theme-ui/core'

// The sx prop allows using theme tokens directly
const MyComponent = () => (
  <Box sx={{ color: 'primary', fontSize: 2 }}>
    Hello Theme UI
  </Box>
)

  5. Use Theme UI component kits

    develop

    Several libraries provide pre-built, themeable React components designed specifically for Theme UI:

    • @component-controls/components: Components built for Theme UI.
    • @source-cooperative/components: Used by Source Cooperative.
    • @cartolab/elements: Themeable components for map-based web applications.
    • @carbonplan/components: Shared React components for Carbonplan.
    • @undataforum/components: Shared React components for UN Data Forum.
    • prestyled: A component library for Theme UI.

  6. Preview and generate Theme UI themes

    develop

    Use these tools to visualize themes or generate new ones:

    • Theme UI Gallery: Live previewer for themed components.
    • Skin UI: Live previewer and code editor.
    • Oh My Theme: Previewer for Theme UI presets.
    • Components.ai Theme Generator: Generate, preview, and export random themes.
    • Controlled Styled Editor: Edit React components based on System UI design principles.

  8. Explore Theme UI custom themes

    develop

    You can use existing design systems and presets built with Theme UI to jumpstart your styling. Notable examples include:

    • Automattic/vip-design-system: Design system for WordPress VIP.
    • @hackclub/theme: Used by Hack Club.
    • @carbonplan/theme: Used by Carbonplan.
    • @undataforum/preset: Used by United Nations World Data Forum.
    • theme-ui-preset-geist: Adapted from Geist UI.
    • theme-ui-preset-nice-boys

  9. Use built-in Theme UI components

    develop

    Theme UI provides a set of built-in UI components for layouts, grids, buttons, form elements, and more. These components can be used as an alternative to the JSX pragma for applying theme-aware styles, or alongside it to provide specific UI elements. Common components include Box, Flex, Heading, and Button.

    <Box p={4} bg="highlight">
  <Flex sx={{ alignItems: 'center' }}>
    <Heading>Components</Heading>
    <Button ml="auto">Beep</Button>
  </Flex>
</Box>

  10. Explore Theme UI ecosystem extensions

    develop

    Beyond web frameworks, Theme UI has extensions for other platforms and workflows:

    • theme-ui-native: Adapted for React Native projects.
    • Dripsy: Responsive, theme-based design system for Expo + React Native Web.
    • Theme UI plugin for Figma: Converts Theme UI config to Figma Styles.
    • @fabulas/theme-ui-modifiers: BEM-style modifiers for Theme UI components.
    • @mattjennings/react-modal: Animated modals using Theme UI & Framer Motion.
    • React Layouts: Grab-and-go layouts for React.
    • Next Theme UI: Components for Next.js integration.
    • MDXP: MDX-based presentation deck library using System UI specifications.

  11. Customize components using variants

    develop

    You can define custom stylistic variations in your theme object. Each Theme UI component accepts a variant prop that allows you to apply these predefined styles quickly. Variants can be nested (e.g., text.heading) and can even extend other variants using the variant key within the theme definition.

    {
  // ...base theme...
  buttons: {
    secondary: {
      fontWeight: 'bold',
      color: 'white',
      bg: 'primary',
      '&:hover': {
        bg: 'dark',
      },
    },
  },
  text: {
    heading: {
      fontFamily: 'heading',
      fontWeight: 'heading',
      lineHeight: 'heading',
    },
    display: {
      // extends the text.heading styles
      variant: 'text.heading',
      fontSize: [6, 7, 8],
      fontWeight: 'display',
    },
  },
  cards: {
    primary: {
      padding: 2,
      borderRadius: 4,
      boxShadow: '0 0 4px 1px rgba(0, 0, 0, 0.5)',
    },
  },
}

    Usage:

    <Button variant="secondary">Secondary Button</Button>

  12. Use `styles` variants for global and themed elements

    develop

    Variants defined within the styles object in your theme are used for several specialized purposes:

    • Base Styles: The styles object can style child HTML elements or Markdown content via the BaseStyles component.
    • Root Styles: If useRootStyles is enabled in your configuration, styles.root will style the <html> element.
    • Themed Components: Themed components automatically use their corresponding variant from the styles object (e.g., <Themed.h2> uses styles.h2).