|
| 1 | +--- |
| 2 | +applyTo: "src/**/*.md" |
| 3 | +--- |
| 4 | + |
| 5 | +# Pattern page link formatting |
| 6 | + |
| 7 | +When creating or reviewing links to pattern pages, always use the full URL path including the category subdirectory. |
| 8 | + |
| 9 | +## Pattern URL structure |
| 10 | + |
| 11 | +Pattern pages primarily use these category subdirectories: |
| 12 | +- `ask-users-for` — Patterns for collecting information from users |
| 13 | +- `help-users-to` — Patterns for helping users accomplish tasks |
| 14 | +- `html` — HTML pattern content stored under `src/_patterns/html/` |
| 15 | + |
| 16 | +**Required link format**: `/patterns/[category]/[pattern-name]` |
| 17 | + |
| 18 | +## Link text formatting rules |
| 19 | + |
| 20 | +**Pattern link text must:** |
| 21 | +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: |
| 22 | + - ✅ `[Ask users for names]` — "names" is all lowercase |
| 23 | + - ✅ `[Ask users for a Social Security number]` — "Social Security" is a proper noun |
| 24 | + - ✅ `[Help users to update prefilled information]` — "update" and "prefilled" are lowercase |
| 25 | + - ❌ `[Ask users for Names]` — "Names" is not a proper noun and should not be capitalized |
| 26 | + - ❌ `[Help users to Update prefilled information]` — "Update" should be lowercase |
| 27 | + - ❌ `[Help users to Know when...]` — "Know" should be lowercase |
| 28 | +2. **Never include ellipses** (`...` or `…`) |
| 29 | +3. **Never include quotes** around or within the link text, including: |
| 30 | + - ❌ `["Help users to..." pattern]` — Quotes around the link text |
| 31 | + - ❌ `[Help users to "update" information]` — Quotes within the link text |
| 32 | + - ❌ `["Update prefilled information"]` — Quotes around entire link text |
| 33 | +4. Include the category prefix when the context requires it |
| 34 | + |
| 35 | +## Examples |
| 36 | + |
| 37 | +**Correct link text:** |
| 38 | +- ✅ `[Names]({{ site.baseurl }}/patterns/ask-users-for/names)` |
| 39 | +- ✅ `[Phone numbers]({{ site.baseurl }}/patterns/ask-users-for/phone-numbers)` |
| 40 | +- ✅ `[Ask users for names]({{ site.baseurl }}/patterns/ask-users-for/names)` |
| 41 | +- ✅ `[Ask users for a single response]({{ site.baseurl }}/patterns/ask-users-for/a-single-response)` |
| 42 | +- ✅ `[Update prefilled information]({{ site.baseurl }}/patterns/help-users-to/update-prefilled-information)` |
| 43 | +- ✅ `[Help users to update prefilled information]({{ site.baseurl }}/patterns/help-users-to/update-prefilled-information)` |
| 44 | +- ✅ `[Complete a sub-task]({{ site.baseurl }}/patterns/help-users-to/complete-a-sub-task)` |
| 45 | +- ✅ With anchor: `[Dates]({{ site.baseurl }}/patterns/ask-users-for/dates#content-considerations)` |
| 46 | + |
| 47 | +**Incorrect link text:** |
| 48 | +- ❌ `[ask users for names]` — First letter not capitalized |
| 49 | +- ❌ `[Ask users for... names]` — Contains ellipses |
| 50 | +- ❌ `[Help users to... Update prefilled information]` — Contains ellipses AND mid-word capital |
| 51 | +- ❌ `["Update prefilled information" pattern]` — Contains quotes |
| 52 | +- ❌ `[Ask users for… names]` — Contains ellipsis character |
| 53 | +- ❌ `[Help users to Know when...]` — Mid-word capital ("Know" should be "know") |
| 54 | +- ❌ `[Help users to Update Prefilled information]` — Mid-word capitals ("Update" and "Prefilled" should be lowercase) |
| 55 | +- ❌ `["Help users to manage benefits" pattern]` — Quotes around link text |
| 56 | +- ❌ The `"[Help users to update...]"` pattern — Quotes wrapping the entire markdown link |
| 57 | + |
| 58 | +**Incorrect URLs:** |
| 59 | +- ❌ `/patterns/names` — Missing category subdirectory |
| 60 | +- ❌ `/patterns/update-prefilled-information` — Missing category subdirectory |
| 61 | +- ❌ `patterns/help-users-to/names` — Missing leading slash |
| 62 | +- ❌ Relative paths like `../patterns/help-users-to/names` |
| 63 | + |
| 64 | +## Pattern name formatting in text |
| 65 | + |
| 66 | +When referencing patterns in prose: |
| 67 | +- Use the pattern's official title as written on the pattern page, and keep capitalization consistent |
| 68 | +- Include "pattern" when first mentioned: "the Update prefilled information pattern" |
| 69 | +- Link pattern names on first reference per page |
| 70 | +- You may refer to the category in prose: "the Ask users for... patterns" or "the Help users to... category" |
| 71 | + |
| 72 | +## Common pattern links |
| 73 | + |
| 74 | +**Ask users for... patterns:** |
| 75 | +- Addresses: `/patterns/ask-users-for/addresses` |
| 76 | +- Dates: `/patterns/ask-users-for/dates` |
| 77 | +- Email address: `/patterns/ask-users-for/email-address` |
| 78 | +- Names: `/patterns/ask-users-for/names` |
| 79 | +- Phone numbers: `/patterns/ask-users-for/phone-numbers` |
| 80 | +- Signature: `/patterns/ask-users-for/signature` |
| 81 | +- Single response: `/patterns/ask-users-for/a-single-response` |
| 82 | +- Social Security or VA file number: `/patterns/ask-users-for/social-security-number` |
| 83 | + |
| 84 | +**Help users to... patterns:** |
| 85 | +- Complete a sub-task: `/patterns/help-users-to/complete-a-sub-task` |
| 86 | +- Know when their information is prefilled: `/patterns/help-users-to/know-when-their-information-is-prefilled` |
| 87 | +- Update prefilled information: `/patterns/help-users-to/update-prefilled-information` |
| 88 | + |
| 89 | +## Validation checklist |
| 90 | + |
| 91 | +When reviewing or editing pattern links, check for: |
| 92 | + |
| 93 | +1. **Capitalization errors:** |
| 94 | + - ✅ First letter of pattern name is capitalized (or lowercase if mid-sentence reference) |
| 95 | + - ✅ Proper nouns and acronyms retain their standard capitalization (e.g., "Social Security number") |
| 96 | + - ❌ Unnecessary mid-word capitals like "Know", "Update", "Prefilled", "Names" (not proper nouns) |
| 97 | + - Search patterns: `[Help users to [A-Z]`, `[Ask users for [A-Z][a-z]+ [A-Z]` |
| 98 | + |
| 99 | +2. **Ellipsis errors:** |
| 100 | + - ❌ Three-dot ellipsis `...` in link text |
| 101 | + - ❌ Em dash ellipsis `…` in link text |
| 102 | + - Search pattern: `\.\.\.|…` in links to pattern pages |
| 103 | + |
| 104 | +3. **Quote errors:** |
| 105 | + - ❌ Quotes around the full link text: `["pattern name"]` |
| 106 | + - ❌ Quotes before the opening bracket: `"[pattern name]"` |
| 107 | + - ❌ Quotes inside link text: `["pattern" name]` |
| 108 | + - Search patterns: `"\[.*patterns/(ask-users-for|help-users-to)`, `\[".*"\]` |
| 109 | + |
| 110 | +4. **URL structure:** |
| 111 | + - ✅ Full path with category: `/patterns/[category]/[pattern-name]` |
| 112 | + - ❌ Missing category subdirectory |
| 113 | + - ❌ Missing leading slash or using relative paths |
| 114 | + |
| 115 | +## Finding the correct path |
| 116 | + |
| 117 | +To verify a pattern's URL: |
| 118 | +1. Check the pattern's markdown file in `src/_patterns/[category]/` |
| 119 | +2. Look at the `permalink` field in the YAML front matter |
| 120 | +3. Use that exact path in your link |
0 commit comments