docs(design-system-docs): add Icon component documentation (#4571)

* docs(design-system-docs): add Icon component documentation

Add structured documentation page for the EDS 2.0 Icon component
covering sizing, typography integration, density modes, colour,
accessibility, and inline vs flex layout patterns. Also adds the
Data Display category to the sidebar.

* docs(design-system-docs): add Data Display category landing page

* docs(design-system-docs): fix lint issue

* docs(design-system-docs): address PR review feedback for Icon docs

- Simplify Structure section, remove CSS variable implementation details
- Rename Dynamic fallback to Default sizing with clearer description
- Use consistent "color" spelling instead of "colour"
- Improve Don't about size + Typography auto-sizing conflict
- Add Usage in Figma section with container padding guidance

Author: eddiman

apps/design-system-docs/docs/components/data-display/data-display.md

@@ -0,0 +1,32 @@
+---
+title: Data Display
+sidebar_position: 0
+---
+
+# Component group - Data Display
+
+Data display components present information to users in clear, structured formats. They help organise content so that it is easy to scan, understand, and act upon.
+
+## When to use
+
+Use data display components when you need to:
+
+- Present information in a structured, readable format
+- Visualise relationships between pieces of data
+- Provide contextual details on demand
+- Display lists, tables, or visual indicators alongside content
+
+## Principles
+
+**Clarity first**
+Data display components should make information easy to read and understand at a glance. Avoid clutter and prioritise the most important content.
+
+**Consistency**
+Use the same data display patterns throughout your application to help users build familiarity and confidence when navigating information.
+
+**Accessibility**
+All data display components must be perceivable by assistive technologies and follow <abbr title="Web Content Accessibility Guidelines">WCAG</abbr> 2.1 AA standards.
+
+## Components in this group
+
+Browse the navigation menu to explore individual data display components and their specific usage guidelines.

apps/design-system-docs/docs/components/data-display/icon.md

@@ -0,0 +1,207 @@
+---
+title: Icon
+---
+
+# Icon
+
+Icons are small visual symbols that communicate meaning at a glance. They support text labels, guide users through interactions, and add clarity to our interfaces. The Icon component is designed with care to scale automatically with typography, adapt to density modes, and meet accessibility standards out of the box.
+
+<iframe
+  class="sb-iframe"
+  src="https://storybook.eds.equinor.com/iframe.html?globals=&args=&id=eds-2-0-beta-icon--introduction"
+  width="100%"
+  height="88"
+  frameborder="1"
+></iframe>
+
+[View in Storybook](https://storybook.eds.equinor.com/?path=/story/eds-2-0-beta-icon--introduction)
+
+## When to Use
+
+Use Icon to reinforce meaning alongside text - in buttons, form fields, status messages, and navigation. Icons help users scan interfaces faster and understand actions without reading every label.
+
+**Avoid Icon for:**
+
+- Purely decorative illustrations - use an image instead
+- Complex graphics or logos - use a dedicated image or SVG
+
+## Structure
+
+The Icon component renders an SVG element with a single `data` prop from `@equinor/eds-icons`. It supports three sizing layers:
+
+- **Explicit `size` prop** - highest priority, for precise control
+- **Parent Typography** - automatically inherits the right size when placed inside Typography
+- **Dynamic fallback** - scales at 1.5× relative to the surrounding font size
+
+## Guidelines
+
+### Sizes
+
+Use the `size` prop for explicit sizing. Each size maps to an EDS design token, ensuring consistency across our interfaces.
+
+| Size | Spacious (default) | Comfortable (compact) |
+| ---- | ------------------ | --------------------- |
+| xs   | 16px               | 14px                  |
+| sm   | 18px               | 16px                  |
+| md   | 20px               | 18px                  |
+| lg   | 24px               | 20px                  |
+| xl   | 28px               | 24px                  |
+| 2xl  | 32px               | 28px                  |
+| 3xl  | 37px               | 32px                  |
+| 4xl  | 42px               | 37px                  |
+| 5xl  | 48px               | 42px                  |
+| 6xl  | 56px               | 48px                  |
+
+<iframe
+  class="sb-iframe"
+  src="https://storybook.eds.equinor.com/iframe.html?globals=&args=&id=eds-2-0-beta-icon--explicit-sizes"
+  width="100%"
+  height="136"
+  frameborder="1"
+></iframe>
+
+[View in Storybook](https://storybook.eds.equinor.com/?path=/story/eds-2-0-beta-icon--explicit-sizes)
+
+### Auto-sizing with Typography
+
+When placed inside a Typography component, icons automatically inherit the correct size via the `--eds-typography-icon-size` CSS variable. This is the recommended approach for icons inline with text.
+
+<iframe
+  class="sb-iframe"
+  src="https://storybook.eds.equinor.com/iframe.html?globals=&args=&id=eds-2-0-beta-icon--auto-size-from-typography"
+  width="100%"
+  height="308"
+  frameborder="1"
+></iframe>
+
+[View in Storybook](https://storybook.eds.equinor.com/?path=/story/eds-2-0-beta-icon--auto-size-from-typography)
+
+### Density modes
+
+Icons respect the `data-density` attribute for density-aware sizing. The same `size` prop renders at different pixel values depending on the density context.
+
+- **Spacious** (default) - larger icons for more breathing room
+- **Comfortable** - smaller icons for compact UIs
+
+<iframe
+  class="sb-iframe"
+  src="https://storybook.eds.equinor.com/iframe.html?globals=&args=&id=eds-2-0-beta-icon--density-modes"
+  width="100%"
+  height="162"
+  frameborder="1"
+></iframe>
+
+[View in Storybook](https://storybook.eds.equinor.com/?path=/story/eds-2-0-beta-icon--density-modes)
+
+### Default sizing
+
+When no `size` prop is set and the icon is outside a Typography component, it scales to 1.5× the surrounding font size. This provides a sensible default in any context.
+
+<iframe
+  class="sb-iframe"
+  src="https://storybook.eds.equinor.com/iframe.html?globals=&args=&id=eds-2-0-beta-icon--dynamic-fallback"
+  width="100%"
+  height="251"
+  frameborder="1"
+></iframe>
+
+[View in Storybook](https://storybook.eds.equinor.com/?path=/story/eds-2-0-beta-icon--dynamic-fallback)
+
+### Color
+
+Icons inherit `currentColor` by default, making them adapt to text color automatically. You can also set a custom color using the `color` prop.
+
+<iframe
+  class="sb-iframe"
+  src="https://storybook.eds.equinor.com/iframe.html?globals=&args=&id=eds-2-0-beta-icon--color"
+  width="100%"
+  height="88"
+  frameborder="1"
+></iframe>
+
+[View in Storybook](https://storybook.eds.equinor.com/?path=/story/eds-2-0-beta-icon--color)
+
+### Inline text vs flex layout
+
+How you use Icon depends on the layout context:
+
+| Context     | Usage                          | Why                                                             |
+| ----------- | ------------------------------ | --------------------------------------------------------------- |
+| Inline text | `<Icon data={save} />`         | Auto-sizes to 1.5em, negative margins for optical alignment     |
+| Flex/Button | `<Icon data={save} size="md">` | Fixed size from tokens, no margins - layout controlled by flex gap |
+
+The `size` prop removes negative margins, giving full control to your layout system.
+
+<iframe
+  class="sb-iframe"
+  src="https://storybook.eds.equinor.com/iframe.html?globals=&args=&id=eds-2-0-beta-icon--inline-with-text"
+  width="100%"
+  height="257"
+  frameborder="1"
+></iframe>
+
+[View in Storybook](https://storybook.eds.equinor.com/?path=/story/eds-2-0-beta-icon--inline-with-text)
+
+## Usage in Figma
+
+There is no dedicated Icon component in Figma. Instead, icons are imported directly from the **Assets** panel.
+
+**Standalone icons** — Import the icon from Assets and place it directly in your design. The icon size is controlled by the asset itself.
+
+**Inline with Typography** — When placing an icon inline with text, wrap it in a container like "Leading Icon Item". This container applies negative padding to optically align the icon with the text baseline — matching how the code component behaves with negative margins for inline icons.
+
+The container exposes variables for controlling size and negative padding:
+
+| Variable                                 | Purpose                                      |
+| ---------------------------------------- | -------------------------------------------- |
+| `Selectable/Icon size`                   | Controls the icon dimensions                 |
+| `Selectable/Icon container padding ↕︎`  | Negative vertical padding for optical alignment |
+| `Selectable/Icon container padding ↔︎`  | Negative horizontal padding (square containers only) |
+
+**Which padding variables to use depends on the container shape:**
+
+- **Rectangular containers** (e.g., a button with text) — Only vertical padding (`↕︎`) is needed. Horizontal spacing is handled by the parent layout's gap.
+- **Square containers** (e.g., an icon-only button) — Both vertical (`↕︎`) and horizontal (`↔︎`) padding are needed, set to the same value, since the icon fills the container in both directions.
+
+## Accessibility
+
+Icons follow WCAG 2.1 AA guidelines with two distinct modes:
+
+**Decorative icons** (no `title` prop)
+
+- Rendered with `aria-hidden="true"`
+- Hidden from screen readers entirely
+- Use when the icon is accompanied by visible text that conveys the same meaning
+
+**Semantic icons** (with `title` prop)
+
+- Rendered with `role="img"` and `aria-labelledby`
+- Announced by screen readers using the title text
+- Use when the icon conveys meaning that is not available through surrounding text
+
+<iframe
+  class="sb-iframe"
+  src="https://storybook.eds.equinor.com/iframe.html?globals=&args=&id=eds-2-0-beta-icon--accessibility"
+  width="100%"
+  height="197"
+  frameborder="1"
+></iframe>
+
+[View in Storybook](https://storybook.eds.equinor.com/?path=/story/eds-2-0-beta-icon--accessibility)
+
+## Do's and Don'ts
+
+:::info **Do**
+
+- Use `title` prop when an icon is the only element conveying meaning (e.g., icon-only buttons)
+- Let icons inherit size from Typography when used inline with text
+- Use the `size` prop in flex layouts where you control spacing with gap
+- Rely on `currentColor` for icons that should match surrounding text color
+:::
+
+:::danger **Don't**
+
+- Don't use icons without a `title` when there is no accompanying text to convey the meaning
+- Don't combine the `size` prop with Typography auto-sizing. The `size` prop takes priority and overrides the inherited size, so the Typography context has no effect
+- Don't use custom pixel values for sizing - use the `size` prop or let tokens handle it
+:::

apps/design-system-docs/sidebars.ts

@@ -65,6 +65,15 @@ const sidebars: SidebarsConfig = {
         'components/inputs/textfield',
       ],
     },
+    {
+      type: 'category',
+      label: 'Data Display',
+      link: {
+        type: 'doc',
+        id: 'components/data-display/data-display',
+      },
+      items: ['components/data-display/icon'],
+    },
   ],
   //Foundation Section
   foundationSidebar: [