# Tones

> One way to color a React component: a tone or any CSS color becomes five CSS variables every variant paints with.

- Type: React helper (Hooks & Utilities)
- Access: Free (the source is open to everyone)
- Version: 1.0.0
- Install: `npx wingo-ui@latest add tones`
- Docs: https://wingo-ui.com/components/tones

## Interaction

Each row is one tone painted three ways: a solid fill, a soft tint and an outline. Pick any color in the playground to see colorVars build the same set from it, with readable text on both themes.

## Installation

```bash
npx wingo-ui@latest add tones
```

The CLI adds the files, their dependencies and a version record for updates.

With shadcn: `npx shadcn@latest add https://wingo-ui.com/r/tones.json`

Files:

- `lib/tones.ts`

## Usage

```tsx
import { colorVars, toneClasses, type Tone } from "@/lib/tones"
import { cn } from "@/lib/utils"

export function Badge({ tone = "neutral", color, className, ...props }: React.ComponentProps<"span"> & { tone?: Tone; color?: string }) {
  return (
    <span
      data-slot="badge"
      className={cn(toneClasses[tone], "rounded-full bg-(--tone-soft) px-2 py-0.5 text-xs font-medium text-(--tone-soft-foreground)", className)}
      style={colorVars(color)}
      {...props}
    />
  )
}
```

## API

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `color?` | `string` | `"#7C3AED"` | colorVars(color): any CSS color turned into the five --tone-* vars, for a component's color prop. |
| `toneClasses?` | `Record<"neutral" \| "brand" \| "success" \| "warning" \| "danger" \| "info", string>` |  | Classes that set --tone, --tone-foreground, --tone-soft, --tone-soft-foreground and --tone-border from the design tokens. |

## Parts

### colorVars (function)

The same vars as an inline style. The text on the fill turns black or white by lightness; soft text mixes toward the foreground. Signature: (color?: string) => CSSProperties | undefined.

### TONES (constant)

Every tone in order, and a guard that turns an unknown string into a tone. Type: Tone[].

### toTone (function)

Every tone in order, and a guard that turns an unknown string into a tone. Signature: (value: unknown, fallback?: Tone) => Tone.

## Examples

- **Invoice status badges**: One badge component; toneClasses maps paid, pending, overdue and draft to success, warning, danger and neutral.
- **Brand colors**: colorVars turns any hex color into the same five variables, with text that stays readable on a light amber.

## See also

- [Button](https://wingo-ui.com/components/button) ([Markdown](https://wingo-ui.com/components/button.md))
- [Motion presets](https://wingo-ui.com/components/motion) ([Markdown](https://wingo-ui.com/components/motion.md))

---

Canonical: https://wingo-ui.com/components/tones
More components: https://wingo-ui.com/components · Index for agents: https://wingo-ui.com/llms.txt