@codecademy/styleguide 79.1.0 → 79.2.0-alpha.2d3aae.0

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

@@ -0,0 +1,47 @@
+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 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'`." /> It
+        takes up half the width of its container. 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/List.mdx

@@ -0,0 +1,38 @@
+import { Meta } from '@storybook/blocks';
+
+import { AboutHeader, LinkTo, TokenTable } from '~styleguide/blocks';
+
+import { defaultColumns, getPropRows } from '../../shared/elements';
+
+export const parameters = {
+  title: 'List',
+  subtitle:
+    'Props for adjusting list styles when rendering a component as a `ul` or `ol`',
+  status: 'current',
+};
+
+<Meta title="Foundations/System/Props/List" />
+
+<AboutHeader {...parameters} />
+
+List props control the appearance of ordered and unordered lists when components are rendered as `ul` or `ol` elements. These properties let you customize bullet styles, list positioning, and even use custom images as list markers, giving you full control over list presentation.
+
+For more advanced list features, refer to the <LinkTo id="Organisms/Lists & Tables/List">List component</LinkTo>.
+
+```tsx
+import styled from '@emotion/styled';
+import { system } from '@codecademy/gamut-styles';
+
+const ListExample = styled.div(system.list);
+
+<ListExample
+  as="ul"
+  listStyleType="square"
+  listStylePosition="inside"
+  listStyleImage="none"
+>
+  <ListExample as="li">a list item</ListExample>
+</ListExample>;
+```
+
+<TokenTable rows={getPropRows('list')} columns={defaultColumns} />

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

@@ -0,0 +1,29 @@
+import { Meta } from '@storybook/blocks';
+
+import { AboutHeader, TokenTable } from '~styleguide/blocks';
+
+import { defaultColumns, getPropRows } from '../../shared/elements';
+
+export const parameters = {
+  title: 'Positioning',
+  subtitle:
+    'Props that affect stacking and position contexts. Like `top`, `position` and `opacity`.',
+  status: 'updating',
+};
+
+<Meta title="Foundations/System/Props/Positioning" />
+
+<AboutHeader {...parameters} />
+
+Positioning props control how elements are positioned within their parent containers and manage their stacking order. Use these properties to create fixed headers, absolute overlays, sticky navigation, and control layering with z-index. The `inset` shorthand provides a convenient way to set all four position values at once.
+
+```tsx
+import styled from '@emotion/styled';
+import { system } from '@codecademy/gamut-styles';
+
+const PositioningExample = styled.div(system.positioning);
+
+<PositioningExample position="absolute" zIndex={2} top="0" left="0" />;
+```
+
+<TokenTable rows={getPropRows('positioning')} columns={defaultColumns} />

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

@@ -0,0 +1,31 @@
+import { Meta } from '@storybook/blocks';
+
+import { AboutHeader, TokenTable } from '~styleguide/blocks';
+
+import { defaultColumns, getPropRows } from '../../shared/elements';
+
+export const parameters = {
+  title: 'Shadow',
+  subtitle: 'Props for box and text shadows.',
+  status: 'current',
+};
+
+<Meta title="Foundations/System/Props/Shadow" />
+
+<AboutHeader {...parameters} />
+
+Shadow props add depth and visual interest to your components through box and text shadows. These properties accept standard CSS shadow syntax, allowing you to create subtle elevation effects or dramatic visual depth. Use shadows consistently to establish visual hierarchy in your interface.
+
+```tsx
+import styled from '@emotion/styled';
+import { system } from '@codecademy/gamut-styles';
+
+const ShadowExample = styled.div(system.shadow);
+
+<ShadowExample
+  boxShadow="0 0 4px rgba(0, 0, 0, .15)"
+  textShadow="0 0 4px rgba(0, 0, 0, .15)"
+/>;
+```
+
+<TokenTable rows={getPropRows('shadows')} columns={defaultColumns} />

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

@@ -0,0 +1,44 @@
+import { Canvas, Meta } from '@storybook/blocks';
+
+import { AboutHeader, Callout, TokenTable } from '~styleguide/blocks';
+
+import { defaultColumns, getPropRows } from '../../shared/elements';
+import * as SpaceStories from './Space.stories';
+
+export const parameters = {
+  title: 'Space',
+  subtitle: 'Props for maintaining specific vertical and horizontal rhythms',
+  status: 'updating',
+};
+
+<Meta of={SpaceStories} title="Foundations/System/Props/Space" />
+
+<AboutHeader {...parameters} />
+
+Space props provide a consistent way to apply margin and padding throughout your application. All spacing values reference the theme's spacing scale, ensuring visual consistency and making it easy to create responsive spacing patterns using array syntax.
+
+```tsx
+import styled from '@emotion/styled';
+import { system } from '@codecademy/gamut-styles';
+
+const SpaceExample = styled.div(system.space);
+
+<SpaceExample p={8} my={[16, 24, 32]} />;
+```
+
+These space 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.
+
+<Callout
+  text={
+    <>
+      You can use the <strong>LogicalProps</strong> button in the toolbar to
+      switch between modes.
+    </>
+  }
+/>
+
+<Canvas of={SpaceStories.MarginExample} />
+
+<Canvas of={SpaceStories.PaddingExample} />
+
+<TokenTable rows={getPropRows('space')} columns={defaultColumns} />

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

@@ -0,0 +1,48 @@
+import { Box, Markdown } from '@codecademy/gamut';
+import type { Meta, StoryObj } from '@storybook/react';
+
+const meta: Meta<typeof Box> = {
+  title: 'Foundations/System/Props/Space',
+  component: Box,
+};
+
+export default meta;
+type Story = StoryObj<typeof Box>;
+
+export const MarginExample: Story = {
+  render: () => (
+    <Box
+      bg="primary"
+      color="background-contrast"
+      mb={64}
+      ml={16}
+      mr={32}
+      mt={4}
+      textAlign="center"
+    >
+      This box has{' '}
+      <Markdown text="`mt={4}`, `mr={32}`, `mb={64}`, and `ml={16}`." /> Inspect
+      the example to see what CSS properties are rendered.
+    </Box>
+  ),
+};
+
+export const PaddingExample: Story = {
+  render: () => (
+    <Box bg="background-selected">
+      <Box
+        bg="primary"
+        color="background-contrast"
+        pb={64}
+        pl={16}
+        pr={32}
+        pt={4}
+        textAlign="center"
+      >
+        This box has{' '}
+        <Markdown text="`pt={4}`, `pr={32}`, `pb={64}`, and `pl={16}`." />{' '}
+        Inspect the example to see what CSS properties are rendered.
+      </Box>
+    </Box>
+  ),
+};

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

@@ -0,0 +1,28 @@
+import { Meta } from '@storybook/blocks';
+
+import { AboutHeader, TokenTable } from '~styleguide/blocks';
+
+import { defaultColumns, getPropRows } from '../../shared/elements';
+
+export const parameters = {
+  title: 'Typography',
+  subtitle: 'Props for text manipulation',
+  status: 'current',
+};
+
+<Meta title="Foundations/System/Props/Typography" />
+
+<AboutHeader {...parameters} />
+
+Typography props give you fine-grained control over text styling and appearance. These properties connect to the theme's typography scales for font families, sizes, weights, and line heights, making it simple to maintain typographic consistency across your application while allowing for custom text transformations and decorations.
+
+```tsx
+import styled from '@emotion/styled';
+import { system } from '@codecademy/gamut-styles';
+
+const TextExample = styled.p(system.typography);
+
+<TextExample fontSize={16} fontFamily="accent" textTransform="uppercase" />;
+```
+
+<TokenTable rows={getPropRows('typography')} columns={defaultColumns} />

package/src/lib/Foundations/System/ResponsiveProperties/ResponsiveProperties.mdx

@@ -6,17 +6,17 @@ import { breakpoint } from '../../shared/elements';
 import * as ResponsivePropertiesStories from './ResponsiveProperties.stories';
 
 export const parameters = {
-  title: 'Responsive Properties',
+  title: 'Responsive properties',
   subtitle:
     'All system props accept a syntax to generate responsive styles on a per prop basis',
   source: {
     repo: 'variance',
     githubLink:
-      'https://github.com/Codecademy/gamut/blob/cass-gm-842/packages/variance/src/utils/responsive.ts',
+      'https://github.com/Codecademy/gamut/blob/main/packages/gamut-styles/src/variables/responsive.ts',
   },
 };
 
-<Meta title="Foundations/System/Responsive Properties" />
+<Meta of={ResponsivePropertiesStories} />
 
 <AboutHeader {...parameters} />
 

package/src/lib/Foundations/System/ResponsiveProperties/ResponsiveProperties.stories.tsx

@@ -2,6 +2,7 @@ import { Box, FlexBox } from '@codecademy/gamut';
 import type { Meta, StoryObj } from '@storybook/react';
 
 const meta: Meta<typeof FlexBox> = {
+  title: 'Foundations/System/Responsive properties',
   component: FlexBox,
   args: {
     center: true,

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

@@ -2,22 +2,32 @@ import { Anchor, Box } from '@codecademy/gamut';
 import {
   Background,
   coreSwatches,
+  css,
   lxStudioColors,
   theme,
   trueColors,
 } from '@codecademy/gamut-styles';
 // eslint-disable-next-line gamut/import-paths
 import * as ALL_PROPS from '@codecademy/gamut-styles/src/variance/config';
+import { useTheme } from '@emotion/react';
+import styled from '@emotion/styled';
 import kebabCase from 'lodash/kebabCase';
 
 import { Code, ColorScale, LinkTo, TokenTable } from '~styleguide/blocks';
 
 import { applyCorrectNotation } from './applyCorrectNotation';
 
+const AnchorCode = styled(Code)(
+  css({
+    textDecoration: 'underline',
+    mx: 4,
+  })
+);
+
 export const PROP_COLUMN = {
   key: 'key',
   name: 'Prop',
-  size: 'md',
+  size: 'lg',
   render: ({ id }: any) => <Code>{id}</Code>,
 };
 
@@ -403,26 +413,61 @@ export const DarkModeTable = () => (
 );
 /* eslint-disable gamut/import-paths */
 
+const PropertiesRenderer = ({
+  property,
+  properties,
+  resolveProperty,
+}: {
+  property: string | { physical: string; logical: string };
+  properties?: string[] | { physical: string[]; logical: string[] };
+  resolveProperty?: (useLogicalProperties: boolean) => 'logical' | 'physical';
+}) => {
+  const currentTheme = useTheme() as { useLogicalProperties?: boolean };
+  const useLogicalProperties = currentTheme?.useLogicalProperties ?? true;
+
+  const mode = resolveProperty
+    ? resolveProperty(useLogicalProperties)
+    : 'physical';
+
+  const resolvedProperty =
+    typeof property === 'string' ? property : property[mode];
+
+  let resolvedProperties: string[];
+  if (!properties) {
+    resolvedProperties = [resolvedProperty];
+  } else if (Array.isArray(properties)) {
+    resolvedProperties = properties;
+  } else {
+    resolvedProperties = properties[mode];
+  }
+
+  return (
+    <>
+      {resolvedProperties.map((prop) => (
+        <Anchor
+          href={`https://developer.mozilla.org/en-US/docs/Web/CSS/${kebabCase(
+            prop
+          )}`}
+          key={prop}
+          rel=""
+          target="_blank"
+        >
+          <AnchorCode>{kebabCase(prop)}</AnchorCode>
+        </Anchor>
+      ))}
+    </>
+  );
+};
+
 const PROPERTIES_COLUMN = {
   key: 'properties',
   name: 'Properties',
   size: 'xl',
-  render: ({
-    property,
-    properties = [property],
-  }: {
-    property: string;
-    properties: string[];
-  }) =>
-    properties.map((property) => (
-      <Anchor
-        href={`https://developer.mozilla.org/en-US/docs/Web/CSS/${property}`}
-        rel=""
-        target="_blank"
-      >
-        <Code key={property}>{kebabCase(property)}</Code>
-      </Anchor>
-    )),
+  render: (props: {
+    property: string | { physical: string; logical: string };
+    properties?: string[] | { physical: string[]; logical: string[] };
+    resolveProperty?: (useLogicalProperties: boolean) => 'logical' | 'physical';
+  }) => <PropertiesRenderer {...props} />,
 };
 
 const SCALE_COLUMN = {
@@ -430,7 +475,7 @@ const SCALE_COLUMN = {
   name: 'Scale',
   size: 'lg',
   render: ({ scale }: { scale: string }) => (
-    <LinkTo id={`foundations-theme--${kebabCase(scale)}`}>{scale}</LinkTo>
+    <LinkTo id="Foundations/Theme/Core Theme">{scale}</LinkTo>
   ),
 };
 
@@ -438,7 +483,12 @@ const TRANSFORM_COLUMN = {
   key: 'transform',
   name: 'Transform',
   size: 'fill',
-  render: ({ transform }: any) => transform && <Code>{transform?.name}</Code>,
+  render: ({ transform, resolveProperty }: any) => (
+    <>
+      {transform && <Code>{transform.name}</Code>}{' '}
+      {resolveProperty && <Code>{resolveProperty.name}</Code>}
+    </>
+  ),
 };
 
 export const defaultColumns = [

package/src/lib/Meta/About.mdx

@@ -13,6 +13,7 @@ import { parameters as deepControlsParameters } from './Deep Controls Add-On.mdx
 import { parameters as eslintRulesParameters } from './ESLint rules.mdx';
 import { parameters as faqsParameters } from './FAQs.mdx';
 import { parameters as installationParameters } from './Installation.mdx';
+import { parameters as logicalPhysicalParameters } from './Logical and physical CSS properties.mdx';
 import { parameters as mcpAboutParameters } from './MCP/About.mdx';
 import { parameters as storiesParameters } from './Stories.mdx';
 import { parameters as usageGuideParameters } from './Usage Guide.mdx';
@@ -35,9 +36,10 @@ export const parameters = {
     deepControlsParameters,
     eslintRulesParameters,
     faqsParameters,
+    installationParameters,
+    logicalPhysicalParameters,
     storiesParameters,
     brandParameters,
-    installationParameters,
     usageGuideParameters,
     mcpAboutParameters,
   ])}

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

@@ -0,0 +1,123 @@
+import { Meta } from '@storybook/blocks';
+
+import {
+  AboutHeader,
+  Callout,
+  Code,
+  ImageWrapper,
+  TokenTable,
+} from '~styleguide/blocks';
+
+export const parameters = {
+  id: 'Meta/Logical and physical CSS properties',
+  title: 'Logical and physical CSS properties',
+  subtitle:
+    'Understanding CSS logical and physical properties and how Gamut supports both modes.',
+  status: 'static',
+};
+
+<Meta title="Meta/Logical and physical CSS properties" />
+
+<AboutHeader {...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)
+
+### Physical Properties (Traditional)
+
+Physical properties reference the physical dimensions of the viewport. For example:
+
+- `margin-left`, `margin-right`, `margin-top`, `margin-bottom`
+- `padding-left`, `padding-right`, `padding-top`, `padding-bottom`
+
+These work well for left-to-right (LTR) languages but require manual overrides for right-to-left (RTL) languages like Arabic or Hebrew.
+
+### Logical Properties (Modern)
+
+Logical properties reference the flow of content:
+
+- **Inline axis** (text direction): `margin-inline-start`, `margin-inline-end`
+- **Block axis** (reading direction): `margin-block-start`, `margin-block-end`
+
+## Using `useLogicalProperties` in Gamut
+
+Gamut supports both physical and logical CSS properties through the `useLogicalProperties` prop on `GamutProvider`. This allows you to choose which mode your application uses. By default, `useLogicalProperties` is set to `true`, meaning Gamut will use logical CSS properties. If you want to use physical CSS properties, you have to set `useLogicalProperties` to `false`.
+
+### Affected Props
+
+Here are some examples of how physical and logical properties are affected by the `useLogicalProperties` prop:
+
+<TokenTable
+  idKey="prop"
+  columns={[
+    {
+      key: 'prop',
+      name: 'Prop',
+      size: 'sm',
+      render: ({ prop }) => <Code>{prop}</Code>,
+    },
+    {
+      key: 'physical',
+      name: 'Physical',
+      size: 'xl',
+      render: ({ physical }) =>
+        physical.map((p) => (
+          <>
+            <Code key={p}>{p}</Code>{' '}
+          </>
+        )),
+    },
+    {
+      key: 'logical',
+      name: 'Logical',
+      size: 'xl',
+      render: ({ logical }) =>
+        logical.map((l) => (
+          <>
+            <Code key={l}>{l}</Code>{' '}
+          </>
+        )),
+    },
+  ]}
+  rows={[
+    {
+      prop: 'mx',
+      physical: ['margin-left', 'margin-right'],
+      logical: ['margin-inline-start', 'margin-inline-end'],
+    },
+    { prop: 'mt', physical: ['margin-top'], logical: ['margin-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'],
+    },
+  ]}
+/>
+
+<Callout
+  text={
+    <>
+      Props like <code>m</code> and <code>p</code> (which set all four sides at
+      once) are not affected by this setting, as the CSS <code>margin</code> and{' '}
+      <code>padding</code> shorthands work identically in both modes.
+    </>
+  }
+/>
+
+## Previewing in Storybook
+
+You can toggle between logical and physical properties in Storybook using the **LogicalProps** toolbar button:
+
+<ImageWrapper
+  src="./meta/toolbar.png"
+  alt="The Storybook toolbar with the LogicalProps toggle highlighted."
+  height="auto"
+/>
+
+This allows you to preview how components render with either property mode without changing any code.

package/src/lib/Meta/Usage Guide.mdx

@@ -39,7 +39,8 @@ On each page is a toolbar located on the top:
 1. Grid (the 2x2 collection of squares) - applies a grid to the preview
 2. Color mode selector (the circle icon) - toggles between light and dark mode for rendered code examples
 3. Theme switcher (the paintbrush icon) - switches between different design system themes (Core, Admin, LX Studio, Percipio)
-4. Outline (dotted square) - applies outlines to elements in the rendered code examples
+4. LogicalProps (the two arrows icon) - toggles between physical and logical CSS properties
+5. Outline (dotted square) - applies outlines to elements in the rendered code examples
 
 ### Theme Switcher
 
@@ -58,6 +59,10 @@ Available themes:
 
 The theme switcher works in combination with the color mode selector, so you can test both light and dark variants of each theme.
 
+### LogicalProps
+
+The LogicalProps button (two arrows icon) provides a menu to select between Logical and Physical CSS properties.
+
 ### Showing code
 
 On the bottom right of each canvas (a rendered code example) is a button to show its code: