React Web Guide

This guide walks you through setting up toned-styles in a React web project using Vite. The same approach works with any bundler that supports TypeScript.

1. Install Dependencies

npm install @toned/core @toned/react @toned/systems @toned/themes

2. Add the Vite Plugin

The toned Vite plugin generates all token CSS at build time. Add it to your vite.config.ts:

// vite.config.ts
import toned from '@toned/core/vite'
import { system } from '@toned/systems/base'
import react from '@vitejs/plugin-react'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [toned({ system }), react()],
})

3. Create the Config File

Create toned.config.ts at your project root. This file must be imported before any component that uses toned styles:

// toned.config.ts
import '@toned/themes/shadcn/config.css'
import 'virtual:toned.css'

import { defineConfig, setConfig } from '@toned/core'
import reactConfig from '@toned/react/react-web'

export default setConfig(
  defineConfig({
    ...reactConfig,
    useClassName: true,  // output className props
    useMedia: true,      // enable responsive breakpoints
    mediaMode: 'css',    // use real CSS @media rules
  }),
)

4. Import Config in Your Entry Point

Import the config file at the very top of your entry point, before any component imports:

// main.tsx
import '../toned.config.ts'

import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import { App } from './App.tsx'

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <App />
  </StrictMode>,
)

5. Define Styles

Create a styles file using the stylesheet function from the base system. Keep style definitions separate from components for better reusability:

// styles/button.ts
import { stylesheet } from '@toned/systems/base'

export const buttonStyles = stylesheet({
  container: {
    bgColor: 'action',
    borderRadius: 'medium',
    borderWidth: 'none',
    paddingX: 3,
    paddingY: 2,
    cursor: 'pointer',
  },
  label: {
    textColor: 'on_action',
    typo: 'body',
  },
}).variants<{
  variant: 'primary' | 'secondary'
}>(($) => ({
  [$.variant('secondary')]: {
    container: {
      bgColor: 'action_secondary',
    },
    label: {
      textColor: 'on_action_secondary',
    },
  },
}))

6. Use Styles in Components

Import your stylesheet and the useStyles hook. Spread the returned element props onto your JSX:

// Button.tsx
import { useStyles } from '@toned/react'
import { buttonStyles } from './styles/button.ts'

export function Button({ label, variant = 'primary' }: {
  label: string
  variant?: 'primary' | 'secondary'
}) {
  const s = useStyles(buttonStyles, { variant })
  return (
    <button type="button" {...s.container}>
      <span {...s.label}>{label}</span>
    </button>
  )
}

Config Options

Key configuration options for web projects:

useClassName: true -- Outputs className props alongside style. This enables CSS-based token resolution and is recommended for production web apps.

useMedia: true -- Enables responsive breakpoint support in stylesheets.

mediaMode: 'css' -- Compiles responsive breakpoints into native CSS @media rules rather than evaluating them in JavaScript.