Start documentation for PVC accessibility linting rules

docs/content/guides/accessibility/tooltipped_migration.md

@@ -0,0 +1,77 @@
+---
+title: Tooltipped migration
+---
+
+## Rule details
+
+The Primer CSS tooltip set using the `.tooltipped` class has been deprecated. There are major accessibility concerns with using this deprecated tooltip so please take action.
+
+Depending on your usecase, there are two potential migration paths.
+
+## 1. Don't use a tooltip.
+
+Tooltips are not visible by default and can easily go unnoticed, so they should only be used as a last resort, and should never be used to convey critical information.
+
+If `.tooltipped` is being set on a non-interactive element  (e.g. `<span>`, `<div>`, `<p>`), please consider an alternative. There is no way to make a tooltip fully accessible on a non-interactive element. See [Tooltip alternatives](https://primer.style/design/guides/accessibility/tooltip-alternatives/) or consult a designer.
+
+## 2. Migrate to the more accessible PVC tooltip
+
+If your tooltip is appropriately set on an interactive element, you can migrate to the latest [Tooltip component](https://primer.style/design/components/tooltip/rails/alpha) which has been implemented with accessibility considerations.
+
+## Example scenarios
+
+### Scenario 1
+
+Flagged code:
+
+```html
+<span aria-label="Mona Lisa" class="tooltipped tooltipped-s">
+  Mona Lisa
+</span>
+```
+
+In this above example, we can get rid of the tooltip because it redundantly repeats the text content, like the following
+
+```html
+<span>Mona Lisa</span>
+```
+
+### Scenario 2
+
+Flagged code:
+
+```html
+<button aria-label="This action is irreversible" class="tooltipped tooltipped-n">
+  Submit
+</button>
+```
+
+In this above example, the information that is conveyed using the tooltip is critical so we should not be using a tooltip to convey it. Update the design to always persist the text.
+
+### Scenario 3
+
+Flagged code:
+
+```html
+<a aria-label="A set of guidelines, principles, and patterns for designing and building UI at GitHub." class="tooltipped tooltipped-s" href="primer.style">
+  Primer
+</a>
+```
+
+In this above example, the information conveyed in this tooltip isn't necessarily critical but supplements the link. If we decide to permanently persist it,we can update the markup like so:
+
+```html
+<a aria-describedby href="https://primer.style/design/">
+  Primer
+</a>
+<p id="primer-link-help">A set of guidelines, principles, and patterns for designing and building UI at GitHub.</p>
+```
+
+A tooltip is also a viable option in this scenario. We can render an accessible tooltip by using the slot of the Link component and setting the tooltip type to `:description`:
+
+```.rb
+render(Primer::Beta::Link.new(href: "https://primer.style/design/", id: "primer-link")) do |component|
+  component.with_tooltip(type: :description, text: "A set of guidelines, principles, and patterns for designing and building UI at GitHub.")
+  "Primer"
+end
+```

lib/primer/view_components/linters/tooltipped_migration.rb

@@ -10,9 +10,7 @@ class TooltippedMigration < Linter
           include LinterRegistry
           include Helpers::RuleHelpers
 
-          MIGRATE_TO_NEWER_TOOLTIP = ".tooltipped has been deprecated. Tooltip should never be set on a non-interactive element (e.g. <span>, <div>, <li>). " \
-            "Find alternatives in https://primer.style/design/guides/accessibility/tooltip-alternatives/. " \
-            "If you're setting a tooltip on an interactive element, use the latest tooltip in https://primer.style/view-components."
+          MIGRATE_TO_NEWER_TOOLTIP = ".tooltipped has been deprecated. There are major accessibility concerns with using this tooltip so please take action. See https://github.com/primer/view_components/blob/main/docs/content/guides/accessibility/tooltipped_migration.md."
           TOOLTIPPED_RUBY_PATTERN = /classes:.*tooltipped|class:.*tooltipped/.freeze
 
           def run(processed_source)

test/lib/erblint/tooltipped_migration_test.rb

@@ -42,7 +42,7 @@ def test_does_not_warn_if_inline_disable_comment
       <%= render SomeComponent.new(classes: "tooltipped") do %><%# erblint:disable Primer::Accessibility::TooltippedMigration %>
     HTML
     @linter.run_and_update_offense_status(processed_source)
-    offenses = @linter.offenses.reject(&:disabled?) # Reject offenses marked as disabled. (This happens at the runner level so we repliace it here)
+    offenses = @linter.offenses.reject(&:disabled?) # Reject offenses marked as disabled. (This happens at the ERB Lint runner level so we replace it here, just for testing)
     assert_equal 0, offenses.count
   end
 end