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:
- Completed Build Your First Application and Add the Design System to Your App
- The
hello-ebrainsapp from the previous tutorial: design-system styles, Tailwind config, loader alias, and the components registered before rendering - Basic React and TypeScript knowledge
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: truemarks 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:
inversetags andbrandInverse/secondaryInversebuttons. 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.
EdsFormtakes its fields as data, withplaceholderandmessageper field, and reports input and submits throughonForm.--eds-form-padding: 0removes 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 aref - Organised views with tabs and a focused task with a modal
Next Steps
Now that you’ve completed this tutorial, you can:
- Compare the Vue and Angular versions of the same app (
apps/live/sandbox,apps/live/angular-sandbox) - Read the EBRAINS Design System overview and the Stencil components explanation
- Solve the next problem with a pattern: Navigation, Notifications, Empty and loading states
- Ship it: Tagging strategy and How to keep a changelog
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
- Build Your First Page: the same dashboard in plain HTML, with live previews and a layout overlay
- Build Inside the Monorepo: the full app setup for Vue, React and Angular
- Layout primitives and the component list
- Tailwind classes reference