ui_guardrails 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 200bad03eb94e193c93e5965c52743f8bc9c4d232003149d482cf8b4bc72d77c
+  data.tar.gz: cd365fa2244f58b1c294f317119be08e03da868f050cc1aae268d6ff524237a0
+SHA512:
+  metadata.gz: 1c23e135b24dcbf76c3d98983ee339a22800fdf4a40fbc4b13dcbebaecfbf8b7160a5aa4472f01440fb20bac8bf6585ada295207189aae11f8809f894ef70003
+  data.tar.gz: 56572b2788586158520982bf9d3d0f18e4920136aab255dec5ef88b08d7c7ef0347ba653e71564f0b439c2c94db53c7eee30a241f9a5c516fc72722900769074

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Meticulous
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,302 @@
+# Guardrails
+
+A Rails toolset that prevents UI drift in AI-assisted applications. Static audits over your views, components, stylesheets, JS controllers, and tokens — surfacing the kinds of inconsistencies that compound silently as an AI assistant ships code faster than design-system discipline can keep up.
+
+Built and maintained by [Meticulous](https://meticulous.com).
+
+**Current release:** 1.0.0 — V0 + V1 + V2 complete, published on [RubyGems.org as `ui_guardrails`](https://rubygems.org/gems/ui_guardrails). The Ruby module stays `Guardrails` (so `require "guardrails"` is unchanged) — only the gem package name on rubygems carries the `ui_` prefix, to clear RubyGems' similarity rule against the unrelated [`guard-rails`](https://rubygems.org/gems/guard-rails) gem. See [`doc/ROADMAP.md`](doc/ROADMAP.md) for status, [`CHANGELOG.md`](CHANGELOG.md) for the full naming rationale.
+
+---
+
+## The problem
+
+AI-assisted Rails development is fast. Too fast. Without design guardrails in place, codebases accumulate:
+
+- Inline `style=` attributes nobody asked for
+- Hex literals scattered across views that should reference a token
+- `bg-[#fa3]` arbitrary Tailwind values when a theme color already exists
+- Six near-duplicate "card" partials when one parameterized component would do
+- `<button>` elements with no accessible name
+- Orphan ViewComponent slots and Stimulus controllers
+- The same 7-class utility soup pasted onto 30 buttons
+
+Guardrails catches these patterns without rendering anything — every detector is a static AST walk over your source. Findings stream into a unified report (text or JSON) with the same exit-code contract every other lint tool uses.
+
+---
+
+## Installation
+
+Guardrails works two ways: **installed in your project** (auto-loaded via a Railtie, runs the audit on every CI pass) or **sidecar** (cloned alongside your app, audits any tree on demand without modifying its Gemfile).
+
+### Installed in-project (recommended)
+
+```ruby
+# Gemfile
+group :development, :test do
+  gem "ui_guardrails", "~> 1.0"
+end
+```
+
+```bash
+bundle install
+bundle exec rake guardrails:init       # writes guardrails.yml, scaffolds MQs
+bundle exec rake guardrails:audit      # run the full audit
+```
+
+The gem's Railtie auto-loads rake tasks and (when [Lookbook](https://lookbook.build) is also in your Gemfile) registers the **Guardrails** panel inside every preview's inspector.
+
+### Sidecar (no Gemfile change)
+
+Useful when you want to audit a Rails app without committing to the gem yet, or in CI for repos you don't own.
+
+```bash
+git clone https://github.com/meticulous/guardrails ~/code/guardrails
+cd ~/code/guardrails && bundle install
+
+# From your Rails app's root:
+cd ~/code/my-rails-app
+bundle exec --gemfile=~/code/guardrails/Gemfile \
+  rake -f ~/code/guardrails/lib/tasks/guardrails.rake \
+  guardrails:audit
+```
+
+Every rake task accepts the same env vars in sidecar mode as in-project. The tasks default `root` to `Rails.root` when Rails is loaded, else `Dir.pwd` — so just run from the target app's root.
+
+---
+
+## Quick start
+
+```bash
+# One-time setup — detects your token stack, writes guardrails.yml,
+# scaffolds prefers-color-scheme media queries if your stylesheet
+# doesn't already have them. Interactive when on a TTY; CI-safe
+# default fallback otherwise.
+bundle exec rake guardrails:init
+
+# Full audit — exits 1 on any violation.
+bundle exec rake guardrails:audit
+
+# Get a markdown checklist of fixable findings:
+SUGGEST=1 bundle exec rake guardrails:audit
+# → writes doc/guardrails-suggestions-{TIMESTAMP}.md
+
+# Auto-fix raw_color and tailwind_arbitrary where a token matches:
+APPLY=1 bundle exec rake guardrails:audit
+```
+
+---
+
+## Tasks at a glance
+
+| Task | What it does |
+|---|---|
+| `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:icons` | Generates an SVG sprite from `app/assets/images/icons/`, flags inline `<svg>` in views, reports unused icons. |
+| `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. |
+
+---
+
+## Detectors
+
+### View-level drift (`guardrails:audit`)
+
+Static AST walk over every `.html.erb` under `app/views/` and `app/components/` (via [Herb](https://github.com/marcoroth/herb), the ERB-aware parser):
+
+| Detector | Catches |
+|---|---|
+| `inline_style` | `<div style="…">` — inline styles bypass tokens entirely. |
+| `raw_color` | Hex / rgb literals in color-bearing attributes (`fill`, `stroke`, `color`, `bgcolor`, `background`, `data-*color*`, etc.). |
+| `tailwind_arbitrary` | `bg-[#fa3]`, `text-[14px]`, `p-[7px]` — arbitrary values that bypass the theme. |
+| `helper_recommended` | `<button>` / `<a>` wrapping `<%= … %>` ERB output. Suggests `tag.button` / `link_to` / `button_to` for clean accessible names. Skips elements that already have `aria-label`. |
+| `image_alt` / `button_name` / `link_name` / `input_label` | The four most common static a11y misses (see [`doc/A11Y.md`](doc/A11Y.md)). |
+
+### Suggest mode and auto-fix
+
+- `SUGGEST=1 rake guardrails:audit` writes `doc/guardrails-suggestions-{TIMESTAMP}.md` — a markdown checklist with one `[ ]` per fixable finding, the rule that fired, and the proposed replacement (closest token by exact match, else near-match within a configurable channel-distance).
+- `APPLY=1 rake guardrails:audit` auto-fixes `raw_color` (→ `var(--token)`) and `tailwind_arbitrary` (→ Tailwind theme color shorthand) when a matching token exists. Near-match auto-fix is gated by `near_match_policy` in `guardrails.yml` (`fix` / `leave` / `notify`).
+
+### Tokens
+
+`Guardrails::Tokens` parses every token source it can find:
+
+- 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 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.
+
+### Stimulus
+
+`Guardrails::StimulusAudit` cross-references `data-controller="…"` attributes against `app/javascript/**/controllers/*_controller.{js,ts}` (works across importmap, Webpacker, Vite, and Avo's `app/javascript/js/controllers/` layout):
+
+- **Orphaned** — controller referenced in a view but no JS file defines it.
+- **Dead** — JS file exists but no view references it.
+- Picks up Ruby helper syntax: `tag.div(data: { controller: "foo" })`.
+
+### ViewComponent
+
+`Guardrails::ViewComponentAudit`:
+
+- Reports components without a preview file (Lookbook discoverability).
+- Reports `renders_one` / `renders_many` slots declared in the component class but never referenced in the template (orphan slots).
+
+### Partial similarity
+
+`Guardrails::PartialSimilarity` runs n-gram Jaccard over the tag-stream of every partial and component template, groups near-duplicates by connected components, and reports clusters above the configured threshold (default 0.7). Pair sample lines surface the most similar match in each cluster.
+
+### Cross-codebase patterns (0.3.0)
+
+`Guardrails::CrossCodebasePatterns` walks every element subtree, fingerprints the tag-only shape (`article(header(h2),section(p,p),footer(a))`), and reports shapes appearing 3+ times with ≥ 5 elements. Distinct from PartialSimilarity (which compares **existing** partials) — this finds shapes that **should** be partials but aren't yet. Dedupes redundant nested patterns so a repeating table doesn't generate three findings (`table(…)`, `thead(…)`, `tr(…)`) for the same locations.
+
+### Class-itis (0.4.0)
+
+`Guardrails::ClassItis` groups elements by `(tag, sorted-uniq-class-list)`. Reports tuples with ≥ 5 distinct classes appearing on the same tag in ≥ 3 places — the classic AI-assisted-Rails failure mode of 8-utility soup pasted across many buttons when the codebase should have a shared component or `@apply` rule. ERB-driven class fragments are dropped; only the static portion is fingerprinted.
+
+### Visual diff via snap_diff-capybara (0.8.0)
+
+`Guardrails::VisualDiff` consumes screenshot-diff tool output and folds findings into the unified report. The shipped adapter is [`snap_diff-capybara`](https://github.com/snap-diff/snap_diff-capybara) — the Rails-native baselines-in-git visual-regression gem:
+
+```bash
+# Your existing system tests produce diffs under doc/screenshots/
+bundle exec rspec spec/system/
+
+# Fold visual-diff findings into the audit:
+VISUAL_DIFF=1 bundle exec rake guardrails:audit
+```
+
+Or standalone via `rake guardrails:visual:deep`. Parse-only — same trade as deep a11y, no Capybara/Chromium runtime deps in the gem. BackstopJS adapter tracked in [#15](https://github.com/meticulous/guardrails/issues/15). See [`doc/VISUAL-DIFF.md`](doc/VISUAL-DIFF.md).
+
+### Deep a11y via axe-core JSON (0.6.0)
+
+`Guardrails::A11yDeep` consumes axe-core JSON output and folds findings into the unified report:
+
+```bash
+npx @axe-core/cli http://localhost:3000/ --save axe.json
+AXE_JSON=axe.json bundle exec rake guardrails:audit
+```
+
+Or standalone via `rake guardrails:a11y:deep`. Stays parse-only — your existing test toolchain runs axe (axe-core-rspec, the CLI, Puppeteer, a CDP script — anything that emits axe v4 JSON), Guardrails provides the merge + report. See [`doc/A11Y.md`](doc/A11Y.md).
+
+### Lookbook auto-panel (0.5.0)
+
+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).
+
+---
+
+## Output
+
+Every task prints a human-readable text report by default and exits 1 when violations or failing findings exist. For machine consumption:
+
+```bash
+FORMAT=json bundle exec rake guardrails:audit > findings.json
+```
+
+The JSON payload has a `summary:` block with finding counts per category plus per-detector arrays — see the rake task source for the exact shape.
+
+### Common env vars
+
+| Var | Effect |
+|---|---|
+| `SUGGEST=1` | Write the markdown checklist alongside the text report. |
+| `APPLY=1` | Auto-fix raw_color + tailwind_arbitrary where tokens match. |
+| `FORMAT=json` | Emit one JSON document to stdout (all other audit output is suppressed). |
+| `FORCE=1` | Bypass `init`'s refuse-to-overwrite default. |
+| `AXE_JSON=path` | Fold axe-core findings into the unified report. |
+| `VISUAL_DIFF=1` | Fold visual-diff findings into `guardrails:audit`. Embedded installs can flip this on permanently via `Guardrails.configure { \|c\| c.visual_diff.enabled = true }`. |
+| `VISUAL_DIFF_DIR=path` / `VISUAL_DIFF_THRESHOLD=0.02` | Tune the visual-diff snap_diff adapter and mismatch threshold. |
+| `SIMILARITY_THRESHOLD=0.85` | Override the partial-similarity Jaccard threshold. |
+| `PATTERN_MIN_SIZE=8` / `PATTERN_MIN_OCCURRENCES=4` | Tune the cross-codebase pattern detector. |
+| `CLASSITIS_MIN_CLASSES=6` / `CLASSITIS_MIN_OCCURRENCES=4` | Tune the class-itis detector. |
+
+---
+
+## CI
+
+The audit task is a single shell command:
+
+```yaml
+# .github/workflows/ci.yml
+- name: Guardrails audit
+  run: bundle exec rake guardrails:audit
+```
+
+For richer integration:
+
+```yaml
+- name: Guardrails audit (JSON)
+  run: bundle exec rake guardrails:audit FORMAT=json > findings.json
+  continue-on-error: true
+
+- name: Upload findings
+  uses: actions/upload-artifact@v4
+  with:
+    name: guardrails-findings
+    path: findings.json
+```
+
+---
+
+## Configuration
+
+`guardrails.yml` at the repo root. `guardrails:init` writes a sensible default after detecting your stack — what's below is annotated to show every available key:
+
+```yaml
+guardrails:
+  scan_paths:
+    - app/views
+    - app/components
+  ignore:
+    - app/views/layouts
+  tokens:
+    # Where your color tokens live. The init task picks this up from
+    # stack detection (CSS vars, SCSS, Tailwind v3/v4); edit if it
+    # guessed wrong.
+    colors_file: app/assets/stylesheets/tokens/_colors.css
+    type_scale_file: app/assets/stylesheets/tokens/_type.css
+    # 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.
+    near_match_threshold: 4
+    # What to do with near-matches: notify (default; suggest in the
+    # report), fix (auto-fix with APPLY=1), or leave (silence).
+    near_match_policy: notify
+```
+
+---
+
+## Demo app
+
+[`examples/demo`](examples/demo) is a bootable Rails 7.2 app with intentionally seeded findings — every detector trips at least once. Clone, `bin/setup`, `bin/rails server`, then visit `/`, `/broken`, and `/rails/lookbook` to see the auto-registered Guardrails panel. `bundle exec rake guardrails:audit` runs the full audit against the seeded tree. See [`examples/demo/README.md`](examples/demo/README.md).
+
+---
+
+## Status & roadmap
+
+- **V0** (foundation) — ✅ shipped
+- **V1** (polish + ecosystem) — ✅ shipped
+- **V2** (advanced) — ✅ shipped (cross-codebase patterns, class-itis, visual diff via snap_diff-capybara)
+
+Full status table and decision log: [`doc/ROADMAP.md`](doc/ROADMAP.md).
+
+---
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec        # 453 examples
+```
+
+Real-world signal lives in `examples/demo` (integration spec) and in the dogfood patches against four real codebases (Patchvault, Talos, Forem, Avo — see `CHANGELOG.md` for what each round caught).
+
+Issues and PRs: <https://github.com/meticulous/guardrails>
+
+---
+
+## License
+
+MIT

data/doc/A11Y.md

@@ -0,0 +1,87 @@
+# Accessibility (a11y) checks
+
+Guardrails ships **static** a11y checks — element-level rules that can be answered from your view source without rendering. These run as part of `rails guardrails:audit` and contribute to the exit code.
+
+For full a11y coverage (color contrast, focus order, ARIA tree, dynamic content), wire **axe-core** alongside Guardrails in your test suite. Static checks catch the obvious template-level mistakes; runtime checks catch everything else.
+
+## Static checks (built-in)
+
+Run via `rails guardrails:audit`. Findings appear under "Guardrails a11y" in the report and as `a11y` in `FORMAT=json` output.
+
+| Rule | Catches |
+|---|---|
+| `image_alt` | `<img>` without an `alt` attribute (use `alt=""` for decorative images) |
+| `button_name` | `<button>` with no text content and no `aria-label` / `aria-labelledby` |
+| `link_name` | `<a href="...">` with no text, no `aria-label`, no `title` |
+| `input_label` | Interactive `<input>` without `aria-label`, `aria-labelledby`, or a matching `<label for>` |
+
+These rules align conceptually with the corresponding rules in [axe-core](https://dequeuniversity.com/rules/axe/) but run against template source rather than rendered DOM.
+
+## Deep a11y via axe-core JSON (`AXE_JSON=…`)
+
+When you run axe-core in CI or locally, pass the JSON output to Guardrails to fold runtime findings into the unified report:
+
+```bash
+# Run axe-core however you already do (one of these):
+npx @axe-core/cli http://localhost:3000/ http://localhost:3000/dashboard --save axe.json
+# or via axe-core-rspec, axe-puppeteer, your CDP script — anything that emits axe JSON v4
+
+# Hand the JSON to Guardrails:
+AXE_JSON=axe.json bundle exec rake guardrails:audit
+```
+
+Or run the deep check standalone:
+
+```bash
+AXE_JSON=axe.json bundle exec rake guardrails:a11y:deep
+```
+
+The report groups findings by URL and prints rule + impact + selector + help URL per node. Exit code is 1 when any finding's impact is in the failing set (default: `minor`, `moderate`, `serious`, `critical` — i.e. any impact fails). The full payload is also included in `FORMAT=json` output under the `a11y_deep` key.
+
+The input accepts either axe's single-page result object (`{ "url": "...", "violations": [...] }`) or an array of those for multi-URL runs — what `npx @axe-core/cli --save` emits.
+
+Why parse-only and not bundled: see ["Why not bundle axe-core directly?"](#why-not-bundle-axe-core-directly) below. The short version is "your test suite already runs a browser; we don't need to duplicate that infrastructure."
+
+## Runtime axe-core (recommended addition)
+
+For a system test suite:
+
+```ruby
+# Gemfile
+group :test do
+  gem "axe-core-rspec"
+end
+```
+
+```ruby
+# spec/rails_helper.rb
+require "axe-rspec"
+```
+
+```ruby
+# spec/system/checkout_spec.rb
+require "rails_helper"
+
+RSpec.describe "checkout flow", type: :system do
+  it "is accessible at the cart screen" do
+    visit cart_path
+    expect(page).to be_axe_clean.according_to(:wcag2a, :wcag2aa)
+  end
+end
+```
+
+For component-level a11y inside Lookbook previews, see `doc/LOOKBOOK.md` and add an axe panel via Lookbook's panel API.
+
+## Why not bundle axe-core directly?
+
+axe-core needs a real browser. Adding Capybara + headless Chrome as runtime dependencies of a static-analysis gem would balloon installation cost for users who don't run system tests. Keeping the integration as a documented opt-in lets you size your a11y testing to match your actual test infrastructure.
+
+## What static checks miss
+
+- Color contrast (needs rendered colors in context)
+- Focus order and keyboard navigation
+- ARIA relationships and live regions
+- Dynamic content that appears after JS runs
+- Heading hierarchy across a full page (we see one component at a time)
+
+If any of these matter to you, layer axe-core on top.

data/doc/LOOKBOOK.md

@@ -0,0 +1,52 @@
+# Lookbook integration
+
+When you have both Guardrails and [Lookbook](https://lookbook.build) in your Gemfile, Guardrails auto-registers a `:guardrails` panel that appears next to every preview, surfacing per-component audit findings inline. No initializer wiring required.
+
+## What you see
+
+In a preview's inspector, alongside the standard Source / Notes / Params panels, a **Guardrails** tab shows:
+
+- **Drift in template** — `inline_style`, `raw_color`, `tailwind_arbitrary`, `helper_recommended` findings for the component's `.html.erb`
+- **Orphan slots** — `renders_one` / `renders_many` declarations not rendered by the template
+- **Similar templates** — other partials / components above the similarity threshold
+
+If the component has no findings, the panel renders a "No findings — this component is clean." message. If Guardrails can't locate the component's class file under `app/components/`, the panel says so.
+
+## How auto-registration works
+
+The Railtie's `guardrails.lookbook_panel` initializer runs at app boot and is a no-op unless `defined?(::Lookbook)`. When Lookbook is present:
+
+1. The gem **appends** its view directory (`lib/guardrails/lookbook/views`) to `ActionController::Base.view_paths`. Append, not prepend, so the host's `app/views/lookbook_panels/_guardrails.html.erb` (if present) still wins.
+2. It calls `Rails.application.config.lookbook.preview_inspector.panels.add(:guardrails)` with a locals lambda that, per render, runs `Guardrails::Lookbook::ComponentReport` against the current preview's component class.
+
+## Programmatic access
+
+The same data the panel renders is exposed as a plain Hash, useful for CI dashboards or custom rendering:
+
+```ruby
+Guardrails::Lookbook::ComponentReport.new(root: Rails.root).for("ButtonComponent")
+# => {
+#   component: "ButtonComponent",
+#   class_file: "app/components/button_component.rb",
+#   template_file: "app/components/button_component.html.erb",
+#   violations: [
+#     { type: :raw_color, file: "...", line: 3, column: 12, snippet: "...", value: "#0066ff" }
+#   ],
+#   orphan_slots: [
+#     { component: "button", slot: "icon", slot_kind: :renders_one, file: "...", line: 4 }
+#   ],
+#   similar_templates: [
+#     { partner: "app/components/icon_button_component.html.erb", score: 0.92 }
+#   ]
+# }
+```
+
+Returns `nil` when the component class file can't be located.
+
+## Overriding the partial
+
+The shipped partial deliberately uses class hooks (`lookbook-guardrails-empty`, `lookbook-guardrails-clean`) but no styling — the host app's design system wins. If you need a different layout entirely, drop a file at `app/views/lookbook_panels/_guardrails.html.erb` in your app: standard Rails view-path precedence puts the host's version ahead of the gem's.
+
+## Performance note
+
+`ComponentReport#for` runs the full audit, view-component audit, and partial-similarity pass on every panel render, then filters by component. For large codebases that's wasteful when Lookbook re-renders frequently. If you hit perf issues, cache results per Lookbook session or move audit invocation to a background job that writes JSON to disk for the panel to read.

data/doc/PRD.md

@@ -0,0 +1,145 @@
+# Guardrails — Product Requirements Document
+
+**Status:** Draft  
+**Owner:** John Athayde / Meticulous  
+**Last updated:** 2026-05-04
+
+---
+
+## Problem Statement
+
+AI-assisted Rails development accelerates shipping but introduces a new failure mode: UI drift. Developers using Copilot, Claude, or similar tools generate UI code fast — too fast to maintain design system consistency. The result is:
+
+- Duplicate or near-duplicate components
+- Ad-hoc color values that bypass design tokens
+- Icon sprawl (inline SVGs, mixed icon sets, no sprite optimization)
+- Type scale violations (hardcoded font sizes, inconsistent heading hierarchy)
+- No enforcement layer between "AI wrote this" and "this ships"
+
+Rails developers without dedicated designers have no tooling to catch this before it compounds.
+
+---
+
+## Target User
+
+**Primary:** Rails developers at small-to-mid-sized product companies who:
+- Ship UI features frequently (weekly or faster)
+- Use AI coding assistants
+- Don't have a dedicated designer or design system engineer
+- Care about consistency but lack the time to enforce it manually
+
+**Secondary:** Design-aware Rails consultants (Meticulous ICP) who want to hand clients something they can run themselves post-engagement.
+
+---
+
+## Goals
+
+1. Give Rails devs a single command to audit UI consistency across a codebase
+2. Enforce design token usage (colors, type scale) via configurable rules
+3. Generate optimized icon sprites from raw SVG assets
+4. Integrate naturally into existing Rails workflows (rake tasks, CI)
+5. Be opinionated but configurable
+
+---
+
+## Non-Goals
+
+- Not a design system generator (doesn't create components for you)
+- Not a linter replacement (Rubocop, ESLint still own their domains)
+- Not a visual regression tool (no screenshots/diffs)
+- Not a component library
+
+---
+
+## Features
+
+### 1. Component Audit (`rails guardrails:audit`)
+
+Scans views and partials for:
+- Near-duplicate partials (structural similarity, not just naming)
+- Inline styles that bypass CSS custom properties
+- Hardcoded color values (hex, rgb) outside of token files
+- Hardcoded font-size/line-height values outside of type scale
+
+Outputs: summary report to stdout + optional JSON/HTML report
+
+### 2. Icon Management (`rails guardrails:icons`)
+
+- Scans configured SVG source directory
+- Generates optimized SVG sprite sheet
+- Audits for inline SVGs in views that should be sprite references
+- Reports icon usage frequency (find dead icons)
+
+### 3. Design Token Enforcement (`rails guardrails:tokens`)
+
+- Reads a `guardrails.yml` token definition (colors, type scale, spacing)
+- Scans CSS/SCSS/Tailwind config for values that don't match defined tokens
+- Reports violations with file + line number
+- Optional: auto-suggest the closest token for a given raw value
+
+### 4. Configuration (`guardrails.yml`)
+
+```yaml
+guardrails:
+  icons:
+    source: app/assets/images/icons
+    sprite_output: app/assets/images/icons/sprite.svg
+
+  tokens:
+    colors_file: app/assets/stylesheets/tokens/_colors.scss
+    type_scale_file: app/assets/stylesheets/tokens/_type.scss
+
+  audit:
+    scan_paths:
+      - app/views
+      - app/components
+    ignore:
+      - app/views/layouts
+```
+
+### 5. CI Integration
+
+- Exit codes: 0 = clean, 1 = violations found
+- `--strict` flag to fail CI on any violation
+- `--format json` for machine-readable output
+
+---
+
+## Technical Approach
+
+- Ruby gem, distributed via RubyGems
+- Rake tasks registered via Railtie
+- No runtime dependency — development/test group only
+- Minimal dependencies (avoid pulling in heavy gems)
+
+---
+
+## Success Metrics
+
+- Developers can run `rails guardrails:audit` in < 30 seconds on a mid-sized app
+- Catches at least 80% of common UI drift patterns in a test app
+- Zero false positives on a clean, well-structured Rails app
+- Used by at least 3 Meticulous clients within 6 months of launch
+
+---
+
+## Open Questions
+
+- [ ] Tailwind support: scan for arbitrary values in class strings? (complex but high value)
+- [ ] ViewComponent vs ERB partials: audit strategy differs
+- [ ] Auto-fix mode: is this in scope for v1?
+- [ ] VS Code extension as a companion? (out of scope for now)
+- [ ] Where do Stimulus controllers fit in the audit?
+
+---
+
+## Milestones
+
+| Milestone | Target | Notes |
+|-----------|--------|-------|
+| PRD + README stub | 2026-05-04 | ✅ Done |
+| Gem skeleton + Railtie | TBD | First Claude Code session |
+| `guardrails:audit` v0 | TBD | |
+| `guardrails:icons` v0 | TBD | |
+| `guardrails:tokens` v0 | TBD | |
+| Public beta / RubyGems publish | TBD | Before next speaking slot |