diff --git a/lib/capybara.rb b/lib/capybara.rb
index 3fc3e4c3..c0606d0d 100644
--- a/lib/capybara.rb
+++ b/lib/capybara.rb
@@ -169,13 +169,14 @@ module Capybara
     ##
     #
     # Modify a selector previously created by {Capybara.add_selector}.
-    # For example modifying the :button selector to also find divs styled
-    # to look like buttons might look like this
+    # For example, adding a new filter to the :button selector to filter based on
+    # button style (a class) might look like this
     #
     #     Capybara.modify_selector(:button) do
-    #       xpath { |locator| XPath::HTML.button(locator).or(XPath::css('div.btn')[XPath::string.n.is(locator)]) }
+    #       filter (:style, valid_values: [:primary, :secondary]) { |node, style| node[:class].split.include? "btn-#{style}" }
     #     end
     #
+    #
     # @param [Symbol] name    The name of the selector to modify
     # @yield                  A block executed in the context of the existing {Capybara::Selector}
     #
diff --git a/lib/capybara/spec/session/all_spec.rb b/lib/capybara/spec/session/all_spec.rb
index 16301fbc..afb9f2e7 100644
--- a/lib/capybara/spec/session/all_spec.rb
+++ b/lib/capybara/spec/session/all_spec.rb
@@ -16,7 +16,8 @@ Capybara::SpecHelper.spec "#all" do
 
   it "should accept an XPath instance" do
     @session.visit('/form')
-    @xpath = XPath::HTML.fillable_field('Name')
+    @xpath = Capybara::Selector.all[:fillable_field].call('Name')
+    expect(@xpath).to be_a(::XPath::Union)
     @result = @session.all(@xpath).map { |r| r.value }
     expect(@result).to include('Smith', 'John', 'John Smith')
   end
diff --git a/lib/capybara/spec/session/find_spec.rb b/lib/capybara/spec/session/find_spec.rb
index 52ecf464..c53d16e7 100644
--- a/lib/capybara/spec/session/find_spec.rb
+++ b/lib/capybara/spec/session/find_spec.rb
@@ -210,7 +210,8 @@ Capybara::SpecHelper.spec '#find' do
 
   it "should accept an XPath instance" do
     @session.visit('/form')
-    @xpath = XPath::HTML.fillable_field('First Name')
+    @xpath = Capybara::Selector.all[:fillable_field].call('First Name')
+    expect(@xpath).to be_a(::XPath::Union)
     expect(@session.find(@xpath).value).to eq('John')
   end
 
diff --git a/lib/capybara/spec/session/first_spec.rb b/lib/capybara/spec/session/first_spec.rb
index a2782127..6c20e1b9 100644
--- a/lib/capybara/spec/session/first_spec.rb
+++ b/lib/capybara/spec/session/first_spec.rb
@@ -15,7 +15,8 @@ Capybara::SpecHelper.spec '#first' do
 
   it "should accept an XPath instance" do
     @session.visit('/form')
-    @xpath = XPath::HTML.fillable_field('First Name')
+    @xpath = Capybara::Selector.all[:fillable_field].call('First Name')
+    expect(@xpath).to be_a(::XPath::Union)
     expect(@session.first(@xpath).value).to eq('John')
   end