@codecademy/styleguide 79.2.0-alpha.e6658d.0 → 79.2.0-alpha.ed9688.0

package/.storybook/components/Scales/ColorScale.tsx

@@ -1,7 +1,7 @@
 import * as React from 'react';
 import { themed } from '@codecademy/gamut-styles';
 import styled from '@emotion/styled';
-import { Box, GridBox } from '@codecademy/gamut';
+import { Box, GridBox } from '@codecademy/gamut/src';
 
 const HexCode = styled.span`
   font-family: ${themed('fontFamily.monospace')};

package/.storybook/preview.ts

@@ -183,12 +183,13 @@ export const globalTypes = {
   },
   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

@@ -68,9 +68,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 +85,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,13 +3,22 @@
 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.e6658d.0](https://github.com/Codecademy/gamut/compare/@codecademy/styleguide@79.1.0...@codecademy/styleguide@79.2.0-alpha.e6658d.0) (2026-02-09)
+## [79.2.0-alpha.ed9688.0](https://github.com/Codecademy/gamut/compare/@codecademy/styleguide@79.1.2...@codecademy/styleguide@79.2.0-alpha.ed9688.0) (2026-03-05)
 
 ### Features
 
-- Add border related logical props ([#3257](https://github.com/Codecademy/gamut/issues/3257)) ([e852afa](https://github.com/Codecademy/gamut/commit/e852afa6b0f70eb0e3a696c2b0fde7be0047bd5b))
+- Layout related logical CSS props ([#3267](https://github.com/Codecademy/gamut/issues/3267)) ([b43cbf1](https://github.com/Codecademy/gamut/commit/b43cbf1256fbf292a141c77a3251fd95f0085a04))
+- 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))
 
+### [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)
+
+**Note:** Version bump only for package @codecademy/styleguide
+
 ## [79.1.0](https://github.com/Codecademy/gamut/compare/@codecademy/styleguide@79.0.0...@codecademy/styleguide@79.1.0) (2026-02-09)
 
 ### Features

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@codecademy/styleguide",
   "description": "Styleguide & Component library for codecademy.com",
-  "version": "79.2.0-alpha.e6658d.0",
+  "version": "79.2.0-alpha.ed9688.0",
   "author": "Codecademy Engineering",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
   },
   "repository": "git@github.com:Codecademy/gamut.git",
-  "gitHead": "c9f76514b37c19884b8dcd3fcdff03be92fb7500"
+  "gitHead": "149f648579774f0f7be4f3ba4e759bd039b8a3ce"
 }

package/src/lib/Foundations/Layout.mdx

@@ -1,4 +1,4 @@
-import { Box } from '@codecademy/gamut';
+import { Box } from '@codecademy/gamut/src';
 import { Meta } from '@storybook/blocks';
 
 import { ComponentHeader, LinkTo, TokenTable } from '~styleguide/blocks';

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

@@ -18,6 +18,16 @@ export const 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';

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

@@ -9,6 +9,45 @@ const meta: Meta<typeof 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}>
@@ -19,9 +58,8 @@ export const WidthExample: Story = {
         p={16}
         width="50%"
       >
-        This box has <Markdown text="`width='50%' and height='300px'`." /> It
-        takes up half the width of its container. Inspect the box to see the
-        rendered CSS property.
+        This box has <Markdown text="`width='50%' and height='300px'`." />{' '}
+        Inspect the box to see the rendered CSS property.
       </Box>
     </Box>
   ),

package/src/lib/Foundations/System/Props/Positioning.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 PositioningStories from './Positioning.stories';
 
 export const parameters = {
   title: 'Positioning',
@@ -11,7 +12,7 @@ export const parameters = {
   status: 'updating',
 };
 
-<Meta title="Foundations/System/Props/Positioning" />
+<Meta title="Foundations/System/Props/Positioning" of={PositioningStories} />
 
 <AboutHeader {...parameters} />
 
@@ -26,4 +27,8 @@ const PositioningExample = styled.div(system.positioning);
 <PositioningExample position="absolute" zIndex={2} top="0" left="0" />;
 ```
 
+These positioning props support both physical and logical CSS properties and will render the appropriate properties based on `useLogicalProperties`'s value passed into the `<GamutProvider>` at the root of your application.
+
+<Canvas of={PositioningStories.PositionExample} />
+
 <TokenTable rows={getPropRows('positioning')} columns={defaultColumns} />

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

@@ -0,0 +1,32 @@
+import { Box, Markdown } from '@codecademy/gamut';
+import type { Meta, StoryObj } from '@storybook/react';
+
+const meta: Meta<typeof Box> = {
+  title: 'Foundations/System/Props/Positioning',
+  component: Box,
+};
+
+export default meta;
+type Story = StoryObj<typeof Box>;
+
+export const PositionExample: Story = {
+  render: () => (
+    <Box bg="background-selected" height="250px" position="relative">
+      <Box
+        bg="primary"
+        color="background-contrast"
+        left={16}
+        p={16}
+        position="absolute"
+        top={16}
+      >
+        This box has{' '}
+        <Markdown text="`position='absolute'`, `top={16}`, and `left={16}`." />{' '}
+        Inspect the example to see what CSS properties are rendered. You can
+        also change the value of{' '}
+        <Markdown text="`useLogicalProperties` and `direction`" /> in the
+        toolbar to see how the box renders differently.
+      </Box>
+    </Box>
+  ),
+};

package/src/lib/Foundations/shared/elements.tsx

@@ -485,8 +485,8 @@ const TRANSFORM_COLUMN = {
   size: 'fill',
   render: ({ transform, resolveProperty }: any) => (
     <>
-      {transform && <Code>{transform.name}</Code>}{' '}
-      {resolveProperty && <Code>{resolveProperty.name}</Code>}
+      {transform && <Code>{transform?.name}</Code>}
+      {resolveProperty && <Code>{resolveProperty?.name}</Code>}
     </>
   ),
 };

package/src/lib/Meta/Logical and physical CSS properties.mdx

@@ -22,7 +22,7 @@ export const parameters = {
 
 ## What are CSS logical properties?
 
-CSS logical properties are a modern approach to styling that adapts to the writing mode and text direction of your content, rather than being tied to physical screen directions. More information can be found on[MDN: CSS Logical Properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values)
+CSS logical properties are a modern approach to styling that adapts to the writing mode and text direction of your content, rather than being tied to physical screen directions. More information can be found on [MDN: CSS Logical Properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values)
 
 ### Physical Properties (Traditional)
 
@@ -46,7 +46,9 @@ Gamut supports both physical and logical CSS properties through the `useLogicalP
 
 ### Affected Props
 
-Here are some examples of how physical and logical properties are affected by the `useLogicalProperties` prop:
+When `useLogicalProperties` is enabled, Gamut replaces physical CSS properties with their logical equivalents. This applies to both **base properties** (like `marginLeft`, `width`) and **shorthand props** (like `mx`, `py`).
+
+The table below shows a few examples — this is not a comprehensive list.
 
 <TokenTable
   idKey="prop"
@@ -59,7 +61,7 @@ Here are some examples of how physical and logical properties are affected by th
     },
     {
       key: 'physical',
-      name: 'Physical',
+      name: 'Physical CSS',
       size: 'xl',
       render: ({ physical }) =>
         physical.map((p) => (
@@ -70,7 +72,7 @@ Here are some examples of how physical and logical properties are affected by th
     },
     {
       key: 'logical',
-      name: 'Logical',
+      name: 'Logical CSS',
       size: 'xl',
       render: ({ logical }) =>
         logical.map((l) => (
@@ -81,21 +83,35 @@ Here are some examples of how physical and logical properties are affected by th
     },
   ]}
   rows={[
+    {
+      prop: 'marginLeft',
+      physical: ['margin-left'],
+      logical: ['margin-inline-start'],
+    },
     {
       prop: 'mx',
       physical: ['margin-left', 'margin-right'],
       logical: ['margin-inline-start', 'margin-inline-end'],
     },
-    { prop: 'mt', physical: ['margin-top'], logical: ['margin-block-start'] },
+    {
+      prop: 'paddingTop',
+      physical: ['padding-top'],
+      logical: ['padding-block-start'],
+    },
     {
       prop: 'py',
       physical: ['padding-top', 'padding-bottom'],
       logical: ['padding-block-start', 'padding-block-end'],
     },
     {
-      prop: 'pb',
-      physical: ['padding-bottom'],
-      logical: ['padding-block-end'],
+      prop: 'width',
+      physical: ['width'],
+      logical: ['inline-size'],
+    },
+    {
+      prop: 'height',
+      physical: ['height'],
+      logical: ['block-size'],
     },
   ]}
 />

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/Molecules/Tips/InfoTip/InfoTip.stories.tsx

@@ -296,14 +296,14 @@ export const ZIndex: Story = {
   },
   render: (args) => (
     <FlexBox center flexDirection="column" m={24} py={64}>
-      <Box bg="paleBlue" zIndex={3}>
+      <Box bg="background-primary" zIndex={3}>
         I will not be behind the infotip, sad + unreadable
       </Box>
       <InfoTip
         ariaLabel="z-index example without override"
         info="I am inline, cool"
       />
-      <Box bg="paleBlue" zIndex={3}>
+      <Box bg="background-primary" zIndex={3}>
         I will be behind the infotip, nice + great
       </Box>
       <InfoTip {...args} ariaLabel="z-index example with override" />

package/src/lib/Typography/Text/Text.stories.tsx

@@ -1,12 +1,12 @@
 import { Box, Column, LayoutGrid, Text } from '@codecademy/gamut';
-import type { Meta, StoryObj } from '@storybook/react';
-import { Fragment } from 'react';
-
+// eslint-disable-next-line gamut/import-paths
 import {
   typographyElementVariants,
   typographyStyleVariants,
   typographyUtilities,
-} from '../../../../../gamut/src/Typography/variants';
+} from '@codecademy/gamut/src/Typography/variants';
+import type { Meta, StoryObj } from '@storybook/react';
+import { Fragment } from 'react';
 
 const meta: Meta<typeof Text> = {
   component: Text,

package/src/lib/Typography/Text/tables.tsx

@@ -1,8 +1,8 @@
 import { Column, LayoutGrid, Text } from '@codecademy/gamut';
+// eslint-disable-next-line gamut/import-paths
+import { typographyElementVariants } from '@codecademy/gamut/src/Typography/variants';
 import { Fragment } from 'react';
 
-import { typographyElementVariants } from '../../../../../gamut/src/Typography/variants';
-
 export const Elements: React.FC = () => (
   <LayoutGrid gap={32} my={48}>
     {Object.keys(typographyElementVariants).map((tag) => (

package/src/lib/UX Writing/Component guidelines/Alerts.mdx

@@ -1,4 +1,4 @@
-import { Alert, Text } from '@codecademy/gamut';
+import { Alert, Text } from '@codecademy/gamut/src';
 import { Meta } from '@storybook/blocks';
 
 import { AboutHeader, LinkTo } from '~styleguide/blocks';