Amsterdam · VincentSmedinga · Jun 4, 2024 · May 31, 2024 · May 31, 2024 · May 31, 2024
diff --git a/packages/react/README.md b/packages/react/README.md
@@ -10,11 +10,12 @@ which are automatically installed when you install the React package.
 
 ## Stability of the components
 
-The React components are released as _alpha_ version, which means the components are still work in progress and it is likely that some APIs will change between releases.
+The React Library has not yet reached a 1.0.0 version.
+However, most of them are stable enough to be used in production.
+Components that have known issues, or for which we anticipate API changes, show a ‘beta’ badge on their page.
 
-Make sure you specify the exact version as dependency, so you can schedule to upgrade to the latest version when you have time to test for regression bugs.
-
-<!-- TODO: add alpha, beta and production statuses to components. Also show in Storybook -->
+Make sure you specify the exact version as dependency.
+You can then schedule an upgrade to the latest version when you have time to test for regressions.
 
 ## Getting started
 

diff --git a/storybook/config/storybook-overrides.css b/storybook/config/storybook-overrides.css
@@ -33,6 +33,16 @@
   margin-block-end: 2em;
 }
 
+.sbdocs-content.sbdocs-content > .ams-storybook-status-badge {
+  margin-block-end: 1.5rem;
+}
+
+.sbdocs-content.sbdocs-content > .ams-storybook-status-badge > span:nth-child(2) {
+  color: #000000;
+  font-family: "Amsterdam Sans", Arial, sans-serif;
+  font-size: var(--ams-text-level-6-font-size);
+}
+
 .sbdocs-content.sbdocs-content .sbdocs-a {
   color: #004699;
   text-decoration: underline;
@@ -55,6 +65,7 @@
 .sbdocs-content.sbdocs-content > h1,
 .sbdocs-content.sbdocs-content > div:not(.sb-unstyled) > h1 {
   font-size: 2.5rem;
+  margin-block-start: 0;
 }
 
 .sbdocs-content.sbdocs-content > h2,
@@ -88,11 +99,6 @@
   padding-block: 0;
 }
 
-.sbdocs-content.sbdocs-content > :first-child,
-.sbdocs-content.sbdocs-content > div:not(.sb-unstyled) > :first-child {
-  margin-block-start: 0;
-}
-
 .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) {
   font-size: 1rem;

diff --git a/storybook/src/components/Header/Header.docs.mdx b/storybook/src/components/Header/Header.docs.mdx
@@ -1,9 +1,12 @@
 import { Canvas, Controls, Markdown, Meta, Primary } from "@storybook/blocks";
 import * as HeaderStories from "./Header.stories.tsx";
 import README from "../../../../packages/css/src/components/header/README.md?raw";
+import { StatusBadge } from "../../docs/components/StatusBadge";
 
 <Meta of={HeaderStories} />
 
+<StatusBadge reason="Needs work for narrow screens and integration with Mega Menu." />
+
 <Markdown>{README}</Markdown>
 
 <Primary />

diff --git a/storybook/src/components/Icon/Icon.docs.mdx b/storybook/src/components/Icon/Icon.docs.mdx
@@ -1,9 +1,12 @@
 import { Canvas, Controls, Markdown, Meta, Primary } from "@storybook/blocks";
 import * as IconStories from "./Icon.stories.tsx";
 import README from "../../../../packages/css/src/components/icon/README.md?raw";
+import { StatusBadge } from "../../docs/components/StatusBadge";
 
 <Meta of={IconStories} />
 
+<StatusBadge reason="The set of available icon names and the component API will change." />
+
 <Markdown>{README}</Markdown>
 
 # Usage

diff --git a/storybook/src/components/MegaMenu/MegaMenu.docs.mdx b/storybook/src/components/MegaMenu/MegaMenu.docs.mdx
@@ -1,9 +1,12 @@
 import { Canvas, Markdown, Meta, Primary } from "@storybook/blocks";
 import * as MegaMenuStories from "./MegaMenu.stories.tsx";
 import README from "../../../../packages/css/src/components/mega-menu/README.md?raw";
+import { StatusBadge } from "../../docs/components/StatusBadge";
 
 <Meta of={MegaMenuStories} />
 
+<StatusBadge reason="Needs work for narrow screens and integration with Mega Menu." />
+
 <Markdown>{README}</Markdown>
 
 <Primary />

diff --git a/storybook/src/components/PageMenu/PageMenu.docs.mdx b/storybook/src/components/PageMenu/PageMenu.docs.mdx
@@ -1,9 +1,12 @@
 import { Canvas, Controls, Markdown, Meta, Primary } from "@storybook/blocks";
 import * as PageMenuStories from "./PageMenu.stories.tsx";
 import README from "../../../../packages/css/src/components/page-menu/README.md?raw";
+import { StatusBadge } from "../../docs/components/StatusBadge";
 
 <Meta of={PageMenuStories} />
 
+<StatusBadge reason="May be affected by changes to Header and/or have its name changed." />
+
 <Markdown>{README}</Markdown>
 
 <Primary />

diff --git a/storybook/src/components/TopTaskLink/TopTaskLink.docs.mdx b/storybook/src/components/TopTaskLink/TopTaskLink.docs.mdx
@@ -1,9 +1,12 @@
 import { Canvas, Controls, Markdown, Meta, Primary } from "@storybook/blocks";
 import * as TopTaskLinkStories from "./TopTaskLink.stories.tsx";
 import README from "../../../../packages/css/src/components/top-task-link/README.md?raw";
+import { StatusBadge } from "../../docs/components/StatusBadge";
 
 <Meta of={TopTaskLinkStories} />
 
+<StatusBadge reason="Will probably be removed in favour of Card." />
+
 <Markdown>{README}</Markdown>
 
 <Primary />

diff --git a/storybook/src/docs/color.docs.mdx b/storybook/src/docs/color.docs.mdx
@@ -1,9 +1,12 @@
 import tokens from "@amsterdam/design-system-tokens/dist/index.json";
 import { Meta } from "@storybook/blocks";
 import { ColorPalette } from "./components/ColorPalette";
+import { StatusBadge } from "./components/StatusBadge";
 
 <Meta title="Docs/Assets/Colour" />
 
+<StatusBadge reason="The set of available colours and their names will change." />
+
 # Colour
 
 The basic colours of Amsterdam are white, red, and black.

diff --git a/storybook/src/docs/components/StatusBadge.tsx b/storybook/src/docs/components/StatusBadge.tsx
@@ -0,0 +1,15 @@
+import './status-badge.css'
+import { Badge } from '@amsterdam/design-system-react/src'
+
+type StatusBadgeProps = {
+  /* Explains how the component must change to transition into another status. */
+  reason: string
+}
+
+/** Indicates the status of a component. Use this to prepare implementers for API changes. */
+export const StatusBadge = ({ reason }: StatusBadgeProps) => (
+  <span className="ams-storybook-status-badge">
+    <Badge color="orange" label="beta" />
+    <span>{reason}</span>
+  </span>
+)
diff --git a/storybook/src/docs/components/status-badge.css b/storybook/src/docs/components/status-badge.css
@@ -0,0 +1,5 @@
+.ams-storybook-status-badge {
+  align-items: center;
+  display: inline-flex;
+  gap: var(--ams-space-stack-xs);
+}
diff --git a/storybook/src/docs/icon-gallery.docs.mdx b/storybook/src/docs/icon-gallery.docs.mdx
@@ -1,8 +1,11 @@
 import { Meta } from "@storybook/blocks";
 import { AmsterdamIconGallery } from "./components/AmsterdamIconGallery";
+import { StatusBadge } from "./components/StatusBadge";
 
 <Meta title="Docs/Assets/Icons" />
 
+<StatusBadge reason="The set of available icons will change." />
+
 # Icons
 
 An overview of all currently available icons.