Create and updated documentation (and minor theme updated)

.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,82 @@
+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>
+
+## Start here
+
+<ul>
+  <li>Start with the Practical guidance section.</li>
+  <li>
+    Read Working with components to understand component standards and extension
+    rules.
+  </li>
+  <li>Use existing components and patterns before creating new ones.</li>
+  <li>Prefer semantic theme roles and tokens over hardcoded values.</li>
+  <li>Keep interactions consistent across products and workflows.</li>
+</ul>
+
+</div>