From 54bf4709386d6b6e2f553f7bf5ab1dd9ea95669c Mon Sep 17 00:00:00 2001 From: Cee Chen <549407+cee-chen@users.noreply.github.com> Date: Thu, 31 Oct 2024 08:52:35 -0700 Subject: [PATCH] [EUI+] Polish pass on all docs callouts (#8107) --- .../src/components/call_out/index.tsx | 2 ++ .../docs/components/display/aspect_ratio.mdx | 2 -- .../website/docs/components/display/badge.mdx | 2 +- .../website/docs/components/display/card.mdx | 20 ++++------------ .../docs/components/display/comment_list.mdx | 6 ++--- .../docs/components/display/drag_and_drop.mdx | 6 ++--- .../components/display/icons/overview.mdx | 6 ++--- .../website/docs/components/display/image.mdx | 2 +- .../docs/components/display/progress.mdx | 4 ++-- .../docs/components/display/skeleton.mdx | 6 +---- .../website/docs/components/display/text.mdx | 8 ++----- .../docs/components/display/timeline.mdx | 4 +--- .../docs/components/display/tour/overview.mdx | 4 +--- .../components/editors_and_syntax/code.mdx | 4 +--- .../elastic_charts/accessibility_features.mdx | 6 +---- .../elastic_charts/metric_chart.mdx | 2 -- .../docs/components/forms/combo_box.mdx | 8 ++----- .../components/forms/compressed_forms.mdx | 8 ++----- .../docs/components/forms/date_picker.mdx | 2 -- .../forms/form_controls/overview.mdx | 8 +++---- .../docs/components/forms/range_sliders.mdx | 6 ++--- .../docs/components/forms/selectable.mdx | 10 ++++---- .../forms/selection_controls/overview.mdx | 10 +++----- .../docs/components/forms/super_select.mdx | 2 +- .../components/guidelines/accessibility.mdx | 10 +++----- .../guidelines/writing/guidelines.mdx | 7 +++--- .../docs/components/layout/accordion.mdx | 8 ++----- .../docs/components/layout/bottom_bar.mdx | 4 +--- .../website/docs/components/layout/flyout.mdx | 6 +---- .../layout/page_components/overview.mdx | 4 +--- .../docs/components/layout/popover.mdx | 8 ++----- .../components/layout/resizable_container.mdx | 6 ++--- .../components/navigation/breadcrumbs.mdx | 12 ++++------ .../components/navigation/button/overview.mdx | 12 +++------- .../components/navigation/collapsible_nav.mdx | 4 +--- .../components/navigation/context_menu.mdx | 6 ++--- .../components/navigation/key_pad_menu.mdx | 4 +--- .../navigation/pagination/overview.mdx | 6 ++--- .../docs/components/navigation/side_nav.mdx | 2 -- .../docs/components/navigation/tree_view.mdx | 6 ++--- .../components/tabular_content/data_grid.mdx | 4 +--- .../tabular_content/data_grid_advanced.mdx | 21 ++++------------- .../data_grid_cells_and_popovers.mdx | 23 +++++-------------- .../tabular_content/in_memory_tables.mdx | 6 +++-- .../components/tabular_content/tables.mdx | 2 +- .../templates/page_template/overview.mdx | 8 ++----- .../components/templates/sitewide_search.mdx | 2 -- .../templates/super_date_picker.mdx | 2 -- 48 files changed, 93 insertions(+), 218 deletions(-) diff --git a/packages/docusaurus-theme/src/components/call_out/index.tsx b/packages/docusaurus-theme/src/components/call_out/index.tsx index 2fecf2d1bd7..4a651aaf18b 100644 --- a/packages/docusaurus-theme/src/components/call_out/index.tsx +++ b/packages/docusaurus-theme/src/components/call_out/index.tsx @@ -43,6 +43,8 @@ const getStyles = (theme: UseEuiTheme, variant: VARIANTS) => { return { note: css` + margin-block-start: var(--eui-theme-content-vertical-spacing); + &:not(:last-child) { margin-block-end: ${euiTheme.size.xl}; } diff --git a/packages/website/docs/components/display/aspect_ratio.mdx b/packages/website/docs/components/display/aspect_ratio.mdx index 32174114187..cd9552a0b4d 100644 --- a/packages/website/docs/components/display/aspect_ratio.mdx +++ b/packages/website/docs/components/display/aspect_ratio.mdx @@ -6,9 +6,7 @@ id: display_aspect_ratio # Aspect ratio :::warning - In some cases, aspect ratio sizing may not be supported by the embed. This component will only work with ones that do, like YouTube. - ::: **EuiAspectRatio** provides a way to responsively resize a single block level child element to a specificied ratio. This is useful for things like YouTube iframes or other embeds that initially have a fixed size. If you need something similar for images, take a look at CSS's [object-fit property](https://www.w3schools.com/css/css3_object-fit.asp). diff --git a/packages/website/docs/components/display/badge.mdx b/packages/website/docs/components/display/badge.mdx index f5edb6d71b3..e6491e6455f 100644 --- a/packages/website/docs/components/display/badge.mdx +++ b/packages/website/docs/components/display/badge.mdx @@ -131,7 +131,7 @@ export default () => ( Badges can have `onClick` events applied to the badge itself or the icon within the badge. The latter option is useful for when you might use badges in other components (like a tag system with autocomplete where you need close events). -:::note onClick with iconOnClick +:::note `onClick` with `iconOnClick` When providing both these click handlers, **EuiBadge** must alter the contents so that it does not contain nested button tags. Please make note that if you provide props other than those explicit to **EuiBadge**, they will always be applied to the main `button` tag which may be inside of the outer most tag. diff --git a/packages/website/docs/components/display/card.mdx b/packages/website/docs/components/display/card.mdx index 882ce747460..43e3e4a51eb 100644 --- a/packages/website/docs/components/display/card.mdx +++ b/packages/website/docs/components/display/card.mdx @@ -41,10 +41,8 @@ export default () => {cardNodes}; Most of the time, cards should read from top to bottom (vertical). However, in some cases, you may want the icon to be to the left of the content. In this case, add the prop `layout="horizontal"`. Works best when the icon is size `xl`. -:::danger Horizontal layouts do not work with images, footers, or textAlign. Therefore, these properties will be ignored. - +:::danger Horizontal layouts **do not** work with images, footers, or `textAlign`. Therefore, these properties will be ignored. - ::: ```tsx interactive @@ -89,9 +87,7 @@ export default () => ( Images can be added in place of, or in conjuction with, icons. Just pass a url into the `image` prop and it will expand to the edges of the card. -:::note Make sure that all images are the same proportions when used in a singular row. - -Make sure that all images are the **same proportions** when used in a singular row. +:::tip Make sure that all images are the **same proportions** when used in a singular row. Also, when passing an **element** to the `image` prop that consists solely of inline elements or does not contain an`` element, each element will require a style of `width: 100%`. @@ -155,10 +151,8 @@ export default () => ( Footers can contain any number of elements and will always align to the bottom of the card. However, if you supply a footer containing a **EuiButton** you **must not** also give it an `onClick`. -:::warning When using footers to display generic "Go" buttons, you must provide an aria-label to the button itself that refers back to the title of the card. - +:::note Accessibility requirement When using footers to display generic "Go" buttons, you must provide an `aria-label` to the button itself that refers back to the title of the card. - ::: ```tsx interactive @@ -295,10 +289,8 @@ export default () => ( When you have a list of cards that can be selected but **do not navigate anywhere**, you can add the `selectable` prop. The prop is an object that extends **EuiButtonEmpty**. It will apply the button as seen below, and passing `selectable.isSelected=true` will alter the styles of the card and button to look selected. -:::warning - +:::tip When providing an extra link to more details or such, be sure to stop event propagation from also selecting the card. - ::: ```tsx interactive @@ -422,10 +414,8 @@ export default () => { }; ``` -:::warning When used as a radio group, you must provide a fieldset with a legend for accessibility. - +:::note Accessibility requirement When used as a radio group, you must provide a `fieldset` with a `legend` for accessibility. - ::: ```tsx interactive diff --git a/packages/website/docs/components/display/comment_list.mdx b/packages/website/docs/components/display/comment_list.mdx index 46cda291171..df09cb52f57 100644 --- a/packages/website/docs/components/display/comment_list.mdx +++ b/packages/website/docs/components/display/comment_list.mdx @@ -7,10 +7,8 @@ id: display_comment_list The **EuiCommentList** is a timeline component built on top of [**EuiTimeline**](/docs/display/timeline). It allows you to display comments or logged actions that either a user or a system has performed. -:::warning - -For accessibility, it is highly recommended to provide a descriptive `aria-label` or the ID of an external label to the `aria-labelledby` prop of the **EuiCommentList**. A `timelineAvatarAriaLabel` should be provided for every **EuiComment** with or without a `timelineAvatar` as `IconType`. - +:::note Accessibility recommendation +Provide a descriptive `aria-label` or the ID of an external label to the `aria-labelledby` prop of the **EuiCommentList**. A `timelineAvatarAriaLabel` should be provided for every **EuiComment** with or without a `timelineAvatar` as `IconType`. ::: ## Basic comment list diff --git a/packages/website/docs/components/display/drag_and_drop.mdx b/packages/website/docs/components/display/drag_and_drop.mdx index e5d134605bb..6db879aaff8 100644 --- a/packages/website/docs/components/display/drag_and_drop.mdx +++ b/packages/website/docs/components/display/drag_and_drop.mdx @@ -11,7 +11,7 @@ An extension of [@hello-pangea/dnd](https://github.com/hello-pangea/dnd) (which * ``: Area into which items can be dropped. Contains one or more ``. * ``: Items that can be dragged. Must be part of an `` -:::warning Consider your users, use case +:::warning Consider your users and use case Drag and drop interfaces are not well-adapted to many cases, and may be less suitable than other form types for data operations. For instance, drag and drop interaction relies heavily on spatial orientation that may not be entirely valid to all users (e.g., screen readers as the sole source of information). Similarly, users navigating by keyboard may not be afforded nuanced, dual-axis drag item manipulation. @@ -143,10 +143,8 @@ By default the entire element surface can initiate a drag. To specify an element The `provided` parameter on the **EuiDraggable** `children` render prop has all data required for functionality. Along with the `customDragHandle` flag,`provided.dragHandleProps` needs to be added to the intended handle element. -:::note Icon-only custom drag handles require an accessible label. Add an aria-label="Drag handle" attribute to your React component or HTML element that receivesprovided.dragHandleProps. - +:::note Accessibility requirement **Icon-only** custom drag handles require an accessible label. Add an `aria-label="Drag handle"` attribute to your React component or HTML element that receives`provided.dragHandleProps`. - ::: ```tsx interactive diff --git a/packages/website/docs/components/display/icons/overview.mdx b/packages/website/docs/components/display/icons/overview.mdx index 57f723ce14b..cd6c2959592 100644 --- a/packages/website/docs/components/display/icons/overview.mdx +++ b/packages/website/docs/components/display/icons/overview.mdx @@ -13,10 +13,8 @@ import { EuiCodeBlock, EuiSpacer, EuiSplitPanel, EuiToken } from '@elastic/eui'; ``` -:::warning For better accessibility it's always recommended to give a descriptive title based on the icon use. - -If no title is provided the icon is going to be purely decorative and it will get by default an `aria-hidden=true`. - +:::note Accessibility recommendation +If possible, provide a descriptive title based on the icon use. If no title is provided, the icon is considered purely decorative, and it will default to `aria-hidden=true`. ::: ## Glyphs diff --git a/packages/website/docs/components/display/image.mdx b/packages/website/docs/components/display/image.mdx index 74d91786e0c..d3042dc64a4 100644 --- a/packages/website/docs/components/display/image.mdx +++ b/packages/website/docs/components/display/image.mdx @@ -7,7 +7,7 @@ id: display_image Use **EuiImage** when you need to place a static image into a page with an optional caption. -:::note Writing meaningful image alt text +:::tip Writing meaningful image alt text This page has several examples of alt text written to aid screen reader users, as well as several examples of when _not_ to include alt text. When an image is decorative, or if the image is adequately described by surrounding text, it is better to pass an empty `""` string instead. diff --git a/packages/website/docs/components/display/progress.mdx b/packages/website/docs/components/display/progress.mdx index a0b3d9ae61c..6b1809858bc 100644 --- a/packages/website/docs/components/display/progress.mdx +++ b/packages/website/docs/components/display/progress.mdx @@ -88,9 +88,9 @@ export default () => { Using the `position` prop we can align our bar to be `fixed` or `absolute`. In both options, the background color of the base bar is dropped (since the context of width is already known from your wrapping element). For the absolute option, make sure that your wrapping element has `position: relative` applied. -:::note Note about progress bars over fixed headers +:::warning Progress bars over fixed headers -Using **EuiProgress** with a `fixed` position may result in it being overlayed when its parent wrapper has a `z-index` value lower than another fixed element, such as **EuiHeader**. In that case, wrap **EuiProgress** in an **EuiPortal** as seen on the Snippet tab. +Using the `fixed` position may result in **EuiProgress** being overlayed when its parent wrapper has a `z-index` value lower than another fixed element, such as **EuiHeader**. In this scenario, wrap **EuiProgress** in an **EuiPortal** (example below). ::: diff --git a/packages/website/docs/components/display/skeleton.mdx b/packages/website/docs/components/display/skeleton.mdx index 21b7c6efe68..e0ae7eb2db5 100644 --- a/packages/website/docs/components/display/skeleton.mdx +++ b/packages/website/docs/components/display/skeleton.mdx @@ -7,12 +7,8 @@ id: display_skeleton The **EuiSkeleton** components are placeholder components for content which has yet to load. They provide meaningful previews, avoid layout content shifts, and add accessible announcements to screen readers when content is done loading. -:::note Using the contentAriaLabel prop - -Using the `contentAriaLabel` prop - +:::note Accessibility recommendation The `contentAriaLabel` prop should be used to help describe the type of content that is loading to screen reader users. If you do not provide a descriptive label and have have multiple loading skeletons on the page, screen reader users may hear a multitude of “Loaded” messages in a row, with no meaningful indication of what actually loaded. - ::: ## Text diff --git a/packages/website/docs/components/display/text.mdx b/packages/website/docs/components/display/text.mdx index ba15cf799df..97bf3c7a647 100644 --- a/packages/website/docs/components/display/text.mdx +++ b/packages/website/docs/components/display/text.mdx @@ -5,15 +5,11 @@ id: display_text # Text -**EuiText** is a generic catchall wrapper that will apply our standard typography styling and spacing to naked HTML. Because of its forced style it **only accepts raw XHTML**. - -:::note When using EuiText, keep in mind: - -When using **EuiText**, keep in mind: +**EuiText** is a generic catchall wrapper that will apply our standard typography styling and spacing to naked HTML. Because of its forced styles, it **only accepts raw XHTML**. +:::warning * All your **XHTML** elements should be direct descendants of **EuiText**. You should avoid wrapping them in a `div` or `span`. This will ensure styles are applied correctly. * Avoid nesting React components which would break their styling. - ::: **EuiText** can ensure proper line-length for readability by setting a `max-width` on the entire component. To add the max-width setting, set `grow=false`. diff --git a/packages/website/docs/components/display/timeline.mdx b/packages/website/docs/components/display/timeline.mdx index 58836295b3f..59d829569f6 100644 --- a/packages/website/docs/components/display/timeline.mdx +++ b/packages/website/docs/components/display/timeline.mdx @@ -12,10 +12,8 @@ This component allows you to create any type of timeline, but for more specific * [**EuiSteps**](/docs/navigation/steps): a timeline that allows you to present instructional content that must be conducted in a particular order and might contain progress indications. * [**EuiCommentList**](/docs/display/comment-list): a timeline that allows you to display comments or logging actions that either a user or a system has performed. -:::warning For accessibility, it is required to wrap your EuiTimelineItem's with a EuiTimeline. It is highly recommended to provide a descriptive aria-label, or a text node ID of an external label to the aria-labelledby prop of the EuiTimeline. - +:::note Accessibility requirement For accessibility, it is required to wrap your **EuiTimelineItem**'s with a **EuiTimeline**. It is highly recommended to provide a descriptive `aria-label`, or a text node ID of an external label to the `aria-labelledby` prop of the **EuiTimeline**. - ::: ```tsx interactive diff --git a/packages/website/docs/components/display/tour/overview.mdx b/packages/website/docs/components/display/tour/overview.mdx index 4a2cd8eb84d..aee449b2a27 100644 --- a/packages/website/docs/components/display/tour/overview.mdx +++ b/packages/website/docs/components/display/tour/overview.mdx @@ -8,9 +8,7 @@ id: display_tour The tour components provided by EUI allow for a flexible and customizable way to showcase items on a page in an ordered manner by augmenting existing elements on the page without altering functionality. :::note - -The examples on this page, use localStorage to persist state to demonstrate starting a tour at different stages. - +The examples on this page use localStorage to persist state to demonstrate starting a tour at different stages. ::: ## Step options diff --git a/packages/website/docs/components/editors_and_syntax/code.mdx b/packages/website/docs/components/editors_and_syntax/code.mdx index c63d9b5cc02..32c3d592524 100644 --- a/packages/website/docs/components/editors_and_syntax/code.mdx +++ b/packages/website/docs/components/editors_and_syntax/code.mdx @@ -5,10 +5,8 @@ id: editors_syntax_code # Code -:::note - +:::tip **EuiCode** and **EuiCodeBlock** are intended to render static lines or blocks of code in **read-only** contexts. If you need capabilities to edit, or want to print long code (e.g., printing JSON from an API), we recommend installing a version of Monaco. If you are building within the Kibana platform, you can use their [**CodeEditor**](https://github.com/elastic/kibana/tree/main/packages/shared-ux/code_editor/impl). - ::: The **EuiCode** and **EuiCodeBlock** components support [all language syntaxes](https://prismjs.com/#supported-languages) supported by the `prism` [library](https://prismjs.com/). The `language` prop can also be omitted to simply render formatted but unhighlighted code. diff --git a/packages/website/docs/components/elastic_charts/accessibility_features.mdx b/packages/website/docs/components/elastic_charts/accessibility_features.mdx index 285151c26d2..52cce48872e 100644 --- a/packages/website/docs/components/elastic_charts/accessibility_features.mdx +++ b/packages/website/docs/components/elastic_charts/accessibility_features.mdx @@ -70,10 +70,8 @@ You may want to set a heading level if there are multiple charts on the page but ``` -:::warning ariaDescribedBy will override ariaDescription if both are specified. - +:::warning `ariaDescribedBy` will override `ariaDescription` if both are specified. - ::: `ariaUseDefaultSummary` is a boolean defaulted to `true`. The default summary is bare bones and only reports the chart type(s). Some chart types provide more information but today that is only Gauge and Goal charts. If you are passing in a custom description, you can disable this prop. @@ -335,9 +333,7 @@ XY charts include: area, bar, and histogram. You can add meaning to your color segments by using the `bandLabels` prop. :::note - In version 64.1.0, semantic groupings are only available for **goal and gauge charts**. - ::: diff --git a/packages/website/docs/components/elastic_charts/metric_chart.mdx b/packages/website/docs/components/elastic_charts/metric_chart.mdx index 5bd7f7a9e87..57726cf0ada 100644 --- a/packages/website/docs/components/elastic_charts/metric_chart.mdx +++ b/packages/website/docs/components/elastic_charts/metric_chart.mdx @@ -614,9 +614,7 @@ Metric charts are composed of a series of elements that follow a specified hiera Below certain breakpoints, secondary elements such as `subtitles` are removed in order to leave as much space as possible for primary elements (`title`, `value`). Be aware of this limitation when dealing with small metrics. :::warning - Please be always aware of this limit and resize the Metric component accordingly within your interface or dashboard. - ::: ```mdx-code-block diff --git a/packages/website/docs/components/forms/combo_box.mdx b/packages/website/docs/components/forms/combo_box.mdx index 2b2a496b07a..6dfbfe555cc 100644 --- a/packages/website/docs/components/forms/combo_box.mdx +++ b/packages/website/docs/components/forms/combo_box.mdx @@ -7,12 +7,8 @@ id: forms_combo_box Use a **EuiComboBox** when the input has so many options that the user needs to be able to search them, the user needs to be able to select multiple options, and/or the user should have the ability to specify a custom value in addition to selecting from a predetermined list. If you're unsure of which selection component to use, see [EUI's in-depth guide to selection components](https://github.com/elastic/eui/discussions/7049) for more information. -:::note You must add an accessible label to each instance of EuiComboBox - -You must add an accessible label to each instance of **EuiComboBox** - -Labels can be created by wrapping the combo box in an **EuiFormRow** with a `label`, adding an `aria-label` prop, or passing a text node ID to the `aria-labelledby` prop. - +:::note Accessibility requirement +Add an accessible label to each instance of **EuiComboBox**. Labels can be created by wrapping the combo box in an **EuiFormRow** with a `label`, adding an `aria-label` prop, or passing a text node ID to the `aria-labelledby` prop. ::: ```tsx interactive diff --git a/packages/website/docs/components/forms/compressed_forms.mdx b/packages/website/docs/components/forms/compressed_forms.mdx index 127acaf332c..cb0a9fc4111 100644 --- a/packages/website/docs/components/forms/compressed_forms.mdx +++ b/packages/website/docs/components/forms/compressed_forms.mdx @@ -8,9 +8,7 @@ id: forms_compressed_forms Also known as **Editor-Style Controls**, compressed forms and controls were specifically created for use when space is at a premium. They are not intended for use when the form is the main objective of the page. They work best in editor-style applications where form controls are being used to create or edit content on the page. :::danger - Do not use compressed and non-compressed form controls in the same form. - ::: To use compressed forms, pass `display="rowCompressed"` to the EuiFormRows and `compressed=true` to the form controls themselves. @@ -322,7 +320,7 @@ export default () => ( ## In a popover -Always use the compressed version of forms and elements when they exist inside of a[popover](/docs/layout/popover). +Always use the compressed version of forms and elements when they exist inside of a [popover](/docs/layout/popover). ```tsx interactive import React, { useState } from 'react'; @@ -410,10 +408,8 @@ export default () => { This is an example of how to combine compressed form controls with from rows, labels, prepend and appends in a column layout. -:::warning Pay close attention to the patterns of using htmlFor and aria-label. For best results, each form control that is not wrapped in an EuiFormRow should be supplied an id. - +:::note Accessibility recommendation Pay close attention to the patterns of using `htmlFor` and `aria-label`. For best results, each form control that is not wrapped in an EuiFormRow should be supplied an `id`. - ::: ```tsx interactive diff --git a/packages/website/docs/components/forms/date_picker.mdx b/packages/website/docs/components/forms/date_picker.mdx index 3ecd7b7f3ed..9cc1853891e 100644 --- a/packages/website/docs/components/forms/date_picker.mdx +++ b/packages/website/docs/components/forms/date_picker.mdx @@ -151,9 +151,7 @@ export default () => { Locale formatting is achieved by using the `locale`,`timeFormat`, and `dateFormat` props. The latter will take any `moment()` notation. Check [Date format by country](https://en.wikipedia.org/wiki/Date_format_by_country) for formatting examples. :::warning - Moment will try to load the locale on demand when it is used. Bundlers that do not support dynamic require statements will need to explicitly import the locale, e.g. `import 'moment/locale/zh-cn'`. See the below demo JS for examples. - ::: ```tsx interactive diff --git a/packages/website/docs/components/forms/form_controls/overview.mdx b/packages/website/docs/components/forms/form_controls/overview.mdx index d863a7913dc..8d9c4d8935f 100644 --- a/packages/website/docs/components/forms/form_controls/overview.mdx +++ b/packages/website/docs/components/forms/form_controls/overview.mdx @@ -7,12 +7,10 @@ id: forms_form_controls EUI provides different types of basic form controls: [**EuiFieldText**](/docs/forms/form-controls#text-field), [**EuiFieldSearch**](/docs/forms/form-controls#search-field), [**EuiFieldNumber**](/docs/forms/form-controls#number-field), [**EuiFieldPassword**](/docs/forms/form-controls#password-field), [**EuiSelect**](/docs/forms/form-controls#select), [**EuiTextArea**](/docs/forms/form-controls#textarea), and [**EuiFilePicker**](/docs/forms/form-controls#file-picker). -:::warning Wrap each of your from controls in a EuiFormRow - -Wrap each of your from controls in a **EuiFormRow** - -Use the [**EuiFormRow**](/docs/forms/form-layouts#form-and-form-rows) component to easily associate form components with labels, help text, and error text. For accessibility, you must provide a `label`, `aria-label` , or a text node ID of an external label to the `aria-labelledby` prop. +:::note Accessibility requirement +You must provide a `label`, `aria-label`, or valid `aria-labelledby` prop to all form controls. +To easily meet this requirement, we recommend wrapping your form controls in the [**EuiFormRow**](/docs/forms/form-layouts#form-and-form-rows) component, which automatically associates form controls with labels, help text, and error text. ::: ## Text field diff --git a/packages/website/docs/components/forms/range_sliders.mdx b/packages/website/docs/components/forms/range_sliders.mdx index 9d6cbad3c3e..f81b820e85c 100644 --- a/packages/website/docs/components/forms/range_sliders.mdx +++ b/packages/website/docs/components/forms/range_sliders.mdx @@ -5,7 +5,7 @@ id: forms_range_sliders # Range sliders -:::warning Understanding precision +:::tip Understanding precision Range sliders should only be used when **the precise value is not considered important**. If the precise value does matter, add the `showInput` prop or use a **EuiFieldNumber** instead. @@ -98,9 +98,9 @@ export default () => { The **EuiDualRange** accepts almost all the same props as the regular **EuiRange**, with the exception of `showRange` which is on by default, and `showValue` since tooltips don't fit properly when there are two. -:::warning Retrieving field values +:::info Retrieving field values -Two-value `input[type=range]` elements are not part of the HTML5 specification. Because of this support gap, **EuiDualRange** cannot expose a native `value` property for native form to consumption. **The React `onChange` prop is the recommended method for retrieving the upper and lower values.** +Two-value `input[type=range]` elements are not part of the HTML5 specification. Because of this support gap, **EuiDualRange** does not (by default) expose a native `value` property for form consumption. The React `onChange` prop is the recommended method for retrieving the upper and lower values. **EuiDualRange** does use native inputs to help validate step values and range limits. These may be used as form values when `showInput` is in use. The alternative is to store values in `input[type=hidden]`. diff --git a/packages/website/docs/components/forms/selectable.mdx b/packages/website/docs/components/forms/selectable.mdx index 9273493f7d2..6b92af2a2fc 100644 --- a/packages/website/docs/components/forms/selectable.mdx +++ b/packages/website/docs/components/forms/selectable.mdx @@ -11,9 +11,11 @@ id: forms_selectable At its simplest, **EuiSelectable** requires an array of `options` and an `onChange` handler which passes back the altered `selectedOptions` array. The `children` is a function that return the `list` and `search` nodes. -:::note Selected options are based on the checked = on property +:::tip Selected options are based on the checked = on property -**EuiSelectable** offers the ability to **exclude** selections or **include selections for some** (mixed). Therefore, the `checked` property is one of `undefined | 'on' | 'off' | 'mixed'`, `'on'` being the default for selected options when `allowExclusions = false`. +**EuiSelectable** offers the ability to **exclude** selections or **include selections for some** (mixed). Therefore, the `checked` property is one of `undefined | 'on' | 'off' | 'mixed'`. + +`'on'` is the default for selected options when `allowExclusions = false`. ::: @@ -77,10 +79,8 @@ export default () => { To add a search component to the list, simply add the `searchable` prop. You can optionally pass in a `searchProps` object which will get passed down to the actual **EuiFieldSearch** used. In this example,`onSearch` will return a second parameter, enabling you to access the list of filtered items -:::note The search is performed as a string match against the option.label unless a separate option.searchableLabel is provided. - +:::tip The search is performed as a string match against the `option.label` unless a separate `option.searchableLabel` is provided. - ::: ```tsx interactive diff --git a/packages/website/docs/components/forms/selection_controls/overview.mdx b/packages/website/docs/components/forms/selection_controls/overview.mdx index 347e19fbd39..689ed58d02f 100644 --- a/packages/website/docs/components/forms/selection_controls/overview.mdx +++ b/packages/website/docs/components/forms/selection_controls/overview.mdx @@ -324,10 +324,8 @@ Make sure to pass a `label` to ensure a larger clickable area and ensure that sc If the switch is described in some other manner, like when using an [**EuiFormRow**](/docs/forms/form-layouts#form-and-form-rows), you can eliminate the visible label with `showLabel={false}` or use it to further describe the state. -:::warning - -When providing the state as the label, you'll need to provide an aria-describedby with the label's id to associate it with the switch. - +:::note Accessibility requirement +When providing the state as the label, you'll need to provide an `aria-describedby` with the label's `id` to associate it with the switch. ::: ```tsx interactive @@ -381,10 +379,8 @@ export default () => { ## Fieldset and legend -:::warning "[Use a fieldset and legend] for groups of related controls where the individual labels for each control do not provide a sufficient description, and an additional group level description is needed." WCAG Spec - +:::note Accessibility recommendation "\[Use a fieldset and legend\] for groups of related controls where the individual labels for each control do not provide a sufficient description, and an additional group level description is needed." [WCAG Spec](https://www.w3.org/WAI/WCAG21/Techniques/html/H71) - ::: **EuiFormFieldset** simply wraps its children in a `
` with the option to add a `` via the `legend` object prop. Find more examples in the [guidelines tab](/docs/forms/selection-controls/guidelines). diff --git a/packages/website/docs/components/forms/super_select.mdx b/packages/website/docs/components/forms/super_select.mdx index 45fac22a687..9fe74c2dc67 100644 --- a/packages/website/docs/components/forms/super_select.mdx +++ b/packages/website/docs/components/forms/super_select.mdx @@ -5,7 +5,7 @@ id: forms_super_select # Super select -:::note Not sure which selection component to use? +:::tip Not sure which selection component to use? See [EUI's in-depth guide to selection components ](https://github.com/elastic/eui/discussions/7049) for more information. diff --git a/packages/website/docs/components/guidelines/accessibility.mdx b/packages/website/docs/components/guidelines/accessibility.mdx index 29f6f46cf23..f3d0f165371 100644 --- a/packages/website/docs/components/guidelines/accessibility.mdx +++ b/packages/website/docs/components/guidelines/accessibility.mdx @@ -76,7 +76,7 @@ You can aid navigation and make pages more accessible for screen reader users by ``` -:::note +:::tip [**EuiTitle**](/docs/display/title) gives you a way to separate your presentation from your semantic markup. ::: @@ -217,10 +217,8 @@ Focus states are an important part of design because they let keyboard users kno Given that a keyboard user primarily navigates pages in one direction (either forward or backward), it’s important to have an intuitive focus order. Focus order should follow the flow of the page to make it easy to follow. If you’ve made a normally non-interactive element like a `
` interactive via JavaScript, you can enable a tab stop using `tabIndex=0`. If you want something that is only focusable programmatically, you can use `tabIndex=-1`. -:::danger Using tabIndex values greater than 0 is problematic and should be avoided. - +:::danger Using `tabIndex` values greater than 0 is problematic and should be avoided. - ::: ### How do I get back to where I was? @@ -340,8 +338,7 @@ Here, the 3 buttons have the same accessible name. There are a few different pat ``` -:::note Give lists an accessible name to improve their discoverability! - +:::tip Give lists an accessible label to improve their discoverability! ```

My favorite fruit

@@ -350,7 +347,6 @@ Here, the 3 buttons have the same accessible name. There are a few different pat
    ...
``` - ::: ### Further reading diff --git a/packages/website/docs/components/guidelines/writing/guidelines.mdx b/packages/website/docs/components/guidelines/writing/guidelines.mdx index 03d9c553918..333ad17865f 100644 --- a/packages/website/docs/components/guidelines/writing/guidelines.mdx +++ b/packages/website/docs/components/guidelines/writing/guidelines.mdx @@ -7,6 +7,7 @@ sidebar_position: 3 import { EuiCard, + EuiCallOut, EuiFlexGroup, EuiButton, EuiPanel, @@ -100,9 +101,9 @@ Proper nouns include product names, solutions, apps, feature tiers, and subscrip - :::note Building a dashboard? - Create content directly from our Dashboard app using our new integrated workflow. [Learn more](https://brand.elastic.co/302f66895/p/072ccc-naming-guide) - ::: + + Create content directly from our Dashboard app using our new integrated workflow. Learn more + For more information, view the [Elastic name guidelines.](https://brand.elastic.co/302f66895/p/072ccc-naming-guide) diff --git a/packages/website/docs/components/layout/accordion.mdx b/packages/website/docs/components/layout/accordion.mdx index 211e4c4ae1e..15feb7c561c 100644 --- a/packages/website/docs/components/layout/accordion.mdx +++ b/packages/website/docs/components/layout/accordion.mdx @@ -399,10 +399,8 @@ In some cases you might want to prevent the user from closing the **EuiAccordion The `isDisabled` prop will disable interaction on the button and the arrow. Use it in conjunction with `initialIsOpen` to achieve the desired effect. -:::warning - +:::note Accessibility recommendation When disabling the interaction of accordions based on user input, it's advisable to ensure there is further explanation through the use of help or error text. - ::: ```tsx interactive @@ -532,10 +530,8 @@ Passing interactive content like links, buttons, or form elements as the `button If you don't want the interactive content to trigger the accordion expansion, you will have to apply `e.stopPropagation()` to your element manually. -:::warning - +:::note Accessibility requirement Accordions need a focusable button for accessibility, so changing the element to anything other than a button will enforce the display of the arrow. - ::: ```tsx interactive diff --git a/packages/website/docs/components/layout/bottom_bar.mdx b/packages/website/docs/components/layout/bottom_bar.mdx index 0cdc969b78f..a0ebc1f270d 100644 --- a/packages/website/docs/components/layout/bottom_bar.mdx +++ b/packages/website/docs/components/layout/bottom_bar.mdx @@ -5,10 +5,8 @@ id: layout_bottom_bar # Bottom bar -:::note - +:::tip **EuiPageTemplate** offers a quick way to [apply a bottom bar to your page layouts](/docs/templates/page-template#showing-a-bottom-bar). - ::: **EuiBottomBar** is a simple wrapper component that does nothing but affix a dark bar (usually filled with buttons) to the bottom of the page. Use it when you have really long pages or complicated, multi-page forms. In the case of forms, only invoke it if a form is in a savable state. diff --git a/packages/website/docs/components/layout/flyout.mdx b/packages/website/docs/components/layout/flyout.mdx index d8bfc6c40e2..51308457c15 100644 --- a/packages/website/docs/components/layout/flyout.mdx +++ b/packages/website/docs/components/layout/flyout.mdx @@ -9,10 +9,8 @@ id: layout_flyout Like modals, you control the visibilty of the flyout using your own state management, but **EuiFlyout** requires an `onClose` handler for it's internal dismiss buttons. -:::note - +:::note Accessibility recommendation Use `aria-labelledby={headingId}` to announce the flyout to screen readers. - ::: ```tsx interactive @@ -815,9 +813,7 @@ export default () => { By default, flyouts will continue to grow with the width of the window. To stop this growth at an ideal width, set `maxWidth` to `true`, or pass your own custom size. :::warning - Note that there are some caveats to providing a maxWidth that is smaller than the minWidth. - ::: ```tsx interactive diff --git a/packages/website/docs/components/layout/page_components/overview.mdx b/packages/website/docs/components/layout/page_components/overview.mdx index e18b9576486..c74aa7851e8 100644 --- a/packages/website/docs/components/layout/page_components/overview.mdx +++ b/packages/website/docs/components/layout/page_components/overview.mdx @@ -180,10 +180,8 @@ When using [**EuiEmptyPrompt**](/docs/display/empty-prompt) to replace the main -:::note - +:::tip Reminder: [**EuiPageTemplate**](/docs/templates/page-template) can handle all these configurations for you. - ::: diff --git a/packages/website/docs/components/layout/popover.mdx b/packages/website/docs/components/layout/popover.mdx index 379e0ec7605..28f230b2a97 100644 --- a/packages/website/docs/components/layout/popover.mdx +++ b/packages/website/docs/components/layout/popover.mdx @@ -1041,10 +1041,8 @@ export default () => { If you want a specific child element of the popover to immediately gain focus when the popover is open, use the `initialFocus` prop to pass either a selector or DOM node. -:::warning - +:::note Accessibility recommendation It can be jarring for keyboard and screen reader users to immediately land on an element with no other context. To alleviate this, ensure that your initial focus target makes sense alone or is the primary goal of the popover. - ::: ```tsx interactive @@ -1166,10 +1164,8 @@ export default () => { If the popover should not trap focus within itself, then you can remove it with `ownFocus={false}`. -:::warning Removing ownFocus makes it difficult for keyboard-only and screen reader users to navigate to and from your popover. - +:::warning Accessibility warning Removing `ownFocus` makes it difficult for keyboard-only and screen reader users to navigate to and from your popover. - ::: ```tsx interactive diff --git a/packages/website/docs/components/layout/resizable_container.mdx b/packages/website/docs/components/layout/resizable_container.mdx index c5ee4dc9ef2..6e50f3a3bf0 100644 --- a/packages/website/docs/components/layout/resizable_container.mdx +++ b/packages/website/docs/components/layout/resizable_container.mdx @@ -9,10 +9,8 @@ import { faker } from '@faker-js/faker'; This component is handy for various resizable containers. **EuiResizableContainer** uses the [React Render Props](https://reactjs.org/docs/render-props.html#using-props-other-than-render) technique to provide **EuiResizablePanel** and **EuiResizableButton** components for layout, and `actions` for custom handling collapse and resize functionality in your app. Wrap parts of your content with the **EuiResizablePanel** component and put the **EuiResizableButton** component between. -:::note Consider adding a tabIndex for keyboard accessibility - -Add a prop `tabIndex=0` to the **EuiResizableContainer** if it is a fixed height or has a lot of content. This ensures keyboard users can set focus on the container and scroll to the bottom using arrow keys. - +:::note Accessibility recommendation +Consider adding a `tabIndex=0` prop to the **EuiResizableContainer** if it is a fixed height or has a lot of content. This ensures keyboard users can set focus on the container and scroll to the bottom using arrow keys. ::: ## Horizontal resizing diff --git a/packages/website/docs/components/navigation/breadcrumbs.mdx b/packages/website/docs/components/navigation/breadcrumbs.mdx index cfd206ed878..b1f679abec6 100644 --- a/packages/website/docs/components/navigation/breadcrumbs.mdx +++ b/packages/website/docs/components/navigation/breadcrumbs.mdx @@ -11,10 +11,8 @@ See [**EuiTabs guidelines**](/docs/navigation/tabs/guidelines) if your applicati **EuiBreadcrumbs** requires an array of **EuiBreadcrumb** objects as `breadcrumbs` and handles truncation, including middle-truncation in the case of many items, and mobile responsiveness. Each item accepts an `href` prop, though we recommend the last item represent the current page and therefore the link is unnecessary. -:::warning For accessibility, it is highly recommended to provide a descriptive aria-label for each set of breadcrumbs. - -For accessibility, it is highly recommended to provide a descriptive `aria-label` for each set of breadcrumbs. - +:::note Accessibility recommendation +Provide a descriptive `aria-label` for each set of breadcrumbs. ::: ```tsx interactive @@ -353,10 +351,8 @@ You may also pass `popoverProps` with almost any prop that [**EuiPopover**](/doc If you need the ability to close the breadcrumb popover from within your popover content, `popoverContent` accepts a render function that will be passed a `closePopover` callback, which you can invoke to close the popover. See the Deployment breadcrumb below for example usage. -:::warning Please note that creating a breadcrumb with a popover will nullify any passed href or onClick behavior, as the only interaction the breadcrumb should have at that point is the popover toggle. - -Please note that creating a breadcrumb with a popover will nullify any passed `href` or `onClick` behavior, as the _only_ interaction the breadcrumb should have at that point is the popover toggle. - +:::warning +Creating a breadcrumb with a popover will nullify any passed `href` or `onClick` behavior, as the _only_ interaction the breadcrumb should have at that point is the popover toggle. ::: ```tsx interactive diff --git a/packages/website/docs/components/navigation/button/overview.mdx b/packages/website/docs/components/navigation/button/overview.mdx index ef32b45440a..ccee78bc9d9 100644 --- a/packages/website/docs/components/navigation/button/overview.mdx +++ b/packages/website/docs/components/navigation/button/overview.mdx @@ -427,10 +427,8 @@ export default () => ( An **EuiButtonIcon** is a button that only contains an icon (no text). Use the `display` and `size` props to match the appearance of your **EuiButtonIcon** to other standard buttons. By default they will appear as `xs`, `empty` buttons. -:::warning EuiButtonIcon requires an aria-label to express the meaning to screen readers. - +:::note Accessibility requirement **EuiButtonIcon** requires an `aria-label` to express the meaning to screen readers. - ::: ```tsx interactive @@ -795,10 +793,8 @@ export default () => { 2. If your button only changes the **visual** appearance, you must add `aria-pressed` passing a boolean for the on and off states. All EUI button types provide a helper prop for this called `isSelected`. -:::warning Do not add aria-pressed or isSelected if you also change the readable text. - +:::note Accessibility recommendation Do not add `aria-pressed` or `isSelected` if you also change the readable text. - ::: ```tsx interactive @@ -843,10 +839,8 @@ export default () => { An **EuiButtonGroup** is for indicating **selection** only. They utilize the `type="single"` or `"multi"` prop to determine whether multiple or only single selections are allowed per group. -:::warning In order for groups to be properly read as groups with a title, the legend prop is required. This is only for accessibility, however, so it will be visibly hidden. - +:::note Accessibility requirement In order for groups to be properly read as groups with a title, the `legend` prop is **required**. This is only for accessibility, however, so it will be visibly hidden. - ::: ```tsx interactive diff --git a/packages/website/docs/components/navigation/collapsible_nav.mdx b/packages/website/docs/components/navigation/collapsible_nav.mdx index 3486b0cf253..e17522a2b69 100644 --- a/packages/website/docs/components/navigation/collapsible_nav.mdx +++ b/packages/website/docs/components/navigation/collapsible_nav.mdx @@ -9,10 +9,8 @@ This is a high level component that creates a flyout-style navigational pane. **EuiCollapsibleNav** is a custom implementation of [**EuiFlyout**](/docs/layout/flyout); the visibility of which must still be maintained by the consuming application. An extra feature that it provides is the ability to `dock` the flyout. This affixes the flyout to the window and pushes the body content by adding left side padding. -:::note - +:::warning Docking is not possible on small screens because it would force less real estate for the page content. - ::: ```tsx interactive diff --git a/packages/website/docs/components/navigation/context_menu.mdx b/packages/website/docs/components/navigation/context_menu.mdx index c744172b4e2..34d12edd8f1 100644 --- a/packages/website/docs/components/navigation/context_menu.mdx +++ b/packages/website/docs/components/navigation/context_menu.mdx @@ -240,10 +240,8 @@ export default () => { Use **EuiContextMenuPanel** for simple, non-nested context menus. The below pagination example has no nesting and no title. -:::note The selected context menu item should have an aria-current attribute - -**aria-current** tells screen readers which item is selected. Add an `aria-current="true"` attribute to `EuiContextMenuItem` when a context menu item is clicked or receives a keypress. - +:::note Accessibility recommendation +The selected context menu item should receive the `aria-current="true"` attribute, which tells screen readers which item is selected. ::: ```tsx interactive diff --git a/packages/website/docs/components/navigation/key_pad_menu.mdx b/packages/website/docs/components/navigation/key_pad_menu.mdx index 23d4ef23e6b..fbc675b8a70 100644 --- a/packages/website/docs/components/navigation/key_pad_menu.mdx +++ b/packages/website/docs/components/navigation/key_pad_menu.mdx @@ -9,10 +9,8 @@ The **EuiKeyPadMenu** component presents **EuiKeyPadMenuItems** in a tiled forma **EuiKeyPadMenu** is just a wrapping element for creating the list elements but you must declare each **EuiKeyPadMenu** component manually. -:::warning If the menu provides navigation for your application, wrap the EuiKeyPadMenu with . - +:::note Accessibility recommendation If the menu provides navigation for your application, wrap the **EuiKeyPadMenu** with ``. - ::: ```tsx interactive diff --git a/packages/website/docs/components/navigation/pagination/overview.mdx b/packages/website/docs/components/navigation/pagination/overview.mdx index b60b953fbe0..05e40bbde1e 100644 --- a/packages/website/docs/components/navigation/pagination/overview.mdx +++ b/packages/website/docs/components/navigation/pagination/overview.mdx @@ -11,10 +11,8 @@ Some EUI components have pagination built-in, like [**EuiBasicTable**](/docs/tab **EuiPagination** accepts a total `pageCount` and only shows up to 5 consecutive pages, with shortcuts to the first and/or last page. It also requires the parent component to maintain the current `activePage` and handle the `onPageClick`. -:::warning For accessibility, it is highly recommended to provide a descriptive aria-label for each pagination set. - -For accessibility, it is highly recommended to provide a descriptive `aria-label` for each pagination set. - +:::note Accessibility recommendation +Provide a descriptive `aria-label` for each pagination set. ::: ```tsx interactive diff --git a/packages/website/docs/components/navigation/side_nav.mdx b/packages/website/docs/components/navigation/side_nav.mdx index 4d44befd07e..df559e23620 100644 --- a/packages/website/docs/components/navigation/side_nav.mdx +++ b/packages/website/docs/components/navigation/side_nav.mdx @@ -76,9 +76,7 @@ Since **EuiSideNav** renders a `