elastic · cee-chen · Oct 31, 2024 · Oct 29, 2024 · Oct 29, 2024 · Oct 29, 2024
@@ -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};
       }

@@ -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).

@@ -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.
 

@@ -41,10 +41,8 @@ export default () => <EuiFlexGroup gutterSize="l">{cardNodes}</EuiFlexGroup>;
 
 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`<img />` 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

@@ -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

@@ -11,7 +11,7 @@ An extension of [@hello-pangea/dnd](https://github.com/hello-pangea/dnd) (which
 *   `<EuiDroppable />`: Area into which items can be dropped. Contains one or more `<EuiDraggable />`.
 *   `<EuiDraggable />`: Items that can be dragged. Must be part of an `<EuiDroppable />`
 
-:::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

@@ -13,10 +13,8 @@ import { EuiCodeBlock, EuiSpacer, EuiSplitPanel, EuiToken } from '@elastic/eui';
 <EuiIcon type="grid" />
 ```
 
-:::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

@@ -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.
 

@@ -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).
 
 :::
 

@@ -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

@@ -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`.

@@ -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

@@ -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

@@ -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.

@@ -70,10 +70,8 @@ You may want to set a heading level if there are multiple charts on the page but
 </Chart>
 ```
 
-:::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**.
-
 :::
 
 <Demo scope={{ ...ElasticCharts, useChartBaseTheme }}>

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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]`.
-Original file line number
+Diff line change
@@ Expand Up / @@ -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.
@@ Expand Down @@