docs(item): add best practices and usage guides (#3123)

Author: liamdebeasi

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';
 
 <Fill />

docs/api/item.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';
 
 <Fill />

docs/api/textarea.md

@@ -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);
+}

src/components/global/BestPracticeFigure/best-practice-figure.css

@@ -0,0 +1,82 @@
+import React from 'react';
+
+import './best-practice-figure.css';
+
+/**
+ Usage:
+
+ import BestPracticeFigure from '@components/global/BestPracticeFigure';
+
+ <BestPracticeFigure
+   text="..."
+   doText="..."
+   dontText="..."
+   doImage={<img alt="..." src={useBaseUrl(...)} />}
+   dontImage={<img alt="..." src={useBaseUrl(...)} />}
+ />
+
+ 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 <a href="#">link</a></>}
+
+ Markdown such as backticks will not be processed when using curly braces.
+ The <code> tag can be used instead:
+
+ text={<>The <code>button</code> property</>}
+
+ This component also supports a caution option. Typically you should use
+ either a "Don't" image or a "Caution" image but not both.
+
+ <BestPracticeFigure
+    text="..."
+    doText="..."
+    cautionText="..."
+    doImage={<img alt="..." src={useBaseUrl(...)} />}
+    cautionImage={<img alt="..." src={useBaseUrl(...)} />}
+  />
+
+  @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 (
+    <div className="best-practice__container">
+      <p>{text}</p>
+      <div className="best-practice__do_dont">
+        <figure className="best-practice__do">
+          <div className="best-practice__image-wrapper">{doImage}</div>
+          <figcaption>
+            <div className="best-practice__do-text">Do</div>
+            <p>{doText}</p>
+          </figcaption>
+        </figure>
+        {dontText && dontImage && (
+          <figure className="best-practice__dont">
+            <div className="best-practice__image-wrapper">{dontImage}</div>
+            <figcaption>
+              <div className="best-practice__dont-text">Don't</div>
+              <p>{dontText}</p>
+            </figcaption>
+          </figure>
+        )}
+        {cautionText && cautionImage && (
+          <figure className="best-practice__caution">
+            <div className="best-practice__image-wrapper">{cautionImage}</div>
+            <figcaption>
+              <div className="best-practice__caution-text">Caution</div>
+              <p>{cautionText}</p>
+            </figcaption>
+          </figure>
+        )}
+      </div>
+    </div>
+  );
+}