DiamondLightSource · vredchenko · Dec 16, 2025 · Dec 17, 2025 · Dec 19, 2025 · Jan 7, 2026
diff --git a/.gitignore b/.gitignore
@@ -10,4 +10,8 @@
 /docs
 .pnpm-store/
 
-tsconfig.tsbuildinfo
+tsconfig.tsbuildinfo
+
+# System files
+.DS_Store
+**/.DS_Store
diff --git a/.storybook/main.ts b/.storybook/main.ts
@@ -1,32 +1,35 @@
-import type { StorybookConfig } from "@storybook/react-webpack5";
+import type { StorybookConfig } from "@storybook/react-vite";
 
 const config: StorybookConfig = {
   stories: ["../src/**/*.mdx", "../src/**/*.stories.@(js|jsx|mjs|ts|tsx)"],
   addons: [
-    "@storybook/addon-webpack5-compiler-swc",
     "@storybook/addon-essentials",
     "@chromatic-com/storybook",
     "@storybook/addon-interactions",
     "@storybook/addon-links",
     "storybook-dark-mode",
+    "@storybook/addon-themes",
+    "@storybook/addon-a11y",
   ],
-  framework: {
-    name: "@storybook/react-webpack5",
-    options: {
-      builder: {
-        useSWC: true,
+  framework: { name: "@storybook/react-vite", options: {} },
+  docs: { autodocs: true },
+  typescript: {
+    check: false,
+    reactDocgen: "react-docgen",
+    reactDocgenTypescriptOptions: {
+      compilerOptions: {
+        allowSyntheticDefaultImports: false,
+        esModuleInterop: false,
       },
+      shouldExtractLiteralValuesFromEnum: true,
+      shouldRemoveUndefinedFromOptional: true,
+      propFilter: (prop) =>
+        prop.parent
+          ? !/node_modules\/(?!@mui)/.test(prop.parent.fileName)
+          : true,
     },
   },
   staticDirs: ["../src/public/"],
-  swc: () => ({
-    jsc: {
-      transform: {
-        react: {
-          runtime: "automatic",
-        },
-      },
-    },
-  }),
 };
+
 export default config;
diff --git a/.storybook/preview.tsx b/.storybook/preview.tsx
@@ -1,39 +1,79 @@
-import React from "react";
+import React, { useLayoutEffect } from "react";
 import { CssBaseline } from "@mui/material";
 import type { Preview } from "@storybook/react";
-
+import "@fontsource-variable/inter";
+import "./storybook.css"; /* Storybook CSS override */
 import { ThemeProvider } from "../src";
-import { GenericTheme, DiamondTheme } from "../src";
-
+import {
+  GenericTheme,
+  DiamondTheme,
+  DiamondDSTheme,
+  DiamondDSThemeDark,
+} from "../src";
 import { Context, ThemeSwapper, TextLight, TextDark } from "./ThemeSwapper";
 
 const TextThemeBase = "Theme: Generic";
 const TextThemeDiamond = "Theme: Diamond";
 
+const TextThemeDiamondDS = "Theme: DiamondDS";
+
+function resolveTheme(selectedTheme: string, mode: "light" | "dark") {
+  switch (selectedTheme) {
+    case TextThemeBase:
+      return GenericTheme;
+    case TextThemeDiamondDS:
+      return mode === "dark" ? DiamondDSThemeDark : DiamondDSTheme;
+    case TextThemeDiamond:
+    default:
+      return DiamondTheme;
+  }
+}
+
+function ApplyModeToPreviewDoc({
+  mode,
+  doc,
+}: {
+  mode: "light" | "dark";
+  doc: Document;
+}) {
+  useLayoutEffect(() => {
+    const root = doc.documentElement; // <html>
+    root.setAttribute("data-mode", mode);
+
+    // Optional: keep class too if your CSS supports it
+    root.classList.toggle("dark", mode === "dark");
+    root.classList.toggle("light", mode === "light");
+
+    root.style.colorScheme = mode;
+  }, [mode, doc]);
+
+  return null;
+}
+
 export const decorators = [
-  (StoriesWithPadding: React.FC) => {
-    return (
-      <div style={{ padding: "2em" }}>
-        <StoriesWithPadding />
-      </div>
-    );
-  },
-  (StoriesWithThemeSwapping: React.FC, context: Context) => {
-    return (
-      <ThemeSwapper context={context}>
-        <StoriesWithThemeSwapping />
-      </ThemeSwapper>
-    );
-  },
+  (StoriesWithPadding: React.FC) => (
+    <div style={{ padding: "2em" }}>
+      <StoriesWithPadding />
+    </div>
+  ),
+  (StoriesWithThemeSwapping: React.FC, context: Context) => (
+    <ThemeSwapper context={context}>
+      <StoriesWithThemeSwapping />
+    </ThemeSwapper>
+  ),
   (StoriesWithThemeProvider: React.FC, context: Context) => {
     const selectedTheme = context.globals.theme || TextThemeBase;
     const selectedThemeMode = context.globals.themeMode || TextLight;
+    const mode = selectedThemeMode === TextLight ? "light" : "dark";
 
+    // ensure we target the preview iframe document
+    const doc: Document = context?.canvasElement?.ownerDocument ?? document;
     return (
       <ThemeProvider
-        theme={selectedTheme == TextThemeBase ? GenericTheme : DiamondTheme}
-        defaultMode={selectedThemeMode == TextLight ? "light" : "dark"}
+        theme={resolveTheme(selectedTheme, mode)}
+        defaultMode={mode}
       >
+        <ApplyModeToPreviewDoc mode={mode} doc={doc} />
         <CssBaseline />
         <StoriesWithThemeProvider />
       </ThemeProvider>
@@ -48,7 +88,7 @@ const preview: Preview = {
       toolbar: {
         title: "Theme",
         icon: "cog",
-        items: [TextThemeBase, TextThemeDiamond],
+        items: [TextThemeBase, TextThemeDiamond, TextThemeDiamondDS],
         dynamicTitle: true,
       },
     },
@@ -63,35 +103,22 @@ const preview: Preview = {
     },
   },
   initialGlobals: {
-    theme: "Theme: Diamond",
-    themeMode: "Mode: Light",
+    theme: TextThemeDiamondDS,
+    themeMode: TextLight,
   },
   parameters: {
     controls: {
+      expanded: true,
       matchers: {
         color: /(background|color)$/i,
         date: /Date$/i,
       },
     },
     backgrounds: { disable: true },
     layout: "fullscreen",
-    options: {
-      storySort: {
-        order: [
-          "Introduction",
-          "Components",
-          "Theme",
-          "Theme/Logos",
-          "Theme/Colours",
-          "Helpers",
-        ],
-      },
-    },
   },
   argTypes: {
-    linkComponent: {
-      control: false,
-    },
+    linkComponent: { control: false },
   },
 };
 

diff --git a/.storybook/storybook.css b/.storybook/storybook.css
@@ -0,0 +1,58 @@
+:root {
+    --ds-font-body: 'Inter', system-ui, -apple-system, BlinkMacSystemFont,
+      'Segoe UI', Roboto, Helvetica, Arial, sans-serif;
+
+    --ds-font-heading: 'Outfit', system-ui, -apple-system, BlinkMacSystemFont,
+      'Segoe UI', Roboto, Helvetica, Arial, sans-serif;
+
+    --ds-font-mono: 'IBM Plex Mono', ui-monospace, SFMono-Regular, Menlo, Monaco,
+      Consolas, 'Liberation Mono', 'Courier New', monospace;
+  }
+
+  /* Docs root */
+  .sbdocs, .sbdocs p, .sbdocs li,.sb-unstyled, .sb-unstyled ul, .sb-unstyled li {
+    font-family: var(--ds-font-body);
+    font-size: 16px !important;
+    line-height: 1.6;
+  }
+
+  /* Lists */
+  .sbdocs li {
+    font-size: 16px !important;
+  }
+
+  /* Headings use Outfit or Inter */
+
+  .sbdocs h1 {
+    font-family: var(--ds-font-heading);
+  }
+
+  .sbdocs h3,
+  .sbdocs h4,
+  .sbdocs h5,
+  .sbdocs h6 {
+    font-family: var(--ds-font-body);
+  }
+
+  /* Code uses IBM Plex Mono */
+  .sbdocs code,
+  .sbdocs pre,
+  .sbdocs kbd,
+  .sbdocs samp,
+  .token {
+    font-family: var(--ds-font-mono);
+    font-size: 1em;
+  }
+
+  /* Neutralise Storybook Docs inline preview background wrapper */
+  .sbdocs-preview div[style*="background-color"], #storybook-root div[style*="background-color"] {
+    background-color: transparent !important;
+  }
+
+  .light .sbdocs-preview div[style*="background-color"] {
+    background-color: #f6f6f6 !important;
+  }
+
+  .dark .sbdocs-preview div[style*="background-color"]{
+    background-color: #212121   !important;
+  }
diff --git a/package.json b/package.json
@@ -27,6 +27,7 @@
     "storybook:publish": "gh-pages -b storybook/publish -d storybook-static"
   },
   "dependencies": {
+    "@fontsource-variable/inter": "^5.2.8",
     "keycloak-js": "^26.2.1",
     "react-icons": "^5.3.0",
     "utif": "^3.1.0"
@@ -48,23 +49,27 @@
     "@babel/preset-typescript": "^7.26.0",
     "@chromatic-com/storybook": "^3.2.2",
     "@eslint/eslintrc": "^3.2.0",
+    "@fontsource/ibm-plex-mono": "^5.2.7",
+    "@fontsource/inter": "^5.2.8",
+    "@fontsource/outfit": "^5.2.8",
     "@rollup/plugin-commonjs": "^28.0.1",
     "@rollup/plugin-image": "^3.0.3",
     "@rollup/plugin-json": "^6.1.0",
     "@rollup/plugin-node-resolve": "^15.3.0",
     "@rollup/plugin-terser": "^0.4.4",
     "@rollup/plugin-typescript": "^12.1.1",
-    "@storybook/addon-actions": "^8.4.4",
-    "@storybook/addon-controls": "^8.4.4",
-    "@storybook/addon-essentials": "^8.4.4",
-    "@storybook/addon-interactions": "^8.4.4",
-    "@storybook/addon-links": "^8.4.4",
-    "@storybook/addon-toolbars": "^8.4.4",
-    "@storybook/addon-webpack5-compiler-swc": "^1.0.5",
-    "@storybook/blocks": "^8.4.4",
-    "@storybook/react": "^8.4.4",
-    "@storybook/react-webpack5": "^8.4.4",
-    "@storybook/test": "^8.4.4",
+    "@storybook/addon-a11y": "^8.6.14",
+    "@storybook/addon-actions": "^8.4.7",
+    "@storybook/addon-controls": "^8.4.7",
+    "@storybook/addon-essentials": "^8.6.14",
+    "@storybook/addon-interactions": "^8.6.14",
+    "@storybook/addon-links": "^8.6.14",
+    "@storybook/addon-themes": "^8.6.14",
+    "@storybook/addon-toolbars": "^8.4.7",
+    "@storybook/blocks": "^8.4.7",
+    "@storybook/react": "^8.6.14",
+    "@storybook/react-vite": "^8.6.14",
+    "@storybook/test": "^8.6.14",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.1.0",
     "@types/node": "^20.19.21",
@@ -80,13 +85,14 @@
     "eslint-plugin-react-hooks": "^5.1.0",
     "file-loader": "^6.2.0",
     "gh-pages": "^6.2.0",
+    "react-docgen": "^8.0.2",
     "react-dom": "^18.3.1",
     "react-router-dom": "^7.5.3",
     "rollup": "^4.27.3",
     "rollup-plugin-dts": "^6.1.1",
     "rollup-plugin-peer-deps-external": "^2.2.4",
     "rollup-plugin-postcss": "^4.0.2",
-    "storybook": "^8.4.4",
+    "storybook": "^8.6.14",
     "storybook-dark-mode": "^4.0.2",
     "tslib": "^2.8.1",
     "typedoc": "^0.28.5",