rails_accessibility_testing 1.5.3 → 1.5.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 58922a0f7334ba5695d55aeb1d02576e975504492d7ae47c1ae37552cba246c3
-  data.tar.gz: a07f66b20c17b6da10ef18518d58a20d4de9429f2fac3af7dc9e2505bf3d218e
+  metadata.gz: c200c81650bf10d4b74b6f8270aad8ee888ea42aa6b979bb3c38d15c28f34884
+  data.tar.gz: f650081313bc70c51f10a86e54ea189356bf27258c5e83a2e0e3ba72367478db
 SHA512:
-  metadata.gz: 5f12b4e6da01ca76d1deb3aba955f284915857bf003fa6cb7568b8be05ea78e2eb7dddaf94bbe89fbe665cf99afb951ffbb86517eb3ea4862084b767939e779a
-  data.tar.gz: f638f6fbc1a0e4f7f3405f2c49929172d364910ad8140be4b662e823ab3c734fcde487666ae9874d973ec6d2643cb97ca2dc33e4419f805be45b0e2dec8daa2e
+  metadata.gz: dbf1bf3b4d4ae115a82d46d5e331ce3538b7a48fea54e391b3e2701a8f6676042b9cc6dc719a185f7ce80d783803bd46ec5950acd156ead844dca9eb042c8c40
+  data.tar.gz: 24c012d81ec25267d948c661f8631c9c760d32793e5c3261e023d7d76e3ee65d72ee0c4ed871ced3fac1e0d82ec8646ee77920d166381fcec2acd5d53a12d312

data/ARCHITECTURE.md

@@ -49,6 +49,14 @@ rails_accessibility_testing/
 │   ├── First-Run Logic      # Optimizes initial vs subsequent runs
 │   └── Asset Change Detection # Tracks CSS/JS changes
 │
+├── Static Scanning System (NEW in 1.5.3)
+│   ├── StaticFileScanner    # Main orchestrator for file-based scanning
+│   ├── FileChangeTracker   # Tracks file modification times
+│   ├── ErbExtractor        # Converts ERB templates to HTML
+│   ├── StaticPageAdapter   # Makes Nokogiri look like Capybara
+│   ├── LineNumberFinder    # Maps HTML elements to ERB line numbers
+│   └── ViolationConverter  # Formats violations with line numbers
+│
 ├── Rails Integration
 │   ├── Railtie             # Rails initialization hooks
 │   ├── RSpec Integration    # RSpec helpers and matchers
@@ -74,6 +82,111 @@ rails_accessibility_testing/
     └── Doc Site             # Static documentation site
 ```
 
+#### Visual Architecture Diagram
+
+```mermaid
+graph TB
+    subgraph "Rails Application"
+        App[Your Rails App]
+        Tests[System Tests/Specs]
+        Views[Views & Partials]
+        Routes[Routes & Controllers]
+    end
+    
+    subgraph "Rails Accessibility Testing Gem"
+        Entry[Gem Entry Point]
+        Railtie[Rails Integration Layer]
+        
+        subgraph "Test Integration"
+            RSpec[RSpec Integration]
+            Minitest[Minitest Integration]
+            AutoHook[Automatic Test Hooks]
+        end
+        
+        subgraph "Core Engine"
+            RuleEngine[Rule Engine]
+            Checks[11+ Accessibility Checks]
+            Collector[Violation Collector]
+        end
+        
+        subgraph "Intelligence Layer"
+            ViewDetector[View File Detector]
+            PartialDetector[Partial Detection]
+            ChangeDetector[Change Detector]
+            Cache[Page Scanning Cache]
+        end
+        
+        subgraph "Static Scanning"
+            StaticScanner[Static File Scanner]
+            FileTracker[File Change Tracker]
+            ErbExtractor[ERB Extractor]
+            StaticAdapter[Static Page Adapter]
+            LineFinder[Line Number Finder]
+        end
+        
+        subgraph "Configuration"
+            YAMLConfig[YAML Config Loader]
+            Profiles[Profile Manager]
+            RubyConfig[Ruby Configuration]
+        end
+        
+        subgraph "Output & Reporting"
+            ErrorBuilder[Error Message Builder]
+            CLI[CLI Tool]
+            Reports[Reports & Logs]
+        end
+    end
+    
+    subgraph "Testing Tools"
+        Capybara[Capybara]
+        Selenium[Selenium WebDriver]
+        AxeCore[axe-core Engine]
+    end
+    
+    Tests --> RSpec
+    Tests --> Minitest
+    RSpec --> AutoHook
+    Minitest --> AutoHook
+    App --> Railtie
+    Entry --> Railtie
+    
+    AutoHook --> Cache
+    Cache --> ViewDetector
+    ViewDetector --> ChangeDetector
+    ChangeDetector --> RuleEngine
+    RuleEngine --> YAMLConfig
+    YAMLConfig --> Profiles
+    RuleEngine --> Checks
+    Checks --> Capybara
+    Capybara --> Selenium
+    Checks --> AxeCore
+    Checks --> ViewDetector
+    ViewDetector --> PartialDetector
+    PartialDetector --> Views
+    Checks --> Collector
+    Collector --> ErrorBuilder
+    ErrorBuilder --> Reports
+    
+    CLI --> RuleEngine
+    Routes --> ViewDetector
+    
+    StaticScanner --> FileTracker
+    StaticScanner --> ErbExtractor
+    ErbExtractor --> StaticAdapter
+    StaticAdapter --> RuleEngine
+    StaticScanner --> LineFinder
+    LineFinder --> ErrorBuilder
+    
+    style Entry fill:#ff6b6b
+    style RuleEngine fill:#4ecdc4
+    style Checks fill:#45b7d1
+    style ViewDetector fill:#96ceb4
+    style ErrorBuilder fill:#ffeaa7
+    style Cache fill:#a29bfe
+    style StaticScanner fill:#feca57
+    style FileTracker fill:#ff9ff3
+```
+
 ### Data Flow
 
 ```
@@ -99,6 +212,80 @@ Error Message Builder (with file paths)
 Test Failure / CLI Report
 ```
 
+#### Request Flow Sequence Diagram
+
+```mermaid
+sequenceDiagram
+    participant Dev as Developer
+    participant Test as Test Suite
+    participant Hook as Auto Hooks
+    participant Cache as Scan Cache
+    participant Detector as View Detector
+    participant Change as Change Detector
+    participant Engine as Rule Engine
+    participant Checks as 11 Check Modules
+    participant Capybara as Capybara/Browser
+    participant Collector as Violation Collector
+    participant Builder as Error Builder
+    participant Report as Test Report
+    
+    Dev->>Test: Run test suite
+    Test->>Hook: Execute system test
+    Hook->>Test: visit('/some/path')
+    Test->>Capybara: Load page
+    Capybara->>Test: Page loaded
+    
+    rect rgb(200, 220, 250)
+        Note over Hook,Cache: Performance Optimization
+        Hook->>Cache: Check if page scanned
+        alt Page already scanned
+            Cache->>Hook: Skip (cached)
+        else Not in cache
+            Cache->>Detector: Continue with scan
+        end
+    end
+    
+    rect rgb(220, 250, 220)
+        Note over Detector,Change: Smart Detection
+        Detector->>Change: Check for file changes
+        Change->>Change: Analyze views/partials/assets
+        alt No changes detected
+            Change->>Hook: Skip scan (no changes)
+        else Changes detected
+            Change->>Engine: Proceed with checks
+        end
+    end
+    
+    rect rgb(250, 220, 220)
+        Note over Engine,Checks: Accessibility Checks
+        Engine->>Checks: Run enabled checks
+        loop For each check (11 total)
+            Checks->>Capybara: Query DOM elements
+            Capybara->>Checks: Return elements
+            Checks->>Checks: Validate WCAG rules
+            Checks->>Collector: Report violations
+        end
+    end
+    
+    rect rgb(250, 240, 200)
+        Note over Collector,Report: Error Reporting
+        Collector->>Detector: Map violations to files
+        Detector->>Detector: Find view files
+        Detector->>Detector: Detect partials
+        Detector->>Builder: Pass file locations
+        Builder->>Builder: Format error messages
+        Builder->>Report: Generate detailed report
+    end
+    
+    alt Violations found
+        Report->>Test: Fail with detailed errors
+        Test->>Dev: Show actionable errors
+    else No violations
+        Report->>Test: Pass
+        Test->>Dev: ✓ Accessibility checks passed
+    end
+```
+
 ### Rule Engine Design
 
 The rule engine is the heart of the gem. It:
@@ -109,6 +296,43 @@ The rule engine is the heart of the gem. It:
 4. **Collects Violations**: Aggregates all violations before reporting
 5. **Formats Output**: Creates actionable error messages with precise file locations
 
+#### Rule Engine Flow Diagram
+
+```mermaid
+graph TB
+    A[Rule Engine] --> B[Load Configuration]
+    B --> C[Apply Profiles]
+    C --> D[Filter Enabled Checks]
+    D --> E[Execute Checks in Order]
+    
+    E --> F1[Form Labels]
+    E --> F2[Image Alt Text]
+    E --> F3[Interactive Elements]
+    E --> F4[Heading Hierarchy]
+    E --> F5[Keyboard Access]
+    E --> F6[ARIA Landmarks]
+    E --> F7[Form Errors]
+    E --> F8[Table Structure]
+    E --> F9[Duplicate IDs]
+    E --> F10[Skip Links]
+    E --> F11[Color Contrast]
+    
+    F1 --> G[Collect Violations]
+    F2 --> G
+    F3 --> G
+    F4 --> G
+    F5 --> G
+    F6 --> G
+    F7 --> G
+    F8 --> G
+    F9 --> G
+    F10 --> G
+    F11 --> G
+    
+    style A fill:#4ecdc4
+    style G fill:#ffeaa7
+```
+
 ### Check Definition Structure
 
 Each check is a self-contained class that:
@@ -157,6 +381,24 @@ module AccessibilityHelper
 end
 ```
 
+#### View Detection Flow Diagram
+
+```mermaid
+graph TB
+    subgraph "View Detection System"
+        A[Page URL] --> B[Route Recognition]
+        B --> C{Exact Match?}
+        C -->|Yes| D[Found View File]
+        C -->|No| E[Fuzzy Matching]
+        E --> F[Scan Controller Dir]
+        F --> D
+        D --> G[Scan for Partials]
+        G --> H[Map Elements to Partials]
+    end
+    
+    style B fill:#96ceb4
+```
+
 ### Performance System (NEW in 1.5.0)
 
 #### Page Scanning Cache
@@ -185,6 +427,121 @@ end
 - **Subsequent Runs**: Only tests changed files
 - **Force Option**: `TEST_ALL_PAGES=true` environment variable
 
+### Static Scanning System (NEW in 1.5.3)
+
+The static scanning system allows scanning view files directly without browser rendering, providing fast feedback during development.
+
+#### Components
+
+1. **StaticFileScanner** - Main orchestrator
+   - Reads ERB template files
+   - Coordinates HTML extraction and scanning
+   - Returns errors with file locations and line numbers
+
+2. **FileChangeTracker** - Change detection for static files
+   - Tracks file modification times in `tmp/.rails_a11y_scanned_files.json`
+   - Detects which files have changed since last scan
+   - Supports atomic writes to prevent partial state
+
+3. **ErbExtractor** - ERB to HTML conversion
+   - Converts Rails helpers (`link_to`, `image_tag`, `select_tag`, etc.) to HTML placeholders
+   - Preserves attributes (id, name, src, alt, href) for analysis
+   - Removes ERB tags while preserving structure
+
+4. **StaticPageAdapter** - Capybara compatibility layer
+   - Makes Nokogiri documents look like Capybara pages
+   - Allows reuse of existing checks without modification
+   - Provides Capybara-like interface (`all`, `has_css?`, etc.)
+
+5. **LineNumberFinder** - Precise error location
+   - Maps HTML elements back to original ERB line numbers
+   - Uses element attributes (id, src, href) for matching
+   - Enables precise error reporting
+
+6. **ViolationConverter** - Result formatting
+   - Converts raw violations to structured errors/warnings
+   - Adds line numbers and file paths
+   - Respects `ignore_warnings` configuration
+
+#### Static Scanning Flow
+
+```mermaid
+graph TB
+    A[View File Changed] --> B[FileChangeTracker]
+    B --> C{File Modified?}
+    C -->|No| D[Skip Scan]
+    C -->|Yes| E[StaticFileScanner]
+    E --> F[ErbExtractor]
+    F --> G[Convert ERB to HTML]
+    G --> H[StaticPageAdapter]
+    H --> I[RuleEngine]
+    I --> J[11 Checks]
+    J --> K[ViolationConverter]
+    K --> L[LineNumberFinder]
+    L --> M[Errors with Line Numbers]
+    M --> N[Update FileChangeTracker State]
+    
+    style E fill:#feca57
+    style F fill:#ff9ff3
+    style H fill:#48dbfb
+    style L fill:#ff6b6b
+```
+
+#### Configuration
+
+Static scanner behavior is controlled via `config/accessibility.yml`:
+
+```yaml
+static_scanner:
+  # Only scan files that have changed since last scan
+  scan_changed_only: true
+  
+  # Check interval in seconds when running continuously
+  check_interval: 3
+  
+  # Force full scan on startup (true/false)
+  # When true: scans all files on first run, then only changed files
+  # When false: only scans changed files from the start
+  full_scan_on_startup: true
+```
+
+#### Benefits
+
+- **Fast**: No browser needed - scans ERB templates directly
+- **Precise**: Reports exact file locations and line numbers
+- **Efficient**: Only scans changed files using modification time tracking
+- **Continuous**: Runs continuously, watching for file changes
+- **Reusable**: Leverages existing RuleEngine and all 11 checks
+
+#### Performance Optimization Flow
+
+```mermaid
+graph TB
+    A[Page Visit] --> B{In Page Cache?}
+    B -->|Yes| C[Skip Scan]
+    B -->|No| D{First Run?}
+    D -->|Yes| E[Scan All Pages]
+    D -->|No| F{Files Changed?}
+    F -->|No| G[Skip Scan]
+    F -->|Yes| H[Smart Scan]
+    
+    H --> I{Which Files?}
+    I -->|View| J[Scan This Page]
+    I -->|Partial| K[Scan Pages Using Partial]
+    I -->|Helper| L[Scan All Pages]
+    I -->|Asset| M[Scan All Pages]
+    
+    E --> N[Add to Cache]
+    J --> N
+    K --> N
+    L --> N
+    M --> N
+    
+    style B fill:#a29bfe
+    style F fill:#fdcb6e
+    style N fill:#55efc4
+```
+
 ---
 
 ## Key Design Decisions
@@ -286,6 +643,13 @@ lib/
 │   ├── change_detector.rb          # Smart change detection
 │   │                                # (enhanced in 1.5.0 for assets/partials)
 │   │
+│   ├── static_file_scanner.rb     # Static file scanner orchestrator
+│   ├── file_change_tracker.rb     # Tracks file modification times
+│   ├── erb_extractor.rb           # Converts ERB to HTML
+│   ├── static_page_adapter.rb     # Nokogiri → Capybara adapter
+│   ├── line_number_finder.rb      # Maps elements to line numbers
+│   ├── violation_converter.rb     # Formats violations with line numbers
+│   │
 │   ├── integration/
 │   │   ├── rspec_integration.rb
 │   │   ├── minitest_integration.rb
@@ -319,7 +683,8 @@ lib/
 exe/
 ├── rails_a11y                    # CLI executable
 ├── rails_server_safe             # Safe server wrapper (NEW in 1.5.0)
-└── a11y_live_scanner            # Live scanner tool
+├── a11y_live_scanner            # Live scanner tool (browser-based)
+└── a11y_static_scanner          # Static file scanner (NEW in 1.5.0+)
 
 GUIDES/
 ├── getting_started.md
@@ -420,6 +785,13 @@ ci:
 3. **Enhanced ChangeDetector**: Asset change detection and smart partial impact analysis
 4. **Improved View File Detection**: Fuzzy matching and controller directory scanning
 5. **Rails Server Safe Wrapper**: Prevents Foreman from terminating processes
+6. **Static Scanning System**: File-based scanning without browser (NEW in 1.5.0+)
+   - **StaticFileScanner**: Main orchestrator for static file scanning
+   - **FileChangeTracker**: Tracks file modification times for change detection
+   - **ErbExtractor**: Converts ERB templates to HTML for analysis
+   - **StaticPageAdapter**: Makes Nokogiri documents compatible with existing checks
+   - **LineNumberFinder**: Maps HTML elements to ERB line numbers
+   - **ViolationConverter**: Formats violations with precise file locations
 
 ### Enhanced Components
 
@@ -435,6 +807,9 @@ ci:
 2. **Smart Change Detection**: Only tests affected pages
 3. **First-Run Optimization**: Faster initial setup
 4. **Reduced Wait Times**: Faster Capybara operations
+5. **Static File Scanning**: Fast file-based scanning without browser overhead (NEW in 1.5.0+)
+6. **File Change Tracking**: Only scans modified files using modification time tracking
+7. **Continuous Monitoring**: Watches for file changes and re-scans automatically
 
 ---
 

data/CHANGELOG.md

@@ -5,18 +5,65 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.5.4] - 2024-11-20
+
+### Changed
+- **Static scanner startup behavior**: Always runs full scan on startup when `full_scan_on_startup: true` (default)
+- **Improved first-run detection**: Better handling of initial scan vs subsequent scans
+
+### Fixed
+- **Static scanner startup**: Fixed issue where scanner wasn't running full scan on every `bin/dev` startup
+- **Documentation**: Updated all documentation to reflect static scanner as primary development tool
+
 ## [1.5.3] - 2024-11-20
 
+### Added
+
+#### Static File Scanner (NEW)
+- **Fast file-based scanning**: Scans ERB templates directly without browser rendering
+- **Smart change detection**: Only scans files that have changed since last scan using file modification time tracking
+- **Precise error reporting**: Shows exact file locations and line numbers for accessibility issues
+- **Continuous monitoring**: Watches for file changes and re-scans automatically
+- **YAML configuration**: Fully configurable via `config/accessibility.yml` with `static_scanner` section
+- **Reuses existing checks**: Leverages all 11 accessibility checks via RuleEngine
+- **Modular architecture**: New components (`FileChangeTracker`, `ErbExtractor`, `StaticPageAdapter`, `LineNumberFinder`, `ViolationConverter`)
+- **Full scan on startup**: Always runs complete scan when `bin/dev` starts (configurable)
+- **Warning filtering**: New `ignore_warnings` flag in YAML config to hide warnings, only show errors
+
+#### New Components
+- **FileChangeTracker**: Tracks file modification times in `tmp/.rails_a11y_scanned_files.json` for efficient change detection
+- **ErbExtractor**: Converts ERB templates to HTML by replacing Rails helpers with HTML placeholders
+- **StaticPageAdapter**: Makes Nokogiri documents compatible with existing Capybara-based checks
+- **LineNumberFinder**: Maps HTML elements back to original ERB line numbers for precise error reporting
+- **ViolationConverter**: Formats violations with file paths and line numbers, respects `ignore_warnings` config
+
+#### Configuration Enhancements
+- **Static scanner config**: New `static_scanner` section in `accessibility.yml`:
+  - `scan_changed_only`: Only scan changed files (default: true)
+  - `check_interval`: Seconds between file checks (default: 3)
+  - `full_scan_on_startup`: Full scan on startup (default: true)
+- **Summary config**: New `ignore_warnings` flag to filter out warnings completely
+
+### Changed
+- **Generator**: Now adds `a11y_static_scanner` to `Procfile.dev` instead of live scanner
+- **Default behavior**: Static scanner runs full scan on every `bin/dev` startup by default
+- **Error reporting**: Static scanner shows errors with file paths and line numbers instead of URLs
+
 ### Fixed
 - **Gem packaging**: Verified all required files are included in gem package
-  - All executables (rails_a11y, rails_server_safe, a11y_live_scanner)
+  - All executables (rails_a11y, rails_server_safe, a11y_live_scanner, a11y_static_scanner)
   - All generator templates (.erb files)
   - Complete library files and documentation
+- **Rails helper compatibility**: Fixed `blank?` and `present?` calls to work without Rails (pure Ruby)
+- **Check compatibility**: Fixed `FormLabelsCheck`, `InteractiveElementsCheck`, `HeadingCheck` to work with static scanning
+- **Element queries**: Added `all` method to `StaticElementAdapter` for nested element queries
 
 ### Verified
 - All executables properly included in gemspec
 - Generator templates correctly packaged
 - rails_server_safe Ruby script working correctly
+- Static scanner working correctly with all 11 checks
+- File change detection working correctly
 - Local development setup confirmed working
 
 ## [1.5.2] - 2024-11-20
@@ -327,6 +374,8 @@ This release introduces significant improvements to view file detection, partial
 - Compatible with RSpec Rails 6.0+
 - Modular architecture with rule engine and check definitions
 
+[1.5.4]: https://github.com/rayraycodes/rails-accessibility-testing/releases/tag/v1.5.4
+[1.5.3]: https://github.com/rayraycodes/rails-accessibility-testing/releases/tag/v1.5.3
 [1.5.2]: https://github.com/rayraycodes/rails-accessibility-testing/releases/tag/v1.5.2
 [1.5.0]: https://github.com/rayraycodes/rails-accessibility-testing/releases/tag/v1.5.0
 [1.4.3]: https://github.com/rayraycodes/rails-accessibility-testing/releases/tag/v1.4.3

data/GUIDES/getting_started.md

@@ -62,14 +62,14 @@ bundle exec rspec spec/system/
 
 Accessibility checks run automatically on every system test that visits a page.
 
-#### Option B: Run Continuously with Procfile (Recommended for Development)
+#### Option B: Static File Scanner (Recommended for Development)
 
-The generator automatically adds an accessibility watch command to your `Procfile.dev`:
+The generator automatically adds a static accessibility scanner to your `Procfile.dev`:
 
 ```procfile
 web: bin/rails server
 css: bin/rails dartsass:watch
-a11y: while true; do bundle exec rspec spec/system/*_accessibility_spec.rb; sleep 30; done
+a11y: bundle exec a11y_static_scanner
 ```
 
 Then run:
@@ -81,9 +81,31 @@ bin/dev
 This will:
 - Start your Rails server
 - Watch for CSS changes
-- **Automatically run accessibility checks every 30 seconds** on all `*_accessibility_spec.rb` files
+- **Continuously scan view files for accessibility issues** - Only scans files that have changed since last scan
+- Shows errors with exact file locations and line numbers
 
-The accessibility checker will continuously monitor your pages and alert you to any issues as you develop!
+**How it works:**
+- **First run**: Scans all view files to establish baseline
+- **Subsequent runs**: Only scans files that have been modified
+- **Continuous monitoring**: Watches for file changes and re-scans automatically
+- **Smart change detection**: Uses file modification times to track changes
+- **Fast feedback**: No browser needed - scans ERB templates directly
+
+**Configuration** (in `config/accessibility.yml`):
+
+```yaml
+static_scanner:
+  # Only scan files that have changed since last scan (true/false)
+  scan_changed_only: true
+  
+  # Check interval in seconds when running continuously
+  check_interval: 3
+  
+  # Force full scan on startup (true/false)
+  full_scan_on_startup: true
+```
+
+The static scanner provides fast, continuous feedback as you develop, catching accessibility issues before you even run your tests!
 
 #### Option C: All Pages Spec with Smart Change Detection
 
@@ -226,6 +248,19 @@ Edit `config/accessibility.yml`:
 ```yaml
 wcag_level: AA
 
+# Summary configuration
+summary:
+  show_summary: true
+  errors_only: false
+  show_fixes: true
+  ignore_warnings: false  # Set to true to hide warnings, only show errors
+
+# Static scanner configuration
+static_scanner:
+  scan_changed_only: true    # Only scan changed files
+  check_interval: 3          # Seconds between file checks
+  full_scan_on_startup: true # Full scan on first run
+
 checks:
   form_labels: true
   image_alt_text: true

data/GUIDES/system_specs_for_accessibility.md

@@ -38,16 +38,24 @@ end
 
 The gem automatically runs comprehensive accessibility checks after each `visit` in system specs. You don't need to call `check_comprehensive_accessibility` manually unless you want to run checks at a specific point in your test.
 
-### 3. Continuous Testing with Procfile (Optional)
+### 3. Continuous Testing with Static Scanner (Recommended)
 
-The generator automatically adds an accessibility watch command to your `Procfile.dev`:
+The generator automatically adds a static accessibility scanner to your `Procfile.dev`:
 
-```ruby
+```procfile
 web: bin/rails server
 css: bin/rails dartsass:watch
-a11y: while true; do bundle exec rspec spec/system/*_accessibility_spec.rb; sleep 30; done
+a11y: bundle exec a11y_static_scanner
 ```
 
+This provides fast, continuous feedback by scanning view files directly without browser rendering. The scanner:
+- Scans all files on startup
+- Only re-scans files that have changed
+- Shows errors with exact file locations and line numbers
+- Watches for file changes continuously
+
+See the [Getting Started Guide](getting_started.md) for more details on static scanner configuration.
+
 This will run your accessibility specs every 30 seconds while you develop. The `all_pages_accessibility_spec.rb` uses smart change detection to only test pages when their related files change, making it fast and focused.
 
 ## Example Specs