Tovai

Token groups define named values. CSS output places every token in :root as a custom property named --<group>-<name>.

Typed token groups are shorthand top-level declarations for common design-token families:

These emit as --typography-*, --shadow-*, --breakpoint-*, --z-index-*, and --duration-*.

Scales use the same reference model as token groups. A reference such as space.md resolves to var(--space-md).

Token and scale values may reference other tokens and use simple arithmetic:

CSS emits arithmetic as calc(var(--space-md) * 2). Supported operators are plus, minus, times, and divided-by, plus the symbolic forms +, -, *, and /.

Color token values can be derived at compile time:

lighten(color, amount) mixes toward white. darken(color, amount) mixes toward black. alpha(color, amount) emits rgba(...). mix(left, right, amount) mixes from left toward right. Amounts accept 0..1 numbers or percentages.

Ramps generate tonal entries 50, 100, 200, 300, 400, 500, 600, 700, 800, and 900 under a target group. The example emits color.brand-50 through color.brand-900; 500 is the seed color.

Utility declarations opt token or scale groups into atomic class generation. Each utility entry maps a class prefix to one or more CSS properties. The CLI command tovai utilities FILE.tovai emits deterministic classes such as .p-md, .mt-lg, and .text-brand.

Theme declarations override existing token or scale entries. Every theme must define the same token set as the base document, including tokens generated by ramps. Missing theme tokens are validation errors. Overrides compile to [data-theme=<name>] blocks.

Recipes compile to classes. Declaration values may contain literals and token references. References must resolve to an existing token or scale entry and emit as CSS var(...) calls.

variant <group> { <name> { ... } } blocks define recipe variants. Variant groups are used for authoring organization; emitted selectors use the recipe and variant names, such as .button--sm and .button--lg.

Interaction state blocks named hover, focus, active, or disabled emit pseudo-class selectors such as .button:hover and .button:disabled. The equivalent explicit form state hover { ... } is also accepted.

layer declares deterministic CSS cascade-layer ordering for generated build output. When present, tovai build emits an @layer prelude and wraps token, theme, and recipe sections in @layer tokens, @layer themes, and @layer recipes blocks. Without a layer declaration, CSS output remains unlayered.

tokens emits deterministic JSON with a flat base token map and a flat map for each theme. References are resolved for JSON consumers; CSS output keeps references as custom properties.

dtcg emits deterministic W3C Design Tokens (DTCG) JSON with nested token groups. Tokens include $value and $type; theme values are emitted under a top-level themes object when themes are present.

utilities emits only configured utility groups.