docs: add a Figure element for figures with captions

website/docs/topics/anatomy-of-unleash.mdx

@@ -1,6 +1,7 @@
 ---
 title: Anatomy of Unleash
 ---
+import Figure from '@site/src/components/Figure/Figure.tsx'
 
 Unleash has many different components on different levels. This guide is here to give you a conceptual overview over how Unleash works. It covers the various components that exist within an Unleash system and how they interact with each other and with external applications. The diagrams are intended to help you understand the fundamental building blocks, such as [projects](../user_guide/projects.md), [environments](../user_guide/environments.md), [variants](../advanced/feature-toggle-variants.md) and, of course, [feature toggles](../reference/feature-toggles.mdx).
 
@@ -27,7 +28,7 @@ All Unleash instances must have at least one project at any given time. New inst
 
 Pro and Enterprise customers can create, rename, and delete projects as they wish (as long as there is always _at least one project_). Open-source users, on the other hand can _not_, and only get access to the default project.
 
-![alt_text](/img/anatomy-of-unleash-environment.png)
+<Figure caption="Unleash projects (the outer box) contain one or more environments (the inner box)." img="/img/anatomy-of-unleash-environment.png"/>
 
 ## Environments and project environments
 

website/src/components/Figure/Figure.stories.tsx

@@ -0,0 +1,30 @@
+import React from 'react';
+import Component from './Figure';
+import Layout from '@theme/Layout';
+import { BrowserRouter } from 'react-router-dom';
+
+export default {
+    title: 'Figure',
+    component: Component,
+};
+
+const Template = (args) => (
+    <BrowserRouter>
+        <Layout>
+            <Component {...args} />
+        </Layout>
+    </BrowserRouter>
+);
+
+export const WithCaption = Template.bind({});
+WithCaption.args = {
+    img: '/img/anatomy-of-unleash-constraint.png',
+    caption: 'This explanatory caption is visible to everyone.',
+};
+
+export const WithCaptionAndAlt = Template.bind({});
+WithCaption.args = {
+    img: '/img/anatomy-of-unleash-constraint.png',
+    caption: 'This explanatory caption is visible to everyone.',
+    alt: "This alt text is read out by screen readers and displayed if the image doesn't load",
+};

website/src/components/Figure/Figure.tsx

@@ -0,0 +1,89 @@
+/**
+    This component displays a figure with an accompanying figure caption. Use it
+    to display diagrams, charts, and other images that have an explanatory
+    caption that should be visible to everyone.
+
+    For some info regarding alt text vs fig captions, see this stack overflow
+    response from a blind user (available at
+    https://stackoverflow.com/questions/58447538/accessibility-difference-between-img-alt-and-figcaption):
+
+    I'm a blind user. I would say that there are two big categories of images on the web:
+
+        1. Functional images
+        2. Illustrative images a.k.a. figures
+
+    AS the name says, figcaption is a caption for a figure. The caption is
+    always visible by everybody, not only blind people. Figures are images that
+    can be found in a book, an article, or whatever more or less long paragraphs
+    of text. Most of the time, figures are purely illustrative.
+
+    When you use figcaption, the alt attribute should probably be empty:
+
+    - Copying the text of the figcaption into the alt attribute, or any
+      shortened version, is almost always useless: the screen reader will read
+      twice the same or almost the same information, and it's worth absolutely
+      nothing
+
+    - You may think that the alt attribute could be useful for a longer
+      description of the image, that wouldn't fit in the figcaption; for example
+      a detailed description of a chart or a diagram. But in fact, this kind of
+      description is better below the image or in another page (then available
+      for everybody), rather than in the alt attribute. The alt attribute should
+      normally remain short.
+
+    - You may think that the figcaption is useless and only set the alt
+      attribute to something. Example: "Photo with Alice on the left, Bob on the
+      right". But in fact sighted people could as well find this information
+      useful, if they don't know Alice and Bob for example. So it could be
+      interesting to move this description to the figcaption, so that everybody
+      benefits from it and not only blind people.
+
+    Now, the biggest case when you won't use figure/figcaption is when images
+    are functional: a button taht can be clicked, an icon with a precise
+    meaning, etc. The basic rules for alt texts of functional images are:
+
+    - If you can interact with the image to perform actions (click, etc.), or if
+      the icon conveys an information, then you must set a non-empty alt. It
+      must be a function description, not a objective description of the image.
+
+        Example 1: "Go back" is good, while "Blue left arrow" is bad.
+        Example 2: "Unread message" is good, while "Closed enveloppe" is bad
+
+    - Otherwise, if the image provide no interaction and if it doesn't convey
+      any information, then it is illustrative; the alt should be empty in that
+      case.
+
+      ------
+
+    However, even when using fig captions, there **may** be times when also
+    using an alt is appropriate, which is why it's an optional attribute on
+    this component. However, if you do use it, make sure it conveys
+    **separate** information to what the fig caption does.
+
+
+**/
+
+import React from 'react';
+
+import './styles.module.css';
+
+type Props = {
+    // An optional alt text, if the caption does not already convey all relevant
+    // information.
+    alt?: string;
+    // The figure caption, visible to everyone
+    caption: string;
+    // the path to the image, starting with `/img/`. Example: /img/image.png
+    img: string;
+};
+
+const Component: React.FC<Props> = ({ img, alt, caption }) => {
+    return (
+        <figure>
+            <img alt={alt} src={require(`@site/static${img}`).src} />
+            <figcaption>{caption}</figcaption>
+        </figure>
+    );
+};
+
+export default Component;

website/src/components/Figure/styles.module.css

@@ -0,0 +1,5 @@
+/* Figures (with captions) */
+figcaption {
+    text-align: center;
+}
+/* End figures (with captions) */