Build Your First Page
This tutorial builds a complete EBRAINS dashboard, step by step: the home page of a Workflows app, where researchers run and monitor Common Workflow Language (CWL) pipelines. It has a bold brand hero with a compute-quota gauge, headline figures, a status chart, a runs table, live progress, and links onward to related EBRAINS services.
Everything is built from the layout primitives and ready components: no custom CSS for layout, colour or type. Each preview can show the layout: containers (dashed), the 12-column grid, column spans and stacks. Copy HTML copies the page, ready to use with the CDN.
Here is where we are going:
It is plain HTML, so it works as-is or inside any framework. Afterwards, the Integration Guide sets up the same building blocks in React, Vue or Angular.
Step 1: The page shell
Every EBRAINS page starts the same way: the stylesheet, the components loader, and the EBRAINS header and footer.
Why it’s built this way
langand<title>tell browsers and screen readers the language and the page. Most specific first: “Dashboard · Workflows · EBRAINS”.product="Workflows"puts your app’s name next to the EBRAINS logo. The links sit on the right; below 1024px they move to a scrollable row under the bar.current: truemarks where the user is.variant="strong"makes the header brand black, so it runs into the dark hero below. On dark, use the dark-ground button (secondaryInverse).- The thin rule under the header is yours to add: the header draws none. On a dark header use
border-inverse-softer, the same colour as the header’s small-screen link row; on a light one,border-softer. - The skip link lets keyboard users jump past the header. Show it on focus (Copy HTML includes the style).
<eds-footer>gives the standard EBRAINS footer with the funding statement and legal links. It is dark by default;variant="default"makes it light, which closes a page with a dark hero more calmly.
Step 2: A brand hero
The hero says what the app does, in a few big words, with the main action right there. A full-width band (bg-strongest text-inverse) holds a container, so the colour runs edge to edge while the content lines up with the rest of the page.
- Big type, few words.
f-heading-01grows from 42px on phones to 83px on large screens. Two short lines read faster than one long one. - One accent.
text-accentputs the brand neon on the second line only. Neon is for dark grounds, used once. - Band outside, container inside: the pattern for every full-width section. The dashed outline is the container; the dotted ones are stacks (32px between groups, 16px inside, 8px between tags).
- Dark-ground variants: the
inversetag, thebrandInverseandsecondaryInversebuttons. Never recolour a light component by hand.size="large"makes the hero’s actions as confident as its title. - No breadcrumb here: this is the app’s top page. Add one on deeper pages, above the title.
Step 3: The grid
Now the structure. The hero splits 8 + 4 for a quota card; the body opens with a strip of figures, then a main and a side column. Both use the 12-column grid: full width on small screens, split from 900px.
The pink stripes are the 12 grid columns; each labelled box is a column span. The green outline is an equal-column grid: four figures on wide screens, two per row below. Open the full page and narrow the window to watch them reflow.
Step 4: Fill it with components
Now the content: a compact quota gauge, four headline figures, a status chart, the runs table, live progress, and a getting-started card.
- Pick the component by the job: a gauge for one value against a limit, stat cards for headline figures, a pie for parts of a whole, a table for records, progress bars for work in flight.
- Let people fold away what they’ve read.
eds-accordionwithexpanded="true"shows the figures first and lets regular users collapse them; the heading stays as a summary. - Headline figures don’t need cards. A
<dl>with a label (dt), a big number and a trend tag (dd) reads faster than boxes, and screen readers announce each label with its value. Keep the number alone on its line so it sits exactly centred. - Pick the card by its weight: the neon
eds-card-generic intent="primary"is the one bright call to action in the body. Use one loud card per view. - Boxes group related content:
border border-softer rounded-lg p-24on white,bg-darkfor a tinted side panel,bg-inverse … shadow-mediumfor a card floating on a dark band. - Every section has a heading, tied to it with
aria-labelledby, so screen-reader users can jump between sections by name. One<h1>, then<h2>s.
Step 5: Tabs, status and next steps
A dashboard gathers several views of the same app. Put them in tabs right under the hero: the overview you built, the full runs list, your workflows, settings and support. Inside the overview, surface what needs attention, related services, and a closing call to action.
- Tabs flush under the hero: no top padding on
<main>, so the tab bar reads as the hero’s sub-navigation. It sits inside the container, so the tabs and every panel share one left edge with the hero. - Generous space before the footer:
pb-space-03is a section-spacing token (100px on phones, 120px on large screens), larger than the 0–64 scale. - Each panel lays itself out with the same primitives: a stack, an equal-column grid, or the 12-column grid.
- Forms sit flush in a panel with
style="--eds-form-padding: 0": the form drops its card padding and lines up with the tabs. - Tabs switch views of the same thing. If a view needs its own URL (to share a link to the runs list), make it a page instead.
Upload CWL opens a modal. A dialog suits a short, focused task that shouldn’t take the user away from the dashboard:
- Actions in
slot="footer": secondary first, primary last; the footer stays put while the body scrolls. - The modal handles focus: it moves focus inside on open, closes on Escape or the close button, and returns focus to “Upload CWL”.
Then, in the overview panel:
eds-card-herosuits a set of destinations: category, title, a line of description and tags, on the dark surface.eds-card-ctacloses the page with one clear next step on the brand gradient. One per page.
Plan the other states before you need them: no runs yet, loading, and errors. See Empty & Loading States, and Notifications for confirmations such as “Run started”.
Check before you ship
Brand
- The EBRAINS header with your product name, and the EBRAINS footer, on every page
- Type only from
f-*classes; colours only from thebg-*,text-*andborder-*tokens - Neon only on dark grounds, and sparingly: one accent in the hero, one loud card per view
- Dark bands use the components’ dark-ground variants, not recoloured light ones
- Spacing only from the scale (4, 8, 12, 16, 24, 32, 48, 64)
- One primary action per view, named after what it does
Accessibility
-
langon<html>and a page<title>that starts with the page name - A skip link, and one
<main>with the id it points to - One
<h1>, headings in order, sections labelled by their heading - The current page marked in the header (
current: true); on deeper pages, a breadcrumb - Everything works with the keyboard alone, and focus is always visible
- Charts have a text equivalent nearby (the pie’s legend, the gauge’s caption)
Layout
- Checked at phone width (around 375px), tablet and desktop
- No horizontal scrolling at any width
Next steps
You have a finished page. Now make it an app:
- Start Your Own App: install the packages from npm, run the page with Vite, make it interactive, build and deploy. In plain JavaScript, Vue or React.
- Build Inside the Monorepo: for EBRAINS-maintained apps in ebrains-ui-ecosystem, with Nx.
- More page types: Templates and Patterns.