+
+# 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.
+
+
+
+# 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
+
+
+
+
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.
+
+
+
+ The `LucideIcon` wrapper is still in development. Until it ships, import
+ icons directly from `lucide-react` and size them by hand using the sizes and
+ stroke weights above.
+
+
+
+{/*
+Hidden pending real icon component usage (LucideIcon, Button/IconButton icon
+props, menu icon patterns) landing in the DS. Re-enable once that work ships;
+the surrounding sections describe the intended shape of this guidance.
+
+## 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
+
+ CircleCheckBig
+
+
+
+
Information
+
+ Info
+
+
+
+
Warning
+
+ TriangleAlert
+
+
+
+
Error
+
+ CircleX
+
+
+
+
+
+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.
+
+