+
+# Colour
+
+
+ Colour helps users understand structure, meaning, and system state across
+ Diamond applications. In scientific software, colour must support complex
+ workflows, dense information displays, and operational decision-making without
+ becoming distracting or overwhelming.
+
+
+DiamondDS uses colour semantically. Colours are chosen based on purpose rather than appearance. Neutral colours provide structure and hierarchy, intent colours communicate actions and status, and brand colours express Diamond identity.
+
+Most interfaces should be built primarily from neutral colours, with semantic colours used deliberately to draw attention to actions, changes in state, warnings, errors, or other important information. This helps maintain clarity, reduces visual noise, and ensures meaningful information stands out when it matters.
+
+---
+
+
+ Colour should support understanding, not carry meaning on its own. Important
+ information should also be communicated through text, icons, labels, layout,
+ or interaction patterns.
+
+
+## Contents
+
+
+
+
Colour principles
+
Colour model
+
Colour decision tree
+
Surface model
+
Colour anatomy
+
Interaction states
+
Scientific workflow guidance
+
Data visualisation guidance
+
Accessibility
+
Token reference
+
+
+
+## 1. Colour principles
+
+
+### Colour supports scientific work
+
+Colour should help users understand information, state, and action without becoming visual noise. Scientific applications often display large amounts of information at the same time, so colour must be deliberate, predictable, and accessible.
+
+### Structure before meaning
+
+Use neutral colours to build hierarchy, grouping, and layout.
+
+Apply semantic colours only when meaning needs to be communicated.
+
+### Meaning before brand
+
+Action and status colours communicate behaviour and system state.
+
+Brand colours communicate Diamond identity.
+
+Brand colour should rarely be responsible for functional meaning.
+
+### Consistency over decoration
+
+The same colour role should always communicate the same thing throughout the system.
+
+Avoid using colour simply to make an interface feel more decorative.
+
+### Accessible by default
+
+Colour must never be the sole method of communication.
+
+Use labels, icons, typography, and spatial cues alongside colour.
+
+
+
+## 2. Colour model
+
+DiamondDS separates colour into three categories: **neutral**, **intent**, and **brand**.
+
+This separation helps ensure that visual structure, operational meaning, and organisational identity remain distinct.
+
+
+
+### Neutral
+
+Neutral colours define the structure of the interface.
+
+Use neutral colours for:
+
+- Page backgrounds
+- Surfaces
+- Containers
+- Dividers
+- Tables
+- Text
+- Data-heavy interfaces
+
+Neutral should account for the majority of visible colour in most applications.
+
+### Intent
+
+Intent colours communicate behaviour, status, and meaning.
+
+Intent colours answer: What does this mean?
+
+
+
+### Surface hierarchy
+
+```text
+Background
+ └─ Surface
+ └─ Surface container
+ └─ Surface container high
+ └─ Overlay
+ └─ Modal
+```
+
+### Surface hierarchy and elevation
+
+Surface roles and elevation work together but serve different purposes.
+
+
+
+
+
Concept
Purpose
Examples
+
+
+
+
+
Surface hierarchy
+
Defines content relationships and grouping
+
Background, Surface, Container, Overlay
+
+
+
Elevation
Defines visual prominence and separation
+
Cards, menus, dialogs, temporary layers
+
+
+
+
+A surface may use elevation, but elevation alone should not be used to communicate hierarchy.
+
+
+
+ Prefer surface hierarchy, spacing, and borders before increasing elevation.
+ Elevation should be used primarily for floating, temporary, or
+ high-attention content such as menus, popovers, and dialogs.
+
+
+
+## 5. Colour anatomy
+
+Each semantic colour role contains related tokens that support different levels of emphasis and interaction.
+
+
+
+
+
Part
+
Purpose
+
Typical usage
+
+
+
+
+
Main
+
Core semantic colour
+
Actions, status indicators, emphasis
+
+
+
Accent
+
Supporting highlight
+
Focus rings, highlights, supporting accents
+
+
+
Emphasis
+
Stronger emphasis
+
Hover, active, or stronger emphasis states
+
+
+
Container
+
Low-emphasis semantic surface
+
Chips, alerts, selected regions, grouped states
+
+
+
On Container
+
Foreground for container
+
Text and icons inside semantic containers
+
+
+
Solid
+
High-emphasis interactive surface
+
Contained buttons and strong interactive controls
+
+
+
On Solid
+
Foreground for solid
+
Text and icons inside solid controls
+
+
+
Contrast Text
+
Foreground for the main colour
+
Text and icons placed directly on the main colour
+
+
+
+
+### Container and solid patterns
+
+DiamondDS uses two primary semantic presentation patterns: **container** and **solid**.
+
+
+
+
+
Pattern
+
Emphasis
+
Purpose
+
Typical usage
+
+
+
+
+
Container
+
Low
+
Provides a semantic surface without dominating the interface
+
+Use **container** when meaning should be visible but quiet.
+
+Use **solid** when an action or state needs stronger emphasis.
+
+## 6. Interaction states
+
+Colour changes should support interaction without becoming the only indication of state.
+
+
+
+
+
State
+
Purpose
+
Guidance
+
+
+
+
+
Rest
+
Default appearance
+
Use the base semantic role for the component or surface.
+
+
+
Hover
+
Pointer interaction
+
Use a subtle change in surface, border, or emphasis.
+
+
+
Focus
+
Keyboard focus
+
Always use the focus ring. Do not rely only on colour changes.
+
+
+
Active
+
Pressed state
+
Use a stronger interaction treatment than hover.
+
+
+
Selected
+
Persistent selection
+
+ Use a clear selected treatment that remains visible after interaction.
+
+
+
+
Read-only
+
Viewable but not editable
+
+ Content remains selectable and readable. Users can focus, copy, and
+ inspect values, but cannot modify them.
+
+
+
+
Disabled
+
Unavailable interaction
+
+ Disabled styles always override hover, focus, active, and selected
+ states.
+
+
+
+
+
+### Read-only
+
+Read-only content is available for inspection but cannot be edited.
+
+Use read-only when users need access to information while preventing modification. This is common in scientific and operational workflows where values may be locked, system-generated, or controlled by permissions, but still need to be reviewed, verified, compared, copied, or referenced.
+
+
+
+ Prefer read-only over disabled whenever
+ users still need access to the underlying information. Disabled states
+ should primarily be used for unavailable actions and controls rather than
+ viewable data.
+
+
+
+Disabled content may be omitted from form submissions, skipped during keyboard navigation, unavailable to some automation and testing tools, or inaccessible to integrations and data extraction workflows. Read-only content remains part of the interface and remains available for inspection, copying, automation, and accessibility tooling.
+
+Use read-only when users need to:
+
+- Review values before making decisions.
+- Compare settings or configuration.
+- Copy text or data.
+- Reference system-generated information.
+- Access information that is currently locked for editing.
+
+Read-only content should remain:
+
+- Readable.
+- Clearly identifiable as non-editable.
+- Focusable where appropriate.
+- Selectable and copyable where appropriate.
+- Visually distinct from editable controls.
+
+Read-only content should not appear disabled.
+
+Disabled content communicates that a control is unavailable. Read-only content communicates that a value is available but cannot be changed.
+
+### Read-only vs disabled
+
+
+
+
+
Capability
+
Read-only
+
Disabled
+
+
+
+
+
Visible
+
✓
+
✓
+
+
+
Readable
+
✓
+
✓
+
+
+
Focusable
+
Usually
+
✕
+
+
+
Selectable
+
✓
+
Usually not
+
+
+
Copyable
+
✓
+
Usually not
+
+
+
Submitted with forms
+
Usually
+
Usually not
+
+
+
Available to automation and integrations
+
Usually
+
Not always
+
+
+
Editable
+
✕
+
✕
+
+
+
+
+### State priority
+
+When multiple states apply, use this priority order.
+
+```text
+Disabled
+ ↓
+Error
+ ↓
+Selected
+ ↓
+Active
+ ↓
+Hover
+ ↓
+Rest
+```
+
+Disabled and error states always win over other visual states.
+
+## 7. Scientific workflow guidance
+
+Scientific interfaces often contain:
+
+- Large tables
+- Live data
+- Monitoring views
+- Control panels
+- Acquisition screens
+- Alerts and operational feedback
+
+In these environments, colour must maintain a strong signal-to-noise ratio.
+
+### Do
+
+
+
+
✅ Do
+
+
Use neutral colours for most layout and structure.
+
Reserve semantic colours for meaningful changes in state.
+
Use warning and error colours only when attention or action is needed.
+
Ensure critical alerts remain visually distinct.
+
Allow data visualisation colours to remain distinct from UI colours.
+
+
+
+
+
❌ Don’t
+
+
Don’t use large blocks of semantic colour as decoration.
+
Don’t colour every data point, metric, or row.
+
Don’t use status colours for general layout structure.
+
Don’t create multiple competing status colours in the same view.
+
Don’t make visualisation colours compete with interface colours.
+
+
+
+
+## 8. Data visualisation guidance
+
+UI colours and visualisation colours serve different purposes.
+
+
+
+
+
Colour system
+
Purpose
+
Examples
+
+
+
+
+
UI colours
+
Communicate structure, actions, and status
+
Buttons, alerts, text, borders, surfaces
+
+
+
Visualisation colours
+
Communicate data categories, measurements, and trends
+
+Do not reuse UI intent colours as a general chart palette.
+
+Use visualisation colours for data and UI colours for interface meaning.
+
+## 9. Accessibility
+
+Colour plays an important role in accessibility but should not be relied upon as the sole means of communication.
+
+Important information should be communicated through a combination of colour, text, icons, labels, layout, and interaction patterns.
+
+### Colour accessibility principles
+
+- Do not communicate meaning through colour alone.
+- Ensure important states remain distinguishable in both light and dark modes.
+- Pair status colours with labels, icons, or supporting text.
+- Use semantic colour tokens rather than hardcoded values.
+- Test colour usage in realistic workflows and data-dense interfaces.
+
+
+ For contrast requirements, focus indicators, and broader accessibility
+ standards, refer to the Accessibility section.
+
+
+## 10. Token reference
+
+The token reference connects DiamondDS semantic colour roles to CSS variables and MUI palette roles.
+
+Use semantic tokens and MUI palette roles in components. Avoid hardcoded hex values.
+
+### Semantic intent and brand roles
+
+Intent and brand colours follow a shared semantic structure.
+
+
+
+
+
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
diff --git a/src/storybook/foundation/2. typography.mdx b/src/storybook/foundation/2. typography.mdx
new file mode 100644
index 0000000..0dae091
--- /dev/null
+++ b/src/storybook/foundation/2. typography.mdx
@@ -0,0 +1,518 @@
+import { Meta } from "@storybook/blocks";
+
+
+
+
+
+# Typography
+
+
+ Typography in Diamond DS should support readability, scanning, and technical
+ clarity. Interfaces are often used in dense scientific workflows, so type
+ should feel calm, consistent, and easy to parse.
+
+
+## Typefaces
+
+
+
+## Core principle
+
+Use typography to make information easier to understand, not more decorative.
+
+Scientific interfaces often contain dense data, status information, technical
+labels, long identifiers, and changing values. Typography should help users see
+what matters, compare values, and act with confidence.
+
+## Hierarchy
+
+Use a clear and repeatable hierarchy across products.
+
+- Use headings to structure the page.
+- Use body text for explanation and supporting content.
+- Use meta text for compact operational information and status.
+- Use labels for controls, fields, table headers, and short descriptors.
+- Use mono type for technical values where alignment or precision matters.
+
+Avoid creating one-off heading sizes or local typographic styles unless there is
+a reusable reason.
+
+Use heading levels in order where possible. Avoid jumping directly from h1 to h4 unless the surrounding structure justifies it.
+
+## Typography variants
+
+
+ Subtitle variants are intended for supporting headings and structured content.
+ Use body variants for prose and explanatory text.
+
+
+## Typography scale
+
+Diamond DS provides a shared typography scale that underpins all typography
+variants.
+
+
+
+
+
Token
+
Size
+
+
+
+
+
+ --ds-font-size-100
+
+
0.6875rem (11px)
+
+
+
+ --ds-font-size-200
+
+
0.75rem (12px)
+
+
+
+ --ds-font-size-300
+
+
0.875rem (14px)
+
+
+
+ --ds-font-size-400
+
+
1rem (16px)
+
+
+
+ --ds-font-size-500
+
+
1.125rem (18px)
+
+
+
+ --ds-font-size-600
+
+
1.25rem (20px)
+
+
+
+ --ds-font-size-700
+
+
1.75rem (28px)
+
+
+
+ --ds-font-size-800
+
+
2rem (32px)
+
+
+
+ --ds-font-size-900
+
+
2.125rem (34px)
+
+
+
+ --ds-font-size-1000
+
+
3rem (48px)
+
+
+
+ --ds-font-size-1100
+
+
4.5rem (72px)
+
+
+
+
+Typography variants should normally be used directly.
+
+Font size tokens are primarily intended for creating reusable components,
+defining typography variants, and establishing consistent scale across the
+design system.
+
+Avoid applying arbitrary font sizes when an existing typography variant already
+communicates the correct hierarchy and meaning.
+
+## Display and heading variants
+
+Use display variants for large, high-level moments such as landing pages,
+welcome screens, product introductions, and documentation hero areas.
+
+Use heading variants for application structure and content hierarchy.
+
+Display variants should be used sparingly and are not intended to replace the
+standard heading hierarchy within operational interfaces.
+
+
+
+ The current typography model uses dedicated display variants (
+ h1Display–h4Display) for display typography and
+ h1–h6 for application hierarchy.
+
+
+
+ As the design system evolves, h1 and/or h2 may
+ adopt the display typeface in some contexts. This decision is still under
+ review and may change based on application and public-facing usage patterns.
+
+
+
+## Choosing a typeface
+
+### Inter
+
+Inter is the default interface typeface.
+
+Use Inter for:
+
+- Navigation
+- Buttons
+- Forms
+- Tables
+- Dialogues
+- Cards
+- Body text
+- Labels
+- Status messages
+
+Inter should be the default choice unless there is a specific reason to use
+Outfit or IBM Plex Mono.
+
+### Outfit
+
+Outfit is used for display and high-level headings.
+
+Use Outfit sparingly for:
+
+- Product names
+- Major page titles
+- Welcome or landing areas
+- Documentation hero headings
+
+Do not use Outfit for dense application UI, tables, forms, or technical values.
+
+### IBM Plex Mono
+
+IBM Plex Mono is used for technical and aligned information.
+
+Use IBM Plex Mono for:
+
+- Beamline IDs
+- Sample IDs
+- Proposal IDs
+- Timestamps
+- Code
+- Logs
+- Console output
+- Numeric columns
+- Technical table values
+- Numeric values where alignment helps comparison
+- File paths
+- API-like values
+
+Do not use mono type for general UI text. It reduces readability when used too
+widely.
+
+## Technical values
+
+Technical values should be easy to scan, compare, and copy.
+
+Use mono type where users need to inspect precise values:
+
+```tsx
+
+ energy=12.4 keV · exposure=0.5 s · frames=100
+
+```
+
+For tables with mixed content, use mono only for the technical cells rather than
+the whole table.
+
+## Numbers and units
+
+Keep numbers and units readable.
+
+```text
+12.4 keV
+0.5 s
+180 ms
+1,024 frames
+```
+
+Prefer a space between number and unit unless the notation convention says
+otherwise.
+
+Avoid inconsistent formatting:
+
+```text
+12.4keV
+0.5sec
+180 milliseconds
+1024 Frames
+```
+
+## Overlines and grouping
+
+Overlines provide lightweight hierarchy and grouping without introducing a full
+heading.
+
+They are particularly useful in dense scientific interfaces where additional
+structure is needed without increasing visual weight.
+
+Use overlines to:
+
+- Group related controls
+- Separate sections within cards or panels
+- Label groups of settings
+- Introduce collections of information
+- Provide context above headings or values
+
+```tsx
+
+ Acquisition
+
+
+
+ Detector settings
+
+```
+
+Prefer overlines when a full heading would create unnecessary visual weight.
+
+## Utility text
+
+
+
+### Meta
+
+Use meta for compact operational information such as:
+
+- Status bars
+- Timestamps
+- Counts
+- Short technical metadata
+- Connection status
+- Acquisition state
+
+## Logs and console output
+
+Logs and console output should use mono type.
+
+```tsx
+
+ [14:30:15] Starting data acquisition pipeline [14:30:18] Detector initialised
+ successfully [14:30:22] Scan started — energy 12.4 keV, exposure 0.5 s
+
+```
+
+Use colour and status tokens carefully. Typography should not be the only way to
+communicate severity.
+
+## Do and don't
+
+
+
+
✅ Do
+
+
Keep hierarchy consistent across products.
+
Prefer short, clear labels.
+
Make numbers and technical values easy to scan.
+
Use mono type where alignment matters.
+
Use display variants sparingly for high-level moments.
+
Use meta for compact operational information.
+
Use overlines for lightweight grouping.
+
Keep dense UI text calm and readable.
+
+
+
+
+
❌ Don't
+
+
Don't create new type styles screen by screen.
+
Don't use decorative typography in operational interfaces.
+
Don't use display variants as the default heading style inside applications.
+
Don't use mono type for long paragraphs.
+
Don't rely on font weight alone to show status or severity.
+
Don't mix heading styles without a clear structure.
+
Don't use caption when the content is operational metadata.
+
Don't make technical values harder to copy or compare.
+
+
+
+
+## Light and dark behaviour
+
+Typography should remain readable in both light and dark modes.
+
+Use semantic foreground roles rather than raw colour values:
+
+```tsx
+
+ Primary text
+
+
+
+ Secondary text
+
+
+
+ Disabled text
+
+```
+
+Avoid hard-coded greys for text. They may pass in one mode and fail in another.
+
+## Accessibility
+
+Typography must support legibility, contrast, and predictable reading order.
+
+- Use sufficient contrast for text and icons.
+- Do not use colour alone to communicate meaning.
+- Keep line lengths comfortable for reading.
+- Avoid very small text in dense operational areas.
+- Preserve semantic headings where possible.
+
+
diff --git a/src/storybook/foundation/3. icons.mdx b/src/storybook/foundation/3. icons.mdx
new file mode 100644
index 0000000..eba8dd9
--- /dev/null
+++ b/src/storybook/foundation/3. icons.mdx
@@ -0,0 +1,415 @@
+import { Meta } from "@storybook/blocks";
+
+
+
+
+
+# Icons
+
+
+ Icons support recognition and scanning. They should reinforce meaning, not
+ replace clear language. Diamond DS uses Lucide as its primary icon family.
+
+
+## Overview
+
+Diamond DS uses **Lucide** as its primary icon family.
+
+Lucide icons are simple, line-based icons that support dense scientific
+interfaces without introducing unnecessary visual noise.
+
+Applications should use Lucide icons wherever possible.
+
+When creating bespoke icons, follow the same visual language:
+
+
+
Line-based rather than filled.
+
Consistent stroke weights.
+
Rounded line caps and joins.
+
Simple and recognisable shapes.
+
Minimal detail at small sizes.
+
+
+Avoid mixing multiple icon families within the same application.
+
+
+
+ Material Icons may remain in existing screens during the transition. For new
+ components, new patterns, and new application work, use Lucide or the
+ exported Diamond DS icon aliases.
+
+
+Icons should not be used purely as decoration.
+
+### Prefer labels over icons
+
+Where understanding is important, pair icons with text.
+
+```tsx
+}>Settings
+```
+
+Avoid relying on icons alone for unfamiliar, complex, or high-risk actions.
+
+## Consistency
+
+Use the same icon for the same concept across products.
+
+
+
+
+
Concept
+
Example icon
+
+
+
+
+
Add
+
Plus
+
+
+
Search
+
Search
+
+
+
Expand
+
ChevronDown
+
+
+
Settings
+
Settings
+
+
+
Delete
+
Trash2
+
+
+
Add
+
Plus
+
+
+
Download
+
Download
+
+
+
Upload
+
Upload
+
+
+
+
+Changing icon metaphors between applications increases cognitive load and reduces predictability.
+
+
+
+ When selecting or creating icons, follow the naming conventions used by the
+ underlying icon library to maintain consistency and discoverability.
+
+
+
+## Icon sizes
+
+Diamond DS defines five standard icon sizes.
+
+
+
+
+
Icon size
+
Size
+
Stroke weight
+
+
+
+
+
XS
+
16px
+
1.5px
+
+
+
SM
+
20px
+
1.75px
+
+
+
MD
+
24px
+
2px
+
+
+
LG
+
32px
+
2.25px
+
+
+
XL
+
40px
+
2.25px
+
+
+
+
+Use the smallest icon size that remains recognisable and readable.
+
+## Using icons
+
+Diamond DS provides a `LucideIcon` component that wraps SVG icons and applies
+consistent sizing, accessibility, and styling behaviour.
+
+Prefer using `LucideIcon` rather than rendering icon libraries directly.
+
+```tsx
+import { LucideIcon } from "@diamondlightsource/sci-react-ui;
+import { Search } from "lucide-react";
+
+
+```
+
+### Why use LucideIcon?
+
+
+
Consistent sizing.
Consistent stroke weights.
+
Theme integration.
Accessibility support.
+
Future flexibility if the underlying implementation changes.
+
+
+## Icons in buttons
+
+When using Diamond DS buttons, provide a Lucide icon and allow the button
+component to determine the appropriate icon size.
+
+```tsx
+}>Search
+```
+
+Do not manually size icons inside standard button components unless there is a
+specific reusable requirement.
+
+Button components automatically determine icon size.
+
+
+
+
+
Button size
+
Button height
+
Default icon size
+
+
+
+
+
xs
+
24px
+
XS (16px)
+
+
+
small
+
32px
+
SM (20px)
+
+
+
medium
+
36px
+
MD (24px)
+
+
+
large
+
40px
+
MD (24px)
+
+
+
+
+Do not manually resize icons inside standard button components.
+
+### Leading icons
+
+Use leading icons when the icon reinforces the primary action.
+
+```tsx
+}>Add
+```
+
+### Trailing icons
+
+Use trailing icons when the icon indicates progression, navigation, or expansion.
+
+```tsx
+}>Continue
+```
+
+## Icon-only buttons
+
+Use icon-only buttons when:
+
+
+
Space is limited.
+
The action is widely understood.
+
The icon remains clear without text.
+
+
+Every icon-only button must provide an accessible name.
+
+```tsx
+
+
+
+```
+
+Common examples include:
+
+
+
Search
+
Settings
+
Close
+
More actions
+
Notifications
+
+
+## Icons in menus
+
+Icons can improve scanning within menus containing multiple actions.
+
+```tsx
+
+```
+
+Use icons consistently throughout a menu.
+
+Avoid mixing icon and non-icon menu items without a clear reason.
+
+## Icons in navigation
+
+Icons may support navigation but should rarely replace labels in desktop scientific applications.
+
+Navigation labels should remain visible wherever space allows.
+
+Icons are most useful for:
+
+
+
Application launchers
+
Navigation rails
+
Collapsed side navigation
+
Toolbar actions
+
+
+## Status and feedback
+
+Icons can reinforce status messages but should not be the only indicator.
+
+
+
+
+
Status
+
Typical icon
+
+
+
+
+
Success
+
Circle Check Big
+
+
+
Information
+
Info
+
+
+
Warning
+
Triangle Alert
+
+
+
Error
+
Circle X
+
+
+
+
+Always combine icons with text and colour.
+
+## Accessibility
+
+### Decorative icons
+
+Hide decorative icons from assistive technologies.
+
+```tsx
+
+```
+
+### Interactive icons
+
+Provide a meaningful accessible name.
+
+```tsx
+
+
+
+```
+
+### Status icons
+
+Do not rely on icon shape or colour alone to communicate meaning.
+
+Always provide accompanying text.
+
+## Do and don't
+
+
+
+
✅ Do
+
+
Use Lucide icons consistently.
+
Pair icons with text where clarity matters.
+
Let components control icon sizing.
+
Use icons to improve scanning.
+
Follow Lucide conventions for bespoke icons.
+
+
+
+
+
❌ Don't
+
+
Mix multiple icon families.
+
Use icons purely as decoration.
+
Depend on icons alone for critical actions.
+
Resize button icons manually.
+
Use different icons for the same concept across products.
+
+
+
+
+## Scientific and operational interfaces
+
+In scientific applications, icons should support task completion rather than branding.
+
+Prefer clear text labels for:
+
+- Instrument controls
+- Acquisition actions
+- Safety-related actions
+- Experimental workflows
+- Administrative actions
+
+Icons work best as supporting cues alongside clear terminology.
+
+