Machine UI

Machine UI is Vention's component library for building applications and Human-Machine Interfaces (HMIs). This is the same library that Vention uses internally to build our own applications, now available for you to build custom applications for your Vention machines.

Each component's props and their types are in the package's type declarations, which your editor and tsc read. Look there for props; this README covers only defaults, behaviour and composition that the types can't show.

🚀 Installation

Install Machine UI via npm:

npm install @vention/machine-ui

For the latest version and release notes, visit the npm package page.

Setup

Machine UI builds on MUI v5. The app needs the peer dependencies react and react-dom 17 and @mui/material 5, plus @emotion/react and @emotion/styled, which MUI needs. @tabler/icons-react, tss-react and react-draggable come with the package.

Wrap the app in MUI's ThemeProvider with one of the two themes:

• machineUiTheme: the desktop theme. It sets the palette, the spacing scale (theme.spacing(n) reads [0, 4, 8, 12, 16, 24, 28, 32, 40, 48, 56, 64, 80, 96, 128] px) and the typography variants.
• machineUiHmiTheme: the touch HMI theme. It is machineUiTheme with thicker icon strokes (1.5px instead of 1.01px). Palette, spacing and typography are the same, so touch sizing comes from each component's size prop, not from the theme (see Components).

Both themes add typography variants you can pass to MUI's Typography: heading36Bold, heading24SemiBold, heading24Medium, heading18SemiBold, heading16SemiBold, paragraph18Medium, paragraph18Regular, paragraph16Medium, paragraph16Regular, paragraph14Regular, code16Reg, code14Reg, code12Reg, uiText18SemiBold, uiText18Medium, uiText18Regular, uiText14SemiBold, uiText14Medium, uiText14Regular, uiText12SemiBold, uiText12Medium, uiText12Regular, uiTableNumbers14Reg, uiTableNumbers12Reg, and for HMIs hmiText20Regular, hmiText20SemiBold, hmiText22Regular, hmiText22Medium, hmiText22SemiBold, hmiText28SemiBold, hmiText32SemiBold.

COLORS holds the raw palette: COLORS.slate, COLORS.blue, COLORS.cyan, COLORS.green, COLORS.amber and COLORS.red, each keyed by shade (50, 100 to 900, 950), for example COLORS.slate[800]. Use it where a component takes a color string, such as VentionStatusDot's color.

Importing anything from the package applies its global styles (box-sizing: border-box on every element), so there is no CssBaseline to add. The themes use the Inter and Roboto Mono fonts, which the app loads itself, for example from Google Fonts in index.html:

<link href="https://fonts.googleapis.com/css2?family=Inter:[email protected]&family=Roboto+Mono&display=swap" rel="stylesheet" />

import { ThemeProvider, Typography } from "@mui/material"
import { COLORS, VentionButton, VentionStatusIndicator, machineUiHmiTheme } from "@vention/machine-ui"

export function App() {
  return (
    <ThemeProvider theme={machineUiHmiTheme}>
      <div style={{ backgroundColor: COLORS.slate[50], padding: 24 }}>
        <Typography variant="hmiText28SemiBold">Cell 1</Typography>
        <VentionStatusIndicator label="Running" dotColor={COLORS.green[500]} size="xx-large" />
        <VentionButton size="xx-large" variant="filled-brand" onClick={() => console.log("start")}>
          Start cycle
        </VentionButton>
      </div>
    </ThemeProvider>
  )
}

Components

Every component is a named export of @vention/machine-ui. Most components take a size prop; the HMI sizes are x-large and xx-large.

Buttons, text inputs, selects and comboboxes share one height per size: x-small 16px, small 24px, medium 32px, large 40px, x-large 56px, xx-large 80px. A touch target should be at least 44px, so on a touch HMI use x-large or xx-large. At xx-large, input and select labels switch to hmiText20*; the value text and button labels keep their regular typography.

Components built on an MUI component (noted as "built on MUI X") accept that component's props too, so standard props such as onClick, value, checked and onChange work as they do in MUI.

Actions

• VentionButton: the standard button. size defaults to "small" (24px), too small for touch, so use size="x-large" or "xx-large" on touch screens. variant defaults to "filled-brand". The label is children, else labelText, and reads "Button" when both are missing. type defaults to "button", so pass type="submit" to submit a form. Built on MUI Button.
• VentionIconButton: a square button that shows only an icon, passed as children. It takes the same variant and size as VentionButton, with the same "small" default. Built on MUI IconButton.
• VentionDropdownButton: a button that opens a menu of its children. Pass a VentionMenu wrapping VentionMenu.Item elements as children; the button renders children as-is, so bare items get no menu surface.
• VentionLink: an inline text link. external defaults to true and shows an external-link icon, so pass external={false} for an in-app link. Without labelText it reads "Button".

Inputs

• VentionTextInput: a text field built on MUI TextField. Use state ("error", "warning", "success", "disabled") instead of disabled and error. leftItemText and rightItemText show fixed text inside the field, such as a unit, and maxCharacters shows a character count.
• VentionSuggestionsInput: a VentionTextInput that shows a list of suggestions as the user types. Pass either value (controlled) or defaultValue, not both.
• VentionSelect: a dropdown select. onChange receives the event, so read event.target.value. Each entry in menuItems is a VentionSelectMenuItem or a VentionSelectDivider ({ type: "divider" }). With isMultiple, value is an array. Built on MUI Select.
• VentionSelectSkeleton: the loading placeholder for VentionSelect, also available as VentionSelect.Skeleton.
• VentionCombobox: a searchable single-choice dropdown. groups are matched to options by each option's group.
• VentionTagsInput: a field that collects a list of text tags.
• VentionCheckbox: a checkbox with an optional label, built on MUI FormControlLabel, so checked and onChange work as there. Its size prop is checkboxSize.
• VentionRadio: a radio button, used inside MUI's RadioGroup. Its size prop is radioSize. Built on MUI Radio.
• VentionRadioTile: a large selectable tile with a radio button, used inside MUI's RadioGroup, good for touch choices. Built on MUI FormControlLabel.
• VentionSwitch: an on/off toggle. checked is a string ("on", "off", "mixed" or "loading"), not a boolean, and onChange receives "on" or "off".
• VentionSlider: a range slider built on MUI Slider. largeThumb gives it a bigger handle, for touch.
• VentionCounter: a small pill that shows a number, such as a count of pending items.
• VentionStepper: a value with minus and plus buttons on each side. value is displayed as is. Put onClick and disabled for each button in minusButtonProps and plusButtonProps.
• VentionInputGroupLabel: a label placed beside a group of inputs.
• VentionUploadFile: one row in a list of uploaded files, with its status. Set state to "indeterminate" while uploading.
• VentionDropZone: an area to drop or pick files. onFilesSelect(files) returns an array of error messages, empty when every file is valid.

Feedback

• VentionAlert: an alert box with optional actions. A button or link shows when its text is set, so pair each text with its click handler, such as primaryButtonText with onPrimaryButtonClick. Use size="xx-large" on touch HMIs.
• VentionBanner: a full-width colored strip for a machine or page state.
• VentionCallout: an inline highlighted note with optional actions.
• VentionProgressBar: a horizontal progress bar. value runs from 0 to 100.
• VentionSpinner: a circular progress indicator. With type="progress" it shows value, from 0 to 100.
• VentionSkeleton: a loading placeholder. variant ("text", "rounded" or "circular") decides which other props it needs.
• VentionStatusDot: a small colored dot. dotColor takes the same colors as VentionBadge: "red", "blue", "green", "yellow" or "slate". The older color, which takes any CSS color, is deprecated.
• VentionStatusIndicator: a status dot with a text label, such as a machine state. Use size="xx-large" on touch HMIs.
• VentionBadge: a small labeled tag. Pair the color with a text label, since color alone is hard to read on a shop floor.
• VentionTooltip: a tooltip on hover or focus, built on MUI Tooltip. placement defaults to "top-end". Hover does not exist on touch screens, so don't put information an operator needs only in a tooltip.

Overlays

• VentionModal: a dialog with a title, body and up to two buttons. type sets the icon. backDropClickClosable defaults to true. width overrides the width that modalSize sets. Set isTouchDevice on touch HMIs for larger padding, icons, text and buttons.
• VentionModalBase: the empty modal frame for custom content. Set isTouchDevice on touch HMIs.
• VentionModalBanner: a colored banner to place at the top of a modal.
• VentionDrawer: a panel that slides in from a screen edge, built on MUI Drawer. When onDrawerHandleClick is set, the drawer stays mounted and shows a handle that calls it to toggle.
• VentionPopover: a floating card with an arrow, pointing at an element or a position. Place it with anchorElement (an HTMLElement) or pos2D ({ top, left } in px). buttons takes up to three VentionButton props objects.
• VentionMenu: a menu list that closes when the user clicks outside it. showMenu and closeMenuOnClick default to true. Fill it with VentionMenu.Item (subMenuItems makes a nested menu), VentionMenu.Header and VentionMenu.Divider.
• VentionPositionedComponent: places its children at a fixed position that stays inside the viewport. Pass either anchorRect (a DOMRect, such as from getBoundingClientRect()) or position ({ top, left }), not both.

Navigation and layout

• VentionTabs: a row of tabs. value is the index of the selected tab, and onChange(event, index) receives the new index.
• VentionSteps: a vertical list of steps for a guided procedure. Use size="xx-large" on touch HMIs; "small" always shows dots.
• VentionSidebarItem: a profile entry in a sidebar.
• VentionTreeItem: one row of a tree, with nested VentionTreeItem children.
• VentionDraggable: a floating panel the user can drag around the screen. tabLocation shows a drag handle on that side; without it the whole panel drags.

Identity

• VentionAvatar: a round user picture or initials.
• VentionPersonCard: an avatar with a name and a description line.
• VentionPersonCardSkeleton: the loading placeholder for VentionPersonCard, also available as VentionPersonCard.Skeleton.
• VentionIcon: an icon from the Vention icon set. type is an icon name such as "player-play" or "status-warning-hmi". size is in px and defaults to 24. Icon strokes follow the theme, so they are thicker under machineUiHmiTheme. For other icons, @tabler/icons-react is installed with the package.

A small touch panel that uses several of these:

import { useState } from "react"
import { VentionModal, VentionSelect, VentionSwitch } from "@vention/machine-ui"

export function RecipePanel() {
  const [recipe, setRecipe] = useState<string>("small-box")
  const [vacuum, setVacuum] = useState<"on" | "off">("off")
  const [pendingRecipe, setPendingRecipe] = useState<string | null>(null)

  return (
    <>
      <VentionSelect
        size="xx-large"
        variant="outlined"
        labelText="Recipe"
        value={recipe}
        onChange={event => setPendingRecipe(String(event.target.value))}
        menuItems={[
          { value: "small-box", displayText: "Small box" },
          { value: "large-box", displayText: "Large box" },
          { type: "divider" },
          { value: "custom", displayText: "Custom", isDisabled: true },
        ]}
      />
      <VentionSwitch size="xx-large" labelText="Vacuum" checked={vacuum} onChange={setVacuum} />
      <VentionModal
        isOpen={pendingRecipe !== null}
        onClose={() => setPendingRecipe(null)}
        isTouchDevice
        type="warning"
        titleText="Change recipe?"
        body="The current cycle will stop."
        primaryButton={{
          text: "Change",
          onClick: () => {
            if (pendingRecipe !== null) setRecipe(pendingRecipe)
            setPendingRecipe(null)
          },
        }}
        secondaryButton={{ text: "Cancel", onClick: () => setPendingRecipe(null) }}
      />
    </>
  )
}

Storybook

The Storybook is the visual reference: it renders every component in each of its variants and sizes, with interactive controls, plus design guidelines for color, typography and HMIs.

https://assets.vention.com/machine-ui-storybook/

📋 Versioning Policy

Starting with version 1.0.0, Machine UI follows strict semantic versioning:

• Major versions (e.g., 1.x.x → 2.x.x): Breaking changes to component contracts, APIs, or behavior
• Minor versions (e.g., 1.1.x → 1.2.x): New features with backward compatibility
• Patch versions (e.g., 1.1.1 → 1.1.2): Bug fixes and internal improvements

Any breaking change, no matter how small, will require a major version bump. This ensures you can confidently upgrade patch and minor versions without unexpected breaking changes.

🏭 Building HMIs

Machine UI components work exceptionally well for industrial HMI applications. For guidelines on building touch-screen interfaces optimized for industrial environments, see our documentation on:

• Touch target sizing and spacing
• Readability at distance
• Color contrast requirements
• Simplified interactions for gloved operation

🛠️ Tech Stack

• React: UI framework
• TypeScript: Type safety
• Material-UI (MUI v5): Base component library
• TSS: Styling solution

📄 License

This library is provided for use with Vention machines and applications.