ui_guardrails 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 200bad03eb94e193c93e5965c52743f8bc9c4d232003149d482cf8b4bc72d77c
-  data.tar.gz: cd365fa2244f58b1c294f317119be08e03da868f050cc1aae268d6ff524237a0
+  metadata.gz: 9f34f9ff613f4b10edd128972a3ee8b268e82fee79abc499d7554d48bf834eec
+  data.tar.gz: 937199143fb681851d6493dc666ce9a381d4db83b247059e00e9b0dd91b8a901
 SHA512:
-  metadata.gz: 1c23e135b24dcbf76c3d98983ee339a22800fdf4a40fbc4b13dcbebaecfbf8b7160a5aa4472f01440fb20bac8bf6585ada295207189aae11f8809f894ef70003
-  data.tar.gz: 56572b2788586158520982bf9d3d0f18e4920136aab255dec5ef88b08d7c7ef0347ba653e71564f0b439c2c94db53c7eee30a241f9a5c516fc72722900769074
+  metadata.gz: 8e6d87b9e1bac27c0f79f941343855806c0fb3a3c55b0191cfeb1e184a0b4b5cc6b09eb88ce4df2512ac646c1572f528da269dedacc56fd269f8a4b3ac7630eb
+  data.tar.gz: d50217306f64e883988ad9184adde4d02e274fc8262560aeab3b8a0c9eecd573bae847006c0a3383222020ab3d9281ba96d1720ea9019f17c3491bf21fcf08e1

data/README.md

@@ -1,10 +1,10 @@
-# Guardrails
+# UI-Guardrails
 
 A Rails toolset that prevents UI drift in AI-assisted applications. Static audits over your views, components, stylesheets, JS controllers, and tokens — surfacing the kinds of inconsistencies that compound silently as an AI assistant ships code faster than design-system discipline can keep up.
 
 Built and maintained by [Meticulous](https://meticulous.com).
 
-**Current release:** 1.0.0 — V0 + V1 + V2 complete, published on [RubyGems.org as `ui_guardrails`](https://rubygems.org/gems/ui_guardrails). The Ruby module stays `Guardrails` (so `require "guardrails"` is unchanged) — only the gem package name on rubygems carries the `ui_` prefix, to clear RubyGems' similarity rule against the unrelated [`guard-rails`](https://rubygems.org/gems/guard-rails) gem. See [`doc/ROADMAP.md`](doc/ROADMAP.md) for status, [`CHANGELOG.md`](CHANGELOG.md) for the full naming rationale.
+**Current release:** 1.2.0 — V0 + V1 + V2 complete, published on [RubyGems.org as `ui_guardrails`](https://rubygems.org/gems/ui_guardrails). The Ruby module stays `Guardrails` (so `require "guardrails"` is unchanged) — only the gem package name on rubygems carries the `ui_` prefix, to clear RubyGems' similarity rule against the unrelated [`guard-rails`](https://rubygems.org/gems/guard-rails) gem. See [`doc/ROADMAP.md`](doc/ROADMAP.md) for status, [`CHANGELOG.md`](CHANGELOG.md) for the full naming rationale.
 
 ---
 

data/doc/RESEARCH-visual-diff.md

@@ -0,0 +1,226 @@
+# Visual-diff integration — research memo
+
+> Status: research, not implementation. Closes the V2 visual-diff item's "evaluate a stable visual-regression target" prerequisite before any code lands.
+>
+> Last updated: 2026-05-10
+
+## Executive summary
+
+**Recommendation: ship a `Guardrails::VisualDiff` parser that consumes screenshot-diff tool output, the same way `Guardrails::A11yDeep` consumes axe-core JSON.** Don't bundle Chromium / Playwright / Capybara as runtime deps — that was the constraint that originally parked this item, and it hasn't changed.
+
+The cleanest external producers to support, in priority order:
+
+1. **`snap_diff-capybara`** (formerly `capybara-screenshot-diff`) — the Rails-native default. Active gem (1.12.0 released April 2026), commits baselines to git, no cloud dep. Highest fit-for-purpose.
+2. **BackstopJS** — fully OSS, clean JSON output. Worth a second adapter for non-Rails-monolith projects (the Avo dogfood pattern).
+3. **Percy / Chromatic** — SaaS, vendor-locked. Defer until a user actually asks; webhook ingestion is the integration shape if they do.
+
+The talk narrative writes itself: **static analysis catches the source, visual diff catches what the rendered DOM does next.** Pair this with `ClassItis` — AI-generated 8-class soup looks plausible in the source but pixel-shifts the baseline once a single utility is wrong.
+
+---
+
+## The constraint that shaped A11yDeep applies here too
+
+When deferring deep a11y in the original roadmap, the call was:
+
+> axe-core wrapper with `--deep` mode NOT shipped — would require Capybara + headless Chrome runtime deps.
+
+Then in 0.6.0 we shipped `A11yDeep` as a **parser** for axe JSON output: zero new runtime deps, user runs axe however they already do, Guardrails provides the merge + report + exit-code contract. The same calculus applies to visual diff. Bundling Playwright/Chromium would balloon `bundle install` for users who don't run system tests; bundling Selenium would tie us to Ruby browser-driver decay. The right move is to consume what existing tools emit.
+
+**Acceptance criteria for any candidate tool**, in priority order:
+
+1. **Emits a machine-readable diff summary** — JSON, JUnit XML, or a parseable HTML/filesystem layout. We need per-scenario: name, baseline path, current path, diff path (if any), mismatch % or pass/fail, optionally the URL/component selector.
+2. **Runs without Guardrails being involved.** The user's existing test toolchain runs the tool; we ingest the output. No shelling out to `npx`, no requiring the tool be present at audit time.
+3. **OSS-friendly licensing** *or* a stable public API for SaaS tools.
+4. **Active maintenance.** Sub-12-month release cadence and >50 GitHub stars as a rough proxy.
+
+---
+
+## Per-tool brief
+
+### snap_diff-capybara (Rails-native) — **PRIMARY RECOMMENDATION**
+
+- **What it is:** Ruby gem (formerly `capybara-screenshot-diff`, now maintained at `github.com/snap-diff/snap_diff-capybara` by `donv` and `jetthoughts`). Latest 1.12.0, April 2026. MIT-licensed. ~770k total downloads.
+- **How it works:** `screenshot "name"` inside Capybara system tests. Baselines live at `doc/screenshots/` and are **committed to git** — UI changes get reviewed in PR like code. No external auth, no cloud.
+- **Diff artifacts:**
+  - `*.png` baseline
+  - `*.diff.png` (changed pixels highlighted red)
+  - `*.heatmap.diff.png` (pixel-variance density)
+  - **`snap_diff_report.html`** — interactive multi-view dashboard
+- **CI flow:** Tests fail on baseline mismatch. There's a reusable GitHub Actions workflow that uploads the HTML report and posts PR comments. Ships its own baseline-update flow.
+- **Runtime:** Ruby 3.2+, any Capybara-compatible driver (Selenium / Playwright / Cuprite). libvips 8.9+ for fast comparisons, falls back to ChunkyPNG.
+- **For Guardrails to consume:** the HTML report has a fixed structure, but the gem doesn't (yet) emit a top-level JSON summary. **Either:**
+  - **(a)** ask upstream for a `snap_diff_report.json` companion to the HTML — small ask, this is the maintained gem
+  - **(b)** walk `doc/screenshots/` ourselves: pair `name.png` with `name.diff.png`, treat presence of the diff file as a failing finding
+- **Fit:** ★★★★★. Same ecosystem (Ruby/Rails/Capybara), no new deps for users already running system tests, baselines-in-git matches the Guardrails ethos of "the source is the source of truth."
+
+### BackstopJS
+
+- **What it is:** Node CLI, MIT-licensed, actively maintained, the dominant OSS visual-regression tool outside the Storybook ecosystem.
+- **How it works:** `backstop init`, `backstop test`, `backstop approve`. Configured via `backstop.json` (scenarios = URL × viewport × selector). Headless Chrome via Puppeteer or Firefox/WebKit via Playwright. All artifacts local under `backstop_data/`.
+- **Output:** HTML interactive report, **JSON report**, JUnit XML, CLI text. Exit 0/1.
+- **For Guardrails to consume:** The JSON report already exists and is the canonical machine-readable output. Per-scenario: name, label, mismatch percentage, pass/fail, paths to reference + test + diff images.
+- **Fit:** ★★★★☆. Native machine-readable output, no SaaS dep, but Node-only — Ruby/Rails shops would have a parallel toolchain. Justifiable for the "Rails frontend that already runs JS tooling" subset (any non-trivial Rails app).
+
+### Playwright `toHaveScreenshot` / `toMatchSnapshot`
+
+- **What it is:** Built-in Playwright assertion. The team that maintains Playwright also maintains Chromatic (Microsoft → Storybook acquisition), so it's becoming the de facto cross-tool snapshot mechanism.
+- **How it works:** `await expect(page).toHaveScreenshot()`. Stores baselines in `__screenshots__/`. Updates via `--update-snapshots`.
+- **Output:** JUnit / JSON via Playwright's reporter API; HTML report; per-test pass/fail in CI.
+- **For Guardrails to consume:** Playwright JSON reporter emits a structured test-result document; each failure includes `attachments` with the diff image path. Parseable, but the schema is "Playwright test results" not "visual diff" — we'd be extracting the visual subset.
+- **Fit:** ★★★☆☆. Future-proof and increasingly canonical, but the integration is heavier (have to filter Playwright results for screenshot-specific failures). Worth supporting in v2 of the adapter.
+
+### Percy (BrowserStack)
+
+- **What it is:** SaaS, all builds go through Percy's cloud. Originally a standalone product, BrowserStack-acquired in 2020.
+- **Ruby story:** `percy-capybara` gem exists. Latest release v5.0.0 — July 2021 — i.e. **maintenance-stale**. 4+ years without a meaningful release; the active surface is the JS SDKs.
+- **Output:** Dashboard URL + per-build webhook. No local artifacts beyond the snapshot upload.
+- **Pricing:** Pricing page is gated behind BrowserStack's product navigation; no clear OSS-free tier surfaced via the public site. Assume paid-only for non-trial use.
+- **For Guardrails to consume:** `build-finished` webhook payload is the integration shape — but that requires a receiver, which Guardrails-the-gem isn't. Could ship a parser for the webhook JSON that users POST to their CI.
+- **Fit:** ★★☆☆☆. Stale Ruby SDK, vendor-locked, no clear OSS pricing. Defer until a user asks specifically.
+
+### Chromatic
+
+- **What it is:** SaaS, made by the Storybook team. The standard visual-regression for Storybook-based component libraries; expanded to Playwright + Cypress in 2024–25.
+- **Ruby story:** None. JS-ecosystem only. No Lookbook integration despite Lookbook being the Rails-shaped Storybook equivalent.
+- **Output:** Cloud dashboard, web API for build status, no local artifacts.
+- **Pricing:** Free tier (5,000 snapshots/month, Chrome-only) — generous. Paid starts at $179/mo. "Building in the open?" OSS plan available on application.
+- **Fit:** ★★☆☆☆ for Rails apps without Storybook. ★★★★☆ for ViewComponent shops who use Storybook for non-Rails components alongside. Pair-of-tools story is workable but indirect; Lookbook integration would be the missing link, and that's a Lookbook upstream ask, not a Guardrails one.
+
+### Honorable mentions
+
+- **Loki** — Storybook-only, narrow audience for Rails-flavored Guardrails. Skip.
+- **`reg-suit`** — Cloud or self-hosted, language-agnostic, JSON report. Reasonable BackstopJS-alternative; not common enough in Rails shops to justify a dedicated adapter at v1.
+
+---
+
+## Fit table
+
+| Tool | OSS | Rails-native | Machine-readable output | Cloud dep | Active | Fit score |
+|---|---|---|---|---|---|---|
+| snap_diff-capybara | ✅ MIT | ✅ Ruby gem | 🟡 HTML report (no JSON yet) | ❌ baselines in git | ✅ active | ★★★★★ |
+| BackstopJS | ✅ MIT | ❌ Node | ✅ JSON report | ❌ local FS | ✅ active | ★★★★☆ |
+| Playwright snapshots | ✅ Apache | ❌ Node | ✅ JSON via reporter | ❌ local FS | ✅ active | ★★★☆☆ |
+| Percy | 🔒 SaaS | 🟡 stale gem (2021) | ✅ webhook | ✅ required | 🟡 webhooks active, SDK stale | ★★☆☆☆ |
+| Chromatic | 🔒 SaaS | ❌ JS-only | ✅ API | ✅ required | ✅ active | ★★☆☆☆ |
+
+---
+
+## Proposed integration shape (mirrors A11yDeep)
+
+```
+lib/guardrails/visual_diff.rb           — parser + report
+lib/guardrails/visual_diff/snap_diff.rb — adapter for snap_diff-capybara
+lib/guardrails/visual_diff/backstop.rb  — adapter for BackstopJS JSON
+spec/guardrails/visual_diff_spec.rb
+spec/guardrails/visual_diff/snap_diff_spec.rb
+spec/guardrails/visual_diff/backstop_spec.rb
+```
+
+Normalized `Finding` shape (across both adapters):
+
+```ruby
+Finding = Struct.new(
+  :scenario,        # "homepage", "checkout_cart"
+  :viewport,        # "desktop"; nil if not applicable
+  :mismatch_ratio,  # Float 0.0..1.0 (or nil for snap_diff which is pass/fail)
+  :baseline_path,   # relative path on disk
+  :current_path,    # relative path on disk
+  :diff_path,       # relative path to .diff.png, nil if pass
+  :url,             # optional, BackstopJS scenarios have URLs
+  :selector,        # optional
+  keyword_init: true
+)
+```
+
+Rake task (mirrors `guardrails:a11y:deep`):
+
+```bash
+# Either auto-detect from `doc/screenshots/` (snap_diff convention) ...
+bundle exec rake guardrails:visual:deep
+
+# ... or point at an explicit producer:
+SNAP_DIFF_DIR=doc/screenshots bundle exec rake guardrails:visual:deep
+BACKSTOP_JSON=backstop_data/html_report/jsonReport.json bundle exec rake guardrails:visual:deep
+```
+
+Folded into `guardrails:audit` via `VISUAL_DIFF=...` env var, same shape as `AXE_JSON`.
+
+JSON output extends the existing audit payload:
+
+```json
+{
+  "summary": { "...": "...", "visual_diff": 3 },
+  "visual_diff": [
+    { "scenario": "checkout/cart", "mismatch_ratio": 0.082,
+      "baseline_path": "doc/screenshots/checkout_cart.png",
+      "diff_path": "doc/screenshots/checkout_cart.diff.png" }
+  ]
+}
+```
+
+Exit-code contract: a finding's `mismatch_ratio > threshold` (configurable, default `0.0` — any diff fails) bumps the audit to exit 1. For snap_diff (pass/fail), any failure is a fail.
+
+---
+
+## What this buys the gem (and the talk)
+
+1. **Closes V2.** Roadmap is fully shipped on the three core items.
+2. **Talk narrative is now four layers deep:**
+   - *Static AST drift* (V0): the source-level mistakes.
+   - *Structural drift* (V2 cross-codebase + class-itis): the patterns the source shouldn't have.
+   - *Runtime a11y drift* (V1.6 deep a11y): what the static checks can't see.
+   - *Visual drift* (V2 visual-diff): what the rendered DOM does next.
+
+   AI assistants fail at each layer differently. Each Guardrails detector maps to a specific failure mode.
+
+3. **Same install/run story as everything else.** No new install footprint. Users keep their preferred screenshot tool; Guardrails provides the unified report.
+
+---
+
+## Open decisions for the morning
+
+1. **Primary adapter: snap_diff or BackstopJS?**
+   - My read: snap_diff-capybara, since (a) Rails-native, (b) we'd be working with the maintainers of a small focused gem who'd likely accept a JSON-output PR upstream, and (c) baselines-in-git matches Guardrails' "source is canonical" ethos.
+   - The risk: snap_diff doesn't currently emit JSON, so v0.8.0 might need an upstream contribution. We could ship the filesystem-walking adapter first (look at `doc/screenshots/*.diff.png`) and contribute the JSON emitter separately.
+
+2. **Scope: ship one adapter or two?**
+   - One (snap_diff) keeps the PR small and proves the pattern.
+   - Two (snap_diff + BackstopJS) covers the Avo / non-Rails-monolith case from day one.
+   - I'd ship one and tag, then add BackstopJS in a follow-up if there's signal.
+
+3. **Threshold default: `0.0` (any diff fails) or something more lenient?**
+   - A11yDeep defaulted to "any non-nil impact fails". The visual-diff equivalent is "any pixel mismatch fails" — strict, but visual diff is opt-in (you set up baselines deliberately), so strict is the right default.
+   - Per-call override via `VISUAL_DIFF_THRESHOLD=0.01` env or `visual_diff.threshold` in `guardrails.yml`.
+
+4. **Where does this surface in the Lookbook panel?**
+   - `ComponentReport#for` could add `visual_diff: [...]` showing per-component baseline mismatches. Pulls together: "this component drifted statically (raw_color) AND visually (3% mismatch on the desktop viewport)."
+   - Probably out of scope for v0.8.0 — first land the audit/CI integration, layer Lookbook in v0.9.0.
+
+5. **Is this 0.8.0 or 1.0.0?**
+   - Argument for 0.8.0: matches the pattern of every other increment.
+   - Argument for 1.0.0: with this shipped, all three V0–V2 column-headers are done. We could draw the "ready for serious use" line here and tag a 1.0.0.
+   - My read: 0.8.0 for the visual-diff feature, then a separate 1.0.0 release after dogfooding the full V2 surface against Patchvault/Talos/Forem/Avo. The 0.2.x→0.7.x cadence already moved through dogfood-driven patches; another round before 1.0.0 fits.
+
+---
+
+## Out of scope
+
+- **Running the screenshot tool ourselves.** Not now, possibly not ever — the gem's ethos is parse-only.
+- **Hosted baseline storage.** Baselines stay in the user's repo (snap_diff convention) or wherever their existing tool puts them.
+- **Image-diff algorithm work.** Pixel comparison is a solved problem with multiple good libraries; we don't add value by reinventing it.
+- **Real-browser rendering.** Same as the headless Chrome reasoning in A11yDeep.
+
+---
+
+## What's needed to start
+
+If we go with snap_diff-capybara as the primary adapter:
+
+1. Decide if we file an upstream PR to add `snap_diff_report.json` emission, or build the filesystem-walking adapter first.
+2. Add `snap_diff-capybara` to `examples/demo/Gemfile` and seed a couple of system tests so the integration spec has something to verify against.
+3. Roughly 3 slices, mirroring the A11yDeep PR:
+   - Slice 1: `VisualDiff` parser + `Finding` struct + snap_diff adapter + spec
+   - Slice 2: rake task wiring (standalone + `guardrails:audit` fold-in) + JSON output extension
+   - Slice 3: docs (new `doc/VISUAL-DIFF.md` mirroring `doc/A11Y.md`) + ROADMAP + CHANGELOG → 0.8.0
+
+Estimated scope: a single PR, comparable to 0.6.0's `A11yDeep` (~17 specs, ~400 LOC). Could be shipped same day as kick-off if no upstream blocker.

data/lib/guardrails/a11y_audit.rb

@@ -3,6 +3,7 @@
 require "pathname"
 require "set"
 require_relative "erb_parser"
+require_relative "report/style"
 
 module Guardrails
   # Static a11y checks that don't require a browser — element-level rules
@@ -23,9 +24,17 @@ module Guardrails
 
     NON_INTERACTIVE_INPUT_TYPES = %w[hidden submit button reset image].freeze
 
-    def initialize(root:, output: $stdout)
+    SUGGESTION_FOR_RULE = {
+      "image_alt" => "add an alt attribute (or alt=\"\" if decorative)",
+      "button_name" => "add text, aria-label, or aria-labelledby",
+      "link_name" => "add link text, aria-label, or aria-labelledby",
+      "input_label" => "add aria-label, aria-labelledby, or a matching <label for=...>"
+    }.freeze
+
+    def initialize(root:, output: $stdout, style: nil)
       @root = Pathname(root)
       @output = output
+      @style = style || Report::Style.new(io: output)
     end
 
     def run
@@ -237,12 +246,19 @@ module Guardrails
     def print_report(findings)
       return if findings.empty?
 
-      @output.puts ""
       noun = findings.length == 1 ? "issue" : "issues"
-      @output.puts "Guardrails a11y: #{findings.length} static #{noun} found"
+      @output.puts ""
+      @output.puts @style.section_heading(:error, "a11y (#{findings.length} static #{noun})")
+      @output.puts "  Element-level a11y rules answerable from view source — missing alt text,"
+      @output.puts "  unnamed buttons, unlabeled inputs, link without name. Full WCAG coverage"
+      @output.puts "  needs runtime checks; layer axe-core via AXE_JSON= for that."
+
       findings.each do |f|
-        @output.puts "  [#{f.rule}] #{f.file}:#{f.line}:#{f.column}"
-        @output.puts "    #{f.snippet}"
+        @output.puts ""
+        @output.puts "  #{@style.severity(:error, "#{f.rule}: #{f.snippet.to_s[0, 60]}")}"
+        suggestion = SUGGESTION_FOR_RULE[f.rule.to_s]
+        @output.puts "    #{@style.suggestion(suggestion)}" if suggestion
+        @output.puts "    #{@style.location("#{f.file}:#{f.line}:#{f.column}")}"
       end
     end
   end

data/lib/guardrails/a11y_deep.rb

@@ -3,6 +3,7 @@
 require "json"
 require "pathname"
 require "set"
+require_relative "report/style"
 
 module Guardrails
   # Consumes axe-core JSON output and folds the findings into Guardrails'
@@ -37,10 +38,11 @@ module Guardrails
     # `failing_impacts:` if your rule pack emits custom severities.
     DEFAULT_FAILING_IMPACTS = %w[minor moderate serious critical].freeze
 
-    def initialize(input:, output: $stdout, failing_impacts: DEFAULT_FAILING_IMPACTS)
+    def initialize(input:, output: $stdout, failing_impacts: DEFAULT_FAILING_IMPACTS, style: nil)
       @input = input
       @output = output
       @failing_impacts = Set.new(failing_impacts.map(&:to_s))
+      @style = style || Report::Style.new(io: output)
     end
 
     def run
@@ -101,19 +103,38 @@ module Guardrails
       return if findings.empty?
 
       grouped = findings.group_by(&:url)
+      noun = findings.length == 1 ? "finding" : "findings"
+
       @output.puts ""
-      @output.puts "Guardrails a11y (deep): #{findings.length} finding#{'s' if findings.length != 1} from axe-core"
+      @output.puts @style.section_heading(
+        :error,
+        "a11y deep (#{findings.length} #{noun} from axe-core)"
+      )
+      @output.puts "  Runtime accessibility issues axe-core caught against your live pages."
+      @output.puts "  Each links to dequeuniversity.com for the canonical remediation."
 
       grouped.each do |url, page_findings|
         @output.puts ""
-        @output.puts "  #{url || '(no url)'}"
+        @output.puts "  #{@style.location(url || '(no url)')}"
         page_findings.each do |f|
-          impact_label = f.impact ? "[#{f.impact}]" : "[unknown]"
-          selector = f.selector ? " (#{f.selector})" : ""
-          @output.puts "    #{impact_label} #{f.rule} — #{f.description}#{selector}"
-          @output.puts "      #{f.help_url}" if f.help_url
+          severity = impact_to_severity(f.impact)
+          impact_label = f.impact ? f.impact.to_s : "unknown"
+          selector_part = f.selector ? " (#{f.selector})" : ""
+          @output.puts "    #{@style.severity(severity, "[#{impact_label}] #{f.rule}: #{f.description}#{selector_part}")}"
+          @output.puts "      #{@style.suggestion("see #{f.help_url}")}" if f.help_url
         end
       end
     end
+
+    # Map axe-core's impact levels onto the report's three severities
+    # so they color-code consistently with static a11y findings.
+    def impact_to_severity(impact)
+      case impact.to_s
+      when "critical", "serious" then :error
+      when "moderate" then :warning
+      when "minor" then :suggestion
+      else :warning
+      end
+    end
   end
 end

data/lib/guardrails/audit.rb

@@ -5,6 +5,7 @@ require "set"
 require "stringio"
 require "yaml"
 require_relative "erb_parser"
+require_relative "report/style"
 
 module Guardrails
   class Audit
@@ -69,13 +70,14 @@ module Guardrails
       flood-color lighting-color stop-color
     ].freeze
 
-    def initialize(root:, output: $stdout, suggest: false, format: :text, apply: false)
+    def initialize(root:, output: $stdout, suggest: false, format: :text, apply: false, style: nil)
       @root = Pathname(root)
       @output = output
       @suggest = suggest
       @format = format
       @apply = apply
       @config = load_audit_config
+      @style = style
     end
 
     def run
@@ -445,18 +447,170 @@ module Guardrails
 
     def print_text(violations)
       if violations.empty?
-        @output.puts "Guardrails audit: no violations found."
+        @output.puts ""
+        @output.puts "#{style.colorize("✓", :green)} Guardrails audit: no violations found."
         return
       end
 
-      noun = violations.length == 1 ? "violation" : "violations"
-      @output.puts "Guardrails audit: #{violations.length} #{noun} found"
+      # Group by type so each rule gets its own section with framing
+      # intro + tagged findings + inline suggestion arrows. The order
+      # mirrors what users care about: hex literals + inline styles +
+      # arbitrary Tailwind (real violations) before helper_recommended
+      # (a suggestion-shaped warning) and a11y (errors but grouped
+      # separately because A11yAudit owns them — the audit rake task
+      # threads them in via this same method).
+      type_order = %i[inline_style raw_color tailwind_arbitrary helper_recommended
+                      image_alt button_name link_name input_label]
+      by_type = violations.group_by(&:type)
+      ordered = type_order + (by_type.keys - type_order)
+
+      ordered.each do |type|
+        list = by_type[type] || []
+        next if list.empty?
+
+        print_violation_type(type, list)
+      end
+    end
+
+    SEVERITY_FOR_TYPE = {
+      inline_style: :warning,
+      raw_color: :error,
+      tailwind_arbitrary: :error,
+      helper_recommended: :warning,
+      image_alt: :error,
+      button_name: :error,
+      link_name: :error,
+      input_label: :error
+    }.freeze
+
+    FRAMING_FOR_TYPE = {
+      inline_style: "Inline style attributes bypass your design tokens. Extract these to a CSS class or component stylesheet that references defined tokens.",
+      raw_color: "Hex/rgb literals in color attributes bypass your design tokens. Run APPLY=1 to auto-fix where a token matches; SUGGEST=1 writes a markdown checklist.",
+      tailwind_arbitrary: "Arbitrary Tailwind values (bg-[#fa3] etc.) bypass your theme. Add the value to theme.colors / theme.fontSize and use the named utility, or APPLY=1 to auto-fix where a token matches.",
+      helper_recommended: "Literal <button>/<a> wrapping ERB output hides intent from static analysis and a11y tooling. Switch to tag.button / link_to / button_to so attributes flow through one place.",
+      image_alt: "Images need accessible alt text. Use alt=\"\" for purely decorative images.",
+      button_name: "Buttons need an accessible name — text content, aria-label, or aria-labelledby.",
+      link_name: "Links need an accessible name — text content, aria-label, or aria-labelledby.",
+      input_label: "Interactive inputs need a programmatic label — aria-label, aria-labelledby, or a matching <label for=...>."
+    }.freeze
+
+    AUTO_FIXABLE_TYPES = %i[raw_color tailwind_arbitrary].freeze
+
+    def print_violation_type(type, violations)
+      severity = SEVERITY_FOR_TYPE.fetch(type, :warning)
+      auto_fix_marker = AUTO_FIXABLE_TYPES.include?(type) ? ", auto-fix available" : ""
+
+      @output.puts ""
+      @output.puts style.section_heading(
+        severity,
+        "#{type} (#{violations.length} #{violations.length == 1 ? "finding" : "findings"}#{auto_fix_marker})"
+      )
+      framing = FRAMING_FOR_TYPE[type]
+      wrap_framing(framing).each { |line| @output.puts "  #{line}" } if framing
+
       violations.each do |v|
-        @output.puts "  [#{v.type}] #{v.file}:#{v.line}:#{v.column}"
-        @output.puts "    #{v.snippet}"
+        @output.puts ""
+        header = "#{type}: #{format_value(v)}"
+        @output.puts "  #{style.severity(severity, header)}"
+        suggestion = suggestion_for_violation(v)
+        @output.puts "    #{style.suggestion(suggestion)}" if suggestion
+        @output.puts "    #{style.location("#{v.file}:#{v.line}:#{v.column}")}"
+        @output.puts "    #{v.snippet}" if v.snippet
+      end
+    end
+
+    def format_value(violation)
+      case violation.type
+      when :raw_color, :tailwind_arbitrary
+        violation.value
+      when :inline_style
+        violation.value || "<inline style>"
+      else
+        violation.snippet.to_s[0, 60]
+      end
+    end
+
+    # Hard-wrap the framing-intro paragraph at ~72 chars so it doesn't
+    # run off the side of an 80-col terminal. Cheap word-wrap; nothing
+    # fancy needed for a 1-2 sentence paragraph.
+    def wrap_framing(text, width: 72)
+      lines = []
+      current = +""
+      text.split(/\s+/).each do |word|
+        if current.empty?
+          current << word
+        elsif current.length + 1 + word.length <= width
+          current << " " << word
+        else
+          lines << current
+          current = +word
+        end
+      end
+      lines << current unless current.empty?
+      lines
+    end
+
+    # Per-violation inline suggestion. For token-aware types
+    # (raw_color, tailwind_arbitrary), reuse load_tokens + TokenMatcher
+    # to surface exact matches inline. Anything more elaborate
+    # (near-match, replacement string, etc.) belongs in SUGGEST=1's
+    # markdown checklist.
+    def suggestion_for_violation(violation)
+      case violation.type
+      when :raw_color
+        matched_token_suggestion(violation, [:css_var])
+      when :tailwind_arbitrary
+        matched_token_suggestion(violation, [:tailwind]) ||
+          matched_token_suggestion(violation, [:css_var])
+      when :inline_style
+        "extract to a CSS class or component stylesheet"
+      when :helper_recommended
+        helper_recommended_suggestion(violation)
+      when :image_alt
+        "add an alt attribute (or alt=\"\" if decorative)"
+      when :button_name
+        "add text, aria-label, or aria-labelledby"
+      when :link_name
+        "add link text, aria-label, or aria-labelledby"
+      when :input_label
+        "add aria-label, aria-labelledby, or a matching <label for=...>"
+      end
+    end
+
+    def matched_token_suggestion(violation, allowed_syntaxes)
+      require_relative "token_matcher"
+      tokens = load_tokens.select { |t| allowed_syntaxes.include?(t.syntax) }
+      return nil if tokens.empty?
+
+      match = TokenMatcher.new(tokens).match(violation.value)
+      return nil unless match && match.kind == :exact
+
+      token = match.token
+      "replace with #{token_reference(token)} (exact match from #{token.file})"
+    end
+
+    def token_reference(token)
+      case token.syntax
+      when :css_var then "var(--#{token.name})"
+      when :scss_var then "$#{token.name}"
+      when :tailwind then token.name.to_s
+      else token.name.to_s
+      end
+    end
+
+    def helper_recommended_suggestion(violation)
+      tag = violation.snippet.to_s[/<(\w+)/, 1]
+      case tag
+      when "button" then "use tag.button(label, ...) or button_to(label, path)"
+      when "a" then "use link_to(label, path, ...)"
+      else "use the Rails helper for this element"
       end
     end
 
+    def style
+      @style ||= Report::Style.new(io: @output)
+    end
+
     def print_json(violations)
       require "json"
       payload = {

data/lib/guardrails/class_itis.rb

@@ -2,6 +2,7 @@
 
 require "pathname"
 require_relative "erb_parser"
+require_relative "report/style"
 
 module Guardrails
   # Finds repeating "class soup" — the same long class list applied to
@@ -52,12 +53,14 @@ module Guardrails
     def initialize(root:, output: $stdout,
                    min_classes: DEFAULT_MIN_CLASSES,
                    min_occurrences: DEFAULT_MIN_OCCURRENCES,
-                   max_occurrences_shown: DEFAULT_MAX_OCCURRENCES_SHOWN)
+                   max_occurrences_shown: DEFAULT_MAX_OCCURRENCES_SHOWN,
+                   style: nil)
       @root = Pathname(root)
       @output = output
       @min_classes = min_classes
       @min_occurrences = min_occurrences
       @max_occurrences_shown = max_occurrences_shown
+      @style = style || Report::Style.new(io: output)
     end
 
     def run
@@ -165,25 +168,49 @@ module Guardrails
 
       total_occurrences = clusters.sum(&:count)
       noun = clusters.length == 1 ? "cluster" : "clusters"
+
       @output.puts ""
-      @output.puts "Guardrails class-itis: #{clusters.length} repeating class #{noun} " \
-                   "(#{total_occurrences} occurrences; >= #{@min_classes} classes, >= #{@min_occurrences} occurrences)"
+      @output.puts @style.section_heading(
+        :suggestion,
+        "class-itis (#{clusters.length} #{noun}, #{total_occurrences} occurrences)"
+      )
+      @output.puts "  The same multi-class list applied to the same tag in many places —"
+      @output.puts "  classic AI-paste pattern. Consider extracting a shared component or"
+      @output.puts "  an @apply rule. Threshold: >= #{@min_classes} classes, >= #{@min_occurrences} occurrences."
 
       clusters.each do |cluster|
         @output.puts ""
-        @output.puts "  <#{cluster.tag}> with #{cluster.class_count} classes, " \
-                     "#{cluster.count} occurrences:"
+        header = "<#{cluster.tag}> with #{cluster.class_count} classes, #{cluster.count} occurrences"
+        @output.puts "  #{@style.severity(:suggestion, header)}"
+        @output.puts "    #{@style.suggestion(suggestion_for(cluster))}"
         @output.puts "    class=#{format_classes(cluster.classes)}"
         cluster.occurrences.first(@max_occurrences_shown).each do |occ|
-          @output.puts "    #{occ.file}:#{occ.line}"
+          @output.puts "    #{@style.location("#{occ.file}:#{occ.line}")}"
         end
         if cluster.occurrences.length > @max_occurrences_shown
           remaining = cluster.occurrences.length - @max_occurrences_shown
-          @output.puts "    … and #{remaining} more"
+          @output.puts "    #{@style.location("… and #{remaining} more")}"
         end
       end
     end
 
+    # Suggestion shape varies by cluster size + count. Big class lists
+    # repeated many places want a component; smaller lists repeated
+    # often might just be a shared CSS rule.
+    def suggestion_for(cluster)
+      if cluster.class_count >= 8
+        "extract a #{component_name(cluster)} component — too many classes to keep inlined"
+      elsif cluster.count >= 6
+        "repeated this often, an @apply rule or shared class would dry it up"
+      else
+        "consider a shared component or @apply rule for this class list"
+      end
+    end
+
+    def component_name(cluster)
+      "#{cluster.tag.capitalize}Component"
+    end
+
     # Cap the displayed class string so a 30-utility soup doesn't blow
     # out the terminal. Fingerprint matching is on the full sorted list,
     # so display truncation is purely cosmetic.