updated-icon-foundation (#6824)

Co-authored-by: Tymon Rybak <tymon.rybak@jpmorgan.com>
Co-authored-by: David Oyedeji <40142093+wemmyo@users.noreply.github.com>
Co-authored-by: Amrita Desmet <176904642+amritadesmet@users.noreply.github.com>

Author: 4 people

site/docs/foundations/assets/index.mdx

@@ -17,9 +17,12 @@ Icons come in two variant types: **Outline** and **Solid**. Please note that all
 
 **Outline icons** place less emphasis on non-imperative items and are more recognizable when they have wider inner spacing. They’re also better to use when you need to make subtle design cues more noticeable.
 
-<Image
+<Diagram
   src="/img/foundations/iconography-icon-variants.png"
+  srcDark="/img/foundations/iconography-icon-variants.png"
   alt="Example of solid and outline icons"
+  border
+  background="secondary"
 />
 
 ## All icons
@@ -30,9 +33,14 @@ Icons come in two variant types: **Outline** and **Solid**. Please note that all
 
 Icon size will vary based on use case and system requirements. Standard sizing ensures components maintain a consistent spatial relationship with surrounding elements.
 
-<Image
+We recommend using a size multiplier for icons when its purpose needs to be emphasized; typically standalone and not paired with text.
+
+<Diagram
   src="/img/foundations/iconography-icon-size.png"
+  srcDark="/img/foundations/iconography-icon-size-dark.png"
   alt="Example of an icon in three scaled sizes"
+  border
+  background="secondary"
 />
 
 | Size token         | Multiplier | High Density (HD) | Medium Density (MD) | Low Density (LD) | Touch Density (TD) |
@@ -43,3 +51,177 @@ Icon size will vary based on use case and system requirements. Standard sizing e
 |                    | x4         | 40                | 48                  | 56               | 64                 |
 
 \* Icons have a minimum size set at 12px and should not be displayed any smaller. For high density this means the default size of an icon is 12px, but the rest of the scale grows based on small base dimension.
+
+### Icon sizing when paired with display and heading text
+
+- Match the icon container height to the text line-height.
+- Match the icon glyph size to the text font-size.
+
+When an icon is paired with **display** or **heading** text styles, the icon size (i.e., the glyph) is aligned with the text size, and the icon’s container is aligned with text line height.
+This approach ensures the icon and text remain visually balanced and that the icon stays perfectly aligned with the text block, even in multi-line layouts.
+
+<Diagram
+  src="/img/foundations/iconography-icon-heading-size.png"
+  srcDark="/img/foundations/iconography-icon-heading-size-dark.png"
+  alt="Icon aligned with Display1 text, with spacing measurements"
+  border
+  background="secondary"
+  caption="The diagram shown is based on medium density values. Always use design tokens
+for icon sizing and spacing."
+/>
+
+## Spacing between icon and text
+
+Spacing between an icon and its paired text varies by context. The sub-sections below cover key scenarios.
+
+### When to use spacing-50
+
+Apply `--salt-spacing-50` — the icon is used within small, primitive components to describe the interaction or label. This applies to:
+
+- [Button](/salt/components/button)
+- [Toggle button](/salt/components/toggle-button)
+- [Pill](/salt/components/pill)
+- [Tag](/salt/components/tag)
+
+<ImageSwitcher
+  images={[
+    {
+      src: "/img/foundations/iconography-icon-spacing-50.png",
+      alt: "Spacing 50 examples for icon and text.",
+    },
+    {
+      src: "/img/foundations/iconography-icon-spacing-50-spacer.png",
+      alt: "Spacing 50 examples for icon and text with annotation.",
+    },
+  ]}
+  darkImages={[
+    {
+      src: "/img/foundations/iconography-icon-spacing-50-dark.png",
+      alt: "Spacing 50 examples for icon and text.",
+    },
+    {
+      src: "/img/foundations/iconography-icon-spacing-50-spacer-dark.png",
+      alt: "Spacing 50 examples for icon and text with annotation.",
+    },
+  ]}
+  label="Show spacing"
+/>
+
+### When to use spacing-75
+
+Apply `--salt-spacing-75` — the icon describes a heading or statement; often used within ‘messaging’ type components or where the icon is part of a sentence; it isn’t constrained within a small component. This applies to:
+
+- [Banner](/salt/components/banner)
+- [Toast](/salt/components/toast)
+- [Dialog](/salt/components/dialog)
+- [Tooltip](/salt/components/tooltip)
+- [Form field](/salt/components/form-field) - Validation status
+- [Link](/salt/components/link)
+
+<ImageSwitcher
+  images={[
+    {
+      src: "/img/foundations/iconography-icon-spacing-75.png",
+      alt: "Spacing 75 examples for icon and text.",
+    },
+    {
+      src: "/img/foundations/iconography-icon-spacing-75-spacer.png",
+      alt: "Spacing 75 examples for icon and text with annotation.",
+    },
+  ]}
+  darkImages={[
+    {
+      src: "/img/foundations/iconography-icon-spacing-75-dark.png",
+      alt: "Spacing 75 examples for icon and text.",
+    },
+    {
+      src: "/img/foundations/iconography-icon-spacing-75-spacer-dark.png",
+      alt: "Spacing 75 examples for icon and text with annotation.",
+    },
+  ]}
+  label="Show spacing"
+/>
+
+### When to use spacing-100
+
+Apply `--salt-spacing-100` — the icon describes the title or label of ‘stackable’ (i.e., those with a slightly larger height, designed to accommodated nested controls, such as buttons) or repeated elements (where clean vertical alignment is required); also applies to radio/checkbox controls. This applies to:
+
+- [Accordion](/salt/components/accordion)
+- [Vertical navigation](/salt/components/vertical-navigation)
+- [Tabs](/salt/components/tabs)
+- [Tree](/salt/components/tree)
+- [List box](/salt/components/list-box)
+- [Menu items](/salt/components/menu)
+- [Checkbox](/salt/components/checkbox)
+- [Radio button](/salt/components/radio-button)
+
+<ImageSwitcher
+  images={[
+    {
+      src: "/img/foundations/iconography-icon-spacing-100.png",
+      alt: "Spacing 100 examples for icon and text.",
+    },
+    {
+      src: "/img/foundations/iconography-icon-spacing-100-spacer.png",
+      alt: "Spacing 100 examples for icon and text with annotation.",
+    },
+  ]}
+  darkImages={[
+    {
+      src: "/img/foundations/iconography-icon-spacing-100-dark.png",
+      alt: "Spacing 100 examples for icon and text.",
+    },
+    {
+      src: "/img/foundations/iconography-icon-spacing-100-spacer-dark.png",
+      alt: "Spacing 100 examples for icon and text with annotation.",
+    },
+  ]}
+  label="Show spacing"
+/>
+
+### Spacing between icon and heading/display text
+
+<Callout status="info">
+  This spacing update is experimental. We welcome your feedback to help us
+  refine and optimize this guideline. The goal is to apply these updated rules
+  to existing components, including Dialog (currently using --spacing-75, see
+  above). Please [reach out to the team](/salt/support-and-contributions/index)
+  with any thoughts or suggestions on this new spacing rule.
+</Callout>
+
+To ensure visual balance and readability, spacing between icons and Heading/Display text is tailored according to the size of the text. This approach helps maintain a harmonious and comfortable layout across different heading and display levels.
+
+This is the recommended spacing in editorial/marketing layouts and where headings are used within components.
+
+| Heading/Display text | Spacing between Icon & Text |
+| -------------------- | --------------------------- |
+| Display1, Display2   | `--salt-spacing-300`        |
+| Display3, Display4   | `--salt-spacing-250`        |
+| H1, H2               | `--salt-spacing-150`        |
+| H3, H4               | `--salt-spacing-100`        |
+
+<ImageSwitcher
+  images={[
+    {
+      src: "/img/foundations/iconography-icon-spacing-heading.png",
+      alt: "Icon spacing examples for Display and Heading text sizes.",
+    },
+    {
+      src: "/img/foundations/iconography-icon-spacing-heading-spacer.png",
+      alt: "Icon spacing examples for Display and Heading text size with annotation.",
+    },
+  ]}
+  darkImages={[
+    {
+      src: "/img/foundations/iconography-icon-spacing-heading-dark.png",
+      alt: "Icon spacing examples for Display and Heading text sizes.",
+    },
+    {
+      src: "/img/foundations/iconography-icon-spacing-heading-spacer-dark.png",
+      alt: "Icon spacing examples for Display and Heading text size with annotation.",
+    },
+  ]}
+  label="Show spacing"
+/>
+
+:fragment{src="./../fragments/feedback.mdx"}