ui_guardrails 1.7.0 → 2.0.0.rc1

data/doc/ROADMAP.md

@@ -1,7 +1,7 @@
 # Guardrails — Roadmap
 
-**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
+**Status:** **2.0.0: Feed Ramp.** V0 ✅, V1 ✅, V2 ✅ (the originally-planned roadmap, published as 1.0.0). Post-1.0 releases were about reading findings (1.1–1.4), then new findings and agent hooks (1.5–1.7). 2.0 moves upstream of the audit: it hands coding agents the app's component library before they write markup (manifest, agent rules, MCP server), flags markup that copies a component, and scores drift for before/after comparisons.
+**Last updated:** 2026-10-19
 
 ## Context
 
@@ -13,7 +13,7 @@ This doc tracks shipped vs. planned scope and parks remaining unknowns. V0 + mos
 
 ## V0 — Foundation
 
-### Audit (`rails guardrails:audit`)
+### Audit (`rails ui_guardrails:audit`)
 
 | Item | Status | Notes |
 |---|---|---|
@@ -41,7 +41,7 @@ This doc tracks shipped vs. planned scope and parks remaining unknowns. V0 + mos
 | `inline_style` auto-fix | ❌ deferred | Structural rewrite, not value swap |
 | `font-size` auto-fix | ❌ deferred | Same constraint as inline_style |
 
-### Icons (`rails guardrails:icons`)
+### Icons (`rails ui_guardrails:icons`)
 
 | Item | Status |
 |---|---|
@@ -49,7 +49,7 @@ This doc tracks shipped vs. planned scope and parks remaining unknowns. V0 + mos
 | Inline `<svg>` detection in views | ✅ shipped |
 | Dead-icon report | ✅ shipped |
 
-### Init / analysis (`rails guardrails:init`)
+### Init / analysis (`rails ui_guardrails:init`)
 
 | Item | Status | Notes |
 |---|---|---|
@@ -60,7 +60,7 @@ This doc tracks shipped vs. planned scope and parks remaining unknowns. V0 + mos
 | Refuse-overwrite by default | ✅ shipped | |
 | `FORCE=1` to overwrite + re-scaffold MQs | ✅ shipped | |
 
-### Tokens (`rails guardrails:tokens`)
+### Tokens (`rails ui_guardrails:tokens`)
 
 | Item | Status | Notes |
 |---|---|---|
@@ -99,7 +99,7 @@ This doc tracks shipped vs. planned scope and parks remaining unknowns. V0 + mos
 | Component-shape similarity | ✅ shipped | n-gram Jaccard, default threshold 0.7. PartialSimilarity scans both `_*.html.erb` partials and `*_component.html.erb` VC templates |
 | Lookbook integration | ✅ shipped (0.5.0) | `Guardrails::Lookbook::ComponentReport` data API + Railtie auto-registers the `:guardrails` panel when Lookbook is loaded; partial ships inside the gem. Host can override the partial via standard view-path precedence. |
 | ERB-partial structural similarity | ✅ shipped | Same PartialSimilarity engine |
-| A11y integration | ✅ shipped (0.6.0) | Static checks shipped (image_alt, button_name, link_name, input_label). button_name and link_name skip when the element body wraps ERB output — those cases get a `helper_recommended` finding instead. **Deep mode shipped via `Guardrails::A11yDeep`** — consumes axe-core JSON output (single or multi-page) and folds findings into the unified report. `AXE_JSON=path/to/axe.json bundle exec rake guardrails:audit` or `rake guardrails:a11y:deep`. Stayed parse-only (no Capybara / headless Chrome runtime deps) per the original size constraint. |
+| A11y integration | ✅ shipped (0.6.0) | Static checks shipped (image_alt, button_name, link_name, input_label). button_name and link_name skip when the element body wraps ERB output — those cases get a `helper_recommended` finding instead. **Deep mode shipped via `Guardrails::A11yDeep`** — consumes axe-core JSON output (single or multi-page) and folds findings into the unified report. `AXE_JSON=path/to/axe.json bundle exec rake ui_guardrails:audit` or `rake ui_guardrails:a11y:deep`. Stayed parse-only (no Capybara / headless Chrome runtime deps) per the original size constraint. |
 | `helper_recommended` detector | ✅ shipped | Flags `<button>` / `<a>` wrapping ERB output and suggests `tag.button` / `button_to` / `link_to`. Pairs with the a11y skip for the same case |
 | Targeted auto-fix | ✅ shipped | See V0 auto-fix table; tailwind_arbitrary now also auto-fixes when a `:tailwind` theme token matches |
 | Sample app in `examples/` | ✅ shipped (0.7.0) | Bootable Rails 7.2 app. `cd examples/demo && bundle install && bin/rails server` renders the seeded views and mounts Lookbook with the Guardrails panel auto-registered. Same tree the integration spec exercises. |
@@ -125,20 +125,40 @@ The planned roadmap ended at V2. Running the gem on real codebases (Patchvault:
 | 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. |
+| Interactive browser (`rake ui_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. |
+| 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. `ui_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. |
 | Visual-diff adapter registry | ✅ shipped (1.6.0) | `Guardrails::VisualDiff.register_adapter` lets other gems add adapters; the name is checked when the adapter is built. `VisualDiff::Finding` gains `status`, `comment`, `regions`, `extra_details`. First consumer: ui_guardrails-browser's `:browser` adapter. |
-| Coding agent hooks | ✅ shipped (1.7.0) | `rake guardrails:hooks:install` wires Claude Code, Codex, Cursor and Gemini CLI to `guardrails-hook`: drift an agent introduces (compared with `HEAD`) goes back to it after each edit, and new errors send it back once when it tries to finish. Other gems contribute through `Guardrails::Hooks.register`; ui_guardrails-browser adds visual-review rejections. |
+| Coding agent hooks | ✅ shipped (1.7.0) | `rake ui_guardrails:hooks:install` wires Claude Code, Codex, Cursor and Gemini CLI to `guardrails-hook`: drift an agent introduces (compared with `HEAD`) goes back to it after each edit, and new errors send it back once when it tries to finish. Other gems contribute through `Guardrails::Hooks.register`; ui_guardrails-browser adds visual-review rejections. |
 | Detector registry | ✅ shipped (1.7.0) | `Guardrails::Report::Detectors.register(name, klass)` adds a detector to `Report::Run`, so it reaches the text report, summary, JSON (under `extensions`), HTML and TUI. Each decides when it's on (`enabled?(env:)`), how serious it can get (`max_severity`, so `SEVERITY=` skips it), and when it fails. First consumer: ui_guardrails-browser's heuristic review. |
 | CI test workflow | ✅ shipped | `.github/workflows/test.yml` runs `bundle exec rspec` (including the `examples/demo` integration spec) and `gem build` on every pull request and push to `main`, on Ruby 3.4 (the floor) and 4.0. Floor regressions and packaging mistakes surface on the PR instead of at tag time. |
 
 ---
 
+## 2.0 — Feed Ramp
+
+The audit and the hooks catch drift after an agent has written it. Feed Ramp gives the agent the component library first, so there's less to catch.
+
+| Item | Status | Notes |
+|---|---|---|
+| Component manifest | ✅ shipped (2.0.0) | `ui_guardrails:feed_ramp:manifest` writes `.ui_guardrails/manifest.json` + `COMPONENTS.md` from ViewComponent and Phlex components, Lookbook / ViewComponent previews, call sites and tokens. Prism-parsed, deterministic, examples copied verbatim, never invented. `CHECK=1` compares content, so view edits don't make it stale. |
+| Agent rules | ✅ shipped (2.0.0) | Marker-delimited block in `CLAUDE.md` / `AGENTS.md` (+ opt-in `GEMINI.md`, Copilot), owned `.cursor/rules/ui-guardrails.mdc`. Idempotent; broken markers stop the run; `REMOVE=1`. |
+| Drift score | ✅ shipped (2.0.0) | `ui_guardrails:feed_ramp:score`: issues per 100 templates in three buckets, saved runs, `BASELINE=` deltas. Never fails. |
+| `component_match` | ✅ shipped (2.0.0) | Audit rule, silent without a manifest. Matches a component's signature class on any tag, or its root tag with ≥80% of a 3+ class list. Warning by default, configurable down to suggestion. |
+| MCP server | ✅ shipped (2.0.0) | `ui_guardrails-mcp`: `list_components`, `get_component`, `search_components`, `check_snippet` (drift + component API checks). Hand-rolled JSON-RPC over stdio, no new dependency. |
+| Dynamic component roots | ✅ shipped (2.0.0) | Root classes built by helpers (`class_names`, `build_css`), attribute methods, `attrs[:class] =` and `tag.attributes(**…)` are read statically. Before this, `component_match` found nothing on three real ViewComponent apps. A signature class matches on any tag. |
+| Lookbook `preview_paths` from Rails config | ✅ shipped (2.0.0) | `config.view_component.previews.paths` / `preview_paths` / `config.lookbook.preview_paths` in `config/application.rb` and the development / test environments, read with Prism. Paths computed at boot still go in `guardrails.yml`. |
+| Phlex kit calls as examples | ✅ shipped (2.0.0) | `Alert(...)` and `Components::Alert(...)` are usage examples and are checked by `check_snippet`. |
+| Codex MCP config | ✅ shipped (2.0.0) | `AGENT=codex` writes `[mcp_servers.ui_guardrails]` to `.codex/config.toml` (trusted projects only). |
+| `component_match` for components with argument-dependent roots | not started | A root whose classes all come from arguments, or from an `if` with different classes per branch, has no fingerprint. Rendering the previews would give one, but that means booting the app. |
+| Composed roots | not started | A component whose root is another component (`render DialogComponent.new(class: "nav-drawer")`) gets no root element; following the inner component's root plus the extra class would cover it. |
+
+---
+
 ## Decisions Captured
 
 | Question | Decision |

data/doc/VISUAL-DIFF.md

@@ -14,16 +14,16 @@ In a Rails app with `snap_diff-capybara` installed and system tests that call `s
 bundle exec rspec spec/system/
 
 # Then fold the visual-diff findings into the unified audit:
-VISUAL_DIFF=1 bundle exec rake guardrails:audit
+VISUAL_DIFF=1 bundle exec rake ui_guardrails:audit
 
 # Or run the visual check standalone:
-bundle exec rake guardrails:visual:deep
+bundle exec rake ui_guardrails:visual:deep
 ```
 
 If the diffs sit somewhere other than `doc/screenshots/`:
 
 ```bash
-VISUAL_DIFF_DIR=spec/screenshots bundle exec rake guardrails:visual:deep
+VISUAL_DIFF_DIR=spec/screenshots bundle exec rake ui_guardrails:visual:deep
 ```
 
 To tolerate small mismatches (when the adapter emits a numeric ratio — snap_diff currently emits only a binary pass/fail, see "Adapter limits" below):
@@ -31,7 +31,7 @@ To tolerate small mismatches (when the adapter emits a numeric ratio — snap_di
 ```bash
 # VISUAL_DIFF=1 still needs to be set — VISUAL_DIFF_THRESHOLD alone
 # doesn't enable the check, just tunes it.
-VISUAL_DIFF=1 VISUAL_DIFF_THRESHOLD=0.02 bundle exec rake guardrails:audit
+VISUAL_DIFF=1 VISUAL_DIFF_THRESHOLD=0.02 bundle exec rake ui_guardrails:audit
 ```
 
 ## Configuration
@@ -49,13 +49,13 @@ Guardrails.configure do |c|
 end
 ```
 
-With `enabled = true`, `rake guardrails:audit` always runs the visual-diff check; no need to set `VISUAL_DIFF=1` on each invocation.
+With `enabled = true`, `rake ui_guardrails:audit` always runs the visual-diff check; no need to set `VISUAL_DIFF=1` on each invocation.
 
 ### Sidecar (no Gemfile change) — environment variables
 
 | Var | Effect |
 |---|---|
-| `VISUAL_DIFF=1` | Enable visual-diff on `rake guardrails:audit` (the standalone `guardrails:visual:deep` task is always enabled). |
+| `VISUAL_DIFF=1` | Enable visual-diff on `rake ui_guardrails:audit` (the standalone `ui_guardrails:visual:deep` task is always enabled). |
 | `VISUAL_DIFF_DIR=path` | Override the snap_diff baseline directory (default `doc/screenshots`). |
 | `VISUAL_DIFF_THRESHOLD=0.02` | Per-finding mismatch ratio above which the audit fails. Currently only meaningful for adapters that emit numeric ratios — snap_diff is binary. |
 
@@ -99,7 +99,7 @@ Each finding carries:
 
 ## JSON output
 
-When `FORMAT=json` is set on `guardrails:audit`, visual-diff findings appear under `visual_diff:`:
+When `FORMAT=json` is set on `ui_guardrails:audit`, visual-diff findings appear under `visual_diff:`:
 
 ```json
 {
@@ -132,7 +132,7 @@ A complete CI loop, end-to-end:
   continue-on-error: true  # don't fail the job here — let Guardrails report
 
 - name: Guardrails audit
-  run: VISUAL_DIFF=1 bundle exec rake guardrails:audit FORMAT=json > findings.json
+  run: VISUAL_DIFF=1 bundle exec rake ui_guardrails:audit FORMAT=json > findings.json
 
 - name: Upload findings + diff images
   if: always()

data/exe/guardrails-hook

@@ -2,7 +2,7 @@
 # frozen_string_literal: true
 
 # Called by a coding agent's hooks: `guardrails-hook <agent> <event>`,
-# with the agent's hook input on stdin. `rake guardrails:hooks:install`
+# with the agent's hook input on stdin. `rake ui_guardrails:hooks:install`
 # writes the agent configuration that calls it.
 require "guardrails"
 require "guardrails/hooks/runner"

data/exe/ui_guardrails-mcp

@@ -0,0 +1,32 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# The Feed Ramp MCP server, over stdio: `ui_guardrails-mcp [--root DIR]
+# [--no-write]`. `rake ui_guardrails:feed_ramp:mcp:install` writes the
+# agent configuration that starts it.
+require "optparse"
+
+root = Dir.pwd
+write = true
+OptionParser.new do |opts|
+  opts.banner = "Usage: ui_guardrails-mcp [--root DIR] [--no-write]"
+  opts.on("--root DIR", "The Rails app (default: the current directory)") { |dir| root = dir }
+  opts.on("--[no-]write", "Rewrite .ui_guardrails/ when the components change (default: on)") { |value| write = value }
+  opts.on("-v", "--version") do
+    require "guardrails/version"
+    puts Guardrails::VERSION
+    exit
+  end
+end.parse!
+
+# Stdout carries the protocol and nothing else: keep it for the server,
+# and send anything else that prints there to stderr.
+protocol = $stdout
+protocol.sync = true
+$stdout = $stderr
+
+require "guardrails"
+require "guardrails/feed_ramp/mcp"
+
+library = Guardrails::FeedRamp::MCP::Library.new(root: root, write: write)
+Guardrails::FeedRamp::MCP::Server.new(library: library, input: $stdin, output: protocol).run

data/lib/guardrails/a11y_deep.rb

@@ -19,7 +19,7 @@ module Guardrails
   # CDP-driven script) and pass the JSON output to Guardrails:
   #
   #     npx @axe-core/cli http://localhost:3000/ --save axe.json
-  #     AXE_JSON=axe.json bundle exec rake guardrails:audit
+  #     AXE_JSON=axe.json bundle exec rake ui_guardrails:audit
   #
   # The result is a single unified report — static findings from
   # A11yAudit plus runtime findings from axe — with the same exit-code

data/lib/guardrails/audit/markdown_writer.rb

@@ -25,6 +25,10 @@ module Guardrails
         helper_recommended: {
           rule: "Wrapping ERB output in a literal element hides intent from static analysis and a11y tooling.",
           replacement: "Use the Rails helper for this element so attributes (including aria-*) flow through one place."
+        },
+        component_match: {
+          rule: "This markup copies one of your components; render the component so changes to it reach every use.",
+          replacement: "Render the component (see .ui_guardrails/COMPONENTS.md for its params and an example)."
         }
       }.freeze
 
@@ -151,6 +155,7 @@ module Guardrails
       end
 
       def helper_specific_replacement(violation)
+        return "Render `#{violation.value}` (see .ui_guardrails/COMPONENTS.md for its params and an example)." if violation.type == :component_match
         return nil unless violation.type == :helper_recommended
 
         HELPER_REPLACEMENTS[violation.value]

data/lib/guardrails/audit.rb

@@ -3,8 +3,10 @@
 require "pathname"
 require "set"
 require "stringio"
+require "json"
 require "yaml"
 require_relative "erb_parser"
+require_relative "feed_ramp/config"
 require_relative "report/style"
 require_relative "report/finding"
 require_relative "report/severity"
@@ -89,7 +91,7 @@ module Guardrails
       # 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)
+        reported?(v.type)
       end
       print_report(violations)
       remaining = @apply ? apply_auto_fixes(violations) : violations
@@ -106,7 +108,7 @@ module Guardrails
         list = by_type[type]
         next if list.nil? || list.empty?
 
-        severity = SEVERITY_FOR_TYPE.fetch(type, :warning)
+        severity = severity_for(type)
         auto_fix = AUTO_FIXABLE_TYPES.include?(type)
         Report::Category.new(
           name: type.to_s, severity: severity, framing: FRAMING_FOR_TYPE[type], auto_fix: auto_fix,
@@ -129,7 +131,7 @@ module Guardrails
     # check scan_paths or ignores; ask `covers?` first.
     def scan_source(path, content = nil)
       scan_file(Pathname(path).expand_path(@root), content).select do |v|
-        Report::Severity.include?(SEVERITY_FOR_TYPE.fetch(v.type, :warning), @min_severity)
+        reported?(v.type)
       end
     end
 
@@ -142,6 +144,20 @@ module Guardrails
       scan_paths.any? { |dir| path.to_s.start_with?("#{@root.join(dir)}/") } && !ignored?(path)
     end
 
+    # A violation type's severity: fixed per type, except
+    # `component_match`, set by `feed_ramp.component_match` in
+    # guardrails.yml (nil when it's off).
+    def severity_for(type)
+      return component_match_settings.severity if type == :component_match
+
+      SEVERITY_FOR_TYPE.fetch(type, :warning)
+    end
+
+    # The templates a full run scans, relative to root.
+    def templates
+      collect_files.map { |path| relative(path) }.sort
+    end
+
     private
 
     def load_audit_config
@@ -191,7 +207,97 @@ module Guardrails
       detect_inline_styles_ast(ast_result, file, original_lines) +
         detect_raw_color_literals_ast(ast_result, file, original_lines) +
         detect_tailwind_arbitrary_ast(ast_result, file, original_lines) +
-        detect_helper_recommended_ast(ast_result, file, original_lines)
+        detect_helper_recommended_ast(ast_result, file, original_lines) +
+        detect_component_match_ast(ast_result, file, original_lines)
+    end
+
+    def reported?(type)
+      severity = severity_for(type)
+      !severity.nil? && Report::Severity.include?(severity, @min_severity)
+    end
+
+    def component_match_settings
+      @component_match_settings ||= FeedRamp::Config.load(@root).component_match
+    end
+
+    # Components to match markup against: those in the committed Feed
+    # Ramp manifest whose root element is recognisable, by enough static
+    # classes or by a class named after the component. None without a
+    # manifest, so the rule is silent until
+    # `ui_guardrails:feed_ramp:manifest` has been run.
+    def matchable_components
+      @matchable_components ||= begin
+        path = FeedRamp::Config.load(@root).manifest_path(@root)
+        components = path.file? ? Array(JSON.parse(path.read)["components"]) : []
+        components.select do |component|
+          root = component["root_element"]
+          next false unless root.is_a?(Hash)
+
+          Array(root["classes"]).length >= component_match_settings.min_classes || signature_class(component)
+        end
+      rescue JSON::ParserError, SystemCallError
+        []
+      end
+    end
+
+    # Elements carrying the root tag and most of the root classes of an
+    # existing component: markup that should be a `render` of it. One
+    # finding per element, for the component it covers best. A
+    # component's own template is never matched against itself.
+    def detect_component_match_ast(parse_result, file, original_lines)
+      return [] if severity_for(:component_match).nil? || matchable_components.empty?
+
+      path = relative(file)
+      results = []
+      ErbParser.each_node(parse_result.document) do |node|
+        next unless node.is_a?(::Herb::AST::HTMLElementNode)
+
+        tag = ErbParser.tag_name(node)
+        classes = ErbParser.static_classes(node)
+        next if tag.nil? || classes.empty?
+
+        match = best_component_match(tag, classes, path)
+        next unless match
+
+        line, column = ErbParser.start_position(node)
+        results << Violation.new(type: :component_match, file: path, line: line, column: column,
+                                 snippet: snippet(original_lines, line - 1), value: match["name"])
+      end
+      results
+    end
+
+    # The component its markup matches best: its signature class on any
+    # tag (a component may render a link or a button), or the same tag
+    # with most of a long-enough class list.
+    def best_component_match(tag, classes, path)
+      settings = component_match_settings
+      scored = matchable_components.filter_map do |component|
+        root = component["root_element"]
+        next if component["template"] == path
+
+        wanted = root["classes"]
+        coverage = (classes & wanted).length.fdiv(wanted.length)
+        by_classes = root["tag"] == tag && wanted.length >= settings.min_classes && coverage >= settings.coverage
+        by_signature = classes.include?(signature_class(component))
+        [component, coverage, wanted.length] if by_classes || by_signature
+      end
+      scored.min_by { |component, coverage, size| [-coverage, -size, component["name"]] }&.first
+    end
+
+    # The root class named after the component (`button` or
+    # `button-component` for ButtonComponent, `icon-button` /
+    # `icon_button` for IconButtonComponent, `alert` for
+    # Components::Alert), which marks markup as that component's even
+    # when it's the only class. nil when the root has none.
+    def signature_class(component)
+      @signature_classes ||= {}
+      @signature_classes.fetch(component["name"]) do
+        words = component["name"].to_s.split("::").last.to_s
+                                 .gsub(/([a-z\d])([A-Z])/, '\1_\2').gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2').downcase
+        base = words.delete_suffix("_component")
+        names = [base, words].uniq.flat_map { |name| [name.tr("_", "-"), name] }.uniq
+        @signature_classes[component["name"]] = (Array(component.dig("root_element", "classes")) & names).first
+      end
     end
 
     # AST-based inline_style detector. Walks the parsed document for
@@ -524,7 +630,7 @@ module Guardrails
       end
     end
 
-    TYPE_ORDER = %i[inline_style raw_color tailwind_arbitrary helper_recommended
+    TYPE_ORDER = %i[inline_style raw_color tailwind_arbitrary helper_recommended component_match
                     image_alt button_name link_name input_label].freeze
 
     SEVERITY_FOR_TYPE = {
@@ -532,6 +638,7 @@ module Guardrails
       raw_color: :error,
       tailwind_arbitrary: :error,
       helper_recommended: :warning,
+      component_match: :warning,
       image_alt: :error,
       button_name: :error,
       link_name: :error,
@@ -543,6 +650,7 @@ module Guardrails
       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.",
+      component_match: "Hand-written markup with the root element and classes of one of your components. Render the component instead, so a change to it reaches every use. Components come from the Feed Ramp manifest (rake ui_guardrails:feed_ramp:manifest).",
       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.",
@@ -552,7 +660,7 @@ module Guardrails
     AUTO_FIXABLE_TYPES = %i[raw_color tailwind_arbitrary].freeze
 
     def print_violation_type(type, violations)
-      severity = SEVERITY_FOR_TYPE.fetch(type, :warning)
+      severity = severity_for(type)
       auto_fix_marker = AUTO_FIXABLE_TYPES.include?(type) ? ", auto-fix available" : ""
 
       @output.puts ""
@@ -580,6 +688,9 @@ module Guardrails
         violation.value
       when :inline_style
         violation.value || "<inline style>"
+      when :component_match
+        open_tag = violation.snippet.to_s[/<[^>]*>/] || violation.snippet.to_s.strip
+        "#{open_tag.length > 70 ? "#{open_tag[0, 69]}…" : open_tag} looks like #{violation.value}"
       else
         violation.snippet.to_s[0, 60]
       end
@@ -621,6 +732,8 @@ module Guardrails
         "extract to a CSS class or component stylesheet"
       when :helper_recommended
         helper_recommended_suggestion(violation)
+      when :component_match
+        component_match_suggestion(violation)
       when :image_alt
         "add an alt attribute (or alt=\"\" if decorative)"
       when :button_name
@@ -653,6 +766,16 @@ module Guardrails
       end
     end
 
+    # "render ButtonComponent", with the start of its usage example from
+    # the manifest when it has one.
+    def component_match_suggestion(violation)
+      component = matchable_components.find { |c| c["name"] == violation.value }
+      example = component&.dig("example", "source").to_s.lines.first.to_s.strip
+      return "render #{violation.value} instead" if example.empty?
+
+      "render #{violation.value} instead, e.g. #{example.length > 90 ? "#{example[0, 89]}…" : example}"
+    end
+
     def helper_recommended_suggestion(violation)
       tag = violation.snippet.to_s[/<(\w+)/, 1]
       case tag

data/lib/guardrails/class_itis.rb

@@ -142,54 +142,11 @@ module Guardrails
     end
 
     def element_tag_name(element)
-      return nil unless element.respond_to?(:open_tag) && element.open_tag
-
-      tok = element.open_tag.tag_name
-      tok && tok.respond_to?(:value) ? tok.value.to_s.downcase : nil
+      ErbParser.tag_name(element)
     end
 
-    # Pull the static portion of the element's `class` attribute. If
-    # the attribute is missing, ERB-driven, or empty, returns []. ERB
-    # fragments inside a class attribute are dropped (we can't know
-    # what they'll render); the literal pieces are concatenated and
-    # whitespace-tokenized. Tokens are sorted so two identical lists
-    # in different source order produce the same fingerprint key.
     def static_class_tokens(element)
-      attr = class_attribute_node(element)
-      return [] unless attr
-
-      static = static_attribute_value(attr)
-      return [] if static.nil? || static.strip.empty?
-
-      static.split(/\s+/).reject(&:empty?).sort.uniq
-    end
-
-    def class_attribute_node(element)
-      open_children = ErbParser.compact_children(element.open_tag)
-      open_children.find do |child|
-        next false unless child.is_a?(::Herb::AST::HTMLAttributeNode)
-
-        name_wrapper, _value_wrapper = ErbParser.compact_children(child)
-        next false unless name_wrapper
-
-        literal = ErbParser.compact_children(name_wrapper).first
-        next false unless literal && literal.respond_to?(:content)
-
-        name = literal.content.respond_to?(:value) ? literal.content.value.to_s : literal.content.to_s
-        name.downcase == "class"
-      end
-    end
-
-    def static_attribute_value(attribute_node)
-      _name_wrapper, value_wrapper = ErbParser.compact_children(attribute_node)
-      return nil unless value_wrapper
-
-      ErbParser.compact_children(value_wrapper).filter_map do |child|
-        next unless child.is_a?(::Herb::AST::LiteralNode)
-
-        content = child.content
-        content.respond_to?(:value) ? content.value.to_s : content.to_s
-      end.join
+      ErbParser.static_classes(element)
     end
 
     def print_report(clusters)

data/lib/guardrails/erb_parser.rb

@@ -80,6 +80,59 @@ module Guardrails
       end
     end
 
+    # An element's tag name, downcased, or nil.
+    def tag_name(element)
+      return nil unless element.respond_to?(:open_tag) && element.open_tag
+
+      tok = element.open_tag.tag_name
+      tok.respond_to?(:value) ? tok.value.to_s.downcase : nil
+    end
+
+    # The static portion of an element's `class` attribute, as sorted,
+    # unique tokens. ERB fragments inside the attribute are dropped (we
+    # can't know what they'll render); a missing or ERB-only attribute
+    # gives [].
+    def static_classes(element)
+      attr = attribute(element, "class")
+      return [] unless attr
+
+      _name_wrapper, value_wrapper = compact_children(attr)
+      return [] unless value_wrapper
+
+      pieces = compact_children(value_wrapper).map do |child|
+        next nil unless child.is_a?(::Herb::AST::LiteralNode)
+
+        content = child.content
+        content.respond_to?(:value) ? content.value.to_s : content.to_s
+      end
+      class_tokens(pieces)
+    end
+
+    # Class tokens from a value written in pieces: strings, and nil for
+    # each dynamic part. A token touching a dynamic part (`btn--` in
+    # `btn--<%= variant %>`) isn't a class anyone can know, so it's left
+    # out.
+    def class_tokens(pieces)
+      pieces.map { |piece| piece.nil? ? "\0" : piece.delete("\0") }.join
+            .split(/\s+/).reject { |token| token.empty? || token.include?("\0") }.sort.uniq
+    end
+
+    # An element's attribute node by name, or nil.
+    def attribute(element, name)
+      return nil unless element.respond_to?(:open_tag) && element.open_tag
+
+      compact_children(element.open_tag).find do |child|
+        next false unless child.is_a?(::Herb::AST::HTMLAttributeNode)
+
+        name_wrapper, _value_wrapper = compact_children(child)
+        literal = name_wrapper && compact_children(name_wrapper).first
+        next false unless literal.respond_to?(:content)
+
+        text = literal.content.respond_to?(:value) ? literal.content.value.to_s : literal.content.to_s
+        text.downcase == name
+      end
+    end
+
     # Convert a Herb location to (line, column) for a node's start.
     # Herb uses 1-indexed lines and 0-indexed columns; Guardrails violations
     # use 1-indexed columns. This adjusts for that.