Tutorial: Build an EBRAINS Dashboard with the Design System

In this tutorial you turn the hello-ebrains app from the previous tutorials into a complete, on-brand dashboard: the home page of a Workflows app where researchers run and monitor CWL pipelines. You lay it out with the design system’s layout primitives and build it from ready components, with no custom CSS for layout, colour or type.

Time to complete: 45–60 minutes

What you’ll learn: how to structure a full EBRAINS page (shell, hero, grid, content, tabs, dialogs), which component to pick for which job, and how to pass data and handle events with the React wrapper.

What You’ll Build

By the end of this tutorial, you’ll have:

  • The EBRAINS header and footer, and a brand hero with a compute-quota gauge
  • Headline figures, a status chart, a runs table and live progress, laid out on the 12-column grid
  • Tabs for Overview, Runs, Workflows and Support, with a support form
  • An “Upload CWL” dialog with form inputs

See the finished page, with every step previewed, in the design system’s Build Your First Page tutorial. The finished React code is in the monorepo at apps/live/react-sandbox.

Prerequisites

Before starting, make sure you have:

Step 1: The page shell

Every EBRAINS page has the EBRAINS header with your product name, and the EBRAINS footer. Replace the contents of src/app/app.tsx:

What you just did:

  • product="Workflows" puts your app’s name next to the EBRAINS logo; current: true marks where the user is. Below 1024px the links move to a scrollable row under the bar.
  • variant="strong" makes the header brand black; the thin rule under it is yours to add.
  • variant="default" gives the light footer, with the EU funding statement and legal links.

See eds-header and eds-footer.

Step 2: A brand hero on the grid

The hero is a full-width dark band holding a container, split on the 12-column grid: 8 columns of text, 4 for a quota card. Add it above <main>:

Import EdsTag and EdsGauge from @ebrains/react too.

What you just did:

  • Band outside, container inside: the colour runs edge to edge while the content lines up with the rest of the page.
  • grid-col-span-12 lg:grid-col-span-8: full width on phones, 8 of 12 columns from 900px.
  • Stacks (flex flex-col gap-*) space everything from the spacing scale; f-* classes set the type.
  • Dark-ground variants: inverse tags and brandInverse / secondaryInverse buttons. Never recolour a light component by hand.

The classes are the design system’s layout primitives. For the Tailwind setup behind them, see the Tailwind Factory API.

Step 3: Figures, status and runs

Inside <main className="container max-w-default mx-auto pb-space-03">, build the overview: an alert, the week’s figures, a chart, the runs table and live progress.

Surface what needs attention

Show the figures in a collapsible panel

Headline figures don’t need cards: a description list reads faster, and screen readers announce each label with its value.

Add the chart, the table and live progress

Define the data above the component, for example const statusSlices = [{ id: 'ok', value: 226, label: 'Succeeded' }, ...] and const workflowColumn = { Workflow: { format: 'code' } } as const;.

What you just did: picked each component for its job: an alert for something to act on, a gauge for one value against a limit, a pie for parts of a whole, a table for records, progress bars for work in flight. Each section has a heading tied to it with aria-labelledby.

Step 4: Tabs and a support form

Put the overview in the first of four tabs, right under the hero. Each panel is a child element with slot="panel-N":

What you just did:

  • Tabs switch views of the same thing. If a view needs its own URL, make it a page instead.
  • EdsForm takes its fields as data, with placeholder and message per field, and reports input and submits through onForm.
  • --eds-form-padding: 0 removes the form’s card padding so it lines up with the tabs.

See the eds-tabs and eds-form pages, and the Forms pattern for labels, errors and buttons.

Step 5: An upload dialog

“Upload CWL” opens a modal. The wrapper forwards a ref to the element, so you call its methods directly:

What you just did: used the modal for a short, focused task. Actions go in slot="footer", secondary first and primary last. The modal moves focus inside, closes on Escape, and returns focus to the button.

Verify It Works

Expected result:

  • The header shows four links; below 1024px they sit in a row under the bar
  • “This week at a glance” is open, and the table and chart show data
  • The Runs tab pages through 5 rows at a time
  • “Upload CWL” opens the dialog; Cancel closes it
  • The browser console shows no errors

What You Learned

In this tutorial, you:

  • Structured a page: shell, full-width band with a container, 12-column grid, stacks
  • Chose components by their job, and their dark-ground variants on the hero
  • Passed arrays and objects as props, handled events with onForm, and called methods through a ref
  • Organised views with tabs and a focused task with a modal

Next Steps

Now that you’ve completed this tutorial, you can:

Troubleshooting

Problem: components render empty, and the console says "[object Object]" is not valid JSON. Solution: React rendered before the components registered. Render inside defineCustomElements().then(...) (step 3 of Add the Design System).

Problem: TypeScript rejects .then on defineCustomElements(). Solution: @ebrains/components 3.2.0 and earlier type it as void. Rebuild the components (nx build components) to get the Promise<void> type.

Problem: TypeScript rejects the table config, or a CSS custom property in style. Solution: give literal options a literal type ({ Workflow: { format: 'code' } } as const) and cast the style object (as CSSProperties).

Problem: no tab is selected and every panel is hidden. Solution: mark one tab active: true, or update the components: from 3.3.0 tabs set after load select the first tab.

Problem: the dev server starts on another port. Solution: the port was taken; Vite picks the next free one and prints it.

Additional Resources