Auva

JSONC design-token loader and deterministic theme sheets for Zaniah.

Features · Installation · Quick start · Token format · CLI · Ruby API

Auva is a JSONC design-token loader and deterministic theme-sheet generator for Zaniah. It validates tokens against Zaniah's own theme members, reports source locations, and checks WCAG contrast.

Features

JSONC tokens — comments and trailing commas are accepted.
Built-in inheritance — extend dark, light, or high_contrast.
Strict validation — unknown categories, tokens, and values fail with a source line and path.
WCAG checks — report AA and AAA contrast for essential color pairs.
Native preview — inspect colors, typography, spacing, radii, shadows, motion, buttons, and components.
Live reload — update the preview as a token file changes.
Deterministic sheets — export all eight preview categories as PNG files.

Installation

gem install auva

Auva requires Ruby 3.2 or newer.

Quick start

Create tokens.jsonc:

{
  // Start from a complete Zaniah theme.
  "extends": "light",
  "colors": {
    "accent": "#245b9b"
  },
  "syntax": {
    "keyword": "#7c3aed",
    "string": "#15803d"
  },
  "motion": {
    "reduced": true
  }
}

Open the native preview:

auva tokens.jsonc

Check contrast and fail when any required pair misses WCAG AA:

auva tokens.jsonc --check --strict

Token format

Category	Description
`extends`	Base theme: `dark`, `light`, `high_contrast`, or `none`
`colors`	Zaniah color members such as `accent` and `background`
`syntax`	Code-editor colors: `keyword`, `string`, `comment`, `number`, `function`, `type`, `constant`, `punctuation`, `operator`, `variable`, `text`
`typography`	Font families, sizes, and related type tokens
`spacing`	Numeric spacing scale entries
`radii`	Named border radii
`shadows`	Named shadows with validated members
`motion`	Durations, easing values, and reduced-motion preference

Unspecified values remain inherited from the selected base theme. syntax requires a Zaniah theme with Theme::Syntax support; token files without it remain compatible with older Zaniah versions.

CLI

Export every preview sheet:

auva tokens.jsonc --export public/theme

The directory contains colors.png, typography.png, spacing.png, radii.png, shadows.png, motion.png, buttons.png, and components.png.

Option	Description
`--builtin NAME`	Use `dark`, `light`, or `high_contrast` without a token file
`--themes NAMES`	Preview or export comma-separated built-in themes
`--check`	Print contrast ratios
`--strict`	Exit with failure when WCAG AA is not met
`--export DIR`	Write deterministic PNG sheets
`--watch`	Watch a token file outside the native preview
`--no-watch`	Disable watching

Ruby API

require "auva"

theme = Auva.load("tokens.jsonc")
results = Auva.contrast(theme)
Auva::Preview.render_all(theme, "public/theme")

Development

bundle install
bundle exec rake
bundle exec rbs -I sig validate
gem build --strict auva.gemspec

Contributing

Bug reports and pull requests are welcome on GitHub.

License

Auva is available under the MIT License.

auva

Runtime