or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

components.mdhooks-utilities.mdindex.mdstyling-system.mdtheming.md
tile.json

tessl/npm-theme-ui

The Design Graph Framework - a library for creating themeable user interfaces based on constraint-based design principles

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/theme-ui@0.17.x

To install, run

npx @tessl/cli install tessl/npm-theme-ui@0.17.0

index.mddocs/

Theme UI

Theme UI is a library for creating themeable user interfaces based on constraint-based design principles. Build custom component libraries, design systems, web applications, and more with a flexible API for best-in-class developer ergonomics. It provides theme-based styling with the sx prop, a complete component library, and built-in support for color modes.

Package Information

  • Package Name: theme-ui
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install theme-ui @emotion/react

Core Imports

import { ThemeUIProvider, Box, Button, useColorMode } from 'theme-ui'

For ESM imports:

import { ThemeUIProvider, jsx } from 'theme-ui'
import { Box, Button, Text } from 'theme-ui'

For CommonJS:

const { ThemeUIProvider, Box, Button } = require('theme-ui')

JSX pragma for automatic sx prop support:

/** @jsxImportSource theme-ui */

Basic Usage

import { ThemeUIProvider, Box, Button, Text } from 'theme-ui'

const theme = {
  colors: {
    text: '#000',
    background: '#fff',
    primary: '#33e',
    modes: {
      dark: {
        text: '#fff',
        background: '#000',
        primary: '#0cf',
      },
    },
  },
  fonts: {
    body: 'system-ui, sans-serif',
    heading: '"Avenir Next", sans-serif',
  },
  fontSizes: [12, 14, 16, 20, 24, 32, 48, 64],
  space: [0, 4, 8, 16, 32, 64, 128, 256],
}

export default function App({ children }) {
  return (
    <ThemeUIProvider theme={theme}>
      <Box sx={{ p: 4 }}>
        <Text as="h1" sx={{ fontSize: 5, color: 'primary' }}>
          Hello Theme UI
        </Text>
        <Button variant="primary">Get Started</Button>
        {children}
      </Box>
    </ThemeUIProvider>
  )
}

Using the sx prop with custom pragma:

/** @jsxImportSource theme-ui */

export default function Component() {
  return (
    <div
      sx={{
        color: 'primary',
        fontSize: 4,
        padding: [2, 3, 4], // responsive values
        '&:hover': {
          color: 'secondary',
        },
      }}
    >
      Theme-aware styling
    </div>
  )
}

Architecture

Theme UI is built around several key architectural concepts:

  • Theme Specification: Follows the System UI theme specification for interoperability and consistency across tools
  • Constraint-Based Design: Uses design scales (colors, space, typography) to enforce consistent styling
  • Component System: Provides primitive and UI components with built-in theme awareness and system props
  • Styling Engine: Built on Emotion for performant CSS-in-JS with theme-aware style objects
  • Color Mode System: First-class support for multiple color modes with automatic persistence and flash prevention
  • JSX Enhancement: Custom JSX runtime and pragma for seamless sx prop integration

Capabilities

Styling System

Core styling functionality including the sx prop, responsive design, theme-aware CSS utilities, and the custom JSX runtime system.

function jsx(type: any, props: any, ...children: any[]): JSX.Element;

interface SxProp {
  sx?: ThemeUIStyleObject;
}

interface ThemeUIStyleObject {
  [property: string]: ResponsiveStyleValue<any>;
}

Styling System

Component Library

Complete set of primitive and UI components including layout, typography, forms, and interactive elements with built-in theme support and system props.

interface BoxProps extends SxProp {
  as?: keyof JSX.IntrinsicElements | React.ComponentType<any>;
  children?: React.ReactNode;
  [key: string]: any;
}

interface ButtonProps extends SxProp {
  variant?: string;
  children?: React.ReactNode;
  [key: string]: any;
}

Component Library

Theming System

Theme definition, color modes, design tokens, and theme specification compliance for creating consistent, themeable interfaces.

interface Theme {
  colors?: ColorTheme;
  fonts?: { [key: string]: string };
  fontSizes?: (string | number)[];
  fontWeights?: { [key: string]: string | number };
  lineHeights?: { [key: string]: string | number };
  space?: (string | number)[];
  sizes?: { [key: string]: string | number };
  radii?: { [key: string]: string | number };
  shadows?: { [key: string]: string };
  styles?: ThemeStyles;
  [key: string]: any;
}

interface ColorTheme {
  [key: string]: string;
  modes?: {
    [modeName: string]: {
      [key: string]: string;
    };
  };
}

Theming System

Hooks and Utilities

Theme context access, color mode management, and CSS utilities for advanced theme manipulation and style generation.

function useThemeUI(): ThemeUIContextValue;
function useColorMode(): [string, (mode: string) => void];
function css(styles: ThemeUIStyleObject): (theme: Theme) => CSSObject;
function get(object: object, key: string, fallback?: any): any;
function merge(target: object, source: object): object;

Hooks and Utilities

Types

interface ThemeUIContextValue {
  theme: Theme;
  colorMode?: string;
  setColorMode?: (mode: string) => void;
}

interface Theme {
  colors?: ColorTheme;
  fonts?: { [key: string]: string };
  fontSizes?: (string | number)[];
  fontWeights?: { [key: string]: string | number };
  lineHeights?: { [key: string]: string | number };
  space?: (string | number)[];
  sizes?: { [key: string]: string | number };
  radii?: { [key: string]: string | number };
  shadows?: { [key: string]: string };
  styles?: ThemeStyles;
  [key: string]: any;
}

interface ColorTheme {
  [key: string]: string;
  modes?: {
    [modeName: string]: {
      [key: string]: string;
    };
  };
}

interface ThemeStyles {
  root?: ThemeUIStyleObject;
  [element: string]: ThemeUIStyleObject | undefined;
}

interface SxProp {
  sx?: ThemeUIStyleObject;
}

interface ThemeUIStyleObject {
  [property: string]: ResponsiveStyleValue<any>;
}

type ResponsiveStyleValue<T> = T | Array<T | null>;

interface CSSObject {
  [property: string]: any;
}

interface ThemeUICSSObject extends CSSObject {
  [property: string]: ResponsiveStyleValue<any>;
}

type StylePropertyValue<T> = ResponsiveStyleValue<T>;

type ColorMode = string;

interface ColorModesScale {
  [mode: string]: {
    [key: string]: string;
  };
}