Merge pull request #6106 from department-of-veterans-affairs/fix/pattern-link-formatting

Update pattern link formatting and improve consistency

Author: danbrady

.github/instructions/pattern-links.instructions.md

@@ -0,0 +1,120 @@
+---
+applyTo: "src/**/*.md"
+---
+
+# Pattern page link formatting
+
+When creating or reviewing links to pattern pages, always use the full URL path including the category subdirectory.
+
+## Pattern URL structure
+
+Pattern pages primarily use these category subdirectories:
+- `ask-users-for` — Patterns for collecting information from users
+- `help-users-to` — Patterns for helping users accomplish tasks
+- `html` — HTML pattern content stored under `src/_patterns/html/`
+
+**Required link format**: `/patterns/[category]/[pattern-name]`
+
+## Link text formatting rules
+
+**Pattern link text must:**
+1. **Capitalize only the first letter** of the pattern name in the link text (e.g. "Ask users for" or "Help users to"). The rest of the pattern name uses sentence case — no mid-word capitals except for proper nouns (e.g., "Social Security number") and acronyms. For example:
+   - ✅ `[Ask users for names]` — "names" is all lowercase
+   - ✅ `[Ask users for a Social Security number]` — "Social Security" is a proper noun
+   - ✅ `[Help users to update prefilled information]` — "update" and "prefilled" are lowercase
+   - ❌ `[Ask users for Names]` — "Names" is not a proper noun and should not be capitalized
+   - ❌ `[Help users to Update prefilled information]` — "Update" should be lowercase
+   - ❌ `[Help users to Know when...]` — "Know" should be lowercase
+2. **Never include ellipses** (`...` or `…`)
+3. **Never include quotes** around or within the link text, including:
+   - ❌ `["Help users to..." pattern]` — Quotes around the link text
+   - ❌ `[Help users to "update" information]` — Quotes within the link text
+   - ❌ `["Update prefilled information"]` — Quotes around entire link text
+4. Include the category prefix when the context requires it
+
+## Examples
+
+**Correct link text:**
+- ✅ `[Names]({{ site.baseurl }}/patterns/ask-users-for/names)`
+- ✅ `[Phone numbers]({{ site.baseurl }}/patterns/ask-users-for/phone-numbers)`
+- ✅ `[Ask users for names]({{ site.baseurl }}/patterns/ask-users-for/names)`
+- ✅ `[Ask users for a single response]({{ site.baseurl }}/patterns/ask-users-for/a-single-response)`
+- ✅ `[Update prefilled information]({{ site.baseurl }}/patterns/help-users-to/update-prefilled-information)`
+- ✅ `[Help users to update prefilled information]({{ site.baseurl }}/patterns/help-users-to/update-prefilled-information)`
+- ✅ `[Complete a sub-task]({{ site.baseurl }}/patterns/help-users-to/complete-a-sub-task)`
+- ✅ With anchor: `[Dates]({{ site.baseurl }}/patterns/ask-users-for/dates#content-considerations)`
+
+**Incorrect link text:**
+- ❌ `[ask users for names]` — First letter not capitalized
+- ❌ `[Ask users for... names]` — Contains ellipses
+- ❌ `[Help users to... Update prefilled information]` — Contains ellipses AND mid-word capital
+- ❌ `["Update prefilled information" pattern]` — Contains quotes
+- ❌ `[Ask users for… names]` — Contains ellipsis character
+- ❌ `[Help users to Know when...]` — Mid-word capital ("Know" should be "know")
+- ❌ `[Help users to Update Prefilled information]` — Mid-word capitals ("Update" and "Prefilled" should be lowercase)
+- ❌ `["Help users to manage benefits" pattern]` — Quotes around link text
+- ❌ The `"[Help users to update...]"` pattern — Quotes wrapping the entire markdown link
+
+**Incorrect URLs:**
+- ❌ `/patterns/names` — Missing category subdirectory
+- ❌ `/patterns/update-prefilled-information` — Missing category subdirectory
+- ❌ `patterns/help-users-to/names` — Missing leading slash
+- ❌ Relative paths like `../patterns/help-users-to/names`
+
+## Pattern name formatting in text
+
+When referencing patterns in prose:
+- Use the pattern's official title as written on the pattern page, and keep capitalization consistent
+- Include "pattern" when first mentioned: "the Update prefilled information pattern"
+- Link pattern names on first reference per page
+- You may refer to the category in prose: "the Ask users for... patterns" or "the Help users to... category"
+
+## Common pattern links
+
+**Ask users for... patterns:**
+- Addresses: `/patterns/ask-users-for/addresses`
+- Dates: `/patterns/ask-users-for/dates`
+- Email address: `/patterns/ask-users-for/email-address`
+- Names: `/patterns/ask-users-for/names`
+- Phone numbers: `/patterns/ask-users-for/phone-numbers`
+- Signature: `/patterns/ask-users-for/signature`
+- Single response: `/patterns/ask-users-for/a-single-response`
+- Social Security or VA file number: `/patterns/ask-users-for/social-security-number`
+
+**Help users to... patterns:**
+- Complete a sub-task: `/patterns/help-users-to/complete-a-sub-task`
+- Know when their information is prefilled: `/patterns/help-users-to/know-when-their-information-is-prefilled`
+- Update prefilled information: `/patterns/help-users-to/update-prefilled-information`
+
+## Validation checklist
+
+When reviewing or editing pattern links, check for:
+
+1. **Capitalization errors:**
+   - ✅ First letter of pattern name is capitalized (or lowercase if mid-sentence reference)
+   - ✅ Proper nouns and acronyms retain their standard capitalization (e.g., "Social Security number")
+   - ❌ Unnecessary mid-word capitals like "Know", "Update", "Prefilled", "Names" (not proper nouns)
+   - Search patterns: `[Help users to [A-Z]`, `[Ask users for [A-Z][a-z]+ [A-Z]`
+
+2. **Ellipsis errors:**
+   - ❌ Three-dot ellipsis `...` in link text
+   - ❌ Em dash ellipsis `…` in link text
+   - Search pattern: `\.\.\.|…` in links to pattern pages
+
+3. **Quote errors:**
+   - ❌ Quotes around the full link text: `["pattern name"]`
+   - ❌ Quotes before the opening bracket: `"[pattern name]"`
+   - ❌ Quotes inside link text: `["pattern" name]`
+   - Search patterns: `"\[.*patterns/(ask-users-for|help-users-to)`, `\[".*"\]`
+
+4. **URL structure:**
+   - ✅ Full path with category: `/patterns/[category]/[pattern-name]`
+   - ❌ Missing category subdirectory
+   - ❌ Missing leading slash or using relative paths
+
+## Finding the correct path
+
+To verify a pattern's URL:
+1. Check the pattern's markdown file in `src/_patterns/[category]/`
+2. Look at the `permalink` field in the YAML front matter
+3. Use that exact path in your link

src/_components/alert/index.md

@@ -298,7 +298,7 @@ Displaying multiple alerts should be avoided. However, when you need to display
 <p>
 <va-link-action
   href="{{ site.baseurl }}/patterns/help-users-to/recover-from-errors"
-  text="Review the Help users to...Recover from errors pattern"
+  text="Review the Help users to recover from errors pattern"
   type="secondary"
 ></va-link-action>
 </p>

src/_components/form/telephone-input.md

@@ -63,7 +63,7 @@ Whenever the component is modified it emits a `vaContact` event that includes th
 
 
 ## Content considerations
-Content for both variations can be found in [Ask users for... Phone numbers pattern]({{ site.baseurl }}/patterns/ask-users-for/phone-numbers).
+Content for both variations can be found in [Ask users for phone numbers pattern]({{ site.baseurl }}/patterns/ask-users-for/phone-numbers).
 
 ## Accessibility considerations
 

src/_components/service-list-item.md

@@ -1,7 +1,7 @@
 ---
 layout: component
 title: Service List Item
-intro-text: The Service List Item summarizes a benefit or tool. For example, a Service List Item could show the most important details about an appointment, prescription, or benefit. It shows high-level details, offers a link to view more information, and can alert the user to any actions that need to be taken. It is always displayed in a list, as described in the “Help Users to… Manage Benefits and Tools” pattern.
+intro-text: The Service List Item summarizes a benefit or tool. For example, a Service List Item could show the most important details about an appointment, prescription, or benefit. It shows high-level details, offers a link to view more information, and can alert the user to any actions that need to be taken. It is always displayed in a list, as described in the “Help users to manage benefits and tools” pattern.
 research-title: Service List Item
 figma-link-web: https://www.figma.com/design/afurtw4iqQe6y4gXfNfkkk/VADS-Component-Library?m=auto&node-id=31161-83&t=HFKAGuzWFnrLMXTF-1
 contributors: Lynn Stahl (Agile Six), Adam Whitlock (Ad Hoc), Belle Poopongpanit (Agile Six), Christine Rose Steiffer (Agile Six), Kristen Faiferlick (Ad Hoc)
@@ -42,7 +42,7 @@ anchors:
 * **Benefit**: Aid or assistance provided by VA to Veterans, family members, or caretakers. Examples include health care, education and training, disability compensation, life insurance, and pension.
 * **Tool**: A digital product that Veterans, family members, or caretakers use to manage benefits. Examples include appointments, prescriptions, payments, secure messages,  and claims.
 * **Service**: A term used to describe both benefits and tools.
-* **Service List**: A list of services. The [“Help Users to… Manage Benefits and Tools” pattern]({{ site.baseurl }}/patterns/help-users-to/manage-benefits-and-tools) describes how to build a Service list.
+* **Service List**: A list of services. The [Help users to manage benefits and tools pattern]({{ site.baseurl }}/patterns/help-users-to/manage-benefits-and-tools) describes how to build a Service list.
 * **Service List Item**: An item in a service list. Each item contains a summary of the benefit or tool, with a link to for the user to get more information. This component explains how to use and build a Service List Item.
 
 ### When to use Service List Item

src/_includes/content/addresses.md

@@ -36,6 +36,6 @@ New York, NY 67890 <br/>
 ### Zip codes and postal codes
 
 - When we know an address is a U.S. address, use “zip code.” If the address is outside the U.S. or if you’re unsure of the country, use “postal code.”<br>
-**Note:** The [Ask users for…Addresses pattern](https://design.va.gov/patterns/ask-users-for/addresses) uses “postal code” for the field label. But the error message will say “Enter a valid 5-digit zip code” if we know the address is in the U.S.
+**Note:** The [Ask users for addresses pattern](https://design.va.gov/patterns/ask-users-for/addresses) uses “postal code” for the field label. But the error message will say “Enter a valid 5-digit zip code” if we know the address is in the U.S.
 -	When Veterans fill out their address, we don’t require them to include the extra 4 digits of their zip code. They only need to provide the 5-digit zip code.
 -	When we provide an address to Veterans, we sometimes include the extra 4 digits of the zip code. If we include the extra 4 digits, use a hyphen (ex. 12345-6789).

src/_includes/content/whats-new/december-2025.md

@@ -63,7 +63,7 @@ When possible, keep error and alert message titles (headings) to 50 characters,
 
 ### Patterns
 
-#### [Help users to... Recover from errors](https://design.va.gov/patterns/help-users-to/recover-from-errors)
+#### [Help users to recover from errors](https://design.va.gov/patterns/help-users-to/recover-from-errors)
 
 - Made style guide edits throughout **Step 1** to match current guidance
 - Added guidance on heading/title length:

src/_patterns/ask-users-for/files.md

@@ -72,7 +72,7 @@ Use the [File input]({{ site.baseurl }}/components/form/file-input) component al
 #### Multiple file upload
 
 * If users only need to upload files and don't need to answer separate questions about each one, use the multiple file upload pattern. This pattern lets users add files one at a time (not as a single batch selection) and review or remove each file before continuing.
-* If users also need to provide additional information about each file, use the [Ask for... Multiple Responses]({{ site.baseurl }}/patterns/ask-users-for/multiple-responses) pattern with single file upload inputs.
+* If users also need to provide additional information about each file, use the [Ask users for multiple responses]({{ site.baseurl }}/patterns/ask-users-for/multiple-responses) pattern with single file upload inputs.
 
 #### Additional questions about the file
 

src/_patterns/ask-users-for/housing-status.md

@@ -56,7 +56,7 @@ Answering in the affirmative to "I have another housing risk not listed here" se
 
 {% include component-example.html alt="An example of asking users for other housing risks." file="/images/patterns/ask-users-for/housing-status/other-housing-risks.png" caption="An example of asking a user if they have other housing risks." class="x2" %}
 
-Answering in the affirmative to "None of these situations apply to me" sends the user to the mailing address page which users our [address pattern]({{ site.baseurl }}/patterns/ask-users-for/addresses). They do not see the conditional page asking if they have a mailing address or not.
+Answering in the affirmative to "None of these situations apply to me" sends the user to the mailing address page which uses [Ask users for addresses pattern]({{ site.baseurl }}/patterns/ask-users-for/addresses). They do not see the conditional page asking if they have a mailing address or not.
 
 In addition, it may be appropriate to ask the user for a point of contact to assist us in contacting the person submitting the form.
 

src/_patterns/ask-users-for/marital-information.md

@@ -118,7 +118,7 @@ This optional section features the [Multiple Responses]({{ site.baseurl }}/patte
 
 * If a form requires file uploads (for example, a marriage certificate or divorce decree), state that these files are needed on the form introduction page.
 * As the user moves through the form, if they provide a response that triggers conditionally-required file uploads, explain why the file upload is needed. For example, if a user indicates that they were married in a way that is not among the standard responses, include text like this: "Based on your answer, you'll need to provide supporting documents to help us understand your marital status. We'll ask you to upload these documents on the next screen [or on the final screen of the form, depending on your form's situation]."
-* If you are asking only one question on a page, the question label should be an h3, as shown in the [Ask Users For... A Single Response]({{ site.baseurl }}/patterns/ask-users-for/a-single-response#annotated) pattern. However, if you are asking multiple questions per page, give the page a descriptive page title as an h3 and use standard (non-header) labels for questions.
+* If you are asking only one question on a page, the question label should be an h3, as shown in the [Ask users for a single response]({{ site.baseurl }}/patterns/ask-users-for/a-single-response#annotated) pattern. However, if you are asking multiple questions per page, give the page a descriptive page title as an h3 and use standard (non-header) labels for questions.
 
 
 ## Code usage

src/_patterns/ask-users-for/multiple-responses.md

@@ -51,7 +51,7 @@ Use this pattern when users need to add similar information multiple times, such
 
 ### When to not use multi-page
 
-* **Most of the information being requested is already available.** If we have most of the information being requested already then the "Add item" variation is preferred. If the information we have on file is contact information coming from VA Profile API then the [Help users to... update prefilled information pattern]({{ site.baseurl }}/patterns/help-users-to/update-prefilled-information) is preferred.
+* **Most of the information being requested is already available.** If we have most of the information being requested already then the "Add item" variation is preferred. If the information we have on file is contact information coming from VA Profile API then the [Help users to update prefilled information pattern]({{ site.baseurl }}/patterns/help-users-to/update-prefilled-information) is preferred.
 
 ### Required vs Optional multi-page patterns