From e4c92122bcef3f9b82a725721bdda783fa38ba25 Mon Sep 17 00:00:00 2001 From: Zohar Manor-Abel Date: Tue, 16 Jun 2026 16:22:53 +0100 Subject: [PATCH 1/2] Adding Typography and Icons docs to Foundation Added: 2. typography 3. Icons + - Added icons pack to show icons - Updated typography to align with #222 - Icons is standalone --- package.json | 1 + pnpm-lock.yaml | 12 + src/storybook/foundation/2. typography.mdx | 518 +++++++++++++++++++++ src/storybook/foundation/3. icons.mdx | 466 ++++++++++++++++++ 4 files changed, 997 insertions(+) create mode 100644 src/storybook/foundation/2. typography.mdx create mode 100644 src/storybook/foundation/3. icons.mdx diff --git a/package.json b/package.json index 0cc20ef0..9b56594f 100644 --- a/package.json +++ b/package.json @@ -125,6 +125,7 @@ "gh-pages": "^6.2.0", "jsdom": "^29.1.1", "keycloak-js": "^26.2.1", + "lucide-react": "^1.26.0", "react": "^18.3.1", "react-dom": "^18.3.1", "react-router-dom": "^7.12.0", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 3cc5db37..eb1ae02a 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -195,6 +195,9 @@ importers: jsdom: specifier: ^29.1.1 version: 29.1.1 + lucide-react: + specifier: ^1.26.0 + version: 1.26.0(react@18.3.1) react: specifier: ^18.3.1 version: 18.3.1 @@ -3678,6 +3681,11 @@ packages: lru-cache@5.1.1: resolution: {integrity: sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w==} + lucide-react@1.26.0: + resolution: {integrity: sha512-raglYVR2+VkMfJL158krjVmE+rV5ST2lzA/KQm1FRSjMHT4MnWaegHxoVEpmc2So3nOEhp9oGejJwAPX8MoAjg==} + peerDependencies: + react: ^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0 + lunr@2.3.9: resolution: {integrity: sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow==} @@ -8853,6 +8861,10 @@ snapshots: dependencies: yallist: 3.1.1 + lucide-react@1.26.0(react@18.3.1): + dependencies: + react: 18.3.1 + lunr@2.3.9: {} lz-string@1.5.0: {} diff --git a/src/storybook/foundation/2. typography.mdx b/src/storybook/foundation/2. typography.mdx new file mode 100644 index 00000000..92aaf486 --- /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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TypefaceTokenMUI rolesPurposeTypical usage
Inter + --ds-font-family-default + + body1, body2, subtitle1, + subtitle2, caption,meta,{" "} + button + Default interface typefaceUI text, controls, tables, navigation, forms
Outfit + --ds-font-family-display + + h1Display, h2Display,h3Display,{" "} + h4Display + Display and high-level headingsProduct headings, landing areas, documentation hero areas
IBM Plex Mono + --ds-font-family-mono + + mono1, mono2,mono3 + Technical and aligned contentIDs, timestamps, code, logs, numeric values, instrument output
+ +## 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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
GroupVariantsUse for
Display + h1Display, h2Display, h3Display,{" "} + h4Display + Public-facing pages, landing areas, documentation hero sections
Headings + h1–h6 + Application and document structure
Body + lead, body1, body2,{" "} + subtitle1, subtitle2 + Readable interface text and supporting content
Utility + caption, meta, overline,{" "} + overlineSmall + + Supporting text, operational metadata, grouping labels, status bars and + compact section labels +
Mono + mono1, mono2, mono3 + Logs, console output, IDs, paths, timestamps, technical values
+ +

+ 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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TokenSize
+ --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 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
VariantPurposeTypical usage
+ caption + Small explanatory or supporting textHelper text, figure captions, secondary descriptions
+ meta + Small operational informationStatus bars, timestamps, counts, short technical metadata
+ overline + Grouping and categorisationSection labels, grouped controls, settings groups, card sections
+ overlineSmall + Compact grouping and dense labellingDense panels, compact cards, highly constrained layouts
+ +### 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 00000000..60b62cdd --- /dev/null +++ b/src/storybook/foundation/3. icons.mdx @@ -0,0 +1,466 @@ +import { Meta } from "@storybook/blocks"; +import { + Plus, + Search, + ChevronDown, + Settings, + Trash2, + Download, + Upload, + CircleCheckBig, + Info, + TriangleAlert, + CircleX, +} from "lucide-react"; + +export const iconLabelProps = { + size: 20, + strokeWidth: 1.75, + style: { verticalAlign: "middle", marginRight: "0.5rem" }, +}; + + + +
+ +# 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: + + + +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. +

+
+ +## Choosing icons + +Icons should communicate familiar concepts quickly. + +Good uses include: + + + +Icons should not be used purely as decoration. + +### Prefer labels over icons + +Where understanding is important, pair icons with text. + +```tsx + +``` + +Avoid relying on icons alone for unfamiliar, complex, or high-risk actions. + +## Consistency + +Use the same icon for the same concept across products. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ConceptExample 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 sizeSizeStroke weight
XS16px1.5px
SM20px1.75px
MD24px2px
LG32px2.25px
XL40px2.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 + +``` + +Do not manually size icons inside standard button components unless there is a +specific reusable requirement. + +Button components automatically determine icon size. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Button sizeButton heightDefault icon size
xs24pxXS (16px)
small32pxSM (20px)
medium36pxMD (24px)
large40pxMD (24px)
+ +Do not manually resize icons inside standard button components. + +### Leading icons + +Use leading icons when the icon reinforces the primary action. + +```tsx + +``` + +### Trailing icons + +Use trailing icons when the icon indicates progression, navigation, or expansion. + +```tsx + +``` + +## 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 + + + + + + Settings + +``` + +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. + + + + + + + + + + + + + + + + + + + + + + + + + + +
StatusTypical 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 +
From d453d886332321886c3505877b6e9663b53d08c0 Mon Sep 17 00:00:00 2001 From: Zohar Manor-Abel Date: Thu, 6 Aug 2026 15:00:15 +0100 Subject: [PATCH 2/2] Updated wording --- src/storybook/foundation/2. typography.mdx | 35 +++++++++++++++++----- src/storybook/foundation/3. icons.mdx | 8 ++--- 2 files changed, 32 insertions(+), 11 deletions(-) diff --git a/src/storybook/foundation/2. typography.mdx b/src/storybook/foundation/2. typography.mdx index 92aaf486..b368af97 100644 --- a/src/storybook/foundation/2. typography.mdx +++ b/src/storybook/foundation/2. typography.mdx @@ -7,9 +7,9 @@ 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. + Typography in Diamond DS should support readability and technical clarity. + Interfaces are often used in dense scientific workflows, so type should feel + consistent and easy to parse. ## Typefaces @@ -264,7 +264,14 @@ standard heading hierarchy within operational interfaces. ## Choosing a typeface -

Inter

+

+ Inter +

Inter is the default interface typeface. @@ -283,7 +290,14 @@ Use Inter for: Inter should be the default choice unless there is a specific reason to use Outfit or IBM Plex Mono. -

Outfit

+

+ Outfit +

Outfit is used for display and high-level headings. @@ -296,7 +310,14 @@ Use Outfit sparingly for: Do not use Outfit for dense application UI, tables, forms, or technical values. -

IBM Plex Mono

+

+ IBM Plex Mono +

IBM Plex Mono is used for technical and aligned information. @@ -464,7 +485,7 @@ communicate severity.
  • 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.
    • +
  • Keep dense UI text legible and readable.
    • diff --git a/src/storybook/foundation/3. icons.mdx b/src/storybook/foundation/3. icons.mdx index 60b62cdd..a7858766 100644 --- a/src/storybook/foundation/3. icons.mdx +++ b/src/storybook/foundation/3. icons.mdx @@ -26,7 +26,7 @@ export const iconLabelProps = { # Icons - Icons support recognition and scanning. They should reinforce meaning, not + Icons support visuaul recognition. They should reinforce meaning, not replace clear language. Diamond DS uses Lucide as its primary icon family. @@ -53,7 +53,7 @@ Avoid mixing multiple icon families within the same application.

    - Material Icons may remain in existing screens during the transition. For new + **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.

    @@ -324,7 +324,7 @@ Common examples include: ## Icons in menus -Icons can improve scanning within menus containing multiple actions. +Icons can improve visual recognition within menus containing multiple actions. ```tsx @@ -432,7 +432,7 @@ Always provide accompanying text.
  • Use Lucide icons consistently.
  • Pair icons with text where clarity matters.
  • Let components control icon sizing.
    • -
  • Use icons to improve scanning.
    • +
  • Use icons to improve visual recognition.
  • Follow Lucide conventions for bespoke icons.