feat(audit): token-aware suggestions in markdown checklist

Adds a value field to Violation that detectors populate (raw color,
Tailwind arbitrary, inline style). MarkdownWriter accepts a tokens list
and matches each violation's value against defined token values using
shared HexNormalizer (case-folded, short-form expanded, alpha stripped).
When an exact match is found, the suggestion shows the concrete token
reference (var(--primary-500) or $primary) and points at the definition
file:line. Stock suggestions remain the fallback.

Audit#run loads tokens via Tokens#parse_tokens lazily and only when
SUGGEST=1 is set, so the default path is unaffected.

Tokens task and the new MarkdownWriter both consume HexNormalizer so
hex normalization stays consistent across the gem.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: jathayde

lib/guardrails/audit.rb

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
 
 require "pathname"
+require "stringio"
 
 module Guardrails
   class Audit
-    Violation = Struct.new(:type, :file, :line, :column, :snippet, keyword_init: true)
+    Violation = Struct.new(:type, :file, :line, :column, :snippet, :value, keyword_init: true)
 
     SCAN_PATTERNS = [
       "app/views/**/*.html.erb",
@@ -57,38 +58,41 @@ def scan_file(file)
     end
 
     def detect_inline_styles(content, file, original_lines)
-      scan_lines(content, INLINE_STYLE_PATTERN) do |idx, column|
+      scan_lines(content, INLINE_STYLE_PATTERN) do |idx, column, _line, match_text|
         Violation.new(
           type: :inline_style,
           file: relative(file),
           line: idx + 1,
           column: column,
-          snippet: snippet(original_lines, idx)
+          snippet: snippet(original_lines, idx),
+          value: match_text
         )
       end
     end
 
     def detect_raw_color_literals(content, file, original_lines)
-      violations = scan_lines(content, HEX_LITERAL_PATTERN) do |idx, column, line|
+      violations = scan_lines(content, HEX_LITERAL_PATTERN) do |idx, column, line, match_text|
         next unless inside_quoted_attribute?(line, column - 1)
 
         Violation.new(
           type: :raw_color,
           file: relative(file),
           line: idx + 1,
           column: column,
-          snippet: snippet(original_lines, idx)
+          snippet: snippet(original_lines, idx),
+          value: match_text
         )
       end
-      violations += scan_lines(content, RGB_LITERAL_PATTERN) do |idx, column, line|
+      violations += scan_lines(content, RGB_LITERAL_PATTERN) do |idx, column, line, match_text|
         next unless inside_quoted_attribute?(line, column - 1)
 
         Violation.new(
           type: :raw_color,
           file: relative(file),
           line: idx + 1,
           column: column,
-          snippet: snippet(original_lines, idx)
+          snippet: snippet(original_lines, idx),
+          value: match_text
         )
       end
       violations
@@ -105,12 +109,15 @@ def detect_tailwind_arbitrary(content, file, original_lines)
 
             class_value.scan(ARBITRARY_VALUE_PATTERN) do
               offset = Regexp.last_match.begin(0)
+              bracket_match = Regexp.last_match[0]
+              inner_value = bracket_match[1..-2] # strip [ and ]
               violations << Violation.new(
                 type: :tailwind_arbitrary,
                 file: relative(file),
                 line: idx + 1,
                 column: value_start + offset + 1,
-                snippet: snippet(original_lines, idx)
+                snippet: snippet(original_lines, idx),
+                value: inner_value
               )
             end
           end
@@ -123,8 +130,9 @@ def scan_lines(content, pattern)
       violations = []
       content.each_line.with_index do |line, idx|
         line.scan(pattern) do
-          column = Regexp.last_match.begin(0) + 1
-          violation = yield(idx, column, line)
+          m = Regexp.last_match
+          column = m.begin(0) + 1
+          violation = yield(idx, column, line, m[0])
           violations << violation if violation
         end
       end
@@ -163,7 +171,14 @@ def snippet(lines, idx)
 
     def write_suggestions(violations)
       require_relative "audit/markdown_writer"
-      MarkdownWriter.new(@root, output: @output).write(violations)
+      MarkdownWriter.new(@root, output: @output, tokens: load_tokens).write(violations)
+    end
+
+    def load_tokens
+      require_relative "tokens"
+      Tokens.new(root: @root, output: StringIO.new).parse_tokens
+    rescue StandardError
+      []
     end
 
     def print_report(violations)

lib/guardrails/audit/markdown_writer.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "pathname"
+require_relative "../hex_normalizer"
 
 module Guardrails
   class Audit
@@ -22,10 +23,11 @@ class MarkdownWriter
         }
       }.freeze
 
-      def initialize(root, output: $stdout, now: Time.now)
+      def initialize(root, output: $stdout, now: Time.now, tokens: [])
         @root = Pathname(root)
         @output = output
         @now = now
+        @token_lookup = tokens.to_h { |t| [HexNormalizer.normalize(t.value), t] }
       end
 
       def write(violations)
@@ -89,10 +91,31 @@ def format_type_section(type, violations)
         violations.each do |v|
           lines << "- [ ] **Line #{v.line}, col #{v.column}:** `#{v.snippet}`"
           lines << "  - **Rule:** #{suggestion[:rule]}"
-          lines << "  - **Suggested replacement:** #{suggestion[:replacement]}" unless suggestion[:replacement].empty?
+
+          matched = match_token(v)
+          if matched
+            lines << "  - **Suggested replacement:** Use `#{format_token_reference(matched)}` (matches token `#{matched.name}` defined in `#{matched.file}:#{matched.line}`)."
+          elsif !suggestion[:replacement].empty?
+            lines << "  - **Suggested replacement:** #{suggestion[:replacement]}"
+          end
         end
         lines.join("\n") + "\n"
       end
+
+      def match_token(violation)
+        return nil if violation.value.nil?
+        return nil if @token_lookup.empty?
+
+        @token_lookup[HexNormalizer.normalize(violation.value)]
+      end
+
+      def format_token_reference(token)
+        case token.syntax
+        when :css_var then "var(--#{token.name})"
+        when :scss_var then "$#{token.name}"
+        else token.name
+        end
+      end
     end
   end
 end

lib/guardrails/hex_normalizer.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Guardrails
+  module HexNormalizer
+    module_function
+
+    # Normalize a hex color literal for equality comparison:
+    # - lowercase
+    # - expand 3-char shorthand (#fa3 -> #ffaa33)
+    # - strip alpha channel (#ffaa3380 -> #ffaa33)
+    # - return non-hex input unchanged (after lowercasing)
+    def normalize(value)
+      v = value.to_s.downcase.strip
+      return v unless v.start_with?("#")
+
+      case v.length
+      when 4 # #fa3 -> #ffaa33
+        "#" + v[1..].chars.map { |c| c * 2 }.join
+      when 5 # #fa3a -> #ffaa33 (drop alpha)
+        ("#" + v[1..].chars.map { |c| c * 2 }.join)[0..6]
+      when 7 # #ffaa33 (canonical)
+        v
+      when 9 # #ffaa3380 -> #ffaa33
+        v[0..6]
+      else
+        v
+      end
+    end
+  end
+end

lib/guardrails/tokens.rb

@@ -2,6 +2,7 @@
 
 require "pathname"
 require "yaml"
+require_relative "hex_normalizer"
 
 module Guardrails
   class Tokens
@@ -42,7 +43,7 @@ def parse_tokens
     end
 
     def detect_drift(tokens)
-      lookup = tokens.to_h { |t| [normalize_hex(t.value), t] }
+      lookup = tokens.to_h { |t| [HexNormalizer.normalize(t.value), t] }
       drift = []
 
       stylesheets.each do |file|
@@ -60,7 +61,7 @@ def detect_drift(tokens)
               line: idx + 1,
               column: column,
               value: value,
-              matched_token: lookup[normalize_hex(value)]
+              matched_token: lookup[HexNormalizer.normalize(value)]
             )
           end
         end
@@ -112,24 +113,6 @@ def variable_definition_line?(line)
       line.match?(SCSS_VAR_PATTERN) || line.match?(CSS_VAR_PATTERN)
     end
 
-    def normalize_hex(value)
-      v = value.downcase.strip
-      return v unless v.start_with?("#")
-
-      case v.length
-      when 4 # #fa3 -> #ffaa33
-        "#" + v[1..].chars.map { |c| c * 2 }.join
-      when 5 # #fa3a -> #ffaa33 (strip alpha)
-        ("#" + v[1..].chars.map { |c| c * 2 }.join)[0..6]
-      when 7 # #ffaa33
-        v
-      when 9 # #ffaa3380 -> #ffaa33 (strip alpha)
-        v[0..6]
-      else
-        v
-      end
-    end
-
     def print_drift(drift)
       return if drift.empty?
 

spec/guardrails/audit/markdown_writer_spec.rb

@@ -5,15 +5,16 @@
 require "stringio"
 require "guardrails/audit"
 require "guardrails/audit/markdown_writer"
+require "guardrails/tokens"
 
 RSpec.describe Guardrails::Audit::MarkdownWriter do
   let(:root) { Pathname(Dir.mktmpdir) }
   let(:now) { Time.utc(2026, 5, 4, 16, 30, 0) }
   after { FileUtils.rm_rf(root) }
 
-  def violation(type:, file:, line: 1, column: 1, snippet: "x")
+  def violation(type:, file:, line: 1, column: 1, snippet: "x", value: nil)
     Guardrails::Audit::Violation.new(
-      type: type, file: file, line: line, column: column, snippet: snippet
+      type: type, file: file, line: line, column: column, snippet: snippet, value: value
     )
   end
 
@@ -86,4 +87,79 @@ def violation(type:, file:, line: 1, column: 1, snippet: "x")
       expect(output.string).to include("doc/guardrails-suggestions-20260504T163000Z.md")
     end
   end
+
+  describe "token-aware suggestions" do
+    def token(name:, value:, syntax: :scss_var, file: "tokens.scss", line: 1)
+      Guardrails::Tokens::Token.new(
+        name: name, value: value, syntax: syntax, file: file, line: line
+      )
+    end
+
+    it "suggests the matching token reference for raw_color when an exact match exists" do
+      v = violation(type: :raw_color, file: "app/views/x.html.erb", value: "#0066ff",
+                    snippet: '<svg fill="#0066ff"></svg>')
+      tokens = [token(name: "primary", value: "#0066ff", syntax: :scss_var)]
+
+      described_class.new(root, output: StringIO.new, now: now, tokens: tokens).write([v])
+
+      content = root.join("doc/guardrails-suggestions-20260504T163000Z.md").read(encoding: Encoding::UTF_8)
+      expect(content).to include("Use `$primary`")
+      expect(content).to include("matches token `primary`")
+    end
+
+    it "suggests var(--name) for CSS custom property tokens" do
+      v = violation(type: :raw_color, file: "app/views/x.html.erb", value: "#0066ff",
+                    snippet: '<svg fill="#0066ff"></svg>')
+      tokens = [token(name: "primary-500", value: "#0066ff", syntax: :css_var)]
+
+      described_class.new(root, output: StringIO.new, now: now, tokens: tokens).write([v])
+
+      content = root.join("doc/guardrails-suggestions-20260504T163000Z.md").read(encoding: Encoding::UTF_8)
+      expect(content).to include("Use `var(--primary-500)`")
+    end
+
+    it "matches normalized hex (case + short form)" do
+      v = violation(type: :raw_color, file: "app/views/x.html.erb", value: "#fa3",
+                    snippet: '<svg fill="#fa3"></svg>')
+      tokens = [token(name: "secondary", value: "#FFAA33")]
+
+      described_class.new(root, output: StringIO.new, now: now, tokens: tokens).write([v])
+
+      content = root.join("doc/guardrails-suggestions-20260504T163000Z.md").read(encoding: Encoding::UTF_8)
+      expect(content).to include("matches token `secondary`")
+    end
+
+    it "matches Tailwind arbitrary values against token values" do
+      v = violation(type: :tailwind_arbitrary, file: "app/views/x.html.erb", value: "#0066ff",
+                    snippet: '<div class="bg-[#0066ff]">x</div>')
+      tokens = [token(name: "primary", value: "#0066ff", syntax: :scss_var)]
+
+      described_class.new(root, output: StringIO.new, now: now, tokens: tokens).write([v])
+
+      content = root.join("doc/guardrails-suggestions-20260504T163000Z.md").read(encoding: Encoding::UTF_8)
+      expect(content).to include("matches token `primary`")
+    end
+
+    it "falls back to the stock suggestion when no token matches" do
+      v = violation(type: :raw_color, file: "app/views/x.html.erb", value: "#abcdef",
+                    snippet: '<svg fill="#abcdef"></svg>')
+      tokens = [token(name: "primary", value: "#0066ff")]
+
+      described_class.new(root, output: StringIO.new, now: now, tokens: tokens).write([v])
+
+      content = root.join("doc/guardrails-suggestions-20260504T163000Z.md").read(encoding: Encoding::UTF_8)
+      expect(content).to include("Use a CSS custom property or SCSS variable")
+      expect(content).not_to include("matches token")
+    end
+
+    it "uses stock suggestions when no tokens are provided" do
+      v = violation(type: :raw_color, file: "app/views/x.html.erb", value: "#0066ff",
+                    snippet: '<svg fill="#0066ff"></svg>')
+
+      described_class.new(root, output: StringIO.new, now: now).write([v])
+
+      content = root.join("doc/guardrails-suggestions-20260504T163000Z.md").read(encoding: Encoding::UTF_8)
+      expect(content).to include("Use a CSS custom property or SCSS variable")
+    end
+  end
 end