DS theme docs overview+installation

.storybook/preview.tsx

@@ -96,7 +96,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,31 @@
-import packageJson from "../../package.json"
+import packageJson from "../../package.json";
 import { Meta } from "@storybook/blocks";
 
-<Meta title="Introduction" />
+<Meta title="Installation" />
+
+<style>{`
+  .ds-docs {
+    max-width: 100ch;
+  }
+
+  .ds-docs p {
+    max-width: 78ch;
+  }
+`}</style>
+
+<div className="ds-docs">
 
 <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 +42,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 +124,8 @@ import { Meta } from "@storybook/blocks";
         }
         ```
     </div>
-</div>
 
+</div>
 
 <div className="sb-container">
     <div className='sb-section-title'>
@@ -151,4 +164,20 @@ import { Meta } from "@storybook/blocks";
         on GitHub.
 
     </div>
+    <div className='sb-section-title'>
+
+        ## Adapting the Diamond DS Theme
+
+        The Diamond DS theme is a semantic layer built on top of MUI. It separates component behaviour from fixed Diamond colours, so the same theme structure can be reused with a different palette.
+
+        The important part is the role tokens. If your CSS defines the same role variables, the components will continue to work with your new colours.
+
+        To customise the theme, copy `DiamondDSTheme` and `diamond-ds-roles.css`, then rename both for your project. In your copied CSS file, keep the same token names and replace the colour values with your own palette.
+
+        For example, within the CSS file you can change `--ds-primary: #2a4db8;` to your desired primary colour.
+
+  </div>
+
+</div>
+
 </div>

src/storybook/Overview.mdx

@@ -0,0 +1,55 @@
+import { Meta } from "@storybook/blocks";
+
+<Meta title="Overview" />
+
+<style>{`
+  .ds-docs {
+    max-width: 100ch;
+  }
+
+  .ds-docs p {
+    max-width: 78ch;
+  }
+`}</style>
+
+<div className="ds-docs">
+
+# Diamond Design System ❖
+
+<p>
+  The design system for Diamond Light Source, providing a shared foundation for
+  building clear, consistent, reliable, and predictable scientific interfaces.
+</p>
+
+## 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>
+
+## 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>
+
+## 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>