@@ -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";
}
```
-
+
+
+# Diamond Design System ❖
+
+
+ The design system for Diamond Light Source, providing a shared foundation for
+ building clear, consistent, and reliable scientific interfaces.
+
+
+
+ It evolves SciReactUI into a consistent, semantic, and scalable system for
+ data acquisition, analysis, and operational tools across Diamond.
+
+
+
+ Built on structure and precision, the system supports clear, coherent, and
+ predictable interfaces across scientific workflows and applications.
+
+
+## What it helps us do
+
+
+ - Create clearer, more predictable scientific interfaces.
+ - Bring consistency across tools and beamlines.
+ - Reduce cognitive load in complex workflows.
+ - Speed up development with reusable components.
+ - Ensure new tools start coherent and stay aligned.
+
+
+## What the design system includes
+
+
+ - Reusable MUI-based components adapted for scientific workflows.
+ - Semantic theme roles and design tokens.
+ - Practical guidance for hierarchy, interaction, feedback, and layout.
+ - Shared patterns for operational and data-heavy interfaces.
+
+
+## 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:
+
+
+ - Clarity over decoration
+ - Predictability over novelty
+ - Semantic structure over one-off styling
+ - Accessibility and operational confidence
+ - Reusable patterns over local solutions
+
+
+## Start here
+
+
+ - Start with the Practical guidance section.
+ - Use existing components and patterns before creating new ones.
+ - Prefer semantic theme roles and tokens over hardcoded values.
+ - Keep interactions consistent across products and workflows.
+
+
+
+# Practical guidance
+
+Diamond Design System uses MUI with Diamond semantic tokens layered on top.
+
+CSS variables are the source of truth. The MUI theme adapts those tokens for components and implementation.
+
+## Contents
+
+
+
+ - Using the theme
+ - Component structure
+ - Using components
+ - Colour usage
+ - Surfaces and elevation
+ - Borders
+ - Typography usage
+ - Button hierarchy and pairing
+ - Feedback and status
+ - Errors and recovery
+
+
+
+## Using the theme
+
+Diamond Design System uses semantic design tokens mapped into MUI’s theme
+system.
+
+CSS variables remain the source of truth. The MUI theme adapts those values into
+component APIs, palette roles, typography, spacing, elevation, and interaction
+states.
+
+Prefer theme roles and semantic tokens over hardcoded values.
+
+
+
+
+ | ✅ Prefer |
+ ❌ Avoid |
+
+
+
+
+
+ theme.palette.primary.main
+ |
+
+ #005bbb
+ |
+
+
+
+ theme.palette.divider
+ |
+ Custom border greys |
+
+
+
+ theme.spacing(2)
+ |
+ Arbitrary spacing values |
+
+
+
+ surface.subtle
+ |
+ One-off background colours |
+
+
+
+
+Using semantic roles keeps interfaces consistent across products, supports light
+and dark themes, and allows the system to evolve without rewriting component
+styles.
+
+## Using components
+
+Build with existing components and patterns before creating new ones.
+
+Components should keep interfaces predictable, readable, and consistent.
+
+
+
+
✅ Do
+
+ - Reuse established layouts and behaviours.
+ - Use standard component variants consistently.
+ - Keep disabled and error states visually clear.
+ - Use spacing and typography for hierarchy.
+
+
+
+
+
❌ Don’t
+
+ - Don’t restyle components screen by screen.
+ - Don’t introduce custom colours unnecessarily.
+ - Don’t create multiple patterns for the same interaction.
+ - Don’t override the theme without a reusable reason.
+
+
+
+
+## Colour usage
+
+Use colour semantically. Separate structure, meaning, and brand.
+
+DiamondDS supports:
+
+- action intents: primary, secondary
+- status intents: success, warning, error, info
+
+Intent colours communicate hierarchy, operational meaning, and state through component APIs such as `color="primary"` or `color="error"`.
+Their meaning depends on context and workflow.
+
+Brand colour is intentionally separate. Brand communicates Diamond identity rather than behaviour or status.
+
+
+
+
+ | Token/Role |
+ Type |
+ Purpose |
+ Typical usage |
+
+
+
+
+ |
+
+ Neutral
+ |
+ Structure |
+ Layout and hierarchy |
+ Backgrounds, surfaces, borders, tables |
+
+
+ |
+
+ Primary
+ |
+ Action intent |
+ Main actions and emphasis |
+ Primary actions, selected states |
+
+
+ |
+
+ Secondary
+ |
+ Action intent |
+ Supporting actions and alternate emphasis |
+ Secondary actions, filters, supporting controls |
+
+
+ |
+
+ Success
+ |
+ Status intent |
+ Confirmed, available, or operationally valid states |
+ Completion, confirmation, active or valid states |
+
+
+ |
+
+ Warning
+ |
+ Status intent |
+ Attention, caution, or elevated operational awareness |
+ Risk states, hazardous conditions, attention-required states |
+
+
+ |
+
+ Error (Danger)
+ |
+ Status intent |
+ Critical, blocking, hazardous, or destructive states |
+ Errors, failed actions, emergency-related or destructive actions |
+
+
+ |
+
+ Info
+ |
+ Status intent |
+ Informational, contextual, or progress-related feedback |
+ Progress, guidance, scanning, movement, or system messages |
+
+
+ |
+
+ Brand
+ |
+ Identity |
+ Facility identity |
+ Branding moments and facility identity |
+
+
+
+
+
+
+
+
✅ Do
+
+ - Use neutral roles for structure.
+ - Use intent roles for meaning.
+ - Use
theme.palette or MUI component props so colours work across light and dark themes.
+ - Ensure disabled and error states override hover, focus and selected styling.
+
+
+
+
+
❌ Don’t
+
+ - Don’t hardcode hex values in components.
+ - Don’t use strong intent colours as layout backgrounds.
+ - Don’t rely on colour alone to communicate state.
+ - Don’t invent one-off colour behaviour outside the theme.
+
+
+
+
+### Semantic intent and brand roles
+
+Intent and brand colours follow a shared semantic structure.
+Each role includes related tokens for emphasis, contrast, containers, and interactive states.
+
+
+
+
+ | Token pattern |
+ MUI role |
+ Purpose |
+ Typical use |
+
+
+
+
+
+ --ds-[token]
+ |
+
+ palette.[role].main
+ |
+ Main semantic colour |
+ Actions, status communication, emphasis, identity |
+
+
+
+ --ds-on-[token]
+ |
+
+ palette.[role].contrastText
+ |
+ Foreground colour paired with the role |
+ Text and icons shown on the role colour |
+
+
+
+ --ds-[token]-emphasis
+ |
+
+ palette.[role].dark
+ |
+ Stronger variation of the role |
+ Hover, active, or stronger emphasis states |
+
+
+
+ --ds-[token]-accent
+ |
+
+ palette.[role].light
+ |
+ Lighter accent variation |
+ Focus rings, highlights, supporting accents |
+
+
+
+ --ds-[token]-container
+ |
+
+ palette.[role].container
+ |
+ Lower-emphasis role surface |
+ Chips, alerts, selected regions, grouped states |
+
+
+
+ --ds-on-[token]-container
+ |
+
+ palette.[role].onContainer
+ |
+ Foreground colour paired with role containers |
+ Text and icons inside semantic containers |
+
+
+
+ --ds-[token]-solid
+ |
+
+ palette.[role].solid
+ |
+ High-emphasis interactive surface |
+ Contained buttons and strong interactive controls |
+
+
+
+ --ds-on-[token]-solid
+ |
+
+ palette.[role].onSolid
+ |
+ Foreground colour paired with solid surfaces |
+ Text and icons inside solid controls |
+
+
+
+
+
+
Token names and MUI role names are usually aligned.
+
+ DiamondDS uses danger tokens internally, which map to the MUI
+ error palette role.
+
+
+
+### Neutral roles
+
+Neutral tokens create the structure of the interface.
+They should be the default choice for layout, surfaces, borders, text, and dense scientific workflows.
+
+
+
+
+ | Token |
+ MUI role |
+ Purpose |
+ Typical use |
+
+
+
+
+
+ --ds-background
+ |
+
+ background.default
+ |
+ Root application background |
+ App shell, page canvas, full-screen layouts |
+
+
+
+ --ds-surface
+ |
+
+ background.paper
+ |
+ Base content surface |
+ Cards, dialogs, menus, content panels |
+
+
+
+ --ds-surface-container
+ |
+
+ surface.subtle
+ |
+ Quiet grouped surface |
+ Secondary panels, grouped controls, low-emphasis regions |
+
+
+
+ --ds-surface-container-high
+ |
+
+ surface.strong
+ |
+ Stronger grouped surface |
+ Nested containers, selected regions, raised sections |
+
+
+
+ --ds-surface-disabled
+ |
+
+ surface.disabled
+ |
+ Disabled surface treatment |
+ Disabled filled controls and inactive regions |
+
+
+
+ --ds-on-surface
+ |
+
+ text.primary
+ |
+ Main foreground colour |
+ Primary text and icons |
+
+
+
+ --ds-on-surface-variant
+ |
+
+ text.secondary
+ |
+ Lower-emphasis foreground colour |
+ Secondary text, metadata, helper text |
+
+
+
+ --ds-on-surface-disabled
+ |
+
+ text.disabled
+ |
+ Disabled foreground colour |
+ Disabled text and icons |
+
+
+
+ --ds-action-disabled
+ |
+
+ action.disabled
+ |
+ Disabled interactive colour |
+ Disabled buttons, controls, and actions |
+
+
+
+ --ds-border-subtle
+ |
+
+ borders.base
+ |
+ Quiet structural boundary |
+ Dividers, table lines, subtle outlines |
+
+
+
+ --ds-border-emphasis
+ |
+
+ borders.emphasis
+ |
+ Stronger boundary |
+ Interactive boundaries and active regions |
+
+
+
+ --ds-border-strong
+ |
+
+ borders.strong
+ |
+ Highest-emphasis neutral boundary |
+ Hover states and strong affordance boundaries |
+
+
+
+
+## Surfaces and elevation
+
+Surfaces create structure and hierarchy. They should help users understand
+where content belongs without making dense scientific interfaces feel noisy.
+
+Prefer layered surfaces and borders over heavy shadows.
+
+
+
+
+ | Token |
+ MUI role |
+ Purpose |
+ Typical use |
+
+
+
+
+
+ --ds-bg-page
+ |
+
+ background.default
+ |
+ Root application background |
+ App shell, page canvas, full-screen layouts |
+
+
+
+ --ds-surface
+ |
+
+ background.paper
+ |
+ Base content surface |
+ Cards, dialogs, menus, popovers, standard content panels |
+
+
+
+ --ds-surface-container
+ |
+
+ surface.subtle
+ |
+ Quiet container surface |
+ Secondary panels, grouped content, low-emphasis regions |
+
+
+
+ --ds-surface-container-high
+ |
+
+ surface.strong
+ |
+ Stronger container surface |
+ Raised sections, selected regions, nested containers |
+
+
+
+ --ds-surface-disabled
+ |
+
+ surface.disabled
+ |
+ Disabled surface treatment |
+
+ Disabled filled controls, inactive regions where a surface still needs
+ to be visible
+ |
+
+
+
+
+
+
+
+ | Element |
+ Recommended treatment |
+
+
+
+
+ | Top nav bar |
+
+ Elevation 0 + border-bottom. Elevate to 1–2 on scroll when sticky and no
+ secondary nav is present
+ |
+
+
+ | Sidebar |
+ Elevation 0 + border-right |
+
+
+ | Secondary header/nav bar |
+ Elevation 1. Elevate to 1–2 on scroll when sticky |
+
+
+ | Cards |
+
+ Elevation 0-2 + subtle border, or no border when the surface is already
+ clear
+ |
+
+
+ | Interactive cards |
+ Elevation 3–4, such as drag/drop cards |
+
+
+ | Menus, popovers, drawers |
+ Elevation 8–16 |
+
+
+ | Dialogs |
+ Elevation 16–24 |
+
+
+
+
+
+
+
✅ Do
+
+ - Use
background.default for the application canvas.
+ - Use
background.paper for primary content areas.
+ - Use
surface.subtle to group related content.
+ - Use
surface.strong for stronger grouping or selected regions.
+ - Use surface changes consistently across light and dark mode.
+
+
+
+
+
❌ Don’t
+
+ - Don’t use strong intent colours as general layout backgrounds.
+ - Don’t stack too many nested surface colours.
+ - Don’t use surface changes to compensate for unclear layout.
+ - Don’t create one-off background colours for individual components.
+ - Don’t make disabled surfaces look interactive.
+
+
+
+
+## Borders
+
+Borders define separation, grouping and affordance. They should support structure without creating visual noise.
+
+Use border roles instead of raw greys:
+
+
+
+
+ | Token |
+ MUI role |
+ Purpose |
+ Typical use |
+
+
+
+
+
+ --ds-border-subtle
+ |
+
+ divider
+ /
+
+ border.subtle
+ |
+ Default quiet border |
+ Dividers, table separators, low-emphasis boundaries |
+
+
+
+ --ds-border-emphasis
+ |
+
+ border.emphasis
+ |
+ Elevated interaction/emphasis |
+ Inputs, highlighted cards, panels, tables, important grouping |
+
+
+
+ --ds-border-strong
+ |
+
+ border.strong
+ |
+ Maximum border contrast |
+ Hover states, active regions, selected-neutral |
+
+
+
+
+MUI’s native
divider role and DiamondDS
border.subtle use the same value.
+Use
divider where a MUI component expects it, and
border.subtle when writing DiamondDS border styles directly.
+
+
+
+
✅ Do
+
+ - Use
border.subtle for quiet dividers, separators, table boundaries, and disabled outlines.
+ - Use
border.emphasis for interactive component boundaries and elements that require clearer affordance.
+ - Use
border.strong for elevated interaction states such as hover, active, or selected elements.
+ - Use intent border colours only for meaningful states such as error or selected.
+ - Let disabled and error borders override hover and focus styling.
+
+
+
+
+
❌ Don’t
+
+ - Don’t use raw grey values for component borders.
+ - Don’t use borders as the only way to communicate status.
+ - Don’t add heavy borders to compensate for weak spacing or grouping.
+ - Don’t mix several border strengths in the same small area.
+ - Don’t invent one-off border colours outside the theme.
+
+
+
+
+## Typography usage
+
+Typography should support readability, scanning, and technical clarity.
+
+
+
+
+ | Typeface |
+ Purpose |
+ Typical usage |
+
+
+
+
+ | Inter |
+ Default interface typeface |
+ UI text, controls, tables, navigation |
+
+
+ | Outfit |
+ Brand and high-level headings |
+ Product headings, landing areas |
+
+
+ | IBM Plex Mono |
+ Technical and aligned content |
+ IDs, timestamps, code, numeric values |
+
+
+
+
+
+
+
✅ Do
+
+ - Keep hierarchy consistent across products.
+ - Prefer short, clear labels.
+ - Make numbers and technical values easy to scan.
+ - Use mono type where alignment matters.
+
+
+
+
+
❌ Don’t
+
+ - Don’t use brand typography for dense operational content.
+ - Don’t rely on decorative styling for hierarchy.
+ - Don’t hide important information in faint text.
+ - Don’t introduce one-off font sizes.
+
+
+
+
+## General principles
+
+
+ - Prefer theme palette roles and component props over raw values.
+ - Reuse patterns before creating new ones.
+ - Keep interactions predictable.
+ - Design for clarity and operational confidence.
+ - Similar things should look and behave similarly.
+
+
+## Button hierarchy and pairing
+
+
+ Button hierarchy should make the next safe action obvious. Avoid placing
+ multiple high-emphasis actions next to each other unless they genuinely have
+ equal priority.
+
+
+### Default pairing
+
+Use one contained button for the main action, then reduce emphasis for nearby
+supporting actions.
+
+### Recommended patterns
+
+
+
+
+ | Pattern |
+ Use when |
+ Recommended pairing |
+
+
+
+
+ | Main action + cancel |
+ The user needs a clear way to proceed or back out |
+
+ primary contained + text
+ |
+
+
+ | Main action + supporting action |
+ The second action helps prepare or configure the main action |
+
+ primary contained + outlined
+ |
+
+
+ | Main action + more actions |
+ Additional actions are available but should not compete |
+
+ primary contained + menu button
+ |
+
+
+ | Destructive confirmation |
+ The user is confirming a destructive or irreversible action |
+
+ error contained + neutral text or{" "}
+ outlined
+ |
+
+
+ | Promoted secondary workflow |
+ A secondary action is intentionally more useful in context |
+
+ Lower-emphasis primary action + secondary contained
+ |
+
+
+
+
+
+
+
✅ Do
+
+ - Use one high-emphasis action in a local action group.
+
+ -
+ Use text buttons for cancel, dismiss, and low-risk exits.
+
+
+ -
+ Use menu buttons for overflow actions that should not compete visually.
+
+
+ -
+ Use destructive emphasis only when the action is genuinely destructive
+ or hazardous.
+
+
+
+
+
+
+
❌ Don’t
+
+ -
+ Don’t place
primary contained and
+ secondary contained next to each other by default.
+
+
+ -
+ Don’t use multiple contained buttons to solve unclear priority.
+
+
+ -
+ Don’t make cancel actions visually compete with the main action.
+
+
+ -
+ Don’t promote secondary actions just for visual variety.
+
+
+
+
+
+
+## Feedback and status
+
+
+ Interfaces should continuously communicate system state, progress, success,
+ warnings, and problems. Clear feedback helps users understand what is
+ happening, what requires attention, and whether it is safe to continue.
+
+
+### Communicate state clearly
+
+Provide feedback for important actions, transitions, and system events.
+
+Users should understand:
+
+
+ - what is happening
+ - whether an action succeeded
+ - whether attention is required
+ - whether work is still in progress
+ - what they can safely do next
+
+
+Avoid relying on colour alone. Combine colour with labels, icons, text, or
+layout changes where appropriate.
+
+---
+
+### Status intent meanings
+
+
+
+
+ | Status |
+ Purpose |
+ Typical usage |
+
+
+
+
+ |
+
+ Success
+ |
+ Positive or valid outcome |
+ Completed actions, successful operations, valid system state |
+
+
+ |
+
+ Warning
+ |
+ Caution or attention required |
+ Risk states, interruptions, unusual conditions, partial issues |
+
+
+ |
+
+ Error/Danger
+ |
+ Critical issue or failed action |
+ Validation failures, failed operations, destructive actions |
+
+
+ |
+
+ Info
+ |
+ Informational or transitional state |
+ Progress updates, guidance, active processes, system messages |
+
+
+
+
+---
+
+### Progress and transitional states
+
+Use informational feedback for active or changing system states.
+
+Examples include:
+
+
+ - scanning in progress
+ - moving motors
+ - connecting to device
+ - processing data
+ - queue paused
+
+
+Prefer persistent inline or contextual feedback over temporary notifications for
+long-running operations.
+
+---
+
+### Success feedback
+
+Use success feedback sparingly.
+
+Not every successful action requires a notification.
+
+Prefer lightweight confirmation for routine actions, especially in repetitive
+scientific workflows.
+
+
+
+
+ | ✅ Prefer |
+ ❌ Avoid |
+
+
+
+
+ | Quiet inline confirmation after saving |
+ Large celebratory success states for routine operations |
+
+
+ | Small status update in a queue or table row |
+ Stacking repeated success toasts during repetitive workflows |
+
+
+ | Temporary confirmation for destructive actions |
+ Interrupting workflow with unnecessary success messaging |
+
+
+
+
+---
+
+## Errors and recovery
+
+
+ Error handling should help users recover safely and confidently. Focus on
+ clarity, next steps, and preventing further mistakes.
+
+
+### Make errors actionable
+
+Good error messages explain:
+
+
+ - what happened
+ - what caused the issue, if known
+ - what the user can do next
+
+
+Avoid vague or technical-only messaging where possible.
+
+
+
+
+ | ❌ Avoid |
+ ✅ Prefer |
+
+
+
+
+
+ Operation failed
+ |
+
+ Unable to connect to detector
+ |
+
+
+
+ Validation error
+ |
+
+ Exposure time must be greater than 0
+ |
+
+
+
+ Device unavailable
+ |
+
+
+ Motor controller is offline. Reconnect or contact beamline staff.
+
+ |
+
+
+
+
+---
+
+### Prefer recovery over dead ends
+
+Where possible, help users continue safely.
+
+Provide:
+
+
+ - retry actions
+ - alternative paths
+ - clear recovery guidance
+ - safe defaults
+
+
+Avoid trapping users in blocked states without explanation.
+
+---
+
+### Error severity
+
+Not all errors require the same visual weight.
+
+
+
+
+ | Severity |
+ Typical treatment |
+
+
+
+
+ | Minor |
+ Inline validation or local helper text |
+
+
+ | Moderate |
+ Inline alert, panel warning, persistent message |
+
+
+ | Critical |
+ Blocking alert, dialog, or operational interruption |
+
+
+
+
+---
+
+### Safety and operational awareness
+
+In scientific and operational environments, errors may affect hardware,
+beamtime, experiments, or data integrity.
+
+Use stronger emphasis when actions may:
+
+
+ - interrupt experiments
+ - move hardware
+ - discard data
+ - affect safety
+ - impact other users or systems
+
+
+Destructive or irreversible actions should require clear confirmation and should
+never compete visually with safe actions.
+
+