Add guide page for the password field

guide/content/form-elements/password.slim

@@ -0,0 +1,31 @@
+---
+title: Password fields
+---
+
+markdown:
+  This component allows users to enter a password, with an option to show what they’ve entered as plain text.
+
+  Use this component whenever you need users to create or enter a password.
+
+== render('/partials/example.*',
+  caption: 'A default password field',
+  code: default_password)
+
+== render('/partials/example.*',
+  caption: 'A password field with a custom label, caption and hint',
+  code: password_with_a_captioned_heading_label_and_hint) do
+  markdown:
+    The password field's title, caption and hint can be customised in the usual way.
+
+== render('/partials/example.*',
+  caption: 'Password field with custom text',
+  code: password_with_custom_text) do
+  markdown:
+    The component's text can be customised or localised by providing the following arguments:
+
+  ul.govuk-list.govuk-list--bullet
+    li <code>show_password_text</code> and <code>hide_password_text</code> set the text on the button
+    li <code>show_password_aria_label_text</code> and <code>hide_password_aria_label_text</code> control the text exposed to assistive technologies like screen readers
+    li <code>password_shown_announcement_text</code> and <code>password_hidden_announcement_text</code> control announcements made to screen reader users when the button is clicked
+
+== render('/partials/related-navigation.*', links: password_info)

guide/lib/examples/password.rb

@@ -0,0 +1,31 @@
+module Examples
+  module Password
+    def default_password
+      <<~PASSWORD
+        = f.govuk_password_field :password, label: { text: "Enter your password" }
+      PASSWORD
+    end
+
+    def password_with_a_captioned_heading_label_and_hint
+      <<~PASSWORD
+        = f.govuk_password_field(:pin,
+            label: { text: "Enter your PIN", tag: "h2", size: "l" },
+            caption: { text: "Security", size: "m" },
+            hint: { text: "Your PIN was emailed to you when you registered for this service" })
+      PASSWORD
+    end
+
+    def password_with_custom_text
+      <<~PASSWORD
+        = f.govuk_password_field(:secret_code,
+            label: { text: "Enter your secret code" },
+            show_password_text: "Display",
+            hide_password_text: "Conceal",
+            show_password_aria_label_text: "Display the secret code",
+            hide_password_aria_label_text: "Conceal the secret code",
+            password_shown_announcement_text: "The secret code has been displayed",
+            password_hidden_announcement_text: "The secret code has been concealed")
+      PASSWORD
+    end
+  end
+end

guide/lib/helpers.rb

@@ -35,6 +35,7 @@
 use_helper Examples::ErrorHandling
 use_helper Examples::InjectingContent
 use_helper Examples::Localisation
+use_helper Examples::Password
 
 use_helper Setup::FormBuilderObjects
 use_helper Setup::ExampleData

guide/lib/helpers/link_helpers.rb

@@ -24,6 +24,7 @@ def navigation_links
           "Checkboxes" => "/form-elements/checkboxes/",
           "Date input" => "/form-elements/date-input/",
           "File upload" => "/form-elements/file-upload/",
+          "Password fields" => "/form-elements/password/",
           "Radios" => "/form-elements/radios/",
           "Select" => "/form-elements/select/",
           "Submit button" => "/form-elements/submit/",

guide/lib/helpers/person.rb

@@ -14,6 +14,13 @@ class Person
     :national_insurance_number_without_spacing,
   )
 
+  # password examples
+  attr_accessor(
+    :password,
+    :pin,
+    :secret_code
+  )
+
   # width examples
   attr_accessor(
     :twenty,

guide/lib/helpers/related_info.rb

@@ -88,5 +88,13 @@ def file_info
         'MDN file upload documentation' => 'https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file'
       }
     end
+
+    def password_info
+      {
+        'Form builder documentation for password inputs' => 'https://www.rubydoc.info/gems/govuk_design_system_formbuilder/GOVUKDesignSystemFormBuilder/Builder#govuk_password_field-instance_method',
+        'GOV.UK design system radios component' => 'https://design-system.service.gov.uk/components/password-input/',
+        'MDN radio button documentation' => 'https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/password'
+      }
+    end
   end
 end