Skip to main content

Get Started

Installation​

Install Tosui using your preferred package manager:

npm install @tosui/react
# or
yarn add @tosui/react
# or
pnpm add @tosui/react

Setup​

Import the base styles in your application entry point (e.g., main.tsx or App.tsx):

import "@tosui/react/styles.css";

This stylesheet defines all of Tosui's design token CSS variables and sets two global styles on :root:

  • color: var(--t-color-foreground)
  • background-color: var(--t-color-background)

This ensures that plain text and non-Tosui elements inherit theme-aware colors (including dark mode) without any extra setup. No other global styles are applied — there are no CSS resets, no * selectors, and no element-level styles.

If you need to opt out of this behavior, override the two variables on :root:

:root {
  color: unset;
  background-color: unset;
}

Optional: Font Styles​

Tosui includes optional IBM Plex font styles. To use them, import the fonts CSS:

import "@tosui/react/fonts.css";

Basic Usage​

Start using Tosui components in your React application:

import { Box, Text, Heading } from "@tosui/react";

function App() {
  return (
    <Box p={6}>
      <Heading fontSize="3xl" fontWeight="semibold">
        Welcome to Tosui
      </Heading>
      <Text fontSize="md" color="foregroundMuted">
        A constraint-driven design system for React
      </Text>
    </Box>
  );
}

Core Principles​

Tosui is built on these core principles:

Fewer, Better Choices​

Every design token earns its place in the system. Instead of dozens of color shades or spacing values, Tosui provides a focused set of options that cover real-world use cases.

Composition Over Configuration​

Build complex interfaces from simple primitives like Box, Text, and Heading. The system makes the right thing easy and the custom thing possible.

Semantic, Not Prescriptive​

Design values describe intent (foreground, background), not specific measurements. This means themes swap seamlessly and components adapt automatically to light/dark modes.

Next Steps​

Primitives

  • Box - Foundational layout primitive
  • Text - Text with typography props
  • Heading - Semantic headings

Layout

  • Stack - Vertical/horizontal stacking
  • Flex - Flexbox container
  • Grid - CSS Grid container

Forms

Overlays