@undrr/undrr-mangrove 1.4.0 → 1.5.0

package/scss/Atom/Icons/icons.scss

@@ -1,21 +1,31 @@
 // Mangrove Icon System
-// A custom icon font with mg-icon-* namespaced classes (preferred) and fa-* legacy support.
+// Icons render via CSS mask-image backed by SVG data URIs (Lucide, OCHA, custom sources).
+// The icon font is retained as a fallback for legacy fa-* selectors during migration.
 // Usage:
-//   <span class="mg-icon mg-icon-globe"></span>     (Preferred)
-//   <span class="mg-icon fa-globe"></span>           (Legacy, still supported)
-// Migration note: New code should use mg-icon-* classes. fa-* classes are maintained
-// for backward compatibility but may be deprecated in future versions.
-// More at: https://gitlab.com/undrr/web-backlog/-/issues/927
-// Font references: https://fontawesome.com/v4/assets/font-awesome/css/font-awesome.css
+//   <span class="mg-icon mg-icon-globe"></span>           (Preferred)
+//   <span class="mg-icon mg-icon-globe" style="color: orange"></span>
+//   <span class="mg-icon fa-globe"></span>                (Legacy, still supported via font)
+// See: https://github.com/unisdr/undrr-mangrove/issues/906
+
+// Icon definitions (auto-generated by scripts/icon-build.cjs).
+// Must be imported before any rules to satisfy CSS @import ordering.
+@import "icon-definitions";
+
+// Font fallback (kept for fa-* selectors — removed in phase 4)
 
 @font-face {
   font-family: FontAwesome;
   font-weight: normal;
   src:
-    url("#{$mgIconFontPath}/mangrove-icon-set.ttf") format("ttf"),
-    url("#{$mgIconFontPath}/mangrove-icon-set.woff2") format("woff2");
+    url("#{$mgIconFontPath}/mangrove-icon-set.woff2") format("woff2"),
+    url("#{$mgIconFontPath}/mangrove-icon-set.ttf") format("truetype");
 }
 
+// Font-family applies to .mg-icon unconditionally. For mask-image icons this
+// is harmless — the ::before pseudo-element uses content: "" which renders
+// nothing from the font. For fa-* icons this is required for glyph rendering.
+// This avoids the [class*="mg-icon-"] selector which falsely matches BEM
+// modifiers like mg-icon--lg.
 .mg-icon,
 .fa-before:before,
 .fab,
@@ -25,16 +35,6 @@
   font-style: normal;
 }
 
-.mg-icon {
-  // Improve font rendering quality
-  font-smooth: never;
-  -webkit-font-smoothing: antialiased;
-  -moz-osx-font-smoothing: grayscale;
-  text-rendering: optimizeLegibility;
-  transform: translateZ(0); // Force hardware acceleration
-  backface-visibility: hidden; // Prevent blur during transforms
-}
-
 .fa-before:before {
   padding-right: 0.5em;
 }
@@ -43,231 +43,152 @@
   font-size: 2em;
 }
 
-// =============================================================================
-// Icon Definitions
-// Each icon has both mg-icon-* (preferred) and fa-* (legacy) selectors grouped together
-// =============================================================================
-
-// RSS
-.mg-icon-rss:before,
-.fa-rss:before {
-  content: "\f09e";
-}
-
-// File/Document
-.mg-icon-file-alt:before,
-.fa-file-alt:before {
-  content: "\f15c";
-}
-
-.mg-icon-file:before,
-.fa-file:before {
-  content: "\f15b";
-}
+// Legacy fa-* icon definitions (font-based, removed in phase 4)
+// These keep the font rendering path alive for code that uses fa-* classes.
+// Bare fa-* selectors (specificity 0,1,1) are safe because the base mask rule
+// uses :not([class*="fa-"]) (specificity 0,2,1) and is excluded for these elements.
 
-// Social Media
-.mg-icon-facebook:before,
-.fa-facebook:before {
-  content: "\f230";
-}
+.fa-rss:before { content: "\f09e"; }
+.fa-file-alt:before { content: "\f15c"; }
+.fa-file:before { content: "\f15b"; }
+.fa-facebook:before { content: "\f230"; }
 
-.mg-icon-x-social:before,
-.mg-icon-twitter:before,
 .fa-x-social:before,
-.fa-twitter:before {
-  content: "\f099";
-}
-
-.mg-icon-linkedin:before,
-.fa-linkedin:before {
-  content: "\f0e1";
-}
-
-.mg-icon-flickr:before,
-.fa-flickr:before {
-  content: "\f16e";
-}
-
-.mg-icon-youtube:before,
-.fa-youtube:before {
-  content: "\f16a";
-}
+.fa-twitter:before { content: "\f099"; }
 
-// Search
-.mg-icon-search:before,
-.fa-search:before {
-  content: "\e808";
-}
+.fa-linkedin:before { content: "\f0e1"; }
+.fa-flickr:before { content: "\f16e"; }
+.fa-youtube:before { content: "\f16a"; }
+.fa-search:before { content: "\e808"; }
 
-// Communication
-.mg-icon-envelope:before,
 .fa-envelope:before,
-.fa-envelope-o:before {
-  content: "\e806";
-}
+.fa-envelope-o:before { content: "\e806"; }
 
-// Media
-.mg-icon-newspaper:before,
-.fa-newspaper:before {
-  content: "\f1ea";
-}
+.fa-newspaper:before { content: "\f1ea"; }
 
-// Charts & Data
-.mg-icon-chart-bar:before,
-.mg-icon-bar-chart:before,
 .fa-chart-bar:before,
-.fa-bar-chart:before {
-  content: "\e80B";
-}
-
-// Education
-.mg-icon-graduation-cap:before,
-.fa-graduation-cap:before {
-  content: "\f19D";
-}
-
-// Calendar
-.mg-icon-calendar:before,
-.mg-icon-calendar-alt:before,
-.fa-calendar-alt:before {
-  content: "\f133";
-}
+.fa-bar-chart:before { content: "\e80B"; }
+
+.fa-graduation-cap:before { content: "\f19D"; }
+.fa-calendar-alt:before { content: "\f133"; }
+.fa-building:before { content: "\f0F7"; }
+.fa-landmark:before { content: "\f19c"; }
+.fa-pen-nib:before { content: "\f0f6"; }
+.fa-business-time:before { content: "\e809"; }
+.fa-code-branch:before { content: "\f126"; }
+.fa-life-ring:before { content: "\f1cd"; }
+.fa-lightbulb:before { content: "\f0eb"; }
+.fa-cubes:before { content: "\f1b3"; }
 
-// Buildings & Landmarks
-.mg-icon-building:before,
-.fa-building:before {
-  content: "\f0F7";
-}
-
-.mg-icon-landmark:before,
-.fa-landmark:before {
-  content: "\f19c";
-}
-
-// Writing & Editing
-.mg-icon-pen-nib:before,
-.fa-pen-nib:before {
-  content: "\f0f6";
-}
-
-// Business
-.mg-icon-business-time:before,
-.fa-business-time:before {
-  content: "\e809";
-}
-
-// Development
-.mg-icon-code-branch:before,
-.fa-code-branch:before {
-  content: "\f126";
-}
-
-// Support
-.mg-icon-life-ring:before,
-.fa-life-ring:before {
-  content: "\f1cd";
-}
-
-// Ideas
-.mg-icon-lightbulb:before,
-.fa-lightbulb:before {
-  content: "\f0eb";
-}
-
-// Objects
-.mg-icon-cubes:before,
-.fa-cubes:before {
-  content: "\f1b3";
-}
-
-// Sorting & Organization
-.mg-icon-sort-alpha-down:before,
-.mg-icon-tags:before,
 .fa-sort-alpha-down:before,
-.fa-tags:before {
-  content: "\e800";
-}
-
-// Power
-.mg-icon-power-off:before,
-.fa-power-off:before {
-  content: "\f090";
-}
-
-// User
-.mg-icon-user:before,
-.fa-user:before {
-  content: "\e805";
-}
-
-// Actions
-.mg-icon-times:before,
-.mg-icon-close:before,
-.fa-times:before {
-  content: "\f00d";
-}
-
-.mg-icon-link:before,
-.fa-link:before {
-  content: "\e802";
-}
-
-.mg-icon-clone:before,
-.mg-icon-copy:before,
-.fa-clone:before {
-  content: "\f24d";
-}
+.fa-tags:before { content: "\e800"; }
+
+.fa-power-off:before { content: "\f090"; }
+.fa-user:before { content: "\e805"; }
+.fa-times:before { content: "\f00d"; }
+.fa-link:before { content: "\e802"; }
+.fa-clone:before { content: "\f24d"; }
+.fa-share:before { content: "\f1e0"; }
+.fa-globe:before { content: "\f0ac"; }
+.fa-qrcode:before { content: "\e899"; }
+.fa-left:before { content: "\f177"; }
+.fa-right:before { content: "\f178"; }
+.fa-angle-circled-right:before { content: "\f138"; }
+.fa-angle-circled-left:before { content: "\f137"; }
+.fa-menu:before { content: "\f0c9"; }
+
+// Mask-image icon system
+// content: "" and background-color: currentColor live in .mg-icon:not([class*="fa-"])::before
+// (specificity 0,2,1). The :not() excludes fa-* elements, so font glyphs render
+// correctly without a separate background-color reset.
 
-.mg-icon-share:before,
-.fa-share:before {
-  content: "\f1e0";
-}
-
-// Globe
-.mg-icon-globe:before,
-.fa-globe:before {
-  content: "\f0ac";
-}
-
-// QR Code
-.mg-icon-qrcode:before,
-.fa-qrcode:before {
-  content: "\e899";
-}
-
-// Arrows
-.mg-icon-left:before,
-.mg-icon-arrow-left:before,
-.fa-left:before {
-  content: "\f177";
-}
-
-.mg-icon-right:before,
-.mg-icon-arrow-right:before,
-.fa-right:before {
-  content: "\f178";
-}
-
-.mg-icon-angle-circled-right:before,
-.fa-angle-circled-right:before {
-  content: "\f138";
-}
-
-.mg-icon-angle-circled-left:before,
-.fa-angle-circled-left:before {
-  content: "\f137";
-}
-
-// Menu
-.mg-icon-menu:before,
-.mg-icon-hamburger:before,
-.fa-menu:before {
-  content: "\f0c9";
-}
-
-// =============================================================================
-// Icon Size Modifiers
-// =============================================================================
+.mg-icon {
+  vertical-align: -0.125em;
+  forced-color-adjust: none;
+}
+
+.mg-icon:not([class*="fa-"])::before {
+  display: inline-block;
+  content: "";
+  width: 1em;
+  height: 1em;
+  background-color: currentColor;
+
+  // No -webkit-mask-* prefixes: unprefixed mask-* is supported by all browsers
+  // in our target matrix (Chrome 120+, Safari 17.4+, Firefox 53+, Edge 120+).
+  // Prefixes were deliberately removed as part of PR #907. Do not re-add them.
+  mask-image: var(--mg-icon-svg);
+  mask-size: contain;
+  mask-repeat: no-repeat;
+  mask-position: center;
+}
+
+// Windows High Contrast Mode (WHCM) strategy — keep both halves together:
+// (1) forced-color-adjust: none on .mg-icon prevents WHCM from overriding
+//     background-color on the ::before pseudo-element. Without it, the browser
+//     sets background-color to a system colour that breaks the mask-image
+//     rendering (the icon becomes invisible or a solid rectangle).
+// (2) background-color: CanvasText in the forced-colors media query explicitly
+//     paints the icon with the WHCM foreground system colour. This ensures the
+//     icon is visible and correctly coloured even when currentColor has been
+//     overridden by a WHCM-adjusted ancestor.
+// Neither rule is sufficient alone — forced-color-adjust: none without the
+// CanvasText fallback can leave icons the wrong colour; CanvasText without
+// forced-color-adjust: none has no effect because WHCM overrides it first.
+@media (forced-colors: active) {
+  .mg-icon:not([class*="fa-"])::before {
+    background-color: CanvasText;
+  }
+}
+
+// Multi-color modifier: renders the SVG with its original colors instead of
+// using currentColor through a mask.
+// WHCM note: forced-color-adjust: none is inherited from .mg-icon, so the
+// browser does not override background-image in forced-colors mode. The SVG
+// renders with its embedded fill colors (e.g. SDG wheel segments). This is
+// intentional for brand logos and multi-color assets — the forced-colors
+// background-color: CanvasText rule on .mg-icon:not([class*="fa-"])::before
+// (specificity 0,2,1) is overridden by .mg-icon--multicolor::before
+// (same specificity 0,2,1, but later in source order), which resets
+// background-color to transparent. Result: multicolor icons
+// retain their original colors in WHCM. Always pair multicolor icons with a
+// visible text label so the color meaning is not the sole conveyor of information.
+.mg-icon--multicolor::before {
+  background-color: transparent;
+  background-image: var(--mg-icon-svg);
+  background-size: contain;
+  background-repeat: no-repeat;
+  background-position: center;
+  mask-image: none;
+}
+
+// RTL: flip directional icons horizontally. Icons with an inherent left→right
+// direction must reverse in RTL layouts so they point the correct way.
+[dir="rtl"] {
+  .mg-icon-left::before,
+  .mg-icon-arrow-left::before,
+  .mg-icon-right::before,
+  .mg-icon-arrow-right::before,
+  .mg-icon-angle-circled-left::before,
+  .mg-icon-angle-circled-right::before {
+    transform: scaleX(-1);
+  }
+}
+
+// Print: restore background-color so mask-image icons remain visible.
+// Generic print resets (e.g. HTML5 Boilerplate) set `background: transparent !important`
+// on all elements. Font glyphs were unaffected because they use `color`, but mask-image
+// icons are painted via `background-color: currentColor` — without this override every
+// icon is invisible when printing.
+@media print {
+  .mg-icon:not([class*="fa-"])::before {
+    // Specificity 0,2,1 with !important beats any 0,0,1 universal reset.
+    background-color: #000 !important; // sass-lint:disable-line no-important
+    print-color-adjust: exact;
+  }
+}
+
+// Icon size modifiers
 
 .mg-icon--sm {
   font-size: 0.875em;

package/scss/Atom/Table/table.scss

@@ -23,7 +23,7 @@
       @extend %border-none;
 
       &:nth-child(even) {
-        background-color: $mg-color-neutral-200;
+        background-color: $mg-color-neutral-25;
       }
     }
   }

package/scss/Components/Breadcrumbs/breadcrumbs.scss

@@ -39,11 +39,20 @@
   }
 
   li + li:before {
-    font-family: $mg-font-family-icons;
-    color: $mg-color-text;
-    content: "\f105";
-    padding: 0 12px 0 14px;
-    vertical-align: top;
+    // CSS-only chevron separator (replaces font codepoint \f105)
+    content: "";
+    display: inline-block;
+    width: 0.4em;
+    height: 0.4em;
+    border-right: 0.125em solid $mg-color-text;
+    border-top: 0.125em solid $mg-color-text;
+    transform: rotate(45deg);
+
+    // Asymmetric margin: left side is larger to optically center the rotated
+    // chevron box within the text line. em units scale with font-size.
+    // At 16px base: right = 0.75em (12px), left = 0.875em (14px).
+    margin: 0 0.75em 0 0.875em;
+    vertical-align: middle;
   }
 
   li + li:has(a:empty):before {
@@ -70,7 +79,15 @@
   }
 
   li + li:before {
-    color: $mg-color-white;
+    border-color: $mg-color-white;
+  }
+}
+
+// Forced-colors mode: white variant chevrons could map to Canvas (background)
+// and become invisible. Force CanvasText for visibility.
+@media (forced-colors: active) {
+  .mg-breadcrumb.mg-breadcrumb--white li + li:before {
+    border-color: CanvasText;
   }
 }
 
@@ -98,9 +115,8 @@
     }
 
     li + li:before {
-      @include transform(rotate(180deg));
-
-      padding: 0 14px 0 12px;
+      transform: rotate(225deg);
+      margin: 0 0.875em 0 0.75em;
     }
   }
 }

package/scss/Components/Buttons/CtaButton/cta-button.scss

@@ -55,45 +55,20 @@ button {
     color: $mg-color-button;
     background-color: $mg-color-button-background--hover;
   }
-
-  // &.button-arrow {
-  //   &::after {
-  //     @include transition(0.2s ease);
-
-  //     background: url(#{$img-path-Iconfourback}/chevron-right-black.svg)
-  //       no-repeat left center;
-  //     content: '';
-  //     height: 20px;
-  //     margin-left: $mg-spacing-25;
-  //     width: 13px;
-  //   }
-
-  //   &:hover::after {
-  //     @include translate(70%, 0);
-  //   }
-
-  //   &.disabled {
-  //     &::after {
-  //       background: url(#{$img-path-Iconfourback}/chevron-right-white.svg)
-  //         no-repeat left center;
-  //       content: '';
-  //     }
-  //   }
-  // }
 }
 
 .mg-button-secondary {
-  background-color: $mg-color-blue-600;
+  background-color: $mg-color-button-secondary-background;
 
   &:hover {
     color: $mg-color-button;
-    background-color: $mg-color-blue-400;
+    background-color: $mg-color-button-secondary-background--hover;
   }
 }
 
 .mg-button.disabled {
-  background-color: $mg-color-neutral-400;
-  color: $mg-color-neutral-300;
+  background-color: $mg-color-neutral-500;
+  color: $mg-color-neutral-0;
   pointer-events: none;
 }
 

package/scss/Components/Buttons/ShareButtons/share-buttons.scss

@@ -36,12 +36,6 @@
   cursor: pointer;
   border: $mg-border-width-button solid $mg-border-color-button;
 
-  // Improve icon rendering quality
-  .mg-icon {
-    font-weight: 100;
-    -webkit-text-stroke: 0.25px $mg-color-button-background;
-  }
-
   &:hover {
     background-color: rgba($mg-color-button-background--hover, 0.8);
   }

package/scss/Components/Cards/Card/card.scss

@@ -90,7 +90,7 @@
   &__image {
     object-fit: cover;
     width: 100%;
-    align-self: center;
+    align-self: flex-start;
   }
 
   &__label {
@@ -134,7 +134,7 @@
     position: absolute;
     right: 0;
     top: 0;
-    z-index: 100;
+    z-index: 100; // stretched-link cover — local to card stacking context
   }
 
   // Inline chevron indicator (CSS border triangle)
@@ -227,7 +227,7 @@ $card-variant-colours: (
 .mg-card__label,
 .mg-card .mg-button {
   position: relative;
-  z-index: 101;
+  z-index: 101; // above stretched-link cover — local to card stacking context
 }
 
 .mg-card__label {
@@ -293,7 +293,7 @@ $card-variant-colours: (
     width: 100%;
     display: flex;
     flex-direction: column;
-    align-items: center;
+    align-items: flex-start;
     justify-content: flex-start;
     overflow: visible;
     container-type: inline-size; // Enable container queries for icon scaling
@@ -420,7 +420,7 @@ $card-variant-colours: (
       content: "";
       position: absolute;
       inset: 0;
-      z-index: 1;
+      z-index: 1; // stretched-link cover for logo card — local to icon-card stacking context
     }
 
     &:hover {
@@ -483,7 +483,7 @@ $card-variant-colours: (
       color: $mg-color-interactive;
       text-decoration: none;
       position: relative;
-      z-index: 101;
+      z-index: 101; // above stretched-link cover — local to card stacking context
 
       &:hover {
         text-decoration: underline;
@@ -500,7 +500,7 @@ $card-variant-colours: (
   // Bordered variant (colored border via CSS custom property)
   &--bordered {
     border: 2px solid var(--mg-card-border);
-    padding: max($mg-card-padding + 0rem, $mg-spacing-100);
+    padding: max($mg-card-padding, $mg-spacing-150);
   }
 
   // Centered variant

package/scss/Components/Cards/StatsCard/stats-card.scss

@@ -62,7 +62,7 @@
     content: "";
     position: absolute;
     inset: 0;
-    z-index: 1;
+    z-index: 1; // stretched-link cover — local to stats-card stacking context
   }
 
   // Focus styles for linked cards
@@ -105,7 +105,7 @@
       color: $mg-color-interactive;
       text-decoration: underline;
       position: relative;
-      z-index: 2;
+      z-index: 2; // above stretched-link cover — local to stats-card stacking context
       transition: opacity 200ms ease;
 
       &:hover {

package/scss/Components/Gallery/gallery.scss

@@ -98,7 +98,7 @@
     top: 50%;
     left: 50%;
     transform: translate(-50%, -50%);
-    z-index: 3;
+    z-index: 3; // loading spinner above nav buttons — local to gallery stacking context
   }
 
   &__spinner {
@@ -352,7 +352,7 @@
     color: $mg-color-white;
     font-size: $mg-font-size-400;
     cursor: pointer;
-    z-index: 2;
+    z-index: 2; // nav button above gallery images — local to gallery stacking context
     display: flex;
     align-items: center;
     justify-content: center;
@@ -409,7 +409,7 @@
     right: $mg-spacing-100;
     display: flex;
     gap: $mg-spacing-100;
-    z-index: 2;
+    z-index: 2; // arrow controls above gallery images — local to gallery stacking context
   }
 
   &__arrow-button {