From 47be0c740a993b19898739ba47ba7e812c03dc34 Mon Sep 17 00:00:00 2001
From: NikoHelle <niko.helle@hyperactive.fi>
Date: Tue, 19 Nov 2024 13:33:53 +0200
Subject: [PATCH 1/2] (hds-2266) Add docs about box-shadows

---
 site/src/components/examples/ShadowExample.js | 23 +++++++++++++++
 .../foundation/design-tokens/shadow/index.mdx | 28 +++++++++++++++++++
 .../foundation/design-tokens/shadow/tabs.mdx  | 26 +++++++++++++++++
 .../design-tokens/shadow/tokens.mdx           | 21 ++++++++++++++
 4 files changed, 98 insertions(+)
 create mode 100644 site/src/components/examples/ShadowExample.js
 create mode 100644 site/src/docs/foundation/design-tokens/shadow/index.mdx
 create mode 100644 site/src/docs/foundation/design-tokens/shadow/tabs.mdx
 create mode 100644 site/src/docs/foundation/design-tokens/shadow/tokens.mdx

diff --git a/site/src/components/examples/ShadowExample.js b/site/src/components/examples/ShadowExample.js
new file mode 100644
index 0000000000..84ead41f58
--- /dev/null
+++ b/site/src/components/examples/ShadowExample.js
@@ -0,0 +1,23 @@
+import React from 'react';
+import PropTypes from 'prop-types';
+
+const ShadowExample = ({ size, name }) => (
+  <div
+    aria-label={`Visualized example: ${name}`}
+    role="img"
+    style={{
+      display: 'inline-block',
+      width: '40px',
+      height: '40px',
+      background: `var(--color-fog)`,
+      boxShadow: `var(--box-shadow-${size})`,
+    }}
+  />
+);
+
+ShadowExample.propTypes = {
+  size: PropTypes.string.isRequired,
+  name: PropTypes.string,
+};
+
+export default ShadowExample;
diff --git a/site/src/docs/foundation/design-tokens/shadow/index.mdx b/site/src/docs/foundation/design-tokens/shadow/index.mdx
new file mode 100644
index 0000000000..f263862c13
--- /dev/null
+++ b/site/src/docs/foundation/design-tokens/shadow/index.mdx
@@ -0,0 +1,28 @@
+---
+slug: '/foundation/design-tokens/shadow'
+title: 'Shadow - Usage'
+navTitle: 'Shadow'
+---
+
+import ExternalLink from '../../../../components/ExternalLink';
+import Notification from '../../../../components/Notification';
+import TabsLayout from './tabs.mdx';
+
+export default ({ children, pageContext }) => <TabsLayout pageContext={pageContext}>{children}</TabsLayout>;
+
+<Notification
+  type="alert"
+  label="Shadows are not officially part of City of Helsinki brand"
+  className="siteNotification"
+>
+  Shadows should be used very sparingly if at all and always only to allow greater visual contrast between elements.
+</Notification>
+
+### Principles
+
+- **Shadows are not used to signify elevation of inline elements in HDS.** Elements that require distinction, can however have shadows applied.
+- **Do not use shadows to highlight elements.** Elements with shadow around them should only have it for visual clarity.
+- **Never use shadows on typography (heading nor body).** Primary typographic contrast should always rely on colour contrast.
+- **Never use shadows for effect.** For the City of Helsinki brand to remain intact, do not rely on style based effects of any kind.
+
+HDS offers examples of shadows used in carefully selected components that float on top of other content, such as <ExternalLink href="https://hds.hel.fi/storybook/react/?path=/story/components-notification--with-box-shadow">Notification toast variant</ExternalLink> and <ExternalLink href="https://hds.hel.fi/storybook/react/?path=/story/components-dialog--with-box-shadow">Dialog.</ExternalLink>
diff --git a/site/src/docs/foundation/design-tokens/shadow/tabs.mdx b/site/src/docs/foundation/design-tokens/shadow/tabs.mdx
new file mode 100644
index 0000000000..35e12d121e
--- /dev/null
+++ b/site/src/docs/foundation/design-tokens/shadow/tabs.mdx
@@ -0,0 +1,26 @@
+---
+slug: '/foundation/design-tokens/tabs'
+title: 'Shadow'
+---
+
+import LeadParagraph from '../../../../components/LeadParagraph';
+import Layout from '../../../../components/layout';
+import PageTabs from '../../../../components/PageTabs';
+import StatusLabel from '../../../../components/StatusLabel';
+
+# Shadow
+
+<StatusLabel type="info">Stable</StatusLabel>
+
+<LeadParagraph>
+  Shadows can be used under certain elements to create visual distinction for content that otherwise would be hard to
+  distinguish for the visually impaired or remain unnoticed.
+</LeadParagraph>
+
+<PageTabs pageContext={props.pageContext}>
+  <PageTabs.TabList>
+    <PageTabs.Tab href="/">Usage</PageTabs.Tab>
+    <PageTabs.Tab href="/tokens">Tokens</PageTabs.Tab>
+  </PageTabs.TabList>
+  <PageTabs.TabPanel>{props.children}</PageTabs.TabPanel>
+</PageTabs>
diff --git a/site/src/docs/foundation/design-tokens/shadow/tokens.mdx b/site/src/docs/foundation/design-tokens/shadow/tokens.mdx
new file mode 100644
index 0000000000..e97136cc0e
--- /dev/null
+++ b/site/src/docs/foundation/design-tokens/shadow/tokens.mdx
@@ -0,0 +1,21 @@
+---
+slug: '/foundation/design-tokens/shadow/tokens'
+title: 'Shadow tokens - Tokens'
+---
+
+import ShadowExample from '../../../../components/examples/ShadowExample';
+
+import TabsLayout from './tabs.mdx';
+
+export default ({ children, pageContext }) => <TabsLayout pageContext={pageContext}>{children}</TabsLayout>;
+
+## Tokens
+
+| Figma style             | Token            | Values                                 | Example                                                          |
+| ----------------------- | ---------------- | -------------------------------------- | ---------------------------------------------------------------- |
+| Shadow S                | `--box-shadow-s` | `0px 2px 10px 0px rgba(0, 0, 0, 0.07)` | <ShadowExample size="s" name="Box shadow small size example" />  |
+| Shadow M                | `--box-shadow-m` | `0px 2px 10px 0px rgba(0, 0, 0, 0.1)`  | <ShadowExample size="m" name="Box shadow medium size example" /> |
+| Shadow L                | `--box-shadow-l` | `0px 2px 20px 0px rgba(0, 0, 0, 0.2)`  | <ShadowExample size="l" name="Box shadow large size example" />  |
+| [Table 1:Shadow tokens] |
+
+###

From 29598d4a83d4dbf817240b2a4fa71174bca40e88 Mon Sep 17 00:00:00 2001
From: NikoHelle <niko.helle@hyperactive.fi>
Date: Tue, 19 Nov 2024 14:07:55 +0200
Subject: [PATCH 2/2] (hds-2266) Updated changelog

---
 CHANGELOG.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index e182c7e8e8..beb5a12f38 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -131,6 +131,7 @@ Changes that are not related to specific components
 - [Button] Documentation about SCSS usage.
 - [Table] Documentation about SCSS usage.
 - [Notification] Documentation about SCSS usage.
+- [Shadow] Documentation about box-shadow usage.
 
 #### Changed