From aa01acd263c5d949e24c49a7298125b8fe8318b9 Mon Sep 17 00:00:00 2001 From: Kenny Lin Date: Fri, 16 Oct 2026 15:19:11 -0400 Subject: [PATCH 01/11] updated using-this-site --- .../src/content/docs/getting-started/using-this-site.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/gamut-docs/src/content/docs/getting-started/using-this-site.md b/packages/gamut-docs/src/content/docs/getting-started/using-this-site.md index a2a3b30e0d..a7c76fa38a 100644 --- a/packages/gamut-docs/src/content/docs/getting-started/using-this-site.md +++ b/packages/gamut-docs/src/content/docs/getting-started/using-this-site.md @@ -29,6 +29,6 @@ Every component page follows the same section order, so once you know the patter Sections 2–4 are explanation and how-to material; section 5 is reference, and always lives in Storybook rather than being retyped here — the embed is the source of truth. If you're deciding whether to use the component at all, start at Usage; if you just need to see what a prop looks like, skip straight to the bottom. -## This site is a work in progress +## Contributing to documentation -Gamut's documentation is migrating here from a Storybook-based styleguide. Pages that haven't been migrated yet are marked as such and link back to their current location. If you spot a gap, the [Contributing guide](/guides/contributing-to-gamut/) covers how to add or fix a page. +If you spot a gap, the [Contributing guide](/guides/contributing-to-gamut/) covers how to add or fix a page. From 05807ee5d69d6deb3e452b3cda69c728fa02694f Mon Sep 17 00:00:00 2001 From: Kenny Lin Date: Fri, 16 Oct 2026 15:20:55 -0400 Subject: [PATCH 02/11] update guides overview --- packages/gamut-docs/src/content/docs/guides/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/gamut-docs/src/content/docs/guides/index.md b/packages/gamut-docs/src/content/docs/guides/index.md index 88f28cf7e8..24c2a49f91 100644 --- a/packages/gamut-docs/src/content/docs/guides/index.md +++ b/packages/gamut-docs/src/content/docs/guides/index.md @@ -3,7 +3,7 @@ title: Overview description: Task-oriented recipes for things you already know you need to build. --- -How-to guides for cross-cutting tasks that don't have a home under a single component. +How-to guides for common tasks that users might encounter. - [Theming your app](/guides/theming-your-app/) - [Creating a custom theme](/guides/creating-a-custom-theme/) From 5cc366d6314fde8375ad2bd0ebd518fe2428d85f Mon Sep 17 00:00:00 2001 From: Kenny Lin Date: Fri, 16 Oct 2026 15:28:54 -0400 Subject: [PATCH 03/11] updated creating-a-custom-theme --- .../src/content/docs/guides/creating-a-custom-theme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/gamut-docs/src/content/docs/guides/creating-a-custom-theme.md b/packages/gamut-docs/src/content/docs/guides/creating-a-custom-theme.md index 96163436ad..8f7ea766f9 100644 --- a/packages/gamut-docs/src/content/docs/guides/creating-a-custom-theme.md +++ b/packages/gamut-docs/src/content/docs/guides/creating-a-custom-theme.md @@ -5,7 +5,7 @@ description: Build a custom theme with gamut-styles' createTheme builder. ## When to reach for this -Most apps should [choose an existing theme](/guides/theming-your-app/) rather than build a new one — reach for a custom theme only for a genuinely new product surface that doesn't fit Core, Admin, LX Studio, Percipio, or Platform. +Most apps should [choose an existing theme](/guides/theming-your-app/) rather than build a new one — reach for a custom theme only for a genuinely new product surface that doesn't fit Core, Admin, LX Studio, Percipio, or Platform. If you're unsure, with your team first —a designer should have signed off on this new theme prior to implementation. ## The `createTheme` builder From 35148a4399055a7525ffd2767ae9a689a5f3f7d3 Mon Sep 17 00:00:00 2001 From: Kenny Lin Date: Fri, 16 Oct 2026 15:32:22 -0400 Subject: [PATCH 04/11] updating contribution guide --- .../src/content/docs/guides/contributing-to-gamut.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/packages/gamut-docs/src/content/docs/guides/contributing-to-gamut.md b/packages/gamut-docs/src/content/docs/guides/contributing-to-gamut.md index c59f11540d..34132f5a02 100644 --- a/packages/gamut-docs/src/content/docs/guides/contributing-to-gamut.md +++ b/packages/gamut-docs/src/content/docs/guides/contributing-to-gamut.md @@ -7,10 +7,9 @@ description: How to propose, build, and document changes to Gamut. We track planned work for Gamut components in the [Gamut Board](https://skillsoftdev.atlassian.net/jira/software/c/projects/GMT/boards/3655/backlog) on JIRA. -- If there's a ticket there you want to take on, send a Slack message to `#gamut-team` or come to Gamut Office Hours to talk it through. -- If the work you'd like to do isn't captured in a JIRA ticket, talk to us first and we'll help create one. -- To request work be done, discuss it with us on Slack or during Gamut Office Hours. -- To pitch a change to the design system, attend Gamut Crit, come to Gamut Office Hours, or message `#gamut-team`. +- If there's a ticket there you want to take on, send a Slack message to `#gamut-team` +- If the work you'd like to do isn't captured in a JIRA ticket, talk to us first and we'll help create one +- To pitch a change to the design system, attend Gamut Crit, or message `#gamut-team`. ## Writing components @@ -129,4 +128,4 @@ If your PR has breaking changes affecting at least one downstream repository — 4. Once the new Gamut package publishes, update the downstream PRs to use it. 5. Merge and deploy those PRs as soon as possible. -If a breaking change might affect other users beyond those you've already coordinated with, mention it in `#frontend` too. +If a breaking change might affect other users beyond those you've already coordinated with, mention it in `#gamut-team` too and tag any relevant teams. From 64d69b6d346d4aadeadd62829ef67b3c7d2ab6e0 Mon Sep 17 00:00:00 2001 From: Kenny Lin Date: Tue, 20 Oct 2026 11:05:09 -0400 Subject: [PATCH 05/11] fix typo --- .../src/content/docs/guides/creating-a-custom-theme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/gamut-docs/src/content/docs/guides/creating-a-custom-theme.md b/packages/gamut-docs/src/content/docs/guides/creating-a-custom-theme.md index 8f7ea766f9..c354d8f341 100644 --- a/packages/gamut-docs/src/content/docs/guides/creating-a-custom-theme.md +++ b/packages/gamut-docs/src/content/docs/guides/creating-a-custom-theme.md @@ -5,7 +5,7 @@ description: Build a custom theme with gamut-styles' createTheme builder. ## When to reach for this -Most apps should [choose an existing theme](/guides/theming-your-app/) rather than build a new one — reach for a custom theme only for a genuinely new product surface that doesn't fit Core, Admin, LX Studio, Percipio, or Platform. If you're unsure, with your team first —a designer should have signed off on this new theme prior to implementation. +Most apps should [choose an existing theme](/guides/theming-your-app/) rather than build a new one — reach for a custom theme only for a genuinely new product surface that doesn't fit Core, Admin, LX Studio, Percipio, or Platform. If you're unsure, check with your team first — a designer should have signed off on this new theme prior to implementation. ## The `createTheme` builder From e1b07485c0c3b8a53c8e231b64151a987aa5229e Mon Sep 17 00:00:00 2001 From: Kenny Lin Date: Wed, 11 Nov 2026 16:46:59 -0500 Subject: [PATCH 06/11] add tokentable for astro and update colors in prop groups --- .../src/components/SystemPropTable.astro | 124 ++++++++++++++++++ .../{prop-groups.md => prop-groups.mdx} | 6 +- 2 files changed, 129 insertions(+), 1 deletion(-) create mode 100644 packages/gamut-docs/src/components/SystemPropTable.astro rename packages/gamut-docs/src/content/docs/foundations/system-props/{prop-groups.md => prop-groups.mdx} (87%) diff --git a/packages/gamut-docs/src/components/SystemPropTable.astro b/packages/gamut-docs/src/components/SystemPropTable.astro new file mode 100644 index 0000000000..9524f60ac7 --- /dev/null +++ b/packages/gamut-docs/src/components/SystemPropTable.astro @@ -0,0 +1,124 @@ +--- +/** + * The Starlight counterpart of Storybook's system prop `TokenTable` (see + * styleguide's `Foundations/shared/elements.tsx`): one row per prop in a + * system prop group, with its CSS properties, scale, and transform. + * + * Rows are read from `variance/config.ts` at build time — the same source + * Storybook uses — so the table can't drift from the props themselves. That + * file isn't part of `@skillsoft/gamut-styles`' public exports, so it's + * imported by path, as Storybook does. + * + * Storybook resolves a prop's properties for whichever logical-properties mode + * its toolbar is set to. A static page has no toggle, so a prop whose physical + * and logical properties differ lists both. + */ +import * as ALL_PROPS from '../../../gamut-styles/src/variance/config'; + +type Group = keyof typeof ALL_PROPS; +type Mode = 'physical' | 'logical'; + +interface PropConfig { + property: string | Record; + properties?: readonly string[] | Record; + scale?: string; + transform?: (...args: never[]) => unknown; + resolveProperty?: (useLogicalProperties: boolean) => Mode; +} + +interface Props { + /** A system prop group exported from `variance/config.ts`, e.g. "color" */ + group: Group; +} + +const { group } = Astro.props; + +const toKebab = (value: string) => + value.replace(/[A-Z]/g, (char) => `-${char.toLowerCase()}`); + +const resolveProperties = ( + { property, properties }: PropConfig, + mode: Mode +): string[] => { + const resolved = typeof property === 'string' ? property : property[mode]; + if (!properties) return [resolved]; + if (Array.isArray(properties)) return [...properties]; + return [...(properties as Record)[mode]]; +}; + +const rows = Object.entries( + ALL_PROPS[group] as Record +).map(([id, config]) => { + // Without `resolveProperty`, a prop always renders its physical properties. + const physical = resolveProperties(config, 'physical'); + const logical = config.resolveProperty + ? resolveProperties(config, 'logical') + : physical; + const modesDiffer = physical.join() !== logical.join(); + + return { + id, + propertySets: modesDiffer + ? [ + { label: 'Logical', properties: logical }, + { label: 'Physical', properties: physical }, + ] + : [{ label: undefined, properties: physical }], + scale: config.scale, + transforms: [config.transform?.name, config.resolveProperty?.name].filter( + Boolean + ), + }; +}); + +// Hand-authored hrefs in components aren't rewritten by the markdown base-URL +// plugin in astro.config.mjs, so the base has to be applied here. +const scaleHref = `${import.meta.env.BASE_URL.replace(/\/$/, '')}/foundations/design-tokens/`; +--- + + + + + + + + + + + + { + rows.map(({ id, propertySets, scale, transforms }) => ( + + + + + + + )) + } + +
PropPropertiesScaleTransform
+ {id} + + {propertySets.map(({ label, properties }) => ( +
+ {label && {label}: } + {properties.map((prop, index) => ( + <> + {index > 0 && ' '} + + {toKebab(prop)} + + + ))} +
+ ))} + 		{scale && {scale}} + {transforms.map((name) => ( + {name} + ))} +
diff --git a/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups.md b/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups.mdx similarity index 87% rename from packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups.md rename to packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups.mdx index 71dd781d0c..a16d88d445 100644 --- a/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups.md +++ b/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups.mdx @@ -3,7 +3,9 @@ title: Prop groups description: Every system prop group and what it covers. --- -Each group below is one example of what it covers, not an exhaustive prop list. For every individual prop in a group — its exact CSS properties, its scale, and its transform — open that group's own page in Storybook (for example, [Layout](https://gamut.codecademy.com/?path=/docs/foundations-system-props-layout--docs)) and see its prop table; that table is generated live from `variance/config.ts`, so it can't drift out of sync the way a static copy here would. +import SystemPropTable from '~/components/SystemPropTable.astro'; + +Each group below shows one example of what it covers. Groups with a prop table list every prop in the group — its CSS properties, its scale, and its transform — generated from `variance/config.ts`, so the table stays in sync with the props. For groups without a table yet, open that group's own page in Storybook (for example, [Layout](https://gamut.codecademy.com/?path=/docs/foundations-system-props-layout--docs)). ## Layout @@ -50,6 +52,8 @@ const ColorExample = styled.div(system.color); ; ``` + + ## Border Border props add and style borders on any side of an element, with directional props and horizontal/vertical shorthands. `borderRadius` references the theme's `borderRadii` scale. From c35505b580dd9a06d0646ebffa7ada4479ad5c33 Mon Sep 17 00:00:00 2001 From: Kenny Lin Date: Wed, 11 Nov 2026 16:50:07 -0500 Subject: [PATCH 07/11] re-org prop groups page to have individual pages for each prop group --- packages/gamut-docs/astro.config.mjs | 14 +- .../foundations/system-props/prop-groups.mdx | 145 ------------------ .../system-props/prop-groups/background.md | 16 ++ .../system-props/prop-groups/border.md | 23 +++ .../system-props/prop-groups/color.mdx | 22 +++ .../system-props/prop-groups/flex.md | 16 ++ .../system-props/prop-groups/grid.md | 19 +++ .../system-props/prop-groups/index.md | 21 +++ .../system-props/prop-groups/layout.md | 21 +++ .../system-props/prop-groups/list.md | 23 +++ .../system-props/prop-groups/positioning.md | 18 +++ .../system-props/prop-groups/shadow.md | 19 +++ .../system-props/prop-groups/space.md | 18 +++ .../system-props/prop-groups/typography.md | 16 ++ 14 files changed, 245 insertions(+), 146 deletions(-) delete mode 100644 packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups.mdx create mode 100644 packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/background.md create mode 100644 packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/border.md create mode 100644 packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/color.mdx create mode 100644 packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/flex.md create mode 100644 packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/grid.md create mode 100644 packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/index.md create mode 100644 packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/layout.md create mode 100644 packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/list.md create mode 100644 packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/positioning.md create mode 100644 packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/shadow.md create mode 100644 packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/space.md create mode 100644 packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/typography.md diff --git a/packages/gamut-docs/astro.config.mjs b/packages/gamut-docs/astro.config.mjs index 5a29b58baf..298994bb85 100644 --- a/packages/gamut-docs/astro.config.mjs +++ b/packages/gamut-docs/astro.config.mjs @@ -159,7 +159,19 @@ export default defineConfig({ // needs an explicit label instead of a bare autogenerate. label: 'System props', items: [ - { autogenerate: { directory: 'foundations/system-props' } }, + { slug: 'foundations/system-props' }, + { + label: 'Prop groups', + items: [ + { + autogenerate: { + directory: 'foundations/system-props/prop-groups', + }, + }, + ], + }, + { slug: 'foundations/system-props/compose-and-variants' }, + { slug: 'foundations/system-props/responsive-properties' }, ], }, { slug: 'foundations/themes' }, diff --git a/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups.mdx b/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups.mdx deleted file mode 100644 index a16d88d445..0000000000 --- a/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups.mdx +++ /dev/null @@ -1,145 +0,0 @@ ---- -title: Prop groups -description: Every system prop group and what it covers. ---- - -import SystemPropTable from '~/components/SystemPropTable.astro'; - -Each group below shows one example of what it covers. Groups with a prop table list every prop in the group — its CSS properties, its scale, and its transform — generated from `variance/config.ts`, so the table stays in sync with the props. For groups without a table yet, open that group's own page in Storybook (for example, [Layout](https://gamut.codecademy.com/?path=/docs/foundations-system-props-layout--docs)). - -## Layout - -Layout props control the visual structure and dimensions of elements — how components take up space, their display behavior, and how they align within their containers. - -```tsx -const LayoutExample = styled.div(system.layout); - -; -``` - -## Space - -Space props apply margin and padding consistently, referencing the theme's spacing scale — including responsive array syntax. - -```tsx -const SpaceExample = styled.div(system.space); - -; -``` - -## Typography - -Typography props connect to the theme's font family, size, weight, and line-height scales, alongside text transforms and decorations. - -```tsx -const TextExample = styled.p(system.typography); - -; -``` - -## Color - -Color props control foreground, background, and border colors, restricted to the theme's color palette. `bg` is a shorthand for background color. - -```tsx -const ColorExample = styled.div(system.color); - -; -``` - - - -## Border - -Border props add and style borders on any side of an element, with directional props and horizontal/vertical shorthands. `borderRadius` references the theme's `borderRadii` scale. - -```tsx -const BorderExample = styled.div(system.border); - -; -``` - -## Flex - -Flex props control flexbox layouts end to end — container behavior and individual item properties alike. - -```tsx -const FlexExample = styled.div(system.flex); - -; -``` - -## Grid - -Grid props control CSS Grid layouts — templates, auto-placement, and gaps between items. - -```tsx -const GridExample = styled.div(system.grid); - -; -``` - -## Background - -Background props control background images and patterns — sizing, positioning, and repetition. For solid background colors, use the color props instead. - -```tsx -const BackgroundExample = styled.div(system.background); - -; -``` - -## Positioning - -Positioning props control how an element is placed within its parent and its stacking order — `position`, the individual edge props (or the `inset` shorthand for all four at once), and `zIndex`. - -```tsx -const PositioningExample = styled.div(system.positioning); - -; -``` - -## Shadow - -Shadow props add box and text shadows, using standard CSS shadow syntax. - -```tsx -const ShadowExample = styled.div(system.shadow); - -; -``` - -## List - -List props adjust bullet styles, positioning, and custom marker images when a component renders as a `ul` or `ol`. For richer list features, see [List](/components/data-display/list-and-tables/list/list/). - -```tsx -const ListExample = styled.div(system.list); - - - a list item -; -``` - -`border`, `color`, `positioning`, and `space` props all support both physical and logical CSS properties, resolved by `useLogicalProperties` on `GamutProvider` — see [Migrating to logical properties](/guides/migrating-to-logical-properties/). diff --git a/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/background.md b/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/background.md new file mode 100644 index 0000000000..3222d5e958 --- /dev/null +++ b/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/background.md @@ -0,0 +1,16 @@ +--- +title: Background +description: System props for background images and patterns. +sidebar: + order: 8 +--- + +Background props control background images and patterns — sizing, positioning, and repetition. For solid background colors, use the [color props](/foundations/system-props/prop-groups/color/) instead. + +```tsx +const BackgroundExample = styled.div(system.background); + +; +``` + +For every prop in this group — its CSS properties, scale, and transform — see the [Background prop table](https://gamut.codecademy.com/?path=/docs/foundations-system-props-background--docs) in Storybook. diff --git a/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/border.md b/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/border.md new file mode 100644 index 0000000000..0d75108ad3 --- /dev/null +++ b/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/border.md @@ -0,0 +1,23 @@ +--- +title: Border +description: System props for border width, style, and radius on any side. +sidebar: + order: 5 +--- + +Border props add and style borders on any side of an element, with directional props and horizontal/vertical shorthands. `borderRadius` references the theme's `borderRadii` scale. + +```tsx +const BorderExample = styled.div(system.border); + +; +``` + +These props support both physical and logical CSS properties, resolved by `useLogicalProperties` on `GamutProvider` — see [Migrating to logical properties](/guides/migrating-to-logical-properties/). + +For every prop in this group — its CSS properties, scale, and transform — see the [Border prop table](https://gamut.codecademy.com/?path=/docs/foundations-system-props-border--docs) in Storybook. diff --git a/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/color.mdx b/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/color.mdx new file mode 100644 index 0000000000..8b4720e01d --- /dev/null +++ b/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/color.mdx @@ -0,0 +1,22 @@ +--- +title: Color +description: System props for foreground, background, and border colors. +sidebar: + order: 4 +--- + +import SystemPropTable from '~/components/SystemPropTable.astro'; + +Color props control foreground, background, and border colors, restricted to the theme's color palette. `bg` is a shorthand for background color. + +```tsx +const ColorExample = styled.div(system.color); + +; +``` + +These props support both physical and logical CSS properties, resolved by `useLogicalProperties` on `GamutProvider` — see [Migrating to logical properties](/guides/migrating-to-logical-properties/). + +## Props + + diff --git a/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/flex.md b/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/flex.md new file mode 100644 index 0000000000..7ff7728535 --- /dev/null +++ b/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/flex.md @@ -0,0 +1,16 @@ +--- +title: Flex +description: System props for flexbox containers and items. +sidebar: + order: 6 +--- + +Flex props control flexbox layouts end to end — container behavior and individual item properties alike. + +```tsx +const FlexExample = styled.div(system.flex); + +; +``` + +For every prop in this group — its CSS properties, scale, and transform — see the [Flex prop table](https://gamut.codecademy.com/?path=/docs/foundations-system-props-flex--docs) in Storybook. diff --git a/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/grid.md b/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/grid.md new file mode 100644 index 0000000000..9e6e42baee --- /dev/null +++ b/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/grid.md @@ -0,0 +1,19 @@ +--- +title: Grid +description: System props for grid templates, placement, and gaps. +sidebar: + order: 7 +--- + +Grid props control CSS Grid layouts — templates, auto-placement, and gaps between items. + +```tsx +const GridExample = styled.div(system.grid); + +; +``` + +For every prop in this group — its CSS properties, scale, and transform — see the [Grid prop table](https://gamut.codecademy.com/?path=/docs/foundations-system-props-grid--docs) in Storybook. diff --git a/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/index.md b/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/index.md new file mode 100644 index 0000000000..4ce82ca286 --- /dev/null +++ b/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/index.md @@ -0,0 +1,21 @@ +--- +title: Prop groups +description: Every system prop group and what it covers. +sidebar: + label: Overview + order: 0 +--- + +System props are grouped by the kind of styling they control. Import a group from `system` in `@skillsoft/gamut-styles`, or combine several with [compose](/foundations/system-props/compose-and-variants/). + +- [Layout](/foundations/system-props/prop-groups/layout/) — dimensions, display, and alignment. +- [Space](/foundations/system-props/prop-groups/space/) — margin and padding on the spacing scale. +- [Typography](/foundations/system-props/prop-groups/typography/) — font family, size, weight, and line height. +- [Color](/foundations/system-props/prop-groups/color/) — foreground, background, and border colors. +- [Border](/foundations/system-props/prop-groups/border/) — border width, style, and radius on any side. +- [Flex](/foundations/system-props/prop-groups/flex/) — flexbox containers and items. +- [Grid](/foundations/system-props/prop-groups/grid/) — grid templates, placement, and gaps. +- [Background](/foundations/system-props/prop-groups/background/) — background images and patterns. +- [Positioning](/foundations/system-props/prop-groups/positioning/) — position, edges, and stacking order. +- [Shadow](/foundations/system-props/prop-groups/shadow/) — box and text shadows. +- [List](/foundations/system-props/prop-groups/list/) — list markers and their position. diff --git a/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/layout.md b/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/layout.md new file mode 100644 index 0000000000..a6bd57b2d6 --- /dev/null +++ b/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/layout.md @@ -0,0 +1,21 @@ +--- +title: Layout +description: System props for dimensions, display, and alignment. +sidebar: + order: 1 +--- + +Layout props control the visual structure and dimensions of elements — how components take up space, their display behavior, and how they align within their containers. + +```tsx +const LayoutExample = styled.div(system.layout); + +; +``` + +For every prop in this group — its CSS properties, scale, and transform — see the [Layout prop table](https://gamut.codecademy.com/?path=/docs/foundations-system-props-layout--docs) in Storybook. diff --git a/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/list.md b/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/list.md new file mode 100644 index 0000000000..f89be4211b --- /dev/null +++ b/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/list.md @@ -0,0 +1,23 @@ +--- +title: List +description: System props for list markers and their position. +sidebar: + order: 11 +--- + +List props adjust bullet styles, positioning, and custom marker images when a component renders as a `ul` or `ol`. For richer list features, see [List](/components/data-display/list-and-tables/list/list/). + +```tsx +const ListExample = styled.div(system.list); + + + a list item +; +``` + +For every prop in this group — its CSS properties, scale, and transform — see the [List prop table](https://gamut.codecademy.com/?path=/docs/foundations-system-props-list--docs) in Storybook. diff --git a/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/positioning.md b/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/positioning.md new file mode 100644 index 0000000000..3b1bd45578 --- /dev/null +++ b/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/positioning.md @@ -0,0 +1,18 @@ +--- +title: Positioning +description: System props for position, edges, and stacking order. +sidebar: + order: 9 +--- + +Positioning props control how an element is placed within its parent and its stacking order — `position`, the individual edge props (or the `inset` shorthand for all four at once), and `zIndex`. + +```tsx +const PositioningExample = styled.div(system.positioning); + +; +``` + +These props support both physical and logical CSS properties, resolved by `useLogicalProperties` on `GamutProvider` — see [Migrating to logical properties](/guides/migrating-to-logical-properties/). + +For every prop in this group — its CSS properties, scale, and transform — see the [Positioning prop table](https://gamut.codecademy.com/?path=/docs/foundations-system-props-positioning--docs) in Storybook. diff --git a/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/shadow.md b/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/shadow.md new file mode 100644 index 0000000000..832d5385e4 --- /dev/null +++ b/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/shadow.md @@ -0,0 +1,19 @@ +--- +title: Shadow +description: System props for box and text shadows. +sidebar: + order: 10 +--- + +Shadow props add box and text shadows, using standard CSS shadow syntax. + +```tsx +const ShadowExample = styled.div(system.shadow); + +; +``` + +For every prop in this group — its CSS properties, scale, and transform — see the [Shadow prop table](https://gamut.codecademy.com/?path=/docs/foundations-system-props-shadow--docs) in Storybook. diff --git a/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/space.md b/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/space.md new file mode 100644 index 0000000000..beba07744a --- /dev/null +++ b/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/space.md @@ -0,0 +1,18 @@ +--- +title: Space +description: System props for margin and padding on the spacing scale. +sidebar: + order: 2 +--- + +Space props apply margin and padding consistently, referencing the theme's spacing scale — including responsive array syntax. + +```tsx +const SpaceExample = styled.div(system.space); + +; +``` + +These props support both physical and logical CSS properties, resolved by `useLogicalProperties` on `GamutProvider` — see [Migrating to logical properties](/guides/migrating-to-logical-properties/). + +For every prop in this group — its CSS properties, scale, and transform — see the [Space prop table](https://gamut.codecademy.com/?path=/docs/foundations-system-props-space--docs) in Storybook. diff --git a/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/typography.md b/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/typography.md new file mode 100644 index 0000000000..db7d239232 --- /dev/null +++ b/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/typography.md @@ -0,0 +1,16 @@ +--- +title: Typography +description: System props for font family, size, weight, and line height. +sidebar: + order: 3 +--- + +Typography props connect to the theme's font family, size, weight, and line-height scales, alongside text transforms and decorations. + +```tsx +const TextExample = styled.p(system.typography); + +; +``` + +For every prop in this group — its CSS properties, scale, and transform — see the [Typography prop table](https://gamut.codecademy.com/?path=/docs/foundations-system-props-typography--docs) in Storybook. From fb5435412a9ca8fa28f59783ecc4fdc371b221fb Mon Sep 17 00:00:00 2001 From: Kenny Lin Date: Wed, 11 Nov 2026 16:52:41 -0500 Subject: [PATCH 08/11] update layout props --- packages/gamut-docs/src/components/SystemPropTable.astro | 7 +++++-- .../system-props/prop-groups/{layout.md => layout.mdx} | 8 +++++++- 2 files changed, 12 insertions(+), 3 deletions(-) rename packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/{layout.md => layout.mdx} (58%) diff --git a/packages/gamut-docs/src/components/SystemPropTable.astro b/packages/gamut-docs/src/components/SystemPropTable.astro index 9524f60ac7..b21bec9d20 100644 --- a/packages/gamut-docs/src/components/SystemPropTable.astro +++ b/packages/gamut-docs/src/components/SystemPropTable.astro @@ -113,8 +113,11 @@ const scaleHref = `${import.meta.env.BASE_URL.replace(/\/$/, '')}/foundations/de {scale && {scale}} - {transforms.map((name) => ( - {name} + {transforms.map((name, index) => ( + <> + {index > 0 && ' '} + {name} + ))} diff --git a/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/layout.md b/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/layout.mdx similarity index 58% rename from packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/layout.md rename to packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/layout.mdx index a6bd57b2d6..ac4162b0eb 100644 --- a/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/layout.md +++ b/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/layout.mdx @@ -5,6 +5,8 @@ sidebar: order: 1 --- +import SystemPropTable from '~/components/SystemPropTable.astro'; + Layout props control the visual structure and dimensions of elements — how components take up space, their display behavior, and how they align within their containers. ```tsx @@ -18,4 +20,8 @@ const LayoutExample = styled.div(system.layout); />; ``` -For every prop in this group — its CSS properties, scale, and transform — see the [Layout prop table](https://gamut.codecademy.com/?path=/docs/foundations-system-props-layout--docs) in Storybook. +These props support both physical and logical CSS properties, resolved by `useLogicalProperties` on `GamutProvider` — see [Migrating to logical properties](/guides/migrating-to-logical-properties/). + +## Props + + From 7e8f64e263d3ddf678d4ed3995e7f537e43c3181 Mon Sep 17 00:00:00 2001 From: Kenny Lin Date: Wed, 11 Nov 2026 16:53:54 -0500 Subject: [PATCH 09/11] update space page --- .../system-props/prop-groups/{space.md => space.mdx} | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) rename packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/{space.md => space.mdx} (73%) diff --git a/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/space.md b/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/space.mdx similarity index 73% rename from packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/space.md rename to packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/space.mdx index beba07744a..1ff1094a9c 100644 --- a/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/space.md +++ b/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/space.mdx @@ -5,6 +5,8 @@ sidebar: order: 2 --- +import SystemPropTable from '~/components/SystemPropTable.astro'; + Space props apply margin and padding consistently, referencing the theme's spacing scale — including responsive array syntax. ```tsx @@ -15,4 +17,6 @@ const SpaceExample = styled.div(system.space); These props support both physical and logical CSS properties, resolved by `useLogicalProperties` on `GamutProvider` — see [Migrating to logical properties](/guides/migrating-to-logical-properties/). -For every prop in this group — its CSS properties, scale, and transform — see the [Space prop table](https://gamut.codecademy.com/?path=/docs/foundations-system-props-space--docs) in Storybook. +## Props + + From b4e5342c07fa2461932176c9d2874754638f3e00 Mon Sep 17 00:00:00 2001 From: Kenny Lin Date: Wed, 11 Nov 2026 16:54:31 -0500 Subject: [PATCH 10/11] update typography --- .../prop-groups/{typography.md => typography.mdx} | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) rename packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/{typography.md => typography.mdx} (65%) diff --git a/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/typography.md b/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/typography.mdx similarity index 65% rename from packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/typography.md rename to packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/typography.mdx index db7d239232..087a9b61e5 100644 --- a/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/typography.md +++ b/packages/gamut-docs/src/content/docs/foundations/system-props/prop-groups/typography.mdx @@ -5,6 +5,8 @@ sidebar: order: 3 --- +import SystemPropTable from '~/components/SystemPropTable.astro'; + Typography props connect to the theme's font family, size, weight, and line-height scales, alongside text transforms and decorations. ```tsx @@ -13,4 +15,6 @@ const TextExample = styled.p(system.typography); ; ``` -For every prop in this group — its CSS properties, scale, and transform — see the [Typography prop table](https://gamut.codecademy.com/?path=/docs/foundations-system-props-typography--docs) in Storybook. +## Props + + From a154fbd8d1ad7325bef75da11f334b296e1c7fe1 Mon Sep 17 00:00:00 2001 From: Kenny Lin Date: Wed, 11 Nov 2026 16:55:34 -0500 Subject: [PATCH 11/11] update token table to be 100% width --- .../src/components/SystemPropTable.astro | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/packages/gamut-docs/src/components/SystemPropTable.astro b/packages/gamut-docs/src/components/SystemPropTable.astro index b21bec9d20..2f66411cdb 100644 --- a/packages/gamut-docs/src/components/SystemPropTable.astro +++ b/packages/gamut-docs/src/components/SystemPropTable.astro @@ -76,6 +76,7 @@ const rows = Object.entries( const scaleHref = `${import.meta.env.BASE_URL.replace(/\/$/, '')}/foundations/design-tokens/`; --- +
@@ -125,3 +126,20 @@ const scaleHref = `${import.meta.env.BASE_URL.replace(/\/$/, '')}/foundations/de }
+
+ +