feat: favicon, app icons and optional Web Manifest (#1205)

Co-authored-by: Vincent Smedinga <v.smedinga@amsterdam.nl>
Co-authored-by: Niels Roozemond <n.roozemond@amsterdam.nl>

proprietary/assets/README.md

@@ -3,3 +3,7 @@
 # Assets
 
 Assets for the City of Amsterdam
+
+## Web app manifest, app icons and favicon
+
+See the Design System documentation for an [overview and examples of the manifest and these icons](https://amsterdam.github.io/design-system/?path=/docs/docs-assets-favicon-app-icons--docs).

proprietary/assets/manifest/app.webmanifest

@@ -0,0 +1,16 @@
+{
+  "name": "APP_NAME_FULL",
+  "short_name": "APP_NAME",
+  "icons": [
+    {
+      "src": "app-icons/icon-192.png",
+      "type": "image/png",
+      "sizes": "192x192"
+    },
+    {
+      "src": "app-icons/icon-512.png",
+      "type": "image/png",
+      "sizes": "512x512"
+    }
+  ]
+}

storybook/config/main.ts

@@ -30,6 +30,7 @@ const config: StorybookConfig = {
   docs: {
     autodocs: true,
   },
+  staticDirs: ['../../proprietary/assets'],
   typescript: {
     reactDocgen: 'react-docgen-typescript',
   },

storybook/config/preview-body.html

@@ -1,5 +1,7 @@
 <style>
   .ams-docs-figure {
+    display: flex;
+    gap: 0.25rem;
     margin: 0; /* stylelint-disable-line */
     padding: 0; /* stylelint-disable-line */
   }
@@ -8,6 +10,27 @@
   .ams-docs-figure > img {
     display: block;
     max-width: 100%;
+    outline: 1px dashed #e8e8e8;
+  }
+
+  .ams-docs-figure > figcaption {
+    text-align: center;
+  }
+
+  .ams-docs-gallery {
+    align-items: flex-end;
+    display: flex;
+    gap: 2rem;
+    margin-block: 1.5rem;
+  }
+
+  .ams-docs-gallery .ams-docs-figure {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    margin-inline: 0;
+    width: -moz-fit-content;
+    width: fit-content;
   }
 
   .ams-docs-paragraph {

storybook/config/storybook-overrides.css

@@ -9,7 +9,8 @@
 .sbdocs-content.sbdocs-content > :is(ol, ul) li,
 .sbdocs-content.sbdocs-content > div:not(.sb-unstyled) > :is(ol, ul) li,
 .sbdocs-content.sbdocs-content > table:not(.sb-unstyled) :is(td, th),
-.sbdocs-content.sbdocs-content > div:not(.sb-unstyled) > table:not(.sb-unstyled) :is(td, th) {
+.sbdocs-content.sbdocs-content > div:not(.sb-unstyled) > table:not(.sb-unstyled) :is(td, th),
+.sbdocs-content.sbdocs-content > div:not(.sb-unstyled) figcaption {
   color: #000000;
   font-family: "Amsterdam Sans", Arial, sans-serif;
 }
@@ -103,4 +104,8 @@
   font-size: 1rem;
 }
 
+.sbdocs-content.sbdocs-content > div:not(.sb-unstyled) figcaption {
+  font-size: 0.875rem;
+}
+
 /* stylelint-enable */

storybook/src/docs/components/AppIcons.tsx

@@ -0,0 +1,53 @@
+import { Image } from '@amsterdam/design-system-react'
+
+export const AppleTouchIcon = () => (
+  <div className="ams-docs-gallery">
+    <figure className="ams-docs-figure">
+      <Image src="favicon/apple-touch-icon.png" width={180} height={180} />
+      <figcaption>apple-touch-icon.png (180px)</figcaption>
+    </figure>
+  </div>
+)
+
+export const Favicon = () => (
+  <div className="ams-docs-gallery">
+    <figure className="ams-docs-figure">
+      <Image src="favicon/favicon.ico" width={16} height={16} />
+      <figcaption>favicon.ico (16px)</figcaption>
+    </figure>
+    <figure className="ams-docs-figure">
+      <Image src="favicon/favicon.ico" width={32} height={32} />
+      <figcaption>favicon.ico (32px)</figcaption>
+    </figure>
+    <figure className="ams-docs-figure">
+      <Image src="favicon/favicon.ico" width={48} height={48} />
+      <figcaption>favicon.ico (48px)</figcaption>
+    </figure>
+    <figure className="ams-docs-figure">
+      <Image src="favicon/favicon.ico" width={64} height={64} />
+      <figcaption>favicon.ico (64px)</figcaption>
+    </figure>
+  </div>
+)
+
+export const SvgIcon = () => (
+  <div className="ams-docs-gallery">
+    <figure className="ams-docs-figure">
+      <Image src="favicon/icon.svg" width={64} height={64} />
+      <figcaption>icon.svg (64px)</figcaption>
+    </figure>
+  </div>
+)
+
+export const WebAppIcons = () => (
+  <div className="ams-docs-gallery">
+    <figure className="ams-docs-figure">
+      <Image src="app-icons/icon-192.png" width={192} height={192} />
+      <figcaption>icon-192.png (192px)</figcaption>
+    </figure>
+    <figure className="ams-docs-figure">
+      <Image src="app-icons/icon-512.png" width={512} height={512} />
+      <figcaption>icon-512.png (512px)</figcaption>
+    </figure>
+  </div>
+)

storybook/src/docs/favicon.docs.mdx

@@ -0,0 +1,100 @@
+import { Meta } from "@storybook/blocks";
+import { AppleTouchIcon, Favicon, SvgIcon } from "./components/AppIcons";
+
+<Meta title="Docs/Assets/Favicon" />
+
+# Favicon: the website's icon
+
+Represent the website in bookmarks, on home screens, in syndication and other tools.
+
+Here’s how to display a website icon (a favicon) in the web browser.
+This set covers all common browsers (Chrome, Safari, Edge, and Firefox).
+
+> There is seperate documentation on [how to publish a web app with the proper app names and icons](/docs/docs-assets-web-app--docs).
+
+## Usage
+
+### Install the assets
+
+First, install these assets as they come with the [Amsterdam Design System Assets](https://www.npmjs.com/package/@amsterdam/design-system-assets):
+
+```sh
+npm i @amsterdam/design-system-assets
+```
+
+### Link the installed assets
+
+You can manually [symlink (symbolic link)](https://en.wikipedia.org/wiki/Symbolic_link#POSIX_and_Unix-like_operating_systems) and copy the files to the root or a `public` folder next to where the `index.html` is located in your project.
+An advantage of symlinking is that it tracks changes to the assets when there are package updates. Symlinks are basically shortcuts to files or directories.
+
+Symlinking [the entire favicon directory](https://github.com/Amsterdam/design-system/tree/develop/proprietary/assets/favicon) can be done as follows:
+
+```sh
+# `cd` to the directory where you want to make the symlinks. For example:
+cd public
+
+# Symlink the icons folder. The symlink file (the last argument) can be named anything you like.
+ln -s ../node_modules/@amsterdam/design-system-assets/favicon favicon
+```
+
+> Important: the symlink, the last argument in the above command, cannot be a path, but can only be the file or directory name.
+> I.e. you need to be in the directory where you want to make the symbolic link.
+
+> Note that undoing a symlink can be done by simply removing the created file or directory link:
+>
+> ```sh
+> rm -r favicon
+> ```
+
+Then link all these assets by placing the following tags in the `<head>`:
+
+```html
+<head>
+  ...
+  <link rel="icon" href="favicon/favicon.ico" size="16x16 32x32 48x48 64x64" />
+  <link rel="icon" href="favicon/icon.svg" type="image/svg+xml" />
+  <link rel="apple-touch-icon" href="favicon/apple-touch-icon.png" />
+  ...
+</head>
+```
+
+### Submit the changes
+
+The symlink(s) and edited files can be committed to the repository.
+
+## Overview & examples
+
+### Favicon
+
+<Favicon />
+
+We include a classic icon file with this exact name as a baseline for some browsers and RSS readers.
+
+```html
+<link rel="icon" href="favicon.ico" sizes="16x16 32x32 48x48 64x64" />
+```
+
+### SVG Icon
+
+<SvgIcon />
+
+Roughly 75% of browsers support SVG favicons, which are more efficient and versatile.
+
+```html
+<link rel="icon" type="image/svg+xml" href="icon.svg" />
+```
+
+### Apple Touch Icon
+
+<AppleTouchIcon />
+
+An iPhone or iPad uses this image when adding the webpage as a shortcut to your home screen.
+
+```html
+<link rel="apple-touch-icon" href="apple-touch-icon.png" />
+```
+
+## Further Reading
+
+- [_How to Favicon in 2024: Six files that fit most needs_ by Andrey Sitnik](https://evilmartians.com/chronicles/how-to-favicon-in-2021-six-files-that-fit-most-needs)
+- [_Definitive edition of “How to Favicon” in 2023_ by Masa Kudamatsu](https://dev.to/masakudamatsu/favicon-nightmare-how-to-maintain-sanity-3al7)

storybook/src/docs/web-app.docs.mdx

@@ -0,0 +1,114 @@
+import { Meta } from "@storybook/blocks";
+import { WebAppIcons } from "./components/AppIcons";
+
+<Meta title="Docs/Assets/Web App" />
+
+# Progressive Web App: manifest and icons
+
+Turn a website into a Progressive Web App (PWA) with a Web Manifest and app icons.
+
+Here’s how to publish a web app with the proper app names and icons.
+This set covers all combinations of common operating systems (Android, iOS, macOS, and Windows) and browsers (Chrome, Safari, Edge, and Firefox).
+
+> There is seperate documentation on [how to add a website icon (a “favicon”)](/docs/docs-assets-web-app--docs).
+
+## Usage
+
+### Install the assets
+
+First, install these assets as they come with the [Amsterdam Design System Assets](https://www.npmjs.com/package/@amsterdam/design-system-assets):
+
+```sh
+npm i @amsterdam/design-system-assets
+```
+
+### Link the installed assets
+
+You can manually [symlink (symbolic link)](https://en.wikipedia.org/wiki/Symbolic_link#POSIX_and_Unix-like_operating_systems) and copy the files to the root or a `public` folder next to where the `index.html` is located in your project.
+An advantage of symlinking is that it tracks changes to the assets when there are package updates. Symlinks are basically shortcuts to files or directories.
+
+Symlink the app icons and copy the [Web Manifest](https://github.com/Amsterdam/design-system/tree/develop/proprietary/assets/app.manifest):
+
+```sh
+# `cd` to the directory where you want to make the symlinks. For example:
+cd public
+
+# Symlink the app icons. The symlink file (the last argument) can be named anything you like.
+ln -s ../node_modules/@amsterdam/design-system-assets/app-icons app-icons
+
+# Copy the Web Manifest. Don't forget to edit it with the app's name.
+cp ../node_modules/@amsterdam/design-system-assets/manifest/app.webmanifest app.webmanifest
+```
+
+> Important: the symlink, the last argument in the above command, cannot be a path, but can only be the file or directory name.
+> I.e. you need to be in the directory where you want to make the symbolic link.
+
+> Note that undoing a symlink can be done by simply removing the created file or directory link:
+>
+> ```sh
+> rm -r app-icons app.webmanifest
+> ```
+
+> Note: not all servers recognize the `.webmanifest` extension.
+> See [Using a link element to link to a manifest on W3.org](https://www.w3.org/TR/appmanifest/#using-a-link-element-to-link-to-a-manifest) for more information.
+
+Make sure that the Web Manifest, stating the app's name and referencing the PNG icons, is available in the same location.
+Edit the `app.webmanifest` file to include the app's name and the icons you want to use.
+For example:
+
+```json
+{
+  "name": "A maximum of thirty characters",
+  "short_name": "Max 12 chars",
+  "icons": [
+    { "src": "app-icons/icon-192.png", "type": "image/png", "sizes": "192x192" },
+    { "src": "app-icons/icon-512.png", "type": "image/png", "sizes": "512x512" }
+  ]
+}
+```
+
+Then link all these assets by placing the following tags in the `<head>`:
+
+```html
+<head>
+  ...
+  <link rel="manifest" href="app.webmanifest" />
+  ...
+</head>
+```
+
+### Submit the changes
+
+The symlink(s) and copied and edited files can be committed to the repository.
+
+## Overview & examples
+
+### Web App Icons
+
+<WebAppIcons />
+
+Include `icons` object in `*.webmanifest` (see [Usage](#usage)):
+
+```json
+{
+  "icons": [
+    { "src": "/icon-192.png", "type": "image/png", "sizes": "192x192" },
+    { "src": "/icon-512.png", "type": "image/png", "sizes": "512x512" }
+  ]
+}
+```
+
+Link the Web Manifest in the `<head>`:
+
+```html
+<link rel="manifest" href="app.webmanifest" />
+```
+
+> Note: only include a Web Manifest if you want the website to be installable as a Progressive Web App (PWA).
+> Browsers [may prompt the user to install the app](https://web.dev/learn/pwa/installation-prompt) on their device if a manifest is found.
+
+## Further Reading
+
+- [_Web App Manifest_ on web.dev](https://web.dev/learn/pwa/web-app-manifest)
+- [_Web app manifests: Icons_ on MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/Manifest/icons)
+- [_How to Favicon in 2024: Six files that fit most needs_ by Andrey Sitnik](https://evilmartians.com/chronicles/how-to-favicon-in-2021-six-files-that-fit-most-needs)