Tonex starts with one color, but it does not treat that color as a swatch to copy everywhere. It treats the seed as intent: the source the rest of the system answers to. From there, Tonex derives semantic roles, light and dark palettes, contrast-safe pairings, and exportable tokens that can be bound into real tools.
The model is simple: preserve the brand where exactness matters, derive the system where coherence matters, and make every override explicit.
One seed, plus a brand-safe pair
The seed is your starting color: a brand color, a logo sample, a pasted hex value, or a color an agent has been told to use. It gives the system its direction.
Tonex uses that seed in two ways. First, it keeps the literal color available as a brand pair for places where exactness matters: a CTA, badge, hero accent, logo-adjacent block, or any surface that should use the input color unchanged. Tonex pairs that brand color with an automatically generated text color, so the brand pair can clear WCAG instead of leaving you to guess whether white or black is readable enough.
Second, Tonex derives the larger interface system from the seed. The generated roles may shift tone so they can do their jobs. That is why your exact seed is available as the brand pair, while roles like primary and primary-container are free to become the usable system around it.
Roles before tokens
Tonex does not return a loose list of colors. It returns semantic roles: colors named by their job, not their appearance.
| Role | Job |
|---|---|
primary | Main accent and action color |
surface | Neutral backgrounds behind content |
on-surface | Text and icons that sit on a surface |
error | Error states and destructive actions |
Every role has a relationship to the others. on-surface is readable on surface because the engine builds the pair together, not because someone matched them by eye. See Semantic color model for the full role set.
This is what makes Tonex portable. A target may call its main action color brand, accent, primary, or something custom. Tonex starts from semantic intent, then maps that source into the target's naming system.
Light and dark are co-derived
Dark mode is not a second palette patched onto the first. Tonex derives light and dark from the same source so the roles keep their relationships across both modes.
That matters because color problems often show up at the mode boundary. A color that feels strong in light mode can become muddy in dark mode. A muted surface can lose separation. Text that barely passes in one mode can fail in the other. Tonex treats both modes as one system with two expressions, not two unrelated themes.
Constraints decide what wins
You can shape the system at several stages. Later stages override earlier ones:
- Seed — the source color and brand-safe pair.
- Engine — variant, contrast, and the optional second source set the overall palette. See Variants and Contrast.
- Color overrides — step in on specific colors, at two levels:
- Palette level — change the source color of a whole family, or add your own named colors; the engine rebuilds that family's ramp around it. See Overrides.
- Token level — pin a single role to an exact value. A pin stops tracking the system entirely; it beats every other stage including a later binding. See Role overrides.
- Surfaces — tint or desaturate the neutral backgrounds. See Surfaces.
- shadcn bindings — point a shadcn token at a different generated role so it still tracks the system. A token-level pin from step 3 overrides this. See Role bindings.
When two stages touch the same color, the later one wins. That order is the difference between a flexible system and a pile of exceptions: broad choices stay broad, exact choices stay exact, and overrides do not hide where they came from.
Contrast is part of the model
Tonex checks foreground/background pairs against WCAG thresholds as you build. What passes in the preview is what you export, so readability is not a cleanup step at the end.
Under the hood, Tonex works in a perceptual color model, so tone changes are systematic instead of guessed by eye. See Contrast for the audit itself, and HCT for the color model underneath.
Agents bind, Tonex constrains
Agents are good at context. They can inspect a project, learn its token names, and bind a palette into the codebase you actually have. Tonex does not try to own that final mile.
Tonex owns the color contract before that handoff: the seed, brand pair, semantic roles, light and dark behavior, contrast checks, and export rules. The agent can decide where the tokens go. Tonex makes sure the colors it receives are not random output with no safety net.
That is the core idea: the semantic source is the contract; the target mapping is the last mile. See Export and Targets & formats for how that contract travels.