English
Core Concepts
This page explains how configuration decides colors and sizes, and what strict mode and diagnostics do.
Design
CSS conventions have long relied on discipline: no magic numbers, colors and sizes through shared variables. Tailwind provides the atomic syntax, but leaves every color and size open, so a team convention can only be enforced by code review.
Tunewind writes that convention as configuration and applies it at build time. Colors and sizes become finite sets in the config, so whether a class is usable is decided when the build runs.
The boundary of the design system therefore lives in the config instead of in review.
Tunewind keeps Tailwind's syntax and usage. Class structure, variants, breakpoints and most utilities stay as they are; only color and size values are narrowed.
Themes
The color system has three layers.
- Palette: the source of colors. 26 built-in families with 11 shades each; an object can override one shade or define a new family.
- Aliases: semantic names. The string form of
palette, where{ primary: "sky" }makesprimaryandskypoint to the same scale. - Mappings: the available shades and opacities. Keys of
shadeandopacitybecome class suffixes; undeclared keys are unavailable.
Light and dark are a second dimension on palette and shade. A value can be a plain value or a light and dark pair:
ts
palette: { primary: { light: "sky", dark: "slate" } },
shade: { default: { light: 600, dark: 500 }, subtle: 300 },With the primary color as an example:
ts
theme: {
palette: { primary: { light: "sky", dark: "slate" } },
shade: { default: { light: 600, dark: 500 }, subtle: 300 },
opacity: { default: 100, weak: 80 },
}text-primaryuses600in light mode and500in dark mode.text-primary-subtleuses300in both modes.bg-primary/weakuses80%opacity in both modes.
Themes and modes override these layers. Each scheme declares only what differs from the base, and class names stay unchanged. Dark mode follows prefers-color-scheme, with no extra attribute.
Use a scheme's prefix when a color must be set explicitly for one theme, such as ocean:text-primary.
white and black are always available. Built-in families not declared in palette still produce output; whether they survive is decided by strict mode.
See colors and themes for the full configuration.
Sizes
The size system has two parts.
- Units: length and suffix. Keys of
unitsbecome class suffixes,defaulthas none; a unit can be a fixed length or carry its own range. - Ranges: usable numbers.
min,stepandmaxcan be global or per unit; numbers outside the range are unavailable.
With the default unit as an example:
ts
size: {
max: 64,
units: { default: "4px", r: "1rem" },
}p-4is4 * 4px.w-8ris8 * 1rem.w-96exceedsmaxand is unavailable.
Breakpoints override the length on top of the same units, with the same numbers and class names:
ts
breakpoints: {
xl: { units: { r: "1.25rem" } },
}Here xl:w-8r is 8 times 1.25rem.
See sizes and breakpoints for the full configuration.
Strict mode
Strict mode decides whether values outside the config survive, covering arbitrary values, raw color names and the escape prefix. It can be turned off as a whole or enabled per check; at its strictest, only declared colors and in-range sizes are usable.
The raw: prefix applies to arbitrary values and raw color names only; size ranges and the opacity whitelist do not accept it. See strict mode for the modes and flags.
Diagnostics
Nothing is printed by default; violations only show up as declarations missing from the output. When enabled, the build handles removed nodes by level:
off: remove silently.warn: print each target and reason, keep building.error: collect and throw, aborting the build; suitable for CI.
Lines are ordered by first occurrence and deduplicated, with a configurable limit. Configuration errors are thrown regardless of the level.
See diagnostics for levels and output.