docs: Add back old UX Writing docs into SB8

README.md

@@ -1,7 +1,5 @@
 # Gamut
 
-// Storybook 8 branch
-
 _The component library & design system for Codecademy._ ✨
 
 ---

packages/styleguide/.storybook/components/Navigation/TableOfContents.tsx

@@ -10,6 +10,7 @@ type PageLink = {
   status?: 'current' | 'updating' | 'deprecated' | 'static';
   subtitle: string;
   title: string;
+  href: string;
 };
 
 export const TableOfContents: React.FC<{ links: PageLink[] }> = ({ links }) => {

packages/styleguide/.storybook/preview.ts

@@ -28,6 +28,7 @@ const preview: Preview = {
           'Typography',
           'Atoms',
           'Molecules',
+          'Organisms',
           '*',
         ],
       },

packages/styleguide/src/lib/Molecules/Alert/Alert.mdx

@@ -37,7 +37,7 @@ Use an alert to display an important, succinct message with actions for users to
 - Form field validation– for inline form errors or validation messages, use inline messaging within the form fields instead of an alert.
 
 ## Anatomy
-<ImageWrapper src="./alertAnatomy.png" alt="Alert Anatomy diagram"/>
+<ImageWrapper src="./molecules/alertAnatomy.png" alt="Alert Anatomy diagram"/>
 
 1. Icon
 - Automatically displays for the selected alert type: general, success, error, or subtle

packages/styleguide/src/lib/UX Writing/Accessibility guidelines.mdx

@@ -0,0 +1,115 @@
+import { Meta } from '@storybook/blocks';
+
+import { AboutHeader } from '~styleguide/blocks';
+
+
+export const parameters = {
+  title: "Accessibility guidelines",
+  subtitle: 'In order for content to be accessible, it must be perceivable, operable, understandable, and robust.',
+  status: 'static',
+};
+
+<Meta title="UX Writing/Accessibility guidelines" />
+
+<AboutHeader {...parameters} />
+
+## The 4 principles of accessibility
+
+The World Wide Web Consortium (W3C) is the Internet's main international standards organization. W3C maintains a set of guidelines for web accessibility. The most up-to-date version of W3C's Web Content Accessibility Guidelines is [WCAG 2.2](https://www.w3.org/TR/WCAG22/).
+
+The Web Content Accessibility Guidelines contain 4 principles for creating accessible content. Understanding these 4 principles is key to understanding how to write accessible content.
+
+### 1. Perceivable
+
+Information on-screen must be perceivable to blind, deaf, low-vision, or color-blind learners.
+
+- Include meaningful and unique alt text for all non-decorative images or icons
+- Don't rely on visuals for words to make sense
+- If text is meant to be read, include it as text and not an image
+- Include captions for video and audio content
+
+### 2. Operable
+
+Content should be easy for users to navigate and find what they're looking for. Touch and click targets should be easy to hit and content should be accessible with a screen reader.
+
+- Make hyperlink text long enough that it's easy to hover over and click
+- Use meaningful, unique, and descriptive CTAs
+- Avoid ambiguous link text like "Click here" or "Read more"
+- If more than one label contains the same text, clarify with screen-reader-only text
+- Write so that labels, tooltips, and input fields appear in a logical order
+- Avoid directional language like "above" or "below"
+- Ensure users have enough time to read text
+
+### 3. Understandable
+
+Content should be easy to understand. Plus, it should appear and operate in predictable ways.
+
+- Use H1, H2, H3 headings correctly and consistently ([Learn more about headings](https://www.notion.so/Headings-be907c4d24c84dffb970cedc3ee54936))
+- Check to ensure copy is at a 7th-grade reading level or below
+- Use short, clear sentences and paragraphs
+- Avoid jargon, slang, and idioms
+- Expand acronyms on first use
+- Use list formatting when appropriate
+
+### 4. Robust
+
+- Write in a way that's platform-agnostic (i.e. select or choose vs. tap or click)
+
+### Bonus: Meaningful
+
+You'll find the word "meaningful" used a lot in guidance for writing for accessibility. So we're taking the opportunity to throw in a quick definition of what we mean when we use it.
+
+Meaningful text is useful text. It provides the full context a user needs to understand a situation.
+
+Meaningful alt text describes what's important about an image a user can't see. Meaningful button text clearly where a link will go. It avoids ambiguous standalone phrases like "click here" or "read more."
+
+## Accessible content checklist
+
+### Alt text
+- Is alt text included for all non-decorative images on the page?
+- Does your alt text provide all the information a user needs to understand what the image is being used to convey?
+
+### Buttons
+- Is CTA text meaningful? Is it clear where clicking will take the user?
+- If there is more than one button on the page, is the text for each button unique?
+- If each button is not unique, have you provided screen-reader-only text to clarify?
+
+### Headings
+- Does your page include a single, unique H1 title?
+- Are H2 and H3 headings used correctly and consistently?
+
+
+
+### Hyperlinks
+- Is link text meaningful? Is it clear where clicking will take the user?
+- Are hyperlinks long enough (2-3 words) to be easy to click on?
+- If there is more than one hyperlink on the page, is the text for each link unique?
+- If each hyperlink is not unique, have you provided screen-reader-only text to clarify?
+
+
+### Imagery
+- Do all non-decorative images or icons contain[alt text](https://skillsoftdev.atlassian.net/wiki/spaces/265f8fcabee0479ea6841c6b0b7e2171/pages/4440883349/Alternate+alt+text)?
+- Does the alt text provide all the information a user needs to understand what the image is being used to
+- Are all words understandable without reliance on imagery?
+
+
+### Readability
+- Do users have enough time to read the text?
+- Is your copy at a reading level of grade 7 or below? Test with [Hemingway App](https://hemingwayapp.com).
+- Are sentences and paragraphs short and clear?
+- Is your content free of jargon, slang, and idioms?
+- Have you used list formatting when appropriate?
+- Do users have enough time to read the text?
+
+### Screenreader compatibility
+- Does text appear in chronological order?
+- Are headings used correctly and appropriately?
+- Have you avoided directional language (i.e. "the form on the right" or "in the section below")?
+- Is the language platform-agnostic?
+- Have you passed the buttons, headings, hyperlinks, imagery, and readability checklists?
+
+
+### Video and audio content
+- Are captions included for all audio and video content?
+- For video, do the captions match what's happening on-screen?
+- For audio, are transcripts available?

packages/styleguide/src/lib/UX Writing/Component guidelines/Alerts.mdx

@@ -0,0 +1,76 @@
+import { Alert, Text } from '@codecademy/gamut/src';
+import { Meta } from '@storybook/blocks';
+
+import { AboutHeader, LinkTo } from '~styleguide/blocks';
+
+
+export const parameters = {
+  title: "Alerts",
+  subtitle: 'Make clear what you’re alerting the user to. Then, clarify any next steps they need to take or inform them about the timing of a resolution on our end.',
+  status: 'static',
+};
+
+<Meta title="UX Writing/Component guidelines/Alerts" />
+
+<AboutHeader {...parameters} />
+
+
+
+
+Alerts are used to display important information and, if relevant, provide relevant actions the learner needs to take to resolve the alert.
+
+Alerts are similar to <LinkTo id="UX Writing/Component guidelines/Error messages">error messages</LinkTo>, but the approach is slightly different. An error message informs users of **what went wrong** and **how to proceed**, but with an alert nothing has gone wrong _yet_.
+
+Alerts should make clear **what the issue or information is** and **how to proceed**. In the event of an alert, the user might need to take action to proceed _or_ they may simply need to be informed that _we_ will be taking action within a specific timeframe.
+
+## Examples
+
+<br />
+
+<Alert type="general" cta={{ children: 'Resend verification' }} mx={0} >
+  <Text> Please verify your email so we can make sure your account is secure. A link
+  has been sent to name@email.com. </Text>
+</Alert>
+
+<br />
+
+<Alert type="success" cta={{ children: '' }}>
+  <Text>Success! Your content has been assigned.</Text>
+</Alert>
+
+<br />
+
+<Alert type="error" cta={{ children: '' }}>
+  <Text>We were unable to add this team member. Please refresh the page and try again.</Text>
+</Alert>
+
+<br />
+
+<Alert type="notice" cta={{ children: 'Learn more' }}>
+  <Text>Maintenance: Codecademy will be offline between 2AM and 4AM EST.</Text>
+</Alert>
+
+<br />
+
+<Alert type="feature" cta={{ children: 'Add your name' }}>
+  <Text>Update your profile with your name to help your team with account management.</Text>
+</Alert>
+
+<br />
+
+## Best practices
+
+- **Start with the full context in mind.** Your goal is to alert the learner without frustration. That's why, before you start writing, you'll need to know answers to the following questions:
+  1. What will a learner be trying to do when this alert appears?
+  2. What might happen if the learner doesn't receive the information in this alert?
+  3. Does the learner need to take action to remove the alert?
+  4. If the learner can't resolve the alert on their own, what information can we provide so they know what to expect?
+- **Explain and clarify how to proceed.** Inform learners of the issue or information (explain) and let them know how to proceed. For example, we may alert learners that they need to verify their email address before they can update their profile. If there is no way for them to proceed, don't just leave them hanging. For instance, if the site has scheduled downtime, let them know when it will be back up. If more information is needed, prompt them to contact customer support or share a link to an FAQ where they can learn more.
+- **Write in a conversational style.** Oftentimes, alerts end up sounding robotic. Instead of writing like a computer, write like a human. Before you start writing, try explaining things to yourself or someone else out loud. This practice can help you figure out how to write the alert in a more human way.
+- **Front-load the most important information.** While our alert component allows for multiple lines of text, we truncate after the first line and users can expand to see the full message.
+
+## Checklist
+- Does the alert explain the information or issue clearly?
+- If relevant, have you explained what the user can do to resolve the alert or what we're doing on our end?
+- Is important information front-loaded?
+- Have you asked someone unrelated to the project to read the message and did they understand it?

packages/styleguide/src/lib/UX Writing/Component guidelines/Bell notification.mdx

@@ -0,0 +1,27 @@
+import { Meta } from '@storybook/blocks';
+
+import { AboutHeader } from '~styleguide/blocks';
+
+export const parameters = {
+  title: "Bell notification",
+  subtitle: 'Keep it brief (<86 characters), make it actionable, and ensure the messaging is in support of the learner’s journey.',
+  status: 'static',
+};
+
+<Meta title="UX Writing/Component guidelines/Bell notification" />
+
+<AboutHeader {...parameters} />
+
+Bell notifications let us share CTAs relevant to a learner’s personal experience. This includes things like changes to a course a learner is taking, responses to a forum post they wrote, or other calls to action that support their learning journey.
+
+## Best practices
+
+- **Notifications are personal.** Bell notifications should be used to surface calls to action that are relevant to a learner’s personal experience.
+- **Notifications support focused learning.** Bell notifications should notify learners about information in support of their learning journey. They should not be a deterrent or distractor to that learning. The messaging should be relevant to the interactions, content, goals, and interests of the individual learner.
+- **Notifications are actionable.** All notifications should have a personalized, clickable action. Use a bell notification only when there is a relevant action to take. Otherwise, opt for a different communication channel.
+- **Notifications are brief messages.** Notifications should be no longer than 86 characters (max. 3 lines). Unless otherwise specified — or directly removed by the learner — a notification should disappear after 30 days.
+
+## Checklist
+- Does the notification include an action for the learner to take?
+- Is the action clear?
+- Is the notification copy 86 characters or less?

packages/styleguide/src/lib/UX Writing/Component guidelines/Button and links.mdx

@@ -0,0 +1,52 @@
+import { Meta } from '@storybook/blocks';
+
+import { AboutHeader } from '~styleguide/blocks';
+
+export const parameters = {
+  title: "Button and links",
+  subtitle: 'Be specific, use action-oriented language, and emphasize value. Keep to 3 words or less (unless necessary for clarity), and use sentence case.',
+  status: 'static',
+  design: {
+    type: 'figma',
+    url:
+      'https://www.figma.com/file/P3dOOeVfZGjIfjupKdrZ7j/UX-Writing-Best-Practices?node-id=306%3A2424',
+  },
+};
+
+<Meta title="UX Writing/Component guidelines/Button and links" />
+
+<AboutHeader {...parameters} />
+
+
+Buttons and links enable our learners to "speak" to us. They click to tell us what they want (i.e. to "Start my free trial" or to "Resume learning") and we respond with the anticipated next step.
+
+## Best practices
+
+When approaching writing buttons — whether they're text buttons, fill buttons, or call-to-action buttons — here are a few things to keep in mind:
+
+- **Be specific.** People should know exactly what they're getting when they click on a link or button. If a button or link leaves you questioning what will happen when you click on it, adjust the copy to make it more clear. Specificity also plays a big role in ensuring accessibility for learners navigating our content with screen readers.
+- **Use action-oriented language.** Start with an action-oriented verb rather than simply listing where the button will take you (i.e. Use "Take the quiz" instead of "Language quiz").
+- **Emphasize the value people get, rather than how they get it.** When relevant, focus on the benefit/what people are receiving instead of the way they are receiving it. For instance, instead of "Download for free" try "Get the free guide."
+- **When in doubt, A/B test!** Buttons — specifically call-to-action (CTA) button copy can have a major impact on conversion. If you're undecided about which CTA is best, test — especially for high-impact projects.
+
+### Fill buttons
+
+- **Length:** Keep to a maximum of 3 words (unless more words are necessary for clarity).
+- **Capitalization:** Use sentence case, capitalizing only proper nouns.
+
+### Text buttons
+
+- **Length:** Keep to a maximum of 3 words (unless more words are necessary for clarity).
+- **Capitalization:** Use sentence case, capitalizing only proper nouns.
+- **Arrow usage:** Include → after the text when clicking brings users to a new surface. There should always be a space between the text and the arrow.
+
+### CTA buttons
+
+- **Length:** Keep to a maximum of 3 words (unless more words are necessary for clarity).
+- **Capitalization:** Use sentence case, capitalizing only proper nouns.
+
+## Checklist
+- For buttons, is your copy 3 words or less?
+- For buttons, have you used action-oriented language?
+- Have you used sentence case, only capitalizing proper nouns?
+- Does the copy make it clear where the link will take learners?

packages/styleguide/src/lib/UX Writing/Component guidelines/Confirmation dialogs.mdx

@@ -0,0 +1,54 @@
+import { Meta } from '@storybook/blocks';
+
+import { AboutHeader, LinkTo } from '~styleguide/blocks';
+
+export const parameters = {
+  title: "Confirmation dialogs",
+  subtitle: 'Simplify the language, prioritize the message, and make sure the implication of what learners are saying "Yes" (or "No") to is crystal clear.',
+  status: 'static',
+  design: {
+    type: 'figma',
+    url:
+      'https://www.figma.com/file/P3dOOeVfZGjIfjupKdrZ7j/UX-Writing-Best-Practices?node-id=306%3A2425',
+  },
+};
+
+<Meta title="UX Writing/Component guidelines/Confirmation dialogs" />
+
+<AboutHeader {...parameters} />
+
+Confirmation dialog boxes are used to verify that a learner wants to take a specific action. They are generally used for actions that are irreversible, may result in critical consequences or loss of data, have other severe consequences, or happen infrequently.
+
+They use the <LinkTo id="Molecules/Modals/Dialog">Dialog component in Gamut</LinkTo> and, for actions with serious or irreversible consequences, the `Danger` variant should be used.
+
+## Best practices
+
+### Headline
+
+- **Ask or inform about one main action**, clearly and simply.
+- **Frame your headline as a binary question**, when possible, with 2 unambiguous answers (i.e. Yes/No, Stay/Leave).
+- **Be specific.** Instead of "Are you sure?" focus on what you want to ensure they're sure about (i.e. "Reset your progress?" or "Delete the file?").
+
+### Explanation
+
+- **Share only relevant information** that may help the learner make their decision.
+- **Avoid redundancy.** If you've already set the stage in your headline, there's no need to re-ask the same question in your explanation. If the explanation doesn't add anything new, leave it out (i.e. "Permanently delete this item? Yes/No").
+- **Avoid filler.** Questions like "Are you sure you want to \_\_\_?" take up space, increase cognitive load, and may undermine users' confidence or be interpreted as patronizing.
+- **Keep to 1-2 lines**, unless more is required to get all the information across.
+
+### Button copy
+
+- **Options should be clear and distinct.** Each option should be distinctly different and there should be no opportunity for learners to mix them up (i.e. "Delete" and "Cancel" are ambiguous choices whereas "Yes, remove" and "Cancel" clear up the confusion.
+- **Add context to reaffirm the action.** Instead of "Yes," use "Yes, reset progress."
+- **Match the verb in your headline.** If you use "Save" in your headline, use "Save" in your button copy, rather than keep. Consistency helps keep the message clear. All of this should also match whatever the learner clicked on that triggered the confirmation dialog.
+
+## Checklist
+- Is the language consistent from the wording on the button that opened the confirmation box, to the headline,
+- Does the headline make the action clear?
+- Is the headline framed as a question, if possible?
+- Does the explanation provide relevant details and consequences of the action?
+- Is the explanation 1-2 lines long?
+- Are the words on the buttons clear and distinct?
+- Do the buttons include context to reaffirm the action?
+- Is your copy at a reading level of grade 7 or below? Test with [Hemingway App](https://hemingwayapp.com).
+- Have you asked someone unrelated to the project to read the message and did they understand it?