@codecademy/styleguide 79.1.4-alpha.feaf95.0 → 79.1.4

package/CHANGELOG.md

@@ -3,7 +3,7 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-### [79.1.4-alpha.feaf95.0](https://github.com/Codecademy/gamut/compare/@codecademy/styleguide@79.1.3...@codecademy/styleguide@79.1.4-alpha.feaf95.0) (2026-03-05)
+### [79.1.4](https://github.com/Codecademy/gamut/compare/@codecademy/styleguide@79.1.3...@codecademy/styleguide@79.1.4) (2026-03-09)
 
 **Note:** Version bump only for package @codecademy/styleguide
 

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@codecademy/styleguide",
   "description": "Styleguide & Component library for codecademy.com",
-  "version": "79.1.4-alpha.feaf95.0",
+  "version": "79.1.4",
   "author": "Codecademy Engineering",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
   },
   "repository": "git@github.com:Codecademy/gamut.git",
-  "gitHead": "9e31be8521b0139f2b0436a7c547b88f642deb26"
+  "gitHead": "d98acbdeb5f02be1c5b6592f2968300b9c0c19fe"
 }

package/src/lib/Molecules/Popover/Popover.mdx

@@ -24,12 +24,6 @@ export const parameters = {
 
 <ComponentHeader {...parameters} />
 
-## FOR TESTING/DEMONSTRATION PURPOSES ONLY
-
-Verify that the beak renders correctly without the background covering any content
-
-<Canvas of={PopoverStories.ClearBeakExample} />
-
 ## Usage
 
 Popovers are generally used for interactive contents, such as new and exciting features for users to try.

package/src/lib/Molecules/Popover/Popover.stories.tsx

@@ -7,8 +7,6 @@ import {
   PopoverProps,
 } from '@codecademy/gamut';
 import * as patterns from '@codecademy/gamut-patterns';
-import { theme } from '@codecademy/gamut-styles';
-import styled from '@emotion/styled';
 import type { Meta, StoryObj } from '@storybook/react';
 import { useRef, useState } from 'react';
 
@@ -33,23 +31,13 @@ const PopoverExample = ({ p = 16, ...rest }: PopoverExampleProps) => {
   const [open, setOpen] = useState(false);
   const activeElRef = useRef<HTMLDivElement>(null);
   const toggleOpen = () => setOpen(!open);
-
-  const PopoverWithClearBeak = styled(Popover)`
-    & [data-testid='popover-beak'] {
-      background: linear-gradient(
-        to top left,
-        ${theme.colors['background-current']} 50%,
-        transparent 50%
-      );
-    }
-  `;
   return (
     <>
       <Box ref={activeElRef} width="fit-content">
         <FillButton onClick={toggleOpen}>Open Popover</FillButton>
       </Box>
       <FlexBox>
-        <PopoverWithClearBeak
+        <Popover
           {...(rest as any)}
           isOpen={open}
           targetRef={activeElRef}
@@ -61,37 +49,12 @@ const PopoverExample = ({ p = 16, ...rest }: PopoverExampleProps) => {
               Close Popover
             </FillButton>
           </FlexBox>
-        </PopoverWithClearBeak>
+        </Popover>
       </FlexBox>
     </>
   );
 };
 
-export const ClearBeakExample: Story = {
-  render: (args) => (
-    <FlexBox gap={16}>
-      <PopoverExample {...args} beak="center" p={0} />
-      <PopoverExample {...args} beak="center" p={0} position="above" />
-      <PopoverExample
-        {...args}
-        align="right"
-        beak="center"
-        p={0}
-        pattern={undefined}
-        position="center"
-      />
-      <PopoverExample
-        {...args}
-        align="left"
-        beak="center"
-        p={0}
-        pattern={undefined}
-        position="center"
-      />
-    </FlexBox>
-  ),
-};
-
 export const Default: Story = {
   render: (args) => <PopoverExample {...args} />,
 };

package/src/lib/UX Writing/Component guidelines/Confirmation dialogs.mdx

@@ -1,11 +1,11 @@
 import { Meta } from '@storybook/blocks';
 
-import { AboutHeader, LinkTo } from '~styleguide/blocks';
+import { AboutHeader, ImageWrapper, 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.',
+    'Use the same verb from the triggering button, heading, to action confirmation button; clearly communicate the consequences; and keep the copy decision-focused.',
   status: 'static',
   design: {
     type: 'figma',
@@ -17,39 +17,57 @@ export const parameters = {
 
 <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.
+Confirmation dialogs use the <LinkTo id="Molecules/Modals/Dialog">Dialog component in Gamut</LinkTo> to create intentional friction to verify that a learner wants to take a high-impact action, such as:
 
-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.
+- Irreversible actions (e.g., submitting payment)
+- Loss of data, time, or work (e.g., deleting a course)
+- Unexpected consequences (e.g., losing learning history on an existing prototype when when generating a new prototype)
+
+Adding friction for these purposes helps improve trust and avoid unintentional actions by making sure learners clearly understand the consequences before continuing. It also lets us offer alternatives or undo options when needed.
 
 ## Best practices
 
-### Headline
+### Heading
+
+- **Ask or inform about one main action**, mirroring the button that triggered the confirmation dialog.
+- **Frame your headline as a binary question**, when possible, with 2 unambiguous answers.
+- **Avoid generic “Are you sure?” headings and body text.** This phrasing takes up space, increases cognitive load, and may undermine users' confidence or be interpreted as patronizing.
+
+### Body (optional)
+
+- **Add essential information about the contextual consequences.** State what will happen, what will be lost/changed, and any critical conditions.
+- **Avoid redundancy.** If the heading is already self-explanatory, the body is not needed.
+- **Keep to 1–2 lines, unless more is required to get all the information across.**
+
+### Buttons (CTA1 and CTA2)
 
-- **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?").
+- **Avoid using “Yes” or “No,”** as they can be misinterpreted in global English and internationalization contexts.
+- **CTA1 matches the verb from the heading** to confirm the action.
+- **CTA2 clarifies the alternative or undo** path.
+  - Whenever possible, be specific about the alternative. However, when space is limited, 'Cancel' can be used.
 
-### Explanation
+### Examples — putting it all together
 
-- **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.
+<ImageWrapper
+  src="./ux writing/delete_this_course.png"
+  alt="Delete this course confirmation dialog"
+/>
 
-### Button copy
+<ImageWrapper
+  src="./ux writing/delete_study_plan.png"
+  alt="Delete study plan confirmation dialog"
+/>
 
-- **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.
+<ImageWrapper
+  src="./ux writing/clear_chat.png"
+  alt="Clear chat 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?
+- Is the action irreversible, destructive, or has unexpected consequences? If not, consider using a different pattern.
+- Is the same verb used from the action triggering the confirmation dialog, to the heading, to CTA1?
+- Did you avoid filler language such as “Are you sure you want to...?”
+- Does the body front-load the critical consequence in 1–3 lines?
+- Are the buttons mutually exclusive (and avoid using “Yes/No”)?
+- Is there a safer alternative or undo to mention? (If available, offer the option as CTA2.)