Adding examples inside the doc, and small css tweaks

Orange-OpenSource · Nov 25, 2024 · 49afd5e · 49afd5e
1 parent fdaac34
commit 49afd5e
Show file tree

Hide file tree

Showing 12 changed files with 170 additions and 70 deletions.
diff --git a/NOTICE.txt b/NOTICE.txt
@@ -12,6 +12,7 @@ nuget/ouds-web.png
 site/layouts/partials/icons.html
 site/static/docs/**/assets/brand/orange-logo.svg
 site/static/docs/**/assets/brand/orange-social.png
+site/static/docs/**/assets/fonts/solaris-icons.woff2
 site/static/docs/**/assets/img/favicons/android-chrome-192x192.png
 site/static/docs/**/assets/img/favicons/android-chrome-512x512.png
 site/static/docs/**/assets/img/favicons/apple-touch-icon.png

diff --git a/scss/_utilities.scss b/scss/_utilities.scss
@@ -134,11 +134,12 @@ $utilities: map-merge(
     ),
     "translate-middle": (
       property: transform,
-      class: translate-middle,
+      class: translate,
       values: (
-        null: translate(-50%, -50%),
-        x: translateX(-50%),
-        y: translateY(-50%),
+        middle: translate(-50%, -50%), // OUDS mod: instead of `null`
+        middle-x: translateX(-50%), // OUDS mod: instead of `x`
+        middle-y: translateY(-50%), // OUDS mod: instead of `y`
+        none: none // OUDS mod
       )
     ),
     // scss-docs-end utils-position

diff --git a/scss/_variables.scss b/scss/_variables.scss
@@ -805,7 +805,7 @@ $display-line-height: $headings-line-height !default;
 $lead-font-size:              $h5-font-size !default;
 $lead-font-weight:            $ouds-font-weight-body-default !default;
 
-$small-font-size:             .875em !default;
+// OUDS mod: no $small-font-size
 
 $sub-sup-font-size:           .75em !default;
 
@@ -1077,7 +1077,7 @@ $btn-social-networks: (
 
 // scss-docs-start form-text-variables
 $form-text-margin-top:                  .4375rem !default; // OUDS mod
-$form-text-font-size:                   $small-font-size !default;
+$form-text-font-size:                   null !default; // OUDS mod: instead of `$small-font-size`
 $form-text-font-style:                  null !default;
 $form-text-font-weight:                 $font-weight-bold !default; // OUDS mod: instead of `null`
 $form-text-line-height:                 $line-height-sm !default; // OUDS mod
@@ -1347,7 +1347,7 @@ $form-file-button-hover-bg:       var(--#{$prefix}secondary-bg) !default;
 
 // scss-docs-start form-feedback-variables
 $form-feedback-margin-top:          $form-text-margin-top !default;
-$form-feedback-font-size:           $small-font-size !default;
+$form-feedback-font-size:           null !default; // OUDS mod: instead of `$small-font-size`
 $form-feedback-font-style:          null !default;
 // OUDS mod: deprecated in OUDS Web, kept for Bootstrap compatibility
 // fusv-disable
@@ -2059,7 +2059,7 @@ $thumbnail-box-shadow:              var(--#{$prefix}box-shadow-sm) !default;
 // Figures
 
 // scss-docs-start figure-variables
-$figure-caption-font-size:          $small-font-size !default;
+$figure-caption-font-size:          null !default; // OUDS mod: instead of `$small-font-size`
 $figure-caption-color:              var(--#{$prefix}secondary-color) !default;
 // scss-docs-end figure-variables
 
@@ -2228,7 +2228,7 @@ $offcanvas-backdrop-opacity:        $modal-backdrop-opacity !default;
 
 // Code
 // OUDS mod
-$code-font-size:                    $small-font-size !default;
+$code-font-size:                    .875em !default; // OUDS mod: instead of `$small-font-size`
 $code-color:                        $gray-700 !default; // instead of `$pink`
 
 $kbd-padding-y:                     px-to-rem($ouds-space-fixed-smash) !default; // instead of `.1875rem`
@@ -2270,7 +2270,7 @@ $back-to-top-icon-height:        subtract(1rem, 1px) !default;
 
 //// Stepped process
 // scss-docs-start stepped-process
-$stepped-process-font-size:   $small-font-size !default;
+$stepped-process-font-size:   null !default;
 $stepped-process-font-weight: $font-weight-bold !default;
 $stepped-process-max-items:   5 !default;
 $stepped-process-counter:     step !default; // Used as a counter name

diff --git a/scss/helpers/_icon.scss b/scss/helpers/_icon.scss
@@ -1,46 +1,29 @@
 // scss-docs-start ouds-font-icon-common
 %icon-size {
+  display: inline-block;
+  flex-shrink: 0;
   width: 1em;
   height: 1em;
   line-height: 1;
+  vertical-align: middle;
   fill: currentcolor;
-}
-// scss-docs-end ouds-font-icon-common
-
-@each $icon-size in $ouds-icon-sizes {
-  .hxl-#{$icon-size}-icon {
-    @extend %icon-size;
-    font-size: var(--#{$prefix}icon-#{$icon-size}-with-heading-xlarge) if($enable-important-utilities, !important, null);
-  }
-
-  .hl-#{$icon-size}-icon {
-    @extend %icon-size;
-    font-size: var(--#{$prefix}icon-#{$icon-size}-with-heading-large) if($enable-important-utilities, !important, null);
-  }
-
-  .hm-#{$icon-size}-icon {
-    @extend %icon-size;
-    font-size: var(--#{$prefix}icon-#{$icon-size}-with-heading-medium) if($enable-important-utilities, !important, null);
-  }
-
-  .hs-#{$icon-size}-icon {
-    @extend %icon-size;
-    font-size: var(--#{$prefix}icon-#{$icon-size}-with-heading-small) if($enable-important-utilities, !important, null);
-  }
+  transform: translateY(-7%);
 
-  .bl-#{$icon-size}-icon {
-    @extend %icon-size;
-    font-size: var(--#{$prefix}icon-#{$icon-size}-with-body-large) if($enable-important-utilities, !important, null);
-  }
-
-  .bm-#{$icon-size}-icon {
-    @extend %icon-size;
-    font-size: var(--#{$prefix}icon-#{$icon-size}-with-body-medium) if($enable-important-utilities, !important, null);
+  // Overrides Solaris icons default
+  &::before {
+    vertical-align: baseline !important; // stylelint-disable-line declaration-no-important
   }
+}
+// scss-docs-end ouds-font-icon-common
 
-  .bs-#{$icon-size}-icon {
-    @extend %icon-size;
-    font-size: var(--#{$prefix}icon-#{$icon-size}-with-body-small) if($enable-important-utilities, !important, null);
+@each $font-ref, $font-name in $ouds-font-sizes {
+  @each $icon-size in $ouds-icon-sizes {
+    @if str-slice($font-name, 1, 5) != "/code" {
+      .#{$font-ref}-#{$icon-size}-icon {
+        @extend %icon-size;
+        font-size: var(--#{$prefix}icon-#{$icon-size}-with-#{str-slice($font-name, 2)}) if($enable-important-utilities, !important, null);
+      }
+    }
   }
 }
 

diff --git a/scss/mixins/_fonts.scss b/scss/mixins/_fonts.scss
@@ -1,4 +1,6 @@
 // scss-docs-start ouds-mixin-font
+// $font-size-ref can be one of: "code-small", "code-medium", "label-small", "label-medium", "label-large", "label-xlarge", "body-small", "body-medium", "body-large", "heading-small", "heading-medium", "heading-large", "heading-xlarge", "display-small", "display-medium", "display-large"
+
 @mixin get-font-size($font-size-ref: "display-large") {
   @if str-slice($font-size-ref, 1, 5) != "label" and str-slice($font-size-ref, 1, 4) != "code" {
     max-width: var(--#{$prefix}font-max-width-#{$font-size-ref});

diff --git a/site/assets/scss/docs.scss b/site/assets/scss/docs.scss
@@ -64,3 +64,5 @@ $enable-cssgrid: true;
 @import "mixins";
 @import "ouds-web";
 @import "tarteaucitron";
+
+@import "../../static/docs/0.0/assets/fonts/solaris-icons";
diff --git a/site/content/docs/0.0/content/typography.md b/site/content/docs/0.0/content/typography.md
@@ -413,8 +413,6 @@ We provide a dedicated mixin for font reference. For instance, the mixin is `get
 
 {{< scss-docs name="ouds-mixin-font" file="scss/mixins/_fonts.scss" >}}
 
-`$font-size-ref` can be one of:  `"code-small"`,  `"code-medium"`,  `"label-small"`,  `"label-medium"`,  `"label-large"`,  `"label-xlarge"`,  `"body-small"`,  `"body-medium"`,  `"body-large"`,  `"heading-small"`,  `"heading-medium"`,  `"heading-large"`,  `"heading-xlarge"`,  `"display-small"`,  `"display-medium"`,  `"display-large"`.
-
 Whenever you need a font reference inside a custom component or for whatever reason, please follow the same process as us, so you don't miss any information about a font reference.
 
 {{< scss-docs name="ouds-font-implementation" file="scss/_reboot.scss" >}}
diff --git a/site/content/docs/0.0/helpers/icon.md b/site/content/docs/0.0/helpers/icon.md
@@ -16,10 +16,6 @@ Every icon class presented in here has the common following code:
 
 {{< scss-docs name="ouds-font-icon-common" file="scss/helpers/_icon.scss" >}}
 
-## Display headings
-
-You should not use any icon with our `.display-*` font sizes, because we prefer to keep the place for the text.
-
 ## Headings
 
 Here are the rules to follow for headings. These icons' sizes are responsive.
@@ -178,6 +174,10 @@ Here are the rules to follow for headings. These icons' sizes are responsive.
 </h6>
 {{< /example >}}
 
+## Display headings
+
+You should not use any icon with our `.display-*` font sizes, because we prefer to keep the place for the text.
+
 ## Regular texts
 
 Here are the rules to follow for regular texts. These icons' sizes are responsive.
@@ -288,7 +288,7 @@ Here are the rules to follow for decorative icons. Be careful using these icons'
 <div class="bd-example">
   <div class="d-flex mb-medium">
     <div class="bg-secondary d-inline-flex align-items-center justify-content-center me-medium flex-shrink-0" style="width: 6.25rem; height: 6.25rem;">
-      <svg class="decorative-shortest-icon text-info" width="1rem" height="1rem" fill="currentColor" aria-hidden="true">
+      <svg class="decorative-shortest-icon text-info translate-none" width="1rem" height="1rem" fill="currentColor" aria-hidden="true">
         <use xlink:href="/docs/{{< param docs_version >}}/assets/img/ouds-web-sprite.svg#vector"/>
       </svg>
     </div>
@@ -299,7 +299,7 @@ Here are the rules to follow for decorative icons. Be careful using these icons'
   </div>
   <div class="d-flex mb-medium">
     <div class="bg-secondary d-inline-flex align-items-center justify-content-center me-medium flex-shrink-0" style="width: 6.25rem; height: 6.25rem;">
-      <svg class="decorative-shorter-icon text-info" width="1rem" height="1rem" fill="currentColor" aria-hidden="true">
+      <svg class="decorative-shorter-icon text-info translate-none" width="1rem" height="1rem" fill="currentColor" aria-hidden="true">
         <use xlink:href="/docs/{{< param docs_version >}}/assets/img/ouds-web-sprite.svg#vector"/>
       </svg>
     </div>
@@ -310,7 +310,7 @@ Here are the rules to follow for decorative icons. Be careful using these icons'
   </div>
   <div class="d-flex mb-medium">
     <div class="bg-secondary d-inline-flex align-items-center justify-content-center me-medium flex-shrink-0" style="width: 6.25rem; height: 6.25rem;">
-      <svg class="decorative-short-icon text-info" width="1rem" height="1rem" fill="currentColor" aria-hidden="true">
+      <svg class="decorative-short-icon text-info translate-none" width="1rem" height="1rem" fill="currentColor" aria-hidden="true">
         <use xlink:href="/docs/{{< param docs_version >}}/assets/img/ouds-web-sprite.svg#vector"/>
       </svg>
     </div>
@@ -321,7 +321,7 @@ Here are the rules to follow for decorative icons. Be careful using these icons'
   </div>
   <div class="d-flex mb-medium">
     <div class="bg-secondary d-inline-flex align-items-center justify-content-center me-medium flex-shrink-0" style="width: 6.25rem; height: 6.25rem;">
-      <svg class="decorative-medium-icon text-info" width="1rem" height="1rem" fill="currentColor" aria-hidden="true">
+      <svg class="decorative-medium-icon text-info translate-none" width="1rem" height="1rem" fill="currentColor" aria-hidden="true">
         <use xlink:href="/docs/{{< param docs_version >}}/assets/img/ouds-web-sprite.svg#vector"/>
       </svg>
     </div>
@@ -332,7 +332,7 @@ Here are the rules to follow for decorative icons. Be careful using these icons'
   </div>
   <div class="d-flex mb-medium">
     <div class="bg-secondary d-inline-flex align-items-center justify-content-center me-medium flex-shrink-0" style="width: 6.25rem; height: 6.25rem;">
-      <svg class="decorative-tall-icon text-info" width="1rem" height="1rem" fill="currentColor" aria-hidden="true">
+      <svg class="decorative-tall-icon text-info translate-none" width="1rem" height="1rem" fill="currentColor" aria-hidden="true">
         <use xlink:href="/docs/{{< param docs_version >}}/assets/img/ouds-web-sprite.svg#vector"/>
       </svg>
     </div>
@@ -343,7 +343,7 @@ Here are the rules to follow for decorative icons. Be careful using these icons'
   </div>
   <div class="d-flex mb-medium">
     <div class="bg-secondary d-inline-flex align-items-center justify-content-center me-medium flex-shrink-0" style="width: 6.25rem; height: 6.25rem;">
-      <svg class="decorative-taller-icon text-info" width="1rem" height="1rem" fill="currentColor" aria-hidden="true">
+      <svg class="decorative-taller-icon text-info translate-none" width="1rem" height="1rem" fill="currentColor" aria-hidden="true">
         <use xlink:href="/docs/{{< param docs_version >}}/assets/img/ouds-web-sprite.svg#vector"/>
       </svg>
     </div>
@@ -354,7 +354,7 @@ Here are the rules to follow for decorative icons. Be careful using these icons'
   </div>
   <div class="d-flex mb-medium">
     <div class="bg-secondary d-inline-flex align-items-center justify-content-center me-medium flex-shrink-0" style="width: 6.25rem; height: 6.25rem;">
-      <svg class="decorative-tallest-icon text-info" width="1rem" height="1rem" fill="currentColor" aria-hidden="true">
+      <svg class="decorative-tallest-icon text-info translate-none" width="1rem" height="1rem" fill="currentColor" aria-hidden="true">
         <use xlink:href="/docs/{{< param docs_version >}}/assets/img/ouds-web-sprite.svg#vector"/>
       </svg>
     </div>
@@ -366,15 +366,90 @@ Here are the rules to follow for decorative icons. Be careful using these icons'
 </div>
 
 ```html
-<svg class="decorative-shortest-icon text-info" width="1rem" height="1rem" fill="currentColor" aria-hidden="true"></svg>
-<svg class="decorative-shorter-icon text-info" width="1rem" height="1rem" fill="currentColor" aria-hidden="true"></svg>
-<svg class="decorative-short-icon text-info" width="1rem" height="1rem" fill="currentColor" aria-hidden="true"></svg>
-<svg class="decorative-medium-icon text-info" width="1rem" height="1rem" fill="currentColor" aria-hidden="true"></svg>
-<svg class="decorative-tall-icon text-info" width="1rem" height="1rem" fill="currentColor" aria-hidden="true"></svg>
-<svg class="decorative-taller-icon text-info" width="1rem" height="1rem" fill="currentColor" aria-hidden="true"></svg>
-<svg class="decorative-tallest-icon text-info" width="1rem" height="1rem" fill="currentColor" aria-hidden="true"></svg>
+<svg class="decorative-shortest-icon text-info translate-none" width="1rem" height="1rem" fill="currentColor" aria-hidden="true"></svg>
+<svg class="decorative-shorter-icon text-info translate-none" width="1rem" height="1rem" fill="currentColor" aria-hidden="true"></svg>
+<svg class="decorative-short-icon text-info translate-none" width="1rem" height="1rem" fill="currentColor" aria-hidden="true"></svg>
+<svg class="decorative-medium-icon text-info translate-none" width="1rem" height="1rem" fill="currentColor" aria-hidden="true"></svg>
+<svg class="decorative-tall-icon text-info translate-none" width="1rem" height="1rem" fill="currentColor" aria-hidden="true"></svg>
+<svg class="decorative-taller-icon text-info translate-none" width="1rem" height="1rem" fill="currentColor" aria-hidden="true"></svg>
+<svg class="decorative-tallest-icon text-info translate-none" width="1rem" height="1rem" fill="currentColor" aria-hidden="true"></svg>
 ```
 
+## `<img>` and font icon
+
+SVG Sprite is the preferred choice for flexibility, performance and accessibility but there are other ways to display icons. <!-- Check out for more information in [our documentation]({{< docsref "/extend/icons" >}}). -->
+
+{{< example >}}
+<h1>
+  <img class="hxl-tall-icon me-short" alt="" src="/docs/{{< param docs_version >}}/assets/img/vite.svg">
+  H1 with tall icon
+</h1>
+<h1>
+  <span class="hxl-tall-icon me-short si si-settings" aria-hidden="true"></span>
+  H1 with tall icon
+</h1>
+{{< /example >}}
+
+## Multiple lines
+
+Sometimes you need a different structure to handle larger titles, or paragraphs that wrap over several lines. Here are some examples to handle these use cases.
+
+{{< example >}}
+<h1>
+  <svg class="hxl-tall-icon me-short text-info" width="1rem" height="1rem" fill="currentColor" aria-hidden="true">
+    <use xlink:href="/docs/{{< param docs_version >}}/assets/img/ouds-web-sprite.svg#vector"/>
+  </svg>
+  H1 with tall icon and a very long title to see how it behaves while being wrapped
+</h1>
+
+<!-- Prefer use this -->
+<div class="d-flex">
+  <svg class="hxl-tall-icon me-scaled-short text-info translate-none" width="1rem" height="1rem" fill="currentColor" aria-hidden="true">
+    <use xlink:href="/docs/{{< param docs_version >}}/assets/img/ouds-web-sprite.svg#vector"/>
+  </svg>
+  <h1 class="pt-shorter pt-md-short pt-xl-shorter">H1 with tall icon and a very long title to see how it behaves while being wrapped</h1>
+</div>
+<div class="d-flex">
+  <img class="hxl-tall-icon me-scaled-short translate-none" alt="" src="/docs/{{< param docs_version >}}/assets/img/vite.svg">
+  <h1 class="pt-shorter pt-md-short pt-xl-shorter">H1 with tall icon and a very long title to see how it behaves while being wrapped</h1>
+</div>
+<div class="d-flex">
+  <span class="hxl-tall-icon me-scaled-short si si-settings translate-none" aria-hidden="true"></span>
+  <h1 class="pt-shorter pt-md-short pt-xl-shorter">H1 with tall icon and a very long title to see how it behaves while being wrapped</h1>
+</div>
+{{< /example >}}
+
+{{< example >}}
+<p>
+  <svg class="bm-tall-icon me-short text-info" width="1rem" height="1rem" fill="currentColor" aria-hidden="true">
+    <use xlink:href="/docs/{{< param docs_version >}}/assets/img/ouds-web-sprite.svg#vector"/>
+  </svg>
+  Default long paragraph with tall icon. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent fermentum diam consequat, fermentum sem nec, malesuada eros. Praesent eu lectus ligula. Nullam et est in augue pharetra ultricies quis non orci.
+</p>
+
+<!-- Prefer use this -->
+<div class="d-flex">
+  <svg class="bm-tall-icon me-scaled-short text-info translate-none" width="1rem" height="1rem" fill="currentColor" aria-hidden="true">
+    <use xlink:href="/docs/{{< param docs_version >}}/assets/img/ouds-web-sprite.svg#vector"/>
+  </svg>
+  <p class="pt-smash">
+    Default long paragraph with tall icon. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent fermentum diam consequat, fermentum sem nec, malesuada eros. Praesent eu lectus ligula. Nullam et est in augue pharetra ultricies quis non orci. class="pt-smash"
+  </p>
+</div>
+<div class="d-flex">
+  <img class="bm-tall-icon me-scaled-short translate-none" alt="" src="/docs/{{< param docs_version >}}/assets/img/vite.svg">
+  <p class="pt-smash">
+    Default long paragraph with tall icon. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent fermentum diam consequat, fermentum sem nec, malesuada eros. Praesent eu lectus ligula. Nullam et est in augue pharetra ultricies quis non orci.
+  </p>
+</div>
+<div class="d-flex">
+  <span class="bm-tall-icon me-scaled-short si si-settings translate-none" aria-hidden="true"></span>
+  <p class="pt-smash">
+    Default long paragraph with tall icon. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Praesent fermentum diam consequat, fermentum sem nec, malesuada eros. Praesent eu lectus ligula. Nullam et est in augue pharetra ultricies quis non orci.
+  </p>
+</div>
+{{< /example >}}
+
 ## CSS
 
 ### Variables