Skip to content

Commit 1ad5e9c

Browse files
LinKCodingLinKCoding
committed
Merge branch 'main' into kl-gm-861
2 parents ae3e7ba + 675415a commit 1ad5e9c

File tree

19 files changed

+682
-27
lines changed

19 files changed

+682
-27
lines changed

‎README.md‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,5 @@
11
# Gamut
22

3-
// Storybook 8 branch
4-
53
_The component library & design system for Codecademy._ ✨
64

75
---

‎packages/styleguide/.storybook/preview.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,11 @@ const preview: Preview = {
2828
'Typography',
2929
'Atoms',
3030
'Molecules',
31+
'Organisms',
32+
'UX Writing',
33+
['About', 'DIY UX writing in 8 steps', 'Accessibility guidelines', 'Component guidelines',
34+
['About', 'Alerts', 'Alternative text', 'Buttons', 'Confirmation dialogs', 'Error messages', 'Notifications', 'Toasts', 'Tooltips',]
35+
],
3136
'*',
3237
],
3338
},

‎packages/styleguide/AboutHeader.tsx‎

Lines changed: 0 additions & 23 deletions
This file was deleted.

‎packages/styleguide/CHANGELOG.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,10 @@
33
All notable changes to this project will be documented in this file.
44
See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
55

6+
### [68.3.3](https://github.com/Codecademy/gamut/compare/@codecademy/styleguide@68.3.2...@codecademy/styleguide@68.3.3) (2025-01-13)
7+
8+
**Note:** Version bump only for package @codecademy/styleguide
9+
610
### [68.3.2](https://github.com/Codecademy/gamut/compare/@codecademy/styleguide@68.3.1...@codecademy/styleguide@68.3.2) (2024-12-17)
711

812
**Note:** Version bump only for package @codecademy/styleguide

‎packages/styleguide/package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"name": "@codecademy/styleguide",
33
"description": "Styleguide & Component library for codecademy.com",
4-
"version": "68.3.2",
4+
"version": "68.3.3",
55
"author": "Codecademy Engineering",
66
"license": "MIT",
77
"publishConfig": {

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,7 @@ Use an alert to display an important, succinct message with actions for users to
3737
- Form field validation– for inline form errors or validation messages, use inline messaging within the form fields instead of an alert.
3838

3939
## Anatomy
40-
<ImageWrapper src="./alertAnatomy.png" alt="Alert Anatomy diagram"/>
40+
<ImageWrapper src="./molecules/alertAnatomy.png" alt="Alert Anatomy diagram"/>
4141

4242
1. Icon
4343
- Automatically displays for the selected alert type: general, success, error, or subtle

‎packages/styleguide/src/lib/UX Writing/About.mdx‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
import { Meta } from '@storybook/blocks';
2+
3+
import { AboutHeader, TableOfContents } from '~styleguide/blocks';
4+
5+
export const parameters = {
6+
id: 'UX Writing',
7+
title: 'UX Writing',
8+
subtitle: 'Help learners find success by surfacing the right copy and content to the right people at the right time.',
9+
}
10+
11+
<Meta title='UX Writing/About' />
12+
13+
<AboutHeader {...parameters} />
14+
15+
Words are powerful tools that can help us achieve our mission of empowering inspiring careers in technology. When we surface the right words and content to the right people at the right time, we help learners reach their goals. When our learners are successful, so are we.
16+
17+
In the following pages, you’ll find a collection of tips and tools for writing effective product copy on your own. Need a little help? [Submit a UX writing request here.](https://skillsoftdev.atlassian.net/wiki/spaces/UXW/database/4482760850?savedViewId=6f9f7fdc-f2b8-4746-b99b-689d804c979b)
18+
19+
## Pages
20+
21+
<TableOfContents
22+
links={[
23+
{
24+
id: 'UX Writing/DIY UX writing in 8 steps',
25+
subtitle: 'Follow these steps to write clear, useful UI copy.',
26+
title: 'DIY UX writing in 8 steps',
27+
},
28+
{
29+
id: 'UX Writing/Accessibility guidelines',
30+
subtitle: 'In order for content to be accessible, it must be perceivable, operable, understandable, and robust.',
31+
title: 'Accessibility guidelines',
32+
},
33+
{
34+
id: 'UX Writing/Component Guidelines/About',
35+
subtitle: 'Get up to speed on best practices for writing for user interfaces, including guidance for writing for specific components in Gamut.',
36+
title: 'Component Guidelines',
37+
},
38+
]}
39+
/>
40+
41+
<br />
42+
43+
## Resources
44+
45+
### External Tools & Resources:
46+
47+
🖍 **[Hemingway App](https://hemingwayapp.com/):** Tool for checking copy for grade level and readability
48+
49+
⬆️ **[Capitalize My Title](https://capitalizemytitle.com/style/AP/):** Paste in any title to properly capitalize (use AP style)
50+
51+
📚 **[The UX Writing Library](https://www.uxwritinglibrary.com/):** Massive compilation of UX writing tools and resources
52+
53+
💅 **[Polish](https://www.producthunt.com/posts/polish):** Browser extension that lets you edit the text on any website
54+

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

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
import { Meta } from '@storybook/blocks';
2+
3+
import { AboutHeader, LinkTo } from '~styleguide/blocks';
4+
5+
6+
export const parameters = {
7+
title: "Accessibility guidelines",
8+
subtitle: 'In order for content to be accessible, it must be perceivable, operable, understandable, and robust.',
9+
status: 'static',
10+
};
11+
12+
<Meta title="UX Writing/Accessibility guidelines" />
13+
14+
<AboutHeader {...parameters} />
15+
16+
## The 4 principles of accessibility
17+
18+
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/).
19+
20+
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.
21+
22+
### 1. Perceivable
23+
24+
Information on-screen must be perceivable to blind, deaf, low-vision, or color-blind learners.
25+
26+
- Include meaningful and unique alt text for all non-decorative images or icons
27+
- Don't rely on visuals for words to make sense
28+
- If text is meant to be read, include it as text and not an image
29+
- Include captions for video and audio content
30+
31+
### 2. Operable
32+
33+
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.
34+
35+
- Make hyperlink text long enough that it's easy to hover over and click
36+
- Use meaningful, unique, and descriptive CTAs
37+
- Avoid ambiguous link text like "Click here" or "Read more"
38+
- If more than one label contains the same text, clarify with screen-reader-only text
39+
- Write so that labels, tooltips, and input fields appear in a logical order
40+
- Avoid directional language like "above" or "below"
41+
- Ensure users have enough time to read text
42+
43+
### 3. Understandable
44+
45+
Content should be easy to understand. Plus, it should appear and operate in predictable ways.
46+
47+
- Use H1, H2, H3 headings correctly and consistently
48+
- Check to ensure copy is at a 7th-grade reading level or below
49+
- Use short, clear sentences and paragraphs
50+
- Avoid jargon, slang, and idioms
51+
- Expand acronyms on first use
52+
- Use list formatting when appropriate
53+
54+
### 4. Robust
55+
56+
- Write in a way that's platform-agnostic (i.e. select or choose vs. tap or click)
57+
58+
### Bonus: Meaningful
59+
60+
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.
61+
62+
Meaningful text is useful text. It provides the full context a user needs to understand a situation.
63+
64+
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."
65+
66+
## Accessible content checklist
67+
68+
### Alt text
69+
- Is alt text included for all non-decorative images on the page?
70+
- Does your alt text provide all the information a user needs to understand what the image is being used to convey?
71+
72+
### Buttons
73+
- Is the CTA meaningful? Is it clear where clicking will take the user?
74+
- If there is more than one button on the page, is the text for each button unique?
75+
- If each button is not unique, have you provided screen-reader-only text to clarify?
76+
77+
### Headings
78+
- Does your page include a single, unique H1 title?
79+
- Are H2 and H3 headings used correctly and consistently?
80+
81+
82+
### Hyperlinks
83+
- Is link text meaningful? Is it clear where clicking will take the user?
84+
- Are hyperlinks long enough (2-3 words) to be easy to click on?
85+
- If there is more than one hyperlink on the page, is the text for each link unique?
86+
- If each hyperlink is not unique, have you provided screen-reader-only text to clarify?
87+
88+
89+
### Imagery
90+
- Do all non-decorative images or icons contain <LinkTo id="UX Writing/Component guidelines/Alternative text" > alt text</LinkTo>?
91+
- Does the alt text provide all the information a user needs to understand what the image is being used to convey?
92+
- Are all words understandable without reliance on imagery?
93+
94+
95+
### Readability
96+
- Do users have enough time to read the text?
97+
- Is the reading level grade 7 or below? Use [Hemingway App](https://hemingwayapp.com) to check.
98+
- Are sentences and paragraphs short and clear?
99+
- Is your content free of jargon, slang, and idioms?
100+
- Have you used list formatting when appropriate?
101+
- Do users have enough time to read the text?
102+
103+
### Screenreader compatibility
104+
- Does text appear in chronological order?
105+
- Are headings used correctly and appropriately?
106+
- Have you avoided directional language (i.e. "the form on the right" or "in the section below")?
107+
- Is the language platform-agnostic?
108+
- Have you passed the buttons, headings, hyperlinks, imagery, and readability checklists?
109+
110+
111+
### Video and audio content
112+
- Are captions included for all audio and video content?
113+
- For video, do the captions match what's happening on-screen?

‎packages/styleguide/src/lib/UX Writing/Component guidelines/About.mdx‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
import { Meta } from '@storybook/blocks';
2+
3+
import { AboutHeader, LinkTo, TableOfContents } from '~styleguide/blocks';
4+
5+
export const parameters = {
6+
id: 'Component guidelines',
7+
title: 'Component guidelines',
8+
subtitle: 'Get up to speed on best practices for writing for user interfaces, including guidance for writing for specific components in Gamut.',
9+
}
10+
11+
<Meta title='UX Writing/Component guidelines/About' />
12+
13+
<AboutHeader {...parameters} />
14+
15+
Writing on your own? Use the <LinkTo id="UX Writing/DIY UX writing in 8 steps">step-by-step guide</LinkTo> to ensure the copy is clear and useful.
16+
17+
<TableOfContents
18+
links={[
19+
{
20+
id: 'UX Writing/Component guidelines/Alerts',
21+
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.',
22+
title: 'Alerts',
23+
},
24+
{
25+
id: 'UX Writing/Component guidelines/Alternative text',
26+
title: "Alternative text",
27+
subtitle: 'Alternative text, or alt text, is a brief description of an image for users who cannot view it.',
28+
},
29+
{
30+
id: 'UX Writing/Component guidelines/Buttons',
31+
subtitle: 'Be specific, use action-oriented language, and emphasize value. Keep to 3 words or less (unless necessary for clarity), and use sentence case.',
32+
title: 'Buttons',
33+
},
34+
{
35+
id: 'UX Writing/Component guidelines/Confirmation dialogs',
36+
subtitle: 'Simplify the language, prioritize the message, and make sure the implication of what learners are saying "Yes" (or "No") to is crystal clear.',
37+
title: 'Confirmation dialogs',
38+
},
39+
{
40+
id: 'UX Writing/Component guidelines/Error messages',
41+
subtitle: 'Above all else, error messages should explain and resolve. Inform learners of what went wrong and let them know how to proceed.',
42+
title: 'Error messages',
43+
},
44+
{
45+
id: 'UX Writing/Component guidelines/Notifications',
46+
subtitle: 'Keep it brief (<86 characters), make it actionable, and ensure the messaging is in support of the learner’s journey.',
47+
title: 'Notifications',
48+
},
49+
{
50+
id: 'UX Writing/Component guidelines/Toasts',
51+
subtitle: 'Keep it brief, ensure the message is personal and relevant, and avoid distracting from the learning experience.',
52+
title: 'Toasts',
53+
},
54+
{
55+
id: 'UX Writing/Component guidelines/Tooltips',
56+
subtitle: `Keep tooltips short and useful. Avoid using them to share information that's vital for learners to complete tasks.`,
57+
title: 'Tooltips',
58+
},
59+
]}
60+
/>

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

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
import { Alert, Text } from '@codecademy/gamut/src';
2+
import { Meta } from '@storybook/blocks';
3+
4+
import { AboutHeader, LinkTo } from '~styleguide/blocks';
5+
6+
7+
export const parameters = {
8+
title: "Alerts",
9+
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.',
10+
status: 'static',
11+
};
12+
13+
<Meta title="UX Writing/Component guidelines/Alerts" />
14+
15+
<AboutHeader {...parameters} />
16+
17+
18+
19+
20+
Alerts are used to display important information and, if relevant, provide relevant actions the learner needs to take to resolve the alert.
21+
22+
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_.
23+
24+
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.
25+
26+
## Examples
27+
28+
<br />
29+
30+
<Alert type="general" cta={{ children: 'Resend verification' }} mx={0} >
31+
<Text> Please verify your email so we can make sure your account is secure. A link
32+
has been sent to name@email.com. </Text>
33+
</Alert>
34+
35+
<br />
36+
37+
<Alert type="success" cta={{ children: '' }}>
38+
<Text>Success! Your content has been assigned.</Text>
39+
</Alert>
40+
41+
<br />
42+
43+
<Alert type="error" cta={{ children: '' }}>
44+
<Text>We were unable to add this team member. Please refresh the page and try again.</Text>
45+
</Alert>
46+
47+
<br />
48+
49+
<Alert type="notice" cta={{ children: 'Learn more' }}>
50+
<Text>Maintenance: Codecademy will be offline between 2AM and 4AM EST.</Text>
51+
</Alert>
52+
53+
<br />
54+
55+
<Alert type="feature" cta={{ children: 'Add your name' }}>
56+
<Text>Update your profile with your name to help your team with account management.</Text>
57+
</Alert>
58+
59+
<br />
60+
61+
## Best practices
62+
63+
- **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:
64+
1. What will a learner be trying to do when this alert appears?
65+
2. What might happen if the learner doesn't receive the information in this alert?
66+
3. Does the learner need to take action to remove the alert?
67+
4. If the learner can't resolve the alert on their own, what information can we provide so they know what to expect?
68+
- **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.
69+
- **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.
70+
- **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.
71+
72+
## Checklist
73+
- Does the alert explain the information or issue clearly?
74+
- If relevant, have you explained what the user can do to resolve the alert or what we're doing on our end?
75+
- Is important information front-loaded?
76+
- Have you asked someone unrelated to the project to read the message and did they understand it?

0 commit comments

Comments
 (0)