Getting Started

toned-styles is a cross-platform styling system for React that uses design tokens and type-safe variants. It works with both React Web (DOM) and React Native, letting you share styling logic across platforms while outputting optimised, platform-native styles.

Installation

Install the core packages with your preferred package manager:

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

For web projects you will also need the DOM injection helper and a theme. The shadcn theme ships as a ready-made set of CSS custom properties:

npm install @toned/themes

Project Setup (Vite)

Add the toned Vite plugin to your vite.config.ts. It generates all token CSS at build time as a static file:

// 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()],
})

Then create a toned.config.ts file at the root of your project. This file imports the generated CSS and sets the active configuration:

// 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,
    useMedia: true,
    mediaMode: 'css',
  }),
)

Not using Vite? You can use inject(system) from @toned/core/dom instead to generate CSS at runtime. See the SSR guide for details.

Your First Component

Import stylesheet from the base system to define element styles using design tokens, then use useStyles in your React component to apply them:

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

export const buttonStyles = stylesheet({
  container: {
    bgColor: 'action',
    borderRadius: 'medium',
    borderWidth: 'none',
    cursor: 'pointer',
  },
  label: {
    textColor: 'on_action',
  },
})

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

export function Button({ label }: { label: string }) {
  const s = useStyles(buttonStyles)
  return (
    <button type="button" {...s.container}>
      <span {...s.label}>{label}</span>
    </button>
  )
}

The useStyles hook returns an object whose keys match the element names you defined in the stylesheet. Spreading these onto JSX elements applies the corresponding style and className props automatically.

Next Steps

Read the Core Concepts page to understand how tokens, stylesheets, and variants fit together. Then explore the React Web or React Native guides for platform-specific setup instructions.