Normalize & document icon usage, and move design documents into storybook

frontend/.eslintrc.js

@@ -139,7 +139,14 @@ module.exports = {
       typescript: true,
     },
   },
-  ignorePatterns: ["__generated__", "__mocks__", "dist", "docs"],
+  ignorePatterns: [
+    "__generated__",
+    "__mocks__",
+    "dist",
+    "docs",
+    "!.storybook",
+    "storybook-static",
+  ],
   overrides: [
     {
       extends: ["plugin:@typescript-eslint/disable-type-checked"],
@@ -162,5 +169,18 @@ module.exports = {
         "@typescript-eslint/no-unsafe-call": "off",
       },
     },
+    {
+      files: [".storybook/**/*.tsx"],
+      extends: [
+        "eslint:recommended",
+        "plugin:@typescript-eslint/eslint-recommended",
+        "plugin:import-x/recommended",
+        "plugin:storybook/recommended",
+        "prettier",
+      ],
+      parserOptions: {
+        project: [".storybook/tsconfig.json"],
+      },
+    },
   ],
 };

frontend/.storybook/blocks/ColorSwatch.tsx

@@ -0,0 +1,39 @@
+import React from "react";
+
+export const ColorSwatch = ({
+  color,
+  children,
+}: {
+  color: string;
+  children: React.ReactNode;
+}) => {
+  return (
+    <span
+      className="sb-unstyled inline-flex items-baseline ring-1"
+      style={
+        {
+          "--tw-ring-color": "rgb(236, 244, 249)",
+          "--tw-ring-inset": "inset",
+          paddingTop: 2,
+          paddingBottom: 2,
+          borderRadius: 5,
+          paddingRight: 2,
+        } as React.CSSProperties
+      }
+    >
+      {children}
+      <span
+        className="font-monospace inline-block self-center rounded-sm ring-1"
+        style={
+          {
+            width: 21,
+            height: 21,
+            backgroundColor: color,
+            "--tw-ring-color": "#0004",
+            "--tw-ring-inset": "inset",
+          } as React.CSSProperties
+        }
+      ></span>
+    </span>
+  );
+};

frontend/.storybook/main.ts

@@ -1,6 +1,8 @@
 import path from "path";
 
 import type { StorybookConfig } from "@storybook/web-components-webpack5";
+import EslintWebpackPlugin from "eslint-webpack-plugin";
+import remarkGfm from "remark-gfm";
 import type { WebpackConfiguration } from "webpack-dev-server";
 
 import {
@@ -15,6 +17,7 @@ const config: StorybookConfig = {
       from: shoelaceAssetsSrcPath,
       to: shoelaceAssetsPublicPath,
     },
+    { from: "../src/assets/", to: "/assets" },
   ],
   addons: [
     "@storybook/addon-webpack5-compiler-swc",
@@ -70,17 +73,27 @@ const config: StorybookConfig = {
         ],
       },
     },
+    {
+      name: "@storybook/addon-docs",
+      options: {
+        mdxPluginOptions: {
+          mdxCompileOptions: {
+            remarkPlugins: [remarkGfm],
+          },
+        },
+      },
+    },
   ],
   framework: {
     name: "@storybook/web-components-webpack5",
     options: {},
   },
   webpackFinal: async (config) => {
     // Show eslint errors from Storybook files in Webpack overlay
-    const ESLintPlugin = require("eslint-webpack-plugin");
 
     config.plugins?.push(
-      new ESLintPlugin({
+      // @ts-expect-error something to do with different symbols - not totally sure, but doesn't seem to be a problem
+      new EslintWebpackPlugin({
         files: ["**/stories/**/*.ts", "**/.storybook/*.ts"],
       }),
     );
@@ -98,6 +111,7 @@ const config: StorybookConfig = {
       parser: {
         syntax: "typescript",
         decorators: true,
+        jsx: true,
       },
       // TODO Consolidate with tsconfig.json
       transform: {

frontend/.storybook/preview.ts

@@ -6,8 +6,11 @@ import {
   type Preview,
 } from "@storybook/web-components";
 
+// eslint-disable-next-line import-x/no-unresolved -- File is generated at build time
 import customElements from "@/__generated__/custom-elements.json";
 
+import "../src/theme.stylesheet.css";
+
 // Automatically document component properties
 setCustomElementsManifest(customElements);
 

frontend/.storybook/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "jsx": "react",
+    "resolveJsonModule": true,
+    "esModuleInterop": true,
+  },
+  "include": ["**/*.ts", "**/*.tsx"],
+}

frontend/docs/docs/develop/ui/storybook.md

@@ -1,6 +1,6 @@
 # Using Storybook
 
-[Storybook](https://storybook.js.org/) is a tool for documenting and building UI components in isolation. Component documentation is organized into ["stories"](https://storybook.js.org/docs/writing-stories) that show a variety of possible rendered states of a UI component.
+[Storybook](https://storybook.js.org/) is a tool for documenting and building UI components and design systems in isolation. Component documentation is organized into ["stories"](https://storybook.js.org/docs/writing-stories) that show a variety of possible rendered states of a UI component.
 
 Browsertrix component stories live in `frontend/src/stories`. Component attributes that are public properties (i.e. defined with Lit `@property({ type: Type })`) or documented in a TSDoc comment will automatically appear in stories through the [Custom Elements Manifest](https://custom-elements-manifest.open-wc.org/analyzer/getting-started/) file.