Update iconography and country symbol foundation docs (#4391)

Co-authored-by: Amrita Desmet <176904642+amritadesmet@users.noreply.github.com>
Co-authored-by: origami-z <5257855+origami-z@users.noreply.github.com>
Co-authored-by: Josh Wooding <12938082+joshwooding@users.noreply.github.com>

site/docs/foundations/accent.mdx

@@ -1,6 +1,8 @@
 ---
 title: Accent
 layout: DetailTechnical
+sidebar:
+  priority: 14
 data:
   status: In progress
 ---

site/docs/foundations/color.mdx

@@ -1,7 +1,8 @@
 ---
 title: Color
 layout: DetailTechnical
-data:
+sidebar:
+  priority: 13
 ---
 
 Colors can be used to communicate meaning, establish visual hierarchy, and differentiate products, all while ensuring a cohesive and accessible experience. Colors are divided into several categories to communicate several concepts across the Salt design system.

site/docs/foundations/density.mdx

@@ -1,6 +1,8 @@
 ---
 title: Density
 layout: DetailTechnical
+sidebar:
+  priority: 12
 ---
 
 Density relates to the amount of content that can fit on a screen based on the [size](./size) and [spacing](./spacing) of components.

site/docs/foundations/division.mdx

@@ -1,6 +1,8 @@
 ---
 title: Division
 layout: DetailTechnical
+sidebar:
+  priority: 11
 data:
   status: In progress
 ---

site/docs/foundations/duration.mdx

@@ -1,6 +1,8 @@
 ---
 title: Duration
 layout: DetailTechnical
+sidebar:
+  priority: 10
 ---
 
 Duration represents the time between a user performing an action and the system giving feedback. Consistency in timing provides comfort and can increase trust in a system.

site/docs/foundations/iconography/country-symbols.mdx

@@ -0,0 +1,36 @@
+---
+title: Country symbols
+layout: DetailTechnical
+---
+
+Country symbols represent a specific country and are used in contexts where geographical identification is necessary. They can be considered icons that are visually representative of a country or inter-governmental organisation. All country symbols are available in both circle and rectangle shapes.
+
+<Image
+  src="/img/foundations/iconography-countrysymbols-variant.png"
+  alt="Example of circular country symbols next to rectangular country symbols"
+/>
+
+## All country symbols
+
+<CountrySymbolPreview />
+
+## Scaling country symbols
+
+Country symbols have a standard size that changes in multiples across all four density levels.
+
+<ImageSwitcher
+  images={[
+    { src: "/img/foundations/scale-country.svg", alt: "" },
+    { src: "/img/foundations/scale-country-annotated.svg", alt: "" },
+  ]}
+  label="Show multipliers"
+/>
+
+| Size token         | Multiplier | High Density (HD) | Medium Density (MD) | Low Density (LD) | Touch Density (TD) |
+| ------------------ | ---------- | ----------------- | ------------------- | ---------------- | ------------------ |
+| `--salt-size-base` | x1         | 20                | 28                  | 36               | 44                 |
+|                    | x2         | 40                | 56                  | 72               | 88                 |
+|                    | x3         | 60                | 84                  | 108              | 132                |
+|                    | x4         | 80                | 112                 | 144              | 176                |
+
+:fragment{src="./../fragments/feedback.mdx"}

site/docs/foundations/iconography/index.mdx

@@ -0,0 +1,48 @@
+---
+title: Icons
+layout: DetailTechnical
+sidebar:
+  groupLabel: Iconography
+  label: Icons
+  priority: 9
+---
+
+Icons are simplified visual representations of a specific action, object or concept.
+
+## Icon variants
+
+Icons come in two variant types: **Outline** and **Solid**. Please note that all icons within the icon set have an outline variant, but not all icons have a solid variant.
+
+**Solid icons** may be faster to recognise than outline icons due to less visual noise, especially depending on the complexity of the icon. Solid icons better represent how we view objects, whereas outline icons are silhouettes and therefore can take longer to perceive.
+
+**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
+  src="/img/foundations/iconography-icon-variants.png"
+  alt="Example of solid and outline icons"
+/>
+
+## All icons
+
+<IconPreview />
+
+## Scaling icons
+
+Icon size will vary based on use case and system requirements. Standard sizing ensures components maintain a consistent spatial relationship with surrounding elements.
+
+<ImageSwitcher
+  images={[
+    { src: "/img/foundations/scale-icon.svg", alt: "" },
+    { src: "/img/foundations/scale-icon-annotated.svg", alt: "" },
+  ]}
+  label="Show multipliers"
+/>
+
+| Size token         | Multiplier | High Density (HD) | Medium Density (MD) | Low Density (LD) | Touch Density (TD) |
+| ------------------ | ---------- | ----------------- | ------------------- | ---------------- | ------------------ |
+| `--salt-size-icon` | x1         | 12 \*             | 12                  | 14               | 16                 |
+|                    | x2         | 20                | 24                  | 28               | 32                 |
+|                    | x3         | 30                | 36                  | 42               | 48                 |
+|                    | 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.

site/docs/foundations/modes.mdx

@@ -1,6 +1,8 @@
 ---
 title: Modes
 layout: DetailTechnical
+sidebar:
+  priority: 8
 data:
   status: In progress
 ---

site/docs/foundations/opacity.mdx

@@ -1,6 +1,8 @@
 ---
 title: Opacity
 layout: DetailTechnical
+sidebar:
+  priority: 7
 data:
   status: In progress
 ---

site/docs/foundations/responsiveness.mdx

@@ -1,6 +1,8 @@
 ---
 title: Responsiveness
 layout: DetailTechnical
+sidebar:
+  priority: 6
 ---
 
 A responsive layout makes dynamic changes to the appearance of a product in response to the size of the screen.

site/docs/foundations/scale.mdx

@@ -1,6 +1,8 @@
 ---
 title: Scale
 layout: DetailTechnical
+sidebar:
+  priority: 5
 ---
 
 Scale allows you to give components greater or lesser prominence within an interface through a multiplier of their default size.

site/docs/foundations/shadow.mdx

@@ -1,6 +1,8 @@
 ---
 title: Shadow
 layout: DetailTechnical
+sidebar:
+  priority: 4
 data:
   status: In progress
 ---

site/docs/foundations/size.mdx

@@ -1,6 +1,8 @@
 ---
 title: Size
 layout: DetailTechnical
+sidebar:
+  priority: 3
 ---
 
 Size refers to the restricted dimensions provided within the design system, such as an element's height and/or width.

site/docs/foundations/spacing.mdx

@@ -1,6 +1,8 @@
 ---
 title: Spacing
 layout: DetailTechnical
+sidebar:
+  priority: 2
 ---
 
 The organization of space is a key aspect of design. Spatial tokens help align layouts and create consistent visual rhythm.

site/docs/foundations/typography.mdx

@@ -1,6 +1,8 @@
 ---
 title: Typography
 layout: DetailTechnical
+sidebar:
+  priority: 1
 ---
 
 Typography involves the style and appearance of written language. It plays a crucial role in enhancing readability, establishing hierarchy, and setting a visual tone, resulting in more effective and expressive communication.

site/src/components/country-symbol-preview/CountrySymbolPreview.module.css

@@ -0,0 +1,28 @@
+.root {
+  min-height: 400px;
+}
+
+.formfield {
+  display: flex;
+}
+
+.search {
+  max-width: 40ch;
+  flex: 1;
+}
+
+.symbolsContainer {
+  overflow: auto;
+  max-height: 800px;
+  margin-top: var(--salt-spacing-300);
+}
+
+.notFound {
+  flex: 1;
+  justify-content: center;
+}
+
+.symbolCount {
+  display: flex;
+  align-items: center;
+}

site/src/components/country-symbol-preview/CountrySymbolPreview.tsx

@@ -0,0 +1,115 @@
+import {
+  Button,
+  FlexItem,
+  FlexLayout,
+  FlowLayout,
+  Input,
+  StackLayout,
+  StatusIndicator,
+  Text,
+} from "@salt-ds/core";
+import { LazyCountrySymbol, countryMetaMap } from "@salt-ds/countries";
+import { CloseIcon, SearchIcon } from "@salt-ds/icons";
+import {
+  type ChangeEvent,
+  Suspense,
+  useDeferredValue,
+  useMemo,
+  useState,
+} from "react";
+import styles from "./CountrySymbolPreview.module.css";
+
+export const CountrySymbolPreview = () => {
+  const [search, setSearch] = useState("");
+  const deferredSearch = useDeferredValue(search.toLowerCase());
+
+  const handleSearch = (event: ChangeEvent<HTMLInputElement>) => {
+    setSearch(event.target.value);
+  };
+
+  const handleClear = () => {
+    setSearch("");
+  };
+
+  const filteredSymbols = useMemo(() => {
+    return Object.values(countryMetaMap).filter(
+      ({ countryCode, countryName }) =>
+        countryCode.toLowerCase().includes(deferredSearch) ||
+        countryName.toLowerCase().includes(deferredSearch),
+    );
+  }, [deferredSearch]);
+
+  const renderSymbols = useMemo(() => {
+    if (filteredSymbols.length > 0) {
+      return (
+        <FlowLayout justify="start" gap={1}>
+          {filteredSymbols.map(({ countryCode, countryName }) => (
+            <StackLayout
+              style={{ width: 140 }}
+              gap={1}
+              align="center"
+              key={countryCode}
+            >
+              <LazyCountrySymbol code={countryCode} size={1} />
+              <StackLayout gap={0} align="center">
+                <Text>{countryCode}</Text>
+                <Text style={{ textAlign: "center" }}>{countryName}</Text>
+              </StackLayout>
+            </StackLayout>
+          ))}
+        </FlowLayout>
+      );
+    }
+    return (
+      <StackLayout className={styles.notFound} gap={3} align="center">
+        <StatusIndicator status="info" size={2} />
+        <StackLayout gap={1} align="center">
+          <Text styleAs="h4">
+            <strong>No country symbols found</strong>
+          </Text>
+          <Text>
+            No country symbols found for the search term: "
+            <strong>{deferredSearch}</strong>"
+          </Text>
+        </StackLayout>
+      </StackLayout>
+    );
+  }, [filteredSymbols, deferredSearch]);
+
+  return (
+    <Suspense fallback="Loading...">
+      <StackLayout className={styles.root} gap={1}>
+        <FlexLayout direction="row">
+          <FlexItem>
+            <Input
+              placeholder="Search country symbols"
+              aria-label="Search country symbols"
+              value={search}
+              onChange={handleSearch}
+              className={styles.search}
+              startAdornment={<SearchIcon />}
+              endAdornment={
+                search ? (
+                  <Button
+                    onClick={handleClear}
+                    appearance="transparent"
+                    sentiment="neutral"
+                    aria-label="Clear search"
+                  >
+                    <CloseIcon aria-hidden />
+                  </Button>
+                ) : null
+              }
+            />
+          </FlexItem>
+          <FlexItem className={styles.formfield}>
+            <Text className={styles.symbolCount}>
+              Symbol Count: {filteredSymbols.length}
+            </Text>
+          </FlexItem>
+        </FlexLayout>
+        <div className={styles.symbolsContainer}>{renderSymbols}</div>
+      </StackLayout>
+    </Suspense>
+  );
+};

site/src/components/country-symbol-preview/index.ts

@@ -0,0 +1 @@
+export * from "./CountrySymbolPreview";