diff --git a/docs/api/input.md b/docs/api/input.md
index 519963e4d9c..b4996e6afb4 100644
--- a/docs/api/input.md
+++ b/docs/api/input.md
@@ -85,6 +85,8 @@ Material Design offers filled styles for an input. The `fill` property on the in
Since the `fill` styles visually defines the input container, inputs that use `fill` should not be used in `ion-item`.
+Filled inputs can be used on iOS by setting Input's `mode` to `md`.
+
import Fill from '@site/static/usage/v7/input/fill/index.md';
diff --git a/docs/api/item.md b/docs/api/item.md
index 6aaf0dd0609..913135eebad 100644
--- a/docs/api/item.md
+++ b/docs/api/item.md
@@ -8,6 +8,9 @@ import Parts from '@ionic-internal/component-api/v7/item/parts.md';
import CustomProps from '@ionic-internal/component-api/v7/item/custom-props.md';
import Slots from '@ionic-internal/component-api/v7/item/slots.md';
+import useBaseUrl from '@docusaurus/useBaseUrl';
+import BestPracticeFigure from '@components/global/BestPracticeFigure';
+
ion-item: Input, Edit, or Delete iOS and Android Item Elements
@@ -17,7 +20,8 @@ import EncapsulationPill from '@components/page/api/EncapsulationPill';
-Items are elements that can contain text, icons, avatars, images, inputs, and any other native or custom elements. Generally they are placed in a [list](./list) with other items. Items can be swiped, deleted, reordered, edited, and more.
+Items are elements that can contain text, icons, avatars, images, inputs, and any other native or custom elements. Items should only be used as rows in a [List](./list) with other items. Items can be swiped, deleted, reordered, edited, and more.
+
## Basic Usage
@@ -28,6 +32,135 @@ import Basic from '@site/static/usage/v7/item/basic/index.md';
+## Content Types
+
+While items in a list take many forms, they typically support 5 different content types: supporting visuals, text, metadata, actions, and controls. However, not all of these content types should be used together at the same time. The following guide shows the different content types as well as how to properly utilize them in an application.
+
+### Supporting Visuals
+
+Supporting visuals are decorative icons or other adornments for an item. Common examples of supporting visuals are [Avatars](./avatar), [Icons](./icon), and [Thumbnails](./thumbnail). Since this content is not required to understand the intent of the item, it is typically hidden from screen readers using `aria-hidden="true"`.
+
+If a visual is required to interact with the item, such as an icon button, then the visual is an [action](#actions) not a supporting visual.
+
+}
+ dontImage={}
+/>
+
+In the example below, we are creating two lists with supporting visuals. The first list uses icons, and the second list uses avatars. The visuals are decorative, so they all have `aria-hidden="true"`. Additionally, they are presented consistently in the `start` slot.
+
+import SupportingVisuals from '@site/static/usage/v7/item/content-types/supporting-visuals/index.md';
+
+
+
+### Text
+
+The text content type includes form control labels or other visible text. This text serves to indicate the intent of the item. Try to keep the text short and to the point.
+
+If you find that you need a few more sentences to clarify the item's purpose, consider moving the additional sentences to a Note at the bottom of the list. Adding the item to its own list makes it clear which item the text is associated with.}
+ doText="Move long text outside of the list"
+ dontText="Don't try to fit long text in an item"
+ doImage={}
+ dontImage={}
+/>
+
+In the example below, we are creating a list with different types of text. The "First Name" and "Last Name" labels serve to indicate what to type into the text inputs.
+
+The "Allow Notifications" label on the toggle has additional text underneath it that notes users can disable notifications. Since this text is short, it is placed inside of the item.
+
+Below that list is another list containing a textarea with a [Note](./note) containing long text underneath. The textarea was placed in its own list to make it apparent that the long text is associated with the textarea and not any other fields.
+
+import Text from '@site/static/usage/v7/item/content-types/text/index.md';
+
+
+
+### Metadata
+
+Metadata provides additional context for an item such as status text or counts. Components like [Badge](./badge) or [Note](./note) are great ways of showing metadata.
+
+}
+ dontImage={}
+/>
+
+}
+ cautionImage={}
+/>
+
+In the example below, we are creating two lists with different kinds of metadata. The first list uses [Note](./note) to show how many tasks are in each to-do list.
+
+The second list mimics the iOS Mail app to show an inbox. This list makes use of custom metadata including an "unread message" indicator in the "start" slot as well as a timestamp and custom detail icon in the "end" slot. The "unread message" indicator is highlighted in blue to draw the user's attention to the unread messages, while the timestamp is more subtle.
+
+import Metadata from '@site/static/usage/v7/item/content-types/metadata/index.md';
+
+
+
+### Actions
+
+Actions are interactive elements that do something when you activate them. An item can have multiple actions displayed on a line. However, developers should ensure that each action's tap target is large enough to be usable.
+
+Developers should avoid creating nested interactives which can break the user experience with screen readers. For example, developers should avoid adding a button inside the main content of the Item if the `button` property is set to `true`.
+
+Actions can be added by using the Item Sliding component. Actions can also be placed directly inside of the Item without the use of Item Sliding, but this should be limited to no more than 2 actions.}
+ doText={<>Use an Item Sliding to reveal multiple actions by swiping on the Item.}
+ dontText="Don't put more than 2 actions within an Item."
+ doImage={}
+ dontImage={}
+/>
+
+In the example below, we are creating a list of contacts. Each item is a stubbed button intended to bring you to the full contact page for that item. There are additional actions associated with each item that users can reveal by swiping on the item.
+
+import Actions from '@site/static/usage/v7/item/content-types/actions/index.md';
+
+
+
+### Controls
+
+Controls are form components such as checkboxes, inputs, radios, and more. Each item in a list should have at most two controls due to screen space constraints.
+
+Metadata such as helper text or character counts should not be used on form controls in list views. If such metadata is needed, the form control should be placed outside of a list. Filled Inputs are a great way of visually defining the input container outside of a list.}
+ doText="Place inputs with metadata outside of the list."
+ dontText="Don't put metadata for inputs in the list."
+ doImage={}
+ dontImage={}
+/>
+
+Alternatively, the metadata can be placed in a Note at the bottom of the list.}
+ doText="Place metadata for inputs at the end of a list."
+ dontText="Don't put metadata for inputs in the list."
+ doImage={}
+ dontImage={}
+/>
+
+Items should typically have no more than two controls. If you need more controls, consider adding the additional controls in a Modal that is accessible from the item.}
+ doText="Move additional controls to a submenu accessible from the item."
+ dontText="Don't use more than two controls within an item."
+ doImage={}
+ dontImage={}
+/>
+
+In the example below, we are creating a list of to-do tasks. Each item has a checkbox and an input. The checkbox lets the user mark a task as complete, and the input lets the user change the name of the task.
+
+import Controls from '@site/static/usage/v7/item/content-types/controls/index.md';
+
+
+
+
## Clickable Items
An item is considered "clickable" if it has an `href` or `button` property set. Clickable items have a few visual differences that indicate they can be interacted with. For example, a clickable item receives the ripple effect upon activation in `md` mode, has a highlight when activated in `ios` mode, and has a [detail arrow](#detail-arrows) by default in `ios` mode.
@@ -69,16 +202,6 @@ import Lines from '@site/static/usage/v7/item/lines/index.md';
-
-## Media Items
-
-[Avatars](./avatar) and [Thumbnails](./thumbnail) can be slotted inside of an item. This is useful when making lists of images and text.
-
-import Media from '@site/static/usage/v7/item/media/index.md';
-
-
-
-
## Buttons in Items
Buttons are styled smaller inside of items than when they are outside of them. To make the button size match buttons outside of an item, set the `size` attribute to `"default"`.
@@ -87,14 +210,6 @@ import Buttons from '@site/static/usage/v7/item/buttons/index.md';
-
-## Icons in Items
-
-import Icons from '@site/static/usage/v7/item/icons/index.md';
-
-
-
-
## Item Inputs
import Inputs from '@site/static/usage/v7/item/inputs/index.md';
@@ -132,6 +247,14 @@ import InputHighlight from '@site/static/usage/v7/item/theming/input-highlight/i
+## Guidelines
+
+The following guidelines will help ensure your list items are easy to understand and use.
+
+1. Items should only be used inside of [Lists](./list).
+2. Items inside of a list should be presented in a consistent format. For example, if your items present decorative icons, the icons should be positioned in the same way between items.
+3. Items should never render [nested interactives](https://dequeuniversity.com/rules/axe/4.4/nested-interactive). Screen readers are unable to select the correct interactive element when nested interactives are used. For example, avoid placing a button inside of an `ion-item` that has `button="true"`.
+4. Use [content types](#content-types) correctly. The Item component is designed to be a row in a [List](./list) and should not be used as a general purpose container.
## Properties
diff --git a/docs/api/textarea.md b/docs/api/textarea.md
index 8bc1d7ee99d..25c3328f4d0 100644
--- a/docs/api/textarea.md
+++ b/docs/api/textarea.md
@@ -69,6 +69,8 @@ Material Design offers filled styles for a textarea. The `fill` property on the
Since the `fill` styles visually defines the textarea container, textareas that use `fill` should not be used in `ion-item`.
+Filled textareas can be used on iOS by setting Textarea's `mode` to `md`.
+
import Fill from '@site/static/usage/v7/textarea/fill/index.md';
diff --git a/src/components/global/BestPracticeFigure/best-practice-figure.css b/src/components/global/BestPracticeFigure/best-practice-figure.css
new file mode 100644
index 00000000000..140024cbf83
--- /dev/null
+++ b/src/components/global/BestPracticeFigure/best-practice-figure.css
@@ -0,0 +1,70 @@
+.best-practice__do_dont {
+ display: grid;
+
+ grid-template-columns: 1fr 1fr;
+
+ gap: 12px;
+}
+
+/* Collapse to 1 column per row on smaller viewports */
+@media (max-width: 996px) {
+ .best-practice__do_dont {
+ grid-template-columns: 1fr;
+ }
+}
+
+.best-practice__container figcaption {
+ text-align: start;
+}
+
+.best-practice__do p,
+.best-practice__dont p,
+.best-practice__caution p {
+ padding: 8px 16px;
+}
+
+.best-practice__image-wrapper {
+ border-radius: 8px 8px 0px 0px;
+
+ overflow: hidden;
+}
+
+.best-practice__dont-text,
+.best-practice__do-text,
+.best-practice__caution-text {
+ padding: 12px 16px;
+
+ font-weight: 600;
+
+ border-radius: 0px 0px 8px 8px;
+}
+
+.best-practice__do .best-practice__image-wrapper {
+ border: 1px solid var(--c-blue-10);
+}
+
+.best-practice__dont .best-practice__image-wrapper {
+ border: 1px solid var(--c-red-10);
+}
+
+.best-practice__caution .best-practice__image-wrapper {
+ border: 1px solid var(--c-yellow-10);
+}
+
+.best-practice__dont-text {
+ color: var(--c-red-100);
+ background: var(--c-red-10);
+}
+.best-practice__do-text {
+ color: var(--c-blue-100);
+ background: var(--c-blue-10);
+}
+
+.best-practice__caution-text {
+ /* --c-yellow-100 does not have enough contrast
+ * placed on top of --c-yellow-10, so we manually
+ * choose a darker text color here.
+ */
+ color: #7e5e17;
+ background: var(--c-yellow-10);
+}
diff --git a/src/components/global/BestPracticeFigure/index.tsx b/src/components/global/BestPracticeFigure/index.tsx
new file mode 100644
index 00000000000..73e1eb7d91f
--- /dev/null
+++ b/src/components/global/BestPracticeFigure/index.tsx
@@ -0,0 +1,82 @@
+import React from 'react';
+
+import './best-practice-figure.css';
+
+/**
+ Usage:
+
+ import BestPracticeFigure from '@components/global/BestPracticeFigure';
+
+ }
+ dontImage={}
+ />
+
+ All images must have alt text for screen readers.
+
+ Custom HTML can also be passed to any of the text properties by using curly braces:
+
+ text={<>My text with a link}
+
+ Markdown such as backticks will not be processed when using curly braces.
+ The tag can be used instead:
+
+ text={<>The button property}
+
+ This component also supports a caution option. Typically you should use
+ either a "Don't" image or a "Caution" image but not both.
+
+ }
+ cautionImage={}
+ />
+
+ @prop text - Text that describes the figure as a whole
+ @prop doText - Text that describes a best practice
+ @prop dontText - Text that describes an anti-pattern
+ @prop cautionText - Text that describes something that could be an anti-pattern based on use case
+ @prop doImage - Image associated with doText
+ @prop dontImage - Image associated with dontText
+ @prop cautionImage - Image associated with cautionText
+ */
+
+export default function BestPracticeFigure({ text, doText, dontText, cautionText, doImage, dontImage, cautionImage }) {
+ return (
+
})
}
+/>
+
+In the example below, we are creating two lists with supporting visuals. The first list uses icons, and the second list uses avatars. The visuals are decorative, so they all have `aria-hidden="true"`. Additionally, they are presented consistently in the `start` slot.
+
+import SupportingVisuals from '@site/static/usage/v7/item/content-types/supporting-visuals/index.md';
+
+})
}
+ dontImage={})
}
+/>
+
+In the example below, we are creating a list with different types of text. The "First Name" and "Last Name" labels serve to indicate what to type into the text inputs.
+
+The "Allow Notifications" label on the toggle has additional text underneath it that notes users can disable notifications. Since this text is short, it is placed inside of the item.
+
+Below that list is another list containing a textarea with a [Note](./note) containing long text underneath. The textarea was placed in its own list to make it apparent that the long text is associated with the textarea and not any other fields.
+
+import Text from '@site/static/usage/v7/item/content-types/text/index.md';
+
+})
}
+/>
+
+})
}
+/>
+
+In the example below, we are creating two lists with different kinds of metadata. The first list uses [Note](./note) to show how many tasks are in each to-do list.
+
+The second list mimics the iOS Mail app to show an inbox. This list makes use of custom metadata including an "unread message" indicator in the "start" slot as well as a timestamp and custom detail icon in the "end" slot. The "unread message" indicator is highlighted in blue to draw the user's attention to the unread messages, while the timestamp is more subtle.
+
+import Metadata from '@site/static/usage/v7/item/content-types/metadata/index.md';
+
+})
}
+ dontImage={})
}
+/>
+
+In the example below, we are creating a list of contacts. Each item is a stubbed button intended to bring you to the full contact page for that item. There are additional actions associated with each item that users can reveal by swiping on the item.
+
+import Actions from '@site/static/usage/v7/item/content-types/actions/index.md';
+
+})
}
+ dontImage={})
}
+/>
+
+})
}
+ dontImage={})
}
+/>
+
+})
}
+ dontImage={})
}
+/>
+
+In the example below, we are creating a list of to-do tasks. Each item has a checkbox and an input. The checkbox lets the user mark a task as complete, and the input lets the user change the name of the task.
+
+import Controls from '@site/static/usage/v7/item/content-types/controls/index.md';
+
+})
}
+ />
+
+ @prop text - Text that describes the figure as a whole
+ @prop doText - Text that describes a best practice
+ @prop dontText - Text that describes an anti-pattern
+ @prop cautionText - Text that describes something that could be an anti-pattern based on use case
+ @prop doImage - Image associated with doText
+ @prop dontImage - Image associated with dontText
+ @prop cautionImage - Image associated with cautionText
+ */
+
+export default function BestPracticeFigure({ text, doText, dontText, cautionText, doImage, dontImage, cautionImage }) {
+ return (
+
+ 
+