diff --git a/website/docs/patterns/index.mdx b/website/docs/patterns/index.mdx index d2ec4f18..2cb6a0e0 100644 --- a/website/docs/patterns/index.mdx +++ b/website/docs/patterns/index.mdx @@ -10,7 +10,7 @@ import { Features, FeatureCard } from '@website/components'; Our patterns classify and document reusable solutions built to respond to common user scenarios. Following these guidelines allows us to create experiences that are consistent, accessible, and natural for users as they move between our digital products ensuring that our approach aligns with industry standards. - - A multiple choice question presents a question and set of predefined answer options, allowing for one answer choice submission. + + The multiple choice pattern allows the user to respond to a prompt and then provides feedback about their answer choice. diff --git a/website/docs/patterns/multiple-choice-pattern.mdx b/website/docs/patterns/multiple-choice-pattern.mdx deleted file mode 100644 index b93fd745..00000000 --- a/website/docs/patterns/multiple-choice-pattern.mdx +++ /dev/null @@ -1,195 +0,0 @@ ---- -title: Multiple Choice Pattern -description: A multiple choice question presents a question and set of predefined answer options, allowing for one answer choice submission. ---- - -import useBaseUrl from "@docusaurus/useBaseUrl"; -import { MultipleChoice, FeedbackModal } from "@wwnds/react"; -import { PropsTable } from "@website/components"; - -> A multiple choice question presents a question and set of predefined answer options, allowing for one answer choice submission. - -:::warning -This Multiple-Choice Pattern documentation has been released in Beta format. Questions or concerns? [Please let us know.](mailto:nds@wwnorton.com) -::: - -## Anatomy - -Anatomy of the Multiple Choice Pattern - -Anatomy of the Multiple Choice Pattern - -1. **Question Intro** (optional) - introductory content that helps frame the question. -1. **Question Stem** - the prompt the user responds to. -1. **Instructions** (optional) - text displaying how many attempts a user may submit an answer and instructions to how to complete a question\*, ideally located after the question stem. -1. **[Radio Button](../components/radio-group)** - an input that allows the user to select one answer and reflects the selection state. -1. **Answer Choice Identifier** - a letter or number that identifies each answer choice. -1. **Answer Choice** - a choice in response to the question stem that allows the user to select an answer. -1. **Response Indicator** (optional) - a label that signifies whether a selected response is correct or incorrect which appears next to the selected option after an answer has been submitted. -1. **Submit [Button](../components/button)** - a button that submits the chosen answer that can be located at the application level. -1. **Feedback [Modal](../components/modal)** - a modal dialog that provides feedback about the chosen answer after it is submitted. - - **a)** General Feedback - the chosen answer and whether it is correct or incorrect 1. Supplementary Feedback (optional) - additional answer-specific content - - **b)** Supplementary Feedback (optional) - additional answer-specific content - -## Usage - -- Multiple choice questions only have one correct answer, and use radio buttons (not buttons or dropdowns) to display answer choices. - - **Why:** The consistent use of radio buttons for answer choices, though beneficial for all users, has particular accessibility benefits: - Screen reader users know when they encounter radio buttons that they can only make one choice. - Since screen magnification users experience smaller portions of the screen at once,  they benefit from the visual consistency of always using radio buttons for answer choices. - For users who experience difficulty with attention and working memory, cognitive load is reduced when the same component is encountered repeatedly. See the [Accessibility Notes](#accessibility-notes) section for more information on how consistent navigation benefits users with disabilities. - -- Limit _answer choices_ to a maximum of 5. - - **Why:** Too much content can cause cognitive overload, loss of focus, and anxiety for students with disabilities, i.e. those with processing, attention, or working memory challenges. - -- Feedback should be delivered in a modal after the answer is submitted, as opposed to in-line.\* - - **Why:** In-line feedback presents challenges for many users: - Screen magnification users may miss that the screen content changed. - In-line feedback can make the screen visually overwhelming and increase cognitive load reducing the user's ability to gain the information intended by the in-line feedback. - Implementing in-line feedback presents challenges for screen reader users because you have to manage focus in ways that are unanticipated. See the [Accessibility Notes](#accessibility-notes) section for more information on the impact of in-line feedback on users with disabilities. - -- If more than one attempt is available, this should be clearly defined in the Instructions. The limit and the number of attempts they’ve already made should be indicated to the user. - - **Why:** Transparency and clear expectations are important to ensure all users can complete the task to the best of their ability. It would be frustrating for a user to find out there was a limit only after they reached it. - -- Provide clear instructions on how to complete a question. - - **Why:** Providing clear instructions to users on how to complete the question is key to ensure all users can complete the assigned task. - -- Multiple choice questions require a submit button either at the end of the answer choices or at the platform level. Selecting a response should never trigger a submit action. - - **Why:** Radio buttons are meant to make a selection only, not to submit an answer. For users with disabilities, the use of a submit button is anticipated and gives them control over when their context changes. - -:::danger Don't -Don’t use color alone for signifying correct and incorrect answers. INSTEAD include a visible “correct” or “incorrect” label for [response indicators](../components/response-indicator). - - **Why:** Users who can’t differentiate colors, such as colorblind users or those with visual impairments, won’t know which color is correct or incorrect. All users must have access to the same information. - - Text is the only way to guarantee that the meaning of the response indicator will be understood by all users. This supports low-vision users, English language learners, and those with cognitive disabilities. - -::: - -:::danger Don't -Don’t use dropdowns within multiple choice questions. INSTEAD use a [radio button](../components/radio-group). - - **Why:** Using a component like a dropdown doesn’t signal to the user that they can make only one choice and increases cognitive load by hiding answer choices. *Anticipated behavior by using the same design/consistency. - -::: - -## Content Guidelines - -- Question stems should be kept as brief as possible. - - **Why:** Clear and concise language ensures that all users understand what they are being asked to do. - -- Each answer option should be preceded by a corresponding letter or number, with a few exceptions (where the answer label could be confused with part of the answer choice). - - - The format of the answer label should be applied consistently throughout all multiple choice questions in an application. - - **Why:** This allows users to reference the option they’ve selected without reading the full answer text and allows users to easily differentiate between answer choices. For users who experience difficulty with attention and working memory, cognitive load is reduced when the same component is encountered repeatedly. - -- Answer-specific feedback should be concise and text-only is recommended. Refer to the [Accessibility Notes](#accessibility-notes) when including imagery or other media is necessary. - - **Why:** Users are less likely to consume the content if there’s too much of it, thus defeating the purpose of giving feedback. - -## Accessibility Notes - -This section expands on the design decisions and considerations made to ensure an inclusive and accessible experience for all users. - -### Inline Feedback - -Relying solely on in-line feedback can present challenges for users with disabilities for the following reasons: - -- Easily missed by users utilizing screen magnification: In-line feedback, particularly subtle visual cues or color changes, may become too small to notice when content is magnified. This can make it difficult for users relying on screen magnification to perceive and interpret the feedback, potentially leading to confusion or incomplete understanding. -- Limited perceptual cues in complex interfaces: In-line feedback, especially in interfaces with a lot of visual elements or complexity, may be too subtle for users with visual impairments or cognitive disabilities. These users may require more prominent or distinct cues to effectively grasp and comprehend the feedback provided. -- Potential Challenges in Screen Reader Navigation and Perception of In-Line Feedback: Screen reader users rely on auditory feedback to navigate interfaces. If they are not anticipating in-line feedback to appear, they may miss the alert or cue from the screen reader, resulting in a potential loss of understanding about the feedback's presence and location. - -### Alternative to Including Images or Other Media in Answer-Specific Feedback - -When possible, it is advisable to redirect students to relevant content in their eBook rather than embedding media or imagery within the feedback modal, as this approach enhances accessibility. However, if images or media are deemed absolutely essential, they must meet the following criteria: - -- **No Two-Way Scrolling:** In order to enhance accessibility, feedback should not require two-way scrolling, especially for screen magnification users. This restriction helps reduce cognitive load and completion time for all students. -- **No Color-Dependent Information:** It is strictly prohibited to use color alone in images or media to communicate information. This ensures accessibility for users with color blindness or other visual impairments. -- **Color Contrast Requirements:** Ensure that any images used are compliant with color contrast requirements, as they serve as informative elements rather than decorative features. -- **Alternative Text (Alt Text):** All images within feedback must have informative alt text to facilitate accessibility for users who rely on screen readers. -- **Embedded Media Caution:** It is generally discouraged to embed other media types in feedback. If required, follow these guidelines: - - **Labeling Controls:** Ensure all controls for embedded media are properly labeled. - - **WCAG 2.1 AA Compliance:** Embedded media (audio or video) should meet WCAG 2.1 AA requirements, including: - - Audio descriptions or descriptive transcripts for video content. - - Closed captions for audio or video content. - - Visible labels for any media player controls. - - Compliance with other relevant WCAG criteria. - -## React Implementation Example - -The following example demonstrates how to implement the Multiple Choice Pattern in a React application. - -A live demo can be found in the storybook for the Multiple Choice Pattern. - -```tsx -import React, { useCallback } from "react"; -import { - useMultipleChoice, - MultipleChoice, - FeedbackModal, - Button, -} from "@wwnds/react"; - -const choices = [ - "Jayvon, who had opened a checking account at the branch that same day", - "Ibrahim, who is taking propranolol to control his blood pressure", - "Huong, who was born with Urbach-Wiethe syndrome and lacks an amygdala", -]; - -export function PatternExample() { - const { questionState, setStatus, modalState } = useMultipleChoice(choices); - - const handleSubmit = useCallback( - (event: React.FormEvent) => { - event.preventDefault(); - - if (questionState.selected === 1) { - setStatus("correct"); - } else { - setStatus("incorrect"); - } - }, - [setStatus, questionState.selected] - ); - - return ( -
- - -
- -
- - ); -} -``` - -### useMultipleChoice Hook - -The `useMultipleChoice` hook is used to manage the state of the multiple choice question. It accepts an array of answer choices and returns the state shared by the `FeedbackModal` and `MultipleChoice` components. - -### MultipleChoice Component - -The `MultipleChoice` component is used to render the multiple choice question. It accepts the following props: - - - -### FeedbackModal Component - -The `FeedbackModal` component is used to render the feedback modal. It accepts the following props: - - diff --git a/website/docs/patterns/multiple-choice.mdx b/website/docs/patterns/multiple-choice.mdx new file mode 100644 index 00000000..60a1d1e1 --- /dev/null +++ b/website/docs/patterns/multiple-choice.mdx @@ -0,0 +1,203 @@ +--- +title: Multiple Choice +description: The multiple choice pattern allows the user to respond to a prompt and then provides feedback about their answer choice. +beta: true +--- + +import useBaseUrl from "@docusaurus/useBaseUrl"; +import { Badge, MultipleChoice, FeedbackModal } from "@wwnds/react"; +import { PropsTable } from "@website/components"; + +> The multiple choice pattern allows the user to respond to a prompt and then provides feedback about their answer choice. + +:::warning +Beta This pattern is still a work in progress. Questions or concerns? [Please let us know](mailto:nds@wwnorton.com). +::: + +## Anatomy + +The Multiple Choice pattern contains two views that are presented sequentially in the user flow: + +1. A [question](#question) view, where the user responds to a prompt by selecting an answer and then submitting it. + Submitting a response immediately opens the feedback view. +2. A [feedback](#feedback) view, where the user learns whether they answered correctly and is presented with additional feedback about their answer. + Closing the feedback returns the user to the response view. + +### Question + +The question view presents a prompt to the user, allowing them to select and then submit their answer. +Once submitted, the [feedback](#feedback) view appears. + +![The question anatomy shows various elements, annotated with numbers that correspond to the following anatomy description.](/img/mc_anatomy_question.png) + +1. **Question Framing** (_optional_) - introductory content that provides additional context for the question. + This can include any type of content, including but not limited to text, images, and video. +1. **Question Stem** - the text-only prompt. Answer choices are responses to the question stem. +1. **Functional Instructions** (_optional_) - the constraints for answering the question. + Unlike the stem and framing, this should not contain subject matter related to the question. +1. **Answer Choice** - an option that answers the question. + 1. **Selector** - a [radio button](/docs/components/radio-group) that indicates which choice is currently selected and will be submitted. + 1. **Identifier** - a letter or number that identifies the choice. + 1. **Response** - an answer that relates directly to the question stem. + 1. **Response Indicator** (_only visible after submission_) - a label that signifies whether a submitted response was correct or incorrect. + Once visible, the answer choice can no longer be selected. +1. **Submit Button** - a [button](/docs/components/button) that submits the chosen answer. + +### Feedback + +Feedback is presented in a [modal dialog](/docs/components/modal) after the user has submitted an answer. +Once closed, the user should be returned to the [question](#question) view. + +![The feedback anatomy shows a modal dialog, annotated with numbers that correspond to the following anatomy description.](/img/mc_anatomy_feedback.png) + +1. **Title** - the title should summarize the result of the user's submission in as few words as possible. +1. **General Feedback** - the answer that the user submitted and whether it is correct or incorrect. +1. **Supplementary Feedback** (_optional_) - additional answer-specific content. + +## Design Guidelines + +Following these guidelines will help us create a more consistent experience of multiple choice questions throughout Norton products. + +### Display the stem and answer choices in the same view + +The question stem and its corresponding answer choices should be viewable together, rather than presenting them in separate views or requiring the user to scroll to view them together. + +{/* TODO: add image */} + +:::note Why? +Multiple choice requires the user to hold the question stem in their working memory in order to choose a corresponding response. +This can be difficult for us when we experience impairment of our working memory, such as when we're tired or if we've had a traumatic brain injury. +Displaying the responses in a different view from the question stem unnecessarily compounds this cognitive task. +::: + +### Provide no more than 5 answer choices + +We've chosen 5 as the Norton Design System's preferred limit for most cases, but this depends heavily on the amount of information in the stem and answer choices. + +{/* TODO: add image */} + +:::note Why? +To answer a multiple choice question, we must hold the question stem and all of the answer choices in our working memory. +The more answer choices there are, the more difficult this becomes. + +If we have a disability that impairs our working memory or are experiencing a temporary impairment of our working memory, this may prevent us from even being able to answer the question. + +A complex question stem will contribute to this as well, which is why we also recommend [keeping the stem brief](#keep-the-stem-and-instructions-brief). +::: + +### Deliver answer feedback in its own view + +When feedback is displayed directly in the question view, it's impossible to guarantee that the user will notice it or absorb it. +The Norton Design System has chosen to use our [modal](/docs/components/modal) for feedback in order to bring focus to it. + +{/* TODO: add image */} + +:::note Why? +Absorbing feedback on our answer choice is critical for an effective multiple choice question. +Displaying it in the question view makes this difficult in many ways. + +- The question view is already visually and cognitively dense. +Adding feedback to this view can disorient, distract, and overwhelm users, preventing them from absorbing it or potentially missing it entirely. +- Modal dialogs are the ideal way to directly bring attention to feedback for everyone, including users of assistive technology. +::: + +### Keep the stem and instructions clear and brief + +Both the question stem and the functional instructions give question authors a space to outline requirements for answering the question. +These should follow the rule of [accurate, clear, brief (in that order)](/docs/guides/usable-writing-guidelines#accurate-clear-brief-in-that-order) + +:::note Why? +Complex, unclear, or long text will add extraneous cognitive load to an already information-dense question. +We want users to spend their brain power answering the question. +::: + +### Always use visible text for answer choice feedback + +Avoid using icons or color alone to convey whether the response was correct or incorrect. +Text is the only way to guarantee that the meaning will be understood by all users. + +This supports low-vision users, English language learners, and users with cognitive disabilities. + +:::note Why? +Users who can't differentiate colors, such as colorblind users or those with visual impairments, won't know which color is correct or incorrect. +All users must have access to the same information. +::: + +### Use a consistent answer choice identifier + +The Norton Design System allows answer choice identifiers to be Roman numerals, numbers, or letters to suit the needs of the application. +Avoid mixing these across the same set of questions. + +:::note Why? +A consistent way to reference responses across questions ensures that we don't have to mentally switch from a familiar pattern. +This is especially critical for users who experience difficulty with attention and working memory. +::: + + +A live demo can be found in the storybook for the Multiple Choice Pattern. + +```tsx +import React, { useCallback } from "react"; +import { + useMultipleChoice, + MultipleChoice, + FeedbackModal, + Button, +} from "@wwnds/react"; + +const choices = [ + "Jayvon, who had opened a checking account at the branch that same day", + "Ibrahim, who is taking propranolol to control his blood pressure", + "Huong, who was born with Urbach-Wiethe syndrome and lacks an amygdala", +]; + +export function PatternExample() { + const { questionState, setStatus, modalState } = useMultipleChoice(choices); + + const handleSubmit = useCallback( + (event: React.FormEvent) => { + event.preventDefault(); + + if (questionState.selected === 1) { + setStatus("correct"); + } else { + setStatus("incorrect"); + } + }, + [setStatus, questionState.selected] + ); + + return ( +
+ + +
+ +
+ + ); +} +``` + +### useMultipleChoice Hook + +The `useMultipleChoice` hook is used to manage the state of the multiple choice question. It accepts an array of answer choices and returns the state shared by the `FeedbackModal` and `MultipleChoice` components. + +### MultipleChoice Component + +The `MultipleChoice` component is used to render the multiple choice question. It accepts the following props: + + + +### FeedbackModal Component + +The `FeedbackModal` component is used to render the feedback modal. It accepts the following props: + + diff --git a/website/sidebars.js b/website/sidebars.js index 29f43c57..ac8fb974 100755 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -54,7 +54,12 @@ const sidebars = { "components/tooltip", "components/react-providers", ], - patterns: ["patterns/index", "patterns/multiple-choice-pattern"], + patterns: [ + { + type: "autogenerated", + dirName: "patterns", + }, + ], }; module.exports = sidebars; diff --git a/website/static/img/mc_anatomy_feedback.png b/website/static/img/mc_anatomy_feedback.png new file mode 100644 index 00000000..dd96362f Binary files /dev/null and b/website/static/img/mc_anatomy_feedback.png differ diff --git a/website/static/img/mc_anatomy_question.png b/website/static/img/mc_anatomy_question.png new file mode 100644 index 00000000..a1844f29 Binary files /dev/null and b/website/static/img/mc_anatomy_question.png differ diff --git a/website/static/img/multiple-choice-anatomy.png b/website/static/img/multiple-choice-anatomy.png deleted file mode 100644 index 1cf762f3..00000000 Binary files a/website/static/img/multiple-choice-anatomy.png and /dev/null differ