@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
package/dist/unstable.js CHANGED
@@ -59,5 +59,6 @@ export { TextArea } from './components/text-area/TextArea.js';
59
59
  export { TimeField } from './components/time-field/TimeField.js';
60
60
  export { ToggleSwitch } from './components/toggle-switch/ToggleSwitch.js';
61
61
  export { computedToken, token } from './jsTokens.js';
62
+ export { I18nProvider, setLocale } from './utilities/locale.js';
62
63
  export { reactNativeTokens } from '@planningcenter/tapestry-tokens/react-native-tokens';
63
64
  //# sourceMappingURL=unstable.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"unstable.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
1
+ {"version":3,"file":"unstable.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;"}
@@ -0,0 +1,8 @@
1
+ export type DataHookType = "row-action" | "table-action";
2
+ export type DataHookProps = {
3
+ "data-hook-id"?: string;
4
+ "data-hook-type"?: DataHookType;
5
+ };
6
+ /** Builds an element's data hook attributes, or none when it has no `id`. */
7
+ export declare function dataHookProps(type: DataHookType, id: string | undefined): DataHookProps;
8
+ //# sourceMappingURL=dataHooks.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"dataHooks.d.ts","sourceRoot":"","sources":["../../src/utilities/dataHooks.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG,YAAY,GAAG,cAAc,CAAA;AAExD,MAAM,MAAM,aAAa,GAAG;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,gBAAgB,CAAC,EAAE,YAAY,CAAA;CAChC,CAAA;AAED,6EAA6E;AAC7E,wBAAgB,aAAa,CAC3B,IAAI,EAAE,YAAY,EAClB,EAAE,EAAE,MAAM,GAAG,SAAS,GACrB,aAAa,CAEf"}
@@ -0,0 +1,7 @@
1
+ /** Builds an element's data hook attributes, or none when it has no `id`. */
2
+ function dataHookProps(type, id) {
3
+ return id ? { "data-hook-id": id, "data-hook-type": type } : {};
4
+ }
5
+
6
+ export { dataHookProps };
7
+ //# sourceMappingURL=dataHooks.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"dataHooks.js","sources":["../../src/utilities/dataHooks.ts"],"sourcesContent":["export type DataHookType = \"row-action\" | \"table-action\"\n\nexport type DataHookProps = {\n \"data-hook-id\"?: string\n \"data-hook-type\"?: DataHookType\n}\n\n/** Builds an element's data hook attributes, or none when it has no `id`. */\nexport function dataHookProps(\n type: DataHookType,\n id: string | undefined\n): DataHookProps {\n return id ? { \"data-hook-id\": id, \"data-hook-type\": type } : {}\n}\n"],"names":[],"mappings":"AAOA;AACM,SAAU,aAAa,CAC3B,IAAkB,EAClB,EAAsB,EAAA;AAEtB,IAAA,OAAO,EAAE,GAAG,EAAE,cAAc,EAAE,EAAE,EAAE,gBAAgB,EAAE,IAAI,EAAE,GAAG,EAAE;AACjE;;;;"}
@@ -0,0 +1,25 @@
1
+ import React, { type ReactNode } from "react";
2
+ /**
3
+ * Sets the locale DataTable formats dates with, app-wide. Call once at boot,
4
+ * before the first render; later calls don't re-render mounted components.
5
+ * An `I18nProvider` overrides it for its subtree. Pass `undefined` to fall
6
+ * back to the browser locale.
7
+ */
8
+ export declare function setLocale(locale: string | undefined): void;
9
+ export interface I18nProviderProps {
10
+ children: ReactNode;
11
+ /** A BCP 47 language tag, e.g. `en-GB`. */
12
+ locale: string;
13
+ }
14
+ /**
15
+ * Sets the locale for a subtree, overriding `setLocale`. Use this instead of
16
+ * importing `I18nProvider` from `react-aria`: Tapestry can't see a provider
17
+ * from a separately installed copy. An invalid locale is ignored.
18
+ */
19
+ export declare function I18nProvider({ children, locale }: I18nProviderProps): React.JSX.Element;
20
+ /**
21
+ * Resolves the nearest `I18nProvider`, then `setLocale`, then the browser
22
+ * locale. An invalid locale falls through to the next one.
23
+ */
24
+ export declare function useTapestryLocale(): string;
25
+ //# sourceMappingURL=locale.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"locale.d.ts","sourceRoot":"","sources":["../../src/utilities/locale.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAiB,KAAK,SAAS,EAAc,MAAM,OAAO,CAAA;AAQxE;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,QAEnD;AAaD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,SAAS,CAAA;IACnB,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAA;CACf;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,iBAAiB,qBASnE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,WAIhC"}
@@ -0,0 +1,48 @@
1
+ import React__default, { createContext, useContext } from 'react';
2
+ import { I18nProvider as I18nProvider$1, useLocale } from 'react-aria/I18nProvider';
3
+
4
+ let globalLocale;
5
+ /**
6
+ * Sets the locale DataTable formats dates with, app-wide. Call once at boot,
7
+ * before the first render; later calls don't re-render mounted components.
8
+ * An `I18nProvider` overrides it for its subtree. Pass `undefined` to fall
9
+ * back to the browser locale.
10
+ */
11
+ function setLocale(locale) {
12
+ globalLocale = locale;
13
+ }
14
+ function canonicalLocale(locale) {
15
+ if (!locale)
16
+ return undefined;
17
+ try {
18
+ return Intl.getCanonicalLocales(locale)[0];
19
+ }
20
+ catch {
21
+ return undefined;
22
+ }
23
+ }
24
+ const LocaleContext = createContext(undefined);
25
+ /**
26
+ * Sets the locale for a subtree, overriding `setLocale`. Use this instead of
27
+ * importing `I18nProvider` from `react-aria`: Tapestry can't see a provider
28
+ * from a separately installed copy. An invalid locale is ignored.
29
+ */
30
+ function I18nProvider({ children, locale }) {
31
+ const validLocale = canonicalLocale(locale);
32
+ if (!validLocale)
33
+ return React__default.createElement(React__default.Fragment, null, children);
34
+ return (React__default.createElement(LocaleContext.Provider, { value: validLocale },
35
+ React__default.createElement(I18nProvider$1, { locale: validLocale }, children)));
36
+ }
37
+ /**
38
+ * Resolves the nearest `I18nProvider`, then `setLocale`, then the browser
39
+ * locale. An invalid locale falls through to the next one.
40
+ */
41
+ function useTapestryLocale() {
42
+ const providerLocale = useContext(LocaleContext);
43
+ const { locale: defaultLocale } = useLocale();
44
+ return providerLocale ?? canonicalLocale(globalLocale) ?? defaultLocale;
45
+ }
46
+
47
+ export { I18nProvider, setLocale, useTapestryLocale };
48
+ //# sourceMappingURL=locale.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"locale.js","sources":["../../src/utilities/locale.tsx"],"sourcesContent":["import React, { createContext, type ReactNode, useContext } from \"react\"\nimport {\n I18nProvider as AriaI18nProvider,\n useLocale,\n} from \"react-aria/I18nProvider\"\n\nlet globalLocale: string | undefined\n\n/**\n * Sets the locale DataTable formats dates with, app-wide. Call once at boot,\n * before the first render; later calls don't re-render mounted components.\n * An `I18nProvider` overrides it for its subtree. Pass `undefined` to fall\n * back to the browser locale.\n */\nexport function setLocale(locale: string | undefined) {\n globalLocale = locale\n}\n\nfunction canonicalLocale(locale: string | undefined) {\n if (!locale) return undefined\n try {\n return Intl.getCanonicalLocales(locale)[0]\n } catch {\n return undefined\n }\n}\n\nconst LocaleContext = createContext<string | undefined>(undefined)\n\nexport interface I18nProviderProps {\n children: ReactNode\n /** A BCP 47 language tag, e.g. `en-GB`. */\n locale: string\n}\n\n/**\n * Sets the locale for a subtree, overriding `setLocale`. Use this instead of\n * importing `I18nProvider` from `react-aria`: Tapestry can't see a provider\n * from a separately installed copy. An invalid locale is ignored.\n */\nexport function I18nProvider({ children, locale }: I18nProviderProps) {\n const validLocale = canonicalLocale(locale)\n if (!validLocale) return <>{children}</>\n\n return (\n <LocaleContext.Provider value={validLocale}>\n <AriaI18nProvider locale={validLocale}>{children}</AriaI18nProvider>\n </LocaleContext.Provider>\n )\n}\n\n/**\n * Resolves the nearest `I18nProvider`, then `setLocale`, then the browser\n * locale. An invalid locale falls through to the next one.\n */\nexport function useTapestryLocale() {\n const providerLocale = useContext(LocaleContext)\n const { locale: defaultLocale } = useLocale()\n return providerLocale ?? canonicalLocale(globalLocale) ?? defaultLocale\n}\n"],"names":["React","AriaI18nProvider"],"mappings":";;;AAMA,IAAI,YAAgC;AAEpC;;;;;AAKG;AACG,SAAU,SAAS,CAAC,MAA0B,EAAA;IAClD,YAAY,GAAG,MAAM;AACvB;AAEA,SAAS,eAAe,CAAC,MAA0B,EAAA;AACjD,IAAA,IAAI,CAAC,MAAM;AAAE,QAAA,OAAO,SAAS;AAC7B,IAAA,IAAI;QACF,OAAO,IAAI,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAC5C;AAAE,IAAA,MAAM;AACN,QAAA,OAAO,SAAS;IAClB;AACF;AAEA,MAAM,aAAa,GAAG,aAAa,CAAqB,SAAS,CAAC;AAQlE;;;;AAIG;SACa,YAAY,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAqB,EAAA;AAClE,IAAA,MAAM,WAAW,GAAG,eAAe,CAAC,MAAM,CAAC;AAC3C,IAAA,IAAI,CAAC,WAAW;QAAE,OAAOA,cAAA,CAAA,aAAA,CAAAA,cAAA,CAAA,QAAA,EAAA,IAAA,EAAG,QAAQ,CAAI;IAExC,QACEA,6BAAC,aAAa,CAAC,QAAQ,EAAA,EAAC,KAAK,EAAE,WAAW,EAAA;QACxCA,cAAA,CAAA,aAAA,CAACC,cAAgB,EAAA,EAAC,MAAM,EAAE,WAAW,IAAG,QAAQ,CAAoB,CAC7C;AAE7B;AAEA;;;AAGG;SACa,iBAAiB,GAAA;AAC/B,IAAA,MAAM,cAAc,GAAG,UAAU,CAAC,aAAa,CAAC;IAChD,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,GAAG,SAAS,EAAE;IAC7C,OAAO,cAAc,IAAI,eAAe,CAAC,YAAY,CAAC,IAAI,aAAa;AACzE;;;;"}
@@ -0,0 +1,62 @@
1
+ ---
2
+ title: Accessibility
3
+ description: Planning Center’s accessibility approach and WCAG 2.1 AA baseline, with guidance on form labels, color contrast, keyboard navigation, and screen reader support.
4
+ order: 40
5
+ ---
6
+
7
+ # Accessibility
8
+
9
+ ## Rules
10
+
11
+ - **Do** meet WCAG 2.1 AA contrast: 4.5:1 for normal text, 3:1 for large text and UI components.
12
+ - **Do** make every interactive element keyboard-operable with a visible focus indicator.
13
+ - **Do** use semantic HTML first, and ARIA only when semantic HTML isn’t sufficient.
14
+ - **Don’t** override token-based colors with custom hex values.
15
+ - **Don’t** remove focus indication without a replacement, or let focus become trapped in a component.
16
+ - **Don’t** put interactive elements (links or buttons) inside labels.
17
+
18
+ ## Our approach
19
+
20
+ Planning Center follows **WCAG 2.1 Level AA** as its baseline. Accessibility is a growth edge for us, so we work on it three ways:
21
+
22
+ - **Quick wins:** fix accessibility issues as we come across them in day-to-day work.
23
+ - **Documentation:** log bigger gaps in existing features as we find them.
24
+ - **Build it in:** consider accessibility from the start of new features. Retrofitting is always harder.
25
+
26
+ Current priorities are **keyboard navigation** and **color contrast**.
27
+
28
+ ## Keyboard and focus
29
+
30
+ Everything interactive must work with only a keyboard. This helps people who use keyboards, switch devices, and other assistive technology.
31
+
32
+ | Key | Does |
33
+ | --------------- | --------------------------------------------------------- |
34
+ | Tab / Shift+Tab | Moves focus between controls |
35
+ | Space | Activates buttons, checkboxes, and toggle switches |
36
+ | Enter | Activates buttons |
37
+ | Arrow keys | Moves within radio groups, select menus, and date pickers |
38
+ | Escape | Closes menus and popovers |
39
+
40
+ **Focus**
41
+
42
+ - Focus is always visible. You can restyle the focus ring, but never remove it without a replacement.
43
+ - Opening a modal or dialog moves focus into it. Closing it returns focus to the trigger.
44
+ - Provide skip links to bypass repeated navigation.
45
+ - Focus must never get trapped in a component.
46
+ - Custom controls built on Tapestry primitives need to be in the tab order with a visible focus indicator.
47
+
48
+ ## Screen readers
49
+
50
+ Content must work with screen readers like VoiceOver, NVDA, and JAWS.
51
+
52
+ - **Semantic HTML first:** `<button>` for actions, `<a>` for navigation, `<nav>`, `<main>`, `<header>`, and `<footer>` for page structure, and `<h1>`–`<h6>` in order.
53
+ - **ARIA when HTML isn’t enough:** `aria-label` for elements with no visible text, `aria-labelledby` to point at existing text, `aria-describedby` for extra context, and `role` when there’s no semantic element.
54
+ - **Images:** give meaningful images `alt` text that describes their content and purpose. Decorative images get `alt=""`. Give icon-only buttons and links a `tooltip`; it also becomes their accessible name.
55
+
56
+ ## Resources and help
57
+
58
+ - [WCAG 2.1 quick reference](https://www.w3.org/WAI/WCAG21/quickref/)
59
+ - [WebAIM resources](https://webaim.org/resources/)
60
+ - [The A11y Project](https://www.a11yproject.com/)
61
+
62
+ Questions? Reach out to your squad’s UXD or your area’s UXM.
@@ -0,0 +1,44 @@
1
+ ---
2
+ use_when:
3
+ - two or more related actions that belong together, like a bulk-action bar
4
+ - joining buttons into one control with shared borders
5
+ ---
6
+
7
+ # ButtonGroup
8
+
9
+ ## Rules
10
+
11
+ - **Do** give every button in a group the same `kind`: `primary`, `secondary`, `secondary-interaction`, `neutral`, or `staff-only`.
12
+ - **Do** give the group a clear purpose through a nearby heading or label, and name it with `aria-label` or `aria-labelledby`.
13
+ - **Do** anchor a Button Group to what it acts on, inside the table or card region it controls.
14
+ - **Do** use a Button Group for two or more related actions on the same content, where each button does its own thing, like “Add to list”, “Send email” and “Export”.
15
+ - **Don’t** group unrelated actions; use buttons in a Flex container instead.
16
+ - **Don’t** use a Button Group to pick one option from a set, like switching between Table and Card views. Buttons in a group don’t stay selected, so use a Segmented Control instead.
17
+ - **Don’t** group actions of different importance, like Save and Cancel. Show them as separate buttons so the main action stands out.
18
+ - **Don’t** mix kinds in one group, or use `pill`, `ghost`, or delete kinds; they don’t join cleanly.
19
+
20
+ ## Guidelines
21
+
22
+ ### When to use
23
+
24
+ Button Group visually attaches a row of related Button, Icon Button, or Dropdown Button elements into a single control, with shared borders and rounded corners only on the outer edges. It’s a layout component with no state of its own. Each button keeps its own `onClick`, `kind`, `disabled`, and `loading` states.
25
+
26
+ - Use a Button Group when actions belong together as a set, such as a bulk-action bar.
27
+
28
+ ### Choosing buttons
29
+
30
+ - Button guidelines apply unless noted here.
31
+
32
+ ### Variations
33
+
34
+ | Variation | Use when |
35
+ | ------------------------ | ---------------------------------------------------------------------------------- |
36
+ | Default | Text-only Button children. |
37
+ | Label + icon | Icons help distinguish similar actions. Add a prefix or suffix icon to each label. |
38
+ | Icon only | Icon meaning is unambiguous. Give each Icon Button a `tooltip`. |
39
+ | Staff only | The actions are related and staff-only. |
40
+ | Trailing Dropdown Button | You need “More” actions. Put the Dropdown Button last. |
41
+
42
+ ### Sizes
43
+
44
+ - The group has no `size` prop. Set the same `size` on every button, matched to nearby inputs.
@@ -0,0 +1,78 @@
1
+ ---
2
+ use_when:
3
+ - something happens on click, like save, add, delete or opening a modal
4
+ - the main or secondary action in a form, dialog or page header
5
+ ---
6
+
7
+ # Button
8
+
9
+ ## Rules
10
+
11
+ - **Do** use buttons for actions such as submitting forms, confirming choices, or moving to the next step in a workflow.
12
+ - **Do** write sentence-case, verb-based labels that say what will happen (e.g., “Save changes”).
13
+ - **Do** give every icon-only button a `tooltip`. It becomes the accessible name unless you also set `aria-label`.
14
+ - **Do** add “...” to destructive labels that require confirmation (e.g., “Delete...”).
15
+ - **Do** check text contrast (4.5:1) when placing outline buttons on surfaces other than Neutral/10.
16
+ - **Don’t** use a Button for navigation; use a Link, with a button `kind` if it should look like a button.
17
+ - **Don’t** use a Dropdown Button to select a value; use a Select.
18
+ - **Don’t** use color to tell binary choices apart; use `kind="primary"` for the main action and `kind="secondary"` for the other.
19
+ - **Don’t** put badges inside buttons.
20
+
21
+ ## Guidelines
22
+
23
+ ### When to use
24
+
25
+ - Use one `primary` per section or modal. It’s the solid, highest-emphasis button.
26
+ - For the rest, prefer Interaction kinds (`secondary-interaction`, `ghost-interaction`). Use Neutral kinds (`secondary`, `ghost`, `neutral`) when color adds no meaning, and Delete kinds (`delete`, `secondary-delete`, `ghost-delete`) only for destructive actions.
27
+
28
+ ### Types
29
+
30
+ | Type | Use for |
31
+ | ----------------------------------- | ---------------------------------------------------------------------------------------------- |
32
+ | Button | Most actions. Text-only by default; a prefix or suffix icon is optional. |
33
+ | Icon Button | Common, unambiguous actions where space is tight (close, edit, settings). Give it a `tooltip`. |
34
+ | Dropdown Button | Several related actions under one trigger. |
35
+ | Dropdown Icon Button | A compact menu of related actions. Give it a `tooltip`. |
36
+ | Page Header Actions Dropdown Button | A primary page action with secondary actions in a menu. Can show an attention indicator. |
37
+ | Button with `kind="pill"` | Small, lightweight inline actions like tags, filters, or compact toggles. |
38
+ | Button Group | Two or more related actions joined into one control, like a bulk-action bar. |
39
+
40
+ > **Dropdown Button or Select?**
41
+ >
42
+ > A Dropdown Button runs an action (“Export as PDF”). A Select captures a value in a form (“Choose a campus”). If the choice gets saved or submitted, use a Select.
43
+
44
+ ### Content
45
+
46
+ - Use sentence case and an action verb: “Save”, “Submit”, “Delete”.
47
+ - Keep labels to one or two words for basic actions.
48
+ - Use “Create” for something new from a blank state, and “Add” for adding to something that exists.
49
+ - Use explicit labels in alerts: “Delete account” and “Cancel”, not “Yes” and “No”.
50
+ - Numerals are fine when they add clarity (“Add 3 people”).
51
+ - Skip articles, commas, and semicolons.
52
+ - Use “...” only on destructive actions that ask for confirmation.
53
+ - Keep icon-button tooltips to 1–5 words.
54
+
55
+ ### Variations
56
+
57
+ | Variation | `kind` | Use when |
58
+ | ---------- | ---------------------------------------------- | ----------------------------------------------------------------------------------- |
59
+ | Solid | `primary` | The primary action. Highest emphasis. |
60
+ | Outline | `secondary` (default), `secondary-interaction` | Secondary actions. Medium emphasis. |
61
+ | Ghost | `ghost`, `ghost-interaction` | Tertiary actions in toolbars and compact layouts. Lowest emphasis. |
62
+ | Neutral | `neutral` | General-purpose actions where color doesn’t add meaning. |
63
+ | Delete | `delete`, `secondary-delete`, `ghost-delete` | Destructive actions. |
64
+ | Staff only | `staff-only` | Actions only staff can see. |
65
+ | Inline | `inline-text`, `neutral-inline` | An action inside a sentence or table cell that should look like text, not a button. |
66
+
67
+ `primary-page-header` and `secondary-page-header` are for page headers only.
68
+
69
+ ### Sizes
70
+
71
+ - Choose from `xs`, `sm`, `md` (default), `lg`, and `xl`.
72
+ - Match the density of the layout.
73
+
74
+ ### State usage
75
+
76
+ - **Disabled:** only when the action is temporarily unavailable. Explain why when you can.
77
+ - **Disabled icon buttons:** a `tooltip` doesn't open on hover or keyboard focus while the button is `disabled` or `loading`. Explain why it's disabled in nearby text instead.
78
+ - **Loading:** set `loading` while an action runs, instead of `disabled`.
@@ -0,0 +1,51 @@
1
+ ---
2
+ use_when:
3
+ - a question where people can choose any number of answers
4
+ - two or more checkboxes that answer the same question
5
+ ---
6
+
7
+ # CheckboxGroup
8
+
9
+ ## Rules
10
+
11
+ - **Do** wrap two or more related Checkboxes in a Checkbox Group, with a label that explains what the options have in common.
12
+ - **Do** set `required` on every checkbox when all of them must be checked; the asterisk moves to the group label.
13
+ - **Do** write a group error that says exactly how to fix the problem.
14
+ - **Don’t** use a Checkbox Group when only one option can be chosen; use a Radio Group instead.
15
+ - **Don’t** group unrelated options just to save space; give each question its own group.
16
+ - **Don’t** rely on the default “One or more checkboxes are invalid.” error when you can be more specific.
17
+
18
+ ## Guidelines
19
+
20
+ ### When to use
21
+
22
+ - Use whenever you show two or more Checkboxes 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.
23
+ - Each checkbox stays independent; users can select zero, one, or several.
24
+ - If only one option can be chosen, use a Radio Group.
25
+
26
+ ### Content
27
+
28
+ - **Group label:** a short noun or question in sentence case, like “Email me about” or “Which teams can see this?”.
29
+ - **Description:** optional context below the label, 1–2 sentences.
30
+ - **Error message:** replaces the description when the group is invalid. Say what went wrong and how to fix it (“Choose at least one team”).
31
+ - Follow the Checkbox content guidelines for each option’s label.
32
+
33
+ ### Variations
34
+
35
+ | Variation | Use when |
36
+ | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
37
+ | Required (group) | Every checkbox must be checked, like several required agreements. Set `required` on each one, and the asterisk moves to the group label. |
38
+ | Required (individual) | Some checkboxes are mandatory and others optional, like required terms and optional marketing email. Set `required` on just those checkboxes. |
39
+ | At least one | People must choose one or more options. `required` can’t check this, so say “Choose at least one” in the label or description, check the selection in your own code, and set `invalid` with a specific error. |
40
+
41
+ ### Sizes
42
+
43
+ | Size | Use when |
44
+ | -------------- | ---------------------------------------------------------------------------------------------------------------------- |
45
+ | `md` (default) | Most forms. |
46
+ | `sm` | Compact layouts. The group’s `size` sets the label and description size only, so set `size="sm"` on each Checkbox too. |
47
+
48
+ ### State usage
49
+
50
+ - **Invalid:** set `invalid` on the group to turn the description into an error message. Set `invalid` on the specific checkboxes that need attention too, so they show the error border.
51
+ - **Disabled:** set `disabled` on the group to disable every checkbox in it. Consider a description explaining why.
@@ -0,0 +1,55 @@
1
+ ---
2
+ use_when:
3
+ - turning an option on or off that’s saved later with a Save or Submit button
4
+ - agreeing to something, like terms, before submitting
5
+ ---
6
+
7
+ # Checkbox
8
+
9
+ ## Rules
10
+
11
+ - **Do** use checkboxes when users can select multiple independent options, or toggle a single option in a form that is saved or submitted.
12
+ - **Do** keep labels to the right of the control, in sentence case. The component always puts them there, so don’t move them to the left or above in designs.
13
+ - **Do** group related options under a clear group label or fieldset legend.
14
+ - **Do** keep the label visible unless something on screen already names the checkbox, like a column header or the row it selects. Only then leave it out, and point `aria-labelledby` at that text.
15
+ - **Do** show specific error messages that tell users how to fix the problem.
16
+ - **Don’t** use checkboxes for mutually exclusive options; use a Radio Group instead.
17
+ - **Don’t** use a checkbox for a setting that takes effect immediately; use a Toggle Switch instead.
18
+ - **Don’t** drop the visible label just to save space.
19
+
20
+ ## Guidelines
21
+
22
+ ### When to use
23
+
24
+ - Use when users can select zero, one, or several options. Each checkbox is independent; checking one doesn’t affect the others.
25
+ - Show all the options at once.
26
+ - If only one option can be chosen, use a Radio Group.
27
+
28
+ > **Checkbox or Toggle Switch?**
29
+ >
30
+ > A Checkbox captures a value that’s submitted later with a “Save” or “Submit” action. A Toggle Switch applies the change immediately. If there’s a save step, use a Checkbox.
31
+
32
+ ### Content
33
+
34
+ - Use sentence case and keep labels to 1–5 words when possible.
35
+ - Name the option or feature; don’t frame the label as an action.
36
+ - Make it clear what selecting the option will do.
37
+ - Use a description below the label only when it adds context, and keep it to 1–2 sentences.
38
+ - Numerals are fine (“Add 3 people”).
39
+ - Skip unnecessary articles and trailing commas or semicolons.
40
+
41
+ ### Variations
42
+
43
+ | Variation | Use when |
44
+ | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
45
+ | Standalone | A single checkbox outside a group, such as accepting terms or a notification preference. |
46
+ | No visible label | Something on screen already names the checkbox, like a column header or row text. Point `aria-labelledby` at it. |
47
+ | Description | The label needs added context, like the consequences of checking or unchecking. Keep to 1–2 sentences; put anything lengthy in a helper shelf or support doc. |
48
+ | Required (individual) | Some checkboxes are mandatory and others optional (terms required, marketing email optional). Set `required` on each mandatory checkbox. In a Checkbox Group where every checkbox is required, the asterisk moves to the group label. |
49
+ | Required (group) | Every checkbox in a group must be checked, like several required agreements. Set `required` on each one, and the asterisk moves to the group label. |
50
+
51
+ ### State usage
52
+
53
+ - **Indeterminate:** on a parent checkbox when some, but not all, of the options under it are selected. Set `checked` along with `indeterminate`. Clicking it should select every option under it.
54
+ - **Invalid:** when a required checkbox isn’t checked, a selection creates a conflict, or the action fails. Say exactly what went wrong and how to fix it.
55
+ - **Disabled:** when the checkbox or group is unavailable. Consider a `description` explaining why (on the group, for groups).
@@ -0,0 +1,68 @@
1
+ ---
2
+ use_when:
3
+ - choosing from a list too long to scan, where typing narrows it down
4
+ - choosing one or several options that load from the server as people type
5
+ ---
6
+
7
+ # ComboBox
8
+
9
+ ## Rules
10
+
11
+ - **Do** use a combo box when users need to search or filter a long list of options.
12
+ - **Do** use `menuTrigger="focus"` (the default) when seeing options upfront helps. Use `"input"` when options are familiar or load from the server as people type.
13
+ - **Do** use placeholder text to show the field is searchable (e.g. “Search…”).
14
+ - **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.
15
+ - **Do** keep the label visible unless something on screen already names the field, like a column header, a search icon, or the option it sits under. Only then hide it with `hideLabel`.
16
+ - **Do** use sentence case for error messages.
17
+ - **Don’t** use a combo box when the list is short and fixed; use a Select instead.
18
+ - **Don’t** use `menuTrigger="focus"` for API-driven results that require typing first.
19
+ - **Don’t** hide a label just to save space, and never use placeholder text in its place.
20
+
21
+ ## Guidelines
22
+
23
+ ### When to use
24
+
25
+ - Use when the option list is too long to scan easily, or when users benefit from autocomplete to narrow down choices.
26
+ - Supports single and multiple selection (`selectionMode`). In single mode, choosing an option closes the menu and fills the input. In multiple mode, the menu stays open so users can choose several options. The field doesn’t show the selections, so show them yourself, like a count in the placeholder or a list next to the field.
27
+ - Options can load from a server as the user types, with more loading as they scroll (`loadingState` and `onLoadMore`).
28
+ - By default the value must match an option. `allowsCustomValue` keeps unmatched typed text; use it for standalone search, or with additional UI.
29
+
30
+ ### Content
31
+
32
+ - **Labels:** 1–3 words that describe what the user is selecting or searching for.
33
+ - **Placeholder:** signals the field is searchable. It isn’t a label.
34
+ - **Description:** additional context, valid options, or error instructions. Keep to 1–2 sentences.
35
+ - **Sections:** group long lists under a `ComboBoxSection` with a `title`.
36
+ - **Empty state:** defaults to “No results”. Customize it with `renderEmptyState` to coach users, for example “Start typing to search.”
37
+
38
+ ### Interactions
39
+
40
+ - **Menu trigger:** `menuTrigger` controls when the menu opens.
41
+ - `"focus"` (default): opens as soon as the field is focused. No caret button is shown.
42
+ - `"input"`: opens when the user starts typing.
43
+ - `"manual"`: opens only from the caret button or the arrow keys.
44
+ - **Type to filter:** typing filters the options in real time and hides non-matching ones.
45
+ - **Select an option:** click or press Enter.
46
+ - **Clear:** in single mode, deleting the typed text clears the selection. With `menuTrigger="focus"`, `showClearButton` adds a clear (×) button.
47
+ - **Keyboard:** Arrow Down opens the menu or moves to the next option, Arrow Up moves to the previous option, Enter selects, and Escape closes the menu without selecting.
48
+
49
+ ### Variations
50
+
51
+ | Variation | Use when |
52
+ | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
53
+ | Hidden label | Something on screen already names the field, like a column header. Pass `label` with `hideLabel` so it still has an accessible name. |
54
+ | Search | People pick a result from suggestions, like jumping to a person. Adds a search icon with `showSearchIcon`. To filter content already on the page, use a Search Input. |
55
+ | Multi-select | Picking several values. Set `selectionMode="multiple"` and show the selections yourself. |
56
+
57
+ ### Sizes
58
+
59
+ | Size | Use when |
60
+ | -------------- | ------------------------------------------------ |
61
+ | `md` (default) | Most forms. |
62
+ | `lg` | Prominent inputs that need larger touch targets. |
63
+
64
+ ### State usage
65
+
66
+ - **Invalid:** a required field is empty, the selection creates a conflict, or the action fails. Set `invalid` and say in `description` exactly how to fix it. There’s no default message.
67
+ - **Disabled:** the combo box is unavailable. Consider helper text explaining why.
68
+ - **Read-only:** use instead of disabled when the value is still relevant in context.
@@ -0,0 +1,50 @@
1
+ ---
2
+ use_when:
3
+ - entering an amount of money, like a price, fee or donation
4
+ ---
5
+
6
+ # CurrencyInput
7
+
8
+ ## Rules
9
+
10
+ - **Do** use a currency input for money amounts, such as donations, fees, or prices.
11
+ - **Do** set `currency` to the ISO 4217 code for the amount (e.g. `"CAD"`, `"EUR"`). It defaults to `"USD"`, and both the prefix and the screen-reader currency name come from it.
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 column header or the option it sits under. Only then hide it with `hideLabel`.
14
+ - **Do** use placeholder text only for a sample value, such as “0.00”, or leave it out.
15
+ - **Do** write specific error messages that say how to fix the amount, and pass them as `description` alongside `invalid`. There’s no default message, so `invalid` on its own shows only the error styling.
16
+ - **Don’t** hide a label just to save space, and never use placeholder text in its place.
17
+ - **Don’t** type a currency symbol into the label, placeholder, or value; the prefix already shows it.
18
+ - **Don’t** use a currency input for numbers that aren’t money; use an Input or a Number Stepper.
19
+ - **Don’t** rely on the component to format or validate the amount; handle parsing and rounding in your own code.
20
+
21
+ ## Guidelines
22
+
23
+ ### When to use
24
+
25
+ - Use when users enter an amount of money. The field shows a leading currency symbol derived from the currency code.
26
+ - The component is presentational only: no masking, parsing, or rounding. The value goes in and comes out as typed, so keep whatever number handling you already have.
27
+ - On touch devices it opens a decimal keypad.
28
+
29
+ ### Content
30
+
31
+ - **Labels:** 1–3 words, sentence case, no ending punctuation (e.g. “Amount”, “Registration fee”).
32
+ - **Placeholder:** optional. A sample value only, such as “0.00”.
33
+ - **Description:** brief context or constraints, such as a minimum amount.
34
+ - **Errors:** say what’s wrong and how to fix it, such as “Enter an amount of at least $5.00”.
35
+
36
+ ### Variations
37
+
38
+ | Variation | Use when |
39
+ | ------------------------------------------ | ---------------------------------------------------------- |
40
+ | `currencyDisplay="narrowSymbol"` (default) | The shortest symbol, like `$`, is enough. |
41
+ | `currencyDisplay="symbol"` | You need to disambiguate, like `CA$`. Depends on `locale`. |
42
+ | `currencyDisplay="code"` | You want the code shown, like `USD`. |
43
+ | `expand` | The field should grow to fill a Flex row. |
44
+
45
+ ### Sizes
46
+
47
+ | Size | Use when |
48
+ | -------------- | ------------------------------------------------ |
49
+ | `md` (default) | Most forms. |
50
+ | `lg` | Prominent inputs that need larger touch targets. |
@@ -0,0 +1,67 @@
1
+ ---
2
+ use_when:
3
+ - entering a specific date, like a deadline, event date or birthday
4
+ ---
5
+
6
+ # DatePicker
7
+
8
+ ## Rules
9
+
10
+ - **Do** use a Date Picker when a specific date is required from the user, like scheduling, deadlines, or date of birth.
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 the description to clarify constraints (e.g., “Must be a future date”).
14
+ - **Do** use sentence case for error messages.
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** use a Date Picker for recurring or relative dates (e.g., “every Monday” or “in 3 days”).
18
+ - **Don’t** use a Date Picker when a small set of valid dates spans several months; use a Select or a Radio Group instead (a Checkbox Group if users can pick more than one).
19
+ - **Don’t** use a Date Picker when the date is approximate or flexible, or already known or system-generated.
20
+
21
+ ## Guidelines
22
+
23
+ ### When to use
24
+
25
+ - Users can type into the month, day, and year segments or pick from the calendar popover.
26
+ - If the date is approximate or flexible, a text field or range selector may be more appropriate.
27
+ - For a time of day, use a Time Field.
28
+
29
+ ### Content
30
+
31
+ - Keep the label short (1–3 words) and say which date is being set.
32
+ - Keep the description to 1–2 sentences. Use it for date constraints, not the format; the segments already show the user’s locale format.
33
+ - Use `min` and `max` to restrict the selectable range, and `isDateUnavailable` for individual dates that can’t be chosen.
34
+
35
+ ### Interactions
36
+
37
+ - **Click or tap:** the calendar button opens the calendar popover. Clicking a segment focuses that segment.
38
+ - **Tab / Shift+Tab:** move to the next or previous segment or field.
39
+ - **Arrow Up / Arrow Down:** increment or decrement the focused date segment.
40
+ - **Arrow Left / Arrow Right:** move between date segments.
41
+ - **Page Up / Page Down:** move between months in the calendar popover.
42
+ - **Home / End:** jump to the start or end of the current month.
43
+ - **Escape:** close the calendar popover.
44
+
45
+ ### Localization
46
+
47
+ The date format and the first day of the week follow the user’s locale. You can set the first day of the week explicitly with `firstDayOfWeek`.
48
+
49
+ ### Variations
50
+
51
+ | Variation | Use when |
52
+ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
53
+ | Hidden label | Something on screen already names the field, like a column header. Pass `label` with `hideLabel` so it still has an accessible name. |
54
+ | Required | A date is mandatory to proceed. Consider a description explaining why, and a clear error when it’s missing. |
55
+
56
+ ### Sizes
57
+
58
+ | Size | Use when |
59
+ | -------------- | ------------------------------------------------ |
60
+ | `md` (default) | Standard forms. |
61
+ | `lg` | Prominent inputs that need larger touch targets. |
62
+
63
+ ### State usage
64
+
65
+ - **Invalid:** a required date is missing, the value creates a conflict, or the action fails. Say exactly how to fix it.
66
+ - **Disabled:** the date picker is unavailable. Consider a description explaining why.
67
+ - **Read-only:** use instead of disabled when the value is still relevant to the user’s context.