@planningcenter/tapestry 4.14.0-rc.0 → 4.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (141) hide show
  1. package/dist/components/DataTable/ActiveFilterInstance.d.ts +3 -3
  2. package/dist/components/DataTable/ActiveFilterInstance.d.ts.map +1 -1
  3. package/dist/components/DataTable/ActiveFilterInstance.js +5 -5
  4. package/dist/components/DataTable/ActiveFilterInstance.js.map +1 -1
  5. package/dist/components/DataTable/ActiveFilters.d.ts.map +1 -1
  6. package/dist/components/DataTable/ActiveFilters.js +3 -1
  7. package/dist/components/DataTable/ActiveFilters.js.map +1 -1
  8. package/dist/components/DataTable/DataTable.d.ts +27 -7
  9. package/dist/components/DataTable/DataTable.d.ts.map +1 -1
  10. package/dist/components/DataTable/DataTable.js +34 -5
  11. package/dist/components/DataTable/DataTable.js.map +1 -1
  12. package/dist/components/DataTable/DataTableColumn.d.ts +15 -3
  13. package/dist/components/DataTable/DataTableColumn.d.ts.map +1 -1
  14. package/dist/components/DataTable/DataTableColumnTypes.d.ts +2 -2
  15. package/dist/components/DataTable/DataTableColumnTypes.d.ts.map +1 -1
  16. package/dist/components/DataTable/DataTableColumnTypes.js +6 -12
  17. package/dist/components/DataTable/DataTableColumnTypes.js.map +1 -1
  18. package/dist/components/DataTable/FilterTypes.d.ts +2 -0
  19. package/dist/components/DataTable/FilterTypes.d.ts.map +1 -1
  20. package/dist/components/DataTable/RowActions.d.ts +7 -0
  21. package/dist/components/DataTable/RowActions.d.ts.map +1 -1
  22. package/dist/components/DataTable/RowActions.js +6 -3
  23. package/dist/components/DataTable/RowActions.js.map +1 -1
  24. package/dist/components/DataTable/TableActions.d.ts +5 -0
  25. package/dist/components/DataTable/TableActions.d.ts.map +1 -1
  26. package/dist/components/DataTable/TableActions.js +2 -1
  27. package/dist/components/DataTable/TableActions.js.map +1 -1
  28. package/dist/components/DataTable/ViewsBar.d.ts.map +1 -1
  29. package/dist/components/DataTable/ViewsBar.js +7 -1
  30. package/dist/components/DataTable/ViewsBar.js.map +1 -1
  31. package/dist/components/DataTable/dateFilter.d.ts +4 -2
  32. package/dist/components/DataTable/dateFilter.d.ts.map +1 -1
  33. package/dist/components/DataTable/dateFilter.js +22 -13
  34. package/dist/components/DataTable/dateFilter.js.map +1 -1
  35. package/dist/components/DataTable/dayFilter.d.ts.map +1 -1
  36. package/dist/components/DataTable/dayFilter.js +25 -22
  37. package/dist/components/DataTable/dayFilter.js.map +1 -1
  38. package/dist/components/DataTable/scopedFilter.d.ts +1 -1
  39. package/dist/components/DataTable/scopedFilter.d.ts.map +1 -1
  40. package/dist/components/DataTable/scopedFilter.js +56 -35
  41. package/dist/components/DataTable/scopedFilter.js.map +1 -1
  42. package/dist/components/DataTable/useSearchFilter.d.ts.map +1 -1
  43. package/dist/components/DataTable/useSearchFilter.js +2 -1
  44. package/dist/components/DataTable/useSearchFilter.js.map +1 -1
  45. package/dist/components/page-header/defineElements.js +1 -1
  46. package/dist/components/sidenav/defineElements.js +1 -1
  47. package/dist/index.d.ts +1 -0
  48. package/dist/index.d.ts.map +1 -1
  49. package/dist/index.js +1 -0
  50. package/dist/index.js.map +1 -1
  51. package/dist/packages/tapestry-wc/dist/components/{p-CBFtMIxJ.js → p-Bw5XJ46l.js} +2 -2
  52. package/dist/packages/tapestry-wc/dist/components/{p-CBFtMIxJ.js.map → p-Bw5XJ46l.js.map} +1 -1
  53. package/dist/packages/tapestry-wc/dist/components/{p-BbuNAv9q.js → p-C5B21uv6.js} +3 -3
  54. package/dist/packages/tapestry-wc/dist/components/{p-BbuNAv9q.js.map → p-C5B21uv6.js.map} +1 -1
  55. package/dist/packages/tapestry-wc/dist/components/{p-DNHgMtxw.js → p-D4oSihjy.js} +2 -2
  56. package/dist/packages/tapestry-wc/dist/components/{p-DNHgMtxw.js.map → p-D4oSihjy.js.map} +1 -1
  57. package/dist/packages/tapestry-wc/dist/components/{p-A1JK45WV.js → p-DZA99jMW.js} +3 -3
  58. package/dist/packages/tapestry-wc/dist/components/{p-A1JK45WV.js.map → p-DZA99jMW.js.map} +1 -1
  59. package/dist/packages/tapestry-wc/dist/components/{p-CY_DC4d_.js → p-Dt250a7E.js} +3 -3
  60. package/dist/packages/tapestry-wc/dist/components/{p-CY_DC4d_.js.map → p-Dt250a7E.js.map} +1 -1
  61. package/dist/packages/tapestry-wc/dist/components/tds-page-header-nav.js +2 -2
  62. package/dist/packages/tapestry-wc/dist/components/tds-page-header-nav.js.map +1 -1
  63. package/dist/packages/tapestry-wc/dist/components/tds-page-header.js +3 -3
  64. package/dist/packages/tapestry-wc/dist/components/tds-page-header.js.map +1 -1
  65. package/dist/packages/tapestry-wc/dist/components/tds-sidenav-item.js +3 -3
  66. package/dist/packages/tapestry-wc/dist/components/tds-sidenav-item.js.map +1 -1
  67. package/dist/packages/tapestry-wc/dist/components/tds-sidenav-responsive-header.js +2 -2
  68. package/dist/packages/tapestry-wc/dist/components/tds-sidenav-responsive-header.js.map +1 -1
  69. package/dist/packages/tapestry-wc/dist/components/tds-sidenav-section.js +3 -3
  70. package/dist/packages/tapestry-wc/dist/components/tds-sidenav-section.js.map +1 -1
  71. package/dist/packages/tapestry-wc/dist/components/tds-sidenav.js +5 -5
  72. package/dist/packages/tapestry-wc/dist/components/tds-sidenav.js.map +1 -1
  73. package/dist/reactRender.css +1629 -1629
  74. package/dist/reactRender.css.map +1 -1
  75. package/dist/reactRenderLegacy.css +1629 -1629
  76. package/dist/reactRenderLegacy.css.map +1 -1
  77. package/dist/tapestryMount.css +1629 -1629
  78. package/dist/tapestryMount.css.map +1 -1
  79. package/dist/tapestryMountLegacy.css +1629 -1629
  80. package/dist/tapestryMountLegacy.css.map +1 -1
  81. package/dist/unstable.js +1 -0
  82. package/dist/unstable.js.map +1 -1
  83. package/dist/utilities/dataHooks.d.ts +8 -0
  84. package/dist/utilities/dataHooks.d.ts.map +1 -0
  85. package/dist/utilities/dataHooks.js +7 -0
  86. package/dist/utilities/dataHooks.js.map +1 -0
  87. package/dist/utilities/locale.d.ts +25 -0
  88. package/dist/utilities/locale.d.ts.map +1 -0
  89. package/dist/utilities/locale.js +48 -0
  90. package/dist/utilities/locale.js.map +1 -0
  91. package/docs/accessibility/accessibility.md +62 -0
  92. package/docs/components/button-group.md +44 -0
  93. package/docs/components/button.md +78 -0
  94. package/docs/components/checkbox-group.md +51 -0
  95. package/docs/components/checkbox.md +55 -0
  96. package/docs/components/combo-box.md +68 -0
  97. package/docs/components/currency-input.md +50 -0
  98. package/docs/components/date-picker.md +67 -0
  99. package/docs/components/dropdown.md +74 -0
  100. package/docs/components/field.md +44 -0
  101. package/docs/components/flex.md +66 -0
  102. package/docs/components/input.md +62 -0
  103. package/docs/components/link.md +46 -0
  104. package/docs/components/modal.md +59 -0
  105. package/docs/components/number-stepper.md +50 -0
  106. package/docs/components/page-header.md +48 -0
  107. package/docs/components/popover.md +45 -0
  108. package/docs/components/radio-group.md +47 -0
  109. package/docs/components/radio.md +62 -0
  110. package/docs/components/search-input.md +46 -0
  111. package/docs/components/segmented-control.md +60 -0
  112. package/docs/components/select.md +62 -0
  113. package/docs/components/sidenav.md +36 -0
  114. package/docs/components/text-area.md +65 -0
  115. package/docs/components/time-field.md +62 -0
  116. package/docs/components/toggle-switch.md +56 -0
  117. package/docs/content/addressing-users-in-products.md +153 -0
  118. package/docs/content/browser-tabs.md +59 -0
  119. package/docs/content/capitalization.md +69 -0
  120. package/docs/content/date-formatting.md +145 -0
  121. package/docs/content/displaying-names.md +139 -0
  122. package/docs/content/editing-and-saving.md +95 -0
  123. package/docs/content/file-size-formatting.md +44 -0
  124. package/docs/content/household-ordering.md +127 -0
  125. package/docs/content/micro-copy.md +135 -0
  126. package/docs/content/prompts.md +271 -0
  127. package/docs/content/punctuation.md +71 -0
  128. package/docs/content/sharing-nomenclature.md +67 -0
  129. package/docs/content/timezones.md +108 -0
  130. package/docs/content/tooltip-usage.md +49 -0
  131. package/docs/content/use-of-emoji.md +63 -0
  132. package/docs/content/voice-and-tone.md +251 -0
  133. package/docs/design/design-tokens.md +70 -0
  134. package/docs/design/iconography.md +60 -0
  135. package/docs/design/layout.md +237 -0
  136. package/docs/design/mobile-design-principles.md +109 -0
  137. package/docs/design/pca-design-language.md +78 -0
  138. package/docs/design/typography.md +94 -0
  139. package/docs/get-started/design-system-philosophy.md +33 -0
  140. package/docs/llms.txt +119 -0
  141. package/package.json +7 -5
@@ -0,0 +1,46 @@
1
+ ---
2
+ use_when:
3
+ - searching or filtering a list, table or page
4
+ - a search field above the content it filters
5
+ ---
6
+
7
+ # SearchInput
8
+
9
+ ## Rules
10
+
11
+ - **Do** use a search input for free-text search or filtering of a list, table, or page.
12
+ - **Do** always pass a `label`, 1–3 words in sentence case (e.g. “Search people”). Screen readers use it as the field’s name, even when it’s hidden.
13
+ - **Do** hide the label with `hideLabel` when the field stands on its own above the content it filters. The search icon and placeholder are enough context, so this is the usual case for search.
14
+ - **Do** use placeholder text to say what’s being searched (e.g. “Search people”), and match it to the hidden `label` so sighted and screen reader users get the same name.
15
+ - **Do** keep the label visible when the search input sits among other labeled fields, like in a filter form.
16
+ - **Do** pass a `description` saying how to fix the problem whenever you set `invalid`. There’s no default message, so `invalid` on its own shows only the error styling.
17
+ - **Don’t** hide the label of any other field just because a search input can; the search icon is what makes this exception work.
18
+ - **Don’t** use a search input for regular form fields like names or emails; use an Input instead.
19
+ - **Don’t** use a search input to choose a value from a set list of options; use a Combo Box instead.
20
+ - **Don’t** add your own search icon or clear button; the component includes both.
21
+
22
+ ## Guidelines
23
+
24
+ ### When to use
25
+
26
+ - Use when users type to find or filter content.
27
+ - Search inputs usually sit above the content they filter. Use `expand` to let the field fill the available space in a Flex row.
28
+ - When users need to pick a single value from many options as part of a form, use a Combo Box.
29
+
30
+ ### Content
31
+
32
+ - **Labels:** 1–3 words, sentence case (e.g. “Search people”). Usually visually hidden, but always passed.
33
+ - **Placeholder:** say what’s being searched. With the search icon, it stands in for the visible label, so keep it in step with the hidden `label`.
34
+ - **Description:** use sparingly, for search tips or constraints.
35
+
36
+ ### Interactions
37
+
38
+ - **Clear (×):** appears when the field has a value and is hovered or focused, unless it’s disabled or read-only. Clicking it empties the field and returns focus to it. It’s skipped in the tab order.
39
+ - **Escape:** when the field has a value, Escape stays within the field (browsers clear native search fields on Escape), so it doesn’t also close a surrounding dialog or popover. On an empty field it passes through as usual.
40
+
41
+ ### Sizes
42
+
43
+ | Size | Use when |
44
+ | -------------- | ----------------------------------------------- |
45
+ | `md` (default) | Most searches. |
46
+ | `lg` | Prominent search, such as at the top of a page. |
@@ -0,0 +1,60 @@
1
+ ---
2
+ use_when:
3
+ - switching between 2–5 views or modes that change the screen right away, like Table and Card
4
+ - one option is always selected
5
+ ---
6
+
7
+ # SegmentedControl
8
+
9
+ ## Rules
10
+
11
+ - **Do** use a segmented control to switch between 2 to 5 options, like views, where the change takes effect at once.
12
+ - **Do** keep segment labels short and parallel, like “Table” and “Card”.
13
+ - **Do** give every Icon Segment a `tooltip`. It is also the segment’s accessible name. Always pass the group `label`. Hide it with `hideLabel` only when something on screen already names the choice, like the heading of the pane it switches.
14
+ - **Do** use `fullWidth` only for a primary mode switch at the top of a section, modal, or pane.
15
+ - **Don’t** use a segmented control when the value must be sent in a native form submit; use a Radio Group instead.
16
+ - **Don’t** use a segmented control for more than 5 options; use a Select instead.
17
+ - **Don’t** use a segmented control to trigger actions; use a Button Group or separate buttons instead.
18
+
19
+ ## Guidelines
20
+
21
+ ### When to use
22
+
23
+ - Use when exactly one option is always selected and switching between them changes what’s on screen right away: Table/Card, Tag/Tag group.
24
+ - One segment is always selected: set `value` or `defaultValue` to one segment’s `value`.
25
+ - It doesn’t render a form input, so its value isn’t included in a native form submit. Use a Radio Group for form fields.
26
+ - For a single on/off button that isn’t part of a group, use a Toggle Button.
27
+
28
+ ### Content
29
+
30
+ - **Group label:** names what the choice controls (“View”, “Status”). It’s visible by default; use `hideLabel` only when something on screen already names the choice. It’s still announced to screen readers.
31
+ - **Segment labels:** 1–2 words in sentence case, all the same type (nouns or states). Keep them short so the control doesn’t wrap.
32
+ - **Icons:** add a `prefix` or `suffix` icon to a Segment when it helps scanning. Give each Icon Segment (icon only) a `tooltip`.
33
+
34
+ ### Interactions
35
+
36
+ - **Click or tap:** selects the segment and deselects the others.
37
+ - **Tab:** moves focus to the selected segment. The group is a single tab stop.
38
+ - **Arrow keys:** move to the previous or next segment and select it, wrapping at the ends. **Home** and **End** jump to the first and last segment.
39
+
40
+ ### Kinds
41
+
42
+ Set `kind` per segment. It controls the selected segment’s color.
43
+
44
+ | Kind | Use when |
45
+ | ------------------------------ | --------------------------------------------------- |
46
+ | `interaction-subtle` (default) | Most mode switches. |
47
+ | `neutral-subtle` | A quieter alternative. |
48
+ | `interaction-bold` | A louder alternative. |
49
+ | `success`, `warning`, `error` | Status choices like Confirmed/Unconfirmed/Declined. |
50
+
51
+ ### Sizes
52
+
53
+ | Size | Use when |
54
+ | -------------- | ----------------------------------------------- |
55
+ | `md` (default) | Most layouts. |
56
+ | `sm` | Compact layouts like toolbars and dense panels. |
57
+
58
+ ### State usage
59
+
60
+ - **Disabled:** set `disabled` on the SegmentedControl to disable every segment, or on a single Segment to disable just that option.
@@ -0,0 +1,62 @@
1
+ ---
2
+ use_when:
3
+ - choosing one option from a list of more than 5
4
+ - space is tight, like a table row, toolbar or narrow form
5
+ - people already know the options, like campuses, countries or months
6
+ ---
7
+
8
+ # Select
9
+
10
+ ## Rules
11
+
12
+ - **Do** use a select to choose a single value from a predefined list when space is limited, typically with more than 5 options.
13
+ - **Do** always pass a `label`, 1–3 words in sentence case. Screen readers use it as the field’s name, even when it’s hidden.
14
+ - **Do** keep the label visible unless something on screen already names the field, like a column header or the option it sits under. Only then hide it with `hideLabel`.
15
+ - **Do** use the placeholder to prompt a choice (“Select a country...”), not to name the field.
16
+ - **Do** use sentence case for placeholders, option text, and error messages.
17
+ - **Do** keep option text short and scannable (1-3 words), and group long lists under section headers.
18
+ - **Do** write descriptive error messages that tell users how to fix the selection.
19
+ - **Don’t** hide a label just to save space, and never use placeholder text in its place.
20
+ - **Don’t** use a select when users need to compare all options at once; use a Radio Group.
21
+
22
+ ## Guidelines
23
+
24
+ ### When to use
25
+
26
+ - Use when space is limited and options don’t need to be visible at once, typically more than 5 options or well-understood choices.
27
+ - Single selection only. Don’t add checkboxes to options.
28
+ - Don’t make users guess what options are available; use clear categories and option text.
29
+
30
+ > **Select or Combo Box?**
31
+ >
32
+ > A Select is for a fixed list people can scan. If people need to type to find an option, the options load from the server, or they can pick several, use a Combo Box.
33
+
34
+ ### Content
35
+
36
+ - **Labels:** 1–3 words, no ending punctuation. Always pass one; hide it with `hideLabel` only when something on screen already names the field.
37
+ - **Placeholder:** prompts a choice (“Select a country...”). It disappears after selection, so it can’t stand in for a label.
38
+ - **Description:** optional. Use it for extra context or, with `invalid`, to say how to fix the error. Keep it to 1–2 sentences.
39
+ - **Options:** 1-3 words. No long descriptions, and don’t hide critical information in descriptive text.
40
+ - **Error messages:** say why the selection is invalid and how to fix it.
41
+ - **Capitalization:** sentence case everywhere; capitalize only the first word and proper nouns.
42
+
43
+ ### Variations
44
+
45
+ | Variation | Use when |
46
+ | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
47
+ | Hidden label | Something on screen already names the field, like a column header. Pass `label` with `hideLabel` so it still has an accessible name. |
48
+ | Required | A choice must be made. `required` adds an asterisk to the label but doesn’t flag a blank field. When someone leaves it blank, set `invalid` and use `description` to say what to choose, like “Choose a campus.” |
49
+ | Rich options | Options need an icon or a short description. Set `complex` and pass a node `label` with a plain-text `textValue`. |
50
+
51
+ ### Menu options
52
+
53
+ | Style | Use for |
54
+ | -------- | ------------------------------------------------------------------------------------------------- |
55
+ | Default | Simple lists where all options have equal weight. |
56
+ | Groups | Long lists that fall into categories. Pass `{ label, options }`; group headers can’t be selected. |
57
+ | Dividers | Separating related options without a header. Pass `{ divider: true }`. |
58
+
59
+ ### State usage
60
+
61
+ - **Disabled:** only when the select is temporarily unavailable or waiting on another action.
62
+ - **Invalid:** when a required choice is missing, the value conflicts, or an action failed. Set `invalid` and say in `description` why the selection is invalid and how to fix it. Don’t rely on the default “Please select an option” when you can be more specific.
@@ -0,0 +1,36 @@
1
+ ---
2
+ use_when:
3
+ - secondary navigation within one page header tab, like a person’s profile sections
4
+ - a list of pages or views down the side of a page
5
+ ---
6
+
7
+ # Sidenav
8
+
9
+ ## Rules
10
+
11
+ - **Do** use a sidenav for secondary navigation through subsets of data related to one resource, alongside the page header navigation.
12
+ - **Do** mark the current page’s item `selected` (the sidenav adds `aria-current="page"`), and pass its label to `selectedItemLabel`.
13
+ - **Do** nest every `SidenavItem` in a `SidenavSection`, and set `label` to name what the sidenav navigates (it defaults to “Secondary”).
14
+ - **Do** wrap the item’s label in a `span` when you add a `.prefix` or `.suffix`, so long text truncates.
15
+ - **Don’t** add classes or styles to the item’s link or button; use a plain `a` or `button` and let the sidenav style it.
16
+ - **Don’t** use a sidenav for the top-level pages of a resource; use the page header `navigation`.
17
+
18
+ ## Guidelines
19
+
20
+ ### When to use
21
+
22
+ - Use a link (`a`) for items that go to another page, and a `button` for items that change the view in place.
23
+ - Group related items into sections. Give a section a `label` to show a heading; the section’s list is then labelled by it.
24
+ - For a deeper level of hierarchy, nest a `SidenavSection` with `subnav` inside a `SidenavItem`, after its link or button.
25
+
26
+ ### Content
27
+
28
+ - Keep item labels short: a noun or two (“Members”, “Notifications”).
29
+ - Use sentence case for items. Section labels display in uppercase.
30
+ - Put counts and badges in a `.suffix`, and icons in a `.prefix`.
31
+
32
+ ### Options
33
+
34
+ - **Section actions:** pass actions for a section heading as `labelActions` (it needs a `label`), and actions below the list as `sectionActions`.
35
+ - **Gray theme:** add the `tds-sidenav--theme-gray` class to use neutral gray backgrounds instead of interaction blue.
36
+ - **Custom toggle:** below 720px the items open in a popover. Set `popoverId` and point your own buttons’ `popovertarget` at it to open it.
@@ -0,0 +1,65 @@
1
+ ---
2
+ use_when:
3
+ - entering text that may run to several lines, like notes, comments or a description
4
+ ---
5
+
6
+ # TextArea
7
+
8
+ ## Rules
9
+
10
+ - **Do** use a text area for multi-line entry such as comments, notes, descriptions, and feedback.
11
+ - **Do** set a default height with `rows` that reflects the expected amount of content.
12
+ - **Do** always pass a `label`, 1–3 words in sentence case. Screen readers use it as the field’s name, even when it’s hidden.
13
+ - **Do** keep the label visible unless something on screen already names the field, like a heading above it. Only then hide it with `hideLabel`.
14
+ - **Do** use placeholder text only for a sample value, or leave it out.
15
+ - **Do** show specific error messages that explain how to fix the issue.
16
+ - **Do** set `required` on fields people must fill in; the label shows an asterisk (\*). If you hide the label, its asterisk is hidden too. Show that the field is required somewhere people can see, like in the heading above it.
17
+ - **Don’t** hide a label just to save space, and never use placeholder text in its place.
18
+ - **Don’t** use a text area for short, single-line input; use an Input instead.
19
+ - **Don’t** set `invalid` without a `description`. The default “This field is required” is wrong for any other error, so write one that says how to fix it.
20
+ - **Don’t** disable resize unless layout constraints specifically require it.
21
+
22
+ ## Guidelines
23
+
24
+ ### When to use
25
+
26
+ - Use when users need to enter text that may span multiple lines, such as comment fields, note-taking areas, or feedback forms.
27
+ - Don’t use it when a select, radio button, or checkbox would be clearer.
28
+ - Don’t make the text area unnecessarily wide or narrow for the expected content.
29
+
30
+ ### Validation
31
+
32
+ - Check the value when the form is submitted by default.
33
+ - Check as people type only when instant feedback helps them get it right, like a minimum length for a written response.
34
+ - Once an error shows, clear it as soon as the value is fixed, so people know their change worked.
35
+
36
+ ### Content
37
+
38
+ - **Labels:** concise and descriptive, so it’s clear what input is expected. 1–3 words, sentence case, no ending punctuation.
39
+ - **Placeholder:** optional. A sample value only (e.g. “The page froze after I clicked Save”), not instructions or a replacement for a label. It disappears when the user starts typing.
40
+ - **Descriptive text:** brief guidance on format or constraints, 1–2 sentences. Don’t hide important instructions in a tooltip or helper text. If more context is needed, use a helper shelf or support document instead.
41
+ - **Errors:** specific and actionable, so users can understand and correct their input. Avoid vague messages like “Invalid input”.
42
+
43
+ ### Sizes
44
+
45
+ | Size | Use when |
46
+ | -------------- | ----------------------------------- |
47
+ | `md` (default) | Most forms. |
48
+ | `lg` | Prominent inputs and hero sections. |
49
+
50
+ ### Height and resize
51
+
52
+ - Set the default visible height with `rows` (default 3). Use a shorter height for brief responses and a taller one for longer responses.
53
+
54
+ | Resize | Use when |
55
+ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
56
+ | `vertical` (default) | Most cases. Users can make the field taller or shorter. |
57
+ | `none` | The layout needs a fixed height, or resizing would break surrounding content. |
58
+ | `auto` | The field should grow with its content. There’s no maximum height, and browsers without `field-sizing` fall back to `vertical`. |
59
+
60
+ ### State usage
61
+
62
+ - **Required:** when the user can’t proceed without filling in the field.
63
+ - **Invalid:** when a required field is empty, the value creates a conflict, or the action fails. Include a message that says how to fix it.
64
+ - **Disabled:** when the field is unavailable for input. Consider descriptive text explaining why.
65
+ - **Read-only:** when content should be read and copied but not edited. Unlike disabled, it can receive focus and is submitted with forms.
@@ -0,0 +1,62 @@
1
+ ---
2
+ use_when:
3
+ - entering a specific time of day, like a service or event time
4
+ ---
5
+
6
+ # TimeField
7
+
8
+ ## Rules
9
+
10
+ - **Do** use a Time Field for inputs where a specific time value is required, like event or service times.
11
+ - **Do** always pass a `label`, 1–3 words in sentence case. Screen readers use it as the field’s name, even when it’s hidden.
12
+ - **Do** keep the label visible unless something on screen already names the field, like a column header or the option it sits under. Only then hide it with `hideLabel`.
13
+ - **Do** use sentence case for error messages.
14
+ - **Do** use the description to clarify constraints or context (e.g., “Available between 8:00 AM – 5:00 PM”).
15
+ - **Do** write error messages that say what’s wrong and how to fix it.
16
+ - **Don’t** hide a label just to save space.
17
+ - **Don’t** display a Time Field without context on its purpose.
18
+ - **Don’t** hide time restrictions until there’s an error; explain them in the description up front.
19
+
20
+ ## Guidelines
21
+
22
+ ### When to use
23
+
24
+ - For dates, use a Date Picker.
25
+
26
+ ### Content
27
+
28
+ - Keep the label short (1–3 words) and say which time is being set.
29
+ - Keep the description to 1–2 sentences. Use it for time constraints, not the format; the segments already show the user’s locale format.
30
+ - Use `min` and `max` to restrict the allowed range.
31
+
32
+ ### Interactions
33
+
34
+ - **Placeholder:** shows dashes (––:––) until a value is entered.
35
+ - **Segment navigation:** tabbing into the field focuses the first segment (hours); clicking a segment focuses that segment. Arrow keys or Tab move between segments.
36
+ - **Arrow Up / Arrow Down:** increment or decrement the focused segment.
37
+ - **0–9:** type a digit; focus moves to the next segment once the segment is complete (e.g., typing 1 then 2 sets the hour to 12).
38
+ - **AM/PM:** in 12-hour format, click the AM/PM segment, press A or P, or use the arrow keys to switch.
39
+
40
+ ### Localization
41
+
42
+ The Time Field picks a 12- or 24-hour clock from the user’s locale, and the AM/PM text follows the locale too. Override the clock with `hourCycle` only when the context requires it.
43
+
44
+ ### Variations
45
+
46
+ | Variation | Use when |
47
+ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
48
+ | Hidden label | Something on screen already names the field, like a column header. Pass `label` with `hideLabel` so it still has an accessible name. |
49
+ | Required | A time is mandatory to proceed. Consider a description explaining why, and a clear error when it’s missing. |
50
+
51
+ ### Sizes
52
+
53
+ | Size | Use when |
54
+ | -------------- | ------------------------------------------------ |
55
+ | `md` (default) | Standard forms. |
56
+ | `lg` | Prominent inputs that need larger touch targets. |
57
+
58
+ ### State usage
59
+
60
+ - **Invalid:** a required time is missing, the value creates a conflict, or the action fails. Say exactly how to fix it.
61
+ - **Disabled:** the time field is unavailable. Consider a description explaining why.
62
+ - **Read-only:** use instead of disabled when the value is still relevant to the user’s context.
@@ -0,0 +1,56 @@
1
+ ---
2
+ use_when:
3
+ - turning a setting on or off that takes effect right away, with no Save button
4
+ ---
5
+
6
+ # ToggleSwitch
7
+
8
+ ## Rules
9
+
10
+ - **Do** use toggle switches for settings that take effect immediately, without a save or submit action.
11
+ - **Do** use them for binary settings: on/off, enabled/disabled.
12
+ - **Do** name the feature or setting in the label (“Email notifications”), not the action (“Turn on email notifications”).
13
+ - **Do** keep the label visible unless something on screen already names the setting, like a column header. Only then hide it with `hideLabel`, and pass `label` as a string so screen readers can still read it. `hideLabel` also hides `description`, so show any extra context elsewhere and connect it with `aria-describedby`.
14
+ - **Don’t** use a toggle switch when the user must click save or submit for the change to take effect; use a Checkbox instead.
15
+ - **Don’t** use toggle switches to pick items from a list, like tags or people; use Checkboxes instead.
16
+ - **Don’t** hide the label just to save space.
17
+
18
+ ## Guidelines
19
+
20
+ ### When to use
21
+
22
+ - Use for settings or preferences that take effect the moment the user flips the switch.
23
+ - Don’t use a toggle switch when the change needs confirmation or additional steps.
24
+
25
+ > **Toggle Switch or Checkbox?**
26
+ >
27
+ > Both handle on/off states, but they differ in when the change takes effect. A Toggle Switch applies the change immediately. A Checkbox captures a value that’s submitted later as part of a form. If there’s a “Save” or “Submit” button on the page, use a Checkbox. If the setting takes effect the moment the user flips it, use a Toggle Switch.
28
+
29
+ ### Content
30
+
31
+ - Use sentence case for labels: capitalize only the first word and proper nouns.
32
+ - Use clear, descriptive language that explains what the toggle controls.
33
+ - Keep labels concise, 1–5 words when possible.
34
+ - Frame labels as the feature or setting name, not as an action.
35
+ - Keep labels on the right of the toggle.
36
+ - Use descriptive text below the label only when it adds context, like what happens when the toggle is on versus off. Keep it to 1–2 sentences; put anything lengthy in a helper shelf or support doc instead.
37
+ - Numerals are fine (“Require 2-factor authentication”).
38
+ - Omit unnecessary articles (“a”, “the”), and don’t end labels with commas or semicolons.
39
+
40
+ ### Interactions
41
+
42
+ - **Click or tap:** immediately toggles between on and off.
43
+ - **Tab:** moves focus to the toggle.
44
+ - **Space:** toggles between on and off.
45
+
46
+ ### Sizes
47
+
48
+ | Size | Use when |
49
+ | -------------- | ------------------------------------ |
50
+ | `md` (default) | Most use cases. |
51
+ | `sm` | Compact layouts or dense interfaces. |
52
+
53
+ ### State usage
54
+
55
+ - **Disabled:** when the setting is unavailable, like when the user lacks permission. Say why nearby if it isn’t obvious.
56
+ - **Error:** when the toggle action fails, such as a network error or permission denied. Be specific about what failed and how to resolve it (“Unable to enable notifications. Check permissions.”). The Toggle Switch has no invalid styling of its own, so show the message below it.
@@ -0,0 +1,153 @@
1
+ ---
2
+ title: Addressing users in products
3
+ description: When to use “you,” “your,” and “we,” and when to use passive or imperative voice in Planning Center product copy.
4
+ order: 50
5
+ ---
6
+
7
+ # Addressing users in products
8
+
9
+ ## Rules
10
+
11
+ - **Do** use “you” for actions the user can take or will take.
12
+ - **Do** use “your” for things that belong to or are associated with the user.
13
+ - **Do** use passive voice for automatic system actions (“This event was automatically archived”).
14
+ - **Do** start instructions with an action verb (“Enter your email address”).
15
+ - **Don’t** use “we” for system or user actions; reserve it for Planning Center as a company.
16
+ - **Don’t** refer to the user in the third person (“Users can customize their dashboard”).
17
+ - **Don’t** soften instructions with “You should” or “Please”.
18
+
19
+ ## Overview
20
+
21
+ Planning Center uses clear, direct language to help users understand what they can do and what belongs to them. These guidelines ensure consistent, user-focused communication across all products by establishing when to use “you,” “your,” and when to avoid “we.”
22
+
23
+ ## General guidelines
24
+
25
+ Address users directly with “you” and “your” for actions and possessions. Avoid “we” except when Planning Center as a company is taking action. Use passive voice for system actions and imperative voice for instructions.
26
+
27
+ ## Usage
28
+
29
+ ### Guidelines
30
+
31
+ - **Use “you” for user actions**
32
+ When describing actions the user can take or will take, address them directly with “you.”
33
+ - **Use “your” for user possessions**
34
+ When referring to things that belong to the user or are associated with them, use “your.”
35
+ - **Avoid “we” except for Planning Center company actions**
36
+ Only use “we” when Planning Center as a company is communicating or acting, not for system or user actions.
37
+ - **Use passive voice for system actions**
38
+ When the system performs automatic actions, use passive voice without “you” or “we.”
39
+ - **Use imperative voice for instructions**
40
+ Start instructions with action verbs and address the user directly without “you.”
41
+
42
+ ### Examples
43
+
44
+ #### Use “you” for user actions
45
+
46
+ Use “you” when describing actions the user can take or will take.
47
+
48
+ ::: tip Do
49
+
50
+ - **Good:** “You can customize your dashboard”
51
+ - **Good:** “You’ll receive an email confirmation”
52
+
53
+ :::
54
+
55
+ ::: danger Don’t
56
+
57
+ - **Avoid:** “Users can customize their dashboard”Planning Center conventions
58
+ - **Avoid:** “An email confirmation will be received”
59
+
60
+ :::
61
+
62
+ #### Use “your” for user possessions
63
+
64
+ Use “your” when referring to things that belong to the user or are associated with them.
65
+
66
+ ::: tip Do
67
+
68
+ - **Good:** “Your events appear in the calendar”
69
+ - **Good:** “Manage your team members”
70
+
71
+ :::
72
+
73
+ ::: danger Don’t
74
+
75
+ - **Avoid:** “Events you created appear in the calendar”
76
+ - **Avoid:** “Manage the team members you’ve added”
77
+
78
+ :::
79
+
80
+ #### Avoid “we” except for Planning Center actions
81
+
82
+ Only use “we” when Planning Center as a company is taking action. Avoid “we” for system actions or user actions.
83
+
84
+ ::: tip Do
85
+
86
+ - **Good (Planning Center action):** “We’re here to help if you need support”
87
+ - **Good (system action):** “This event was automatically archived”
88
+
89
+ :::
90
+
91
+ ::: danger Don’t
92
+
93
+ - **Avoid:** “We couldn’t find that person” (system action)
94
+ - **Avoid:** “We saved your changes” (system action)
95
+
96
+ :::
97
+
98
+ ::: warning Caution
99
+
100
+ - **Exception:** Use “we” in help documentation or support messages where Planning Center is directly communicating with the user.
101
+
102
+ :::
103
+
104
+ #### Use passive voice for system actions
105
+
106
+ When the system performs an automatic action, use passive voice without “you” or “we.”
107
+
108
+ ::: tip Do
109
+
110
+ - **Good:** “This registration was submitted on March 15”
111
+ - **Good:** “Your account has been updated”
112
+
113
+ :::
114
+
115
+ ::: danger Don’t
116
+
117
+ - **Avoid:** “You submitted this registration on March 15”
118
+ - **Avoid:** “We updated your account”
119
+
120
+ :::
121
+
122
+ #### Use imperative voice for instructions
123
+
124
+ Start instructions with action verbs. Address the user directly without “you.”
125
+
126
+ ::: tip Do
127
+
128
+ - **Good:** “Enter your email address”
129
+ - **Good:** “Select a team member to continue”
130
+
131
+ :::
132
+
133
+ ::: danger Don’t
134
+
135
+ - **Avoid:** “You should enter your email address”
136
+ - **Avoid:** “Please select a team member to continue”
137
+
138
+ :::
139
+
140
+ ::: warning Caution
141
+
142
+ - **Exception:** Use “you can” when suggesting optional actions or capabilities. ✓ **Acceptable:** “You can filter by date range”
143
+
144
+ :::
145
+
146
+ ## Quick reference
147
+
148
+ - Use “you” for user actions
149
+ - Use “your” for user possessions
150
+ - Avoid “we” except for Planning Center company actions
151
+ - Use passive voice for system actions
152
+ - Start instructions with action verb
153
+ - “Change your preferences in My Account”
@@ -0,0 +1,59 @@
1
+ ---
2
+ title: Browser tabs
3
+ description: When links should open in the same tab versus a new tab in Planning Center products.
4
+ order: 100
5
+ ---
6
+
7
+ # Browser tabs
8
+
9
+ ## Rules
10
+
11
+ - **Do** open links in the same tab by default.
12
+ - **Do** use the “New Window” icon whenever a link opens in a new tab.
13
+ - **Do** consider a new tab when same-tab navigation would interrupt work in progress, like a form or video.
14
+ - **Do** consult with UX before creating an exception.
15
+ - **Don’t** open links in new tabs without a specific user need.
16
+ - **Don’t** open offsite links in new tabs without the “New Window” icon.
17
+
18
+ ## Overview
19
+
20
+ Browser tab behavior determines whether links open in the same tab or a new tab. Planning Center defaults to opening links in the same tab to maintain user control, prevent disorientation, and support accessibility needs across devices.
21
+
22
+ ## Principles
23
+
24
+ - Open links in the same tab by default
25
+ - Only open in a new tab when there’s a compelling user need
26
+ - Consult with UX before creating exceptions
27
+
28
+ ## Usage
29
+
30
+ ### Guidelines
31
+
32
+ **Default to same-tab navigation** because it:
33
+
34
+ - Prevents disorientation on mobile devices where users may not notice a new tab has opened
35
+ - Supports accessibility by avoiding issues with screen readers and users with cognitive disabilities
36
+ - Gives users control—they can choose to open links in new tabs using right-click or long-press, but can’t force a new-tab link to open in the same tab
37
+
38
+ ::: tip Do
39
+
40
+ - Open links in the same tab for standard navigation
41
+ - Use the “New Window” icon when you must open a link in a new tab
42
+ - Consult with UX when you have questions about exceptions
43
+
44
+ :::
45
+
46
+ ::: danger Don’t
47
+
48
+ - Open links in new tabs without a specific user need
49
+ - Open offsite links in new tabs without the “New Window” icon indicator
50
+ - Force new-tab behavior when users are performing standard navigation
51
+
52
+ :::
53
+
54
+ ## Exceptions
55
+
56
+ ### Open links in a new tab when:
57
+
58
+ - **Interrupting an active process:** If opening in the same tab would disrupt work in progress (filling out a form, watching a video, etc.), consider a new tab to prevent data loss. Use the “New Window” icon to signal this behavior.
59
+ - **Linking to offsite resources:** When linking outside Planning Center domains (which should be rare), use a new tab with the “New Window” icon to help users understand the domain change.