@adobe/spectrum-design-data 3.3.0-beta.2 → 3.3.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 (136) hide show
  1. package/components/accordion.json +67 -15
  2. package/components/action-bar.json +30 -9
  3. package/components/action-button.json +92 -39
  4. package/components/action-group.json +137 -18
  5. package/components/alert-banner.json +27 -8
  6. package/components/alert-dialog.json +55 -34
  7. package/components/avatar-group.json +35 -9
  8. package/components/avatar.json +105 -29
  9. package/components/badge.json +163 -56
  10. package/components/breadcrumbs.json +107 -26
  11. package/components/button-group.json +63 -19
  12. package/components/button.json +105 -61
  13. package/components/calendar.json +74 -8
  14. package/components/card.json +13 -0
  15. package/components/cards.json +46 -31
  16. package/components/checkbox-group.json +85 -16
  17. package/components/checkbox.json +97 -27
  18. package/components/close-button.json +75 -20
  19. package/components/coach-indicator.json +44 -14
  20. package/components/coach-mark.json +26 -8
  21. package/components/color-area.json +100 -20
  22. package/components/color-handle.json +46 -25
  23. package/components/color-loupe.json +14 -2
  24. package/components/color-slider.json +129 -26
  25. package/components/color-wheel.json +91 -17
  26. package/components/combo-box.json +189 -50
  27. package/components/contextual-help.json +126 -80
  28. package/components/date-field.json +7 -0
  29. package/components/date-picker.json +127 -24
  30. package/components/divider.json +38 -12
  31. package/components/drop-zone.json +37 -18
  32. package/components/field-label.json +62 -21
  33. package/components/heading.json +7 -0
  34. package/components/help-text.json +53 -16
  35. package/components/illustrated-message.json +85 -21
  36. package/components/in-line-alert.json +53 -13
  37. package/components/link.json +63 -24
  38. package/components/list-view.json +80 -15
  39. package/components/menu.json +181 -45
  40. package/components/meter.json +78 -24
  41. package/components/number-field.json +175 -34
  42. package/components/picker.json +188 -42
  43. package/components/popover.json +126 -37
  44. package/components/progress-bar.json +108 -23
  45. package/components/progress-circle.json +55 -12
  46. package/components/radio-button.json +67 -14
  47. package/components/radio-group.json +132 -28
  48. package/components/rating.json +38 -9
  49. package/components/search-field.json +126 -34
  50. package/components/segmented-control.json +70 -21
  51. package/components/select-box.json +103 -29
  52. package/components/side-navigation.json +69 -28
  53. package/components/slider.json +155 -39
  54. package/components/standard-dialog.json +88 -16
  55. package/components/status-light.json +136 -41
  56. package/components/steplist.json +24 -5
  57. package/components/swatch-group.json +55 -19
  58. package/components/swatch.json +79 -24
  59. package/components/switch.json +79 -31
  60. package/components/table.json +73 -26
  61. package/components/tabs.json +52 -22
  62. package/components/tag-field.json +60 -14
  63. package/components/tag-group.json +56 -16
  64. package/components/tag.json +78 -21
  65. package/components/takeover-dialog.json +61 -10
  66. package/components/text-area.json +205 -49
  67. package/components/text-field.json +170 -42
  68. package/components/thumbnail.json +63 -22
  69. package/components/time-field.json +7 -0
  70. package/components/toast.json +50 -29
  71. package/components/tooltip.json +87 -27
  72. package/components/tree-view.json +147 -45
  73. package/components/user-card.json +7 -0
  74. package/guidelines/app-frame-overview.json +44 -46
  75. package/guidelines/attention-hierarchy.json +22 -13
  76. package/guidelines/background-layers.json +10 -80
  77. package/guidelines/brand.json +12 -32
  78. package/guidelines/colors.json +17 -47
  79. package/guidelines/developer-overview.json +9 -25
  80. package/guidelines/faqs.json +9 -96
  81. package/guidelines/fonts.json +14 -29
  82. package/guidelines/grays.json +44 -17
  83. package/guidelines/icon-fundamentals.json +18 -7
  84. package/guidelines/manifest.json +15 -367
  85. package/guidelines/motion.json +16 -17
  86. package/guidelines/principles.json +8 -7
  87. package/guidelines/resources.json +15 -21
  88. package/guidelines/states.json +11 -16
  89. package/guidelines/using-icons.json +44 -33
  90. package/package.json +2 -2
  91. package/registry/platform-implementations.json +30 -0
  92. package/guidelines/ai-resource-guide.json +0 -50
  93. package/guidelines/applying-the-type-system.json +0 -67
  94. package/guidelines/bi-directionality.json +0 -57
  95. package/guidelines/border-width.json +0 -58
  96. package/guidelines/cognitive.json +0 -197
  97. package/guidelines/component-spacing.json +0 -61
  98. package/guidelines/contact-us.json +0 -67
  99. package/guidelines/content-area-browsing-context.json +0 -65
  100. package/guidelines/content-design-grammar-and-mechanics.json +0 -241
  101. package/guidelines/content-design-voice-and-tone.json +0 -37
  102. package/guidelines/content-grammar-and-mechanics.json +0 -252
  103. package/guidelines/content-language-and-inclusivity-writing-about-people.json +0 -103
  104. package/guidelines/content-language-and-inclusivity-writing-with-visuals.json +0 -70
  105. package/guidelines/content-voice-and-tone.json +0 -47
  106. package/guidelines/creating-bluelines-browsing-context.json +0 -91
  107. package/guidelines/design-tokens.json +0 -158
  108. package/guidelines/drop-shadow.json +0 -68
  109. package/guidelines/grammar-and-mechanics.json +0 -252
  110. package/guidelines/header-browsing-context.json +0 -40
  111. package/guidelines/illustration.json +0 -105
  112. package/guidelines/in-product-word-list.json +0 -29
  113. package/guidelines/inclusive-design.json +0 -101
  114. package/guidelines/inclusive-ux-writing.json +0 -30
  115. package/guidelines/internationalization.json +0 -87
  116. package/guidelines/language-and-inclusivity-writing-about-people.json +0 -85
  117. package/guidelines/language-and-inclusivity-writing-with-visuals.json +0 -61
  118. package/guidelines/layout-and-structure-containers.json +0 -47
  119. package/guidelines/layout-and-structure-spacing-overview.json +0 -66
  120. package/guidelines/layout-spacing.json +0 -39
  121. package/guidelines/object-styles-overview.json +0 -17
  122. package/guidelines/rounding.json +0 -73
  123. package/guidelines/side-navigation-browsing-context.json +0 -74
  124. package/guidelines/spacing-overview.json +0 -45
  125. package/guidelines/support.json +0 -113
  126. package/guidelines/typography-overview.json +0 -43
  127. package/guidelines/typography-system.json +0 -208
  128. package/guidelines/visual-language-containers.json +0 -36
  129. package/guidelines/voice-and-tone.json +0 -47
  130. package/guidelines/whats-new.json +0 -32
  131. package/guidelines/writing-about-people.json +0 -103
  132. package/guidelines/writing-for-errors.json +0 -120
  133. package/guidelines/writing-for-onboarding.json +0 -119
  134. package/guidelines/writing-for-readability.json +0 -54
  135. package/guidelines/writing-with-visuals.json +0 -70
  136. package/registry/platform-extensions/web-components-states.json +0 -58
@@ -9,6 +9,13 @@
9
9
  "category": "inputs",
10
10
  "documentationUrl": "https://spectrum.adobe.com/page/radio-group/"
11
11
  },
12
+ "implementations": [
13
+ {
14
+ "platform": "web",
15
+ "componentName": "RadioGroup",
16
+ "package": "@react-spectrum/s2"
17
+ }
18
+ ],
12
19
  "documentBlocks": [
13
20
  {
14
21
  "type": "purpose",
@@ -16,90 +23,187 @@
16
23
  },
17
24
  {
18
25
  "type": "guideline",
19
- "content": "Keyboard focus.\n\nA radio button can be navigated using a keyboard. The keyboard focus state takes the radio button's visual hover state and adds a blue ring to the radio button in focus."
26
+ "content": "Radio groups organize related radio buttons into a single selection set. Only one option can be selected at a time."
27
+ },
28
+ {
29
+ "type": "guideline",
30
+ "content": "Radio groups should use help text for error messaging and descriptions. Descriptions are valuable for giving context behind why a selection is required, or for clarifying the options."
31
+ },
32
+ {
33
+ "type": "guideline",
34
+ "content": "Radio groups can be marked as having an error to show that a selection needs to be made in order to move forward, or that a selection that was made is invalid. The error is indicated with negative help text, along with an icon."
35
+ },
36
+ {
37
+ "type": "guideline",
38
+ "content": "A radio group in a disabled state shows that a selection exists, but is not available in that circumstance. This can be used to maintain layout continuity and communicate that an action may become available later. The field label, radio buttons, and help text are all displayed in a disabled state when the radio group is disabled."
39
+ },
40
+ {
41
+ "type": "guideline",
42
+ "content": "Radio groups can be marked as optional or required, depending on the situation. For required radio groups, there are two styling options: a “(required)” label or an asterisk. If you use an asterisk, be sure to include help text to explain what the asterisk means. Optional radio groups are either denoted with text added to the end of the label — “(optional)” — or have no indication at all."
43
+ },
44
+ {
45
+ "type": "guideline",
46
+ "content": "The asterisk used in this component is an icon that has specific spacing from the label text — not part of the label text itself."
47
+ },
48
+ {
49
+ "type": "guideline",
50
+ "content": "By default, radio buttons are not emphasized (gray). This option is best for when the radio button is not the core part of an interface, such as in application panels, where all visual components are monochrome in order to direct focus to the content."
51
+ },
52
+ {
53
+ "type": "guideline",
54
+ "content": "The emphasized (blue) version provides a visual prominence that is best for forms, settings, lists or grids of assets, and other situations where a radio button needs to be noticed."
20
55
  },
21
56
  {
22
57
  "type": "guideline",
23
- "content": "Text overflow.\n\nWhen the label is too long for the horizontal space available, it wraps to form another line."
58
+ "content": "Radio groups come in four different sizes: small, medium, large, and extra-large. The medium size is the default and most frequently used option. Use the other sizes sparingly; they should be used to create a hierarchy of importance within the page."
24
59
  },
25
60
  {
26
61
  "type": "guideline",
27
- "content": "Mixed value.\n\nWhen a radio button group presents multiple values that are not identical, the group should not show a selection. Any subsequent selection should update all values."
62
+ "content": "Radio groups can be either horizontal or vertical. By default, radio groups are vertical. Use a horizontal radio group when vertical space is limited."
28
63
  },
29
64
  {
30
65
  "type": "guideline",
31
- "content": "When to use an emphasized radio group?\n\nEmphasized radio group is optimal for forms, settings, and other scenarios where the radio group need to be noticed. Default radio group is optimal for application panels where all the visual components are monochrome in order to direct focus to the canvas."
66
+ "content": "Labels can be placed either on top or on the side. Top labels are the default and are recommended because they work better with long copy, localization, and responsive layouts. Side labels are most useful when vertical space is limited."
32
67
  },
33
68
  {
34
69
  "type": "guideline",
35
- "content": "Use radio buttons for mutually exclusive options.\n\nRadio buttons and checkboxes are not interchangeable. Radio buttons are best used for selecting a single option from a list of mutually exclusive options. Checkboxes are best used for selecting multiple options at once (or no options)."
70
+ "content": "Radio groups should always have a label. In rare cases where context is sufficient and an accessibility expert has reviewed the design, the label could be undefined. These radio groups without a visible label should still include an aria-label in HTML (depending on the context, “aria-label” or “aria-labelledby”)."
36
71
  },
37
72
  {
38
73
  "type": "guideline",
39
- "content": "Always label radio groups.\n\nRadio groups should always have a label that clearly describes what the list of options represents. This is important for accessibility, since a screen reader will read the label before each option. Make sure to include a label, and don't assume that the options are self-explanatory without one. Write the label in sentence case."
74
+ "content": "A radio button can be navigated using a keyboard. The keyboard focus state takes the radio button’s visual hover state and adds a blue ring to the radio button in focus."
40
75
  },
41
76
  {
42
77
  "type": "guideline",
43
- "content": "Radio group, switch, or checkbox?\n\nRadio buttons are best when only one option can be selected at a time from a set (e.g., choosing one preference or mode). Switches are best for communicating activation (e.g., turning a setting on or off). Checkboxes are best for communicating selection (e.g., selecting multiple items from a list)."
78
+ "content": "When the label is too long for the horizontal space available, it wraps to form another line."
44
79
  },
45
80
  {
46
81
  "type": "guideline",
47
- "content": "RTL.\n\nFor RTL (right-to-left) languages, the layout of the radio group (and its components) is mirrored. The radio buttons and icons are placed on the right side of the text, and text is aligned to the right."
82
+ "content": "When a radio button group presents multiple values that are not identical, the group should not show a selection. Any subsequent selection should update all values."
48
83
  },
49
84
  {
50
85
  "type": "guideline",
51
- "content": "Keyboard interactions.\n\nKey Interaction TabMoves focus onto or off of the button.Space or EnterExecutes the button action. The focus remains on the button except if the button opens or closes the current container. In this case, the focus moves to the target or back to the caller."
86
+ "content": "Emphasized radio group is optimal for forms, settings, and other scenarios where the radio group need to be noticed. Default radio group is optimal for application panels where all the visual components are monochrome in order to direct focus to the canvas."
52
87
  },
53
88
  {
54
89
  "type": "guideline",
55
- "content": "Cursor guidelines.\n\nCursor Usage PointerUse the pointer cursor for all interactive components."
90
+ "content": "Radio buttons and checkboxes are not interchangeable. Radio buttons are best used for selecting a single option from a list of mutually exclusive options. Checkboxes are best used for selecting multiple options at once (or no options)."
56
91
  },
57
92
  {
58
93
  "type": "guideline",
59
- "content": "WCAG 2.2 compliance.\n\nAny criterion not mention in the below table are not applicable to this component or are resolved with underlying requirements, engineering, and styles of the entire system. 1. Perceivable Requirement Criterion Level Compliance Non-text content 1.1.1 ANon‑text elements—such as icons used in buttons—must provide a text alternative that communicates the button’s purpose. All buttons, especially icon‑only buttons, need an accessible name (for example, via a title, aria‑label, or associated text) so screen readers can announce their function.Info and relationships, Identify purpose 1.3.1, 1.3.6 A, AAAButtons should be understandable by assistive technologies like screen readers. This means using the proper semantic HTML or ARIA role of buttons should be utilized.Use of color 1.4.1 AColor is never used as the sole way to convey meaning in buttons. While negative buttons do use red to reinforce their purpose, every button also includes a clear text label that communicates the action it performs.Text contrast minimums 1.4.3 AALarge text has a contrast ratio of at least 3:1, and small text has a contrast ratio of at least 4.5:1. Incidental text such as disabled, hidden, or decorative text has no contrast requirement.Resize text 1.4.4 AAButtons should be built in such a way that they can be resized without assistive technology up to 200%.Visual presentation 1.4.8 AAAThe width of text blocks is no more than 80 characters (40 for CJK languages), and text is never justified.Non-text contrast 1.4.11 AAThe visual presentation of icons and various states have a contrast ratio of at least 3:1.Text spacing 1.4.12 AALine height of text is at least 1.5x the font size. 2. Operable Requirement Criterion Level Compliance Keyboard 2.1.1, 2.1.3 A, AAAAll functionality of the component is operable through a keyboard without specific timing for keystrokes.Keyboard traps 2.1.2 AFocus can be moved away from the component using only a keyboard.Seizures and physical reactions 2.3.1, 2.3.2, 2.3.3 A, AAA, AAAThere is no flashing content or unnecessary motion or animation in this component.Focus order 2.4.3 ANavigation sequences receive focus in an order that preserves meaning and operability.Focus visible 2.4.7 AAKeyboard states use an indicator that is visible with at least 3:1 contrast."
94
+ "content": "Radio groups should always have a label that clearly describes what the list of options represents. This is important for accessibility, since a screen reader will read the label before each option. Make sure to include a label, and don't assume that the options are self-explanatory without one. Write the label in sentence case."
95
+ },
96
+ {
97
+ "type": "guideline",
98
+ "content": "Radio buttons are best when only one option can be selected at a time from a set (e.g., choosing one preference or mode)."
99
+ },
100
+ {
101
+ "type": "guideline",
102
+ "content": "Switches are best for communicating activation (e.g., turning a setting on or off)."
103
+ },
104
+ {
105
+ "type": "guideline",
106
+ "content": "Checkboxes are best for communicating selection (e.g., selecting multiple items from a list)."
60
107
  }
61
108
  ],
62
109
  "options": {
63
- "label": { "type": "string" },
110
+ "label": {
111
+ "type": "string"
112
+ },
64
113
  "labelPosition": {
65
114
  "type": "string",
66
115
  "default": "top",
67
- "values": [{ "value": "top" }, { "value": "side" }]
116
+ "values": [
117
+ {
118
+ "value": "top"
119
+ },
120
+ {
121
+ "value": "side"
122
+ }
123
+ ]
68
124
  },
69
125
  "orientation": {
70
126
  "type": "string",
71
127
  "default": "vertical",
72
- "values": [{ "value": "horizontal" }, { "value": "vertical" }]
128
+ "values": [
129
+ {
130
+ "value": "horizontal"
131
+ },
132
+ {
133
+ "value": "vertical"
134
+ }
135
+ ]
73
136
  },
74
137
  "size": {
75
138
  "type": "string",
76
139
  "default": "m",
77
140
  "values": [
78
- { "value": "s" },
79
- { "value": "m" },
80
- { "value": "l" },
81
- { "value": "xl" }
141
+ {
142
+ "value": "s"
143
+ },
144
+ {
145
+ "value": "m"
146
+ },
147
+ {
148
+ "value": "l"
149
+ },
150
+ {
151
+ "value": "xl"
152
+ }
82
153
  ]
83
154
  },
84
- "isEmphasized": { "type": "boolean", "default": false },
155
+ "isEmphasized": {
156
+ "type": "boolean",
157
+ "default": false
158
+ },
85
159
  "necessityIndicator": {
86
160
  "type": "string",
87
161
  "default": "icon",
88
- "values": [{ "value": "text" }, { "value": "icon" }]
162
+ "values": [
163
+ {
164
+ "value": "text"
165
+ },
166
+ {
167
+ "value": "icon"
168
+ }
169
+ ]
170
+ },
171
+ "isRequired": {
172
+ "type": "boolean",
173
+ "default": false
89
174
  },
90
- "isRequired": { "type": "boolean", "default": false },
91
- "isError": { "type": "boolean", "default": false },
92
- "isDisabled": { "type": "boolean", "default": false },
93
- "errorMessage": { "type": "string" },
94
- "description": { "type": "string" }
175
+ "isError": {
176
+ "type": "boolean",
177
+ "default": false
178
+ },
179
+ "isDisabled": {
180
+ "type": "boolean",
181
+ "default": false
182
+ },
183
+ "errorMessage": {
184
+ "type": "string"
185
+ },
186
+ "description": {
187
+ "type": "string"
188
+ }
189
+ },
190
+ "lifecycle": {
191
+ "introduced": "1.0.0-draft"
95
192
  },
96
- "lifecycle": { "introduced": "1.0.0-draft" },
97
193
  "accessibility": {
98
194
  "intents": ["choose"],
99
195
  "focusable": false,
100
196
  "wcag": [
101
- { "criterion": "1.3.1", "level": "A", "title": "Info and Relationships" },
102
- { "criterion": "4.1.2", "level": "A", "title": "Name, Role, Value" }
197
+ {
198
+ "criterion": "1.3.1",
199
+ "level": "A",
200
+ "title": "Info and Relationships"
201
+ },
202
+ {
203
+ "criterion": "4.1.2",
204
+ "level": "A",
205
+ "title": "Name, Role, Value"
206
+ }
103
207
  ]
104
208
  }
105
209
  }
@@ -68,24 +68,53 @@
68
68
  "multipleOf": 0.5,
69
69
  "description": "From 0 to 5, can be a decimal to represent half stars"
70
70
  },
71
- "isEmphasized": { "type": "boolean", "default": false },
72
- "isDisabled": { "type": "boolean", "default": false }
71
+ "isEmphasized": {
72
+ "type": "boolean",
73
+ "default": false
74
+ },
75
+ "isDisabled": {
76
+ "type": "boolean",
77
+ "default": false
78
+ }
73
79
  },
74
80
  "states": [
75
- { "name": "hover", "trigger": "interaction" },
76
- { "name": "down", "trigger": "interaction" },
77
- { "name": "keyboard-focus", "trigger": "interaction" }
81
+ {
82
+ "name": "hover",
83
+ "trigger": "interaction"
84
+ },
85
+ {
86
+ "name": "down",
87
+ "trigger": "interaction"
88
+ },
89
+ {
90
+ "name": "keyboard-focus",
91
+ "trigger": "interaction"
92
+ }
78
93
  ],
79
- "lifecycle": { "introduced": "1.0.0-draft" },
94
+ "lifecycle": {
95
+ "introduced": "1.0.0-draft"
96
+ },
80
97
  "accessibility": {
81
98
  "role": "slider",
82
99
  "intents": ["choose"],
83
100
  "focusable": true,
84
101
  "keyboardIntents": ["increment", "decrement"],
85
102
  "wcag": [
86
- { "criterion": "1.3.1", "level": "A", "title": "Info and Relationships" },
87
- { "criterion": "2.1.1", "level": "A", "title": "Keyboard" },
88
- { "criterion": "4.1.2", "level": "A", "title": "Name, Role, Value" }
103
+ {
104
+ "criterion": "1.3.1",
105
+ "level": "A",
106
+ "title": "Info and Relationships"
107
+ },
108
+ {
109
+ "criterion": "2.1.1",
110
+ "level": "A",
111
+ "title": "Keyboard"
112
+ },
113
+ {
114
+ "criterion": "4.1.2",
115
+ "level": "A",
116
+ "title": "Name, Role, Value"
117
+ }
89
118
  ]
90
119
  }
91
120
  }
@@ -9,6 +9,13 @@
9
9
  "category": "inputs",
10
10
  "documentationUrl": "https://spectrum.adobe.com/page/search-field/"
11
11
  },
12
+ "implementations": [
13
+ {
14
+ "platform": "web",
15
+ "componentName": "SearchField",
16
+ "package": "@react-spectrum/s2"
17
+ }
18
+ ],
12
19
  "documentBlocks": [
13
20
  {
14
21
  "type": "purpose",
@@ -16,106 +23,191 @@
16
23
  },
17
24
  {
18
25
  "type": "guideline",
19
- "content": "Minimum width.\n\nThe minimum width for a search field is 3× the height of the field, for both standard and quiet style. This minimum width guarantees that small search fields are readable and easy to target on touch devices."
26
+ "content": "Search fields enable finding or filtering items based on text input."
27
+ },
28
+ {
29
+ "type": "guideline",
30
+ "content": "A search field should include a label and a search icon. In the default state before a search term is input, the label is in regular body text style to meet contrast ratios and to show that this is a field label, not placeholder text. When no visible label is present, the input must still expose an accessible name (for example, in HTML via “aria-label” or “aria-labelledby,” and on other platforms via the platform’s accessible-name mechanism)."
31
+ },
32
+ {
33
+ "type": "guideline",
34
+ "content": "The value shows a user’s entered text in regular body text style."
35
+ },
36
+ {
37
+ "type": "guideline",
38
+ "content": "The width of a search field can be customized appropriately for its context."
39
+ },
40
+ {
41
+ "type": "guideline",
42
+ "content": "Search fields come in four different sizes: small, medium, large, and extra-large. The medium size is the default and most frequently used option. Use the other sizes sparingly; they should be used to create a hierarchy of importance within the page."
43
+ },
44
+ {
45
+ "type": "guideline",
46
+ "content": "A search field can have help text below the field to give extra context or instruction about what a user should input. The description communicates a hint or helpful information, such as a search’s scope."
47
+ },
48
+ {
49
+ "type": "guideline",
50
+ "content": "Placeholder text provides hints about expected input values."
51
+ },
52
+ {
53
+ "type": "guideline",
54
+ "content": "A search field in a disabled state shows that a search option exists, but is not available in that circumstance. This can be used to maintain layout continuity and communicate that it may become available later."
55
+ },
56
+ {
57
+ "type": "guideline",
58
+ "content": "The minimum width for a search field is 3× the height of the field, for both standard and quiet style. This minimum width guarantees that small search fields are readable and easy to target on touch devices."
20
59
  },
21
60
  {
22
61
  "type": "guideline",
23
- "content": "Text overflow.\n\nWhen the entered text is too long for the available horizontal space in the field, the text truncates."
62
+ "content": "When the entered text is too long for the available horizontal space in the field, the text truncates."
24
63
  },
25
64
  {
26
65
  "type": "guideline",
27
- "content": "Help text overflow.\n\nWhen the help text is too long for the available horizontal space, it wraps to form another line."
66
+ "content": "When the help text is too long for the available horizontal space, it wraps to form another line."
28
67
  },
29
68
  {
30
69
  "type": "guideline",
31
- "content": "Keyboard focus.\n\nA search field can be navigated using a keyboard. The keyboard focus state takes the field's visual hover state and adds a blue ring to the field in focus."
70
+ "content": "A search field can be navigated using a keyboard. The keyboard focus state takes the field’s visual hover state and adds a blue ring to the field in focus."
32
71
  },
33
72
  {
34
73
  "type": "guideline",
35
- "content": "In-field button.\n\nThe in-field button offers an option to clear any input search term. If search results are being shown in a menu or popover, selecting this button will close the menu and clear the field. If a search term has been entered and the results have appeared, selecting this will only clear the field and not affect the list of results."
74
+ "content": "The in-field button offers an option to clear any input search term."
36
75
  },
37
76
  {
38
77
  "type": "guideline",
39
- "content": "Show a \"No results\" state instead of an error.\n\nSearch fields do not have an error state. Search functionality should anticipate spelling mistakes in search queries, and accommodate multiple spellings of words in search results — not treating any search term as an error. Instead of showing an error, show a \"No results\" page or a section with any suggestions for how to get results to appear."
78
+ "content": "If search results are being shown in a menu or popover, selecting this button will close the menu and clear the field. If a search term has been entered and the results have appeared, selecting this will only clear the field and not affect the list of results."
40
79
  },
41
80
  {
42
81
  "type": "guideline",
43
- "content": "Searching versus filtering.\n\nIn a searching scenario, a user inputs a search term for a specific thing they're looking for. In a filtering scenario, a user generally knows what they're looking for, but may not have a specific thing in mind. The search field can be used for both of these contexts. For a search experience, use the search field as-is. For a filtering experience, add a filter icon next to the search field, where a user can narrow down their search results before (or instead of) searching using a specific term. Filters can appear below the search field as tags."
82
+ "content": "Search fields do not have an error state. Search functionality should anticipate spelling mistakes in search queries, and accommodate multiple spellings of words in search results — not treating any search term as an error."
44
83
  },
45
84
  {
46
85
  "type": "guideline",
47
- "content": "Searching within a category.\n\nCreate a scoped search by pairing a search field with a picker component. Add a picker (either quiet or standard style) where a user can select a topic or category that they would like to search within. It's helpful to also update the search field label to communicate what the user is searching within. Spectrum previously had a specific \"search within\" component that would allow a user to filter down a search field category before searching for a particular term. It was deprecated because it did not meet accessibility and localization requirements."
86
+ "content": "Instead of showing an error, show a “No results” page or a section with any suggestions for how to get results to appear."
48
87
  },
49
88
  {
50
89
  "type": "guideline",
51
- "content": "Include a label.\n\nAny search field should include a label inside the field, in the default state. The default label text is Search, but this can be customized to be more specific for use cases like scoped search, wayfinding, or building context — acting like a prompt for a user to search more specifically. Keep in mind that once a search term is entered the label text is no longer viewable. Use help text to show search formatting examples or give hints about what to input. It can be distracting or redundant if the search field label and its help text are both communicating the same thing, so write these thoughtfully."
90
+ "content": "In a searching scenario, a user inputs a search term for a specific thing they’re looking for. In a filtering scenario, a user generally knows what they’re looking for, but may not have a specific thing in mind."
52
91
  },
53
92
  {
54
93
  "type": "guideline",
55
- "content": "Follow capitalization rules.\n\nThe label within the search field should be in sentence case, following Spectrum's UX writing standards for capitalization."
94
+ "content": "The search field can be used for both of these contexts. For a search experience, use the search field as-is. For a filtering experience, add a filter icon next to the search field, where a user can narrow down their search results before (or instead of) searching using a specific term. Filters can appear below the search field as tags."
56
95
  },
57
96
  {
58
97
  "type": "guideline",
59
- "content": "RTL.\n\nIn right‑to‑left languages, the search‑field layout is mirrored. The icon and label are right‑aligned, and the in‑field button is left‑aligned. Keep in mind that some content, such as email addresses, does not change direction or translate. The magnifying‑glass icon itself is not mirrored. The handle stays on the right side because it represents holding the object, and most people worldwide are right‑handed."
98
+ "content": "Spectrum previously had a specific “search within” component that would allow a user to filter down a search field category before searching for a particular term. It was deprecated because it did not meet accessibility and localization requirements."
60
99
  },
61
100
  {
62
101
  "type": "guideline",
63
- "content": "Keyboard interactions.\n\nKey Interaction TabMoves focus onto or off of the button.Space or EnterExecutes the button action. The focus remains on the button except if the button opens or closes the current container. In this case, the focus moves to the target or back to the caller."
102
+ "content": "Any search field should include a label inside the field, in the default state. The default label text is Search, but this can be customized to be more specific for use cases like scoped search, wayfinding, or building context — acting like a prompt for a user to search more specifically."
64
103
  },
65
104
  {
66
105
  "type": "guideline",
67
- "content": "Cursor guidelines.\n\nCursor Usage PointerUse the pointer cursor for all interactive components."
106
+ "content": "Keep in mind that once a search term is entered the label text is no longer viewable. Use help text to show search formatting examples or give hints about what to input. It can be distracting or redundant if the search field label and its help text are both communicating the same thing, so write these thoughtfully."
68
107
  },
69
108
  {
70
109
  "type": "guideline",
71
- "content": "WCAG 2.2 compliance.\n\nAny criterion not mention in the below table are not applicable to this component or are resolved with underlying requirements, engineering, and styles of the entire system. 1. Perceivable Requirement Criterion Level Compliance Non-text content 1.1.1 ANon‑text elements—such as icons used in buttons—must provide a text alternative that communicates the button’s purpose. All buttons, especially icon‑only buttons, need an accessible name (for example, via a title, aria‑label, or associated text) so screen readers can announce their function.Info and relationships, Identify purpose 1.3.1, 1.3.6 A, AAAButtons should be understandable by assistive technologies like screen readers. This means using the proper semantic HTML or ARIA role of buttons should be utilized.Use of color 1.4.1 AColor is never used as the sole way to convey meaning in buttons. While negative buttons do use red to reinforce their purpose, every button also includes a clear text label that communicates the action it performs.Text contrast minimums 1.4.3 AALarge text has a contrast ratio of at least 3:1, and small text has a contrast ratio of at least 4.5:1. Incidental text such as disabled, hidden, or decorative text has no contrast requirement.Resize text 1.4.4 AAButtons should be built in such a way that they can be resized without assistive technology up to 200%.Visual presentation 1.4.8 AAAThe width of text blocks is no more than 80 characters (40 for CJK languages), and text is never justified.Non-text contrast 1.4.11 AAThe visual presentation of icons and various states have a contrast ratio of at least 3:1.Text spacing 1.4.12 AALine height of text is at least 1.5x the font size. 2. Operable Requirement Criterion Level Compliance Keyboard 2.1.1, 2.1.3 A, AAAAll functionality of the component is operable through a keyboard without specific timing for keystrokes.Keyboard traps 2.1.2 AFocus can be moved away from the component using only a keyboard.Seizures and physical reactions 2.3.1, 2.3.2, 2.3.3 A, AAA, AAAThere is no flashing content or unnecessary motion or animation in this component.Focus order 2.4.3 ANavigation sequences receive focus in an order that preserves meaning and operability.Focus visible 2.4.7 AAKeyboard states use an indicator that is visible with at least 3:1 contrast."
110
+ "content": "The label within the search field should be in sentence case, following Spectrum’s UX writing standards for capitalization."
72
111
  }
73
112
  ],
74
113
  "options": {
75
- "label": { "type": "string" },
76
- "hideLabel": { "type": "boolean", "default": false },
114
+ "label": {
115
+ "type": "string"
116
+ },
117
+ "hideLabel": {
118
+ "type": "boolean",
119
+ "default": false
120
+ },
77
121
  "icon": {
78
122
  "$ref": "https://opensource.adobe.com/spectrum-design-data/schemas/types/workflow-icon.json",
79
123
  "description": "Icon must be present if the label is not defined."
80
124
  },
81
- "value": { "type": "string" },
82
- "width": { "type": "number" },
125
+ "value": {
126
+ "type": "string"
127
+ },
128
+ "width": {
129
+ "type": "number"
130
+ },
83
131
  "size": {
84
132
  "type": "string",
85
133
  "default": "m",
86
134
  "pattern": "^(x?s|m|x{0,3}l)$",
87
135
  "values": [
88
- { "value": "s" },
89
- { "value": "m" },
90
- { "value": "l" },
91
- { "value": "xl" }
136
+ {
137
+ "value": "s"
138
+ },
139
+ {
140
+ "value": "m"
141
+ },
142
+ {
143
+ "value": "l"
144
+ },
145
+ {
146
+ "value": "xl"
147
+ }
92
148
  ]
93
149
  },
94
- "helpText": { "type": "string" },
95
- "placeholder": { "type": "string" },
96
- "isDisabled": { "type": "boolean", "default": false }
150
+ "helpText": {
151
+ "type": "string"
152
+ },
153
+ "placeholder": {
154
+ "type": "string"
155
+ },
156
+ "isDisabled": {
157
+ "type": "boolean",
158
+ "default": false
159
+ }
97
160
  },
98
161
  "states": [
99
- { "name": "down", "trigger": "interaction" },
100
- { "name": "hover", "trigger": "interaction" },
101
- { "name": "focus-+-hover", "trigger": "prop" },
102
- { "name": "focus-+-not-hover", "trigger": "prop" },
103
- { "name": "keyboard-focus", "trigger": "interaction" }
162
+ {
163
+ "name": "down",
164
+ "trigger": "interaction"
165
+ },
166
+ {
167
+ "name": "hover",
168
+ "trigger": "interaction"
169
+ },
170
+ {
171
+ "name": "focus-+-hover",
172
+ "trigger": "prop"
173
+ },
174
+ {
175
+ "name": "focus-+-not-hover",
176
+ "trigger": "prop"
177
+ },
178
+ {
179
+ "name": "keyboard-focus",
180
+ "trigger": "interaction"
181
+ }
104
182
  ],
105
- "lifecycle": { "introduced": "1.0.0-draft" },
183
+ "lifecycle": {
184
+ "introduced": "1.0.0-draft"
185
+ },
106
186
  "accessibility": {
107
187
  "role": "textbox",
108
188
  "intents": ["input"],
109
189
  "focusable": true,
110
190
  "wcag": [
111
- { "criterion": "1.3.1", "level": "A", "title": "Info and Relationships" },
191
+ {
192
+ "criterion": "1.3.1",
193
+ "level": "A",
194
+ "title": "Info and Relationships"
195
+ },
112
196
  {
113
197
  "criterion": "1.3.5",
114
198
  "level": "AA",
115
199
  "title": "Identify Input Purpose"
116
200
  },
117
- { "criterion": "2.1.1", "level": "A", "title": "Keyboard" },
118
- { "criterion": "4.1.2", "level": "A", "title": "Name, Role, Value" }
201
+ {
202
+ "criterion": "2.1.1",
203
+ "level": "A",
204
+ "title": "Keyboard"
205
+ },
206
+ {
207
+ "criterion": "4.1.2",
208
+ "level": "A",
209
+ "title": "Name, Role, Value"
210
+ }
119
211
  ]
120
212
  }
121
213
  }