Operational UI

Building blocks for effective operational interfaces

Operational UI is an opinionated set of building blocks designed to best support user interfaces used for operational decision-making.

This is a monorepo consisting of the following packages.

1. Components are the smallest and simplest building blocks, implemented as presentational, heavily controlled React components. Buttons, input fields, modals, date pickers, and the like.
2. Blocks hold more state, more side effects, more opinions. They are our work-in-progress selection of widgets that worked well with client projects and which seemed like a good enough abstraction for a library.
3. Visualizations are full-featured d3 apps,
4. The theme package exports a plain object you can use to customize the designs of components and visualizations.
5. Utils contain helper methods for color manipulation, creating specific higher-order React components, and d3 helpers.
6. Showcase is the documentation website for the modules.

Usage

Here is the minimal setup work required to get going with Operational UI:

import React from "react"
import { render } from "react-dom"
import { ThemeProvider, Button, operationalTheme } from "@operational/components"

const MyInterface = () => (
  // Theme provider is mandatory
  <ThemeProvider theme={operationalTheme}>
    <Button onClick={() => {alert("Hello!")}}>Say hello!</Button>
  </ThemeProvider>
)

render(<MyInterface />, document.querySelector("#app"))

Note that wrapping your application inside a ThemeProvider with an operationalTheme-like theme object is mandatory for the components to render properly. This ensures we have an transparent, explicit set of styling defaults you can edit directly in case you want the UI to look different in a way that doesn't break consistency.

Working on Operational UI

After you install dependencies, simply run npm run dev or yarn dev inside the components or visualizations packages. This spins up a dev server you can use to test packages, by editing the entry point at ./packages/{components,visualizations}/scripts/dev-server/site.tsx.

To run the showcase, simply run npm run start or yarn start from root.

To make sure your code is ready for Travis and your reviewers, run npm run ci:local or yarn ci:local from the root of the project.

Generators

To create a new component, simply run ./scripts/create-component.sh ComponentName. This will generate all the boilerplate, files like ComponentName.tsx and ComponentName.test.tsx, and points to a few remaining manual wiring steps to get your component, its tests and its showcase page in place. The boilerplate also tries to guide towards consistent practices around code style, state management and styling. Please ask if anything is unclear.

More generators coming soon..

Contributing

We look forward to your contribution, and we would like to assure you that we value all thoughts, feedback and PR contribution. Simply open an issue or PR to open up a discussion.

Operational UI adheres to the Berlin Code of Conduct.

Core Team

Peter Szerzo General Codebase Handyperson

Imogen Mason Visualizations Lead

Tejas Kumar The Original Creator

Michael Franzkowiak Contributor

Andrés García Contributor

Made with ❤️ and 🌵 at Contiamo.