tessl/npm-theme-ui

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Theme UI

Name: tessl/npm-theme-ui
Author: tessl

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;
  };
}