Proposal for migration guides

Orange-OpenSource · Oct 16, 2024 · 3b56854 · 3b56854
1 parent 7b22c26
commit 3b56854
Show file tree

Hide file tree

Showing 2 changed files with 130 additions and 36 deletions.
diff --git a/site/content/docs/0.0/migration-from-boosted.md b/site/content/docs/0.0/migration-from-boosted.md
@@ -59,10 +59,20 @@ Technically, it means that you can get rid of the following things:
   - `xxl` has been renamed `2xl`.
   - `2xs` and `3xl` have been added.
   - The breakpoints values have changed. Please refer to the [breakpoints' documentation]({{< docsref "/layout/breakpoints/" >}}).
+  - `.col-{breakpoint}-{number}`, `.g-col-{}
   - The default container to use is now `.container-fluid` associated to `.max-width-public-website` or `.max-width-specific-tools` instead of `.container-xxl` (which doesn't exist anymore). Please refer to the [fluid containers' documentation]({{< docsref "/layout/containers/#fluid-containers" >}}).
+  - Default gutter inside grid have been changed to have a fully responsive behavior. It should be a transparent change for you.
+  - All gutter utilities have been changed. `.g{-breakpoint}-{value}`, `.gx{-breakpoint}-{value}` and `.gy{-breakpoint}-{value}` which value is inside `0|1|2|3|4|5`. Gutter utilities values now use `none|smash|shortest|shorter|short|medium|tall|taller|tallest|spacious|huge|jumbo`. Proportional equivalence between `0` → `none`, `1` → `shortest`, `2` → `shorter`, `3` → `medium`, `4` → `tall`, `5` → `spacious`.
 
   All responsive classes, helpers and utilities have been changed accordingly to the new breakpoints.
 
+## Helpers
+
+### Position
+
+- <span class="badge text-bg-danger">Breaking</span> Responsive sticky helpers `.sticky-xxl-{top|bottom}` have been removed and replaced by their equivalent `.sticky-2xl-{top|bottom}`.
+- <span class="badge text-bg-success">New</span> Responsive sticky helpers: `.sticky-xs-{top|bottom}`, `.sticky-2xl-{top|bottom}` and `.sticky-3xl-{top|bottom}`.
+
 ## Utilities
 
 ### Border
@@ -113,8 +123,6 @@ Technically, it means that you can get rid of the following things:
 - <span class="badge text-bg-danger">Breaking</span> `xxl` responsive object fit utilities have been replaced by `2xl` utilities: `.object-fit-xxl-{contain|cover|fill|scale|none}` utilities have been replaced by ``.object-fit-2xl-{contain|cover|fill|scale|none}``. Please refer to the [new breakpoints' names]({{< docsref "/layout/breakpoints/#available-breakpoints" >}}).
 - <span class="badge text-bg-success">New</span> `xs` and `3xl` responsive object fit utilities have been added:  `.object-fit-xs-{contain|cover|fill|scale|none}` and  `.object-fit-3xl-{contain|cover|fill|scale|none}`. Please refer to the [new breakpoints' names]({{< docsref "/layout/breakpoints/#available-breakpoints" >}}).
 
-
-
 ### Opacity
 
 - <span class="badge text-bg-danger">Breaking</span> `.opacity-0`, `.opacity-25`, `.opacity-50`, `.opacity-75` and `.opacity-100` have been removed from the default build. Please check the new [opacity values]({{< docsref "/utilities/opacity" >}}) directly in the documentation and adapt your websites to them. You can still have them using `$enable-bootstrap-compatibility`.
@@ -126,6 +134,10 @@ Technically, it means that you can get rid of the following things:
 - <span class="badge text-bg-success">New</span> Shadows utilities:
 `shadow-none`, `shadow-raised`, `shadow-drag`, `shadow-overlay-default`, `shadow-overlay-emphasized`, `shadow-sticky-default`, `shadow-sticky-emphasized`, `shadow-sticky-navigation-scrolled` and `shadow-focus`.
 
+## Examples
+
+- <span class="badge text-bg-success">New</span> New OUDS Web [example for the usable grids]({{< docsref "/examples/grid-system" >}}).
+
 ## CSS and Sass variables
 
 - <span class="badge text-bg-success">New</span> `$enable-bootstrap-compatibility` option set to `false` by default. This option allows you to compile the Sass files with a Bootstrap compatibility mode.
@@ -238,6 +250,53 @@ Technically, it means that you can get rid of the following things:
       <li><code>$ouds-elevation-y-sticky-default</code></li>
       <li><code>$ouds-elevation-y-sticky-emphasized</code></li>
       <li><code>$ouds-elevation-y-sticky-navigation-scrolled</code></li>
+      <li><code>$ouds-grid-2xl-column-gap</code></li>
+      <li><code>$ouds-grid-2xl-margin</code></li>
+      <li><code>$ouds-grid-2xl-max-width-public-website</code></li>
+      <li><code>$ouds-grid-2xl-min-width</code></li>
+      <li><code>$ouds-grid-2xs-column-gap</code></li>
+      <li><code>$ouds-grid-2xs-margin</code></li>
+      <li><code>$ouds-grid-3xl-column-gap</code></li>
+      <li><code>$ouds-grid-3xl-margin</code></li>
+      <li><code>$ouds-grid-3xl-max-width</code></li>
+      <li><code>$ouds-grid-3xl-min-width</code></li>
+      <li><code>$ouds-grid-column-gap-100</code></li>
+      <li><code>$ouds-grid-column-gap-200</code></li>
+      <li><code>$ouds-grid-column-gap-400</code></li>
+      <li><code>$ouds-grid-column-gap-600</code></li>
+      <li><code>$ouds-grid-column-gap-800</code></li>
+      <li><code>$ouds-grid-margin-100</code></li>
+      <li><code>$ouds-grid-margin-1100</code></li>
+      <li><code>$ouds-grid-margin-1700</code></li>
+      <li><code>$ouds-grid-margin-2500</code></li>
+      <li><code>$ouds-grid-margin-300</code></li>
+      <li><code>$ouds-grid-margin-400</code></li>
+      <li><code>$ouds-grid-margin-500</code></li>
+      <li><code>$ouds-grid-margin-700</code></li>
+      <li><code>$ouds-grid-max-width-650</code></li>
+      <li><code>$ouds-grid-max-width-800</code></li>
+      <li><code>$ouds-grid-md-column-gap</code></li>
+      <li><code>$ouds-grid-md-margin</code></li>
+      <li><code>$ouds-grid-md-min-width</code></li>
+      <li><code>$ouds-grid-min-width-200</code></li>
+      <li><code>$ouds-grid-min-width-300</code></li>
+      <li><code>$ouds-grid-min-width-400</code></li>
+      <li><code>$ouds-grid-min-width-500</code></li>
+      <li><code>$ouds-grid-min-width-600</code></li>
+      <li><code>$ouds-grid-min-width-700</code></li>
+      <li><code>$ouds-grid-min-width-800</code></li>
+      <li><code>$ouds-grid-lg-column-gap</code></li>
+      <li><code>$ouds-grid-lg-margin</code></li>
+      <li><code>$ouds-grid-lg-min-width</code></li>
+      <li><code>$ouds-grid-sm-column-gap</code></li>
+      <li><code>$ouds-grid-sm-margin</code></li>
+      <li><code>$ouds-grid-sm-min-width</code></li>
+      <li><code>$ouds-grid-xl-column-gap</code></li>
+      <li><code>$ouds-grid-xl-margin</code></li>
+      <li><code>$ouds-grid-xl-min-width</code></li>
+      <li><code>$ouds-grid-xs-column-gap</code></li>
+      <li><code>$ouds-grid-xs-margin</code></li>
+      <li><code>$ouds-grid-xs-min-width</code></li>
       <li><code>$ouds-opacity-0</code></li>
       <li><code>$ouds-opacity-100</code></li>
       <li><code>$ouds-opacity-300</code></li>
@@ -256,6 +315,7 @@ Technically, it means that you can get rid of the following things:
 - <details class="mb-2">
     <summary><span class="badge text-bg-success">New</span> Sass maps:</summary>
     <ul>
+      <li><code>$grid-gutter-widths</code></li>
       <li><code>$ouds-border-radiuses</code></li>
       <li><code>$ouds-border-styles</code></li>
       <li><code>$ouds-border-widths</code></li>
@@ -309,6 +369,7 @@ Technically, it means that you can get rid of the following things:
       <li><code>$form-star-focus-color-dark</code></li>
       <li><code>$form-star-focus-outline</code></li>
       <li><code>$form-star-focus-outline-dark</code></li>
+      <li><code>$grid-gutter-breakpoint</code></li>
       <li><code>$orange-filter</code></li>
       <li><code>$outline-offset</code></li>
       <li><code>$outline-width</code></li>
@@ -344,7 +405,6 @@ Technically, it means that you can get rid of the following things:
       <li><code>--bs-box-shadow-inset</code></li>
       <li><code>--bs-box-shadow-lg</code></li>
       <li><code>--bs-box-shadow-sm</code></li>
-
     </ul>
   </details>
 
@@ -367,3 +427,5 @@ Technically, it means that you can get rid of the following things:
       <li><code>shadow</code></li>
     </ul>
   </details>
+
+- <span class="badge text-bg-warning">Warning</span> OUDS Web changes the signature of `make-row($gutter, $gutter-sm)` to have `make-row($gutter)`.
diff --git a/site/content/docs/0.0/migration.md b/site/content/docs/0.0/migration.md
@@ -15,15 +15,17 @@ toc: true
 
 - <span class="badge text-bg-success">New</span> Responsive flexbox grid system is now available with eight default responsive tiers defined at breakpoints `2xs`, `xs`, `sm`, `md`, `xl`, `2xl` and `3xl`.
   - Containers classes: `.container`, `.container-fluid` and `.container-{breakpoint}`
+  - Limiting classes: `.max-width-public-website` and `.max-width-specific-tools`
   - Row columns classes: `.row-cols-{number}`
-  - Column classes: `.col`, `.col-{breakpoint}`,  and `.offset-{breakpoint}`
+  - Column classes: `.col-{number}`, `.col-{breakpoint}-{number}`,  and `.offset-{breakpoint}-{number}`
 
 - <span class="badge text-bg-success">New</span> Responsive css-grid classes: `.g-col-{breakpoint}-{number}`.
 
 ### Helpers
 
 #### Position
-- <span class="badge text-bg-success">New</span> Responsive sticky helpers: `.sticky-{breakpoint}-top` and `.sticky-{breakpoint}-bottom`.
+
+- <span class="badge text-bg-success">New</span> Responsive sticky helpers: `.sticky-{breakpoint}-top` and `.sticky-{breakpoint}-bottom` where `breakpoint` is in `|xs|sm|md|lg|xl|2xl|3xl`.
 
 ### Utilities
 
@@ -46,20 +48,20 @@ toc: true
 
 #### Display
 
-- <span class="badge text-bg-success">New</span> Responsive display utilities: `.d-{breakpoint}-{value}`.
+- <span class="badge text-bg-success">New</span> Responsive display utilities: `.d-{breakpoint}-{value}` where `breakpoint` is in `|xs|sm|md|lg|xl|2xl|3xl`.
 
 #### Flex
 
-- <span class="badge text-bg-success">New</span> Responsive flex utilities:
+- <span class="badge text-bg-success">New</span> Responsive flex utilities where `breakpoint` is in `|xs|sm|md|lg|xl|2xl|3xl`:
   `.d-{breakpoint}-flex`, `.d-{breakpoint}-inline-flex`, `.flex-{breakpoint}-{row|column}`, `.flex-{breakpoint}-{row|column}-reverse`, `.justify-content-{breakpoint}-{start|end|center|between|around|evenly}`, `.align-items-{breakpoint}-{start|end|center|baseline|stretch}`, `.align-self-{breakpoint}-{start|end|center|baseline|stretch}`, `.flex-{breakpoint}-fill`, `flex-{breakpoint}-{grow|shrink}-{0|1}`, `.flex-{breakpoint}-{nowrap|wrap|wrap-reverse}`, `.order-{breakpoint}-{number}`, `.order-{breakpoint}-{first|last}` and `.align-content-{breakpoint}-{start|end|center|between|around|stretch}`.
 
 #### Float
 
-- <span class="badge text-bg-success">New</span> Responsive float utilities: `.float-{breakpoint}-{start|end|none}`.
+- <span class="badge text-bg-success">New</span> Responsive float utilities: `.float-{breakpoint}-{start|end|none}` where `breakpoint` is in `|xs|sm|md|lg|xl|2xl|3xl`.
 
 #### Object fit
 
-- <span class="badge text-bg-success">New</span> Responsive object fit utilities: `.object-fit-{breakpoint}-{contain|cover|fill|scale|none}`.
+- <span class="badge text-bg-success">New</span> Responsive object fit utilities: `.object-fit-{breakpoint}-{contain|cover|fill|scale|none}` where `breakpoint` is in `|xs|sm|md|lg|xl|2xl|3xl`.
 
 #### Opacity
 
@@ -70,6 +72,12 @@ toc: true
 - <span class="badge text-bg-success">New</span> Shadows utilities:
   `shadow-none`, `shadow-raised`, `shadow-drag`, `shadow-overlay-default`, `shadow-overlay-emphasized`, `shadow-sticky-default`, `shadow-sticky-emphasized`, `shadow-sticky-navigation-scrolled` and `shadow-focus`.
 
+### Examples
+
+- <span class="badge text-bg-success">New</span> New OUDS Web [example for the grids]({{< docsref "/examples/grid" >}}).
+
+- <span class="badge text-bg-success">New</span> New OUDS Web [example for the usable grids]({{< docsref "/examples/grid-system" >}}).
+
 ### CSS and Sass variables
 
 - <span class="badge text-bg-success">New</span> A new file containing maps of token for utilities has been added. If you were using the Sass compilation, you must import this new Sass file before the variables.
@@ -174,43 +182,67 @@ toc: true
       <li><code>$ouds-elevation-y-sticky-default</code></li>
       <li><code>$ouds-elevation-y-sticky-emphasized</code></li>
       <li><code>$ouds-elevation-y-sticky-navigation-scrolled</code></li>
+      <li><code>$ouds-grid-2xl-column-gap</code></li>
+      <li><code>$ouds-grid-2xl-margin</code></li>
+      <li><code>$ouds-grid-2xl-max-width-public-website</code></li>
+      <li><code>$ouds-grid-2xl-min-width</code></li>
+      <li><code>$ouds-grid-2xs-column-gap</code></li>
+      <li><code>$ouds-grid-2xs-margin</code></li>
+      <li><code>$ouds-grid-3xl-column-gap</code></li>
+      <li><code>$ouds-grid-3xl-margin</code></li>
+      <li><code>$ouds-grid-3xl-max-width</code></li>
+      <li><code>$ouds-grid-3xl-min-width</code></li>
+      <li><code>$ouds-grid-column-gap-100</code></li>
+      <li><code>$ouds-grid-column-gap-200</code></li>
+      <li><code>$ouds-grid-column-gap-400</code></li>
+      <li><code>$ouds-grid-column-gap-600</code></li>
+      <li><code>$ouds-grid-column-gap-800</code></li>
+      <li><code>$ouds-grid-margin-100</code></li>
+      <li><code>$ouds-grid-margin-1100</code></li>
+      <li><code>$ouds-grid-margin-1700</code></li>
+      <li><code>$ouds-grid-margin-2500</code></li>
+      <li><code>$ouds-grid-margin-300</code></li>
+      <li><code>$ouds-grid-margin-400</code></li>
+      <li><code>$ouds-grid-margin-500</code></li>
+      <li><code>$ouds-grid-margin-700</code></li>
+      <li><code>$ouds-grid-max-width-650</code></li>
+      <li><code>$ouds-grid-max-width-800</code></li>
+      <li><code>$ouds-grid-md-column-gap</code></li>
+      <li><code>$ouds-grid-md-margin</code></li>
+      <li><code>$ouds-grid-md-min-width</code></li>
+      <li><code>$ouds-grid-min-width-200</code></li>
+      <li><code>$ouds-grid-min-width-300</code></li>
+      <li><code>$ouds-grid-min-width-400</code></li>
+      <li><code>$ouds-grid-min-width-500</code></li>
+      <li><code>$ouds-grid-min-width-600</code></li>
+      <li><code>$ouds-grid-min-width-700</code></li>
+      <li><code>$ouds-grid-min-width-800</code></li>
+      <li><code>$ouds-grid-lg-column-gap</code></li>
+      <li><code>$ouds-grid-lg-margin</code></li>
+      <li><code>$ouds-grid-lg-min-width</code></li>
+      <li><code>$ouds-grid-sm-column-gap</code></li>
+      <li><code>$ouds-grid-sm-margin</code></li>
+      <li><code>$ouds-grid-sm-min-width</code></li>
+      <li><code>$ouds-grid-xl-column-gap</code></li>
+      <li><code>$ouds-grid-xl-margin</code></li>
+      <li><code>$ouds-grid-xl-min-width</code></li>
+      <li><code>$ouds-grid-xs-column-gap</code></li>
+      <li><code>$ouds-grid-xs-margin</code></li>
+      <li><code>$ouds-grid-xs-min-width</code></li>
       <li><code>$ouds-opacity-medium</code></li>
       <li><code>$ouds-opacity-opaque</code></li>
       <li><code>$ouds-opacity-strong</code></li>
       <li><code>$ouds-opacity-transparent</code></li>
       <li><code>$ouds-opacity-weak</code></li>
       <li><code>$ouds-opacity-weaker</code></li>
-      <li><code>$ouds-grid-2xs-margin</code></li>
-      <li><code>$ouds-grid-2xs-column-gap</code></li>
-      <li><code>$ouds-grid-xs-min-width</code></li>
-      <li><code>$ouds-grid-xs-margin</code></li>
-      <li><code>$ouds-grid-xs-column-gap</code></li>
-      <li><code>$ouds-grid-sm-min-width</code></li>
-      <li><code>$ouds-grid-sm-margin</code></li>
-      <li><code>$ouds-grid-sm-column-gap</code></li>
-      <li><code>$ouds-grid-md-min-width</code></li>
-      <li><code>$ouds-grid-md-margin</code></li>
-      <li><code>$ouds-grid-md-column-gap</code></li>
-      <li><code>$ouds-grid-lg-min-width</code></li>
-      <li><code>$ouds-grid-lg-margin</code></li>
-      <li><code>$ouds-grid-lg-column-gap</code></li>
-      <li><code>$ouds-grid-xl-min-width</code></li>
-      <li><code>$ouds-grid-xl-margin</code></li>
-      <li><code>$ouds-grid-xl-column-gap</code></li>
-      <li><code>$ouds-grid-2xl-min-width</code></li>
-      <li><code>$ouds-grid-2xl-max-width-public-website</code></li>
-      <li><code>$ouds-grid-2xl-margin</code></li>
-      <li><code>$ouds-grid-2xl-column-gap</code></li>
-      <li><code>$ouds-grid-3xl-min-width</code></li>
-      <li><code>$ouds-grid-3xl-max-width</code></li>
-      <li><code>$ouds-grid-3xl-margin</code></li>
-      <li><code>$ouds-grid-3xl-column-gap</code></li>
     </ul>
   </details>
 
 - <details class="mb-2">
     <summary><span class="badge text-bg-success">New</span> Sass maps:</summary>
     <ul>
+      <li><code>$grid-gutter-widths</code></li>
+      <li><code>$gutters</code></li>
       <li><code>$ouds-border-radiuses</code></li>
       <li><code>$ouds-border-styles</code></li>
       <li><code>$ouds-border-widths</code></li>
@@ -274,9 +306,9 @@ toc: true
   </details>
 
 - <details class="mb-2">
-    <summary><span class="badge text-bg-danger">Breaking</span> Dropped Sass variables:</summary>
+    <summary><span class="badge text-bg-success">New</span> CSS variable:</summary>
     <ul>
-      <li><code>$grid-gutter-breakpoint</code></li>
+      <li><code>--bs-container-margin-x</code></li>
     </ul>
   </details>