feat: add the ability to use our icons from within SCSS

.changeset/lovely-mails-clap.md

@@ -0,0 +1,8 @@
+---
+'@swisspost/design-system-documentation': minor
+'@swisspost/design-system-styles': minor
+'@swisspost/design-system-icons': minor
+---
+
+Updated the output structure of our UI-Icons.
+Added a `post-icon` mixin, to use any of our icons from within SCSS.

packages/documentation/src/stories/foundations/icons/icon.docs.mdx

@@ -1,7 +1,9 @@
-import { Canvas, Controls, Meta } from '@storybook/blocks';
+import { Canvas, Controls, Meta, Source } from '@storybook/blocks';
 import * as IconStories from './icon.stories';
 import { PostTabHeader, PostTabPanel, PostTabs } from '@swisspost/design-system-components-react';
+import SampleMixin from './mixin.sample.scss?raw';
 import { Search } from './search/search-icons.blocks';
+import './icon.styles.scss';
 
 <Meta of={IconStories} />
 
@@ -14,19 +16,12 @@ import { Search } from './search/search-icons.blocks';
 </div>
 
 <div className="lead">
-  The official Swiss Post Icon Library for the web with over 800 high-quality scalable vector
-  graphics.
+  The official Swiss Post Icon Library with 900+ high-quality svg icons and the official Swiss Post UI Icons Library, exclusivley designed and provided for the web with 160+ icons and size-dependent level-of-detail.
 </div>
 
-<PostTabs>
-  <PostTabHeader panel="usage">Usage</PostTabHeader>
-  <PostTabPanel name="usage">
-    Our <code>&lt;post-icon&gt;</code> component renders SVGs, so it scales quickly and easily and can
-    be styled with CSS.
-
-    <Canvas sourceState="shown" of={IconStories.Default} />
-    <Controls of={IconStories.Default} />
-
+<PostTabs activePanel="search">
+  <PostTabHeader panel="installation">Installation</PostTabHeader>
+  <PostTabPanel name="installation">
     ## Installation
 
     ### Icon Component
@@ -38,8 +33,64 @@ import { Search } from './search/search-icons.blocks';
 
     The SVG files for icons should be hosted within your project.
     For guidelines on how to set this up, please refer to the [icon package documentation](/?path=/docs/40ed323b-9c1a-42ab-91ed-15f97f214608--docs#usage).
+  </PostTabPanel>
 
-    ## Examples
+  <PostTabHeader panel="scss">Usage in CSS</PostTabHeader>
+  <PostTabPanel name="scss">
+    ## Usage in CSS
+
+    To define one of our icons in your own CSS, you need the `@swisspost/design-system-styles` package and use our `post-icon` mixin. The icons can have a different level-of-detail, dependant on how big they are rendered on the page.
+
+    Note: The used classes in the example below are only there for demonstration purposes.
+
+    <Canvas of={IconStories.ScssMixin} sourceState="shown"/>
+
+    ### Mixin
+
+    <Source
+      language="scss"
+      dark
+      code={SampleMixin}
+    ></Source>
+
+    <table className="table">
+      <thead>
+        <tr>
+          <td>Name</td>
+          <td>Description</td>
+          <td>Default</td>
+        </tr>
+      </thead>
+      <tbody>
+        <tr>
+          <td>`$name`</td>
+          <td>The name of the icon which should be used.<br/>Find the name of your desired icon in one of the tabs above.</td>
+          <td>-</td>
+        </tr>
+        <tr>
+          <td>`$base`</td>
+          <td>The base URL, where to load the icon from. Keep this undefined to get the icons loaded from unpkg.com (NOT recommended) or specifiy a path to your self-hosted icons.</td>
+          <td>`https://unpkg.com/`</td>
+        </tr>
+        <tr>
+          <td>`$color`</td>
+          <td>The color in which the icon should be implemented.<br/>You can change that also by just overriding the `color` property on the icon selector.</td>
+          <td>`currentColor`</td>
+        </tr>
+      </tbody>
+    </table>
+
+  </PostTabPanel>
+
+  <PostTabHeader panel="component">Usage as Web-Component</PostTabHeader>
+  <PostTabPanel name="component">
+    ## Usage as Web-Component
+
+    Our <code>&lt;post-icon&gt;</code> component renders SVGs, so it scales quickly and easily and can
+    be styled with CSS.
+
+    <Canvas sourceState="shown" of={IconStories.Default} />
+    <Controls of={IconStories.Default} />
 
     ### Color
 
@@ -102,9 +153,6 @@ import { Search } from './search/search-icons.blocks';
 
   <PostTabHeader panel="search">Find your Icon</PostTabHeader>
   <PostTabPanel name="search">
-    The icons are designed to work with the Swiss Post Design System components. They are SVGs, so they scale and can be styled with CSS.<br/>
-    Use the grid below to browse all available icons.
-
     <Search />
   </PostTabPanel>
 </PostTabs>

packages/documentation/src/stories/foundations/icons/icon.stories.ts

@@ -254,3 +254,25 @@ export const Animate: Story = {
       generateDecorators(story, context, 'd-flex flex-wrap text-center'),
   ],
 };
+
+export const ScssMixin: Story = {
+  render: () => {
+    return html`
+      <div class="my-accessibility-icon my-icon-1"></div>
+      <div class="my-accessibility-icon my-icon-2"></div>
+      <div class="my-accessibility-icon my-icon-3"></div>
+      <div class="my-accessibility-icon my-icon-4"></div>
+      <div class="my-accessibility-icon my-icon-5"></div>
+      <div class="my-accessibility-icon my-icon-6"></div>
+      <hr />
+      <div class="my-handvictory-icon" style="color: currentColor"></div>
+      <div class="my-handvictory-icon" style="width: 32px; height: 32px;"></div>
+      <div class="my-handvictory-icon" style="width: 64px; height: 64px; color: #f60;"></div>
+      <div class="my-handvictory-icon" style="width: 48px; height: 48px;"></div>
+      <div
+        class="my-handvictory-icon"
+        style="width: 32px; height: 32px; color: hsl(230, 90%, 40%); transform: rotate(15deg)"
+      ></div>
+    `;
+  },
+};

packages/documentation/src/stories/foundations/icons/icon.styles.scss

@@ -0,0 +1,39 @@
+@use '@swisspost/design-system-styles/core' as post;
+
+.my-accessibility-icon {
+  @include post.post-icon($name: 'accessibility', $base: '/post-icons');
+}
+
+.my-handvictory-icon {
+  @include post.post-icon($name: 'handvictory', $base: '/post-icons', $color: #666666);
+}
+
+.my-icon-1 {
+  width: 16px;
+  height: 16px;
+}
+
+.my-icon-2 {
+  width: 24px;
+  height: 24px;
+}
+
+.my-icon-3 {
+  width: 32px;
+  height: 32px;
+}
+
+.my-icon-4 {
+  width: 40px;
+  height: 40px;
+}
+
+.my-icon-5 {
+  width: 48px;
+  height: 48px;
+}
+
+.my-icon-6 {
+  width: 64px;
+  height: 64px;
+}

packages/documentation/src/stories/foundations/icons/mixin.sample.scss

@@ -0,0 +1,11 @@
+@use '@swisspost/design-system-styles/core' as post;
+
+.my-icon {
+  @include post.post-icon(
+    $name: 'accessibility',
+    // optional
+    $base: '/optional/path/to/your/self-hosted/svgs',
+    // optional
+    $color: '#fc0'
+  );
+}

packages/icons/src/constants.ts

@@ -19,7 +19,35 @@ export const ICON_V1_TEMPLATE = `<svg xmlns="http://www.w3.org/2000/svg">
   {uses}
 </svg>`;
 
+const ICON_V2_CONTAINER_STYLES = ICON_V2_SIZES.map((size, i) => {
+  const nextSize = ICON_V2_SIZES[i + 1];
+  const min = i !== 0 && `(min-width: ${size}px)`;
+  const max = i < ICON_V2_SIZES.length - 1 && `(max-width: ${nextSize - 1}px)`;
+
+  return `@container pi ${[min, max].filter(Boolean).join(' and ')} {
+    g {
+      --pis-${size}: block;
+    }
+  }`;
+});
+
+const ICON_V2_TEMPLATE_STYLES = `<style>
+  svg {
+    container-name: pi;
+    container-type: inline-size;
+    display: block;
+    width: 100%;
+    height: 100%;
+  }
+
+  ${ICON_V2_CONTAINER_STYLES.join('\n')}
+</style>`;
+
 export const ICON_V2_TEMPLATE = `<svg xmlns="http://www.w3.org/2000/svg">
+  ${ICON_V2_TEMPLATE_STYLES.split('\n')
+    .map(line => line.trim())
+    .map(line => (line.startsWith('@') ? line : line.replace(/(\s|\t|\n)/g, '')))
+    .join('')}
   <defs>
     <symbol id="{id}">
       <defs>
@@ -29,4 +57,8 @@ export const ICON_V2_TEMPLATE = `<svg xmlns="http://www.w3.org/2000/svg">
       {uses}
     </symbol>
   </defs>
+
+  <g>
+    <use href="#{id}"/>
+  </g>
 </svg>`;

packages/icons/src/utilities/buildSVGs.ts

@@ -159,7 +159,7 @@ function createFiles(groupedFilePaths: Record<string, File[]>) {
 
   function createSvg(id: string, template: string, symbols: string[], uses: string[]): string {
     const file = template
-      .replace('{id}', `${ID_PREFIX}-${id}`)
+      .replaceAll('{id}', `${ID_PREFIX}-${id}`)
       .replace('{symbols}', symbols.join(''))
       .replace('{uses}', uses.join(''));
 

packages/icons/svgo.config.ui.ts

@@ -27,7 +27,7 @@ export default {
       name: 'removeAttrs',
       params: {
         elemSeparator: '::',
-        attrs: ['style', 'data-.*', 'svg::(width|height|xml:space)'],
+        attrs: ['style', 'fill', 'stroke', 'data-.*', 'svg::(width|height|xml:space)'],
       },
     },
   ],

packages/styles/src/mixins/_icons.scss

@@ -14,6 +14,20 @@
   forced-color-adjust: preserve-parent-color;
 }
 
+@mixin post-icon(
+  $base: 'https://unpkg.com/@swisspost/design-system-icons/public/post-icons',
+  $name: '',
+  $color: currentColor
+) {
+  display: inline-block;
+  width: 1em;
+  height: 1em;
+  vertical-align: -0.15em;
+  background-color: currentColor;
+  color: $color;
+  mask-image: url('#{$base}/#{$name}.svg');
+}
+
 @mixin remove-icon() {
   mask-image: none;
 }