@codecademy/styleguide 79.2.0-alpha.f9ca97.0 → 79.2.1-alpha.193cb6.0

package/.storybook/preview.ts

@@ -175,20 +175,21 @@ export const globalTypes = {
     toolbar: {
       icon: 'transfer',
       items: [
-        { value: 'true', title: 'Logical' },
         { value: 'false', title: 'Physical' },
+        { value: 'true', title: 'Logical' },
       ],
       showName: true,
     },
   },
   direction: {
     name: 'Direction',
-    description: 'Text direction for the page',
+    description: 'Text direction (LTR or RTL)',
     defaultValue: 'ltr',
     toolbar: {
+      icon: 'arrowright',
       items: [
-        { value: 'ltr', icon: 'arrowright', title: 'Left-To-Right' },
-        { value: 'rtl', icon: 'arrowleft', title: 'Right-To-Left' },
+        { value: 'ltr', title: 'Left-to-Right (LTR)', icon: 'arrowright' },
+        { value: 'rtl', title: 'Right-to-Left (RTL)', icon: 'arrowleft' },
       ],
       showName: true,
     },

package/.storybook/theming/GamutThemeProvider.tsx

@@ -12,6 +12,8 @@ import {
 } from '@codecademy/gamut-styles/src';
 import { Theme } from '@emotion/react';
 
+const STORYBOOK_CSP_NONCE = 'storybook-csp-nonce';
+
 /**
  * Story functions must be called as a regular function to avoid full-remounts
  * See: https://github.com/storybookjs/storybook/issues/12255
@@ -42,7 +44,7 @@ type GlobalsContext = {
 export const withEmotion = (Story: any, context: GlobalsContext) => {
   const colorMode = context.globals.colorMode ?? 'light';
   const selectedTheme = context.globals.theme;
-  const useLogicalProperties = context.globals.logicalProps !== 'false';
+  const useLogicalProperties = context.globals.logicalProps === 'true';
   const direction = context.globals.direction ?? 'ltr';
   const background = corePalette[themeBackground[colorMode]];
   const storyRef = useRef<HTMLDivElement>(null);
@@ -68,9 +70,8 @@ export const withEmotion = (Story: any, context: GlobalsContext) => {
           alwaysSetVariables
           bg={themeBackground[colorMode]}
           ref={storyRef}
-          dir={direction}
         >
-          {Story()}
+          <div dir={direction}>{Story()}</div>
         </Background>
       </GamutProvider>
     );
@@ -86,9 +87,8 @@ export const withEmotion = (Story: any, context: GlobalsContext) => {
         alwaysSetVariables
         bg={themeBackground[colorMode]}
         ref={storyRef}
-        dir={direction}
       >
-        {Story()}
+        <div dir={direction}>{Story()}</div>
       </Background>
     </GamutProvider>
   );

package/CHANGELOG.md

@@ -3,12 +3,29 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-## [79.2.0-alpha.f9ca97.0](https://github.com/Codecademy/gamut/compare/@codecademy/styleguide@79.1.1...@codecademy/styleguide@79.2.0-alpha.f9ca97.0) (2026-02-13)
+### [79.2.1-alpha.193cb6.0](https://github.com/Codecademy/gamut/compare/@codecademy/styleguide@79.2.0...@codecademy/styleguide@79.2.1-alpha.193cb6.0) (2026-03-12)
+
+**Note:** Version bump only for package @codecademy/styleguide
+
+## [79.2.0](https://github.com/Codecademy/gamut/compare/@codecademy/styleguide@79.1.4...@codecademy/styleguide@79.2.0) (2026-03-12)
 
 ### Features
 
-- Updates to ThemeProvider, tokens, and transform to allow Logical vs Physical prop resolution ([#3234](https://github.com/Codecademy/gamut/issues/3234)) ([7efbb9a](https://github.com/Codecademy/gamut/commit/7efbb9aabcd07dc6429432d007eaa5603ac1d70c))
-- Updates to ThemeProvider, tokens, and transform to allow Logical vs Physical prop resolution ([#3234](https://github.com/Codecademy/gamut/issues/3234)) ([567a6ae](https://github.com/Codecademy/gamut/commit/567a6aeffb3e8628db4b5c9a37dab965b716d969))
+- Logical properties ([4c340c3](https://github.com/Codecademy/gamut/commit/4c340c3949bad30fce4f9ffabb2018763df5c4ba))
+
+### [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
+
+### [79.1.3](https://github.com/Codecademy/gamut/compare/@codecademy/styleguide@79.1.2...@codecademy/styleguide@79.1.3) (2026-03-02)
+
+### Bug Fixes
+
+- **GamutProvider:** CSP improvements ([1026353](https://github.com/Codecademy/gamut/commit/10263537c190aff0e5686872da2be2a30b1d9201)), closes [/github.com/adobe/react-spectrum/issues/8273#issuecomment-3897820426](https://github.com/Codecademy//github.com/adobe/react-spectrum/issues/8273/issues/issuecomment-3897820426)
+
+### [79.1.2](https://github.com/Codecademy/gamut/compare/@codecademy/styleguide@79.1.1...@codecademy/styleguide@79.1.2) (2026-02-12)
+
+**Note:** Version bump only for package @codecademy/styleguide
 
 ### [79.1.1](https://github.com/Codecademy/gamut/compare/@codecademy/styleguide@79.1.0...@codecademy/styleguide@79.1.1) (2026-02-11)
 

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@codecademy/styleguide",
   "description": "Styleguide & Component library for codecademy.com",
-  "version": "79.2.0-alpha.f9ca97.0",
+  "version": "79.2.1-alpha.193cb6.0",
   "author": "Codecademy Engineering",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
   },
   "repository": "git@github.com:Codecademy/gamut.git",
-  "gitHead": "d73668577cae898037fa05bed7b91cc4c7312a9d"
+  "gitHead": "36c25d9a8a2de3b244792dfd2d3ccb1dd01eca09"
 }

package/src/lib/Atoms/Card/Card.stories.tsx

@@ -24,6 +24,7 @@ export const Default: Story = {
 export const StaticLight: Story = {
   render: () => (
     <Background bg="white">
+      <p>Test test</p>
       <FlexBox border={1} gap={16} p={16} row>
         <Box flexGrow={1}>
           <Card variant="white">White variant</Card>

package/src/lib/Foundations/System/Props/Layout.mdx

@@ -1,8 +1,9 @@
-import { Meta } from '@storybook/blocks';
+import { Canvas, Meta } from '@storybook/blocks';
 
 import { AboutHeader, TokenTable } from '~styleguide/blocks';
 
 import { defaultColumns, getPropRows } from '../../shared/elements';
+import * as LayoutStories from './Layout.stories';
 
 export const parameters = {
   title: 'Layout',
@@ -11,12 +12,22 @@ export const parameters = {
   status: 'updating',
 };
 
-<Meta title="Foundations/System/Props/Layout" />
+<Meta title="Foundations/System/Props/Layout" of={LayoutStories} />
 
 <AboutHeader {...parameters} />
 
 Layout props control the visual structure and dimensions of elements. These properties determine how components take up space, their display behavior, and how they align within their containers. Use these props to set widths, heights, overflow behavior, and container types for responsive layouts.
 
+## Examples
+
+### Overflow X
+
+<Canvas of={LayoutStories.OverflowXExample} />
+
+### Overflow Y
+
+<Canvas of={LayoutStories.OverflowYExample} />
+
 ```tsx
 import styled from '@emotion/styled';
 import { system } from '@codecademy/gamut-styles';
@@ -31,4 +42,14 @@ const LayoutExample = styled.div(system.layout);
 />;
 ```
 
+## Examples
+
+### Width
+
+<Canvas of={LayoutStories.WidthExample} />
+
+### Direction
+
+<Canvas of={LayoutStories.DirectionExample} />
+
 <TokenTable rows={getPropRows('layout')} columns={defaultColumns} />

package/src/lib/Foundations/System/Props/Layout.stories.tsx

@@ -0,0 +1,85 @@
+import { Box, Markdown } from '@codecademy/gamut';
+import type { Meta, StoryObj } from '@storybook/react';
+
+const meta: Meta<typeof Box> = {
+  title: 'Foundations/System/Props/Layout',
+  component: Box,
+};
+
+export default meta;
+type Story = StoryObj<typeof Box>;
+
+export const OverflowXExample: Story = {
+  render: () => (
+    <Box
+      bg="background-selected"
+      overflowX="scroll"
+      p={16}
+      whiteSpace="nowrap"
+      width="200px"
+    >
+      <Box
+        bg="primary"
+        color="background-contrast"
+        display="inline-block"
+        p={8}
+      >
+        This content is wider than its container and has{' '}
+        <Markdown text="`overflowX='scroll'`." /> Inspect the example to see
+        what CSS properties are rendered.
+      </Box>
+    </Box>
+  ),
+};
+
+export const OverflowYExample: Story = {
+  render: () => (
+    <Box bg="background-selected" height="100px" overflowY="scroll" p={16}>
+      <Box bg="primary" color="background-contrast" p={8}>
+        This content is taller than its container and has{' '}
+        <Markdown text="`overflowY='scroll'`." /> Inspect the example to see
+        what CSS properties are rendered.
+        <Box mt={16}>Line 2</Box>
+        <Box mt={16}>Line 3</Box>
+        <Box mt={16}>Line 4</Box>
+        <Box mt={16}>Line 5</Box>
+      </Box>
+    </Box>
+  ),
+};
+
+export const WidthExample: Story = {
+  render: () => (
+    <Box bg="background-selected" p={16}>
+      <Box
+        bg="primary"
+        color="background-contrast"
+        height="300px"
+        p={16}
+        width="50%"
+      >
+        This box has <Markdown text="`width='50%' and height='300px'`." />{' '}
+        Inspect the box to see the rendered CSS property.
+      </Box>
+    </Box>
+  ),
+};
+
+export const DirectionExample: Story = {
+  render: () => (
+    <Box display="flex" flexDirection="row" gap={16}>
+      <Box bg="background-selected" p={16} width="50%">
+        <Box bg="primary" color="background-contrast" direction="ltr" p={16}>
+          <Markdown text="`direction='ltr'`." /> Left-to-right text direction
+          (default for English).
+        </Box>
+      </Box>
+      <Box bg="background-selected" p={16} width="50%">
+        <Box bg="primary" color="background-contrast" direction="rtl" p={16}>
+          <Markdown text="`direction='rtl'`." /> Right-to-left text direction
+          (used for Arabic, Hebrew, etc.).
+        </Box>
+      </Box>
+    </Box>
+  ),
+};

package/src/lib/Foundations/System/Props/Positioning.stories.tsx

@@ -11,7 +11,7 @@ type Story = StoryObj<typeof Box>;
 
 export const PositionExample: Story = {
   render: () => (
-    <Box bg="background-selected" height="150px" position="relative">
+    <Box bg="background-selected" height="250px" position="relative">
       <Box
         bg="primary"
         color="background-contrast"

package/src/lib/Meta/Installation.mdx

@@ -68,7 +68,7 @@ GamutProvider handles a few critical tasks that need to happen in order for comp
 - **Next** `_app.tsx`
 - **Gatsby** `gatsby-ssr.js` `gatsby-browser.js` and use `wrapRootElement` in each.
 
-4. Add required types for your theme, which will determine what props Gamut components allow.
+5. Add required types for your theme, which will determine what props Gamut components allow.
 
 ```tsx
 // theme.d.ts
@@ -84,7 +84,7 @@ declare module '@emotion/react' {
 
 For more information this declaration please checkout the [official emotion documentation](https://emotion.sh/docs/typescript#define-a-theme)!
 
-5. Start Building!
+6. Start Building!
 
 ```tsx
 import { Background } from '@codecademy/gamut-styles';
@@ -96,3 +96,15 @@ export const App = () => (
   </Background>
 );
 ```
+
+### Content Security Policy (CSP)
+
+If your app uses a strict Content-Security-Policy (e.g. `style-src` without `'unsafe-inline'`), pass a nonce to `GamutProvider` so Emotion and other Gamut-managed style tags are allowed:
+
+```tsx
+<GamutProvider nonce={yourCspNonce}>
+  <App />
+</GamutProvider>
+```
+
+Your nonce should be the same value you use in your CSP header (e.g. `style-src 'self' 'nonce-{value}'`).

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

@@ -80,6 +80,7 @@ export const Above: Story = {
 export const Below: Story = {
   render: (args) => <PopoverExample {...args} beak="center" position="below" />,
 };
+
 export const CenterLeft: Story = {
   render: (args) => (
     <PopoverExample
@@ -113,6 +114,7 @@ export const PopoverCheckerDense: Story = {
     />
   ),
 };
+
 export const PopoverCheckerLoose: Story = {
   render: (args) => (
     <PopoverExample
@@ -122,6 +124,7 @@ export const PopoverCheckerLoose: Story = {
     />
   ),
 };
+
 export const PopoverCheckerRegular: Story = {
   render: (args) => (
     <PopoverExample
@@ -131,6 +134,7 @@ export const PopoverCheckerRegular: Story = {
     />
   ),
 };
+
 export const PopoverDiagonalADense: Story = {
   render: (args) => (
     <PopoverExample
@@ -140,6 +144,7 @@ export const PopoverDiagonalADense: Story = {
     />
   ),
 };
+
 export const PopoverDiagonalALoose: Story = {
   render: (args) => (
     <PopoverExample
@@ -149,6 +154,7 @@ export const PopoverDiagonalALoose: Story = {
     />
   ),
 };
+
 export const PopoverDiagonalARegular: Story = {
   render: (args) => (
     <PopoverExample

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.)