Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore: rename dont props to doNot #3144

Merged
merged 2 commits into from
Sep 22, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 14 additions & 14 deletions docs/api/item.md
Original file line number Diff line number Diff line change
Expand Up @@ -45,9 +45,9 @@ If a visual is required to interact with the item, such as an icon button, then
<BestPracticeFigure
text="Supporting visuals should be rendered in a consistent manner. This makes the information in each item easier to parse."
doText="Align visuals on the same side in a list"
dontText="Don't render visuals with different alignments in the same list"
doNotText="Don't render visuals with different alignments in the same list"
doImage={<img alt="A list with several items. Each item has an icon and visible text describing the item. The icon in each item is rendered at the start of the line." src={useBaseUrl('img/item/visuals-do.jpg')} />}
dontImage={<img alt="A list with several items. Each item has an icon and visible text describing the item. Some icons are rendered at the start of the line, and some icons are rendered at the end of the line" src={useBaseUrl('img/item/visuals-dont.jpg')} />}
doNotImage={<img alt="A list with several items. Each item has an icon and visible text describing the item. Some icons are rendered at the start of the line, and some icons are rendered at the end of the line" src={useBaseUrl('img/item/visuals-dont.jpg')} />}
/>

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.
Expand All @@ -63,9 +63,9 @@ The text content type includes form control labels or other visible text. This t
<BestPracticeFigure
text={<>If you find that you need a few more sentences to clarify the item's purpose, consider moving the additional sentences to a <a href={useBaseUrl('api/note')}>Note</a> 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"
doNotText="Don't try to fit long text in an item"
doImage={<img alt="A list with an item that contains a checked checkbox indicating the user wants to receive emails. Text describing how often the user will receive emails as well as how to unsubscribe from emails is placed underneath the list." src={useBaseUrl('img/item/long-text-do.jpg')} />}
dontImage={<img alt="A list with an item that contains a checked checkbox indicating the user wants to receive emails. Text describing how often the user will receive emails as well as how to unsubscribe from emails is placed as a single paragraph inline with the checkbox, making the text hard to read and increasing the height of the item." src={useBaseUrl('img/item/long-text-dont.jpg')} />}
doNotImage={<img alt="A list with an item that contains a checked checkbox indicating the user wants to receive emails. Text describing how often the user will receive emails as well as how to unsubscribe from emails is placed as a single paragraph inline with the checkbox, making the text hard to read and increasing the height of the item." src={useBaseUrl('img/item/long-text-dont.jpg')} />}
/>

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.
Expand All @@ -85,9 +85,9 @@ Metadata provides additional context for an item such as status text or counts.
<BestPracticeFigure
text="Limit the amount of metadata you include to only the most relevant information."
doText="Add only the most important metadata"
dontText="Don't add too much metadata as it can overwhelm or confuse the user."
doNotText="Don't add too much metadata as it can overwhelm or confuse the user."
doImage={<img alt="A list that contains several items, each representing a different to-do list. A count of how many tasks in each to-do list is placed at the end of each item." src={useBaseUrl('img/item/metadata-relevant-do.jpg')} />}
dontImage={<img alt="A list that contains several items, each representing a different to-do list. Two counts are placed at the end of each item: One count that states the total number of tasks, and another count that states the total number of tasks that are due today." src={useBaseUrl('img/item/metadata-relevant-dont.jpg')} />}
doNotImage={<img alt="A list that contains several items, each representing a different to-do list. Two counts are placed at the end of each item: One count that states the total number of tasks, and another count that states the total number of tasks that are due today." src={useBaseUrl('img/item/metadata-relevant-dont.jpg')} />}
/>

<BestPracticeFigure
Expand Down Expand Up @@ -115,9 +115,9 @@ Developers should avoid creating <a href="https://dequeuniversity.com/rules/axe/
<BestPracticeFigure
text={<>Actions can be added by using the <a href={useBaseUrl('api/item-sliding')}>Item Sliding</a> 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 <a href={useBaseUrl('api/item-sliding')}>Item Sliding</a> to reveal multiple actions by swiping on the Item.</>}
dontText="Don't put more than 2 actions within an Item."
doNotText="Don't put more than 2 actions within an Item."
doImage={<img alt="A list that contains several items, each representing a contact. Each item has text that states the contact's name as well as several actions including pinning the contact, sharing the contact, and deleting the contact. These actions are revealed by swiping on the item." src={useBaseUrl('img/item/actions-do.jpg')} />}
dontImage={<img alt="A list that contains several items, each representing a contact. Each item has text that states the contact's name as well as several actions including pinning the contact, sharing the contact, and deleting the contact. The actions are placed directly on the item. Since there are so many actions, some of the text is cut off." src={useBaseUrl('img/item/actions-dont.jpg')} />}
doNotImage={<img alt="A list that contains several items, each representing a contact. Each item has text that states the contact's name as well as several actions including pinning the contact, sharing the contact, and deleting the contact. The actions are placed directly on the item. Since there are so many actions, some of the text is cut off." src={useBaseUrl('img/item/actions-dont.jpg')} />}
/>

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.
Expand All @@ -133,25 +133,25 @@ Controls are form components such as checkboxes, inputs, radios, and more. Each
<BestPracticeFigure
text={<>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. <a href={useBaseUrl('api/input#filled-inputs')}>Filled Inputs</a> 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."
doNotText="Don't put metadata for inputs in the list."
doImage={<img alt="There is an email input and a password input. Both have helper text associated with them. Since both are placed outside of a list it is clear which input each helper text is associated with." src={useBaseUrl('img/item/controls-metadata-list-do.jpg')} />}
dontImage={<img alt="There is a list containing an email input and a password input. Both have helper texts associated with them. However, the divider between each item and between the helper text makes it hard to tell which input each helper text is associated with." src={useBaseUrl('img/item/controls-metadata-list-dont.jpg')} />}
doNotImage={<img alt="There is a list containing an email input and a password input. Both have helper texts associated with them. However, the divider between each item and between the helper text makes it hard to tell which input each helper text is associated with." src={useBaseUrl('img/item/controls-metadata-list-dont.jpg')} />}
/>

<BestPracticeFigure
text={<>Alternatively, the metadata can be placed in a <a href={useBaseUrl('api/note')}>Note</a> 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."
doNotText="Don't put metadata for inputs in the list."
doImage={<img alt="There are two lists of inputs. The first list contains a password input. Below that list contains text that says 'Password must be at least 16 characters'. The second list contains an email input. This second list is separated so the password length requirement text is clearly associated with the password input above." src={useBaseUrl('img/item/controls-metadata-do.jpg')} />}
dontImage={<img alt="There is one list of inputs. One of the inputs is a password input with text below the input that says 'Password must be at least 16 characters'. However, this text is placed directly above another input, so it's not immediately clear which input the text is associated with." src={useBaseUrl('img/item/controls-metadata-dont.jpg')} />}
doNotImage={<img alt="There is one list of inputs. One of the inputs is a password input with text below the input that says 'Password must be at least 16 characters'. However, this text is placed directly above another input, so it's not immediately clear which input the text is associated with." src={useBaseUrl('img/item/controls-metadata-dont.jpg')} />}
/>

<BestPracticeFigure
text={<>Items should typically have no more than two controls. If you need more controls, consider adding the additional controls in a <a href="useBaseUrl('api/modal')">Modal</a> 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."
doNotText="Don't use more than two controls within an item."
doImage={<img alt="There is one list of inputs. One of the inputs is a password input with text below the input that says 'Password must be at least 16 characters'. However, this text is placed directly above another input, so it's not immediately clear which input the text is associated with." src={useBaseUrl('img/item/controls-count-do.jpg')} />}
dontImage={<img alt="There are two lists of inputs. The first list contains a password input. Below that list contains text that says 'Password must be at least 16 characters'. The second list contains an email input. This second list is separated so the password length requirement text is clearly associated with the password input above." src={useBaseUrl('img/item/controls-count-dont.jpg')} />}
doNotImage={<img alt="There are two lists of inputs. The first list contains a password input. Below that list contains text that says 'Password must be at least 16 characters'. The second list contains an email input. This second list is separated so the password length requirement text is clearly associated with the password input above." src={useBaseUrl('img/item/controls-count-dont.jpg')} />}
/>

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.
Expand Down
24 changes: 16 additions & 8 deletions src/components/global/BestPracticeFigure/index.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,9 @@ import './best-practice-figure.css';
<BestPracticeFigure
text="..."
doText="..."
dontText="..."
doNotText="..."
doImage={<img alt="..." src={useBaseUrl(...)} />}
dontImage={<img alt="..." src={useBaseUrl(...)} />}
doNotImage={<img alt="..." src={useBaseUrl(...)} />}
/>

All images must have alt text for screen readers.
Expand All @@ -39,14 +39,22 @@ import './best-practice-figure.css';

@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 doNotText - 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 doNotImage - Image associated with doNotText
@prop cautionImage - Image associated with cautionText
*/

export default function BestPracticeFigure({ text, doText, dontText, cautionText, doImage, dontImage, cautionImage }) {
export default function BestPracticeFigure({
text,
doText,
doNotText,
cautionText,
doImage,
doNotImage,
cautionImage,
}) {
return (
<div className="best-practice__container">
<p>{text}</p>
Expand All @@ -58,12 +66,12 @@ export default function BestPracticeFigure({ text, doText, dontText, cautionText
<p>{doText}</p>
</figcaption>
</figure>
{dontText && dontImage && (
{doNotText && doNotImage && (
<figure className="best-practice__dont">
<div className="best-practice__image-wrapper">{dontImage}</div>
<div className="best-practice__image-wrapper">{doNotImage}</div>
<figcaption>
<div className="best-practice__dont-text">Don't</div>
<p>{dontText}</p>
<p>{doNotText}</p>
</figcaption>
</figure>
)}
Expand Down
Loading