Design system


Consuming components

All components are available as named exports:

import React from "react";
import { Link } from "@orchest/design-system";

const SomePage = () => (
    <Link href="/link-to-another-page" />

Creating custom components

The design system houses components that we’ll need to use everywhere, not the a place for all of our components.

For one-off styles or project-specific use-cases, the design system exports two options: css and styled.

Both offer strongly-typed access to our CSS-variable-driven design tokens (e.g. $colors$primary), and the ability to use Stitches’ powerful variant system:

import { css, styled } from "@orchest/design-system";

// with the `styled` API
const CustomStyledComponent = styled("div", { color: "$primary" });

// with the `css` API
const customClassName = css({ color: "$primary" });

const CustomClassNameComponent = () => (
  <div className={customClassName()}>


For fast local-development, the sandbox offers a hot-reloading environment to build and test our components.

To get started, run:

pnpm run sandbox

Style guide


  • TypeScript

    • All new .js files should have // @ts-check enabled.

  • Component design

    • Don’t use class components

    • Do use functional components

  • Sharing state and logic

Project-specific Details



When sharing global logic/state, make the most of the useOrchest hook (See #214).

const {
  // Globally-accessed state
  // Actions to modify the globally-accessed state
  // Helpers to filter/find specific areas of the state (e.g. a specific session)
} = useOrchest();

Under-the-hood, useOrchest uses React.useReducer() to handle state.

It can be consumed in a functional component like so:

// @ts-check
import React from "react";
import { useOrchest } from "@/hooks/orchest";

const ExampleFC = () => {
  const { state, dispatch } = useOrchest();

  return (
    // <your-component>

In sessions-dependent views, the additional SessionsConsumer should wrap your component. This will trigger fetching and polling for updates via SWR.

// @ts-check
import React from "react";
import { useOrchest, SessionsConsumer } from "@/hooks/orchest";

const SessionsExampleFC = () => {
  const { state, dispatch } = useOrchest();

  return (
    // <SessionsConsumer>{/* <your-component> */}</SessionsConsumer>;

Ongoing migrations

We can’t spend a lot of time refactoring, but we can implement changes incrementally. When contributing to the front-end, please keep in mind the following ongoing migrations:


  • TypeScript

    • All .js files using // @ts-check

    • All .js files moved to .ts

  • Class components → Functional components