ui_guardrails 1.3.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a78df8763f35470a40ab6c8c8dcc6daf1351d35e733772a33afde5d1b7af1a54
-  data.tar.gz: a1f8aa3366f9a350673c55ff4200716e6c37db2f777592b914ada3236f67682e
+  metadata.gz: b29232255e89ade665ffe0aa02661183fbf71c5918c53704d8241293be757454
+  data.tar.gz: 5d3cf78b2091bb6e781f6bd563976c9bc1c583a8269309ce897ed90d8eae3b3b
 SHA512:
-  metadata.gz: f16927ab59ea1e9e89fe51203d3a0ca0f14331956fdcce4ca1e957642579129ba143651d066d9bb763f85fb4b2f3e5afd93a657a9266550b8435e0159478c659
-  data.tar.gz: 7f4dfebecd72b184a84258ca90f48f978c603eb01739d3217f8cad8b24d0ab7991f2d8a79dc53834e7e67002b0da74219cf68e3aee0ca60c344febb1e3e722e0
+  metadata.gz: 99aa335b527770be65aa661262461ec9b9cc0e1a9f1f2b70153b804b584c5f3de497c0e38f18183d6eac1977d343506d99f42685a49c3bbe3e953781ba3cd176
+  data.tar.gz: 894f7504d9e0f559b79051645f7f2c29de05215de57b2f4e04f78f9eb0bb4145568d13bd593123be401a15f626b9c3872174467dd78920a4ce3f265709bb3712

data/README.md

@@ -4,7 +4,7 @@ A Rails toolset that prevents UI drift in AI-assisted applications. Static audit
 
 Built and maintained by [Meticulous](https://meticulous.com).
 
-**Current release:** 1.3.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.4.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.
 
 ---
 
@@ -93,7 +93,7 @@ APPLY=1 bundle exec rake guardrails:audit
 | `guardrails:init` | Stack detection, writes `guardrails.yml`, scaffolds prefers-color-scheme / prefers-contrast media queries. Refuses to overwrite an existing config — `FORCE=1` overrides. |
 | `guardrails:audit` | Runs every detector — view drift, stimulus, partial similarity, view-components, a11y, cross-codebase patterns, class-itis. Exits 1 on violations. |
 | `guardrails:tui` | The same audit, browsable: a severity roll-up you drill into (category → finding → source), regroup by file, filter, and jump from into your editor or the HTML report. See [Browsing findings](#browsing-findings). |
-| `guardrails:icons` | Generates an SVG sprite from `app/assets/images/icons/`, flags inline `<svg>` in views, reports unused icons. |
+| `guardrails:icons` | Generates an SVG sprite from `app/assets/images/icons/`, flags inline `<svg>` in views, catches emoji / glyph icons across views + helpers + models + JS + locales, reports unused sprite entries. **Exits 1** on any inline SVG, unknown sprite reference, or emoji/glyph icon (1.5.0). Dead icons stay reporting-only. `SUGGEST=1` prints sprite-name suggestions; `FORMAT=json` emits the machine-readable payload. |
 | `guardrails:tokens` | Parses your color and type-scale tokens (CSS vars / SCSS vars / Tailwind v3 config / Tailwind v4 `@theme`), reports hex literals in stylesheets that should reference a token. |
 | `guardrails:a11y:deep` | Reads axe-core JSON output and folds it into the unified report. Doesn't run axe itself (no Capybara / headless Chrome runtime deps) — point it at axe output your existing tooling produces. |
 | `guardrails:visual:deep` | Consumes screenshot-diff tool output (snap_diff-capybara today; BackstopJS in flight, [#15](https://github.com/meticulous/guardrails/issues/15)) and reports visual regressions. Same parse-only design — your existing test toolchain runs screenshots; Guardrails reports. |
@@ -125,7 +125,7 @@ Static AST walk over every `.html.erb` under `app/views/` and `app/components/`
 
 - CSS custom properties in your configured `colors_file`
 - SCSS variables in the same
-- Tailwind v3 `tailwind.config.js` — flat colors and nested scales (`gray.50` → `gray-50`)
+- Tailwind v3 `tailwind.config.js` — flat colors and nested scales (`gray.50` → `gray-50`). Found automatically at the repo root or at `config/tailwind.config.js` (the `tailwindcss-rails` default); set `tokens.tailwind_config` for anything else (`.cjs`, `.ts`, monorepo paths)
 - Tailwind v4 `@theme {}` blocks — picked up by the CSS-custom-property scanner
 
 Then scans every other stylesheet for hex literals and reports drift, matching each to the closest defined token. Block + line comments are stripped before matching, preserving line/column positions so reports are accurate.
@@ -186,6 +186,48 @@ Or standalone via `rake guardrails:a11y:deep`. Stays parse-only — your existin
 
 When [Lookbook](https://lookbook.build) is in the Gemfile, Guardrails auto-registers a `:guardrails` panel that appears next to every preview's Source / Notes panels. The panel renders `Guardrails::Lookbook::ComponentReport#for(component_class_name)` — drift in the template, orphan slots, similar templates — inline. Host apps override by dropping their own partial at `app/views/lookbook_panels/_guardrails.html.erb`. See [`doc/LOOKBOOK.md`](doc/LOOKBOOK.md).
 
+### Emoji and glyph icons (1.5.0)
+
+The `guardrails:icons` task now catches emoji and Unicode-dingbat glyphs used as UI iconography — the most common way AI-assisted code bypasses the sprite. Two tiers, both on by default:
+
+| Tier | What matches | Example |
+|---|---|---|
+| `emoji` | Extended_Pictographic pictographs + multi-codepoint sequences (VS16, ZWJ, flags, keycaps) | `📄` `👨‍👩‍👧` `🇺🇸` `1️⃣` |
+| `glyph` | Single codepoints in Arrows, Misc Technical, Geometric Shapes, Misc Symbols, Dingbats, Misc Symbols & Arrows | `✓` `→` `★` `●` `⚠` |
+
+Grapheme-cluster iteration counts VS16-styled pictographs / ZWJ families / flag pairs / keycaps as **one** violation with the full cluster in the snippet. `\p{Emoji}` is deliberately **not** used (it matches ASCII digits, `#`, and `*`). Explicitly excluded from both tiers: letters, digits, punctuation, currency signs, `©®™`, ellipsis, dashes, quotes — those are copy, not icons.
+
+**Scans**, by default: `app/views`, `app/components`, `app/helpers`, `app/models`, `app/presenters`, `app/javascript`, and `config/locales` — where the emoji-as-icon pattern usually lives (a helper returning `"📄"` per content type, a Stimulus controller setting `textContent = "✓"`). Comments are masked per file type: Prism-parsed for `.rb`, `<%# %>` for ERB, `//` and `/* */` for JS/SCSS/CSS, `#` for YAML. Line and column stay accurate.
+
+**Config** in `guardrails.yml` (defaults shown; `guardrails:init` writes this block for you):
+
+```yaml
+guardrails:
+  icons:
+    emoji:
+      enabled: true          # the emoji tier
+      glyphs: true           # the dingbat/glyph tier; false = emoji only
+      scan_paths:            # optional override of the default file list
+      allow_files:           # emoji-as-content: scanned but never flagged
+        - app/models/reaction.rb
+      allow_chars: []        # specific codepoints to never flag, e.g. ["→"]
+```
+
+**Inline escape** for a single line — the first inline-marker convention in the gem:
+
+```ruby
+BAD = "📄" # guardrails-ok: emoji intentional in this seed data
+
+# guardrails-ok: emoji shipping consciously — deprecation notice text
+LEGACY = "📎 old attachment"
+```
+
+Works on the same line or the preceding line, in Ruby `#` comments, ERB `<%# %>` blocks, JS `//`, SCSS `//`, and YAML `#`.
+
+**Suggestions** with `SUGGEST=1`: when the consumer's sprite contains a conventional name for the flagged emoji (`📄 → check for icon-file or icon-document`, `✓ → icon-check` / `icon-checkmark`), the task prints `→ use <use href="#icon-document"/>`. When no equivalent exists, it prints `→ no sprite equivalent — add one`. Only names the consumer's `collect_icon_names` includes are surfaced. No auto-fix path (`APPLY=1`) — the right sprite name depends on the consumer's semantics.
+
+**No-fix policy**: emoji contribute to `guardrails:icons` exit code (part of Result#violations?). Dead icons stay reporting-only — deleting a file is a human decision.
+
 ---
 
 ## Output
@@ -219,6 +261,7 @@ The editor is `$GUARDRAILS_EDITOR`, then `$VISUAL`, then `$EDITOR`. VS Code-fami
 |---|---|
 | `SUGGEST=1` | Write the markdown checklist alongside the text report. |
 | `APPLY=1` | Auto-fix raw_color + tailwind_arbitrary where tokens match. |
+| `SEVERITY=error` / `SEVERITY=warning` | Severity floor. `error` checks errors only; `warning` drops suggestions; default is everything. Applies to the report, the exit code, JSON, HTML, and the TUI alike. Detectors that can only produce muted findings aren't run. An unrecognized value aborts rather than being ignored. |
 | `FORMAT=json` | Emit one JSON document to stdout (all other audit output is suppressed). |
 | `FORMAT=html` / `OUTPUT=path` | Write the self-contained HTML report (default `tmp/guardrails/audit.html`). |
 | `GUARDRAILS_EDITOR=cmd` | Editor `guardrails:tui` opens locations in. Falls back to `$VISUAL`, then `$EDITOR`. |
@@ -242,6 +285,15 @@ The audit task is a single shell command:
   run: bundle exec rake guardrails:audit
 ```
 
+Adopting Guardrails on an existing codebase usually means a backlog of warnings you can't clear in one PR. Gate on errors now and ratchet down later:
+
+```yaml
+- name: Guardrails audit (errors only)
+  run: bundle exec rake guardrails:audit SEVERITY=error
+```
+
+`SEVERITY=error` exits 1 only when there are error-level findings (raw colors, arbitrary Tailwind values, a11y, visual diffs) and skips the warning- and suggestion-tier detectors entirely, so it's also the fastest way to run the audit. The report ends with a line saying what wasn't checked, so a green run can't be mistaken for a clean codebase.
+
 For richer integration:
 
 ```yaml
@@ -275,6 +327,10 @@ guardrails:
     # guessed wrong.
     colors_file: app/assets/stylesheets/tokens/_colors.css
     type_scale_file: app/assets/stylesheets/tokens/_type.css
+    # Optional. Tailwind v3 config to read theme colors from. Not needed
+    # for tailwind.config.js at the root or under config/ — init writes
+    # it for the latter, and both are discovered without it.
+    tailwind_config: config/tailwind.config.js
     # Per-channel R/G/B distance at which a near-match becomes a
     # "close enough to suggest" finding. 0 = exact only; 4 = default
     # (catches #0066ff ↔ #0067fe); 20+ = aggressive.

data/doc/ROADMAP.md

@@ -1,7 +1,7 @@
 # Guardrails — Roadmap
 
-**Status:** **1.0.0 released on RubyGems.org** — V0 ✅, V1 ✅, V2 ✅ (visual-diff via snap_diff-capybara landed 0.8.0; published as 1.0.0 once the trusted-publisher pipeline merged)
-**Last updated:** 2026-05-11
+**Status:** **1.5.0 released on RubyGems.org** — V0 ✅, V1 ✅, V2 ✅ (the originally-planned roadmap, published as 1.0.0). Post-1.0 releases have been about reading the findings rather than producing more of them: inline suggestions (1.1.0), then an interactive browser + HTML report (1.3.0), then a severity floor for CI adoption on existing codebases (1.4.0). 1.5.0 returns to producing findings — emoji-as-icon detection, the one drift vector that had zero coverage.
+**Last updated:** 2026-09-19
 
 ## Context
 
@@ -116,6 +116,26 @@ This doc tracks shipped vs. planned scope and parks remaining unknowns. V0 + mos
 
 ---
 
+## Post-1.0 — Report UX
+
+The planned roadmap ended at V2. Running the gem on real codebases (Patchvault: 981 findings) showed the next problem wasn't detection, it was *reading* the output.
+
+| Item | Status | Notes |
+|---|---|---|
+| Inline suggestions + triage summary | ✅ shipped (1.1.0) | Every finding carries a `→` action; severity-grouped summary at top and bottom; `[error]` / `[warning]` / `[suggest]` tags; TTY-aware ASCII styling, `NO_COLOR` honored. |
+| Ruby 3.4 / railties 7.2 floor | ✅ shipped (1.2.0) | Compatibility-only release. Ruby 3.2/3.3 or Rails 7.1 users stay on 1.1.0. |
+| Findings data layer | ✅ shipped (1.3.0) | `Guardrails::Report::Run` runs the audit once for every front-end; `Report::Finding` / `Location` / `Category` are detector-agnostic finding data. Every detector implements `categories(result)`, sharing its title / suggestion strings with the text report. New detectors only need to implement that to show up in the TUI and HTML report. |
+| Interactive browser (`rake guardrails:tui`) | ✅ shipped (1.3.0) | Roll-up → category → finding → source, regroup by file, live filter, open in `$EDITOR` at the line, re-run. `io/console` only — no new dependencies. If the hand-rolled rendering stops being enough, swapping in a TUI library means replacing `TUI::Screen` + the loop in `tui.rb`; `TUI::State` (navigation) doesn't know about terminals. |
+| HTML report (`FORMAT=html`) | ✅ shipped (1.3.0) | One self-contained file, no server or assets — opens from disk or as a CI artifact. Generated rather than served: a mounted engine was more surface than the problem needed, and the Lookbook panel already covers in-app. |
+| File-grouped view | ✅ shipped (1.3.0) | `tab` in the TUI. Was a 1.1.0 follow-up. |
+| `SEVERITY=error\|warning` floor | ✅ shipped (1.4.0) | One severity floor across text report, exit code, JSON, HTML, and TUI. Skips detectors that can only produce muted findings. Filtered reports say what wasn't checked; unknown values abort. Supersedes the `--strict` flag dropped in V0. |
+| Emoji + glyph icon detection | ✅ shipped (1.5.0) | `Guardrails::Icons::EmojiScan` catches emoji pictographs and Unicode-dingbat glyphs used as UI iconography — grapheme-cluster iteration (VS16 / ZWJ / flag / keycap count as one), range-first single-codepoint classification, per-file-type comment masking (Prism for Ruby, `<%# %>` for ERB, `//` `/* */` for JS/SCSS, `#` for YAML), `guardrails-ok: emoji` inline marker (first inline-escape convention in the gem), `allow_files` + `allow_chars` config, `SUGGEST=1` sprite-name hints. `guardrails:icons` also flipped to blocking — exit 1 on inline SVGs, unknown sprite refs, or emoji icons. |
+| Lookbook panel on the new data layer | not started | The auto-registered panel still renders from its own `ComponentReport`; it could render `Report::Finding`s and pick up suggestions for free. Icons findings could also flow through — the panel doesn't list icon findings today. |
+| Icons on the new data layer | not started | Icons stays outside `Report::Run` — its rake task calls `Icons.new(root:).run` directly. Migrating gets it into the TUI + HTML report for free but changes the rake shape; hold until there's demand. |
+| CI test workflow | not started | Specs only run inside the release workflow, on one Ruby. A PR-time matrix (3.4 + head) would catch floor regressions before tag time. |
+
+---
+
 ## Decisions Captured
 
 | Question | Decision |

data/lib/guardrails/a11y_deep.rb

@@ -5,6 +5,7 @@ require "pathname"
 require "set"
 require_relative "report/style"
 require_relative "report/finding"
+require_relative "report/severity"
 
 module Guardrails
   # Consumes axe-core JSON output and folds the findings into Guardrails'
@@ -39,7 +40,9 @@ 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, style: nil)
+    def initialize(input:, output: $stdout, failing_impacts: DEFAULT_FAILING_IMPACTS, style: nil,
+                   min_severity: Report::Severity::DEFAULT)
+      @min_severity = min_severity
       @input = input
       @output = output
       @failing_impacts = Set.new(failing_impacts.map(&:to_s))
@@ -47,7 +50,7 @@ module Guardrails
     end
 
     def run
-      findings = parse_input
+      findings = parse_input.select { |f| Report::Severity.include?(impact_to_severity(f.impact), @min_severity) }
       print_report(findings)
       findings
     end

data/lib/guardrails/audit.rb

@@ -7,6 +7,7 @@ require "yaml"
 require_relative "erb_parser"
 require_relative "report/style"
 require_relative "report/finding"
+require_relative "report/severity"
 
 module Guardrails
   class Audit
@@ -71,7 +72,9 @@ module Guardrails
       flood-color lighting-color stop-color
     ].freeze
 
-    def initialize(root:, output: $stdout, suggest: false, format: :text, apply: false, style: nil)
+    def initialize(root:, output: $stdout, suggest: false, format: :text, apply: false, style: nil,
+                   min_severity: Report::Severity::DEFAULT)
+      @min_severity = min_severity
       @root = Pathname(root)
       @output = output
       @suggest = suggest
@@ -82,7 +85,12 @@ module Guardrails
     end
 
     def run
-      violations = collect_files.flat_map { |file| scan_file(file) }
+      # Filtered before anything else sees them, so the report, the
+      # SUGGEST checklist, and the returned list (→ exit code, JSON)
+      # all agree on what this run was about.
+      violations = collect_files.flat_map { |file| scan_file(file) }.select do |v|
+        Report::Severity.include?(SEVERITY_FOR_TYPE.fetch(v.type, :warning), @min_severity)
+      end
       print_report(violations)
       remaining = @apply ? apply_auto_fixes(violations) : violations
       write_suggestions(remaining) if @suggest

data/lib/guardrails/icons/emoji_scan.rb

@@ -0,0 +1,367 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "prism"
+require "set"
+
+module Guardrails
+  class Icons
+    # Emoji and dingbat-glyph detection.
+    #
+    # Two tiers, both on by default:
+    #
+    #   emoji  — anything in \p{Extended_Pictographic}, plus regional-
+    #            indicator pairs (flags, U+1F1E6..U+1F1FF), plus keycap
+    #            sequences ([0-9#*]️?⃣). Handles VS16 (U+FE0F)
+    #            and ZWJ (U+200D) so a family sequence or VS16-styled
+    #            pictograph is reported as one grapheme with the full
+    #            cluster in `snippet`.
+    #
+    #   glyph  — Unicode symbols used as icons that are NOT emoji:
+    #            Dingbats (U+2700..27BF), Miscellaneous Symbols
+    #            (U+2600..26FF), Miscellaneous Technical (U+2300..23FF),
+    #            Arrows (U+2190..21FF), Geometric Shapes
+    #            (U+25A0..25FF), Misc Symbols & Arrows (U+2B00..2BFF).
+    #
+    # These render inconsistently across platforms and are what the
+    # sprite exists to replace. Some teams accept `→` in prose, so the
+    # glyph tier is independently configurable via
+    # `guardrails.icons.emoji.glyphs`.
+    #
+    # `\p{Emoji}` matches ASCII digits, `#`, and `*` — never use it as
+    # the primary test. Iterate grapheme clusters instead, classify
+    # each with the three-way predicate below, and everything ASCII,
+    # `©®™`, `…`, `–—`, currency, typographic quotes stays unflagged.
+    #
+    # Classification order is emoji-first, glyph-second, because
+    # characters like `⚠` (U+26A0) and `✏` (U+270F) fall in the glyph
+    # codepoint ranges but ALSO in Extended_Pictographic. Reporting
+    # them as `emoji` matches user intuition (they're colored on all
+    # modern OSes) and keeps `glyphs: false` semantics honest.
+    class EmojiScan
+      Violation = Struct.new(:type, :file, :line, :column, :snippet, :codepoints, :tier,
+                             keyword_init: true)
+
+      # Default file globs. Reuse Icons::USAGE_SCAN_PATTERNS shape but
+      # extend to helpers/models/presenters and locales — where the
+      # motivating consumer bug lived. `spec/` and `test/` are excluded
+      # by convention (they're outside `app/`).
+      DEFAULT_SCAN_PATTERNS = [
+        "app/views/**/*.html.erb",
+        "app/components/**/*.{html.erb,rb}",
+        "app/helpers/**/*.rb",
+        "app/models/**/*.rb",
+        "app/presenters/**/*.rb",
+        "app/javascript/**/*.{js,ts,jsx,tsx}",
+        "config/locales/**/*.yml"
+      ].freeze
+
+      # Path components we always skip, matching the ignore list other
+      # detectors use. `previews` covers Lookbook / ViewComponent
+      # preview directories under both `app/` and outside it.
+      IMPLICIT_IGNORE_SEGMENTS = %w[vendor node_modules tmp public log spec test previews].freeze
+
+      # Regional-indicator range for flag sequences (pairs of these
+      # form a grapheme cluster that renders as a flag).
+      REGIONAL_INDICATOR = /\A[\u{1F1E6}-\u{1F1FF}]{2}\z/
+
+      # Keycap sequence: a base character (digit, hash, or asterisk)
+      # optionally followed by VS16, then the combining enclosing
+      # keycap U+20E3.
+      KEYCAP = /\A[0-9#*]\u{FE0F}?\u{20E3}\z/
+
+      # Glyph-tier codepoint ranges. The spec groups characters by
+      # visual family (dingbat, arrow, geometric shape) — many of these
+      # ALSO carry the Extended_Pictographic property under Unicode
+      # (⚠ U+26A0, ✏ U+270F, ★ U+2605), but the spec's grouping is
+      # what maps to user intent: a team that accepts `→` in prose
+      # under `glyphs: false` will also accept `★`. So a single
+      # codepoint in one of these ranges wins glyph classification
+      # regardless of Extended_Pictographic — see `classify_single`.
+      #
+      # Multi-codepoint clusters (VS16, ZWJ, flag, keycap) never enter
+      # this branch; they're always emoji.
+      GLYPH_RANGES = [
+        (0x2190..0x21FF), # Arrows
+        (0x2300..0x23FF), # Misc Technical
+        (0x25A0..0x25FF), # Geometric Shapes
+        (0x2600..0x26FF), # Misc Symbols
+        (0x2700..0x27BF), # Dingbats
+        (0x2B00..0x2BFF)  # Misc Symbols and Arrows
+      ].freeze
+
+      # Single codepoints Unicode marks Extended_Pictographic but are
+      # never icons in practice — trademark/registered/copyright marks
+      # ship in body copy as legal notation. Explicit skip so
+      # `Foo® Inc` doesn't report as `emoji`.
+      TYPOGRAPHIC_SKIP = Set[0x00A9, 0x00AE, 0x2122].freeze
+
+      # Same-line or preceding-line marker that silences the finding
+      # on that line. Reason text after `emoji` is optional but
+      # encouraged; only the presence of the marker is required.
+      INLINE_MARKER = /guardrails-ok:\s*emoji\b/
+
+      # `output:` is accepted for symmetry with other detectors but
+      # ignored — EmojiScan is pure return-a-value; the human-readable
+      # report belongs to Icons#report_emoji, which owns the output
+      # stream and the Style.
+      def initialize(root:, output: nil, # rubocop:disable Lint/UnusedMethodArgument
+                     enabled: true, glyphs: true,
+                     scan_paths: nil, allow_files: nil, allow_chars: nil)
+        @root = Pathname(root)
+        @enabled = enabled
+        @glyphs = glyphs
+        @scan_paths = Array(scan_paths).compact.map(&:to_s)
+        @allow_files = normalize_allow_files(allow_files)
+        @allow_chars = Array(allow_chars).flat_map { |c| c.to_s.grapheme_clusters }.to_set
+      end
+
+      def call
+        return [] unless @enabled
+
+        scan_files.flat_map { |file| scan_file(file) }
+      end
+
+      # Public for testing — the classifier is the load-bearing bit.
+      #
+      # Returns :emoji, :glyph, or nil. Grapheme clusters that are
+      # allowlisted, ASCII, punctuation, currency, `©®™`, etc. return
+      # nil.
+      #
+      # Multi-codepoint clusters (VS16, ZWJ, flag, keycap) are always
+      # emoji. Single codepoints check GLYPH_RANGES first (spec's
+      # visual grouping), then fall through to Extended_Pictographic.
+      def classify(grapheme)
+        return nil if grapheme.nil? || grapheme.empty?
+        return nil if @allow_chars.include?(grapheme)
+
+        chars = grapheme.each_char.to_a
+        if chars.length > 1
+          return :emoji if multi_codepoint_emoji?(grapheme)
+          return nil
+        end
+
+        classify_single(chars.first.ord)
+      end
+
+      private
+
+      def multi_codepoint_emoji?(grapheme)
+        return true if grapheme.match?(REGIONAL_INDICATOR)
+        return true if grapheme.match?(KEYCAP)
+
+        # ZWJ sequences and VS16-styled pictographs anchor on at least
+        # one Extended_Pictographic codepoint (a specific pictograph);
+        # the connecting ZWJ / selector pieces don't match on their own
+        # but the base does.
+        grapheme.each_char.any? { |c| c.match?(/\p{Extended_Pictographic}/) }
+      end
+
+      def classify_single(cp)
+        return nil if TYPOGRAPHIC_SKIP.include?(cp)
+
+        # Range-first: a codepoint in a glyph range is a glyph even if
+        # Unicode marks it Extended_Pictographic. This matches the
+        # spec's visual grouping and keeps `glyphs: false` predictable
+        # for teams that accept small monochrome symbols in prose.
+        if GLYPH_RANGES.any? { |r| r.cover?(cp) }
+          return @glyphs ? :glyph : nil
+        end
+
+        return :emoji if [cp].pack("U*").match?(/\p{Extended_Pictographic}/)
+
+        nil
+      end
+
+      def scan_files
+        patterns = @scan_paths.empty? ? DEFAULT_SCAN_PATTERNS : @scan_paths
+        patterns
+          .flat_map { |pattern| Dir.glob(@root.join(pattern)) }
+          .map { |path| Pathname(path) }
+          .uniq
+          .reject { |path| ignored?(path) }
+          .reject { |path| allow_listed?(path) }
+      end
+
+      def ignored?(path)
+        segments = relative(path).split("/")
+        (IMPLICIT_IGNORE_SEGMENTS & segments).any?
+      end
+
+      def allow_listed?(path)
+        @allow_files.include?(relative(path))
+      end
+
+      def scan_file(file)
+        raw = read(file)
+        return [] if raw.nil? || raw.empty?
+
+        masked = mask_comments(raw, file)
+        suppressed_lines = suppressed_line_set(raw, masked)
+        relative_path = relative(file)
+
+        violations = []
+        masked.each_line.with_index(1) do |line, line_num|
+          next if suppressed_lines.include?(line_num)
+
+          scan_line(line).each do |(grapheme, tier, column)|
+            violations << Violation.new(
+              type: :emoji_icon,
+              file: relative_path,
+              line: line_num,
+              column: column,
+              snippet: grapheme,
+              codepoints: grapheme.each_char.map { |c| format("U+%04X", c.ord) }.join(" "),
+              tier: tier
+            )
+          end
+        end
+        violations
+      end
+
+      # Walk the line by grapheme cluster, tracking char offset so
+      # `column` is the 1-indexed character position — not byte
+      # position (would be wrong for any multibyte char) and not
+      # grapheme index (a family sequence spans 5 characters but
+      # counts as one grapheme, and the column of the NEXT thing
+      # after it needs to be char-accurate).
+      def scan_line(line)
+        results = []
+        char_offset = 0
+        line.each_grapheme_cluster do |g|
+          tier = classify(g)
+          results << [g, tier, char_offset + 1] if tier
+          char_offset += g.length
+        end
+        results
+      end
+
+      # Length-preserving comment mask per file type. Non-empty return
+      # value preserves line numbers and columns for accurate location
+      # reporting — mirrors the strategy `mask_erb` uses in Icons.
+      def mask_comments(source, file)
+        ext = file.extname.downcase
+        case ext
+        when ".rb" then mask_ruby_comments(source)
+        when ".erb" then mask_erb_comments(source)
+        when ".js", ".ts", ".jsx", ".tsx", ".scss", ".sass", ".css"
+          mask_js_style_comments(source)
+        when ".yml", ".yaml" then mask_yaml_comments(source)
+        else source
+        end
+      end
+
+      # Prism ships with Ruby 3.4 (min supported). Its `comments` list
+      # is more accurate than any regex: it correctly ignores `#` inside
+      # string literals, interpolation, and heredocs. A regex on `#.*$`
+      # would false-mask `"#icon-check"` and break inline markers.
+      #
+      # NB: Prism's default `start_offset` / `end_offset` are BYTE
+      # offsets; indexing an array of characters with them misaligns
+      # after any multibyte content earlier in the file (an emoji-in-
+      # a-string followed by a `#` comment would leave the `#` region
+      # unmasked and the following line partly masked). Use the
+      # `_character_offset` accessors (Prism 1.5+, bundled with Ruby
+      # 3.4 as a default gem) which count characters and work with
+      # `String#[]=` on the source.
+      def mask_ruby_comments(source)
+        result = Prism.parse(source)
+        chars = source.chars
+        result.comments.each do |c|
+          start_off = c.location.start_character_offset
+          end_off = c.location.end_character_offset
+          # Replace with spaces, but keep newlines so line numbers hold.
+          (start_off...end_off).each do |i|
+            chars[i] = " " unless chars[i] == "\n"
+          end
+        end
+        chars.join
+      rescue StandardError
+        # If Prism fails on malformed source, leave uncommented — we'd
+        # rather over-report than skip a real emoji hidden by a parse
+        # error.
+        source
+      end
+
+      # Only `<%# ... %>` in ERB is a comment. `<% ... %>` and
+      # `<%= ... %>` execute Ruby that may legitimately contain
+      # emoji as string literals — those must remain scannable.
+      ERB_COMMENT = /<%#[\s\S]*?%>/
+      def mask_erb_comments(source)
+        source.gsub(ERB_COMMENT) { |m| preserve_newlines(m) }
+      end
+
+      JS_LINE_COMMENT = %r{//[^\n]*}
+      JS_BLOCK_COMMENT = %r{/\*[\s\S]*?\*/}
+      # Note: string-embedded `//` (e.g. inside a URL literal) will
+      # false-mask through this regex. Documented gap; a full JS parser
+      # would fix it but the false-negative surface is small — a URL
+      # `"http://foo/📄"` would incorrectly not report. Acceptable
+      # tradeoff for zero-dep scanning; add a marker if it hurts.
+      def mask_js_style_comments(source)
+        source
+          .gsub(JS_BLOCK_COMMENT) { |m| preserve_newlines(m) }
+          .gsub(JS_LINE_COMMENT) { |m| " " * m.length }
+      end
+
+      # YAML: `#` starts a comment to end-of-line, except inside quoted
+      # strings. Approximated with a simpler regex: mask `#` at start
+      # of line or after whitespace. Quoted `#` (rare in locale files
+      # for icons) will false-mask; document if it becomes a problem.
+      YAML_COMMENT = /(^|\s)#[^\n]*/
+      def mask_yaml_comments(source)
+        source.gsub(YAML_COMMENT) do |m|
+          # Preserve the leading whitespace/anchor character.
+          prefix = m.start_with?("#") ? "" : m[0]
+          "#{prefix}#{" " * (m.length - prefix.length)}"
+        end
+      end
+
+      def preserve_newlines(str)
+        newline_count = str.count("\n")
+        "\n" * newline_count + " " * (str.length - newline_count)
+      end
+
+      # Build a set of line numbers to suppress based on inline
+      # markers. A marker suppresses the line it appears on. It ALSO
+      # suppresses the following line only when the marker line has no
+      # non-comment content — that's the "marker on the preceding
+      # line" case. A trailing marker (`FOO = "\u{1F4C4}" # guardrails-ok:
+      # emoji`) suppresses only its own line, so a legitimate finding
+      # on the next line still surfaces.
+      #
+      # `raw` carries the marker text (comments are erased in `masked`);
+      # `masked` tells us whether the marker line was a pure comment
+      # (its `strip.empty?` in the masked form) or a trailing comment
+      # after code (non-empty).
+      def suppressed_line_set(raw, masked)
+        suppressed = Set.new
+        masked_lines = masked.lines
+        raw.each_line.with_index(1) do |line, line_num|
+          next unless line.match?(INLINE_MARKER)
+
+          suppressed << line_num
+          masked_line = masked_lines[line_num - 1] || ""
+          suppressed << line_num + 1 if masked_line.strip.empty?
+        end
+        suppressed
+      end
+
+      def read(file)
+        File.read(file, encoding: Encoding::UTF_8)
+      rescue Errno::ENOENT, Errno::EACCES
+        nil
+      end
+
+      def relative(path)
+        path.relative_path_from(@root).to_s
+      rescue ArgumentError
+        path.to_s
+      end
+
+      def normalize_allow_files(list)
+        Array(list).map(&:to_s).to_set
+      end
+    end
+  end
+end

data/lib/guardrails/icons.rb

@@ -1,12 +1,86 @@
 # frozen_string_literal: true
 
 require "pathname"
+require "set"
 require "yaml"
+require_relative "report/style"
+require_relative "icons/emoji_scan"
 
 module Guardrails
   class Icons
     Violation = Struct.new(:type, :file, :line, :column, :snippet, keyword_init: true)
 
+    # Result of a full run. Struct with keyword_init keeps the Hash-style
+    # `result[:inline_svgs]` access existing consumers rely on (see
+    # spec/integration/demo_app_spec.rb) while adding a `violations?`
+    # predicate the rake task can gate `exit 1` on. Mirrors the shape
+    # of `StimulusAudit::Result` / `ViewComponentAudit::Result`.
+    #
+    # Dead icons are excluded from `violations?` on purpose: deleting an
+    # unused SVG file is a human decision (it may be genuinely used by a
+    # deploy path the scan can't see), so the audit reports them but
+    # doesn't fail the build over them. Emoji findings DO fail — the
+    # sprite is the design-system boundary that emoji bypass.
+    Result = Struct.new(:inline_svgs, :dead_icons, :unknown_refs, :emoji, keyword_init: true) do
+      def violations?
+        !inline_svgs.empty? || !unknown_refs.empty? || !emoji.empty?
+      end
+
+      # Machine-readable serialization for FORMAT=json. Structs' default
+      # `to_h` recurses into member Structs but not their arrays of
+      # Structs; call `to_h` on each Violation manually.
+      def to_h
+        {
+          inline_svgs: inline_svgs.map(&:to_h),
+          dead_icons: dead_icons,
+          unknown_refs: unknown_refs,
+          emoji: emoji.map(&:to_h),
+          summary: {
+            inline_svgs: inline_svgs.length,
+            dead_icons: dead_icons.length,
+            unknown_refs: unknown_refs.length,
+            emoji: emoji.length
+          }
+        }
+      end
+    end
+
+    # Sprite-name hint map for SUGGEST=1 output. The pasted spec lists
+    # the well-known emoji → semantic-name mappings; only surface a
+    # suggestion when the target name actually exists in the consumer's
+    # collected icon set (via `collect_icon_names`). Otherwise print
+    # "no sprite equivalent — add one." so users know the gap.
+    #
+    # Codepoints as keys (single-cluster form after removing VS16) so
+    # the lookup survives whichever form the source used.
+    SPRITE_NAME_HINTS = {
+      "✓" => %w[check checkmark],           # ✓
+      "✔" => %w[check checkmark],           # ✔
+      "✕" => %w[x close],                   # ✕
+      "✖" => %w[x close],                   # ✖
+      "✗" => %w[x close],                   # ✗
+      "✘" => %w[x close],                   # ✘
+      "×" => %w[x close],                   # ×
+      "★" => %w[star favorite],             # ★
+      "☆" => %w[star favorite],             # ☆
+      "⚠" => %w[warning alert],             # ⚠
+      "\u{1F4C4}" => %w[file document],         # 📄
+      "\u{1F4CE}" => %w[attachment paperclip],  # 📎
+      "\u{1F511}" => %w[key],                   # 🔑
+      "\u{1F464}" => %w[user person avatar],    # 👤
+      "\u{1F3E2}" => %w[building office],       # 🏢
+      "\u{1F5D1}" => %w[trash delete],          # 🗑
+      "\u{270F}" => %w[edit pencil],            # ✏
+      "➕" => %w[plus add],                  # ➕
+      "➖" => %w[minus remove],              # ➖
+      "\u{1F514}" => %w[bell notification],     # 🔔
+      "\u{1F507}" => %w[mute bell-off],         # 🔇
+      "\u{1F4E6}" => %w[package zip archive],   # 📦
+      "\u{1F3AC}" => %w[video film],            # 🎬
+      "\u{1F3B5}" => %w[audio music note],      # 🎵
+      "\u{1F4CA}" => %w[chart bar-chart]        # 📊
+    }.freeze
+
     DEFAULT_SOURCE = "app/assets/images/icons"
     DEFAULT_SPRITE_OUTPUT = "app/assets/images/icons/sprite.svg"
     DEFAULT_VIEWBOX = "0 0 24 24"
@@ -50,22 +124,58 @@ module Guardrails
       "app/javascript/**/*.{js,ts,jsx,tsx}"
     ].freeze
 
-    def initialize(root:, output: $stdout, source: nil, sprite_output: nil)
+    def initialize(root:, output: $stdout, source: nil, sprite_output: nil,
+                   style: nil, suggest: false, format: :text)
       @root = Pathname(root)
       @output = output
-      config = load_config
+      @style = style || Report::Style.new(io: output)
+      @suggest = suggest
+      @format = format
+      @config = load_config
 
-      @source = resolve_path(source || config.dig("guardrails", "icons", "source") || DEFAULT_SOURCE)
-      @sprite_output = resolve_path(sprite_output || config.dig("guardrails", "icons", "sprite_output") || DEFAULT_SPRITE_OUTPUT)
+      @source = resolve_path(source || @config.dig("guardrails", "icons", "source") || DEFAULT_SOURCE)
+      @sprite_output = resolve_path(sprite_output || @config.dig("guardrails", "icons", "sprite_output") || DEFAULT_SPRITE_OUTPUT)
     end
 
     def run
       generate_sprite
-      violations = audit_inline_svgs
-      report_inline_svgs(violations)
+      inline_violations = audit_inline_svgs
       dead_report = report_dead_icons
-      print_dead_report(dead_report)
-      { inline_svgs: violations, dead_icons: dead_report[:dead], unknown_refs: dead_report[:unknown] }
+      emoji_violations = audit_emoji
+
+      unless @format == :json
+        report_inline_svgs(inline_violations)
+        print_dead_report(dead_report)
+        report_emoji(emoji_violations)
+      end
+
+      Result.new(
+        inline_svgs: inline_violations,
+        dead_icons: dead_report[:dead],
+        unknown_refs: dead_report[:unknown],
+        emoji: emoji_violations
+      )
+    end
+
+    # Runs the emoji/glyph scan against the configured file set.
+    # Returns [] when the tier is disabled or the config block is
+    # missing entirely (opt-out escape hatch for teams that don't want
+    # this rule yet).
+    def audit_emoji
+      opts = emoji_config
+      enabled = opts.fetch("enabled", true)
+      return [] unless enabled
+
+      scanner = EmojiScan.new(
+        root: @root,
+        output: @output,
+        enabled: enabled,
+        glyphs: opts.fetch("glyphs", true),
+        scan_paths: opts["scan_paths"],
+        allow_files: opts["allow_files"],
+        allow_chars: opts["allow_chars"]
+      )
+      scanner.call
     end
 
     def audit_inline_svgs
@@ -106,6 +216,10 @@ module Guardrails
       YAML.safe_load_file(path) || {}
     end
 
+    def emoji_config
+      @config.dig("guardrails", "icons", "emoji") || {}
+    end
+
     def resolve_path(path)
       pathname = Pathname(path)
       pathname.absolute? ? pathname : @root.join(pathname)
@@ -229,5 +343,54 @@ module Guardrails
         @output.puts "    #{v.snippet}"
       end
     end
+
+    def report_emoji(violations)
+      return if violations.empty?
+
+      grouped = violations.group_by(&:file).sort_by { |file, _| file }
+      noun = violations.length == 1 ? "emoji icon" : "emoji icons"
+      @output.puts ""
+      @output.puts "Guardrails icons: #{violations.length} #{noun} used as UI iconography (the sprite is the design-system boundary; these bypass it)"
+      grouped.each do |file, list|
+        @output.puts "  #{file}"
+        list.each { |v| report_emoji_line(v) }
+      end
+    end
+
+    def report_emoji_line(violation)
+      # `snippet` here IS the grapheme cluster (`📄`), which chomp
+      # only touches \n / \r / \r\n, safe on the cluster.
+      shown = violation.snippet.to_s.chomp
+      location = @style.location("#{violation.line}:#{violation.column}")
+      meta = @style.location("(#{violation.codepoints}, #{violation.tier})")
+      @output.puts "    #{location}  #{shown}  #{meta}"
+      hint = suggestion_for(violation)
+      @output.puts "      #{@style.suggestion(hint)}" if hint
+    end
+
+    # Sprite-name hint under SUGGEST=1, per the pasted spec. Only
+    # surface a suggestion when one of the mapped names actually exists
+    # in the consumer's icon set — otherwise the "add one" nudge is
+    # more useful than a name that doesn't resolve.
+    def suggestion_for(violation)
+      return nil unless @suggest
+
+      candidates = SPRITE_NAME_HINTS[canonical_key(violation.snippet)] || []
+      present = candidates & collect_icon_names
+      if present.any?
+        %(use <use href="#icon-#{present.first}"/>)
+      else
+        "no sprite equivalent — add one"
+      end
+    end
+
+    # Look up the hint using the grapheme's base character (dropping
+    # VS16 U+FE0F) so `📽️` and `📽` share a mapping. Multi-codepoint
+    # emoji (ZWJ families, flags, keycaps) rarely have single-icon
+    # sprite equivalents; those miss SPRITE_NAME_HINTS entirely and
+    # fall through to the "add one" hint.
+    def canonical_key(grapheme)
+      grapheme.to_s.delete("\u{FE0F}")
+    end
   end
 end

data/lib/guardrails/init/config_writer.rb

@@ -51,6 +51,14 @@ module Guardrails
 
       def yaml_for(result, overrides)
         token_paths = DEFAULT_TOKEN_PATHS.fetch(result.strategy)
+        tokens = {
+          "strategy" => result.strategy.to_s,
+          "colors_file" => token_paths["colors_file"],
+          "type_scale_file" => token_paths["type_scale_file"]
+        }
+        tokens["tailwind_config"] = overrides[:tailwind_config] if overrides[:tailwind_config]
+        tokens["near_match_policy"] = overrides.fetch(:near_match_policy, "notify")
+        tokens["near_match_threshold"] = overrides.fetch(:near_match_threshold, 4)
         config = {
           "guardrails" => {
             "audit" => {
@@ -59,19 +67,19 @@ module Guardrails
             },
             "icons" => {
               "source" => "app/assets/images/icons",
-              "sprite_output" => "app/assets/images/icons/sprite.svg"
+              "sprite_output" => "app/assets/images/icons/sprite.svg",
+              "emoji" => {
+                "enabled" => true,
+                "glyphs" => true,
+                "allow_files" => [],
+                "allow_chars" => []
+              }
             },
-            "tokens" => {
-              "strategy" => result.strategy.to_s,
-              "colors_file" => token_paths["colors_file"],
-              "type_scale_file" => token_paths["type_scale_file"],
-              "near_match_policy" => overrides.fetch(:near_match_policy, "notify"),
-              "near_match_threshold" => overrides.fetch(:near_match_threshold, 4)
-            }
+            "tokens" => tokens
           }
         }
 
-        header(result) + config.to_yaml(line_width: -1) + threshold_footer
+        header(result) + config.to_yaml(line_width: -1) + threshold_footer + icons_emoji_footer
       end
 
       def threshold_footer
@@ -86,6 +94,28 @@ module Guardrails
         YAML
       end
 
+      def icons_emoji_footer
+        <<~YAML
+
+          # icons.emoji tiers:
+          #   emoji   Extended_Pictographic pictographs plus multi-codepoint
+          #           sequences (flags, keycaps, ZWJ family, VS16-styled).
+          #           Colored on every modern OS — always drift.
+          #   glyphs  Monochrome symbols in the Arrows / Misc Technical /
+          #           Geometric Shapes / Misc Symbols / Dingbats / Misc
+          #           Symbols & Arrows ranges (→ ✓ ★ ● ⚠). Set glyphs: false
+          #           if your team accepts → in prose.
+          #
+          # allow_files skips a file entirely (chat reactions constants,
+          # emoji picker data). allow_chars keeps specific codepoints from
+          # flagging anywhere, e.g. ["→"].
+          #
+          # Inline escape for a single line: append `# guardrails-ok: emoji <reason>`
+          # (same line or preceding line, works in Ruby / ERB `<%# %>` / JS //
+          # / SCSS // / YAML #).
+        YAML
+      end
+
       def header(result)
         unset_paths = result.strategy == :raw_hex || result.strategy == :none
         comment = +"# Generated by `rails guardrails:init` on #{@now.strftime('%Y-%m-%d')}\n"

data/lib/guardrails/init.rb

@@ -6,6 +6,7 @@ require_relative "init/stack_detector"
 require_relative "init/config_writer"
 require_relative "init/media_query_scaffolder"
 require_relative "init/prompter"
+require_relative "tokens"
 
 module Guardrails
   class Init
@@ -34,6 +35,7 @@ module Guardrails
       # Don't prompt the user if we know we won't write — keeps reruns from
       # asking questions whose answers will be discarded.
       overrides = config_writeable? ? collect_overrides : {}
+      overrides[:tailwind_config] = detected_tailwind_config
 
       written = ConfigWriter.new(@root, output: @output).write(result, overrides: overrides, force: @force)
       if written
@@ -86,6 +88,17 @@ module Guardrails
       value.to_s.split(",").map(&:strip).reject(&:empty?)
     end
 
+    # Relative path of the Tailwind v3 config when one exists somewhere
+    # other than the repo root (typically `config/tailwind.config.js`
+    # from tailwindcss-rails). Root-level configs are found without
+    # configuration, so they're left out of the generated yml.
+    def detected_tailwind_config
+      found = Tokens::TAILWIND_CONFIG_CANDIDATES.find { |relative| @root.join(relative).exist? }
+      return nil if found.nil? || found == Tokens::TAILWIND_CONFIG_CANDIDATES.first
+
+      found
+    end
+
     def scaffold_media_queries
       file = configured_colors_file
       status, message = MediaQueryScaffolder.new(file, output: @output).scaffold
@@ -110,6 +123,8 @@ module Guardrails
       @output.puts "  custom-property files: #{result.evidence[:custom_property_files]}"
       @output.puts "  SCSS-variable files:   #{result.evidence[:scss_variable_files]}"
       @output.puts "  raw-hex files:         #{result.evidence[:raw_hex_files]}"
+      tailwind = Tokens::TAILWIND_CONFIG_CANDIDATES.find { |relative| @root.join(relative).exist? }
+      @output.puts "Tailwind config: #{tailwind}" if tailwind
     end
   end
 end

data/lib/guardrails/report/html/template.html.erb

@@ -107,7 +107,7 @@
 </header>
 
 <main class="wrap">
-  <p class="meta"><%= pluralize(findings.length, "finding") %> across <%= pluralize(@categories.length, "category", "categories") %> · <span class="mono"><%= h @root %></span> · generated <%= h @generated_at.strftime("%Y-%m-%d %H:%M") %> by ui_guardrails <%= h Guardrails::VERSION %></p>
+  <p class="meta"><%= pluralize(findings.length, "finding") %> across <%= pluralize(@categories.length, "category", "categories") %> · <span class="mono"><%= h @root %></span> · generated <%= h @generated_at.strftime("%Y-%m-%d %H:%M") %> by ui_guardrails <%= h Guardrails::VERSION %><% if muted_note %> · <strong><%= h muted_note %></strong><% end %></p>
 
   <%- if @categories.empty? -%>
   <p class="clean">✓ No findings — the audit is clean.</p>

data/lib/guardrails/report/html.rb

@@ -34,7 +34,10 @@ module Guardrails
 
       SEVERITY_LABEL = { error: "Error", warning: "Warning", suggestion: "Suggestion" }.freeze
 
-      def initialize(categories:, root:, generated_at: Time.now)
+      # `muted` — severities the run was told not to check (SEVERITY=).
+      # Stated on the page so a filtered report can't pass for a full one.
+      def initialize(categories:, root:, generated_at: Time.now, muted: [])
+        @muted = muted
         @categories = categories
         @root = Pathname(root).expand_path
         @generated_at = generated_at
@@ -74,6 +77,12 @@ module Guardrails
         end
       end
 
+      def muted_note
+        return nil if @muted.empty?
+
+        "#{@muted.map { |s| "#{SEVERITY_LABEL[s].downcase}s" }.join(' and ')} not checked"
+      end
+
       def severity_count(severity)
         findings.count { |f| f.severity == severity }
       end

data/lib/guardrails/report/run.rb

@@ -13,6 +13,7 @@ require_relative "../a11y_deep"
 require_relative "../visual_diff"
 require_relative "summary"
 require_relative "finding"
+require_relative "severity"
 require_relative "../configuration"
 
 module Guardrails
@@ -33,11 +34,13 @@ module Guardrails
       TRUTHY = %w[1 true yes].freeze
 
       attr_reader :violations, :stimulus, :similarity, :view_components,
-                  :a11y, :patterns, :classitis, :a11y_deep, :visual_diff
+                  :a11y, :patterns, :classitis, :a11y_deep, :visual_diff, :min_severity
 
       # Builds a Run from the documented env vars (SUGGEST, APPLY,
       # AXE_JSON, VISUAL_DIFF*, SIMILARITY_THRESHOLD, PATTERN_*,
-      # CLASSITIS_*).
+      # CLASSITIS_*, SEVERITY). Raises ArgumentError on a SEVERITY it
+      # doesn't recognize — a typo there would otherwise silently
+      # un-gate a CI check.
       def self.from_env(root:, style: nil, env: ENV)
         # Visual-diff is opt-in (baselines need deliberate setup). Enabled
         # when either VISUAL_DIFF=1 is set in the env (sidecar mode) or
@@ -66,7 +69,8 @@ module Guardrails
         new(root: root, style: style,
             suggest: truthy?(env["SUGGEST"]), apply: truthy?(env["APPLY"]),
             axe_json: env["AXE_JSON"], visual_diff: visual_diff_on,
-            similarity: similarity, patterns: patterns, classitis: classitis)
+            similarity: similarity, patterns: patterns, classitis: classitis,
+            min_severity: Severity.parse(env["SEVERITY"]))
       end
 
       def self.truthy?(value)
@@ -80,7 +84,9 @@ module Guardrails
       # uncolored output (what JSON mode wants — the body is discarded).
       def initialize(root:, style: nil, suggest: false, apply: false,
                      axe_json: nil, visual_diff: false,
-                     similarity: {}, patterns: {}, classitis: {})
+                     similarity: {}, patterns: {}, classitis: {},
+                     min_severity: Severity::DEFAULT)
+        @min_severity = min_severity
         @root = Pathname(root)
         @style = style
         @suggest = suggest
@@ -94,20 +100,35 @@ module Guardrails
       end
 
       def call
-        @violations = detect(Audit.new(**common, suggest: @suggest, apply: @apply, format: :text))
-        @stimulus = detect(StimulusAudit.new(**common))
-        @similarity = detect(PartialSimilarity.new(**common, **@similarity_opts))
-        @view_components = detect(ViewComponentAudit.new(**common))
+        # Detectors whose findings all sit below the severity floor
+        # aren't run at all — SEVERITY=error skips the two slowest
+        # (similarity, patterns) rather than computing results to
+        # discard. Audit and A11yDeep emit mixed severities, so they
+        # always run and filter internally.
+        @violations = detect(Audit.new(**common, suggest: @suggest, apply: @apply, format: :text,
+                                                 min_severity: @min_severity))
+        @stimulus = wanted?(:warning) ? detect(StimulusAudit.new(**common)) : StimulusAudit::Result.new(orphaned: [], dead: [])
+        @similarity = wanted?(:suggestion) ? detect(PartialSimilarity.new(**common, **@similarity_opts)) : []
+        @view_components = if wanted?(:warning) then detect(ViewComponentAudit.new(**common))
+                           else ViewComponentAudit::Result.new(missing_previews: [], orphan_slots: [])
+                           end
         @a11y = detect(A11yAudit.new(**common))
-        @patterns = detect(CrossCodebasePatterns.new(**common, **@pattern_opts))
-        @classitis = detect(ClassItis.new(**common, **@classitis_opts))
-        @a11y_deep_runner = @axe_json ? A11yDeep.new(input: @axe_json, output: @sink, style: @style) : nil
+        @patterns = wanted?(:suggestion) ? detect(CrossCodebasePatterns.new(**common, **@pattern_opts)) : []
+        @classitis = wanted?(:suggestion) ? detect(ClassItis.new(**common, **@classitis_opts)) : []
+        @a11y_deep_runner = if @axe_json
+                              A11yDeep.new(input: @axe_json, output: @sink, style: @style, min_severity: @min_severity)
+                            end
         @a11y_deep = @a11y_deep_runner ? detect(@a11y_deep_runner) : []
         @visual_diff_runner = @visual_diff_on ? VisualDiff.new(**common) : nil
         @visual_diff = @visual_diff_runner ? detect(@visual_diff_runner) : []
         self
       end
 
+      # Severities this run didn't look at (empty by default).
+      def muted_severities
+        Severity.muted(@min_severity)
+      end
+
       # Every finding as detector-agnostic data (see Report::Finding),
       # grouped by category and ordered errors → warnings →
       # suggestions, biggest category first — the same order the
@@ -208,6 +229,10 @@ module Guardrails
         result
       end
 
+      def wanted?(severity)
+        Severity.include?(severity, @min_severity)
+      end
+
       def common
         { root: @root, output: @sink, style: @style }
       end

data/lib/guardrails/report/severity.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "summary"
+
+module Guardrails
+  module Report
+    # The severity floor behind SEVERITY=: "only tell me about findings
+    # at least this serious". `:suggestion` (the default) is everything;
+    # `:warning` mutes suggestions; `:error` mutes warnings too.
+    module Severity
+      ORDER = Summary::SEVERITY_ORDER
+      DEFAULT = :suggestion
+
+      NAMES = {
+        "error" => :error, "errors" => :error,
+        "warning" => :warning, "warnings" => :warning,
+        "suggestion" => :suggestion, "suggestions" => :suggestion, "suggest" => :suggestion, "all" => :suggestion
+      }.freeze
+
+      module_function
+
+      # nil / blank is "not set", not an error — same blank-env
+      # tolerance as the VISUAL_DIFF_* vars.
+      def parse(value)
+        text = value.to_s.strip.downcase
+        return DEFAULT if text.empty?
+
+        NAMES.fetch(text) do
+          raise ArgumentError, "SEVERITY=#{value} isn't a severity. Use error, warning, or suggestion."
+        end
+      end
+
+      def include?(severity, floor)
+        ORDER.index(severity) <= ORDER.index(floor)
+      end
+
+      # The severities a floor hides, most serious first.
+      def muted(floor)
+        ORDER.reject { |severity| include?(severity, floor) }
+      end
+    end
+  end
+end

data/lib/guardrails/tokens.rb

@@ -20,6 +20,15 @@ module Guardrails
       "app/assets/tailwind/**/*.css"
     ].freeze
 
+    # Where a Tailwind v3 config lives when `tokens.tailwind_config` isn't
+    # set. The repo root is the JS-first convention; `config/` is what
+    # `tailwindcss-rails` (the official Rails integration) generates for
+    # every Tailwind v3 app. First match wins.
+    TAILWIND_CONFIG_CANDIDATES = %w[
+      tailwind.config.js
+      config/tailwind.config.js
+    ].freeze
+
     # Same path-component skip-list as Audit / StackDetector — vendor
     # stylesheets nested under app/assets/stylesheets/ shouldn't surface
     # as drift since they're typically third-party.
@@ -59,8 +68,8 @@ module Guardrails
       # the config no longer matches the preset pattern.
       @tailwind_preset_hint = nil
 
-      file = @root.join("tailwind.config.js")
-      return [] unless file.exist?
+      file = tailwind_config_path
+      return [] unless file&.exist?
 
       content = File.read(file, encoding: Encoding::UTF_8)
       entries = TailwindConfigParser.parse(content)
@@ -72,7 +81,7 @@ module Guardrails
       # tailwind.config.js does `module.exports = { presets: [preset] }`.
       if entries.empty? && tailwind_uses_presets?(content)
         @tailwind_preset_hint =
-          "tailwind.config.js uses a `presets:` import; only the literal config file " \
+          "#{file.relative_path_from(@root)} uses a `presets:` import; only the literal config file " \
             "is parsed (we don't evaluate JS). Define non-color tokens in v4 `@theme` " \
             "blocks for cross-tool token visibility."
       end
@@ -91,11 +100,10 @@ module Guardrails
     def detect_drift(tokens)
       lookup = tokens.to_h { |t| [HexNormalizer.normalize(t.value), t] }
       drift = []
-      definition_files = [colors_file, type_scale_file].compact
+      definition_files = [colors_file, type_scale_file, tailwind_config_path].compact
 
       stylesheets.each do |file|
         next if definition_files.include?(file)
-        next if file == @root.join("tailwind.config.js")
 
         raw_content = File.read(file, encoding: Encoding::UTF_8)
         content = strip_comments(raw_content)
@@ -118,6 +126,19 @@ module Guardrails
       drift
     end
 
+    # The Tailwind v3 config to parse, or nil when there isn't one.
+    # `tokens.tailwind_config` in guardrails.yml wins (needed for `.cjs` /
+    # `.ts` configs or monorepo layouts); otherwise the first existing
+    # candidate path is used.
+    def tailwind_config_path
+      configured = configured_token_file("tailwind_config")
+      return configured if configured
+
+      TAILWIND_CONFIG_CANDIDATES
+        .map { |relative| @root.join(relative) }
+        .find(&:exist?)
+    end
+
     private
 
     def tailwind_uses_presets?(content)
@@ -221,12 +242,13 @@ module Guardrails
         ["tokens.type_scale_file", type_scale_file]
       ].select { |_key, path| path }
 
-      tailwind_path = @root.join("tailwind.config.js")
-      tailwind_source = tailwind_path.exist? ? tailwind_path : nil
+      tailwind_path = tailwind_config_path
+      tailwind_source = tailwind_path&.exist? ? tailwind_path : nil
       all_sources = configured_entries.map { |_, p| p } + [tailwind_source].compact
 
       if all_sources.empty?
         @output.puts "Guardrails tokens: no colors_file, type_scale_file, or tailwind.config.js found"
+        @output.puts "  → Looked for #{TAILWIND_CONFIG_CANDIDATES.join(' and ')}; set tokens.tailwind_config in guardrails.yml for other locations."
         return
       end
 

data/lib/guardrails/tui.rb

@@ -90,7 +90,7 @@ module Guardrails
     end
 
     def open_web_report
-      path = Report::Html.new(categories: @run.categories, root: @root).write
+      path = Report::Html.new(categories: @run.categories, root: @root, muted: @run.muted_severities).write
       opener = Editor.opener(path.to_s)
       opened = opener && system(*opener, out: File::NULL, err: File::NULL)
       @state.notice = "#{opened ? 'Opened' : 'Wrote'} #{path.relative_path_from(Pathname(@root).expand_path)}"

data/lib/guardrails/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Guardrails
-  VERSION = "1.3.0"
+  VERSION = "1.5.0"
 end

data/lib/tasks/guardrails.rake

@@ -9,7 +9,7 @@ namespace :guardrails do
     Guardrails::Init.new(root: root, force: force).run
   end
 
-  desc "Audit views and components for UI drift (SUGGEST=1, APPLY=1, FORMAT=json|html)"
+  desc "Audit views and components for UI drift (SUGGEST=1, APPLY=1, FORMAT=json|html, SEVERITY=error|warning)"
   task :audit do
     require "guardrails/report/run"
     require "guardrails/report/style"
@@ -22,7 +22,11 @@ namespace :guardrails do
     # (see Report::Run). JSON and HTML modes discard the report body,
     # so they run unstyled.
     report_style = format == :text ? Guardrails::Report::Style.new(io: $stdout) : nil
-    run = Guardrails::Report::Run.from_env(root: root, style: report_style).call
+    run = begin
+      Guardrails::Report::Run.from_env(root: root, style: report_style).call
+    rescue ArgumentError => e
+      abort e.message
+    end
 
     if format == :json
       require "json"
@@ -32,7 +36,7 @@ namespace :guardrails do
       # CI artifact. OUTPUT= overrides the default tmp/ location.
       require "guardrails/report/html"
       output = ENV["OUTPUT"].to_s.strip
-      path = Guardrails::Report::Html.new(categories: run.categories, root: root)
+      path = Guardrails::Report::Html.new(categories: run.categories, root: root, muted: run.muted_severities)
                                      .write(output.empty? ? Guardrails::Report::Html::DEFAULT_PATH : output)
       $stdout.puts "Guardrails audit: #{run.findings.length} findings → #{path}"
     else
@@ -45,6 +49,13 @@ namespace :guardrails do
       summary.render
       $stdout.write run.body
       summary.render(recap: true)
+      # A filtered run that prints "no violations found" must not read
+      # as a clean bill of health.
+      unless run.muted_severities.empty?
+        muted = run.muted_severities.map { |s| "#{s}s" }.join(" and ")
+        $stdout.puts ""
+        $stdout.puts report_style.colorize("SEVERITY=#{run.min_severity} — #{muted} were not checked.", :dim)
+      end
     end
 
     exit 1 if run.failing?
@@ -63,7 +74,7 @@ namespace :guardrails do
     runner = -> { Guardrails::Report::Run.from_env(root: root, env: env).call }
     begin
       Guardrails::TUI.new(runner: runner, root: root).start
-    rescue Guardrails::TUI::NotInteractive => e
+    rescue Guardrails::TUI::NotInteractive, ArgumentError => e
       abort e.message
     end
   end
@@ -96,11 +107,25 @@ namespace :guardrails do
     exit 1 if runner.any_failing?(findings)
   end
 
-  desc "Generate SVG icon sprite and audit icon usage"
+  desc "Generate SVG icon sprite and audit icon usage (SUGGEST=1, FORMAT=json) — exits 1 on inline SVGs, unknown icon refs, or emoji/glyph icons"
   task :icons do
     require "guardrails/icons"
+    require "stringio"
     root = defined?(Rails) ? Rails.root : Pathname(Dir.pwd)
-    Guardrails::Icons.new(root: root).run
+    suggest = %w[1 true yes].include?(ENV["SUGGEST"]&.downcase)
+    format = ENV["FORMAT"].to_s.downcase == "json" ? :json : :text
+
+    if format == :json
+      # Suppress human-readable output; only JSON goes to stdout.
+      require "json"
+      result = Guardrails::Icons.new(root: root, output: StringIO.new,
+                                     suggest: suggest, format: :json).run
+      $stdout.puts JSON.pretty_generate(result.to_h)
+    else
+      result = Guardrails::Icons.new(root: root, suggest: suggest).run
+    end
+
+    exit 1 if result.violations?
   end
 
   desc "Audit design tokens and report drift"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ui_guardrails
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.5.0
 platform: ruby
 authors:
 - John Athayde
@@ -95,6 +95,7 @@ files:
 - lib/guardrails/erb_parser.rb
 - lib/guardrails/hex_normalizer.rb
 - lib/guardrails/icons.rb
+- lib/guardrails/icons/emoji_scan.rb
 - lib/guardrails/init.rb
 - lib/guardrails/init/config_writer.rb
 - lib/guardrails/init/media_query_scaffolder.rb
@@ -109,6 +110,7 @@ files:
 - lib/guardrails/report/html.rb
 - lib/guardrails/report/html/template.html.erb
 - lib/guardrails/report/run.rb
+- lib/guardrails/report/severity.rb
 - lib/guardrails/report/style.rb
 - lib/guardrails/report/summary.rb
 - lib/guardrails/stimulus_audit.rb