zma/DS theme docs overview+installation

.storybook/preview.tsx

@@ -95,7 +95,8 @@ const preview: Preview = {
     options: {
       storySort: {
         order: [
-          "Introduction",
+          "Overview",
+          "Installation",
           "Helpers",
           "Theme",
           "Theme/Logos",

src/storybook/Introduction.mdx → src/storybook/Installation.mdx

@@ -1,19 +1,19 @@
-import packageJson from "../../package.json"
+import packageJson from "../../package.json";
 import { Meta } from "@storybook/blocks";
 
-<Meta title="Introduction" />
+<Meta title="Installation" />
 
 <div className="sb-container">
     <div className='sb-section-title'>
-        # Scientific React UI - v{packageJson.version}
+        # SciReactUI - v{packageJson.version}
 
         ## Introduction
 
-        SciReactUI is a collection of useful scientific focused components which utilizing Material UI
-        to make your React based websites look great.
+        SciReactUI provides the implementation package for Diamond Design System.
 
-        Check out the list of components on the left. To use them, follow the instructions below.
+        Use this page to install the package, add the theme provider, and start using components in a React application.
     </div>
+
 </div>
 
 <div className="sb-container">
@@ -30,8 +30,9 @@ import { Meta } from "@storybook/blocks";
 
         ### Next, Add a ThemeProvider
 
-        Select a theme, either `GenericTheme` or `DiamondTheme` (Or you can create your own, see below), and add
-        it to the App via the ThemeProvider:
+        Select theme `DiamondDSTheme` (or `GenericTheme`), and add it to the App via the ThemeProvider.
+
+        Alternatively, you can fork an existing theme or create your own (see below).
 
         ```tsx filename="main.tsx"
         import {
@@ -111,8 +112,8 @@ import { Meta } from "@storybook/blocks";
         }
         ```
     </div>
-</div>
 
+</div>
 
 <div className="sb-container">
     <div className='sb-section-title'>
@@ -151,4 +152,23 @@ import { Meta } from "@storybook/blocks";
         on GitHub.
 
     </div>
+    <div className='sb-section-title'>
+
+        ## Forking the Diamond theme
+
+        If you need the same DiamondDS component behaviour with a different palette, you
+        can fork `DiamondDSTheme` and provide your own role CSS file instead of
+        `diamond-ds-roles.css`.
+
+        The theme is designed so most component styling uses semantic roles, not raw
+        Diamond colours. If your new CSS file defines the same role variables, the
+        components should continue to work with the new palette.
+
+        For example, replace:
+
+        ```ts
+        import "../styles/diamondDS/diamond-ds-roles.css";
+        ```
+    </div>
+
 </div>

src/storybook/Overview.mdx

@@ -0,0 +1,69 @@
+import { Meta } from "@storybook/blocks";
+
+<Meta title="Overview" />
+
+<style>{`
+  .ds-docs {
+    max-width: 64ch;
+  }
+`}</style>
+
+<div className="ds-docs">
+
+# Diamond Design System ❖
+
+<p>
+  The design system for Diamond Light Source, providing a shared foundation for
+  building clear, consistent, and reliable scientific interfaces.
+</p>
+
+<p>
+  It evolves SciReactUI into a consistent, semantic, and scalable system for
+  data acquisition, analysis, and operational tools across Diamond.
+</p>
+
+<p>
+  Built on structure and precision, the system supports clear, coherent, and
+  predictable interfaces across scientific workflows and applications.
+</p>
+
+## What it helps us do
+
+<ul>
+  <li>Create clearer, more predictable scientific interfaces.</li>
+  <li>Bring consistency across tools and beamlines.</li>
+  <li>Reduce cognitive load in complex workflows.</li>
+  <li>Speed up development with reusable components.</li>
+  <li>Ensure new tools start coherent and stay aligned.</li>
+</ul>
+
+## What the design system includes
+
+<ul>
+  <li>Reusable MUI-based components adapted for scientific workflows.</li>
+  <li>Semantic theme roles and design tokens.</li>
+  <li>Practical guidance for hierarchy, interaction, feedback, and layout.</li>
+  <li>Shared patterns for operational and data-heavy interfaces.</li>
+</ul>
+
+## Who it is for
+
+Diamond Design System supports designers, engineers, scientists, and product
+teams building operational and experimental software across Diamond.
+
+The system helps teams create interfaces that feel consistent, predictable, and
+safe to use across different tools and beamlines.
+
+## Principles
+
+The system focuses on:
+
+<ul>
+  <li>Clarity over decoration</li>
+  <li>Predictability over novelty</li>
+  <li>Semantic structure over one-off styling</li>
+  <li>Accessibility and operational confidence</li>
+  <li>Reusable patterns over local solutions</li>
+</ul>
+
+</div>

src/styles/diamondDS/diamond-ds-roles.css

@@ -51,8 +51,8 @@
   --ds-placeholder-focus: var(--ds-grey-700);
 
   --ds-border-subtle: var(--ds-grey-300);
-  --ds-border: var(--ds-grey-400);
-  --ds-border-emphasis: var(--ds-grey-500);
+  --ds-border-emphasis: var(--ds-grey-400);
+  --ds-border-strong: var(--ds-grey-500);
   --ds-border-subtle-channel: 221 225 232;
 
   /* Interaction overlays

src/themes/DiamondDSTheme.ts

@@ -186,10 +186,10 @@ declare module "@mui/material/styles" {
     brand?: BrandPaletteColor;
 
     /** Neutral border roles used for structure, not meaning. */
-    borders: {
+    border: {
       subtle: string;
-      base: string;
       emphasis: string;
+      strong: string;
     };
 
     /** Neutral surface roles used to create hierarchy without semantic state. */
@@ -216,10 +216,10 @@ declare module "@mui/material/styles" {
   interface PaletteOptions {
     brand?: BrandPaletteOptions;
 
-    borders?: {
+    border?: {
       subtle?: string;
-      base?: string;
       emphasis?: string;
+      strong?: string;
     };
     surface?: {
       subtle?: string;
@@ -514,13 +514,22 @@ const createDiamondPalette = (mode: DSMode) => {
       paper: "rgb(var(--ds-surface-channel))",
     },
 
+    /**
+     * Divider and border roles describe structure and separation, not meaning.
+     *
+     * Divider is the default border role for general structure and separatio.
+     * Border.subtle is a semantic utlisity role for components that need to reference a border colour directly.
+     * Border.emphasis is a emphasised border role for actionable elements and highlighted states.
+     * Border.strong is a stronger border role for hover and focus states.
+     *
+     */
     divider: "var(--ds-border-subtle)",
     dividerChannel: "var(--ds-border-subtle-channel)",
 
-    borders: {
-      subtle: "var(--ds-border-subtle)",
-      base: "var(--ds-border)",
+    border: {
+      subtle: "var(--ds-border)",
       emphasis: "var(--ds-border-emphasis)",
+      strong: "var(--ds-border-strong)",
     },
 
     surface: {
@@ -746,7 +755,7 @@ const DiamondDSTheme = extendTheme({
 
               "&.Mui-disabled": {
                 ...getDisabledControlStyles(),
-                borderColor: "var(--ds-border-subtle)",
+                borderColor: "var(--ds-border)",
               },
             };
           }
@@ -835,10 +844,10 @@ const DiamondDSTheme = extendTheme({
       styleOverrides: {
         root: ({ theme }: ThemeOnlyArgs): CSSObject => ({
           textTransform: "none",
-          border: `1px solid ${theme.palette.borders.base}`,
+          border: `1px solid ${theme.palette.border.emphasis}`,
 
           "&:hover": {
-            borderColor: theme.palette.borders.emphasis,
+            borderColor: theme.palette.border.strong,
           },
 
           "&.Mui-selected": {
@@ -855,7 +864,7 @@ const DiamondDSTheme = extendTheme({
 
           "&.Mui-disabled": {
             color: "var(--ds-on-surface-disabled)",
-            borderColor: "var(--ds-border-subtle)",
+            borderColor: "var(--ds-border)",
           },
         }),
       },
@@ -888,7 +897,7 @@ const DiamondDSTheme = extendTheme({
               ...(isInteractive ? getFocusOutline() : {}),
 
               color: "var(--ds-on-surface)",
-              borderColor: "var(--ds-border)",
+              borderColor: "var(--ds-border-emphasis)",
               backgroundColor,
 
               ...(isInteractive && {
@@ -1039,12 +1048,12 @@ const DiamondDSTheme = extendTheme({
 
           return {
             "& .MuiOutlinedInput-notchedOutline": {
-              borderColor: theme.palette.borders.base,
+              borderColor: theme.palette.border.emphasis,
             },
 
             "&:hover:not(.Mui-disabled):not(.Mui-error):not(.Mui-focused) .MuiOutlinedInput-notchedOutline":
               {
-                borderColor: theme.palette.borders.emphasis,
+                borderColor: theme.palette.border.strong,
               },
 
             "&.Mui-focused:not(.Mui-disabled):not(.Mui-error) .MuiOutlinedInput-notchedOutline":
@@ -1079,7 +1088,7 @@ const DiamondDSTheme = extendTheme({
             },
 
             "&.Mui-disabled .MuiOutlinedInput-notchedOutline": {
-              borderColor: "var(--ds-border-subtle)",
+              borderColor: "var(--ds-border)",
             },
           };
         },
@@ -1214,7 +1223,7 @@ const DiamondDSTheme = extendTheme({
             ...common,
             backgroundColor: p.container,
             color: p.onContainer,
-            border: "1px solid var(--ds-border-subtle)",
+            border: "1px solid var(--ds-border)",
           };
         },
       },
@@ -1302,7 +1311,7 @@ const DiamondDSTheme = extendTheme({
         root: {
           backgroundColor: "var(--ds-surface-container)",
           color: "var(--ds-on-surface)",
-          border: "1px solid var(--ds-border-subtle)",
+          border: "1px solid var(--ds-border)",
           borderRadius: 8,
         },