Tone

A semantic status scale used by status-bearing components: dots, banners, callouts, toasts, progress bars, and trend badges.

Tone is a set of five canonical statuses: neutral, info, ok, warn, err, plus primary for accent-driven components. Every component that displays status reads from --m-tone-* CSS variables, so a single tone change re-colors foreground, background, and border together.

toneVars("ok") produces a style object with --m-tone-fg, --m-tone-bg, --m-tone-border, and several internal variables for the given tone. Components prefer the data-m-tone attribute (styled by tone.css) when they own their root element, or spread the vars when they don’t.

Components like StatusDot, Banner, Callout, Toast, ProgressBar, and TrendBadge all accept a tone prop. Pass a canonical tone or an alias; resolveTone normalizes it.

TonesCopy link

The canonical list is TONES: ["neutral", "primary", "info", "ok", "warn", "err"]. Each one maps to a base color:

neutralCopy link

The default, no-status tone. Uses the foreground dim color as its base and the neutral surface ramp for backgrounds. ThemeProvider sets a neutral tone at the root as a default.

primaryCopy link

The accent / brand tone. Derived from --m-color-primary. Used by buttons, selected states, and brand-colored elements.

infoCopy link

Informational or in-progress states. Derived from --m-color-bright, the brightest step on the accent ramp.

okCopy link

Success, healthy, online. A fixed green per mode, not derived from the base color.

warnCopy link

Warning, degraded, attention needed. A fixed amber per mode.

errCopy link

Error, critical, down. A fixed red per mode.

How components use toneCopy link

Every tone-bearing component accepts a tone prop. You can pass a canonical tone or any recognized alias:

import { StatusDot, Banner, Callout, Toast } from "@solarius/onset";

// Canonical tones
<StatusDot tone="ok" />
<Banner tone="warn" title="Degraded performance" />
<Callout tone="info">Deployment is in progress.</Callout>

// Aliases — resolveTone() normalizes these
<StatusDot tone="success" />   // → "ok"
<Banner tone="warning" />      // → "warn"
<Callout tone="danger" />      // → "err"
<StatusDot tone="dim" />       // → "neutral"

Inside a component, the recommended approach is to set data-m-tone="ok" on the root element. The global tone.css stylesheet handles the rest:

// In your custom component's JSX:
<div data-m-tone="warn" className="my-status-card">
  <span className="icon">…</span>
  <span className="label">{label}</span>
</div>

// In your CSS, read the resolved tone vars:
.my-status-card .icon {
  color: var(--m-tone-fg);
}
.my-status-card {
  background: var(--m-tone-bg);
  border-color: var(--m-tone-border);
}

When a component can’t own the attribute on its root (e.g. it’s rendered inside a Popover panel whose element the caller controls), spread toneVars() instead:

import { toneVars } from "@solarius/onset/tokens";

// Inside a component that renders into a caller-controlled wrapper:
<div style={toneVars("err")}>
  <span style={{ color: "var(--m-tone-fg)" }}>Error state</span>
</div>;

allToneVarsCopy link

allToneVars() returns a map of every tone to its variable set. Useful for generating static CSS at build time:

import { allToneVars } from "@solarius/onset/tokens";

const all = allToneVars();
// {
//   neutral: { "--m-tone-fg": "…", "--m-tone-bg": "…", … },
//   primary: { "--m-tone-fg": "…", "--m-tone-bg": "…", … },
//   info:    { … },
//   ok:      { … },
//   warn:    { … },
//   err:     { … },
// }

API referenceCopy link

TONESCopy link

The canonical readonly array: ["neutral", "primary", "info", "ok", "warn", "err"].

ToneCopy link

The Tone type is (typeof TONES)[number], a union of those six string literals.

resolveTone(tone, fallback?)Copy link

Accepts any string and returns a canonical Tone. If the input matches a known tone it returns it directly. If it matches an alias ("success", "warning", "danger", etc.) it returns the mapped canonical tone. Otherwise it returns the fallback (default "neutral").

TONE_ALIASESCopy link

A Record<string, Tone> mapping all recognized alternative spellings:

import { TONE_ALIASES } from "@solarius/onset/tokens";

// {
//   default: "neutral",   dim: "neutral",
//   idle: "neutral",      muted: "neutral",
//   accent: "primary",    brand: "primary",
//   prov: "info",         pending: "info",
//   success: "ok",        ok: "ok",
//   warning: "warn",      caution: "warn",
//   danger: "err",        error: "err",
//   critical: "err",
// }

toneVars(tone)Copy link

Returns a Record<string, string> of --m-tone-* CSS custom properties for a single tone. The returned object includes --m-tone-base, --m-tone-fg, --m-tone-bg, --m-tone-bg-strong, --m-tone-border, --m-tone-solid, and --m-tone-on-solid.

allToneVars()Copy link

Returns a Record<Tone, Record<string, string>>: every tone's variables at once. Used to generate the static tone.css rulesheet.