From 5a564da2b8f67ecc005f7ff814424245ca68c6c7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Aliz=C3=A9=20Debray?= <33580481+alizedebray@users.noreply.github.com> Date: Mon, 2 Dec 2024 14:34:43 +0100 Subject: [PATCH] feat(docs): update layout documentation (#4048) --- packages/documentation/.storybook/preview.ts | 14 +- .../layout/breakpoints/breakpoints.docs.mdx | 13 +- .../layout/columns/columns.stories.ts | 7 +- .../layout/columns/columns.styles.scss | 6 +- .../foundations/layout/grid/grid.docs.mdx | 36 +-- .../foundations/layout/grid/grid.stories.ts | 292 +++++------------- .../foundations/layout/grid/grid.styles.scss | 3 +- .../foundations/layout/shared.blocks.tsx | 2 +- 8 files changed, 106 insertions(+), 267 deletions(-) diff --git a/packages/documentation/.storybook/preview.ts b/packages/documentation/.storybook/preview.ts index c41a66d6c7..e10fe379cf 100644 --- a/packages/documentation/.storybook/preview.ts +++ b/packages/documentation/.storybook/preview.ts @@ -38,11 +38,15 @@ const preview: Preview = { // Category - Foundations 'Foundations', - ['Logo', 'Icons', 'Palettes', 'Typography', ['Overview']], - - // Category - Layout - 'Layout', - ['Breakpoints', 'Containers', 'Grid', 'Columns'], + [ + 'Logo', + 'Icons', + 'Palettes', + 'Typography', + ['Overview'], + 'Layout', + ['Breakpoints', 'Containers', 'Grid', 'Columns'], + ], // Category - Raw Components (INTERNAL ONLY) 'Raw Components', diff --git a/packages/documentation/src/stories/foundations/layout/breakpoints/breakpoints.docs.mdx b/packages/documentation/src/stories/foundations/layout/breakpoints/breakpoints.docs.mdx index 3e9bc87b43..7c5dab971a 100644 --- a/packages/documentation/src/stories/foundations/layout/breakpoints/breakpoints.docs.mdx +++ b/packages/documentation/src/stories/foundations/layout/breakpoints/breakpoints.docs.mdx @@ -18,21 +18,10 @@ import SampleBetween from './breakpoints-between.sample.scss?raw'; ## Available breakpoints -The Swiss Post Design System includes - -{Object.keys(SCSS_VARIABLES.breakpoint).length} +The Swiss Post Design System includes {Object.keys(SCSS_VARIABLES.breakpoint).length} breakpoints, sometimes referred to as grid tiers, for building responsively. These breakpoints can be customized if you’re using our source Sass files. -
-

- The regular Breakpoint is deprecated -

-

- Its CSS helper classes, as well as its SASS variables and mixins will be removed in the future. -

-
- ## CSS diff --git a/packages/documentation/src/stories/foundations/layout/columns/columns.stories.ts b/packages/documentation/src/stories/foundations/layout/columns/columns.stories.ts index 5bfb236ab5..e8b900a194 100644 --- a/packages/documentation/src/stories/foundations/layout/columns/columns.stories.ts +++ b/packages/documentation/src/stories/foundations/layout/columns/columns.stories.ts @@ -141,9 +141,14 @@ export const VerticalExample: Story = { include: ['Align Items', 'Align Item 1'], }, }, + decorators: [ + (story: StoryFn, context: StoryContext) => html` +
${story(context.args, context)}
+ `, + ], render: (args: Args) => html`
-
+
Item 1
diff --git a/packages/documentation/src/stories/foundations/layout/columns/columns.styles.scss b/packages/documentation/src/stories/foundations/layout/columns/columns.styles.scss index 0ca6b8aa18..0b31c3a0e6 100644 --- a/packages/documentation/src/stories/foundations/layout/columns/columns.styles.scss +++ b/packages/documentation/src/stories/foundations/layout/columns/columns.styles.scss @@ -13,11 +13,7 @@ background-color: lighten(#0076a8, 61.5%); } - .row-height { + .high-row .row { min-height: 10rem; } - - .standalone-columns > *:not(p){ - padding-block: 0.75rem; - } } diff --git a/packages/documentation/src/stories/foundations/layout/grid/grid.docs.mdx b/packages/documentation/src/stories/foundations/layout/grid/grid.docs.mdx index 4c3ef138b8..e1911e644e 100644 --- a/packages/documentation/src/stories/foundations/layout/grid/grid.docs.mdx +++ b/packages/documentation/src/stories/foundations/layout/grid/grid.docs.mdx @@ -1,10 +1,11 @@ import { Canvas, Meta, Source } from '@storybook/blocks'; -import { formatAsMap } from '@/utils/sass-export'; -import { GridTable, SCSS_VARIABLES } from './grid.blocks'; +import { parse } from '@/utils/sass-export'; +import scss from './grid.module.scss'; import * as GridStories from './grid.stories'; import './grid.styles.scss'; import SampleContainer from './grid-container.sample.html?raw'; -import SampleScssMixins from './grid-scss-mixins.sample.scss?raw'; + +export const SCSS_VARIABLES = parse(scss); @@ -47,13 +48,6 @@ Breaking it down, here’s how the grid system comes together: - **Gutters are also responsive and customizable.** Gutter classes are available across all breakpoints, with all the same sizes as our `margin` and `padding` spacing. Change horizontal gutters with `.gx-*` classes, vertical gutters with `.gy-*`, or all gutters with `.g-*` classes. `.g-0` is also available to remove gutters. - **Sass variables, maps, and mixins power the grid.** If you don’t want to use the predefined grid classes, you can use the grid’s source Sass to create your own with more semantic markup. We also include some CSS custom properties to consume these Sass variables for even greater flexibility for you. -## Grid options - -Our grid system can adapt across all {SCSS_VARIABLES['breakpoint-count']} breakpoints. -Each of these breakpoints have their own specifications, a unique class prefix, and some modifiers. - - - ## Auto-layout columns Utilize breakpoint-specific column classes for easy column sizing without an explicit numbered class like `.col-sm-6`. @@ -119,25 +113,3 @@ To nest your content with the default grid, add a new `.row` and set of `.col-*` Note: the style in this example is applied to the column to visually better understand nesting. However, it's recommended to apply the style on a child element of the column. - -## CSS - -When using our source Sass files, you have the option of using Sass variables and mixins to create custom, semantic, and responsive page layouts. Our predefined grid classes use these same variables and mixins to provide a whole suite of ready-to-use classes for fast responsive layouts. - -### Sass variables - -Variables and maps determine the number of columns, the gutter width, and the media query point at which to begin floating columns. We use these to generate the predefined grid classes documented above, as well as for the custom mixins listed below. - - `$${key}: ${formatAsMap(value)};`) - .join('\n')} -> - -### Sass mixins - -Mixins are used in conjunction with the grid variables to generate semantic CSS for individual grid columns. - - diff --git a/packages/documentation/src/stories/foundations/layout/grid/grid.stories.ts b/packages/documentation/src/stories/foundations/layout/grid/grid.stories.ts index c930e97aef..0826654e2a 100644 --- a/packages/documentation/src/stories/foundations/layout/grid/grid.stories.ts +++ b/packages/documentation/src/stories/foundations/layout/grid/grid.stories.ts @@ -25,15 +25,9 @@ export const Basis: Story = { render: () => html`
-
-
Column
-
-
-
Column
-
-
-
Column
-
+
Column
+
Column
+
Column
`, @@ -43,15 +37,11 @@ export const SingleColumnOnly: Story = { render: () => html`
-
-
Don't do this!
-
+
Don't do this!

-
-
Nor this!
-
+
Nor this!

Instead, your content should go here!

@@ -62,24 +52,14 @@ export const SingleColumnOnly: Story = { export const EqualWidth: Story = { render: () => html`
-
-
-
1 of 2
-
-
-
2 of 2
-
+
+
1 of 2
+
2 of 2
-
-
-
1 of 3
-
-
-
2 of 3
-
-
-
3 of 3
-
+
+
1 of 3
+
2 of 3
+
3 of 3
`, @@ -88,27 +68,15 @@ export const EqualWidth: Story = { export const SettingOneColumnWidth: Story = { render: () => html`
-
-
-
1 of 3
-
-
-
2 of 3 (wider)
-
-
-
3 of 3
-
+
+
1 of 3
+
2 of 3 (wider)
+
3 of 3
-
-
-
1 of 3
-
-
-
2 of 3 (wider)
-
-
-
3 of 3
-
+
+
1 of 3
+
2 of 3 (wider)
+
3 of 3
`, @@ -117,27 +85,15 @@ export const SettingOneColumnWidth: Story = { export const VariableWidthContent: Story = { render: () => html`
-
-
-
1 of 3
-
-
-
Variable width content
-
-
-
3 of 3
-
+
+
1 of 3
+
Variable width content
+
3 of 3
-
-
-
1 of 3
-
-
-
Variable width content
-
-
-
3 of 3
-
+
+
1 of 3
+
Variable width content
+
3 of 3
`, @@ -146,27 +102,15 @@ export const VariableWidthContent: Story = { export const AllBreakpoints: Story = { render: () => html`
-
-
-
col
-
-
-
col
-
-
-
col
-
-
-
col
-
+
+
col
+
col
+
col
+
col
-
-
-
col-8
-
-
-
col-4
-
+
+
col-8
+
col-4
`, @@ -175,24 +119,14 @@ export const AllBreakpoints: Story = { export const StackedToHorizontal: Story = { render: () => html`
-
-
-
col-md-8
-
-
-
col-md-4
-
+
+
col-md-8
+
col-md-4
-
-
-
col-md
-
-
-
col-md
-
-
-
col-md
-
+
+
col-md
+
col-md
+
col-md
`, @@ -202,36 +136,22 @@ export const MixAndMatch: Story = { render: () => html`
-
-
-
.col-md-8
-
-
-
.col-6 .col-md-4
-
+
+
.col-md-8
+
.col-6 .col-md-4
-
-
-
.col-6 .col-md-4
-
-
-
.col-6 .col-md-4
-
-
-
.col-6 .col-md-4
-
+
+
.col-6 .col-md-4
+
.col-6 .col-md-4
+
.col-6 .col-md-4
-
-
-
.col-4
-
-
-
.col-8
-
+
+
.col-4
+
.col-8
`, @@ -240,77 +160,39 @@ export const MixAndMatch: Story = { export const RowColumns: Story = { render: () => html`
-
-
-
Column
-
-
-
Column
-
-
-
Column
-
-
-
Column
-
+
+
Column
+
Column
+
Column
+
Column

-
-
-
Column
-
-
-
Column
-
-
-
Column
-
-
-
Column
-
+
+
Column
+
Column
+
Column
+
Column

-
-
-
Column
-
-
-
Column
-
-
-
Column
-
-
-
Column
-
+
+
Column
+
Column
+
Column
+
Column

-
-
-
Column
-
-
-
Column
-
+
+
Column
+
Column
Column
-
-
Column
-
+
Column

-
-
-
Column
-
-
-
Column
-
-
-
Column
-
-
-
Column
-
+
+
Column
+
Column
+
Column
+
Column
`, @@ -320,18 +202,10 @@ export const Gutters: Story = { render: () => html`
-
-
Column
-
-
-
Column
-
-
-
Column
-
-
-
Column
-
+
Column
+
Column
+
Column
+
Column
`, @@ -343,10 +217,10 @@ export const Nested: Story = { }, render: () => html`
-
+
Level 1: .col-md-3
-
+
Level 2: .col-8 .col-md-6
Level 2: .col-4 .col-md-6
diff --git a/packages/documentation/src/stories/foundations/layout/grid/grid.styles.scss b/packages/documentation/src/stories/foundations/layout/grid/grid.styles.scss index 56a47a8877..5781adbbe8 100644 --- a/packages/documentation/src/stories/foundations/layout/grid/grid.styles.scss +++ b/packages/documentation/src/stories/foundations/layout/grid/grid.styles.scss @@ -3,8 +3,7 @@ .grid-example { font-size: post.$font-size-sm; - &.grid-nested-example [class^="col"], - &:not(.grid-nested-example) .my-col-content-style { + [class^="col"] { padding: 0.75rem; background-color: lighten(#0076a8, 60%); border: 1px solid lighten(#004976, 60%); diff --git a/packages/documentation/src/stories/foundations/layout/shared.blocks.tsx b/packages/documentation/src/stories/foundations/layout/shared.blocks.tsx index 73a1f27865..6cbb531f35 100644 --- a/packages/documentation/src/stories/foundations/layout/shared.blocks.tsx +++ b/packages/documentation/src/stories/foundations/layout/shared.blocks.tsx @@ -8,7 +8,7 @@ export const SCSS_VARIABLES: any = parse(scss); export const SpecTable = (props: { children: string | JSX.Element | JSX.Element[] }) => (
- + {forEach(SCSS_VARIABLES.breakpoint, ({ key, value }) => (