auva 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2d5a58d9d63594cd4bec804137ae667e67a6b771e4d6dd99b5df344841c05c76
-  data.tar.gz: f7bfc056380e510ea32ccd873e588ee13e7d03f42557943c7e0ecaf511aea799
+  metadata.gz: caeb5bc6900e617822665366a145c8e931b752612eb2617a5b4521ca7fc91768
+  data.tar.gz: 8cb0e0402e3582f7c9eed983b58eaa04b77c3b79c3744909af97dc82d52cc416
 SHA512:
-  metadata.gz: 62b6e3da3cbc77c36eb6ea3d1eea4a5d025acbd5da19a54a541234f5244efd9875a4f5b60354de8c1205cd45b7e8911c611c3d1c070bedae2906b394f84e9a27
-  data.tar.gz: f75f1723c4280fdbf1ddf5b9dedecc8cbb28b0e6f5421e0ac888ccd0b4f6d499430be29b5524a6c1c2671c092773a6c16c93cf3867c408759acb665ba49c6bc6
+  metadata.gz: dbdd43f740b4ff501864eb89014fc0acfc5a1347918aaf26839d781da470ff0d96b6ea8c67d5b1e2df6f49b53f9effc55a35dec4b521dc0d187cbb1650755b83
+  data.tar.gz: c71cddfd5bf23af0f365195cc0ac7b73ea6d6bfed75fcfe65a37a0c01a8db19ab1655100b2a5bda30418e15d1dd4bd62f322c439cf6d95a0de429d603bf3dae4

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.2.0 — 2026-09-25
+
+- Validate CodeEditor syntax tokens against Zaniah theme scopes.
+
 ## 0.1.0 - 2026-09-20
 
 - Initial release.

data/README.md

@@ -1,38 +1,145 @@
-# Auva
+<h1 align="center">Auva</h1>
 
-JSONC design-token loading and deterministic theme sheets for Zaniah. Auva
-validates token names from Zaniah's own `members`, reports source lines, and
-checks WCAG contrast ratios.
+<p align="center">
+  <strong>JSONC design-token loader and deterministic theme sheets for Zaniah.</strong>
+</p>
+
+<p align="center">
+  <a href="https://rubygems.org/gems/auva"><img src="https://img.shields.io/gem/v/auva?style=flat-square" alt="Gem version"></a>
+  <a href="https://rubygems.org/gems/auva"><img src="https://img.shields.io/gem/dt/auva?style=flat-square" alt="Gem downloads"></a>
+  <a href="https://github.com/noxdea/auva/actions/workflows/main.yml"><img src="https://github.com/noxdea/auva/actions/workflows/main.yml/badge.svg" alt="CI"></a>
+  <img src="https://img.shields.io/badge/Ruby-%3E%3D%203.2-CC342D?style=flat-square" alt="Ruby 3.2 or newer">
+  <a href="LICENSE.txt"><img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="MIT license"></a>
+</p>
+
+<p align="center">
+  <a href="#features">Features</a> ·
+  <a href="#installation">Installation</a> ·
+  <a href="#quick-start">Quick start</a> ·
+  <a href="#token-format">Token format</a> ·
+  <a href="#cli">CLI</a> ·
+  <a href="#ruby-api">Ruby API</a>
+</p>
+
+---
+
+Auva is a JSONC design-token loader and deterministic theme-sheet generator
+for [Zaniah](https://github.com/noxdea/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
 
-```sh
+```bash
 gem install auva
 ```
 
-## Usage
+Auva requires Ruby 3.2 or newer.
+
+## Quick start
+
+Create `tokens.jsonc`:
+
+```jsonc
+{
+  // Start from a complete Zaniah theme.
+  "extends": "light",
+  "colors": {
+    "accent": "#245b9b"
+  },
+  "syntax": {
+    "keyword": "#7c3aed",
+    "string": "#15803d"
+  },
+  "motion": {
+    "reduced": true
+  }
+}
+```
+
+Open the native preview:
+
+```bash
+auva tokens.jsonc
+```
+
+Check contrast and fail when any required pair misses WCAG AA:
 
-```sh
+```bash
 auva tokens.jsonc --check --strict
-auva --builtin dark --export public/theme
 ```
 
-The export directory contains deterministic `colors.png`, `typography.png`,
-`spacing.png`, `radii.png`, `shadows.png`, `motion.png`, `buttons.png`, and
-`components.png` sheets. Library
-consumers can load a theme with `Auva.load("tokens.jsonc")`.
+## 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:
+
+```bash
+auva tokens.jsonc --export public/theme
+```
 
-Supported token categories are `extends`, `colors`, `typography`, `spacing`,
-`radii`, `shadows`, and `motion`; unknown names fail with a line number.
+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
+
+```ruby
+require "auva"
+
+theme = Auva.load("tokens.jsonc")
+results = Auva.contrast(theme)
+Auva::Preview.render_all(theme, "public/theme")
+```
 
 ## Development
 
-Run `rake spec` and `gem build --strict auva.gemspec`.
+```bash
+bundle install
+bundle exec rake
+bundle exec rbs -I sig validate
+gem build --strict auva.gemspec
+```
 
 ## Contributing
 
-Bug reports and pull requests are welcome at https://github.com/noxdea/auva.
+Bug reports and pull requests are welcome on
+[GitHub](https://github.com/noxdea/auva).
 
 ## License
 
-MIT.
+Auva is available under the [MIT License](LICENSE.txt).

data/index.html

@@ -0,0 +1,133 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta name="theme-color" content="#080c0b">
+  <meta name="description" content="Auva is a JSONC design-token loader and deterministic theme-sheet generator for Zaniah.">
+  <link rel="canonical" href="https://noxdea.github.io/auva/">
+  <title>Auva — Design tokens for Zaniah</title>
+  <style>
+    :root { color-scheme: dark; --bg:#080c0b; --panel:#101715; --line:#293a34; --text:#edf2ef; --muted:#9faea8; --accent:#83b79f; --ink:#08120d; }
+    * { box-sizing: border-box; }
+    html { background: var(--bg); }
+    body { margin: 0; min-width: 320px; color: var(--text); background: var(--bg); font: 16px/1.62 "Helvetica Neue", Helvetica, Arial, sans-serif; }
+    a { color: inherit; }
+    .skip { position: absolute; top: -5rem; left: 1rem; z-index: 20; padding: .65rem .9rem; color: var(--ink); background: var(--accent); }
+    .skip:focus { top: 1rem; }
+    .wrap { width: min(1180px, calc(100% - 40px)); margin: 0 auto; }
+    header { display: flex; align-items: center; justify-content: space-between; min-height: 76px; border-bottom: 1px solid var(--line); }
+    .brand { font: 700 1.15rem/1 "Helvetica Neue", Helvetica, sans-serif; text-decoration: none; }
+    nav { display: flex; gap: 1.4rem; color: var(--muted); font-size: .9rem; }
+    nav a { text-decoration: none; }
+    nav a:hover { color: var(--text); }
+    :focus-visible { outline: 3px solid var(--accent); outline-offset: 4px; }
+    .hero { display: grid; grid-template-columns: minmax(0, 1fr) minmax(520px, 1fr); gap: clamp(3rem, 7vw, 7rem); align-items: center; min-height: 700px; padding: 90px 0; }
+    .context { margin: 0 0 1.2rem; color: var(--accent); font-size: .95rem; }
+    h1, h2 { margin: 0; font-family: "Helvetica Neue", Helvetica, sans-serif; font-weight: 700; text-wrap: balance; }
+    h1 { max-width: 11ch; font-size: clamp(3.4rem, 5.7vw, 5.7rem); line-height: .94; }
+    h2 { font-size: clamp(2rem, 4vw, 3.2rem); line-height: 1.05; }
+    p { text-wrap: pretty; }
+    .lede { max-width: 54ch; margin: 1.6rem 0 0; color: var(--muted); font-size: 1.08rem; }
+    .actions { display: flex; flex-wrap: wrap; gap: .8rem; margin-top: 2rem; }
+    .button { display: inline-flex; align-items: center; min-height: 44px; padding: .65rem 1rem; border: 1px solid var(--line); text-decoration: none; }
+    .button.primary { border-color: var(--accent); color: var(--ink); background: var(--accent); font-weight: 700; }
+    .token-lab { display: grid; grid-template-columns: 1fr 1fr; border: 1px solid var(--line); background: var(--panel); }
+    .source { padding: 1.2rem; border-right: 1px solid var(--line); color: var(--muted); font: .72rem/1.75 ui-monospace, "SFMono-Regular", Consolas, monospace; }
+    .source .key { color: var(--text); }
+    .source .value { color: var(--accent); }
+    .source .comment { color: #718079; }
+    .inspect { padding: 1.2rem; }
+    .inspect h3 { margin: 0 0 1rem; font-size: .85rem; font-weight: 600; }
+    .swatch { display: grid; grid-template-columns: 42px 1fr auto; gap: .75rem; align-items: center; padding: .7rem 0; border-top: 1px solid var(--line); font-size: .75rem; font-variant-numeric: tabular-nums; }
+    .chip { width: 42px; height: 28px; border: 1px solid #53645d; background: var(--accent); }
+    .chip.surface { background: #19211e; } .chip.text { background: #edf2ef; } .chip.muted { background: #9faea8; }
+    .swatch span:last-child { color: var(--muted); }
+    .contrast { margin-top: 1rem; padding-top: .8rem; border-top: 1px solid var(--line); }
+    .contrast-row { display: flex; justify-content: space-between; gap: 1rem; padding: .35rem 0; color: var(--muted); font-size: .72rem; font-variant-numeric: tabular-nums; }
+    .contrast-row b { color: var(--accent); }
+    .section { display: grid; grid-template-columns: .72fr 1.28fr; gap: clamp(2rem, 7vw, 7rem); padding: 88px 0; border-top: 1px solid var(--line); }
+    .section-copy { max-width: 38ch; color: var(--muted); }
+    .rows { border-top: 1px solid var(--line); }
+    .row { display: grid; grid-template-columns: 150px 1fr; gap: 1.5rem; padding: 1.35rem 0; border-bottom: 1px solid var(--line); }
+    .row strong { color: var(--accent); font-weight: 600; }
+    .row p { margin: 0; color: var(--muted); }
+    .categories { display: grid; grid-template-columns: repeat(2, 1fr); border-top: 1px solid var(--line); }
+    .category { display: grid; grid-template-columns: 24px 1fr; gap: .8rem; padding: 1rem 0; border-bottom: 1px solid var(--line); color: var(--muted); }
+    .category:nth-child(odd) { padding-right: 1rem; }
+    .category:nth-child(even) { padding-left: 1rem; border-left: 1px solid var(--line); }
+    .category i { width: 24px; height: 24px; border: 1px solid var(--accent); }
+    .category b { display: block; color: var(--text); font-weight: 600; }
+    pre.command { margin: 0; overflow-x: auto; padding: 1.2rem; border: 1px solid var(--line); color: var(--accent); background: var(--panel); font: .9rem/1.7 ui-monospace, "SFMono-Regular", Consolas, monospace; }
+    footer { display: flex; justify-content: space-between; gap: 1rem; padding: 30px 0 46px; border-top: 1px solid var(--line); color: var(--muted); font-size: .85rem; }
+    @media (max-width: 900px) {
+      .hero, .section { grid-template-columns: 1fr; }
+      .hero { min-height: auto; padding: 72px 0; }
+      .token-lab { max-width: 680px; }
+    }
+    @media (max-width: 580px) {
+      .wrap { width: min(100% - 24px, 1180px); }
+      nav a:not(:last-child) { display: none; }
+      .token-lab { grid-template-columns: 1fr; }
+      .source { border-right: 0; border-bottom: 1px solid var(--line); }
+      .row, .categories { grid-template-columns: 1fr; }
+      .row { gap: .35rem; }
+      .category:nth-child(even) { padding-left: 0; border-left: 0; }
+      footer { flex-direction: column; }
+    }
+  </style>
+</head>
+<body>
+  <a class="skip" href="#content">Skip to content</a>
+  <header class="wrap">
+    <a class="brand" href="./">Auva</a>
+    <nav aria-label="Primary navigation">
+      <a href="#contract">Contract</a>
+      <a href="#system">System</a>
+      <a href="https://github.com/noxdea/auva">Source</a>
+    </nav>
+  </header>
+  <main id="content">
+    <section class="hero wrap">
+      <div>
+        <p class="context">Design tokens for Zaniah</p>
+        <h1>Make the theme inspectable before it reaches the interface.</h1>
+        <p class="lede">Auva loads JSONC into a validated Zaniah theme, checks essential contrast pairs, and exports deterministic sheets for every token category.</p>
+        <div class="actions"><a class="button primary" href="https://rubygems.org/gems/auva">Install the gem</a><a class="button" href="https://github.com/noxdea/auva#quick-start">Read the guide</a></div>
+      </div>
+      <div class="token-lab" aria-label="Auva token validation example">
+        <pre class="source"><code><span class="comment">// tokens.jsonc</span>
+{
+  <span class="key">"extends"</span>: <span class="value">"dark"</span>,
+  <span class="key">"colors"</span>: {
+    <span class="key">"accent"</span>: <span class="value">"#83b79f"</span>,
+    <span class="key">"background"</span>: <span class="value">"#080c0b"</span>
+  },
+  <span class="key">"motion"</span>: {
+    <span class="key">"reduced"</span>: <span class="value">true</span>
+  }
+}</code></pre>
+        <div class="inspect"><h3>Resolved theme</h3><div class="swatch"><i class="chip" aria-hidden="true">&nbsp;</i><span>accent</span><span>#83b79f</span></div><div class="swatch"><i class="chip surface" aria-hidden="true">&nbsp;</i><span>surface</span><span>#19211e</span></div><div class="swatch"><i class="chip text" aria-hidden="true">&nbsp;</i><span>text</span><span>#edf2ef</span></div><div class="swatch"><i class="chip muted" aria-hidden="true">&nbsp;</i><span>text_muted</span><span>#9faea8</span></div><div class="contrast"><div class="contrast-row"><span>text / background</span><b>AAA</b></div><div class="contrast-row"><span>accent_text / accent</span><b>AA</b></div></div></div>
+      </div>
+    </section>
+    <section class="section wrap" id="contract">
+      <div><h2>Bad tokens fail where they are written.</h2><p class="section-copy">The schema comes from Zaniah's theme members, so validation tracks the real interface contract instead of a parallel copy.</p></div>
+      <div class="rows">
+        <div class="row"><strong>Parse</strong><p>Accept comments and trailing commas while retaining source ranges.</p></div>
+        <div class="row"><strong>Validate</strong><p>Reject unknown categories, members, types, colors, and shadow fields with a line and token path.</p></div>
+        <div class="row"><strong>Check</strong><p>Measure WCAG AA and AAA contrast for the color pairs users depend on.</p></div>
+      </div>
+    </section>
+    <section class="section wrap" id="system">
+      <div><h2>Inspect the whole system, not a single swatch.</h2></div>
+      <div class="categories"><div class="category"><i aria-hidden="true">&nbsp;</i><span><b>Colors</b>Semantic palette and contrast</span></div><div class="category"><i aria-hidden="true">&nbsp;</i><span><b>Typography</b>Families and type scale</span></div><div class="category"><i aria-hidden="true">&nbsp;</i><span><b>Spacing</b>Numeric rhythm</span></div><div class="category"><i aria-hidden="true">&nbsp;</i><span><b>Radii</b>Named corner system</span></div><div class="category"><i aria-hidden="true">&nbsp;</i><span><b>Shadows</b>Validated shadow members</span></div><div class="category"><i aria-hidden="true">&nbsp;</i><span><b>Motion</b>Durations, easing, reduction</span></div><div class="category"><i aria-hidden="true">&nbsp;</i><span><b>Buttons</b>Interactive states</span></div><div class="category"><i aria-hidden="true">&nbsp;</i><span><b>Components</b>Full UI gallery</span></div></div>
+    </section>
+    <section class="section wrap">
+      <div><h2>Load and check a theme.</h2></div>
+      <pre class="command"><code>gem install auva
+auva tokens.jsonc --check --strict</code></pre>
+    </section>
+  </main>
+  <footer class="wrap"><span>Auva 0.1.0</span><span>Ruby 3.2+ · MIT</span></footer>
+</body>
+</html>

data/lib/auva/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Auva
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/auva.rb

@@ -72,20 +72,22 @@ module Auva
 
     def call
       validate_top_level
-      @base.with(
+      overrides = {
         colors: build_colors,
         typography: build_data(:typography),
         motion: build_data(:motion),
         spacing: build_hash(:spacing, integer_keys: true),
         radii: build_hash(:radii, symbol_keys: true),
         shadows: build_shadows
-      )
+      }
+      overrides[:syntax] = build_syntax if @tokens.key?("syntax")
+      @base.with(**overrides)
     end
 
     private
 
     def validate_top_level
-      unknown = @tokens.keys.map(&:to_s) - %w[extends colors typography spacing radii shadows motion]
+      unknown = @tokens.keys.map(&:to_s) - %w[extends colors typography spacing radii shadows motion syntax]
       raise_token("unknown token category: #{unknown.join(", ")}", [unknown.first]) unless unknown.empty?
       base = @tokens["extends"]
       unless base.nil? || %w[dark light high_contrast high-contrast none].include?(base)
@@ -101,6 +103,15 @@ module Auva
       @base.colors.with(**overrides)
     end
 
+    def build_syntax
+      raise_token("syntax tokens require a Zaniah theme with syntax support", ["syntax"]) unless @base.respond_to?(:syntax)
+      values = @tokens.fetch("syntax", {})
+      ensure_hash(values, ["syntax"])
+      validate_keys(values, @base.syntax.members.map(&:to_s), ["syntax"])
+      overrides = values.to_h { |key, value| [key.to_sym, parse_color(value, ["syntax", key])] }
+      @base.syntax.with(**overrides)
+    end
+
     def build_data(category)
       values = @tokens.fetch(category.to_s, {})
       ensure_hash(values, [category.to_s])

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: auva
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Yudai Takada
@@ -43,20 +43,20 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.6.0
+        version: 0.10.0
     - - "<"
       - !ruby/object:Gem::Version
-        version: '0.7'
+        version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.6.0
+        version: 0.10.0
     - - "<"
       - !ruby/object:Gem::Version
-        version: '0.7'
+        version: '1.0'
 description: Load JSONC design tokens into Zaniah themes and check WCAG contrast ratios.
 email:
 - t.yudai92@gmail.com
@@ -70,6 +70,7 @@ files:
 - README.md
 - Rakefile
 - exe/auva
+- index.html
 - lib/auva.rb
 - lib/auva/version.rb
 - sig/auva.rbs
@@ -94,7 +95,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Design token loader and preview utilities for Zaniah
 test_files: []