@codecademy/styleguide 79.0.1-alpha.4aeb6d.0 → 79.0.1-alpha.4fa3a1.0

package/.storybook/components/Elements/DocsContainer.tsx

@@ -52,9 +52,6 @@ export const DocsContainer: React.FC<{
 
   const globalTheme =
     (context as any).store.userGlobals?.globals?.theme || 'core';
-  const globalLogicalProps = (context as any).store.userGlobals?.globals
-    ?.logicalProps;
-  const useLogicalProperties = globalLogicalProps !== 'false';
 
   const { currentTheme } = useMemo(() => {
     const findThemeStory: keyof typeof themeSpecificStories | undefined =
@@ -80,7 +77,6 @@ export const DocsContainer: React.FC<{
         cache={createEmotionCache({ speedy: false })}
         // This is typed to the CoreTheme in theme.d.ts
         theme={currentTheme as unknown as CoreTheme}
-        useLogicalProperties={useLogicalProperties}
       >
         <ColorMode mode="light">
           <HelmetProvider>

package/.storybook/components/Elements/Markdown.tsx

@@ -43,6 +43,7 @@ export const Code = styled.code`
   color: ${themed('colors.navy-700')};
   background-color: ${themed('colors.gray-100')};
   display: inline-block;
+  overflow-x: scroll;
 
   ::-webkit-scrollbar {
     width: 4px;

package/.storybook/preview.ts

@@ -49,7 +49,6 @@ const preview: Preview = {
             'ESLint rules',
             'Contributing',
             'FAQs',
-            'Logical and physical CSS properties',
             'Stories',
           ],
           'Foundations',
@@ -164,19 +163,6 @@ export const globalTypes = {
       showName: true,
     },
   },
-  logicalProps: {
-    name: 'LogicalProps',
-    description: 'Toggle between logical and physical CSS properties',
-    defaultValue: 'true',
-    toolbar: {
-      icon: 'transfer',
-      items: [
-        { value: 'true', title: 'Logical' },
-        { value: 'false', title: 'Physical' },
-      ],
-      showName: true,
-    },
-  },
 };
 
 export const decorators = [withEmotion];

package/.storybook/theming/GamutThemeProvider.tsx

@@ -34,14 +34,12 @@ type GlobalsContext = {
   globals: {
     colorMode: 'light' | 'dark';
     theme: keyof typeof themeMap;
-    logicalProps: 'true' | 'false';
   };
 };
 
 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 background = corePalette[themeBackground[colorMode]];
   const storyRef = useRef<HTMLDivElement>(null);
   const currentTheme = themeMap[selectedTheme];
@@ -59,7 +57,6 @@ export const withEmotion = (Story: any, context: GlobalsContext) => {
       <GamutProvider
         useCache={false}
         useGlobals={false}
-        useLogicalProperties={useLogicalProperties}
         theme={currentTheme as unknown as Theme}
       >
         <Background
@@ -75,10 +72,7 @@ export const withEmotion = (Story: any, context: GlobalsContext) => {
 
   // Wrap all stories in minimal provider
   return (
-    <GamutProvider
-      useLogicalProperties={useLogicalProperties}
-      theme={currentTheme as unknown as Theme}
-    >
+    <GamutProvider theme={currentTheme as unknown as Theme}>
       <Background
         alwaysSetVariables
         bg={themeBackground[colorMode]}

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.0.1-alpha.4aeb6d.0](https://github.com/Codecademy/gamut/compare/@codecademy/styleguide@79.0.0...@codecademy/styleguide@79.0.1-alpha.4aeb6d.0) (2026-01-30)
+### [79.0.1-alpha.4fa3a1.0](https://github.com/Codecademy/gamut/compare/@codecademy/styleguide@79.0.0...@codecademy/styleguide@79.0.1-alpha.4fa3a1.0) (2026-02-02)
 
 **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.0.1-alpha.4aeb6d.0",
+  "version": "79.0.1-alpha.4fa3a1.0",
   "author": "Codecademy Engineering",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
   },
   "repository": "git@github.com:Codecademy/gamut.git",
-  "gitHead": "c3bacad29ba252b1df9328296dd76c713cd2df16"
+  "gitHead": "bcc5f0d8a1a6bb0fa31053767e304e387b8c1683"
 }

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

@@ -7,7 +7,7 @@ import {
 } from '~styleguide/blocks';
 
 import { parameters as composeParameters } from './Compose.mdx';
-import { parameters as propsParameters } from './Props/About.mdx';
+import { parameters as propsParameters } from './Props.mdx';
 import { parameters as responsivePropertiesParameters } from './ResponsiveProperties/ResponsiveProperties.mdx';
 import { parameters as variantsParameters } from './Variants.mdx';
 

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

@@ -0,0 +1,230 @@
+import { Meta } from '@storybook/blocks';
+
+import { AboutHeader, TokenTable } from '~styleguide/blocks';
+
+import { defaultColumns, getPropRows } from '../shared/elements';
+
+export const parameters = {
+  title: 'Props',
+  subtitle:
+    'Reusable CSS-in-JS props with predictable behaviors and a consistent API for responsive CSS.',
+  source: {
+    repo: 'gamut-styles',
+    githubLink:
+      'https://github.com/Codecademy/gamut/blob/af5be6e39cccca5d5d8a1f811c77a7a0b618c914/packages/gamut-styles/src/variance/config.ts#L11',
+  },
+};
+
+<Meta title="Foundations/System/Props" />
+
+<AboutHeader {...parameters} />
+
+We provide a set of out of style functions out of the box through `@codecademy/gamut-styles` that are standardized throughout all of our components. These props are strongly typed and can be included as necessary on any styled component.
+
+System props have a few facets that are important to note:
+
+- They can some times represent multiple properties.
+- They may be restricted to specific token scales but will always have access to global css values like `initial` and `none`.
+- They may have a function that transforms the given value into a standardized value (e.g. `width={.5}` => `width: 50%`)
+
+We've grouped these into a few main groups that affect simliar behaviors: `layout`, `space`, `color`, `border`, `background`, `typography`, `positioning`, `grid`, `flex`, `shadow`.
+
+You may import these groups directly from `gamut-styles`.
+
+```tsx
+import { variance } from '@codecademy/variance';
+import { system } from '@codecademy/gamut-styles';
+
+const Box = styled.div(variance.compose(system.layout, system.positioning));
+
+<Box position="absolute" width="50px" height="50px" />;
+```
+
+Each system prop has 3 important features:
+
+- `properties`: Any number of CSS Properties this prop is responsible for.
+- `scale`: A set of values that determines valid inputs for each prop (e.g. a scale of `colors` will restrict to only theme colors). These are generally aliases for more verbose or opaque css properties allowing you to specify a human readable name in your props. If a prop doesn't have a scale that means it accepts all valid CSSType values as props, however if it does have a scale it will only accept global values and keys of the provided scale.
+- `transform`: A function that changes the prop / scale value prior to adding it to the stylehseet. This allows us to add / change units for properties like `width` and `height`. Or ensure extra defaults or fallbacks are added dynamically.
+
+<br />
+
+## Layout
+
+Props for handling dimensions and other layout specific properties.
+
+```tsx
+import styled from '@emotion/styled';
+import { system } from '@codecademy/gamut-styles';
+
+const Box = styled.div(system.layout);
+
+<Box display="flex" width="50%" height="300px" verticalAlign="middle" />;
+```
+
+<TokenTable rows={getPropRows('layout')} columns={defaultColumns} />
+
+## Space
+
+Props for maintaining specific vertical and horizontal rhythms
+
+```tsx
+import styled from '@emotion/styled';
+import { system } from '@codecademy/gamut-styles';
+
+const Spacer = styled.div(system.space);
+
+<Spacer p={8} my={[16, 24, 32]} />;
+```
+
+<TokenTable rows={getPropRows('space')} columns={defaultColumns} />
+
+## Typography
+
+Props for text manipulation
+
+```tsx
+import styled from '@emotion/styled';
+import { system } from '@codecademy/gamut-styles';
+
+const Text = styled.p(system.typography);
+
+<Text fontSize={16} fontFamily="accent" textTransform="uppercase" />;
+```
+
+<TokenTable rows={getPropRows('typography')} columns={defaultColumns} />
+
+## Color
+
+Specific color properties
+
+```tsx
+import styled from '@emotion/styled';
+import { system } from '@codecademy/gamut-styles';
+
+const Background = styled.div(system.color);
+
+<Background bg="navy" textColor="gray-100" borderColor="blue" />;
+```
+
+<TokenTable rows={getPropRows('color')} columns={defaultColumns} />
+
+## Border
+
+Border styles
+
+```tsx
+import styled from '@emotion/styled';
+import { system } from '@codecademy/gamut-styles';
+
+const Box = styled.div(system.border);
+
+<Box
+  border={1}
+  borderLeft="none"
+  borderRightStyle="dotted"
+  borderRadius="md"
+/>;
+```
+
+<TokenTable rows={getPropRows('border')} columns={defaultColumns} />
+
+## Flex
+
+Flex specific properties
+
+```tsx
+import styled from '@emotion/styled';
+import { system } from '@codecademy/gamut-styles';
+
+const FlexBox = styled.div(system.flex);
+
+<FlexBox flex={1} justifyContent="center" alignItems="flex-start" />;
+```
+
+<TokenTable rows={getPropRows('flex')} columns={defaultColumns} />
+
+## Grid
+
+Grid specific properties
+
+```tsx
+import styled from '@emotion/styled';
+import { system } from '@codecademy/gamut-styles';
+
+const GridBox = styled.div(system.grid);
+
+<GridBox gridTemplateColumns="max-content 1fr max-content" columnGap={32} />;
+```
+
+<TokenTable rows={getPropRows('grid')} columns={defaultColumns} />
+
+## Background
+
+Props for background manipulation (sizing / repitition / images), for background color see `colors`.
+
+```tsx
+import styled from '@emotion/styled';
+import { system } from '@codecademy/gamut-styles';
+import myBg from './myBg.png';
+
+const Box = styled.div(system.background);
+
+<Box background={`url(${myBg}`} backgroundSize="cover" />;
+```
+
+<TokenTable rows={getPropRows('background')} columns={defaultColumns} />
+
+## Positioning
+
+Props that affect stacking and position contexts. Like `top`, `position` and `opacity`.
+
+```tsx
+import styled from '@emotion/styled';
+import { system } from '@codecademy/gamut-styles';
+
+const Box = styled.div(system.positioning);
+
+<Box position="absolute" zIndex={2} top="0" left="0" />;
+```
+
+<TokenTable rows={getPropRows('positioning')} columns={defaultColumns} />
+
+## Shadow
+
+Props for box and text shadows.
+
+```tsx
+import styled from '@emotion/styled';
+import { system } from '@codecademy/gamut-styles';
+
+const Box = styled.div(system.shadow);
+
+<Box
+  boxShadow="0 0 4px rgba(0, 0, 0, .15)"
+  textShadow="0 0 4px rgba(0, 0, 0, .15)"
+/>;
+```
+
+<TokenTable rows={getPropRows('shadows')} columns={defaultColumns} />
+
+## List
+
+Props for adjusting list styles when rendering a component as a `ul` or `ol`
+
+```tsx
+import styled from '@emotion/styled';
+import { system } from '@codecademy/gamut-styles';
+
+const Box = styled.div(system.list);
+
+<Box
+  as="ul"
+  listStyleType="square"
+  listStylePosition="inside"
+  listStyleImage="none"
+>
+  <Box as="li">a list item</Box>
+</Box>;
+```
+
+<TokenTable rows={getPropRows('list')} 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/main/packages/gamut-styles/src/variables/responsive.ts',
+      'https://github.com/Codecademy/gamut/blob/cass-gm-842/packages/variance/src/utils/responsive.ts',
   },
 };
 
-<Meta of={ResponsivePropertiesStories} />
+<Meta title="Foundations/System/Responsive Properties" />
 
 <AboutHeader {...parameters} />
 

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

@@ -2,7 +2,6 @@ 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,32 +2,22 @@ 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: 'lg',
+  size: 'md',
   render: ({ id }: any) => <Code>{id}</Code>,
 };
 
@@ -413,61 +403,26 @@ 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: (props: {
-    property: string | { physical: string; logical: string };
-    properties?: string[] | { physical: string[]; logical: string[] };
-    resolveProperty?: (useLogicalProperties: boolean) => 'logical' | 'physical';
-  }) => <PropertiesRenderer {...props} />,
+  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>
+    )),
 };
 
 const SCALE_COLUMN = {
@@ -475,7 +430,7 @@ const SCALE_COLUMN = {
   name: 'Scale',
   size: 'lg',
   render: ({ scale }: { scale: string }) => (
-    <LinkTo id="Foundations/Theme/Core Theme">{scale}</LinkTo>
+    <LinkTo id={`foundations-theme--${kebabCase(scale)}`}>{scale}</LinkTo>
   ),
 };
 
@@ -483,12 +438,7 @@ const TRANSFORM_COLUMN = {
   key: 'transform',
   name: 'Transform',
   size: 'fill',
-  render: ({ transform, resolveProperty }: any) => (
-    <>
-      {transform && <Code>{transform?.name}</Code>}
-      {resolveProperty && <Code>{resolveProperty?.name}</Code>}
-    </>
-  ),
+  render: ({ transform }: any) => transform && <Code>{transform?.name}</Code>,
 };
 
 export const defaultColumns = [

package/src/lib/Meta/About.mdx

@@ -13,7 +13,6 @@ 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 storiesParameters } from './Stories.mdx';
 import { parameters as usageGuideParameters } from './Usage Guide.mdx';
 
@@ -35,10 +34,9 @@ export const parameters = {
     deepControlsParameters,
     eslintRulesParameters,
     faqsParameters,
-    installationParameters,
-    logicalPhysicalParameters,
     storiesParameters,
     brandParameters,
+    installationParameters,
     usageGuideParameters,
   ])}
 />

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

@@ -39,8 +39,7 @@ 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. 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
+4. Outline (dotted square) - applies outlines to elements in the rendered code examples
 
 ### Theme Switcher
 
@@ -59,10 +58,6 @@ 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: