@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.
- package/dist/components/DataTable/ActiveFilterInstance.d.ts +3 -3
- package/dist/components/DataTable/ActiveFilterInstance.d.ts.map +1 -1
- package/dist/components/DataTable/ActiveFilterInstance.js +5 -5
- package/dist/components/DataTable/ActiveFilterInstance.js.map +1 -1
- package/dist/components/DataTable/ActiveFilters.d.ts.map +1 -1
- package/dist/components/DataTable/ActiveFilters.js +3 -1
- package/dist/components/DataTable/ActiveFilters.js.map +1 -1
- package/dist/components/DataTable/DataTable.d.ts +27 -7
- package/dist/components/DataTable/DataTable.d.ts.map +1 -1
- package/dist/components/DataTable/DataTable.js +34 -5
- package/dist/components/DataTable/DataTable.js.map +1 -1
- package/dist/components/DataTable/DataTableColumn.d.ts +15 -3
- package/dist/components/DataTable/DataTableColumn.d.ts.map +1 -1
- package/dist/components/DataTable/DataTableColumnTypes.d.ts +2 -2
- package/dist/components/DataTable/DataTableColumnTypes.d.ts.map +1 -1
- package/dist/components/DataTable/DataTableColumnTypes.js +6 -12
- package/dist/components/DataTable/DataTableColumnTypes.js.map +1 -1
- package/dist/components/DataTable/FilterTypes.d.ts +2 -0
- package/dist/components/DataTable/FilterTypes.d.ts.map +1 -1
- package/dist/components/DataTable/RowActions.d.ts +7 -0
- package/dist/components/DataTable/RowActions.d.ts.map +1 -1
- package/dist/components/DataTable/RowActions.js +6 -3
- package/dist/components/DataTable/RowActions.js.map +1 -1
- package/dist/components/DataTable/TableActions.d.ts +5 -0
- package/dist/components/DataTable/TableActions.d.ts.map +1 -1
- package/dist/components/DataTable/TableActions.js +2 -1
- package/dist/components/DataTable/TableActions.js.map +1 -1
- package/dist/components/DataTable/ViewsBar.d.ts.map +1 -1
- package/dist/components/DataTable/ViewsBar.js +7 -1
- package/dist/components/DataTable/ViewsBar.js.map +1 -1
- package/dist/components/DataTable/dateFilter.d.ts +4 -2
- package/dist/components/DataTable/dateFilter.d.ts.map +1 -1
- package/dist/components/DataTable/dateFilter.js +22 -13
- package/dist/components/DataTable/dateFilter.js.map +1 -1
- package/dist/components/DataTable/dayFilter.d.ts.map +1 -1
- package/dist/components/DataTable/dayFilter.js +25 -22
- package/dist/components/DataTable/dayFilter.js.map +1 -1
- package/dist/components/DataTable/scopedFilter.d.ts +1 -1
- package/dist/components/DataTable/scopedFilter.d.ts.map +1 -1
- package/dist/components/DataTable/scopedFilter.js +56 -35
- package/dist/components/DataTable/scopedFilter.js.map +1 -1
- package/dist/components/DataTable/useSearchFilter.d.ts.map +1 -1
- package/dist/components/DataTable/useSearchFilter.js +2 -1
- package/dist/components/DataTable/useSearchFilter.js.map +1 -1
- package/dist/components/page-header/defineElements.js +1 -1
- package/dist/components/sidenav/defineElements.js +1 -1
- package/dist/index.d.ts +1 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -0
- package/dist/index.js.map +1 -1
- package/dist/packages/tapestry-wc/dist/components/{p-CBFtMIxJ.js → p-Bw5XJ46l.js} +2 -2
- package/dist/packages/tapestry-wc/dist/components/{p-CBFtMIxJ.js.map → p-Bw5XJ46l.js.map} +1 -1
- package/dist/packages/tapestry-wc/dist/components/{p-BbuNAv9q.js → p-C5B21uv6.js} +3 -3
- package/dist/packages/tapestry-wc/dist/components/{p-BbuNAv9q.js.map → p-C5B21uv6.js.map} +1 -1
- package/dist/packages/tapestry-wc/dist/components/{p-DNHgMtxw.js → p-D4oSihjy.js} +2 -2
- package/dist/packages/tapestry-wc/dist/components/{p-DNHgMtxw.js.map → p-D4oSihjy.js.map} +1 -1
- package/dist/packages/tapestry-wc/dist/components/{p-A1JK45WV.js → p-DZA99jMW.js} +3 -3
- package/dist/packages/tapestry-wc/dist/components/{p-A1JK45WV.js.map → p-DZA99jMW.js.map} +1 -1
- package/dist/packages/tapestry-wc/dist/components/{p-CY_DC4d_.js → p-Dt250a7E.js} +3 -3
- package/dist/packages/tapestry-wc/dist/components/{p-CY_DC4d_.js.map → p-Dt250a7E.js.map} +1 -1
- package/dist/packages/tapestry-wc/dist/components/tds-page-header-nav.js +2 -2
- package/dist/packages/tapestry-wc/dist/components/tds-page-header-nav.js.map +1 -1
- package/dist/packages/tapestry-wc/dist/components/tds-page-header.js +3 -3
- package/dist/packages/tapestry-wc/dist/components/tds-page-header.js.map +1 -1
- package/dist/packages/tapestry-wc/dist/components/tds-sidenav-item.js +3 -3
- package/dist/packages/tapestry-wc/dist/components/tds-sidenav-item.js.map +1 -1
- package/dist/packages/tapestry-wc/dist/components/tds-sidenav-responsive-header.js +2 -2
- package/dist/packages/tapestry-wc/dist/components/tds-sidenav-responsive-header.js.map +1 -1
- package/dist/packages/tapestry-wc/dist/components/tds-sidenav-section.js +3 -3
- package/dist/packages/tapestry-wc/dist/components/tds-sidenav-section.js.map +1 -1
- package/dist/packages/tapestry-wc/dist/components/tds-sidenav.js +5 -5
- package/dist/packages/tapestry-wc/dist/components/tds-sidenav.js.map +1 -1
- package/dist/reactRender.css +1629 -1629
- package/dist/reactRender.css.map +1 -1
- package/dist/reactRenderLegacy.css +1629 -1629
- package/dist/reactRenderLegacy.css.map +1 -1
- package/dist/tapestryMount.css +1629 -1629
- package/dist/tapestryMount.css.map +1 -1
- package/dist/tapestryMountLegacy.css +1629 -1629
- package/dist/tapestryMountLegacy.css.map +1 -1
- package/dist/unstable.js +1 -0
- package/dist/unstable.js.map +1 -1
- package/dist/utilities/dataHooks.d.ts +8 -0
- package/dist/utilities/dataHooks.d.ts.map +1 -0
- package/dist/utilities/dataHooks.js +7 -0
- package/dist/utilities/dataHooks.js.map +1 -0
- package/dist/utilities/locale.d.ts +25 -0
- package/dist/utilities/locale.d.ts.map +1 -0
- package/dist/utilities/locale.js +48 -0
- package/dist/utilities/locale.js.map +1 -0
- package/docs/accessibility/accessibility.md +62 -0
- package/docs/components/button-group.md +44 -0
- package/docs/components/button.md +78 -0
- package/docs/components/checkbox-group.md +51 -0
- package/docs/components/checkbox.md +55 -0
- package/docs/components/combo-box.md +68 -0
- package/docs/components/currency-input.md +50 -0
- package/docs/components/date-picker.md +67 -0
- package/docs/components/dropdown.md +74 -0
- package/docs/components/field.md +44 -0
- package/docs/components/flex.md +66 -0
- package/docs/components/input.md +62 -0
- package/docs/components/link.md +46 -0
- package/docs/components/modal.md +59 -0
- package/docs/components/number-stepper.md +50 -0
- package/docs/components/page-header.md +48 -0
- package/docs/components/popover.md +45 -0
- package/docs/components/radio-group.md +47 -0
- package/docs/components/radio.md +62 -0
- package/docs/components/search-input.md +46 -0
- package/docs/components/segmented-control.md +60 -0
- package/docs/components/select.md +62 -0
- package/docs/components/sidenav.md +36 -0
- package/docs/components/text-area.md +65 -0
- package/docs/components/time-field.md +62 -0
- package/docs/components/toggle-switch.md +56 -0
- package/docs/content/addressing-users-in-products.md +153 -0
- package/docs/content/browser-tabs.md +59 -0
- package/docs/content/capitalization.md +69 -0
- package/docs/content/date-formatting.md +145 -0
- package/docs/content/displaying-names.md +139 -0
- package/docs/content/editing-and-saving.md +95 -0
- package/docs/content/file-size-formatting.md +44 -0
- package/docs/content/household-ordering.md +127 -0
- package/docs/content/micro-copy.md +135 -0
- package/docs/content/prompts.md +271 -0
- package/docs/content/punctuation.md +71 -0
- package/docs/content/sharing-nomenclature.md +67 -0
- package/docs/content/timezones.md +108 -0
- package/docs/content/tooltip-usage.md +49 -0
- package/docs/content/use-of-emoji.md +63 -0
- package/docs/content/voice-and-tone.md +251 -0
- package/docs/design/design-tokens.md +70 -0
- package/docs/design/iconography.md +60 -0
- package/docs/design/layout.md +237 -0
- package/docs/design/mobile-design-principles.md +109 -0
- package/docs/design/pca-design-language.md +78 -0
- package/docs/design/typography.md +94 -0
- package/docs/get-started/design-system-philosophy.md +33 -0
- package/docs/llms.txt +119 -0
- package/package.json +7 -5
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
---
|
|
2
|
+
use_when:
|
|
3
|
+
- a menu of actions on an item, like Edit, Duplicate and Delete
|
|
4
|
+
- a “more” menu of actions or links behind a button
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Dropdown
|
|
8
|
+
|
|
9
|
+
## Rules
|
|
10
|
+
|
|
11
|
+
- **Do** use a Dropdown to group two or more related actions behind a single trigger.
|
|
12
|
+
- **Do** keep action labels short and verb-led (e.g., “Edit”, “Archive”, “Delete”).
|
|
13
|
+
- **Do** use separators to divide unrelated groups of actions.
|
|
14
|
+
- **Do** give icon-only triggers (`DropdownIconButton`, `ActionsDropdownIconButton`) a `tooltip`.
|
|
15
|
+
- **Do** give each `ActionsDropdownIconButton` a specific `aria-label` when a page has more than one. Start it with the tooltip text, like tooltip “Actions” and `aria-label` “Actions for Jane Doe”.
|
|
16
|
+
- **Don’t** use a Dropdown for a single action; use a Button instead.
|
|
17
|
+
- **Don’t** use a Dropdown to collect data; use a Select for form inputs.
|
|
18
|
+
- **Don’t** use a Dropdown to display informative text unless it’s attached to an action.
|
|
19
|
+
|
|
20
|
+
## Guidelines
|
|
21
|
+
|
|
22
|
+
### When to use
|
|
23
|
+
|
|
24
|
+
- Use when the user needs to perform an action (Edit, Duplicate, Delete) or navigate to a URL.
|
|
25
|
+
- When the user is choosing a value to persist or submit in a form, use a Select. The two look similar but are semantically distinct.
|
|
26
|
+
- For arbitrary content anchored to a button, like a short form or filter, use a Popover.
|
|
27
|
+
|
|
28
|
+
> **Dropdown or Select?**
|
|
29
|
+
>
|
|
30
|
+
> A Dropdown runs an action or follows a link. A Select captures a value in a form. If the choice gets saved or submitted, use a Select.
|
|
31
|
+
|
|
32
|
+
### Content
|
|
33
|
+
|
|
34
|
+
- Name the trigger for the group of actions, and keep it short: “Actions”, “More”, or “Share”.
|
|
35
|
+
- Write each item as a single, clear verb phrase.
|
|
36
|
+
- Use item descriptions sparingly, mainly to clarify the outcome of complex or destructive actions, or why an item is disabled.
|
|
37
|
+
- Use prefix icons only when the icon is universally understood for the action. Keep suffix content to things like keyboard shortcuts (⌘E).
|
|
38
|
+
|
|
39
|
+
### Interactions
|
|
40
|
+
|
|
41
|
+
- Enter, Space, or Arrow Down on the trigger opens the menu and focuses the first item; Arrow Up opens it and focuses the last item.
|
|
42
|
+
- Arrow Down / Arrow Up move between items, skipping disabled items and wrapping at the ends. Home and End jump to the first and last items.
|
|
43
|
+
- Enter or Space activates the focused item and closes the menu.
|
|
44
|
+
- Escape closes the menu and returns focus to the trigger. Clicking or tapping outside also closes it.
|
|
45
|
+
- Typing a character moves focus to the next item whose label starts with that character.
|
|
46
|
+
|
|
47
|
+
### Triggers
|
|
48
|
+
|
|
49
|
+
| Trigger | Use when |
|
|
50
|
+
| -------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
|
|
51
|
+
| Default (`DropdownButton`) | Most cases. A labeled button with a trailing caret. |
|
|
52
|
+
| Icon trigger (`DropdownIconButton`) | Context makes the trigger’s purpose clear. |
|
|
53
|
+
| Caret hidden (`ActionsDropdownIconButton`) | Space is tight, like cards, table rows, and popovers. A three-dot `ghost` button with no caret. |
|
|
54
|
+
| Attention icon (`PageHeaderActionsDropdownButton`) | Page header actions need attention. Set `needsAttention`. |
|
|
55
|
+
|
|
56
|
+
### Menu alignment
|
|
57
|
+
|
|
58
|
+
- Use the default `placement` (`"bottom start"`). Use `"bottom end"` only when the trigger sits near the right edge.
|
|
59
|
+
|
|
60
|
+
### Items
|
|
61
|
+
|
|
62
|
+
| Item | Use when |
|
|
63
|
+
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------- |
|
|
64
|
+
| Label only, or label and icon | Most cases. Prefer these standard items. |
|
|
65
|
+
| Slotted content | Avatars, color swatches, multi-line layouts, or keyboard shortcuts are needed. |
|
|
66
|
+
| Sections and separators | A longer menu has distinct groups. Use sparingly. |
|
|
67
|
+
| Destructive | The action is destructive. Set `destructive`, and put it last, after a `DropdownSeparator`. |
|
|
68
|
+
| Staff only | The action is restricted to staff. `staffOnly` only changes the item’s color; render it only for staff yourself. |
|
|
69
|
+
|
|
70
|
+
### State usage
|
|
71
|
+
|
|
72
|
+
- **Disabled trigger:** when the whole menu is unavailable. Prefer hiding the trigger over disabling it when the reason isn’t obvious.
|
|
73
|
+
- **Disabled item:** when one action is unavailable but others aren’t. Avoid hiding disabled items; seeing them helps users understand the full set of actions.
|
|
74
|
+
- **Links** can’t be disabled; omit them instead.
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
---
|
|
2
|
+
use_when:
|
|
3
|
+
- building a form control Tapestry doesn’t have yet
|
|
4
|
+
- giving a custom control the same label, description and error as other fields
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Field
|
|
8
|
+
|
|
9
|
+
## Rules
|
|
10
|
+
|
|
11
|
+
- **Do** use the ready-made form components (Input, Select, Text Area, Checkbox, and so on) first; reach for Field only when composing a control they don’t cover.
|
|
12
|
+
- **Do** always pass a `label`, 1–3 words in sentence case, or `aria-labelledby` pointing at visible text that already names the control.
|
|
13
|
+
- **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`.
|
|
14
|
+
- **Do** give the control the same `id` you pass to Field, so the label is connected to it.
|
|
15
|
+
- **Do** set `aria-describedby="{id}-description"` on the control whenever you pass a `description`.
|
|
16
|
+
- **Do** set `required`, `disabled`, and `aria-invalid` on the control itself; Field styles the label and description from those attributes.
|
|
17
|
+
- **Don’t** wrap more than one control in a Field; use a group component like Checkbox Group or Radio Group for sets of options.
|
|
18
|
+
- **Don’t** hide a label just to save space.
|
|
19
|
+
|
|
20
|
+
## Guidelines
|
|
21
|
+
|
|
22
|
+
### When to use
|
|
23
|
+
|
|
24
|
+
Field is a layout primitive. It wraps a single form control with a label, an optional description, and the required, invalid, and disabled styling shared by Tapestry form fields. Components like Search Input and Currency Input are built on it.
|
|
25
|
+
|
|
26
|
+
- Use it to build a form control that Tapestry doesn’t provide yet, so the label and description match the rest of the form.
|
|
27
|
+
- Field renders the control untouched, without styling it. You wire the control to the label and description yourself.
|
|
28
|
+
- Set `expand` when the field should grow and shrink to fill a Flex row.
|
|
29
|
+
|
|
30
|
+
### Wiring
|
|
31
|
+
|
|
32
|
+
| On the control | When |
|
|
33
|
+
| ------------------------------------------------------- | ------------------------------------------------------------------ |
|
|
34
|
+
| `id` matching Field’s `id` | Always. Connects the `<label>` to the control. |
|
|
35
|
+
| `aria-describedby="{id}-description"` | When Field has a `description`. |
|
|
36
|
+
| `aria-labelledby` | When Field uses `aria-labelledby` instead of `label`. |
|
|
37
|
+
| `required` or `aria-required="true"` | To show the required asterisk. |
|
|
38
|
+
| `aria-invalid="true"` | To show the description as an error, with the invalid icon. |
|
|
39
|
+
| `disabled` on a native `input`, `select`, or `textarea` | To dim the label and description. Other elements don’t trigger it. |
|
|
40
|
+
|
|
41
|
+
### Content
|
|
42
|
+
|
|
43
|
+
- Keep labels to 1–3 words in sentence case.
|
|
44
|
+
- Keep the description to 1–2 sentences. When the field is invalid, the description becomes the error message, so say how to fix the problem.
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
---
|
|
2
|
+
use_when:
|
|
3
|
+
- laying out items in a row or column with token spacing
|
|
4
|
+
- a layout that changes direction or spacing at a breakpoint
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Flex
|
|
8
|
+
|
|
9
|
+
## Rules
|
|
10
|
+
|
|
11
|
+
- **Do** space children with `gap`, not margins or inline `style`.
|
|
12
|
+
- **Do** use `as` to render a semantically appropriate landmark element when the layout corresponds to one, like `<Flex as="nav">` or `<Flex as="section">`.
|
|
13
|
+
- **Do** use `expand` on a child to fill remaining space in a flex row, replacing the old `distribution="fill"` pattern from `StackView`.
|
|
14
|
+
- **Do** use `responsive` to change layout props like `direction`, `gap`, or `align` at a breakpoint. `as`, `expand`, and `inline` can’t change responsively.
|
|
15
|
+
- **Don’t** pass interactive elements (`button`, `a`, `label`, `input`) as the `as` prop; wrap the interactive element around Flex instead (button > Flex > content).
|
|
16
|
+
- **Don’t** rely on container queries in production yet; they are experimental and subject to change.
|
|
17
|
+
|
|
18
|
+
## Guidelines
|
|
19
|
+
|
|
20
|
+
### When to use
|
|
21
|
+
|
|
22
|
+
Use Flex for any row or column layout. It replaces `StackView` from `@planningcenter/tapestry-react` and renders a `div` unless you set `as`.
|
|
23
|
+
|
|
24
|
+
### Component interactions
|
|
25
|
+
|
|
26
|
+
- Flex has no interactive states and does not handle user input. The components inside it handle their own focus management, keyboard navigation, and events.
|
|
27
|
+
- Responsive layout changes driven by the `responsive` prop are handled entirely with CSS: static media queries for viewport breakpoints and injected `@container` rules for container queries. No JavaScript runs at render time for viewport-based responsiveness.
|
|
28
|
+
- Prop values are reflected as data attributes on the root element (such as `data-flex-direction`, `data-flex-gap`, and `data-padding`), making the current layout visible and tweakable in browser DevTools.
|
|
29
|
+
|
|
30
|
+
### Spacing scale
|
|
31
|
+
|
|
32
|
+
`gap`, `rowGap`, `columnGap`, `padding`, `paddingBlock`, and `paddingInline` accept `0`, `0.25`, `0.5`, `1`, `1.5`, `2`, `3`, `4`, `5`, `6`, and `7`, mapped to the `--t-spacing-*` tokens (`1` is `--t-spacing-1`, 8px).
|
|
33
|
+
|
|
34
|
+
### Container props
|
|
35
|
+
|
|
36
|
+
| Prop | Values |
|
|
37
|
+
| ----------- | -------------------------------------------------------------------------------------------------- |
|
|
38
|
+
| `direction` | `row` (default), `row-reverse`, `column`, `column-reverse`. |
|
|
39
|
+
| `align` | Cross-axis alignment: `start`, `center`, `end`, `stretch`, `baseline`. |
|
|
40
|
+
| `justify` | Main-axis distribution: `start`, `center`, `end`, `space-between`, `space-around`, `space-evenly`. |
|
|
41
|
+
| `wrap` | `nowrap`, `wrap`, `wrap-reverse`. |
|
|
42
|
+
| `inline` | Renders as `inline-flex`. |
|
|
43
|
+
|
|
44
|
+
### Item props
|
|
45
|
+
|
|
46
|
+
| Prop | Values |
|
|
47
|
+
| ----------- | ---------------------------------------------------------------------------------------------------------- |
|
|
48
|
+
| `expand` | Fills remaining space (`flex: 1 1 0%; min-width: 0`). Can’t be combined with `grow`, `shrink`, or `basis`. |
|
|
49
|
+
| `grow` | `0`, `1`. |
|
|
50
|
+
| `shrink` | `0`, `1`. |
|
|
51
|
+
| `basis` | `0`, `auto`, `100%`. |
|
|
52
|
+
| `alignSelf` | Overrides the container’s `align` for this item. |
|
|
53
|
+
|
|
54
|
+
### Responsive
|
|
55
|
+
|
|
56
|
+
`responsive` takes overrides keyed by breakpoint, applied from that width up. For example, `md: { direction: "row", gap: 2 }` switches to a row with a larger gap from 720px.
|
|
57
|
+
|
|
58
|
+
| Breakpoint | Applies from |
|
|
59
|
+
| ---------- | ------------ |
|
|
60
|
+
| `xs` | 480px |
|
|
61
|
+
| `sm` | 600px |
|
|
62
|
+
| `md` | 720px |
|
|
63
|
+
| `lg` | 960px |
|
|
64
|
+
| `xl` | 1200px |
|
|
65
|
+
|
|
66
|
+
**Experimental:** A `container` key takes container query conditions, like `"(inline-size > 20rem)"`. It needs an ancestor with `container-type: inline-size`.
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
---
|
|
2
|
+
use_when:
|
|
3
|
+
- entering short, single-line text, like a name, email or title
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Input
|
|
7
|
+
|
|
8
|
+
## Rules
|
|
9
|
+
|
|
10
|
+
- **Do** use an Input for single-line entry such as names, emails, or passwords. For search, use a Search Input.
|
|
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 placeholder text only for a sample value, such as “name@example.com”, or leave it out.
|
|
14
|
+
- **Do** write specific, actionable error messages.
|
|
15
|
+
- **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 column header.
|
|
16
|
+
- **Do** set the input type (`email`, `tel`, `url`) so mobile devices show the right keyboard.
|
|
17
|
+
- **Don’t** hide a label just to save space, and never use placeholder text in its place.
|
|
18
|
+
- **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.
|
|
19
|
+
- **Don’t** use an Input for long-form content; use a Text Area.
|
|
20
|
+
|
|
21
|
+
## Guidelines
|
|
22
|
+
|
|
23
|
+
### When to use
|
|
24
|
+
|
|
25
|
+
- Use for short, single-line entry in forms and dialogs.
|
|
26
|
+
- Size the input to fit the expected content; don’t make it unnecessarily wide or narrow.
|
|
27
|
+
- If a specific format is required, show an example.
|
|
28
|
+
|
|
29
|
+
### Validation
|
|
30
|
+
|
|
31
|
+
- Check the value when the form is submitted by default.
|
|
32
|
+
- Check as people type only when instant feedback helps them get it right, like password requirements or a username that must be available.
|
|
33
|
+
- Once an error shows, clear it as soon as the value is fixed, so people know their change worked.
|
|
34
|
+
|
|
35
|
+
### Content
|
|
36
|
+
|
|
37
|
+
- **Labels:** 1–3 words, sentence case, no ending punctuation (unless the label is a question asking for a short answer).
|
|
38
|
+
- **Placeholder:** optional. A sample value only, such as “name@example.com”. It disappears when the user types.
|
|
39
|
+
- **Descriptive text:** brief formatting hints or constraints, 1–2 sentences. It isn’t a replacement for helper text.
|
|
40
|
+
- **Errors:** say what’s wrong and how to fix it. Avoid vague messages like “Invalid input”.
|
|
41
|
+
- Don’t hide important instructions in a tooltip or helper text.
|
|
42
|
+
|
|
43
|
+
### Variations
|
|
44
|
+
|
|
45
|
+
| Variation | Use when |
|
|
46
|
+
| ----------- | ---------------------------------------------------------- |
|
|
47
|
+
| `autoWidth` | The field should grow with its content, like a short code. |
|
|
48
|
+
| `expand` | The field should grow to fill a Flex row. |
|
|
49
|
+
|
|
50
|
+
### Sizes
|
|
51
|
+
|
|
52
|
+
| Size | Use when |
|
|
53
|
+
| -------------- | ----------------------------------------------------------------- |
|
|
54
|
+
| `md` (default) | Standard forms. |
|
|
55
|
+
| `lg` | Prominent inputs or hero sections that need larger touch targets. |
|
|
56
|
+
|
|
57
|
+
### State usage
|
|
58
|
+
|
|
59
|
+
- **Required:** when the user can’t proceed without filling in the field.
|
|
60
|
+
- **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.
|
|
61
|
+
- **Disabled:** when the field is unavailable for input. Consider descriptive text explaining why.
|
|
62
|
+
- **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,46 @@
|
|
|
1
|
+
---
|
|
2
|
+
use_when:
|
|
3
|
+
- going to another page, file or resource
|
|
4
|
+
- linking text in a sentence, a table cell or a heading
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Link
|
|
8
|
+
|
|
9
|
+
## Rules
|
|
10
|
+
|
|
11
|
+
- **Do** use a sentence link (`kind="inline-text"`) for links that are part of a longer phrase or sentence.
|
|
12
|
+
- **Do** use a UI link (`kind="neutral-inline"`) for links in page titles, subheadings, table cells, and attachments.
|
|
13
|
+
- **Do** write link text that says where it goes, like “adding a new team member”, not “click here”.
|
|
14
|
+
- **Do** set `external` on links that open another site, so they open in a new tab safely.
|
|
15
|
+
- **Don’t** use a link for an action that doesn’t navigate; use a Button instead.
|
|
16
|
+
- **Don’t** use a neutral UI link inside running text; use a sentence link so it reads as a link.
|
|
17
|
+
|
|
18
|
+
## Guidelines
|
|
19
|
+
|
|
20
|
+
### When to use
|
|
21
|
+
|
|
22
|
+
Text that is clickable, but not in a button, can be tricky. Planning Center’s admin UI handles it in two ways:
|
|
23
|
+
|
|
24
|
+
- **Sentence link** (`kind="inline-text"`): any link that is part of a longer phrase or sentence. For example: “Visit our blog to read more about adding a new team member”, where “adding a new team member” is the link.
|
|
25
|
+
- **UI link** (`kind="neutral-inline"`): a link to a resource or reference that doesn’t look like a button but still needs a signifier. For example: page titles, subheadings, data inside a table cell, and attachment or resource links (PDF, DOC, and other files).
|
|
26
|
+
|
|
27
|
+
Links navigate. If clicking performs an action (save, delete, open a modal), use a Button. If navigation needs to look like a button, use `Link` with a button `kind` such as `primary` or `secondary`.
|
|
28
|
+
|
|
29
|
+
### Content
|
|
30
|
+
|
|
31
|
+
- Make the link text describe the destination. Avoid “click here” and “learn more” on their own.
|
|
32
|
+
- Keep link text short, and link the most meaningful words in the sentence.
|
|
33
|
+
- Use sentence case.
|
|
34
|
+
|
|
35
|
+
### Variations
|
|
36
|
+
|
|
37
|
+
| Variation | `kind` | Use when |
|
|
38
|
+
| ------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
|
|
39
|
+
| Sentence link | `inline-text` | The link is part of a sentence. Underlined until hover or focus. |
|
|
40
|
+
| UI link | `neutral-inline` | Page titles, subheadings, table cells, attachments. Underlined on hover. |
|
|
41
|
+
| Button-styled link | Any other `kind` | Navigation should look like a button. Pick any `size`. A `primary` link counts as the one primary in its section or modal. |
|
|
42
|
+
| Icon Link | Any other `kind` | Navigation should look like an icon-only button. Give it a `tooltip`; without `aria-label`, the tooltip is also its accessible name. |
|
|
43
|
+
|
|
44
|
+
`primary-page-header` and `secondary-page-header` are for page headers only.
|
|
45
|
+
|
|
46
|
+
Without a `kind`, `Link` renders a plain `<a>` with no Tapestry styles.
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
---
|
|
2
|
+
use_when:
|
|
3
|
+
- a focused task people finish or cancel before going back, like setting up a new item
|
|
4
|
+
- the task is short and doesn’t need its own page
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Modal
|
|
8
|
+
|
|
9
|
+
## Rules
|
|
10
|
+
|
|
11
|
+
- **Do** use modals sparingly, for a single decision or a short, bounded task that is separate from the main flow.
|
|
12
|
+
- **Do** write a header that states what’s happening (screen readers announce it as the dialog’s name) and button labels that say exactly what will happen.
|
|
13
|
+
- **Do** keep footer actions to two in most cases: one `primary` action and a `ghost` Cancel.
|
|
14
|
+
- **Do** start with the `md` (600px) size unless the content clearly needs more room.
|
|
15
|
+
- **Don’t** set `dismissible` on data entry modals, where unsaved input could be lost. It’s off by default.
|
|
16
|
+
- **Don’t** nest modals inside modals.
|
|
17
|
+
- **Don’t** use a modal for a simple destructive confirmation; use a SweetestAlert dialog (from `@planningcenter/sweetest-alert`) instead.
|
|
18
|
+
- **Don’t** use a modal for tasks that need their own URL or information from outside the dialog; use a dedicated page.
|
|
19
|
+
|
|
20
|
+
## Guidelines
|
|
21
|
+
|
|
22
|
+
### When to use
|
|
23
|
+
|
|
24
|
+
- First ask whether the interaction would work better as on-page content. Modals are invasive.
|
|
25
|
+
- Use for focused processes separate from the main flow, like adding a new item that needs careful setup.
|
|
26
|
+
- For tasks with several steps, default to a dedicated page. A modal is allowed, but it isn’t the first choice.
|
|
27
|
+
- Don’t use for nonessential information unrelated to the current flow.
|
|
28
|
+
- Don’t use when the user would need to look something up outside the dialog to finish.
|
|
29
|
+
|
|
30
|
+
### Destructive actions
|
|
31
|
+
|
|
32
|
+
| Situation | Use |
|
|
33
|
+
| ---------------------------------------------------------------------------------- | --------------------------- |
|
|
34
|
+
| Single confirm/cancel decision (delete, archive, remove) | SweetestAlert (the default) |
|
|
35
|
+
| Confirmation with type-to-confirm input | SweetestAlert |
|
|
36
|
+
| Confirmation that needs more input, like composing a message or filling out a form | Modal |
|
|
37
|
+
|
|
38
|
+
### Content
|
|
39
|
+
|
|
40
|
+
- Limit interactions to what supports the task; remove everything else.
|
|
41
|
+
- Avoid long content that scrolls. If scrolling is unavoidable, make it obvious; long content pushes buttons out of view.
|
|
42
|
+
- A tertiary footer action is fine in some cases, but default to two.
|
|
43
|
+
- For edge-to-edge content like a table, set `fullWidth` on `ModalBody`.
|
|
44
|
+
- The footer has a left-aligned slot (`slot="start"`) for a destructive action, but it’s rarely needed.
|
|
45
|
+
|
|
46
|
+
### Behavior
|
|
47
|
+
|
|
48
|
+
- **Dismissible** (`dismissible={true}`): **Esc**, backdrop click, and the close button all dismiss the modal and fire `onClose` through the same handler.
|
|
49
|
+
- **Non-dismissible** (`dismissible={false}`, the default): those three paths are suppressed; the user must complete or cancel with the footer buttons.
|
|
50
|
+
- **Scrolling:** When content is taller than the viewport, the whole modal scrolls inside the backdrop. On viewports 720px and wider, `ModalFooter` sticks to the bottom; `ModalHeader` scrolls with the content.
|
|
51
|
+
|
|
52
|
+
### Sizes
|
|
53
|
+
|
|
54
|
+
| Size | Use when |
|
|
55
|
+
| ------------- | ------------------------------------------------------------------------------------------------- |
|
|
56
|
+
| `sm` (400px) | Destructive actions or forms with one or two fields. Anything longer moves to `md`. |
|
|
57
|
+
| `md` (600px) | The default. Most forms and single-record create or edit flows. |
|
|
58
|
+
| `lg` (800px) | Many fields, permissions lists, file or attachment management, multi-section forms, short tables. |
|
|
59
|
+
| `xl` (1000px) | Dense content like wide tables, matrices, or multi-column layouts. Use sparingly. |
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
---
|
|
2
|
+
use_when:
|
|
3
|
+
- entering a number or adjusting it in small steps, like a quantity or capacity
|
|
4
|
+
- the number has limits, like 1 to 10
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# NumberStepper
|
|
8
|
+
|
|
9
|
+
## Rules
|
|
10
|
+
|
|
11
|
+
- **Do** use a number stepper for small, bounded numeric inputs like quantities, counts, or durations.
|
|
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. Say what value is being set (e.g. “Quantity”, “Duration”, “Count”).
|
|
13
|
+
- **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`.
|
|
14
|
+
- **Do** set a `min` and `max` when the range is known, and use the description to communicate it (e.g. “Between 1 and 99”).
|
|
15
|
+
- **Don’t** use a number stepper for large ranges where typing is faster; use an Input instead.
|
|
16
|
+
- **Don’t** hide a min/max range from users, especially when hitting the limit would block them from moving forward.
|
|
17
|
+
- **Don’t** hide a label just to save space.
|
|
18
|
+
|
|
19
|
+
## Guidelines
|
|
20
|
+
|
|
21
|
+
### When to use
|
|
22
|
+
|
|
23
|
+
- Use when users need to enter a number or adjust it by small amounts, either with the stepper buttons or by typing directly.
|
|
24
|
+
- Constrain the value with `min`, `max`, and `step`.
|
|
25
|
+
- Format values as decimals, currency, percentages, or units with `formatOptions`, which accepts `Intl.NumberFormat` options.
|
|
26
|
+
|
|
27
|
+
### Content
|
|
28
|
+
|
|
29
|
+
- **Labels:** 1–3 words, sentence case.
|
|
30
|
+
- **Description:** additional context, the expected range, or error instructions. Keep to 1–2 sentences.
|
|
31
|
+
- **Errors:** sentence case, and say what to change.
|
|
32
|
+
|
|
33
|
+
### Interactions
|
|
34
|
+
|
|
35
|
+
- **Increment (+) and decrement (−):** change the value by the `step` amount.
|
|
36
|
+
- **Direct input:** users can type a value. On blur, it’s clamped to `min` and `max` and rounded to the nearest `step`, so it can’t end up out of range.
|
|
37
|
+
- **Keyboard:** Arrow Up and Arrow Down change the value by `step`. Home and End jump to `min` and `max`, when set.
|
|
38
|
+
|
|
39
|
+
### Sizes
|
|
40
|
+
|
|
41
|
+
| Size | Use when |
|
|
42
|
+
| -------------- | ------------------------------------------------ |
|
|
43
|
+
| `md` (default) | Most forms. |
|
|
44
|
+
| `lg` | Prominent inputs that need larger touch targets. |
|
|
45
|
+
|
|
46
|
+
### State usage
|
|
47
|
+
|
|
48
|
+
- **Invalid:** the value is required and empty, or fails a rule of your own. Say exactly how to fix it in `description`; there’s no default message, so `invalid` on its own shows only the error styling.
|
|
49
|
+
- **Disabled:** the stepper is unavailable. Consider helper text explaining why.
|
|
50
|
+
- **Read-only:** use instead of disabled when the value is still relevant in context. The + and − buttons are hidden.
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
---
|
|
2
|
+
use_when:
|
|
3
|
+
- the title, main actions and tabs at the top of a page
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# PageHeader
|
|
7
|
+
|
|
8
|
+
## Rules
|
|
9
|
+
|
|
10
|
+
- **Do** use one page header per page, with an `h1` for the page title.
|
|
11
|
+
- **Do** use the page header button kinds (`primary-page-header`, `secondary-page-header`) for actions in the header.
|
|
12
|
+
- **Do** mark the current navigation item with the `selected` class and `aria-current="page"`.
|
|
13
|
+
- **Do** build navigation as an unordered list of links or buttons.
|
|
14
|
+
- **Don’t** add more than one primary action; put extra actions in a Page Header Actions Dropdown Button.
|
|
15
|
+
- **Don’t** use regular button kinds in the header actions; below 600px they don’t match the header’s tinted background.
|
|
16
|
+
|
|
17
|
+
## Guidelines
|
|
18
|
+
|
|
19
|
+
### When to use
|
|
20
|
+
|
|
21
|
+
A page header lays out the primary title, optional navigation, and action buttons at the top of a page. Use one per page to anchor the page’s identity and primary controls.
|
|
22
|
+
|
|
23
|
+
- **Title:** the `children` of the header. For simple pages, an `h1` is enough. The `h1` can be wrapped in other elements alongside other content, like a subtitle or avatar.
|
|
24
|
+
- **Actions:** the main things people do on this page, shown on the right of the title at wide widths.
|
|
25
|
+
- **Navigation:** tabs for moving between the related pages of a resource, shown below the title.
|
|
26
|
+
|
|
27
|
+
Use a Sidenav for deeper secondary navigation within a section.
|
|
28
|
+
|
|
29
|
+
### Content
|
|
30
|
+
|
|
31
|
+
- Keep the title short and specific to the page. Use sentence case.
|
|
32
|
+
- Write navigation labels as short nouns (“Home”, “Members”, “Settings”).
|
|
33
|
+
- Write action labels as verbs, following the Button guidelines.
|
|
34
|
+
|
|
35
|
+
### Variations
|
|
36
|
+
|
|
37
|
+
| Variation | Use when |
|
|
38
|
+
| --------------------- | -------------------------------------------------------------------- |
|
|
39
|
+
| Default | Most pages. A title, with optional actions and navigation. |
|
|
40
|
+
| Profile (`profile`) | Person and profile pages. Centers the title and actions below 960px. |
|
|
41
|
+
| Inactive (`inactive`) | The record is inactive or archived. Uses a neutral background. |
|
|
42
|
+
|
|
43
|
+
### State usage
|
|
44
|
+
|
|
45
|
+
- **Disabled:** use a `button` with `disabled` for a navigation item that’s unavailable.
|
|
46
|
+
- **Indicator:** add the `indicator` class to a navigation item to draw attention to it.
|
|
47
|
+
- **Badge:** add `<span class="suffix"><span class="badge">3</span></span>` after the label to show a count or short text. If the label does not explain the count, add visually hidden text, such as “3 unread”.
|
|
48
|
+
- **Icon:** add `<span class="suffix">` with an icon after the label. Add a `status-error`, `status-info`, `status-success` or `status-warning` class to the `suffix` to color the icon. Give the icon an `aria-label`, because color alone does not tell people the status.
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
---
|
|
2
|
+
use_when:
|
|
3
|
+
- showing a short form, filter or list from a button without leaving the page
|
|
4
|
+
- content anchored to a button that isn’t a menu of actions
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Popover
|
|
8
|
+
|
|
9
|
+
## Rules
|
|
10
|
+
|
|
11
|
+
- **Do** use a Popover for supplementary content or lightweight controls anchored to a button, like column settings, a short filter, or a small form.
|
|
12
|
+
- **Do** use a Tapestry button as the trigger, wrapped in `PopoverTrigger`: `<Popover><PopoverTrigger><Button /></PopoverTrigger><PopoverContent>…</PopoverContent></Popover>`.
|
|
13
|
+
- **Do** give icon-only triggers a `tooltip`.
|
|
14
|
+
- **Do** keep content short and focused. The surface is capped at 24rem wide.
|
|
15
|
+
- **Do** set `aria-label` on `PopoverContent` when the trigger’s name doesn’t describe what the popover contains.
|
|
16
|
+
- **Don’t** use a Popover for a list of actions or links; use a Dropdown instead.
|
|
17
|
+
- **Don’t** use a Popover for a focused task that needs the user’s full attention; use a Modal instead.
|
|
18
|
+
|
|
19
|
+
## Guidelines
|
|
20
|
+
|
|
21
|
+
### When to use
|
|
22
|
+
|
|
23
|
+
- Use to reveal content or controls on demand without leaving the page: a search field, a short form, a list, or plain text.
|
|
24
|
+
- For a menu of actions or links, use a Dropdown. It provides menu semantics and keyboard navigation that a Popover doesn’t.
|
|
25
|
+
- For a bounded task that blocks the rest of the page, use a Modal.
|
|
26
|
+
|
|
27
|
+
> **Popover or Dropdown?**
|
|
28
|
+
>
|
|
29
|
+
> A Dropdown is a menu: every item is an action or a link. A Popover holds anything else. If the content is a list of commands, use a Dropdown.
|
|
30
|
+
|
|
31
|
+
### Content
|
|
32
|
+
|
|
33
|
+
- Keep content brief. If it needs scrolling or headings, it probably belongs in a Modal. If it needs several steps, it usually belongs on its own page.
|
|
34
|
+
- Put a close or apply button inside the content when the user needs an explicit way to finish. Content can close the popover itself with `usePopoverClose()`.
|
|
35
|
+
|
|
36
|
+
### Behavior
|
|
37
|
+
|
|
38
|
+
- Pressing the trigger toggles the popover. Escape and clicking outside close it.
|
|
39
|
+
- When it closes, focus returns to the trigger.
|
|
40
|
+
- By default the popover is modal: content outside it is hidden from assistive tech and a click-blocking underlay sits behind it, so the first click outside only closes the popover.
|
|
41
|
+
- Set `modal={false}` on `PopoverContent` for lighter dismissal, such as several popovers side by side where one click should move straight from one trigger to another. The page still can’t scroll while it’s open.
|
|
42
|
+
|
|
43
|
+
### Positioning
|
|
44
|
+
|
|
45
|
+
- It opens below the trigger by default. Change the side with `placement` on `PopoverContent`, and nudge it with `offset` (distance from the trigger) and `crossOffset`.
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
---
|
|
2
|
+
use_when:
|
|
3
|
+
- choosing one option from 2–5 choices
|
|
4
|
+
- people should compare the options before choosing
|
|
5
|
+
- an option needs a description under it
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# RadioGroup
|
|
9
|
+
|
|
10
|
+
## Rules
|
|
11
|
+
|
|
12
|
+
- **Do** wrap every set of two or more related Radios in a Radio Group, with a label that explains what the choice is for.
|
|
13
|
+
- **Do** give every radio in the group the same `name`, so selecting one deselects the others.
|
|
14
|
+
- **Do** set `required` on a radio when a choice is mandatory, and leave every radio unchecked until the user chooses. The asterisk appears on the group label.
|
|
15
|
+
- **Do** write a group error that says exactly how to fix the problem.
|
|
16
|
+
- **Don’t** use a Radio Group when users can choose more than one option; use a Checkbox Group instead.
|
|
17
|
+
- **Don’t** use a Radio Group for more than 5 options; use a Select instead.
|
|
18
|
+
- **Don’t** rely on the default “Please select an option” error when you can be more specific.
|
|
19
|
+
|
|
20
|
+
## Guidelines
|
|
21
|
+
|
|
22
|
+
### When to use
|
|
23
|
+
|
|
24
|
+
- Use whenever you show two or more Radios that answer the same question. The group renders as a `<fieldset>` with a `<legend>`, so screen readers announce the group label along with each option.
|
|
25
|
+
- Show every option at once so users can compare before choosing.
|
|
26
|
+
- If there are more than 5 options or space is tight, use a Select.
|
|
27
|
+
- If choosing is optional, add a “None” option so people can undo a selection.
|
|
28
|
+
|
|
29
|
+
### Content
|
|
30
|
+
|
|
31
|
+
- **Group label:** a short noun or question in sentence case that explains the purpose of the group, like “Campus” or “Who can see this event?”.
|
|
32
|
+
- **Description:** optional context below the label, 1–2 sentences.
|
|
33
|
+
- **Error message:** replaces the description when the group is invalid. Say what went wrong and how to fix it (“Choose a campus”).
|
|
34
|
+
- Follow the Radio content guidelines for each option’s label.
|
|
35
|
+
|
|
36
|
+
### Sizes
|
|
37
|
+
|
|
38
|
+
| Size | Use when |
|
|
39
|
+
| -------------- | ------------------------------------------------------------------------------------------------------------------- |
|
|
40
|
+
| `md` (default) | Most forms. |
|
|
41
|
+
| `sm` | Compact layouts. The group’s `size` sets the label and description size only, so set `size="sm"` on each Radio too. |
|
|
42
|
+
|
|
43
|
+
### State usage
|
|
44
|
+
|
|
45
|
+
- **Invalid:** set `invalid` when a required choice wasn’t made, a selection creates a conflict, or the action fails.
|
|
46
|
+
- **Disabled:** set `disabled` on the group to disable every radio in it. If the whole group is unavailable, consider hiding it or explaining why.
|
|
47
|
+
- **Required:** set `required` on a radio in the group. When a radio is selected by default, leave `required` off.
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
---
|
|
2
|
+
use_when:
|
|
3
|
+
- choosing exactly one option, with every option visible
|
|
4
|
+
- building the options inside a Radio Group
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Radio
|
|
8
|
+
|
|
9
|
+
## Rules
|
|
10
|
+
|
|
11
|
+
- **Do** use radios when users must select exactly one option from a list of mutually exclusive choices.
|
|
12
|
+
- **Do** show all available options so users can compare before selecting.
|
|
13
|
+
- **Do** always put radios in a Radio Group with a clear label, and give every radio in the group the same `name`.
|
|
14
|
+
- **Do** keep each radio’s label visible unless something on screen already names it, like the row it selects. Only then leave it out, and point `aria-labelledby` at that text.
|
|
15
|
+
- **Do** pre-select an option only when there’s a safe default, like a current setting. Otherwise leave every radio unchecked and set `required`.
|
|
16
|
+
- **Don’t** use radios when users can select more than one option; use Checkboxes instead.
|
|
17
|
+
- **Don’t** use radios for a setting that takes effect immediately; use a Toggle Switch for on/off, or a Segmented Control for 2–5 options.
|
|
18
|
+
- **Don’t** use radios for more than 5 options; use a Select instead.
|
|
19
|
+
- **Don’t** use a Radio by itself, outside a Radio Group.
|
|
20
|
+
|
|
21
|
+
## Guidelines
|
|
22
|
+
|
|
23
|
+
### When to use
|
|
24
|
+
|
|
25
|
+
- Use when only one option can be chosen from a set and you want to show all the options at once.
|
|
26
|
+
- Once a radio is selected, it can only be deselected by selecting a different option in the group.
|
|
27
|
+
- If choosing is optional, add a “None” option so people can undo a selection.
|
|
28
|
+
|
|
29
|
+
> **Radio Group or Select?**
|
|
30
|
+
>
|
|
31
|
+
> Both handle single selection from a list. A Radio Group displays all options at once so users can compare before choosing. A Select hides options behind a dropdown, which is better when space is limited or the list is long. If users benefit from seeing all choices side by side, use a Radio Group. If there are more than 5 options or the choice is straightforward, use a Select.
|
|
32
|
+
|
|
33
|
+
### Content
|
|
34
|
+
|
|
35
|
+
- Use sentence case for labels: capitalize only the first word and proper nouns.
|
|
36
|
+
- Use clear, descriptive language that explains what each option represents.
|
|
37
|
+
- Keep labels concise, 1–5 words when possible.
|
|
38
|
+
- Frame labels as options or states, not as actions.
|
|
39
|
+
- Keep labels to the right of the radio. The component always puts them there, so don’t move them to the left or above in designs.
|
|
40
|
+
- Use descriptive text below the label only when it adds context, and keep it to 1–2 sentences.
|
|
41
|
+
- Numerals are fine (“$3 every 3 months”).
|
|
42
|
+
- Omit unnecessary articles (“a”, “the”), and don’t end labels with commas or semicolons.
|
|
43
|
+
|
|
44
|
+
### Interactions
|
|
45
|
+
|
|
46
|
+
- **Click or tap:** selects the radio button and deselects any other selected option in the group.
|
|
47
|
+
- **Tab:** moves focus into the group, to the selected option (or the first option when none is selected).
|
|
48
|
+
- **Arrow keys:** move between options and select them.
|
|
49
|
+
- **Space:** selects the focused option.
|
|
50
|
+
|
|
51
|
+
### Sizes
|
|
52
|
+
|
|
53
|
+
| Size | Use when |
|
|
54
|
+
| -------------- | -------------------------------------------------------------------------------------------------------- |
|
|
55
|
+
| `md` (default) | Most forms. |
|
|
56
|
+
| `sm` | Compact layouts. A Radio Group’s `size` doesn’t change its radios, so set `size="sm"` on each radio too. |
|
|
57
|
+
|
|
58
|
+
### State usage
|
|
59
|
+
|
|
60
|
+
- **Disabled:** when the option is unavailable. If every option is disabled, consider hiding the group or explaining why.
|
|
61
|
+
- **Invalid:** when a required choice wasn’t made, a selection creates a conflict, or the action fails. Set `invalid` on the Radio Group so every radio and the group description show the error, and say exactly how to fix it.
|
|
62
|
+
- **Required:** when a choice is mandatory. Leave the radios unchecked until the user chooses. The asterisk goes on the group label, not on individual radios. A radio that’s selected by default (such as on a settings page) doesn’t need a required indicator.
|