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.
- JSONC tokens — comments and trailing commas are accepted.
- Built-in inheritance — extend
dark,light, orhigh_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.
gem install auvaAuva requires Ruby 3.2 or newer.
Create tokens.jsonc:
Open the native preview:
auva tokens.jsoncCheck contrast and fail when any required pair misses WCAG AA:
auva tokens.jsonc --check --strict| 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.
Export every preview sheet:
auva tokens.jsonc --export public/themeThe 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 |
require "auva"
theme = Auva.load("tokens.jsonc")
results = Auva.contrast(theme)
Auva::Preview.render_all(theme, "public/theme")bundle install
bundle exec rake
bundle exec rbs -I sig validate
gem build --strict auva.gemspecBug reports and pull requests are welcome on GitHub.
Auva is available under the MIT License.
{ // Start from a complete Zaniah theme. "extends": "light", "colors": { "accent": "#245b9b" }, "syntax": { "keyword": "#7c3aed", "string": "#15803d" }, "motion": { "reduced": true } }