From 053400a1b88f4502a726c07f6208d90c4b3e14ae Mon Sep 17 00:00:00 2001 From: Zohar Manor-Abel Date: Fri, 29 May 2026 11:55:59 +0100 Subject: [PATCH] Added guidance for input textfield as well as updated stories --- .../MUI/Inputs/TextField.stories.tsx | 171 +++++--- .../MUI/Inputs/TextFieldGuidance.mdx | 375 ++++++++++++++++++ 2 files changed, 493 insertions(+), 53 deletions(-) create mode 100644 src/components/MUI/Inputs/TextFieldGuidance.mdx diff --git a/src/components/MUI/Inputs/TextField.stories.tsx b/src/components/MUI/Inputs/TextField.stories.tsx index 32f1305..efda89a 100644 --- a/src/components/MUI/Inputs/TextField.stories.tsx +++ b/src/components/MUI/Inputs/TextField.stories.tsx @@ -12,9 +12,7 @@ const meta: Meta = { argTypes: { variant: { control: { type: "select" }, - options: ["outlined", "filled,", "standard"].map((s) => - s.replace(",", ""), - ), + options: ["outlined", "filled", "standard"], }, color: { control: { type: "select" }, @@ -42,8 +40,8 @@ const meta: Meta = { size: "medium", margin: "none", type: "text", - label: "Your name", - placeholder: "Type here…", + label: "Sample name", + placeholder: "Enter sample name", helperText: "", error: false, required: false, @@ -64,56 +62,98 @@ export const Basic: Story = { export const Variants: Story = { render: (args) => ( - - - + + + ), - args: { color: "primary", helperText: "" }, + args: { color: "primary" }, }; -export const SizesAndColors: Story = { - render: (args) => ( - - - - - - - - - +export const DefaultInput: Story = { + name: "Default input", + render: () => ( + + + + + ), +}; + +export const LiveInstrumentInput: Story = { + name: "Live instrument input", + render: () => ( + + + ), - args: { variant: "outlined", helperText: "" }, }; export const States: Story = { render: (args) => ( - - + + + + + + + + + ), - args: { variant: "outlined", color: "primary" }, + args: { + variant: "outlined", + color: "primary", + }, +}; + +export const Validation: Story = { + render: () => ( + + + + + ), }; export const Multiline: Story = { args: { multiline: true, rows: 4, - label: "Message", - placeholder: "Write a few lines…", + label: "Notes", + placeholder: "Add notes for this setup…", + helperText: + "Use multiline fields for comments, notes, or longer descriptions.", }, render: (args) => , }; export const InputTypes: Story = { render: (args) => ( - + - + ), args: { variant: "outlined", helperText: "" }, diff --git a/src/components/MUI/Inputs/TextFieldGuidance.mdx b/src/components/MUI/Inputs/TextFieldGuidance.mdx new file mode 100644 index 0000000..09ccabb --- /dev/null +++ b/src/components/MUI/Inputs/TextFieldGuidance.mdx @@ -0,0 +1,375 @@ +import { Meta, Canvas } from "@storybook/blocks"; +import * as TextFieldStories from "./TextField.stories"; + + + + + +
+ +# Input guidance + +

+ Inputs capture and edit data. In DiamondDS, input styles communicate the + context and consequences of an action, not simply visual preference. +

+ +
+ Choose the input style based on context. + Outlined inputs are the default for forms, configuration, setup, and planning. + Filled inputs are reserved for direct interaction with live systems, + instruments, or time-sensitive operations. +
+ +

+ These guidance should be applied for select fields as well +

+ + + +## Overview + +

+ Input fields are used throughout acquisition, configuration, analysis, and + operational workflows. Different input variants help communicate whether a + value is being prepared, configured, or directly controlling equipment. +

+ +

+ Use the least visual emphasis necessary while still providing clear feedback + and confidence. +

+ +## Use inputs when + +
+
+

✅ Do

+
    +
  • Use outlined inputs by default.
    • +
  • Use filled inputs when interacting with live equipment.
    • +
  • Keep variants consistent within a workflow.
    • +
  • Provide labels and helper text.
    • +
  • Validate after users complete input.
    • +
+
+ +
+

❌ Don’t

+
    +
  • Don’t mix variants without a clear reason.
    • +
  • Don’t use filled inputs purely for decoration.
    • +
  • Don’t show validation errors while users are typing.
    • +
  • Don’t rely on placeholder text as a label.
    • +
  • Don’t use colour alone to communicate status.
    • +
+
+
+ +## Input hierarchy + + + + + + + + + + + + + + + + + + + + + + + + + + +
VariantUse forGuidance
OutlinedGeneral forms, configuration, setup, planning, metadata entryDefault choice
Filled + Live equipment control, operational adjustments, values with immediate + effect + Use deliberately
StandardInline or compact layoutsRarely used
+ +## Outlined inputs + +

Outlined inputs are the default input style in DiamondDS.

+ +

+ Use them when users are preparing values, configuring experiments, entering + metadata, defining scans, editing parameters, or making changes that are not + immediately applied to equipment. +

+ +
    +
  • Best for acquisition setup and planning.
    • +
  • Best for configuration screens.
    • +
  • Best for structured forms.
    • +
  • Supports dense layouts and scanning.
    • +
+ + + +## Filled inputs + +

Filled inputs indicate a stronger operational context.

+ +

+ Use them when a value directly affects a running system, instrument, motor, + detector, or operational process. +

+ +
    +
  • Live motor movement.
    • +
  • Direct instrument control.
    • +
  • Operational adjustments.
    • +
  • Situations where changes have immediate consequences.
    • +
+ +

Filled inputs should be used sparingly so their meaning remains clear.

+ + + +## Future direction + +

+ DiamondDS may introduce additional filled variants for operational workflows. +

+ +

+ One possibility is a subtle intent-based filled style using semantic container + colours, allowing live controls to stand out without requiring strong visual + emphasis. This pattern is still under evaluation and should not be considered + part of the current guidance. +

+ +## Validation + +

Validation should support users, not interrupt them.

+ +
    +
  • Validate on blur or submit.
    • +
  • Avoid showing errors while users are typing.
    • +
  • Use helper text to prevent errors before they occur.
    • +
  • Keep messages specific and actionable.
    • +
+ +## Input states + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
StatePurposeUse when
DefaultReady for input.The field is available for editing.
HoverIndicates pointer interaction.The user is pointing at the field.
FocusIndicates keyboard or active input.The field is currently being edited.
Read-onlyDisplays a value that cannot be edited. + The value should remain visible, selectable, and copyable, but editing + is not permitted. +
ErrorIndicates validation or input problems.The value requires attention before the workflow can continue.
DisabledIndicates interaction is unavailable.The field cannot currently be interacted with or modified.
+ +

+ Prefer read-only over disabled when + displaying useful information. Read-only fields remain legible and can still + be selected or copied, while disabled fields indicate that interaction is + unavailable. +

+ +

+ Disabled and error states should remain clearly visible and should not be + overridden by hover or focus styling. +

+ + + +## Token guidance + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NeedPreferAvoid
Input border + border.emphasis, border.strong + Hardcoded greys
Input text + text.primary + Custom text colours
Error state + error + Custom red values
Focus + theme.focusRing + Browser default focus only
+ +## Accessibility + +
    +
  • Always provide a visible label.
    • +
  • Use helper text for guidance and validation.
    • +
  • Ensure sufficient text and border contrast.
    • +
  • Provide clear focus indicators.
    • +
  • Do not rely solely on colour to communicate validation.
    • +
+ +## Related components + +
    +
  • + TextField — general text input. +
    • +
  • + Autocomplete — searchable selection. +
    • +
  • + Select — predefined option selection. +
    • +
  • + Checkbox — independent choices. +
    • +
  • + Radio — single selection from a group. +
    • +
  • + Switch — immediate on/off state. +
    • +
+ +