Core Concepts

toned-styles is built around four core ideas: design tokens, systems, stylesheets, and variants. Together they give you type-safe, cross-platform styling with a single authoring model.

Design Tokens

Tokens are the atomic building blocks of your design system. Each token maps a semantic name to one or more platform-specific values. For example, the bgColor token accepts values like 'action', 'muted', or 'elevated'. On the web these resolve to CSS custom properties; on React Native they resolve to colour values directly.

// Tokens are used directly inside stylesheet definitions:
container: {
  bgColor: 'action',       // semantic background colour
  borderRadius: 'medium',  // semantic border radius
  paddingX: 3,             // spacing scale value
}

The base system ships with tokens for colour (bgColor, textColor, borderColor), borders (borderRadius, borderWidth), typography (typo), shadows (shadow), layout (paddingX, paddingY, gap, flexLayout), and sizing (width, height).

Systems

A system is a collection of tokens plus configuration (breakpoints, selectors, rules). You create one with defineSystem:

import { defineSystem } from '@toned/core'

export const { system, stylesheet, t } = defineSystem(
  { ...typo, ...colour, ...border, ...layout, ...shadow, ...sizes },
  config,
)

The returned stylesheet function is bound to that system's token set, giving you full autocompletion and type checking for every token property.

Stylesheets

A stylesheet defines one or more named elements, each with a set of token values and an optional style escape hatch for raw CSS properties:

const cardStyles = stylesheet({
  card: {
    bgColor: 'elevated',
    borderRadius: 'large',
    borderColor: 'subtle',
    borderWidth: 'thin',
    shadow: 'small',
    padding: 3,
  },
})

Stylesheets are plain objects until they are consumed by a framework adapter (like useStyles in React). This keeps your style definitions platform-agnostic.

Variants

Variants let you conditionally apply different token values based on component state. Chain .variants() onto a stylesheet and use the dollar-sign builder to declare variant conditions:

const buttonStyles = stylesheet({
  container: { bgColor: 'action', borderRadius: 'medium' },
  label: { textColor: 'on_action' },
}).variants<{
  size: 'm' | 's'
  variant: 'accent' | 'danger'
}>(($) => ({
  [$.variant('accent')]: {
    container: { bgColor: 'action' },
    label: { textColor: 'on_action' },
  },
  [$.size('m')]: {
    container: { paddingX: 3 },
  },
  [$.size('s')]: {
    container: { paddingX: 2, paddingY: 1 },
  },
}))

Variant keys are fully typed: your component will get compile-time errors if it passes invalid variant values to useStyles.

Media Queries / Breakpoints

The base system defines breakpoints (xs, sm, md, lg, xl). You can apply responsive token values by prefixing a breakpoint name with @:

const responsiveCard = stylesheet({
  card: {
    paddingX: 2,
    '@md': {
      paddingX: 4,
    },
    '@lg': {
      paddingX: 6,
    },
  },
})

When mediaMode is set to 'css' in your config, these generate real CSS @media rules. In JavaScript mode they are evaluated at runtime.