diff --git a/packages/styleguide/.storybook/components/Elements/Markdown.tsx b/packages/styleguide/.storybook/components/Elements/Markdown.tsx index b1c75f2f356..e26f71e4466 100644 --- a/packages/styleguide/.storybook/components/Elements/Markdown.tsx +++ b/packages/styleguide/.storybook/components/Elements/Markdown.tsx @@ -43,7 +43,6 @@ 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; diff --git a/packages/styleguide/src/lib/Foundations/System/About.mdx b/packages/styleguide/src/lib/Foundations/System/About.mdx index 3735ec08601..effca42ebc0 100644 --- a/packages/styleguide/src/lib/Foundations/System/About.mdx +++ b/packages/styleguide/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.mdx'; +import { parameters as propsParameters } from './Props/About.mdx'; import { parameters as responsivePropertiesParameters } from './ResponsiveProperties/ResponsiveProperties.mdx'; import { parameters as variantsParameters } from './Variants.mdx'; diff --git a/packages/styleguide/src/lib/Foundations/System/Props.mdx b/packages/styleguide/src/lib/Foundations/System/Props.mdx deleted file mode 100644 index dc8bb6ce53d..00000000000 --- a/packages/styleguide/src/lib/Foundations/System/Props.mdx +++ /dev/null @@ -1,230 +0,0 @@ -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', - }, -}; - - - - - -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)); - -; -``` - -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. - -
- -## 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); - -; -``` - - - -## 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); - -; -``` - - - -## Typography - -Props for text manipulation - -```tsx -import styled from '@emotion/styled'; -import { system } from '@codecademy/gamut-styles'; - -const Text = styled.p(system.typography); - -; -``` - - - -## Color - -Specific color properties - -```tsx -import styled from '@emotion/styled'; -import { system } from '@codecademy/gamut-styles'; - -const Background = styled.div(system.color); - -; -``` - - - -## Border - -Border styles - -```tsx -import styled from '@emotion/styled'; -import { system } from '@codecademy/gamut-styles'; - -const Box = styled.div(system.border); - -; -``` - - - -## Flex - -Flex specific properties - -```tsx -import styled from '@emotion/styled'; -import { system } from '@codecademy/gamut-styles'; - -const FlexBox = styled.div(system.flex); - -; -``` - - - -## Grid - -Grid specific properties - -```tsx -import styled from '@emotion/styled'; -import { system } from '@codecademy/gamut-styles'; - -const GridBox = styled.div(system.grid); - -; -``` - - - -## 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); - -; -``` - - - -## 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); - -; -``` - - - -## 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); - -; -``` - - - -## 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); - - - a list item -; -``` - - diff --git a/packages/styleguide/src/lib/Foundations/System/Props/About.mdx b/packages/styleguide/src/lib/Foundations/System/Props/About.mdx new file mode 100644 index 00000000000..97ca50cd4b0 --- /dev/null +++ b/packages/styleguide/src/lib/Foundations/System/Props/About.mdx @@ -0,0 +1,81 @@ +import { Meta } from '@storybook/blocks'; + +import { + AboutHeader, + addParentPath, + TableOfContents, +} from '~styleguide/blocks'; + +import { parameters as backgroundParameters } from './Background.mdx'; +import { parameters as borderParameters } from './Border.mdx'; +import { parameters as colorParameters } from './Color.mdx'; +import { parameters as flexParameters } from './Flex.mdx'; +import { parameters as gridParameters } from './Grid.mdx'; +import { parameters as layoutParameters } from './Layout.mdx'; +import { parameters as listParameters } from './List.mdx'; +import { parameters as positioningParameters } from './Positioning.mdx'; +import { parameters as shadowParameters } from './Shadow.mdx'; +import { parameters as spaceParameters } from './Space.mdx'; +import { parameters as typographyParameters } from './Typography.mdx'; + +export const parameters = { + id: 'Foundations/System/Props', + title: 'Props', + subtitle: + 'Reusable CSS-in-JS props with predictable behaviors and a consistent API for responsive CSS.', + status: 'current', + source: { + repo: 'gamut-styles', + githubLink: + 'https://github.com/Codecademy/gamut/blob/main/packages/gamut-styles/src/variance/config.ts', + }, +}; + + + + + +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 ExampleContainer = styled.div( + variance.compose(system.layout, system.positioning) +); + +; +``` + +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 based on the selected theme and that theme's typing (e.g. if the `lxStudio` theme is being used, a scale of `colors` will restrict to the `lxStudio` theme's 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. + + diff --git a/packages/styleguide/src/lib/Foundations/System/Props/Background.mdx b/packages/styleguide/src/lib/Foundations/System/Props/Background.mdx new file mode 100644 index 00000000000..e5c34129cf8 --- /dev/null +++ b/packages/styleguide/src/lib/Foundations/System/Props/Background.mdx @@ -0,0 +1,30 @@ +import { Meta } from '@storybook/blocks'; + +import { AboutHeader, TokenTable } from '~styleguide/blocks'; + +import { defaultColumns, getPropRows } from '../../shared/elements'; + +export const parameters = { + title: 'Background', + subtitle: + 'Props for background manipulation (sizing / repitition / images), for background color see `colors`.', + status: 'current', +}; + + + + + +Background props control how background images and patterns are displayed on elements. These properties give you control over image sizing, positioning, and repetition behavior. For solid background colors, use the color props which connect to the theme's color palette. + +```tsx +import styled from '@emotion/styled'; +import { system } from '@codecademy/gamut-styles'; +import myBg from './myBg.png'; + +const BackgroundExample = styled.div(system.background); + +; +``` + + diff --git a/packages/styleguide/src/lib/Foundations/System/Props/Border.mdx b/packages/styleguide/src/lib/Foundations/System/Props/Border.mdx new file mode 100644 index 00000000000..554cafe2139 --- /dev/null +++ b/packages/styleguide/src/lib/Foundations/System/Props/Border.mdx @@ -0,0 +1,33 @@ +import { Meta } from '@storybook/blocks'; + +import { AboutHeader, TokenTable } from '~styleguide/blocks'; + +import { defaultColumns, getPropRows } from '../../shared/elements'; + +export const parameters = { + title: 'Border', + subtitle: 'Border styles', + status: 'updating', +}; + + + + + +Border props enable you to add and style borders on any side of an element. These properties support directional borders (top, right, bottom, left) as well as convenient shorthands for horizontal and vertical borders. Border radius values connect to the theme's `borderRadii` scale for consistent corner rounding. + +```tsx +import styled from '@emotion/styled'; +import { system } from '@codecademy/gamut-styles'; + +const BorderExample = styled.div(system.border); + +; +``` + + diff --git a/packages/styleguide/src/lib/Foundations/System/Props/Color.mdx b/packages/styleguide/src/lib/Foundations/System/Props/Color.mdx new file mode 100644 index 00000000000..0f2e7cb15e1 --- /dev/null +++ b/packages/styleguide/src/lib/Foundations/System/Props/Color.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: 'Color', + subtitle: 'Specific color properties', + status: 'current', +}; + + + + + +Color props control the foreground, background, and border colors of elements. All color values are restricted to your theme's color palette, ensuring consistent color usage throughout your application. The `bg` shorthand provides a convenient way to set background colors quickly. + +```tsx +import styled from '@emotion/styled'; +import { system } from '@codecademy/gamut-styles'; + +const ColorExample = styled.div(system.color); + +; +``` + + diff --git a/packages/styleguide/src/lib/Foundations/System/Props/Flex.mdx b/packages/styleguide/src/lib/Foundations/System/Props/Flex.mdx new file mode 100644 index 00000000000..85f515de38c --- /dev/null +++ b/packages/styleguide/src/lib/Foundations/System/Props/Flex.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: 'Flex', + subtitle: 'Flex specific properties', + status: 'current', +}; + + + + + +Flex props provide complete control over flexbox layouts, from container behavior to individual flex item properties. These properties make it easy to create flexible, responsive layouts with proper alignment and distribution of child elements. Use these on flex containers to control their children or on flex items to control their own behavior. + +```tsx +import styled from '@emotion/styled'; +import { system } from '@codecademy/gamut-styles'; + +const FlexExample = styled.div(system.flex); + +; +``` + + diff --git a/packages/styleguide/src/lib/Foundations/System/Props/Grid.mdx b/packages/styleguide/src/lib/Foundations/System/Props/Grid.mdx new file mode 100644 index 00000000000..39d17e1b3c0 --- /dev/null +++ b/packages/styleguide/src/lib/Foundations/System/Props/Grid.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: 'Grid', + subtitle: 'Grid specific properties', + status: 'current', +}; + + + + + +Grid props give you powerful control over CSS Grid layouts. Define grid templates, control auto-placement behavior, and set gaps between grid items. These properties make it straightforward to create complex, responsive grid layouts with precise control over both container and item positioning. + +```tsx +import styled from '@emotion/styled'; +import { system } from '@codecademy/gamut-styles'; + +const GridExample = styled.div(system.grid); + +; +``` + + diff --git a/packages/styleguide/src/lib/Foundations/System/Props/Layout.mdx b/packages/styleguide/src/lib/Foundations/System/Props/Layout.mdx new file mode 100644 index 00000000000..8c687a4dee5 --- /dev/null +++ b/packages/styleguide/src/lib/Foundations/System/Props/Layout.mdx @@ -0,0 +1,34 @@ +import { Meta } from '@storybook/blocks'; + +import { AboutHeader, TokenTable } from '~styleguide/blocks'; + +import { defaultColumns, getPropRows } from '../../shared/elements'; + +export const parameters = { + title: 'Layout', + subtitle: + 'Props for handling dimensions and other layout specific properties.', + status: 'updating', +}; + + + + + +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. + +```tsx +import styled from '@emotion/styled'; +import { system } from '@codecademy/gamut-styles'; + +const LayoutExample = styled.div(system.layout); + +; +``` + + diff --git a/packages/styleguide/src/lib/Foundations/System/Props/List.mdx b/packages/styleguide/src/lib/Foundations/System/Props/List.mdx new file mode 100644 index 00000000000..74398b42e07 --- /dev/null +++ b/packages/styleguide/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', +}; + + + + + +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 List component. + +```tsx +import styled from '@emotion/styled'; +import { system } from '@codecademy/gamut-styles'; + +const ListExample = styled.div(system.list); + + + a list item +; +``` + + diff --git a/packages/styleguide/src/lib/Foundations/System/Props/Positioning.mdx b/packages/styleguide/src/lib/Foundations/System/Props/Positioning.mdx new file mode 100644 index 00000000000..fb916b46286 --- /dev/null +++ b/packages/styleguide/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', +}; + + + + + +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); + +; +``` + + diff --git a/packages/styleguide/src/lib/Foundations/System/Props/Shadow.mdx b/packages/styleguide/src/lib/Foundations/System/Props/Shadow.mdx new file mode 100644 index 00000000000..60ee41e8f09 --- /dev/null +++ b/packages/styleguide/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', +}; + + + + + +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); + +; +``` + + diff --git a/packages/styleguide/src/lib/Foundations/System/Props/Space.mdx b/packages/styleguide/src/lib/Foundations/System/Props/Space.mdx new file mode 100644 index 00000000000..0afcbb48e6a --- /dev/null +++ b/packages/styleguide/src/lib/Foundations/System/Props/Space.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: 'Space', + subtitle: 'Props for maintaining specific vertical and horizontal rhythms', + status: 'updating', +}; + + + + + +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); + +; +``` + + diff --git a/packages/styleguide/src/lib/Foundations/System/Props/Typography.mdx b/packages/styleguide/src/lib/Foundations/System/Props/Typography.mdx new file mode 100644 index 00000000000..a63af6ab7bf --- /dev/null +++ b/packages/styleguide/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', +}; + + + + + +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); + +; +``` + + diff --git a/packages/styleguide/src/lib/Foundations/System/ResponsiveProperties/ResponsiveProperties.mdx b/packages/styleguide/src/lib/Foundations/System/ResponsiveProperties/ResponsiveProperties.mdx index 32ef96b22b2..03a9f18b744 100644 --- a/packages/styleguide/src/lib/Foundations/System/ResponsiveProperties/ResponsiveProperties.mdx +++ b/packages/styleguide/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', }, }; - + diff --git a/packages/styleguide/src/lib/Foundations/System/ResponsiveProperties/ResponsiveProperties.stories.tsx b/packages/styleguide/src/lib/Foundations/System/ResponsiveProperties/ResponsiveProperties.stories.tsx index c7b51fc8085..cc8e3a88bd0 100644 --- a/packages/styleguide/src/lib/Foundations/System/ResponsiveProperties/ResponsiveProperties.stories.tsx +++ b/packages/styleguide/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 = { + title: 'Foundations/System/Responsive properties', component: FlexBox, args: { center: true, diff --git a/packages/styleguide/src/lib/Foundations/shared/elements.tsx b/packages/styleguide/src/lib/Foundations/shared/elements.tsx index d01149e99d5..a6b0cf500cf 100644 --- a/packages/styleguide/src/lib/Foundations/shared/elements.tsx +++ b/packages/styleguide/src/lib/Foundations/shared/elements.tsx @@ -2,22 +2,31 @@ 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 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) => {id}, }; @@ -416,11 +425,14 @@ const PROPERTIES_COLUMN = { }) => properties.map((property) => ( - {kebabCase(property)} + {kebabCase(property)} )), }; @@ -430,7 +442,7 @@ const SCALE_COLUMN = { name: 'Scale', size: 'lg', render: ({ scale }: { scale: string }) => ( - {scale} + {scale} ), };