Merge pull request #1431 from City-of-Helsinki/hds-2266-shadow-docs

(Release-4.0.0) hds-2266: Add docs about (box-) shadows

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
 

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;

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>

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>

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] |
+
+###