@codecademy/styleguide 79.1.0-alpha.e84769.0 → 79.1.1-alpha.0165b9.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

@@ -45,12 +45,33 @@ const preview: Preview = {
           'Meta',
           [
             'About',
-            'Best Practices',
-            'ESLint rules',
+            'Brand',
+            'Best practices',
             'Contributing',
+            'Deep Controls add-on',
+            'ESLint rules',
             'FAQs',
-            'Logical and physical CSS properties',
+            'Installation',
             'Stories',
+            'Usage guide',
+            'MCP',
+            'Gamut writing guide',
+            [
+              'About',
+              'General principles',
+              'Documentation in code',
+              'Formatting',
+              'Language and grammar',
+              'Linking',
+              'Referencing code',
+              'Stories',
+              [
+                'About',
+                'About pages',
+                'Component story documentation',
+                'Component code examples',
+              ],
+            ],
           ],
           'Foundations',
           'Layouts',
@@ -164,19 +185,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,12 +3,15 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-## [79.1.0-alpha.e84769.0](https://github.com/Codecademy/gamut/compare/@codecademy/styleguide@79.0.0...@codecademy/styleguide@79.1.0-alpha.e84769.0) (2026-02-06)
+### [79.1.1-alpha.0165b9.0](https://github.com/Codecademy/gamut/compare/@codecademy/styleguide@79.1.0...@codecademy/styleguide@79.1.1-alpha.0165b9.0) (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
 
-- Add border related logical props ([#3257](https://github.com/Codecademy/gamut/issues/3257)) ([e852afa](https://github.com/Codecademy/gamut/commit/e852afa6b0f70eb0e3a696c2b0fde7be0047bd5b))
-- 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))
+- Figma CodeConnect and MCP documentation and enablement ([7236a27](https://github.com/Codecademy/gamut/commit/7236a27ecc88eb6794049f06928e6c573213ae60))
 
 ## [79.0.0](https://github.com/Codecademy/gamut/compare/@codecademy/styleguide@78.5.5...@codecademy/styleguide@79.0.0) (2026-01-29)
 

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@codecademy/styleguide",
   "description": "Styleguide & Component library for codecademy.com",
-  "version": "79.1.0-alpha.e84769.0",
+  "version": "79.1.1-alpha.0165b9.0",
   "author": "Codecademy Engineering",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
   },
   "repository": "git@github.com:Codecademy/gamut.git",
-  "gitHead": "744d95e322f1e323af94678988aecf562dfacfe8"
+  "gitHead": "36a5b43d98d0c4bc396b0abaa56bcfb52b757904"
 }

package/src/lib/Atoms/Badge/Badge.mdx

@@ -124,7 +124,7 @@ Use `sm` when the `Badge` is inline with other components such as <LinkTo id='Ty
 
 ## Leading icon
 
-Include the `icon` property when the icon reinforces the badge’s message and improves scannability. Since badges are inherently small, it's recommended to use Gamut's mini icons. Below are examples of using icons with the different `Badge` sizes.
+Include the `icon` property when the icon reinforces the badge's message and improves scannability. Since badges are inherently small, it's recommended to use Gamut's mini icons. Below are examples of using icons with the different `Badge` sizes.
 
 ### Default size with icon
 

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

@@ -6,16 +6,16 @@ import {
   TableOfContents,
 } from '~styleguide/blocks';
 
-import { parameters as bestPracticesParameters } from './Best Practices.mdx';
+import { parameters as bestPracticesParameters } from './Best practices.mdx';
 import { parameters as brandParameters } from './Brand.mdx';
 import { parameters as contributingParameters } from './Contributing.mdx';
-import { parameters as deepControlsParameters } from './Deep Controls Add-On.mdx';
+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 gamutWritingGuideParameters } from './Gamut writing guide/About.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';
+import { parameters as mcpAboutParameters } from './MCP/About.mdx';
+import { parameters as usageGuideParameters } from './Usage guide.mdx';
 
 export const parameters = {
   id: 'Meta',
@@ -35,10 +35,10 @@ export const parameters = {
     deepControlsParameters,
     eslintRulesParameters,
     faqsParameters,
-    installationParameters,
-    logicalPhysicalParameters,
-    storiesParameters,
+    gamutWritingGuideParameters,
     brandParameters,
+    installationParameters,
     usageGuideParameters,
+    mcpAboutParameters,
   ])}
 />

package/src/lib/Meta/{Best Practices.mdx → Best practices.mdx }

@@ -3,13 +3,13 @@ import { Meta } from '@storybook/blocks';
 import { AboutHeader, Callout } from '~styleguide/blocks';
 
 export const parameters = {
-  id: 'Best Practices',
-  title: 'Best Practices',
+  id: 'Best practices',
+  title: 'Best practices',
   subtitle: 'Current best practices for using the Gamut Design System',
   status: 'current',
 };
 
-<Meta title="Meta/Best Practices" />
+<Meta title="Meta/Best practices" />
 
 <AboutHeader {...parameters} />
 

package/src/lib/Meta/Gamut writing guide/About.mdx

@@ -0,0 +1,43 @@
+import { Meta } from '@storybook/blocks';
+
+import {
+  AboutHeader,
+  addParentPath,
+  LinkTo,
+  TableOfContents,
+} from '~styleguide/blocks';
+
+import { parameters as documentationInCodeParameters } from './Documentation in code.mdx';
+import { parameters as formattingParameters } from './Formatting.mdx';
+import { parameters as generalPrinciplesParameters } from './General principles.mdx';
+import { parameters as languageAndGrammarParameters } from './Language and grammar.mdx';
+import { parameters as linkingParameters } from './Linking.mdx';
+import { parameters as referencingCodeParameters } from './Referencing code.mdx';
+import { parameters as storiesParameters } from './Stories/About.mdx';
+
+export const parameters = {
+  id: 'Meta/Gamut writing guide',
+  title: 'Gamut writing guide',
+  subtitle:
+    'Guidelines and standards for creating consistent, clear, and effective documentation.',
+};
+
+<Meta title="Meta/Gamut writing guide/About" />
+
+<AboutHeader {...parameters} />
+
+Welcome to the Gamut writing guide! Thanks for taking the time to learn about our documentation standards. This guide helps keep our documentation clear, consistent, and useful across the Gamut design system.
+
+The <LinkTo id="Meta/Gamut writing guide/General principles">General principles</LinkTo> is a great place to get an overview of our documentation philosophy and best practices. For specific topics like formatting, code documentation, or writing Storybook stories, check out the other pages below.
+
+<TableOfContents
+  links={addParentPath(parameters.id, [
+    generalPrinciplesParameters,
+    documentationInCodeParameters,
+    formattingParameters,
+    languageAndGrammarParameters,
+    linkingParameters,
+    referencingCodeParameters,
+    storiesParameters,
+  ])}
+/>